stageflow 0.25.0 → 0.30.0

package/examples/route-wiring-smoke-test/stages/branch-b.yaml

@@ -0,0 +1,12 @@
+id: branch-b
+system_prompt: |
+  Branch B -- an external stage file loaded via `uses:`. One sentence is enough.
+  Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/route-wiring-smoke-test/stages/decide.yaml

@@ -0,0 +1,12 @@
+id: decide
+system_prompt: |
+  Start both follow-up branches. branch-a and branch-b both run next. One sentence is enough.
+  Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/route-wiring-smoke-test/stages/finish.yaml

@@ -0,0 +1,12 @@
+id: finish
+system_prompt: |
+  Finish -- an external stage file loaded via `uses:`. One sentence is enough.
+  Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/ship-feature/README.md

@@ -0,0 +1,190 @@
+# Ship-feature pipeline
+
+A small, general-purpose "ship any small feature through a governed
+pipeline" pattern: plan → implement → parallel review → address feedback →
+ship. It is deliberately a trimmed sibling of
+[`examples/oss-issue-contribution/`](../oss-issue-contribution/) — no intake,
+no explainers, no read-only reproduction stage, no investigation fan-out —
+built for the common case where a feature is already well understood and the
+value is in a governed, evidence-backed path from plan to pull request, not
+in a multi-stage investigation.
+
+The pipeline is repository-neutral. Point the task's `checkout` at a
+dedicated branch of whatever repository you're shipping into. It reads that
+repository's own scripts and conventions before acting; nothing in the stage
+files names a specific repository, feature, or keyword.
+[`ship-feature.task.yaml`](ship-feature.task.yaml) is one concrete instance
+of the pattern — extending Stageflow's envelope JSON Schema subset — not a
+template you must follow.
+
+## Flow
+
+1. Plan and get explicit operator approval for the exact scope, edit sites,
+   and validation commands (`feat-plan`, one merged propose-and-approve
+   stage — there is no separate earlier planning stage).
+2. Implement the approved plan and drive its full validation command list to
+   green in one session, writing any tests the plan calls for as part of
+   implementing rather than in a separate stage (`feat-implement`, the only
+   stage with edit access to the checkout).
+3. Fan out two to four focused, non-overlapping reviews in parallel — no
+   human gate here, this is the one automated fan-out in the middle
+4. Address every blocking review finding in one fixup stage — sweeping for
+   every instance of the same category of problem, not only the ones
+   reviewers happened to cite. This catalog stays a DAG; it does not
+   declare `{ type: loop }` back to `feat-implement` or a second review pass
+   (`feat-address-feedback`).
+5. Assemble a ship package, ask for final approval, and — once the operator
+   accepts — push the current branch and open the pull request in that same
+   stage (`feat-ship`).
+
+No stage before the last one commits, pushes, or opens a pull request, and
+no stage ever creates or renames a branch — the checkout is expected to
+already be on the correct feature branch when the run starts. `feat-ship`
+writes `ship-package.md`, calls `ask_operator`, and only runs `git`/`gh`
+against the checkout's current branch after an explicit accept through its
+`artifact_backed` gate. There is no separate publish flag or dry-run mode:
+the operator's accept is the only gate between "package written" and "PR
+opened."
+
+## Runtime contracts
+
+Every stage declares `io.output.schema`, so a success emit is rejected unless
+the payload matches it, and each stage file lists `verify` items so success
+is independently checked rather than only claimed. Artifact paths below are
+after-phase `type: artifact` checks on the stage body:
+
+| Stage | `gate_kinds` | Required artifacts | Other `verify` |
+|-------|--------------|--------------------|----------------|
+| `feat-plan` | `[artifact_backed]` | `implementation-plan.md` | `gate` `artifact_backed` |
+| `feat-implement` | `[]` | `implementation-report.md` | `checkout_changes` on `changed_files` |
+| `feat-review` | `[]` | `review.md` | — |
+| `feat-address-feedback` | `[]` | `review-feedback-report.md` | — |
+| `feat-ship` | `[artifact_backed]` | `ship-package.md`, `pull-request.md` | `gate` `artifact_backed` |
+
+`feat-implement`'s `checkout_changes` check (with `path_fields: [changed_files]`)
+compares the checkout before and after the attempt and rejects a success emit
+if `changed_files` is non-empty but the checkout never actually changed, or if
+any listed path is not a real checkout-relative change. `feat-plan` and
+`feat-ship` each also carry a `gate` verify item of kind `artifact_backed`, so
+their `ask_operator` approval is independently verified, not just
+self-reported. See [Verified Stage Execution](../../docs/verified-stage-execution.md)
+and [YAML catalog — Verify](../../docs/yaml-catalog.md#verify).
+
+it must partition the diff into two to four independent review assignments
+and fan them out; it cannot skip review or hand it to a single clone.
+`feat-review` `io.input` is an empty object so it stays a subset of
+`feat-implement` `io.output`. See
+
+Every stage but `feat-ship` uses `on_verify_fail: { mode: repair, max_attempts: 3,
+retry_safety: idempotent, include_failed_checks: true }` on the pipeline
+entry, so an after-phase verify failure starts a fresh attempt with the
+failed-check evidence carried forward, up to three attempts. `feat-ship` uses
+`on_verify_fail: { mode: manual, retry_safety: side_effecting }` instead,
+because it publishes: a failed after-phase check there leaves the stage failed
+until an operator explicitly retries or stops via `on_verify_fail` manual
+handling. See
+[Verified Stage Execution — Recovery policy](../../docs/verified-stage-execution.md#recovery-policy).
+
+### Review feedback has no loop in this catalog
+
+Loops exist via `{ type: loop }` on `route` (see
+[`examples/feedback-loop/`](../feedback-loop/)). This pipeline does not use
+one. If `feat-review` finds a blocking problem, the run does not resume
+`feat-implement`. `feat-address-feedback` is the accommodation: a single
+fixup stage after review and before shipping that addresses every blocking
+finding — sweeping for other instances of the same category of problem, not
+only the ones a reviewer happened to cite — then hands off to `feat-ship`,
+which independently re-checks the fix before accepting it. It cannot get a
+fresh review of its own fix, though: if its patch introduces something new,
+`feat-ship`'s fail-closed check is the backstop, and the operator has to
+intervene by hand — see [`sf runs retry`](../../docs/cli-reference.md), which
+can retry a succeeded stage in place and reset everything downstream.
+
+## Prepare a worktree
+
+This pipeline expects to run against a checkout that is **already** on a
+dedicated feature branch — no stage creates, renames, or switches a branch.
+A `git worktree` keeps that branch isolated from whatever else you have
+checked out in your primary clone of the target repository:
+
+```bash
+cd /path/to/your/repo
+git fetch origin
+git worktree add ../your-repo-feature-branch -b your-feature-branch origin/main
+cd ../your-repo-feature-branch
+npm install   # or the target repository's equivalent bootstrap command
+git status --short
+```
+
+Point the task's `checkout` field at that worktree's absolute path. When the
+run finishes (or if it fails partway through), remove the worktree with
+`git worktree remove ../your-repo-feature-branch` from the main clone once
+you no longer need it.
+
+## Create a task
+
+Task context is the pipeline's portable feature brief. Include enough detail
+that `feat-plan` can ground a real plan in the actual repository rather than
+re-deriving requirements from a one-line goal:
+
+```yaml
+id: my-feature
+goal: >
+  Describe the concrete, scoped change to ship, ending in an
+  operator-approved pull request against <owner>/<repo>.
+context: |
+  Name the exact files and symbols involved, the existing conventions to
+  follow (test style, doc sections to update), and the ship target: which
+  repository, which base branch, and which branch the checkout is already on.
+constraints: |
+  Do not create, rename, or switch branches — the checkout is already on the
+  correct branch.
+  Do not commit, push, or open a pull request in any stage except feat-ship.
+checkout: /absolute/path/to/your-repo-feature-branch
+```
+
+[`ship-feature.task.yaml`](ship-feature.task.yaml) is a complete example: it
+targets this same Stageflow repository, adding `pattern`, `minLength`,
+`maxLength`, and `nullable` support to `src/envelope/payloadSchema.ts`
+against a worktree on branch `demo/richer-payload-schema-constraints`.
+
+## Run
+
+From any directory with Stageflow installed:
+
+```bash
+sf validate \
+  --pipeline /path/to/stageflow/examples/ship-feature/ship-feature.pipeline.yaml \
+  --strict
+
+sf run \
+  --pipeline /path/to/stageflow/examples/ship-feature/ship-feature.pipeline.yaml \
+  --task /path/to/my-feature.task.yaml
+```
+
+`feat-ship` pushes the checkout's current branch and opens the pull request
+as soon as the operator accepts its `artifact_backed` gate — there is no
+dry-run mode and no extra flag. `gh` must be on `PATH` and authenticated
+(`GH_TOKEN` or `GITHUB_TOKEN`) before you accept, or the publish step will
+fail after approval.
+
+Run `sf ui` in another terminal to inspect envelopes, artifacts, clone
+fan-out, and answer the two artifact-backed gates.
+
+## Safety and interpretation
+
+- Plan approval authorizes only local edits in the task checkout.
+- Review clones always complete successfully and carry `pass` or
+  `changes_required` in their payload, so `feat-address-feedback` sees every
+  review even when some pass and some don't.
+- Any blocking review that survives `feat-address-feedback` fails the final
+  stage closed — `feat-ship` cross-checks `addressed_all_blocking` against
+  the original `blocking_findings` rather than trusting the fixup stage's
+  own claim.
+- The operator's accept through `feat-ship`'s `artifact_backed` gate is the
+  only authorization to publish, and it happens moments before the stage
+  runs `git push` / `gh pr create` in the same session — there is no
+  separate flag and no second chance to reconsider after accepting.
+- No stage creates, renames, or switches a branch. If the checkout is not
+  already on the intended feature branch when the run starts, fix that
+  before running — the pipeline will not do it for you.

package/examples/ship-feature/feat-address-feedback.yaml

@@ -0,0 +1,119 @@
+id: feat-address-feedback
+system_prompt: |
+  Address every blocking finding from feat-review before the ship package is
+  assembled. There is no automatic path back to feat-implement in this
+  pipeline, and this is the only stage positioned to edit the checkout after
+  review — treat that as the reason this stage exists, not as license to
+  rewrite the implementation. This stage is the last-mile fixup for what
+  reviewers found, not a second implementation pass.
+
+  Reading upstream evidence. The user prompt contains a line
+  "Factory run workspace: <absolute path>". Prior artifacts arrive in the
+  prior envelope's artifacts[] as run-relative paths; read each one at
+  <Factory run workspace>/<artifact path>. Every feat-review envelope's
+  payload (review_id, verdict, blocking_findings) and its review.md are
+  authoritative; implementation-report.md gives the context needed to make a
+  correct, narrow fix. Prose summaries are secondary.
+
+  Definition of done — every line must hold before you emit success:
+  - Every feat-review envelope and its review.md have been read.
+  - If every verdict is pass: the checkout is untouched, fixed_files is
+    empty, and addressed_all_blocking is true.
+  - If any verdict is changes_required: every entry in every review's
+    blocking_findings has been addressed, not only the specific file/line
+    reviewers happened to cite — search for every other instance of the same
+    category of problem (for example, every other call site with the same
+    missing validation, or every other test still asserting the old
+    behavior) and fix those too. A reviewer's citation is a sample of the
+    problem, not its full extent.
+  - git diff in the checkout is non-empty whenever any verdict was
+    changes_required; the emit is rejected if you claim to have addressed a
+    blocking finding while the working tree is clean.
+  - Every fixed_files entry is a repo-relative path inside the checkout that
+    also appears in git diff --name-only; the emit is rejected for any entry
+    pointing into the factory run workspace.
+  - Every check a blocking finding cited as failing has been re-run here and
+    now passes; verification_commands records each with its result.
+  - review-feedback-report.md was written through write_stage_artifact and
+    appears in the emitted artifacts list; the emit is rejected without it.
+
+  1. Read every feat-review envelope and review.md via the recipe
+     above. If every verdict is pass, skip to step 5 with nothing to fix.
+  2. For each changes_required review, read every blocking_findings entry
+     and its remediation guidance. Do not re-litigate a pass verdict or
+     reopen non-blocking findings or suggestions — those are out of scope
+     here.
+  3. Fix each blocking finding at its cited location, then search the rest
+     of the checkout for other instances of the same category of problem and
+     fix those too (see Definition of done). Do not perform unrelated
+     formatting, refactors, or scope expansion beyond what the findings
+     require. Do not weaken, delete, or skip a test to make it pass.
+  4. Re-run every command a blocking finding cited as failing, plus the
+     specific test(s) it named, and confirm each now passes. If a fix cannot
+     be completed or a re-run still fails, emit failure and record exactly
+     what remains broken and why — do not present partial remediation as
+     success.
+  5. Call write_stage_artifact with path review-feedback-report.md listing
+     every blocking finding, whether it was addressed (with the fix location
+     and the passing re-run), or that there was nothing to address because
+     every verdict was pass.
+  6. Emit exactly once, including review-feedback-report.md and all
+     inherited evidence artifacts, with a payload matching the schema.
+
+  Contract violations — emit failure rather than presenting these as
+  success:
+  - addressed_all_blocking: true while any blocking_findings entry remains
+    unaddressed or unverified.
+  - Fixing only the literal file/line a reviewer cited when the same
+    category of problem exists elsewhere in the diff.
+  - Emitting success while git diff is empty and any verdict was
+    changes_required.
+  - A fixed_files entry under stages/.../artifacts/ or anywhere else in the
+    factory run workspace.
+  - Editing anything outside the scope of a blocking finding.
+  - verification_commands listing commands you did not execute.
+
+  Never commit, push, or open a pull request.
+
+  Write summary as outcomes and resulting state for feat-ship: which
+  blocking findings existed, what changed to address them, and confirmation
+  every cited check now passes (or, on failure, what remains open).
+  Downstream stages receive this summary verbatim and can mistake it for
+  their own instructions, so never restate this stage's prohibitions or
+  scope limits in it.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - addressed_all_blocking
+        - fixed_files
+        - verification_commands
+        - remaining_risks
+      properties:
+        addressed_all_blocking:
+          type: boolean
+        fixed_files:
+          type: array
+          items:
+            type: string
+        verification_commands:
+          type: array
+          items:
+            type: string
+        remaining_risks:
+          type: array
+          items:
+            type: string
+verify:
+  - id: review-feedback-report
+    type: artifact
+    path: review-feedback-report.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/ship-feature/feat-implement.yaml

@@ -0,0 +1,180 @@
+id: feat-implement
+system_prompt: |
+  Edit the checkout so the accepted plan is fully implemented and every one
+  of its validation_commands passes — not just the commands you find
+  convenient. Modified files under the project checkout are the only
+  acceptable output of this stage; no map, excerpt, document, or report can
+  substitute for them. If the plan calls for test coverage, write it here —
+  there is no separate stage that writes tests before this one.
+
+  You own the whole loop: implement, run the plan's full validation_commands,
+  and if anything fails, diagnose and fix it and run them again. Repeat until
+  every command passes or you have a concrete, evidence-backed reason further
+  iteration in this attempt will not help. This stage is the only one with
+  edit access to the checkout — nothing downstream can fix what you leave
+  broken, so do not hand off a partially-green result as success.
+
+  Reading upstream work: the prior envelope's artifacts[] holds run-relative
+  paths. Read each one at <Factory run workspace>/<artifact path>, using the
+  absolute "Factory run workspace" value given in this stage's user prompt.
+  implementation-plan.md is the authoritative approved scope — its
+  validation_commands list is the actual definition of done, not a
+  suggestion — and it outranks any prose in the prior envelope's summary.
+  That summary describes the PREVIOUS stage: any prohibition it carries, for
+  example "no source edits", applied to that stage and does not apply here.
+
+  Definition of done — every line must hold before you emit success:
+  - git diff in the checkout is non-empty and contains your edits; the emit
+    is rejected while the working tree is clean.
+  - Every changed_files entry is a repo-relative path inside the checkout
+    that also appears in git diff --name-only; the emit is rejected for any
+    entry pointing into the factory run workspace.
+  - Every command in implementation-plan.md's validation_commands has been
+    run here, in order, with its exit code recorded, and every one exited
+    zero. all_passed is true only when that is actually the case.
+  - implementation-report.md was written through write_stage_artifact and
+    appears in the emitted artifacts list; the emit is rejected without it.
+  - commands_run lists only commands you actually executed, each with its
+    outcome — the full validation_commands list plus anything else you ran
+    while diagnosing failures.
+
+  1. Resolve implementation-plan.md from the prior envelope's artifacts[]
+     against the Factory run workspace absolute path and read it. If it
+     cannot be read, emit failure — do not substitute a plan you re-derived
+     yourself.
+  2. Edit the source files — and add any test files
+     implementation-plan.md's validation_commands require that do not exist
+     yet — to satisfy the accepted plan. Do not perform unrelated
+     formatting, refactors, dependency upgrades, generated-file changes, or
+     scope expansion beyond what the plan describes.
+  3. Run every command in implementation-plan.md's validation_commands, in
+     order, recording exit code and a stdout tail for each.
+  4. If any command fails, treat that as unfinished work, not a report
+     footnote: diagnose the specific cause, make the corresponding source or
+     test edit, and return to step 3. Do not move on while a
+     validation_commands entry is red.
+  5. Once every command passes, run git status --porcelain and git diff
+     --stat in the checkout and inspect the complete diff. If either output
+     is empty, this stage has not done its job: return to step 2 or emit
+     failure.
+  6. Call write_stage_artifact with path implementation-report.md containing
+     the verbatim non-empty git diff --stat and git status --porcelain
+     output, the files changed, before/after behavior, every validation
+     command with its result, how many iterations it took, assumptions, and
+     any deviation from the plan.
+  7. Partition the resulting diff into two to four independent,
+     non-overlapping review assignments (for example: correctness and edge
+     cases, test quality and coverage, and — only when the diff materially
+     involves compatibility, security, or public API surface — a scope and
+     compatibility assignment). Each assignment needs a review_id,
+     objective, the concrete repo-relative paths it owns (taken from the
+     actual diff, not guessed), specific questions a reviewer can answer by
+     reading those paths, and constraints. Scopes must not overlap and must
+     collectively cover every changed file.
+  8. Emit exactly once, including implementation-report.md and all inherited
+     evidence artifacts, with a payload matching the schema, and the
+     definition-of-done line holds; otherwise emit failure while preserving
+     the working-tree evidence for the operator, and record in the summary
+     exactly which validation_commands entries remain red and why. On
+
+  Contract violations — emit failure rather than presenting these as
+  success:
+  - Emitting success while git diff in the checkout is empty.
+  - Emitting success while any validation_commands entry has not been run,
+    was skipped, or exited non-zero. all_passed: true when that is not the
+    case is a contract violation, not a reporting choice.
+  - A changed_files entry under stages/.../artifacts/ or anywhere else in
+    the factory run workspace. Such a path is never a valid entry.
+  - commands_run listing commands you did not execute.
+  - Treating a markdown map, excerpt file, or report as the deliverable.
+    Exploration-only completion is a failure of this stage.
+    four clones, overlapping scopes, or an assignment with empty paths or
+    questions.
+
+  only — skipping review is not permitted.
+
+  Write summary as outcomes and resulting state for downstream stages: what
+  now differs in the checkout, which tests cover it, confirmation that every
+  validation command passed, and which review scopes were assigned and why.
+  Downstream stages receive this summary verbatim and can mistake it for
+  their own instructions, so never restate this stage's prohibitions or
+  scope limits in it.
+model: omniroute/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - approved
+        - scope_summary
+        - planned_files
+        - validation_commands
+        - risks
+      properties:
+        approved:
+          type: boolean
+        scope_summary:
+          type: string
+        planned_files:
+          type: array
+          items:
+            type: string
+        validation_commands:
+          type: array
+          items:
+            type: string
+        risks:
+          type: array
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - changed_files
+        - implementation_summary
+        - tests_added
+        - commands_run
+        - all_passed
+        - review_count
+        - review_strategy
+      properties:
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implementation_summary:
+          type: string
+        tests_added:
+          type: array
+          items:
+            type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        all_passed:
+          type: boolean
+        review_count:
+          type: integer
+          minimum: 2
+          maximum: 4
+        review_strategy:
+          type: string
+verify:
+  - id: implementation-report
+    type: artifact
+    path: implementation-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - changed_files
+    when:
+      - after
+gate_kinds: []

package/examples/ship-feature/feat-plan.yaml

@@ -0,0 +1,120 @@
+id: feat-plan
+system_prompt: |
+  Write implementation-plan.md as a mechanical checklist the implement stage
+  can execute, and get explicit operator approval of it before any source
+  edit happens anywhere in this pipeline. This stage is the only planner —
+  there is no separate proposal stage before it and no separate approval
+  stage after it, so both concerns live here.
+
+  Reading the task. There is no prior stage in this pipeline; the task goal,
+  context, and constraints are the only input. Read the actual repository at
+  the checkout path in this stage's user prompt — the files the task names,
+  their neighbors, and any docs the task points at — rather than planning
+  from the task text alone. A plan that restates the goal without grounding
+  it in the real files is not done.
+
+  Definition of done — every line must hold before you emit success:
+  - implementation-plan.md was written through write_stage_artifact and
+    appears in the emitted artifacts list; the emit is rejected without it.
+  - The plan names the exact files to touch, the exact symbol or region at
+    each edit site, and the exact validation commands to run — copied
+    verbatim from this repository's own scripts (for example package.json),
+    never invented or guessed.
+  - If the task's goal implies new behavior needs test coverage, the plan
+    says so explicitly and names where that coverage belongs; it does not
+    silently omit tests.
+  - The operator explicitly accepted the plan through the artifact_backed
+    gate, and that accepted decision is recorded verbatim inside
+    implementation-plan.md.
+  - approved is true only after that explicit accept; planned_files and
+    validation_commands are non-empty and concrete.
+
+  1. Read the task goal, context, and constraints. Read every file the task
+     names and enough of their neighbors to ground a real plan — the current
+     shape of the code to change, the existing test style to match, and any
+     doc sections that need updating alongside the code.
+  2. Call write_stage_artifact with path implementation-plan.md containing:
+     the root cause or approach in plain terms, each file to edit with the
+     symbol/region of the edit site and the minimal change intended there,
+     the exact validation commands to run in the checkout (verified against
+     this repo's own script names, not guessed), any test coverage the plan
+     requires, and risks or open questions worth flagging before
+     implementation starts.
+  3. Call ask_operator with kind artifact_backed referencing that artifact.
+     Ask whether to approve the exact scope for implementation.
+  4. On rejection or requested changes, revise the artifact and ask again.
+  5. After explicit acceptance, rewrite implementation-plan.md to include an
+     operator-decision section holding the accepted decision, the operator's
+     wording, and any conditions attached. The HITL question-and-answer
+     trail is not replayed into downstream prompts, so this artifact is the
+     only durable record the implement stage can read.
+  6. Emit exactly one envelope, including implementation-plan.md, with a
+     payload matching the schema. Emit success only after explicit
+     acceptance. If the operator declines, emit failure with a concise
+     reason.
+
+  Contract violations — do not present these as success:
+  - approved: true without an explicit operator accept, or interpreting
+    silence as approval.
+  - planned_files or validation_commands left empty, generic, or expressed
+    as intent rather than concrete paths and runnable commands.
+  - A validation command you did not verify exists in this repository (check
+    package.json or the equivalent script manifest before naming one).
+  - A plan that describes the problem without naming exact edit sites.
+
+  Never edit source files in this stage. Never commit, push, or open a pull
+  request.
+
+  Write summary as outcomes and resulting state for downstream stages: what
+  the approved scope is, which artifact carries the checklist, and what the
+  operator accepted. The implement stage receives this summary verbatim and
+  can mistake it for its own instructions, so never put this stage's own
+  prohibitions or scope limits in it — in particular, no "no source edits"
+  language, which applies here and not downstream.
+model: omniroute/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - approved
+        - scope_summary
+        - planned_files
+        - validation_commands
+        - risks
+      properties:
+        approved:
+          type: boolean
+        scope_summary:
+          type: string
+        planned_files:
+          type: array
+          items:
+            type: string
+        validation_commands:
+          type: array
+          items:
+            type: string
+        risks:
+          type: array
+          items:
+            type: string
+verify:
+  - id: plan-approved
+    type: gate
+    kind: artifact_backed
+    when:
+      - emit
+      - after
+  - id: implementation-plan
+    type: artifact
+    path: implementation-plan.md
+    nonempty: true
+    when:
+      - after
+gate_kinds:
+  - artifact_backed