feat(enforcement-ladder): rewrite the ladder as 2.0.0 with four tiers, a runs-at column and the guardrail criterion #8731

Refs: #7572
Blocked by: #8537 (the ADR that amends ADR 0003; criterion (3) names its file). Start from main after it merges.

Agent Brief

Type: Task
Summary: Rewrite the enforcement ladder as version 2.0.0 (four tier headings, a "runs at" column, the new and renamed rung ids, the one guardrail criterion) and regenerate its four plugin copies. The plugin files that write a rung id move to the new ids in the follow-on writers slice.

Current behavior:

• docs/conventions/enforcement-ladder/README.md:2 declares enforcement-ladder: 1.0.0. The rungs are one flat list of nine (README.md:21-62): make-impossible, compiler settings, four linter sub-rungs, canonical-helper (rung 4, below linters), architecture-test, tests, "Git hook or CI" (rung 7), hook (rung 8) and llm-only (rung 9).
• Where a check runs (edit time, commit, PR) is mixed into the rungs: rung 7 is a delivery point, and rung 8 covers both code-content hooks and action guards.
• The ladder has no guardrail criterion: nothing says when a lesson earns a deterministic check.
• scripts/sync-shared-copies.sh copies the README into four plugins (scripts/shared-copies.txt:90-93): plugins/review/context/enforcement-ladder.md, plugins/session-flow/skills/retro/reference/enforcement-ladder.md, plugins/harness-config/skills/audit-automation-gaps/context/enforcement-ladder.md, plugins/architecture/skills/improve/research/enforcement-ladder.md. Each says 1.0.0.

Desired behavior:

• The README frontmatter reads enforcement-ladder: 2.0.0, and CHANGELOG.md beside it gains a ## [2.0.0] entry naming every moved, renamed, added and removed rung id.
• Four tier headings, strongest rung first, cost only breaking ties:
  1. Codebase: make-impossible, then shared-helper (renamed from canonical-helper). shared-helper counts on this tier only when a lint or check names the helper; without one the README says it enforces nothing.
  2. Static analysis (a machine asserts it and can block): compiler or type settings, the four linter sub-rungs (ids unchanged), architecture-test, tests, harness-setting (new: permission deny rules, skill frontmatter flags), action-guard (renamed from hook: a Claude Code hook on an action no file check sees, such as a force-push or a write outside the tree), then scaffold (new: a template or generator that produces the right shape), the last rung before prose.
  3. Guidance (a model reads it; nothing blocks): automated-review (renamed from llm-only: REVIEW.md read by the review bot on every PR), instruction (CLAUDE.md, AGENTS.md, path-scoped rules), skill (a procedure loaded on demand; an action on an existing skill first).
  4. Human only: human-review, the last rung id (project docs a person applies).
• "Git hook or CI" and the code-content hook stop being rungs. A "runs at" column (edit time, commit, PR) on the static-analysis rungs says where each check runs; the default is the same command at edit time and in CI.
• One "Guardrail criterion" section, the single source the readers will point to: a finding earns a deterministic rung only if (1) it can be decided without reasoning, (2) it recurs past the threshold (once if policy-class), (3) a blocking check has no effective false positives and an advisory one stays under 10%, the 10% named as a corpus-precision proxy, with 0003-verification-guards-earn-default-on-by-measured-precision.md and the ADR file docs(adr): record check precision defaults in an ADR that amends ADR 0003 #8537 adds named in backticks as the record, (4) its message names the owner or the API to use instead, (5) it fails on a planted or past violation and passes after the revert, and is recorded only with that proof, (6) it runs at edit time and in CI and fails only on new violations, (7) no stronger rung already covers it, (8) it has a kill switch, a "not useful" exit, and exceptions with an expiry.
• One rule for a recurring correction: if the rule was not loaded, fix where it lives; if it was loaded and ignored, move it up the ladder, judged by native means only.
• The "Selection rules" table and the "Versioning" section are updated to the new ids. The README stays free of relative links (README.md:12-14).
• Run scripts/sync-shared-copies.sh to regenerate the four copies; never edit a copy by hand.

