stageflow 0.12.0 → 0.15.0

package/dist/ui/index.html

@@ -13,7 +13,7 @@
     <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-CXGz4nL7.js"></script>
+    <script type="module" crossorigin src="/assets/index-GtyiWiZg.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-uVHiae8s.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.12.0",
+  "version": "0.15.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -63,9 +63,12 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.263",
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "better-sqlite3": "^13.0.3",
+    "jiti": "^2.7.0",
+    "pi-mcp-adapter": "^2.32.1",
     "typebox": "^1.3.7",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"

package/skills/stageflow-author/SKILL.md

@@ -35,9 +35,27 @@ Ask until you can name every step, how they sequence, any decision point, and an
 
 ## Map
 
-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`, `model`, and `gate_kinds`.
+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, and a prompt plan per stage.
+**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.
+
+## Anti-patterns
+
+Author these contracts explicitly. They come from long runs that failed after hours of real work.
+
+| 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. |
+| 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. |
+| 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. |
+
+Throwaway checkout deliverables (HTML spike, scratch file): prompt builtin `write` at a checkout-relative path, `artifacts: []` on emit, path in `payload`.
 
 ## Locate
 

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

@@ -7,4 +7,12 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you repaired.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - repaired
+      properties:
+        repaired:
+          type: boolean

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

@@ -1,4 +1,5 @@
 id: release-gate
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: run-tests
     uses: ./run-tests.yaml
@@ -6,7 +7,10 @@ stages:
       select: one
   - id: hotfix
     uses: ./hotfix.yaml
-    needs: run-tests
+    needs: [run-tests]
   - id: ship
     uses: ./ship.yaml
-    needs: run-tests
+    needs: [run-tests]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

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

@@ -10,4 +10,12 @@ system_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: hotfix when the results fail, ship when they pass.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - ready
+      properties:
+        ready:
+          type: boolean

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

@@ -7,4 +7,19 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you shipped.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - shipped
+      properties:
+        shipped:
+          type: boolean
+verify:
+  - id: ship-notes
+    type: artifact
+    path: ship.md
+    nonempty: true
+    when:
+      - after

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

@@ -5,5 +5,15 @@ system_prompt: |
   Write the draft via write_stage_artifact (for example draft.md).
 
   When finished, call emit_stage_envelope exactly once with status, summary,
-  artifacts, and a payload the next stage can use.
-model: anthropic/claude-sonnet-4-5
+  artifacts, and a payload the next stage can use. Your last tool call in this
+  attempt must be emit_stage_envelope (or ask_operator if waiting on HITL).
+  An empty final message is a stage failure.
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - title
+      properties:
+        title:
+          type: string

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

@@ -7,4 +7,19 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing what you produced.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - published
+      properties:
+        published:
+          type: boolean
+verify:
+  - id: published-artifact
+    type: artifact
+    path: published.md
+    nonempty: true
+    when:
+      - after

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

@@ -1,10 +1,19 @@
 id: review-loop
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: draft
     uses: ./draft.yaml
   - id: review
     uses: ./review.yaml
-    needs: draft
+    needs: [draft]
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
   - id: publish
     uses: ./publish.yaml
-    needs: review
+    needs: [review]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

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

@@ -12,4 +12,22 @@ system_prompt: |
      again with artifact_backed in this same stage. Do not complete yet.
   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:
+  output:
+    schema:
+      type: object
+      required:
+        - verdict
+      properties:
+        verdict:
+          type: string
+verify:
+  - id: review-accepted
+    type: gate
+    kind: artifact_backed
+  - id: review-artifact
+    type: artifact
+    path: review.md
+    nonempty: true
+    when:
+      - after

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

@@ -6,4 +6,12 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload the next stage can use.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - source_count
+      properties:
+        source_count:
+          type: integer

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

@@ -1,10 +1,14 @@
 id: research-digest
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: gather
     uses: ./gather.yaml
   - id: summarize
     uses: ./summarize.yaml
-    needs: gather
+    needs: [gather]
   - id: send
     uses: ./send.yaml
-    needs: summarize
+    needs: [summarize]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

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

@@ -7,4 +7,19 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload describing who received the digest.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - sent
+      properties:
+        sent:
+          type: boolean
+verify:
+  - id: sent-record
+    type: artifact
+    path: sent.md
+    nonempty: true
+    when:
+      - after

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

@@ -6,4 +6,12 @@ system_prompt: |
 
   When finished, call emit_stage_envelope exactly once with status, summary,
   artifacts, and a payload the next stage can use.
-model: anthropic/claude-sonnet-4-5
+io:
+  output:
+    schema:
+      type: object
+      required:
+        - headline
+      properties:
+        headline:
+          type: string

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

@@ -16,7 +16,7 @@ Collision handling lives in [`catalog-write-conventions.md`](catalog-write-conve
 
 ## Sequencing
 
-`needs` is a single parent stage id, or an array of at least two parent ids when one step waits for several earlier steps. Strings default to `on: [succeeded]`. `{ id, on }` accepts a non-empty unique subset of `succeeded` | `failed` | `skipped`.
+`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`.
 
 | Human says | Pipeline shape |
 |---|---|
@@ -28,30 +28,93 @@ Collision handling lives in [`catalog-write-conventions.md`](catalog-write-conve
 
 Default `select` is `one` unless the human says more than one branch can run.
 
-Map linear chains, sibling fan-out, generic fan-in (`needs` array), and single-level `fork`. A runtime clone count is not knowable from a static description — leave `clonable` and `clone_forks` unset. Clone-list joins (one catalog parent, `priorEnvelopes`) are not this shape.
+Map linear chains, sibling fan-out, generic fan-in (`needs` array), and single-level `fork`.
 
 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).
 
+## Review then fix then approve
+
+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.
+
+## Verify and on_verify_fail
+
+Put `verify` on the **stage body** (the `uses:` file or inline entry). Put `on_verify_fail` on the **pipeline** stage entry (the `uses:` wrapper). Use when the human needs a hard gate before advance:
+
+| Need | Catalog |
+|---|---|
+| Required file under the attempt artifact dir | `verify` with `type: artifact`, `path`, usually `nonempty: true`, `when: [after]` |
+| HITL must complete this attempt | `type: gate` with `kind` that appears in the stage's `gate_kinds` (default `when: [emit]`) |
+| Implement must change the checkout | `type: checkout_changes` with `path_fields` naming required arrays in `io.output.schema` |
+| Auto-retry when after-phase verify fails | `on_verify_fail: { mode: repair, max_attempts: N, retry_safety: idempotent, include_failed_checks: true }` |
+| Side-effecting publish / ship | `on_verify_fail: { mode: manual, retry_safety: side_effecting }` |
+
+`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
+
+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.
+
+When the human explicitly wants N parallel instances of **one** successor catalog id (e.g. several review lenses, several prototype variants):
+
+- 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`.
+
+`fork` + `fork_choice` picks which **branch stage ids** run. `clone_forks` spawns **N instances** of one successor id.
+
+## 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.
+
 ## Worked examples
 
 ### Review loop (linear)
 
-Three sequential steps; the middle one is a sign-off.
+Three sequential steps; the middle one is a sign-off. Reject/revise stays inside the gated `review` stage.
 
 ```yaml
 id: review-loop
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: draft
     uses: ./draft.yaml
   - id: review
     uses: ./review.yaml
-    needs: draft
+    needs: [draft]
   - id: publish
     uses: ./publish.yaml
-    needs: review
+    needs: [review]
+```
+
+`review` carries `gate_kinds: [artifact_backed]` and emit-phase `verify` `type: gate`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-review/).
+
+### Review with separate fix stage
+
+When review can emit blockers and a later stage approves or ships, insert address-feedback between them:
+
+```yaml
+stages:
+  - id: implement
+    uses: ./implement.yaml
+  - id: review
+    uses: ./review.yaml
+    needs: [implement]
+  - id: address-feedback
+    uses: ./address-feedback.yaml
+    needs: [review]
+  - id: approve
+    uses: ./approve.yaml
+    needs: [address-feedback]
 ```
 
-`review` carries `gate_kinds: [artifact_backed]`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-review/).
+Do not make `approve` / `ship` `needs: review` when blockers are expected.
 
 ### Release gate (fork, select one)
 
@@ -66,10 +129,10 @@ stages:
       select: one
   - id: hotfix
     uses: ./hotfix.yaml
-    needs: run-tests
+    needs: [run-tests]
   - id: ship
     uses: ./ship.yaml
-    needs: run-tests
+    needs: [run-tests]
 ```
 
 Full set: [`../assets/examples/branch-decision/`](../assets/examples/branch-decision/).
