stageflow 0.25.0 → 0.30.0

package/examples/oss-issue-contribution/oss-verify-fix.yaml

@@ -0,0 +1,130 @@
+id: oss-verify-fix
+system_prompt: |
+  Independently re-verify the proposed upstream fix already present in the task
+  checkout working tree, and record the evidence in verification.md. This stage
+  is read-only: do not edit, create, or delete files in the checkout, and do not
+  commit, push, or open a pull request.
+
+  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-report.md is the authoritative record of what
+  oss-implement-source-fix did, including its own full validation_commands
+  run, and implementation-plan.md is the authoritative approved scope; both
+  outrank any prose in the prior envelope's summary. That summary describes
+  the PREVIOUS stage, and any prohibition or scope limit it carries applied to
+  that stage, not to this one.
+
+  Definition of done — every line must hold before you emit success:
+  - git diff in the checkout is non-empty; the emit is rejected while the
+    working tree is clean.
+  - Every command recorded in oss-implement-source-fix's commands_run
+    (its own full validation_commands run) has been re-executed here
+    verbatim, with its exit code and a stdout tail recorded in
+    verification.md.
+  - The narrow regression test actually passed in this stage's own run.
+  - verification.md is written and listed in the emitted artifacts; the emit is
+    rejected without it.
+  - commands lists only commands you actually executed here.
+
+  1. Read the task, the accepted plan, the implementation envelope and report,
+     the repository instructions, and the current diff.
+  2. Run git status --porcelain and git diff --stat. If the working tree is
+     clean, there is nothing to verify: emit failure.
+  3. Confirm every changed file is in approved scope and the diff contains no
+     unrelated, generated, secret, credential, or debug-output changes. Flag
+     every out-of-scope or unexplained change explicitly.
+  4. Re-execute oss-implement-source-fix's commands_run verbatim, in order,
+     then the smallest broader test/typecheck/lint set the repository
+     guidance requires. Record each command with its exit code and a stdout
+     tail. Do not hide flaky or environmental failures. If the regression
+     test cannot be run here, emit failure.
+  5. Check the fix against the issue's expected behavior and examine boundary,
+     failure, concurrency, cleanup, or compatibility cases relevant to this bug.
+  6. Write verification.md with a reproducible verification record: the diff
+     stat, each command with exit code and stdout tail, scope findings, and
+     remaining risks.
+  7. Emit exactly once, including verification.md and all inherited evidence
+     artifacts, with a payload matching the schema.
+
+  Contract violations — emit failure rather than presenting these as success:
+  - result: pass when the regression did not pass in this stage. A pass inherited
+    from the implement payload is not verification.
+  - commands listing commands you did not execute, or copied from the implement
+    payload without re-running them.
+  - Emitting success while git diff in the checkout is empty.
+  - Editing the checkout to make a command pass.
+
+  Write summary as outcomes and resulting state for downstream stages: what was
+  re-executed, what passed or failed, what scope or risk findings stand.
+  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: 1800000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - changed_files
+        - regression_test
+        - implementation_summary
+        - assumptions
+        - commands_run
+        - all_passed
+      properties:
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        regression_test:
+          type: string
+        implementation_summary:
+          type: string
+        assumptions:
+          type: array
+          items:
+            type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        all_passed:
+          type: boolean
+  output:
+    schema:
+      type: object
+      required:
+        - result
+        - commands
+        - changed_files
+        - remaining_risks
+      properties:
+        result:
+          type: string
+          enum:
+            - pass
+        commands:
+          type: array
+          items:
+            type: string
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        remaining_risks:
+          type: array
+          items:
+            type: string
+verify:
+  - id: verification
+    type: artifact
+    path: verification.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-issue-contribution/oss-write-regression-test.yaml

