Gate Every Prose Rule Now That the Backlog Is Zero

[ptr727]

Closes the last piece of #519, which is now closed with its evidence quoted on the issue.

Why now

The prose backlog reached zero at 20916ad. semicolon and dash were warn-only because a whole-tree gate on them would have failed every run while several hundred findings sat in the tree. That reason has expired, and a warn-only tier over a clean tree is how the backlog grows back.

Measured on this branch before writing the change, and again after:

python3 scripts/prose_lint.py . --check charset --check semicolon --check dash --check dupword \
  --check spelling --check comment-wrap --check comment-case --check home-path
0 violation(s) across 0 file(s)

home-path gated nothing anywhere, which is the substantive fix

home-path has been in DEFAULT_RULES since it was written, so a bare local run has always included it. It was named by neither CI step, so the rule that catches an absolute home path naming a real account ran on a developer's machine and gated nothing in CI. That is the pattern-detectable sliver of GOVERNANCE.md "Representative Data in Agent-Authored Text", the section that exists because real paths carrying real names reached a public comment.

OPERATIONS.md already recorded the hole, correctly and in detail. This closes it and drops the record, rather than leaving a runbook describing a gap that no longer exists.

What stays warn-only, and why that is not an oversight

charset-unknown alone. A finding there names a character no tier covers, and classifying one is a fleet-law edit rather than something the change that happened to type it can fix. Blocking on it would make an un-tiered character an unmergeable change instead of a question for the maintainer. The step keeps continue-on-error: true and is renamed from "Report prose backlog step" to "Report unclassified characters step", since there is no backlog left for it to report.

sentence-split remains named by no invocation and stays that way here. It is deliberately outside DEFAULT_RULES, so promoting it is a separate decision rather than a consequence of this one, and OPERATIONS.md still records it as a gap.

The composite action is unaffected

.github/actions/prose-gate runs python3 "$SCRIPT" --diff "$BASE" with no --check list, so it already gates the full default set, home-path included, over the lines a change touches. A downstream caller sees no behavior change from this pull request. Only the hub's own whole-tree steps move.

Documentation kept level with the change

• OPERATIONS.md carries the two CI invocations verbatim so a local run matches CI rather than exceeding it, so both lines are updated, the three-gap paragraph becomes two, and the sentence describing the second invocation as a backlog report is corrected.
• scripts/README.md claimed five rules gate and the rest report. It now states the tree is zero and every default rule gates but one. It also names home-path for the first time, including the limit that it closes a sliver of its section and nothing more, because the exposure that section exists for was name-shaped and no pattern finds a name.
• TODO.md loses the prose_lint: the hub's own docs, spec, and catalog do not pass the gate it ships #519 entry and its link definition.

Three corrections the closing comment carries rather than this diff

The TODO.md entry being removed held three wrong figures, each re-measured before the issue was closed:

