sequant 2.12.0 → 2.13.0

package/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "sequant",
       "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Includes 17 skills, workflow MCP tools, and pre/post-tool hooks.",
-      "version": "2.12.0",
+      "version": "2.13.0",
       "author": {
         "name": "sequant-io",
         "email": "hello@sequant.io"

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/README.md

@@ -1,8 +1,8 @@
 # Sequant
 
-**Spec-driven AI coding agents — every acceptance criterion verified, stops at the human merge gate.**
+**AI coding agents that prove their work — every acceptance criterion verified, and you hold the merge button.**
 
-For teams that can't ship un-reviewed AI code. Solve GitHub issues with structured phases and quality gates — from issue to merge-ready PR.
+For developers who won't merge what they can't trust — solo or on a team. Solve GitHub issues with structured phases and quality gates, from issue to merge-ready PR.
 
 **[sequant.io](https://sequant.io)** — docs, guides, and getting started.
 
@@ -12,10 +12,17 @@ For teams that can't ship un-reviewed AI code. Solve GitHub issues with structur
 [![CI](https://github.com/sequant-io/sequant/actions/workflows/ci.yml/badge.svg)](https://github.com/sequant-io/sequant/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-AI coding agents write code well, but leave you to run the workflow around it — planning, isolation, review, and merge safety. Sequant wraps an agent in a structured **spec → exec → qa** pipeline with isolated git worktrees and quality gates, taking a GitHub issue from triage to a merge-ready PR without babysitting each step.
+AI coding agents write code well, but leave you to run the workflow around it — planning, isolation, review, and merge safety. Sequant wraps an agent in a structured **spec → exec → qa** pipeline with isolated git worktrees and quality gates, taking a GitHub issue from triage to a merge-ready PR without babysitting each step. The PR arrives with evidence — each acceptance criterion checked against the code — and the merge is always yours.
 
 See the [CHANGELOG](CHANGELOG.md) for release notes, or the [migration guide](CHANGELOG.md#migration-from-v1x) if upgrading from v1.x.
 
+### What's new in 2.13
+
+- **NEEDS_VERIFICATION verdicts stop blocking their own follow-up** — a QA verdict of NEEDS_VERIFICATION now maps to a dedicated `awaiting_verification` state instead of `ready_for_merge`, so after you execute the ACs the qa re-run just runs — no `--force`, no editing `state.json` by hand. The state shows up in `sequant status` and the dashboard with a re-run hint, and an issue whose PR you merge directly still sweeps to `merged`. MCP `sequant_run` also gains a real `force` parameter (previously silently ignored). The full verdict→state contract is documented in [qa-verdict-workflow-states.md](docs/features/qa-verdict-workflow-states.md) (#972).
+- **A bad model name is now a loud failure, not a silent no-op** — when a phase's session ends on an API error (e.g. a typo'd or roster-stale model string), the driver now fails the phase with the API error text and structured `terminal_reason`/`api_error_status` context, instead of reporting a zero-work "success" that only surfaced downstream as an empty diff entering QA (#973).
+- **Model roles: name the tier, not the model** — `run.modelRoles` maps semantic roles (defaults: `fast`, `strong`, `frontier`) to model strings, and phase policy or `--models` can reference them as `role:fast`. Raw model strings still pass through verbatim, a missing role fails loudly at config-resolution before any session spawns, and run metrics record both the requested value and the concrete model ID actually dispatched — so a roster change means editing one map, not every settings file (#975). `agents.model` now accepts any model string instead of a stale three-model enum.
+- **A constitution with teeth** — the constitution template is now the enforceable agent contract: its Definition of Done table is *generated* from `/qa`'s real gate list and drift-gated in CI (`lint:constitution-dod`), an AC authoring standard is cross-linked from `/spec`'s lint output, and every Boundaries/Budgets rule names its actual enforcing mechanism — a gate test asserts every cited settings key and hook path resolves. Customized constitutions are preserved by `update`/`sync`; the new template reaches fresh `init` projects only (#943).
+
 ### What's new in 2.12
 
 - **QA gates you can parse, not just read** — `/qa` now closes every review with a structured findings marker (six-category taxonomy, evidence, recommended action) that `/loop` and `sequant ready` consume directly, so a finding QA itself called non-blocking is never burned as a fix iteration (#937). Gate-test ACs must ship a machine-checkable `SEQUANT_MUTATION` record in the PR body, enforced by `/qa` (#939), and an AC can declare its own verification command via a trailing `Evidence:` clause that QA must actually execute (#938). A new advisory CI job annotates PRs with likely-vacuous tests (#940).
@@ -175,6 +182,17 @@ your-project/           # Main repo (stays on main branch)
 - Each issue has its own dependencies and build
 - Safe to discard failed experiments
 
+### Agent Contract
+
+Every project gets `.claude/memory/constitution.md` — the machine-enforceable agent contract that answers "what will the agent refuse to do, what must every PR satisfy, and where does it stop for me?":
+
+- **Definition of Done** — generated from `/qa`'s §7 gate list; a CI check (`lint:constitution-dod`) fails when the table drifts from the live gates. These are project-wide — issue ACs don't restate them.
+- **AC Authoring Standard** — the house format for writing ACs (single-line, `Evidence:`/`Risk:`/`Human decision` fields, Non-Goals); referenced by `/spec`'s lint warnings.
+- **Boundaries** — every rule names its enforcer: the force-push hook, the worktree-only editing guard, the mutation-verification gate.
+- **Budgets & Stop Conditions** — iteration caps, the human merge gate, hold states, and gap-prompt discipline.
+
+The file is a `CUSTOMIZABLE_FILES` entry: plain `sequant update` and `sync` preserve your edits. Only `--force` replaces it.
+
 ### Quality Gates
 
 Every `/qa` runs automated checks:
@@ -190,6 +208,19 @@ Every `/qa` runs automated checks:
 
 When checks fail, `/loop` automatically fixes and re-runs (up to 3x).
 
+### Thinking of building this on a graph framework?
+
+You could assemble this workflow yourself on LangGraph, CrewAI, Mastra, or the Claude Agent SDK — they sell the primitives and leave the workflow as an exercise. Sequant is the finished, hardened version of what you'd end up building, in the frameworks' own vocabulary:
+
+- **Isolated execution** — one git worktree per issue, resolved by the branch git reports rather than directory globs
+- **Human-in-the-loop approval gate** — the pipeline stops at the PR and never merges; this is an invariant, not optional wiring
+- **Guardrails** — QA verdicts with an enforced floor, mutation-verified gate tests, scope and security checks
+- **Durable execution** — a rate-limit halt writes a resumable record; `sequant resume` picks up where it left off, skipping completed phases
+- **State management** — per-issue and checkout-scoped locks, so concurrent sessions can't interleave git operations in the same tree
+- **Deterministic control flow** — dependency-ordered batch scheduling over `blocked by #N` relationships
+
+On a general framework, every one of these is something you wire up — and can wire wrong or skip. Here they hold for every run. The boring 80% (retries, resume, locking, exit codes your scripts can trust) has already been run in anger; the [CHANGELOG](CHANGELOG.md) is the receipts.
+
 ---
 
 ## Using Sequant

package/dist/dashboard/server.js

@@ -42,6 +42,8 @@ function getStatusClass(status) {
             return "primary";
         case "waiting_for_qa_gate":
             return "warning";
+        case "awaiting_verification":
+            return "warning";
         case "ready_for_merge":
             return "success";
         case "blocked":
@@ -347,6 +349,7 @@ function renderIssuesList(issues) {
         in_progress: [],
         waiting_for_qa_gate: [],
         waiting_for_human_merge: [],
+        awaiting_verification: [],
         ready_for_merge: [],
         blocked: [],
         not_started: [],
@@ -364,6 +367,7 @@ function renderIssuesList(issues) {
     const statusOrder = [
         "in_progress",
         "waiting_for_qa_gate",
+        "awaiting_verification",
         "ready_for_merge",
         "blocked",
         "not_started",

package/dist/marketplace/external_plugins/sequant/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
   "description": "AI coding agent orchestrator for Claude Code — resolve GitHub issues end-to-end with isolated git worktrees and quality gates, through spec → exec → qa phases.",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "author": {
     "name": "sequant-io",
     "email": "hello@sequant.io"

package/dist/marketplace/external_plugins/sequant/.mcp.json

@@ -1,6 +1,6 @@
 {
   "sequant": {
     "command": "npx",
-    "args": ["-y", "sequant@2.12.0", "serve"]
+    "args": ["-y", "sequant@2.13.0", "serve"]
   }
 }

package/dist/marketplace/external_plugins/sequant/README.md

@@ -75,6 +75,15 @@ sequant init
 - **Pre-tool guardrails** — blocks dangerous commands, enforces worktree safety
 - **Post-tool tracking** — timing, quality metrics, smart test runner
 
+### Agent Contract
+
+Every project gets `.claude/memory/constitution.md` — the machine-enforceable agent contract that answers "what must every PR satisfy, and where does the agent stop?":
+
+- **Definition of Done** — generated from `/qa`'s §7 gate list; a CI check fails on drift
+- **AC Authoring Standard** — the house format for ACs; referenced by `/spec`'s lint warnings
+- **Boundaries** — every rule names its enforcer (hook, gate, or settings key)
+- **Budgets & Stop Conditions** — iteration caps, the human merge gate, and hold states
+
 ## Quick Start
 
 ```

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

@@ -107,6 +107,8 @@ Mark tier in HTML comment for downstream parsing: `<!-- SEQUANT_SPEC_TIER: [tier
    | Open-ended | "etc.", "and more" | Scope undefined |
    | Title/body tension | doc-noun title ("note", "comment", "snippet") + runtime-imperative body ("execute", "trigger", "capture", incl. inflections like `triggered`/`captured`, `run /<cmd>`); separators `.`/`\n`/`:`/`—` | Two different verification bars |
 
+   > For the house AC format rules (single-line constraint, `Evidence:`/`Risk:`/`Human decision` fields, Non-Goals section), see the constitution's §2 AC Authoring Standard (`.claude/memory/constitution.md`).
+
 3. **Scope Assessment** (unless `--skip-scope-check`): Use `performScopeAssessment` from `./src/lib/scope/index.ts` with settings from `getSettings()`. Verdicts: SCOPE_OK (green), SCOPE_WARNING (yellow, auto-enables quality loop), SCOPE_SPLIT_RECOMMENDED (red). Store results in state.
 
 ### If guard fails (consumer projects):

package/dist/src/commands/ready.js

@@ -107,7 +107,9 @@ 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());
+    // #975: pass modelRoles + active driver so `role:` prefixes resolve,
+    // matching the same call in buildExecutionConfig (AC-5 drift guard).
+    const phasePolicies = resolvePhasePolicies(options.models, options.efforts, settings.run.phases, getPhaseNames(), settings.run.modelRoles, settings.run.agent ?? "claude-code");
     // #915: CLI > settings > default `false`, same precedence as the `run`
     // path's `buildExecutionConfig` (config-resolver.ts).
     const effortEscalation = options.escalateEffort ?? settings.run.effortEscalation ?? false;

package/dist/src/commands/status.js

@@ -69,6 +69,8 @@ function colorStatus(status, resolvedAt) {
             return chalk.yellow(status);
         case "waiting_for_human_merge":
             return chalk.green(status);
+        case "awaiting_verification":
+            return chalk.magenta(status);
         case "ready_for_merge":
             return chalk.green(status);
         case "merged":
@@ -171,6 +173,7 @@ function displayIssueSummary(issues) {
         in_progress: [],
         waiting_for_qa_gate: [],
         waiting_for_human_merge: [],
+        awaiting_verification: [],
         ready_for_merge: [],
         blocked: [],
         not_started: [],
@@ -184,6 +187,7 @@ function displayIssueSummary(issues) {
     const statusOrder = [
         "in_progress",
         "waiting_for_qa_gate",
+        "awaiting_verification",
         "waiting_for_human_merge",
         "ready_for_merge",
         "blocked",

package/dist/src/lib/settings.d.ts

@@ -40,14 +40,14 @@ export interface AgentSettings {
      */
     parallel: boolean;
     /**
-     * Default model for sub-agents.
-     * Options: "haiku" (cheapest), "sonnet" (balanced), "opus" (most capable)
+     * Default model for sub-agents (free string — any alias or dated ID accepted).
      * Default: "haiku" — currently inert per anthropics/claude-code#43869.
+     * See `run.modelRoles` for semantic role indirection (#975).
      * @deprecated currently inert; see anthropics/claude-code#43869. Subagents
      * inherit the parent session's model regardless of this value. Kept so
      * existing user settings.json files continue to parse without error.
      */
-    model: "haiku" | "sonnet" | "opus";
+    model: string;
     /**
      * Isolate parallel agent groups in separate worktrees.
      * When true, each agent in a parallel group gets its own sub-worktree,
@@ -64,6 +64,23 @@ export interface AgentSettings {
  * two validation points cannot drift apart on which values are accepted.
  */
 export declare const EFFORT_LEVELS: readonly ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Map of semantic role names to model strings, used by `run.modelRoles` (#975).
+ *
+ * A value is either:
+ * - a plain string shorthand — desugars to `{ "claude-code": value }` (claude-code driver only)
+ * - an object keyed by driver registry name, for cross-driver mappings
+ *
+ * Role references use a `role:` prefix in phase policy / ladder entries;
+ * bare strings pass through verbatim (AC-3 backward compat).
+ */
+export declare const ModelRolesSchema: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>;
+export type ModelRoles = z.infer<typeof ModelRolesSchema>;
+/**
+ * Shipped default role map (#975). Family aliases only — no dated model IDs.
+ * Claude-code shorthand form; no opencode/aider entries shipped by default.
+ */
+export declare const DEFAULT_MODEL_ROLES: ModelRoles;
 /**
  * A single phase's `model`/`effort` override for the claude-code driver
  * (#914). See `RunSettings.phases`.
@@ -231,6 +248,17 @@ export interface RunSettings {
      * never merges regardless of this setting).
      */
     autoMerge: boolean;
+    /**
+     * Map of semantic role names to model strings (#975).
+     *
+     * Config expresses **roles**; this map resolves roles to concrete model
+     * strings. Phase policy, ladder, and other model-referencing surfaces use
+     * `role:<name>` to reference an entry; bare strings pass through verbatim.
+     *
+     * Default: `{ fast: "sonnet", strong: "opus", frontier: "fable" }`.
+     * `sequant setup` writes nothing here — absent key → defaults apply.
+     */
+    modelRoles: ModelRoles;
 }
 /**
  * Scope assessment threshold configuration
@@ -362,11 +390,7 @@ export declare const AiderSettingsSchema: z.ZodObject<{
 /** Zod schema for AgentSettings */
 export declare const AgentSettingsSchema: z.ZodObject<{
     parallel: z.ZodDefault<z.ZodBoolean>;
-    model: z.ZodDefault<z.ZodEnum<{
-        haiku: "haiku";
-        sonnet: "sonnet";
-        opus: "opus";
-    }>>;
+    model: z.ZodDefault<z.ZodString>;
     isolateParallel: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
@@ -432,6 +456,7 @@ export declare const RunSettingsSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     effortEscalation: z.ZodDefault<z.ZodBoolean>;
     autoMerge: z.ZodDefault<z.ZodBoolean>;
+    modelRoles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
 }, z.core.$strip>;
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export declare const ScopeThresholdSchema: z.ZodObject<{
@@ -538,14 +563,11 @@ export declare const SettingsSchema: z.ZodObject<{
         }, z.core.$strip>>>;
         effortEscalation: z.ZodDefault<z.ZodBoolean>;
         autoMerge: z.ZodDefault<z.ZodBoolean>;
+        modelRoles: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>>>;
     }, z.core.$strip>>;
     agents: z.ZodDefault<z.ZodObject<{
         parallel: z.ZodDefault<z.ZodBoolean>;
-        model: z.ZodDefault<z.ZodEnum<{
-            haiku: "haiku";
-            sonnet: "sonnet";
-            opus: "opus";
-        }>>;
+        model: z.ZodDefault<z.ZodString>;
         isolateParallel: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
     scopeAssessment: z.ZodDefault<z.ZodObject<{

package/dist/src/lib/settings.js

@@ -25,6 +25,26 @@ export const SETTINGS_VERSION = "1.0";
  * two validation points cannot drift apart on which values are accepted.
  */
 export const EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"];
+/**
+ * Map of semantic role names to model strings, used by `run.modelRoles` (#975).
+ *
+ * A value is either:
+ * - a plain string shorthand — desugars to `{ "claude-code": value }` (claude-code driver only)
+ * - an object keyed by driver registry name, for cross-driver mappings
+ *
+ * Role references use a `role:` prefix in phase policy / ladder entries;
+ * bare strings pass through verbatim (AC-3 backward compat).
+ */
+export const ModelRolesSchema = z.record(z.string(), z.union([z.string(), z.record(z.string(), z.string())]));
+/**
+ * Shipped default role map (#975). Family aliases only — no dated model IDs.
+ * Claude-code shorthand form; no opencode/aider entries shipped by default.
+ */
+export const DEFAULT_MODEL_ROLES = {
+    fast: "sonnet",
+    strong: "opus",
+    frontier: "fable",
+};
 // ─── Zod Schemas (AC-1, AC-5) ────────────────────────────────────────────────
 /** Zod schema for RotationSettings */
 export const RotationSettingsSchema = z.object({
@@ -41,7 +61,7 @@ export const AiderSettingsSchema = z.object({
 /** Zod schema for AgentSettings */
 export const AgentSettingsSchema = z.object({
     parallel: z.boolean().default(false),
-    model: z.enum(["haiku", "sonnet", "opus"]).default("haiku"),
+    model: z.string().default("haiku"),
     isolateParallel: z.boolean().default(false),
 });
 /**
@@ -111,6 +131,12 @@ export const RunSettingsSchema = z.object({
      * #817–#819. Overridable per-invocation with `--auto-merge`.
      */
     autoMerge: z.boolean().default(false),
+    /**
+     * Semantic role → model string map (#975). See `ModelRolesSchema` and
+     * `DEFAULT_MODEL_ROLES` for the shipped defaults. Absent from generated
+     * settings — absent key → defaults apply. Do not emit in `generateSettingsJsonc`.
+     */
+    modelRoles: ModelRolesSchema.default(() => ({ ...DEFAULT_MODEL_ROLES })),
 });
 /** Zod schema for ScopeThreshold (base — fields required, no defaults) */
 export const ScopeThresholdSchema = z.object({
@@ -233,6 +259,7 @@ const KNOWN_KEYS = {
         "aider",
         "relay",
         "phases",
+        "modelRoles",
     ]),
     // #914: keyed by real phase name so a typo (`run.phases.exce`) warns
     // instead of silently resolving to nothing. Computed from the registry
@@ -460,6 +487,7 @@ export const DEFAULT_SETTINGS = {
         relay: true, // Enable interactive relay (#383) by default
         effortEscalation: false, // #915: off by default — raises token spend
         autoMerge: false, // #958: off by default — preserves the human merge gate
+        modelRoles: DEFAULT_MODEL_ROLES, // #975: shipped defaults; absent key → these
     },
     agents: DEFAULT_AGENT_SETTINGS,
     scopeAssessment: DEFAULT_SCOPE_ASSESSMENT_SETTINGS,
@@ -616,7 +644,7 @@ export function generateSettingsJsonc(settings) {
     lines.push(`  "agents": {`);
     lines.push(`    // Run agents in parallel (faster, higher token usage)`);
     lines.push(`    "parallel": ${JSON.stringify(settings.agents.parallel)},`);
-    lines.push(`    // Default model for sub-agents ("haiku", "sonnet", "opus") — currently inert per anthropics/claude-code#43869`);
+    lines.push(`    // Default model for sub-agents (any alias/ID) — currently inert per anthropics/claude-code#43869`);
     lines.push(`    "model": ${JSON.stringify(settings.agents.model)},`);
     lines.push(`    // Isolate parallel agent groups in separate worktrees`);
     lines.push(`    "isolateParallel": ${JSON.stringify(settings.agents.isolateParallel)}`);
@@ -738,7 +766,7 @@ Generated by \`sequant init\`. See defaults below.
 | Key | Type | Default | Description |
 |-----|------|---------|-------------|
 | \`parallel\` | boolean | \`false\` | Run agents in parallel (faster, higher token usage) |
-| \`model\` | enum | \`"haiku"\` | Default model: \`"haiku"\`, \`"sonnet"\`, or \`"opus"\`. **Currently inert** per [anthropics/claude-code#43869](https://github.com/anthropics/claude-code/issues/43869) — subagents inherit the parent session's model. Kept for forward compatibility. |
+| \`model\` | string | \`"haiku"\` | Default model (any alias or dated ID). **Currently inert** per [anthropics/claude-code#43869](https://github.com/anthropics/claude-code/issues/43869) — subagents inherit the parent session's model. See \`run.modelRoles\` for semantic roles (#975). |
 | \`isolateParallel\` | boolean | \`false\` | Isolate parallel agents in separate worktrees |
 
 ## \`scopeAssessment\` — Scope Assessment Settings

package/dist/src/lib/workflow/batch-executor.js

@@ -1407,10 +1407,13 @@ export async function runIssueWithLogging(ctx) {
     // Hoisted out of the `if (stateManager)` block below because the checkpoint
     // warning also has to name this status, and naming the wrong one is exactly
     // the #837 inaccuracy being fixed here.
+    const qaVerdict = phaseResults.find((p) => p.phase === "qa")?.verdict;
     const finalStatus = readyGateResult
         ? readyGateResult.issueStatus
         : success
-            ? "ready_for_merge"
+            ? qaVerdict === "NEEDS_VERIFICATION"
+                ? "awaiting_verification"
+                : "ready_for_merge"
             : "in_progress";
     if (stateManager) {
         try {

package/dist/src/lib/workflow/config-resolver.d.ts

@@ -7,7 +7,7 @@
  * @module
  */
 import { type ExecutionConfig, type RunOptions } from "./types.js";
-import type { SequantSettings } from "../settings.js";
+import type { SequantSettings, ModelRoles } from "../settings.js";
 /**
  * Layers for config resolution.
  * Each field is optional — only defined values participate in merging.
@@ -72,6 +72,19 @@ export declare function positiveOr(value: number | undefined, fallback: number):
 export interface PhasePolicy {
     model?: string;
     effort?: string;
+    /**
+     * The original `role:<name>` string before resolution (#975). Set only when
+     * a `role:` prefix was used; absent for raw model strings. Allows metrics to
+     * record both what the user configured and what was actually dispatched.
+     */
+    requestedModel?: string;
+    /**
+     * Concrete model ID from `modelUsage` after phase execution (#975). Not
+     * present on the static config — populated by `enrichPhasePoliciesFromResults`
+     * just before the run is written to metrics. Absent for phases that did not
+     * execute or drivers that do not report `modelUsage`.
+     */
+    resolvedModel?: string;
 }
 /**
  * Parse a `--models`/`--efforts` CLI spec into a phase → value map.
@@ -83,6 +96,21 @@ export interface PhasePolicy {
  * malformed spec must never silently resolve to "nothing configured".
  */
 export declare function parsePhaseSpec(spec: string, phaseNames: string[]): Record<string, string>;
+/**
+ * Resolve a model-or-role reference to a concrete model string (#975).
+ *
+ * - No `role:` prefix → returns verbatim (backward compat, AC-3).
+ * - `role:<name>` → looks up `<name>` in `modelRoles`.
+ *   - Missing entry → throws, naming the role and available keys (AC-2).
+ *   - String value → desugars to `{ "claude-code": value }`, picks by `activeDriver`.
+ *   - Object value → picks by `activeDriver`; missing driver key → throws.
+ * - A role that resolves to a string for a different driver throws (AC-2).
+ *
+ * @param roleOrString - The model string from config/CLI (may have `role:` prefix).
+ * @param modelRoles   - The resolved `run.modelRoles` map.
+ * @param activeDriver - Driver registry name (default: `"claude-code"`).
+ */
+export declare function resolveRoleToModel(roleOrString: string, modelRoles?: ModelRoles, activeDriver?: string): string;
 /**
  * Resolve per-phase model/effort policies with CLI > settings > absent
  * precedence.
@@ -92,7 +120,7 @@ export declare function parsePhaseSpec(spec: string, phaseNames: string[]): Reco
  * two `phaseTimeout` producers did in #833 — see `positiveOr`'s doc comment
  * for that history.
  */
-export declare function resolvePhasePolicies(cliModels: string | undefined, cliEfforts: string | undefined, settingsPhases: Record<string, PhasePolicy> | undefined, phaseNames: string[]): Record<string, PhasePolicy>;
+export declare function resolvePhasePolicies(cliModels: string | undefined, cliEfforts: string | undefined, settingsPhases: Record<string, PhasePolicy> | undefined, phaseNames: string[], modelRoles?: ModelRoles, activeDriver?: string): Record<string, PhasePolicy>;
 /**
  * Build an ExecutionConfig from merged RunOptions and settings.
  * Extracts the phase-timeout, MCP, retry, and mode resolution logic

package/dist/src/lib/workflow/config-resolver.js

@@ -7,6 +7,7 @@
  * @module
  */
 import { DEFAULT_CONFIG, DEFAULT_PHASES, } from "./types.js";
+import { DEFAULT_MODEL_ROLES } from "../settings.js";
 import { getEnvConfig } from "./batch-executor.js";
 import { getPhaseNames } from "./phase-registry.js";
 /**
@@ -213,6 +214,46 @@ function applyPhaseSpec(target, parsed, field, phaseNames) {
         target[phase] = { ...target[phase], [field]: value };
     }
 }
+/**
+ * Resolve a model-or-role reference to a concrete model string (#975).
+ *
+ * - No `role:` prefix → returns verbatim (backward compat, AC-3).
+ * - `role:<name>` → looks up `<name>` in `modelRoles`.
+ *   - Missing entry → throws, naming the role and available keys (AC-2).
+ *   - String value → desugars to `{ "claude-code": value }`, picks by `activeDriver`.
+ *   - Object value → picks by `activeDriver`; missing driver key → throws.
+ * - A role that resolves to a string for a different driver throws (AC-2).
+ *
+ * @param roleOrString - The model string from config/CLI (may have `role:` prefix).
+ * @param modelRoles   - The resolved `run.modelRoles` map.
+ * @param activeDriver - Driver registry name (default: `"claude-code"`).
+ */
+export function resolveRoleToModel(roleOrString, modelRoles = DEFAULT_MODEL_ROLES, activeDriver = "claude-code") {
+    if (!roleOrString.startsWith("role:")) {
+        return roleOrString;
+    }
+    const roleName = roleOrString.slice("role:".length);
+    if (!roleName) {
+        throw new Error(`Invalid role reference "role:" — role name is empty. Available roles: ${Object.keys(modelRoles).join(", ")}.`);
+    }
+    const entry = modelRoles[roleName];
+    if (entry === undefined) {
+        throw new Error(`Role "${roleName}" is not defined in run.modelRoles. Available roles: ${Object.keys(modelRoles).join(", ")}.`);
+    }
+    if (typeof entry === "string") {
+        // String shorthand desugars to { "claude-code": value } — only for claude-code.
+        if (activeDriver !== "claude-code") {
+            throw new Error(`Role "${roleName}" uses a string shorthand (claude-code only) but the active driver is "${activeDriver}". Use an object map to define per-driver models.`);
+        }
+        return entry;
+    }
+    // Object map: pick by driver.
+    const resolved = entry[activeDriver];
+    if (resolved === undefined) {
+        throw new Error(`Role "${roleName}" has no entry for driver "${activeDriver}". Available drivers in this role: ${Object.keys(entry).join(", ")}.`);
+    }
+    return resolved;
+}
 /**
  * Resolve per-phase model/effort policies with CLI > settings > absent
  * precedence.
@@ -222,7 +263,7 @@ function applyPhaseSpec(target, parsed, field, phaseNames) {
  * two `phaseTimeout` producers did in #833 — see `positiveOr`'s doc comment
  * for that history.
  */
-export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phaseNames) {
+export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phaseNames, modelRoles, activeDriver) {
     const result = {};
     // Layer 1 (lowest): settings.run.phases. Skip any phase name settings
     // validation already didn't recognize — that's surfaced as a settings
@@ -243,6 +284,20 @@ export function resolvePhasePolicies(cliModels, cliEfforts, settingsPhases, phas
     if (cliEfforts) {
         applyPhaseSpec(result, parsePhaseSpec(cliEfforts, phaseNames), "effort", phaseNames);
     }
+    // Role resolution (#975): resolve any `role:<name>` model references to
+    // concrete model strings. Raw strings (no `role:` prefix) pass through
+    // verbatim — this is AC-3 backward compat.
+    if (modelRoles) {
+        for (const [phase, policy] of Object.entries(result)) {
+            if (policy.model && policy.model.startsWith("role:")) {
+                result[phase] = {
+                    ...policy,
+                    requestedModel: policy.model, // capture pre-resolution value (AC-4)
+                    model: resolveRoleToModel(policy.model, modelRoles, activeDriver),
+                };
+            }
+        }
+    }
     return result;
 }
 /**
@@ -304,7 +359,8 @@ export function buildExecutionConfig(mergedOptions, settings, issueCount) {
         // #914: CLI > settings > absent, via the shared resolver both
         // ExecutionConfig producers call (see `resolvePhasePolicies`'s doc
         // comment for the #833 drift this guards against).
-        phasePolicies: resolvePhasePolicies(mergedOptions.models, mergedOptions.efforts, settings.run.phases, getPhaseNames()),
+        // #975: pass modelRoles + active driver so `role:` prefixes resolve.
+        phasePolicies: resolvePhasePolicies(mergedOptions.models, mergedOptions.efforts, settings.run.phases, getPhaseNames(), settings.run.modelRoles, settings.run.agent ?? "claude-code"),
         // #915: CLI > settings > default `false` — mirrors the `readyGate`
         // precedent above. Both `ExecutionConfig` producers (here and
         // `ready-gate.ts:buildPhaseConfig`) resolve this the same way (#833).

package/dist/src/lib/workflow/drivers/agent-driver.d.ts

@@ -109,6 +109,13 @@ export interface AgentPhaseResult {
     stdoutTail?: string[];
     /** Process exit code (undefined for SDK-based drivers) (#447) */
     exitCode?: number;
+    /**
+     * Per-model usage totals from the SDK result (#975). Keys are concrete model
+     * IDs (e.g. `"claude-sonnet-5"`); first key is the resolved model string used
+     * for this phase. Only set by SDK-based drivers (claude-code); undefined for
+     * subprocess drivers (aider).
+     */
+    modelUsage?: Record<string, unknown>;
 }
 /**
  * Interface that all agent backends must implement.

package/dist/src/lib/workflow/drivers/claude-code.js

@@ -6,7 +6,7 @@
  */
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { getPhaseMcpServersConfig } from "../../mcp-config.js";
-import { RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
+import { ApiError, RateLimitError, BillingError, createRateLimitError, isWaitableWindow, isRateLimitFailureInfo, } from "../../errors.js";
 import { RingBuffer } from "../ring-buffer.js";
 export class ClaudeCodeDriver {
     name = "claude-code";
@@ -173,6 +173,31 @@ export class ClaudeCodeDriver {
             const structuredError = this.buildStructuredError(rateLimitInfo, assistantError, apiRetryError);
             if (resultMessage) {
                 if (resultMessage.subtype === "success") {
+                    // The SDK emits subtype "success" with is_error:true when the turn
+                    // ends on an API error (e.g. unrecognized model). Treat it as a
+                    // phase failure so the caller gets a real error, not a zero-work
+                    // success. See #973 / SDK docs §SDKResultMessage.
+                    if (resultMessage.is_error) {
+                        const metadata = {};
+                        if (resultMessage.api_error_status != null) {
+                            metadata.statusCode = resultMessage.api_error_status;
+                            metadata.api_error_status = resultMessage.api_error_status;
+                        }
+                        if (resultMessage.terminal_reason != null) {
+                            metadata.terminal_reason = resultMessage.terminal_reason;
+                        }
+                        const apiError = new ApiError(resultMessage.result, metadata);
+                        return {
+                            success: false,
+                            output: capturedOutput,
+                            sessionId: resultSessionId,
+                            resumeHandle,
+                            error: resultMessage.result,
+                            structuredError: apiError,
+                            stderrTail: stderrBuffer.getLines(),
+                            stdoutTail: stdoutBuffer.getLines(),
+                        };
+                    }
                     return {
                         success: true,
                         output: capturedOutput,
@@ -180,6 +205,7 @@ export class ClaudeCodeDriver {
                         resumeHandle,
                         stderrTail: stderrBuffer.getLines(),
                         stdoutTail: stdoutBuffer.getLines(),
+                        modelUsage: resultMessage.modelUsage,
                     };
                 }
                 // Turn-cap is a soft, recoverable outcome, not a hard failure: the

package/dist/src/lib/workflow/metrics-schema.d.ts

@@ -116,6 +116,8 @@ export declare const MetricRunSchema: z.ZodObject<{
     phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
         effort: z.ZodOptional<z.ZodString>;
+        requestedModel: z.ZodOptional<z.ZodString>;
+        resolvedModel: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
     effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         phase: z.ZodString;
@@ -176,6 +178,8 @@ export declare const MetricsSchema: z.ZodObject<{
         phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
             model: z.ZodOptional<z.ZodString>;
             effort: z.ZodOptional<z.ZodString>;
+            requestedModel: z.ZodOptional<z.ZodString>;
+            resolvedModel: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>>;
         effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
             phase: z.ZodString;
@@ -215,15 +219,20 @@ export declare function createMetricRun(options: {
     flags?: string[];
     failureCategory?: FailureCategory;
     /**
-     * Resolved per-phase model/effort overrides (#914), keyed by phase name.
+     * Resolved per-phase model/effort overrides (#914/#975), keyed by phase name.
      * Pass only the phases that actually had a configured override — a phase
      * that inherited the CLI default should not appear here at all. See
      * `resolvePhasePolicies` in `config-resolver.ts`, which already produces
      * a map shaped this way.
+     *
+     * `requestedModel` and `resolvedModel` are #975 additions — pass when available
+     * to enable cross-time benchmark comparisons as the model roster evolves.
      */
     phasePolicies?: Record<string, {
         model?: string;
         effort?: string;
+        requestedModel?: string;
+        resolvedModel?: string;
     }>;
     /**
      * Effort escalations applied during this run (#915), one entry per

package/dist/src/lib/workflow/metrics-schema.js

@@ -103,9 +103,21 @@ export const MetricRunSchema = z.object({
      * undefined fields. Enum/alias strings only, consistent with this
      * schema's no-file-paths/no-content privacy contract. Optional and
      * additive — absent on records written before this field existed.
+     *
+     * `requestedModel` and `resolvedModel` are added in #975 to record the
+     * role string (pre-resolution) and the concrete model ID from `modelUsage`
+     * (post-execution) respectively — enabling cross-time benchmark comparisons
+     * as the model roster moves under aliases.
      */
     phasePolicies: z
-        .record(z.string(), z.object({ model: z.string().optional(), effort: z.string().optional() }))
+        .record(z.string(), z.object({
+        model: z.string().optional(),
+        effort: z.string().optional(),
+        /** The role string or raw model string as configured (pre-resolution, #975). */
+        requestedModel: z.string().optional(),
+        /** The concrete model ID from `modelUsage` after execution (#975). */
+        resolvedModel: z.string().optional(),
+    }))
         .optional(),
     /**
      * Effort escalations applied during this run (#915), one entry per

package/dist/src/lib/workflow/metrics-writer.d.ts

@@ -70,10 +70,12 @@ export declare class MetricsWriter {
         model?: string;
         flags?: string[];
         failureCategory?: FailureCategory;
-        /** Resolved per-phase model/effort overrides (#914). See `createMetricRun`. */
+        /** Resolved per-phase model/effort overrides (#914/#975). See `createMetricRun`. */
         phasePolicies?: Record<string, {
             model?: string;
             effort?: string;
+            requestedModel?: string;
+            resolvedModel?: string;
         }>;
         /** Effort escalations applied during this run (#915). See `createMetricRun`. */
         effortEscalations?: Array<{

package/dist/src/lib/workflow/phase-executor.js

@@ -1138,10 +1138,18 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         shutdownManager.removeAbortController(abortController);
     }
     const durationSeconds = (Date.now() - startTime) / 1000;
+    // #975: extract the concrete model ID from the driver's modelUsage map.
+    // First key is the primary model dispatched; undefined for drivers that
+    // don't populate modelUsage (aider, subprocess paths).
+    const resolvedModel = agentResult.modelUsage
+        ? Object.keys(agentResult.modelUsage)[0]
+        : undefined;
     if (agentResult.success) {
-        return mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
+        const result = mapAgentSuccessToPhaseResult(phase, agentResult, durationSeconds, cwd);
+        return resolvedModel ? { ...result, resolvedModel } : result;
     }
-    return mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
+    const result = mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds);
+    return resolvedModel ? { ...result, resolvedModel } : result;
 }
 /**
  * Execute a phase with automatic retry for cold-start failures and MCP fallback.

package/dist/src/lib/workflow/reconcile.js

@@ -88,13 +88,15 @@ export function getNextActionHint(issue) {
             if (issue.currentPhase) {
                 const failedPhase = Object.entries(issue.phases).find(([, ps]) => ps.status === "failed");
                 if (failedPhase) {
-                    return `sequant run ${issue.number} --phase ${failedPhase[0]}`;
+                    return `sequant run ${issue.number} --phases ${failedPhase[0]}`;
                 }
             }
             return `sequant run ${issue.number}`;
         }
         case "waiting_for_qa_gate":
-            return `sequant run ${issue.number} --phase qa`;
+            return `sequant run ${issue.number} --phases qa`;
+        case "awaiting_verification":
+            return `sequant run ${issue.number} --phases qa`;
         case "waiting_for_human_merge":
             // `sequant ready` certified the work; a human reviews + merges manually.
             if (issue.pr?.number) {

package/dist/src/lib/workflow/run-orchestrator.d.ts

@@ -16,6 +16,7 @@ import type { LockFile } from "../locks/index.js";
 import { type ChainResumePlan } from "./chain-resume.js";
 import { WorkflowEventEmitter } from "./event-emitter.js";
 import type { SequantSettings } from "../settings.js";
+import { type PhasePolicy } from "./config-resolver.js";
 /**
  * Build the stack-manifest line emitted into PR bodies under --stacked.
  *
@@ -172,6 +173,23 @@ export interface RunResult {
      */
     wallClockDurationSeconds: number;
 }
+/**
+ * Merge per-phase `resolvedModel` from execution results into the static
+ * phasePolicies map before it is written to metrics (#975 AC-4).
+ *
+ * `config.phasePolicies` carries the model alias resolved at config time (e.g.
+ * `"sonnet"`). The concrete model ID only becomes known after execution, from
+ * the driver's `modelUsage` map. This function enriches each phase entry with
+ * that runtime-observed value so benchmark comparisons across roster changes
+ * (#916/#944) see the actual model dispatched, not just the alias.
+ *
+ * `requestedModel` (the pre-resolution role string, e.g. `"role:fast"`) flows
+ * through from `config.phasePolicies` unchanged — it is already set by
+ * `resolvePhasePolicies` for role references and absent for raw strings.
+ *
+ * @internal Exported for testing only.
+ */
+export declare function enrichPhasePoliciesFromResults(phasePolicies: Record<string, PhasePolicy> | undefined, results: IssueResult[]): Record<string, PhasePolicy> | undefined;
 /**
  * CLI-free workflow execution engine.
  *

package/dist/src/lib/workflow/run-orchestrator.js

@@ -82,7 +82,7 @@ import { MetricsWriter } from "./metrics-writer.js";
 import { WorkflowEventEmitter } from "./event-emitter.js";
 import { determineOutcome } from "./metrics-schema.js";
 import { getTokenUsageForRun } from "./token-utils.js";
-import { resolveRunOptions, buildExecutionConfig } from "./config-resolver.js";
+import { resolveRunOptions, buildExecutionConfig, } from "./config-resolver.js";
 import { pipelineHasFailed } from "./status-derivation.js";
 /**
  * Build the stack-manifest line emitted into PR bodies under --stacked.
@@ -96,6 +96,40 @@ export function buildStackManifest(issueNumbers, currentIndex) {
     const parts = issueNumbers.map((n, i) => i === currentIndex ? `#${n} (this)` : `#${n}`);
     return `Part of stack: ${parts.join(" → ")}`;
 }
+// ── Metrics helpers ─────────────────────────────────────────────────────────
+/**
+ * Merge per-phase `resolvedModel` from execution results into the static
+ * phasePolicies map before it is written to metrics (#975 AC-4).
+ *
+ * `config.phasePolicies` carries the model alias resolved at config time (e.g.
+ * `"sonnet"`). The concrete model ID only becomes known after execution, from
+ * the driver's `modelUsage` map. This function enriches each phase entry with
+ * that runtime-observed value so benchmark comparisons across roster changes
+ * (#916/#944) see the actual model dispatched, not just the alias.
+ *
+ * `requestedModel` (the pre-resolution role string, e.g. `"role:fast"`) flows
+ * through from `config.phasePolicies` unchanged — it is already set by
+ * `resolvePhasePolicies` for role references and absent for raw strings.
+ *
+ * @internal Exported for testing only.
+ */
+export function enrichPhasePoliciesFromResults(phasePolicies, results) {
+    const resolvedByPhase = new Map();
+    for (const result of results) {
+        for (const pr of result.phaseResults) {
+            if (pr.resolvedModel) {
+                resolvedByPhase.set(pr.phase, pr.resolvedModel);
+            }
+        }
+    }
+    if (resolvedByPhase.size === 0)
+        return phasePolicies;
+    const enriched = { ...(phasePolicies ?? {}) };
+    for (const [phase, resolvedModel] of resolvedByPhase.entries()) {
+        enriched[phase] = { ...enriched[phase], resolvedModel };
+    }
+    return enriched;
+}
 // ── Orchestrator ────────────────────────────────────────────────────────────
 /**
  * CLI-free workflow execution engine.
@@ -1239,7 +1273,9 @@ export class RunOrchestrator {
             flags: cliFlags,
             failureCategory,
             // #914: resolved per-phase model/effort, when any phase had one.
-            phasePolicies: config.phasePolicies,
+            // #975: enriched with resolvedModel from execution (modelUsage) and
+            // requestedModel already flows through from resolvePhasePolicies.
+            phasePolicies: enrichPhasePoliciesFromResults(config.phasePolicies, results),
             // #915: escalated tiers, when any phase execution escalated.
             effortEscalations,
             metrics: {

package/dist/src/lib/workflow/state-cleanup.d.ts

@@ -58,7 +58,7 @@ export interface ReconcileOptions {
 export interface ReconcileResult {
     /** Whether reconciliation was successful */
     success: boolean;
-    /** Issues advanced to `merged` (from `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`) */
+    /** Issues advanced to `merged` (from `ready_for_merge`, `in_progress`, `waiting_for_qa_gate`, `waiting_for_human_merge`, or `awaiting_verification`) */
     advanced: number[];
     /** Issues checked but not yet merged (status unchanged) */
     stillPending: number[];
@@ -68,9 +68,9 @@ export interface ReconcileResult {
 /**
  * Lightweight state reconciliation at run start
  *
- * Checks issues in `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`
- * state and advances them to `merged` if their PRs are merged or their branches
- * are in main.
+ * Checks issues in `ready_for_merge`, `in_progress`, `waiting_for_qa_gate`,
+ * `waiting_for_human_merge`, or `awaiting_verification` state and advances
+ * them to `merged` if their PRs are merged or their branches are in main.
  *
  * Including `in_progress` covers the case where a PR was merged outside
  * this sequant session (separate process, `gh pr merge`, web UI) — without

package/dist/src/lib/workflow/state-cleanup.js

@@ -188,9 +188,9 @@ export async function cleanupStaleEntries(options = {}) {
 /**
  * Lightweight state reconciliation at run start
  *
- * Checks issues in `ready_for_merge`, `in_progress`, or `waiting_for_qa_gate`
- * state and advances them to `merged` if their PRs are merged or their branches
- * are in main.
+ * Checks issues in `ready_for_merge`, `in_progress`, `waiting_for_qa_gate`,
+ * `waiting_for_human_merge`, or `awaiting_verification` state and advances
+ * them to `merged` if their PRs are merged or their branches are in main.
  *
  * Including `in_progress` covers the case where a PR was merged outside
  * this sequant session (separate process, `gh pr merge`, web UI) — without
@@ -227,14 +227,18 @@ export async function reconcileStateAtStartup(options = {}) {
         // waiting_for_human_merge covers #817's `--ready-gate` terminal: a gated
         // issue never reaches ready_for_merge, so without it a gated issue whose PR
         // a human then merged stayed here forever and never advanced to merged
-        // (#837). Note this list is deliberately WIDER than `isCompletedIssueStatus`
+        // (#837). awaiting_verification covers the same shape for #972: the issue
+        // has an open PR pending human verification, and the human may verify and
+        // merge it directly instead of re-running qa first.
+        // Note this list is deliberately WIDER than `isCompletedIssueStatus`
         // — it asks "might this have a merged PR?", not "is this done?", which is
         // why in_progress belongs here but not there.
         for (const [issueNumStr, issueState] of Object.entries(state.issues)) {
             if (issueState.status !== "ready_for_merge" &&
                 issueState.status !== "in_progress" &&
                 issueState.status !== "waiting_for_qa_gate" &&
-                issueState.status !== "waiting_for_human_merge") {
+                issueState.status !== "waiting_for_human_merge" &&
+                issueState.status !== "awaiting_verification") {
                 continue;
             }
             const issueNum = parseInt(issueNumStr, 10);

package/dist/src/lib/workflow/state-schema.d.ts

@@ -47,6 +47,7 @@ export declare const IssueStatusSchema: z.ZodEnum<{
     not_started: "not_started";
     waiting_for_qa_gate: "waiting_for_qa_gate";
     waiting_for_human_merge: "waiting_for_human_merge";
+    awaiting_verification: "awaiting_verification";
     ready_for_merge: "ready_for_merge";
     blocked: "blocked";
     abandoned: "abandoned";
@@ -72,6 +73,8 @@ export declare const PhaseMarkerSchema: z.ZodObject<{
     pr: z.ZodOptional<z.ZodNumber>;
     error: z.ZodOptional<z.ZodString>;
     commitSHA: z.ZodOptional<z.ZodString>;
+    requestedModel: z.ZodOptional<z.ZodString>;
+    resolvedModel: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type PhaseMarker = z.infer<typeof PhaseMarkerSchema>;
 /**
@@ -235,6 +238,7 @@ export declare const IssueStateSchema: z.ZodObject<{
         not_started: "not_started";
         waiting_for_qa_gate: "waiting_for_qa_gate";
         waiting_for_human_merge: "waiting_for_human_merge";
+        awaiting_verification: "awaiting_verification";
         ready_for_merge: "ready_for_merge";
         blocked: "blocked";
         abandoned: "abandoned";
@@ -385,6 +389,7 @@ export declare const WorkflowStateSchema: z.ZodObject<{
             not_started: "not_started";
             waiting_for_qa_gate: "waiting_for_qa_gate";
             waiting_for_human_merge: "waiting_for_human_merge";
+            awaiting_verification: "awaiting_verification";
             ready_for_merge: "ready_for_merge";
             blocked: "blocked";
             abandoned: "abandoned";

package/dist/src/lib/workflow/state-schema.js

@@ -47,6 +47,7 @@ export const IssueStatusSchema = z.enum([
     "in_progress", // Actively being worked on
     "waiting_for_qa_gate", // QA completed, waiting for gate approval in chain mode
     "waiting_for_human_merge", // `sequant ready` (#683) finished its A+ gate; awaiting human merge decision (never auto-merges)
+    "awaiting_verification", // QA returned NEEDS_VERIFICATION; human must execute ACs before QA re-run (#972)
     "ready_for_merge", // All phases passed, PR ready for review
     "merged", // PR merged, work complete
     "blocked", // Waiting on external input or dependency
@@ -72,6 +73,10 @@ export const PhaseMarkerSchema = z.object({
     error: z.string().optional(),
     /** Git HEAD SHA at time of phase completion (used for incremental QA) */
     commitSHA: z.string().optional(),
+    /** Role string or raw model string as configured for this phase (#975). */
+    requestedModel: z.string().optional(),
+    /** Concrete model ID from `modelUsage` after phase execution (#975). */
+    resolvedModel: z.string().optional(),
 });
 /**
  * Individual phase state within an issue

package/dist/src/lib/workflow/types.d.ts

@@ -287,6 +287,12 @@ export interface PhaseResult {
         base: string;
         escalated: string;
     };
+    /**
+     * Concrete model ID from the SDK `modelUsage` map for this phase execution
+     * (#975). First key of `modelUsage` — records the actual model dispatched,
+     * distinct from the configured alias. Used to populate metrics `phasePolicies`.
+     */
+    resolvedModel?: string;
 }
 /**
  * Result of executing all phases for an issue

package/dist/src/mcp/tools/run.js

@@ -390,6 +390,12 @@ const runToolInputSchema = {
         .boolean()
         .optional()
         .describe("Enable auto-retry on QA failure"),
+    force: z
+        .boolean()
+        .optional()
+        .describe("Re-run even if the issue is already in a completed state such as " +
+        "ready_for_merge (mirrors CLI --force). Not needed after a " +
+        "NEEDS_VERIFICATION verdict: awaiting_verification re-runs freely."),
     agent: z
         .string()
         .optional()
@@ -410,7 +416,7 @@ export function registerRunTool(server) {
             openWorldHint: true,
         },
         inputSchema: runToolInputSchema,
-    }, (async ({ issues, phases, qualityLoop, agent, }, extra) => {
+    }, (async ({ issues, phases, qualityLoop, force, agent, }, extra) => {
         if (!issues || issues.length === 0) {
             return {
                 content: [
@@ -435,6 +441,9 @@ export function registerRunTool(server) {
         if (qualityLoop) {
             args.push("--quality-loop");
         }
+        if (force) {
+            args.push("--force");
+        }
         if (agent) {
             args.push("--agent", agent);
         }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sequant",
-  "version": "2.12.0",
-  "description": "AI coding agent orchestrator — resolve GitHub issues end-to-end with isolated git worktrees, quality gates, and an MCP server. Works with Claude Code or Aider.",
+  "version": "2.13.0",
+  "description": "AI coding agent orchestrator that proves its work — GitHub issues to merge-ready PRs with every acceptance criterion verified, isolated git worktrees, quality gates, an MCP server, and a human merge gate. Works with Claude Code or Aider.",
   "type": "module",
   "bin": {
     "sequant": "dist/bin/cli.js"
@@ -31,6 +31,7 @@
     "typecheck:scripts": "tsc --noEmit -p tsconfig.scripts.json",
     "lint:skill-calls": "npx tsx scripts/lint-skill-calls.ts",
     "lint:skill-gates": "npx tsx scripts/lint-skill-gates.ts",
+    "lint:constitution-dod": "npx tsx scripts/check-constitution-dod.ts",
     "lint:skill-sync": "npx tsx scripts/check-skill-sync.ts",
     "prepare:marketplace": "npx tsx scripts/prepare-marketplace.ts",
     "validate:marketplace": "npx tsx scripts/prepare-marketplace.ts --validate-only",
@@ -91,7 +92,7 @@
     }
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.142",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.242",
     "@hono/node-server": "^2.0.0",
     "boxen": "^8.0.1",
     "chalk": "^6.0.0",
@@ -99,9 +100,9 @@
     "cli-table3": "^0.6.5",
     "commander": "^14.0.3",
     "diff": "^9.0.0",
-    "hono": "^4.12.1",
+    "hono": "^4.13.4",
     "ink": "^7.0.1",
-    "inquirer": "^14.0.1",
+    "inquirer": "^14.1.0",
     "log-update": "^7.0.1",
     "open": "^11.0.0",
     "ora": "^9.3.0",
@@ -114,16 +115,16 @@
   "devDependencies": {
     "@eslint/js": "^10.0.1",
     "@types/inquirer": "^9.0.7",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.3.0",
     "@types/react": "^19.2.14",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "eslint": "^10.1.0",
+    "@typescript-eslint/eslint-plugin": "^8.68.0",
+    "@typescript-eslint/parser": "^8.68.0",
+    "eslint": "^10.9.1",
     "globals": "^17.0.0",
     "ink-testing-library": "^4.0.0",
     "tsx": "^4.19.2",
     "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.0",
-    "vitest": "^4.1.0"
+    "typescript-eslint": "^8.68.0",
+    "vitest": "^4.1.11"
   }
 }

package/templates/memory/constitution.md

@@ -1,64 +1,131 @@
-# {{PROJECT_NAME}} Constitution
+# {{PROJECT_NAME}} Agent Contract
 
-This document defines the core principles and patterns for AI-assisted development in this project.
+This document is the enforceable contract surface for AI-assisted development in this project. Every section either machine-checked or referenced by a named skill at a named decision point. Values with no consumer are not present.
 
-## Core Principles
+---
 
-1. **Quality First** - Never sacrifice code quality for speed
-2. **Test Everything** - All features must have appropriate test coverage
-3. **Document Decisions** - Important decisions should be captured in issue comments
-4. **Incremental Progress** - Break large tasks into small, reviewable chunks
-5. **Respect Existing Patterns** - Follow established project conventions
+## 1. Definition of Done
 
-## Workflow Phases
+Every PR must pass all gates below before merge. Verified by `/qa` §7 — the table is generated from that section and cannot drift from it (`lint:constitution-dod` fails CI on divergence).
 
-### Phase 1: Planning (`/spec`)
-- Understand requirements and acceptance criteria
-- Identify potential risks and dependencies
-- Draft implementation plan for approval
+**These are project-wide gates. Do not restate them as issue-level ACs.**
 
-### Phase 2: Implementation (`/exec`)
-- Work in feature worktree
-- Follow established patterns
-- Keep commits atomic and well-described
+<!-- BEGIN:DOD-GATES -->
+| Gate | Trigger | Verdict impact |
+|------|---------|----------------|
+| All ACs MET | any `NOT_MET` or `PARTIALLY_MET` | `AC_NOT_MET` — blocks merge |
+| Detection patterns (§6c) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Behavior-rule check (§6e) | `Survivors Found` | `AC_NOT_MET` — blocks merge |
+| Trust boundary (§6f) | `Injection Acted On` | `AC_NOT_MET` — blocks merge |
+| CLI registration (§2h) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Mutation verification (§6i) | `Failed` | `AC_NOT_MET` — blocks merge |
+| Adversarial re-read (§6d) | `Severe Gap` | `AC_NOT_MET` — blocks merge |
+| Skill verification (§6a) | `Failed` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Script execution evidence | `Incomplete` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Declared evidence (§6h) | `Incomplete` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Mutation verification (§6i) | `Missing` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Script verification (§11) | `Not Verified` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| CHANGELOG entry (§10a) | both conditions true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Quality plan (Phase 0b) | both conditions true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Browser test | condition true | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Pending verifications | count `> 0` | `NEEDS_VERIFICATION` — holds for external verification |
+| Quality plan (Phase 0b) | `Partial` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Smoke tests (§6b) | `Partial` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Detection patterns (§6c) | `Insufficient Samples` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Detection patterns (§6c) | `Skipped` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Adversarial re-read (§6d) | `Gaps Found` | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+| Improvement suggestions | list non-empty | `AC_MET_BUT_NOT_A_PLUS` — cannot be A+ |
+<!-- END:DOD-GATES -->
 
-### Phase 3: Quality (`/qa`)
-- Review against acceptance criteria
-- Run all quality checks
-- Address feedback before merge
+---
 
-## Code Standards
+## 2. AC Authoring Standard
 
-### Naming Conventions
-- Use descriptive variable and function names
-- Follow language-specific conventions (camelCase, snake_case, etc.)
+Referenced by `/spec`'s AC Quality Check step when flagging lint warnings.
 
-### Error Handling
-- Handle errors gracefully
-- Log meaningful error messages
-- Don't swallow exceptions silently
+### Format rules
 
-### Testing
-- Write tests for new features
-- Update tests when modifying existing code
-- Test edge cases and error paths
+**Write each AC on a single line.** The parser is line-anchored; an AC that wraps to a second line is silently truncated at the first newline, producing a partial description with no `Evidence:` or `Risk:` clause. This is the most common AC-hygiene defect in this repo.
 
-## Commands Available
+**Required fields for testable ACs:**
 
-| Command | Purpose |
-|---------|---------|
-| `/spec` | Plan implementation for an issue |
-| `/exec` | Implement a planned feature |
-| `/test` | Run browser-based UI tests |
-| `/qa` | Quality review before merge |
-| `/loop` | Fix iteration when tests fail |
-| `/docs` | Generate feature documentation |
+| Field | Purpose | Required when |
+|-------|---------|---------------|
+| `Evidence:` | Names the artifact that proves the AC was met | AC is verifiable by code review or test |
+| `Risk:` | Names the failure mode if this AC is wrong | AC has a non-obvious failure mode |
+| `Human decision` | Flags the AC as requiring human judgment | AC cannot be verified mechanically |
 
-## Stack-Specific Notes
+**Non-Goals section:** Every issue must have a `## Non-Goals` section. Scope without a boundary is unbounded scope. The Non-Goals section is where you declare what the issue explicitly does not do.
+
+### Examples
+
+**Bad** (three violations on one AC):
+```
+- [ ] **AC-3:** The feature should work correctly and handle errors
+  gracefully with good test coverage.
+```
+Problems: wraps to second line (parser truncates), "work correctly" is not measurable, no `Evidence:` clause.
+
+**Good** (single line, measurable, evidence declared):
+```
+- [ ] **AC-3:** `/spec`'s AC Quality Check output references the constitution AC standard. Evidence: scoped gate test on the spec skill's reference string, mutation-verified.
+```
+
+---
+
+## 3. Boundaries
+
+Every rule below names its enforcing mechanism. Rules without a named enforcer are not in this section.
+
+| Rule | Enforcing mechanism |
+|------|---------------------|
+| No force-push or amend on pushed branches | `templates/hooks/pre-tool.sh` (pre-tool hook, `HOOK_BLOCKED: Force push`) |
+| No edits outside the issue worktree | `templates/hooks/pre-tool.sh` (worktree-only editing guard) |
+| Gate tests must be mutation-verified | `/qa` §6i + `SEQUANT_MUTATION` marker in PR body (#939); `Missing` caps at `AC_MET_BUT_NOT_A_PLUS`, `Failed` floors at `AC_NOT_MET` |
+| All §1 Definition of Done gates | `/qa` §7 verdict algorithm (see §1 above) |
+
+---
+
+## 4. Budgets & Stop Conditions
+
+### Iteration and token caps
+
+| Cap | Setting key | Default |
+|-----|-------------|---------|
+| Quality-loop max iterations | `run.maxIterations` | 3 |
+| Auto-wait budget (rate-limit windows) | `run.autoWaitMinutes` | 0 (off) |
+
+When a cap is reached, the run stops at the human merge gate rather than continuing indefinitely.
+
+### Stop and hold states
+
+The workflow stops or holds at these states — do not attempt to continue past them:
+
+| State | Meaning | Action |
+|-------|---------|--------|
+| `waiting_for_human_merge` | All gates passed; PR is open | Human reviews and merges |
+| `awaiting_verification` | At least one AC is `PENDING` external verification | Wait for the external signal; see [`docs/features/qa-verdict-workflow-states.md`](../../docs/features/qa-verdict-workflow-states.md) |
+| `blocked` | A guard halted the run | Investigate the block; do not bypass |
+
+### Gap-prompt discipline
+
+**Diagnostic prompts are cheap and high-yield. Imperative prompts require triage first.**
+
+- **Diagnostic** ("what are the gaps?"): run freely. Surfaces unknowns at low cost.
+- **Imperative** ("fix all gaps"): requires triage first. An unfocused imperative prompt against a list of gaps produces shallow patches for every item rather than deep fixes for the real ones. The 2026-08 incident (#930) demonstrated this directly: an imperative "fix all gaps" run against a QA verdict produced 12 surface-level changes that passed re-QA but left the root-cause gap intact, requiring a third QA cycle.
+
+When QA returns gaps: run a diagnostic first ("which gap is the most blocking?"), then issue a targeted imperative for that gap specifically.
+
+---
+
+## 5. Stack-Specific Notes
 
 {{STACK_NOTES}}
 
-## Project-Specific Notes
+---
 
-<!-- Add your project-specific guidelines below -->
+## Project-Specific Notes
 
+<!-- Add your project-specific guidelines below this line.
+     This section is preserved across `sequant update` and `sync` runs
+     (it is in CUSTOMIZABLE_FILES). Everything above is updated automatically. -->

package/templates/skills/spec/SKILL.md

@@ -107,6 +107,8 @@ Mark tier in HTML comment for downstream parsing: `<!-- SEQUANT_SPEC_TIER: [tier
    | Open-ended | "etc.", "and more" | Scope undefined |
    | Title/body tension | doc-noun title ("note", "comment", "snippet") + runtime-imperative body ("execute", "trigger", "capture", incl. inflections like `triggered`/`captured`, `run /<cmd>`); separators `.`/`\n`/`:`/`—` | Two different verification bars |
 
+   > For the house AC format rules (single-line constraint, `Evidence:`/`Risk:`/`Human decision` fields, Non-Goals section), see the constitution's §2 AC Authoring Standard (`.claude/memory/constitution.md`).
+
 3. **Scope Assessment** (unless `--skip-scope-check`): Use `performScopeAssessment` from `./src/lib/scope/index.ts` with settings from `getSettings()`. Verdicts: SCOPE_OK (green), SCOPE_WARNING (yellow, auto-enables quality loop), SCOPE_SPLIT_RECOMMENDED (red). Store results in state.
 
 ### If guard fails (consumer projects):