@@ -0,0 +1,135 @@
+id: oss-write-regression-test
+system_prompt: |
+  Add the narrow regression test named in the approved plan, and only that
+  test. Do not touch source files. Modified test files under "Project checkout
+  (agent cwd)" are the only acceptable output of this stage; no map, excerpt,
+  document, or report can substitute for them.
+
+  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 input and 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 only test-file edits;
+    the emit is rejected while the working tree is clean.
+  - Every test_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.
+  - test_node_id names the exact test you added or identified, in a form the
+    next stage can run directly (e.g. `pytest tests/x.py::test_y`).
+  - The test demonstrably fails against the current (unfixed) source. If a red
+    run is genuinely impractical (for example the failure requires an external
+    service), record why and the alternative evidence instead of a fabricated
+    failure.
+  - regression-test-report.md is written and listed in the emitted artifacts;
+    the emit is rejected without it.
+  - commands_run lists only commands you actually executed, each with its
+    outcome.
+
+  1. Resolve implementation-plan.md from the prior envelope's artifacts[]
+     against the Factory run workspace absolute path and read it. Treat it as
+     authoritative over the prior summary. If the plan cannot be read, emit
+     failure — do not substitute a plan you re-derived yourself.
+  2. Confirm the checkout is still on the recorded base commit and that no
+     unexpected tracked changes appeared. If it diverged, emit failure without
+     overwriting work.
+  3. Add or identify the exact regression test the plan names. Do not write
+     source fixes here, even trivially — that is the next stage's job.
+  4. Run the test and confirm it fails for the reason the plan describes (the
+     bug, not a typo or fixture error). Record the failing output verbatim.
+  5. Run git status --porcelain and git diff --stat. If either output is
+     empty, or the diff touches anything outside test files, this stage has
+     not done its job: return to step 3 or emit failure.
+  6. Write regression-test-report.md containing the verbatim non-empty
+     git diff --stat and git status --porcelain output, the test node id, the
+     red-run output, and any deviation from the plan.
+  7. Emit exactly once, including regression-test-report.md and all inherited
+     evidence artifacts, with a payload matching the schema. Emit success only
+     if every definition-of-done line holds; otherwise emit failure while
+     preserving the working-tree evidence for the operator.
+
+  Contract violations — emit failure rather than presenting these as success:
+  - Emitting success while git diff in the checkout is empty.
+  - A test_files entry under stages/.../artifacts/ or anywhere else in the
+    factory run workspace. Such a path is never a valid entry.
+  - test_node_id that is not directly runnable, or that names a test you did
+    not actually add or locate.
+  - Claiming a red run without having executed the test.
+  - Editing any source file in this stage.
+
+  Never commit, push, or open a pull request.
+
+  Write summary as outcomes and resulting state for downstream stages: which
+  test now exists, why it currently fails, what remains for the fix.
+  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: 2400000
+io:
+  input:
+    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
+  output:
+    schema:
+      type: object
+      required:
+        - test_files
+        - test_node_id
+        - red_evidence
+        - commands_run
+      properties:
+        test_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        test_node_id:
+          type: string
+        red_evidence:
+          type: string
+        commands_run:
+          type: array
+          items:
+            type: string
+verify:
+  - id: regression-test-report
+    type: artifact
+    path: regression-test-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - test_files
+    when:
+      - after
+gate_kinds: []

package/examples/oss-issue-contribution/pi-7629.task.yaml