Claim in the entry	Measured
Fixed by f7a6a13 (snippets)	Not a valid object in this repository. The snippets batch is b002fac (#600).
557 across 45 to zero, 184 in snippets	553 across 44 to zero, batches 181, 241, 90 and 41, with today's checker run at every point
#573 accounts for 37 of the 38 carried findings	38 of 38. Pre-#573 checker reports 0 and post-#573 reports 38 over the identical bytes at 69688ec.

Verification

Check	Result
New gating invocation, whole tree	0 violations across 0 files
charset-unknown, whole tree	0 violations across 0 files
python3 scripts/test_prose_lint.py	198 tests, OK
python3 scripts/repo_gate.py	eol 0, sha-pin 0
actionlint	exit 0
editorconfig-checker	exit 0
python3 spec/validate.py	22 cataloged, 0 backlog repos classify cleanly

The four edited files keep their declared line endings, CRLF for the three Markdown files and LF for the workflow, which editorconfig-checker confirms.

[Copilot]

Pull request overview

Updates the hub’s CI and documentation so that, now the prose backlog is cleared, the whole-tree validation workflow gates on all default prose_lint.py rules (including home-path) except charset-unknown, which remains warn-only.

Changes:

• Expand the validate workflow’s prose gate invocation to include semicolon, dash, and home-path, and narrow the warn-only step to charset-unknown only.
• Update OPERATIONS.md and scripts/README.md to reflect the new CI invocation and rationale for the remaining warn-only rule.
• Remove the completed #519 entry and link definition from TODO.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
TODO.md	Removes the completed #519 tracking entry and its reference link definition.
scripts/README.md	Updates prose_lint documentation to reflect the “all rules gate except charset-unknown” posture and adds home-path context.
OPERATIONS.md	Updates the “run gates like CI” runbook commands and explanations to match the new gating/warn-only split.
.github/workflows/validate-task.yml	Changes CI to gate additional prose rules whole-tree and renames/repurposes the warn-only step for charset-unknown.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (2)

OPERATIONS.md:11

• This says "sentence-split is in neither and is asked for by name", but a later paragraph in this section says sentence-split is "named by no invocation, so nothing runs it". To avoid contradicting the runbook's own gap list, reword this sentence to clarify that sentence-split is not invoked by CI and must be explicitly requested to run.

CI passes explicit `--check` lists, and a bare `python3 scripts/prose_lint.py [file]` runs `DEFAULT_RULES`, which is those two lists together. What differs is the exit code rather than the coverage: CI gates on eight of the nine and reports `charset-unknown` warn-only, where a bare run exits non-zero on any of the nine. `sentence-split` is in neither and is asked for by name. Run the CI invocations:

.github/workflows/validate-task.yml:72

• This comment says "Every prose rule" is clean and gating, but scripts/prose_lint.py implements sentence-split and the runbooks note it is not invoked by CI. Consider narrowing the wording to "Every default prose rule" so it matches what this workflow actually runs.

      # Every prose rule is clean tree-wide, so each one gates rather than reporting a backlog.
      # `charset-unknown` is clean too and still reports, for the reason the step below gives.

[ptr727]

Round 2, both suppressed findings accepted and fixed in 809da2f

Round 2 reported no new comments and carried two findings inside a <details> block. Those reach no review thread, so they are answered here rather than resolved.

.github/workflows/validate-task.yml:72, accepted. The comment read Every prose rule is clean tree-wide, so each one gates, which overstates what the step does. sentence-split is a prose rule, it is clean tree-wide, and it gates nowhere, because it sits outside DEFAULT_RULES deliberately. Narrowed to Every default prose rule, which is the suggested wording and the accurate one.

OPERATIONS.md:11, accepted. It said sentence-split is in neither and is asked for by name, sixteen lines above saying it is named by no invocation, so nothing runs it. Both statements are true, and read together they contradict. The first now reads that sentence-split is in neither, so nothing below runs it and a local run reaches it only by naming it. The gap paragraph keeps its own wording, since its job is to record the gap rather than to explain the mechanism.

A third instance the findings did not name. Sweeping the phrasing rather than the two cited lines found scripts/README.md:75 carrying the same overstatement, Every rule above is clean tree-wide, which is what lets CI gate them. That line is new in this pull request, written one round earlier while fixing the first finding, so the same claim went in three places and the review caught two of them. It now says every rule in the default set.

This is the third round in a row where the defect was an over-broad claim rather than broken code, which is worth naming rather than quietly fixing.

Verification on 809da2f

Check	Result
Gating invocation, whole tree	0 violations across 0 files
sentence-split, whole tree	0 violations across 0 files
python3 scripts/test_prose_lint.py	198 tests, OK
python3 scripts/repo_gate.py	eol 0, sha-pin 0
actionlint	exit 0
editorconfig-checker	exit 0

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

Suppressed comments (1)

scripts/README.md:21

• The new home-path description does not mention that prose_lint.py skips this check when run from an operational repository checkout. Without that caveat, the README implies the rule always runs and may mislead operators reviewing why a local run didn’t flag an absolute path.

Enforces the [`GOVERNANCE.md`][governance] "Documentation Style Conventions" rules that no linter checks: non-ASCII judged against the charset rule's three tiers, a semicolon in prose, a spaced hyphen joining or interrupting a sentence, a duplicated consecutive word, a British spelling, and the shape of a comment's prose. It carries one rule from elsewhere in that document, `home-path`, which comes from "Representative Data in Agent-Authored Text" and catches an absolute home path naming a real account. That rule closes the pattern-detectable sliver of its section and nothing beyond it, since the exposure the section exists for was name-shaped and no pattern finds a name.

[ptr727]

Round 3, the suppressed finding accepted and fixed in 0e4a1c2

One finding, inside a <details> block again, so it is answered here rather than resolved.

scripts/README.md:21, accepted, and checked against the code rather than taken on trust. The mechanism it names is real. scripts/prose_lint.py discards home-path when the checkout is an operational repository, and it announces the skip on stderr rather than going quiet:

note: home-path is not checked in an operational repository, where an absolute path is the
operator instruction rather than observed data.

The reason is sound. An operational repository's runbook carries the literal path an operator types, which is that repository's own content rather than an agent quoting an environment it observed. My paragraph described the rule as though it always runs, so the caveat is now stated.

Where the finding leaves out something worth stating. The skip keys on which repository-configuration payload a checkout carries, so a repository declares its own model and nothing reaches the hub registry to ask. The hub carries both payloads, being the template for each, so it reads as a release repository:

operational_checkout(hub) = False

That matters to this pull request rather than being trivia. Gating home-path here would be worth nothing if the rule excused itself on the very repository the gate runs on, and it does not.

Verification on 0e4a1c2

Check	Result
Gating invocation, whole tree	0 violations across 0 files
python3 scripts/test_prose_lint.py	198 tests, OK
python3 scripts/repo_gate.py	eol 0, sha-pin 0
editorconfig-checker	exit 0

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

[ptr727]

Round 4 is clean, and the loop is closed

Copilot reviewed 5 of 5 files on 0e4a1c2 and generated no comments, with no suppressed block in the body. That is the first round carrying neither, so every finding this pull request drew is answered.

Round	Head	Findings	Disposition
1	66c8adb	1 thread	Accepted. scripts/README.md contradicted itself on the warn-only tier.
2	3523f60	2 suppressed	Both accepted. Over-broad "every prose rule", and a sentence-split contradiction in OPERATIONS.md.
3	809da2f	1 suppressed	Accepted. The home-path opt-out in an operational checkout was undocumented.
4	0e4a1c2	none	Clean.

Two of the four rounds reported no comments while carrying findings in a <details> block, which is the shape a thread-polling loop reads as a pass.

A sweep beat the review to a third instance twice. Rounds 1 and 2 each named one line, and grepping the term rather than fixing the named line found another instance the review had not reached, in scripts/test_prose_lint.py and then in scripts/README.md. Both were the same claim written in more than one place, which is what the whole change is about: a statement about the gate, kept in prose, drifting from the gate.

Final verification on 0e4a1c2

Check	Result
Gating invocation, whole tree	0 violations across 0 files
charset-unknown, whole tree	0 violations across 0 files
sentence-split, whole tree	0 violations across 0 files
python3 scripts/test_prose_lint.py	198 tests, OK
python3 scripts/repo_gate.py	eol 0, sha-pin 0
actionlint	exit 0
editorconfig-checker	exit 0
python3 spec/validate.py	22 cataloged, 0 backlog repos classify cleanly
CI on the head	Validate sources job and workflow status job both SUCCESS

One review thread stays unresolved rather than declined. The reply carrying the fix is on it, and resolving it is the maintainer's action here.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

[ptr727]

Round 5 is clean, and the merge state is CLEAN

6fa593b adds one work cluster to TODO.md, recording the two failures this pull request's own review loop hit at its last step. Copilot reviewed 5 of 5 files and generated no comments, with no suppressed block. The one review thread is resolved.

The cluster carries three bullets, each checked against the code rather than asserted:

Bullet	Finding
Document it	The runbook's dead-path list holds only GitHub's own refusals, so a refusal raised locally matches none of them and reads as a bad identifier.
Detect it	reply already exits 63 where the resolve did not report the thread resolved. A loop driving gh api by hand gets no exit code, so the state is the evidence rather than the mutation returning.
Resolve it	Q_THREADS selects a thread's id, resolved state, path and first comment, and not its url, so the digest names a thread it cannot point at.

Implementing the url selection is left to that cluster rather than done here, since it changes scripts/pr_review.py and this pull request is about the prose gate.

Verification on 6fa593b

Check	Result
Gating invocation, whole tree	0 violations across 0 files
charset-unknown and sentence-split, whole tree	0 violations across 0 files
python3 scripts/test_prose_lint.py	198 tests, OK
python3 scripts/repo_gate.py	eol 0, sha-pin 0
python3 spec/validate.py	22 cataloged, 0 backlog repos classify cleanly
editorconfig-checker	exit 0
markdownlint-cli2 on TODO.md	0 issues