stageflow 0.25.0 → 0.27.0

package/examples/retry-tour/README.md

@@ -0,0 +1,75 @@
+# Retry tour
+
+One short spine that walks Stageflow’s **retry surfaces**. Each stage does one job. First passes are supposed to fail; later attempts (or a second emit in the same session) pass.
+
+This catalog is a **deep spine**: ungated `to:` is the next stop. Open the stage after each stop and inspect **attempts** — automatic repair is a second attempt on the same node, not a new stage.
+
+Two stops need you: **Retry with guidance** on `manual-recover`, then **Retry** on `ordinary-retry`.
+
+## Run
+
+From the repo git root, after `sf ui` is up, pick pipeline `retry-tour` and task `retry-tour`.
+
+Or:
+
+```bash
+npx tsx src/cli.ts validate --pipeline examples/retry-tour/retry-tour.pipeline.yaml
+npx tsx src/cli.ts run \
+  --pipeline examples/retry-tour/retry-tour.pipeline.yaml \
+  --task examples/retry-tour/retry-tour.task.yaml
+```
+
+Validate should succeed (`ok: true`). You may see `pipeline.model_applies` because `model` is set on the pipeline, not on each stage.
+
+The run should **succeed** after the two operator actions below. If a model writes `proof.md` on attempt 1, that stop is not covered — rerun.
+
+## Walk (follow-along order)
+
+| Level | Stage | Retry surface | What you do |
+|-------|-------|---------------|-------------|
+| 1 | `kickoff` | none | Watch it succeed |
+| 2 | `emit-retry` | Emit-phase verify soft reject | Same attempt: first emit is rejected (`note.md` missing), second emit succeeds. Attempt stays **1** |
+| 3 | `auto-repair` | `on_verify_fail.mode: repair` | Attempt 1 omits `proof.md` → after-verify fails → Stageflow starts attempt 2 by itself. Attempt 2 writes `proof.md`. No click |
+| 4 | `manual-recover` | `on_verify_fail.mode: manual` | Attempt 1 fails after-verify. Stage stays **failed**. Select it → type guidance (for example `Write proof.md this time`) → **Retry with guidance**. Do **not** use **Retry**. Do **not** **Stop recovery** |
+| 5 | `ordinary-retry` | Ordinary **Retry** (no `on_verify_fail`) | Attempt 1 emits `status: failure`. Select it → **Retry**. Attempt 2 emits success |
+| 6 | `done` | none | Runs only after `ordinary-retry` succeeds — proof that Retry unblocked the successor |
+
+## Scenario table
+
+| Scenario | How this pipeline covers it | Evidence |
+|----------|------------------------------|----------|
+| Emit-phase verify rejects in-session | `emit-retry` `type: artifact` `when: [emit]` | First `emit_stage_envelope` is `isError`; second emit is accepted; still attempt 1 |
+| Emit reject does not fail the stage | same | Stage succeeds; no `on_verify_fail` |
+| Automatic repair after after-phase fail | `auto-repair` `mode: repair` `max_attempts: 2` | Attempt 1 verification **failed**; attempt 2 **passed**; stage succeeded with no click |
+| `max_attempts: 2` means 1 initial + 1 repair | same | Exactly two attempts on `auto-repair` |
+| Failed-check capsule on repair | `include_failed_checks: true` | Attempt 2 prompt contains failed-check evidence for `proof-on-disk` |
+| Repair is a fresh attempt | same | Attempt 2 has its own artifacts dir |
+| Manual recovery (not auto) | `manual-recover` `mode: manual` `retry_safety: side_effecting` | After attempt 1 fail, stage stays failed until Recover |
+| Ordinary **Retry** is refused here | same | Map/workspace **Retry** should 409; use **Retry with guidance** |
+| Recover with guidance | operator types guidance | Attempt 2 prompt includes operator instructions + failed-check capsule |
+| Ordinary Retry after agent failure | `ordinary-retry` emits `status: failure` | No after-verify; **Retry** is offered |
+| Retry unblocks the successor | `done` | `done` does not start while `ordinary-retry` is failed; it runs after Retry succeeds |
+
+## Expected stage status (after the full walk)
+
+| Stage | Attempts | Final status | Why |
+|-------|----------|--------------|-----|
+| `kickoff` | 1 | succeeded | entry |
+| `emit-retry` | 1 | succeeded | two emits, one attempt |
+| `auto-repair` | 2 | succeeded | automatic repair |
+| `manual-recover` | 2 | succeeded | you Recovered |
+| `ordinary-retry` | 2 | succeeded | you Retried |
+| `done` | 1 | succeeded | ungated after ordinary-retry success |
+
+Mid-walk: after `auto-repair` succeeds, `manual-recover` is **failed** and the run looks failed until Recover. Then `ordinary-retry` is **failed** until Retry.
+
+## Not in this pipeline
+
+| Scenario | Why it is absent | Where to see it |
+|---------|------------------|-----------------|
+| Repair budget exhausted | would fail the stage after attempt 2 | `max_attempts: 2` with another miss; then ordinary Retry |
+| **Stop recovery** | terminal fail for that stage this run | click it on `manual-recover` instead of Recover |
+| Loop `send_back` / `max_replays` | different product (route loop) | [`examples/route-if-tour/`](../route-if-tour/), [`examples/feedback-loop/`](../feedback-loop/) |
+| `on_verify_fail` with emit-only verify | illegal (`pipeline.invalid_recovery`) | yaml-catalog |
+| `mode: repair` + `retry_safety: side_effecting` | illegal | yaml-catalog |
+| Agent never emits (timeout / hang) | flaky | ordinary Retry after a real hang |

