sequant 2.4.0 → 2.6.0

package/dist/marketplace/external_plugins/sequant/skills/spec/references/parallel-groups.md

@@ -25,6 +25,13 @@ When the implementation involves 3+ independent tasks that could be parallelized
 
 ## Model Selection
 
+> **Note:** Per anthropics/claude-code#43869, the `[model: ...]` annotation
+> below and the `model=` parameter `/exec` passes to `Agent(...)` are currently
+> ignored — every spawned subagent inherits the parent session's model. The
+> guidance here reflects the *intended* tier for each task once upstream fixes
+> ship; the parser in `exec/SKILL.md` is kept intact so it reactivates
+> automatically.
+
 Include a `[model: haiku]` or `[model: sonnet]` annotation at the end of each task line:
 
 | Task Type | Recommended Model |

package/dist/marketplace/external_plugins/sequant/skills/spec/references/quality-checklist.md

@@ -0,0 +1,75 @@
+# Feature Quality Planning — Full Checklist
+
+Use this checklist for **Complex** tier issues or when the exception-based summary in SKILL.md flags significant gaps. For Simple/Standard tiers, the exception-based approach in the main prompt is sufficient.
+
+## Section Applicability
+
+| Issue Type | Sections Required |
+|------------|-------------------|
+| Bug fix | Completeness, Error Handling, Test Coverage |
+| New feature | All sections |
+| Refactor | Completeness, Code Quality, Test Coverage |
+| UI change | All sections including Polish |
+| Backend/API | Completeness, Error Handling, Code Quality, Test Coverage, Best Practices |
+| CLI/Script | Completeness, Error Handling, Test Coverage, Best Practices |
+| Docs only | Completeness only |
+
+## Completeness Check
+
+- [ ] All AC items have corresponding implementation steps
+- [ ] Integration points with existing features identified
+- [ ] No partial implementations or TODOs planned
+- [ ] State management considered (if applicable)
+- [ ] Data flow is complete end-to-end
+
+## Error Handling
+
+- [ ] Invalid input scenarios identified
+- [ ] API/external service failures handled
+- [ ] Edge cases documented (empty, null, max values)
+- [ ] Error messages are user-friendly
+- [ ] Graceful degradation planned
+
+## Code Quality
+
+- [ ] Types fully defined (no `any` planned)
+- [ ] Follows existing patterns in codebase
+- [ ] Error boundaries where needed
+- [ ] No magic strings/numbers
+- [ ] Consistent naming conventions
+
+## Test Coverage Plan
+
+- [ ] Unit tests for business logic
+- [ ] Integration tests for data flow
+- [ ] Edge case tests identified
+- [ ] Mocking strategy appropriate
+- [ ] Critical paths have test coverage
+
+## Best Practices
+
+- [ ] Logging for debugging/observability
+- [ ] Accessibility considerations (if UI)
+- [ ] Performance implications considered
+- [ ] Security reviewed (auth, validation, sanitization)
+- [ ] Documentation updated (if behavior changes)
+
+## Polish (UI features only)
+
+- [ ] Loading states planned
+- [ ] Error states have UI
+- [ ] Empty states handled
+- [ ] Responsive design considered
+- [ ] Keyboard navigation works
+
+## Derived ACs
+
+Based on quality planning, identify additional ACs:
+
+| Source | Derived AC | Priority |
+|--------|-----------|----------|
+| Error Handling | AC-N: Handle [specific error] with [specific response] | High/Medium/Low |
+| Test Coverage | AC-N+1: Add tests for [specific scenario] | High/Medium/Low |
+| Best Practices | AC-N+2: Add logging for [specific operation] | High/Medium/Low |
+
+Derived ACs are numbered sequentially after original ACs.

package/dist/marketplace/external_plugins/sequant/skills/spec/references/recommended-workflow.md

@@ -14,16 +14,18 @@ This document shows the expected output format for the `## Recommended Workflow`
 
 ## Examples
 
