stageflow 0.23.0 → 0.27.0

package/examples/feedback-loop/README.md

@@ -0,0 +1,72 @@
+# feedback-loop
+
+Source-owned feedback loop: `review` may `continue` or `send_back` to `implement`.
+`submit` is `replay_safe: false` so it is never on a replay route.
+
+Catalog policy is a `{ type: loop }` entry on `route` (not a top-level `feedback_loop:` key). The envelope field is still `feedback_loop`. See [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops) and [`feedback-loop.pipeline.yaml`](../../tests/fixtures/pipelines/feedback-loop.pipeline.yaml).
+
+Domain-neutral — the same wiring works for release notes, research digests, content review, or an SDLC-style plan/implement pass.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed (`npm i -g stageflow`), **or** this repo built (`npm run build`)
+- Provider auth connected (`sf ui` → Settings → Providers, or `sf providers login …`)
+
+## Manual verification (recommended)
+
+Step-by-step scenarios A–D (continue, one send_back, require_continue exhaust, wait_for_human decide):
+
+→ **[VERIFY.md](./VERIFY.md)**
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+sf run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/feedback-loop.task.yaml
+```
+
+Wait-for-human policy (`max_replays: 1`):
+
+```bash
+sf run \
+  --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-wait-human.task.yaml
+```
+
+Optional console (any subdirectory):
+
+```bash
+cd examples/feedback-loop && sf ui
+```
+
+### From the Stageflow repo (no global install)
+
+```bash
+npm run build
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/feedback-loop.task.yaml
+```
+
+## Layout
+
+```
+examples/feedback-loop/
+  VERIFY.md                          # manual scenarios A–D
+  feedback-loop.pipeline.yaml        # require_continue, max_replays 2
+  feedback-loop-wait-human.pipeline.yaml
+  feedback-loop.task.yaml
+  continue-only / send-back-once / exhaust-*.task.yaml
+  plan.yaml | implement.yaml | review.yaml | submit.yaml
+```
+
+## References
+
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)
+- [Envelopes — Feedback loops](../../docs/envelopes.md#feedback-loops)
+- [CLI — feedback-decide](../../docs/cli-reference.md#sf-runs-feedback-decide)

package/examples/feedback-loop/VERIFY.md

@@ -0,0 +1,208 @@
+# Feedback-loop manual verification
+
+Simple runs to exercise the feedback-loop work from this repo. Uses a real provider (not FakeAgent).
+
+## Setup
+
+```bash
+cd /path/to/software-factory
+npm i
+npm run build
+# Provider auth once (example stages use omniroute/auto)
+# Connect via: npm run dev -- ui  → Settings → Providers
+```
+
+Use `npm run dev -- …` as `sf` from this worktree. Run state lives in `<repo>/.stageflow/`.
+
+Optional console:
+
+```bash
+npm run dev -- ui
+```
+
+If `sf ui` is up on `:3847`, mutating CLI (`runs feedback-decide`) is refused — decide in the UI panel, or stop the host and use CLI.
+
+Validate once:
+
+```bash
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml --strict
+```
+
+---
+
+## Scenario A — Continue only (happy path)
+
+**Expect:** `plan → implement → review → submit`, no replay.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/continue-only.task.yaml \
+  --json > /tmp/fb-a.json
+```
+
+**Pass:** exit `0`; all four stages `succeeded`; `submit` ran once.
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-a.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  stages: [.stages[] | {id: .stage_id, status}],
+  active: .active_feedback_loop,
+  loops: [.feedback_loops[]?.loop.state]
+}'
+```
+
+**Fail:** any `send_back`, or `submit` never runs.
+
+---
+
+## Scenario B — One send_back, then continue
+
+**Expect:** review sends back to `implement` once; replay includes Feedback Loop Context; then continue → submit.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/send-back-once.task.yaml \
+  --json > /tmp/fb-b.json
+```
+
+**Pass:**
+
+- Stage path roughly `plan → implement → review → implement → review → submit`
+- One replay in history; loop ends `continued`
+- On the replayed stages, the agent prompt shows a **Feedback Loop Context** block
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-b.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  stages: [.stages[] | {id: .stage_id, status}],
+  replays: [.feedback_loops[0].replays[] | {
+    n: .replay.replay_number,
+    target: .replay.target_stage_id,
+    status: .replay.status
+  }],
+  loop: .feedback_loops[0].loop.state
+}'
+```
+
+UI: Feedback Loop panel shows budget / route / replay timeline.
+
+**Fail:** submit before continue; no replay recorded; no Feedback Loop Context on replay.
+
+---
+
+## Scenario C — Exhaust `require_continue` (over-limit send_back fails)
+
+Pipeline: `max_replays: 2`, `on_max_replays: require_continue`.
+
+**Expect:** two accepted send_backs, third rejected; `submit` never succeeds.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-require-continue.task.yaml \
+  --json > /tmp/fb-c.json
+```
+
+**Pass:** run failed; ~2 replays; failure mentions `max_replays` / `require_continue`; `submit` not succeeded.
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-c.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  failed_stage_id,
+  failed_reason,
+  replay_count: (.feedback_loops[0].replays | length),
+  submit: [.stages[] | select(.stage_id=="submit") | .status]
+}'
+```
+
+**Fail:** third send_back accepted; run succeeds; or parks for human (wrong policy).
+
+---
+
+## Scenario D — Exhaust `wait_for_human`, then decide
+
+Pipeline: `feedback-loop-wait-human.pipeline.yaml` (`max_replays: 1`, `on_max_replays: wait_for_human`).
+
+**Pairing:** You **must** use `feedback-loop-wait-human.pipeline.yaml` with `exhaust-wait-human.task.yaml`. The default `feedback-loop.pipeline.yaml` uses `require_continue` — wrong pipeline means **no human ask** (run fails on over-limit send_back instead of parking). Every review success until park must `send_back` (never `continue`).
+
+**Expect:** second send_back parks the run; you choose extend / continue / abandon.
+
+Prefer **no** `sf ui` on `:3847` if you will use CLI decide.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-wait-human.task.yaml \
+  --json > /tmp/fb-d.json
+# Exit 2 when parked waiting is normal
+```
+
+Inspect the park:
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-d.json)
+npm run dev -- runs waiting --run "$RUN" --json
+npm run dev -- runs show --run "$RUN" --json | jq '.active_feedback_loop | {
+  state, policy, deferred_send_back
+}'
+```
+
+Expect `waiting_kind: "feedback_loop_decision"`, `state: "waiting_for_human"`, deferred target `implement`.
+
+Pick **one** decision (host down for CLI):
+
+```bash
+# Extra replay budget, then agent should continue later
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision extend --json
+
+# Or release downstream without another replay
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision continue --json
+
+# Or fail the run
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision abandon --reason "stop" --json
+```
+
+With `sf ui` instead: open the run → FeedbackDecidePanel → Extend / Continue / Abandon.
+
+After decide, wait for terminal if needed:
+
+```bash
+npm run dev -- runs wait --run "$RUN" --until terminal --timeout-ms 240000 --json
+```
+
+**Pass:**
+
+| Decision | Expect |
+|----------|--------|
+| `extend` | `effect: extended`; another implement→review; then continue → submit; `max_replays` bumped by 1 |
+| `continue` | `effect: continued`; submit runs; no further replay |
+| `abandon` | run `failed`; submit never runs |
+
+**Fail:** second send_back rejected instead of parking; decide refused while host is still up.
+
+---
+
+## Quick matrix
+
+| Scenario | Pipeline | Task | Cost note |
+|----------|----------|------|-----------|
+| A Continue | `feedback-loop.pipeline.yaml` | `continue-only.task.yaml` | ~4 stages |
+| B One send_back | `feedback-loop.pipeline.yaml` | `send-back-once.task.yaml` | ~6 stage runs |
+| C require_continue exhaust | `feedback-loop.pipeline.yaml` | `exhaust-require-continue.task.yaml` | ~7+ stage runs, expects failure |
+| D wait_for_human | `feedback-loop-wait-human.pipeline.yaml` | `exhaust-wait-human.task.yaml` | parks; then decide |
+
+Clone-chain Loop from Join is covered by fixture
+[`tests/fixtures/pipelines/clone-chain-loop-from-join.pipeline.yaml`](../../tests/fixtures/pipelines/clone-chain-loop-from-join.pipeline.yaml),
+not this walkthrough.
+
+## References
+
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)
+- [CLI — feedback-decide](../../docs/cli-reference.md#sf-runs-feedback-decide)
+- [Envelopes — Feedback loops](../../docs/envelopes.md#feedback-loops)

package/examples/feedback-loop/continue-only.task.yaml

@@ -0,0 +1,4 @@
+id: feedback-loop-continue-only
+goal: Draft a short brief and submit it after review continues on the first pass
+context: Verification scenario — review must emit continue (no send_back)
+constraints: Docs only. review must emit feedback_loop.action continue on the first success.

package/examples/feedback-loop/exhaust-require-continue.task.yaml

@@ -0,0 +1,6 @@
+id: feedback-loop-exhaust-require-continue
+goal: Keep sending work back from review until the loop rejects further send_back
+context: Verification scenario — force require_continue max_replays exhaustion
+constraints: |
+  Docs only. Every successful review must emit feedback_loop send_back target implement.
+  Never emit continue. Expect the third send_back to fail after max_replays 2.

package/examples/feedback-loop/exhaust-wait-human.task.yaml

@@ -0,0 +1,11 @@
+id: feedback-loop-exhaust-wait-human
+goal: Send work back twice so the loop parks for a human decision
+context: Verification scenario — wait_for_human after max_replays 1
+constraints: |
+  MUST pair with pipeline feedback-loop-wait-human.pipeline.yaml
+  (on_max_replays: wait_for_human, max_replays: 1). Do NOT use
+  feedback-loop.pipeline.yaml (require_continue) — that never asks a human.
+  Docs only. Every review success until the run parks MUST emit send_back
+  target implement — never emit continue. First review: send_back implement;
+  after replay, second review: send_back implement again so the loop parks
+  for feedback-decide.

package/examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml

@@ -0,0 +1,23 @@
+id: feedback-loop-wait-human
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    uses: ./plan.yaml
+  - id: implement
+    route:
+      - to: review
+    uses: ./implement.yaml
+  - id: review
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 1
+        on_max_replays: wait_for_human
+        replay_session: resume
+    uses: ./review.yaml
+  - id: submit
+    uses: ./submit.yaml
+    replay_safe: false

package/examples/feedback-loop/feedback-loop.pipeline.yaml

@@ -0,0 +1,23 @@
+id: feedback-loop
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    uses: ./plan.yaml
+  - id: implement
+    route:
+      - to: review
+    uses: ./implement.yaml
+  - id: review
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 2
+        on_max_replays: require_continue
+        replay_session: resume
+    uses: ./review.yaml
+  - id: submit
+    uses: ./submit.yaml
+    replay_safe: false

package/examples/feedback-loop/feedback-loop.task.yaml

@@ -0,0 +1,4 @@
+id: feedback-loop
+goal: Draft a short brief, revise it until a review stage continues, then submit
+context: Domain-neutral feedback-loop walkthrough — plan → implement → review → submit
+constraints: Docs only; no implementation code. Prefer one send_back then continue.

package/examples/feedback-loop/implement.yaml

@@ -0,0 +1,14 @@
+id: implement
+system_prompt: |
+  Produce the work described by the upstream plan envelope.
+  Keep the deliverable short (a brief outline or draft).
+  Emit a success envelope summarizing what you produced.
+  On a feedback replay, read Feedback Loop Context and address the review feedback.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/plan.yaml

@@ -0,0 +1,14 @@
+id: plan
+system_prompt: |
+  Create a short plan for the task goal.
+  List the sections you will produce and any open questions.
+  Emit a success envelope with a clear summary when done.
+  On a feedback replay, read Feedback Loop Context and revise the plan to address the send-back.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/review.yaml

@@ -0,0 +1,15 @@
+id: review
+system_prompt: |
+  Review the upstream work against the task goal.
+  On success you MUST include feedback_loop in emit_stage_envelope:
+  - {"action":"continue"} when the work is good enough to submit
+  - {"action":"send_back","target":"implement"} when another pass is needed
+  Prefer at most one send_back in this walkthrough, then continue.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/send-back-once.task.yaml

@@ -0,0 +1,6 @@
+id: feedback-loop-send-back-once
+goal: Draft a short brief, send it back once from review, then continue and submit
+context: Verification scenario — exactly one send_back to implement, then continue
+constraints: |
+  Docs only. On the first review success, emit feedback_loop send_back target implement.
+  On the second review success, emit feedback_loop continue. Do not send_back twice.

package/examples/feedback-loop/submit.yaml

@@ -0,0 +1,12 @@
+id: submit
+system_prompt: |
+  Submit the approved work. Summarize the final brief in the envelope.
+  This stage is replay_safe: false — it runs only after review continues.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/generic-fan-in/README.md

@@ -0,0 +1,151 @@
+# generic-fan-in
+
+Dummy catalog for **manual operator-console testing** of generic multi-parent
+fan-in. `research` and `validation` run in parallel after `clarify`, pause on
+a free-text gate, then emit distinct payloads. `synthesize` waits for both and
+must copy `priorEnvelopesByStage` into `payload.received` so you can inspect
+what was handed across the join.
+
+Catalog wiring is outbound `route`: `research` and `validation` each list `to: synthesize`. Join rules (shipped runtime): the child waits until every parent is terminal; it **runs** if at least one parent succeeded (skipped siblings do not block); it stays **pending** if any parent failed (even when `on` lists `failed`); it force-skips only if every parent skipped. Including `failed` or `skipped` in `on:` opts that edge out of skip-cascade; it does not launch the Join from a failed parent.
+
+Wiring matches the fixture twins: [`diamond-fan-in.pipeline.yaml`](../../tests/fixtures/pipelines/diamond-fan-in.pipeline.yaml) and [`diamond-fan-in-accepted.pipeline.yaml`](../../tests/fixtures/pipelines/diamond-fan-in-accepted.pipeline.yaml). See [`docs/yaml-catalog.md#generic-fan-in`](../../docs/yaml-catalog.md#generic-fan-in).
+
+Two pipelines:
+
+| Pipeline | What it exercises |
+|----------|-------------------|
+| `generic-fan-in` | Default succeeded-only edges into `synthesize` |
+| `generic-fan-in-accepted` | Research edge `on: [succeeded, failed, skipped]` — still does **not** run the Join after research fails |
+
+## Prerequisites
+
+Use this repo's CLI (`npm run build` / `npm run dev`) or a Stageflow release
+that includes generic fan-in. A globally installed `sf` from npm may lag.
+
+- Node.js ≥ 20
+- From repo root: `npm run build` and `npm run ui:build`
+- Provider auth connected (`sf ui` → Settings → Providers). Stages use `cursor/auto`.
+
+Run state lives in `<repo>/.stageflow` even if you start the console from a subdirectory.
+
+## Terminal 1 — operator console
+
+From the **repository git root**:
+
+```bash
+npm run build
+npm run ui:build
+PI_CURSOR_SETTING_SOURCES=all STAGEFLOW_ACTIVITY_VERBOSE=1 node dist/cli.js ui
+```
+
+`npm run dev -- ui` runs the TypeScript CLI via tsx; use `node dist/cli.js ui` after `ui:build` so the console is served from `dist/ui`. Do not use a globally installed `sf` — Homebrew `sf` is an older build that cannot load this catalog.
+
+Open `http://127.0.0.1:3847`. Browse should list **generic-fan-in** and **generic-fan-in-accepted** (same names as the YAML files).
+
+## Terminal 2 — start a run (repo root)
+
+```bash
+node dist/cli.js validate --pipeline examples/generic-fan-in/generic-fan-in.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/generic-fan-in/generic-fan-in.pipeline.yaml \
+  --task examples/generic-fan-in/generic-fan-in.task.yaml
+```
+
+Exit code `2` means waiting on operator input. Leave this terminal; do the rest in the console.
+
+Start a **new run** for each scenario below. Do not reuse a finished run.
+
+---
+
+## Scenario A — both parents succeed (main envelope check)
+
+At **research**, answer exactly:
+
+```
+ok glaciers
+```
+
+At **validation**, answer exactly:
+
+```
+ok citations
+```
+
+Order of answers does not matter. `synthesize` starts only after both succeed.
+
+### What to verify
+
+1. Track is a diamond: `clarify` fans out to **research** and **validation**, then both wires inbound into **synthesize**.
+2. While only one parent is answered, select **synthesize**. It stays blocked. Copy / `blocked_by` lists the remaining parent, not only the first YAML parent.
+3. After `research` succeeds, select it and open **Files → Handoff envelope** (or `#/runs/<runId>/stages/research/envelope`). Payload should have `finding: glaciers`.
+4. After `validation` succeeds, open its handoff envelope. Payload should have `finding: citations`.
+5. **synthesize** runs once both parents succeeded. Open its handoff envelope. Confirm:
+   - `payload.received` has keys `research` then `validation` (YAML declaration order, not the order you answered).
+   - `received.research.finding` is `glaciers` and `received.validation.finding` is `citations`.
+   - Summary mentions both parent keys and their success status.
+6. From the repo root, you can also print the same records:
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage research --json
+node dist/cli.js envelope get --run <runId> --stage validation --json
+node dist/cli.js envelope get --run <runId> --stage synthesize --json
+```
+
+`<runId>` is on the run detail URL (`#/runs/<runId>/…`) and in the run list.
+
+The synthesize payload is the join copy of `priorEnvelopesByStage`. That field is keyed; it is not a clone-list `priorEnvelopes` array, and `priorEnvelope` is null on the join.
+
+---
+
+## Scenario B — failed parent leaves the join pending
+
+New run of **generic-fan-in**. At research, answer:
+
+```
+fail
+```
+
+At validation, answer:
+
+```
+ok citations
+```
+
+### What to verify
+
+1. **research** is failed (open its handoff envelope — failure status, no finding).
+2. **validation** still finishes; its envelope is success with `citations`.
+3. **synthesize** stays **pending** (not skip-cascaded). A failed parent blocks the Join.
+4. Run outcome **failed**.
+5. Open synthesize anyway: there is no join envelope. The Join did not receive `priorEnvelopesByStage`.
+
+---
+
+## Scenario C — listing `failed` on `on:` still does not open the join
+
+New run:
+
+```bash
+node dist/cli.js run \
+  --pipeline examples/generic-fan-in/generic-fan-in-accepted.pipeline.yaml \
+  --task examples/generic-fan-in/generic-fan-in-accepted.task.yaml
+```
+
+At research, answer `fail`. At validation, answer `ok citations`.
+
+### What to verify
+
+1. **research** stays visibly **failed**. **validation** succeeds.
+2. **synthesize** stays **pending**. Listing `failed` on the research edge only opts that edge out of skip-cascade; it does not launch `synthesize`.
+3. Run outcome **failed**. Skipped siblings would not block a Join that has a succeeded parent; a **failed** parent still does.
+
+---
+
+## Envelope inspector (any scenario)
+
+On a completed stage, the first Files row is **Handoff envelope**. It opens the
+inspector (`#/runs/<runId>/stages/<stageId>/envelope`) with `summary`, `payload`,
+and artifact paths. Use that for the parent envelopes; use **synthesize** for the
+keyed join copy.
+
+CLI equivalent: `node dist/cli.js envelope get --run <runId> --stage <stageId> --json`.

