prose_lint: the hub's own docs, spec, and catalog do not pass the gate it ships

[ptr727]

Summary

scripts/prose_lint.py is enforced on downstream repos, but the hub's own tree does not pass it. Running the gate from a clean hub clone at 69688ec:

python3 scripts/prose_lint.py .
668 violation(s)

Excluding the generated reports/ tree, 119 violations remain in hand-authored content:

file	violations
docs/devcontainer.md	22
spec/type-model.md	17
docs/ssh-signing.md	17
catalog/snippets/vscode/README.md	13
catalog/snippets/workflows/README.md	9
spec/fidelity-model.md	8
spec/scope-model.md	7
docs/repo-config-carry.md	7
catalog/README.md	6
docs/token-cost.md	5
host-setup/agent-safety/claude-md-safety.md	3
catalog/snippets/husky/README.md	3
catalog/snippets/configs/docker-hub-readme.md	2

The governance files themselves are clean, so this is not a carry problem. GOVERNANCE.md, AGENTS.md, CODESTYLE.md, WORKFLOW.md, AUDIT.md, repo-config/README.md, and .github/copilot-instructions.md all report zero. The gap is in the surrounding documentation and the spec models.

Why it matters

Two of the affected files are the spec models a downstream agent reads to decide what is carried and how faithfully: spec/fidelity-model.md and spec/scope-model.md. An agent sent to those documents to resolve a conformance question reads prose that the same repository's gate rejects, which undercuts the rule while teaching it.

catalog/snippets/** is the more direct risk. Those are the snippets downstream repos copy, so a non-conformant snippet seeds a violation into every repo that adopts it, and the downstream repo then gets flagged for content it was handed.

Questions

1. Is reports/** intended to be exempt? It is generated output, so a documented exclusion in the gate (rather than a standing backlog of 549) would make the hub's own result meaningful.
2. Should catalog/snippets/** be treated as higher priority than the rest, given the seeding effect above?

Context

Found while bringing ptr727/PhotoCleaner to spec ahead of going public (ptr727/PhotoCleaner#35). That repo's own carried files were stale rather than wrong: the hub's copies are clean and PhotoCleaner's were behind, which is a separate catch-up on our side and not a hub defect.

[ptr727]

Reproduced your numbers exactly from a clean hub checkout at 69688ec: 668 whole-tree, 119 excluding reports/, with the same per-file breakdown. The governance files are clean as you say, so this is not a carry problem. Good catch, and the catalog/snippets/** seeding argument is the sharpest part of it.

Two corrections, one to the premise and one that makes the finding bigger.

prose_lint.py is not enforced on downstream repos. It is hub-only and deliberately not carried: spec/files.json declares no scripts/ entry, and scripts/README.md states it directly, "Hub-only, not carried. These are not declared in spec/files.json, so the audit does not expect a downstream repo to ship them." PhotoCleaner encountered it because it was run there by hand against a hub clone, not because anything gates it. So the framing of a hub that holds others to a rule it breaks is not quite the situation. The real situation is worse in a different way, which is that nothing gates comment shape anywhere, including here.

The comment rules are not in the gate's default rule set, so your run never measured them. DEFAULT_RULES at scripts/prose_lint.py:35 is charset, charset-unknown, semicolon, dash, dupword, spelling. It excludes comment-wrap and comment-case. A bare prose_lint.py . therefore reports nothing about comments, which is why your 668 splits cleanly into dash 467 and semicolon 201 with no comment findings. Enabling them explicitly:

python3 scripts/prose_lint.py . --check comment-wrap --check comment-case --summary
424 violation(s) across 30 file(s)
  comment-wrap     390
  comment-case      34

Concentrated in spec/audit.py (103) and host-setup/agent-safety/gh-write-guard.py (56), then across the catalog/snippets/** workflow and config YAMLs. That last part compounds your seeding point rather than sitting beside it: a downstream repo copying build-docker-task.yml or dependabot.yml inherits comment-shape violations along with the workflow, and comment shape is the single most frequently regressed rule in agent-authored work.

On your two questions.

1. Yes, reports/** should be exempt. It is generated by spec/audit.py, and 549 of the 668 sit there, so the hub's own number is currently dominated by output nobody hand-writes. A documented exclusion in the gate is better than a standing backlog, and it makes the remaining figure mean something.
2. Yes, catalog/snippets/** leads the fix order, for exactly the reason you give, and the comment violations above make it more urgent than the dash and semicolon counts alone suggest.

Design consequence worth stating before anyone writes a fix. A whole-tree blocking gate is not reachable from here, in the hub or downstream, because the hub itself carries 119 default-rule violations plus 424 comment violations. The workable shape is the one the script already supports, --diff BASE, which reports only lines a change touches. That gates every new and edited line without demanding a sweep, and it matches the standing policy that existing prose is corrected as each file is next edited rather than swept. It is also the only shape that can be carried downstream without handing a repo a CI failure on day one.

Being picked up now as part of a change set that adds the comment rules to the default set, exempts reports/**, cleans the snippets first, and settles whether the gate becomes a carried file rather than a hub-only one.

[ptr727]

The semicolon rule newly reports 44 findings, from the #570 exemption fix

#573 scopes the semicolon exemption to the sentence its list lives in. The exemption had been judged over the whole span, so a colon anywhere before a bullet's first semicolon exempted every semicolon after it. Over the gate's Markdown scope that covered 62 spans holding 120 semicolons across 9 files while the rule reported none of them.

Old and new verdicts were diffed over the same tree: 20 findings become 64, and nothing previously reported went silent. The 44 new ones are backlog this issue owns, not a regression #573 introduces, and no prose is changed there, since the standing rule is to correct as each file is next edited and #570 asked that the exemption be proven before anything acts on its output.

The work list, 33 lines across 7 files

File	Lines
WORKFLOW.md	146, 149, 154, 161, 163, 171, 173, 225, 238, 286, 287
GOVERNANCE.md	64, 81, 84, 90, 206, 209, 213, 253, 326, 330, 337
CODESTYLE.md	38, 264, 358, 369, 384, 401
.github/copilot-instructions.md	90, 265
HISTORY.md	8
repo-config/README.md	22
spec/readme-structure.md	3

Reading them, they fall into two shapes:

1. A plain splice, which is what the exemption was hiding. HISTORY.md:8 ends Ships no application code; the old sample project and its build pipeline are removed., and the colon that exempted it sits in a different sentence three clauses earlier. GOVERNANCE.md:90, GOVERNANCE.md:213 and copilot-instructions.md:265 are the same shape.
2. A colon-introduced list carrying no comma, such as WORKFLOW.md's *Prevents: a PR publishing; orphaned artifacts churning the storage quota.*. The rule's exemption is for a list that already contains commas, so a semicolon-separated list without them is a finding by the letter of the rule and reads fine with a comma or an and.

One thing to decide before sweeping

28 of the 33 lines sit in GOVERNANCE.md, CODESTYLE.md and WORKFLOW.md, which are carried verbatim. A downstream repo cannot edit its copy, and re-vendoring changes those lines, so its own diff-scoped prose gate will flag them on the next vendor bump with no fix available downstream. GOVERNANCE.md "Documentation Style Conventions" already answers this, that carried content is swept at the hub for the whole class rather than waiting for the next edit, which argues these three files go together in one pass ahead of catalog/snippets/** rather than after it.

Headline figure for this issue, re-measured on develop at the time of writing: 559 whole-tree under the default rules, up from 520 before #573, and 184 under catalog/snippets alone, which #573 does not move.