sequant 2.10.0 → 2.12.0

package/dist/marketplace/external_plugins/sequant/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/dist/marketplace/external_plugins/sequant/skills/test/SKILL.md

@@ -582,7 +582,7 @@ Create structured test results:
 ### 3.2 GitHub Comment
 
 **If orchestrated (SEQUANT_ORCHESTRATOR is set):**
-- Skip posting GitHub comment (orchestrator handles summary)
+- Skip posting this skill's own GitHub comment — no per-phase comment is posted under `sequant run`; test results surface through the run summary and the PR body (#964)
 - Include test summary in output for orchestrator to capture
 - Let orchestrator aggregate results across phases
 

package/dist/marketplace/external_plugins/sequant/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/dist/src/commands/doctor.js

@@ -8,7 +8,8 @@ import { GitHubProvider } from "../lib/workflow/platforms/github.js";
 import { fileExists, isExecutable } from "../lib/fs.js";
 import { checkSkillsInstalled } from "../lib/skills-check.js";
 import { getManifest } from "../lib/manifest.js";
-import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, getMcpServersConfig, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { commandExists, isGhAuthenticated, isNativeWindows, isWSL, checkOptionalMcpServers, OPTIONAL_MCP_SERVERS, } from "../lib/system.js";
+import { getPhaseMcpServersConfig } from "../lib/mcp-config.js";
 import { getSettings, DEFAULT_AGENT_SETTINGS } from "../lib/settings.js";
 import { checkVersionThorough, getVersionWarning, resolveCliInvocation, } from "../lib/version-check.js";
 import { areSkillsOutdated } from "./sync.js";
@@ -435,23 +436,24 @@ export async function doctorCommand(options = {}) {
             message: "No optional MCPs configured (Sequant works without them, but they enhance functionality)",
         });
     }
