stageflow 0.16.0 → 0.18.0

package/README.md

@@ -31,13 +31,12 @@ The same pipeline runs three ways without rewriting anything:
 - **Path-based CLI** — `--pipeline` and `--task` take filesystem paths (no bare-id lookup)
 - **Pi-native** — runs on `@earendil-works/pi-coding-agent`; reuse an existing Pi login (`pi_home`) or store credentials in `~/.stageflow/agent/auth.json` (`sf_owned`)
 - **Envelope handoffs** — typed stage payloads and artifacts via `write_stage_artifact` / `emit_stage_envelope`
-- **Verified stage execution** — pipeline-owned completion checks with durable evidence, automatic repair, and manual recovery ([guide](docs/verified-stage-execution.md))
+- **Verified stage execution** — after-phase `verify` checks with durable evidence, plus `on_verify_fail` repair or manual operator recovery ([guide](docs/verified-stage-execution.md))
 - **HITL gates** — operator questions in the console; CI exits `2` when a run is waiting
 - **Operator console** — triage runs, connect providers, answer gates, inspect transcripts at `http://127.0.0.1:3847`
 - **MCP endpoint** — Streamable HTTP at `/mcp` when `sf ui` or `sf mcp` is running
 - **CI / headless** — `sf validate --strict --json`, `sf run --json` with exit codes `0` / `1` / `2`
-- **Parallel stages** — pipeline DAG with fan-out and join (see [YAML catalog](docs/yaml-catalog.md))
-- **Clonable fan-out** — clone one successor N times at completion, then join (see [YAML catalog](docs/yaml-catalog.md#clonable-successors))
+- **Parallel stages** — pipeline DAG with fan-out, join, and Clone Chains (one Clone Instance per Clone Array element; see [YAML catalog](docs/yaml-catalog.md#clone-chain))
 - **SQLite run store** — `<git-root>/.stageflow/` state plus per-run workspaces under `.stageflow/runs/`
 
 ## Architecture at a glance
@@ -219,7 +218,6 @@ If you want deterministic YAML routing across many agents, look at [Conductor](h
 | [hello-world](examples/hello-world/) | Single stage, domain-neutral |
 | [plan-review](examples/plan-review/) | Multi-stage with operator gate — SDLC-style **example** |
 | [conditional-fork](examples/conditional-fork/) | Exclusive fork routing with operator branch choice |
-| [clonable-fanout](examples/clonable-fanout/) | Clone one successor N times, then join |
 | [stage-mcp](examples/stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture |
 | [playwright-mcp](examples/playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) |
 | [context7-mcp](examples/context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) |

package/dist/agent/claudeTools.d.ts

@@ -45,10 +45,8 @@ export type AskOperatorCapture = {
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export declare function buildEmitStageEnvelopeShape(options: {
     forkEmitContext?: ForkEmitContext;
@@ -62,7 +60,6 @@ export declare function buildEmitStageEnvelopeShape(options: {
     artifacts: z.ZodArray<z.ZodString>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     fork_choice: z.ZodArray<z.ZodString> | z.ZodOptional<z.ZodArray<z.ZodString>>;
-    clone_forks?: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>> | undefined;
     checklist_attestations: z.ZodOptional<z.ZodArray<z.ZodObject<{
         check_id: z.ZodString;
         items: z.ZodArray<z.ZodString>;

package/dist/agent/claudeTools.js

@@ -40,10 +40,8 @@ export const ASK_OPERATOR_TOOL_NAME = `mcp__${STAGEFLOW_MCP_SERVER_NAME}__ask_op
  * nothing else catches one drifting from the other.
  *
  * Field presence mirrors the typebox schema's own conditionality:
- * `clone_forks` only exists when a stage can clone-fork at all, and
  * `fork_choice` is required (not just present) when the stage has a fork
- * to route. Building this statically would silently offer the model a
- * `clone_forks` field on stages that have nowhere to route one.
+ * to route.
  */
 export function buildEmitStageEnvelopeShape(options) {
     return {
@@ -54,9 +52,6 @@ export function buildEmitStageEnvelopeShape(options) {
         fork_choice: options.forkEmitContext !== undefined
             ? z.array(z.string())
             : z.array(z.string()).optional(),
-        ...(options.cloneEmitContext !== undefined
-            ? { clone_forks: z.array(z.record(z.string(), z.unknown())) }
-            : {}),
         checklist_attestations: z
             .array(z.object({
             check_id: z.string().min(1),

package/dist/agent/fakeAgent.js

@@ -3,7 +3,6 @@ import path from "node:path";
 import { assertRequiredEnvelope, isAdvancingEnvelope, } from "../envelope/check.js";
 import { assertFeedbackLoopAction } from "../envelope/feedbackLoop.js";
 import { assertEnvelopePayload } from "../envelope/payloadSchema.js";
-import { assertCloneForks } from "../envelope/cloneForks.js";
 import { assertForkEnvelope } from "../envelope/forkChoice.js";
 import { assertAnswerMatchesPrompt, parseAskOperatorAnswer, } from "../tools/askOperator.js";
 import { tryParsePendingPrompt } from "../runtime/stageHitl.js";
@@ -154,15 +153,15 @@ export class FakeAgent {
                 ? behavior.envelope
                 : undefined;
             try {
-                const envelope = assertRequiredEnvelope(envelopeValue);
+                let envelope = assertRequiredEnvelope(envelopeValue);
+                if (envelope.status === "success" && envelope.payload === undefined) {
+                    envelope = { ...envelope, payload: {} };
+                }
                 assertFeedbackLoopAction(envelope, input.feedbackLoopEmitContext);
                 const isFeedbackSendBack = envelope.feedback_loop?.action === "send_back";
                 if (!isFeedbackSendBack && input.forkEmitContext !== undefined) {
                     assertForkEnvelope(envelope, input.forkEmitContext);
                 }
-                if (!isFeedbackSendBack && input.cloneEmitContext !== undefined) {
-                    assertCloneForks(envelope, input.cloneEmitContext);
-                }
                 assertEnvelopePayload(envelope, input.stage.payload_schema);
                 if (!isAdvancingEnvelope(envelope)) {
                     input.onActivity?.({ event: "agent_end" });

package/dist/agent/piAdapter.js

@@ -404,23 +404,10 @@ function buildUserPrompt(input, emitToolName, emitHintOverride, artifactToolName
             emitHint += `\nFailed-check evidence from attempt ${input.repairContext.prior_attempt}:\n${JSON.stringify(input.repairContext.failed_checks, null, 2)}`;
         }
     }
-    if (input.cloneEmitContext !== undefined) {
-        const allowedActions = input.cloneEmitContext.allowedActions ?? ["skip", "once", "fanout"];
-        const successorLines = input.cloneEmitContext.clonableSuccessors.map((successor) => {
-            const header = `- ${successor.successorId} (clone_cap: ${successor.cloneCap})`;
-            if (successor.cloneInputSchema === undefined) {
-                return header;
-            }
-            return `${header}\n  Assignment schema (io.input.schema):\n${JSON.stringify(successor.cloneInputSchema, null, 2)}`;
-        });
-        emitHint += `\nClonable successors — emit clone_forks covering each of these ids exactly once:\n${successorLines.join("\n")}`;
-        emitHint += `\nEach once or fanout envelope is a full StageEnvelope — it requires status ("success" or "failure"), summary (non-empty string), and artifacts (array of strings). io.input.schema fields belong in envelope.payload, not at the top level of the clone_forks item.`;
-        emitHint += `\nAllowed clone actions: ${allowedActions.join(", ")}`;
-    }
     if (input.feedbackLoopEmitContext !== undefined) {
         emitHint += `\nFeedback-loop decision: this stage is a feedback-loop source. On status=success, feedback_loop is required. Emit either {"action":"continue"} to proceed downstream or {"action":"send_back","target":"…"} to request another pass.`;
         emitHint += `\nAllowed send_back target: ${input.feedbackLoopEmitContext.target}.`;
-        emitHint += `\nA send_back decision cannot be combined with fork_choice or clone_forks.`;
+        emitHint += `\nA send_back decision cannot be combined with fork_choice.`;
     }
     const attempt = input.roots.attempt ?? 1;
     const attemptArtifactsPath = `stages/${runtimeStageId(input)}/attempts/${attempt}/artifacts/`;

package/dist/config/cloneChain.d.ts

@@ -0,0 +1,12 @@
+import type { PipelineStageRef, ResolvedPipelineDag } from "../types/pipeline.js";
+import type { StageConfig } from "../types/stage.js";
+import { type LoadOutcome } from "./loadOutcome.js";
+export type DetectedCloneChain = {
+    emitterId: string;
+    cloneChildId: string;
+    joinId: string;
+    arrayField: string;
+    ref: string;
+};
+export declare function detectCloneChains(stages: StageConfig[], refs: PipelineStageRef[], pipelineId: string): LoadOutcome<DetectedCloneChain[]>;
+export declare function applyCloneChains(stages: StageConfig[], refs: PipelineStageRef[], dag: ResolvedPipelineDag, pipelineId: string): LoadOutcome<void>;

package/dist/config/cloneChain.js

@@ -0,0 +1,322 @@
+import { loadFailure, loadSuccess } from "./loadOutcome.js";
+import { toRouteEdges, toRouteLoopEntries } from "./pipelineRoute.js";
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function namedSchemaRef(schema) {
+    if (!isPlainObject(schema))
+        return undefined;
+    const keys = Object.keys(schema);
+    if (keys.length !== 1 || keys[0] !== "$ref")
+        return undefined;
+    const ref = schema.$ref;
+    if (typeof ref !== "string" || !ref.startsWith("#/schemas/"))
+        return undefined;
+    const name = ref.slice("#/schemas/".length);
+    if (!name || name.includes("/"))
+        return undefined;
+    return ref;
+}
+function inspectOutput(schema) {
+    const empty = {
+        namedRefArrays: [],
+        nonRefArrayFields: [],
+        isRootArray: false,
+        rootArrayRef: undefined,
+    };
+    if (!isPlainObject(schema))
+        return empty;
+    if (schema.type === "array") {
+        const ref = namedSchemaRef(schema.items);
+        return {
+            namedRefArrays: [],
+            nonRefArrayFields: ref === undefined ? ["<root>"] : [],
+            isRootArray: true,
+            rootArrayRef: ref,
+        };
+    }
+    if (schema.type !== "object" || !isPlainObject(schema.properties))
+        return empty;
+    const namedRefArrays = [];
+    const nonRefArrayFields = [];
+    for (const [field, prop] of Object.entries(schema.properties)) {
+        if (!isPlainObject(prop) || prop.type !== "array")
+            continue;
+        const ref = namedSchemaRef(prop.items);
+        if (ref !== undefined)
+            namedRefArrays.push({ field, ref });
+        else
+            nonRefArrayFields.push(field);
+    }
+    return {
+        namedRefArrays,
+        nonRefArrayFields,
+        isRootArray: false,
+        rootArrayRef: undefined,
+    };
+}
+function inboundSources(refs, targetId) {
+    return refs.filter((ref) => toRouteEdges(ref.route).some((edge) => edge.to === targetId));
+}
+function isSealedThreeStagePath(refs, stageById, refById, emitter, childId) {
+    const edges = toRouteEdges(emitter.route);
+    if (edges.length !== 1)
+        return false;
+    const childEdge = edges[0];
+    if (childEdge.to !== childId || childEdge.if !== undefined)
+        return false;
+    const childStage = stageById.get(childId);
+    const childRef = refById.get(childId);
+    if (!childStage || !childRef)
+        return false;
+    if (inboundSources(refs, childId).length !== 1)
+        return false;
+    const childEdges = toRouteEdges(childRef.route);
+    if (childEdges.length !== 1 || childEdges[0].if !== undefined)
+        return false;
+    const joinId = childEdges[0].to;
+    if (!stageById.has(joinId))
+        return false;
+    if (inboundSources(refs, joinId).length !== 1)
+        return false;
+    return true;
+}
+function dagError(pipelineId, message, stageId) {
+    return {
+        code: "pipeline.dag_error",
+        message: `Pipeline ${pipelineId}: ${message}`,
+        category: "pipeline",
+        pipelineId,
+        ...(stageId !== undefined ? { stageId } : {}),
+    };
+}
+function fail(pipelineId, message, stageId) {
+    return loadFailure([dagError(pipelineId, message, stageId)]);
+}
+function childOutputIsCloneArray(schema) {
+    const inspected = inspectOutput(schema);
+    return inspected.namedRefArrays.length > 0 || inspected.rootArrayRef !== undefined;
+}
+export function detectCloneChains(stages, refs, pipelineId) {
+    const stageById = new Map(stages.map((stage) => [stage.id, stage]));
+    const refById = new Map(refs.map((ref) => [ref.id, ref]));
+    const chains = [];
+    for (const emitter of refs) {
+        const emitterStage = stageById.get(emitter.id);
+        if (!emitterStage)
+            continue;
+        const edges = toRouteEdges(emitter.route);
+        const output = inspectOutput(emitterStage.payload_schema);
+        if (output.namedRefArrays.length >= 2 && edges.length > 0) {
+            return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter output must have exactly one named $ref Clone Array`, emitter.id);
+        }
+        if (output.isRootArray && edges.length > 0) {
+            const looksLikeChain = edges.some((edge) => {
+                const childStage = stageById.get(edge.to);
+                if (!childStage)
+                    return false;
+                if (namedSchemaRef(childStage.clone_input_schema) === undefined)
+                    return false;
+                return isSealedThreeStagePath(refs, stageById, refById, emitter, edge.to);
+            });
+            if (looksLikeChain) {
+                return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter output is a root-level array, which is not a Clone Array`, emitter.id);
+            }
+        }
+        if (output.namedRefArrays.length === 0 &&
+            output.nonRefArrayFields.length > 0 &&
+            edges.length > 0) {
+            for (const edge of edges) {
+                const childStage = stageById.get(edge.to);
+                const childRef = refById.get(edge.to);
+                if (!childStage || !childRef)
+                    continue;
+                if (namedSchemaRef(childStage.clone_input_schema) === undefined)
+                    continue;
+                if (toRouteEdges(childRef.route).length === 0)
+                    continue;
+                return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter Clone Array items must be a named $ref`, emitter.id);
+            }
+        }
+        if (output.namedRefArrays.length !== 1 || edges.length === 0)
+            continue;
+        const array = output.namedRefArrays[0];
+        const childTakesNamedRef = edges.some((edge) => {
+            const childStage = stageById.get(edge.to);
+            return (childStage !== undefined &&
+                namedSchemaRef(childStage.clone_input_schema) !== undefined);
+        });
+        const hasClonePolicy = emitter.clone_cap !== undefined || emitter.clone_mode !== undefined;
+        const sealedLookalike = edges.some((edge) => isSealedThreeStagePath(refs, stageById, refById, emitter, edge.to));
+        if (!childTakesNamedRef && !hasClonePolicy && !sealedLookalike) {
+            continue;
+        }
+        const matchingChildIds = edges
+            .filter((edge) => {
+            const childStage = stageById.get(edge.to);
+            return (childStage !== undefined &&
+                namedSchemaRef(childStage.clone_input_schema) === array.ref);
+        })
+            .map((edge) => edge.to);
+        const uniqueMatching = [...new Set(matchingChildIds)];
+        if (edges.length !== 1) {
+            if (uniqueMatching.length >= 2) {
+                return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter must have exactly one clone child`, emitter.id);
+            }
+            return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter must have exactly one forward Route (the clone child)`, emitter.id);
+        }
+        const childEdge = edges[0];
+        const cloneChildId = childEdge.to;
+        if (childEdge.if !== undefined) {
+            return fail(pipelineId, `stage "${emitter.id}": Clone Chain inbound edge to the clone child must not have if`, emitter.id);
+        }
+        const childStage = stageById.get(cloneChildId);
+        const childRef = refById.get(cloneChildId);
+        if (!childStage || !childRef) {
+            return fail(pipelineId, `stage "${emitter.id}": Clone Chain emitter must have exactly one forward Route (the clone child)`, emitter.id);
+        }
+        if (namedSchemaRef(childStage.clone_input_schema) !== array.ref) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain clone child input must be exactly the named $ref of the emitter Clone Array`, cloneChildId);
+        }
+        if (inboundSources(refs, cloneChildId).length !== 1) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain clone child must have exactly one parent (the emitter)`, cloneChildId);
+        }
+        const childEdges = toRouteEdges(childRef.route);
+        if (childEdges.length !== 1) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain clone child must have exactly one forward Route (the Join)`, cloneChildId);
+        }
+        if (childEdges[0].if !== undefined) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain inbound edge to the Join must not have if`, cloneChildId);
+        }
+        const joinId = childEdges[0].to;
+        if (!stageById.has(joinId)) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain clone child must have exactly one forward Route (the Join)`, cloneChildId);
+        }
+        if (inboundSources(refs, joinId).length !== 1) {
+            return fail(pipelineId, `stage "${joinId}": Clone Chain Join must have exactly one parent (the clone child)`, joinId);
+        }
+        if (childOutputIsCloneArray(childStage.payload_schema)) {
+            return fail(pipelineId, `stage "${cloneChildId}": Clone Chain clone child output must not be a Clone Array`, cloneChildId);
+        }
+        chains.push({
+            emitterId: emitter.id,
+            cloneChildId,
+            joinId,
+            arrayField: array.field,
+            ref: array.ref,
+        });
+    }
+    const emitterIds = new Set();
+    const cloneChildIds = new Set();
+    const joinIds = new Set();
+    for (const chain of chains) {
+        if (emitterIds.has(chain.emitterId)) {
+            return fail(pipelineId, `stage "${chain.emitterId}": Clone Chain emitter is shared with another Clone Chain`, chain.emitterId);
+        }
+        if (cloneChildIds.has(chain.cloneChildId)) {
+            return fail(pipelineId, `stage "${chain.cloneChildId}": Clone Chain clone child is shared with another Clone Chain`, chain.cloneChildId);
+        }
+        if (joinIds.has(chain.joinId)) {
+            return fail(pipelineId, `stage "${chain.joinId}": Clone Chain Join is shared with another Clone Chain`, chain.joinId);
+        }
+        emitterIds.add(chain.emitterId);
+        cloneChildIds.add(chain.cloneChildId);
+        joinIds.add(chain.joinId);
+    }
+    return loadSuccess(chains);
+}
+function validateCloneChainLoops(refs, chains, pipelineId) {
+    if (chains.length === 0)
+        return loadSuccess(undefined);
+    const emitterIds = new Set(chains.map((chain) => chain.emitterId));
+    const cloneChildIds = new Set(chains.map((chain) => chain.cloneChildId));
+    const forbiddenTargets = new Map();
+    for (const chain of chains) {
+        forbiddenTargets.set(chain.emitterId, "emitter");
+        forbiddenTargets.set(chain.cloneChildId, "clone child");
+        forbiddenTargets.set(chain.joinId, "Join");
+    }
+    for (const ref of refs) {
+        const loops = toRouteLoopEntries(ref.route);
+        if (loops.length === 0)
+            continue;
+        if (emitterIds.has(ref.id)) {
+            return loadFailure([
+                dagError(pipelineId, `stage "${ref.id}": Clone Chain emitter cannot originate a Loop`, ref.id),
+            ]);
+        }
+        if (cloneChildIds.has(ref.id)) {
+            return loadFailure([
+                dagError(pipelineId, `stage "${ref.id}": Clone Chain clone child cannot originate a Loop`, ref.id),
+            ]);
+        }
+        for (const loop of loops) {
+            const role = forbiddenTargets.get(loop.to);
+            if (role === undefined)
+                continue;
+            return loadFailure([
+                dagError(pipelineId, `stage "${ref.id}": Loop target "${loop.to}" is a Clone Chain ${role}`, ref.id),
+            ]);
+        }
+    }
+    return loadSuccess(undefined);
+}
+function applyCloneCapToSchema(schema, field, cap) {
+    if (!isPlainObject(schema) || !isPlainObject(schema.properties))
+        return;
+    const prop = schema.properties[field];
+    if (!isPlainObject(prop))
+        return;
+    prop.minItems = 1;
+    prop.maxItems = cap;
+}
+export function applyCloneChains(stages, refs, dag, pipelineId) {
+    const detected = detectCloneChains(stages, refs, pipelineId);
+    if (!detected.ok)
+        return detected;
+    const chains = detected.value;
+    const emitterIds = new Set(chains.map((chain) => chain.emitterId));
+    const refById = new Map(refs.map((ref) => [ref.id, ref]));
+    const nodeById = new Map(dag.nodes.map((node) => [node.id, node]));
+    for (const ref of refs) {
+        const isEmitter = emitterIds.has(ref.id);
+        if (isEmitter) {
+            if (ref.clone_cap === undefined || ref.clone_mode === undefined) {
+                return loadFailure([
+                    dagError(pipelineId, `stage "${ref.id}": Clone Chain emitter requires clone_cap and clone_mode`, ref.id),
+                ]);
+            }
+            continue;
+        }
+        if (ref.clone_cap !== undefined) {
+            return loadFailure([
+                dagError(pipelineId, `stage "${ref.id}": "clone_cap" is no longer supported — use a Clone Chain instead`, ref.id),
+            ]);
+        }
+        if (ref.clone_mode !== undefined) {
+            return loadFailure([
+                dagError(pipelineId, `stage "${ref.id}": "clone_mode" is only valid on a Clone Chain emitter`, ref.id),
+            ]);
+        }
+    }
+    const loopsOutcome = validateCloneChainLoops(refs, chains, pipelineId);
+    if (!loopsOutcome.ok)
+        return loopsOutcome;
+    const stageById = new Map(stages.map((stage) => [stage.id, stage]));
+    for (const chain of chains) {
+        const ref = refById.get(chain.emitterId);
+        const cap = ref.clone_cap;
+        const mode = ref.clone_mode;
+        const node = nodeById.get(chain.emitterId);
+        if (node) {
+            node.clone_cap = cap;
+            node.clone_mode = mode;
+            node.clone_array_field = chain.arrayField;
+        }
+        const emitterStage = stageById.get(chain.emitterId);
+        if (emitterStage?.payload_schema !== undefined) {
+            applyCloneCapToSchema(emitterStage.payload_schema, chain.arrayField, cap);
+        }
+    }
+    return loadSuccess(undefined);
+}

package/dist/config/createPipeline.js

@@ -1,6 +1,6 @@
 import { access, mkdir, readdir, unlink, writeFile } from "node:fs/promises";
 import path from "node:path";
-import { parsePipelineNeeds } from "./pipelineNeeds.js";
+import { invertPredecessorEdgesToRoute, invertRouteToPredecessorEdges, parsePipelineNeeds, toPipelineNeeds, } from "./pipelineNeeds.js";
 import { STAGE_ID_PATTERN } from "./createStage.js";
 import { inferIdFromUsesPath, normalizePipelineStageEntries, toWiringRefs, } from "./normalizePipelineStageEntry.js";
 import { parseModelField } from "./modelField.js";
@@ -29,10 +29,12 @@ export function normalizeCreatePipelineStages(stages) {
         uses: stage.uses ?? (stage.inline ? undefined : defaultUsesPath(stage.id)),
     }));
 }
-function stageRefToRaw(ref) {
+function stageRefToRaw(ref, routeInfo) {
     const raw = { id: ref.id };
-    if (ref.needs !== undefined)
-        raw.needs = ref.needs;
+    if (routeInfo?.entry)
+        raw.entry = true;
+    if (routeInfo?.route && routeInfo.route.length > 0)
+        raw.route = routeInfo.route;
     if (ref.uses !== undefined)
         raw.uses = ref.uses;
     if (ref.inline) {
@@ -47,16 +49,20 @@ function stageRefToRaw(ref) {
     return raw;
 }
 function toAuthoringRawEntries(stages, declaringPath) {
+    const routeById = invertPredecessorEdgesToRoute(stages);
     return stages.map((stage) => ({
-        raw: stageRefToRaw(stage),
+        raw: stageRefToRaw(stage, routeById.get(stage.id)),
         declaringPath,
     }));
 }
 function normalizedToCreateRefs(entries) {
+    const inbound = invertRouteToPredecessorEdges(entries);
     return entries.map((entry) => {
         const ref = { id: entry.id };
-        if (entry.needs !== undefined)
-            ref.needs = entry.needs;
+        const edges = inbound.get(entry.id);
+        const needs = edges !== undefined ? toPipelineNeeds(edges) : undefined;
+        if (needs !== undefined)
+            ref.needs = needs;
         if (entry.body.kind === "uses") {
             ref.uses = entry.body.path;
         }
@@ -236,21 +242,86 @@ export function parseCreatePipelineBody(body) {
         stages: refs,
     };
 }
-function appendNeedsYaml(lines, needs) {
-    if (typeof needs === "string") {
-        lines.push(`    needs: ${needs}`);
+function formatRouteIfValue(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (value === null)
+        return "null";
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => formatRouteIfValue(item)).join(", ")}]`;
+    }
+    return JSON.stringify(value);
+}
+function appendRouteIfYamlListItem(lines, indent, predicate) {
+    if ("all" in predicate) {
+        lines.push(`${indent}- all:`);
+        for (const child of predicate.all) {
+            appendRouteIfYamlListItem(lines, `${indent}  `, child);
+        }
         return;
     }
-    lines.push("    needs:");
-    for (const edge of needs) {
-        if (edge.on.length === 1 && edge.on[0] === "succeeded") {
-            lines.push(`      - ${edge.id}`);
-            continue;
+    if ("any" in predicate) {
+        lines.push(`${indent}- any:`);
+        for (const child of predicate.any) {
+            appendRouteIfYamlListItem(lines, `${indent}  `, child);
+        }
+        return;
+    }
+    if ("not" in predicate) {
+        lines.push(`${indent}- not:`);
+        appendRouteIfYaml(lines, `${indent}    `, predicate.not);
+        return;
+    }
+    lines.push(`${indent}- field: ${formatInlineYamlScalar(predicate.field)}`);
+    lines.push(`${indent}  op: ${predicate.op}`);
+    lines.push(`${indent}  value: ${formatRouteIfValue(predicate.value)}`);
+}
+function appendRouteIfYaml(lines, indent, predicate) {
+    if ("all" in predicate) {
+        lines.push(`${indent}all:`);
+        for (const child of predicate.all) {
+            appendRouteIfYamlListItem(lines, `${indent}  `, child);
+        }
+        return;
+    }
+    if ("any" in predicate) {
+        lines.push(`${indent}any:`);
+        for (const child of predicate.any) {
+            appendRouteIfYamlListItem(lines, `${indent}  `, child);
+        }
+        return;
+    }
+    if ("not" in predicate) {
+        lines.push(`${indent}not:`);
+        appendRouteIfYaml(lines, `${indent}  `, predicate.not);
+        return;
+    }
+    lines.push(`${indent}field: ${formatInlineYamlScalar(predicate.field)}`);
+    lines.push(`${indent}op: ${predicate.op}`);
+    lines.push(`${indent}value: ${formatRouteIfValue(predicate.value)}`);
+}
+function appendRouteYaml(lines, routeInfo) {
+    if (routeInfo.entry) {
+        lines.push("    entry: true");
+    }
+    if (!routeInfo.route || routeInfo.route.length === 0) {
+        return;
+    }
+    lines.push("    route:");
+    for (const item of routeInfo.route) {
+        const on = item.on === undefined ? ["succeeded"] : Array.isArray(item.on) ? item.on : [item.on];
+        lines.push(`      - to: ${item.to}`);
+        if (!(on.length === 1 && on[0] === "succeeded")) {
+            lines.push("        on:");
+            for (const state of on) {
+                lines.push(`          - ${state}`);
+            }
         }
-        lines.push(`      - id: ${edge.id}`);
-        lines.push("        on:");
-        for (const state of edge.on) {
-            lines.push(`          - ${state}`);
+        if (item.if !== undefined) {
+            lines.push("        if:");
+            appendRouteIfYaml(lines, "          ", item.if);
         }
     }
 }
@@ -266,6 +337,7 @@ function formatInlineYamlScalar(value) {
     return value;
 }
 export function pipelineConfigToYaml(pipeline, options) {
+    const routeById = invertPredecessorEdgesToRoute(pipeline.stages);
     const lines = [`id: ${pipeline.id}`, "stages:"];
     for (const stage of pipeline.stages) {
         if (options.format === "linear" && !stage.needs && !stage.inline && stage.uses) {
@@ -274,8 +346,9 @@ export function pipelineConfigToYaml(pipeline, options) {
             continue;
         }
         lines.push(`  - id: ${stage.id}`);
-        if (stage.needs) {
-            appendNeedsYaml(lines, stage.needs);
+        const routeInfo = routeById.get(stage.id);
+        if (routeInfo) {
+            appendRouteYaml(lines, routeInfo);
         }
         if (stage.inline) {
             if (stage.inline.gate_kinds !== undefined) {
@@ -301,6 +374,13 @@ export function pipelineConfigToYaml(pipeline, options) {
             if (stage.inline.model !== undefined && stage.inline.model.length > 0) {
                 lines.push(`    model: ${formatInlineYamlScalar(stage.inline.model)}`);
             }
+            lines.push("    io:");
+            lines.push("      input:");
+            lines.push("        schema:");
+            lines.push("          type: object");
+            lines.push("      output:");
+            lines.push("        schema:");
+            lines.push("          type: object");
         }
         else if (stage.uses) {
             lines.push(`    uses: ${stage.uses}`);

package/dist/config/createStage.js

@@ -122,6 +122,13 @@ export function stageConfigToYaml(stage) {
     if (stage.model !== undefined && stage.model.length > 0) {
         lines.push(`model: ${formatInlineYamlScalar(stage.model)}`);
     }
+    lines.push("io:");
+    lines.push("  input:");
+    lines.push("    schema:");
+    lines.push("      type: object");
+    lines.push("  output:");
+    lines.push("    schema:");
+    lines.push("      type: object");
     lines.push("");
     return lines.join("\n");
 }

package/dist/config/loadOutcome.d.ts

@@ -5,6 +5,7 @@ export type LoadIssue = {
     message: string;
     category: "pipeline";
     pipelineId?: string;
+    stageId?: string;
 } | {
     code: ValidationFindingCode;
     message: string;