package/examples/retry-tour/retry-tour.pipeline.yaml

@@ -0,0 +1,122 @@
+id: retry-tour
+model: cursor/auto
+schemas:
+  empty:
+    type: object
+stages:
+  - id: kickoff
+    entry: true
+    route:
+      - to: emit-retry
+    system_prompt: |
+      Start the retry tour in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+
+  - id: emit-retry
+    route:
+      - to: auto-repair
+    system_prompt: |
+      Cover emit-phase verify soft reject (same attempt, not a new attempt).
+      You MUST call emit_stage_envelope twice:
+      1. First call: status: success, a one-sentence summary, artifacts: [], payload: {}. Do not write any artifact yet. This emit is rejected because note.md is missing — that is the scenario.
+      2. After that tool error: call write_stage_artifact with path note.md and a short nonempty markdown body. Then emit_stage_envelope again with status: success, a one-sentence summary, artifacts listing the path returned by write_stage_artifact, and payload: {}.
+      Do not skip the failing first emit. Do not call ask_operator.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: note-declared
+        type: artifact
+        basename: note.md
+        when: [emit]
+
+  - id: auto-repair
+    route:
+      - to: manual-recover
+    system_prompt: |
+      Cover on_verify_fail.mode: repair. Look at the artifacts path in this prompt (stages/auto-repair/attempts/N/artifacts/).
+      If N is 1: call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}. Do not write proof.md. After-phase verify will fail and Stageflow will start attempt 2 by itself.
+      If N is 2 or greater, or the user message contains "This is recovery attempt": call write_stage_artifact with path proof.md and a short nonempty body, then emit_stage_envelope with status: success, a one-sentence summary, artifacts listing that path, and payload: {}.
+      Do not call ask_operator. Do not "helpfully" write proof.md on attempt 1.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: proof-on-disk
+        type: artifact
+        path: proof.md
+        nonempty: true
+        when: [after]
+    on_verify_fail:
+      mode: repair
+      max_attempts: 2
+      retry_safety: idempotent
+      include_failed_checks: true
+
+  - id: manual-recover
+    route:
+      - to: ordinary-retry
+    system_prompt: |
+      Cover on_verify_fail.mode: manual. Look at the artifacts path in this prompt (stages/manual-recover/attempts/N/artifacts/).
+      If N is 1: call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}. Do not write proof.md. After-phase verify will fail and this stage stays failed until the operator uses Retry with guidance.
+      If N is 2 or greater, or the user message contains "This is recovery attempt": call write_stage_artifact with path proof.md and a short nonempty body, then emit_stage_envelope with status: success, a one-sentence summary, artifacts listing that path, and payload: {}.
+      Do not call ask_operator. Do not "helpfully" write proof.md on attempt 1.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: proof-on-disk
+        type: artifact
+        path: proof.md
+        nonempty: true
+        when: [after]
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting
+      include_failed_checks: true
+
+  - id: ordinary-retry
+    route:
+      - to: done
+    system_prompt: |
+      Cover ordinary Retry (no on_verify_fail). Look at the artifacts path in this prompt (stages/ordinary-retry/attempts/N/artifacts/).
+      If N is 1: call emit_stage_envelope with status: failure, a one-sentence summary that you failed on purpose, artifacts: [], and payload: {}. Do not emit success.
+      If N is 2 or greater: call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}.
+      Do not call ask_operator.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+
+  - id: done
+    system_prompt: |
+      The retry tour finished. Emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"

