specpipe 1.0.0

package/templates/.claude/settings.json

@@ -0,0 +1,68 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/path-guard.sh"
+          },
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sensitive-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Write|Edit|MultiEdit|Grep",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/sensitive-guard.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/comment-guard.js"
+          }
+        ]
+      },
+      {
+        "matcher": "Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/glob-guard.js"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/file-guard.js"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/self-review.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/docs/WORKFLOW.md

@@ -0,0 +1,325 @@
+# Development Workflow Reference
+
+> Spec-first development: every change follows SPEC (with acceptance scenarios) → CODE + TESTS → BUILD PASS.
+
+---
+
+## 1. Workflow Types
+
+### New Project (Greenfield)
+
+When: Brand-new project — no codebase yet (empty repo, no package manager / `src/`).
+
+```
+Step 1 → /sp-explore "what you're building"
+          Detects greenfield → ALSO decides app-type + stack (versions researched,
+          current — not recalled from memory) and emits a Bootstrap Brief.
+          Output: docs/explore/<feature>.md (with ## Bootstrap Brief)
+
+Step 2 → /sp-scaffold
+          Reads the Bootstrap Brief → generator-first runnable skeleton:
+          core/ + ONE pattern-demonstrating module + co-located tests.
+          Smoke-gated (install → build → start/smoke must be GREEN, ≥1 real test —
+          this resolves TEST_CMD for /sp-build). Writes ARCHITECTURE.md + ADRs.
+          Hands off ONLY when it actually runs; otherwise BLOCKED.
+
+Step 3 → /sp-plan → /sp-build
+          Normal New Feature flow, now on a runnable base. /sp-build's Foundation
+          Gate confirms the harness exists before the first RED.
+```
+
+### Explore Before Planning
+
+When: Requirements are unclear, multiple approaches are possible, or it's a brownfield feature with existing code to understand first.
+
+```
+Step 1 → /sp-explore "feature description"
+          Clarifies: why the feature is needed, desired behavior, boundaries,
+          edge cases, business rules, permissions, UI expectations.
+          Asks questions as a Client Technical Lead — one topic at a time.
+          Output: docs/explore/<feature>.md
+
+Step 2 → /sp-plan "feature description"
+          Auto-detects docs/explore/<feature>.md → skips redundant codebase
+          discovery, uses explore findings as direct input for the spec.
+          Continue with the normal New Feature flow from Step 2.
+```
+
+### New Feature
+
+When: Building something that doesn't exist yet (no code, no spec).
+
+```
+Step 1 → /sp-plan "description of feature"
+          Generates: docs/specs/<feature>/<feature>.md (spec with acceptance scenarios)
+          Runs Scope Challenge: reuse check, complexity smell (8+ files = flag),
+          framework built-in search, distribution check.
+          Adds "What Already Exists" and "Not in Scope" sections to the spec.
+          Answers validation questions with effort scales (human: X / CC: Y).
+          At the end, suggests /sp-spec-render if you want a scannable HTML view.
+          Review before proceeding.
+
+Step 1.5 → (Optional) /sp-spec-render <feature>
+          Generates <feature>.html next to the .md — sidebar TOC, story cards,
+          collapsible Given/When/Then, dark/light theme. Useful when the spec
+          is long and you want to scan it visually or share it with stakeholders.
+          Source .md remains canonical; .html is regenerable, never hand-edit.
+          For non-spec markdown (investigation, explore, RFC, retro, README),
+          use /sp-md-render <file.md> instead — same idea, generic content.
+
+Step 2 → (Optional) /sp-challenge docs/specs/<feature>/<feature>.md
+          Adversarial review: spawns hostile reviewers to find flaws.
+          Recommended for complex features, auth, data pipelines.
+          Skip for simple CRUD or small features.
+
+Step 3 → Implement in chunks. After each chunk:
+          /sp-build
+          Checks 8 edge case categories (null, empty, invalid types, boundary,
+          error paths, race conditions, large data, special chars).
+          Draws Coverage Map before writing tests: traces code paths + user flows,
+          marks [GAP], [GAP][→E2E], [GAP][→EVAL] (with pass@1/pass@3 guidance).
+          Regression rule enforced.
+          Repeat until chunk is green.
+
+Step 4 → /sp-review (before merge)
+          Checks API/Backend patterns (rate limiting, timeouts, CORS, error leakage).
+          Extra layer for AI-generated code: regressions, trust boundaries, cost escalation.
+
+Step 4.5 → (Optional) /sp-voices
+          Multi-LLM second opinion: sends the diff (or spec) to 2–3 different LLMs,
+          synthesizes consensus + disagreements. Use when: high-stakes change
+          (auth/payment/data), mixed-confidence findings from /sp-review, or
+          you want cross-model verification before merge. Skip for routine changes.
+
+Step 5 → /sp-commit
+```
+
+### Update Existing Feature
+
+When: Changing behavior, adding options, refactoring logic.
+
+```
+Step 1 → /sp-plan docs/specs/<feature>/<feature>.md "description of changes"
+          Mode C handles everything: snapshot → classification → change report → apply.
+          Do NOT manually edit the spec before running /sp-plan — it creates the
+          snapshot first, then applies changes. Manual edits bypass snapshot protection.
+          At the end, suggests /sp-spec-render to refresh <feature>.html if you
+          have an HTML view (it's stale after this update).
+
+Step 2 → Implement code changes.
+          /sp-build
+          Fix until green.
+
+Step 4 → /sp-review → /sp-commit
+```
+
+### Bug Fix
+
+When: Something is broken and needs fixing.
+
+```
+Step 0 → (OPTIONAL) /sp-investigate "description of the bug"
+          Use ONLY when: bug is complex, ambiguous, production outage, data
+          corruption, regression with unclear cause, or user wants diagnosis
+          before any code change. Skip for trivial/obvious bugs.
+          Read-only: traces data flow, maps blast radius, lists hypotheses
+          with confidence levels. Writes docs/investigate/<slug>-<date>.md.
+          No code changes — hands off the report to /sp-fix.
+
+Step 1 → /sp-fix "description" (or /sp-fix docs/investigate/<slug>-<date>.md)
+          Auto-detects investigation file if passed → skips redundant discovery.
+          Draws Bug Path Diagram to confirm hypothesis ([GAP] must be locatable).
+          Regression rule: if diff broke existing behavior with no test → CRITICAL test required.
+          Writes failing test → fixes code → confirms green → runs full suite.
+
+Step 2 → /sp-commit
+
+Optional → If the bug reveals an undocumented edge case, update the spec.
+```
+
+### Remove Feature
+
+When: Deleting a feature, removing deprecated code.
+
+```
+Step 1 → /sp-plan docs/specs/<feature>/<feature>.md "remove stories S-XXX"
+          Mode C creates a snapshot (removing stories = M2 = Major),
+          then marks stories and AS as removed in the spec.
+          (Or if removing the entire feature: archive the directory.)
+
+Step 2 → Delete production code and related test code.
+
+Step 3 → Run the full test suite with the project's native test command.
+          Fix any cascading breakage.
+
+Step 4 → /sp-commit
+```
+
+---
+
+## 2. Decision Tree
+
+Use this to decide which workflow to follow:
+
+```
+Is there a runnable project yet (package manager / src / build)?
+├─ No → New Project (Greenfield). /sp-explore (greenfield) → /sp-scaffold → then /sp-plan.
+└─ Yes ↓
+
+Is this a brand new feature (no existing spec or code)?
+├─ Yes
+│   ├─ Are requirements clear and approach decided?
+│   │   ├─ Yes → New Feature workflow. Start with /sp-plan.
+│   │   │   └─ Is the feature complex (auth, data pipeline, multi-service)?
+│   │   │       ├─ Yes → Run /sp-challenge after /sp-plan, before coding.
+│   │   │       └─ No → Skip /sp-challenge, go straight to implementation.
+│   │   └─ No → Explore Before Planning. Start with /sp-explore.
+│   │           Then /sp-plan using the explore output.
+└─ No
+    ├─ Is this a bug fix?
+    │   ├─ Yes → Bug Fix workflow.
+    │   │   ├─ Complex / outage / ambiguous cause / data corruption?
+    │   │   │   ├─ Yes → /sp-investigate first, then /sp-fix.
+    │   │   │   └─ No  → /sp-fix directly.
+    │   └─ No
+    │       ├─ Are you removing/deprecating code?
+    │       │   ├─ Yes → Remove Feature workflow.
+    │       │   └─ No → Update Feature workflow. Start with /sp-plan.
+    │       │
+    │       └─ Is the change very small (< 5 lines, behavior unchanged)?
+    │           └─ Yes → Skip spec update. Just /sp-build and /sp-commit.
+```
+
+---
+
+## 3. Prompt Templates
+
+Copy-paste these when working with your agent.
+
+### Template A — Implement + Test Together
+
+```
+I just implemented [brief description].
+Files changed: [list files]
+
+Based on:
+- Spec: docs/specs/<feature>/<feature>.md (section §X)
+- Acceptance scenarios: docs/specs/<feature>/<feature>.md (section ## Stories)
+
+Write tests for the part I just implemented.
+Only tests related to this change — not the entire feature.
+Build and run until all pass.
+If the spec seems incomplete, note what's missing but don't change it.
+```
+
+### Template B — Update Feature + Tests
+
+```
+I'm about to change [description of change].
+Affected files: [list]
+
+1. /sp-plan docs/specs/<feature>/<feature>.md "description of changes"
+   (handles snapshot + spec update + acceptance scenarios)
+2. Implement the code change
+3. Update tests to match
+4. Build and run → fix until green
+```
+
+### Template C — Test-First Bug Fix
+
+```
+Bug: [description]
+Steps to reproduce: [steps]
+Expected: [correct behavior]
+Actual: [broken behavior]
+
+1. Write a test that reproduces this bug (must fail currently)
+2. Fix the production code to make the test pass
+3. Run the full test suite — nothing else should break
+4. Update the spec if this is an undocumented edge case
+```
+
+### Template D — Remove Feature
+
+```
+Removing: [feature name]
+Files to delete: [list]
+
+1. /sp-plan docs/specs/<feature>/<feature>.md "remove stories S-XXX, S-YYY"
+   (handles snapshot + marks stories and AS as removed)
+2. Delete production code
+3. Delete test code
+4. Run full test suite → fix cascading breaks
+```
+
+---
+
+## 4. Token Cost Guide
+
+| Workflow | Estimated Tokens | When |
+|----------|-----------------|------|
+| `/sp-explore` | 10–20k | Before /sp-plan when requirements are unclear |
+| `/sp-scaffold` | 15–40k + real install/build time | Greenfield only — once, to stand up a runnable skeleton before the first spec |
+| `/sp-build` (incremental) | 5–10k | Daily, after each code chunk |
+| `/sp-investigate` (complex bug) | 8–15k | OPTIONAL before /sp-fix — complex/outage only |
+| `/sp-fix` (single bug) | 3–5k | As bugs arise |
+| `/sp-commit` | 2–4k | Each commit |
+| `/sp-review` (diff-based) | 10–20k | Before merge |
+| `/sp-plan` (new feature) | 20–40k | Start of new feature |
+| `/sp-challenge` (adversarial) | 15–30k | After /sp-plan, for complex features |
+| `/sp-spec-render` (HTML view) | 3–8k | User-invoked after `/sp-plan` if HTML view wanted, or to refresh stale `.html` |
+| `/sp-md-render` (HTML view, any md) | 3–8k | User-invoked for non-spec markdown — investigation, explore, RFC, retro, README |
+| `/sp-voices` (multi-LLM review) | 10–30k + external API cost | Optional — after /sp-review for high-stakes changes |
+| `/sp-humanize` (rephrase text) | 2–6k | User-invoked — rephrase plan/notes/AI output into send-ready text. Outside the dev cycle |
+| Full audit (manual) | 100k+ | Before release, quarterly |
+
+**Rule of thumb:** Daily work uses templates + `/sp-build` → low token cost.
+Save `/sp-plan` and full audits for significant milestones.
+
+---
+
+## 5. CI Integration Checklist
+
+Use this as a PR review checklist (enforce manually or via CI):
+
+- [ ] **Spec updated?** If production behavior changed, `docs/specs/<feature>/` should have changes.
+- [ ] **Acceptance scenarios updated?** If spec behavior changed, AS in spec should reflect it.
+- [ ] **Tests pass?** The project's test command exits 0.
+- [ ] **No dead tests?** Removed production code → removed corresponding tests.
+- [ ] **Coverage not decreased?** (Optional, per-team decision.)
+- [ ] **No secrets in diff?** No API keys, tokens, passwords in committed code.
+- [ ] **Commit messages conventional?** `type(scope): description` format.
+
+---
+
+## 6. Spec-Test-Code Sync Rules
+
+| Change | Must Also Update |
+|--------|-----------------|
+| Production code behavior changed | Spec (including acceptance scenarios) + tests |
+| Spec updated | Acceptance scenarios + tests (if behavior changed) |
+| Code removed | Remove related tests. Mark spec and AS as removed. |
+| Bug fix | Add test. Update spec if edge case was undocumented. |
+
+**Never acceptable:**
+- Code changed, spec not updated (spec drift)
+- Code changed, tests not updated (untested code)
+- Spec changed, acceptance scenarios or tests not updated (AS drift)
+- Code removed, dead tests remain (orphaned tests)
+
+**Acceptable shortcut** for changes under 5 lines with no behavior change:
+- Code + tests together, skip spec update (same PR).
+
+---
+
+## 7. Common Pitfalls
+
+| Pitfall | Symptom | Prevention |
+|---------|---------|------------|
+| **Spec drift** | Code does X, spec says Y | Always update spec before coding |
+| **Dead tests** | Tests pass but test removed functionality | Delete tests when removing features |
+| **Over-testing** | 50 tests for simple CRUD, slow suite | Focus on behavior, not implementation details |
+| **Mock abuse** | Tests pass with mocks, fail in production | Use real implementations; mock only external services |
+| **Big-bang testing** | All tests written after all code is done | Test incrementally after each chunk |
+| **Ignoring flaky tests** | Tests pass sometimes, fail sometimes | Fix immediately — flaky tests erode trust |
+| **Testing private methods** | Tests break on refactor | Test public API and behavior only |

package/templates/hooks/specpipe-read-guard.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# specpipe-read-guard.sh — blocking pre-file-read hook (enforced guardrail).
+#
+# For agents whose pre-read payload puts the path at .file_path (Cursor
+# beforeReadFile) or .tool_input.file_path (Claude/Codex Read). Blocks (exit 2)
+# reads of secret files; allows *.example / *.sample / *.template.
+#
+# Exit codes: 0 = allow, 2 = block (reason on stderr).
+set -euo pipefail
+
+INPUT=$(cat)
+[[ -z "$INPUT" ]] && exit 0
+
+extract_path() {
+  if command -v node &>/dev/null; then
+    printf '%s' "$1" | node -e "
+      try {
+        const d = JSON.parse(require('fs').readFileSync(0,'utf-8'));
+        const p = d.file_path ?? d.tool_input?.file_path ?? d.path;
+        if (typeof p === 'string') process.stdout.write(p);
+      } catch {}
+    " 2>/dev/null
+  else
+    printf '%s' "$1" | grep -oE '\"file_path\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed -E 's/.*:[[:space:]]*\"//;s/\"$//'
+  fi
+}
+
+P=$(extract_path "$INPUT") || exit 0
+[[ -z "$P" ]] && exit 0
+
+# Allow example/template variants.
+case "$P" in
+  *.example|*.sample|*.template) exit 0 ;;
+esac
+
+SECRET="(\.env)($|\.[A-Za-z0-9]+$)|\.(pem|key|p12|pfx|keystore)$|id_(rsa|ed25519|ecdsa)$|(credentials|secrets?)\.(json|ya?ml|toml|txt)$"
+if printf '%s\n' "$P" | grep -qiE "$SECRET"; then
+  echo "Blocked: '$P' is a secret file. Use its .example variant, or ask the user first." >&2
+  exit 2
+fi
+
+exit 0

