sequant 2.10.0 → 2.11.0

package/dist/src/lib/workflow/effort-escalation.js

@@ -0,0 +1,82 @@
+/**
+ * Evidence-based effort escalation on quality-loop retries (#915).
+ *
+ * Sequant already detects several "this attempt is a retry" moments: the
+ * outer quality-loop re-entering a phase (`batch-executor.ts`) and the
+ * `sequant ready` QA-pass loop re-running `qa`/`loop` (`ready-gate.ts`).
+ * Escalation raises the phase's reasoning effort one tier for exactly that
+ * retried execution when the workflow observed a prior attempt fail — never
+ * speculatively, and never more than one tier per retry (see AC-6).
+ *
+ * Deliberately its own module rather than living beside `resolvePhasePolicies`
+ * in `config-resolver.ts`: `config-resolver.ts` imports `getEnvConfig` from
+ * `batch-executor.ts`, and `batch-executor.ts` is one of this module's
+ * dispatch-time callers, so co-locating here avoids introducing that cycle.
+ */
+import { EFFORT_LEVELS } from "../settings.js";
+/**
+ * Base effort assumed for a phase with no configured `effort` override, when
+ * escalation needs a starting point to step up from (AC-5). `phase-executor.ts`
+ * omits the `effort` key entirely in that case (#914) so the Agent SDK's own
+ * default applies — #914 deliberately never encoded what that default is,
+ * since "omitted" is not the same claim as "equals X".
+ *
+ * Verified against `@anthropic-ai/claude-agent-sdk`'s own `query()` Options
+ * type (`sdk.d.ts`): `effort?: EffortLevel` is documented inline as
+ * `'high' — Deep reasoning (default)`. That is the SDK's default for the
+ * exact call sequant makes (raw `query()`, not the Claude Code CLI product —
+ * whose own `xhigh` default is a caller choice on top of this SDK, not the
+ * SDK's own default), so this constant is not a guess.
+ */
+export const DEFAULT_ESCALATION_BASE = "high";
+/**
+ * Pure ladder step: one tier above `base` on `EFFORT_LEVELS`, capped at the
+ * top (`max`). Returns `base` unchanged whenever `enabled` is false or this
+ * isn't a retry — the disabled/first-attempt path must be indistinguishable
+ * from #914 with escalation never having existed (AC-2).
+ *
+ * Always escalates from the phase's CONFIGURED base, never from a previously
+ * escalated value — callers must not accumulate escalation across iterations
+ * (AC-6): base `high` on the 3rd loop iteration is `xhigh`, not `max`.
+ */
+export function resolveEscalatedEffort(base, isRetry, enabled) {
+    if (!enabled || !isRetry)
+        return base;
+    const effectiveBase = (base ??
+        DEFAULT_ESCALATION_BASE);
+    const baseIdx = EFFORT_LEVELS.indexOf(effectiveBase);
+    const resolvedIdx = baseIdx === -1 ? EFFORT_LEVELS.indexOf(DEFAULT_ESCALATION_BASE) : baseIdx;
+    const nextIdx = Math.min(resolvedIdx + 1, EFFORT_LEVELS.length - 1);
+    return EFFORT_LEVELS[nextIdx];
+}
+/**
+ * Apply escalation to ONE phase's execution, for THIS dispatch only.
+ *
+ * This is deliberately a per-execution decision made at the dispatch site,
+ * not a value baked into `ExecutionConfig` at build time: `buildExecutionConfig`
+ * / `buildPhaseConfig` run once per run/gate, not once per phase execution, so
+ * a static escalated value would leak across every phase in the chain and
+ * violate AC-7. The three retry-dispatch sites (batch-executor.ts's quality
+ * loop, ready-gate.ts's QA-pass loop `qa`/`loop` dispatch) call this function
+ * — and only this function — so they cannot drift on the cap/one-tier rules
+ * in AC-6 (see resolveEscalatedEffort's doc comment).
+ */
+export function withEscalatedEffort(config, phase, isRetry) {
+    if (!config.effortEscalation || !isRetry)
+        return { config };
+    const currentPolicy = config.phasePolicies?.[phase];
+    const base = currentPolicy?.effort;
+    const escalated = resolveEscalatedEffort(base, isRetry, true);
+    if (!escalated || escalated === base)
+        return { config };
+    return {
+        config: {
+            ...config,
+            phasePolicies: {
+                ...config.phasePolicies,
+                [phase]: { ...currentPolicy, effort: escalated },
+            },
+        },
+        record: { phase, base: base ?? DEFAULT_ESCALATION_BASE, escalated },
+    };
+}

