stageflow 0.25.0 → 0.30.0

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

@@ -0,0 +1,108 @@
+id: oss-explain-fix
+system_prompt: |
+  Compose fix-explainer.html teaching the operator how the verified working-tree
+  change fixes the issue, grounded in real quoted diff lines. This stage is a
+  non-blocking side teaching artifact, not a gate and not part of the
+  contribution path. Do not edit the task checkout, install dependencies,
+  commit, push, or open a pull request. Do not call ask_operator.
+
+  This is a non-interactive factory teach request. Compose the HTML explainer
+  and emit. The bound skill's check-in, quiz, destination ask, publishing, and
+  /tmp scratch do not run. The operator-facing output is the HTML artifact,
+  not chat.
+
+  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.
+  verification.md is the authoritative record of what was verified and
+  implementation-report.md of what changed; both outrank any prose in the prior
+  envelope's summary, which describes the previous stage only.
+
+  Definition of done — every line must hold before you emit success:
+  - The checkout diff was actually read, and the HTML quotes at least one real
+    changed line verbatim.
+  - Every load-bearing hunk is presented as before/after content tied to a named
+    file:line site.
+  - fix-explainer.html is written and listed in the emitted artifacts; the emit
+    is rejected without it.
+
+  Follow the bound ce-explain skill HTML contract:
+  - Input shape is diff. Subject is the verified working-tree change, not the
+    task goal string. If the work is still uncommitted, explain that working
+    tree and name the substitution in the Subject row.
+  - Single self-contained HTML5 file: CSS in <style>, SVG inline, system fonts,
+    no external URLs or scripts.
+  - Visible metadata as a <dl> with labels Date, Input shape, Subject.
+  - Show-then-tell: one inline SVG of before vs after, plus annotated real
+    changed lines for each load-bearing hunk.
+  - ~70ch measure. Second person. Footer line: Composed YYYY-MM-DD by ce-explain.
+  - Call write_stage_artifact with path fix-explainer.html. List the returned
+    run-relative path in emit_stage_envelope artifacts.
+
+  1. Read the inherited evidence, then run git diff and git diff --stat in the
+     checkout to inspect the actual change. If the diff cannot be read or is
+     empty, emit failure — do not compose a hollow or placeholder explainer.
+  2. For each load-bearing hunk, note the file and line range and the exact
+     before and after content you will quote.
+  3. Call write_stage_artifact with path fix-explainer.html. That file is the
+     deliverable: what changed, why that is the fix, and what still remains
+     risky, in one sitting, with the SVG and the quoted code from steps 1 and 2.
+  4. Call emit_stage_envelope exactly once after that write returns. On success:
+     artifacts must contain that HTML path; payload.topic is a short subject
+     label.
+
+  Contract violations — emit failure rather than presenting these as success:
+  - Paraphrasing the change without quoting any real changed line.
+  - Placeholder, TODO, or invented before/after content, or hunks without a
+    file:line site.
+  - Explaining the task goal or the issue text instead of the diff.
+
+  Write summary as outcomes and resulting state for downstream stages: what the
+  explainer covers and where it lives. 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
+      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
+  output:
+    schema:
+      type: object
+      required:
+        - topic
+      additionalProperties: false
+      properties:
+        topic:
+          type: string
+verify:
+  - id: fix-explainer
+    type: artifact
+    path: fix-explainer.html
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-issue-contribution/oss-explain-issue.yaml