package/templates/hooks/specpipe-shell-guard.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# specpipe-shell-guard.sh — blocking pre-shell/pre-tool hook (enforced guardrail).
+#
+# Portable across agents whose hook payload puts the shell command at either
+#   .tool_input.command   (Codex PreToolUse, Claude PreToolUse)
+#   .command              (Cursor beforeShellExecution)
+# Blocks (exit 2) commands that explore wasteful directories or touch secrets.
+#
+# Exit codes: 0 = allow, 2 = block (reason on stderr). Exit 2 is the portable
+# block primitive honored by Claude, Codex, and Cursor.
+set -euo pipefail
+
+INPUT=$(cat)
+[[ -z "$INPUT" ]] && exit 0
+
+extract_command() {
+  if command -v node &>/dev/null; then
+    printf '%s' "$1" | node -e "
+      try {
+        const d = JSON.parse(require('fs').readFileSync(0,'utf-8'));
+        const c = d.tool_input?.command ?? d.command;
+        if (typeof c === 'string') process.stdout.write(c);
+      } catch {}
+    " 2>/dev/null
+  else
+    printf '%s' "$1" | grep -oE '\"command\"[[:space:]]*:[[:space:]]*\"[^\"]*\"' | head -1 | sed -E 's/.*:[[:space:]]*\"//;s/\"$//'
+  fi
+}
+
+COMMAND=$(extract_command "$INPUT") || exit 0
+[[ -z "$COMMAND" ]] && exit 0
+
+SEP="[/\\\\]"
+
+# Secrets: block reading/copying credential files (allow *.example / *.sample).
+SECRET="(^|[ /\\\\\"'])(\.env)($|[ /\\\\\"'.])"
+SECRET+="|(^|[ /\\\\])\.env\.[A-Za-z0-9]+"
+SECRET+="|\.(pem|key|p12|pfx|keystore)(\b|$)"
+SECRET+="|(^|[ /\\\\])id_(rsa|ed25519|ecdsa)"
+SECRET+="|(credentials|secrets?)\.(json|ya?ml|toml|txt)"
+if printf '%s\n' "$COMMAND" | grep -qiE '(^|[ |;&`(])(cat|less|more|head|tail|bat|cp|nano|vi|vim|grep|rg|strings|xxd|od|base64)([ ])'; then
+  CLEAN=$(printf '%s\n' "$COMMAND" | sed -E 's/\.env\.(example|sample|template)//g')
+  if printf '%s\n' "$CLEAN" | grep -qiE "$SECRET"; then
+    echo "Blocked: command accesses a secret file (.env / key / credentials). Use .env.example, or ask the user first." >&2
+    exit 2
+  fi
+fi
+
+# Wasteful directories: only when an exploration verb is present.
+EXPLORE="(^|[[:space:]|;&\`(])(ls|ll|la|find|cat|head|tail|less|more|wc|stat|du|tree|bat|od|xxd|hexdump|nl)([[:space:]]|$)"
+printf '%s\n' "$COMMAND" | grep -qE "$EXPLORE" || exit 0
+
+BLOCKED="(^|[ /\\\\])node_modules(${SEP}|$| )"
+BLOCKED+="|(__pycache__)|\.git${SEP}(objects|refs)"
+BLOCKED+="|(^|[ /\\\\])dist${SEP}|(^|[ /\\\\])build${SEP}|\.next${SEP}"
+BLOCKED+="|(^|[ /\\\\])vendor(${SEP}|$| )|(^|[ /\\\\])target${SEP}"
+BLOCKED+="|(^|[ /\\\\])\.venv${SEP}|(^|[ /\\\\])venv${SEP}|\.pytest_cache${SEP}|\.cache(${SEP}|$| )"
+CLEAN=$(printf '%s\n' "$COMMAND" | sed -E "s|node_modules[/\\]\.bin[/\\][^[:space:]]*||g")
+if printf '%s\n' "$CLEAN" | grep -qE "$BLOCKED"; then
+  M=$(printf '%s\n' "$COMMAND" | grep -oE "$BLOCKED" | head -1)
+  echo "Blocked: command explores '$M' — a large/generated directory. Use scoped paths or Grep." >&2
+  exit 2
+fi
+
+exit 0

package/templates/rules/specpipe-guards.md

@@ -0,0 +1,40 @@
+These are the always-on operating rules for working in this repository with specpipe.
+On Claude Code the guardrails are enforced by hooks; on other agents this whole document
+is an always-on rule you must self-enforce.
+
+## Spec-first cycle
+
+Every change follows: **SPEC (with acceptance scenarios) → CODE + TESTS → BUILD PASS**.
+
+- Specs live in `docs/specs/<feature>/<feature>.md`; acceptance scenarios (Given/When/Then)
+  are embedded under `## Stories`.
+- Never write code before the spec exists. Never auto-modify a spec from code.
+- The spec is the source of truth — if code contradicts it, the code is wrong.
+
+## Guardrails
+
+- **Don't explore large directories.** Never grep/list/read inside `node_modules/`,
+  build/dist artifacts, or `.git/` internals — scope to specific paths.
+- **Never touch secrets.** Do not read or write `.env*`, private keys, credentials, or
+  token stores. Respect any `.agentignore` patterns.
+- **Never drop real code.** Don't replace implementation with placeholder comments like
+  `// ... existing code ...`. Reproduce the full code when editing.
+- **Avoid broad globs.** No `**/*.ts` at the project root; scope globs to a directory.
+- **Keep files focused.** Don't let a source file grow past a few hundred lines — split.
+
+## Testing
+
+- Run the project's native test command (`npx vitest run`, `pytest`, `cargo test`,
+  `go test ./...`, `swift test`, …). Compile/typecheck before running tests.
+- Max 3 fix loops on a failure, then stop and report.
+- **Never edit production code to make a test pass** — ask first.
+- No mocks/fakes/stubs to pass builds; real implementations only. Test doubles are for
+  external services (APIs, DBs) that can't run locally.
+
+## Conventions
+
+- Commits: conventional — `type(scope): description` (`feat`, `fix`, `docs`, `refactor`,
+  `test`, `chore`, `perf`, `build`, `ci`).
+- File names: kebab-case, descriptive enough to understand purpose from the path.
+- Never `git push --force` to `main`/`master`; never commit `.env`, certs, or keys.
+- Self-review before finishing: tests pass, no secrets, no debug code, matches the spec.

package/templates/scripts/test-hooks.sh

@@ -0,0 +1,66 @@
+#!/usr/bin/env bash
+# test-hooks.sh — Hook unit tests
+# Usage: bash scripts/test-hooks.sh [--filter PATTERN]
+# Exit: 0 = all pass, 1 = failures
+
+set -uo pipefail
+
+FILTER=""
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --filter) FILTER="${2:-}"; shift 2 ;;
+        *) FILTER="$1"; shift ;;
+    esac
+done
+
+HOOKS_DIR="$(cd "$(dirname "$0")/../.claude/hooks" && pwd)"
+PASS=0; FAIL=0
+
+# Encode a string as a JSON string literal using node
+json_str() { node -e "process.stdout.write(JSON.stringify(process.argv[1]))" -- "$1"; }
+
+bash_payload() { printf '{"tool_name":"Bash","tool_input":{"command":%s}}' "$(json_str "$1")"; }
+
+run() {
+    local name="$1" hook="$2" payload="$3" expected_exit="$4"
+    if [[ -n "$FILTER" && "$name" != *"$FILTER"* ]]; then return 0; fi
+    local actual_exit=0
+    printf '%s' "$payload" | bash "$HOOKS_DIR/$hook" >/dev/null 2>&1 || actual_exit=$?
+    if [[ "$actual_exit" == "$expected_exit" ]]; then
+        echo "[PASS] $name"
+        PASS=$((PASS + 1))
+    else
+        echo "[FAIL] $name  (expected exit $expected_exit, got $actual_exit)"
+        FAIL=$((FAIL + 1))
+    fi
+}
+
+# ── path-guard.sh ──────────────────────────────────────────────────────────────
+
+# Should BLOCK: reading/listing blocked dirs
+run "pg: ls dist/"         path-guard.sh "$(bash_payload 'ls dist/')"                          2
+run "pg: cat dist/file"    path-guard.sh "$(bash_payload 'cat dist/bundle.js')"                2
+run "pg: find dist"        path-guard.sh "$(bash_payload 'find dist/ -name "*.js"')"           2
+run "pg: head dist file"   path-guard.sh "$(bash_payload 'head -20 dist/server.js')"           2
+run "pg: ls node_modules"  path-guard.sh "$(bash_payload 'ls node_modules/')"                  2
+run "pg: cat node_modules" path-guard.sh "$(bash_payload 'cat node_modules/lodash/index.js')"  2
+run "pg: ls build/"        path-guard.sh "$(bash_payload 'ls build/')"                         2
+run "pg: wc dist file"     path-guard.sh "$(bash_payload 'wc -l dist/bundle.js')"              2
+
+# Should ALLOW: existence/permission checks and variable assignments (no file content read)
+# Regression: dist/ path as intermediate component in binary check — path-guard.sh:55 blocked this
+run "pg: allow -x binary check" \
+    path-guard.sh \
+    "$(bash_payload 'B=~/.claude/skills/gstack/browse/dist/browse
+if [ -x "$B" ]; then echo "READY: $B"; else echo "NEEDS_SETUP"; fi')" \
+    0
+run "pg: allow -f check"   path-guard.sh "$(bash_payload '[ -f /usr/local/dist/bin/tool ] && echo ok')" 0
+run "pg: allow path assign" path-guard.sh "$(bash_payload 'TOOL=~/.claude/dist/mytool; "$TOOL" --version')" 0
+run "pg: allow git command" path-guard.sh "$(bash_payload 'git rev-parse --show-toplevel')"    0
+run "pg: allow empty"       path-guard.sh '{}'                                                 0
+
+# ── End ───────────────────────────────────────────────────────────────────────
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[[ "$FAIL" -eq 0 ]]