sequant 2.10.0 → 2.12.0

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/mutation-marker.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Parseable mutation-verification markers for `/qa` §6i (#939).
+ *
+ * CLAUDE.md's testing rule ("Gate tests ship with a recorded mutation
+ * result") was honor-system prose — nothing parsed or checked the recorded
+ * result, so compliance was invisible (see #830, #834's "prose only, and
+ * therefore unenforceable" defect class). This module promotes that record
+ * to a parseable PR-body marker:
+ *
+ * ```
+ * <!-- SEQUANT_MUTATION: {"ac":"AC-3","mutation":"removed payload fixture
+ * block","failedTest":"injection.test.ts > rejects payload"} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts) and
+ * `SEQUANT_PHASE` (phase-detection.ts): a flat-JSON HTML comment, matched
+ * with the `{[^}]+}` regex family. That regex stops at the FIRST `}`, so the
+ * payload must stay flat — a nested object would truncate mid-JSON and fail
+ * to parse. Unlike those two markers (one recommendation / one status per
+ * comment, latest-wins), a PR body carries one `SEQUANT_MUTATION` marker per
+ * AC, so all markers are collected, not just the latest.
+ */
+import { z } from "zod";
+declare const MutationMarkerSchema: z.ZodObject<{
+    ac: z.ZodString;
+    mutation: z.ZodString;
+    failedTest: z.ZodString;
+}, z.core.$strip>;
+export type MutationMarker = z.infer<typeof MutationMarkerSchema>;
+export type MutationMarkerClassification = "valid" | "test_not_in_diff";
+export interface ClassifiedMutationMarker extends MutationMarker {
+    classification: MutationMarkerClassification;
+}
+/**
+ * Parse every `SEQUANT_MUTATION` marker from a PR body.
+ *
+ * Markers inside fenced code blocks or inline code (e.g. a doc example
+ * showing the marker format) are ignored, matching `parsePhaseMarkers`.
+ * Malformed JSON or schema-invalid entries are skipped silently rather than
+ * thrown — one bad marker must not take down the rest of the PR body's
+ * markers.
+ *
+ * Called with just `prBody`, this only parses. Given a second argument —
+ * the diff's test-file paths — it also **rejects** markers naming a test
+ * absent from the diff, attaching a `classification` to each result rather
+ * than silently dropping the rejected ones (a fabricated marker is worse
+ * than a missing one; it must be visible, not discarded). The two-argument
+ * form is what makes this function itself the rejecting entry point AC-3
+ * names, while the one-argument form stays free of a git-diff dependency
+ * for parser-only tests.
+ *
+ * @param prBody - The full PR body text
+ * @param diffTestFiles - When provided, test file paths present in the PR's
+ *   diff; each returned marker is classified against them
+ * @returns Every valid marker found, in document order — classified when
+ *   `diffTestFiles` is provided
+ */
+export declare function parseMutationMarkers(prBody: string): MutationMarker[];
+export declare function parseMutationMarkers(prBody: string, diffTestFiles: string[]): ClassifiedMutationMarker[];
+/**
+ * Reduce a marker list to one-per-AC, the later marker winning.
+ *
+ * A re-run's marker (e.g. after amending the PR body) supersedes the
+ * earlier one for the same AC — the same "latest wins" idiom
+ * `resolveSpecRecommendation` uses for `SEQUANT_SPEC`.
+ *
+ * @param markers - Markers as returned by {@link parseMutationMarkers}
+ * @returns Map keyed by AC id, one marker per key
+ */
+export declare function latestMutationMarkerPerAc(markers: MutationMarker[]): Map<string, MutationMarker>;
+/**
+ * Classify a marker's `failedTest` against the diff's actual test files.
+ *
+ * A fabricated marker (naming a test that doesn't exist in the diff) is
+ * worse than a missing one — it claims verification that never happened.
+ * `failedTest` follows the `<file> > <test name>` shape `/qa` §6i renders
+ * in its output table (e.g. `injection.test.ts > rejects payload`); only
+ * the file segment is checked, since the suite/test-name portion after
+ * ` > ` isn't independently verifiable without executing the test.
+ *
+ * @param marker - A single parsed marker
+ * @param diffTestFiles - Test file paths present in the PR's diff
+ * @returns `"valid"` when the named file is in the diff, `"test_not_in_diff"` otherwise
+ */
+export declare function classifyMutationMarker(marker: MutationMarker, diffTestFiles: string[]): MutationMarkerClassification;
+export {};

package/dist/src/lib/workflow/mutation-marker.js

@@ -0,0 +1,97 @@
+/**
+ * Parseable mutation-verification markers for `/qa` §6i (#939).
+ *
+ * CLAUDE.md's testing rule ("Gate tests ship with a recorded mutation
+ * result") was honor-system prose — nothing parsed or checked the recorded
+ * result, so compliance was invisible (see #830, #834's "prose only, and
+ * therefore unenforceable" defect class). This module promotes that record
+ * to a parseable PR-body marker:
+ *
+ * ```
+ * <!-- SEQUANT_MUTATION: {"ac":"AC-3","mutation":"removed payload fixture
+ * block","failedTest":"injection.test.ts > rejects payload"} -->
+ * ```
+ *
+ * Same durable-marker idiom as `SEQUANT_SPEC` (spec-recommendation.ts) and
+ * `SEQUANT_PHASE` (phase-detection.ts): a flat-JSON HTML comment, matched
+ * with the `{[^}]+}` regex family. That regex stops at the FIRST `}`, so the
+ * payload must stay flat — a nested object would truncate mid-JSON and fail
+ * to parse. Unlike those two markers (one recommendation / one status per
+ * comment, latest-wins), a PR body carries one `SEQUANT_MUTATION` marker per
+ * AC, so all markers are collected, not just the latest.
+ */
+import { z } from "zod";
+import { stripMarkdownCode } from "./phase-detection.js";
+/** Regex to extract mutation-verification marker JSON from HTML comments. */
+const MUTATION_MARKER_REGEX = /<!-- SEQUANT_MUTATION: (\{[^}]+\}) -->/g;
+const MutationMarkerSchema = z.object({
+    ac: z.string().min(1),
+    mutation: z.string().min(1),
+    failedTest: z.string().min(1),
+});
+function parseMarkersRaw(prBody) {
+    const markers = [];
+    const stripped = stripMarkdownCode(prBody);
+    MUTATION_MARKER_REGEX.lastIndex = 0;
+    let match;
+    while ((match = MUTATION_MARKER_REGEX.exec(stripped)) !== null) {
+        let parsed;
+        try {
+            parsed = JSON.parse(match[1]);
+        }
+        catch {
+            continue;
+        }
+        const result = MutationMarkerSchema.safeParse(parsed);
+        if (result.success) {
+            markers.push(result.data);
+        }
+    }
+    return markers;
+}
+export function parseMutationMarkers(prBody, diffTestFiles) {
+    const markers = parseMarkersRaw(prBody);
+    if (diffTestFiles === undefined) {
+        return markers;
+    }
+    return markers.map((marker) => ({
+        ...marker,
+        classification: classifyMutationMarker(marker, diffTestFiles),
+    }));
+}
+/**
+ * Reduce a marker list to one-per-AC, the later marker winning.
+ *
+ * A re-run's marker (e.g. after amending the PR body) supersedes the
+ * earlier one for the same AC — the same "latest wins" idiom
+ * `resolveSpecRecommendation` uses for `SEQUANT_SPEC`.
+ *
+ * @param markers - Markers as returned by {@link parseMutationMarkers}
+ * @returns Map keyed by AC id, one marker per key
+ */
+export function latestMutationMarkerPerAc(markers) {
+    const byAc = new Map();
+    for (const marker of markers) {
+        byAc.set(marker.ac, marker);
+    }
+    return byAc;
+}
+/**
+ * Classify a marker's `failedTest` against the diff's actual test files.
+ *
+ * A fabricated marker (naming a test that doesn't exist in the diff) is
+ * worse than a missing one — it claims verification that never happened.
+ * `failedTest` follows the `<file> > <test name>` shape `/qa` §6i renders
+ * in its output table (e.g. `injection.test.ts > rejects payload`); only
+ * the file segment is checked, since the suite/test-name portion after
+ * ` > ` isn't independently verifiable without executing the test.
+ *
+ * @param marker - A single parsed marker
+ * @param diffTestFiles - Test file paths present in the PR's diff
+ * @returns `"valid"` when the named file is in the diff, `"test_not_in_diff"` otherwise
+ */
+export function classifyMutationMarker(marker, diffTestFiles) {
+    const namedFile = marker.failedTest.split(">")[0]?.trim() ?? "";
+    const found = diffTestFiles.some((file) => file === namedFile || file.endsWith(`/${namedFile}`));
+    return found ? "valid" : "test_not_in_diff";
+}

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.d.ts

@@ -225,6 +225,15 @@ export declare function endedWithoutVerdict(output: string | undefined): boolean
  * @internal Exported for testing only
  */
 export declare function parseQaSummary(output: string): QaSummary | null;
+/**
+ * Select the gap descriptions from a QA summary appropriate to feed a fix
+ * loop (#937 AC-3): every gap, except one whose `SEQUANT_QA_GAPS` finding is
+ * explicitly marked `document` or `pause_for_human` — those are QA-real but
+ * not code-fixable (quality/polish, or a decision the loop can't make on its
+ * own). A gap with no matching finding (the legacy prose-scrape path) is
+ * always included, unchanged from pre-#937 behavior.
+ */
+export declare function selectFixableGaps(summary: QaSummary | null | undefined): string[];
 /**
  * Format duration in human-readable format
  */
@@ -341,6 +350,14 @@ export declare function mapAgentFailureToPhaseResult(phase: Phase, agentResult:
     sessionId?: string;
     resumeHandle?: ResumeHandle;
 };
+/**
+ * Marks the embedded `promptContext` block appended below so a phase's own
+ * skill (e.g. `/loop`) can detect it deterministically instead of pattern-
+ * matching prose that varies per producer (`ready-gate.ts` and
+ * `batch-executor.ts` build differently-worded context for the same slot).
+ * See #960.
+ */
+export declare const PROMPT_CONTEXT_SENTINEL = "SEQUANT_PROMPT_CONTEXT";
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.

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

@@ -10,6 +10,7 @@
 import chalk from "chalk";
 import { execFileSync } from "child_process";
 import { resolveDiffBase } from "./git-diff-utils.js";
+import { parseQaGapsMarker } from "./qa-gaps-marker.js";
 import { readAgentsMd } from "../agents-md.js";
 import { getDriver } from "./drivers/index.js";
 import { classifyError } from "./error-classifier.js";
@@ -499,9 +500,43 @@ export function parseQaSummary(output) {
     }
     if (acTotal === 0)
         return null;
-    const gaps = parseListSection(output, /\*\*(?:Issues|Gaps)/);
+    const proseGaps = parseListSection(output, /\*\*(?:Issues|Gaps)/);
     const suggestions = parseListSection(output, /\*\*Suggestions/);
-    return { acMet, acTotal, gaps, suggestions };
+    // #937: prefer the structured marker, but UNION with the prose scrape
+    // rather than replace it — a marker-carrying comment can still contain a
+    // gap the model couldn't fit into the six categories (the fallback rule),
+    // and that prose-only finding must not be silently dropped (AC-5).
+    const findings = parseQaGapsMarker(output) ?? undefined;
+    const seen = new Set();
+    const gaps = [];
+    for (const gap of [
+        ...(findings?.map((f) => f.description) ?? []),
+        ...proseGaps,
+    ]) {
+        const key = gap.trim().toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        gaps.push(gap);
+    }
+    return { acMet, acTotal, gaps, suggestions, ...(findings && { findings }) };
+}
+/**
+ * Select the gap descriptions from a QA summary appropriate to feed a fix
+ * loop (#937 AC-3): every gap, except one whose `SEQUANT_QA_GAPS` finding is
+ * explicitly marked `document` or `pause_for_human` — those are QA-real but
+ * not code-fixable (quality/polish, or a decision the loop can't make on its
+ * own). A gap with no matching finding (the legacy prose-scrape path) is
+ * always included, unchanged from pre-#937 behavior.
+ */
+export function selectFixableGaps(summary) {
+    if (!summary)
+        return [];
+    const excluded = new Set((summary.findings ?? [])
+        .filter((f) => f.recommendedAction === "document" ||
+        f.recommendedAction === "pause_for_human")
+        .map((f) => f.description.trim().toLowerCase()));
+    return summary.gaps.filter((g) => !excluded.has(g.trim().toLowerCase()));
 }
 /**
  * Parse a markdown bullet list section, filtering out "None" variants.
@@ -850,6 +885,14 @@ export function mapAgentFailureToPhaseResult(phase, agentResult, durationSeconds
         exitCode: agentResult.exitCode,
     };
 }
+/**
+ * Marks the embedded `promptContext` block appended below so a phase's own
+ * skill (e.g. `/loop`) can detect it deterministically instead of pattern-
+ * matching prose that varies per producer (`ready-gate.ts` and
+ * `batch-executor.ts` build differently-worded context for the same slot).
+ * See #960.
+ */
+export const PROMPT_CONTEXT_SENTINEL = "SEQUANT_PROMPT_CONTEXT";
 /**
  * Get the prompt for a phase with the issue number substituted.
  * Selects self-contained prompts for non-Claude agents.
@@ -867,9 +910,11 @@ export async function getPhasePrompt(phase, issueNumber, agent, promptContext) {
         : undefined;
     const template = driverPrompt ?? definition.promptTemplate;
     let basePrompt = template.replace(/\{issue\}/g, String(issueNumber));
-    // Append phase-specific context (e.g., QA findings for loop phase)
+    // Append phase-specific context (e.g., QA findings for loop phase),
+    // wrapped in a sentinel so the phase's own skill (e.g. /loop) can detect
+    // embedded orchestrator context without re-fetching it from GitHub (#960).
     if (promptContext) {
-        basePrompt += `\n\n---\n\n${promptContext}`;
+        basePrompt += `\n\n---\n\n<!-- ${PROMPT_CONTEXT_SENTINEL} -->\n${promptContext}\n<!-- /${PROMPT_CONTEXT_SENTINEL} -->`;
     }
     // Include AGENTS.md content in the prompt context for non-Claude agent compatibility.
     // Claude reads CLAUDE.md natively, but other agents (Aider, Codex, Gemini CLI)
@@ -1032,6 +1077,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,
@@ -1040,9 +1091,14 @@ async function executePhase(issueNumber, phase, config, resumeHandle, worktreePa
         phaseTimeout: config.phaseTimeout,
         verbose: config.verbose,
         mcp: config.mcp,
+        mcpAllowlist: config.mcpAllowlist,
         resumeHandle: eligibleHandle,
         sessionId: eligibleHandle?.token,
         files,
+        ...(phasePolicy?.model ? { model: phasePolicy.model } : {}),
+        ...(phasePolicy?.effort
+            ? { effort: phasePolicy.effort }
+            : {}),
         onOutput: config.verbose || reportActivity
             ? (text) => {
                 if (config.verbose) {