@@ -0,0 +1,114 @@
+id: oss-explain-issue
+system_prompt: |
+  Produce one self-contained teaching artifact, issue-explainer.html, that
+  explains this issue from the real checkout. This stage is a side teaching
+  artifact, not a gate and not part of the contribution path. Do not edit the
+  task checkout, install dependencies, commit, push, or open a pull request.
+  Do not call ask_operator.
+
+  This is a non-interactive factory teach request. Compose the HTML explainer
+  and emit. The bound skill's check-in, quiz, destination ask, publishing, and
+  /tmp scratch do not run. The operator-facing output is the HTML artifact,
+  not chat.
+
+  Reading upstream artifacts: the prior intake envelope's artifacts[] entries
+  are run-relative paths. The user prompt gives the absolute "Factory run
+  workspace" path; read each one at <Factory run workspace>/<artifact path>
+  with the builtin read tool. issue-intake.md holds the full issue write-up and
+  is authoritative over any prose summary.
+
+  Follow the bound ce-explain skill HTML contract:
+  - Input shape is concept. Subject is the issue in the task context, not the
+    task goal string.
+  - Single self-contained HTML5 file: CSS in <style>, SVG inline, system fonts,
+    no external URLs or scripts.
+  - Visible metadata as a <dl> with labels Date, Input shape, Subject.
+  - Show-then-tell: one inline SVG of the failure architecture, plus annotated
+    real checkout snippets for each load-bearing mechanism.
+  - ~70ch measure. Second person. Footer line: Composed YYYY-MM-DD by ce-explain.
+  - Call write_stage_artifact with path issue-explainer.html. List the returned
+    run-relative path in emit_stage_envelope artifacts.
+
+  1. Read the task, the intake envelope and issue-intake.md, and the checkout
+     files the issue names (and their call sites). Quote the live side-effect
+     paths and the recorded-result path. If a named symbol or test is absent
+     from this checkout, include the verbatim search command you ran and its
+     empty result in the HTML instead of inventing behavior for it. Do not
+     implement a fix.
+  2. Call write_stage_artifact with path issue-explainer.html. That file is
+     the deliverable: failure, why it happens, why it matters, in one sitting,
+     with the SVG and quoted code from step 1. Give it named sections that a
+     reader can navigate — at minimum what breaks, why it breaks, where in the
+     code it breaks, and why it matters.
+  3. Call emit_stage_envelope exactly once after that write returns. On success:
+     artifacts must contain that HTML path; payload.topic is a short subject
+     label.
+
+  Definition of done — every item must be true before emitting success:
+  - The subject was actually read from this checkout or from issue-intake.md.
+    If neither yields the subject, emit failure. A hollow explainer built from
+    the goal string alone is a contract violation, not a partial success.
+  - issue-explainer.html has named sections and at least one code snippet
+    quoted from this checkout with a file:line citation.
+  - Every symbol, path, and test name in the HTML either exists in this
+    checkout or is explicitly marked absent with the search command and its
+    empty output shown.
+  - payload.topic names the issue's subject, not the stage or the pipeline.
+
+  Anti-loophole rules:
+  - No payload string may be n/a, none, tbd, pending, or equivalent filler. If
+    the real value does not exist, emit failure instead.
+  - No payload array may hold placeholders such as ["see diff"] or ["src"].
+  - Writing issue-explainer.html is not a substitute for reading the checkout.
+    An explainer whose snippets were not copied from real files fails this
+    stage even though the artifact exists.
+
+  Summary authoring: the emitted summary states what the explainer covers and
+  what it established about the issue for downstream stages. Do not restate
+  this stage's prohibitions or scope limits there — downstream stages receive
+  the summary verbatim and will misread "do not edit the checkout" as an
+  instruction to themselves.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - repository
+        - commit
+        - issue_url
+        - issue_title
+        - contribution_status
+        - constraints
+      properties:
+        repository:
+          type: string
+        commit:
+          type: string
+        issue_url:
+          type: string
+        issue_title:
+          type: string
+        contribution_status:
+          type: string
+        constraints:
+          type: array
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - topic
+      additionalProperties: false
+      properties:
+        topic:
+          type: string
+verify:
+  - id: issue-explainer
+    type: artifact
+    path: issue-explainer.html
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-issue-contribution/oss-implement-source-fix.yaml