-### Simple Bug Fix
+### Simple Bug Fix (spec confirms straightforward scope)
 
 ```markdown
 ## Recommended Workflow
 
 **Phases:** exec → qa
 **Quality Loop:** disabled
-**Reasoning:** Straightforward bug fix with clear root cause. No planning needed.
+**Reasoning:** This spec pass confirmed a clear root cause and narrow scope — no testgen or additional phases required; proceed to exec.
 ```
 
+*Note:* Since #533, spec always runs by default. `**Phases:**` lists phases **after** spec — use `exec → qa` here to indicate "spec is done; only exec and qa remain."
+
 ### Standard Feature
 
 ```markdown

package/dist/marketplace/external_plugins/sequant/skills/test/SKILL.md

@@ -805,33 +805,6 @@ Both can be used together:
 
 ---
 
-## State Tracking
-
-**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
-
-### State Updates (Standalone Only)
-
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
-
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> test
-```
-
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> test
-```
-
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> test "X/Y tests failed"
-```
-
-**Why this matters:** State tracking enables dashboard visibility, resume capability, and workflow orchestration. Skills update state when standalone; orchestrators handle state when running workflows.
-
----
-
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/dist/marketplace/external_plugins/sequant/skills/testgen/SKILL.md

@@ -39,9 +39,16 @@ When invoked as `/testgen <issue-number>`, your job is to:
 - `/testgen 123` - Generate test stubs for issue #123 based on /spec comment
 - `/testgen` - Generate stubs for the most recently discussed issue in conversation
 
-## Token Optimization with Haiku Sub-Agents
+## Sub-Agent Delegation for Stub Generation
 
-**Purpose:** Test stub generation is highly mechanical and benefits from using haiku sub-agents to minimize token cost.
+**Purpose:** Test stub generation is highly mechanical and is delegated to `sequant-testgen` so the main agent focuses on orchestration.
+
+> **Upstream caveat:** `sequant-testgen` declares `model: haiku`, but per
+> anthropics/claude-code#43869 that declaration is currently ignored — the
+> subagent inherits the parent session's model. Older versions of this doc
+> claimed concrete token-cost savings from haiku. Those numbers are not
+> achievable until the upstream fix ships; treat the haiku claim as the
+> *intended* tier, not the runtime one.
 
 **Pattern:** Use `Agent(subagent_type="sequant-testgen")` for:
 1. Parsing verification criteria from /spec comments
@@ -49,13 +56,12 @@ When invoked as `/testgen <issue-number>`, your job is to:
 3. Writing test file content
 
 **Benefits:**
-- 90% token cost reduction for mechanical generation
-- Faster execution for templated operations
-- Main agent focuses on orchestration and decisions
+- Main agent focuses on orchestration and decisions, not stub templating
+- Designated tier (`haiku`) will yield token savings once anthropics/claude-code#43869 is fixed; today subagents inherit the parent's model
 
 ### Sub-Agent Usage
 
