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

[kyle-sexton]

Closes #1352

Summary

Adds docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md, recording the #1270 guard program's generalizable lesson: a sound oracle is necessary but not sufficient to ship a PostToolUse verification guard default-on. Two of three scoped guards did not survive contact with the repo — the version-vs-manifest guard was dropped before implementation (already covered by check-changelog-parity.sh --check-bump), and asserted-path-verify was built to 61 contract cases, fully reviewed, then withdrawn on a full-corpus sweep: 231/975 markdown files (23.7%) fired, 389 findings, zero true positives (#1314). skill-reference-verify shipped (#1319) on the same evidentiary basis at 0.51% firing, 57% precision. The ADR records the decision that a guard measures 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 lifecycle stage earlier and defers to docs/conventions/hook-precision/README.md for the post-ship precision rules rather than restating them.

Test plan

• markdownlint-cli2 docs/adr/0003-*.md — 0 issues
• lychee --config lychee.toml docs/adr/0003-*.md — 1/1 links OK (cross-reference to ADR 0002 resolves)
• Manually verified every cross-referenced issue (guardrails: add a claim-verification guard (plugin-skill reference) #1270, feat(guardrails): add asserted-path and skill-reference claim guards #1284, feat(guardrails): add the skill-reference-verify claim guard #1319, guardrails: rescope asserted-path-verify — 23.7% firing rate, zero true positives on a full-corpus sweep #1314) and doc (docs/adr/0002-*.md, docs/conventions/hook-precision/README.md) exists and its cited content matches

Related

Refs #1270 — original guard-program scoping (version-vs-manifest guard dropped there).
Refs #1284 — superseded PR that first shipped asserted-path-verify (closed).
Refs #1319 — PR that shipped skill-reference-verify and withdrew asserted-path-verify on measurement.
Refs #1314 — full-corpus sweep measurement for the withdrawn asserted-path-verify guard.

🤖 Generated with Claude Code

[claude]

Claude finished @kyle-sexton's task in 1m 29s —— View job

---

PR Review

• Read changed file
• Verified cross-references (ADR 0002, docs/conventions/hook-precision/README.md)
• Checked ADR structure against existing ADRs (0001, 0002)
• Review complete

---

Summary

This is a clean, well-evidenced ADR. The core argument (sound oracle ≠ sufficient scope) is correctly established, the numbers are concrete and internally consistent (231/975 = 23.7% checks out), the cross-references all resolve, and the five-point decision section gives implementers an unambiguous checklist. One structural gap and one minor clarity nit worth addressing before merge.

---

Findings

Missing "Revisit triggers" section — both ADR 0001 and ADR 0002 close with a "Revisit triggers" section; ADR 0003 has none. For a process rule like this, relevant triggers do exist: e.g., the corpus-sweep tooling changes (invalidating the measurement approach), the repo scope changes significantly (new file classes the sweep should cover), or a withdrawn guard later finds a valid rescoping and re-ships. Omitting the section is a divergence from the established pattern in this repo and leaves the "when does this rule change?" question unrecorded.

claude-code-plugins/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md

Line 55 in 3181da9

## Decision

---

CHANGELOG exclusion rationale missing from the precision figure — line 29 states skill-reference-verify shipped at "0.51% firing, 57% precision after excluding CHANGELOGs" but doesn't explain why CHANGELOGs are excluded from the precision denominator. A reader reaching this ADR years from now without #1319 context won't know whether the exclusion was a principled scope boundary (CHANGELOGs carry a different citation structure and were out of the guard's target scope) or a precision-laundering maneuver. One subordinate clause would close this: e.g., "57% precision (CHANGELOGs excluded — their version-reference syntax is structurally distinct from the skill-reference surface the guard targets)."

claude-code-plugins/docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md

Line 29 in 3181da9

- **`skill-reference-verify`** shipped in #1319 at 0.51% firing, 57% precision after excluding

---

What checks out

• The relative link on line 40 (0002-default-on-ai-review-advisory-with-earned-promotion.md) resolves correctly — both files are siblings in docs/adr/. ✓
• The characterization of ADR 0002's scope is accurate: ADR 0002 governs advisory→blocking promotion; ADR 0003 governs whether a guard ships default-on at all. The "one lifecycle stage earlier" framing holds. ✓
• The deferral to docs/conventions/hook-precision/README.md for post-ship precision rules is accurate — that file owns the over-fire discipline; this ADR correctly does not restate it. ✓
• The "wrong oracle vs wrong scope → deletion vs rescoping" heuristic (decision point 4) is well-grounded by the two concrete cases. ✓
• The cost-of-measuring-late paragraph motivating decision point 5 is proportionate — it explains the lesson without relitigating feat(guardrails): add asserted-path and skill-reference claim guards #1284. ✓
• ADR date (2026-07-25), numbering (0003), and status (accepted) are all correct. ✓

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3181da97d6

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[kyle-sexton]

Closing as superseded by #1357, which merged the same ADR at the same path and closed the same issue (#1352).

docs/adr/0003-verification-guards-earn-default-on-by-measured-precision.md now exists on main in a strictly more developed form than this branch carries — same decision, more evidence, and it already resolves this PR's second review thread (zero findings leave precision undefined, not zero; seeded controls establish detection). The merge produced an add/add conflict with no composition that improves on the merged text, so merging this could only degrade main.

The one review finding not covered by the merged ADR — that decision rule 1 says "the real corpus" without scoping the sweep to a plugin-shipped guard's actual deployment surface (arbitrary consuming repos, not this marketplace) — is filed against the merged ADR as #1438 so it does not die with this branch.