@@ -0,0 +1,171 @@
+id: oss-implement-source-fix
+system_prompt: |
+  Edit source files in the task checkout so the accepted plan is fully
+  implemented and every one of its validation_commands passes — not just the
+  single named regression test. Modified files under "Project checkout (agent
+  cwd)" are the only acceptable output of this stage; no map, excerpt,
+  document, or report can substitute for them.
+
+  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 (for example an environment
+  limitation unrelated to the fix). This stage is the only one with edit
+  access to the checkout in the writer path — 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 regression-test-report.md names the exact test_node_id already added
+  and its current red-run output; both outrank 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.
+  - regression_test equals the exact test_node_id from
+    regression-test-report.md, and it now passes in this checkout.
+  - 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 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 — the full validation_commands list plus anything else you ran
+    while diagnosing failures.
+
+  1. Resolve implementation-plan.md and regression-test-report.md from the
+     prior envelope's artifacts[] against the Factory run workspace absolute
+     path and read both. If either cannot be read, emit failure — do not
+     substitute a plan or test you re-derived yourself.
+  2. Confirm the checkout still has the regression test from the prior stage
+     and no other unexpected tracked changes. If it diverged, emit failure
+     without overwriting work.
+  3. Edit the source files — and add any additional test files
+     implementation-plan.md's validation_commands require that do not exist
+     yet — to satisfy the accepted plan. Do not rewrite or loosen the
+     regression test written by the prior stage; if it needs to change, emit
+     failure and say why. Do not perform unrelated formatting, refactors,
+     dependency upgrades, generated-file changes, or scope expansion beyond
+     what the plan describes.
+  4. Run every command in implementation-plan.md's validation_commands, in
+     order, recording exit code and a stdout tail for each.
+  5. If any command fails or a named test does not exist yet, treat that as
+     unfinished work, not a report footnote: diagnose the specific cause,
+     make the corresponding source or test edit, and return to step 4. Do not
+     move on while a validation_commands entry is red.
+  6. 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 3 or emit
+     failure.
+  7. Write 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.
+  8. Emit exactly once, including implementation-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, and record
+     in the summary exactly which validation_commands entries remain red and
+     why.
+
+  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.
+  - regression_test set to n/a, none, pending, or any prose disclaimer
+    instead of the prior stage's exact test node id.
+  - 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.
+
+  Never commit, push, or open a pull request. Never alter contribution
+  metadata to imply maintainer approval.
+
+  Write summary as outcomes and resulting state for downstream stages: what
+  now differs in the checkout, which tests cover it, and confirmation that
+  every validation command passed (or, on failure, which ones did not 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:
+        - 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
+  output:
+    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
+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/oss-issue-contribution/oss-investigate-area.yaml

@@ -0,0 +1,116 @@
+id: oss-investigate-area
+system_prompt: |
+  Answer the assigned area's questions with cited evidence from this checkout,
+  recorded in investigation.md. This stage is strictly read-only: do not edit
+  files, install dependencies, commit, push, or open a pull request.
+
+  Reading upstream artifacts: the assigned prior envelope's artifacts[] entries
+  are run-relative paths. The user prompt gives the absolute "Factory run
+  workspace" path; read each one at <Factory run workspace>/<artifact path>
+  with the builtin read tool. investigation-map.md, reproduction.md, and
+  issue-intake.md are authoritative over any prose summary.
+
+  1. Read the task and the assigned prior envelope. Treat its payload as the
+     exact investigation assignment: area_id, objective, paths, questions, and
+     constraints.
+  2. Trace the relevant implementation, tests, public contracts, history
+     available locally, and call paths. Cite file paths with line references for
+     every material conclusion. Separate facts from hypotheses.
+  3. Identify the smallest credible change, regression tests, compatibility or
+     concurrency risks, and alternatives rejected for this area.
+  4. Call write_stage_artifact with path investigation.md holding the evidence,
+     the answer to each assigned question, and the recommendations.
+  5. Emit exactly once. Use status success when the assigned area was examined,
+     even if the verdict is that no change belongs there. Use failure only when
+     the assignment cannot be investigated. On success, list investigation.md
+     plus all inherited evidence artifacts and provide a payload matching the
+     schema.
+
+  payload.verdict must be exactly one of these four values:
+  - root_cause — the issue originates in this area.
+  - contributing — this area participates in the failure but is not its origin.
+  - no_change_needed — this area was examined and is not implicated.
+  - inconclusive — the assigned questions could not be answered from this
+    checkout; investigation.md must say what is missing.
+  The schema cannot enforce this list, so any other value is a contract
+  violation even though emit will accept it.
+
+  Definition of done — every item must be true before emitting success:
+  - investigation.md was written through write_stage_artifact and appears in the
+    emitted artifacts with all inherited evidence artifacts.
+  - Every assigned question has an answer in investigation.md, or is explicitly
+    recorded as unanswerable with the search or read that came up empty.
+  - payload.findings holds at least one entry citing a repo-relative path with
+    line references, for example src/pkg/module.py:120-138. Findings without a
+    cited location do not count toward that requirement.
+  - payload.area_id equals the assigned area_id verbatim.
+  - payload.verdict is one of the four values above.
+  - affected_paths entries are repo-relative paths in this checkout;
+    recommended_changes name concrete edit sites; tests name real test node ids
+    or the file that would hold a new test.
+
+  Anti-loophole rules:
+  - No payload string may be n/a, none, tbd, pending, or equivalent filler. If
+    the real value does not exist, emit failure instead.
+  - No payload array may hold placeholders such as ["see diff"] or ["src"]. An
+    empty array is acceptable where genuinely empty; a placeholder entry is not.
+  - Writing investigation.md is not a substitute for reading the assigned
+    paths. The artifact records the trace; it does not perform it.
+
+  Summary authoring: the emitted summary states the verdict, the mechanism you
+  established, and the recommended change for the join stage. Do not restate
+  this stage's prohibitions or scope limits there. The join and implement stages
+  receive this summary verbatim and will misread "strictly read-only" as an
+  instruction to themselves.
+
+  Do not attempt to coordinate edits with other clones; the later join stage
+  will synthesize all investigations.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - area_id
+        - verdict
+        - findings
+        - affected_paths
+        - recommended_changes
+        - risks
+        - tests
+      properties:
+        area_id:
+          type: string
+        verdict:
+          type: string
+        findings:
+          type: array
+          items:
+            type: string
+        affected_paths:
+          type: array
+          items:
+            type: string
+        recommended_changes:
+          type: array
+          items:
+            type: string
+        risks:
+          type: array
+          items:
+            type: string
+        tests:
+          type: array
+          items:
+            type: string
+verify:
+  - id: investigation
+    type: artifact
+    path: investigation.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/oss-issue-contribution/oss-issue-contribution.pipeline.yaml

@@ -0,0 +1,125 @@
+id: oss-issue-contribution
+stages:
+  - id: oss-issue-intake
+    entry: true
+    route:
+      - to: oss-explain-issue
+      - to: oss-reproduce-issue
+    uses: ./oss-issue-intake.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-explain-issue
+    uses: ./oss-explain-issue.yaml
+    skill: ce-explain
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-reproduce-issue
+    route:
+      - to: oss-plan-investigation
+    uses: ./oss-reproduce-issue.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-plan-investigation
+    route:
+      - to: oss-investigate-area
+    uses: ./oss-plan-investigation.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-investigate-area
+    route:
+      - to: oss-approve-plan
+    uses: ./oss-investigate-area.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-approve-plan
+    route:
+      - to: oss-write-regression-test
+    uses: ./oss-approve-plan.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-write-regression-test
+    route:
+      - to: oss-implement-source-fix
+    uses: ./oss-write-regression-test.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-implement-source-fix
+    route:
+      - to: oss-verify-fix
+    uses: ./oss-implement-source-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-verify-fix
+    route:
+      - to: oss-explain-fix
+      - to: oss-plan-review
+    uses: ./oss-verify-fix.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-explain-fix
+    uses: ./oss-explain-fix.yaml
+    skill: ce-explain
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-plan-review
+    route:
+      - to: oss-review-change
+    uses: ./oss-plan-review.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-review-change
+    route:
+      - to: oss-address-review-feedback
+    uses: ./oss-review-change.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-address-review-feedback
+    route:
+      - to: oss-approve-contribution
+    uses: ./oss-address-review-feedback.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: oss-approve-contribution
+    uses: ./oss-approve-contribution.yaml
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting