feat(toolkit): verify-branch-state skill + /verify + warn-mode hook (DOJ-4872) — v1.31.0

[lapc506]

Summary

Plugin-layer (Level 1) extension of the working-tree-vs-ref discipline rule. This release operationalizes memory feedback_working_tree_is_not_truth at the toolkit layer so the rule travels with the plugin to every repo it's installed in.

Incident origin (2026-06-03). A re-audit subagent correctly flagged usePathwayViewModel.ts as deleted on develop during DOJ-4849 triage. The orchestrator "corrected" the subagent by running ls src/hooks/path/usePathwayViewModel.ts against a local main checkout that another session had switched to a different branch. The bare-FS read returned a stale projection; authoritative "FRESH — proceed as briefed" comments went to DOJ-4851/4863/4864 and had to be retracted publicly. Root cause: working tree was treated as truth instead of one projection.

Defense in depth. Earlier today, DOJ-4868 shipped the repo-layer (Level 2) enforcement via .claude/hooks/ + root CLAUDE.md in dojo-os (PR #2604). DOJ-4872 ships the plugin-layer (Level 1) here: skill + slash command + warn-mode PreToolUse hook. Without it, agents using make-no-mistakes-toolkit in any other repo have zero guidance about the rule.

Linear: DOJ-4872
Sibling: DOJ-4868 (dojo-os, Level 2)
Memory: feedback_working_tree_is_not_truth
Release: v1.30.0 → v1.31.0

What ships

4 new artifacts:

1. skills/verify-branch-state/SKILL.md — auto-loading skill, tuned description triggers on "verify against develop", "does X exist on <branch>", "what's on origin/…", "did this land on main", "re-validate the subagent", "before I claim", "post-merge state". Body covers the rule statement, canonical ref-explicit commands (git fetch + git show / ls-tree / grep / diff against origin/<ref>), anti-patterns (ls, grep -rn src/, find, git status), pre-flight checklist, multi-worktree context, and the 2026-06-03 origin incident.

2. commands/verify.md — slash command /verify <ref> <path-or-pattern>. Runs git fetch origin <ref> --quiet then git ls-tree origin/<ref> -- <path> for paths or git grep <pattern> origin/<ref> -- src/ for patterns. Emits a single verdict line citing the ref's short SHA in the shape origin/<ref> @ <sha7> — <path-or-pattern> <PRESENT|NOT PRESENT|N MATCHES> so the claim can be re-checked later. Handles ref-not-found, shell metacharacters in patterns, and squash-merge cache staleness (always re-fetches).

3. hooks/pre-tool-use-claim-verification.sh — warn-mode PreToolUse hook, repo-agnostic, no per-repo manifest required. Detects bare-FS verification ops (ls, grep -rn src/, find src/, cat src/, head src/) and, when combined with intent keywords in the recent context envelope (or CLAUDE_HOOK_CONTEXT for smoke tests), prints a stderr warning with the local checkout's HEAD ref + short SHA, a suggested ref-explicit replacement specific to the detected op, and pointers to the skill + slash command. Always exit 0. Defensive set +e. Uses cd -P + pwd -P from day 1 (DOJ-4868 PR #2604 lesson). Trailing-newline-safe while read. Honors CLAUDE_DISABLE_PLUGIN_HOOKS=1. Shellcheck clean.

4. CHANGELOG.md [1.31.0] - 2026-06-03 — Added / Changed / Why sections + reference link added at bottom.

4 edits:

5. hooks/hooks.json — registers the new hook under the Bash PreToolUse matcher with a 3-second timeout, alongside the existing pre-bash.sh dispatcher.
6. .claude-plugin/marketplace.json — top-level + plugin version 1.30.0 → 1.31.0; plugin description pair-mentions the new skill; component counts updated to 30 commands / 11 skills / 2 agents.
7. .claude-plugin/plugin.json — version 1.30.0 → 1.31.0.
8. package.json — version 1.30.0 → 1.31.0.
9. README.md — **Version:** header bumped; new "Also start here: verify-branch-state + /verify" peer subsection sits between the domain-driven-advisor "Start here" block and "What's Inside"; Commands table 29 → 30 (adds /verify); Skills table 10 → 11 (adds verify-branch-state).

Cohesive-PR exception (9 files)

9 files instead of the soft ≤8 target. The 4 new artifacts + 4 release-cut edits sum to 8; the 9th is hooks/hooks.json, which is required to make the new hook non-dead code. The whole set is a single cohesive surface (working-tree-vs-ref discipline) plus the standard release-cut shape mirroring v1.30.0's commit shape. Documented per CLAUDE.md rule 7 cohesive-PR exception.

Per-AC ship status

AC	Requirement	Status
AC1	Skill with frontmatter + tuned auto-trigger description	shipped
AC2	Slash command /verify <ref> <path-or-pattern> cites ref SHA	shipped
AC3	Hook: set +e, cd -P + pwd -P, exit 0 always, shellcheck clean	shipped
AC4	Versions 1.31.0 agree across 4 manifests	verified via jq
AC5	CHANGELOG entry under [1.31.0] - 2026-06-03 + reference link	shipped
AC6	README "Start here" peer subsection	shipped
AC7	Hook smoke tests pass	see below
AC8	Skill cites memory feedback_working_tree_is_not_truth	shipped
AC9	Cohesive PR ≤8 files	9 files; exception documented
AC10	Tag release v1.31.0	post-merge, manual

Smoke test outputs (AC7)

$ bash hooks/pre-tool-use-claim-verification.sh "ls src/foo.tsx"

[verify-branch-state] WARN: working-tree read used for a branch-level claim.

  Local HEAD: andres/doj-4872-toolkit-verify-branch-state-skill-v1.31.0 @ c513198
  Command:    ls src/foo.tsx

  This reads the working-tree projection, not the ref. The local checkout
  may have drifted (other sessions, worktrees, hooks). The ref is the truth.

  Suggested ref-explicit replacement:
    git fetch origin <branch> --quiet && git ls-tree origin/<branch> -- src/foo.tsx

  Or use the slash command (cites the ref's SHA for you):
    /make-no-mistakes:verify <branch> <path-or-pattern>

  See: skills/verify-branch-state/SKILL.md
  Memory: feedback_working_tree_is_not_truth (origin 2026-06-03)

  (warn-mode only — your command will still run)

$ bash hooks/pre-tool-use-claim-verification.sh "echo hello"
(silent — exit 0)

$ bash hooks/pre-tool-use-claim-verification.sh 'grep -rn "Symbol" src/'
[verify-branch-state] WARN: working-tree read used for a branch-level claim.
  Command:    grep -rn "Symbol" src/
  Suggested: git fetch origin <branch> --quiet && git grep "Symbol" origin/<branch> -- src/
  ...

$ bash hooks/pre-tool-use-claim-verification.sh 'find src/ -name "*.tsx"'
[verify-branch-state] WARN: ...
  Suggested: git fetch origin <branch> --quiet && git ls-tree -r origin/<branch> -- <path> | grep <pattern>

$ echo '{"tool_name":"Bash","tool_input":{"command":"ls src/foo.tsx"}}' | bash hooks/pre-tool-use-claim-verification.sh
(silent — no intent keyword in context envelope; bare ls alone does not trigger)

$ CLAUDE_HOOK_CONTEXT="does X exist on develop" bash -c 'echo "{...}" | bash hooks/pre-tool-use-claim-verification.sh'
[verify-branch-state] WARN: ... (intent ctx present → triggers)

$ shellcheck hooks/pre-tool-use-claim-verification.sh
(0 issues)

$ jq -r '.version' .claude-plugin/marketplace.json       # 1.31.0
$ jq -r '.plugins[0].version' .claude-plugin/marketplace.json   # 1.31.0
$ jq -r '.version' .claude-plugin/plugin.json            # 1.31.0
$ jq -r '.version' package.json                          # 1.31.0
$ grep '^\*\*Version:' README.md                         # **Version: 1.31.0**

Post-merge actions (deferred to maintainer)

These are explicitly out of this PR's scope and will be performed after merge by @lapc506:

• Tag the release: git tag -a v1.31.0 -m "v1.31.0" + git push origin v1.31.0 (AC10)
• Flip Linear DOJ-4872 → Done
• Post a thread reply to the v1.30.0 announcement in #doj-repo-health (Slack thread)

Test plan

• All four version manifests agree at 1.31.0 (jq -r '.version' … × 4)
• Hook smoke tests: warn on ls, silent on echo, warn on grep -rn, warn on find
• Hook stdin-mode: silent without intent ctx, warn with intent ctx
• shellcheck hooks/pre-tool-use-claim-verification.sh → 0 issues
• Hook honors CLAUDE_DISABLE_PLUGIN_HOOKS=1 (early exit 0)
• cd -P + pwd -P used for hook self-location (day 1, per DOJ-4868 PR #2604)
• Skill description field tuned for auto-trigger on the canonical intent phrases
• Slash command emits verdict line in citation-ready format
• CHANGELOG reference link added at bottom ([1.31.0]: …/releases/tag/v1.31.0)
• Marketplace plugin description pair-mentions the new skill
• README "Start here" peer subsection drafted to match the domain-driven-advisor style

Created by Claude Code on behalf of @lapc506.

[lapc506]

@dojo-code-reviewer review

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 2 P2, 2 P3. Confidence: 3/5.

🟡 P2 — Major

• commands/verify.md:42 — 🟡 P2 (major) — The slash command currently assumes the user always passes a branch name that needs to be prefixed with 'origin/'. However, if a user passes a remote-tracking branch like 'origin/develop', a tag like 'v1.31.0', or a commit SHA, this leads to failures like 'origin/origin/develop' or 'origin/v1.31.0' during fetch, rev-parse, and ls-tree/grep. Additionally, the hardcoded '-C "$REPO"' directory switches can fail if the environment hasn't defined the '$REPO' variable. Normalize the reference explicitly first to handle all formats seamlessly, and execute directly within the current workspace.

• hooks/pre-tool-use-claim-verification.sh:116 — 🟡 P2 (major) — The regex matches bare-filesystem operations followed by a space, which means it will fail to detect verification commands that appear at the end of a line or command string without a trailing space (for example, 'ls' alone or the end of a chain like 'cd src && ls'). Use '([[:space:]]|$)' to ensure the hook reliably triggers in these scenarios.

  if printf '%s' "$cmd" | grep -qE '(^|[;&|][[:space:]]*)(ls|find|cat|head)([[:space:]]|$)'; then

🔵 P3 — Minor

• hooks/pre-tool-use-claim-verification.sh:162 — 🔵 P3 (minor) — To ensure that the suggested replacement helper is chosen correctly when 'ls' is used at the end of a command string without trailing space, replace 'ls[[:space:]]' with 'ls([[:space:]]|$)'.

if printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)ls([[:space:]]|$)'; then

• hooks/pre-tool-use-claim-verification.sh:181 — 🔵 P3 (minor) — To ensure that the suggested replacement helper is chosen correctly when 'find' is used at the end of a command string without trailing space, replace 'find[[:space:]]' with 'find([[:space:]]|$)'.

elif printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)find([[:space:]]|$)'; then

---

Total findings: 2 compliance, 2 business context (4 total)

---

ℹ️ Inline anchoring failed for the comments below; they are listed here instead.

• commands/verify.md:42 — 🟡 P2 (major) — The slash command currently assumes the user always passes a branch name that needs to be prefixed with 'origin/'. However, if a user passes a remote-tracking branch like 'origin/develop', a tag like 'v1.31.0', or a commit SHA, this leads to failures like 'origin/origin/develop' or 'origin/v1.31.0' during fetch, rev-parse, and ls-tree/grep. Additionally, the hardcoded '-C "$REPO"' directory switches can fail if the environment hasn't defined the '$REPO' variable. Normalize the reference explicitly first to handle all formats seamlessly, and execute directly within the current workspace.
• hooks/pre-tool-use-claim-verification.sh:116 — 🟡 P2 (major) — The regex matches bare-filesystem operations followed by a space, which means it will fail to detect verification commands that appear at the end of a line or command string without a trailing space (for example, 'ls' alone or the end of a chain like 'cd src && ls'). Use '([[:space:]]|$)' to ensure the hook reliably triggers in these scenarios.

  if printf '%s' "$cmd" | grep -qE '(^|[;&|][[:space:]]*)(ls|find|cat|head)([[:space:]]|$)'; then

• hooks/pre-tool-use-claim-verification.sh:162 — 🔵 P3 (minor) — To ensure that the suggested replacement helper is chosen correctly when 'ls' is used at the end of a command string without trailing space, replace 'ls[[:space:]]' with 'ls([[:space:]]|$)'.

if printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)ls([[:space:]]|$)'; then

• hooks/pre-tool-use-claim-verification.sh:181 — 🔵 P3 (minor) — To ensure that the suggested replacement helper is chosen correctly when 'find' is used at the end of a command string without trailing space, replace 'find[[:space:]]' with 'find([[:space:]]|$)'.

elif printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)find([[:space:]]|$)'; then

[lapc506]

@dojo-code-reviewer review

Addressed all 4 findings from prior review (3/5 confidence):

• P2 commands/verify.md:42 — Added ref normalization step at the top of the Behavior pipeline. origin/<branch>, tags (refs/tags/<tag>), and commit SHAs are now resolved explicitly; bare branch names are the only case that synthesizes origin/<branch>. Dropped -C "$REPO" indirection — slash command's cwd is the repo. Verdict line shape updated to <resolved-ref> @ <sha7> with tag + SHA examples.
• P2 hooks/pre-tool-use-claim-verification.sh:116 — Detector regex trailing class [[:space:]] → ([[:space:]]|$). Bare ls, cd src && ls, find (no trailing space) now trigger correctly.
• P3 hooks/pre-tool-use-claim-verification.sh:162 — Same fix in the suggester's ls branch.
• P3 hooks/pre-tool-use-claim-verification.sh:181 — Same fix in the suggester's find branch.

Smoke tests + shellcheck still green. Fix commit: 31f10c9.

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 2 P3. Confidence: 4/5.

🔵 P3 — Minor

• hooks/pre-tool-use-claim-verification.sh:145 — 🔵 P3 (minor) — Simplify and make the path argument extraction for ls commands more robust. The current sed regular expression assumes the flags always have a trailing space, which fails to strip flags if they are at the end of the command (e.g., ls -la), resulting in path_arg being extracted as -la. Using awk to loop through the tokens and extract the first non-option token after ls is cleaner, shorter, and correctly handles trailing options or extra whitespace.

  path_arg="$(printf '%s' "$COMMAND" \
    | awk '{for(i=1;i<=NF;i++) if ($i == "ls") {for(j=i+1;j<=NF;j++) if ($j !~ /^-/) {print $j; exit}}}')"

• hooks/pre-tool-use-claim-verification.sh:158 — 🔵 P3 (minor) — Fix the grep pattern extraction when multiple option flags are specified separately. In the current implementation, if a user runs grep -i -r "Symbol" src/, the awk block matches -i and immediately extracts the next token $(i+1) (which is -r) as the pattern. By utilizing a nested loop in awk that skips any subsequent option tokens starting with -, you can correctly isolate the actual search pattern.

    pattern_arg="$(printf '%s' "$COMMAND" \
      | awk '{for(i=1;i<=NF;i++) if ($i ~ /^-[rRnliN]+$/) {for(j=i+1;j<=NF;j++) if ($j !~ /^-/) {print $j; exit}}}' \
      | tr -d '\"')"

---

Total findings: 2 business context (2 total)

---

ℹ️ Inline anchoring failed for the comments below; they are listed here instead.

• hooks/pre-tool-use-claim-verification.sh:145 — 🔵 P3 (minor) — Simplify and make the path argument extraction for ls commands more robust. The current sed regular expression assumes the flags always have a trailing space, which fails to strip flags if they are at the end of the command (e.g., ls -la), resulting in path_arg being extracted as -la. Using awk to loop through the tokens and extract the first non-option token after ls is cleaner, shorter, and correctly handles trailing options or extra whitespace.

  path_arg="$(printf '%s' "$COMMAND" \
    | awk '{for(i=1;i<=NF;i++) if ($i == "ls") {for(j=i+1;j<=NF;j++) if ($j !~ /^-/) {print $j; exit}}}')"

• hooks/pre-tool-use-claim-verification.sh:158 — 🔵 P3 (minor) — Fix the grep pattern extraction when multiple option flags are specified separately. In the current implementation, if a user runs grep -i -r "Symbol" src/, the awk block matches -i and immediately extracts the next token $(i+1) (which is -r) as the pattern. By utilizing a nested loop in awk that skips any subsequent option tokens starting with -, you can correctly isolate the actual search pattern.

    pattern_arg="$(printf '%s' "$COMMAND" \
      | awk '{for(i=1;i<=NF;i++) if ($i ~ /^-[rRnliN]+$/) {for(j=i+1;j<=NF;j++) if ($j !~ /^-/) {print $j; exit}}}' \
      | tr -d '\"')"

[lapc506]

@dojo-code-reviewer review

Round-2 feedback (4/5) addressed — both P3 items applied verbatim with explanatory comments. Fix commit: $(git rev-parse --short HEAD).

• P3 ls path extraction: awk-only nested loop replaces sed prefix-strip, fixes ls -la leaking -la as the path arg.
• P3 grep pattern extraction: nested awk loop skips additional flag tokens, fixes grep -i -r "Symbol" src/ mis-extracting -r as the pattern.

Smoke tests + shellcheck green.

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 1 P3. Confidence: 4/5.

🔵 P3 — Minor

• hooks/pre-tool-use-claim-verification.sh:185 — 🔵 P3 (minor) — Strip single quotes as well as double quotes in the fallback pattern extractor to handle single-quoted search patterns (e.g. grep -rn 'Symbol').

      | tr -d "\"'")"

---

Total findings: 1 business context (1 total)

---

ℹ️ Inline anchoring failed for the comments below; they are listed here instead.

• hooks/pre-tool-use-claim-verification.sh:185 — 🔵 P3 (minor) — Strip single quotes as well as double quotes in the fallback pattern extractor to handle single-quoted search patterns (e.g. grep -rn 'Symbol').

      | tr -d "\"'")"

[lapc506]

@dojo-code-reviewer review

Round-3 feedback (4/5, 1 P3) addressed:

• P3 single-quoted grep patterns: added a single-quote extractor branch parallel to the existing double-quote branch, and extended the awk-fallback tr -d to strip both " and '. grep -rn 'Symbol' src/, grep -i -r 'Symbol' src/, and the double-quoted equivalents all extract Symbol cleanly now.

Smoke tests + shellcheck green. Fix commit: $(git rev-parse --short HEAD).

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 1 P2, 3 P3. Confidence: 3/5.

🟡 P2 — Major

• hooks/pre-tool-use-claim-verification.sh:81 — 🟡 P2 (major) — The fallback regex "[^\"]*" stops at the first backslash (which JSON uses to escape internal double quotes), resulting in truncated command extraction when the executed bash command contains quotes (e.g. grep -rn \"Symbol\" src/). This causes subsequent command matching and warning suggestions to fail.

Using an escape-aware JSON string regex resolves this.

    | grep -oE '"command"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' \

🔵 P3 — Minor

• hooks/pre-tool-use-claim-verification.sh:164 — 🔵 P3 (minor) — Redundant backslashes inside a single-quoted string are treated as literal backslashes by some shells and grep implementations, which can cause pattern extraction to fail or behave inconsistently depending on the platform's grep engine (e.g. macOS BSD grep vs GNU grep). Removing the backslashes before the double quotes inside single quotes improves cross-platform reliability.

Please also apply the same cleanup to the double quote backslashes on line 166.

    | grep -oE 'grep[[:space:]]+-[rRnliN]+[[:space:]]+"[^"]+"' \

• commands/verify.md:112 — 🔵 P3 (minor) — Hardcoding -- src/ restricts pattern verification to the src/ directory. If the toolkit is installed in a repository that uses a different directory structure (e.g., lib/, app/, packages/, or root-level files), git grep will fail with a fatal pathspec error. Removing the -- src/ suffix or falling back to the repo root if src/ is absent makes the command truly generic and repo-agnostic.

• commands/verify.md:45 — 🔵 P3 (minor) — Remote-only tags will fail to resolve. If a tag (e.g., v1.31.0) exists on the remote but has not been fetched locally yet, git rev-parse will fail, pushing the ref to the else block which resolves it to the nonexistent branch origin/v1.31.0. Pre-fetching tags or querying git ls-remote first would prevent this failure mode.

---

Total findings: 1 compliance, 3 business context (4 total)

---

ℹ️ Inline anchoring failed for the comments below; they are listed here instead.

• hooks/pre-tool-use-claim-verification.sh:81 — 🟡 P2 (major) — The fallback regex "[^\"]*" stops at the first backslash (which JSON uses to escape internal double quotes), resulting in truncated command extraction when the executed bash command contains quotes (e.g. grep -rn \"Symbol\" src/). This causes subsequent command matching and warning suggestions to fail.

Using an escape-aware JSON string regex resolves this.

    | grep -oE '"command"[[:space:]]*:[[:space:]]*"([^"\\]|\\.)*"' \

• hooks/pre-tool-use-claim-verification.sh:164 — 🔵 P3 (minor) — Redundant backslashes inside a single-quoted string are treated as literal backslashes by some shells and grep implementations, which can cause pattern extraction to fail or behave inconsistently depending on the platform's grep engine (e.g. macOS BSD grep vs GNU grep). Removing the backslashes before the double quotes inside single quotes improves cross-platform reliability.

Please also apply the same cleanup to the double quote backslashes on line 166.

    | grep -oE 'grep[[:space:]]+-[rRnliN]+[[:space:]]+"[^"]+"' \

• commands/verify.md:112 — 🔵 P3 (minor) — Hardcoding -- src/ restricts pattern verification to the src/ directory. If the toolkit is installed in a repository that uses a different directory structure (e.g., lib/, app/, packages/, or root-level files), git grep will fail with a fatal pathspec error. Removing the -- src/ suffix or falling back to the repo root if src/ is absent makes the command truly generic and repo-agnostic.
• commands/verify.md:45 — 🔵 P3 (minor) — Remote-only tags will fail to resolve. If a tag (e.g., v1.31.0) exists on the remote but has not been fetched locally yet, git rev-parse will fail, pushing the ref to the else block which resolves it to the nonexistent branch origin/v1.31.0. Pre-fetching tags or querying git ls-remote first would prevent this failure mode.

[lapc506]

@dojo-code-reviewer review

Round-4 feedback (3/5, 1 P2 + 3 P3) addressed:

• P2 hook JSON command-extractor: switched the jq-less fallback regex from "[^"]*" to the escape-aware "([^"\\\\]|\\\\.)*" so envelopes containing grep -rn \"Symbol\" src/ extract the full command instead of truncating at the first inner quote. Verified end-to-end.
• P3 cross-platform grep quote-handling: removed the explicit single-quoted-pattern extractor branch (which used embedded-quote shell escaping fragile across GNU/BSD grep); the awk fallback already strips both " and ' so it covers both styles cleanly. Net code reduction.
• P3 commands/verify.md repo-agnostic grep: dropped hardcoded -- src/. Detect src/ on the resolved ref; if absent, pass no path filter so the command works in repos with lib/, app/, packages/, or flat layouts.
• P3 commands/verify.md remote-only tag: added a git ls-remote --tags --exit-code probe between the local-tag and SHA branches; on hit, fetches the tag before resolving so remote-only tags don't fall through to a nonexistent origin/<tag>.

Smoke tests + shellcheck green. Fix commit: $(git rev-parse --short HEAD).

[dojo-code-reviewer]

✅ Approved

Approved — 0 blockers, 4 P2. Confidence: 2/5.

🟡 P2 — Major

• commands/verify.md:44 — 🟡 P2 (major) — The ARG variable is used in later steps (e.g., "$ARG") but is never defined or assigned. This will cause $ARG to resolve to an empty string, breaking file path and pattern verification when Claude follows these instructions. Assigning ARG="$2" next to RAW_REF ensures proper parameter mapping.

   RAW_REF="$1"
   ARG="$2"

• commands/verify.md:54 — 🟡 P2 (major) — Running git fetch origin "tag $RAW_REF" (with quotes grouping the tag keyword and the tag name together) passes them as a single argument to Git. This will cause the fetch operation to fail with a "does not appear to be a git repository" error. Separating them as distinct arguments ensures the remote-only tag is fetched successfully.

     git fetch origin tag "$RAW_REF" --quiet

• hooks/pre-tool-use-claim-verification.sh:99 — 🟡 P2 (major) — The unanchored pattern grep[[:space:]]+-[rRnliN]+ matches any occurrence of grep followed by flags, which includes legitimate Git commands like git grep -n. This causes the hook to generate false-positive warnings even when users are running the exact ref-explicit git grep commands recommended by this very skill. Anchoring grep to the start of the command or a separator prevents these false positives.

  if printf '%s' "$cmd" | grep -qE '(^|[;&|][[:space:]]*)grep[[:space:]]+-[rRnliN]+'; then

• hooks/pre-tool-use-claim-verification.sh:145 — 🟡 P2 (major) — The unanchored pattern grep[[:space:]]+-[rRnliN]+ matches git grep here as well, causing false positives in the suggestion logic. Anchoring grep to the start of the command or a separator keeps the matching logic consistent with the detector.

elif printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)grep[[:space:]]+-[rRnliN]+'; then

---

Total findings: 4 compliance (4 total)

---

ℹ️ Inline anchoring failed for the comments below; they are listed here instead.

• commands/verify.md:44 — 🟡 P2 (major) — The ARG variable is used in later steps (e.g., "$ARG") but is never defined or assigned. This will cause $ARG to resolve to an empty string, breaking file path and pattern verification when Claude follows these instructions. Assigning ARG="$2" next to RAW_REF ensures proper parameter mapping.

   RAW_REF="$1"
   ARG="$2"

• commands/verify.md:54 — 🟡 P2 (major) — Running git fetch origin "tag $RAW_REF" (with quotes grouping the tag keyword and the tag name together) passes them as a single argument to Git. This will cause the fetch operation to fail with a "does not appear to be a git repository" error. Separating them as distinct arguments ensures the remote-only tag is fetched successfully.

     git fetch origin tag "$RAW_REF" --quiet

• hooks/pre-tool-use-claim-verification.sh:99 — 🟡 P2 (major) — The unanchored pattern grep[[:space:]]+-[rRnliN]+ matches any occurrence of grep followed by flags, which includes legitimate Git commands like git grep -n. This causes the hook to generate false-positive warnings even when users are running the exact ref-explicit git grep commands recommended by this very skill. Anchoring grep to the start of the command or a separator prevents these false positives.

  if printf '%s' "$cmd" | grep -qE '(^|[;&|][[:space:]]*)grep[[:space:]]+-[rRnliN]+'; then

• hooks/pre-tool-use-claim-verification.sh:145 — 🟡 P2 (major) — The unanchored pattern grep[[:space:]]+-[rRnliN]+ matches git grep here as well, causing false positives in the suggestion logic. Anchoring grep to the start of the command or a separator keeps the matching logic consistent with the detector.

elif printf '%s' "$COMMAND" | grep -qE '(^|[;&|][[:space:]]*)grep[[:space:]]+-[rRnliN]+'; then

[lapc506]

@dojo-code-reviewer review

Round-5 feedback (2/5, 4 P2) addressed — all four were real correctness bugs:

• P2 hook detector: anchored grep -FLAGS so git grep -n no longer false-positives. Critical fix — the hook was attacking its own ref-explicit recommendation, creating a self-defeating warning loop.
• P2 hook suggester: same anchor applied in the suggester branch.
• P2 commands/verify.md ARG undefined: added ARG="$2" next to RAW_REF="$1". Without it, following the example verbatim would leave $ARG empty and break every verification.
• P2 commands/verify.md tag-fetch arg gluing: switched git fetch origin "tag $RAW_REF" to separate tag + "$RAW_REF" args, and refactored step 3 to a case-statement dispatcher over $FETCH_KIND ("tag" | "branch" | "") so the tag vs branch fetch shapes stay distinct.

Smoke tests + shellcheck green. Fix commit: $(git rev-parse --short HEAD).

[dojo-code-reviewer]

✅ Approved

Approved — no findings. Confidence: 5/5.

[dojo-code-reviewer]

✅ Approved

Approved — no findings. Confidence: 5.00/5.00.

Walkthrough

⚠️ GOVERNANCE WARNING: This PR targets the main branch directly. Standard GitFlow workflow expects features to target develop first (feature → develop → main). Since the code itself is functionally sound and fully backward-compatible, this is an informative warning and does not block approval.

Walkthrough

This PR implements the verify-branch-state skill, the /verify slash command, and the plugin-wide pre-tool-use-claim-verification.sh hook. It enforces the core discipline that the local working tree is only one projection of the repository, while the remote/fetched ref is the absolute truth, preventing agent footguns when answering branch-level questions in multi-worktree/multi-session environments.

Files Reviewed

• hooks/pre-tool-use-claim-verification.sh (Warn-mode detector, awk suggestions, fail-open logic)
• commands/verify.md (Ref-explicit command, tag/branch/SHA normalization, remote tag fetching)
• skills/verify-branch-state/SKILL.md (Auto-triggering skill definition, checklist, incident reference)
• hooks/hooks.json (Registration under the Bash matcher with 3s timeout)
• .claude-plugin/marketplace.json, CHANGELOG.md, and README.md (Release manifest updates and documentation additions)

Safety Rationale

The hook operates entirely in warn-mode (set +e and guaranteed exit 0 on all paths) and fails open gracefully if jq or git tools are missing or if any path resolution fails, making it extremely safe to deploy.

Verdict

Approved — no findings.