stageflow 0.25.0 → 0.30.0

package/examples/oss-issue-contribution/README.md

@@ -0,0 +1,218 @@
+# OSS issue contribution pipeline
+
+Use a real upstream issue to demonstrate Stageflow's strongest runtime features:
+evidence-preserving stages, parallel investigation, explicit handoffs, human
+approval, one controlled writer, independent verification, parallel review, and
+a final publication gate.
+
+The pipeline is repository-neutral. Point the task's `checkout` at a dedicated,
+clean branch in Mastra, Pydantic AI, or another project. It reads that project's
+own contribution instructions before acting.
+
+This catalog is **route-wired** (`entry` / `route` / multiple `to:`). Investigation
+and review are parallel DAG fan-out, not a sealed
+[Clone Chain](../../docs/yaml-catalog.md#clone-chain) (emitter → clone child → Join).
+One Clone Instance per investigation or review item remains intended future
+wiring; author that shape from
+[`tests/fixtures/pipelines/clone-chain-*.pipeline.yaml`](../../tests/fixtures/pipelines/).
+
+## Flow
+
+1. Capture the issue, repository baseline, and contribution rules.
+2. In parallel with reproduction, write a ce-explain HTML teaching artifact for the issue (no HITL).
+3. Reproduce the failure without editing tracked files.
+4. Intended Clone Chain: one Clone Instance per investigation item (parallel).
+5. Join the evidence into an implementation plan and ask for approval.
+6. Write the regression test in its own short stage, then implement the fix
+   and drive the plan's full validation command list to green in one
+   session — the only stage that can edit the checkout owns the whole
+   fix-and-validate loop, rather than handing an unfinished fix to a
+   read-only stage that could only report the gap.
+7. Independently verify the diff and relevant tests.
+8. In parallel with review planning, write a ce-explain HTML teaching artifact for the verified fix (no HITL).
+9. Intended Clone Chain: one Clone Instance per focused review (parallel).
+10. 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 (parallel fan-out
+    via multiple `to:`); it does not declare `{ type: loop }` back to
+    oss-implement-source-fix or a second review pass.
+11. Join into a PR-ready package, ask for final approval, and — once the
+    operator accepts — push the branch and open the pull request against the
+    fork in that same stage.
+
+No stage ever targets the upstream repo, and no stage before the final one
+commits, pushes, or opens a pull request. `oss-approve-contribution` writes
+`contribution-package.md`, calls `ask_operator`, and only runs `git`/`gh`
+against the fork 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
+
+Several stages opt into Stageflow runtime contracts that make the pipeline fail
+closed when a stage skips its deliverable.
+
+Every stage except the two approval stages declares `gate_kinds: []`, which
+unregisters the `ask_operator` tool entirely. Those stages cannot pause for
+operator input or offer to substitute a report for real work. Only
+`oss-approve-plan` and `oss-approve-contribution` keep
+`gate_kinds: [artifact_backed]`.
+
+### 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: it stays a DAG with parallel fan-out via multiple `to:`. If
+`oss-review-change` finds a blocking problem, the run does not resume
+`oss-implement-source-fix` or `oss-verify-fix`. `oss-address-review-feedback`
+is the accommodation: a single fixup stage after review and before approval
+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 `oss-approve-contribution`, 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, `oss-approve-contribution`'s
+fail-closed check is the backstop, and the operator has to intervene by hand —
+see [docs/cli-reference.md](../../docs/cli-reference.md) for `sf runs retry`,
+which can retry a succeeded stage in place and reset everything downstream.
+
+Every stage declares `verify` with at least one `type: artifact` check, so a
+success emit is rejected unless the named file appears in the envelope's
+artifact list. Writer stages add `type: checkout_changes` with `path_fields`;
+approval stages also declare a `type: gate` check (`kind: artifact_backed`).
+Pipeline entries wire `on_verify_fail` (repair for most stages; `manual` on
+`oss-approve-contribution`) so after-phase failures retry or wait for an
+operator instead of silently advancing.
+
+| Stage | Gate | Required artifacts | Other checks |
+|-------|------|--------------------|--------------|
+| `oss-issue-intake` | `[]` | `issue-intake.md` | — |
+| `oss-explain-issue` | `[]` | `issue-explainer.html` | — |
+| `oss-reproduce-issue` | `[]` | `reproduction.md` | — |
+| `oss-plan-investigation` | `[]` | `investigation-map.md` | intended Clone Chain emitter |
+| `oss-investigate-area` | `[]` | `investigation.md` | intended clone child |
+| `oss-approve-plan` | `[artifact_backed]` | `implementation-plan.md` | — |
+| `oss-write-regression-test` | `[]` | `regression-test-report.md` | `[test_files]` |
+| `oss-implement-source-fix` | `[]` | `implementation-report.md` | `[changed_files]` |
+| `oss-verify-fix` | `[]` | `verification.md` | — |
+| `oss-explain-fix` | `[]` | `fix-explainer.html` | — |
+| `oss-plan-review` | `[]` | `review-plan.md` | intended Clone Chain emitter |
+| `oss-review-change` | `[]` | `review.md` | intended clone child |
+| `oss-address-review-feedback` | `[]` | `review-feedback-report.md` | — |
+| `oss-approve-contribution` | `[artifact_backed]` | `contribution-package.md`, `pull-request.md` | — |
+
+Intended Clone Chains: `oss-plan-investigation` → `oss-investigate-area` → `oss-approve-plan`, and `oss-plan-review` → `oss-review-change` → join at address/approve. This directory's YAML is not yet that shape. See [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain).
+
+`oss-investigate-area` and `oss-review-change` use empty `io.input` (a subset of each parent's `io.output`). Assignment fields (`area_id`/`objective`/`paths`/`questions`/`constraints` or the review equivalent) belong on intended Clone Chain payloads, not this DAG.
+
+Plan approval (`oss-approve-plan`) and contribution approval
+(`oss-approve-contribution`) use `artifact_backed` HITL and cannot self-approve;
+the runtime checks the QA trail before accepting a success emit.
+
+`oss-write-regression-test` and `oss-implement-source-fix` require an array
+field (`test_files` or `changed_files`) with `minItems: 1` on `io.output.schema`.
+That constraint only checks the array is non-empty — it does not verify the
+entries are real edits in the checkout, and a Stageflow artifact path satisfies
+it. A run that never touched the checkout has passed this way before.
+
+Both writer stages therefore also declare a `verify` check of
+`type: checkout_changes` with `path_fields` naming that array field, so the
+runtime enforces after the stage what the prompts alone could not:
+
+- `type: checkout_changes` rejects a success outcome when
+  `git status --porcelain` in the bound task checkout is empty.
+- `path_fields: [changed_files]` (or `[test_files]`) rejects a success outcome
+  when any listed entry is not a path inside the checkout — including the
+  `stages/<id>/attempts/<n>/artifacts/...` paths returned by
+  `write_stage_artifact`.
+
+Stageflow is a configurable-stage runtime. These contracts are opt-in per
+catalog; this example is one consumer that uses them to enforce a strict
+contribution workflow.
+
+## Explainers
+
+The two explainer stages are dead-end siblings: they do not pause investigation,
+implementation, or review, and they do not call `ask_operator`. Each composes a
+ce-explain HTML teaching artifact — concept for the issue, diff for the verified
+fix — grounded in quoted checkout source and an inline SVG, written with
+`write_stage_artifact`. Open `issue-explainer.html` and `fix-explainer.html`
+from the run artifacts when you want them. They require the `ce-explain` skill
+at `.pi/skills/ce-explain/` (copy the skill tree from Compound Engineering;
+`sf skills install` expects a doctor binary this skill does not ship).
+
+## Prepare the target repository
+
+Use a dedicated branch and begin with a clean tracked worktree:
+
+```bash
+git clone https://github.com/mastra-ai/mastra.git
+cd mastra
+git switch -c investigate-22863
+git status --short
+```
+
+## Create a task outside the target checkout
+
+Task context is the pipeline's portable issue input. Include the issue body or
+acceptance criteria so the run remains useful if GitHub access is unavailable.
+
+```yaml
+id: mastra-22863
+goal: >
+  Deliver a verified minimal fix for Mastra issue #22863, applied as source and
+  test edits in the checkout working tree.
+context: |
+  Issue: https://github.com/mastra-ai/mastra/issues/22863
+  Title: <copy the current issue title>
+  Reported behavior: <copy or summarize the concrete failure>
+  Expected behavior: <copy or summarize the acceptance criterion>
+  Current triage/maintainer status: <record what you verified today>
+constraints: |
+  Respect all repository contribution and agent instructions.
+  Do not publish while the issue is awaiting maintainer direction.
+  Do not commit, push, or open a pull request.
+  Keep the change limited to the reproduced issue and its regression test.
+checkout: /absolute/path/to/mastra
+```
+
+For Pydantic AI, use the same shape with a Pydantic issue and set `checkout` to
+the absolute path of that clone. A ready task for issue #7971 is
+`pydantic-ai-7971.task.yaml`. The stage definitions do not need to change.
+
+## Run
+
+From any directory with Stageflow installed:
+
+```bash
+sf validate \
+  --pipeline /path/to/stageflow/examples/oss-issue-contribution/oss-issue-contribution.pipeline.yaml \
+  --strict
+
+sf run \
+  --pipeline /path/to/stageflow/examples/oss-issue-contribution/oss-issue-contribution.pipeline.yaml \
+  --task /path/to/mastra-22863.task.yaml
+```
+
+`oss-approve-contribution` pushes and opens the pull request against the fork
+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 Instances,
+and answer the two artifact-backed gates. The explainer HTML files are ordinary
+stage artifacts; they do not appear as gates.
+
+## Safety and interpretation
+
+- Plan approval authorizes only local edits in the task checkout.
+- Review Clone Instances always complete successfully and carry `pass` or
+  `changes_required` in their payload, allowing the Join to see every review.
+- Any blocking review fails the final stage closed.
+- The operator's accept through `oss-approve-contribution`'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. It never
+  authorizes targeting upstream.
+- Issue labels, assignments, and maintainer guidance can change. Re-verify them
+  before accepting the gate on a run that will open a pull request.

package/examples/oss-issue-contribution/oss-address-review-feedback.yaml

@@ -0,0 +1,117 @@
+id: oss-address-review-feedback
+system_prompt: |
+  Address every blocking finding from oss-review-change before the
+  contribution package is assembled. There is no automatic path back to
+  oss-implement-source-fix or oss-verify-fix 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 fix. 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 oss-review-change
+  envelope's payload (review_id, verdict, blocking_findings) and its review.md
+  are authoritative; implementation-report.md and verification.md give 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 oss-review-change 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 test still asserting
+    semantics the fix already inverted elsewhere, or every other call site
+    with the same missing type widening) 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 is written and listed in the emitted artifacts;
+    the emit is rejected without it.
+
+  1. Read every oss-review-change 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. Write 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 oss-approve-contribution:
+  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/oss-issue-contribution/oss-approve-contribution.yaml

@@ -0,0 +1,181 @@
+id: oss-approve-contribution
+system_prompt: |
+  Produce one operator-approved contribution-package.md that states the
+  verified facts of the change, then — once the operator accepts it — publish
+  the pull request against the fork yourself in this same stage. Do not edit
+  source files. Never target pydantic/pydantic-ai; only the fork named in the
+  task.
+
+  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>. verification.md is the authoritative
+  record of which commands ran and their results, implementation-report.md of
+  what was changed, implementation-plan.md of what was approved,
+  review-feedback-report.md of what oss-address-review-feedback fixed after
+  review, and each review.md of what each reviewer originally found. Prose
+  summaries are secondary.
+
+  Trust but verify oss-address-review-feedback. Its report is a claim, not
+  proof by itself: cross-check addressed_all_blocking against the original
+  review.md blocking_findings and confirm the specific checks they cited
+  actually pass now, rather than accepting the claim at face value.
+
+  Definition of done, checked before you emit:
+  - Every oss-review-change envelope, its review.md, and
+    review-feedback-report.md have been read.
+  - contribution-package.md is written, listed in the emitted artifacts, and
+    contains the PR title, PR body, tests run with their results, changed
+    files, and the exact publish commands.
+  - changed_files matches git diff --name-only in the checkout.
+  - tests are the commands and node ids recorded in verify/implement evidence.
+  - publish_repo is the fork named in the task, and the artifact says so
+    explicitly.
+  - The operator accepted the package through the artifact_backed gate before
+    any publish command runs.
+  - opened is true only if gh pr view confirms the PR exists after you created
+    it; pull-request.md is written and listed in the emitted artifacts.
+
+  1. Read every oss-review-change envelope/artifact, review-feedback-
+     report.md, the task, implementation-plan.md, implementation-report.md,
+     and verification.md via the recipe above. Run git diff --name-only and
+     git diff --stat in the checkout.
+  2. Write contribution-package.md containing issue link and scope, root cause,
+     before/after behavior, changed files, exact validation results, all review
+     verdicts and how any blocking findings were addressed, remaining risks,
+     current maintainer/triage status, and a proposed pull-request title and
+     body targeting the fork named in the task (not upstream). State the fork
+     explicitly as the publish target. Do not claim tests, approval,
+     assignment, or maintainer support that was not verified.
+  3. Fail closed. If review-feedback-report.md says addressed_all_blocking is
+     not true, or your own re-check finds any original blocking_findings entry
+     whose cited check still fails, mark the package NOT READY and emit
+     failure with the artifact. Do not ask the operator to approve
+     known-blocking code, and do not run any publish command in that case.
+  4. Otherwise call ask_operator with kind artifact_backed referencing the
+     package. Ask whether it is ready to publish against the fork.
+  5. For wording/report changes, revise the artifact and ask again. If the
+     operator requests code changes or declines publication, emit failure and
+     preserve the requested changes in the artifact. Do not run any publish
+     command without an explicit accept.
+  6. Only after explicit acceptance: confirm publish_repo is exactly the fork
+     named in the task (never pydantic/pydantic-ai), then run git add, git
+     commit (using pr_title as the message unless the package recipe says
+     otherwise), git push, and gh pr create --repo <publish_repo>
+     --head <branch> --base main --title <pr_title> --body <pr_body_summary>.
+     Auth is GH_TOKEN or GITHUB_TOKEN already in the environment; gh is on
+     PATH.
+  7. Confirm with gh pr view. Write pull-request.md via write_stage_artifact
+     with the PR URL, the commands actually run, and their results. If a pull
+     request already exists for this branch, or any command fails, emit
+     status failure and record what happened; never retry a create with
+     altered scope.
+  8. Emit exactly once, including contribution-package.md, pull-request.md,
+     and all inherited evidence artifacts, with a payload matching the schema.
+     Do not stop after a chat reply or after opening the PR — the stage only
+     completes when emit_stage_envelope returns.
+
+  Payload discipline. changed_files must be copied from the verify and
+  implement payloads and cross-checked against git diff --name-only; entries
+  that do not appear in that output, or that point under stages/.../artifacts/,
+  are a contract violation. tests must be the real commands or test node ids
+  from verification.md, never invented and never n/a, none, tbd, or pending.
+  Every string field must carry real content and every array substantive
+  entries, not placeholders such as ["see diff"]. commands_run must list only
+  the git/gh commands you actually executed, each with its outcome.
+
+  Contract violations — emit failure rather than presenting these as success:
+  - Running git add, git commit, git push, or gh pr create before the operator
+    has explicitly accepted through the artifact_backed gate.
+  - opened: true without gh pr view confirming the PR exists.
+  - publish_repo anything other than the exact fork named in the task.
+  - commands_run listing commands you did not execute.
+  - Writing contribution-package.md without reading the reviews and
+    reconciling the diff first.
+
+  Summary authoring. The emitted summary describes outcomes and state for
+  downstream consumers: readiness, review verdicts, which files changed, which
+  tests passed, the publish target, and the PR URL if opened. Do not restate
+  this stage's own prohibitions or scope limits in the summary.
+model: omniroute/auto
+io:
+  input:
+    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
+  output:
+    schema:
+      type: object
+      required:
+        - pr_title
+        - pr_body_summary
+        - tests
+        - changed_files
+        - publish_repo
+        - commands_run
+        - opened
+        - pr_url
+      properties:
+        pr_title:
+          type: string
+        pr_body_summary:
+          type: string
+        tests:
+          type: array
+          items:
+            type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        publish_repo:
+          type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+verify:
+  - id: contribution-approved
+    type: gate
+    kind: artifact_backed
+    when:
+      - emit
+      - after
+  - id: contribution-package
+    type: artifact
+    path: contribution-package.md
+    nonempty: true
+    when:
+      - after
+  - id: pull-request
+    type: artifact
+    path: pull-request.md
+    nonempty: true
+    when:
+      - after
+gate_kinds:
+  - artifact_backed

package/examples/oss-issue-contribution/oss-approve-plan.yaml

@@ -0,0 +1,111 @@
+id: oss-approve-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.
+
+  Reading upstream work: prior envelopes' artifacts[] hold 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. The
+  oss-investigate-area investigation artifacts and the intake and reproduction
+  artifacts are authoritative over any prose in the prior envelopes' summaries;
+  those summaries describe their own stages only.
+
+  Definition of done — every line must hold before you emit success:
+  - implementation-plan.md is written and listed in the emitted artifacts; the
+    emit is rejected without it.
+  - The plan names the exact regression test node id, the exact files and edit
+    sites, and the exact validation commands to run.
+  - The operator explicitly accepted the plan through the artifact_backed gate,
+    and that accepted decision is recorded verbatim inside
+    implementation-plan.md.
+  - planned_files and validation_commands are non-empty and concrete;
+    approved is true only after that explicit accept.
+
+  1. Read the task, all prior oss-investigate-area envelopes and their
+     artifacts, plus the intake and reproduction evidence. Reconcile
+     contradictions rather than silently choosing one claim.
+  2. Write implementation-plan.md with root-cause evidence and a mechanical
+     implementation checklist: the exact regression test name and node id to add
+     or run, each file to edit with the symbol and line region of the edit site,
+     the minimal change at each site, and the validation commands to run in the
+     checkout. Then record alternatives and tradeoffs, risks, and any
+     contribution-policy blockers. State whether current issue triage or
+     maintainer guidance permits publishing a pull request; lack of permission
+     may block publication without blocking a local investigation.
+  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 plan 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 the accepted plan and the inherited
+     evidence artifacts, with a payload matching the schema. Emit success only
+     after explicit acceptance. If the operator declines implementation, 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 plan that describes the problem without naming the regression test node id
+    and the 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, what the operator
+  accepted, and what blockers remain. The implement stage receives this summary
+  verbatim and can mistake it for its own instructions, so never put this
+  stage's 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
+        - publication_blockers
+      properties:
+        approved:
+          type: boolean
+        scope_summary:
+          type: string
+        planned_files:
+          type: array
+          items:
+            type: string
+        validation_commands:
+          type: array
+          items:
+            type: string
+        publication_blockers:
+          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