-    // Check: MCP availability for headless mode (sequant run)
-    const mcpServersConfig = getMcpServersConfig();
-    if (mcpServersConfig) {
-        const serverCount = Object.keys(mcpServersConfig).length;
-        checks.push({
-            name: "MCP Servers (headless)",
-            status: "pass",
-            message: `Available for sequant run (${serverCount} server${serverCount !== 1 ? "s" : ""} configured)`,
-        });
-    }
-    else {
-        checks.push({
-            name: "MCP Servers (headless)",
-            status: "warn",
-            message: "Not available for sequant run (no Claude Desktop config found or empty mcpServers)",
-        });
-    }
+    // Check: MCP availability for headless mode (sequant run) (#936)
+    //
+    // Phase agents read the project's .mcp.json + settings.run.mcpAllowlist,
+    // never Claude Desktop config wholesale — see getPhaseMcpServersConfig.
+    // The sequant server is always guaranteed, so this check reports what a
+    // phase will actually receive rather than pass/warn on presence.
+    const phaseServersConfig = getPhaseMcpServersConfig(process.cwd(), {
+        desktopAllowlist: settings.run.mcpAllowlist,
+    });
+    const phaseServerCount = Object.keys(phaseServersConfig).length;
+    const extraServerCount = phaseServerCount - 1; // minus the guaranteed sequant entry
+    checks.push({
+        name: "MCP Servers (headless)",
+        status: "pass",
+        message: extraServerCount > 0
+            ? `Available for sequant run (${phaseServerCount} servers: sequant + ${extraServerCount} from .mcp.json${settings.run.mcpAllowlist?.length ? "/mcpAllowlist" : ""})`
+            : "Available for sequant run (sequant only — add servers to .mcp.json, or settings.run.mcpAllowlist for desktop servers, for more)",
+    });
     // Check: Sequant MCP server health
     try {
         // Verify MCP server can be created (validates SDK availability)

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

@@ -1,5 +1,6 @@
 /**
- * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625) and
+ * the checkout-scoped lock (#901).
  */
 export interface LocksListOptions {
     json?: boolean;
@@ -26,6 +27,24 @@ export interface LocksCheckBatchOptions {
 }
 /** `sequant locks list` — print every active lock with staleness metadata. */
 export declare function locksListCommand(options?: LocksListOptions): Promise<void>;
+export interface LocksCheckoutOptions {
+    issue?: string;
+    command?: string;
+    sessionId?: string;
+    skipPidCheck?: boolean;
+    force?: boolean;
+    json?: boolean;
+}
+/**
+ * `sequant locks checkout <acquire|release|check|clear>` — the working-tree
+ * lock (#901).
+ *
+ * Exit codes mirror the per-issue commands:
+ *   0 — success (acquired / released / free / cleared / nothing to release)
+ *   1 — held by another session, or refused
+ *   2 — invalid arguments
+ */
+export declare function locksCheckoutCommand(action: string, options?: LocksCheckoutOptions): Promise<void>;
 /**
  * `sequant locks clear <issue>` — remove a lock manually.
  * By default refuses to clear a fresh same-host lock whose PID is alive;

package/dist/src/commands/locks.js

@@ -1,8 +1,9 @@
 /**
- * `sequant locks` — inspect and clear per-issue concurrency locks (#625).
+ * `sequant locks` — inspect and clear per-issue concurrency locks (#625) and
+ * the checkout-scoped lock (#901).
  */
 import chalk from "chalk";
-import { LockManager, formatLockedMessage, } from "../lib/locks/index.js";
+import { CheckoutLock, LockManager, describeCheckoutHolderIssue, formatCheckoutLockedMessage, formatLockedMessage, } from "../lib/locks/index.js";
 /** Human-readable line for the `--signal-other` log output (#637). */
 function formatSignalLine(issue, pid, result) {
     switch (result.reason) {
@@ -44,14 +45,35 @@ export async function locksListCommand(options = {}) {
         return;
     }
     const listings = manager.list();
+    // The checkout lock lives in the same directory but is deliberately not a
+    // numeric filename, so `manager.list()` skips it (#901). Query it separately
+    // rather than widening the numeric key everywhere.
+    const checkout = new CheckoutLock().listing();
     if (options.json) {
-        console.log(JSON.stringify({ locks: listings }, null, 2));
+        console.log(JSON.stringify({ locks: listings, checkout }, null, 2));
         return;
     }
-    if (listings.length === 0) {
+    if (listings.length === 0 && !checkout) {
         console.log(chalk.gray("No active locks."));
         return;
     }
+    if (checkout) {
+        const ageMinutes = Math.floor(checkout.ageMs / 60_000);
+        const staleTag = checkout.stale
+            ? chalk.yellow(`  (stale: ${checkout.staleReason})`)
+            : "";
+        console.log(chalk.bold("Checkout lock (whole working tree):"));
+        console.log(`  issue=${describeCheckoutHolderIssue(checkout.holder.issue)}  ` +
+            `pid=${checkout.holder.pid}  ` +
+            `host=${checkout.holder.hostname}  age=${ageMinutes}m  ` +
+            `started=${checkout.holder.startedAt}${staleTag}`);
+        console.log(`    command: ${checkout.holder.command}`);
+        console.log("");
+    }
+    if (listings.length === 0) {
+        console.log(chalk.gray("No active per-issue locks."));
+        return;
+    }
     console.log(chalk.bold(`Active locks (${listings.length}):`));
     console.log("");
     for (const l of listings) {
@@ -62,6 +84,186 @@ export async function locksListCommand(options = {}) {
         console.log(`    command: ${l.holder.command}`);
     }
 }
+/**
+ * Validate `--issue` for the checkout commands. Shared by `acquire` (where the
+ * flag is required) and `release` (where it is optional) so the two cannot
+ * drift on what counts as a valid issue.
+ *
+ * `Number.parseInt` + `Number.isInteger`, never a bare `Number(x)`:
+ * `Number(undefined)` is `NaN`, and `NaN !== undefined`, so a `NaN` would sail
+ * through the `issue !== undefined` guard in `isCheckoutOwner` and silently
+ * refuse every release instead of erroring here (#906).
+ */
+function parseCheckoutIssue(raw) {
+    const issue = Number.parseInt(raw, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${raw}`));
+        process.exitCode = 2;
+        return { ok: false };
+    }
+    return { ok: true, issue };
+}
+/**
+ * `sequant locks checkout <acquire|release|check|clear>` — the working-tree
+ * lock (#901).
+ *
+ * Exit codes mirror the per-issue commands:
+ *   0 — success (acquired / released / free / cleared / nothing to release)
+ *   1 — held by another session, or refused
+ *   2 — invalid arguments
+ */
+export async function locksCheckoutCommand(action, options = {}) {
+    const lock = new CheckoutLock();
+    if (lock.isNoop) {
+        // AC-5: orchestrator/MCP mode is a no-op across the whole surface.
+        if (options.json) {
+            console.log(JSON.stringify({ action, orchestratorMode: true, ok: true }));
+        }
+        else {
+            console.log(chalk.gray("Lock operations are disabled (SEQUANT_ORCHESTRATOR set)."));
+        }
+        return;
+    }
+    switch (action) {
+        case "acquire": {
+            if (options.issue === undefined) {
+                console.error(chalk.red("`locks checkout acquire` requires --issue"));
+                process.exitCode = 2;
+                return;
+            }
+            const parsed = parseCheckoutIssue(options.issue);
+            if (!parsed.ok)
+                return;
+            const issue = parsed.issue;
+            const result = lock.acquire(issue, options.command ?? "unknown", {
+                sessionId: options.sessionId,
+                skipPidCheck: options.skipPidCheck,
+            });
+            if (result.acquired) {
+                if (options.json) {
+                    console.log(JSON.stringify({
+                        acquired: true,
+                        reentrant: result.reentrant,
+                        lockPath: result.lockPath,
+                    }));
+                }
+                else {
+                    console.log(chalk.green(result.reentrant
+                        ? `✓ Checkout already held by this session (#${issue})`
+                        : `✓ Acquired checkout lock for #${issue}`));
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (options.json) {
+                console.log(JSON.stringify({
+                    acquired: false,
+                    holder: result.holder,
+                    lockPath: result.lockPath,
+                }));
+            }
+            else {
+                console.error(chalk.yellow(formatCheckoutLockedMessage(result.holder, { issue })));
+            }
+            return;
+        }
+        case "release": {
+            // `--issue` is optional here, unlike `acquire`: a live process releasing
+            // its own lock is identified by PID. It is required in practice for
+            // skill shells, whose PID is already gone — see `isCheckoutOwner`.
+            let issue;
+            if (options.issue !== undefined) {
+                const parsed = parseCheckoutIssue(options.issue);
+                if (!parsed.ok)
+                    return;
+                issue = parsed.issue;
+            }
+            // Read the holder *before* releasing, so a refusal can name it.
+            const holder = lock.check();
+            const released = lock.release({
+                sessionId: options.sessionId,
+                ...lock.selfIdentity,
+                issue,
+            });
+            // Three outcomes, not two (#906). Before ownership was enforced,
+            // "released nothing" could only mean "nothing was held". It now also
+            // means "held, but not by you" — a real refusal, which must not print
+            // the same gray no-op line or exit 0.
+            if (options.json) {
+                console.log(JSON.stringify({
+                    released,
+                    refused: !released && holder !== null,
+                    ...(holder ? { holder } : {}),
+                }));
+                if (!released && holder)
+                    process.exitCode = 1;
+                return;
+            }
+            if (released) {
+                console.log(chalk.green("✓ Released checkout lock"));
+                return;
+            }
+            if (holder) {
+                process.exitCode = 1;
+                console.error(chalk.yellow(`Refusing to release the checkout lock — it belongs to the session working ${describeCheckoutHolderIssue(holder.issue)} ` +
+                    `(PID ${holder.pid} on ${holder.hostname}, started ${holder.startedAt}).\n` +
+                    (issue === undefined
+                        ? `You passed no --issue, so nothing identified you as the holder.\n` +
+                            `  • If you are that session: sequant locks checkout release --issue=${holder.issue}\n`
+                        : `You passed --issue=${issue}.\n`) +
+                    `  • If that session is gone: sequant locks checkout clear --force`));
+                return;
+            }
+            console.log(chalk.gray("No releasable checkout lock"));
+            return;
+        }
+        case "check": {
+            const holder = lock.check();
+            if (!holder) {
+                if (options.json) {
+                    console.log(JSON.stringify({ locked: false }));
+                }
+                else {
+                    console.log(chalk.gray("Checkout is not locked"));
+                }
+                return;
+            }
+            process.exitCode = 1;
+            if (options.json) {
+                console.log(JSON.stringify({ locked: true, holder }));
+            }
+            else {
+                console.log(chalk.yellow(formatCheckoutLockedMessage(holder)));
+            }
+            return;
+        }
+        case "clear": {
+            const result = lock.clear({ safetyCheck: !options.force });
+            if (options.json) {
+                console.log(JSON.stringify(result));
+                if (!result.cleared)
+                    process.exitCode = 1;
+                return;
+            }
+            if (result.cleared) {
+                console.log(chalk.green("✓ Cleared checkout lock"));
+                return;
+            }
+            process.exitCode = 1;
+            if (result.reason === "no-lock") {
+                console.log(chalk.gray("No checkout lock to clear"));
+                process.exitCode = 0;
+                return;
+            }
+            console.log(chalk.yellow("Refusing to clear a fresh checkout lock. " +
+                "Re-run with `sequant locks checkout clear --force` if you are sure the holder is gone."));
+            return;
+        }
+        default:
+            console.error(chalk.red(`Unknown action: ${action}. Expected acquire|release|check|clear.`));
+            process.exitCode = 2;
+    }
+}
 /**
  * `sequant locks clear <issue>` — remove a lock manually.
  * By default refuses to clear a fresh same-host lock whose PID is alive;

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

@@ -25,6 +25,12 @@ export interface ReadyCommandOptions {
     mcp?: boolean;
     json?: boolean;
     verbose?: boolean;
+    /** Per-phase model override (#914). See `RunOptions.models`. */
+    models?: string;
+    /** Per-phase effort override (#914). See `RunOptions.efforts`. */
+    efforts?: string;
+    /** Evidence-based effort escalation on QA-pass retries (#915). See `RunOptions.escalateEffort`. */
+    escalateEffort?: boolean;
 }
 /**
  * Exit code from a ready result.

package/dist/src/commands/ready.js

@@ -23,7 +23,8 @@ import { executePhaseWithRetry } from "../lib/workflow/phase-executor.js";
 import { buildProgressWiring } from "./run-progress.js";
 import { ReadySnapshotAdapter } from "./ready-tui-adapter.js";
 import { DEFAULT_CONFIG } from "../lib/workflow/types.js";
-import { positiveOr } from "../lib/workflow/config-resolver.js";
+import { positiveOr, resolvePhasePolicies, } from "../lib/workflow/config-resolver.js";
+import { getPhaseNames } from "../lib/workflow/phase-registry.js";
 import { runReadyGate, parseNonGoals, } from "../lib/workflow/ready-gate.js";
 /**
  * Exit code from a ready result.
@@ -106,6 +107,10 @@ export async function readyCommand(issueArg, options) {
     const policy = resolvePolicy(options.policy, settings.ready.policy);
     const { maxIterations, tokenBudget, phaseTimeout } = resolveReadyLimits(options, settings);
     const mcp = options.mcp !== false;
+    const phasePolicies = resolvePhasePolicies(options.models, options.efforts, settings.run.phases, getPhaseNames());
+    // #915: CLI > settings > default `false`, same precedence as the `run`
+    // path's `buildExecutionConfig` (config-resolver.ts).
+    const effortEscalation = options.escalateEffort ?? settings.run.effortEscalation ?? false;
     // Resolve the issue's existing worktree (reuses run/state worktree infra).
     const worktreePath = resolveWorktreePath(issueNumber);
     if (!worktreePath) {
@@ -195,9 +200,15 @@ export async function readyCommand(issueArg, options) {
             nonGoals,
             phaseTimeout,
             mcp,
+            mcpAllowlist: settings.run.mcpAllowlist,
             verbose: options.verbose,
             runPhase,
             onProgress,
+            phasePolicies,
+            effortEscalation,
+            // #937 AC-4: persist the final gap report so it survives the terminal
+            // closing (previously terminal-scrollback only under `ac` policy).
+            postReport: (body) => gh.postComment(String(issueNumber), body),
         });
     }
     catch (error) {
@@ -220,6 +231,13 @@ export async function readyCommand(issueArg, options) {
         process.exitCode = 2;
         return;
     }
+    // #915: surface any escalated qa/loop dispatches — the gate has no live
+    // print of its own (see `withEscalatedEffort` in `ready-gate.ts`).
+    if (options.verbose) {
+        for (const e of result.effortEscalations) {
+            console.log(colors.muted(`  effort: ${e.base} → ${e.escalated} (${e.phase} retry)`));
+        }
+    }
     // Persist the terminal state so `sequant status` reflects it (Derived AC).
     // Best-effort: initialize the issue in state if a prior run didn't track it.
     try {

package/dist/src/commands/run-display.js

@@ -90,6 +90,7 @@ function toIssueSummary(r) {
         loopTriggered: r.loopTriggered,
         prNumber: r.prNumber,
         prUrl: r.prUrl,
+        prSkippedReason: r.prSkippedReason,
     };
     if (!r.success) {
         // #879: a PR-creation failure has no failed phase — fall back to its error

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

@@ -0,0 +1,31 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+export interface WorktreeResolveOptions {
+    json?: boolean;
+}
+export interface WorktreeVerifyOptions {
+    issue?: string;
+    json?: boolean;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export declare function worktreeResolveCommand(issueArg: string, options?: WorktreeResolveOptions): Promise<void>;
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export declare function worktreeVerifyCommand(pathArg: string, options?: WorktreeVerifyOptions): Promise<void>;

package/dist/src/commands/worktree.js

@@ -0,0 +1,95 @@
+/**
+ * `sequant worktree` — repo-scoped worktree resolution for skill bodies (#899).
+ *
+ * `/fullsolve` uses `resolve` to turn an issue number into a real absolute
+ * path before exporting `SEQUANT_WORKTREE`; `/exec` uses `verify` to refuse a
+ * path that does not exist or belongs to another repository. Both fail closed:
+ * a non-zero exit means the caller must halt, not continue where it stands.
+ */
+import chalk from "chalk";
+import { resolveIssueWorktree, verifyWorktreePath, } from "../lib/workflow/worktree-resolver.js";
+function parseIssue(arg) {
+    const issue = Number.parseInt(arg, 10);
+    if (!Number.isInteger(issue) || issue <= 0) {
+        console.error(chalk.red(`Invalid issue number: ${arg}`));
+        process.exitCode = 2;
+        return null;
+    }
+    return issue;
+}
+/**
+ * `sequant worktree resolve <issue>` — print the absolute path of this
+ * repository's worktree for an issue.
+ *
+ * On success the path is the *only* thing written to stdout, so callers can
+ * capture it with `WT="$(sequant worktree resolve 123)"`. Everything else goes
+ * to stderr.
+ */
+export async function worktreeResolveCommand(issueArg, options = {}) {
+    const issue = parseIssue(issueArg);
+    if (issue === null)
+        return;
+    const result = resolveIssueWorktree(issue);
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                issue,
+                ok: false,
+                error: result.error,
+                message: result.message,
+                candidates: result.candidates,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({
+            issue,
+            ok: true,
+            path: result.path,
+            branch: result.branch,
+        }));
+        return;
+    }
+    // Bare path only — this is consumed by `$(...)` in skill bodies.
+    console.log(result.path);
+}
+/**
+ * `sequant worktree verify <path>` — confirm a path is a worktree of this
+ * repository (and, with `--issue`, that it belongs to that issue).
+ *
+ * Exit 1 with a named error is the signal for `/exec` to halt.
+ */
+export async function worktreeVerifyCommand(pathArg, options = {}) {
+    let issue;
+    if (options.issue !== undefined) {
+        const parsed = parseIssue(options.issue);
+        if (parsed === null)
+            return;
+        issue = parsed;
+    }
+    const result = verifyWorktreePath(pathArg, { issue });
+    if (!result.ok) {
+        process.exitCode = 1;
+        if (options.json) {
+            console.error(JSON.stringify({
+                ok: false,
+                error: result.error,
+                message: result.message,
+            }));
+        }
+        else {
+            console.error(chalk.red(result.message));
+        }
+        return;
+    }
+    if (options.json) {
+        console.log(JSON.stringify({ ok: true, path: result.path, branch: result.branch }));
+        return;
+    }
+    console.log(chalk.green(`✓ ${result.path} (${result.branch})`));
+}

package/dist/src/lib/ac-linter.js

@@ -272,6 +272,29 @@ function detectTitleBodyTension(ac) {
         suggestion: "Two verification bars detected. Either (a) tighten the title to match the runtime body (e.g., 'Smoke test execution — capture evidence'), or (b) split the runtime requirement into a separate AC.",
     };
 }
+/**
+ * Detect a test-type AC (unit/integration/browser) whose verification
+ * method came from keyword inference rather than a declared `Evidence:`
+ * clause (#938). `manual` ACs are exempt — docs/decision ACs legitimately
+ * have no runnable evidence.
+ *
+ * Warning-only, same convention as the regex-based DEFAULT_LINT_PATTERNS.
+ *
+ * @param ac - The acceptance criterion to check
+ * @returns A lint issue if evidence is missing, otherwise null
+ */
+function detectMissingEvidence(ac) {
+    if (ac.evidence)
+        return null;
+    if (ac.verificationMethod === "manual")
+        return null;
+    return {
+        type: "incomplete",
+        matchedPattern: ac.verificationMethod,
+        problem: `Incomplete: verification not named — method "${ac.verificationMethod}" was inferred from keywords, not declared`,
+        suggestion: "Add a trailing `Evidence:` clause naming the command or check that verifies this AC (e.g., `Evidence: \\`npm test -- foo\\``).",
+    };
+}
 /**
  * Lint a single acceptance criterion against all patterns
  *
@@ -296,6 +319,9 @@ export function lintAcceptanceCriterion(ac, patterns = DEFAULT_LINT_PATTERNS) {
     const tension = detectTitleBodyTension(ac);
     if (tension)
         issues.push(tension);
+    const missingEvidence = detectMissingEvidence(ac);
+    if (missingEvidence)
+        issues.push(missingEvidence);
     return {
         ac,
         issues,