sequant 2.2.0 → 2.3.0

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.