Skip to content

writing.md names a check-writing.sh that does not exist, so the em-dash rule is unenforced #1

Description

@rusholme

What the purpose requires

The writing design states mechanical style rules and says they are enforced
by a pattern scan that runs in the pull-request checks. For that statement to
be true, the scan has to exist and has to run. A rule the site describes as
blocking should block.

What exists today

system/writing.md line 238 names the scan as scripts/check-writing.sh and
describes it as running beside check-public-safety.sh in the pull-request
checks. That file does not exist. scripts/ contains only acceptance.sh and
check-public-safety.sh.

The gap was found by walking into it. Commit 5258ab5 (2026-09-12, "Make the
em dash a blocking check") established that every page on the site is free of
em dashes and that the scan blocks on one rather than warning. On 2026-09-13 a
new page, system/glossary.md, was written and committed carrying 22 em
dashes, with 5 more added to repositories.md and 1 to code-standards.md.
Nothing objected: check-public-safety.sh returned OK, the Sphinx build
succeeded, and scripts/acceptance.sh passed every check. The violation was
caught by a human-directed review reading the commit history, which is exactly
the labour the scan exists to replace.

So the rule is real and ratified, the pages comply with it by hand, and the
enforcement the design claims is live is not wired up. A rule that depends on
each author knowing it is a convention, not a check.

The trigger that reopens this

This is open now. It closes when scripts/check-writing.sh exists, runs in
the same place check-public-safety.sh runs, and fails on an em dash in a
tracked page. Until then, writing.md line 238 describes machinery the
repository does not have, and either the script or that sentence needs to
change.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    handoverHandover: outstanding at the 2026-09-13 documentation handover

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions