stageflow 0.13.0 → 0.15.0

package/skills/stageflow-author/SKILL.md

@@ -35,9 +35,9 @@ 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`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan `completion` / `recovery` on pipeline entries. When a review can demand changes, include an address-feedback stage before approve/ship.
+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 `completion` / `recovery` / remediation stages the structure requires.
+**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
 
@@ -46,14 +46,14 @@ 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. |
-| Land required files in the attempt artifact dir | Prompt `write_stage_artifact`. Pipeline `completion.checks` with `type: artifact`. `ask_operator` `artifact_backed` references that same path. |
-| Make implement stages change the checkout | Pipeline `checkout_changes` + `path_fields`; stage `payload_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 `payload_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 `payload_schema`. |
+| 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 `clone_input_schema`. Leave clonable unset when the clone count is unknown. |
+| 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`.
 

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 |
 |---|---|
@@ -42,19 +42,19 @@ When the human wants a review that can demand changes, then a later approve/ship
 
 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.
 
-## Completion and recovery
+## Verify and on_verify_fail
 
-Put `completion` / `recovery` on the **pipeline** stage entry (the `uses:` wrapper), not on the stage body. Use when the human needs a hard gate before advance:
+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 | Pipeline wiring |
+| Need | Catalog |
 |---|---|
-| Required file under the attempt artifact dir | `completion.checks` with `type: artifact`, `path`, usually `nonempty: true` |
-| HITL must complete | `type: gate` with `kind` that appears in the stage's `gate_kinds` |
-| Implement must change the checkout | `type: checkout_changes` with `path_fields` naming required arrays in `payload_schema` |
-| Auto-retry after verification fail | `recovery: { mode: repair, max_attempts: N, retry_safety: idempotent, include_failed_checks: true }` |
-| Side-effecting publish / ship | `recovery: { mode: manual, retry_safety: side_effecting }` |
+| 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 }` |
 
-`completion.mode` is `all`. Check `id` values must be unique within the stage. Wire these for writer stages and final gates; prompts alone do not enforce them.
+`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
 
@@ -64,7 +64,7 @@ When the human explicitly wants N parallel instances of **one** successor catalo
 
 - 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 `clone_input_schema` on the clonable stage body.
+- 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.
@@ -81,18 +81,19 @@ Three sequential steps; the middle one is a sign-off. Reject/revise stays inside
 
 ```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]`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-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
 
@@ -104,16 +105,17 @@ stages:
     uses: ./implement.yaml
   - id: review
     uses: ./review.yaml
-    needs: implement
+    needs: [implement]
   - id: address-feedback
     uses: ./address-feedback.yaml
-    needs: review
+    needs: [review]
   - id: approve
     uses: ./approve.yaml
-    needs: address-feedback
+    needs: [address-feedback]
 ```
 
 Do not make `approve` / `ship` `needs: review` when blockers are expected.
+
 ### Release gate (fork, select one)
 
 One deciding step, then exactly one successor.
@@ -127,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/).
@@ -146,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/).
@@ -164,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.
@@ -182,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:
@@ -193,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
 
@@ -207,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. 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` 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
 
@@ -22,11 +22,11 @@ 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 `completion.checks` with `type: artifact`, add this line after the goal:
+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 completion checks.
+does not satisfy after-phase verify.
 ```
 
 When the stage must change the project checkout (implement, patch, edit source), add:
@@ -54,7 +54,7 @@ artifact pointers only. Do not repeat this stage's prohibitions in summary —
 downstream will obey them literally.
 ```
 
-When `payload_schema` is on the stage file, name the required fields in the prompt so the emit matches.
+When `io.output.schema` is on the stage file, name the required fields in the prompt so the emit matches.
 
 ## Gated
 
@@ -108,7 +108,7 @@ When a successor is `clonable: true`, the parent success emit uses `clone_forks`
 ```
 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 clone_input_schema — not a stub object.
+matching that successor's io.input.schema — not a stub object.
 ```
 
 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

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`, `model`. Filename stem must match `id` (`research.yaml` → `id: research`).
+Required fields: `id`, `system_prompt`. 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,7 @@ 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.
+`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.
 
 Worked example: `assets/example-pipeline/example.pipeline.yaml`.