stageflow 0.12.0 → 0.13.0

package/dist/ui/index.html

@@ -13,7 +13,7 @@
     <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Figtree:wght@400;500;600;700&display=swap" />
     <link rel="icon" type="image/svg+xml" href="/stageflow-icon.svg" />
     <title>Stageflow</title>
-    <script type="module" crossorigin src="/assets/index-CXGz4nL7.js"></script>
+    <script type="module" crossorigin src="/assets/index-Yzh42vhf.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-uVHiae8s.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -63,9 +63,12 @@
     "@anthropic-ai/claude-agent-sdk": "^0.3.263",
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-tui": "^0.84.4",
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "better-sqlite3": "^13.0.3",
+    "jiti": "^2.7.0",
+    "pi-mcp-adapter": "^2.32.1",
     "typebox": "^1.3.7",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"

package/skills/stageflow-author/SKILL.md

@@ -35,9 +35,27 @@ Ask until you can name every step, how they sequence, any decision point, and an
 
 ## Map
 
-Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, `model`, and `gate_kinds`.
+Read [`references/catalog-mapping.md`](references/catalog-mapping.md). Apply those rules to the confirmed structure. Read [`references/stage-prompt-template.md`](references/stage-prompt-template.md) for each stage's `system_prompt`, `model`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan `completion` / `recovery` on pipeline entries. When a review can demand changes, include an address-feedback stage before approve/ship.
 
-**Done when** you have a pipeline id, one stage id per step, `needs` / `fork` wiring, and a prompt plan per stage.
+**Done when** you have a pipeline id, one stage id per step, `needs` / `fork` wiring, a prompt plan per stage, and any `completion` / `recovery` / remediation stages the structure requires.
+
+## Anti-patterns
+
+Author these contracts explicitly. They come from long runs that failed after hours of real work.
+
+| Always do | How |
+|---|---|
+| End every attempt on a tool call | Prompt: last call is `emit_stage_envelope`, or `ask_operator` while waiting on HITL. Each clonable instance emits on its own. |
+| Land required files in the attempt artifact dir | Prompt `write_stage_artifact`. Pipeline `completion.checks` with `type: artifact`. `ask_operator` `artifact_backed` references that same path. |
+| Make implement stages change the checkout | Pipeline `checkout_changes` + `path_fields`; stage `payload_schema` with required checkout-relative path arrays. Exploration-only is its own stage or a failure emit. |
+| Hand successors clean envelopes | `summary` / `payload` = outcomes and artifact pointers only. Name required `payload_schema` fields in the prompt. |
+| Give review blockers a place to land | Wire `review → address-feedback → approve/ship`. Put `verdict` / `blocking_findings` (or equivalent) in the review `payload_schema`. |
+| Bind success to the full checklist | If a plan lists N commands, success requires all of them in `commands_run` with exit 0. Cheap checks first; slow suites last or in a verify stage. Size `timeout_ms` to the work. |
+| Use configured models on every sibling | Same configured `model` family after a fork/fan-out unless the human asks otherwise. Reliable model on publish/PR stages. |
+| Finish publish in the accept attempt | After `artifact_backed` accept: side effects (commit/push/PR) → final artifact → emit in the same attempt. Fix emit/schema errors by re-emitting. |
+| Emit full clone assignments | When `clonable: true`, parent success uses `clone_forks` with full envelopes matching `clone_input_schema`. Leave clonable unset when the clone count is unknown. |
+
+Throwaway checkout deliverables (HTML spike, scratch file): prompt builtin `write` at a checkout-relative path, `artifacts: []` on emit, path in `payload`.
 
 ## Locate
 

package/skills/stageflow-author/references/catalog-mapping.md

