stageflow 0.16.0 → 0.18.0

package/skills/stageflow-author/references/stage-prompt-template.md

@@ -1,10 +1,10 @@
 # Stage prompt template
 
-Every external stage file has `id` and `system_prompt`. Filename stem matches `id`. `model` is optional when the pipeline or `stageflow.yaml` supplies it — otherwise set it on the stage. Default when writing a concrete string is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim. Before writing models, confirm at least one provider is `configured` (see the skill Provider gate). Sibling stages after a fork should use the same configured model family unless the human asks otherwise.
+Every external stage file has `id`, `system_prompt`, `io.input.schema`, and `io.output.schema`. Filename stem matches `id`. `model` is optional when the pipeline or `stageflow.yaml` supplies it — otherwise set it on the stage. Default when writing a concrete string is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim. Before writing models, confirm at least one provider is `configured` (see the skill Provider gate). Sibling stages after fan-out should use the same configured model family unless the human asks otherwise.
 
 ## Base
 
-Use for every stage that is not a review point and does not decide a branch.
+Use for every stage that is not a review point. Branching is catalog `if` on the source `route`, not an agent choice. Base stages do not name successor ids.
 
 ```yaml
 id: <id>
@@ -18,6 +18,13 @@ system_prompt: |
   attempt must be emit_stage_envelope (or ask_operator if waiting on HITL).
   An empty final message is a stage failure.
 model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
 ```
 
 The prompt has no `ask_operator` line. It ends on the `emit_stage_envelope` instruction. Call `emit_stage_envelope` once per attempt.
@@ -46,7 +53,7 @@ Set artifacts: [] on emit. Put that path in payload.<field>.
 
 ## Summary and payload
 
-Add to every stage (base, gated, or fork):
+Add to every stage (base, gated, or route-if):
 
 ```
 summary and payload are handed to the next stage verbatim. State outcomes and
@@ -75,6 +82,13 @@ system_prompt: |
   4. Call emit_stage_envelope with an advancing success status only after the
      operator accepts. Never emit before accept.
 model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
 ```
 
 Use the `gate_kinds` value that matches the human's review: `artifact_backed` for a file to accept, `confirm` for yes/no, `free_text` for an open reply, `multi_question` for a batch. `ask_operator` does not complete the stage.
@@ -87,28 +101,54 @@ same attempt (commit, push, open PR as required), write any final artifact,
 then emit. Do not pause after accept. Do not ask_operator for emit/schema errors.
 ```
 
-## Fork
+## Route if
 
-When the pipeline entry has `fork`, the success emit names immediate successors in `fork_choice`. Add this block to the base (or gated) prompt:
+When the source `route` uses `if`, the success payload must include the required discriminator field(s) named in `if.field`. Those fields must be required in `io.output.schema`. The agent emits the field values; it does not name successor ids and does not emit `fork_choice`. Listed `to:` stay on the DAG; `if` decides which run.
+
+Add this block to the base (or gated) prompt:
+
+```
+On success, emit the payload fields this stage's route if predicates read
+(name them). Use the types in io.output.schema. Do not name successor stage
+ids. Catalog if decides which children run.
+```
+
+## Loop
+
+When `route` has `{ type: loop }`, the success emit includes envelope field `feedback_loop`: `{ action: continue }` or `{ action: send_back, target: <ancestor id> }`. Catalog YAML uses `{ type: loop }` inside `route`, not a `feedback_loop:` key. `if` is not allowed on the loop entry.
+
+Add this block to the base (or gated) prompt:
 
 ```
-On a success emit, include fork_choice naming immediate successor id(s) that
-should run. Name only ids listed as this stage's children. select: one →
-exactly one id. select: subset → one or more of those ids.
-Normalize free_text answers before mapping (trim, lowercase, collapse spaces
-and hyphens). If unmapped, ask_operator again; do not emit.
+On success, include feedback_loop: { action: continue } to advance, or
+{ action: send_back, target: <ancestor id> } to replay that ancestor.
 ```
 
-`fork_choice` on a failure emit is ignored. Leave `clone_forks` unset unless the human explicitly asked for clonable fan-out (see [`catalog-mapping.md`](catalog-mapping.md)).
+## Clone Chain
+
+A Clone Chain emitter succeeds by emitting a valid payload only. Do not emit `clone_forks`. The Clone Array field in `io.output.schema` is the list; Stageflow mints one Clone Instance per element.
 
-## Clonable parent
+The clone child's opening input is that array element (the named `$ref`) and nothing else. Prompt it as work on one item.
 
-When a successor is `clonable: true`, the parent success emit uses `clone_forks` (not `fork_choice`) for that successor. Add:
+The Join receives the Clone Instance success envelopes (array order). It does not unpack a clone list from the emitter.
+
+Add this block to an **emitter** prompt:
+
+```
+On success, emit the list in the Clone Array field named in io.output.schema
+(length 1..clone_cap). Do not emit clone_forks. Stageflow starts one run of
+the next stage per element.
+```
+
+Add this block to a **clone child** prompt:
 
 ```
-On success, include clone_forks covering every clonable successor exactly once.
-Each clone entry is a full envelope with status, summary, artifacts, and payload
-matching that successor's io.input.schema — not a stub object.
+Your input is one list element. Do the work for that element only. Emit a
+payload that matches io.output.schema. Do not emit a Clone Array.
 ```
 
-Clonable child stages use the base (or gated) prompt. Remind them they are one clone among others and must emit independently.
+Add this block to a **Join** prompt:
+
+```
+You receive every Clone Instance success envelope. Gather them in list order.
+```

package/skills/stageflow-session-capture/SKILL.md

@@ -74,8 +74,8 @@ Read [`references/catalog-authoring.md`](references/catalog-authoring.md) before
    `node scripts/resolve-catalog-id.mjs --text "<phrase>" --dir <write-dir> --kind pipeline|stage`
 
    Use the printed `{"id":"..."}`.
-3. Write one external stage YAML per phase (`id`, `system_prompt`, optional `model`). End every `system_prompt` with an `emit_stage_envelope` footer. Omit `gate_kinds`. Filename stem must match `id`.
-4. Write one pipeline YAML that wires the stages with `uses:` and `needs:` in dependency order.
+3. Write one external stage YAML per phase (`id`, `system_prompt`, `io`, optional `model`). End every `system_prompt` with an `emit_stage_envelope` footer. Omit `gate_kinds`. Filename stem must match `id`.
+4. Write one pipeline YAML that wires the stages with `uses:`, marks the first stage `entry: true`, and lists forward `route: [{ to: next }]` on each non-leaf in dependency order.
 
 Do not write a `*.task.yaml`.
 

package/skills/stageflow-session-capture/assets/example-pipeline/example.pipeline.yaml

@@ -3,6 +3,8 @@ model: anthropic/claude-sonnet-4-5
 stages:
   - id: research
     uses: ./research.yaml
+    entry: true
+    route:
+      - to: implement
   - id: implement
     uses: ./implement.yaml
-    needs: [research]

package/skills/stageflow-session-capture/assets/example-pipeline/implement.yaml

@@ -7,6 +7,21 @@ system_prompt: |
   and a payload describing what you produced. Your last tool call in this
   attempt must be emit_stage_envelope. An empty final message is a stage failure.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - known
+        - unknown
+      properties:
+        known:
+          type: array
+          items:
+            type: string
+        unknown:
+          type: array
+          items:
+            type: string
   output:
     schema:
       type: object

package/skills/stageflow-session-capture/assets/example-pipeline/research.yaml

@@ -7,6 +7,9 @@ system_prompt: |
   and a payload the next stage can use. Your last tool call in this attempt must
   be emit_stage_envelope. An empty final message is a stage failure.
 io:
+  input:
+    schema:
+      type: object
   output:
     schema:
       type: object

package/skills/stageflow-session-capture/references/catalog-authoring.md

@@ -10,7 +10,7 @@ Resolve collision-safe ids with `scripts/resolve-catalog-id.mjs` (`--text`, `--d
 
 ## External stage file
 
-Required fields: `id`, `system_prompt`. Filename stem must match `id` (`research.yaml` → `id: research`). `model` is optional when the pipeline or manifest supplies it.
+Required fields: `id`, `system_prompt`, `io.input.schema`, `io.output.schema`. Filename stem must match `id` (`research.yaml` → `id: research`). `model` is optional when the pipeline or manifest supplies it.
 
 Every `system_prompt` ends with a mandatory `emit_stage_envelope` footer, for example:
 