@@ -0,0 +1,79 @@
+id: pi-7629
+goal: >
+  Deliver a verified minimal local fix for Pi issue #7629, tui.select.pageUp
+  and tui.select.pageDown are not handled in all select lists, applied as
+  source and test edits in the checkout working tree, plus an
+  operator-approved pull request opened against tejasghutukade/pi rather than
+  earendil-works/pi.
+context: |
+  Issue: https://github.com/earendil-works/pi/issues/7629
+  Title: tui.select.pageUp and tui.select.pageDown are not handled in all select lists
+  Upstream repo: https://github.com/earendil-works/pi
+  Fork (PR target after the run): https://github.com/tejasghutukade/pi
+  State: OPEN, unassigned, labeled bug, zero human comments — unclaimed.
+
+  Pi's CONTRIBUTING.md auto-closes issues and PRs from new/unproven
+  contributors by default and requires a maintainer to reply `lgtm` (not
+  `lgtmi`, which only exempts future issues) before any PR against
+  earendil-works/pi is permitted. No such reply exists yet, so this run
+  prepares a local change and a fork PR only; the upstream PR is a separate,
+  explicitly-authorized step after `lgtm` lands.
+
+  Reported behavior: the reporter remapped the configurable keybindings
+  tui.select.pageUp / tui.select.pageDown (default Page Up / Page Down) to
+  other keys (ctrl+v / alt+v, Emacs-style) in settings. The remap is honored
+  in some select-list UI (works in at least one place) but not others,
+  specifically:
+    - file-path autocompletion in the editor
+    - the /settings menu
+    - the model selector
+  In the broken locations, paging does not scroll the list at all when the
+  remapped key is pressed. Expected behavior: every select-list surface pages
+  one page down/up on tui.select.pageDown / tui.select.pageUp regardless of
+  what physical key(s) they are bound to.
+
+  Reporter's repro: bind tui.select.pageDown to ctrl+v, open the "/" command
+  menu (works), then try file-path autocomplete, /settings, or the model
+  selector (Page Up/Down and the remapped key both fail to scroll).
+  Reporter attached a standalone extension-based workaround (select-page-keys)
+  they had an LLM write, which is evidence they understand the shape of the
+  problem but not proof of the actual root cause.
+
+  Suspected root cause (to verify during investigation, not assumed): pi
+  likely has more than one TUI "select list" component implementation, and
+  only one of them resolves paging through the shared configurable-keybinding
+  lookup (tui.select.pageUp/pageDown); the others either hardcode literal
+  PageUp/PageDown key handling or omit paging entirely. The fix is to make
+  every select-list surface read paging from the same keybinding resolution
+  path as the one that already works, not to hand-wire the reporter's
+  specific remap.
+
+  The full issue write-up is captured by the intake stage in
+  issue-intake.md; treat this context as a starting point, not a substitute
+  for reading the issue and the source directly.
+constraints: |
+  Respect pi's AGENTS.md, CONTRIBUTING.md, and any package-local test docs
+  (e.g. under packages/*/docs). Before reporting or assuming an issue is core
+  behavior, validate it is not caused by an extension, matching pi's own
+  contribution guidance.
+  Do not commit, push, create a branch, or open a pull request in any stage
+  except oss-approve-contribution, which may do so only after the operator
+  has explicitly accepted the contribution package through its
+  artifact_backed gate.
+  Do not target earendil-works/pi. The PR base is always tejasghutukade/pi
+  (gh pr create --repo tejasghutukade/pi).
+  Do not edit CHANGELOG.md; pi's maintainers add changelog entries themselves.
+  Before opening the local PR, the checkout must pass `npm run check` and
+  `./test.sh` (or the package-scoped equivalents for the touched package) —
+  record their exact output as evidence, do not claim they passed without
+  running them.
+  Keep the change limited to the reported paging inconsistency and its
+  regression test; do not expand scope to unrelated keybinding behavior.
+  Do not treat missing maintainer lgtm or assignment as a reason to skip
+  local work — investigate, fix, and verify locally regardless; publication
+  policy lives only at the contribution gate.
+  Source and test edits belong in the checkout working tree and must never be
+  replaced by a Stageflow artifact or report describing the change.
+  In the explainer stages only (oss-explain-issue, oss-explain-fix), the
+  explainer HTML belongs in Stageflow artifacts, never in the checkout.
+checkout: /Users/tejasghutukade/Projects/pi

package/examples/oss-issue-contribution/pi-8919.task.yaml

@@ -0,0 +1,75 @@
+id: pi-8919
+goal: >
+  Deliver a verified minimal local fix for Pi issue #8919, fullscreen mode
+  reserving a blank line for a zero-row custom footer, applied as source and
+  test edits in the checkout working tree, plus an operator-approved pull
+  request opened against tejasghutukade/pi rather than earendil-works/pi.
+context: |
+  Issue: https://github.com/earendil-works/pi/issues/8919
+  Title: Fullscreen mode reserves a blank line for zero-row custom footers (footer minSize should be 0)
+  Upstream repo: https://github.com/earendil-works/pi
+  Fork (PR target after the run): https://github.com/tejasghutukade/pi
+  State: OPEN, unassigned at the time this task was written, though another
+  contributor has since commented intending to fix it. Pi's CONTRIBUTING.md
+  auto-closes issues/PRs from unproven contributors and requires a
+  maintainer `lgtm` before any PR against earendil-works/pi is permitted —
+  no such reply exists, so this run prepares a local change and a fork PR
+  only; the upstream PR is a separate, explicitly-authorized step.
+
+  This run's primary purpose is validating the oss-issue-contribution
+  pipeline's Verified Stage Execution contracts (`verify` artifact /
+  checkout_changes / gate checks, plus `on_verify_fail` wiring) against a
+  real run, not a genuine race to land this specific fix upstream.
+
+  Reported behavior: in fullscreen TUI mode, a custom footer
+  (`pi.ui.setFooter`) that renders zero rows still occupies one blank line;
+  inline mode collapses it correctly. Root cause per the reporter: the
+  fullscreen dock in
+  packages/coding-agent/src/modes/interactive/interactive-mode.ts reserves
+  the footer's row unconditionally via `{ component: this.footerContainer,
+  shrink: 1, minSize: 1 }` (around line 935). `allocateStackSizes` clamps to
+  `minSize` before distribution, so the slot gets at least 1 row even when
+  the footer component renders `[]`.
+
+  Reporter's proposed fix: change `minSize: 1` to `minSize: 0` on that one
+  dock entry. Reporter states this causes no visual change for the built-in
+  footer (with `basis` unset, size comes from intrinsic rows and
+  `FooterComponent` always renders at least 1 row; `minSize` is only a
+  shrink floor) — the only behavioral difference is that at extreme terminal
+  heights the footer can now shrink to 0 before the editor is squeezed,
+  which the reporter argues is preferable. Verify this reasoning independently
+  by reading `allocateStackSizes` and the footer rendering path rather than
+  taking the reporter's claim at face value.
+
+  Repro (from the issue): fullscreen mode
+  (`"tuiMode": "fullscreen"`) plus any extension registering an empty
+  footer, e.g. `pi.ui.setFooter(() => ({ invalidate() {}, render: () => [] }))`.
+
+  The full issue write-up is captured by the intake stage in
+  issue-intake.md; treat this context as a starting point, not a substitute
+  for reading the issue and the source directly.
+constraints: |
+  Respect pi's AGENTS.md, CONTRIBUTING.md, and any package-local test docs.
+  Before reporting or assuming an issue is core behavior, validate it is not
+  caused by an extension, matching pi's own contribution guidance.
+  Do not commit, push, create a branch, or open a pull request in any stage
+  except oss-approve-contribution, which may do so only after the operator
+  has explicitly accepted the contribution package through its
+  artifact_backed gate.
+  Do not target earendil-works/pi. The PR base is always tejasghutukade/pi
+  (gh pr create --repo tejasghutukade/pi).
+  Do not edit CHANGELOG.md.
+  Before opening the local PR, the checkout must pass `npm run check` and
+  `./test.sh` (or the package-scoped equivalent for packages/coding-agent) —
+  record their exact output as evidence, do not claim they passed without
+  running them.
+  Keep the change limited to the reported footer minSize issue and its
+  regression test; do not expand scope to unrelated layout behavior.
+  Do not treat the other contributor's stated intent to fix this as a
+  reason to skip local work — investigate, fix, and verify locally
+  regardless; publication policy lives only at the contribution gate.
+  Source and test edits belong in the checkout working tree and must never
+  be replaced by a Stageflow artifact or report describing the change.
+  In the explainer stages only (oss-explain-issue, oss-explain-fix), the
+  explainer HTML belongs in Stageflow artifacts, never in the checkout.
+checkout: /Users/tejasghutukade/Projects/pi

package/examples/oss-issue-contribution/pydantic-ai-7971.task.yaml

@@ -0,0 +1,53 @@
+id: pydantic-ai-7971
+goal: >
+  Deliver a verified minimal local fix for Pydantic AI issue #7971, Carry a
+  durable unit's emitted events and enqueued messages in its recorded output,
+  applied as source and test edits in the checkout working tree, plus an
+  operator-approved pull request opened against tejasghutukade/pydantic-ai
+  rather than pydantic/pydantic-ai.
+context: |
+  Issue: https://github.com/pydantic/pydantic-ai/issues/7971
+  Title: Carry a durable unit's emitted events and enqueued messages in its recorded output
+  Upstream repo: https://github.com/pydantic/pydantic-ai
+  Fork (PR target after the run): https://github.com/tejasghutukade/pydantic-ai
+  State: OPEN, unassigned. Pydantic contributing guidance asks for assignment
+  before an upstream PR, so this run prepares a local change for a fork PR only.
+
+  Reported behavior: under durable execution, ctx.emit() and ctx.enqueue() are
+  side effects of running a durable unit rather than part of its recorded
+  result, so they do not survive replay. On Prefect/DBOS a replayed result
+  never re-emits; on Temporal emit from a tool or event stream handler raises;
+  ctx.enqueue() is rejected on all three engines. A capability therefore cannot
+  emit from its own tools under durable execution.
+
+  Expected behavior (proposal on the issue): carry the emitted events and
+  enqueued messages back in the unit's recorded output and replay them
+  container-side. (1) Worker-side, install capture sinks on the unit's
+  RunContext so emit and enqueue append instead of raising or reaching the live
+  buffer. (2) Return them alongside the operation's value in an envelope over
+  ResultT. (3) Container-side, re-emit the captured events and extend
+  pending_messages before handing the value back. DurableOperation already has
+  the shape: one handler, one result_codec, and declaration sites in
+  durable_exec/_base.py.
+
+  Care needed: liveness on in-process engines (live delivery vs
+  capture-then-replay), and wire compatibility (decode both the bare value and
+  the envelope; see test_durable_exec_compat.py).
+
+  The full issue write-up, including per-engine detail and related issues, is
+  captured by the intake stage in issue-intake.md.
+constraints: |
+  Respect pydantic-ai AGENTS.md, CONTRIBUTING.md, and test docs.
+  Do not commit, push, create a branch, or open a pull request in any stage
+  except oss-approve-contribution, which may do so only after the operator
+  has explicitly accepted the contribution package through its
+  artifact_backed gate.
+  Do not target pydantic/pydantic-ai. The PR base is always
+  tejasghutukade/pydantic-ai (gh pr create --repo tejasghutukade/pydantic-ai).
+  Keep the change limited to the reproduced issue and its regression test.
+  Do not treat missing maintainer assignment as a reason to skip local work.
+  Source and test edits belong in the checkout working tree and must never be
+  replaced by a Stageflow artifact or report describing the change.
+  In the explainer stages only (oss-explain-issue, oss-explain-fix), the
+  explainer HTML belongs in Stageflow artifacts, never in the checkout.
+checkout: /Users/tejasghutukade/Projects/pydantic-ai

package/examples/oss-quick-fix/README.md

@@ -0,0 +1,65 @@
+# oss-quick-fix
+
+A minimal, fully unattended sibling of
+[`oss-issue-contribution`](../oss-issue-contribution/): one straight-line
+spine from "understand the issue" to "PR opened against my fork," with no
+operator gate anywhere in the run.
+
+Every stage declares `gate_kinds: []`, which unregisters `ask_operator`
+entirely — stages must decide and proceed, never pause for a human. Use this
+shape for issues small enough that you trust a single unsupervised pass; use
+`oss-issue-contribution` when you want parallel investigation/review and an
+operator approval before anything ships.
+
+## Flow
+
+```
+understand-issue → implement-fix → verify-fix → ship-fix
+```
+
+1. **understand-issue** — Reads the task goal/context, locates the responsible
+   code, reproduces the bug if practical, and writes `investigation.md`.
+2. **implement-fix** — Writes a failing regression test, fixes the root cause,
+   confirms the test (and the broader suite) passes, and writes
+   `fix-report.md`. `changed_files` must match `git diff --name-only` exactly.
+3. **verify-fix** — Independently re-runs the repo's real check/lint/test
+   commands against the actual diff (not the report's description of it) and
+   writes `verification.md`. `all_passed` is true only if every command it
+   ran actually exited zero.
+4. **ship-fix** — Commits, pushes, and opens a pull request against
+   `publish_repo` — the fork named in the task, never the upstream repo — and
+   writes `ship-report.md`. Refuses to proceed if `verify-fix` did not pass or
+   if the task does not name a fork.
+
+Every stage declares `on_verify_fail: { mode: repair, retry_safety: idempotent, max_attempts: 3 }`
+except `ship-fix`, which uses `mode: manual` / `retry_safety: side_effecting`
+because it is the only stage with side effects (git push, PR creation).
+
+## Runtime contracts
+
+| Stage | Required artifact | Other checks |
+|-------|--------------------|---------------|
+| `understand-issue` | `investigation.md` | — |
+| `implement-fix` | `fix-report.md` | `type: checkout_changes` on `changed_files` |
+| `verify-fix` | `verification.md` | — |
+| `ship-fix` | `ship-report.md` | — |
+
+## Run
+
+Fill in [`oss-quick-fix.task.yaml`](oss-quick-fix.task.yaml) — the issue, the
+fork to publish to, and `checkout` pointed at a clean working tree of the
+target repository.
+
+```bash
+sf validate --pipeline examples/oss-quick-fix/oss-quick-fix.pipeline.yaml --strict
+sf run \
+  --pipeline examples/oss-quick-fix/oss-quick-fix.pipeline.yaml \
+  --task examples/oss-quick-fix/oss-quick-fix.task.yaml
+```
+
+Needs a configured provider (`sf providers status`), and `gh` on `PATH`
+authenticated (`GH_TOKEN` or `GITHUB_TOKEN`) before `ship-fix` runs, or the
+publish step fails after the fix is already verified.
+
+Run `sf ui` in another terminal to inspect envelopes and artifacts — there are
+no gates to answer.

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

@@ -0,0 +1,84 @@
+id: implement-fix
+system_prompt: |
+  Fix the issue in the checkout: edit source, add a regression test, and get
+  both passing. Never call ask_operator — decide and proceed.
+
+  Read investigation.md from the prior envelope's artifacts (a run-relative
+  path under the "Factory run workspace" value given in this stage's user
+  prompt) for the root cause, target files, and fix approach. Treat it as the
+  starting point, not gospel — if the real fix differs once you're in the
+  code, take the correct one and say why in fix-report.md.
+
+  1. Write a regression test that fails against the current (buggy) code for
+     the reason described in investigation.md, using the repo's actual test
+     framework and conventions (find an existing test file near the affected
+     code and match its style; do not invent a new test setup pattern).
+     Confirm it fails, and capture that failing output.
+  2. Edit the source to fix the root cause. Keep the change minimal and
+     scoped to this issue — do not refactor, rename, or clean up unrelated
+     code along the way.
+  3. Run the regression test again and confirm it now passes. Then run the
+     broader test suite (or the most relevant scoped slice if a full run is
+     impractical) to check you haven't broken anything else. If something
+     breaks, fix it before moving on — you own this loop end to end; nothing
+     downstream can repair a broken implementation.
+  4. Call write_stage_artifact with path fix-report.md containing: what you
+     changed and why, the regression test's id/path and its before/after
+     output, every command you ran with its result, and anything from
+     investigation.md you deviated from and why.
+  5. Call emit_stage_envelope exactly once. changed_files must match
+     git diff --name-only exactly — no more, no fewer.
+model: openrouter/minimax/minimax-m3:free
+timeout_ms: 7200000
+io:
+  input:
+    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
+  output:
+    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
+verify:
+  - id: fix-report
+    type: artifact
+    path: fix-report.md
+    nonempty: true
+    when:
+      - after
+  - id: checkout-changed
+    type: checkout_changes
+    path_fields:
+      - changed_files
+    when:
+      - after
+gate_kinds: []

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

@@ -0,0 +1,35 @@
+id: oss-quick-fix
+stages:
+  - id: understand-issue
+    entry: true
+    route:
+      - to: implement-fix
+    uses: ./understand-issue.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: implement-fix
+    route:
+      - to: verify-fix
+    uses: ./implement-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: verify-fix
+    route:
+      - to: ship-fix
+    uses: ./verify-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: ship-fix
+    uses: ./ship-fix.yaml
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

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

@@ -0,0 +1,19 @@
+id: oss-quick-fix-template
+goal: >
+  Deliver a verified minimal local fix for <issue URL / short description>,
+  applied as source and test edits in the checkout working tree, plus a pull
+  request opened against your own fork (never the upstream repository).
+context: |
+  Issue: <issue URL>
+  Title: <copy the current issue title>
+  Upstream repo: <owner/repo>
+  Fork (PR target): <your-username>/<repo>
+  Reported behavior: <copy or summarize the concrete failure>
+  Expected behavior: <copy or summarize the acceptance criterion>
+constraints: |
+  Respect the target repository's AGENTS.md / CONTRIBUTING.md and test
+  conventions.
+  publish_repo in the final stage must be exactly the fork named above —
+  never the upstream owner/repo.
+  Keep the change limited to the reported issue and its regression test.
+checkout: /absolute/path/to/checkout