Part of #1311. Priority: next. One pull request for the format and lint, one for the pilot.
Why
Every sentence in the governing prose is written as a checkable contract, including the sentences that are only rationale. A rule bullet in GOVERNANCE.md carries the rule, its history, the tool behavior it depends on, and its exceptions, in one paragraph, and eleven such bullets exceed 1,500 characters. The 15 "claim falsified" and 9 "two documents disagree" issues are overwhelmingly rationale sentences going stale, and they are reviewed to the same standard as the rule because nothing marks which is which. "Verification Discipline" is 18 KB, is the most-cited section in the open backlog, and has #1241, #1296, #1239 and others open against it.
Scope
- Define the format in
GOVERNANCE.md "Documentation Style Conventions" or its Skill, once: a rule is one bold normative statement, at most two sentences, using MUST, MUST NOT, or NEVER. Everything under it is rationale, set apart by a fixed marker (a nested bullet, or a line opening with a fixed word such as "Why:"), and rationale is non-normative. A stale rationale is a cleanup, filed to the unit's tracker, never a blocking finding. Only the normative statement is what a review holds a change to.
- Add a
prose_lint.py rule, opt-in first then gating once the pilot lands, that flags a normative bullet over a stated length and a rule bullet with no marked rationale boundary. Add the test that watches it fail.
- Tell the reviewer:
local-strict-review's brief and code-review's "Review the Change" say that a finding on rationale is reported under its own label and never blocks.
- Pilot: rewrite "Verification Discipline" into the format. Keep every rule. Move each rule's evidence into its rationale. Where a rationale sentence is a claim about a script or workflow, either cite the check that proves it or delete it. Close the pre-existing findings against the section that the rewrite settles, and move the rest to the section's tracker.
Rules that bind this task
- No rule is weakened or removed in the pilot. The normative statement of each rule says what the old bullet said.
- One unit per pull request. The pilot touches "Verification Discipline" and nothing else in
GOVERNANCE.md.
- The format definition lives in one place. Skills point to it.
Acceptance
prose_lint.py reports zero on the rewritten section and reports the old text.
- A whole-unit pass over the rewritten section, run with the stop condition from the P0 sub-issue, closes in one round with its findings labeled rationale.
Relates #1241, #1296, #1239, #1164, #1153.
Part of #1311. Priority: next. One pull request for the format and lint, one for the pilot.
Why
Every sentence in the governing prose is written as a checkable contract, including the sentences that are only rationale. A rule bullet in
GOVERNANCE.mdcarries the rule, its history, the tool behavior it depends on, and its exceptions, in one paragraph, and eleven such bullets exceed 1,500 characters. The 15 "claim falsified" and 9 "two documents disagree" issues are overwhelmingly rationale sentences going stale, and they are reviewed to the same standard as the rule because nothing marks which is which. "Verification Discipline" is 18 KB, is the most-cited section in the open backlog, and has #1241, #1296, #1239 and others open against it.Scope
GOVERNANCE.md"Documentation Style Conventions" or its Skill, once: a rule is one bold normative statement, at most two sentences, using MUST, MUST NOT, or NEVER. Everything under it is rationale, set apart by a fixed marker (a nested bullet, or a line opening with a fixed word such as "Why:"), and rationale is non-normative. A stale rationale is a cleanup, filed to the unit's tracker, never a blocking finding. Only the normative statement is what a review holds a change to.prose_lint.pyrule, opt-in first then gating once the pilot lands, that flags a normative bullet over a stated length and a rule bullet with no marked rationale boundary. Add the test that watches it fail.local-strict-review's brief andcode-review's "Review the Change" say that a finding on rationale is reported under its own label and never blocks.Rules that bind this task
GOVERNANCE.md.Acceptance
prose_lint.pyreports zero on the rewritten section and reports the old text.Relates #1241, #1296, #1239, #1164, #1153.