Repository navigation
P1: Define the Normative-Statement Format, Lint It, and Pilot It on "Verification Discipline" #1316
Description
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.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. - Tell the reviewer:
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. - 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.pyreports 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.
Activity
ptr727 commentedon Sep 8, 2026
A worked measurement in favour of this issue, from PR #1435, which added two bullets to
GOVERNANCE.md"Communicating with the User".Bullet sizes in that section after the change:
The new parked-queue bullet is 2.2 times the longest bullet that was already there, and longer than the two next-longest combined. It carries 11 sentences.
Every blocking finding in the last six review rounds on that PR was inside it, and none was a wrong rule. The normative statement was correct in the first draft and never changed. What kept failing was rationale: a claim that a label was in every carrier's set, a claim that a session had nowhere else to learn a name, a claim that a session ends by exhausting its context (contradicting
AGENTS.md"Session Scope", cited in the same sentence), and twice over a claim about what happens to an omitted item that the rule's own enumerate-and-rank mechanism forecloses. The last of those was settled by deleting the explanation rather than rewording it a third time.The growth mechanism is visible in the diff history: each failure mode a reviewer found was answered with another clause, and no round ever removed one. A format that separates a short normative statement from separately-marked, non-contractual commentary would have absorbed all fifteen rounds without growing the contract, because fourteen of the roughly thirty findings were against sentences that are not rules.
The maintainer's decision on that PR was to ship the bullet as it stands and let this issue reshape it, rather than hand-shaping it ahead of the format and paying the review rounds twice. So this bullet is a ready-made pilot candidate alongside the "Verification Discipline" one this issue already names, and it has a documented round-by-round record of which sentences failed and why.
Widen the Parked Queue to the Label's Own Meaning, and Delete What Ov…
Make a Parked Decision Something the Session Still Owes the User (#1435)
Promote develop to main: a declared destination list for includes, an…
ptr727 commentedon Oct 23, 2026
Closed under the maintainer's decision (ptr727, 2026-10-23) on #3391, item 6: the #1311 structural items that have had no activity since September are closed so the backlog states what is planned. #1321 stays open as the one structural item still under consideration. The re-assessment that supersedes #1311's plan is the comparison on #3391.