specpipe 1.0.1 → 1.0.3

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

@@ -1,42 +1,115 @@
 #!/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.
+# The single file-access guard for every agent. Reads the target path from
+# whichever shape the agent's payload uses:
+#   .tool_input.file_path (Claude/Codex Read/Write/Edit)  ·  .file_path (Cursor beforeReadFile)
+#
+# Blocks (exit 2) reads/writes of secret files: .env, private keys, credentials,
+# tokens. Allows *.example / *.sample / *.template. Honors .agentignore.
 #
 # Exit codes: 0 = allow, 2 = block (reason on stderr).
+# Env: SENSITIVE_GUARD_EXTRA — extra pipe-separated path patterns to block.
 set -euo pipefail
 
 INPUT=$(cat)
 [[ -z "$INPUT" ]] && exit 0
 
+# Security guard: warn loudly if Node is missing rather than silently allowing.
+if ! command -v node &>/dev/null; then
+  echo "WARNING: read-guard degraded — Node.js not found. Sensitive files are NOT fully protected." >&2
+  exit 0
+fi
+
 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/\"$//'
+  printf '%s' "$1" | node -e "
+    try {
+      const d = JSON.parse(require('fs').readFileSync(0,'utf-8'));
+      const p = d.tool_input?.file_path ?? d.file_path ?? d.tool_input?.path ?? d.path;
+      if (typeof p === 'string') process.stdout.write(p);
+    } catch {}
+  " 2>/dev/null
+}
+
+FILE_PATH=$(extract_path "$INPUT") || exit 0
+[[ -z "$FILE_PATH" ]] && exit 0
+
+# ─── Fast-path: obviously safe source/doc files (json still checked) ─
+fast_path_safe() {
+  local ext="${1##*.}"
+  case "$ext" in
+    md|ts|tsx|js|jsx|css|scss|html|svg|yaml|yml|toml|xml|txt|sh|py|rb|rs|go|java|kt|swift|c|cpp|h|hpp|cs|vue|svelte|astro)
+      return 0 ;;
+  esac
+  return 1
+}
+
+# ─── Sensitive filename detection ───────────────────────────────────
+is_sensitive() {
+  local filepath="$1" basename
+  basename=$(basename "$filepath" 2>/dev/null) || return 1
+
+  case "$basename" in
+    .env|.env.local|.env.development|.env.production|.env.staging|.env.test) return 0 ;;
+    .npmrc|.pypirc|.netrc) return 0 ;;
+    id_rsa|id_ecdsa|id_ed25519|id_dsa) return 0 ;;
+    serviceAccountKey.json|service-account*.json) return 0 ;;
+    config.json) [[ "$filepath" == *".docker/config.json"* ]] && return 0 ;;
+  esac
+  case "$basename" in
+    *.pem|*.key|*.p12|*.pfx|*.jks|*.keystore|*.truststore) return 0 ;;
+    *_rsa|*_ecdsa|*_ed25519|*_dsa) return 0 ;;
+  esac
+  local lower
+  lower=$(echo "$basename" | tr '[:upper:]' '[:lower:]')
+  case "$lower" in
+    *credential*|*secret*|*private_key*|*privatekey*) return 0 ;;
+    firebase-adminsdk*) return 0 ;;
+  esac
+  if [[ "$basename" =~ ^\.env\. ]]; then
+    case "$basename" in
+      .env.example|.env.sample|.env.template) return 1 ;;
+      *) return 0 ;;
+    esac
   fi
+  if [[ -n "${SENSITIVE_GUARD_EXTRA:-}" ]] && printf '%s\n' "$filepath" | grep -qE "$SENSITIVE_GUARD_EXTRA"; then
+    return 0
+  fi
+  return 1
 }
 
-P=$(extract_path "$INPUT") || exit 0
-[[ -z "$P" ]] && exit 0
+# ─── .agentignore / .aiignore / .cursorignore ───────────────────────
+check_agentignore() {
+  local filepath="$1" ignorefile=""
+  for candidate in .agentignore .aiignore .cursorignore; do
+    [[ -f "$candidate" ]] && { ignorefile="$candidate"; break; }
+  done
+  [[ -z "$ignorefile" ]] && return 1
+
+  local normalized_fp normalized_pwd relpath
+  normalized_fp=$(printf '%s' "$filepath" | tr '\\' '/')
+  normalized_pwd=$(pwd | tr '\\' '/')
+  relpath=$(printf '%s' "$normalized_fp" | sed "s|^${normalized_pwd}/||") 2>/dev/null || relpath="$filepath"
 
-# Allow example/template variants.
-case "$P" in
+  while IFS= read -r pattern || [[ -n "$pattern" ]]; do
+    [[ -z "$pattern" || "$pattern" == \#* ]] && continue
+    if [[ "$relpath" == $pattern ]] || [[ "$(basename "$relpath")" == $pattern ]]; then
+      return 0
+    fi
+  done < "$ignorefile"
+  return 1
+}
+
+# ─── Allow example/template variants outright ───────────────────────
+case "$FILE_PATH" 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
+if ! fast_path_safe "$FILE_PATH"; then
+  if is_sensitive "$FILE_PATH" || check_agentignore "$FILE_PATH"; then
+    echo "Blocked: '$FILE_PATH' is a sensitive file (secrets, keys, or credentials). Use its .example variant, or ask the user first." >&2
+    exit 2
+  fi
 fi
 
 exit 0

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

@@ -1,29 +1,68 @@
 #!/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)
+# The single shell guard for every agent. Reads the command from whichever shape
+# the agent's hook payload uses:
+#   .tool_input.command   (Claude PreToolUse, Codex PreToolUse)
 #   .command              (Cursor beforeShellExecution)
-# Blocks (exit 2) commands that explore wasteful directories or touch secrets.
+#
+# Two protections:
+#   1. Secrets — commands that read/copy credential files (.env, keys, …).
+#        SECRET_POLICY=block (default) → exit 2; =warn → warn on stderr, exit 0
+#        (the approval flow: Claude asks the user, then may `cat .env`).
+#   2. Wasteful dirs — exploring node_modules / build output / caches, which
+#        burns tokens. Always blocks (exit 2) when an exploration verb is present.
 #
 # Exit codes: 0 = allow, 2 = block (reason on stderr). Exit 2 is the portable
 # block primitive honored by Claude, Codex, and Cursor.
+#
+# Env:
+#   SECRET_POLICY          block (default) | warn
+#   PATH_GUARD_EXTRA       extra pipe-separated dir patterns to block
+#   SENSITIVE_GUARD_EXTRA  extra pipe-separated secret patterns to block
 set -euo pipefail
 
 INPUT=$(cat)
 [[ -z "$INPUT" ]] && exit 0
+POLICY="${SECRET_POLICY:-block}"
+
+# Antigravity honors a stdout JSON decision ({"decision":"deny","reason":…}), NOT exit
+# codes — a non-zero exit is logged as a hook failure and falls through to its native
+# permission prompt. Detect its payload shape so block() emits the right thing.
+IS_ANTIGRAVITY=0
+printf '%s' "$INPUT" | grep -q '"toolCall"' && IS_ANTIGRAVITY=1
+
+# Block primitive. Antigravity → stdout JSON deny (+ exit 0, clean). Everyone else →
+# reason on stderr + exit 2 (honored by Claude/Codex directly, Cursor via failClosed).
+block() {
+  local reason="$1"
+  if [[ "$IS_ANTIGRAVITY" == "1" ]]; then
+    local esc; esc=$(printf '%s' "$reason" | sed 's/\\/\\\\/g; s/"/\\"/g')
+    printf '{"decision":"deny","reason":"%s"}\n' "$esc"
+    exit 0
+  fi
+  echo "$reason" >&2
+  exit 2
+}
 
+# ─── Extract command (multi-payload) ────────────────────────────────
+# Covers every agent's hook payload shape:
+#   .tool_input.command   Claude / Codex (PreToolUse Bash)
+#   .command              Cursor (beforeShellExecution)
+#   .tool_args.CommandLine  Antigravity (PreToolUse run_command) — verified 2026
 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;
+        const a = d.toolCall?.args ?? {};   // Antigravity 1.0.13: { toolCall: { args: { CommandLine } } }
+        const c = d.tool_input?.command ?? d.command ?? d.tool_args?.CommandLine
+                  ?? a.CommandLine ?? a.Command ?? a.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/\"$//'
+    printf '%s' "$1" | grep -oE '"(command|CommandLine)"[[:space:]]*:[[:space:]]*"[^"]*"' | head -1 | sed -E 's/.*:[[:space:]]*"//;s/"$//'
   fi
 }
 
@@ -32,34 +71,87 @@ COMMAND=$(extract_command "$INPUT") || 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
+# ─── Secrets in the command ─────────────────────────────────────────
+# Only flag when a read/copy verb is present (so "echo use .env.example" or
+# variable assignments don't trip the guard).
+handle_secret() {
+  local match="$1"
+  if [[ "$POLICY" == "warn" ]]; then
+    echo "Warning: '$match' is a sensitive file. If the user approved this access, proceed. Otherwise ask the user first before reading secrets." >&2
+    exit 0
   fi
-fi
+  block "Blocked: command accesses a secret file ('$match'). Use its .example variant, or ask the user first."
+}
 
-# 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
+# No verb gate here (matches the original sensitive-guard): a secret referenced
+# anywhere in the command is flagged — `ssh -i id_rsa`, `openssl -in cert.pem`,
+# `gcloud --key-file=…` included. The .example/.sample/.template strip avoids the
+# obvious false positives.
+CLEAN=$(printf '%s\n' "$COMMAND" | sed -E 's/\.env\.(example|sample|template)//g')
 
+SENSITIVE_IN_CMD=$(printf '%s\n' "$CLEAN" | grep -oE '[\./[:alnum:]_-]*\.env([\.[:alnum:]_-]*)?' | head -5) || true
+if [[ -n "$SENSITIVE_IN_CMD" ]]; then
+  while IFS= read -r m; do
+    [[ -z "$m" ]] && continue
+    case "$m" in *.example|*.sample|*.template) continue ;; esac
+    handle_secret "$m"
+  done <<< "$SENSITIVE_IN_CMD"
+fi
+KEY_IN_CMD=$(printf '%s\n' "$CLEAN" | grep -oE '[[:alnum:]_./-]*\.(pem|key|p12|pfx|jks|keystore)($|[^[:alnum:]])' | head -3) || true
+[[ -n "$KEY_IN_CMD" ]] && handle_secret "$(printf '%s' "$KEY_IN_CMD" | head -1)"
+NAME_IN_CMD=$(printf '%s\n' "$CLEAN" | grep -oiE '(id_rsa|id_ecdsa|id_ed25519|id_dsa|serviceAccountKey\.json|service-account[[:alnum:]_-]*\.json|\.npmrc|\.pypirc|\.netrc)' | head -3) || true
+[[ -n "$NAME_IN_CMD" ]] && handle_secret "$(printf '%s' "$NAME_IN_CMD" | head -1)"
+CRED_IN_CMD=$(printf '%s\n' "$CLEAN" | grep -oiE '[[:alnum:]_./-]*(credential|secret|private_key|privatekey)[[:alnum:]_./-]*' | head -3) || true
+[[ -n "$CRED_IN_CMD" ]] && handle_secret "$(printf '%s' "$CRED_IN_CMD" | head -1)"
+if [[ -n "${SENSITIVE_GUARD_EXTRA:-}" ]] && printf '%s\n' "$CLEAN" | grep -qE "$SENSITIVE_GUARD_EXTRA"; then
+  handle_secret "$(printf '%s\n' "$CLEAN" | grep -oE "$SENSITIVE_GUARD_EXTRA" | head -1)"
+fi
+
+# ─── Wasteful directories ───────────────────────────────────────────
 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
+BLOCKED+="|(__pycache__)"
+BLOCKED+="|\.git${SEP}(objects|refs)"
+BLOCKED+="|(^|[ /\\\\])dist${SEP}"
+BLOCKED+="|(^|[ /\\\\])build${SEP}"
+BLOCKED+="|\.next${SEP}"
+BLOCKED+="|(^|[ /\\\\])vendor(${SEP}|$| )"
+BLOCKED+="|(^|[ /\\\\])Pods(${SEP}|$| )"
+BLOCKED+="|\.build${SEP}"
+BLOCKED+="|DerivedData"
+BLOCKED+="|\.gradle${SEP}"
+BLOCKED+="|(^|[ /\\\\])target${SEP}"
+BLOCKED+="|\.nuget"
+BLOCKED+="|\.cache(${SEP}|$| )"
+BLOCKED+="|(^|[ /\\\\])\.venv${SEP}"
+BLOCKED+="|(^|[ /\\\\])venv${SEP}"
+BLOCKED+="|\.mypy_cache${SEP}"
+BLOCKED+="|\.pytest_cache${SEP}"
+BLOCKED+="|\.ruff_cache${SEP}"
+BLOCKED+="|\.egg-info(${SEP}|$| )"
+BLOCKED+="|(^|[ /\\\\])bin${SEP}(Debug|Release|net|x64|x86)"
+BLOCKED+="|(^|[ /\\\\])obj${SEP}(Debug|Release|net)"
+BLOCKED+="|\.nuxt${SEP}"
+BLOCKED+="|\.svelte-kit${SEP}"
+BLOCKED+="|\.parcel-cache${SEP}"
+BLOCKED+="|\.turbo${SEP}"
+BLOCKED+="|(^|[ /\\\\])out${SEP}(server|static|_next)"
+BLOCKED+="|\.bundle${SEP}"
+
+if [[ -n "${PATH_GUARD_EXTRA:-}" ]]; then
+    BLOCKED+="|$PATH_GUARD_EXTRA"
+fi
+
+EXPLORE_VERB_RE="(^|[[:space:]|;&\`(])(ls|ll|la|find|cat|head|tail|less|more|wc|stat|du|tree|bat|od|xxd|hexdump|nl)([[:space:]]|$)"
+if ! printf '%s\n' "$COMMAND" | grep -qE "$EXPLORE_VERB_RE"; then
+    exit 0
+fi
+
+# Strip node_modules/.bin/<binary> — executing an installed binary isn't exploration.
+COMMAND_FOR_CHECK=$(printf '%s\n' "$COMMAND" | sed -E "s|node_modules[/\\]\.bin[/\\][^[:space:]]*||g")
+
+if printf '%s\n' "$COMMAND_FOR_CHECK" | grep -qE "$BLOCKED"; then
+    MATCHED=$(printf '%s\n' "$COMMAND" | grep -oE "$BLOCKED" | head -1)
+    block "Blocked: command references '$MATCHED' — this directory is typically large and exploring it wastes tokens. Use Glob or Grep tools instead."
 fi
 
 exit 0

package/templates/rules/specpipe-rules.md

@@ -0,0 +1,77 @@
+These are the always-on operating rules for working in this repository with specpipe.
+On Claude Code the guardrails are also enforced by blocking hooks; on every agent 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.
+
+## Workflow
+
+| Trigger | Commands |
+|---------|----------|
+| New project (no codebase yet) | `/sp-explore` → `/sp-scaffold` → `/sp-plan` → `/sp-build` |
+| Feature unclear / complex | `/sp-explore` → `/sp-plan` |
+| New feature | `/sp-plan` → `/sp-challenge` (optional) → code in chunks → `/sp-build` each chunk |
+| Update feature | `/sp-plan <spec-path> "changes"` → code → `/sp-build` (do NOT hand-edit the spec first) |
+| Bug (complex/outage) | `/sp-investigate "<bug>"` → `/sp-fix <investigation-file>` |
+| Bug fix | `/sp-fix "<bug>"` (test-first: failing test → fix → green) |
+| Remove feature | `/sp-plan <spec-path> "remove stories"` → delete code + tests → build pass |
+| Pre-merge check | `/sp-review` |
+| Commit | `/sp-commit` (secret scan + conventional message) |
+| Render spec / markdown as HTML | `/sp-spec-render <feature>` · `/sp-md-render <file.md>` |
+| Multi-LLM review / humanize | `/sp-voices [target]` · `/sp-humanize [text]` |
+
+## 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.
+- Dates in filenames: `$(date +%Y-%m-%d)` — never guess dates.
+- Specs: kebab-case feature dir `docs/specs/<feature>/<feature>.md` (2–3 words, no prefix).
+- 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.
+
+## Forbidden
+
+- `any`/`Any` without a justifying comment; force unwrap/cast without a preceding guard.
+- Hardcoded secrets, API keys, tokens, or credentials in source.
+- Mocks or fake data used solely to pass tests.
+- Editing generated files, vendor dirs, or lock files; ignoring compiler/linter warnings.
+- Replacing real code with placeholder comments; renaming params to `_param` to dodge
+  unused-warnings instead of fixing them.
+- Reading/writing `.env`, `.pem`, `.key`, or other sensitive files (use `.env.example`).
+
+## Project Info
+
+> Auto-detected on install; verify and edit if wrong.
+
+- **Language:** [CUSTOMIZE]
+- **Test framework:** [CUSTOMIZE]
+- **Source directory:** [CUSTOMIZE]
+- **Test directory:** [CUSTOMIZE]

package/templates/skills/sp-build/SKILL.md

@@ -84,6 +84,7 @@ The prompt MUST contain:
 2. **The dispatched-subagent contract** (paste verbatim — this is what keeps the controller the single owner of cross-story state):
    - Build only your assigned story; the Phase 2 loop runs exactly once.
    - Name every test with the `AS-NNN` it covers (`AS-NNN: <scenario>`), one test node per primary AS — the controller's Spec Coverage Gate (Phase 3.5) counts coverage by that ID, so an untagged test is invisible to it.
+   - If your pasted checklist contains `BM.<AS-NNN>.<surface>` lines, treat each as a cell-level test obligation. Your test evidence must include the AS id and exercise that exact surface/source/timing cell. Do not satisfy a BM line with a mock of the boundary named by the cell.
    - Do NOT write `.build-progress` or `.build-checklist` — the controller owns them. Report your checklist ticks in the contract instead.
    - Do NOT run Phase 3 (full-suite), Phase 4.5 (cross-story checklist review), or Phase 5 (summary/cleanup) — those are the controller's job. Run only your story's filtered tests.
    - Do NOT surface a spec signal to the user or edit the spec — return it in the `Spec signal` field.
@@ -109,6 +110,7 @@ Files changed: [...]
 Tests added: [exact test names]
 Checklist: [lines ticked]
 Edge compliance: [the 8-row table for this story — each ✓ or N/A+reason] (depth forcing-function; the controller aggregates these into Phase 5)
+Behavior Matrix evidence: [BM lines covered with test refs; BM lines partial with destinations; mocked-boundary concerns]
 Spec signal: none | S1 <gap> | S2 <conflict> | S3 <added guard>
 ```
 
@@ -266,10 +268,15 @@ Derive a checklist from the spec — each "promise" in this build's scope become
 **Sources (all in `docs/specs/<feature>/<feature>.md`) — anchor on IDENTITY, not nouns:**
 - **Each `AS-NNN` → at least one line carrying that ID** (`AS-NNN`, or `AS-NNN.Tk` when one AS needs several assertions). This is the primary anchor: the checklist is keyed on the spec's case IDs, not on text it happens to mention. A Then with several fields/effects becomes several `AS-NNN.Tk` lines — but they all carry the same AS-NNN, so the AS is never lost.
 - Each Constraint → one `C-NNN` line.
+- Each `## Behavior Matrix` cell with `Coverage = AS-NNN` → one `BM.<AS-NNN>.<surface>` line carrying the referenced `AS-NNN`. This is a stricter obligation than the generic AS line: it preserves the exact state/viewer/surface cell that QA will test.
+- Each `## Behavior Matrix` cell with `Coverage = GAP-NNN` → a normal `GAP-NNN` checklist line annotated `BM cell unresolved: <state>/<viewer>/<surface>`. It is visible, but it is NOT a BM test obligation.
+- Each `## Behavior Matrix` cell with `Coverage = N/A: <reason>` → one `[N/A] BM.NA.<surface>` line with the reason.
 - Each open `GAP-NNN` (status not `resolved`) → one `[ ]` line tagged `GAP` (so a parked gap is visible, not silently dropped — see Spec Coverage Gate).
 - Each Not-in-Scope row → one `[N/A]` line (prevents accidental ticking).
+- Each matching project-local invariant entry under `docs/invariants/INV-*.md` with `status: enforced` and a `test_ref` → one `INV-###` checklist line carrying the invariant id and test ref. `candidate` and `confirmed` entries are visible risks/spec obligations but not build gates unless the spec turned them into AS/GAP/BM lines. Use the invariant registry README/schema as base knowledge; README examples are not runtime entries.
+- Each `## Sibling Surface Map` confirmed surface is checked through its AS/GAP/BM coverage, not by a separate checklist line. Candidate rows with `GAP-NNN` or `ignore(reason)` are visible context only. A candidate row with missing disposition is a spec signal, not a build requirement to implement.
 
-**Completeness invariant (checked, not hoped):** every `AS-NNN` and `C-NNN` in the spec's `## Stories`/Constraints MUST appear on ≥1 checklist line. An AS with no line = the checklist is wrong (re-derive), not the spec. Deriving from Then-nouns alone silently drops AS whose Then is verb-shaped ("retries", "must not send") or whose nouns collide with another AS — anchoring on the ID closes that.
+**Completeness invariant (checked, not hoped):** every `AS-NNN` and `C-NNN` in the spec's `## Stories`/Constraints MUST appear on ≥1 checklist line. Every `Coverage = AS-NNN` Behavior Matrix cell MUST appear on exactly one `BM.AS-*` checklist line; every `Coverage = GAP-NNN` Behavior Matrix cell MUST appear on exactly one `GAP-* — BM cell unresolved` checklist line; every `Coverage = N/A` Behavior Matrix cell MUST appear on one `[N/A] BM.NA.*` checklist line. An AS with no line = the checklist is wrong (re-derive), not the spec. A Behavior Matrix cell with no line = QA coverage was dropped. Deriving from Then-nouns alone silently drops AS whose Then is verb-shaped ("retries", "must not send") or whose nouns collide with another AS — anchoring on the ID closes that.
 
 **Granularity rule (so two devs produce the same checklist):**
 - 1 line per **observable output field** (appears in Then result, independently assertable)
@@ -287,6 +294,9 @@ Example: Then "returns sorted list of {file, confidence, edges}" → 3 lines (on
 [ ] AS-012.T2 — affected_tests includes TESTED_BY edges              | owner: S-003
 [ ] AS-012.T3 — output sorted by confidence                          | owner: S-004
 [ ] C-003     — query completes under 50ms                           | owner: S-005
+[ ] BM.AS-012.appointment-list — Confirmed/trainer/list row parity    | owner: S-003
+[ ] GAP-004   — BM cell unresolved: Requested/booker/reschedule action | owner: GAP
+[N/A] BM.NA.cancelled-client-calendar — terminal state has no invite  | owner: —
 [N/A] AS-015  — out of scope (M3)                                    | owner: —
 ```
 
@@ -374,6 +384,22 @@ Before writing tests, trace all paths and draw a diagram to see gaps upfront —
 
 **Step 2 — Trace user flows:** For multi-step features, trace the user journey. Edge cases: double-click/rapid resubmit, navigate away mid-op, submit stale data (session expired), slow connection, concurrent actions (2 tabs open).
 
+**Step 2b — Trace Behavior Matrix cells:** If the spec has `## Behavior Matrix`, copy every non-N/A cell into the Coverage Map before drawing the diagram. Each cell is a QA-visible obligation, not just prose. Classify the test level by the cell's surface:
+- Same-process logic/state cell → unit or integration is acceptable if it observes the public boundary.
+- Cross-surface parity cell (list/detail/feed/API/dashboard/worklist) → integration/E2E over the real producer/consumer path.
+- External/provider surface (calendar/email/payment/identity) → contract/integration against the verified boundary or provider fake that is itself verified; never a pure mock of the boundary under test.
+- Timing/source cell (`realtime`, `refresh-required`, `persisted+served`, `transient`) → the test must assert that lifecycle point, not just the immediate action response.
+
+In the diagram, prefix these rows with `[BM]` and keep the AS id visible:
+
+```
+BEHAVIOR MATRIX COVERAGE
+========================
+[BM] Confirmed × trainer × worklist — AS-004
+    ├── [GAP] [→E2E] assigned trainer sees updated item
+    └── [GAP] [→E2E] non-runner does not see item
+```
+
 **Step 3 — Draw the diagram:**
 
 ```
@@ -446,6 +472,20 @@ If every path is already covered, the diagram will have zero `[GAP]` rows — th
 
 **LINKED-FIELD SEAM RULE:** If the spec has a `## Linked Fields` block (it is one side of a producer/consumer split), each linked field's **seam AS is a real-integration test** — run it against the ACTUAL producer (build the producer side first; the consumer spec's seam tests run against it), **never a mocked consumer**. A mocked seam is a vacuous test: the mismatch it exists to catch — field on the wrong surface (list vs single-get) or wrong lifecycle (transient-in-response vs persisted+served) — is exactly what the mock hides. Do NOT mark a consumer story `done` on a mocked seam. **Auto-Mode:** a single-side subagent cannot see the seam — the controller runs the cross-spec seam tests after both sibling specs are built (A4b/A7).
 
+**BEHAVIOR MATRIX NO-VACUOUS-MOCK RULE:** If a `## Behavior Matrix` cell names a surface/source/timing boundary, the test for that cell must not mock the boundary it is meant to verify. Examples:
+- API list vs single-get parity → do not assert against fabricated response fixtures only; exercise the real read serializers/handlers or an integration path that uses them.
+- Calendar/email parity → do not mock both email and calendar recipients from the same test fixture; verify the mapping into each outbound contract or a verified provider fake.
+- Worklist/feed/dashboard cascade → do not mock the read model that should be updated; verify the persisted/read-model result after the state transition.
+
+A mocked dependency is allowed only outside the boundary under test. If you cannot test the boundary with the current harness, mark the BM checklist line `[~]` with a concrete destination (`/sp-scaffold` E2E harness, contract-test story, or Known-Gap). Do not mark it `[x]`.
+
+**TERMINAL LIFECYCLE CASCADE TEST RULE:** If a Behavior Matrix cell or AS describes a terminal lifecycle action (`done`, `completed`, `cancelled`, `declined`, `log outcome`, `terminal outcome`, `overdue outcome`, `reschedule creates replacement`) that removes, cancels, replaces, or advances pending work, the owning checklist MUST include a named cascade test. The test name or evidence must contain the word `cascade` and assert the downstream work surface changed, not only the primary record. Examples:
+- Pending matchup terminal outcome → assert pending matchup queue/assignment affordance is removed or cancelled.
+- Reschedule/next appointment → assert old and new appointment state, runner/owner carry-forward, and affected calendar/worklist surfaces.
+- Outcome-created tracker/todo/FNA/production records → assert the downstream record is visible to the required viewer(s) with the expected role fields.
+
+Do not satisfy this rule with a unit test that only checks `is_done`, status text, or a returned DTO. If the downstream surface cannot be exercised in the current harness, mark the BM line `[~]` with a concrete cascade-test destination. A terminal lifecycle BM line without a cascade test is not DONE.
+
 ---
 
 ## Test Command
@@ -551,9 +591,15 @@ Record for the Phase 5 summary: `S-00X added N tests: <list exact test names>`.
 ```
 [x] AS-012.T1 — covered by affected_tests_test.rs:test_convention_match
 [~] AS-012.T2 — PARTIAL: query wired, emit deferred → M3 S-008
+[x] BM.AS-012.appointment-list — covered by appointment_reschedule_e2e.ts:AS-012 list row parity
 ```
 For `[x]`, record `file:test-name`. For `[~]`, record the destination.
 
+If a checklist line starts with `BM.`:
+- The `file:test-name` must include the AS id from the BM line.
+- The test must assert the exact cell surface/source/timing from the Behavior Matrix row.
+- Before ticking `[x]`, apply the Behavior Matrix No-Vacuous-Mock Rule. If the test mocks the named boundary, mark `[~]` with a concrete destination instead.
+
 **Carve-out scan on the story diff:**
 ```
 git diff <story-files> | grep -nE "TODO|FIXME|XXX|HACK"
@@ -647,6 +693,57 @@ comm -23 /tmp/spec-ids.txt /tmp/covered-ids.txt
 
 **Auto-mode:** the controller runs this gate at A7 (finish) over the whole spec, and may run the per-story slice after each story's gates (A4). Dispatched subagents are told (A2 contract) to embed `AS-NNN` in every test name so the gate can see their work.
 
+### Behavior Matrix Coverage Gate
+
+Run this in addition to the AS/C identity gate when the spec contains `## Behavior Matrix`.
+
+The AS/C gate proves every acceptance scenario has at least one test. It does not prove every state/viewer/surface cell was tested, because several cells can share one AS id. The Behavior Matrix gate is the stricter cell-level check.
+
+Required evidence for each matrix cell:
+- For `Coverage = AS-NNN`: a `.build-checklist` line named `BM.<AS-NNN>.<surface>` is `[x]`.
+- That line includes a concrete test reference (`file:test-name`) and the test name contains the cell's `AS-NNN`.
+- The referenced test exercises the named surface/source/timing boundary, not a mock of that boundary.
+- If the cell is a terminal lifecycle/cascade cell, the referenced evidence includes a named cascade test per the Terminal Lifecycle Cascade Test Rule.
+- For `Coverage = GAP-NNN`: a normal `GAP-NNN — BM cell unresolved: ...` checklist line exists. It stays visible in the open-gaps summary and is not a test obligation until `/sp-plan` resolves it into an AS.
+- For `Coverage = N/A`: an `[N/A] BM.NA.<surface>` checklist line exists with a concrete reason.
+
+Minimal shell check (identity only; still review the checklist line for surface/boundary evidence):
+
+```bash
+CHECKLIST=docs/specs/<feature>/.build-checklist
+
+# Any BM.AS line not ticked is an uncovered matrix test obligation.
+grep '^\\[ \\] BM\\.AS\\|^\\[~\\] BM\\.AS' "$CHECKLIST" || true
+
+# Any ticked BM.AS line without a test reference is suspicious and must be reviewed.
+grep '^\\[x\\] BM\\.AS' "$CHECKLIST" | grep -vE '[[:alnum:]_./-]+:[[:alnum:]_ -]+' || true
+```
+
+- **Any `[ ] BM.AS...` line → BLOCKED.** The QA cell has no test.
+- **Any `[~] BM.AS...` line → DONE_WITH_CONCERNS**, unless the destination is a concrete future story/Known-Gap and the feature is not release-critical.
+- **Any `[x] BM.AS...` line with only mocked-boundary evidence → treat as `[~]`**, not done.
+- **Any terminal lifecycle BM line without a named cascade test → treat as `[~]` or BLOCKED**, depending on release criticality.
+- **Any `GAP-NNN — BM cell unresolved` line → visible open gap, not a build test failure.** Do not implement or test that cell until `/sp-plan` resolves it.
+
+### Sibling Surface Map Gate
+
+Run this when the spec contains `## Sibling Surface Map`.
+
+- Confirmed sibling surfaces must be covered indirectly by AS/GAP/BM lines. If a confirmed surface has no AS/GAP/BM coverage, emit a Spec Signal and mark DONE_WITH_CONCERNS or BLOCKED depending on release criticality.
+- Candidate rows are not build gates. Do not implement a candidate solely because it was discovered.
+- A high/medium candidate without `cover`, `GAP-NNN`, or `ignore(reason)` means `/sp-plan` did not finish disposition. Emit a Spec Signal; do not silently choose behavior in code.
+
+### Invariant Registry Gate
+
+Use the invariant registry README/schema as base knowledge; README examples are not runtime entries. Run this when the current project has `docs/invariants/INV-*.md`.
+
+- `status: enforced` with `test_ref` → the referenced test, or an equivalent regression named in the build summary, must be present and run. Missing evidence → BLOCKED.
+- `status: confirmed` → not a hard build gate by itself; verify the spec has AS/GAP/BM coverage when this build touches the component.
+- `status: candidate` → advisory only; do not invent requirements. If the build confirms it, emit a Spec Signal to promote it via `/sp-plan` or `/sp-fix`.
+- `status: retired` → ignore unless this build revives the component.
+
+This gate prevents "memory exists but is never enforced" while avoiding false requirements from noisy candidate entries.
+
 ---
 
 ## Phase 4: Fix Loop
@@ -722,6 +819,9 @@ Stories: [AS-001 ✓, AS-002 ✓, AS-005 new]
 TDD evidence: [S-001: RED (paste 1st failing assertion raw) → GREEN ✓ | tests added: <names>, S-002: RED (raw output) → GREEN ✓ | tests added: <names>]
 Checklist: X/Y [x], A/Y [~] (destinations: <story-id list or Known-Gap refs>), B/Y [ ] (reasons), C/Y [N/A]
 Coverage gate (Phase 3.5): PASS — all AS/C carry a test | BLOCKED — uncovered: <AS/C ids>   (breadth)
+Behavior Matrix gate: PASS — all BM cells [x] | BLOCKED — uncovered: <BM lines> | CONCERNS — partial/mocked-boundary: <BM lines>
+Sibling Surface Map gate: PASS — confirmed surfaces covered | CONCERNS — candidate disposition/spec signal: <candidate ids> | N/A
+Invariant gate: PASS — enforced invariants covered | BLOCKED — missing enforced invariant tests: <INV ids> | N/A — no enforced invariants touched
 Edge Case Compliance: [per-story table — every row ✓ or N/A+reason]   (depth)
 Open gaps: [GAP-NNN not yet resolved, or "none"]
 E2E: [authored + green: <test names> | deferred non-critical (with reason): <flows> | none]. A critical [→E2E] left unwritten → status is DONE_WITH_CONCERNS, not DONE.