stageflow 0.25.0 → 0.27.0

package/examples/mcp-hitl-tour/gather.yaml

@@ -0,0 +1,31 @@
+id: gather
+system_prompt: |
+  You are the Clone Chain join. Summarize each clone instance's angle.md into
+  one note. Do not invent angles that were not cloned.
+
+  1. Call write_stage_artifact with path angles-brief.md.
+  2. Emit success with artifacts [angles-brief.md] and payload
+     { "kind": "angles" }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+verify:
+  - id: angles-brief-declared
+    type: artifact
+    basename: angles-brief.md
+    when:
+      - emit
+  - id: angles-brief-on-disk
+    type: artifact
+    path: angles-brief.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/intake.yaml

@@ -0,0 +1,62 @@
+id: intake
+gate_kinds:
+  - free_text
+system_prompt: |
+  You are the HITL intake for an MCP operator-host walkthrough.
+
+  The topic arrives as task input (io.input.topic). Do not invent a different topic.
+
+  Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask which audience the brief is
+     for. Tell the operator to reply with exactly one of: operators or
+     executives.
+     - operators: concrete, how-it-works language
+     - executives: short, stakes-and-tradeoffs language
+  2. Wait for the operator answer. Do not call emit_stage_envelope before you
+     have that answer.
+  3. Call write_stage_artifact with path intake.md. Write the topic, the chosen
+     audience, and one sentence that both a clone-chain draft and a short
+     draft will run, then join at polish.
+  4. Call emit_stage_envelope exactly once with:
+     - status: success
+     - a non-empty summary
+     - artifacts: [intake.md]
+     - payload: { "topic": "<task topic>", "audience": "operators" } or
+       { "topic": "<task topic>", "audience": "executives" }, matching the
+       operator reply exactly
+
+  Rules:
+  - Never emit before the operator answers.
+  - Never invent other audience values.
+  - Do not emit fork_choice. Both successor stages always run.
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - topic
+      properties:
+        topic:
+          type: string
+  output:
+    schema:
+      type: object
+      required: [topic, audience]
+      properties:
+        topic:
+          type: string
+        audience:
+          type: string
+verify:
+  - id: intake-declared
+    type: artifact
+    basename: intake.md
+    when:
+      - emit
+  - id: intake-on-disk
+    type: artifact
+    path: intake.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/mcp-hitl-tour-exhaust.task.yaml

@@ -0,0 +1,13 @@
+id: mcp-hitl-tour-exhaust
+goal: |
+  Same walkthrough as mcp-hitl-tour: send the brief back until the loop parks
+  for a human decision after intake HITL.
+context: |
+  Pair with mcp-hitl-tour.pipeline.yaml. Answer intake with exactly operators
+  or executives. Every review success MUST emit send_back target polish —
+  never continue — until waiting_kind is feedback_loop_decision.
+constraints: |
+  Docs only. First review: send_back polish. After the polish replay, second
+  review: send_back polish again so MCP can call decide_feedback_loop.
+input:
+  topic: Local-first notes apps for small teams

package/examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml

@@ -0,0 +1,54 @@
+id: mcp-hitl-tour
+model: cursor/auto
+schemas:
+  Angle:
+    type: object
+    required: [id, title, topic]
+    properties:
+      id:
+        type: string
+      title:
+        type: string
+      topic:
+        type: string
+stages:
+  - id: intake
+    uses: ./intake.yaml
+    entry: true
+    route:
+      - to: emit-angles
+      - to: draft-short
+  - id: emit-angles
+    uses: ./emit-angles.yaml
+    clone_cap: 2
+    clone_mode: sequential
+    route:
+      - to: draft-angle
+  - id: draft-angle
+    uses: ./draft-angle.yaml
+    route:
+      - to: gather
+  - id: gather
+    uses: ./gather.yaml
+    route:
+      - to: polish
+  - id: draft-short
+    uses: ./draft-short.yaml
+    route:
+      - to: polish
+  - id: polish
+    uses: ./polish.yaml
+    route:
+      - to: review
+  - id: review
+    uses: ./review.yaml
+    route:
+      - to: ship
+      - type: loop
+        to: polish
+        max_replays: 1
+        on_max_replays: wait_for_human
+        replay_session: resume
+  - id: ship
+    uses: ./ship.yaml
+    replay_safe: false

package/examples/mcp-hitl-tour/mcp-hitl-tour.task.yaml

@@ -0,0 +1,16 @@
+id: mcp-hitl-tour
+goal: |
+  Produce a short operator-readable brief on the given topic. At intake, the
+  operator chooses audience (operators or executives). Both a Clone Chain
+  draft and a short draft always run, then join at polish. Review always
+  sends the brief back once so the operator decides the loop.
+context: |
+  MCP operator-host walkthrough. Answer the intake free_text gate with exactly
+  operators or executives. Every review success MUST emit send_back target
+  polish — never continue — until waiting_kind is feedback_loop_decision.
+constraints: |
+  Docs only; no implementation code; no git push. First review: send_back
+  polish. After the polish replay, second review: send_back polish again so
+  the operator can call decide_feedback_loop.
+input:
+  topic: Local-first notes apps for small teams

package/examples/mcp-hitl-tour/polish.yaml

@@ -0,0 +1,33 @@
+id: polish
+system_prompt: |
+  Produce the canonical brief.md the reviewer will read.
+
+  Both parents always ran: start from short.md and from angles-brief.md plus
+  the clone angle.md files. Match the intake audience. On a feedback replay,
+  read Feedback Loop Context and revise brief.md to address the send-back.
+
+  1. Call write_stage_artifact with path brief.md.
+  2. Emit success with artifacts [brief.md] and payload { "polished": true }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [polished]
+      properties:
+        polished:
+          type: boolean
+verify:
+  - id: brief-declared
+    type: artifact
+    basename: brief.md
+    when:
+      - emit
+  - id: brief-on-disk
+    type: artifact
+    path: brief.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/review.yaml

@@ -0,0 +1,17 @@
+id: review
+system_prompt: |
+  Review brief.md against the task goal.
+  On every success you MUST emit feedback_loop send_back — never continue:
+
+  {"action":"send_back","target":"polish"}
+
+  This walkthrough always takes one polish replay, then parks for a human
+  feedback decision (MCP decide_feedback_loop). Do not continue to ship from
+  this stage.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/mcp-hitl-tour/ship.yaml

@@ -0,0 +1,25 @@
+id: ship
+system_prompt: |
+  Ship the approved brief. Call write_stage_artifact with path ship.md
+  summarizing the final brief in a few sentences. Emit success with
+  artifacts [ship.md]. This stage is replay_safe: false — it runs only after
+  review continues.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+verify:
+  - id: ship-declared
+    type: artifact
+    basename: ship.md
+    when:
+      - emit
+  - id: ship-on-disk
+    type: artifact
+    path: ship.md
+    nonempty: true
+    when:
+      - after

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: []