sequant 2.10.0 → 2.11.0

package/templates/skills/release/SKILL.md

@@ -112,6 +112,62 @@ gh auth status || { echo "Not logged in - run: gh auth login"; exit 1; }
 
 ## Release Steps
 
+### Step 0: Acquire the Checkout Lock (REQUIRED)
+
+Everything from here on mutates the **main checkout**: the version bump and its
+commit, tag, and push (Steps 4–7), plus the rollback verbs (`git reset --soft`,
+`git checkout -- …`) if a step fails. `git commit`/`tag`/`push` are not guarded
+by `pre-tool.sh`, but the `git reset` in rollback is — and, more importantly,
+holding the checkout lock (#901) is what stops a session on another issue from
+interleaving a `git checkout` between the bump and the commit and landing the
+release commit on the wrong HEAD. So claim the tree now, before the first
+interactive approval pause (Step 2's release-notes review), exactly as
+`/fullsolve` does in its Phase 0.3.
+
+`/release` has no issue of its own, and the checkout lock proves ownership by a
+**positive integer** — the `pre-tool.sh` guard and `sequant locks checkout` both
+key on `--issue=<N>`. So `/release` claims the tree under a reserved sentinel
+issue id, **`999999999`** (a number that will never be a real issue), and uses it
+on the acquire and on every release below. `locks list` and the CLI's
+release-refusal render this sentinel as `/release (sentinel)` so it does not
+read as a real issue. A symbolic holder (e.g. `--label=release`) would avoid
+the reserved-number scheme entirely, but it would require changing the
+lock-file schema, the CLI, *and* the numeric-only `pre-tool.sh` guard — out of
+scope for #911 (tracked there as a follow-up).
+
+```bash
+# Claim the shared working tree before the first mutation / approval pause.
+# Skip for --dry-run: it previews only and mutates nothing, so it needs no lock.
+npx sequant locks checkout acquire \
+    --issue=999999999 \
+    --command="/release" \
+    --skip-pid-check || true
+export SEQUANT_ISSUE=999999999
+```
+
+Acquire **after** the read-only pre-flight checks above, not before: those checks
+(`git status`/`fetch`, `npm test`/`build`, `npm whoami`, `gh auth`) mutate
+nothing, so a pre-flight abort holds no lock and needs no release. That is why the
+pre-flight `exit 1` branches carry no release call — you cannot release a lock you
+have not taken.
+
+**`--issue=999999999` is mandatory on release** (#906): it is what proves you are
+the holder once the acquiring shell's PID is gone (`--skip-pid-check`). Stale
+recovery is age-based only (the 6h `SEQUANT_SKILL_LOCK_TTL_MS` and the 24h
+`SEQUANT_MAX_LOCK_AGE_MS` ceiling), not same-host dead-PID recovery.
+
+**Release contract:** release the checkout lock —
+`npx sequant locks checkout release --issue=999999999 || true` — on **every**
+path that exits after this acquire: happy-path completion (Post-Release
+Verification), any mid-release error (Error Handling), and the Rollback
+Procedures. Releasing an already-released lock is a harmless no-op, so a failure
+that both errors and rolls back may run two of these — that is safe.
+
+**Orchestrator/MCP mode:** when `SEQUANT_ORCHESTRATOR` is set, every `locks
+checkout` action is a no-op (exit 0, no file touched) and the `pre-tool.sh`
+checkout guard stands down, so the acquire/release calls are safe to run
+unconditionally.
+
 ### Step 1: Determine Version
 
 If version type not provided as argument, ask the user:
@@ -493,6 +549,13 @@ gh release view "v${new_version}"
 npx sequant@${new_version} --version
 ```
 
+The release is complete — hand the working tree back (#901). This is the
+counterpart to the acquire in Step 0.
+
+```bash
+npx sequant locks checkout release --issue=999999999 || true
+```
+
 ## Output Summary
 
 ```
@@ -575,6 +638,11 @@ git reset --soft HEAD~1
 
 # Delete local tag
 git tag -d v{version}
+
+# Rollback aborts the release — hand the working tree back (#901/#906).
+# The git reset above is a guarded verb; it runs unrefused only because Step 0
+# made this session the checkout holder.
+npx sequant locks checkout release --issue=999999999 || true
 ```
 
 ### After git push, before npm publish
@@ -589,6 +657,9 @@ gh release delete v{version} --yes
 # Revert commit
 git revert HEAD
 git push origin main
+
+# Rollback aborts the release — hand the working tree back (#901/#906).
+npx sequant locks checkout release --issue=999999999 || true
 ```
 
 ### After npm publish
@@ -601,6 +672,14 @@ Instead:
 
 ## Error Handling
 
+**If a release step fails and you halt without completing, release the checkout
+lock first** (#901/#906) — Step 0 acquired it and every abort after that must hand
+the working tree back before stopping:
+
+```bash
+npx sequant locks checkout release --issue=999999999 || true
+```
+
 | Error | Cause | Resolution |
 |-------|-------|------------|
 | "Not on main" | Wrong branch | `git checkout main` |

package/templates/skills/spec/SKILL.md

@@ -13,7 +13,7 @@ allowed-tools:
   - Bash(gh label:*)
   - Bash(git worktree:*)
   - Bash(git -C:*)
-  - Agent(sequant-explorer)
+  - Agent(Explore)
   - AgentOutputTool
 ---
 
@@ -24,6 +24,22 @@ allowed-tools:
 
 Phase 1 "Planning Agent." Understands the issue and AC, reviews or synthesizes a plan, identifies gaps and risks, and drafts a GitHub issue comment.
 
+## Worktree Contract
+
+<!-- BEGIN: spec-worktree-contract (#899) -->
+
+**No worktree needed. Planning happens in the main repository directory.** The
+worktree is created later — by the orchestrator (`/fullsolve` Phase 1.5, or
+`sequant run`) when one is driving, otherwise by `/exec` itself.
+
+This skill only ever *reads* `git worktree list`, for in-flight collision
+detection. **Do not create a worktree here, and do not describe one as
+existing after `/spec`** — downstream skills that trust such a claim end up
+implementing in the main checkout (#899, and the line this restores was
+dropped by #515).
+
+<!-- END: spec-worktree-contract (#899) -->
+
 ## Platform Detection — Run First
 
 ```bash
@@ -114,22 +130,11 @@ ls -d src/ app/ lib/ components/ pages/ routes/ docs/ 2>/dev/null || true
 
 Use discovered paths in all agent prompts and search commands.
 
-### Agent Spawn Rules
+### Context-Gathering Strategy
 
-Determine agent count from issue content — do NOT always spawn 3:
+Default to targeted inline `Read`/`Grep` against the paths the issue names or the ones discovered above — this is what actually resolves most issues and avoids paying subagent overhead for context you can fetch directly. Escalate to a single `Explore` agent only for genuinely open-ended discovery (e.g. "where does X live?" with no named files or an unfamiliar area of the codebase). Don't spawn more than one `Explore` agent per `/spec` run — if the issue needs more context than that, narrow the search instead of fanning out.
 
-| Issue Content | Agents | What to Spawn |
-|---------------|--------|---------------|
-| Database/SQL/migration keywords in AC or labels | 3 | Similar features + Codebase area + Database schema |
-| UI/frontend (`.tsx`/`.jsx`/`components/` references) | 2 | Similar features + Codebase area |
-| CLI/script changes | 2 | Similar features + Codebase area |
-| Docs/config/`simple-fix` label | 1 | General context only |
-
-**Execution mode:** Read `.sequant/settings.json` → `agents.parallel` (default: false).
-- **Parallel:** Spawn all agents in a SINGLE message
-- **Sequential:** Spawn one at a time, waiting for each to complete
-
-Agent prompts MUST reference discovered paths from the step above, not hardcoded ones like `components/admin/` or `lib/queries/`.
+Whichever path you take, reference discovered paths from the step above in searches, not hardcoded ones like `components/admin/` or `lib/queries/`.
 
 ### In-Flight Work Analysis
 
@@ -319,6 +324,8 @@ See [verification-criteria.md](references/verification-criteria.md) for detailed
 **Quality Loop:** [enabled/disabled]
 **Reasoning:** [Brief explanation]
 
+<!-- SEQUANT_SPEC: {"phases":["exec","qa"],"qualityLoop":false} -->
+
 <!-- Decision logic:
      - UI/frontend → add `test` phase
      - `no-browser-test` label → skip `test` (overrides UI labels)
@@ -327,6 +334,15 @@ See [verification-criteria.md](references/verification-criteria.md) for detailed
      - New features with Unit/Integration Test verification ACs → add `testgen` phase
      - Docs-only → skip spec, just exec → qa -->
 
+**Emit the `SEQUANT_SPEC` marker with the real resolved values** — `phases`
+is the same list shown in `**Phases:**` above, minus `spec` (it already
+ran); `qualityLoop` mirrors `**Quality Loop:**`. This is the durable
+resolution channel `sequant run` reads first (#921) — `**Phases:**` prose
+and spec's own chat output are both fallbacks for when this marker is
+missing or fails validation, so an omitted or stale marker silently
+downgrades which phases actually run. It MUST be included in the comment
+actually posted via `gh issue comment`, not just shown in this response.
+
 ---
 
 ## Label Review

package/templates/skills/spec/references/recommended-workflow.md

@@ -1,6 +1,17 @@
 # Recommended Workflow Format
 
-This document shows the expected output format for the `## Recommended Workflow` section in `/spec` output. The `parseRecommendedWorkflow()` function parses this format to determine which phases to execute.
+This document shows the expected output format for the `## Recommended Workflow` section in `/spec` output.
+
+## Resolution chain (#921)
+
+`sequant run` resolves phases through an ordered chain, not `parseRecommendedWorkflow()` alone:
+
+1. **`SEQUANT_SPEC` marker** — a structured HTML comment in the posted plan comment, e.g. `<!-- SEQUANT_SPEC: {"phases":["testgen","exec","qa"],"qualityLoop":true} -->`. This is the primary, durable channel — always emit it alongside the prose section below.
+2. **Comment prose** — `parseRecommendedWorkflow()` applied to the plan comment body (same format as this doc).
+3. **Chat text** — the same parser applied to the spec agent's chat output. Nondeterministic: only present if the agent happens to restate the section in chat rather than posting via a body file (#814).
+4. **Label fallback** — `detectPhasesFromLabels()`. Can never produce `testgen` or `security-review`.
+
+The marker's `phases` array excludes `spec` (it already ran) and must name only registered phases — an unknown phase name invalidates the whole marker and falls through to step 2.
 
 ## Format
 
@@ -10,6 +21,8 @@ This document shows the expected output format for the `## Recommended Workflow`
 **Phases:** spec → exec → qa
 **Quality Loop:** disabled
 **Reasoning:** Brief explanation of why this workflow was chosen.
+
+<!-- SEQUANT_SPEC: {"phases":["exec","qa"],"qualityLoop":false} -->
 ```
 
 ## Examples

package/templates/skills/testgen/SKILL.md

@@ -6,6 +6,7 @@ metadata:
   author: sequant
   version: "1.0"
 allowed-tools:
+  - Bash(npx sequant worktree:*)
   - Read
   - Write
   - Edit
@@ -530,17 +531,33 @@ If an AC has verification method "N/A - Trivial", skip test generation and note
 
 ### Step 4: Locate Feature Worktree
 
-If generating file-based tests (Unit Test, Integration Test), find the worktree:
+If generating file-based tests (Unit Test, Integration Test), find the worktree.
 
-```bash
-git worktree list | grep -E "feature.*<issue-number>" || true
-```
+<!-- BEGIN: worktree-standalone-lookup (#899) -->
+
+Resolve it through git, not the filesystem:
 
-Or check:
 ```bash
-ls ../worktrees/feature/<issue-number>-*/
+WORKTREE="$(npx sequant worktree resolve <issue-number>)" || {
+  echo "❌ HALT: no worktree for #<issue-number> in this repository."
+  exit 1
+}
+cd "$WORKTREE"
 ```
 
+`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 the directory name.
+
+**Do not glob `../worktrees/feature/<issue-number>-*`, and do not grep
+`git worktree list` for the issue number.** The first matches across sibling
+repositories, which share that directory; the second matches the printed path,
+so it keys on the directory slug — and a slug can drift from its own branch
+after a rename. Because this skill **writes test files**, landing in the wrong
+tree scatters stubs into an unrelated project.
+
+<!-- END: worktree-standalone-lookup (#899) -->
+
 Create test directories if needed:
 ```bash
 mkdir -p __tests__/integration

package/templates/agents/sequant-explorer.md

@@ -1,24 +0,0 @@
----
-name: sequant-explorer
-description: Codebase exploration agent for sequant /spec phase. Searches for existing patterns, components, database schemas, and file structures. Use when gathering context before planning a feature implementation.
-# Note: per anthropics/claude-code#43869 this is currently a no-op; agent runs on parent's model
-model: haiku
-maxTurns: 15
-tools:
-  - Read
-  - Grep
-  - Glob
----
-
-You are an exploration agent for the sequant development workflow.
-
-Your job is to search the codebase for existing patterns, components, and structures relevant to a planned feature.
-
-Rules:
-- Search thoroughly across relevant directories
-- Report findings in structured format: file paths, patterns discovered, recommendations
-- Do NOT modify any files
-- Do NOT run shell commands
-- Send results back via SendMessage when complete
-- All grep commands must use `|| true` to prevent exit code 1 on zero matches
-- Focus on actionable findings that inform implementation decisions