package/examples/generic-fan-in/clarify.yaml

@@ -0,0 +1,18 @@
+id: clarify
+system_prompt: |
+  You are the root of a diamond pipeline. Call emit_stage_envelope exactly once.
+
+  Emit status success, artifacts [], payload { "brief": "diamond start" },
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string

package/examples/generic-fan-in/generic-fan-in-accepted.pipeline.yaml

@@ -0,0 +1,19 @@
+id: generic-fan-in-accepted
+stages:
+  - id: clarify
+    entry: true
+    route:
+      - to: research
+      - to: validation
+    uses: ./clarify.yaml
+  - id: research
+    route:
+      - to: synthesize
+        on: [succeeded, failed, skipped]
+    uses: ./research.yaml
+  - id: validation
+    route:
+      - to: synthesize
+    uses: ./validation.yaml
+  - id: synthesize
+    uses: ./synthesize.yaml

package/examples/generic-fan-in/generic-fan-in-accepted.task.yaml

@@ -0,0 +1,8 @@
+id: generic-fan-in-accepted
+goal: |
+  Dummy walkthrough for an accepted-failure diamond. research may succeed or
+  fail. validation must succeed. synthesize still runs when research fails and
+  must copy that failure envelope under received.research.
+context: |
+  Manual operator-console test. Reply fail at research and ok citations at
+  validation, then open synthesize to see the keyed failure + success pair.

package/examples/generic-fan-in/generic-fan-in.pipeline.yaml

@@ -0,0 +1,18 @@
+id: generic-fan-in
+stages:
+  - id: clarify
+    entry: true
+    route:
+      - to: research
+      - to: validation
+    uses: ./clarify.yaml
+  - id: research
+    route:
+      - to: synthesize
+    uses: ./research.yaml
+  - id: validation
+    route:
+      - to: synthesize
+    uses: ./validation.yaml
+  - id: synthesize
+    uses: ./synthesize.yaml

package/examples/generic-fan-in/generic-fan-in.task.yaml

@@ -0,0 +1,9 @@
+id: generic-fan-in
+goal: |
+  Dummy walkthrough for generic multi-parent fan-in. research and validation
+  run in parallel after clarify. Reply to each with ok <finding> or fail.
+  synthesize waits for both and must copy priorEnvelopesByStage into payload.received.
+context: |
+  Manual operator-console test. Distinct findings (for example glaciers and
+  citations) make it obvious which parent envelope landed under which key.
+  On fail of either parent, synthesize is skipped and the run fails.