sequant 2.7.0 → 2.9.0

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

@@ -10,10 +10,11 @@
 import chalk from "chalk";
 import { spawnSync } from "child_process";
 import { createPhaseLogFromTiming } from "./log-writer.js";
-import { classifyError, errorTypeToCategory } from "./error-classifier.js";
+import { classifyError, errorTypeToCategory, } from "./error-classifier.js";
 import { getGitDiffStats, getCommitHash } from "./git-diff-utils.js";
 import { createCheckpointCommit, rebaseBeforePR, createPR, readCacheMetrics, filterResumedPhases, } from "./worktree-manager.js";
 import { executePhaseWithRetry } from "./phase-executor.js";
+import { parseBodyDependencyMarkers } from "./dependency-markers.js";
 import { detectPhasesFromLabels, parseRecommendedWorkflow, determinePhasesForIssue, DOCS_LABELS, } from "./phase-mapper.js";
 import { activateRelay, deactivateRelay, } from "../relay/activation.js";
 /**
@@ -137,17 +138,13 @@ export function parseDependencies(issueNumber) {
             return [];
         const data = JSON.parse(result.stdout.toString());
         const dependencies = [];
-        // Parse from body: "Depends on: #123" or "**Depends on**: #123"
+        // Parse from body: line-leading "Depends on: #123" / "**Depends on**: #123".
+        // Delegates to the shared, hardened parser (#767): mid-sentence prose,
+        // in-fence examples, and inline-code mentions are ignored, and the `#` is
+        // required. Honors ONLY `depends on` — the sorter must not start reordering
+        // on `blocked by`, which would be a new silent-reorder class (#762 Open Q #3).
         if (data.body) {
-            const bodyMatch = data.body.match(/\*?\*?depends\s+on\*?\*?:?\s*#?(\d+)/gi);
-            if (bodyMatch) {
-                for (const match of bodyMatch) {
-                    const numMatch = match.match(/(\d+)/);
-                    if (numMatch) {
-                        dependencies.push(parseInt(numMatch[1], 10));
-                    }
-                }
-            }
+            dependencies.push(...parseBodyDependencyMarkers(data.body, ["depends on"]));
         }
         // Parse from labels: "depends-on/123" or "depends-on-123"
         if (data.labels && Array.isArray(data.labels)) {
@@ -305,6 +302,27 @@ export async function executeBatch(issueNumbers, batchCtx) {
     }
     return results;
 }
+/**
+ * Derive the bounded-enum failure category for a failed issue (#761 AC-7).
+ *
+ * Scans for the LAST non-loop failing phase — the same reverse scan
+ * `toIssueSummary` uses (#766), so the recorded category and the displayed
+ * failure reason describe the same attempt. Prefers the driver's structured
+ * cause over stderr-regex classification (#732). Returns only the enum value;
+ * message strings never leave this function (metrics privacy contract).
+ *
+ * @internal Exported for testing
+ */
+export function deriveFailureCategory(phaseResults) {
+    const failedPhase = [...phaseResults]
+        .reverse()
+        .find((p) => !p.success && p.phase !== "loop");
+    if (!failedPhase)
+        return undefined;
+    const typedError = failedPhase.structuredError ??
+        classifyError(failedPhase.stderrTail ?? [], failedPhase.exitCode);
+    return errorTypeToCategory(typedError);
+}
 export async function runIssueWithLogging(ctx) {
     // Destructure context for use throughout the function
     const { issueNumber, config, options, title: issueTitle, labels, services: { logWriter, stateManager, shutdownManager }, worktree, chain, packageManager, baseBranch, onProgress, onPhasePlan, phasePauseHandle, } = ctx;
@@ -432,7 +450,17 @@ export async function runIssueWithLogging(ctx) {
             }
         }
         else {
-            const extra = { error: specResult.error ?? "unknown" };
+            // Mirror the main phase loop (#739): a turn-capped spec phase surfaces the
+            // distinct "partial output preserved" signal rather than a generic failure
+            // reason, so the cap is recognizable on the spec path too (it has its own
+            // failure handling, separate from the main loop). The partial output is
+            // preserved in `phaseResults` (pushed above) and the run still halts via
+            // the early return below.
+            const extra = {
+                error: specResult.capped
+                    ? "turn cap reached — partial output preserved (resume to continue)"
+                    : (specResult.error ?? "unknown"),
+            };
             emitProgressLine(issueNumber, "spec", "failed", extra);
             try {
                 onProgress?.(issueNumber, "spec", "failed", extra);
@@ -444,10 +472,13 @@ export async function runIssueWithLogging(ctx) {
         // Log spec phase result
         // Note: Spec runs in main repo, not worktree, so no git diff stats
         if (logWriter) {
-            // Build errorContext from captured stderr/stdout tails (#447)
+            // Build errorContext from captured stderr/stdout tails (#447). Prefer
+            // the driver's structured cause (#761 AC-6) — stderr-regex
+            // classification never sees the SDK's rate-limit/billing signals.
             let specErrorContext;
             if (!specResult.success && specResult.stderrTail) {
-                const specError = classifyError(specResult.stderrTail ?? [], specResult.exitCode);
+                const specError = specResult.structuredError ??
+                    classifyError(specResult.stderrTail ?? [], specResult.exitCode);
                 specErrorContext = {
                     stderrTail: specResult.stderrTail ?? [],
                     stdoutTail: specResult.stdoutTail ?? [],
@@ -462,7 +493,13 @@ export async function runIssueWithLogging(ctx) {
                 ? "success"
                 : specResult.error?.includes("Timeout")
                     ? "timeout"
-                    : "failure", { error: specResult.error, errorContext: specErrorContext });
+                    : "failure", {
+                error: specResult.error,
+                // Mark a turn-capped spec phase distinctly in the log (#739), matching
+                // the main phase loop: status stays "failure" but `capped` flags it.
+                capped: specResult.capped,
+                errorContext: specErrorContext,
+            });
             logWriter.logPhase(phaseLog);
         }
         // Track spec phase completion in state
@@ -471,6 +508,9 @@ export async function runIssueWithLogging(ctx) {
                 const phaseStatus = specResult.success ? "completed" : "failed";
                 await stateManager.updatePhaseStatus(issueNumber, "spec", phaseStatus, {
                     error: specResult.error,
+                    // Mark a turn-capped spec halt distinctly in state (#739), matching
+                    // the run-log marker — status stays "failed", `capped` flags it.
+                    capped: specResult.capped,
                 });
             }
             catch {
@@ -499,6 +539,7 @@ export async function runIssueWithLogging(ctx) {
                 phaseResults,
                 durationSeconds,
                 loopTriggered: false,
+                failureCategory: deriveFailureCategory(phaseResults),
             };
         }
         // Parse recommended workflow from spec output
@@ -595,6 +636,10 @@ export async function runIssueWithLogging(ctx) {
     const useQualityLoop = config.qualityLoop || detectedQualityLoop;
     const maxIterations = useQualityLoop ? config.maxIterations : 1;
     let completedSuccessfully = false;
+    // Set when a phase hits its turn cap (#739): halt the outer quality-loop
+    // retry too, not just the inner /loop spawn — re-running a capped phase
+    // would only cap again, and "surface + halt" means the user resumes.
+    let haltedByCap = false;
     while (iteration < maxIterations) {
         iteration++;
         if (useQualityLoop && iteration > 1) {
@@ -655,7 +700,18 @@ export async function runIssueWithLogging(ctx) {
                 }
             }
             else {
-                const extra = { error: result.error ?? "unknown", iteration };
+                // A turn-capped phase is incomplete-but-not-hard-failed (#739): surface a
+                // distinct "partial output preserved" signal instead of a generic failure
+                // reason, so the user knows the run halted on a recoverable cap (and can
+                // resume) rather than on a genuine error. The partial `result.output` is
+                // already preserved in `phaseResults` (pushed above) and the phase log
+                // (`capped` flag below); the run still halts cleanly at the `break` below.
+                const extra = {
+                    error: result.capped
+                        ? "turn cap reached — partial output preserved (resume to continue)"
+                        : (result.error ?? "unknown"),
+                    iteration,
+                };
                 emitProgressLine(issueNumber, phase, "failed", extra);
                 try {
                     onProgress?.(issueNumber, phase, "failed", extra);
@@ -676,10 +732,13 @@ export async function runIssueWithLogging(ctx) {
                     : undefined;
                 // Read cache metrics for QA phase (AC-7)
                 const cacheMetrics = phase === "qa" ? readCacheMetrics(worktreePath) : undefined;
-                // Build errorContext from captured stderr/stdout tails (#447, AC-7/AC-8)
+                // Build errorContext from captured stderr/stdout tails (#447, AC-7/AC-8).
+                // Prefer the driver's structured cause (#761 AC-6) — stderr-regex
+                // classification never sees the SDK's rate-limit/billing signals.
                 let errorContext;
                 if (!result.success && result.stderrTail) {
-                    const typedError = classifyError(result.stderrTail ?? [], result.exitCode);
+                    const typedError = result.structuredError ??
+                        classifyError(result.stderrTail ?? [], result.exitCode);
                     errorContext = {
                         stderrTail: result.stderrTail ?? [],
                         stdoutTail: result.stdoutTail ?? [],
@@ -696,6 +755,9 @@ export async function runIssueWithLogging(ctx) {
                         ? "timeout"
                         : "failure", {
                     error: result.error,
+                    // Mark a turn-capped phase distinctly in the log (#739): status stays
+                    // "failure" (no new enum value) but `capped` flags it as recoverable.
+                    capped: result.capped,
                     verdict: result.verdict,
                     summary: result.summary,
                     // Observability fields (AC-1, AC-2, AC-3, AC-7)
@@ -715,7 +777,13 @@ export async function runIssueWithLogging(ctx) {
                         : result.error?.includes("Timeout")
                             ? "failed"
                             : "failed";
-                    await stateManager.updatePhaseStatus(issueNumber, phase, phaseStatus, { error: result.error });
+                    await stateManager.updatePhaseStatus(issueNumber, phase, phaseStatus, {
+                        error: result.error,
+                        // Mark a turn-capped phase halt distinctly in state (#739),
+                        // matching the run-log marker — status stays "failed",
+                        // `capped` flags it as recoverable for the resume path.
+                        capped: result.capped,
+                    });
                 }
                 catch {
                     // State tracking errors shouldn't stop execution
@@ -726,8 +794,15 @@ export async function runIssueWithLogging(ctx) {
             }
             else {
                 phasesFailed = true;
-                // If quality loop enabled, run loop phase to fix issues
-                if (useQualityLoop && iteration < maxIterations) {
+                if (result.capped) {
+                    haltedByCap = true;
+                }
+                // If quality loop enabled, run loop phase to fix issues.
+                // A turn-capped phase (#739) is incomplete, not a genuine quality
+                // failure: skip the loop and halt cleanly ("surface + halt"). Spawning
+                // /loop on partial output would act on incomplete work — exactly the
+                // risk the capped path is meant to avoid. The user resumes instead.
+                if (useQualityLoop && iteration < maxIterations && !result.capped) {
                     // #624 Item 3 (AC-3.3): the loop phase carries the current outer
                     // iteration so the live-zone status cell can show `loop N/M`.
                     const loopStartExtra = { iteration };
@@ -751,6 +826,23 @@ export async function runIssueWithLogging(ctx) {
                     const loopResult = await executePhaseWithRetry(issueNumber, "loop", withActivityHook(loopConfig, issueNumber, "loop", onProgress), resumeHandle, worktreePath, shutdownManager, phasePauseHandle);
                     const loopEndTime = new Date();
                     phaseResults.push(loopResult);
+                    // #766: record the loop phase in the run log — spec (:655) and the
+                    // regular phases (:982) log via logWriter, but the loop was never
+                    // logged, so a loop that decided the card's verdict was absent from
+                    // the log you'd use to debug it (AC-6). Loop status never determines
+                    // the issue verdict (see deriveIssueLogStatus), but the entry with
+                    // phase/status/duration/error must exist.
+                    if (logWriter) {
+                        const loopPhaseLog = createPhaseLogFromTiming("loop", issueNumber, loopStartTime, loopEndTime, loopResult.success
+                            ? "success"
+                            : loopResult.error?.includes("Timeout")
+                                ? "timeout"
+                                : "failure", {
+                            error: loopResult.error,
+                            capped: loopResult.capped,
+                        });
+                        logWriter.logPhase(loopPhaseLog);
+                    }
                     // Emit loop completion/failure progress event (AC-8)
                     const loopDurationSec = Math.round((loopEndTime.getTime() - loopStartTime.getTime()) / 1000);
                     if (loopResult.success) {
@@ -790,6 +882,11 @@ export async function runIssueWithLogging(ctx) {
             completedSuccessfully = true;
             break;
         }
+        // A turn-capped phase (#739) halts the outer quality-loop retry as well —
+        // re-running would only cap again; the partial work is already preserved.
+        if (haltedByCap) {
+            break;
+        }
         // If we're not in quality loop mode, don't retry
         if (!config.qualityLoop) {
             break;
@@ -809,9 +906,25 @@ export async function runIssueWithLogging(ctx) {
             // State tracking errors shouldn't stop execution
         }
     }
-    // Create checkpoint commit in chain mode after QA passes
+    // Create checkpoint commit in chain mode after QA passes.
+    // #760: chain resume rebases the next link onto this checkpoint, so a failure
+    // here is not silent — warn prominently and record it on the result (AC-4).
+    //
+    // Note the status above is already `ready_for_merge`, so a re-run reads this
+    // link as a completed prefix and does NOT redo it. Its uncommitted work is
+    // therefore absent from the branch tip, which `computeChainResumePlan` detects
+    // (dirty worktree → fail fast) rather than wrong-basing the next link. The
+    // message states that outcome exactly: the work must be committed, or --force.
+    let checkpointFailed = false;
     if (success && chainMode && worktreePath) {
-        createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
+        const checkpointOk = createCheckpointCommit(worktreePath, issueNumber, config.verbose, baseBranch);
+        if (!checkpointOk) {
+            checkpointFailed = true;
+            log(chalk.yellow(`  ⚠️  Checkpoint commit for #${issueNumber} could not be created — its uncommitted ` +
+                `changes are NOT on branch ${branch ?? "the feature branch"}. #${issueNumber} stays ` +
+                `ready_for_merge, so a re-run will skip it and refuse to resume the chain here until the ` +
+                `work is committed in ${worktreePath} (or re-run with --force to redo the whole chain).`));
+        }
     }
     // Rebase onto the base branch before PR creation (unless --no-rebase)
     // This ensures the branch is up-to-date and prevents lockfile drift
@@ -838,7 +951,10 @@ export async function runIssueWithLogging(ctx) {
                 stackManifest: chain.stackManifest,
             }
             : undefined;
-        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions);
+        // #749: surface a non-A+ qa verdict (e.g. AC_MET_BUT_NOT_A_PLUS) in the PR
+        // body so a reviewer sees why the run broke to PR rather than reaching A+.
+        const qaVerdict = phaseResults.find((p) => p.phase === "qa")?.verdict;
+        const prResult = createPR(worktreePath, issueNumber, issueTitle, branch, config.verbose, labels, stackOptions, qaVerdict);
         if (prResult.success && prResult.prNumber && prResult.prUrl) {
             prNumber = prResult.prNumber;
             prUrl = prResult.prUrl;
@@ -881,5 +997,7 @@ export async function runIssueWithLogging(ctx) {
         loopTriggered,
         prNumber,
         prUrl,
+        checkpointFailed,
+        failureCategory: success ? undefined : deriveFailureCategory(phaseResults),
     };
 }

package/dist/src/lib/workflow/chain-preflight.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Lightweight content pre-flight for `--chain` runs (#762).
+ *
+ * Chain flag-validation only checks flag *combinations* (see `run.ts`); nothing
+ * inspects the *content* of the issues being chained. This module adds a fast,
+ * warn-by-default pre-flight that runs before the first worktree is provisioned
+ * and surfaces four cheap content-level problems:
+ *
+ *   1. An issue has no (or an empty) Acceptance Criteria section.
+ *   2. An issue declares a blocker (`blocked by #N` / `depends on #N`) that runs
+ *      *after* it in the CLI order — the order contradicts the declaration.
+ *   3. Two chained issues are predicted to modify the same file, but the CLI
+ *      order contradicts the predicted (ascending) land order.
+ *   4. An issue is CLOSED on GitHub — chaining a closed/merged issue is almost
+ *      certainly unintended.
+ *
+ * The design follows the #604 philosophy: **suggest, never auto-decide**. False
+ * dependency inference is worse than none, so warnings are non-fatal by default;
+ * `--strict-preflight` opts in to a hard stop.
+ *
+ * Overlap prediction is delegated to `assess-collision-detect` (AC-3) rather
+ * than reimplemented. The pure `computePreflightWarnings` function is the unit
+ * surface (AC-1/AC-5); `runChainPreflight` adds the `gh` fetch and warn-degrades
+ * if a fetch fails — the pre-flight must never be the thing that breaks a run.
+ */
+/** The class of content problem a warning describes. */
+export type PreflightWarningKind = "missing-ac" | "dependency-order" | "file-overlap-order" | "closed-issue";
+/** A single content-level pre-flight warning. */
+export interface PreflightWarning {
+    /** Primary issue the warning is attached to. */
+    issue: number;
+    /** The class of problem (one warning per class per AC-1). */
+    kind: PreflightWarningKind;
+    /** Human-readable, ready to print after a `⚠` prefix. */
+    message: string;
+}
+/** Fetched issue content the pure computation operates over. */
+export interface PreflightIssue {
+    number: number;
+    /** Raw issue body markdown. */
+    body: string;
+    /** GitHub issue state, e.g. `"OPEN"` / `"CLOSED"`. */
+    state: string;
+    /** Issue title (for message context). */
+    title: string;
+}
+/**
+ * Parse the issue numbers a body declares itself blocked by / dependent on.
+ * Catches both `depends on #N` and `blocked by #N` (deduped, order-preserving).
+ * Only line-leading markers count as declarations — see the shared
+ * `dependency-markers.ts` parser for why mid-sentence prose mentions are
+ * deliberately ignored.
+ *
+ * The pre-flight honors BOTH markers (unlike `batch-executor.ts`, which honors
+ * only `depends on` so the sorter's ordering semantics stay untouched — #762
+ * Open Q #3). The hardened mechanics are shared; the marker set is per-caller.
+ */
+export declare function parseDeclaredBlockers(body: string): number[];
+/**
+ * Detect whether a body has a non-empty Acceptance Criteria section.
+ *
+ * Fast path reuses `hasAcceptanceCriteria` (ac-parser) so `AC-N:`-prefixed
+ * checklists are recognized directly. The fallback catches AC sections written
+ * as bare checkboxes under an "Acceptance Criteria" heading (e.g. this very
+ * issue, #762) — those are legitimately non-empty AC sections that the
+ * `AC-N:` patterns don't match, and warning on them would be a false positive
+ * (worse than no warning, per #604).
+ */
+export declare function hasNonEmptyAcSection(body: string): boolean;
+/**
+ * Compute chain pre-flight warnings over already-fetched issue content.
+ *
+ * Pure and deterministic — this is the unit-test surface (AC-1/AC-5). Issues
+ * absent from `issues` (e.g. a `gh` fetch failed for them) are silently skipped
+ * so a fetch error degrades to fewer checks rather than aborting the run.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted — see #762 Open Q #1).
+ * @param issues   Map of issue number → fetched content.
+ */
+export declare function computePreflightWarnings(cliOrder: number[], issues: Map<number, PreflightIssue>): PreflightWarning[];
+/**
+ * Run the chain content pre-flight: fetch each issue's body/state/title, then
+ * compute warnings. Fetch failures warn-degrade (a gray note is printed and the
+ * issue's checks are skipped) — the pre-flight never aborts a run on its own.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted).
+ * @returns The list of content warnings (empty when everything looks consistent).
+ */
+export declare function runChainPreflight(cliOrder: number[]): Promise<PreflightWarning[]>;

package/dist/src/lib/workflow/chain-preflight.js

@@ -0,0 +1,199 @@
+/**
+ * Lightweight content pre-flight for `--chain` runs (#762).
+ *
+ * Chain flag-validation only checks flag *combinations* (see `run.ts`); nothing
+ * inspects the *content* of the issues being chained. This module adds a fast,
+ * warn-by-default pre-flight that runs before the first worktree is provisioned
+ * and surfaces four cheap content-level problems:
+ *
+ *   1. An issue has no (or an empty) Acceptance Criteria section.
+ *   2. An issue declares a blocker (`blocked by #N` / `depends on #N`) that runs
+ *      *after* it in the CLI order — the order contradicts the declaration.
+ *   3. Two chained issues are predicted to modify the same file, but the CLI
+ *      order contradicts the predicted (ascending) land order.
+ *   4. An issue is CLOSED on GitHub — chaining a closed/merged issue is almost
+ *      certainly unintended.
+ *
+ * The design follows the #604 philosophy: **suggest, never auto-decide**. False
+ * dependency inference is worse than none, so warnings are non-fatal by default;
+ * `--strict-preflight` opts in to a hard stop.
+ *
+ * Overlap prediction is delegated to `assess-collision-detect` (AC-3) rather
+ * than reimplemented. The pure `computePreflightWarnings` function is the unit
+ * surface (AC-1/AC-5); `runChainPreflight` adds the `gh` fetch and warn-degrades
+ * if a fetch fails — the pre-flight must never be the thing that breaks a run.
+ */
+import { spawnSync } from "child_process";
+import chalk from "chalk";
+import { hasAcceptanceCriteria } from "../ac-parser.js";
+import { extractPathsFromIssueBody, detectFileCollisions, } from "../assess-collision-detect.js";
+import { parseBodyDependencyMarkers } from "./dependency-markers.js";
+/**
+ * Parse the issue numbers a body declares itself blocked by / dependent on.
+ * Catches both `depends on #N` and `blocked by #N` (deduped, order-preserving).
+ * Only line-leading markers count as declarations — see the shared
+ * `dependency-markers.ts` parser for why mid-sentence prose mentions are
+ * deliberately ignored.
+ *
+ * The pre-flight honors BOTH markers (unlike `batch-executor.ts`, which honors
+ * only `depends on` so the sorter's ordering semantics stay untouched — #762
+ * Open Q #3). The hardened mechanics are shared; the marker set is per-caller.
+ */
+export function parseDeclaredBlockers(body) {
+    return parseBodyDependencyMarkers(body, ["depends on", "blocked by"]);
+}
+/**
+ * Detect whether a body has a non-empty Acceptance Criteria section.
+ *
+ * Fast path reuses `hasAcceptanceCriteria` (ac-parser) so `AC-N:`-prefixed
+ * checklists are recognized directly. The fallback catches AC sections written
+ * as bare checkboxes under an "Acceptance Criteria" heading (e.g. this very
+ * issue, #762) — those are legitimately non-empty AC sections that the
+ * `AC-N:` patterns don't match, and warning on them would be a false positive
+ * (worse than no warning, per #604).
+ */
+export function hasNonEmptyAcSection(body) {
+    if (hasAcceptanceCriteria(body))
+        return true;
+    const lines = body.split("\n");
+    let inSection = false;
+    for (const line of lines) {
+        if (/^#{1,6}\s+.*acceptance\s+criteria/i.test(line)) {
+            inSection = true;
+            continue;
+        }
+        // A subsequent heading closes the AC section.
+        if (inSection && /^#{1,6}\s+/.test(line))
+            break;
+        // A checkbox item inside the section proves it is non-empty.
+        if (inSection && /^\s*-\s*\[[x\s]\]/i.test(line))
+            return true;
+    }
+    return false;
+}
+/**
+ * Compute chain pre-flight warnings over already-fetched issue content.
+ *
+ * Pure and deterministic — this is the unit-test surface (AC-1/AC-5). Issues
+ * absent from `issues` (e.g. a `gh` fetch failed for them) are silently skipped
+ * so a fetch error degrades to fewer checks rather than aborting the run.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted — see #762 Open Q #1).
+ * @param issues   Map of issue number → fetched content.
+ */
+export function computePreflightWarnings(cliOrder, issues) {
+    const warnings = [];
+    const positionOf = new Map();
+    cliOrder.forEach((n, i) => positionOf.set(n, i));
+    // Per-issue checks, in CLI order for deterministic output.
+    for (const num of cliOrder) {
+        const issue = issues.get(num);
+        if (!issue)
+            continue;
+        // AC-4: closed/merged issue check (consistent with the #305 state guard).
+        if (issue.state.toUpperCase() === "CLOSED") {
+            warnings.push({
+                issue: num,
+                kind: "closed-issue",
+                message: `#${num} is CLOSED on GitHub — chaining a closed/merged issue is ` +
+                    `likely unintended (consistent with the #305 ready_for_merge/merged ` +
+                    `guard; the #592 in_progress-but-merged gap is not covered here).`,
+            });
+        }
+        // AC-1: missing/empty Acceptance Criteria section.
+        if (!hasNonEmptyAcSection(issue.body)) {
+            warnings.push({
+                issue: num,
+                kind: "missing-ac",
+                message: `#${num} has no non-empty Acceptance Criteria section — the chain ` +
+                    `cannot verify it is ready to implement.`,
+            });
+        }
+        // AC-1: CLI order contradicts a declared dependency marker.
+        for (const blocker of parseDeclaredBlockers(issue.body)) {
+            const blockerPos = positionOf.get(blocker);
+            // Only meaningful if the blocker is itself in this chain.
+            if (blockerPos === undefined)
+                continue;
+            if (blockerPos > positionOf.get(num)) {
+                warnings.push({
+                    issue: num,
+                    kind: "dependency-order",
+                    message: `#${num} declares it is blocked by / depends on #${blocker}, but ` +
+                        `#${blocker} runs AFTER #${num} in the chain order — reorder so ` +
+                        `#${blocker} comes first.`,
+                });
+            }
+        }
+    }
+    // AC-1/AC-3: CLI order contradicts predicted file-overlap order.
+    const issuePaths = new Map();
+    for (const num of cliOrder) {
+        const issue = issues.get(num);
+        if (issue)
+            issuePaths.set(num, extractPathsFromIssueBody(issue.body));
+    }
+    for (const collision of detectFileCollisions(issuePaths)) {
+        // `collision.issues` is ascending issue-number order = the predicted land
+        // order used by /assess. Restrict to issues actually in the chain.
+        const predicted = collision.issues.filter((n) => positionOf.has(n));
+        if (predicted.length < 2)
+            continue;
+        const cliRelative = [...predicted].sort((a, b) => positionOf.get(a) - positionOf.get(b));
+        const contradicts = predicted.some((n, i) => n !== cliRelative[i]);
+        if (contradicts) {
+            warnings.push({
+                issue: predicted[0],
+                kind: "file-overlap-order",
+                message: `#${predicted.join(", #")} are predicted to modify ${collision.file}; ` +
+                    `predicted land order is #${predicted.join(" → #")} but the CLI order ` +
+                    `is #${cliRelative.join(" → #")} — landing out of order risks the ` +
+                    `downstream-staleness class (#133).`,
+            });
+        }
+    }
+    return warnings;
+}
+/**
+ * Fetch a single issue's pre-flight content via `gh`. Returns `null` on any
+ * failure so the caller can warn-degrade (skip that issue's checks) rather than
+ * abort the run.
+ */
+function fetchPreflightIssue(issueNumber) {
+    try {
+        const result = spawnSync("gh", ["issue", "view", String(issueNumber), "--json", "body,state,title"], { stdio: "pipe" });
+        if (result.status !== 0)
+            return null;
+        const data = JSON.parse(result.stdout.toString());
+        return {
+            number: issueNumber,
+            body: typeof data.body === "string" ? data.body : "",
+            state: typeof data.state === "string" ? data.state : "",
+            title: typeof data.title === "string" ? data.title : `Issue #${issueNumber}`,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the chain content pre-flight: fetch each issue's body/state/title, then
+ * compute warnings. Fetch failures warn-degrade (a gray note is printed and the
+ * issue's checks are skipped) — the pre-flight never aborts a run on its own.
+ *
+ * @param cliOrder Raw CLI issue order (NOT dep-sorted).
+ * @returns The list of content warnings (empty when everything looks consistent).
+ */
+export async function runChainPreflight(cliOrder) {
+    const issues = new Map();
+    for (const num of cliOrder) {
+        const fetched = fetchPreflightIssue(num);
+        if (fetched) {
+            issues.set(num, fetched);
+        }
+        else {
+            console.log(chalk.gray(`  (pre-flight: could not fetch #${num} — skipping its content checks)`));
+        }
+    }
+    return computePreflightWarnings(cliOrder, issues);
+}