stageflow 0.9.0 → 0.12.0

package/dist/cli/runsCommand.d.ts

@@ -1,6 +1,6 @@
 import type { RunStore } from "../runstore/port.js";
 import { RunManager } from "../runtime/runManager.js";
-export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
+export declare const RUNS_USAGE = "Usage:\n  sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]\n  sf runs show --run <runId> [--from <sf-run.json>] [--json]\n  sf runs verify --run <runId> --stage <stageId> [--json]\n  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]\n  sf runs waiting [--run <runId>] [--json]\n  sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]\n  sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]\n  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]\n  sf runs retry --run <runId> --stage <stageId> [--json]\n  sf runs abandon --run <runId> --stage <stageId> [--json]\n  sf runs rerun --run <runId> [--json]";
 export type RunsCommandIo = {
     log: (line: string) => void;
     error: (line: string) => void;

package/dist/cli/runsCommand.js

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import path from "node:path";
-import { PiAgentAdapter } from "../agent/piAdapter.js";
+import { resolveGlobalOnlyAgentPort } from "../agent/resolveAgentPort.js";
 import { projectRun } from "../projection/projectRun.js";
 import { waitRun } from "../mcp/waitRun.js";
 import { projectWaitingGates } from "../mcp/waitingGates.js";
@@ -8,6 +8,7 @@ import { resolveOperatorCatalog } from "./operatorCatalog.js";
 import { completeCliRun } from "./runCommand.js";
 import { reportCliRun } from "./runOutput.js";
 import { createRunStore } from "../runstore/createStore.js";
+import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
 import { RunManager } from "../runtime/runManager.js";
 import { readStageExecutionMode } from "../runtime/stageConcurrency.js";
 import { DEFAULT_PORT } from "../server/createHttpHost.js";
@@ -16,9 +17,12 @@ import { AskOperatorError, parseAskOperatorAnswer, } from "../tools/askOperator.
 export const RUNS_USAGE = `Usage:
   sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
   sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs verify --run <runId> --stage <stageId> [--json]
+  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]
   sf runs waiting [--run <runId>] [--json]
   sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
   sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
+  sf runs feedback-decide --run <runId> --stage <sourceStageId> [--loop <loopId>] --decision extend|continue|abandon [--reason <text>] [--json]
   sf runs retry --run <runId> --stage <stageId> [--json]
   sf runs abandon --run <runId> --stage <stageId> [--json]
   sf runs rerun --run <runId> [--json]`;
@@ -41,6 +45,16 @@ const LIST_FLAGS = new Set([
     "-h",
 ]);
 const SHOW_FLAGS = new Set(["--run", "--from", "--json", "--help", "-h"]);
+const VERIFY_FLAGS = new Set(["--run", "--stage", "--json", "--help", "-h"]);
+const RECOVER_FLAGS = new Set([
+    "--run",
+    "--stage",
+    "--guidance",
+    "--stop",
+    "--json",
+    "--help",
+    "-h",
+]);
 const WAITING_FLAGS = new Set(["--run", "--json", "--help", "-h"]);
 const WAIT_FLAGS = new Set([
     "--run",
@@ -55,6 +69,17 @@ const ANSWER_FLAGS = new Set([
     "--run",
     "--stage",
     "--answer",
+    "--guidance",
+    "--json",
+    "--help",
+    "-h",
+]);
+const FEEDBACK_DECIDE_FLAGS = new Set([
+    "--run",
+    "--stage",
+    "--loop",
+    "--decision",
+    "--reason",
     "--json",
     "--help",
     "-h",
@@ -72,6 +97,10 @@ const VALUE_FLAGS = new Set([
     "--timeout-ms",
     "--stage",
     "--answer",
+    "--loop",
+    "--decision",
+    "--reason",
+    "--guidance",
 ]);
 function flagsFor(subcommand) {
     switch (subcommand) {
@@ -79,12 +108,18 @@ function flagsFor(subcommand) {
             return LIST_FLAGS;
         case "show":
             return SHOW_FLAGS;
+        case "verify":
+            return VERIFY_FLAGS;
+        case "recover":
+            return RECOVER_FLAGS;
         case "waiting":
             return WAITING_FLAGS;
         case "wait":
             return WAIT_FLAGS;
         case "answer":
             return ANSWER_FLAGS;
+        case "feedback-decide":
+            return FEEDBACK_DECIDE_FLAGS;
         case "retry":
             return RETRY_FLAGS;
         case "abandon":
@@ -118,6 +153,11 @@ function parseRunsArgs(args) {
     let timeoutMs;
     let stageId;
     let answer;
+    let guidance;
+    let stop = false;
+    let loopId;
+    let decision;
+    let reason;
     for (let i = 1; i < args.length; i++) {
         const arg = args[i];
         if (arg === "--help" || arg === "-h") {
@@ -126,6 +166,11 @@ function parseRunsArgs(args) {
         else if (arg === "--json") {
             json = true;
         }
+        else if (arg === "--stop") {
+            if (!allowed.has(arg))
+                throw new Error(`Unknown flag: ${arg}`);
+            stop = true;
+        }
         else if (VALUE_FLAGS.has(arg)) {
             if (!allowed.has(arg)) {
                 throw new Error(`Unknown flag: ${arg}`);
@@ -152,6 +197,14 @@ function parseRunsArgs(args) {
                 stageId = value;
             else if (arg === "--answer")
                 answer = value;
+            else if (arg === "--guidance")
+                guidance = value;
+            else if (arg === "--loop")
+                loopId = value;
+            else if (arg === "--decision")
+                decision = value;
+            else if (arg === "--reason")
+                reason = value;
         }
         else if (arg.startsWith("-")) {
             throw new Error(`Unknown flag: ${arg}`);
@@ -173,6 +226,11 @@ function parseRunsArgs(args) {
         timeoutMs,
         stageId,
         answer,
+        guidance,
+        stop,
+        loopId,
+        decision,
+        reason,
     };
 }
 function resolveRunIdFromFile(fromPath, cwd) {
@@ -275,6 +333,7 @@ export async function runRunsCommand(args, options = {}) {
         return resolvedStore;
     };
     const mutatingIo = out;
+    const agent = await resolveGlobalOnlyAgentPort(projectRoot);
     const buildManager = () => {
         const store = getStore();
         if (options.createManager)
@@ -285,7 +344,7 @@ export async function runRunsCommand(args, options = {}) {
             defaultCwd: cwd,
         });
         return new RunManager({
-            agent: new PiAgentAdapter(),
+            agent,
             store,
             cwd,
             projectRoot,
@@ -359,6 +418,32 @@ export async function runRunsCommand(args, options = {}) {
                 return 1;
             }
         }
+        case "verify": {
+            if (!parsed.runId)
+                return usageError(out, "Missing --run");
+            if (!parsed.stageId)
+                return usageError(out, "Missing --stage");
+            try {
+                const history = await readStageVerificationHistory(getStore(), parsed.runId, parsed.stageId);
+                if (parsed.json) {
+                    printJson(out, history);
+                }
+                else {
+                    for (const attempt of history.attempts) {
+                        const checks = attempt.checks
+                            .map((check) => `${check.check_id}:${check.status}`)
+                            .join(", ");
+                        out.log(`attempt ${attempt.attempt}\t${attempt.status}${checks ? `\t${checks}` : ""}`);
+                    }
+                }
+                return 0;
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                out.error(message);
+                return 1;
+            }
+        }
         case "waiting": {
             const waiting = await projectWaitingGates(getStore(), {
                 runId: parsed.runId,
@@ -512,6 +597,61 @@ export async function runRunsCommand(args, options = {}) {
             }
             return 0;
         }
+        case "feedback-decide": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId) {
+                return usageError(out, "Missing --run");
+            }
+            if (!parsed.stageId) {
+                return usageError(out, "Missing --stage");
+            }
+            if (!parsed.decision) {
+                return usageError(out, "Missing --decision");
+            }
+            if (parsed.decision !== "extend" &&
+                parsed.decision !== "continue" &&
+                parsed.decision !== "abandon") {
+                const message = "--decision must be extend, continue, or abandon";
+                if (parsed.json) {
+                    printJson(out, { error: message, status: 400 });
+                }
+                else {
+                    out.error(message);
+                }
+                return 1;
+            }
+            const manager = buildManager();
+            const result = await manager.decideFeedbackLoop(parsed.runId, parsed.stageId, {
+                decision: parsed.decision,
+                ...(parsed.loopId !== undefined ? { loopId: parsed.loopId } : {}),
+                ...(parsed.reason !== undefined ? { reason: parsed.reason } : {}),
+            });
+            if (!result.ok) {
+                const payload = { error: result.reason };
+                if (result.status !== undefined)
+                    payload.status = result.status;
+                if (parsed.json) {
+                    printJson(out, payload);
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            if (parsed.json) {
+                printJson(out, {
+                    ok: true,
+                    effect: result.effect,
+                    loopId: result.loopId,
+                });
+            }
+            else {
+                out.log(`ok\t${result.effect}\t${result.loopId}`);
+            }
+            return 0;
+        }
         case "retry": {
             const blocked = await guardHost();
             if (blocked !== undefined)
@@ -535,6 +675,48 @@ export async function runRunsCommand(args, options = {}) {
             }
             return reportCliRun({ kind: "completion", result: result.pipeline }, { json: parsed.json, io: mutatingIo });
         }
+        case "recover": {
+            const blocked = await guardHost();
+            if (blocked !== undefined)
+                return blocked;
+            if (!parsed.runId || !parsed.stageId) {
+                return usageError(out, "Missing --run and/or --stage");
+            }
+            const manager = buildManager();
+            if (parsed.stop) {
+                if (parsed.guidance !== undefined) {
+                    return usageError(out, "--guidance cannot be used with --stop");
+                }
+                const result = await manager.stopManualRecovery(parsed.runId, parsed.stageId);
+                if (!result.ok) {
+                    if (parsed.json) {
+                        printJson(out, { error: result.reason, status: result.status });
+                    }
+                    else {
+                        out.error(result.reason);
+                    }
+                    return 1;
+                }
+                if (parsed.json) {
+                    printJson(out, result);
+                }
+                else {
+                    out.log(`${result.runId}\t${result.stageId}\tstopped`);
+                }
+                return 0;
+            }
+            const result = await manager.recoverManualStageUntilStop(parsed.runId, parsed.stageId, parsed.guidance);
+            if (!result.ok) {
+                if (parsed.json) {
+                    printJson(out, { ...mapRetryStageFailure(result), status: result.status });
+                }
+                else {
+                    out.error(result.reason);
+                }
+                return 1;
+            }
+            return reportCliRun({ kind: "completion", result: result.pipeline }, { json: parsed.json, io: mutatingIo });
+        }
         case "abandon": {
             const blocked = await guardHost();
             if (blocked !== undefined)

package/dist/cli.d.ts

@@ -3,7 +3,7 @@ import type { OperatorCatalog } from "./runtime/stageAttemptBootstrap.js";
 export declare function parseRunStageArgs(argv: string[]): {
     runId: string;
     stageId: string;
-    mode?: "run" | "resume";
+    mode?: "run" | "resume" | "feedback_resume" | "new_session";
     resumeAnswer?: unknown;
     attempt?: number;
     sessionFilePath?: string;

package/dist/cli.js

@@ -3,7 +3,7 @@ import { spawn } from "node:child_process";
 import { realpathSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { PiAgentAdapter } from "./agent/piAdapter.js";
+import { globalAgentBackendFromManifest, resolveAgentPort } from "./agent/resolveAgentPort.js";
 import { ARTIFACT_USAGE, runArtifactCommand } from "./cli/artifactCommand.js";
 import { ENVELOPE_USAGE, runEnvelopeCommand, } from "./cli/envelopeCommand.js";
 import { EXPORT_RUN_USAGE, runExportRunCommand, } from "./cli/exportRunCommand.js";
@@ -31,6 +31,8 @@ const USAGE = `Usage:
   sf export-run --run <runId> [--from <sf-run.json>] [--out <file>]
   sf runs list [--status created|running|succeeded|failed] [--since <iso>] [--pipeline <id-or-path>] [--json]
   sf runs show --run <runId> [--from <sf-run.json>] [--json]
+  sf runs verify --run <runId> --stage <stageId> [--json]
+  sf runs recover --run <runId> --stage <stageId> [--guidance <text>] [--stop] [--json]
   sf runs waiting [--run <runId>] [--json]
   sf runs wait --run <runId> [--from <sf-run.json>] [--until any|waiting|terminal] [--timeout-ms <n>] [--json]
   sf runs answer --run <runId> --stage <stageId> [--answer '<json>'] [--json]
@@ -154,8 +156,11 @@ export function parseRunStageArgs(argv) {
         }
         else if (argv[i] === "--mode") {
             const raw = argv[++i];
-            if (raw !== "run" && raw !== "resume") {
-                throw new Error("--mode must be run or resume");
+            if (raw !== "run" &&
+                raw !== "resume" &&
+                raw !== "feedback_resume" &&
+                raw !== "new_session") {
+                throw new Error("--mode must be run, resume, feedback_resume, or new_session");
             }
             mode = raw;
         }
@@ -314,12 +319,13 @@ async function main(argv) {
             });
         }
         const store = createRunStore({ rootDir: ctx.projectRoot });
+        const globalAgent = globalAgentBackendFromManifest(ctx.manifest);
         if (parsed.command === "ui") {
             const mcpStateless = resolveMcpStateless({
                 mcpStateless: parsed.mcpStateless,
             });
             const { url, mcpUrl } = await startUiServer({
-                agent: new PiAgentAdapter(),
+                agent: resolveAgentPort({ global: globalAgent }),
                 store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,
@@ -337,7 +343,7 @@ async function main(argv) {
                 mcpStateless: parsed.mcpStateless,
             });
             const { mcpUrl } = await startMcpServer({
-                agent: new PiAgentAdapter(),
+                agent: resolveAgentPort({ global: globalAgent }),
                 store,
                 cwd: ctx.invocationCwd,
                 rootDir: ctx.projectRoot,

package/dist/config/browseCatalog.js

@@ -14,7 +14,7 @@ function repoRelPath(projectRoot, absPath) {
 function mapStageListing(stage, source, projectRoot) {
     const listing = {
         id: stage.id,
-        ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+        ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
     };
     if (source?.kind === "inline") {
         listing.inline = true;

package/dist/config/createPipeline.d.ts

@@ -1,3 +1,4 @@
+import type { PipelineNeeds } from "../types/pipeline.js";
 import type { StageGateKind } from "../types/stage.js";
 import type { PipelineListing } from "./listConfig.js";
 export type CreatePipelineStageInline = {
@@ -7,7 +8,7 @@ export type CreatePipelineStageInline = {
 };
 export type CreatePipelineStageRef = {
     id: string;
-    needs?: string;
+    needs?: PipelineNeeds;
     uses?: string;
     inline?: CreatePipelineStageInline;
 };

package/dist/config/createPipeline.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { parsePipelineNeeds } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { readYamlObject } from "./readYamlObject.js";
@@ -149,14 +150,15 @@ function parseStageEntry(entry, index) {
     }
     const ref = { id };
     if (entry.needs !== undefined) {
-        if (typeof entry.needs !== "string") {
+        const parsedNeeds = parsePipelineNeeds(entry.needs, id);
+        if (!parsedNeeds.ok) {
             return {
                 ok: false,
                 status: 400,
-                error: `stages[${index}].needs must be a string`,
+                error: parsedNeeds.message.replace(/^stage "[^"]+": /, `stages[${index}].`),
             };
         }
-        ref.needs = entry.needs;
+        ref.needs = parsedNeeds.value;
     }
     if (entry.uses !== undefined) {
         if (typeof entry.uses !== "string" || !entry.uses.trim()) {
@@ -224,6 +226,24 @@ export function parseCreatePipelineBody(body) {
         stages: refs,
     };
 }
+function appendNeedsYaml(lines, needs) {
+    if (typeof needs === "string") {
+        lines.push(`    needs: ${needs}`);
+        return;
+    }
+    lines.push("    needs:");
+    for (const edge of needs) {
+        if (edge.on.length === 1 && edge.on[0] === "succeeded") {
+            lines.push(`      - ${edge.id}`);
+            continue;
+        }
+        lines.push(`      - id: ${edge.id}`);
+        lines.push("        on:");
+        for (const state of edge.on) {
+            lines.push(`          - ${state}`);
+        }
+    }
+}
 function formatInlineYamlScalar(value) {
     if (value.includes("\n") ||
         /[:#"'&*!|>@`[\]{}]/.test(value) ||
@@ -245,13 +265,18 @@ export function pipelineConfigToYaml(pipeline, options) {
         }
         lines.push(`  - id: ${stage.id}`);
         if (stage.needs) {
-            lines.push(`    needs: ${stage.needs}`);
+            appendNeedsYaml(lines, stage.needs);
         }
         if (stage.inline) {
-            if (stage.inline.gate_kinds && stage.inline.gate_kinds.length > 0) {
-                lines.push("    gate_kinds:");
-                for (const kind of stage.inline.gate_kinds) {
-                    lines.push(`      - ${kind}`);
+            if (stage.inline.gate_kinds !== undefined) {
+                if (stage.inline.gate_kinds.length === 0) {
+                    lines.push("    gate_kinds: []");
+                }
+                else {
+                    lines.push("    gate_kinds:");
+                    for (const kind of stage.inline.gate_kinds) {
+                        lines.push(`      - ${kind}`);
+                    }
                 }
             }
             if (stage.inline.system_prompt.includes("\n")) {
@@ -364,7 +389,7 @@ function buildPipelineListing(projectRoot, relPath, loaded) {
             const source = loaded.stageSources?.[stage.id];
             const listing = {
                 id: stage.id,
-                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+                ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
             };
             if (source?.kind === "inline") {
                 return { ...listing, inline: true };

package/dist/config/createStage.js

@@ -22,7 +22,7 @@ function validateStageId(id) {
 function parseGateKinds(raw) {
     if (raw === undefined)
         return undefined;
-    if (!Array.isArray(raw) || raw.length === 0)
+    if (!Array.isArray(raw))
         return "invalid";
     const kinds = [];
     for (const item of raw) {
@@ -71,7 +71,7 @@ export function parseCreateStageBody(body) {
         return {
             ok: false,
             status: 400,
-            error: `gate_kinds must be a non-empty array of: ${STAGE_GATE_KINDS.join(", ")}`,
+            error: `gate_kinds must be an array of: ${STAGE_GATE_KINDS.join(", ")}`,
         };
     }
     return {
@@ -80,7 +80,7 @@ export function parseCreateStageBody(body) {
         id: body.id,
         system_prompt: body.system_prompt,
         model: body.model,
-        ...(gateKinds ? { gate_kinds: gateKinds } : {}),
+        ...(gateKinds !== undefined ? { gate_kinds: gateKinds } : {}),
     };
 }
 function formatInlineYamlScalar(value) {
@@ -96,10 +96,15 @@ function formatInlineYamlScalar(value) {
 }
 export function stageConfigToYaml(stage) {
     const lines = [`id: ${stage.id}`];
-    if (stage.gate_kinds && stage.gate_kinds.length > 0) {
-        lines.push("gate_kinds:");
-        for (const kind of stage.gate_kinds) {
-            lines.push(`  - ${kind}`);
+    if (stage.gate_kinds !== undefined) {
+        if (stage.gate_kinds.length === 0) {
+            lines.push("gate_kinds: []");
+        }
+        else {
+            lines.push("gate_kinds:");
+            for (const kind of stage.gate_kinds) {
+                lines.push(`  - ${kind}`);
+            }
         }
     }
     if (stage.system_prompt.includes("\n")) {
@@ -186,7 +191,7 @@ export async function createStage(projectRoot, input) {
             id: input.id,
             system_prompt: input.system_prompt,
             model: input.model,
-            ...(input.gate_kinds ? { gate_kinds: input.gate_kinds } : {}),
+            ...(input.gate_kinds !== undefined ? { gate_kinds: input.gate_kinds } : {}),
         }), "utf8");
     }
     catch (err) {
@@ -200,7 +205,7 @@ export async function createStage(projectRoot, input) {
             stage: {
                 path: relPath,
                 id: stage.id,
-                ...(stage.gate_kinds ? { gate_kinds: stage.gate_kinds } : {}),
+                ...(stage.gate_kinds !== undefined ? { gate_kinds: stage.gate_kinds } : {}),
             },
         };
     }

package/dist/config/loadPipeline.js

@@ -5,6 +5,7 @@ import { mergePipelineStages } from "./mergePipelineIncludes.js";
 import { normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { loadStageFromObjectOutcome, loadStageOutcome } from "./loadStage.js";
 import { resolvePipelineDagFromRefs } from "./resolvePipelineDag.js";
+import { validateCompletionContractForStage } from "./validateCompletionContract.js";
 export async function resolvePipelinePath(pipelinePath, cwd) {
     const resolved = path.normalize(path.resolve(cwd, pipelinePath));
     try {
@@ -21,7 +22,7 @@ async function loadPipelineFromPath(pipelinePath) {
     if (!mergeOutcome.ok) {
         return loadFailure(mergeOutcome.issues);
     }
-    const { entries: rawEntries, pipelineId } = mergeOutcome.value;
+    const { entries: rawEntries, pipelineId, agent: pipelineAgent } = mergeOutcome.value;
     const ctx = { pipelineId, path: normalizedPipelinePath };
     const normalizeOutcome = normalizePipelineStageEntries(rawEntries, ctx);
     if (!normalizeOutcome.ok) {
@@ -106,7 +107,15 @@ async function loadPipelineFromPath(pipelinePath) {
     const pipeline = {
         id: pipelineId,
         stages: stageIds,
+        ...(pipelineAgent !== undefined ? { agent: pipelineAgent } : {}),
     };
+    const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const stage of stages) {
+        const completion = nodeById.get(stage.id)?.completion;
+        const completionOutcome = validateCompletionContractForStage(stage, completion);
+        if (!completionOutcome.ok)
+            return loadFailure(completionOutcome.issues);
+    }
     return loadSuccess({
         pipeline,
         stages,