feat(claude-config): stable audit-instructions finding identity (#4116)

[kyle-sexton]

Closes #4116

Summary

Give every audit-instructions finding a stable audit-pass identity, and persist I30–I33 from the lane.

Deviation from #4116: the issue says a lane-sourced finding's confidence is fixed to high because "a deterministic detector still fired". No scanner produces I30–I33, so that premise does not hold; lane rows leave Confidence blank instead of claiming a detector confidence.

Fix

• Identity is (check, claim, sites): check is claude-config/audit-instructions/<id>, claims live in reference/finding-identity.md, anchors are anchor/v1 excerpts with the heading-path discriminator, and an I15 conflict is one finding with two sites.
• scripts/finding-ids.sh derives finding_id/v1 and group/v1 through audit-pass's finding-identity.sh.
• emit-findings.sh --from-lane emits I30–I33 (detector-findings 3.2.0 crosswalk). I32 in frontmatter and I31/I33 outside a spoke are declined with a named reason. Phase D table gains a Finding ID column.
• Rows that share a finding_id are emitted once, with an Identity collisions: finding_id=<id> count=<n> line under ## Surfaces, per the audit-pass identity contract.
• The I32 fallback target matches only /plugin:skill or a backticked plugin:skill; anything else reports shape=.
• detector-findings README adopter row states the I30–I33 tier spread.
• Version 0.51.27 with CHANGELOG.

Verification

• finding-ids.test.sh: 28 passed (a new case proves a fenced ## not a heading is not in the heading path).
• emit-findings.test.sh: 170 passed (new Case 16: identical lines collide to one row with count=2; 10:30 yields shape=).
• scripts/check-detector-findings-crosswalk.sh, scripts/validate-plugins.sh, scripts/check-changelog-parity.sh --check --check-order, scripts/check-changed-skills.sh origin/main: pass.

Related

• docs/conventions/detector-findings 3.2.0.
• I6/I33 fences are audit-instructions: I6 pre-scan adopts the audit-noise gate set; I33 lane fences, excerpt anchors, and per-plugin presentation #4115 (PR feat(claude-config): fence I6 gate set and per-spoke I33 (#4115) #4850).
• Follow-up outside this plugin: plugins/review/skills/audit-enforceability/context/crosswalk.md has no exact rows for the four new lane rules, so they fall to the claude-config/audit-instructions/ family row ("already deterministic").

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hx63mvV8t39y644DQ3uLnn

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-28T18:07:06.139037Z	e00f825	Draft marked ready

ℹ️ 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" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[claude]

Claude finished @kyle-sexton's task in 4m 13s —— View job

---

Claude finished the security review

• Gather context (PR diff, changed files)
• Invoke /review:security-review per custom instructions
• Post findings

Reviewed the two new scripts (finding-ids.sh, emit-findings.sh) and the doc/context changes in this PR. Most of the code is careful about the usual shell pitfalls (quoted expansions, cd --/basename --/dirname -- to block option injection, ..-traversal fencing with fail-closed behavior, temp-file-mediated cygpath invocation instead of string interpolation). One finding below.

IMPORTANT — finding-ids.sh reads and excerpts any file under $HOME, not just the Claude-config subtree, before persisting an identity

File: plugins/claude-config/skills/audit-instructions/scripts/finding-ids.sh
Lines: 160–189 (surface_of) and 233–270 (site_of)

surface_of() accepts any resolved path that is a prefix-match under "$ROOT" or under the entirety of $HOME ("$abs" == "$HOME_P"/*", line 184), not scoped to ~/.claude (or $CLAUDE_CONFIG_DIR). Once a row's path clears that check, site_of() (called from process_row, lines 302/310) reads the actual line text out of that file via line_context and hands it to finding-identity.sh anchor --excerpt "$text" ... to build the finding's anchor/identity — i.e. this script will happily open and excerpt any file the process can read anywhere under the user's home directory (~/.ssh/id_rsa, ~/.aws/credentials, ~/.netrc, etc.), as long as a row names it.

Exploit path: rows here are <path>:<line>:<check-id>, and for the new I30–I33 families they come from the Phase B/C model lane described in context/execution-and-report.md — a subagent reading (potentially adversarial) instruction content and proposing findings, which this PR wires straight into --from-lane → finding-ids.sh (emit-findings.sh lines 272–274). A prompt-injection payload in an audited file that gets the lane to fabricate a row such as /home/<user>/.ssh/id_rsa:1:I30 — or a repo-committed symlink under context//reference/ resolving outside the repo into $HOME — clears surface_of's home-directory check and causes finding-ids.sh to open and excerpt that file's content into the emitted identity/anchor. This is exactly the class of attack the audit-instructions skill is designed to catch elsewhere (self-referential/injected instructions), so the row-provenance trust here is worth hardening rather than assuming benign input.

Note: emit-findings.sh's own findings table additionally requires relativize_in_repo() to succeed before a row is printed (repo-relative Location only), so a user:-scoped row is declined there and its content does not reach the written ## Findings table via that path. But finding-ids.sh is also documented as a standalone, directly-invoked tool (reference/finding-identity.md lines 40–50, and Phase D per SKILL.md), and in that direct-invocation / --records path there is no equivalent fence — the home-directory-wide surface and its excerpted anchor are exactly what get emitted. Whether the anchor format embeds the literal excerpt text or only a hash of it is defined in the sibling audit-pass plugin (../../audit-pass/scripts/finding-identity.sh), which isn't part of this diff/repo checkout, so I can't confirm the exact severity of content disclosure from here — but the read-and-excerpt of arbitrary $HOME content on a lane-supplied path, unscoped to the Claude-config surface the skill is meant to audit, is a new, concrete data-flow this PR introduces.

Suggested fix: scope the "user surface" branch of surface_of() to ${CLAUDE_CONFIG_DIR:-$HOME/.claude} (the actual claimed audit surface per persist-findings.md's "Phase A inventory spans user-level surfaces under CLAUDE_CONFIG_DIR") rather than all of $HOME.

Fix this →

No other security-relevant issues found in this diff — the shell-injection surfaces (path handling, temp-file usage, YAML/markdown escaping) are handled defensively, and GitHub Actions hardening is out of scope for this lane.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e00f8256bb

ℹ️ 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".

[claude]

Claude finished @kyle-sexton's task in 2m 38s —— View job

---

Security review — /review:security-review

• Gather context (PR diff, changed files, prior review comments)
• Invoke /review:security-review per custom instructions
• Post findings

Skip gate triggered. The diff since the last full security review on this PR (commit e00f825, reviewed above) is a single commit, 04c66dc, that only renames local test variables in emit-findings.test.sh (DOUT→DUPOUT, DROWS→DUPROWS) for spell-check compliance. No source script, no crosswalk logic, and no input-handling code changed — there is no new security-relevant surface for this lane to review.

I re-checked the one finding from that prior review against the current head rather than re-running a full pass:

Still open — IMPORTANT: finding-ids.sh's surface_of() accepts any path under $HOME, not just the audited ~/.claude surface
Lines 165–189 (surface_of), called from site_of, are byte-for-byte unchanged since e00f825. The "$abs" == "$HOME_P"/*" check at line 184 scopes the "user surface" branch to the entire home directory rather than ${CLAUDE_CONFIG_DIR:-$HOME/.claude}, so a lane-supplied row naming a path anywhere under $HOME (e.g. ~/.ssh/id_rsa:1:I30) still clears the surface check and gets opened.

One correction to the earlier writeup, from reading ../../audit-pass/scripts/finding-identity.sh (present in this checkout, at plugins/claude-config/skills/audit-pass/scripts/finding-identity.sh, which wasn't inspected in the prior pass): an excerpt anchor is e:<sha256(normalized excerpt) truncated to 12 hex>:<n> — a truncated hash, never the literal line text — and finding-ids.sh --records emits only {surface, anchor}, not raw content. So the concrete impact is narrower than "reads and excerpts arbitrary $HOME file content into the output": it's an arbitrary-file-read-and-hash primitive under an attacker-supplied path (existence/readability confirmation, plus a low-value hash oracle against a guessed line), not literal secret disclosure. That's still worth fixing — it's a real, unscoped file read driven by adversarial (lane/prompt-injectable) input, on a tool documented to audit only Claude-config surfaces — but the severity is IMPORTANT rather than CRITICAL.

Since the code path is unchanged from the prior review and this correction is informational, I haven't filed a new inline comment for it; the fix suggested previously still applies: scope HOME_P's prefix check to ${CLAUDE_CONFIG_DIR:-$HOME/.claude} instead of all of $HOME, and update finding-ids.test.sh's user-scope test accordingly.

No new security issues found in the 04c66dc diff itself.
· branch cursor/4116-finding-identity-37e9

[claude]

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

---

Security review — /review:security-review

• Gather context (PR diff, changed files, prior review comments)
• Invoke /review:security-review per custom instructions
• Post findings

Skip gate triggered. The diff since the last full security review on this PR (commit e00f825, reviewed here, re-checked against 04c66dc here) is one new commit, 7dba2d2, which resolves the three Codex P2 review comments and adds matching test coverage:

• finding-ids.sh's line_context awk (now lines 190–219) gained an incomment state that skips heading-shaped lines inside a block `` comment outside a fence, so such a line no longer enters the anchor heading path. Traced the rule ordering by hand — incomment is checked before the fence-toggle and heading-capture rules, and is only set when `!infence`, so a `<!--` inside a fenced code block still isn't treated as a comment. Covered by a new case in `finding-ids.test.sh`.
• emit-findings.sh's in_rule_surfaces for I33 now accepts references/ alongside reference/ and context/, matching what I31 already allowed and what the I33 catalog documents (diff).
• fired_marker's I32 branch (lines 586–599) now counts all slash-form and backtick-form skill-ref candidates in the line before picking one; with more than one candidate it falls back to shape="route-to-absent-skill" instead of silently naming the first (possibly valid) match as the unresolved target.

All three fixes are narrow, match the reported failure mode, and are unit-tested (finding-ids.test.sh Case for the comment-heading fix; emit-findings.test.sh Case 17 for the references/ spoke and the two-candidate I32 line). I wasn't able to execute the test scripts myself in this sandbox (the auto-mode permission classifier denied running them directly), so this is verified by reading the awk/bash logic and the added assertions rather than by re-running the suite — the PR body's own numbers (170/28 passed) are consistent with what the diff adds.

Still open — not touched by this commit, no new severity assessment needed: finding-ids.sh's surface_of() (lines 165–189, HOME_P check unchanged from prior review) still scopes the "user surface" branch to all of $HOME rather than ${CLAUDE_CONFIG_DIR:-$HOME/.claude}. A lane-supplied row naming a path anywhere under $HOME (e.g. ~/.ssh/id_rsa:1:I30) still clears the surface check and gets opened by site_of(), yielding an arbitrary-file-read-and-hash primitive on adversarial (lane/prompt-injectable) input, on a tool documented to audit only Claude-config surfaces. Confirmed byte-identical to the version reviewed at 04c66dc. Suggested fix stands: narrow HOME_P's prefix check to ${CLAUDE_CONFIG_DIR:-$HOME/.claude} and update finding-ids.test.sh's user-scope test accordingly.

No new security issues introduced by 7dba2d2.
· branch cursor/4116-finding-identity-37e9

[claude]

Claude finished @kyle-sexton's task in 5m 26s —— View job

---

Code review (/review:code-review lane)

• Gather context (PR diff, changed files)
• Invoke /review:code-review per custom instructions
• Post findings

Scope: correctness and maintainability in the two new/changed scripts (finding-ids.sh, emit-findings.sh) and the doc/context changes. Security-shaped findings are scoped to the separate security lane, which already reviewed this PR.

No new blocking findings. I read finding-ids.sh in full (identity derivation, symlink-following surface_of, the heading-path/fence/comment-tracking line_context awk, process_row's pairwise/single-site handling) and the changed regions of emit-findings.sh (the --from-lane intake, IDMAP construction, fired_marker, in_rule_surfaces, relativize_in_repo/win_long/has_dotdot_segment, and the identity-collision dedup in the main awk loop). I also traced the three items the automated Codex review left as P2 suggestions against the current head (7dba2d2) and confirmed each is already fixed there, not just proposed:

• Heading-shaped lines inside a block HTML comment are now excluded from the heading path (line_context's incomment tracking, finding-ids.sh#L209-L212), and it's covered by a dedicated test case (finding-ids.test.sh "a heading-shaped line inside a block HTML comment is not in the heading path").
• I33 now admits the plural references/ spoke directory alongside context//reference/ (emit-findings.sh#L346-L349).
• fired_marker's I32 branch now counts all slash/backtick skill-reference candidates in the sentence first and falls back to a generic shape= when there's more than one, instead of always reporting the first syntactic match (emit-findings.sh#L591-L600).

Beyond re-verifying those, I looked for a cross-file inconsistency between emit-findings.sh's relativize_in_repo() (which anchors on a caller-pwd-derived root specifically to survive a documented Git-Bash/MSYS toplevel-spelling mismatch) and finding-ids.sh's own, simpler root resolution (git rev-parse --show-toplevel physically resolved, no --root passed by the caller). On reflection this isn't a solid finding: finding-ids.sh compares paths after a real cd/pwd -P filesystem resolution on both sides, which should converge on the same canonical spelling regardless of how the input path was originally written, unlike the pure string-prefix matching relativize_in_repo() has to do inside awk — so I'm not reporting it without a reproducible failing input.

Not independently verified: I don't have Bash execution allowed in this session, so I could not run finding-ids.test.sh / emit-findings.test.sh myself; the PR's stated 28/170 pass counts are author-claimed, not confirmed by me here.
· branch cursor/4116-finding-identity-37e9

[claude]

Claude finished @kyle-sexton's task in 50s —— View job

---

Security review — /review:security-review

• Gather context (PR diff, changed files, prior review comments)
• Invoke /review:security-review per custom instructions
• Post findings

Skip gate triggered. Diffing the last fully-reviewed commit (7dba2d2, re-checked at 04c66dc and 7dba2d2 in prior comments on this PR) against current HEAD (5d0f897) shows finding-ids.sh and emit-findings.sh are byte-identical — git diff 7dba2d2..HEAD -- .../finding-ids.sh .../emit-findings.sh is empty. The only changes since the last review are a Merge origin/main bringing in unrelated main-branch commits (version bumps for unhobble/audit-permission-grants, a routing-text reword in SKILL.md changing "your session" → "this session", and the resulting plugin.json/CHANGELOG.md version renumbering to 0.51.27). Confirmed against git diff origin/main...HEAD --stat, which matches the PR's own 12 changed files with no new ones. No new security-relevant surface for this lane to review.

Still open — unchanged, re-verified at current HEAD: finding-ids.sh's surface_of() (lines 165–189) still scopes its "user surface" branch to the entire $HOME ("$abs" == "$HOME_P"/*", line 184) rather than ${CLAUDE_CONFIG_DIR:-$HOME/.claude}, the surface the skill is documented to audit. A lane-supplied row naming a path anywhere under $HOME (e.g. ~/.ssh/id_rsa:1:I30) still clears the check and is opened by site_of(), which reads and hashes the file's content into the emitted anchor. As corrected in an earlier pass on this PR: the anchor is a truncated SHA-256 of the excerpt (../../audit-pass/scripts/finding-identity.sh), not the literal line text, and --records emits only {surface, anchor} — so this is an arbitrary-file-read-and-hash primitive on adversarial (lane/prompt-injectable) input, not literal secret disclosure. Severity: IMPORTANT.

Suggested fix (unchanged from prior reviews): narrow HOME_P's prefix check to ${CLAUDE_CONFIG_DIR:-$HOME/.claude} and update finding-ids.test.sh's user-scope test accordingly.

Fix this →

No new security issues introduced since the last review.
· branch cursor/4116-finding-identity-37e9

[claude]

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

---

Code review (/review:code-review lane)

• Gather context (PR diff, changed files, prior review comments)
• Invoke /review:code-review per custom instructions
• Post findings

Skip gate triggered (rule 4: this head already has a successful review from this lane that still applies).

The last full code-review pass on this PR ran at commit 7dba2d2 (here) and found no blocking issues. The head has since moved to 5d0f897 via two commits, 4081930 and 5d0f897, both merges of origin/main bringing in an unrelated change (#3563 / #5082, the unhobble deletion-tier grammar) plus routine version bumps.

I diffed 7dba2d2..HEAD and confirmed none of the files this PR actually owns changed:

• plugins/claude-config/skills/audit-instructions/scripts/{finding-ids,emit-findings}.sh and their *.test.sh — byte-identical since 7dba2d2.
• plugins/claude-config/skills/audit-instructions/{context/persist-findings.md,reference/finding-identity.md,evals/evals.json,SKILL.md} — byte-identical since 7dba2d2.
• docs/conventions/detector-findings/{README.md,CHANGELOG.md} — byte-identical since 7dba2d2.

The only diffs in that range touch plugins/claude-config/skills/audit-instructions/reference/criteria.md and reference/bundled-claude-api.md — but those two files are unchanged by this PR relative to origin/main (they aren't in this PR's own file list); the diff is origin/main's content arriving through the merge, not something authored on this branch. There is no new review surface for this lane.

No new findings. The prior pass's read of the code (identity derivation, symlink-following surface_of, the heading-path/fence/comment-tracking line_context awk, --from-lane intake, IDMAP construction, fired_marker, in_rule_surfaces, dedup/collision handling) still applies, and all three Codex P2 suggestions remain fixed at 7dba2d2 as previously confirmed.
· branch cursor/4116-finding-identity-37e9