docs(adr): record that verification guards earn default-on by measured precision

[kyle-sexton]

Observation

The #1270 guard program produced a reusable lesson that currently lives only in closed PRs and issue bodies. It should be an ADR.

Three guards were scoped on sound oracles. Two did not survive contact with the repository:

• The version-vs-manifest guard was dropped before implementation: its only in-repo surface is already covered by scripts/check-changelog-parity.sh --check-bump, and the residual prose surface is historical, minimum-floor, and planned version claims that a manifest compare reads wrong.
• The asserted-path guard was built to 61 contract cases, fully reviewed, then withdrawn on measurement: a sweep of all 975 tracked markdown files showed 23.7% of files firing across 389 findings with zero true positives (guardrails: rescope asserted-path-verify — 23.7% firing rate, zero true positives on a full-corpus sweep #1314).
• The plugin-skill reference guard shipped (feat(guardrails): add the skill-reference-verify claim guard #1319), at 0.51% firing and 57% precision after excluding CHANGELOGs.

The generalizable finding: a sound oracle is necessary but not sufficient for shipping a guard default-on. The path guard's oracle was exact � no candidate resolved at the repo root. Its scope was wrong: a repo whose docs mostly describe other repos' trees. A passing contract suite proves the oracle; only a corpus sweep proves the scoping.

Direction (no open decision)

Add docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md recording the decision that a verification guard measures its firing rate and precision against a real corpus before shipping default-on, that the number appears in the PR, that zero true positives disqualifies regardless of oracle soundness, and that "wrong oracle" versus "wrong scope" decides deletion versus rescoping.

It extends ADR 0002's verification-promotion discipline one step earlier in the lifecycle: 0002 governs promoting an advisory gate to blocking on demonstrated precision, this governs whether it ships default-on at all, on the same evidentiary basis. docs/conventions/hook-precision/README.md keeps the post-ship over-fire discipline.

The ADR also records the cost honestly: measuring immediately after the guard first worked, rather than after polish and review, would have saved a full review round.

Acceptance

• ADR exists, follows the house format of 0001/0002 (# Title, Status, Date, Context, Decision, Consequences)
• Every cross-reference resolves
• It defers to hook-precision/README.md rather than restating it
• The withdrawn guards' evidence is cited, not duplicated

Related

#1270 (scoping), #1284 (closed), #1319 (shipped guard), #1314 (withdrawn guard + measurement).

---

This was generated by AI during a session on the fact-check capability.

[kyle-sexton]

[kyle-sexton]

This was generated by AI during work-loop execution.

Auto-confirmed by the work-loop orchestrator's admission gate (work-class: read-only / C1, agent-ready, no needs-human, re-verified clear of any branch/PR/assignee before claim). Claimed via the seam, worked in an out-of-tree worktree on branch docs/1352-adr-verification-guard-precision, and opened PR #1364 with the ADR content per the acceptance criteria.

PR: #1364

[kyle-sexton]

This was generated by AI during work-loop execution.

Done (2026-07-25): Added docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md, recording the #1270 guard program's lesson that a sound oracle is necessary but not sufficient to ship a verification guard default-on -- a corpus sweep must also measure firing rate and precision, the number goes in the PR, zero true positives disqualifies regardless of oracle soundness, and "wrong oracle" vs "wrong scope" decides deletion vs rescoping. Follows the house ADR format (0001/0002), extends ADR 0002's verification-promotion discipline one lifecycle stage earlier, defers to docs/conventions/hook-precision/README.md rather than restating it, and cites (without duplicating) the withdrawn-guard evidence in #1314/#1319.

Fixed in #1364 -- this item will auto-close when that PR merges (per Closes #1352 in the PR body). Per work-loop worker-lane authority, this session claims and authors only; merging is left to the babysit/merge lane or a human.