audit: a citation must resolve on the ref the audit named, and both passes get checkpointed (0.2.0)

[mmcky]

The two severity-1 defects from run 1, filed as items 1 and 2 on #21 and sequenced there as one doctrine-level PR because they are the same defect at two altitudes: the audit's own record claiming more than it can support. Five of the seven defects on #21 remain open after this.

Defect 1 — a [verified] citation that the reader cannot resolve

doctrine §2 required file:line, a merged PR or a tag, and never that the cited thing be reachable from the ref the audit says it verified against. Run 1's headline finding cited commit b99b431 as where a file's history ends — a commit that is real and does touch the file, but lives only on an unmerged branch, while the report's own header said "verified against main @ 2c3d624". The conclusion survived independent checking; the citation did not. A citation that resolves for its author and not for its reader is worse than an untagged claim, because the tag is what invited the trust.

§2 now states the requirement for every citation form, not just commits. This is broader than #21 asked for, deliberately: file:line and PR citations are ref-relative too and fail the same way — a line number that is right in a dirty working tree and wrong on the ref, an open PR cited as though merged. So a commit must be an ancestor of the baseline ref, a file:line must be that line on the ref rather than in the working tree, and a PR must be merged into it. /audit:issues phase 2 runs the mechanical case before tagging:

git merge-base --is-ancestor <sha> <ref>   # exit 0 = citable

Evidence that genuinely lives off-ref stays citable — as the open PR it is, tagged [stated] or [inferred]. The rule removes a false-precision trap, not a class of evidence.

Defect 2 — half of phase 2 sat outside the checkpoint

findings.md held the 56 open issues. The 62 closed ones were verified and written straight into the catalog, so the resume rule shipped in 0.1.2 — "resume at the lowest number in issues.json with no entry" — would have re-verified all 62 from scratch while reporting itself complete. The checkpoint materialised, which is what #17 set out to prove; it just covered one of the two passes.

findings.md now carries ## Open and ## Closed sections, and the resume rule partitions issues.json by state and resumes each side independently at the lowest number with no entry under the matching heading. The skill also says explicitly not to infer progress from a single block or from the file's length.

This is what makes run 2 worth running for its stated purpose. Run 2 exists to test resume, and testing a resume path against a checkpoint already known to cover half the phase would have wasted the most informative run in #16's matrix — the block-3-before-block-4 argument on #25.

Release

audit 0.1.4 → 0.2.0, minor rather than patch. Both fixes change what an operator does during a run — one adds a check that can change how a finding is tagged, the other changes which files a run writes — which is the line developing-skills draws between the two. scripts/validate.py passes all three plugins and scripts/check-version-bump.py reports ok audit — 0.1.4 → 0.2.0.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the audit plugin’s doctrine and /audit:issues runbook to (1) require that [verified] citations resolve on the baseline ref the audit names, and (2) ensure phase-2 checkpointing covers both the open and closed passes, with a corresponding minor version bump to 0.2.0.

Changes:

• Tighten evidence rules: [verified] citations must be reachable from the audit’s named baseline ref (including commit-SHA reachability checks).
• Update /audit:issues checkpoint/resume guidance so findings.md checkpoints both open and closed passes separately.
• Release the behavior/procedure change as audit 0.2.0 and sync the marketplace entry.

Reviewed changes

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

Show a summary per file

File	Description
audit/skills/issues/SKILL.md	Updates the runbook to checkpoint both passes and to require baseline-ref citation checks before tagging [verified].
audit/references/doctrine.md	Extends evidence-class doctrine to make baseline-ref reachability a requirement for [verified] citations.
audit/CHANGELOG.md	Documents the 0.2.0 release and the two severity-1 procedural fixes.
audit/.claude-plugin/plugin.json	Bumps audit plugin version to 0.2.0.
.claude-plugin/marketplace.json	Updates the marketplace’s audit entry to version 0.2.0.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mmcky]

Good catch, and fixed in 27a5db6 — though at the other end than suggested. You are right that the two statements disagreed: §2's table had grown a fourth form and the reachability rule, while §1 rule 1 still read "Cite file:line, a PR, or a tag for each verified claim". A reader meets rule 1 first and gets the stale list.

The fix is to stop §1 enumerating rather than to add a clarification at §2. §2 already states it correctly, so a third statement of the accepted forms would be one more copy to drift — and duplicated lists drifting is exactly what produced this defect. Rule 1 now carries the requirement and points at §2 for the forms, which leaves one place where they are written down. That also matches the repo's single-source-of-truth rule (AGENTS.md), which this plugin's own doctrine is supposed to model.