Known call (2026-10-20):

• Run after docs(adr): record check precision defaults in an ADR that amends ADR 0003 #8537 merges, and name its ADR file in backticks beside 0003-verification-guards-earn-default-on-by-measured-precision.md in criterion (3).
• This slice changes the README, its CHANGELOG and the regenerated copies only. /review:audit-enforceability keeps emitting hook and llm-only until the writers slice that this one blocks merges.

Key interfaces:

• docs/conventions/enforcement-ladder/README.md, docs/conventions/enforcement-ladder/CHANGELOG.md.
• scripts/sync-shared-copies.sh (run it).

Done when:

• The diff sets docs/conventions/enforcement-ladder/README.md to exactly one line enforcement-ladder: 2.0.0, and the four regenerated copies each carry enforcement-ladder: 2.0.0 (read from the diff).
• The README in the diff contains each of the six ids shared-helper, harness-setting, action-guard, scaffold, automated-review and human-review, and no longer contains canonical-helper or llm-only (read from the diff).
• The README has exactly one ## Guardrail criterion heading, a "runs at" column, and the criterion names 0003-verification-guards-earn-default-on-by-measured-precision.md and docs(adr): record check precision defaults in an ADR that amends ADR 0003 #8537's ADR file, each in backticks (read from the diff).
• docs/conventions/enforcement-ladder/CHANGELOG.md has a ## [2.0.0] heading (read from the diff).
• scripts/sync-shared-copies.sh --check exits 0.
• scripts/check-changelog-fragments.sh --check passes, with one major fragment each for review, session-flow, harness-config and architecture (their ladder copies change).
• CI's check-plugins passes on the PR, including sync-shared-copies.sh --check-bump origin/main and check-changelog-fragments.sh --check-required origin/main (a PR check; this run does not run it).

Out of scope:

• Every plugin file that writes a rung id (emit-stubs.sh, the rest of audit-enforceability, plugins/review/README.md, audit-automation-gaps/SKILL.md, improvement/skills/find/context/unattended.md): the writers slice this one blocks.
• The precision ADR (docs(adr): record check precision defaults in an ADR that amends ADR 0003 #8537); the README only names it.
• Pointing retro, /harness-config:audit-automation-gaps and /overengineering:audit at the criterion (feat(session-flow): point retro, automation-gaps and overengineering at the ladder's guardrail criterion #8538).
• The old ids in docs/upstream/cursor-pstack.md; the pstack-recheck slice of marketplace: pstack recheck and listing budget #7588 updates that record.
• Installing any new blocking check.

Origin:

• Four tiers as headings, strongest first: hers (Lauren's), D17, D28, D50 item 8, Q117.
• "Runs at" column and one command at edit time and in CI: ours, D28.
• harness-setting (Q13), scaffold (Q49, hers), the guidance split ending in human-review (D28, Q5, Q206): ours, from her order; ids per D32.
• shared-helper only with a lint that names it: ours, D28.
• One guardrail criterion in the ladder: ours, D18, D29; precision bar as corpus-precision proxy: D31, D116.
• Check message names the owner or API: hers, Q50.
• Fail-then-pass proof before a check is recorded: hers (pstack correct), D22, Q115, Q526.
• Forgotten versus ignored rule, native means only: ours, D23, Q511.
• Split from feat(enforcement-ladder): ship ladder 2.0.0 with a runs-at column, four tiers and the new rung ids #8536 (Large) into this ladder slice and a writers slice, 2026-10-20.

Do not run with: #7573 slices that move audit-enforceability; #7575 (retro, per PLAN's shared-state list for Phases 4, 5, 7); #8538 (criterion pointers); any other change to scripts/shared-copies.txt lines 90-93.

Slice of #7572, split from #8536.