@@ -85,10 +148,10 @@ stages:
     uses: ./gather.yaml
   - id: summarize
     uses: ./summarize.yaml
-    needs: gather
+    needs: [gather]
   - id: send
     uses: ./send.yaml
-    needs: summarize
+    needs: [summarize]
 ```
 
 Full set: [`../assets/examples/non-sdlc-digest/`](../assets/examples/non-sdlc-digest/).
@@ -103,10 +166,10 @@ stages:
     uses: ./intake.yaml
   - id: collect-quotes
     uses: ./collect-quotes.yaml
-    needs: intake
+    needs: [intake]
   - id: collect-notes
     uses: ./collect-notes.yaml
-    needs: intake
+    needs: [intake]
 ```
 
 No `fork` field. Both siblings run.
@@ -121,10 +184,10 @@ stages:
     uses: ./clarify.yaml
   - id: research
     uses: ./research.yaml
-    needs: clarify
+    needs: [clarify]
   - id: validation
     uses: ./validation.yaml
-    needs: clarify
+    needs: [clarify]
   - id: synthesize
     uses: ./synthesize.yaml
     needs:
@@ -132,7 +195,7 @@ stages:
       - validation
 ```
 
-`needs` array length is ≥ 2. The join reads `priorEnvelopesByStage`, not clone-list `priorEnvelopes`.
+`needs` array length ≥ 2 is keyed fan-in. The join reads `priorEnvelopesByStage`, not clone-list `priorEnvelopes`.
 
 ### Fork, select subset
 
@@ -146,10 +209,10 @@ stages:
       select: subset
   - id: email
     uses: ./email.yaml
-    needs: choose-channels
+    needs: [choose-channels]
   - id: post
     uses: ./post.yaml
-    needs: choose-channels
+    needs: [choose-channels]
 ```
 
 The success emit names one or more of those successor ids in `fork_choice`.

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

@@ -18,9 +18,9 @@ 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`; `gate_kinds` when the step is gated |
+| `<stage-id>.yaml` | `id`, `system_prompt`; `model` when not inherited; `io` / `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:` as an array of at least two parent ids (strings or `{ id, on }`) when the stage waits for several parents. A deciding stage adds `fork:`. Filename stem matches `id` on every file.
+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`.
 
 ## Collisions
 

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

@@ -1,6 +1,6 @@
 # Stage prompt template
 
-Every external stage file has `id`, `system_prompt`, and `model`. Filename stem matches `id`. Default `model` is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim.
+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.
 
 ## Base
 
@@ -14,12 +14,48 @@ system_prompt: |
   Write any output this step produces via write_stage_artifact.
 
   When finished, call emit_stage_envelope exactly once with status, summary,
