stageflow 0.25.0 → 0.30.0

package/examples/feature-loop/review.yaml

@@ -0,0 +1,146 @@
+id: review
+system_prompt: |
+  Review the entire implementation as one change — every story's edits
+  together, not per-story. Work the way a compound-engineering
+  ce-code-review run would: report-only, persona-quality findings,
+  no checkout edits. Do not commit, push, or open a pull request.
+
+  This is a whole-diff review. coverage.md and the union of implement
+  reports are context; git diff against the feature branch merge base
+  is the code under review. Emit success even when verdict is
+  changes_required — failure only if the review itself cannot be
+  performed.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read coverage.md and inherited artifacts
+  at <Factory run workspace>/<path>. If this attempt includes Feedback
+  Loop Context, that envelope is the address-feedback send-back: review
+  the current checkout plus what that pass claimed to fix, not the
+  original review-report.md as if nothing changed.
+
+  Definition of done — every line must hold before you emit success:
+  - You ran git diff against the merge base (origin/main or the task's
+    base branch) and read every changed file, not hunks alone.
+  - review-report.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+  - Every publication-blocking issue is in blocking_findings with
+    file:line evidence. Describing a blocker only in prose findings
+    while leaving blocking_findings empty is a contract violation.
+  - verdict is pass only when blocking_findings is empty.
+  - The working tree is unchanged by this stage.
+
+  1. Read the task, coverage.md, aligned-plans.md, and every
+     implementation-report.md you can resolve. Run git diff and
+     git diff --name-only against the merge base.
+  2. Review correctness, regressions, tests, security, and whether the
+     landed diff still matches the aligned plans as a whole (cross-story
+     seams, duplicated abstractions, missed acceptance).
+  3. Classify findings. Blocking: correctness, regression, missing
+     required tests, security, or broken acceptance. Suggestions stay
+     out of blocking_findings.
+  4. Call write_stage_artifact with path review-report.md: verdict,
+     answers, findings, evidence, and concrete remediation for each
+     blocker.
+  5. Emit success with a payload matching the schema, including
+     review-report.md and inherited evidence.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  verdict, whether blockers exist, and the artifact pointer. Do not
+  repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - expected_story_ids
+        - implemented_story_ids
+        - missing_story_ids
+        - extra_story_ids
+        - coverage_complete
+        - changed_files
+      properties:
+        expected_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implemented_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        missing_story_ids:
+          type: array
+          items:
+            type: string
+        extra_story_ids:
+          type: array
+          items:
+            type: string
+        coverage_complete:
+          type: boolean
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - verdict
+        - findings
+        - blocking_findings
+        - suggestions
+        - evidence
+        - reviewed_files
+      properties:
+        verdict:
+          type: string
+          enum:
+            - pass
+            - changes_required
+        findings:
+          type: array
+          items:
+            type: string
+        blocking_findings:
+          type: array
+          items:
+            type: string
+        suggestions:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: array
+          items:
+            type: string
+        reviewed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+verify:
+  - id: review-report-declared
+    type: artifact
+    basename: review-report.md
+    when:
+      - emit
+  - id: review-report
+    type: artifact
+    path: review-report.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/feature-loop/verify.yaml