package/examples/retry-tour/retry-tour.task.yaml

@@ -0,0 +1,9 @@
+id: retry-tour
+goal: Walk emit soft-reject, automatic repair, manual recover, and ordinary Retry.
+context: |
+  Retry tour — each stage covers one retry surface. First attempts are
+  supposed to fail the check or the stage; later attempts pass. Follow each
+  stage prompt, including intentional failing emits.
+constraints: |
+  Docs only; no checkout edits. One-sentence summaries.
+  Never emit fork_choice. Do not skip the failing first pass on a stage.

package/examples/route-if-tour/README.md

@@ -0,0 +1,202 @@
+# Route `if` tour
+
+One pipeline that walks every **runtime** deterministic-`if` case that can succeed in a single run. Each stage does one job. Payloads are baked into prompts so the gates that we claim to cover actually fire.
+
+This catalog is a **deep spine**. In the operator console you walk **top to bottom**: ungated `to:` continues the story. Gated `if`s are local side branches that mostly leaf. Fan-out exists only where the scenario needs it (several matching `if`s, a join with two parents, skip-cascade, or the two-way split that keeps `quiet` all-gated).
+
+A condition that stays false does **not** count as covering that operator. Misses exist only where skip / quiet-end / join-skip **is** the scenario.
+
+Illegal catalogs (`if` on a loop, optional field, empty `all`, …) cannot live in this file — validate would reject the whole pipeline. Those stay under [`../route-wiring-smoke-test/rejected/`](../route-wiring-smoke-test/).
+
+## Run
+
+From the repo git root, after `sf ui` is up, pick pipeline `route-if-tour` and task `route-if-tour`.
+
+Or:
+
+```bash
+npx tsx src/cli.ts validate --pipeline examples/route-if-tour/route-if-tour.pipeline.yaml
+npx tsx src/cli.ts run \
+  --pipeline examples/route-if-tour/route-if-tour.pipeline.yaml \
+  --task examples/route-if-tour/route-if-tour.task.yaml
+```
+
+Validate should succeed (`ok: true`) with warning `pipeline.route_all_gated` on `gated-only`, `quiet`, and `loop-check` (every **forward** `to:` has `if`; the loop on `loop-check` does not count as an ungated sibling). `--strict` does not promote that warning. You may also see `pipeline.model_applies` because `model` is set on the pipeline, not on each stage.
+
+The run should **succeed**. Skipped stages: `skipped-page`, `skipped-page-child`, `skipped-quiet`, `assemble-miss`, `assemble-mix-miss`, `skipped-coerced`. Every other stage should **succeed**. `loop-check` should `send_back` once (replay `loop-draft`) then `continue` so `loop-done` runs.
+
+Joins still wait even though their parents sit on the spine in sequence: `assemble-ok` does not start until both `write` and `draw` are terminal.
+
+## Walk (follow-along order)
+
+Ungated `to:` is the next spine stage. Gated `if`s are local.
+
+| Level | Spine stage | Always continues | Local branches |
+|-------|-------------|------------------|----------------|
+| 1 | `kickoff` | `classify` | — |
+| 2 | `classify` | `score` | `ran-eq-string`, `ran-eq-int`, `ran-eq-num`, `ran-eq-bool`, `ran-ne`, `ran-in`, `ran-not-in`, `ran-gt-num` (`if`) |
+| 3 | `score` | `account` | `ran-gt`, `ran-gte`, `ran-lt`, `ran-lte` (`if`) |
+| 4 | `account` | `verdict` | `ran-nested` (`if`) |
+| 5 | `verdict` | `compose` | `ran-ref` (`if`) |
+| 6 | `compose` | `triage` | `ran-all`, `ran-any`, `ran-not`, `ran-nested-compose`, `ran-any-of-alls` (`if`) |
+| 7 | `triage` | `ran-notify` | `skipped-page` (`if` miss: `severity eq high`, emit `low`) |
+| 8 | `skipped-page` | — | `skipped-page-child` (skip-cascade) |
+| 9 | `ran-notify` | `gated-only` | — |
+| 10 | `gated-only` | — (all-gated fire) | `ran-all-gated` only (`if go eq true`; emit `go true`) |
+| 11 | `ran-all-gated` | `quiet` **and** `write` (two ungated) | required 2-way fan-out so `quiet` can stay all-gated |
+| 12 | `quiet` | — (dead-end all-gated miss) | `skipped-quiet` only (`if go eq true`; emit `go false`) |
+| 13 | `write` | `draw` | `assemble-ok` (`if ready eq true`; emit `true`) |
+| 14 | `draw` | `write-miss` | `assemble-ok` (`if complete eq true`; emit `true`) |
+| 15 | `write-miss` | `draw-miss` | `assemble-miss` (`if ready eq true`; emit `true`) |
+| 16 | `draw-miss` | `mix-open` | `assemble-miss` (`if complete eq true`; emit `false` so MISS) |
+| 17 | `mix-open` | `mix-gated` | `assemble-mix-ok` (no `if`) |
+| 18 | `mix-gated` | `mix-open-miss` | `assemble-mix-ok` (`if ready eq true`; emit `true`) |
+| 19 | `mix-open-miss` | `mix-gated-miss` | `assemble-mix-miss` (no `if`) |
+| 20 | `mix-gated-miss` | `strict-num` | `assemble-mix-miss` (`if ready eq true`; emit `false` so MISS) |
+| 21 | `strict-num` | `loop-draft` | `ran-int-one` (`if n eq 1`); `skipped-coerced` (`if n eq "1"` string). Emit `{"n":1}` integer |
+| 22 | `loop-draft` | `loop-check` | — |
+| 23 | `loop-check` | — | `loop-done` (`if pass eq true`); `{ type: loop }` to `loop-draft` (`max_replays: 1`, `on_max_replays: require_continue`, `replay_session: resume`). First attempt `send_back`, second `continue`. Payload `{"pass":true}`. `loop-done` has `replay_safe: false` |
+
+## Lanes
+
+Each scenario is a stop on the spine (plus its local `if` leaves), not a parallel lane from `kickoff`.
+
+| Stop | Source payload | What you should see |
+|------|----------------|---------------------|
+| Classify | `kind=ok`, `count=3`, `ratio=1.5`, `flag=true`, `tag=gold` | Eight gated handlers run; spine continues to `score` |
+| Score | `score=10` | `gt` / `gte` / `lt` / `lte` all fire; spine continues to `account` |
+| Account | `customer.tier=gold` | Nested path fires; sequential `io` on `ran-nested` |
+| Verdict | `ok=true` via `$ref` `#/schemas/flag` | `$ref` path check fires |
+| Compose | `severity=high`, `channel=web`, `customer.tier=gold` | `all`, `any`, `not`, nested `not(all)`, `any` of `all`s all fire |
+| Triage | `severity=low` | `skipped-page` skips; skip-cascade skips `skipped-page-child`; `ran-notify` still runs |
+| All-gated fire | `go=true` | Validate warns; `ran-all-gated` still runs |
+| Quiet miss | `go=false` | `skipped-quiet` skips; the run still succeeds |
+| Join fire | write `ready=true`, draw `complete=true` | `assemble-ok` runs with both envelopes after both parents are terminal |
+| Join miss | write-miss `ready=true`, draw-miss `complete=false` | `assemble-miss` skips (not pending, not partial) |
+| Mixed join fire | `mix-open` ungated, `mix-gated` `ready=true` | `assemble-mix-ok` runs |
+| Mixed join miss | `mix-open-miss` ungated, `mix-gated-miss` `ready=false` | `assemble-mix-miss` skips |
+| Type-strict | integer `n=1` | `ran-int-one` runs (`eq 1`); `skipped-coerced` skips (`eq "1"`) |
+| Loop | `pass=true`; first attempt `send_back`, second `continue` | `loop-draft` replays once; `loop-done` runs after continue; `if` on the forward, not on the loop |
+
+## Scenario table
+
+| Scenario | How this pipeline covers it | Evidence |
+|----------|------------------------------|----------|
+| `if` on a forward Route Entry | Every gated `to:` below | Child runs or (for skip rows) is skipped |
+| Evaluated only against the source payload | Prompts emit payload only; no status/timestamp fields in `if` | Gates match those JSON fields |
+| No `if` → edge always fires | Spine `to:` with no `if` (`kickoff` → `classify`, `classify` → `score`, …, `ran-notify` → `gated-only`, `ran-all-gated` → `quiet` and `write`) | Those stages succeed |
+| Mix always-run + gated siblings | `triage` → `skipped-page` (`if`) + `ran-notify` (no `if`) | `ran-notify` succeeds while `skipped-page` skips |
+| Two (or more) matching `if`s both fire | `classify` and `score` each have several true `if`s | All `ran-eq-*` / `ran-gt` / `ran-gte` / `ran-lt` / `ran-lte` succeed |
+| `eq` string | `kind eq ok` | `ran-eq-string` succeeded |
+| `eq` integer | `count eq 3` | `ran-eq-int` succeeded |
+| `eq` number | `ratio eq 1.5` | `ran-eq-num` succeeded |
+| `eq` boolean | `flag eq true` | `ran-eq-bool` succeeded |
+| `ne` | `kind ne fail` | `ran-ne` succeeded |
+| `gt` integer | `score gt 5` (10 > 5) | `ran-gt` succeeded |
+| `gt` number | `ratio gt 1.0` | `ran-gt-num` succeeded |
+| `gte` (equal bound) | `score gte 10` | `ran-gte` succeeded |
+| `lt` | `score lt 20` | `ran-lt` succeeded |
+| `lte` (equal bound) | `score lte 10` | `ran-lte` succeeded |
+| `in` | `tag in [gold, silver]` | `ran-in` succeeded |
+| `not_in` | `tag not_in [bronze]` | `ran-not-in` succeeded |
+| Nested object path | `customer.tier eq gold` | `ran-nested` succeeded |
+| `$ref` / `schemas:` after expansion | `verdict` output `$ref: "#/schemas/flag"`, `ok eq true` | `ran-ref` succeeded |
+| Sequential `io` still applies on a fired gated edge | `ran-nested` / `ran-ref` / `ran-all` require a subset of the parent output | Those stages start with that input |
+| `all` (AND) true | both leaves true | `ran-all` succeeded |
+| `any` (OR) true | `channel eq web` true; the `severity eq low` arm is **not** a covered `eq` | `ran-any` succeeded |
+| `not` true | `not (severity eq low)` | `ran-not` succeeded |
+| Nested `not` around `all` | `not (severity low AND channel phone)` | `ran-nested-compose` succeeded |
+| Nested `any` of `all`s | first `all` true (high+web); second `all` is not a covered `all` | `ran-any-of-alls` succeeded |
+| Independent evaluation (not first-match) | compose's five `if`s all true | five compose handlers succeed |
+| Single-parent miss → skip, run still succeeds | `triage` `severity eq high` is **false** on purpose | `skipped-page` skipped; run succeeded |
+| Skip-cascade | `skipped-page` routes to `skipped-page-child` with no `if` | `skipped-page-child` skipped too |
+| Always-run sibling still runs after a miss | `ran-notify` | succeeded |
+| Nothing matches and nothing else pending | `quiet` only forward `if` misses | `skipped-quiet` skipped; run succeeded |
+| `pipeline.route_all_gated` warning | `gated-only`, `quiet`, and `loop-check` have only gated **forwards** | validate warning, `ok: true` |
+| All-gated `if` that **does** match | `gated-only` `go eq true` | `ran-all-gated` succeeded |
+| Loop does not count as an ungated sibling | `loop-check` has gated `to: loop-done` plus `{ type: loop }` | `pipeline.route_all_gated` on `loop-check` |
+| Join waits for every parent | `write` and `draw` both route to `assemble-ok` (parents run in sequence on the spine) | `assemble-ok` does not start until both succeeded |
+| Join runs only when every inbound `if` fired | both `ready` and `complete` true | `assemble-ok` succeeded |
+| Each parent's `if` reads that parent only | `write.ready` vs `draw.complete` | `assemble-ok` sees both envelopes |
+| Join skip when any inbound `if` missed | `draw-miss` emits `complete: false` | `assemble-miss` skipped |
+| Missed join `if` does not skip while the other parent runs | `write-miss` fires; `draw-miss` misses | child waits, then skips |
+| Mixed join (ungated + gated fire) | `mix-open` has no `if`; `mix-gated` `ready eq true` | `assemble-mix-ok` succeeded |
+| Mixed join (ungated + gated miss) | `mix-open-miss` ungated; `mix-gated-miss` `ready eq true` misses | `assemble-mix-miss` skipped |
+| DAG still lists skipped `to:` | skipped stages still appear on the map | visible as skipped, not missing |
+| Type-strict comparison | `strict-num` emits integer `1` | `ran-int-one` succeeded; `skipped-coerced` skipped (`eq "1"` did not coerce) |
+| Loop still works next to `if` | `loop-check` has `{ type: loop }` to `loop-draft` and a gated forward `to: loop-done` | DAG shows the loop; `loop-done` succeeded after continue |
+| `send_back` then `continue` | first `loop-check` attempt sends back; second continues | `loop-draft` runs twice; then `loop-done` |
+| `if` stays off the loop entry | `if` is only on the forward to `loop-done` | validate still `ok` |
+
+## Expected stage status
+
+| Stage | Status | Why |
+|-------|--------|-----|
+| `kickoff` | succeeded | entry |
+| `classify` | succeeded | ungated from kickoff |
+| `ran-eq-string` | succeeded | `if` met |
+| `ran-eq-int` | succeeded | `if` met |
+| `ran-eq-num` | succeeded | `if` met |
+| `ran-eq-bool` | succeeded | `if` met |
+| `ran-ne` | succeeded | `if` met |
+| `ran-in` | succeeded | `if` met |
+| `ran-not-in` | succeeded | `if` met |
+| `ran-gt-num` | succeeded | `if` met |
+| `score` | succeeded | ungated from classify |
+| `ran-gt` | succeeded | `if` met |
+| `ran-gte` | succeeded | `if` met |
+| `ran-lt` | succeeded | `if` met |
+| `ran-lte` | succeeded | `if` met |
+| `account` | succeeded | ungated from score |
+| `ran-nested` | succeeded | `if` met |
+| `verdict` | succeeded | ungated from account |
+| `ran-ref` | succeeded | `if` met |
+| `compose` | succeeded | ungated from verdict |
+| `ran-all` | succeeded | `if` met |
+| `ran-any` | succeeded | `if` met |
+| `ran-not` | succeeded | `if` met |
+| `ran-nested-compose` | succeeded | `if` met |
+| `ran-any-of-alls` | succeeded | `if` met |
+| `triage` | succeeded | ungated from compose |
+| `skipped-page` | **skipped** | `severity` is `low`, not `high` |
+| `skipped-page-child` | **skipped** | skip-cascade from `skipped-page` |
+| `ran-notify` | succeeded | ungated from triage |
+| `gated-only` | succeeded | ungated from ran-notify |
+| `ran-all-gated` | succeeded | `if` met |
+| `quiet` | succeeded | ungated from ran-all-gated |
+| `skipped-quiet` | **skipped** | `go` is `false` |
+| `write` | succeeded | ungated from ran-all-gated |
+| `draw` | succeeded | ungated from write |
+| `assemble-ok` | succeeded | both inbound `if`s met (write then draw, then join) |
+| `write-miss` | succeeded | ungated from draw |
+| `draw-miss` | succeeded | ungated from write-miss |
+| `assemble-miss` | **skipped** | `draw-miss` inbound `if` missed |
+| `mix-open` | succeeded | ungated from draw-miss |
+| `mix-gated` | succeeded | ungated from mix-open |
+| `assemble-mix-ok` | succeeded | ungated inbound fired and gated inbound matched |
+| `mix-open-miss` | succeeded | ungated from mix-gated |
+| `mix-gated-miss` | succeeded | ungated from mix-open-miss |
+| `assemble-mix-miss` | **skipped** | gated inbound missed |
+| `strict-num` | succeeded | ungated from mix-gated-miss |
+| `ran-int-one` | succeeded | integer `1 eq 1` |
+| `skipped-coerced` | **skipped** | integer `1` is not string `"1"` |
+| `loop-draft` | succeeded | ungated from strict-num; replayed once after `send_back` |
+| `loop-check` | succeeded | `send_back` then `continue`; forward `if` met on continue |
+| `loop-done` | succeeded | gated forward from `loop-check` after continue |
+
+## Not in this pipeline
+
+These are real cases, but putting them here would either fail validate or fail the run, so they are **not** claimed as covered by this example.
+
+| Scenario | Why it is absent | Where to see it |
+|---------|------------------|-----------------|
+| `if` field not in schema | `pipeline.route_if_invalid` | `examples/route-wiring-smoke-test/rejected/22-reject-if-unknown-field.pipeline.yaml` |
+| `if` field optional / not `required` | same | `rejected/23-reject-if-optional-field.pipeline.yaml` |
+| Empty `all` / `any` / `in` | same | `rejected/24-reject-if-empty-all.pipeline.yaml` |
+| `gt` on a string | same | `rejected/25-reject-if-gt-on-string.pipeline.yaml` |
+| Nested optional path | same | `rejected/26-reject-if-optional-nested.pipeline.yaml` |
+| `if` on `{ type: loop }` | same | `rejected/27-reject-if-on-loop.pipeline.yaml` |
+| `if` + `on: [failed]` | same | `rejected/29-reject-if-on-failed.pipeline.yaml` |
+| Failed parent blocks a Join | a failed parent fails/blocks the run | runtime tests / yaml-catalog Generic fan-in |
+| Payload-gated loops (`if` on `{ type: loop }`) | out of scope; would fail validate | `rejected/27-reject-if-on-loop.pipeline.yaml` |
+| `exists` / array paths / fallback / first-match-wins | out of scope | spec |