sequant 2.10.0 → 2.12.0

package/templates/scripts/new-feature.sh

@@ -3,7 +3,7 @@
 # Create a new feature worktree from a GitHub issue
 # Usage: ./scripts/new-feature.sh <issue-number> [--base <branch>] [--stash]
 # Example: ./scripts/new-feature.sh 4
-# Example: ./scripts/new-feature.sh 4 --stash  # Auto-stash uncommitted changes
+# Example: ./scripts/new-feature.sh 4 --stash  # Deprecated no-op (kept for compatibility)
 # Example: ./scripts/new-feature.sh 4 --base feature/dashboard  # Branch from feature branch
 
 set -e
@@ -108,18 +108,14 @@ echo -e "${BLUE}Base: ${BASE_BRANCH}${NC}"
 echo -e "${BLUE}Worktree: ${WORKTREE_DIR}${NC}"
 echo ""
 
-# Check for uncommitted changes before switching branches
-if ! git diff-index --quiet HEAD -- 2>/dev/null; then
-    if [ "$STASH_FLAG" = true ]; then
-        echo -e "${YELLOW}📦 Stashing uncommitted changes...${NC}"
-        git stash push --include-untracked -m "WIP before issue #${ISSUE_NUMBER}"
-        echo -e "${GREEN}   Changes stashed successfully${NC}"
-    else
-        echo -e "${RED}❌ Working tree has uncommitted changes${NC}"
-        echo -e "${YELLOW}   Use --stash to auto-stash, or manually:${NC}"
-        echo -e "   git stash push -m 'WIP before issue #${ISSUE_NUMBER}'"
-        exit 1
-    fi
+# The main checkout is no longer switched or updated by this script (#910), so
+# an uncommitted main working tree can no longer block or endanger worktree
+# creation — the worktree is branched directly off the fetched remote ref
+# below, and `git fetch` / `git worktree add` both operate happily on a dirty
+# main tree. `--stash` is therefore obsolete: still accepted for backward
+# compatibility, but a no-op, since there is nothing to move out of the way.
+if [ "$STASH_FLAG" = true ]; then
+    echo -e "${YELLOW}ℹ️  --stash is deprecated and now does nothing: new-feature.sh no longer touches the main checkout, so its uncommitted changes are left in place.${NC}"
 fi
 
 # Check if branch already exists
@@ -142,15 +138,25 @@ if git show-ref --verify --quiet "refs/heads/${BRANCH_NAME}"; then
     fi
 fi
 
-# Update base branch
-echo -e "${BLUE}📥 Updating ${BASE_BRANCH} branch...${NC}"
+# Refresh the base branch's remote-tracking ref WITHOUT touching the main
+# checkout. The old flow — `git checkout <base>` then `git pull` — switched the
+# main checkout's branch and mutated its working tree, a global operation the
+# #901 checkout lock exists to serialize. But the pre-tool guard inspects only
+# the top-level Bash command the agent runs; that command is `new-feature.sh`,
+# which carries no guarded git verb, so the inner `checkout`/`pull` sailed past
+# the guard and a losing session could switch the holder's branch out from
+# under it (#910). Reading the ref instead of checking it out closes the gap at
+# its root: the main tree is never mutated, so no lock — and no guard — is
+# needed here at all.
+echo -e "${BLUE}📥 Fetching ${BASE_BRANCH} from origin...${NC}"
 git fetch origin "$BASE_BRANCH"
-git checkout "$BASE_BRANCH"
-git pull origin "$BASE_BRANCH"
 
-# Create worktree from base branch
+# Branch the worktree directly off the freshly fetched remote ref.
+# `git worktree add -b <new> <path> <start-point>` resolves <start-point>
+# without changing the main checkout, and `origin/<base>` is exactly the
+# up-to-date commit the old `checkout`+`pull` used to land on.
 echo -e "${BLUE}🌿 Creating new worktree from ${BASE_BRANCH}...${NC}"
-git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME"
+git worktree add "$WORKTREE_DIR" -b "$BRANCH_NAME" "origin/${BASE_BRANCH}"
 
 # Record the base branch on the new branch so downstream tooling
 # (e.g. phase-executor zero-diff guard, see #537) can resolve the

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

@@ -15,7 +15,7 @@ Claude Code supports exactly **4 built-in subagent types**:
 
 ## Custom Agents (Sequant)
 
-Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
+Sequant defines **3 custom agents** in `.claude/agents/`. These centralize model, permissions, effort, and tool restrictions that were previously duplicated inline.
 
 > **Upstream caveat:** `Model` values below are *declared* in the agent files but
 > currently ignored at runtime per anthropics/claude-code#43869 — every subagent
@@ -24,20 +24,10 @@ Sequant defines **4 custom agents** in `.claude/agents/`. These centralize model
 
 | Agent Name | Based On | Model (declared) | Permission Mode | Used By |
 |------------|----------|------------------|-----------------|---------|
-| `sequant-explorer` | Explore | haiku | (default) | `/spec` |
 | `sequant-qa-checker` | general-purpose | sonnet | bypassPermissions | `/qa` |
 | `sequant-implementer` | general-purpose | (inherits) | bypassPermissions | `/exec` |
 | `sequant-testgen` | general-purpose | haiku | (default) | `/testgen` |
 
-### sequant-explorer
-
-Read-only codebase exploration for the `/spec` phase. No Bash, Edit, or Write access.
-
-```
-Agent(subagent_type="sequant-explorer",
-     prompt="Find similar features in components/. Report patterns.")
-```
-
 ### sequant-qa-checker
 
 Quality check agent for the `/qa` phase. Has `bypassPermissions` for Bash access (git diff, npm test). Effort: low.
@@ -175,12 +165,11 @@ Agent(subagent_type="sequant-qa-checker",
 ```
 
 ### Context Gathering (via /spec)
+
+`/spec` defaults to targeted inline `Read`/`Grep`, not an agent spawn. It escalates to a single `Explore` agent only for open-ended discovery:
 ```
-Agent(subagent_type="sequant-explorer",
+Agent(subagent_type="Explore",
      prompt="Find similar features in components/. Report patterns.")
-
-Agent(subagent_type="sequant-explorer",
-     prompt="Explore database schema for user tables. Report structure.")
 ```
 
 ### Background Execution (via /exec)
@@ -215,7 +204,7 @@ inline when spawning them.
 | Task | Recommended Agent | Why |
 |------|-------------------|-----|
 | 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) |
+| Codebase exploration (open-ended only) | `Explore` | Read-only, built-in; `/spec` prefers inline Read/Grep by default |
 | Implementation subtask | `sequant-implementer` | Full access, inherits model |
 | 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 |
@@ -239,8 +228,8 @@ inline when spawning them.
 These types do **not exist** and will cause silent failures:
 
 - ~~`quality-checker`~~ → Use `sequant-qa-checker` or `general-purpose`
-- ~~`pattern-scout`~~ → Use `sequant-explorer` or `Explore`
-- ~~`schema-inspector`~~ → Use `sequant-explorer` or `Explore`
+- ~~`pattern-scout`~~ → Use `Explore`
+- ~~`schema-inspector`~~ → Use `Explore`
 - ~~`code-reviewer`~~ → Use `sequant-qa-checker` or `general-purpose`
 - ~~`implementation`~~ → Use `sequant-implementer` or `general-purpose`
 

package/templates/skills/assess/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "3.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Read
   - Glob
   - Grep
@@ -99,7 +100,10 @@ gh issue view <N> --json title,body,labels,state,comments,assignees
 
 ```bash
 git branch -a | grep <N> || true
-git worktree list | grep <N> || true
+# Resolve by branch, not by grepping the printed path (#899/#904) — a bare
+# number match is cross-issue (89 matches 899-...) and keys on the directory
+# slug, which can diverge from the branch after a rename.
+npx sequant worktree resolve <N> || true
 gh pr list --search "<N> in:title" --json number,title,state,headRefName,mergeable || true
 ```
 

package/templates/skills/exec/SKILL.md

@@ -29,6 +29,7 @@ allowed-tools:
   # Worktree management
   - Bash(./scripts/new-feature.sh:*)
   - Bash(./scripts/cleanup-worktree.sh:*)
+  - Bash(npx sequant worktree:*)
   # GitHub CLI
   - Bash(gh issue view:*)
   - Bash(gh issue comment:*)
@@ -136,7 +137,7 @@ When running as part of an orchestrated workflow (e.g., `sequant run` or `/fulls
 
 1. **Skip pre-flight git checks** - The orchestrator has already verified git state
 2. **Skip worktree creation** - Orchestrator creates worktrees before invoking skills
-3. **Use provided worktree path** - Work in `SEQUANT_WORKTREE` instead of creating a new one
+3. **Verify, then use, the provided path** - `SEQUANT_WORKTREE` is authoritative *when valid*, but it is never trusted unchecked: run the existence guard in "Feature Worktree Workflow" below and halt if it fails (#899)
 4. **Reduce GitHub comment frequency** - Defer progress updates to the orchestrator
 5. **Trust issue context** - The orchestrator has already fetched and validated issue data
 
@@ -472,15 +473,68 @@ echo "Current branch: $CURRENT_BRANCH"
 **Why this matters:** Work done directly on main can be lost during sync operations (git reset, git pull --rebase, etc.). Worktrees provide isolation and safe recovery through branches.
 
 **If orchestrated (SEQUANT_WORKTREE is set):**
-- Use the provided worktree path directly: `cd $SEQUANT_WORKTREE`
-- Skip steps 1-2 below (worktree already created by orchestrator)
-- Continue with step 3 (Work in the worktree)
+
+<!-- BEGIN: worktree-existence-guard (#899) -->
+
+**Verify the path before you use it. Never `cd` into it unchecked.** An
+orchestrator can hand over a path that was never created, or one that resolves
+into a *different repository's* worktree — `../worktrees/` is one flat
+namespace shared by every repo under the same parent, and issue numbers are
+per-repo. A bare `cd` fails silently and leaves you implementing in the main
+checkout, on whatever branch it happens to be on.
+
+```bash
+npx sequant worktree verify "$SEQUANT_WORKTREE" --issue <issue-number> || {
+  echo "❌ HALT: SEQUANT_WORKTREE is not a usable worktree of this repository."
+  exit 1
+}
+cd "$SEQUANT_WORKTREE"
+```
+
+`verify` exits non-zero with one of these named errors. **Every one of them is
+a halt** — report it and stop; do not fall back to creating a worktree, and do
+not continue in the current directory:
+
+| Error | Meaning |
+|-------|---------|
+| `SEQUANT_WORKTREE_NOT_FOUND` | Path is empty, an unexpanded glob, or not an existing directory |
+| `SEQUANT_WORKTREE_FOREIGN` | Real directory, but not a worktree of *this* repository (another project's, or stale) |
+| `SEQUANT_WORKTREE_ISSUE_MISMATCH` | A worktree of this repo, but its branch belongs to a different issue |
+
+Once verify passes, skip steps 1-2 below and continue with step 3 (Work in the
+worktree).
+
+<!-- END: worktree-existence-guard (#899) -->
 
 **If standalone:**
 
-1. **Check if worktree already exists:**
-   - Check if you're already in a worktree: `git worktree list` or check if `../worktrees/` contains a directory for this issue
-   - If worktree exists, navigate to it and continue work there
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
+1. **Check if a worktree already exists for this issue:**
+
+   Resolve through git, not the filesystem. `sequant worktree resolve` reads
+   `git worktree list` in the current repository — which reports only *this*
+   repo's worktrees — and selects on the **branch** git reports, not on the
+   directory name. That matters twice over: a directory slug is shared across
+   repositories, and it can drift from its own branch after a rename
+   (`578-seo-expand-city-coverage` holding branch `feature/578-city-expansion-clean`),
+   so a name match proves nothing about which branch you would land on.
+
+   ```bash
+   if WORKTREE="$(npx sequant worktree resolve <issue-number>)"; then
+     echo "Existing worktree: $WORKTREE"
+     cd "$WORKTREE"
+     # Continue work there — skip step 2.
+   else
+     echo "No worktree for #<issue-number> in this repository — create one (step 2)."
+   fi
+   ```
+
+   **Do not glob `../worktrees/feature/<issue-number>-*` to find it.** That
+   directory is shared by every sibling repository, so the match may belong to
+   another project entirely.
+
+<!-- END: worktree-standalone-lookup (#899) -->
 
 2. **Create worktree if needed (with parallel context gathering):**
 
@@ -1901,7 +1955,7 @@ The goal is to satisfy AC with the smallest, safest change possible.
 ### 6. Progress Summary and Draft Issue Update
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting progress comments to GitHub (orchestrator handles summary)
+- Skip posting progress comments to GitHub — no per-phase comment is posted under `sequant run`; progress surfaces through the run summary and the PR body (#964)
 - Still provide AC coverage summary in output for orchestrator to capture
 - Let orchestrator handle final GitHub update