@@ -0,0 +1,106 @@
+id: verify
+system_prompt: |
+  You are the join after implement. Confirm every aligned
+  story was implemented and none were skipped, then hand a coverage
+  ledger to review. Do not edit source, commit, push, or open a pull
+
+  Read each prior implement payload.story_id and changed_files.
+  aligned-plans.md is the expected story set and implementation_order.
+
+  Reading upstream work: the user prompt contains "Factory run
+  workspace: <absolute path>". Read artifacts at <Factory run
+  workspace>/<artifact path>. Also run git diff --name-only in the
+  checkout so the ledger matches the tree, not just envelopes.
+
+  Definition of done — every line must hold before you emit success:
+  - expected_story_ids is the full implementation_order from
+    aligned-plans.md.
+  - implemented_story_ids is every implement payload.story_id.
+  - missing_story_ids is empty. extra_story_ids is empty.
+  - coverage_complete is true only when those sets match and every
+    expected story has a non-empty changed_files list that exists in
+    git diff --name-only.
+  - coverage.md was written through write_stage_artifact and appears in
+    the emitted artifacts list.
+
+  1. Read aligned-plans.md and every implement envelope/report.
+  2. Build the expected vs implemented sets. Union changed_files across
+     implement reports and intersect with git diff --name-only.
+  3. If any story is missing, extra, or claimed files that are not in
+     the checkout diff, write coverage.md describing the gap and emit
+     failure. Do not present partial coverage as success.
+  4. Otherwise write coverage.md with the story matrix, files per
+     story, union diff, and residual risk from implement reports.
+  5. Emit success with a payload matching the schema, including
+     coverage.md and inherited evidence.
+
+  Required files must be created with write_stage_artifact. Checkout
+  write/edit does not satisfy after-phase verify.
+
+  summary and payload are handed to the next stage verbatim. State
+  that coverage is complete, list story_ids, and point at coverage.md.
+  Do not repeat this stage's prohibitions in summary.
+
+  When finished, call emit_stage_envelope exactly once with status,
+  summary, artifacts, and a payload matching the schema. Your last
+  tool call in this attempt must be emit_stage_envelope. An empty
+  final message is a stage failure.
+model: cursor/auto
+timeout_ms: 1800000
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - expected_story_ids
+        - implemented_story_ids
+        - missing_story_ids
+        - extra_story_ids
+        - coverage_complete
+        - changed_files
+      properties:
+        expected_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        implemented_story_ids:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        missing_story_ids:
+          type: array
+          items:
+            type: string
+        extra_story_ids:
+          type: array
+          items:
+            type: string
+        coverage_complete:
+          type: boolean
+        changed_files:
+          type: array
+          minItems: 1
+          items:
+            type: string
+verify:
+  - id: coverage-declared
+    type: artifact
+    basename: coverage.md
+    when:
+      - emit
+  - id: coverage
+    type: artifact
+    path: coverage.md
+    nonempty: true
+    when:
+      - after
+  - id: coverage-payload
+    type: payload_schema
+    when:
+      - after
+gate_kinds: []

package/examples/feedback-loop/README.md