-**Step 1: Parse Verification Criteria (use haiku)**
+**Step 1: Parse Verification Criteria (designated haiku — currently inert per anthropics/claude-code#43869)**
 
 ```javascript
 Agent(subagent_type="sequant-testgen", prompt=`
@@ -87,7 +93,7 @@ ${specComment}
 `)
 ```
 
-**Step 2: Generate Test Stubs (use haiku for each AC)**
+**Step 2: Generate Test Stubs (designated haiku — currently inert per anthropics/claude-code#43869)**
 
 ```javascript
 // For each AC with Unit Test or Integration Test verification method
@@ -122,16 +128,16 @@ The main agent handles file operations to ensure proper coordination:
 
 | Task | Agent | Reasoning |
 |------|-------|-----------|
-| Parse /spec comment | haiku | Mechanical text extraction |
-| Generate test stub code | haiku | Templated generation |
-| Identify failure scenarios | haiku | Pattern matching |
+| Parse /spec comment | `sequant-testgen` (declared haiku, inert per #43869) | Mechanical text extraction |
+| Generate test stub code | `sequant-testgen` (declared haiku, inert per #43869) | Templated generation |
+| Identify failure scenarios | `sequant-testgen` (declared haiku, inert per #43869) | Pattern matching |
 | Decide file locations | main | Requires codebase context |
 | Write files | main | File system coordination |
 | Post GitHub comment | main | Session context needed |
 
 ### Parallel Sub-Agent Execution
 
-When multiple ACs need test stubs, spawn haiku agents in parallel:
+When multiple ACs need test stubs, spawn `sequant-testgen` agents in parallel (declared haiku tier, currently inert per anthropics/claude-code#43869):
 
 ```javascript
 // Spawn all stub generation agents in a single message
@@ -143,11 +149,12 @@ const stubPromises = criteria
 // Main agent writes all files
 ```
 
-**Cost savings example:**
-- 5 AC items with Unit Test verification
-- Without haiku: ~50K tokens (main agent generates all)
-- With haiku: ~5K tokens (main orchestrates, haiku generates)
-- Savings: ~90%
+**Cost savings (when upstream lands):**
+Once anthropics/claude-code#43869 is fixed and the declared haiku tier takes
+effect, delegating mechanical stub generation to `sequant-testgen` will
+substantially reduce token cost vs. having the main agent generate every stub.
+Concrete savings are not measured here because the declaration is currently
+inert.
 
 ## Workflow
 
@@ -626,7 +633,7 @@ Cannot generate test files - no feature worktree exists for Issue #<N>.
 
 **Options:**
 1. Run `/exec <issue>` first (creates worktree automatically)
-2. Create worktree manually: `./scripts/dev/new-feature.sh <issue>`
+2. Create worktree manually: `./scripts/new-feature.sh <issue>`
 3. Use the browser/manual test scenarios from this comment
 ```
 
@@ -672,33 +679,6 @@ Generated with [Claude Code](https://claude.com/claude-code)
 
 ---
 
-## State Tracking
-
-**IMPORTANT:** Update workflow state when running standalone (not orchestrated).
-
-### State Updates (Standalone Only)
-
-When NOT orchestrated (`SEQUANT_ORCHESTRATOR` is not set):
-
-**At skill start:**
-```bash
-npx tsx scripts/state/update.ts start <issue-number> testgen
-```
-
-**On successful completion:**
-```bash
-npx tsx scripts/state/update.ts complete <issue-number> testgen
-```
-
-**On failure:**
-```bash
-npx tsx scripts/state/update.ts fail <issue-number> testgen "Failed to generate test stubs"
-```
-
-**Note:** `/testgen` is an optional skill that generates test stubs. State tracking is informational - it doesn't block subsequent phases.
-
----
-
 ## Output Verification
 
 **Before responding, verify your output includes ALL of these:**

package/dist/src/commands/ready-tui-adapter.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Single-issue snapshot adapter for `sequant ready` (#699 Part A).
+ *
+ * The Ink TUI is pull-based: `App` polls `getSnapshot(): RunSnapshot` at 10 Hz
+ * (see `src/ui/tui/index.ts`). But `ready` has no `RunOrchestrator` — its
+ * progress arrives push-style via the gate's `onProgress` hook (#697). This
+ * adapter bridges the two: a small mutable tracker the gate feeds, exposing a
+ * `getSnapshot()` that returns a one-issue `RunSnapshot` for the TUI to mount.
+ *
+ * The gate fires `start`/`complete`/`failed` around each `qa`/`loop` pass; we
+ * model those passes as the phase row, with a coarse `nowLine`
+ * (`formatCoarseNowLine`) — no agent-stream enrichment (a stated Non-Goal).
+ */
+import type { ProgressCallback } from "../lib/workflow/types.js";
+import { type RunSnapshot } from "../lib/workflow/run-state.js";
+export interface ReadySnapshotAdapterOptions {
+    issueNumber: number;
+    title: string;
+    branch: string;
+    /** Surfaced in the snapshot config header; `ready` always loops. */
+    qualityLoop?: boolean;
+}
+/**
+ * Mutable single-issue runtime tracker that doubles as a TUI snapshot provider.
+ *
+ * Lifecycle: construct → mount `renderTui(adapter)` → pass `adapter.onProgress`
+ * to the gate → on gate resolution call `markDone(ready)` so the polling `App`
+ * sees `done` and unmounts.
+ */
+export declare class ReadySnapshotAdapter {
+    private readonly issueNumber;
+    private readonly title;
+    private readonly branch;
+    private readonly qualityLoop;
+    private status;
+    private readonly phases;
+    private currentPhase;
+    private startedAt;
+    private completedAt;
+    private finished;
+    constructor(opts: ReadySnapshotAdapterOptions);
+    /**
+     * `ProgressCallback`-shaped sink wired into the gate's `onProgress`.
+     *
+     * - `start`    → append a running phase + set `currentPhase` (coarse nowLine).
+     * - `complete` → mark the active phase done, record elapsed, clear nowLine.
+     * - `failed`   → mark the active phase failed, flip issue status to failed.
+     * - `activity` → refresh the activity stamp / nowLine if a finer signal lands.
+     */
+    readonly onProgress: ProgressCallback;
+    /**
+     * Mark the run finished after `runReadyGate` resolves. Flips the snapshot's
+     * `done` flag so the polling `App` unmounts, and sets a terminal status
+     * (failed wins if a phase already failed).
+     */
+    markDone(ready: boolean): void;
+    /** Pull-based snapshot consumed by the TUI's 10 Hz poll loop. */
+    getSnapshot(): RunSnapshot;
+}

package/dist/src/commands/ready-tui-adapter.js

@@ -0,0 +1,130 @@
+/**
+ * Single-issue snapshot adapter for `sequant ready` (#699 Part A).
+ *
+ * The Ink TUI is pull-based: `App` polls `getSnapshot(): RunSnapshot` at 10 Hz
+ * (see `src/ui/tui/index.ts`). But `ready` has no `RunOrchestrator` — its
+ * progress arrives push-style via the gate's `onProgress` hook (#697). This
+ * adapter bridges the two: a small mutable tracker the gate feeds, exposing a
+ * `getSnapshot()` that returns a one-issue `RunSnapshot` for the TUI to mount.
+ *
+ * The gate fires `start`/`complete`/`failed` around each `qa`/`loop` pass; we
+ * model those passes as the phase row, with a coarse `nowLine`
+ * (`formatCoarseNowLine`) — no agent-stream enrichment (a stated Non-Goal).
+ */
+import { formatCoarseNowLine, } from "../lib/workflow/run-state.js";
+/**
+ * Mutable single-issue runtime tracker that doubles as a TUI snapshot provider.
+ *
+ * Lifecycle: construct → mount `renderTui(adapter)` → pass `adapter.onProgress`
+ * to the gate → on gate resolution call `markDone(ready)` so the polling `App`
+ * sees `done` and unmounts.
+ */
+export class ReadySnapshotAdapter {
+    issueNumber;
+    title;
+    branch;
+    qualityLoop;
+    status = "queued";
+    phases = [];
+    currentPhase;
+    startedAt;
+    completedAt;
+    finished = false;
+    constructor(opts) {
+        this.issueNumber = opts.issueNumber;
+        this.title = opts.title;
+        this.branch = opts.branch;
+        this.qualityLoop = opts.qualityLoop ?? true;
+    }
+    /**
+     * `ProgressCallback`-shaped sink wired into the gate's `onProgress`.
+     *
+     * - `start`    → append a running phase + set `currentPhase` (coarse nowLine).
+     * - `complete` → mark the active phase done, record elapsed, clear nowLine.
+     * - `failed`   → mark the active phase failed, flip issue status to failed.
+     * - `activity` → refresh the activity stamp / nowLine if a finer signal lands.
+     */
+    onProgress = (_issue, phase, event, extra) => {
+        const now = new Date();
+        switch (event) {
+            case "start": {
+                if (!this.startedAt)
+                    this.startedAt = now;
+                this.status = "running";
+                this.phases.push({ name: phase, status: "running", startedAt: now });
+                this.currentPhase = {
+                    name: phase,
+                    startedAt: now,
+                    lastActivityAt: now,
+                    nowLine: formatCoarseNowLine(phase),
+                };
+                break;
+            }
+            case "complete":
+            case "failed": {
+                const active = this.phases[this.phases.length - 1];
+                if (active && active.status === "running") {
+                    active.status = event === "failed" ? "failed" : "done";
+                    active.elapsedMs =
+                        extra?.durationSeconds != null
+                            ? Math.round(extra.durationSeconds * 1000)
+                            : active.startedAt
+                                ? now.getTime() - active.startedAt.getTime()
+                                : undefined;
+                }
+                this.currentPhase = undefined;
+                if (event === "failed")
+                    this.status = "failed";
+                break;
+            }
+            case "activity": {
+                if (this.currentPhase) {
+                    this.currentPhase = {
+                        ...this.currentPhase,
+                        lastActivityAt: now,
+                        nowLine: extra?.text?.trim()
+                            ? extra.text.trim()
+                            : this.currentPhase.nowLine,
+                    };
+                }
+                break;
+            }
+        }
+    };
+    /**
+     * Mark the run finished after `runReadyGate` resolves. Flips the snapshot's
+     * `done` flag so the polling `App` unmounts, and sets a terminal status
+     * (failed wins if a phase already failed).
+     */
+    markDone(ready) {
+        this.completedAt = new Date();
+        this.currentPhase = undefined;
+        if (this.status !== "failed") {
+            this.status = ready ? "passed" : "failed";
+        }
+        this.finished = true;
+    }
+    /** Pull-based snapshot consumed by the TUI's 10 Hz poll loop. */
+    getSnapshot() {
+        const issue = {
+            number: this.issueNumber,
+            title: this.title,
+            branch: this.branch,
+            status: this.status,
+            phases: this.phases.map((p) => ({ ...p })),
+            currentPhase: this.currentPhase ? { ...this.currentPhase } : undefined,
+            startedAt: this.startedAt,
+            completedAt: this.completedAt,
+        };
+        return {
+            config: {
+                concurrency: 1,
+                baseBranch: this.branch,
+                qualityLoop: this.qualityLoop,
+            },
+            issues: [issue],
+            done: this.finished,
+            capturedAt: new Date(),
+        };
+    }
+}

package/dist/src/commands/ready.d.ts

@@ -0,0 +1,49 @@
+/**
+ * sequant ready <issue> — post-resolve A+ QA gate (#683)
+ *
+ * Runs a full-weight `qa → loop → qa` pipeline against an issue's existing
+ * worktree, reproducing the maintainer's manual fresh-session A+ pass
+ * deterministically, then STOPS at a human merge gate. It NEVER merges.
+ *
+ * Gate policy (flag > settings.ready.policy > "ac"):
+ * - `ac`    (default) — loop until ACs are objectively met; report (not fix)
+ *                        quality gaps and Non-Goal-touching findings.
+ * - `a-plus` (opt-in)  — loop toward READY_FOR_MERGE, auto-fixing quality gaps.
+ *
+ * Terminates in `waiting_for_human_merge` (when ready) or `blocked` (needs
+ * human / no implementation), persists that state, and emits a structured gap
+ * report. See `src/lib/workflow/ready-gate.ts` for the engine.
+ */
+import { type ReadyPolicy } from "../lib/settings.js";
+import { type ReadyResult } from "../lib/workflow/ready-gate.js";
+export interface ReadyCommandOptions {
+    policy?: string;
+    maxIterations?: number;
+    budget?: number;
+    timeout?: number;
+    /** Commander surfaces `--no-mcp` as `mcp === false`. */
+    mcp?: boolean;
+    json?: boolean;
+    verbose?: boolean;
+}
+/**
+ * Exit code from a ready result.
+ * - 0: ready (awaiting human merge)
+ * - 1: not ready — needs human intervention (budget/iterations/stagnation)
+ * - 2: not ready — no implementation (#534) or hard error
+ */
+export declare function getReadyExitCode(result: ReadyResult): number;
+/**
+ * Resolve the gate policy: `--policy` flag > settings.ready.policy > "ac".
+ * Invalid flag values fall back to the settings/default value.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolvePolicy(flag: string | undefined, settingsPolicy: ReadyPolicy): ReadyPolicy;
+/**
+ * Locate the worktree path for an issue from `git worktree list`.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function resolveWorktreePath(issueNumber: number): string | null;
+export declare function readyCommand(issueArg: string, options: ReadyCommandOptions): Promise<void>;