@@ -28,7 +28,9 @@ Worked example: `assets/example-pipeline/research.yaml` and `assets/example-pipe
 
 ## Pipeline file
 
-`id` plus `stages:` entries with `id`, `uses:` (path relative to the pipeline file), and `needs:` for every non-root stage. Linear chain: each stage `needs` the previous id (scalar or a one-item array). Optional pipeline-root `model` fills stages that omit `model`. Put body contracts (`io`, `verify`) on stage files; put `on_verify_fail` on the pipeline entry when after-phase verify should repair or wait for an operator.
+`id` plus `stages:` array of object entries with `id`, `uses:` (path relative to the pipeline file). Mark the first stage `entry: true`. Linear chain: each non-leaf lists `route: [{ to: next-id }]`. Optional pipeline-root `model` fills stages that omit `model`. Put body contracts (`io`, `verify`) on stage files; `io.input.schema` and `io.output.schema` are required on every stage. Put `on_verify_fail` on the pipeline entry when after-phase verify should repair or wait for an operator.
+
+Session-capture is a linear chain of transcript phases. Exclusive branches, if needed, are catalog `if` on `route` after success, not agent-picked ids — see [`../../stageflow-author/references/catalog-mapping.md`](../../stageflow-author/references/catalog-mapping.md). `needs` and `fork` fail load.
 
 Worked example: `assets/example-pipeline/example.pipeline.yaml`.
 

package/dist/envelope/cloneForks.d.ts

@@ -1,2 +0,0 @@
-import { type CloneEmitContext } from "../types/forkChoice.js";
-export declare function assertCloneForks(params: unknown, cloneEmitContext: CloneEmitContext): void;

package/dist/envelope/cloneForks.js

@@ -1,77 +0,0 @@
-import { parseCloneForks } from "./check.js";
-import { assertCloneAssignmentPayload } from "./payloadSchema.js";
-import { EnvelopeError } from "../types/envelope.js";
-import { CLONE_ACTIONS } from "../types/forkChoice.js";
-function fieldPresent(item, key) {
-    return item[key] !== undefined;
-}
-export function assertCloneForks(params, cloneEmitContext) {
-    const record = params;
-    if (record.status === "failure")
-        return;
-    if (record.clone_forks === undefined || !Array.isArray(record.clone_forks)) {
-        throw new EnvelopeError("clonable successor requires clone_forks on success");
-    }
-    const items = parseCloneForks(record.clone_forks);
-    if (items.length === 0 && cloneEmitContext.clonableSuccessors.length > 0) {
-        throw new EnvelopeError("clone_forks must not be empty when clonable successors exist");
-    }
-    const expectedIds = cloneEmitContext.clonableSuccessors.map((s) => s.successorId);
-    const expectedSet = new Set(expectedIds);
-    const seen = new Set();
-    for (const [i, item] of items.entries()) {
-        const itemPath = `clone_forks[${i}]`;
-        if (seen.has(item.successor_id)) {
-            throw new EnvelopeError(`${itemPath} contains duplicate successor_id: ${item.successor_id}`);
-        }
-        if (!expectedSet.has(item.successor_id)) {
-            throw new EnvelopeError(`${itemPath} contains extra successor_id: ${item.successor_id}`);
-        }
-        seen.add(item.successor_id);
-        const capEntry = cloneEmitContext.clonableSuccessors.find((s) => s.successorId === item.successor_id);
-        const cloneCap = capEntry?.cloneCap;
-        const allowedActions = cloneEmitContext.allowedActions ?? [...CLONE_ACTIONS];
-        if (!allowedActions.includes(item.action)) {
-            throw new EnvelopeError(`${itemPath} action "${item.action}" is not allowed for ${item.successor_id} (allowed: ${allowedActions.join(", ")})`);
-        }
-        if (item.action === "skip") {
-            if (fieldPresent(item, "envelope") ||
-                fieldPresent(item, "mode") ||
-                fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`${itemPath} skip for ${item.successor_id} must not include envelope, mode, or clones`);
-            }
-        }
-        else if (item.action === "once") {
-            if (!fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} requires envelope`);
-            }
-            if (fieldPresent(item, "mode") || fieldPresent(item, "clones")) {
-                throw new EnvelopeError(`${itemPath} once for ${item.successor_id} must not include mode or clones`);
-            }
-            if (capEntry?.cloneInputSchema !== undefined) {
-                assertCloneAssignmentPayload(item.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.envelope`);
-            }
-        }
-        else if (item.action === "fanout") {
-            if (fieldPresent(item, "envelope")) {
-                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must not include a top-level envelope`);
-            }
-            if (!fieldPresent(item, "mode") || !fieldPresent(item, "clones") || item.clones === undefined) {
-                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} requires mode and clones`);
-            }
-            if (cloneCap === undefined || item.clones.length < 2 || item.clones.length > cloneCap) {
-                throw new EnvelopeError(`${itemPath} fanout for ${item.successor_id} must have between 2 and ${cloneCap} clones`);
-            }
-            if (capEntry?.cloneInputSchema !== undefined) {
-                for (const [j, clone] of item.clones.entries()) {
-                    assertCloneAssignmentPayload(clone.envelope, capEntry.cloneInputSchema, item.successor_id, `${itemPath}.clones[${j}].envelope`);
-                }
-            }
-        }
-    }
-    for (const id of expectedIds) {
-        if (!seen.has(id)) {
-            throw new EnvelopeError(`clone_forks missing successor_id: ${id}`);
-        }
-    }
-}