-  artifacts, and a payload the next stage can use.
+  artifacts, and a payload the next stage can use. Your last tool call in this
+  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
 ```
 
 The prompt has no `ask_operator` line. It ends on the `emit_stage_envelope` instruction. Call `emit_stage_envelope` once per attempt.
 
+When the pipeline entry will carry after-phase `verify` with `type: artifact`, add this line after the goal:
+
+```
+Required files must be created with write_stage_artifact. Checkout write/edit
+does not satisfy after-phase verify.
+```
+
+When the stage must change the project checkout (implement, patch, edit source), add:
+
+```
+Success requires real checkout edits. Put checkout-relative paths in
+payload.changed_files. Do not put stages/.../artifacts paths there. A report
+or map alone is a failure emit, not success.
+```
+
+When the deliverable is throwaway checkout content instead of a stage artifact:
+
+```
+Write the deliverable with builtin write at <checkout-relative path>.
+Set artifacts: [] on emit. Put that path in payload.<field>.
+```
+
+## Summary and payload
+
+Add to every stage (base, gated, or fork):
+
+```
+summary and payload are handed to the next stage verbatim. State outcomes and
+artifact pointers only. Do not repeat this stage's prohibitions in summary —
+downstream will obey them literally.
+```
+
+When `io.output.schema` is on the stage file, name the required fields in the prompt so the emit matches.
+
 ## Gated
 
 When the step is a review, approval, or sign-off, add `gate_kinds` and resolve the gate before emit. Match this sequence: `write_stage_artifact` → `ask_operator` → `emit_stage_envelope` on accept.
@@ -32,7 +68,8 @@ system_prompt: |
   <one-line goal>. Get operator acceptance before completing this stage.
 
   1. Write the reviewable output via write_stage_artifact.
-  2. Call ask_operator with kind artifact_backed referencing that artifact path.
+  2. Call ask_operator with kind artifact_backed referencing that artifact path
+     (stage artifact path, not a checkout path).
   3. On reject or change text: revise the artifact and call ask_operator again
      with artifact_backed in this same stage. Do not complete yet.
   4. Call emit_stage_envelope with an advancing success status only after the
@@ -42,6 +79,14 @@ model: anthropic/claude-sonnet-4-5
 
 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.
 
+When the gated stage also publishes or opens a PR after accept, append:
+
+```
+After the operator accepts, immediately finish publish side effects in this
+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
 
 When the pipeline entry has `fork`, the success emit names immediate successors in `fork_choice`. Add this block to the base (or gated) prompt:
@@ -50,6 +95,20 @@ When the pipeline entry has `fork`, the success emit names immediate successors
 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.
+```
+
+`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)).
+
+## Clonable parent
+
+When a successor is `clonable: true`, the parent success emit uses `clone_forks` (not `fork_choice`) for that successor. Add:
+
+```
+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.
 ```
 
-`fork_choice` on a failure emit is ignored. Leave `clone_forks` unset.
+Clonable child stages use the base (or gated) prompt. Remind them they are one clone among others and must emit independently.

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

@@ -74,7 +74,7 @@ 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`, `model`). End every `system_prompt` with an `emit_stage_envelope` footer. Omit `gate_kinds`. Filename stem must match `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.
 
 Do not write a `*.task.yaml`.

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

@@ -1,7 +1,8 @@
 id: example
+model: anthropic/claude-sonnet-4-5
 stages:
   - id: research
     uses: ./research.yaml
   - id: implement
     uses: ./implement.yaml
-    needs: research
+    needs: [research]

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

@@ -4,5 +4,16 @@ system_prompt: |
   there. Prefer what already worked in the source session.
 
   When finished, call emit_stage_envelope once with status, summary, artifacts,
-  and a payload describing what you produced.
-model: anthropic/claude-sonnet-4-5
+  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:
+  output:
+    schema:
+      type: object
+      required:
+        - changed_files
+      properties:
+        changed_files:
+          type: array
+          items:
+            type: string

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

@@ -4,5 +4,21 @@ system_prompt: |
   unknown, and the next useful work.
 
   When finished, call emit_stage_envelope once with status, summary, artifacts,
-  and a payload the next stage can use.
-model: anthropic/claude-sonnet-4-5
+  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:
+  output:
+    schema:
+      type: object
+      required:
+        - known
+        - unknown
+      properties:
+        known:
+          type: array
+          items:
+            type: string
+        unknown:
+          type: array
+          items:
+            type: string