stageflow 0.25.0 → 0.30.0

package/examples/oss-quick-fix/ship-fix.yaml

@@ -0,0 +1,81 @@
+id: ship-fix
+system_prompt: |
+  Publish the verified fix as a pull request against your own fork —
+  never the upstream project. Opening a PR against upstream is a separate,
+  explicitly-authorized manual step outside this pipeline; this stage never
+  does that. Never call ask_operator or pause for review — within that
+  fork-only boundary, commit, push, and open the pull request yourself.
+
+  Read verification.md, fix-report.md, and investigation.md from prior
+  envelopes' artifacts (run-relative paths under the "Factory run workspace"
+  value given in this stage's user prompt). Do not proceed if
+  verification.md's all_passed is not true — emit failure instead and say
+  what's unresolved.
+
+  publish_repo is exactly the fork repository the task goal/context names as
+  the PR target (e.g. your-username/project, not the original upstream
+  owner/project). If the task does not explicitly name a fork, emit failure
+  instead of guessing — never push or open a PR against a repository nobody
+  named, and never target the upstream repository under any circumstance.
+
+  1. Run git status to confirm the diff from implement-fix/verify-fix is
+     still present and is the only thing you're about to commit.
+  2. Stage exactly the changed files (never a blanket add), commit with a
+     concise message describing the fix and why (match the target repo's
+     commit conventions from investigation.md if it recorded any), and push
+     to a new branch on publish_repo (your fork).
+  3. Open a pull request with gh pr create --repo <publish_repo> against that
+     fork's default branch: title stating the fix, body with the issue
+     reference, root cause, what changed, and the verification commands that
+     passed. Note in the body that this targets the fork and that opening it
+     against upstream is a separate manual step.
+  4. Confirm the PR exists with gh pr view. Call write_stage_artifact with
+     path ship-report.md containing the branch, commit sha, PR url, and the
+     exact git/gh commands you ran.
+  5. Call emit_stage_envelope exactly once. opened is true only if gh pr view
+     confirmed the PR exists.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - commands_run
+        - all_passed
+      properties:
+        commands_run:
+          type: array
+          items:
+            type: string
+        all_passed:
+          type: boolean
+        notes:
+          type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - publish_repo
+        - branch
+        - opened
+        - pr_url
+      properties:
+        publish_repo:
+          type: string
+        branch:
+          type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+      additionalProperties: false
+verify:
+  - id: ship-report
+    type: artifact
+    path: ship-report.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-quick-fix/understand-issue.yaml

@@ -0,0 +1,67 @@
+id: understand-issue
+system_prompt: |
+  Understand the reported issue well enough to fix it, then write
+  investigation.md as the durable record downstream stages read instead of
+  re-deriving this work. Do not edit source files in this stage. Never call
+  ask_operator — this pipeline runs unattended; make the best defensible call
+  yourself and keep going.
+
+  1. Read the task goal and context for the issue statement (what's broken,
+     why, why it matters). If the checkout has AGENTS.md, CONTRIBUTING.md, or
+     other repo-instruction files, read the ones that govern the suspected
+     code area and note anything that constrains how a fix should look
+     (commit conventions, test runner, things you must not touch).
+  2. Locate the actual code responsible, by reading it — not by guessing from
+     the issue text. Trace the failure to specific files and line ranges.
+  3. Reproduce the bug if at all practical: write and run a minimal script,
+     failing test, or repro command that demonstrates the broken behavior
+     right now, in this checkout. If true reproduction isn't practical
+     (e.g. needs hardware or a live external service you don't have), say so
+     explicitly and explain what you verified by reading the code instead —
+     do not claim a reproduction that didn't happen.
+  4. Call write_stage_artifact with path investigation.md containing: the
+     issue restated in full (not abbreviated — downstream stages rely on
+     this, not on the task text), root cause with file:line references,
+     repro method and its actual output, the fix approach you intend to take
+     and why, and any repo rules from step 1 that constrain the fix.
+  5. Call emit_stage_envelope exactly once with a payload matching the
+     schema.
+
+  No placeholder values (n/a, tbd, unknown, "see issue") anywhere in the
+  payload or artifact — if something is genuinely unknown, say what you'd
+  need to find out and why you couldn't, and still record what you did
+  verify.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - root_cause
+        - target_files
+        - repro_confirmed
+        - fix_approach
+      properties:
+        root_cause:
+          type: string
+        target_files:
+          type: array
+          items:
+            type: string
+        repro_confirmed:
+          type: boolean
+        fix_approach:
+          type: string
+      additionalProperties: false
+verify:
+  - id: investigation
+    type: artifact
+    path: investigation.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-quick-fix/verify-fix.yaml

@@ -0,0 +1,73 @@
+id: verify-fix
+system_prompt: |
+  Independently verify the fix is correct, complete, and clean before it
+  ships — you are the only check this pipeline has; there is no human review
+  step. Never call ask_operator. If you find a problem, fix it yourself and
+  re-verify rather than reporting it downstream.
+
+  Read fix-report.md and investigation.md from prior envelopes' artifacts
+  (run-relative paths under the "Factory run workspace" value given in this
+  stage's user prompt).
+
+  1. Read the actual diff (git diff) rather than trusting fix-report.md's
+     description of it. Confirm the change matches the claimed root cause
+     and is scoped to the issue — flag and fix anything unrelated, debug
+     leftovers, commented-out code, or stray files.
+  2. Run the repo's real check/lint/typecheck command and its real test
+     command (found in AGENTS.md, package scripts, or equivalent — use
+     whatever investigation.md recorded, or find it yourself if that's
+     incomplete). Run the regression test by its exact id, and the broader
+     suite. Record every command and its exit status.
+  3. If anything fails or looks wrong, fix it in this stage and re-run until
+     it's clean. Do not report success on a red run, and do not hand a known
+     problem downstream with a note about it instead of fixing it.
+  4. Call write_stage_artifact with path verification.md containing: every
+     command run and its result, confirmation the regression test passes,
+     confirmation of no unrelated changes, and any issues you found and
+     fixed in this stage.
+  5. Call emit_stage_envelope exactly once with all_passed true only if
+     every command you ran actually exited zero.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - changed_files
+        - regression_test
+        - tests_passed
+      properties:
+        changed_files:
+          type: array
+          items:
+            type: string
+        regression_test:
+          type: string
+        tests_passed:
+          type: boolean
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - commands_run
+        - all_passed
+      properties:
+        commands_run:
+          type: array
+          items:
+            type: string
+        all_passed:
+          type: boolean
+        notes:
+          type: string
+      additionalProperties: false
+verify:
+  - id: verification
+    type: artifact
+    path: verification.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/plan-review/README.md

@@ -0,0 +1,37 @@
+# plan-review
+
+Two-stage pipeline with an **artifact-backed operator gate** (`ask_operator`). This is an **SDLC-style example** — plan review before implementation — but the same HITL pattern applies to any workflow you author.
+
+Fixture twin: `tests/fixtures/pipelines/plan-review-proving.pipeline.yaml`.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed
+- Provider auth connected
+- Operator console: `sf ui` (default `http://127.0.0.1:3847`)
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/plan-review/plan-review.pipeline.yaml --strict
+```
+
+Terminal 1:
+
+```bash
+sf ui
+```
+
+Terminal 2:
+
+```bash
+sf run \
+  --pipeline examples/plan-review/plan-review.pipeline.yaml \
+  --task examples/plan-review/plan-review.task.yaml
+```
+
+When the first stage blocks on HITL, open the run in the console, review the plan artifact, and accept or reject. Exit code `2` means waiting on operator input.
+
+See [docs/hitl.md](../../docs/hitl.md).

package/examples/plan-review/plan-review-followup.yaml

@@ -0,0 +1,13 @@
+id: plan-review-followup
+system_prompt: |
+  Acknowledge that the prior plan-review stage completed with operator acceptance
+  of the plan. Call emit_stage_envelope once with a short summary. Do not call
+  ask_operator. Do not perform further HITL.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/plan-review/plan-review.pipeline.yaml

@@ -0,0 +1,9 @@
+id: plan-review
+stages:
+  - id: plan-review
+    entry: true
+    route:
+      - to: plan-review-followup
+    uses: ./plan-review.yaml
+  - id: plan-review-followup
+    uses: ./plan-review-followup.yaml

package/examples/plan-review/plan-review.task.yaml

@@ -0,0 +1,9 @@
+id: plan-review
+goal: Prove plan-review HITL through artifact-backed accept/reject then follow-up
+context: |
+  Operator-console proving task for the plan-review pipeline. The first stage
+  must write a plan artifact, gate on ask_operator kind artifact_backed, and
+  emit only after accept. The follow-up stage only acknowledges acceptance.
+constraints: |
+  Do not skip ask_operator. Do not emit_stage_envelope before plan accept.
+  Follow-up must not call ask_operator.

package/examples/plan-review/plan-review.yaml

@@ -0,0 +1,25 @@
+id: plan-review
+gate_kinds:
+  - artifact_backed
+system_prompt: |
+  Your job is to produce a concise feature plan for the task and get operator
+  acceptance before completing this stage.
+
+  1. Write a concise feature plan via write_stage_artifact to a stage artifact
+     path (for example plan.md under stages/plan-review/attempts/1/artifacts/).
+  2. Call ask_operator with kind artifact_backed referencing that artifact path
+     so the operator can review the plan.
+  3. On reject or change text: revise the plan 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
+     operator accepts/confirms the plan. Never emit before plan accept.
+  5. Optionally, before the plan gate, you may ask one clarifying free_text or
+     multi_question via ask_operator if needed. Never emit before plan accept.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/playwright-mcp/README.md

@@ -0,0 +1,39 @@
+# playwright-mcp
+
+One-stage walkthrough: **open a page and screenshot it**, using Microsoft Playwright MCP (`npx @playwright/mcp@latest`) from git-root `.mcp.json`.
+
+Playwright's `--output-dir` is interpolated to `STAGEFLOW_STAGE_ARTIFACTS_DIR` (this attempt's artifacts folder). Auto-named snapshots use that directory. A named `browser_take_screenshot` `filename` does **not** — Playwright MCP resolves it against the MCP client workspace (the project checkout). The stage prompt therefore passes `${STAGEFLOW_STAGE_ARTIFACTS_DIR}/page.png` (stamped to an absolute artifacts path at attach) so the PNG lands in the run Files pane instead of the git root.
+
+| Stage | MCP | What it does |
+|-------|-----|----------------|
+| `screenshot` | `playwright` | `browser_navigate` → `browser_take_screenshot` (`page.png`) |
+
+Completion requires `page.png` on disk. Settings Check (no stage) falls back to `examples/playwright-mcp/.playwright-mcp/` (gitignored).
+
+## Prerequisites
+
+- Node.js ≥ 20 and this repo's CLI (`npm run build`), not an older global `sf`
+- Provider auth (`sf ui` → Settings → Providers)
+- First run may download Chromium via Playwright (needs network)
+
+Git-root `.mcp.json` already names `playwright`. The stage still passes `mcp: [playwright]` — listing it in the catalog is not attach.
+
+Optional: Settings → **Project MCP servers** → Check `playwright` before the run.
+
+## Run (repo root)
+
+```bash
+npm run build
+node dist/cli.js validate --pipeline examples/playwright-mcp/playwright-mcp.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/playwright-mcp/playwright-mcp.pipeline.yaml \
+  --task examples/playwright-mcp/playwright-mcp.task.yaml
+```
+
+Inspect:
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage screenshot --json
+```
+
+The Files row is `page.png`.

package/examples/playwright-mcp/playwright-mcp.pipeline.yaml

@@ -0,0 +1,5 @@
+id: playwright-mcp
+stages:
+  - id: screenshot
+    uses: ./screenshot.yaml
+    mcp: [playwright]

package/examples/playwright-mcp/playwright-mcp.task.yaml

@@ -0,0 +1,4 @@
+id: playwright-mcp
+goal: Open https://google.com and take a screenshot of that page as a PNG artifact.
+context: One-stage Playwright MCP walkthrough. Playwright must save page.png under this attempt's artifacts directory (absolute path in the stage prompt), not the repo root.
+constraints: Use only the playwright server named on the stage. Do not call ask_operator. The screenshot must be page.png in artifacts, not markdown and not the git root.

package/examples/playwright-mcp/screenshot.yaml

@@ -0,0 +1,40 @@
+id: screenshot
+system_prompt: |
+  Open the URL from the task in Playwright MCP, then take a screenshot.
+  Call browser_navigate, then browser_take_screenshot with type png and
+  filename exactly ${STAGEFLOW_STAGE_ARTIFACTS_DIR}/page.png — copy that
+  path verbatim. Playwright resolves a bare filename like page.png against
+  the project checkout (repo root), not --output-dir. Do not pass filename
+  page.png without the artifacts-directory prefix. Do not write screenshot.md.
+  Do not call write_stage_artifact for the image. Do not call ask_operator.
+
+  When finished, call emit_stage_envelope exactly once with status success,
+  a short summary, payload { "url": "<final page URL>", "screenshot": "page.png" },
+  and artifacts listing the run-relative PNG path this session already names
+  (stages/screenshot/attempts/<n>/artifacts/page.png). summary and payload are
+  handed downstream verbatim. State outcomes and artifact pointers only.
+
+  Your last tool call in this attempt must be emit_stage_envelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - url
+        - screenshot
+      properties:
+        url:
+          type: string
+        screenshot:
+          type: string
+verify:
+  - id: png
+    type: artifact
+    path: page.png
+    nonempty: true
+    when:
+      - after

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.