AGENTS.md: add Verification Discipline; sweep prose on a behavior change (#356)

[ptr727]

Fixes#356, including the amendment.

What lands

New ## Verification Discipline section in AGENTS.md, placed between Documentation Style Conventions and PR Review Etiquette - write it right, verify it, then review. It opens with the unifying property: every failure below is green, so no linter, status check, or review layer catches any of them.

The six from the proposal, plus the amendment's review companion:

1. A test must assert the mechanism it names.
2. Gates, filters, and gate-like watchers fail loud, never narrow quietly.
3. Run the repo's whole lint gate before every push.
4. Editing CRLF files programmatically: . matches \r.
5. A green check is not evidence the work happened.
6. A workflow change is only fully exercised by CI.
7. A review flags an instance; fix the class.

Rule 7 from the amendment - search for prose asserting the old behavior after changing it - goes under Documentation Style Conventions per your placement note, directly beside the present-tense rule as its maintenance counterpart: that rule governs how to phrase a doc, this one how to keep it true when the behavior underneath moves.

Placement judgment on the companion: you grouped "fix the class" with rule 7 but did not place it. I put it in Verification Discipline rather than the docs section, because it generalizes past stale prose to any flagged defect class (a silent-narrowing pattern, a mis-worded contract). Happy to move it if you'd rather keep the pair together.

Complementing rather than duplicating

You named three adjacent rules; each generalization now cross-references its instance instead of restating it:

• fail-loud -> WORKFLOW.mdD8.4 (the identity-allowlist gate, landed yesterday via publish-plan-task: the actor allowlist fails silently if the App identity changes #354)
• whole-lint-gate -> "Running the Linters Locally" (which documents how to invoke each, not that all run)
• green-check -> the changes-job note under Branching Model (its instance for that one job)
• CRLF regex -> the Line Endings warning, whose mechanism it names

I also folded the mirror failure into rule 4: a text-mode rewrite silently flattens CRLF to LF, the inverse of the CRCRLF case. I hit exactly that two days ago - a scripted edit flattened spec/project-types.json and CI caught it, not my local run, which is also rule 3 in action.

README

Rules -> Always gains the two that read as fleet-wide invariants rather than technique: run the whole lint gate before pushing, and make gates fail loud. Both are bullets under an existing heading, so the auto-generated Table of Contents needs no change (and is never hand-edited per its own rule).

Validation

spec/validate.py, markdownlint, CI-scoped cspell, editorconfig-checker: clean. CRLF preserved on both files.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new "Verification Discipline" section to AGENTS.md and updates adjacent prose so the governance docs explicitly capture the class of failures that still appear "green" in CI, alongside a companion maintenance rule for keeping documentation accurate after behavior changes.

Changes:

• Add ## Verification Discipline to AGENTS.md, documenting seven verification rules (including the amendment's review companion).
• Add a new Documentation Style Conventions bullet: when changing behavior, grep for prose that asserts the old behavior and update it.
• Update README.md's "Rules -> Always" index with two new invariant-style bullets (full lint gate before pushing; gates fail loud).

Reviewed changes

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

File	Description
README.md	Extends the high-level rules index with two new invariant-style bullets aligned with the new verification discipline guidance.
AGENTS.md	Adds the new Verification Discipline section and the companion doc-maintenance rule near present-tense guidance to keep governance text accurate over time.