stageflow 0.16.0 → 0.18.0

package/dist/ui/index.html

@@ -13,8 +13,8 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/index-XWJovnp7.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-D2Wt8hwH.css">
+    <script type="module" crossorigin src="/assets/index-DwKGaQvQ.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DsgVjLUS.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.16.0",
+  "version": "0.18.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -37,6 +37,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "dev": "tsx src/cli.ts",
+    "dev:watch": "PI_CURSOR_SETTING_SOURCES=all STAGEFLOW_ACTIVITY_VERBOSE=1 tsx watch src/cli.ts ui",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "ui:dev": "npm run dev -w ui",
     "ui:build": "npm run build -w ui && npm run copy:ui-dist",

package/skills/stageflow-author/SKILL.md

@@ -37,7 +37,7 @@ Ask until you can name every step, how they sequence, any decision point, and an
 
 Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, optional `model`, `io`, `verify`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan body `verify` and wiring `on_verify_fail`. When a review can demand changes, include an address-feedback stage before approve/ship.
 
-**Done when** you have a pipeline id, one stage id per step, `needs` / `fork` wiring, a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages the structure requires.
+**Done when** you have a pipeline id, one stage id per step, `route` / `entry` wiring (optional `if`, `{ type: loop }`, sealed Clone Chain when the human wants one run per list item), a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages the structure requires.
 
 ## Anti-patterns
 
@@ -45,15 +45,15 @@ Author these contracts explicitly. They come from long runs that failed after ho
 
 | Always do | How |
 |---|---|
-| End every attempt on a tool call | Prompt: last call is `emit_stage_envelope`, or `ask_operator` while waiting on HITL. Each clonable instance emits on its own. |
+| End every attempt on a tool call | Prompt: last call is `emit_stage_envelope`, or `ask_operator` while waiting on HITL. |
 | Land required files in the attempt artifact dir | Prompt `write_stage_artifact`. Body `verify` with `type: artifact` and `when` including `after`. `ask_operator` `artifact_backed` references that same path. |
 | Make implement stages change the checkout | Body `verify` `checkout_changes` + `path_fields`; `io.output.schema` with required checkout-relative path arrays. Exploration-only is its own stage or a failure emit. |
 | Hand successors clean envelopes | `summary` / `payload` = outcomes and artifact pointers only. Name required `io.output.schema` fields in the prompt. |
 | Give review blockers a place to land | Wire `review → address-feedback → approve/ship`. Put `verdict` / `blocking_findings` (or equivalent) in the review `io.output.schema`. |
 | Bind success to the full checklist | If a plan lists N commands, success requires all of them in `commands_run` with exit 0. Cheap checks first; slow suites last or in a verify stage. Size `timeout_ms` to the work. |
-| Use configured models on every sibling | Same configured `model` family after a fork/fan-out unless the human asks otherwise. Reliable model on publish/PR stages. |
+| Use configured models on every sibling | Same configured `model` family after fan-out unless the human asks otherwise. Reliable model on publish/PR stages. |
 | Finish publish in the accept attempt | After `artifact_backed` accept: side effects (commit/push/PR) → final artifact → emit in the same attempt. Fix emit/schema errors by re-emitting. |
-| Emit full clone assignments | When `clonable: true`, parent success uses `clone_forks` with full envelopes matching `io.input.schema`. Leave clonable unset when the clone count is unknown. |
+| Author a sealed Clone Chain | One run per list item is emitter → clone child → Join. Never write `clonable`, `clone_forks`, or emit-time `skip` / `once` / `fanout`. See [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain). |
 
 Throwaway checkout deliverables (HTML spike, scratch file): prompt builtin `write` at a checkout-relative path, `artifacts: []` on emit, path in `payload`.
 

package/skills/stageflow-author/assets/examples/branch-decision/hotfix.yaml

@@ -1,13 +1,21 @@
 id: hotfix
 system_prompt: |
-  Take the failing results from the prior envelope and repair the work they
-  describe.
+  Take the prior envelope (payload.ready is false) and repair the work it
+  describes.
 
   Write the repair notes via write_stage_artifact (for example hotfix.md).
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you repaired.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - ready
+      properties:
+        ready:
+          type: boolean
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/branch-decision/release-gate.pipeline.yaml

@@ -3,14 +3,22 @@ model: anthropic/claude-sonnet-4-5
 stages:
   - id: run-tests
     uses: ./run-tests.yaml
-    fork:
-      select: one
+    entry: true
+    route:
+      - to: ship
+        if:
+          field: ready
+          op: eq
+          value: true
+      - to: hotfix
+        if:
+          field: ready
+          op: eq
+          value: false
   - id: hotfix
     uses: ./hotfix.yaml
-    needs: [run-tests]
   - id: ship
     uses: ./ship.yaml
-    needs: [run-tests]
     on_verify_fail:
       mode: manual
       retry_safety: side_effecting

package/skills/stageflow-author/assets/examples/branch-decision/run-tests.yaml

@@ -4,13 +4,15 @@ system_prompt: |
 
   Write the results via write_stage_artifact (for example results.md).
 
+  When you can assess readiness, emit a success envelope. Set payload.ready to
+  true or false. Do not emit a failure status to express unreadiness.
+
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload the next stage can use.
-
-  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: hotfix when the results fail, ship when they pass.
 io:
+  input:
+    schema:
+      type: object
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/branch-decision/ship.yaml

@@ -1,6 +1,6 @@
 id: ship
 system_prompt: |
-  Take the passing results from the prior envelope and produce the shippable
+  Take the prior envelope (payload.ready is true) and produce the shippable
   package.
 
   Write the package notes via write_stage_artifact (for example ship.md).
@@ -8,6 +8,14 @@ system_prompt: |
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you shipped.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - ready
+      properties:
+        ready:
+          type: boolean
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/linear-review/draft.yaml

@@ -9,6 +9,9 @@ system_prompt: |
   attempt must be emit_stage_envelope (or ask_operator if waiting on HITL).
   An empty final message is a stage failure.
 io:
+  input:
+    schema:
+      type: object
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/linear-review/publish.yaml

@@ -8,6 +8,14 @@ system_prompt: |
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you produced.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - verdict
+      properties:
+        verdict:
+          type: string
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/linear-review/review-loop.pipeline.yaml

@@ -3,9 +3,13 @@ model: anthropic/claude-sonnet-4-5
 stages:
   - id: draft
     uses: ./draft.yaml
+    entry: true
+    route:
+      - to: review
   - id: review
     uses: ./review.yaml
-    needs: [draft]
+    route:
+      - to: publish
     on_verify_fail:
       mode: repair
       max_attempts: 3
@@ -13,7 +17,6 @@ stages:
       include_failed_checks: true
   - id: publish
     uses: ./publish.yaml
-    needs: [review]
     on_verify_fail:
       mode: manual
       retry_safety: side_effecting

package/skills/stageflow-author/assets/examples/linear-review/review.yaml

@@ -13,6 +13,14 @@ system_prompt: |
   4. Call emit_stage_envelope with an advancing success status only after the
      operator accepts. Never emit before accept.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - title
+      properties:
+        title:
+          type: string
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/non-sdlc-digest/gather.yaml

@@ -7,6 +7,9 @@ system_prompt: |
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload the next stage can use.
 io:
+  input:
+    schema:
+      type: object
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/non-sdlc-digest/research-digest.pipeline.yaml

@@ -3,12 +3,15 @@ model: anthropic/claude-sonnet-4-5
 stages:
   - id: gather
     uses: ./gather.yaml
+    entry: true
+    route:
+      - to: summarize
   - id: summarize
     uses: ./summarize.yaml
-    needs: [gather]
+    route:
+      - to: send
   - id: send
     uses: ./send.yaml
-    needs: [summarize]
     on_verify_fail:
       mode: manual
       retry_safety: side_effecting

package/skills/stageflow-author/assets/examples/non-sdlc-digest/send.yaml

@@ -8,6 +8,14 @@ system_prompt: |
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing who received the digest.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - headline
+      properties:
+        headline:
+          type: string
   output:
     schema:
       type: object

package/skills/stageflow-author/assets/examples/non-sdlc-digest/summarize.yaml

@@ -7,6 +7,14 @@ system_prompt: |
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload the next stage can use.
 io:
+  input:
+    schema:
+      type: object
+      required:
+        - source_count
+      properties:
+        source_count:
+          type: integer
   output:
     schema:
       type: object

package/skills/stageflow-author/references/catalog-mapping.md

@@ -16,21 +16,67 @@ Collision handling lives in [`catalog-write-conventions.md`](catalog-write-conve
 
 ## Sequencing
 
-`needs` is a parent stage id, or a non-empty array (length ≥ 1). Strings default to `on: [succeeded]`. `{ id, on }` accepts a non-empty unique subset of `succeeded` | `failed` | `skipped`.
+Write **Author YAML only**:
+
+- Wiring: `route` / `entry: true` / `{ type: loop }`
+- Contracts: `io` / `verify` / `on_verify_fail`
+- Every stage body has `io.input.schema` and `io.output.schema`
+- Sequential and fan-in edges: consumer `io.input` must be a structural subset of **each** parent's `io.output`
+
+Wiring is declared on the **source** stage. Children do not list parents. A pipeline that uses `route` must mark at least one `entry: true` root.
+
+`route` is a list of entries. Forward entries name `to:`, optional `on:`, optional `if`. Load rejects `needs`, `fork`, `feedback_loop`, `route_select`, and `allow_none`.
 
 | Human says | Pipeline shape |
 |---|---|
-| Steps in order | Each later stage `needs` the previous id. No `fork` field. |
-| Steps happen together | Sibling stages share one `needs` (the same parent). No `fork` field. |
-| A later step waits for two or more earlier steps | That stage `needs` an array of those parent ids (length ≥ 2). |
-| Exactly one branch runs | Deciding stage gets `fork: { select: one }`. Each branch `needs` the decider. |
-| Either, both, or a subset may run | Deciding stage gets `fork: { select: subset }`. Each branch `needs` the decider. |
+| Steps in order | First stage `entry: true`. Each source lists `route: [{ to: next }]`. |
+| Steps happen together | Parent lists multiple `to:` with no `if`. Both run after the parent succeeds. |
+| A later step waits for two or more earlier steps | Each parent lists `to: join`. The join does not declare parents. |
+| Exactly one of several successors should run | Source lists every `to:` with mutually exclusive `if`s on a required payload field. Agent emits that field; it does not name successor ids. |
+| Optional extra successor | `if` on that `to:`. Keep an ungated sibling if something should always run. |
+| Review can send work back | Source `route` includes `{ type: loop, to: ancestor, max_replays, on_max_replays, replay_session }`. Success emit includes envelope `feedback_loop`. |
+| One run per list item | Sealed [Clone Chain](../../../docs/yaml-catalog.md#clone-chain): emitter → clone child → Join. Emitter output has exactly one array of a named `$ref`; the clone child's entire input is that `$ref`. Emitter pipeline entry has `clone_cap` and `clone_mode`. |
 
-Default `select` is `one` unless the human says more than one branch can run.
+A review, approval, or sign-off step is a gated stage: put `gate_kinds` on that stage file and follow [`stage-prompt-template.md`](stage-prompt-template.md).
 
-Map linear chains, sibling fan-out, generic fan-in (`needs` array), and single-level `fork`.
+### `on:` (skip-cascade policy, not a launch)
 
-A review, approval, or sign-off step is a gated stage: put `gate_kinds` on that stage file and follow [`stage-prompt-template.md`](stage-prompt-template.md).
+Default is succeeded-only. Omit `on:` unless you need to opt an edge out of skip-cascade.
+
+Including `failed` or `skipped` in `on:` opts that edge out of skip-cascade. It does **not** launch a child from a skipped or failed parent.
+
+- Single-parent: launch still requires a **succeeded** parent. A skipped parent skip-cascades children whose `on` does **not** include `skipped`. Including `skipped` only prevents cascade; the child stays pending.
+- Multi-parent Join (two or more parents each listing `to:` the same child): never skip-cascaded from one parent. Wait until every parent is terminal. Runs if at least one parent succeeded (skipped siblings do not block). Stays pending if any parent failed (even if `on` lists `failed`). Force-skipped if every parent skipped.
+
+For exclusive branching after a check, emit **success** with a required discriminator in `io.output.schema` and gate successors with `if`. `on: [failed]` does not mean “run hotfix when tests fail” — that child will not launch.
+
+### `if` (runtime gate after success)
+
+Evaluated after the source **succeeds**, against that source's output payload only.
+
+Leaf `{ field, op, value }` or composition `{ all: [...] }` | `{ any: [...] }` | `{ not: {...} }`.
+
+Operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`. Type-strict (`1` is not `"1"`).
+
+`field` is a dot-separated path; every segment must be a **required** object property in the source `io.output.schema`.
+
+Two matching `if`s both fire (not first-match-wins).
+
+When every forward `to:` on a stage has `if`, validate warns `pipeline.route_all_gated` (`ok: true`; `--strict` does not promote). That is acceptable for exclusive branches.
+
+`if` is illegal on `{ type: loop }`, or combined with `on` other than succeeded-only.
+
+The completing agent does **not** pick which successors run. Do not emit `fork_choice`.
+
+### Loops
+
+A review that can send work back to an ancestor is a `{ type: loop }` entry **inside** `route` on the source (the reviewer). Required fields: `type: loop`, `to` (earlier ancestor), `max_replays`, `on_max_replays` (`require_continue` | `wait_for_human`), `replay_session` (`resume` | `new_session`).
+
+The **envelope** field on emit is still `feedback_loop` (`continue` / `send_back`). Catalog YAML does not use a `feedback_loop:` key.
+
+Optional `replay_safe: false` on stages that must not be replayed (e.g. one-shot submit).
+
+Forward-only “review → address-feedback → approve” is still the right map when the human wants a separate fix stage rather than send-back.
 
 ## Review then fix then approve
 
@@ -40,7 +86,7 @@ When the human wants a review that can demand changes, then a later approve/ship
 … → review → address-feedback → approve
 ```
 
-Do not wire approve/ship as the immediate child of review. Pipelines are forward-only; without an address-feedback stage, blocking findings have nowhere to land. The address-feedback stage is the only post-review editor; the approve stage is the backstop.
+Do not wire approve/ship as the immediate child of review when blockers are expected. The address-feedback stage is the only post-review editor; the approve stage is the backstop. When they want send-back to an earlier stage instead, put `{ type: loop }` on the reviewer's `route`.
 
 ## Verify and on_verify_fail
 
@@ -56,22 +102,21 @@ Put `verify` on the **stage body** (the `uses:` file or inline entry). Put `on_v
 
 `on_verify_fail` requires at least one after-phase `verify` item. Check `id` values must be unique within the stage. Check discriminator is `type:` (gate widgets still use `kind:`). Wire these for writer stages and final gates; prompts alone do not enforce them.
 
-## Clonable successors
+## Clone Chain
+
+A Clone Chain is emitter → clone child → Join. The emitter output has exactly one array of a named `$ref`; the clone child's entire input is that same `$ref`. Put `clone_cap` (integer ≥ 1) and `clone_mode` (`parallel` | `sequential`) on the **emitter pipeline entry**, not on the stage body. N=1 still mints `{child}~1`.
 
-A runtime clone count is not knowable from a vague description — leave `clonable` and `clone_forks` unset and prefer sibling stages or a single review.
+An empty Clone Array or a length above the Clone Cap fails the **emitter emit** — it does not skip the chain or truncate. Gate a zero-item path before the emitter. Both inbound chain edges are sealed: no extra routes, no `if`. The Join may Loop only to a stage before the emitter; the emitter, clone child, and Join are not Loop targets; the clone child cannot Loop or `send_back`.
 
-When the human explicitly wants N parallel instances of **one** successor catalog id (e.g. several review lenses, several prototype variants):
+See [YAML catalog — Clone Chain](../../../docs/yaml-catalog.md#clone-chain) and [`clone-chain-smallest.pipeline.yaml`](../../../tests/fixtures/pipelines/clone-chain-smallest.pipeline.yaml).
 
-- On that successor pipeline entry: `clonable: true` and `clone_cap` (integer ≥ 2).
-- That successor must have at least one child (a join / address-feedback / collect stage). It cannot be a DAG leaf.
-- Parent success emit uses `clone_forks` for that successor (not `fork_choice`). Each clone assignment is a full envelope; validate assignments with `io.input.schema` on the clonable stage body.
-- Join stages that wait on the clonable parent read clone-list `priorEnvelopes`, not `priorEnvelopesByStage`.
+## Rejected clone fields
 
-`fork` + `fork_choice` picks which **branch stage ids** run. `clone_forks` spawns **N instances** of one successor id.
+Do not author `clonable`, `clone_actions`, or envelope `clone_forks`. Do not put `clone_cap` / `clone_mode` on a stage that is not a Clone Chain emitter.
 
 ## Models
 
-Confirm providers before writing. After a fork, give every sibling the same configured `model` unless the human asks for different ones. Prefer a reliable configured model on side-effecting final stages.
+Confirm providers before writing. After fan-out, give every sibling the same configured `model` unless the human asks for different ones. Prefer a reliable configured model on side-effecting final stages.
 
 ## Worked examples
 
@@ -85,12 +130,23 @@ model: anthropic/claude-sonnet-4-5
 stages:
   - id: draft
     uses: ./draft.yaml
+    entry: true
+    route:
+      - to: review
   - id: review
     uses: ./review.yaml
-    needs: [draft]
+    route:
+      - to: publish
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
   - id: publish
     uses: ./publish.yaml
-    needs: [review]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting
 ```
 
 `review` carries `gate_kinds: [artifact_backed]` and emit-phase `verify` `type: gate`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-review/).
@@ -103,55 +159,78 @@ When review can emit blockers and a later stage approves or ships, insert addres
 stages:
   - id: implement
     uses: ./implement.yaml
+    entry: true
+    route:
+      - to: review
   - id: review
     uses: ./review.yaml
-    needs: [implement]
+    route:
+      - to: address-feedback
   - id: address-feedback
     uses: ./address-feedback.yaml
-    needs: [review]
+    route:
+      - to: approve
   - id: approve
     uses: ./approve.yaml
-    needs: [address-feedback]
 ```
 
-Do not make `approve` / `ship` `needs: review` when blockers are expected.
+Do not wire approve/ship as the immediate child of review when blockers are expected.
 
-### Release gate (fork, select one)
+### Release gate (exclusive via `if`)
 
-One deciding step, then exactly one successor.
+`run-tests` emits **success** with required `ready` boolean. Catalog `if` picks the successor. A failure emit would leave both children unlaunched.
 
 ```yaml
 id: release-gate
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: run-tests
     uses: ./run-tests.yaml
-    fork:
-      select: one
+    entry: true
+    route:
+      - to: ship
+        if:
+          field: ready
+          op: eq
+          value: true
+      - to: hotfix
+        if:
+          field: ready
+          op: eq
+          value: false
   - id: hotfix
     uses: ./hotfix.yaml
-    needs: [run-tests]
   - id: ship
     uses: ./ship.yaml
-    needs: [run-tests]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting
 ```
 
 Full set: [`../assets/examples/branch-decision/`](../assets/examples/branch-decision/).
 
 ### Research digest (linear, non-software)
 
-Weekly gather → summarize → send. Same `needs` chain as the review loop; ids and prompts stay in that domain.
+Weekly gather → summarize → send. Same `entry` + `route` chain as the review loop; ids and prompts stay in that domain.
 
 ```yaml
 id: research-digest
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: gather
     uses: ./gather.yaml
+    entry: true
+    route:
+      - to: summarize
   - id: summarize
     uses: ./summarize.yaml
-    needs: [gather]
+    route:
+      - to: send
   - id: send
     uses: ./send.yaml
-    needs: [summarize]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting
 ```
 
 Full set: [`../assets/examples/non-sdlc-digest/`](../assets/examples/non-sdlc-digest/).
@@ -164,15 +243,17 @@ Full set: [`../assets/examples/non-sdlc-digest/`](../assets/examples/non-sdlc-di
 stages:
   - id: intake
     uses: ./intake.yaml
+    entry: true
+    route:
+      - to: collect-quotes
+      - to: collect-notes
   - id: collect-quotes
     uses: ./collect-quotes.yaml
-    needs: [intake]
   - id: collect-notes
     uses: ./collect-notes.yaml
-    needs: [intake]
 ```
 
-No `fork` field. Both siblings run.
+Both run after intake succeeds. No `if`.
 
 ### Diamond join
 
@@ -182,37 +263,65 @@ No `fork` field. Both siblings run.
 stages:
   - id: clarify
     uses: ./clarify.yaml
+    entry: true
+    route:
+      - to: research
+      - to: validation
   - id: research
     uses: ./research.yaml
-    needs: [clarify]
+    route:
+      - to: synthesize
   - id: validation
     uses: ./validation.yaml
-    needs: [clarify]
+    route:
+      - to: synthesize
   - id: synthesize
     uses: ./synthesize.yaml
-    needs:
-      - research
-      - validation
 ```
 
-`needs` array length ≥ 2 is keyed fan-in. The join reads `priorEnvelopesByStage`, not clone-list `priorEnvelopes`.
+The join reads `priorEnvelopesByStage`, not a list of sibling envelopes. A skipped sibling does not block. A failed parent leaves the join pending.
 
-### Fork, select subset
+### Optional / subset fan-out
 
-"Email, post, or both could go out":
+"Email, post, or both": list both `to:` with no `if` (both run). To skip a channel, add `if` on that `to:` and put the discriminator in `io.output.schema`. Do not emit `fork_choice`.
 
 ```yaml
 stages:
   - id: choose-channels
     uses: ./choose-channels.yaml
-    fork:
-      select: subset
+    entry: true
+    route:
+      - to: email
+      - to: post
   - id: email
     uses: ./email.yaml
-    needs: [choose-channels]
   - id: post
     uses: ./post.yaml
-    needs: [choose-channels]
 ```
 
-The success emit names one or more of those successor ids in `fork_choice`.
+To skip a channel, add `if` on that `to:` (keep an ungated sibling if the other channel should always run).
+
+### Review send-back (loop)
+
+```yaml
+stages:
+  - id: implement
+    uses: ./implement.yaml
+    entry: true
+    route:
+      - to: review
+  - id: review
+    uses: ./review.yaml
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 2
+        on_max_replays: require_continue
+        replay_session: resume
+  - id: submit
+    uses: ./submit.yaml
+    replay_safe: false
+```
+
+Success emit from `review` includes envelope `feedback_loop`: `{ action: continue }` or `{ action: send_back, target: implement }`.

package/skills/stageflow-author/references/catalog-write-conventions.md

@@ -17,10 +17,10 @@ One directory (or the project root) holds:
 
 | File | Required fields |
 |---|---|
-| `<pipeline-id>.pipeline.yaml` | `id` matching the filename stem; `stages:` object entries |
-| `<stage-id>.yaml` | `id`, `system_prompt`; `model` when not inherited; `io` / `verify` / `gate_kinds` when the step needs them |
+| `<pipeline-id>.pipeline.yaml` | `id` matching the filename stem; `stages:` array of object entries |
+| `<stage-id>.yaml` | `id`, `system_prompt`; `model` when not inherited; required `io.input.schema` and `io.output.schema`; `verify` / `gate_kinds` when the step needs them |
 
-Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). Non-root stages add `needs: <parent-id>` or `needs: [<parent-id>, …]` (length ≥ 1; strings or `{ id, on }`). A deciding stage adds `fork:`. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. Filename stem matches `id` on every file. Optional pipeline-root `model` fills stages that omit `model`.
+Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). At least one root marks `entry: true`. Sources list forward `route: [{ to: <id> }, …]`. Optional `on:` is skip-cascade policy (default succeeded-only); it does not launch from skipped/failed. Optional `if` gates a successor after the source succeeds (predicate on required `io.output.schema` fields). A review that can send work back adds `{ type: loop, to, max_replays, on_max_replays, replay_session }` inside `route`. A Clone Chain emitter puts `clone_cap` and `clone_mode` on that **pipeline entry**, never on the reusable stage body. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. Filename stem matches `id`. Optional pipeline-root `model` fills stages that omit `model`. Sequencing rules: [`catalog-mapping.md`](catalog-mapping.md). Catalog load rejects `needs`, `fork`, and `feedback_loop` as YAML keys.
 
 ## Collisions