From 0205b69251a6401d78b1dfb199fd2da6cc5ac066 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 23:25:21 -0400 Subject: [PATCH 1/5] fix(guardrails): anchor skill-reference-verify's partial-Edit reconstruction on hunk lines MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The guard's header comment claimed the token filter held the diff-scope contract for partial-Edit reconstruction — a pre-existing unrelated reference sharing a recovered line never fires. It did not: a 4+ character word token is short enough to occur on lines the edit never touched, so a hunk of unrelated prose containing e.g. `legacy` grepped back every `*-legacy` reference in the file, and an untouched broken one among them passed the substring gate and fired from an edit that never touched it. Lines are now located by the hunk's own text, not its tokens: every line of new_string is on disk verbatim by PostToolUse time, so line-anchoring selects a strict subset of what token-anchoring returned and always retains the edited line. The token filter survives as a second gate on the reported candidate rather than as the locator — the same shape stale-path-verify was fixed to on #1432 (65b4f67c), ported here to this guard's /plugin:skill reference syntax. A regression test proves the false-positive direction, verified to fail against the pre-fix guard (PASS=60 FAIL=1). Existing partial-replacement true-positive cases keep passing; the composite complete-reference-plus-bare-word case is reshaped onto a realistic multi-line hunk, since a single Edit's new_string cannot land in two disjoint places on disk. Header comment corrected to state what the anchor guarantees. Closes #1453 Co-Authored-By: Claude Sonnet 5 --- plugins/guardrails/.claude-plugin/plugin.json | 2 +- plugins/guardrails/CHANGELOG.md | 20 ++++++++ .../hooks/skill-reference-verify.sh | 48 +++++++++++-------- .../hooks/skill-reference-verify.test.sh | 26 +++++++++- 4 files changed, 74 insertions(+), 22 deletions(-) diff --git a/plugins/guardrails/.claude-plugin/plugin.json b/plugins/guardrails/.claude-plugin/plugin.json index bebc2238a15..9d5072c80a0 100644 --- a/plugins/guardrails/.claude-plugin/plugin.json +++ b/plugins/guardrails/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "guardrails", - "version": "0.16.1", + "version": "0.16.2", "description": "Eleven safety guards that block secret/credential writes, hardcoded machine-specific paths, git hook-bypass attempts, irreversible git operations (force-push, reset --hard, worktree-wide checkout/restore discards), Bash file-write workarounds that circumvent Write/Edit hooks, commit subjects and gh pr create titles that violate the repo's tracked team convention (when one is declared in .claude/source-control.md), (advisory) hallucinated CLI flags, (advisory) /plugin:skill references that do not resolve, (advisory) un-throttled Workflow fan-out that risks burst 529s, and (advisory) direct git commit/gh pr create calls bypassing this marketplace's own commit/pull-request skills — each independently toggleable.", "author": { "name": "Melodic Software", diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index 8644401565f..f5ea07e5774 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -3,6 +3,26 @@ All notable changes to the `guardrails` plugin are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.16.2] + +### Fixed + +- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own lines, + not its word tokens (#1453).** The guard's header comment claimed the token filter held the + diff-scope contract — a pre-existing unrelated reference sharing a recovered line never fires — + but a 4+ character word token is short enough to occur on lines the edit never touched: a hunk of + unrelated prose containing `legacy` grepped back every `*-legacy` reference in the file, including + an untouched broken one, which then passed the substring gate and fired from an edit that never + touched it. Lines are now located by the hunk's own text: every line of `new_string` is on disk + verbatim by `PostToolUse` time, so line-anchoring selects a strict subset of what token-anchoring + returned and always retains the edited line. The token filter survives as a second gate on the + reported candidate rather than as the locator — the same shape `stale-path-verify` was fixed to on + `#1432` (`65b4f67c`), ported here to this guard's `/plugin:skill` syntax. A regression test proves + the false-positive direction against the pre-fix guard; the existing partial-replacement + true-positive cases keep passing, with the composite (complete-reference-plus-bare-word) case + reshaped onto a realistic multi-line hunk since a single Edit's `new_string` cannot land in two + disjoint places on disk. + ## [0.16.1] ### Fixed diff --git a/plugins/guardrails/hooks/skill-reference-verify.sh b/plugins/guardrails/hooks/skill-reference-verify.sh index b9ab9c7842c..5dc5e4d63a5 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.sh @@ -148,39 +148,49 @@ emit_refs() { } # Partial-replacement context reconstruction (Edit only), mirroring -# cli-flag-verify's reconstruct_partial_edit. +# stale-path-verify's reconstruct_partial_edit (fixed for the same defect class +# by 65b4f67c, #1432). # # An Edit may replace an arbitrary substring: swapping `setup` for `ghost` inside # an existing `/alpha:setup` leaves `/alpha:ghost` on disk, but the hunk is the # bare word `ghost` and carries no command for emit_refs to find, so a # newly-broken reference would be silently missed. # -# Recover bounded context: the edit is already applied by PostToolUse time, so pull -# from disk only the lines carrying one of the hunk's word tokens, scan those, and -# keep only references whose plugin or skill segment appears in the hunk. That -# token filter is what preserves the diff-scope contract — a pre-existing unrelated -# reference sharing one of those lines never fires. The anchor is the token, not -# the line, since a bare-word hunk carries no positional information. +# Recover bounded context: the edit is already applied by PostToolUse time, so +# pull from disk only the lines the hunk's OWN TEXT appears in, scan those, and +# keep only references whose plugin or skill segment contains one of the hunk's +# word tokens. Two filters compose to hold the diff-scope contract: the line must +# be one this hunk's text landed in, and the reported reference must contain +# edited text. reconstruct_partial_edit() { [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0 - # Anchor tokens come from the hunk with any COMPLETE reference removed first. - # A complete reference is already handled by the direct scan, and leaving it in - # would contribute its own plugin name as an anchor — `alpha` then matches every - # reference to that plugin, including untouched ones on neighbouring lines, which - # breaks diff-scope. What remains is the genuinely bare edited text. + # The token filter reads the hunk with any COMPLETE reference removed first. A + # complete reference is already handled by the direct scan, and leaving it in + # would contribute its own plugin name as a token — `alpha` then passes every + # reference to that plugin. What remains is the genuinely bare edited text. local residue residue=$(printf '%s' "$SCAN_CONTENT" | sed -E 's#/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*##g') - # Minimum anchor length. A substring match on a very short token matches almost + # Minimum token length. A substring match on a very short token matches almost # any segment — stripping a reference out of `Run `/alpha:x` now.` leaves the - # fragment `un`, which substring-matches `untouched-ghost` on an untouched line - # and breaks diff-scope. 4 characters is the shortest command segment worth - # anchoring on; below that the token carries no locating power. + # fragment `un`, which substring-matches `untouched-ghost`. 4 characters is the + # shortest command segment worth filtering on; below that the token carries no + # filtering power. local -a toks=() mapfile -t toks < <(printf '%s' "$residue" | grep -oE '[a-z][a-z0-9-]{3,}' 2>/dev/null | sort -u) ((${#toks[@]})) || return 0 - local tok lines ctx="" - for tok in "${toks[@]}"; do - lines=$(grep -F -- "$tok" "$FILE" 2>/dev/null) + # Lines are located by the hunk's own lines, never by its tokens. Every line of + # new_string is on disk verbatim, so it matches the line the edit landed in; a + # token, being shorter, also matches lines the edit never touched — a bare + # `legacy` in unrelated prose pulls in every `/alpha:*-legacy` reference on any + # line, and an untouched broken one among them would fire. Line-anchoring can + # only ever select a subset of what token-anchoring would, and the edited line + # is always in that subset. + local -a anchors=() + mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null) + ((${#anchors[@]})) || return 0 + local anchor lines ctx="" + for anchor in "${anchors[@]}"; do + lines=$(grep -F -- "$anchor" "$FILE" 2>/dev/null) [[ -n "$lines" ]] && ctx+="$lines"$'\n' done [[ -n "$ctx" ]] || return 0 diff --git a/plugins/guardrails/hooks/skill-reference-verify.test.sh b/plugins/guardrails/hooks/skill-reference-verify.test.sh index 7e0a195c403..a60bca5381c 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.test.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.test.sh @@ -245,7 +245,7 @@ assert_contains "CHANGELOG-in-name but not a CHANGELOG → still adjudicated" "$ # PARTIAL-EDIT RECONSTRUCTION. An Edit may replace an arbitrary substring, so a # hunk can be a bare word with no command in it. The edit is already applied by # PostToolUse time, so the containing reference is recovered from disk, anchored to -# the hunk's tokens. +# the hunk's own text. PARTIAL="$REPO/partial.md" printf 'Run `/alpha:ghost-partial` to begin.\n' >"$PARTIAL" OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL" 'ghost-partial')" 2>&1) @@ -264,6 +264,23 @@ assert_contains "reconstruction reports the edited reference" "$OUT" \ assert_absent "reconstruction does NOT report an untouched neighbour" "$OUT" \ "untouched-ghost" +# Diff-scope again, against the harder shape from #1453: the hunk is unrelated +# prose that merely SHARES A WORD TOKEN with an untouched broken reference +# elsewhere in the same file. Anchoring on the token alone (the pre-fix behavior) +# pulls that reference in — `legacy` occurs in both `ghost-legacy` and the prose — +# so the anchor has to be the hunk's own line, which occurs verbatim in exactly +# the line the edit landed in. Verified to fail against the pre-fix guard (which +# fired `UNRESOLVED_SKILL: /alpha:ghost-legacy`), the same shape #1432 proved for +# stale-path-verify's sibling defect. +SEGSHARE="$REPO/segshare.md" +printf 'Stale `/alpha:ghost-legacy` here.\nThe legacy naming convention was updated today.\n' \ + >"$SEGSHARE" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" \ + <<<"$(edit_json "$SEGSHARE" 'The legacy naming convention was updated today.')" 2>&1) +RC=$? +assert_exit "prose hunk sharing a word token → exit 0" 0 "$RC" +assert_silent "hunk sharing only a token does not drag in an untouched broken reference" "$OUT" + # A hunk that already carries a full command is scanned directly. OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL2" 'Run `/alpha:ghost-three` now.')" 2>&1) assert_contains "full-command hunk → scanned directly" "$OUT" \ @@ -282,9 +299,14 @@ assert_contains "substring Edit inside a segment → recovered" "$OUT" \ # A hunk carrying BOTH a complete reference and a substring change to another must # report both — gating reconstruction on an empty scan would miss the partial half. +# The two live on separate lines of the SAME hunk: a single Edit's new_string can +# span several lines of a replaced passage, and each line lands on disk verbatim, +# so line-anchoring finds the bare-word line while the complete reference on the +# other line is already caught by the direct scan of the whole hunk. MIXED="$REPO/mixed.md" printf 'First `/alpha:ghost-mixed` here.\nSecond `/alpha:audit` is fine.\n' >"$MIXED" -OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$MIXED" 'ghost-mixed and `/alpha:ghost-direct`')" 2>&1) +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" \ + <<<"$(edit_json "$MIXED" $'ghost-mixed\nAlso now cites `/alpha:ghost-direct`.')" 2>&1) assert_contains "mixed hunk → direct reference reported" "$OUT" \ "UNRESOLVED_SKILL: /alpha:ghost-direct" assert_contains "mixed hunk → reconstructed reference also reported" "$OUT" \ From cd1ded76bd79993aa11cd7a61680d781daf3e852 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 25 Jul 2026 23:32:28 -0400 Subject: [PATCH 2/5] docs(guardrails): hedge skill-reference-verify's line-anchor comment for the degenerate case MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found the reconstruct_partial_edit header still overstated: when the whole hunk IS a single short token (the existing "substring Edit inside a segment" case, hunk = `host`), the anchor degenerates to plain token-anchoring since there is no larger line-text to distinguish it from the token. State the guarantee that actually always holds instead — line- anchoring can only ever select a strict subset of what token-anchoring returned, and the edited line is always in that subset — and name the degenerate case explicitly so the token filter reads as a real second gate, not a formality. Follow-up to #1453 / PR #1466. Co-Authored-By: Claude Sonnet 5 --- plugins/guardrails/hooks/skill-reference-verify.sh | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/plugins/guardrails/hooks/skill-reference-verify.sh b/plugins/guardrails/hooks/skill-reference-verify.sh index 5dc5e4d63a5..4e1d9396d27 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.sh @@ -159,9 +159,13 @@ emit_refs() { # Recover bounded context: the edit is already applied by PostToolUse time, so # pull from disk only the lines the hunk's OWN TEXT appears in, scan those, and # keep only references whose plugin or skill segment contains one of the hunk's -# word tokens. Two filters compose to hold the diff-scope contract: the line must -# be one this hunk's text landed in, and the reported reference must contain -# edited text. +# word tokens. What line-anchoring actually guarantees: it can only ever select a +# STRICT SUBSET of what token-anchoring alone would, and the edited line is always +# in that subset — never a wider net. It degrades to plain token-anchoring in the +# limiting case where the whole hunk IS a single short token (a bare `host` +# substitution carries no more positional information than the token itself), so +# the token filter stays a real second gate, not a formality, on the candidate +# that survives. reconstruct_partial_edit() { [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0 # The token filter reads the hunk with any COMPLETE reference removed first. A From 5ba706cef446681bd250e4635d6f8e93ae676a5d Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sun, 26 Jul 2026 00:12:40 -0400 Subject: [PATCH 3/5] fix(guardrails): require a unique line match in skill-reference-verify's anchor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review on #1466 found the line-anchoring fix incomplete in its degenerate case, and the repro holds against the branch head: when an Edit's new_string IS the shared word, the anchor is no longer than the token it replaced. A bare `legacy` hunk grep -F'd back both the edited prose line and an untouched `/alpha:ghost-legacy` line, and since `legacy` is a substring of that skill segment the token filter passed it through — the guard fired UNRESOLVED_SKILL on a reference the edit never touched. Anchoring on lines cannot separate those two lines; only refusing to guess between them can. An anchor is now used ONLY when it locates exactly one line on disk, and an anchor matching several is dropped rather than unioned. The cost is a missed advisory when an edit lands in a line duplicated verbatim elsewhere in the same file. That is the right side of the trade for a detect-then-judge guard, which — per 65b4f67c — is degraded the only way that matters by being wrong when it speaks. The header comment and CHANGELOG bullet asserted the token filter was a real second gate on the surviving candidate; the repro shows it gates nothing in this shape. Both are corrected to state where the diff-scope contract actually lives: uniqueness at the locate step, with the token filter as a second gate on what survives it. The "mirroring stale-path-verify" claim is narrowed too, since that sibling does not carry the uniqueness requirement yet. Codex's alternative — reconstruct context from old_string — is not available: by PostToolUse time old_string has been replaced on disk, so it is ungreppable. Regression test added for the bare-token hunk; all 63 cases pass, shellcheck and markdownlint clean on the touched paths. Co-Authored-By: Claude Opus 5 (1M context) --- plugins/guardrails/CHANGELOG.md | 35 +++++++----- .../hooks/skill-reference-verify.sh | 55 +++++++++++++------ .../hooks/skill-reference-verify.test.sh | 15 +++++ 3 files changed, 72 insertions(+), 33 deletions(-) diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index f5ea07e5774..1cb84cb90cd 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -7,21 +7,26 @@ All notable changes to the `guardrails` plugin are documented here. Format follo ### Fixed -- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own lines, - not its word tokens (#1453).** The guard's header comment claimed the token filter held the - diff-scope contract — a pre-existing unrelated reference sharing a recovered line never fires — - but a 4+ character word token is short enough to occur on lines the edit never touched: a hunk of - unrelated prose containing `legacy` grepped back every `*-legacy` reference in the file, including - an untouched broken one, which then passed the substring gate and fired from an edit that never - touched it. Lines are now located by the hunk's own text: every line of `new_string` is on disk - verbatim by `PostToolUse` time, so line-anchoring selects a strict subset of what token-anchoring - returned and always retains the edited line. The token filter survives as a second gate on the - reported candidate rather than as the locator — the same shape `stale-path-verify` was fixed to on - `#1432` (`65b4f67c`), ported here to this guard's `/plugin:skill` syntax. A regression test proves - the false-positive direction against the pre-fix guard; the existing partial-replacement - true-positive cases keep passing, with the composite (complete-reference-plus-bare-word) case - reshaped onto a realistic multi-line hunk since a single Edit's `new_string` cannot land in two - disjoint places on disk. +- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own lines and + only where they locate a single line, not on its word tokens (#1453).** The guard's header comment + claimed the token filter held the diff-scope contract — a pre-existing unrelated reference sharing + a recovered line never fires — but a 4+ character word token is short enough to occur on lines the + edit never touched: a hunk of unrelated prose containing `legacy` grepped back every `*-legacy` + reference in the file, including an untouched broken one, which then passed the substring gate and + fired from an edit that never touched it. Lines are now located by the hunk's own text: every line + of `new_string` is on disk verbatim by `PostToolUse` time, so a match is the line the edit landed + in. Anchoring on lines alone is not enough, because a hunk can be one short word and then the + anchor is no longer than the token it was replacing — so an anchor is used only when it matches + **exactly one** line, and an ambiguous anchor is dropped rather than unioned. That is what closes + the false positive; the token filter is a second gate on what survives, never the locator. Cost of + the trade: an edit landing in a line duplicated verbatim elsewhere in the same file now goes + unreported, which is the right side of the trade for a detect-then-judge guard, degraded far worse + by speaking wrongly than by staying quiet. Two regression tests cover the shared-token and + bare-token shapes; the existing partial-replacement true-positive cases keep passing, with the + composite (complete-reference-plus-bare-word) case reshaped onto a realistic multi-line hunk since + a single Edit's `new_string` cannot land in two disjoint places on disk. `stale-path-verify` and + `cli-flag-verify` carry the same reconstruction shape and are tracked separately — see `#1432` + (`65b4f67c`) for the sibling fix this ports from. ## [0.16.1] diff --git a/plugins/guardrails/hooks/skill-reference-verify.sh b/plugins/guardrails/hooks/skill-reference-verify.sh index 4e1d9396d27..65a78f0b440 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.sh @@ -147,9 +147,10 @@ emit_refs() { sed -nE 's|^(/[a-z][a-z0-9-]*:[a-z][a-z0-9-]*)([[:space:]].*)?$|\1|p' } -# Partial-replacement context reconstruction (Edit only), mirroring -# stale-path-verify's reconstruct_partial_edit (fixed for the same defect class -# by 65b4f67c, #1432). +# Partial-replacement context reconstruction (Edit only). The same shape lives in +# stale-path-verify and cli-flag-verify; stale-path-verify was fixed for this +# defect class by 65b4f67c (#1432) and this one goes one step further with the +# uniqueness requirement below, so the three are not yet identical. # # An Edit may replace an arbitrary substring: swapping `setup` for `ghost` inside # an existing `/alpha:setup` leaves `/alpha:ghost` on disk, but the hunk is the @@ -157,15 +158,23 @@ emit_refs() { # newly-broken reference would be silently missed. # # Recover bounded context: the edit is already applied by PostToolUse time, so -# pull from disk only the lines the hunk's OWN TEXT appears in, scan those, and -# keep only references whose plugin or skill segment contains one of the hunk's -# word tokens. What line-anchoring actually guarantees: it can only ever select a -# STRICT SUBSET of what token-anchoring alone would, and the edited line is always -# in that subset — never a wider net. It degrades to plain token-anchoring in the -# limiting case where the whole hunk IS a single short token (a bare `host` -# substitution carries no more positional information than the token itself), so -# the token filter stays a real second gate, not a formality, on the candidate -# that survives. +# pull from disk only the lines the hunk's OWN TEXT UNIQUELY locates, scan those, +# and keep only references whose plugin or skill segment contains one of the +# hunk's word tokens. Two independent gates, and the first one is where the +# diff-scope contract actually lives: +# +# 1. LOCATE by the hunk's own lines, and only where a line matches exactly once. +# Every line of new_string is on disk verbatim, so a unique match IS the line +# the edit landed in. A hunk line that matches several lines — most sharply +# when the whole hunk is one short word — cannot distinguish them, so it is +# dropped rather than unioned; unioning is exactly how a token-length anchor +# drags in an untouched reference elsewhere in the file. +# 2. FILTER the references found there by the hunk's word tokens. +# +# Gate 2 alone is not sufficient and was never the guarantee: a token short +# enough to occur in unrelated prose is also short enough to be a substring of an +# untouched skill segment, so it would pass the reference through. Uniqueness at +# gate 1 is what keeps the guard inside the diff. reconstruct_partial_edit() { [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0 # The token filter reads the hunk with any COMPLETE reference removed first. A @@ -186,16 +195,26 @@ reconstruct_partial_edit() { # new_string is on disk verbatim, so it matches the line the edit landed in; a # token, being shorter, also matches lines the edit never touched — a bare # `legacy` in unrelated prose pulls in every `/alpha:*-legacy` reference on any - # line, and an untouched broken one among them would fire. Line-anchoring can - # only ever select a subset of what token-anchoring would, and the edited line - # is always in that subset. + # line, and an untouched broken one among them would fire. local -a anchors=() mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null) ((${#anchors[@]})) || return 0 - local anchor lines ctx="" + # An anchor is used ONLY when it locates exactly ONE line. Several matches mean + # the anchor cannot say which of them the edit landed in, and unioning them + # re-opens the very false positive line-anchoring exists to close: a hunk that + # is itself just `legacy` matches both the edited prose line and an untouched + # `` `/alpha:ghost-legacy` `` line, and the token filter — `legacy` being a + # substring of that skill segment — passes it straight through. So ambiguous + # anchors are dropped, not unioned. The cost is a missed advisory when an edit + # lands in a line duplicated verbatim elsewhere in the same file; for a + # detect-then-judge guard that is the right side of the trade, which is + # degraded far worse by being wrong when it speaks than by staying quiet. + local anchor ctx="" + local -a hits=() for anchor in "${anchors[@]}"; do - lines=$(grep -F -- "$anchor" "$FILE" 2>/dev/null) - [[ -n "$lines" ]] && ctx+="$lines"$'\n' + mapfile -t hits < <(grep -F -- "$anchor" "$FILE" 2>/dev/null) + ((${#hits[@]} == 1)) || continue + ctx+="${hits[0]}"$'\n' done [[ -n "$ctx" ]] || return 0 local saved="$SCAN_CONTENT" diff --git a/plugins/guardrails/hooks/skill-reference-verify.test.sh b/plugins/guardrails/hooks/skill-reference-verify.test.sh index a60bca5381c..5ba9783baae 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.test.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.test.sh @@ -281,6 +281,21 @@ RC=$? assert_exit "prose hunk sharing a word token → exit 0" 0 "$RC" assert_silent "hunk sharing only a token does not drag in an untouched broken reference" "$OUT" +# The DEGENERATE shape of the same defect: the hunk IS the shared word, so its +# anchor is no longer than the token and matches BOTH the edited prose line and +# the untouched reference. Anchoring on lines cannot separate them here — only +# requiring the anchor to locate exactly ONE line does. An anchor matching several +# cannot say which the edit landed in, so it is dropped rather than unioned; +# unioning fired `UNRESOLVED_SKILL: /alpha:ghost-legacy` from an edit that never +# touched it, since `legacy` is also a substring of that skill segment and so +# clears the token filter. Trading this for a missed advisory when an edit lands +# in a verbatim-duplicated line is deliberate — an advisory guard is degraded +# worse by speaking wrongly than by staying quiet. +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$SEGSHARE" 'legacy')" 2>&1) +RC=$? +assert_exit "bare-token hunk matching several lines → exit 0" 0 "$RC" +assert_silent "ambiguous anchor is dropped, not unioned" "$OUT" + # A hunk that already carries a full command is scanned directly. OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL2" 'Run `/alpha:ghost-three` now.')" 2>&1) assert_contains "full-command hunk → scanned directly" "$OUT" \ From 1d586c3103b3bf27af1ed0fa079e41b88c16ea61 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sun, 26 Jul 2026 00:15:56 -0400 Subject: [PATCH 4/5] docs(guardrails): cite the real tracking issue for the sibling-guard class MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous bullet said stale-path-verify and cli-flag-verify "are tracked separately" without a number — an unsupported cross-reference, which is the same overclaim class the commit it sits in exists to correct. #547 is the open issue covering the guard-wide false-positive class those two belong to; cited directly, with the vaguer clause replaced by the factual "not fixed here". Co-Authored-By: Claude Opus 5 (1M context) --- plugins/guardrails/CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index 1cb84cb90cd..12006c6cd64 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -25,8 +25,9 @@ All notable changes to the `guardrails` plugin are documented here. Format follo bare-token shapes; the existing partial-replacement true-positive cases keep passing, with the composite (complete-reference-plus-bare-word) case reshaped onto a realistic multi-line hunk since a single Edit's `new_string` cannot land in two disjoint places on disk. `stale-path-verify` and - `cli-flag-verify` carry the same reconstruction shape and are tracked separately — see `#1432` - (`65b4f67c`) for the sibling fix this ports from. + `cli-flag-verify` carry the same reconstruction shape and are not fixed here; the guard-wide + false-positive class they belong to is tracked on `#547`, and `#1432` (`65b4f67c`) is the sibling + fix this ports from. ## [0.16.1] From f0887b3fb15bdc4ed6e677af584f545ea8fb0823 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sun, 26 Jul 2026 00:30:56 -0400 Subject: [PATCH 5/5] fix(guardrails): count anchor occurrences and exempt replace_all edits MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two follow-up findings on #1466, both reproduced against the branch head before changing anything. Counting matching LINES was the wrong granularity. Two occurrences of the anchor on one physical line are a single grep hit, so the uniqueness gate saw nothing wrong: inserting `legacy` into a line that already carried an untouched `/alpha:ghost-legacy` reported that reference, from a call that never wrote it. The gate now counts occurrences, which subsumes counting lines — one occurrence can only be on one line — so the line check is gone rather than doubled up. Requiring uniqueness also broke `replace_all`, which the guard never read. Per the Edit tool reference fetched this session (https://code.claude.com/docs/en/tools-reference), `old_string` must occur exactly once and `replace_all: true` is how every occurrence is edited instead. There, repeated matches are the edit's own footprint, so demanding one silenced the guard on a genuine multi-site break: `setup` -> `ghost` across two references reported neither. `replace_all` is now read from the payload and every match retained. The header comment asserted "uniqueness at gate 1 is what keeps the guard inside the diff", which the same-line case disproved — corrected, along with the CHANGELOG. Both remaining costs are now stated rather than implied: a dropped advisory when the anchor repeats verbatim, and, under `replace_all`, a retained line that independently read the same and was never touched. Nothing in the payload separates that last one; reconstruction is a best effort under an advisory guard, not a proof. Tests: same-line-double-occurrence and `replace_all` cases added, both verified to fail against the previous commit. The `replace_all` payload is built inline rather than in guardrails-test-helpers.sh, which is shared across guard suites and gated by hook-utils-sync. 68/68 pass; shellcheck and markdownlint clean on the touched paths. Co-Authored-By: Claude Opus 5 (1M context) --- plugins/guardrails/CHANGELOG.md | 46 ++++++------ .../hooks/skill-reference-verify.sh | 71 +++++++++++++------ .../hooks/skill-reference-verify.test.sh | 31 ++++++++ 3 files changed, 106 insertions(+), 42 deletions(-) diff --git a/plugins/guardrails/CHANGELOG.md b/plugins/guardrails/CHANGELOG.md index 12006c6cd64..d446d5ff393 100644 --- a/plugins/guardrails/CHANGELOG.md +++ b/plugins/guardrails/CHANGELOG.md @@ -7,27 +7,31 @@ All notable changes to the `guardrails` plugin are documented here. Format follo ### Fixed -- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own lines and - only where they locate a single line, not on its word tokens (#1453).** The guard's header comment - claimed the token filter held the diff-scope contract — a pre-existing unrelated reference sharing - a recovered line never fires — but a 4+ character word token is short enough to occur on lines the - edit never touched: a hunk of unrelated prose containing `legacy` grepped back every `*-legacy` - reference in the file, including an untouched broken one, which then passed the substring gate and - fired from an edit that never touched it. Lines are now located by the hunk's own text: every line - of `new_string` is on disk verbatim by `PostToolUse` time, so a match is the line the edit landed - in. Anchoring on lines alone is not enough, because a hunk can be one short word and then the - anchor is no longer than the token it was replacing — so an anchor is used only when it matches - **exactly one** line, and an ambiguous anchor is dropped rather than unioned. That is what closes - the false positive; the token filter is a second gate on what survives, never the locator. Cost of - the trade: an edit landing in a line duplicated verbatim elsewhere in the same file now goes - unreported, which is the right side of the trade for a detect-then-judge guard, degraded far worse - by speaking wrongly than by staying quiet. Two regression tests cover the shared-token and - bare-token shapes; the existing partial-replacement true-positive cases keep passing, with the - composite (complete-reference-plus-bare-word) case reshaped onto a realistic multi-line hunk since - a single Edit's `new_string` cannot land in two disjoint places on disk. `stale-path-verify` and - `cli-flag-verify` carry the same reconstruction shape and are not fixed here; the guard-wide - false-positive class they belong to is tracked on `#547`, and `#1432` (`65b4f67c`) is the sibling - fix this ports from. +- **`skill-reference-verify`'s partial-Edit reconstruction now anchors on the hunk's own text, and + only where that text occurs exactly once, instead of on its word tokens (#1453).** The guard's + header comment claimed the token filter held the diff-scope contract — a pre-existing unrelated + reference sharing a recovered line never fires — but a 4+ character word token is short enough to + occur where the edit never landed: a hunk of unrelated prose containing `legacy` grepped back every + `*-legacy` reference in the file, including an untouched broken one, which then passed the + substring gate and fired from an edit that never touched it. Anchors are now the hunk's own lines, + each on disk verbatim by `PostToolUse` time, and an anchor is used only when it **occurs exactly + once**; anything repeated cannot say which copy the edit landed on and is dropped rather than + unioned. Occurrences, not matching lines — two copies on one physical line are a single `grep` hit, + so inserting `legacy` into a line that already carried an untouched `` `/alpha:ghost-legacy` `` + would otherwise still fire. The token filter survives as a second gate on what the locator returns, + never as the locator. `replace_all` is read from the payload and exempted: there every occurrence + is a site this call edited, so requiring uniqueness would silence the guard on a genuine multi-site + break. Costs, stated rather than papered over — an edit landing in text that repeats verbatim + elsewhere goes unreported, and under `replace_all` a line that independently read the same is kept + even though the edit never touched it. Both are the right side of the trade for a detect-then-judge + guard, degraded far worse by speaking wrongly than by staying quiet, and reconstruction stays a + best effort rather than a proof. Four regression tests cover the shared-token, bare-token, + same-line-double-occurrence, and `replace_all` shapes; the existing partial-replacement + true-positive cases keep passing, with the composite (complete-reference-plus-bare-word) case + reshaped onto a realistic multi-line hunk since a single Edit's `new_string` cannot land in two + disjoint places on disk. `stale-path-verify` and `cli-flag-verify` carry the same reconstruction + shape and are not fixed here; the guard-wide false-positive class they belong to is tracked on + `#547`, and `#1432` (`65b4f67c`) is the sibling fix this ports from. ## [0.16.1] diff --git a/plugins/guardrails/hooks/skill-reference-verify.sh b/plugins/guardrails/hooks/skill-reference-verify.sh index 65a78f0b440..d4a013612f4 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.sh @@ -66,8 +66,18 @@ esac # Diff-scope: verify only the content THIS tool call wrote, never re-read the # whole file from disk. TOOL=$(printf '%s' "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null | tr -d '\r') +# Edit's `replace_all` (documented at +# https://code.claude.com/docs/en/tools-reference — Edit requires `old_string` to +# occur exactly once, and `replace_all: true` is how Claude edits every occurrence +# instead). Reconstruction needs it: with `replace_all` the same `new_string` +# lands in several places on purpose, so several matches are the edit's own +# footprint rather than an ambiguity. Absent or false on every ordinary Edit. +REPLACE_ALL=false case "$TOOL" in -Edit) SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') ;; +Edit) + SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.new_string // empty' 2>/dev/null | tr -d '\r') + REPLACE_ALL=$(printf '%s' "$INPUT" | jq -r '(.tool_input.replace_all // false) | tostring' 2>/dev/null | tr -d '\r') + ;; Write) SCAN_CONTENT=$(printf '%s' "$INPUT" | jq -r '.tool_input.content // empty' 2>/dev/null | tr -d '\r') ;; *) exit 0 ;; esac @@ -160,21 +170,26 @@ emit_refs() { # Recover bounded context: the edit is already applied by PostToolUse time, so # pull from disk only the lines the hunk's OWN TEXT UNIQUELY locates, scan those, # and keep only references whose plugin or skill segment contains one of the -# hunk's word tokens. Two independent gates, and the first one is where the -# diff-scope contract actually lives: +# hunk's word tokens. Two gates, and the first is where diff-scope actually lives: # -# 1. LOCATE by the hunk's own lines, and only where a line matches exactly once. -# Every line of new_string is on disk verbatim, so a unique match IS the line -# the edit landed in. A hunk line that matches several lines — most sharply -# when the whole hunk is one short word — cannot distinguish them, so it is -# dropped rather than unioned; unioning is exactly how a token-length anchor -# drags in an untouched reference elsewhere in the file. +# 1. LOCATE by the hunk's own lines, and only where a line OCCURS exactly once +# in the file. Every line of new_string is on disk verbatim, so a unique +# occurrence IS where the edit landed. Anything repeated cannot say which +# copy that was, so it is dropped rather than unioned. Occurrences, not +# matching lines — two copies on one physical line are a single grep hit and +# would otherwise slip through. Exception: under `replace_all` every +# occurrence is a place this call edited, so all are kept. # 2. FILTER the references found there by the hunk's word tokens. # # Gate 2 alone is not sufficient and was never the guarantee: a token short # enough to occur in unrelated prose is also short enough to be a substring of an # untouched skill segment, so it would pass the reference through. Uniqueness at # gate 1 is what keeps the guard inside the diff. +# +# What this does NOT claim: the `replace_all` branch keeps every occurrence, +# including one that pre-existed the edit and merely happens to read the same — +# nothing in the payload separates those. Reconstruction is a best effort under an +# advisory guard, not a proof that every reported line was written by this call. reconstruct_partial_edit() { [[ "$TOOL" == "Edit" && -f "$FILE" ]] || return 0 # The token filter reads the hunk with any COMPLETE reference removed first. A @@ -199,21 +214,35 @@ reconstruct_partial_edit() { local -a anchors=() mapfile -t anchors < <(printf '%s' "$SCAN_CONTENT" | grep -vE '^[[:space:]]*$' 2>/dev/null) ((${#anchors[@]})) || return 0 - # An anchor is used ONLY when it locates exactly ONE line. Several matches mean - # the anchor cannot say which of them the edit landed in, and unioning them - # re-opens the very false positive line-anchoring exists to close: a hunk that - # is itself just `legacy` matches both the edited prose line and an untouched - # `` `/alpha:ghost-legacy` `` line, and the token filter — `legacy` being a - # substring of that skill segment — passes it straight through. So ambiguous - # anchors are dropped, not unioned. The cost is a missed advisory when an edit - # lands in a line duplicated verbatim elsewhere in the same file; for a - # detect-then-judge guard that is the right side of the trade, which is - # degraded far worse by being wrong when it speaks than by staying quiet. - local anchor ctx="" + # An anchor is used ONLY when it OCCURS exactly once in the file — occurrences, + # not matching lines. Counting lines is not enough: two occurrences on one + # physical line are one grep hit, and that is a real shape — inserting `legacy` + # into a line that already carries an untouched `` `/alpha:ghost-legacy` `` + # leaves the anchor twice on that line, and reporting the reference would be an + # advisory about text this call never wrote. Occurrence uniqueness subsumes line + # uniqueness (one occurrence can only be on one line), so it is the only gate. + # + # A non-unique anchor cannot say WHICH occurrence the edit landed on, so it is + # dropped rather than unioned. Cost: a missed advisory when an edit lands in + # text that repeats verbatim elsewhere in the file. For a detect-then-judge + # guard that is the right side of the trade — it is degraded far worse by being + # wrong when it speaks than by staying quiet. + local anchor occ ctx="" local -a hits=() for anchor in "${anchors[@]}"; do mapfile -t hits < <(grep -F -- "$anchor" "$FILE" 2>/dev/null) - ((${#hits[@]} == 1)) || continue + ((${#hits[@]})) || continue + # `replace_all` is the one case where repetition is expected rather than + # ambiguous: every occurrence is a place THIS call edited, so all of them are + # in scope and uniqueness must not be required. Accepted narrowing — a line + # that independently contained `new_string` and was never touched is kept too, + # since nothing in the payload distinguishes it from an edited one. + if [[ "$REPLACE_ALL" == "true" ]]; then + for occ in "${hits[@]}"; do ctx+="$occ"$'\n'; done + continue + fi + occ=$(grep -o -F -- "$anchor" "$FILE" 2>/dev/null | grep -c .) + ((occ == 1)) || continue ctx+="${hits[0]}"$'\n' done [[ -n "$ctx" ]] || return 0 diff --git a/plugins/guardrails/hooks/skill-reference-verify.test.sh b/plugins/guardrails/hooks/skill-reference-verify.test.sh index 5ba9783baae..e3e40892342 100755 --- a/plugins/guardrails/hooks/skill-reference-verify.test.sh +++ b/plugins/guardrails/hooks/skill-reference-verify.test.sh @@ -296,6 +296,37 @@ RC=$? assert_exit "bare-token hunk matching several lines → exit 0" 0 "$RC" assert_silent "ambiguous anchor is dropped, not unioned" "$OUT" +# Same defect one level finer: both occurrences of the anchor are on ONE physical +# line, so `grep` reports a single matching line and a line-count uniqueness check +# sees nothing wrong. Inserting `legacy` into a line that already carried an +# untouched reference must not report that reference — this call never wrote it. +# The gate therefore counts OCCURRENCES, which subsumes counting lines. +SAMELINE="$REPO/sameline.md" +printf 'Run `/alpha:ghost-sameline` and note the sameline convention.\n' >"$SAMELINE" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$SAMELINE" 'sameline')" 2>&1) +RC=$? +assert_exit "anchor occurring twice on one line → exit 0" 0 "$RC" +assert_silent "two occurrences on a single line are ambiguous, not unique" "$OUT" + +# `replace_all` is the one shape where repetition is EXPECTED, not ambiguous: +# every occurrence is a place this call edited, so uniqueness must not be +# required or the guard goes silent on a genuine multi-site break. Built inline +# rather than through edit_json — that helper is shared across guard suites and +# gated by hook-utils-sync, so this suite's payload variant stays local to it. +replall_json() { + MSYS_NO_PATHCONV=1 jq -n --arg fp "$1" --arg s "$2" \ + '{tool_name:"Edit",tool_input:{file_path:$fp,new_string:$s,replace_all:true}}' +} +REPLALL="$REPO/replall.md" +printf 'First `/alpha:ghost-one` here.\nSecond `/alpha:ghost-two` there.\n' >"$REPLALL" +OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(replall_json "$REPLALL" 'ghost')" 2>&1) +RC=$? +assert_exit "replace_all Edit → exit 0" 0 "$RC" +assert_contains "replace_all → first edited reference reported" "$OUT" \ + "UNRESOLVED_SKILL: /alpha:ghost-one" +assert_contains "replace_all → second edited reference reported" "$OUT" \ + "UNRESOLVED_SKILL: /alpha:ghost-two" + # A hunk that already carries a full command is scanned directly. OUT=$(CLAUDE_PROJECT_DIR="$REPO" bash "$HOOK" <<<"$(edit_json "$PARTIAL2" 'Run `/alpha:ghost-three` now.')" 2>&1) assert_contains "full-command hunk → scanned directly" "$OUT" \