Skip to content

P1: Define the Normative-Statement Format, Lint It, and Pilot It on "Verification Discipline" #1316

Description

@ptr727

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.

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

    documentationImprovements or additions to documentationproseA defect in rule or procedure text

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions