guard-audit

Analyze branch guard configuration to find false positives and reduce friction. Proposes changes to .claude/branch-guard.json — never modifies the guard script itself.

When to Use

• User reports branch guard blocking legitimate operations
• User says "audit guard", "tune guard", "guard friction"
• After multiple guard false positives in a session
• User wants to understand guard behavior

Prerequisites

• scripts/branch-guard.sh must exist (the guard script)
• Git repository with branch protection enabled

Guard Audit Pipeline

Execute these steps in order.

Step 1: Discovery

Read the branch guard script and extract all protection rules:

# Extract protection patterns from branch-guard.sh
grep -n "BLOCKED\|blocked\|exit 2\|protection" scripts/branch-guard.sh

# Extract regex patterns used for detection
grep -n "grep.*-E\|=~\|pattern\|regex" scripts/branch-guard.sh

# Read existing config (if any)
cat .claude/branch-guard.json 2>/dev/null || echo "No config file found"

Present a summary:

┌───────────────────────────────────────────────────────────────┐
│ GUARD DISCOVERY                                               │
├───────────────────────────────────────────────────────────────┤
│ Script:    scripts/branch-guard.sh (N lines)                  │
│ Config:    .claude/branch-guard.json (found/not found — flat  │
│            branch→level map, e.g. {"main":"block-all"})       │
│ Branches:  main (block-all), dev (smart), feature/* (none)    │
│                                                               │
│ Protection Rules Found:                                       │
│   1. [HIGH] Destructive git commands (reset --hard, clean -f) │
│   2. [HIGH] Force push to protected branches                  │
│   3. [MEDIUM] New code files via Write or shell redirection   │
│   4. [MEDIUM] Guard-bypass marker creation                    │
│   ... (N total rules)                                         │
└───────────────────────────────────────────────────────────────┘

Step 1b: Matcher-Overlap Check

Check ~/.claude/settings.json for duplicate PreToolUse matcher strings:

jq -r '.hooks.PreToolUse[]?.matcher // empty' ~/.claude/settings.json | sort | uniq -d

If any duplicates appear, flag them — a guard registered twice fires twice for that tool, causing double prompts.

Progress indicator: [1b/5] Matcher-overlap .......... DONE (N duplicates found)

Step 1c: Duplicated Rule Coverage + Guard State

Rule coverage check: Scan both scripts/branch-guard.sh and scripts/no-switch-guard.sh for patterns that handle the same git operations. Common overlap site: git restore / git checkout -- <file> (data-loss detection).

# Check if both guards handle restore
grep -n 'restore\|checkout.*--' scripts/branch-guard.sh
grep -n 'restore\|checkout.*--' scripts/no-switch-guard.sh

Flag any operation handled by BOTH guards (double prompts; ownership should be assigned to one).

Guard state: Surface disabled or muted guards so audit context includes current guard state:

jq -r '.guards | to_entries[] | "\(.key): enabled=\(.value.enabled // true), muted_until=\(.value.muted_until // "null")"' \
  ~/.claude/guards.json 2>/dev/null || echo "(guards.json not found — guards at default state)"

Progress indicator: [1c/5] Rule-coverage + state ...... DONE (N overlaps, M muted)

Step 2: Friction Analysis

For each rule, identify scenarios where it produces false positives:

| Rule | Intended Block | False Positive Scenario | |------|---------------|------------------------| | Force push detection | Force push to main/dev | Rebased feature branch push (already excluded — verify the branch was matched correctly) | | New code files on dev (shell redirection) | echo/cat/tee/cp/touch writing code to dev | A > character, or the keyword cp, tee, or touch followed by a space, appearing INSIDE a single- or double-quoted argument (an awk/grep/sed program, a search pattern) — text, not real shell syntax | | New code files on dev (path scoping) | Writes landing inside the repo tree | A target outside PROJECT_ROOT entirely (/tmp/..., $HOME/...) — poses no risk to this repo's branch | | File extension detection | Source code files | Generated/template files with a non-code extension already in NONCODE_EXTENSIONS |

Step 3: Test Harness

Generate test scenarios and report which ones trigger incorrectly:

# Test 1: PR body with documentation about git commands
# Should NOT trigger — it's documentation, not actual commands
echo "Testing: PR body with 'git reset' in docs context..."

# Test 2: Force push on feature branch
# Should NOT trigger — feature branches allow force push
echo "Testing: Force push on feature/my-feature..."

# Test 3: Config file write on dev
# Should allow — .json/.yaml are config, not code
echo "Testing: Write .claude/branch-guard.json on dev..."

# Test 4: Markdown file on dev
# Should allow — .md files are documentation
echo "Testing: Write docs/guide.md on dev..."

Step 4: Report

First, classify each false positive by what can actually fix it — this determines whether Step 5 applies at all:

| Class | What it looks like | Fixable via config? | |---|---|---| | Branch policy | The wrong protection level for a branch (e.g. a research repo's draft branch needs smart but has none) | Yes — Step 5's flat schema | | Detection logic | The guard misparses a specific command regardless of branch — e.g. a > inside a quoted awk/grep program read as a redirect, or an out-of-repo target (/tmp/...) flagged as an in-repo write | No — this is a bug in scripts/branch-guard.sh itself; only a code fix (PR) resolves it |

Output a friction report with specific recommendations:

┌───────────────────────────────────────────────────────────────┐
│ GUARD FRICTION REPORT                                         │
├───────────────────────────────────────────────────────────────┤
│                                                               │
│ Rules Analyzed: N                                             │
│ False Positives Found: M (X branch-policy, Y detection-logic) │
│                                                               │
│ Recommendation 1 [branch-policy]: Protect the 'draft' branch  │
│   Issue: research-repo integration branch has no protection   │
│   Config change: {"draft": "smart"}                            │
│                                                               │
│ Recommendation 2 [detection-logic — NOT config-fixable]:      │
│   Issue: `awk 'NR>=203'` flagged as a redirect — the `>` is   │
│          inside a single-quoted awk program, not shell syntax │
│   Fix: requires editing scripts/branch-guard.sh's Pattern 1   │
│        detection to strip quoted spans before scanning (see   │
│        the 2026-07-16 quoted-span-stripping fix for the       │
│        precedent — same class, PR against the script)         │
│   Config change: none exists — the flat schema (Step 5) has   │
│        no such knob                                           │
│                                                               │
└───────────────────────────────────────────────────────────────┘

Step 5: Apply (with user confirmation)

The real config schema is a flat branch-name → protection-level map — nothing else. scripts/branch-guard.sh reads it with a single lookup, _json_get ".\"${BRANCH}\"" — there is no nested "branches" object, no allowed_extensions, pr_body_scan, or force_push_allow key. Those do not exist in the script; proposing them would produce a config file the guard silently ignores.

Valid protection-level values (from the script's own comment): "block-all", "smart", "block-new-code" (alias for smart), "confirm" (alias for smart), or "" (no protection). A branch not listed in the config gets no protection — a custom config is explicit and authoritative; it does not merge with auto-detection.

{
  "main": "block-all",
  "dev": "smart",
  "draft": "smart"
}

Only propose branch-policy changes this way (see Step 4's classification). Ask the user to confirm before writing to .claude/branch-guard.json.

IMPORTANT: Never modify scripts/branch-guard.sh. If the false positive is a detection-logic bug (not fixable via this flat schema), say so plainly and recommend a code fix as its own PR — do not fabricate a config key to paper over it.

Output Format

Use craft box-drawing format throughout. Each step shows progress:

[1/5]  Discovery ................. DONE (N rules found)
[1b/5] Matcher-overlap ........... DONE (0 duplicates)
[1c/5] Rule-coverage + state ..... DONE (0 overlaps, 0 muted)
[2/5]  Friction analysis ......... DONE (M false positives)
[3/5]  Test harness .............. DONE (P/Q tests passed)
[4/5]  Report .................... SHOWN
[5/5]  Apply ..................... WAITING (user confirmation)

Error Recovery

| Error | Recovery | |-------|----------| | No guard script found | Report error, suggest installing guard | | No false positives found | Report clean audit, no changes needed | | Config write fails | Show JSON for manual copy | | Tests inconclusive | Show raw test output for review |

See Also

• scripts/branch-guard.sh — The guard script (read-only for this skill)
• .claude/branch-guard.json — Per-project config (this skill's output)
• skills/dev/git/SKILL.md — unprotect, protect, and guard management (ask naturally; folded from /craft:git:unprotect/protect/guard, 2026-07 v4 consolidation)
• docs/guide/guard-suite.md — Guard suite concepts and usage guide