package/dist/src/lib/workflow/error-classifier.d.ts

@@ -11,9 +11,12 @@ import { SequantError } from "../errors.js";
  * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
  * errors — `classifyError` never produces them, since stderr text cannot
  * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * `pr_creation` (#920) is assigned only at the `deriveFailureCategory` call
+ * site, not by `classifyError` — a failed `createPR` has no failing phase to
+ * classify, so it would otherwise leave `failureCategory` `undefined`.
  * Keep in sync with the inline category enum in `run-log-schema.ts`.
  */
-export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "unknown"];
+export declare const ERROR_CATEGORIES: readonly ["context_overflow", "api_error", "hook_failure", "build_error", "timeout", "rate_limit", "billing", "pr_creation", "unknown"];
 export type ErrorCategory = (typeof ERROR_CATEGORIES)[number];
 /**
  * Map from error type name to legacy category string.

package/dist/src/lib/workflow/error-classifier.js

@@ -11,6 +11,9 @@ import { ContextOverflowError, ApiError, HookFailureError, BuildError, TimeoutEr
  * `rate_limit` / `billing` (#761 AC-6) only arise from the driver's structured
  * errors — `classifyError` never produces them, since stderr text cannot
  * distinguish a window-exhausted limit from a transient 429 (`api_error`).
+ * `pr_creation` (#920) is assigned only at the `deriveFailureCategory` call
+ * site, not by `classifyError` — a failed `createPR` has no failing phase to
+ * classify, so it would otherwise leave `failureCategory` `undefined`.
  * Keep in sync with the inline category enum in `run-log-schema.ts`.
  */
 export const ERROR_CATEGORIES = [
@@ -21,6 +24,7 @@ export const ERROR_CATEGORIES = [
     "timeout",
     "rate_limit",
     "billing",
+    "pr_creation",
     "unknown",
 ];
 /**

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

@@ -13,7 +13,7 @@
  * await writer.finalize();
  * ```
  */
-import { type RunLog, type RunConfig, type PhaseLog, type Phase } from "./run-log-schema.js";
+import { type RunLog, type RunConfig, type PhaseLog, type Phase, type SpecRecommendation } from "./run-log-schema.js";
 import { type RotationSettings } from "./log-rotation.js";
 export interface LogWriterOptions {
     /** Path to log directory (default: .sequant/logs in current directory) */
@@ -82,6 +82,15 @@ export declare class LogWriter {
      * Set PR info on the current issue (call before completeIssue)
      */
     setPRInfo(prNumber: number, prUrl: string, issueNumber?: number): void;
+    /**
+     * Record how the spec→run phase recommendation was resolved (#921 AC-4).
+     *
+     * Called right after `resolveSpecRecommendation` runs, before the next
+     * phase starts — mirrors {@link setPRInfo}'s post-hoc-setter shape because
+     * the spec `PhaseLog` is already written by the time resolution (which does
+     * its own comment-fetch I/O) completes.
+     */
+    setSpecRecommendation(recommendation: SpecRecommendation, issueNumber?: number): void;
     /**
      * Force the in-flight issue's status to `failure` (#879).
      *

package/dist/src/lib/workflow/log-writer.js

@@ -134,6 +134,23 @@ export class LogWriter {
         issue.prNumber = prNumber;
         issue.prUrl = prUrl;
     }
+    /**
+     * Record how the spec→run phase recommendation was resolved (#921 AC-4).
+     *
+     * Called right after `resolveSpecRecommendation` runs, before the next
+     * phase starts — mirrors {@link setPRInfo}'s post-hoc-setter shape because
+     * the spec `PhaseLog` is already written by the time resolution (which does
+     * its own comment-fetch I/O) completes.
+     */
+    setSpecRecommendation(recommendation, issueNumber) {
+        const issue = issueNumber
+            ? (this.activeIssues.get(issueNumber) ?? this.currentIssue)
+            : this.currentIssue;
+        if (!issue) {
+            return;
+        }
+        issue.specRecommendation = recommendation;
+    }
     /**
      * Force the in-flight issue's status to `failure` (#879).
      *
@@ -209,6 +226,9 @@ export class LogWriter {
             ...(issue.prUrl != null && {
                 prUrl: issue.prUrl,
             }),
+            ...(issue.specRecommendation != null && {
+                specRecommendation: issue.specRecommendation,
+            }),
         };
         this.runLog.issues.push(issueLog);
         // Clean up from activeIssues map

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

@@ -41,6 +41,7 @@ export declare const FailureCategorySchema: z.ZodEnum<{
     build_error: "build_error";
     rate_limit: "rate_limit";
     billing: "billing";
+    pr_creation: "pr_creation";
 }>;
 export type FailureCategory = z.infer<typeof FailureCategorySchema>;
 /**
@@ -48,12 +49,12 @@ export type FailureCategory = z.infer<typeof FailureCategorySchema>;
  */
 export declare const MetricPhaseSchema: z.ZodEnum<{
     exec: "exec";
-    qa: "qa";
-    loop: "loop";
     spec: "spec";
     "security-review": "security-review";
     testgen: "testgen";
     test: "test";
+    qa: "qa";
+    loop: "loop";
 }>;
 export type MetricPhase = z.infer<typeof MetricPhaseSchema>;
 /**
@@ -86,12 +87,12 @@ export declare const MetricRunSchema: z.ZodObject<{
     issues: z.ZodArray<z.ZodNumber>;
     phases: z.ZodArray<z.ZodEnum<{
         exec: "exec";
-        qa: "qa";
-        loop: "loop";
         spec: "spec";
         "security-review": "security-review";
         testgen: "testgen";
         test: "test";
+        qa: "qa";
+        loop: "loop";
     }>>;
     outcome: z.ZodEnum<{
         success: "success";
@@ -110,7 +111,17 @@ export declare const MetricRunSchema: z.ZodObject<{
         build_error: "build_error";
         rate_limit: "rate_limit";
         billing: "billing";
+        pr_creation: "pr_creation";
     }>>;
+    phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        model: z.ZodOptional<z.ZodString>;
+        effort: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        phase: z.ZodString;
+        base: z.ZodString;
+        escalated: z.ZodString;
+    }, z.core.$strip>>>;
     metrics: z.ZodObject<{
         tokensUsed: z.ZodNumber;
         filesChanged: z.ZodNumber;
@@ -136,12 +147,12 @@ export declare const MetricsSchema: z.ZodObject<{
         issues: z.ZodArray<z.ZodNumber>;
         phases: z.ZodArray<z.ZodEnum<{
             exec: "exec";
-            qa: "qa";
-            loop: "loop";
             spec: "spec";
             "security-review": "security-review";
             testgen: "testgen";
             test: "test";
+            qa: "qa";
+            loop: "loop";
         }>>;
         outcome: z.ZodEnum<{
             success: "success";
@@ -160,7 +171,17 @@ export declare const MetricsSchema: z.ZodObject<{
             build_error: "build_error";
             rate_limit: "rate_limit";
             billing: "billing";
+            pr_creation: "pr_creation";
         }>>;
+        phasePolicies: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            model: z.ZodOptional<z.ZodString>;
+            effort: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        effortEscalations: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            phase: z.ZodString;
+            base: z.ZodString;
+            escalated: z.ZodString;
+        }, z.core.$strip>>>;
         metrics: z.ZodObject<{
             tokensUsed: z.ZodNumber;
             filesChanged: z.ZodNumber;
@@ -193,6 +214,28 @@ export declare function createMetricRun(options: {
     model?: string;
     flags?: string[];
     failureCategory?: FailureCategory;
+    /**
+     * Resolved per-phase model/effort overrides (#914), 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.
+     */
+    phasePolicies?: Record<string, {
+        model?: string;
+        effort?: string;
+    }>;
+    /**
+     * Effort escalations applied during this run (#915), one entry per
+     * escalated phase execution. Pass only executions that actually escalated
+     * — see `MetricRunSchema.effortEscalations`'s doc comment for why this is
+     * a sibling array rather than an extension of `phasePolicies`.
+     */
+    effortEscalations?: Array<{
+        phase: string;
+        base: string;
+        escalated: string;
+    }>;
     metrics?: Partial<RunMetrics>;
 }): MetricRun;
 /**

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

@@ -96,6 +96,33 @@ export const MetricRunSchema = z.object({
      * existed (additive — no `version` bump required).
      */
     failureCategory: FailureCategorySchema.optional(),
+    /**
+     * Resolved per-phase `model`/`effort` overrides (#914), keyed by phase
+     * name. Only phases with a configured override get an entry — a phase
+     * that inherited the CLI default is omitted entirely, not recorded with
+     * 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.
+     */
+    phasePolicies: z
+        .record(z.string(), z.object({ model: z.string().optional(), effort: z.string().optional() }))
+        .optional(),
+    /**
+     * Effort escalations applied during this run (#915), one entry per
+     * escalated phase execution — distinct from `phasePolicies`, which is a
+     * flat phase→policy map recorded once per run and can't express a value
+     * that changes per retry. Only populated when at least one execution
+     * escalated; omitted entirely (not an empty array) otherwise, matching
+     * `phasePolicies`'s omit-when-empty convention. Phase names and enum
+     * effort strings only, consistent with this schema's privacy contract.
+     */
+    effortEscalations: z
+        .array(z.object({
+        phase: z.string(),
+        base: z.string(),
+        escalated: z.string(),
+    }))
+        .optional(),
     /** Aggregate metrics */
     metrics: RunMetricsSchema,
 });
@@ -137,6 +164,12 @@ export function createMetricRun(options) {
         model: options.model ?? "unknown",
         flags: options.flags ?? [],
         failureCategory: options.failureCategory,
+        ...(options.phasePolicies && Object.keys(options.phasePolicies).length > 0
+            ? { phasePolicies: options.phasePolicies }
+            : {}),
+        ...(options.effortEscalations && options.effortEscalations.length > 0
+            ? { effortEscalations: options.effortEscalations }
+            : {}),
         metrics: {
             tokensUsed: options.metrics?.tokensUsed ?? 0,
             filesChanged: options.metrics?.filesChanged ?? 0,

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

@@ -70,6 +70,17 @@ export declare class MetricsWriter {
         model?: string;
         flags?: string[];
         failureCategory?: FailureCategory;
+        /** Resolved per-phase model/effort overrides (#914). See `createMetricRun`. */
+        phasePolicies?: Record<string, {
+            model?: string;
+            effort?: string;
+        }>;
+        /** Effort escalations applied during this run (#915). See `createMetricRun`. */
+        effortEscalations?: Array<{
+            phase: string;
+            base: string;
+            escalated: string;
+        }>;
         metrics?: Partial<RunMetrics>;
     }): Promise<MetricRun>;
     /**

package/dist/src/lib/workflow/phase-detection.d.ts

@@ -11,6 +11,18 @@
  * ```
  */
 import { type Phase, type PhaseMarker } from "./state-schema.js";
+/**
+ * Strip markdown code blocks and inline code from text.
+ * This prevents phase markers inside code examples from being parsed.
+ *
+ * Exported for reuse by `spec-recommendation.ts` (#921), which applies the
+ * same code-fence stripping to the `SEQUANT_SPEC` marker so documentation
+ * examples embedding that marker can't false-positive either.
+ *
+ * @param text - The text to strip code from
+ * @returns Text with code blocks and inline code removed
+ */
+export declare function stripMarkdownCode(text: string): string;
 /**
  * Format a phase marker as an HTML comment string for embedding in GitHub comments.
  *

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

@@ -25,10 +25,14 @@ const INLINE_CODE_REGEX = /`[^`\n]+`/g;
  * Strip markdown code blocks and inline code from text.
  * This prevents phase markers inside code examples from being parsed.
  *
+ * Exported for reuse by `spec-recommendation.ts` (#921), which applies the
+ * same code-fence stripping to the `SEQUANT_SPEC` marker so documentation
+ * examples embedding that marker can't false-positive either.
+ *
  * @param text - The text to strip code from
  * @returns Text with code blocks and inline code removed
  */
-function stripMarkdownCode(text) {
+export function stripMarkdownCode(text) {
     // First remove fenced code blocks (multi-line)
     let result = text.replace(FENCED_CODE_BLOCK_REGEX, "");
     // Then remove inline code

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

@@ -1032,6 +1032,12 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
     const eligibleHandle = resumeHandle && driver.canResume(resumeHandle, cwd)
         ? resumeHandle
         : undefined;
+    // #914: resolved per-phase model/effort, if this phase has one. Both
+    // ExecutionConfig producers (buildExecutionConfig, ready-gate.ts's
+    // buildPhaseConfig) populate `phasePolicies` the same way, so this is the
+    // single site that turns it into driver-facing fields — see the doc
+    // comment on ExecutionConfig.phasePolicies.
+    const phasePolicy = config.phasePolicies?.[phase];
     // Build AgentExecutionConfig for the driver
     const agentConfig = {
         cwd,
@@ -1043,6 +1049,10 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         resumeHandle: eligibleHandle,
         sessionId: eligibleHandle?.token,
         files,
+        ...(phasePolicy?.model ? { model: phasePolicy.model } : {}),
+        ...(phasePolicy?.effort
+            ? { effort: phasePolicy.effort }
+            : {}),
         onOutput: config.verbose || reportActivity
             ? (text) => {
                 if (config.verbose) {

package/dist/src/lib/workflow/ready-gate.d.ts

@@ -22,6 +22,7 @@
  * lives in `src/commands/ready.ts`.
  */
 import type { ExecutionConfig, PhaseResult, ProgressCallback } from "./types.js";
+import { type EscalationRecord } from "./effort-escalation.js";
 import type { QaVerdict } from "./run-log-schema.js";
 import type { ReadyPolicy } from "../settings.js";
 import type { IssueStatus } from "./state-schema.js";
@@ -90,6 +91,12 @@ export interface ReadyResult {
     tokensUsed: number;
     /** Human-readable markdown gap report (AC-4). */
     report: string;
+    /**
+     * Effort escalations applied during this gate's QA-pass loop (#915),
+     * base+escalated tier per escalated `qa`/`loop` dispatch. Empty when
+     * `effortEscalation` is off or no dispatch escalated.
+     */
+    effortEscalations: EscalationRecord[];
 }
 /**
  * Thin phase-runner abstraction so the engine can be unit-tested without the
@@ -127,6 +134,27 @@ export interface RunReadyGateOptions {
     classifyChangesFn?: (cwd: string) => ExecChangeState;
     /** Injectable loop-progress snapshot — defaults to {@link snapshotLoopProgress}. */
     snapshotFn?: (cwd: string) => LoopProgressSnapshot;
+    /**
+     * Resolved per-phase `model`/`effort` overrides (#914), keyed by phase
+     * name. Callers (e.g. `commands/ready.ts`) resolve this via
+     * `resolvePhasePolicies` — the same shared resolver `buildExecutionConfig`
+     * uses — so this producer cannot drift from that one (#833 class).
+     * `buildPhaseConfig` spreads it onto every `ExecutionConfig` it builds;
+     * `phase-executor.ts` applies the entry for the phase actually running.
+     */
+    phasePolicies?: Record<string, {
+        model?: string;
+        effort?: string;
+    }>;
+    /**
+     * Evidence-based effort escalation on quality-loop retries (#915). Callers
+     * (e.g. `commands/ready.ts`) resolve this CLI > settings > `false`, the same
+     * precedence `buildExecutionConfig` uses for the `run` path (#833 class).
+     * `buildPhaseConfig` spreads it onto every `ExecutionConfig` it builds;
+     * `withEscalatedEffort` (`effort-escalation.ts`) reads it at each QA-pass
+     * dispatch to decide whether that specific `qa`/`loop` call escalates.
+     */
+    effortEscalation?: boolean;
 }
 /**
  * Pure exit predicate. Given a policy and a QA verdict, has the loop reached

package/dist/src/lib/workflow/ready-gate.js

@@ -21,6 +21,7 @@
  * (out of scope for #683) can reuse `runReadyGate` directly. The command shell
  * lives in `src/commands/ready.ts`.
  */
+import { withEscalatedEffort, } from "./effort-escalation.js";
 import { snapshotLoopProgress, compareLoopProgress, } from "./qa-stagnation.js";
 import { classifyExecChanges } from "./phase-executor.js";
 import { readTokenUsageFiles, aggregateTokenUsage, TOKEN_USAGE_DIR, } from "./token-utils.js";
@@ -167,6 +168,11 @@ function buildPhaseConfig(opts, extra) {
         dryRun: false,
         mcp: opts.mcp,
         retry: true,
+        // #914: producer 2 (see the doc comment on RunReadyGateOptions.phasePolicies
+        // for why this can't drift from buildExecutionConfig's own assignment).
+        phasePolicies: opts.phasePolicies,
+        // #915: producer 2 (see RunReadyGateOptions.effortEscalation).
+        effortEscalation: opts.effortEscalation,
         ...extra,
     };
 }
@@ -268,6 +274,9 @@ export async function runReadyGate(opts) {
     const autoFixed = [];
     let remaining = [];
     let tokensUsed = 0;
+    // #915: escalated (base, escalated) tiers, one entry per QA-pass dispatch
+    // that actually escalated. Populated at the two dispatch sites below.
+    const effortEscalations = [];
     const finish = (reason) => {
         const ready = reason === "AC_MET" || reason === "READY_FOR_MERGE";
         const issueStatus = ready
@@ -285,6 +294,7 @@ export async function runReadyGate(opts) {
             remaining,
             tokensUsed,
             report: "",
+            effortEscalations,
         };
         result.report = formatReadyReport(result);
         return result;
@@ -299,7 +309,12 @@ export async function runReadyGate(opts) {
             return finish("TOKEN_BUDGET");
         }
         iterations++;
-        const qaResult = await runPhaseTracked("qa", buildPhaseConfig(opts, { fullQa: true }), iterations);
+        // #915: iterations > 1 means this QA pass is a retry of a prior
+        // unsatisfied verdict — the ready-gate's retry signal.
+        const qaEscalation = withEscalatedEffort(buildPhaseConfig(opts, { fullQa: true }), "qa", iterations > 1);
+        if (qaEscalation.record)
+            effortEscalations.push(qaEscalation.record);
+        const qaResult = await runPhaseTracked("qa", qaEscalation.config, iterations);
         tokensUsed = readTokensUsed(worktreePath);
         const verdict = qaResult.verdict ?? null;
         // #534 guard: a null verdict is never "ready". #853: report it as
@@ -343,11 +358,17 @@ export async function runReadyGate(opts) {
             .filter((g) => !g.nonGoal)
             .map((g) => g.description);
         const before = snapshotFn(worktreePath);
-        const loopResult = await runPhaseTracked("loop", buildPhaseConfig(opts, {
+        // #915: iterations > 1 means this fix pass follows a QA pass that was
+        // itself a retry — the same ready-gate retry signal as the qa dispatch
+        // above.
+        const loopEscalation = withEscalatedEffort(buildPhaseConfig(opts, {
             lastVerdict: verdict,
             failedAcs: fixableGaps.join("; ") || undefined,
             promptContext: buildLoopContext(policy, verdict, fixableGaps),
-        }), iterations);
+        }), "loop", iterations > 1);
+        if (loopEscalation.record)
+            effortEscalations.push(loopEscalation.record);
+        const loopResult = await runPhaseTracked("loop", loopEscalation.config, iterations);
         tokensUsed = readTokensUsed(worktreePath);
         if (!loopResult.success) {
             return finish("LOOP_FAILED");

package/dist/src/lib/workflow/run-log-schema.d.ts

@@ -48,6 +48,37 @@ export declare const QaVerdictSchema: z.ZodEnum<{
     NEEDS_VERIFICATION: "NEEDS_VERIFICATION";
 }>;
 export type QaVerdict = z.infer<typeof QaVerdictSchema>;
+/**
+ * Source that produced the resolved spec→run phase recommendation (#921).
+ *
+ * Ordered by resolution priority: a durable structured marker in the spec's
+ * GitHub comment beats the same comment's prose section, which beats the
+ * spec agent's ephemeral chat text, which beats label-based guessing.
+ */
+export declare const SpecRecommendationSourceSchema: z.ZodEnum<{
+    marker: "marker";
+    "comment-prose": "comment-prose";
+    chat: "chat";
+    "label-fallback": "label-fallback";
+}>;
+export type SpecRecommendationSource = z.infer<typeof SpecRecommendationSourceSchema>;
+/**
+ * Resolved spec→run phase recommendation, recorded on the issue log so
+ * fallback frequency is auditable (#921 AC-4). Additive/optional — absent on
+ * runs that never reached spec resolution (e.g. spec failed) or predate this
+ * field, keeping the persisted-log schema stable at `version: 1`.
+ */
+export declare const SpecRecommendationSchema: z.ZodObject<{
+    source: z.ZodEnum<{
+        marker: "marker";
+        "comment-prose": "comment-prose";
+        chat: "chat";
+        "label-fallback": "label-fallback";
+    }>;
+    phases: z.ZodArray<z.ZodString>;
+    qualityLoop: z.ZodBoolean;
+}, z.core.$strip>;
+export type SpecRecommendation = z.infer<typeof SpecRecommendationSchema>;
 /**
  * File diff statistics for a single file (AC-3)
  */
@@ -91,6 +122,7 @@ export declare const ErrorContextSchema: z.ZodObject<{
         build_error: "build_error";
         rate_limit: "rate_limit";
         billing: "billing";
+        pr_creation: "pr_creation";
     }>;
     errorType: z.ZodOptional<z.ZodString>;
     errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -174,6 +206,7 @@ export declare const PhaseLogSchema: z.ZodObject<{
             build_error: "build_error";
             rate_limit: "rate_limit";
             billing: "billing";
+            pr_creation: "pr_creation";
         }>;
         errorType: z.ZodOptional<z.ZodString>;
         errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -253,6 +286,7 @@ export declare const IssueLogSchema: z.ZodObject<{
                 build_error: "build_error";
                 rate_limit: "rate_limit";
                 billing: "billing";
+                pr_creation: "pr_creation";
             }>;
             errorType: z.ZodOptional<z.ZodString>;
             errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -264,6 +298,16 @@ export declare const IssueLogSchema: z.ZodObject<{
     abortReason: z.ZodOptional<z.ZodString>;
     prNumber: z.ZodOptional<z.ZodNumber>;
     prUrl: z.ZodOptional<z.ZodString>;
+    specRecommendation: z.ZodOptional<z.ZodObject<{
+        source: z.ZodEnum<{
+            marker: "marker";
+            "comment-prose": "comment-prose";
+            chat: "chat";
+            "label-fallback": "label-fallback";
+        }>;
+        phases: z.ZodArray<z.ZodString>;
+        qualityLoop: z.ZodBoolean;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type IssueLog = z.infer<typeof IssueLogSchema>;
 /**
@@ -377,6 +421,7 @@ export declare const RunLogSchema: z.ZodObject<{
                     build_error: "build_error";
                     rate_limit: "rate_limit";
                     billing: "billing";
+                    pr_creation: "pr_creation";
                 }>;
                 errorType: z.ZodOptional<z.ZodString>;
                 errorMetadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -388,6 +433,16 @@ export declare const RunLogSchema: z.ZodObject<{
         abortReason: z.ZodOptional<z.ZodString>;
         prNumber: z.ZodOptional<z.ZodNumber>;
         prUrl: z.ZodOptional<z.ZodString>;
+        specRecommendation: z.ZodOptional<z.ZodObject<{
+            source: z.ZodEnum<{
+                marker: "marker";
+                "comment-prose": "comment-prose";
+                chat: "chat";
+                "label-fallback": "label-fallback";
+            }>;
+            phases: z.ZodArray<z.ZodString>;
+            qualityLoop: z.ZodBoolean;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     summary: z.ZodObject<{
         totalIssues: z.ZodNumber;