sequant 2.1.2 → 2.3.0

package/templates/agents/sequant-testgen.md

@@ -1,6 +1,7 @@
 ---
 name: sequant-testgen
 description: Test stub generator for sequant /testgen phase. Parses verification criteria from /spec comments and generates Jest/Vitest test stubs with Given/When/Then structure. Use when spawned by the /testgen skill.
+# Note: per anthropics/claude-code#43869 this is currently a no-op; agent runs on parent's model
 model: haiku
 maxTurns: 25
 tools:

package/templates/hooks/post-tool.sh

@@ -13,6 +13,17 @@ if [[ "${CLAUDE_HOOKS_DISABLED:-}" == "true" ]]; then
     exit 0
 fi
 
+# === RELAY CHECK (#383) ===
+# Sourced only when SEQUANT_RELAY=true. The check itself is a single env-var
+# comparison when relay is disabled (default), so non-relay runs incur no cost.
+if [[ "${SEQUANT_RELAY:-}" == "true" ]]; then
+    _RELAY_CHECK="$(dirname "${BASH_SOURCE[0]:-$0}")/relay-check.sh"
+    if [[ -f "${_RELAY_CHECK}" ]]; then
+        # shellcheck source=relay-check.sh disable=SC1091
+        source "${_RELAY_CHECK}" || true
+    fi
+fi
+
 # === READ INPUT FROM STDIN ===
 # Claude Code passes tool data as JSON via stdin, not environment variables
 INPUT_JSON=$(cat)

package/templates/hooks/pre-tool.sh

@@ -104,20 +104,23 @@ if echo "$TOOL_INPUT" | grep -qE '^(env|printenv|export)$'; then
 fi
 
 # Destructive system commands
-if echo "$TOOL_INPUT" | grep -qE 'sudo|rm -rf /|rm -rf ~|rm -rf \$HOME'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#570)
+if ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'sudo|rm -rf /|rm -rf ~|rm -rf \$HOME'; then
     echo "HOOK_BLOCKED: Destructive system command" | tee -a "$HOOK_LOG" >&2
     exit 2
 fi
 
 # Deployment (should never happen in issue automation)
-if echo "$TOOL_INPUT" | grep -qE 'vercel (deploy|--prod)|terraform (apply|destroy)|kubectl (apply|delete)'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#570)
+if ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'vercel (deploy|--prod)|terraform (apply|destroy)|kubectl (apply|delete)'; then
     echo "HOOK_BLOCKED: Deployment command" | tee -a "$HOOK_LOG" >&2
     exit 2
 fi
 
 # Force push
 # Pattern requires -f to be a standalone flag (not part of branch name like -fix)
-if echo "$TOOL_INPUT" | grep -qE 'git push.*(--force| -f($| ))'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#564)
+if ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git push.*(--force| -f($| ))'; then
     echo "HOOK_BLOCKED: Force push" | tee -a "$HOOK_LOG" >&2
     exit 2
 fi
@@ -127,7 +130,8 @@ fi
 # - Unpushed commits on main/master
 # - Uncommitted changes (staged or unstaged)
 # - Unfinished merge in progress
-if echo "$TOOL_INPUT" | grep -qE 'git reset.*(--hard|origin)'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#570)
+if ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git reset.*(--hard|origin)'; then
     CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "")
     BLOCK_REASONS=""
     
@@ -167,7 +171,8 @@ if echo "$TOOL_INPUT" | grep -qE 'git reset.*(--hard|origin)'; then
 fi
 
 # CI/CD triggers (automation shouldn't trigger more automation)
-if echo "$TOOL_INPUT" | grep -qE 'gh workflow run'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#570)
+if ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'gh workflow run'; then
     echo "HOOK_BLOCKED: Workflow trigger" | tee -a "$HOOK_LOG" >&2
     exit 2
 fi
@@ -225,7 +230,8 @@ check_sensitive_files() {
 
 if [[ "${CLAUDE_HOOKS_SECURITY:-true}" != "false" ]]; then
     # Security checks for git commit
-    if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
+    # Skip for gh issue/pr commands — body text may legitimately reference these tokens (#564)
+    if [[ "$TOOL_NAME" == "Bash" ]] && ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
         # Skip security checks if --no-verify is used
         if ! echo "$TOOL_INPUT" | grep -qE -- '--no-verify'; then
             # Check staged files for secrets
@@ -257,7 +263,8 @@ fi
 # --- No-Changes Guard (AC-7) ---
 # Block commits when there are no staged or unstaged changes (prevents empty commits)
 # Skips for --amend since amending doesn't require new changes
-if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#564)
+if [[ "$TOOL_NAME" == "Bash" ]] && ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
     if ! echo "$TOOL_INPUT" | grep -qE -- '--amend|--allow-empty'; then
         # Extract target directory from cd command if present (for worktree commits)
         # Handles: "cd /path && git commit" or "cd /path; git commit"
@@ -284,7 +291,8 @@ fi
 # Warn (but don't block) when committing outside a feature worktree
 # This catches accidental commits to main repo during feature work
 QUALITY_LOG="${_LOG_DIR}/claude-quality.log"
-if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#564)
+if [[ "$TOOL_NAME" == "Bash" ]] && ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
     CWD=$(pwd)
     if ! echo "$CWD" | grep -qE 'worktrees/feature/'; then
         echo "$(date +%H:%M:%S) WORKTREE_WARNING: Committing outside feature worktree ($CWD)" >> "$QUALITY_LOG"
@@ -295,7 +303,8 @@ fi
 # --- Commit Message Validation (AC-3) ---
 # Enforce conventional commits format: type(scope): description
 # Types: feat|fix|docs|style|refactor|test|chore|ci|build|perf
-if [[ "$TOOL_NAME" == "Bash" ]] && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
+# Skip for gh issue/pr commands — body text may legitimately reference these tokens (#564)
+if [[ "$TOOL_NAME" == "Bash" ]] && ! echo "$TOOL_INPUT" | grep -qE '^gh (issue|pr) ' && echo "$TOOL_INPUT" | grep -qE 'git commit'; then
     # Extract message from -m flag
     MSG=""
 

package/templates/hooks/relay-check.sh

@@ -0,0 +1,107 @@
+#!/bin/bash
+# Relay check (#383): sourced from post-tool.sh on every PostToolUse when
+# SEQUANT_RELAY=true. Reads unread user messages from inbox.jsonl, renders the
+# framing prompt to stdout (which Claude Code surfaces as additional context),
+# and advances the per-issue read cursor.
+#
+# Fast path (no pending messages): exits silently in well under 5 ms.
+# Slow path (messages pending): renders one framing block per invocation.
+
+# Opt-in guard. Fast path #1: env var unset / not exactly "true".
+# Bash precedence makes `cmd1 && cmd2 || cmd3` equivalent to `(cmd1 && cmd2) || cmd3`,
+# so we must use an explicit `if` block to avoid falling through to `exit 0`
+# when the test is FALSE (which is the relay-enabled case).
+if [[ "${SEQUANT_RELAY:-}" != "true" ]]; then
+    return 0 2>/dev/null || exit 0
+fi
+
+# Resolve relay directory. Inside an isolated worktree, the phase-executor sets
+# SEQUANT_WORKTREE. During the spec phase (main repo) we fall back to the
+# per-issue layout under .sequant/relay/<issue>/.
+if [[ -n "${SEQUANT_WORKTREE:-}" ]]; then
+  _RELAY_DIR="${SEQUANT_WORKTREE}/.sequant/relay"
+elif [[ -n "${SEQUANT_ISSUE:-}" ]]; then
+  _RELAY_DIR="${PWD}/.sequant/relay/${SEQUANT_ISSUE}"
+else
+  # Nothing to do without a target issue or worktree.
+  return 0 2>/dev/null || exit 0
+fi
+
+_INBOX="${_RELAY_DIR}/inbox.jsonl"
+_CURSOR="${_RELAY_DIR}/.cursor"
+
+# Fast path #2: AC-8 — `test -s` is sub-millisecond. Empty/missing inbox skips.
+[[ -s "${_INBOX}" ]] || return 0 2>/dev/null || exit 0
+
+# Cursor read (missing → 0). Compare against current inbox line count.
+_CURSOR_VAL=0
+if [[ -f "${_CURSOR}" ]]; then
+  _CURSOR_VAL=$(cat "${_CURSOR}" 2>/dev/null || echo 0)
+  [[ "${_CURSOR_VAL}" =~ ^[0-9]+$ ]] || _CURSOR_VAL=0
+fi
+
+_INBOX_LINES=$(wc -l < "${_INBOX}" 2>/dev/null || echo 0)
+_INBOX_LINES=${_INBOX_LINES// /} # trim whitespace from wc output on macOS
+
+# Fast path #3: cursor caught up.
+if [[ "${_INBOX_LINES}" -le "${_CURSOR_VAL}" ]]; then
+  return 0 2>/dev/null || exit 0
+fi
+
+# Slow path: render frame.
+
+# Resolve frame template. Phase-executor sets SEQUANT_RELAY_FRAME to the
+# absolute path within the sequant installation. Falls back to ./templates/
+# (when running from the sequant repo itself).
+_FRAME_PATH="${SEQUANT_RELAY_FRAME:-}"
+if [[ -z "${_FRAME_PATH}" || ! -f "${_FRAME_PATH}" ]]; then
+  for _candidate in \
+      "${PWD}/.claude/relay/frame.txt" \
+      "${PWD}/templates/relay/frame.txt"; do
+    if [[ -f "${_candidate}" ]]; then
+      _FRAME_PATH="${_candidate}"
+      break
+    fi
+  done
+fi
+if [[ -z "${_FRAME_PATH}" || ! -f "${_FRAME_PATH}" ]]; then
+  # Missing template — emit a minimal frame so the user still gets through.
+  _FRAME_PATH=""
+fi
+
+# Skip the lines we've already shown the model. `tail -n +N` is 1-indexed.
+_START=$((_CURSOR_VAL + 1))
+
+# Render messages. Sort by timestamp ascending (AC-9). jq handles JSON parsing.
+# Messages are separated by `---` lines; a single message has no separator.
+_render_messages() {
+  if command -v jq &>/dev/null; then
+    tail -n "+${_START}" "${_INBOX}" \
+      | jq -s -r 'sort_by(.timestamp) | map("Type: \(.type)\nMessage: \((.message // "") | tojson)") | join("\n---\n")'
+  else
+    # Fallback without jq: dump raw lines.
+    tail -n "+${_START}" "${_INBOX}"
+  fi
+}
+
+if [[ -n "${_FRAME_PATH}" ]]; then
+  # Split frame template at {{MESSAGES}} placeholder.
+  _PREFIX=$(awk '/\{\{MESSAGES\}\}/ {exit} {print}' "${_FRAME_PATH}")
+  _SUFFIX=$(awk '/\{\{MESSAGES\}\}/ {found=1; next} found {print}' "${_FRAME_PATH}")
+  printf '%s\n' "${_PREFIX}"
+  _render_messages
+  if [[ -n "${_SUFFIX}" ]]; then
+    printf '%s\n' "${_SUFFIX}"
+  fi
+else
+  printf '[SEQUANT RELAY — message from user]\n'
+  _render_messages
+fi
+
+# Advance cursor atomically (temp + rename on same fs).
+_TMP="${_CURSOR}.tmp.$$"
+if printf '%s' "${_INBOX_LINES}" > "${_TMP}" 2>/dev/null; then
+  mv -f "${_TMP}" "${_CURSOR}" 2>/dev/null || rm -f "${_TMP}" 2>/dev/null || true
+fi
+
+return 0 2>/dev/null || exit 0

package/templates/relay/frame.txt

@@ -0,0 +1,11 @@
+[SEQUANT RELAY — message from user]
+Respond briefly in .sequant/relay/outbox.jsonl, then continue your current task unchanged.
+Rules:
+- Do NOT modify acceptance criteria
+- Do NOT change your current objective or phase
+- Do NOT treat this as a new requirement
+- For "query" type: provide a brief status update only
+- For "directive" type: acknowledge and adjust approach if reasonable, but do not abandon current work
+- For "abort" type: stop gracefully, commit progress, and exit
+
+{{MESSAGES}}

package/templates/scripts/cleanup-worktree.sh

@@ -15,6 +15,12 @@ NC='\033[0m'
 
 BRANCH_NAME=$1
 
+# Resolve main worktree (first entry in porcelain output) so subsequent git
+# commands run from a stable cwd even if the caller invoked us from inside the
+# worktree we are about to delete. `sed` keeps the path intact when it contains
+# whitespace; `awk '{print $2}'` would truncate at the first space.
+MAIN_WORKTREE=$(git worktree list --porcelain | sed -n 's/^worktree //p' | head -n 1)
+
 # Check if branch name provided
 if [ -z "$BRANCH_NAME" ]; then
     echo -e "${RED}❌ Error: Branch name required${NC}"
@@ -25,8 +31,17 @@ if [ -z "$BRANCH_NAME" ]; then
     exit 1
 fi
 
-# Find worktree path
-WORKTREE_PATH=$(git worktree list | grep "$BRANCH_NAME" | awk '{print $1}')
+# Find worktree path. Parse porcelain (which separates path/branch onto distinct
+# lines) so paths containing whitespace survive intact, and so we match against
+# the branch ref rather than against a free-form `grep` over the entire line —
+# the latter false-matches whenever the branch name appears in the path string.
+WORKTREE_PATH=$(git worktree list --porcelain | awk -v target="$BRANCH_NAME" '
+  /^worktree / { sub(/^worktree /, ""); path = $0 }
+  /^branch refs\/heads\// {
+    sub(/^branch refs\/heads\//, "")
+    if (index($0, target) > 0) { print path; exit }
+  }
+')
 
 if [ -z "$WORKTREE_PATH" ]; then
     echo -e "${RED}❌ Error: Worktree not found for branch: $BRANCH_NAME${NC}"
@@ -53,6 +68,13 @@ if [ "$PR_STATUS" != "MERGED" ]; then
     fi
 fi
 
+# Move to the main worktree before any destructive operation. If the caller's
+# cwd is inside $WORKTREE_PATH (or any of its .exec-agents/agent-* sub-worktrees
+# below), the first `git worktree remove` would invalidate cwd and every
+# subsequent git/gh call would silently fail with "Unable to read current
+# working directory" — including the ones with `2>/dev/null || true`.
+cd "$MAIN_WORKTREE"
+
 # Clean up any exec-agent sub-worktrees first (from parallel isolation)
 EXEC_AGENTS_DIR="$WORKTREE_PATH/.exec-agents"
 if [ -d "$EXEC_AGENTS_DIR" ]; then
@@ -71,7 +93,7 @@ if [ -d "$EXEC_AGENTS_DIR" ]; then
     rmdir "$EXEC_AGENTS_DIR" 2>/dev/null || true
 fi
 
-# Remove worktree
+# Remove worktree (cwd already pinned to $MAIN_WORKTREE above)
 echo -e "${BLUE}📂 Removing worktree...${NC}"
 git worktree remove "$WORKTREE_PATH" --force
 

package/templates/scripts/new-feature.sh

@@ -152,6 +152,12 @@ git pull origin "$BASE_BRANCH"
 echo -e "${BLUE}🌿 Creating new worktree from ${BASE_BRANCH}...${NC}"
 git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
 
+# Record the base branch on the new branch so downstream tooling
+# (e.g. phase-executor zero-diff guard, see #537) can resolve the
+# correct comparison ref when the worktree was branched off something
+# other than origin/main.
+git -C "$WORKTREE_DIR" config "branch.${BRANCH_NAME}.sequantBase" "$BASE_BRANCH"
+
 # Navigate to worktree
 cd "$WORKTREE_DIR"
 

package/templates/skills/_shared/references/behavior-rule-detection.md

@@ -0,0 +1,205 @@
+# Behavior-Rule Detection (Shared Heuristic for /spec + /qa)
+
+> **Source of truth:** `src/lib/heuristics/behavior-rule-detector.ts`. The
+> keyword set, threshold, and pattern list live in TypeScript so they can be
+> unit-tested (per AC-5 of #552); this doc cites them.
+
+## Why this exists
+
+Behavior-rule ACs ("default becomes X", "always include Y", "never skip Z") are
+routinely implemented at **multiple touchpoints** — typically a skill prompt
+(LLM-interpreted) **and** runtime TypeScript that duplicates the same rule.
+Without a shared check, edits land at one site and the other goes stale.
+
+**Motivating miss — issue #533** ("default /assess spec phase ON, remove
+bug/docs auto-skip"):
+
+- The AC explicitly named `.claude/skills/assess/SKILL.md`.
+- `/spec` scoped the work to that file + CHANGELOG. `/exec` implemented it.
+  `/qa` returned `READY_FOR_MERGE`.
+- Meanwhile the runtime CLI (`phase-mapper.ts` `detectPhasesFromLabels` +
+  `batch-executor.ts` auto-detect branch) still short-circuited bug/docs
+  issues to `exec → qa`, contradicting the new "spec by default" rule.
+- Caught only by manual user follow-up; required two extra commits and four
+  doc updates on top of the original PR.
+
+A pre-flight grep for `BUG_LABELS` / `DOCS_LABELS` / `"skip spec"` at /spec
+time would have surfaced 90% of these in one pass. That's exactly what this
+heuristic does.
+
+## Trigger keywords
+
+A `BEHAVIOR_KEYWORDS` constant in `behavior-rule-detector.ts`. Each keyword
+also matches common inflections via the `KEYWORD_REGEXES` map (mirrors the
+stem-aware pattern landed by #597 in `ac-linter.ts`); word boundaries are
+preserved so `defaultValue` (camelCase identifier) does NOT trigger.
+
+| Keyword | Inflections matched | Why it's in the set |
+|---------|---------------------|---------------------|
+| `default` | `defaults`, `defaulted`, `defaulting` | "default becomes X", "defaults to Y" |
+| `always` | (adverb, no inflections) | "always include", "always run" |
+| `never` | (adverb, no inflections) | "never skip", "never run when X" |
+| `rule` | `rules`, `ruled`, `ruling` | "the rule is", "this rule applies" |
+| `behavior` | `behaviors`, `behavioral`, `behaviorally` | "the behavior is", "behaviors change" |
+| `skip` | `skips`, `skipped`, `skipping` | "skip spec", "skipping when X" |
+
+## Trigger threshold (false-positive guard)
+
+To avoid flagging localized fixes that happen to mention "default" once
+("set default value to 5"), the detector requires **either**:
+
+1. **>= 2 distinct keywords** from `BEHAVIOR_KEYWORDS` in the AC description
+   (case-insensitive, word-boundary), **OR**
+2. An **explicit pattern** match (single keyword is enough):
+   - Mid-sentence rule constructs:
+     - `always X unless Y`
+     - `never X unless Y`
+     - `default X when Y`
+   - Capitalized imperative AC openers (case-sensitive — matches the
+     imperative-rule register, not "the system always defaults to..." prose):
+     - `Always <verb> ...` — covers AC-5 literal "Always include Y"
+     - `Never <verb> ...` — covers AC-5 literal "Never skip Z"
+     - `Default <verb> ...` — covers AC-5 literal "Default rule becomes X"
+
+Tunable in `EXPLICIT_PATTERNS` in `behavior-rule-detector.ts`.
+
+## Symbol categories surfaced by `findTouchpoints`
+
+When the trigger fires, `findTouchpoints` extracts identifier-like substrings
+from the AC and greps the codebase for them, plus any line that contains >= 2
+distinct behavior keywords (catches comment-only sites). Symbol categories:
+
+| Category | Example | Why include |
+|----------|---------|-------------|
+| Backticked symbols | `` `BUG_LABELS` ``, `` `phase-mapper.ts` `` | Verbatim from issue body — most specific |
+| `SCREAMING_SNAKE_CASE` constants | `BUG_LABELS`, `DOCS_LABELS`, `SKIP_PHASES` | Dominant runtime-rule pattern |
+| `camelCase` function names | `detectPhasesFromLabels`, `shouldSkipSpec` | Rule-implementing functions |
+| File paths with extensions | `.claude/skills/assess/SKILL.md`, `phase-mapper.ts` | Direct touchpoint citations |
+| Bold spans | `**always X unless Y**` | Author-emphasized rule statements |
+
+## Inverse search (`findSurvivingInverseSymbols`, used by `/qa`)
+
+`/qa` runs the detector against the diff blast radius (changed files +
+optional 1-hop importers) using **inverse** keywords derived from each
+asserted keyword. Asymmetric on purpose — an AC asserting the NEW rule
+"always include spec" should look for "skip" / "exclude" / "bypass"
+survivors, not "always" itself.
+
+| Asserted keyword | Inverse search terms |
+|------------------|----------------------|
+| `default` | `skip`, `exclude`, `bypass`, `override` |
+| `always` | `skip`, `never`, `exclude`, `conditional`, `shortcut` |
+| `never` | `always`, `default`, `exclude` |
+| `rule` | `exception`, `override`, `shortcut`, `bypass` |
+| `behavior` | `legacy`, `deprecated` |
+| `skip` | `always`, `default`, `exclude` |
+
+High-noise common English words (`include`, `run`, `auto`, `old`,
+`previous`) were pruned from this map after QA's self-dogfood pass on #552
+returned 50 survivors entirely from definitional prose. As defense in
+depth, `deriveInverseTerms` also drops any term in the `COMMON_WORDS`
+filter at runtime, so future tunings that re-add a common word are still
+filtered out.
+
+A survival inside the diff blast radius -> AC `NOT_MET` with `path:line`
+listed in the QA output (per AC-2 of #552).
+
+## False-positive guards
+
+- Test files (`*.test.ts`, `*.spec.ts`) are excluded from `findTouchpoints` —
+  they implement *checks* of behavior rules, not the rules themselves.
+- Walk-skip dirs: `node_modules`, `.git`, `dist`, `build`, `.next`,
+  `coverage`, `__tests__`, `__snapshots__`.
+- Common English words (`the`, `from`, `should`, `becomes`, ...) are filtered
+  from the symbol-extraction pass to avoid grepping for "the".
+- Per-file cap (3) + total cap (200) on `findTouchpoints` results — keeps
+  `/spec` output readable when an AC's keywords are ambient in the repo.
+- Total cap (50, `SURVIVOR_TOTAL_CAP`) on `findSurvivingInverseSymbols`
+  results — tighter than `findTouchpoints` because survivors are surfaced
+  inside the QA verdict and a long list drowns out the rule-relevant hits.
+
+## Performance budget
+
+- `detectBehaviorRule(ac)` is a cheap regex pass — runs per AC.
+- `findTouchpoints` and `findSurvivingInverseSymbols` short-circuit to `[]`
+  when `detectBehaviorRule` returns `triggered: false`.
+- For `/qa`, the per-AC grep cost is bounded by the diff blast radius (not
+  the whole repo). For `/spec`, scope is `src/lib`, `src/commands`, `bin`,
+  and `.claude/skills` — `bin/` and `src/commands/` are included because CLI
+  option registration (Commander.js `.option()` chains, `RunOptions` interface)
+  is a recurring rule-drift site. `templates/skills/` and `skills/` are
+  intentionally excluded since they 1:1 mirror `.claude/skills/`.
+
+When zero behavior-rule ACs are detected across the issue, both detectors
+should be skipped entirely (no per-file grep pass).
+
+## Where to call from
+
+- **`/spec`** — `### Rule Touchpoints (Conditional)` subsection under
+  `## Context Gathering`. Calls `findTouchpoints` per AC; emits a
+  `## Rule Touchpoints` section in the plan output when any hits found.
+- **`/qa`** — `### 6e. Behavior-Rule Survival Check` between
+  `### 6d. Adversarial Re-Read` and `### 7. A+ Status Verdict`. Calls
+  `findSurvivingInverseSymbols` per behavior-rule AC; survivals -> AC
+  `NOT_MET`, gated through `behavior_rule_survival_status` in section 7.
+
+## API
+
+```typescript
+import {
+  detectBehaviorRule,
+  findTouchpoints,
+  findSurvivingInverseSymbols,
+} from "./src/lib/heuristics/behavior-rule-detector.ts";
+
+// Cheap gate
+const detection = detectBehaviorRule(ac);
+// detection.triggered: boolean
+// detection.keywords: BehaviorKeyword[]
+// detection.matchedPattern?: string
+
+// /spec: enumerate likely implementation sites
+const hits = findTouchpoints(ac, repoRoot);
+// hits: { path, line, snippet }[]
+
+// /qa: search diff blast radius for OLD-rule survivors
+const survivors = findSurvivingInverseSymbols(ac, repoRoot, diffPaths);
+// survivors: { path, line, snippet }[]
+```
+
+## Known limitations
+
+**Meta-recursion** — when an AC describes the detector itself (e.g. lists
+all six trigger keywords as part of explaining the trigger condition),
+`findSurvivingInverseSymbols` will self-fire on the new feature's own
+definitional documentation. The pruned `INVERSE_KEYWORDS` map and
+`SURVIVOR_TOTAL_CAP = 50` mitigate noise, but the heuristic cannot
+distinguish "code that implements the OLD rule" from "documentation that
+defines the rule". Treat survivors inside this reference doc and
+`spec/SKILL.md` / `qa/SKILL.md` as definitional, not stale. See QA's
+self-dogfood result on PR #607 for the original observation.
+
+**Inverse-phrase fallback (deferred)** — `findSurvivingInverseSymbols`
+relies on the asserted-→-inverse keyword map. When an AC's inverse rule
+has no obvious symbol or keyword (e.g. "API responses always include the
+user ID field"), the natural next layer is to derive an inverse English
+phrase ("exclude user ID", "don't include user ID") and grep for that.
+Not implemented — file a follow-up issue with the concrete fixture if a
+real `/qa` miss surfaces.
+
+## Tuning
+
+Edit `src/lib/heuristics/behavior-rule-detector.ts`:
+
+- `BEHAVIOR_KEYWORDS` — keyword stem set (the source of truth)
+- `KEYWORD_REGEXES` — per-stem inflection regex map; word-boundary
+  guarded so identifier-shaped tokens (`defaultValue`, `skipperFn`) do
+  not trigger
+- `EXPLICIT_PATTERNS` — single-keyword override patterns (mid-sentence
+  rule constructs + capitalized imperative AC openers)
+- `INVERSE_KEYWORDS` — asserted -> inverse mapping for `/qa` (common
+  English words filtered at runtime in `deriveInverseTerms`)
+- `TOUCHPOINT_ROOTS` — directories scanned by `findTouchpoints`
+- `SURVIVOR_TOTAL_CAP` — total survivor cap on `findSurvivingInverseSymbols`
+
+Re-run `npx vitest run src/lib/heuristics` after tuning.

package/templates/skills/_shared/references/subagent-types.md

@@ -17,10 +17,15 @@ Claude Code supports exactly **4 built-in subagent types**:
 
 Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
 
-| Agent Name | Based On | Model | Permission Mode | Used By |
-|------------|----------|-------|-----------------|---------|
+> **Upstream caveat:** `Model` values below are *declared* in the agent files but
+> currently ignored at runtime per anthropics/claude-code#43869 — every subagent
+> inherits the parent session's model. Tiers are kept aligned with intended
+> defaults so they reactivate when upstream fixes ship.
+
+| Agent Name | Based On | Model (declared) | Permission Mode | Used By |
+|------------|----------|------------------|-----------------|---------|
 | `sequant-explorer` | Explore | haiku | (default) | `/spec` |
-| `sequant-qa-checker` | general-purpose | haiku | bypassPermissions | `/qa` |
+| `sequant-qa-checker` | general-purpose | sonnet | bypassPermissions | `/qa` |
 | `sequant-implementer` | general-purpose | (inherits) | bypassPermissions | `/exec` |
 | `sequant-testgen` | general-purpose | haiku | (default) | `/testgen` |
 
@@ -68,7 +73,8 @@ Custom agents are defined in `.claude/agents/*.md` with YAML frontmatter:
 ---
 name: sequant-qa-checker
 description: Quality check agent for sequant QA phase.
-model: haiku
+# Note: per anthropics/claude-code#43869 this is currently a no-op; agent runs on parent's model
+model: sonnet
 permissionMode: bypassPermissions
 effort: low
 maxTurns: 15
@@ -139,10 +145,17 @@ Agent(subagent_type="Plan",
 
 **Default:** Use `haiku` unless the task requires deep reasoning.
 
+> **Note:** Per anthropics/claude-code#43869, both the per-call `model:`
+> parameter and the agent-definition `model:` field are currently ignored.
+> Subagents inherit the parent session's model regardless of what you specify
+> here. The guidance below reflects the *intended* tier each task should use
+> once upstream fixes land.
+
 Custom agents set their model in the agent definition, so you don't need to specify it inline:
 
 ```
-# Model comes from .claude/agents/sequant-qa-checker.md (haiku)
+# Model comes from .claude/agents/sequant-qa-checker.md (sonnet, declared)
+# Note: declared tier currently inert per anthropics/claude-code#43869
 Agent(subagent_type="sequant-qa-checker",
      prompt="...")
 ```
@@ -201,10 +214,10 @@ inline when spawning them.
 
 | Task | Recommended Agent | Why |
 |------|-------------------|-----|
-| Quality checks (git diff, npm test) | `sequant-qa-checker` | bypassPermissions + haiku + effort:low |
-| Codebase exploration | `sequant-explorer` | Read-only, haiku, focused tools |
+| Quality checks (git diff, npm test) | `sequant-qa-checker` | bypassPermissions + effort:low (declared model: sonnet, inert per #43869) |
+| Codebase exploration | `sequant-explorer` | Read-only, focused tools (declared model: haiku, inert per #43869) |
 | Implementation subtask | `sequant-implementer` | Full access, inherits model |
-| Test stub generation | `sequant-testgen` | Write access, no Bash, haiku |
+| Test stub generation | `sequant-testgen` | Write access, no Bash (declared model: haiku, inert per #43869) |
 | One-off custom task | `general-purpose` | Flexible, specify model/mode inline |
 
 **CRITICAL:** If your background agent runs `git diff`, `npm test`, `git status`, or any shell command, use `sequant-qa-checker` or `sequant-implementer` (both have bypassPermissions). Do NOT use `general-purpose` without `mode="bypassPermissions"` — Bash calls will silently fail.