sequant 2.8.0 → 2.10.0

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);
+}

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

@@ -0,0 +1,118 @@
+/**
+ * Chain resume planning (#760).
+ *
+ * When a `--chain` run fails mid-way, earlier links may already be complete
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
+ * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
+ * should skip that completed prefix and resume at the first incomplete link,
+ * rebased onto the last completed link's committed tip — NOT `main` (which is
+ * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
+ *
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
+ *
+ * The planner is pure over an injected {@link CompletedLinkResolver} so the
+ * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
+ * real-git rebase is covered by the integration test.
+ */
+import { type CompletedIssueStatus } from "./completed-status.js";
+/** A completed link that will be skipped (not re-executed) on resume. */
+export interface ChainResumeSkip {
+    issueNumber: number;
+    /** Why it was skipped — the terminal-ish status that made it complete. */
+    status: CompletedIssueStatus;
+    /** The link's local feature branch (from state), if known. */
+    branch?: string;
+    /** The link's worktree path (from state), if known — used for the dirty check. */
+    worktree?: string;
+}
+/** The computed plan for resuming a partially-completed chain. */
+export interface ChainResumePlan {
+    /** Contiguous completed prefix that will be skipped (not re-executed). */
+    skipped: ChainResumeSkip[];
+    /** Issue numbers to actually execute (the incomplete tail). */
+    active: number[];
+    /**
+     * Local branch (or base ref) the first active link must be provisioned from
+     * and rebased onto. Undefined on a fresh run (no completed prefix).
+     */
+    resumeBase?: string;
+    /** Commit the resume base resolves to — reported so the user sees the point. */
+    resumeBaseCommit?: string;
+    /** First incomplete issue number (the resume point), if any. */
+    resumeIssue?: number;
+    /**
+     * Set when resume cannot proceed safely (AC-3): an unmerged completed link's
+     * (`ready_for_merge` or `waiting_for_human_merge`) branch/checkpoint is gone
+     * and its tip is unreconstructable. The caller must abort rather than
+     * silently execute the successor on the wrong base.
+     */
+    failFast?: string;
+    /** True when every link in the chain is already complete. */
+    allComplete: boolean;
+}
+/** Resolves the git refs a resume base depends on. Injected for testability. */
+export interface CompletedLinkResolver {
+    /**
+     * Resolve a local branch ref to its tip commit SHA, or undefined if the
+     * branch does not exist (destroyed worktree/branch — the AC-3 fail-fast case).
+     */
+    resolveBranchTip(branch: string): string | undefined;
+    /** Resolve the base branch tip (for merged-resume reporting). */
+    resolveBaseTip(): string | undefined;
+    /**
+     * True iff the worktree has uncommitted changes (tracked or non-ignored
+     * untracked). Used to detect a resume base whose checkpoint never landed —
+     * see the dirty-tip fail-fast in {@link computeChainResumePlan}. Must return
+     * false (not throw) when the worktree is gone or unreadable; branch-tip
+     * resolution governs that case instead.
+     */
+    isWorktreeDirty(worktreePath: string): boolean;
+}
+/** An ordered chain link with its persisted state (status + branch + worktree). */
+export interface ChainLinkState {
+    issueNumber: number;
+    status?: string;
+    branch?: string;
+    worktree?: string;
+}
+/**
+ * Compute a chain-correct resume plan.
+ *
+ * Peels the *contiguous* completed prefix off the front of the chain (chain
+ * mode breaks on the first failure, so completed links always form a prefix).
+ * A completed link that appears *after* an incomplete one is left in `active`
+ * and re-executed — the conservative choice, since automatic skipping must not
+ * silently drop an issue the user intended to redo.
+ *
+ * @param orderedLinks Chain links in execution order, with persisted state.
+ * @param baseBranch The run's base branch (resume base when the prefix merged).
+ * @param resolver Git-ref resolver (injected for tests).
+ */
+export declare function computeChainResumePlan(orderedLinks: ChainLinkState[], baseBranch: string, resolver: CompletedLinkResolver): ChainResumePlan;
+/** The subset of persisted issue state the resume planner reads. */
+export interface PersistedLinkState {
+    status?: string;
+    branch?: string;
+    worktree?: string;
+}
+/**
+ * Read each link's persisted state and compute the resume plan.
+ *
+ * Split out of `run-orchestrator.ts` so the state-reading half of resume — in
+ * particular "a state lookup failure must treat the link as *incomplete*", the
+ * conservative choice that re-executes rather than skipping on bad data — is
+ * testable without standing up an orchestrator.
+ *
+ * @param issueNumbers Chain issues in execution order.
+ * @param baseBranch The run's base branch.
+ * @param getIssueState Reads persisted state for one issue (may reject).
+ * @param resolver Git-ref resolver.
+ * @param onStateError Called when a lookup throws; the link is then treated as
+ *   incomplete (no status), so it stays in `active`.
+ */
+export declare function planChainResumeFromState(issueNumbers: number[], baseBranch: string, getIssueState: (issueNumber: number) => Promise<PersistedLinkState | null | undefined>, resolver: CompletedLinkResolver, onStateError?: (issueNumber: number, error: unknown) => void): Promise<ChainResumePlan>;

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

@@ -0,0 +1,170 @@
+/**
+ * Chain resume planning (#760).
+ *
+ * When a `--chain` run fails mid-way, earlier links may already be complete
+ * (see `completed-status.ts`) with a checkpoint commit on their feature branch
+ * (`createCheckpointCommit`, worktree-manager.ts). Re-running the same chain
+ * should skip that completed prefix and resume at the first incomplete link,
+ * rebased onto the last completed link's committed tip — NOT `main` (which is
+ * the #748 wrong-base failure this reuses the #748 rebase path to avoid).
+ *
+ * The non-chain pre-flight guard (`run-orchestrator.ts`) drops completed issues
+ * from the run using the same {@link isCompletedIssueStatus} predicate, but it
+ * is chain-unaware: dropping the completed prefix leaves the first incomplete
+ * link at index 0, where `executeSequential`'s successor-rebase never fires, so
+ * it silently builds on `main`. This module computes a *chain-correct* resume
+ * plan that preserves the completed prefix as the resume base.
+ *
+ * The planner is pure over an injected {@link CompletedLinkResolver} so the
+ * skip/fail-fast state machine (AC-3) is unit-testable without real git; the
+ * real-git rebase is covered by the integration test.
+ */
+import { isCompletedIssueStatus, } from "./completed-status.js";
+/**
+ * Compute a chain-correct resume plan.
+ *
+ * Peels the *contiguous* completed prefix off the front of the chain (chain
+ * mode breaks on the first failure, so completed links always form a prefix).
+ * A completed link that appears *after* an incomplete one is left in `active`
+ * and re-executed — the conservative choice, since automatic skipping must not
+ * silently drop an issue the user intended to redo.
+ *
+ * @param orderedLinks Chain links in execution order, with persisted state.
+ * @param baseBranch The run's base branch (resume base when the prefix merged).
+ * @param resolver Git-ref resolver (injected for tests).
+ */
+export function computeChainResumePlan(orderedLinks, baseBranch, resolver) {
+    const skipped = [];
+    let firstIncomplete = 0;
+    for (const link of orderedLinks) {
+        if (isCompletedIssueStatus(link.status)) {
+            skipped.push({
+                issueNumber: link.issueNumber,
+                status: link.status,
+                branch: link.branch,
+                worktree: link.worktree,
+            });
+            firstIncomplete++;
+        }
+        else {
+            break;
+        }
+    }
+    const allNumbers = orderedLinks.map((l) => l.issueNumber);
+    // No completed prefix → fresh run, nothing to resume.
+    if (skipped.length === 0) {
+        return { skipped: [], active: allNumbers, allComplete: false };
+    }
+    // Every link already complete → nothing to execute.
+    if (firstIncomplete >= orderedLinks.length) {
+        return { skipped, active: [], allComplete: true };
+    }
+    const active = allNumbers.slice(firstIncomplete);
+    const last = skipped[skipped.length - 1];
+    let resumeBase;
+    let resumeBaseCommit;
+    if (last.status === "merged") {
+        // The completed prefix's work is in the merged base (origin/main). Provision
+        // the first incomplete link from the base branch — the same base a fresh
+        // first link would use — rather than a local tip that squash-merge may have
+        // orphaned (never rebase a successor onto a stale post-merge local tip).
+        resumeBase = baseBranch;
+        resumeBaseCommit = resolver.resolveBaseTip();
+    }
+    else {
+        // ready_for_merge / waiting_for_human_merge: the checkpoint tip lives only
+        // on the local feature branch. If that branch is gone (worktree/branch
+        // destroyed mid-way), the tip is unreconstructable — fail fast instead of
+        // wrong-basing the successor onto main (which would miss the completed
+        // link's work).
+        if (!last.branch) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ${last.status} but no branch is recorded in state — ` +
+                    `cannot reconstruct the resume base. Re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        const tip = resolver.resolveBranchTip(last.branch);
+        if (!tip) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ${last.status} but its branch "${last.branch}" no longer exists — ` +
+                    `the resume base is unreconstructable. Re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        // The branch exists, but a tip is only a valid resume base if it actually
+        // contains the link's work. `createCheckpointCommit` sweeps trailing
+        // uncommitted changes into a checkpoint commit; when it fails (commit hook,
+        // staging error, or unrelated dirty files) a completed status was *already*
+        // written — `ready_for_merge` on a plain run, or `waiting_for_human_merge`
+        // when #817's `--ready-gate` owned the terminal status (#837) — so this link
+        // still reads as a completed prefix while its tip is missing work. Both
+        // statuses reach this branch, so the check covers gated links too. Rebasing
+        // the successor onto such a tip would be exactly the silent wrong-base
+        // execution AC-3 forbids — fail fast instead.
+        if (last.worktree && resolver.isWorktreeDirty(last.worktree)) {
+            return {
+                skipped,
+                active,
+                resumeIssue: active[0],
+                allComplete: false,
+                failFast: `#${last.issueNumber} is ${last.status} but its worktree has uncommitted changes — ` +
+                    `its checkpoint commit never landed, so branch "${last.branch}" is missing that work and ` +
+                    `resuming #${active[0]} here would build on an incomplete base. Commit them in ${last.worktree}, ` +
+                    `or re-run with --force to redo the chain from scratch.`,
+            };
+        }
+        resumeBase = last.branch;
+        resumeBaseCommit = tip;
+    }
+    return {
+        skipped,
+        active,
+        resumeBase,
+        resumeBaseCommit,
+        resumeIssue: active[0],
+        allComplete: false,
+    };
+}
+/**
+ * Read each link's persisted state and compute the resume plan.
+ *
+ * Split out of `run-orchestrator.ts` so the state-reading half of resume — in
+ * particular "a state lookup failure must treat the link as *incomplete*", the
+ * conservative choice that re-executes rather than skipping on bad data — is
+ * testable without standing up an orchestrator.
+ *
+ * @param issueNumbers Chain issues in execution order.
+ * @param baseBranch The run's base branch.
+ * @param getIssueState Reads persisted state for one issue (may reject).
+ * @param resolver Git-ref resolver.
+ * @param onStateError Called when a lookup throws; the link is then treated as
+ *   incomplete (no status), so it stays in `active`.
+ */
+export async function planChainResumeFromState(issueNumbers, baseBranch, getIssueState, resolver, onStateError) {
+    const orderedLinks = [];
+    for (const issueNumber of issueNumbers) {
+        let status;
+        let branch;
+        let worktree;
+        try {
+            const issueState = await getIssueState(issueNumber);
+            status = issueState?.status;
+            branch = issueState?.branch;
+            worktree = issueState?.worktree;
+        }
+        catch (error) {
+            // Unknown state → treat as incomplete and re-execute. Skipping on a
+            // failed lookup could silently drop an issue the user meant to run.
+            onStateError?.(issueNumber, error);
+        }
+        orderedLinks.push({ issueNumber, status, branch, worktree });
+    }
+    return computeChainResumePlan(orderedLinks, baseBranch, resolver);
+}

package/dist/src/lib/workflow/completed-status.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Which persisted issue statuses mean "this issue is already done" (#837).
+ *
+ * Single source of truth for every pre-flight guard that skips finished work.
+ * It exists because the same predicate was previously spelled out inline at two
+ * sites with two different lists, and #817's `--ready-gate` extended the status
+ * vocabulary without either site following:
+ *
+ * - `chain-resume.ts` peels the completed prefix off a `--chain` run.
+ * - `run-orchestrator.ts` drops finished issues from a non-chain run.
+ *
+ * A gated issue deliberately terminates in `waiting_for_human_merge` (policy
+ * threshold reached) rather than `ready_for_merge`, since `ready_for_merge`
+ * would read as auto-merge-ready and defeat the human merge gate the feature
+ * exists to preserve. Both guards missed it, so re-running re-executed
+ * already-gated issues from phase 0 — a full spec/exec/qa pipeline plus another
+ * full-weight ready gate.
+ *
+ * `blocked` is deliberately NOT a completed status, for two reasons:
+ *
+ * 1. It is a *generic* member of `IssueStatusSchema` ("waiting on external input
+ *    or dependency"), not a ready-gate-exclusive terminal. Admitting it here
+ *    would silently apply to every other writer of that status, present and
+ *    future.
+ * 2. A guard halt IS the human-attention signal. Skipping it as complete would
+ *    report the issue as passed when it demonstrably did not.
+ *
+ * So a `blocked` issue is re-executed rather than skipped — the same
+ * conservative rule already applied to issues whose state lookup fails.
+ * Re-running wastes tokens; silently dropping an issue the user must look at is
+ * the worse failure. Once the user clears the blocker, the re-run is what lets
+ * work resume.
+ *
+ * NOTE: this is "done, do not re-run", which is NOT the same set as "might have
+ * a merged PR" — `state-cleanup.ts`'s merge-detection sweep deliberately keeps
+ * its own wider list (it also scans `in_progress`, #592, and
+ * `waiting_for_qa_gate`, #606). Do not unify the two.
+ *
+ * When adding a status to `IssueStatusSchema`, decide here whether it belongs.
+ */
+export declare const COMPLETED_ISSUE_STATUSES: readonly ["ready_for_merge", "merged", "waiting_for_human_merge"];
+/** A persisted status that counts as completed work. */
+export type CompletedIssueStatus = (typeof COMPLETED_ISSUE_STATUSES)[number];
+/**
+ * True iff `status` marks the issue as already finished, so a re-run should
+ * skip it unless `--force` is passed.
+ *
+ * Accepts `string | undefined` because persisted state may predate the current
+ * schema or be absent entirely; an unknown or missing status is treated as
+ * incomplete (re-execute), never as complete.
+ */
+export declare function isCompletedIssueStatus(status: string | undefined): status is CompletedIssueStatus;