@@ -28,15 +28,56 @@ Collision handling lives in [`catalog-write-conventions.md`](catalog-write-conve
 
 Default `select` is `one` unless the human says more than one branch can run.
 
-Map linear chains, sibling fan-out, generic fan-in (`needs` array), and single-level `fork`. A runtime clone count is not knowable from a static description — leave `clonable` and `clone_forks` unset. Clone-list joins (one catalog parent, `priorEnvelopes`) are not this shape.
+Map linear chains, sibling fan-out, generic fan-in (`needs` array), and single-level `fork`.
 
 A review, approval, or sign-off step is a gated stage: put `gate_kinds` on that stage file and follow [`stage-prompt-template.md`](stage-prompt-template.md).
 
+## Review then fix then approve
+
+When the human wants a review that can demand changes, then a later approve/ship:
+
+```
+… → review → address-feedback → approve
+```
+
+Do not wire approve/ship as the immediate child of review. Pipelines are forward-only; without an address-feedback stage, blocking findings have nowhere to land. The address-feedback stage is the only post-review editor; the approve stage is the backstop.
+
+## Completion and recovery
+
+Put `completion` / `recovery` on the **pipeline** stage entry (the `uses:` wrapper), not on the stage body. Use when the human needs a hard gate before advance:
+
+| Need | Pipeline wiring |
+|---|---|
+| Required file under the attempt artifact dir | `completion.checks` with `type: artifact`, `path`, usually `nonempty: true` |
+| HITL must complete | `type: gate` with `kind` that appears in the stage's `gate_kinds` |
+| Implement must change the checkout | `type: checkout_changes` with `path_fields` naming required arrays in `payload_schema` |
+| Auto-retry after verification fail | `recovery: { mode: repair, max_attempts: N, retry_safety: idempotent, include_failed_checks: true }` |
+| Side-effecting publish / ship | `recovery: { mode: manual, retry_safety: side_effecting }` |
+
+`completion.mode` is `all`. Check `id` values must be unique within the stage. Wire these for writer stages and final gates; prompts alone do not enforce them.
+
+## Clonable successors
+
+A runtime clone count is not knowable from a vague description — leave `clonable` and `clone_forks` unset and prefer sibling stages or a single review.
+
+When the human explicitly wants N parallel instances of **one** successor catalog id (e.g. several review lenses, several prototype variants):
+
+- On that successor pipeline entry: `clonable: true` and `clone_cap` (integer ≥ 2).
+- That successor must have at least one child (a join / address-feedback / collect stage). It cannot be a DAG leaf.
+- Parent success emit uses `clone_forks` for that successor (not `fork_choice`). Each clone assignment is a full envelope; validate assignments with `clone_input_schema` on the clonable stage body.
+- Join stages that wait on the clonable parent read clone-list `priorEnvelopes`, not `priorEnvelopesByStage`.
+
+`fork` + `fork_choice` picks which **branch stage ids** run. `clone_forks` spawns **N instances** of one successor id.
+
+## Models
+
+Confirm providers before writing. After a fork, give every sibling the same configured `model` unless the human asks for different ones. Prefer a reliable configured model on side-effecting final stages.
+
 ## Worked examples
 
 ### Review loop (linear)
 
-Three sequential steps; the middle one is a sign-off.
+Three sequential steps; the middle one is a sign-off. Reject/revise stays inside the gated `review` stage.
 
 ```yaml
 id: review-loop
@@ -53,6 +94,26 @@ stages:
 
 `review` carries `gate_kinds: [artifact_backed]`. Full set: [`../assets/examples/linear-review/`](../assets/examples/linear-review/).
 
+### Review with separate fix stage
+
+When review can emit blockers and a later stage approves or ships, insert address-feedback between them:
+
+```yaml
+stages:
+  - id: implement
+    uses: ./implement.yaml
+  - id: review
+    uses: ./review.yaml
+    needs: implement
+  - id: address-feedback
+    uses: ./address-feedback.yaml
+    needs: review
+  - id: approve
+    uses: ./approve.yaml
+    needs: address-feedback
+```
+
+Do not make `approve` / `ship` `needs: review` when blockers are expected.
 ### Release gate (fork, select one)
 
 One deciding step, then exactly one successor.

package/skills/stageflow-author/references/stage-prompt-template.md

@@ -1,6 +1,6 @@
 # Stage prompt template
 
-Every external stage file has `id`, `system_prompt`, and `model`. Filename stem matches `id`. Default `model` is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim.
+Every external stage file has `id`, `system_prompt`, and `model`. Filename stem matches `id`. Default `model` is `anthropic/claude-sonnet-4-5`. When the human names a different model, write that string verbatim. Before writing models, confirm at least one provider is `configured` (see the skill Provider gate). Sibling stages after a fork should use the same configured model family unless the human asks otherwise.
 
 ## Base
 
@@ -14,12 +14,48 @@ system_prompt: |
   Write any output this step produces via write_stage_artifact.
 
   When finished, call emit_stage_envelope exactly once with status, summary,
-  artifacts, and a payload the next stage can use.
+  artifacts, and a payload the next stage can use. Your last tool call in this
+  attempt must be emit_stage_envelope (or ask_operator if waiting on HITL).
+  An empty final message is a stage failure.
 model: anthropic/claude-sonnet-4-5
 ```
 
 The prompt has no `ask_operator` line. It ends on the `emit_stage_envelope` instruction. Call `emit_stage_envelope` once per attempt.
 
+When the pipeline entry will carry `completion.checks` with `type: artifact`, add this line after the goal:
+
+```
+Required files must be created with write_stage_artifact. Checkout write/edit
+does not satisfy completion checks.
+```
+
+When the stage must change the project checkout (implement, patch, edit source), add:
+
+```
+Success requires real checkout edits. Put checkout-relative paths in
+payload.changed_files. Do not put stages/.../artifacts paths there. A report
+or map alone is a failure emit, not success.
+```
+
+When the deliverable is throwaway checkout content instead of a stage artifact:
+
+```
+Write the deliverable with builtin write at <checkout-relative path>.
+Set artifacts: [] on emit. Put that path in payload.<field>.
+```
+
+## Summary and payload
+
+Add to every stage (base, gated, or fork):
+
+```
+summary and payload are handed to the next stage verbatim. State outcomes and
+artifact pointers only. Do not repeat this stage's prohibitions in summary —
+downstream will obey them literally.
+```
+
+When `payload_schema` is on the stage file, name the required fields in the prompt so the emit matches.
+
 ## Gated
 
 When the step is a review, approval, or sign-off, add `gate_kinds` and resolve the gate before emit. Match this sequence: `write_stage_artifact` → `ask_operator` → `emit_stage_envelope` on accept.
@@ -32,7 +68,8 @@ system_prompt: |
   <one-line goal>. Get operator acceptance before completing this stage.
 
   1. Write the reviewable output via write_stage_artifact.
-  2. Call ask_operator with kind artifact_backed referencing that artifact path.
+  2. Call ask_operator with kind artifact_backed referencing that artifact path
+     (stage artifact path, not a checkout path).
   3. On reject or change text: revise the artifact and call ask_operator again
      with artifact_backed in this same stage. Do not complete yet.
   4. Call emit_stage_envelope with an advancing success status only after the
@@ -42,6 +79,14 @@ model: anthropic/claude-sonnet-4-5
 
 Use the `gate_kinds` value that matches the human's review: `artifact_backed` for a file to accept, `confirm` for yes/no, `free_text` for an open reply, `multi_question` for a batch. `ask_operator` does not complete the stage.
 
+When the gated stage also publishes or opens a PR after accept, append:
+
+```
+After the operator accepts, immediately finish publish side effects in this
+same attempt (commit, push, open PR as required), write any final artifact,
+then emit. Do not pause after accept. Do not ask_operator for emit/schema errors.
+```
+
 ## Fork
 
 When the pipeline entry has `fork`, the success emit names immediate successors in `fork_choice`. Add this block to the base (or gated) prompt:
@@ -50,6 +95,20 @@ When the pipeline entry has `fork`, the success emit names immediate successors
 On a success emit, include fork_choice naming immediate successor id(s) that
 should run. Name only ids listed as this stage's children. select: one →
 exactly one id. select: subset → one or more of those ids.
+Normalize free_text answers before mapping (trim, lowercase, collapse spaces
+and hyphens). If unmapped, ask_operator again; do not emit.
+```
+
+`fork_choice` on a failure emit is ignored. Leave `clone_forks` unset unless the human explicitly asked for clonable fan-out (see [`catalog-mapping.md`](catalog-mapping.md)).
+
+## Clonable parent
+
+When a successor is `clonable: true`, the parent success emit uses `clone_forks` (not `fork_choice`) for that successor. Add:
+
+```
+On success, include clone_forks covering every clonable successor exactly once.
+Each clone entry is a full envelope with status, summary, artifacts, and payload
+matching that successor's clone_input_schema — not a stub object.
 ```
 
-`fork_choice` on a failure emit is ignored. Leave `clone_forks` unset.
+Clonable child stages use the base (or gated) prompt. Remind them they are one clone among others and must emit independently.

package/skills/stageflow-session-capture/references/catalog-authoring.md

@@ -16,9 +16,12 @@ Every `system_prompt` ends with a mandatory `emit_stage_envelope` footer, for ex
 
 ```
 When finished, call emit_stage_envelope once with status, summary, artifacts,
-and a payload the next stage can use.
+and a payload the next stage can use. Your last tool call in this attempt must
+be emit_stage_envelope. An empty final message is a stage failure.
 ```
 
+Write reviewable or required outputs with `write_stage_artifact`, not checkout `write`/`edit`, unless the step's deliverable is intentionally checkout-only. `summary` is for the next stage — outcomes and artifact pointers only; do not put this stage's prohibitions in the summary.
+
 Omit `gate_kinds`. A human-review checkpoint from the source session stays as prose in the stage approach, not a HITL gate.
 
 Worked example: `assets/example-pipeline/research.yaml` and `assets/example-pipeline/implement.yaml`.