@@ -0,0 +1,72 @@
+# feedback-loop
+
+Source-owned feedback loop: `review` may `continue` or `send_back` to `implement`.
+`submit` is `replay_safe: false` so it is never on a replay route.
+
+Catalog policy is a `{ type: loop }` entry on `route` (not a top-level `feedback_loop:` key). The envelope field is still `feedback_loop`. See [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops) and [`feedback-loop.pipeline.yaml`](../../tests/fixtures/pipelines/feedback-loop.pipeline.yaml).
+
+Domain-neutral — the same wiring works for release notes, research digests, content review, or an SDLC-style plan/implement pass.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed (`npm i -g stageflow`), **or** this repo built (`npm run build`)
+- Provider auth connected (`sf ui` → Settings → Providers, or `sf providers login …`)
+
+## Manual verification (recommended)
+
+Step-by-step scenarios A–D (continue, one send_back, require_continue exhaust, wait_for_human decide):
+
+→ **[VERIFY.md](./VERIFY.md)**
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+sf run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/feedback-loop.task.yaml
+```
+
+Wait-for-human policy (`max_replays: 1`):
+
+```bash
+sf run \
+  --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-wait-human.task.yaml
+```
+
+Optional console (any subdirectory):
+
+```bash
+cd examples/feedback-loop && sf ui
+```
+
+### From the Stageflow repo (no global install)
+
+```bash
+npm run build
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/feedback-loop.task.yaml
+```
+
+## Layout
+
+```
+examples/feedback-loop/
+  VERIFY.md                          # manual scenarios A–D
+  feedback-loop.pipeline.yaml        # require_continue, max_replays 2
+  feedback-loop-wait-human.pipeline.yaml
+  feedback-loop.task.yaml
+  continue-only / send-back-once / exhaust-*.task.yaml
+  plan.yaml | implement.yaml | review.yaml | submit.yaml
+```
+
+## References
+
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)
+- [Envelopes — Feedback loops](../../docs/envelopes.md#feedback-loops)
+- [CLI — feedback-decide](../../docs/cli-reference.md#sf-runs-feedback-decide)

package/examples/feedback-loop/VERIFY.md

@@ -0,0 +1,208 @@
+# Feedback-loop manual verification
+
+Simple runs to exercise the feedback-loop work from this repo. Uses a real provider (not FakeAgent).
+
+## Setup
+
+```bash
+cd /path/to/software-factory
+npm i
+npm run build
+# Provider auth once (example stages use omniroute/auto)
+# Connect via: npm run dev -- ui  → Settings → Providers
+```
+
+Use `npm run dev -- …` as `sf` from this worktree. Run state lives in `<repo>/.stageflow/`.
+
+Optional console:
+
+```bash
+npm run dev -- ui
+```
+
+If `sf ui` is up on `:3847`, mutating CLI (`runs feedback-decide`) is refused — decide in the UI panel, or stop the host and use CLI.
+
+Validate once:
+
+```bash
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml --strict
+npm run dev -- validate --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml --strict
+```
+
+---
+
+## Scenario A — Continue only (happy path)
+
+**Expect:** `plan → implement → review → submit`, no replay.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/continue-only.task.yaml \
+  --json > /tmp/fb-a.json
+```
+
+**Pass:** exit `0`; all four stages `succeeded`; `submit` ran once.
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-a.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  stages: [.stages[] | {id: .stage_id, status}],
+  active: .active_feedback_loop,
+  loops: [.feedback_loops[]?.loop.state]
+}'
+```
+
+**Fail:** any `send_back`, or `submit` never runs.
+
+---
+
+## Scenario B — One send_back, then continue
+
+**Expect:** review sends back to `implement` once; replay includes Feedback Loop Context; then continue → submit.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/send-back-once.task.yaml \
+  --json > /tmp/fb-b.json
+```
+
+**Pass:**
+
+- Stage path roughly `plan → implement → review → implement → review → submit`
+- One replay in history; loop ends `continued`
+- On the replayed stages, the agent prompt shows a **Feedback Loop Context** block
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-b.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  stages: [.stages[] | {id: .stage_id, status}],
+  replays: [.feedback_loops[0].replays[] | {
+    n: .replay.replay_number,
+    target: .replay.target_stage_id,
+    status: .replay.status
+  }],
+  loop: .feedback_loops[0].loop.state
+}'
+```
+
+UI: Feedback Loop panel shows budget / route / replay timeline.
+
+**Fail:** submit before continue; no replay recorded; no Feedback Loop Context on replay.
+
+---
+
+## Scenario C — Exhaust `require_continue` (over-limit send_back fails)
+
+Pipeline: `max_replays: 2`, `on_max_replays: require_continue`.
+
+**Expect:** two accepted send_backs, third rejected; `submit` never succeeds.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-require-continue.task.yaml \
+  --json > /tmp/fb-c.json
+```
+
+**Pass:** run failed; ~2 replays; failure mentions `max_replays` / `require_continue`; `submit` not succeeded.
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-c.json)
+npm run dev -- runs show --run "$RUN" --json | jq '{
+  status,
+  failed_stage_id,
+  failed_reason,
+  replay_count: (.feedback_loops[0].replays | length),
+  submit: [.stages[] | select(.stage_id=="submit") | .status]
+}'
+```
+
+**Fail:** third send_back accepted; run succeeds; or parks for human (wrong policy).
+
+---
+
+## Scenario D — Exhaust `wait_for_human`, then decide
+
+Pipeline: `feedback-loop-wait-human.pipeline.yaml` (`max_replays: 1`, `on_max_replays: wait_for_human`).
+
+**Pairing:** You **must** use `feedback-loop-wait-human.pipeline.yaml` with `exhaust-wait-human.task.yaml`. The default `feedback-loop.pipeline.yaml` uses `require_continue` — wrong pipeline means **no human ask** (run fails on over-limit send_back instead of parking). Every review success until park must `send_back` (never `continue`).
+
+**Expect:** second send_back parks the run; you choose extend / continue / abandon.
+
+Prefer **no** `sf ui` on `:3847` if you will use CLI decide.
+
+```bash
+npm run dev -- run \
+  --pipeline examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml \
+  --task examples/feedback-loop/exhaust-wait-human.task.yaml \
+  --json > /tmp/fb-d.json
+# Exit 2 when parked waiting is normal
+```
+
+Inspect the park:
+
+```bash
+RUN=$(jq -r .runId /tmp/fb-d.json)
+npm run dev -- runs waiting --run "$RUN" --json
+npm run dev -- runs show --run "$RUN" --json | jq '.active_feedback_loop | {
+  state, policy, deferred_send_back
+}'
+```
+
+Expect `waiting_kind: "feedback_loop_decision"`, `state: "waiting_for_human"`, deferred target `implement`.
+
+Pick **one** decision (host down for CLI):
+
+```bash
+# Extra replay budget, then agent should continue later
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision extend --json
+
+# Or release downstream without another replay
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision continue --json
+
+# Or fail the run
+npm run dev -- runs feedback-decide --run "$RUN" --stage review --decision abandon --reason "stop" --json
+```
+
+With `sf ui` instead: open the run → FeedbackDecidePanel → Extend / Continue / Abandon.
+
+After decide, wait for terminal if needed:
+
+```bash
+npm run dev -- runs wait --run "$RUN" --until terminal --timeout-ms 240000 --json
+```
+
+**Pass:**
+
+| Decision | Expect |
+|----------|--------|
+| `extend` | `effect: extended`; another implement→review; then continue → submit; `max_replays` bumped by 1 |
+| `continue` | `effect: continued`; submit runs; no further replay |
+| `abandon` | run `failed`; submit never runs |
+
+**Fail:** second send_back rejected instead of parking; decide refused while host is still up.
+
+---
+
+## Quick matrix
+
+| Scenario | Pipeline | Task | Cost note |
+|----------|----------|------|-----------|
+| A Continue | `feedback-loop.pipeline.yaml` | `continue-only.task.yaml` | ~4 stages |
+| B One send_back | `feedback-loop.pipeline.yaml` | `send-back-once.task.yaml` | ~6 stage runs |
+| C require_continue exhaust | `feedback-loop.pipeline.yaml` | `exhaust-require-continue.task.yaml` | ~7+ stage runs, expects failure |
+| D wait_for_human | `feedback-loop-wait-human.pipeline.yaml` | `exhaust-wait-human.task.yaml` | parks; then decide |
+
+Clone-chain Loop from Join is covered by fixture
+[`tests/fixtures/pipelines/clone-chain-loop-from-join.pipeline.yaml`](../../tests/fixtures/pipelines/clone-chain-loop-from-join.pipeline.yaml),
+not this walkthrough.
+
+## References
+
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)
+- [CLI — feedback-decide](../../docs/cli-reference.md#sf-runs-feedback-decide)
+- [Envelopes — Feedback loops](../../docs/envelopes.md#feedback-loops)

package/examples/feedback-loop/continue-only.task.yaml

@@ -0,0 +1,4 @@
+id: feedback-loop-continue-only
+goal: Draft a short brief and submit it after review continues on the first pass
+context: Verification scenario — review must emit continue (no send_back)
+constraints: Docs only. review must emit feedback_loop.action continue on the first success.

package/examples/feedback-loop/exhaust-require-continue.task.yaml

@@ -0,0 +1,6 @@
+id: feedback-loop-exhaust-require-continue
+goal: Keep sending work back from review until the loop rejects further send_back
+context: Verification scenario — force require_continue max_replays exhaustion
+constraints: |
+  Docs only. Every successful review must emit feedback_loop send_back target implement.
+  Never emit continue. Expect the third send_back to fail after max_replays 2.

package/examples/feedback-loop/exhaust-wait-human.task.yaml

@@ -0,0 +1,11 @@
+id: feedback-loop-exhaust-wait-human
+goal: Send work back twice so the loop parks for a human decision
+context: Verification scenario — wait_for_human after max_replays 1
+constraints: |
+  MUST pair with pipeline feedback-loop-wait-human.pipeline.yaml
+  (on_max_replays: wait_for_human, max_replays: 1). Do NOT use
+  feedback-loop.pipeline.yaml (require_continue) — that never asks a human.
+  Docs only. Every review success until the run parks MUST emit send_back
+  target implement — never emit continue. First review: send_back implement;
+  after replay, second review: send_back implement again so the loop parks
+  for feedback-decide.

package/examples/feedback-loop/feedback-loop-wait-human.pipeline.yaml

@@ -0,0 +1,23 @@
+id: feedback-loop-wait-human
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    uses: ./plan.yaml
+  - id: implement
+    route:
+      - to: review
+    uses: ./implement.yaml
+  - id: review
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 1
+        on_max_replays: wait_for_human
+        replay_session: resume
+    uses: ./review.yaml
+  - id: submit
+    uses: ./submit.yaml
+    replay_safe: false

package/examples/feedback-loop/feedback-loop.pipeline.yaml

@@ -0,0 +1,23 @@
+id: feedback-loop
+stages:
+  - id: plan
+    entry: true
+    route:
+      - to: implement
+    uses: ./plan.yaml
+  - id: implement
+    route:
+      - to: review
+    uses: ./implement.yaml
+  - id: review
+    route:
+      - to: submit
+      - type: loop
+        to: implement
+        max_replays: 2
+        on_max_replays: require_continue
+        replay_session: resume
+    uses: ./review.yaml
+  - id: submit
+    uses: ./submit.yaml
+    replay_safe: false

package/examples/feedback-loop/feedback-loop.task.yaml

@@ -0,0 +1,4 @@
+id: feedback-loop
+goal: Draft a short brief, revise it until a review stage continues, then submit
+context: Domain-neutral feedback-loop walkthrough — plan → implement → review → submit
+constraints: Docs only; no implementation code. Prefer one send_back then continue.

package/examples/feedback-loop/implement.yaml

@@ -0,0 +1,14 @@
+id: implement
+system_prompt: |
+  Produce the work described by the upstream plan envelope.
+  Keep the deliverable short (a brief outline or draft).
+  Emit a success envelope summarizing what you produced.
+  On a feedback replay, read Feedback Loop Context and address the review feedback.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/plan.yaml

@@ -0,0 +1,14 @@
+id: plan
+system_prompt: |
+  Create a short plan for the task goal.
+  List the sections you will produce and any open questions.
+  Emit a success envelope with a clear summary when done.
+  On a feedback replay, read Feedback Loop Context and revise the plan to address the send-back.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/review.yaml

@@ -0,0 +1,15 @@
+id: review
+system_prompt: |
+  Review the upstream work against the task goal.
+  On success you MUST include feedback_loop in emit_stage_envelope:
+  - {"action":"continue"} when the work is good enough to submit
+  - {"action":"send_back","target":"implement"} when another pass is needed
+  Prefer at most one send_back in this walkthrough, then continue.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/feedback-loop/send-back-once.task.yaml

@@ -0,0 +1,6 @@
+id: feedback-loop-send-back-once
+goal: Draft a short brief, send it back once from review, then continue and submit
+context: Verification scenario — exactly one send_back to implement, then continue
+constraints: |
+  Docs only. On the first review success, emit feedback_loop send_back target implement.
+  On the second review success, emit feedback_loop continue. Do not send_back twice.

package/examples/feedback-loop/submit.yaml

@@ -0,0 +1,12 @@
+id: submit
+system_prompt: |
+  Submit the approved work. Summarize the final brief in the envelope.
+  This stage is replay_safe: false — it runs only after review continues.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object