stageflow 0.25.0 → 0.27.0

package/examples/compliance-review-demo/run-compliance-check.yaml

@@ -0,0 +1,96 @@
+id: run-compliance-check
+system_prompt: |
+  Read the four public-access-block field values, bucket, and check_id from
+  the prior stage's payload.
+
+  Apply the rule for bucket-level public access block (the same rule
+  Prowler's SOC2-labeled AWS S3 check uses, applied here to whichever
+  cloud the prior stage actually polled): the check passes only if
+  block_public_acls, ignore_public_acls, block_public_policy, and
+  restrict_public_buckets are all true. If any field is false, the check
+  fails; name which field(s) failed in failed_fields. Use an empty list
+  when nothing failed.
+
+  Write the verdict via write_stage_artifact (for example verdict.md),
+  including the field values and which failed, if any.
+
+  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 finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: everything carried
+  forward from the prior stage, plus verdict ("PASS" or "FAIL"), resource
+  (the bucket name), and failed_fields. Your last tool call in this attempt
+  must be emit_stage_envelope. An empty final message is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+  output:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string

package/examples/compliance-review-demo/store-evidence.yaml

@@ -0,0 +1,143 @@
+id: store-evidence
+system_prompt: |
+  Append one row to the checkout-relative evidence log at
+  examples/compliance-review-demo/data/evidence-log.json.
+
+  Read that file with the Read tool if it exists and parse it as a JSON
+  array; if it does not exist yet, start from an empty array. Append a new
+  object with: timestamp (ISO 8601, now), check_id, resource, control_id,
+  verdict, reviewed, auto_approved, reviewer (use JSON null in this file
+  when reviewer is "") — all from the prior stage's payload. Write the full
+  updated array back to that same path with the checkout write/edit tool,
+  pretty-printed.
+
+  Success requires real checkout edits. Put
+  ["examples/compliance-review-demo/data/evidence-log.json"] in
+  payload.changed_files. Do not put stages/.../artifacts paths there. A
+  report or map alone is a failure emit, not success.
+
+  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 finished, call emit_stage_envelope exactly once with status, summary,
+  artifacts, and a payload matching io.output.schema: everything carried
+  forward from the prior stage, plus changed_files naming the evidence log
+  path. Your last tool call in this attempt must be emit_stage_envelope. An
+  empty final message is a stage failure.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+        - control_id
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string
+        control_id:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - bucket
+        - check_id
+        - scenario
+        - source
+        - block_public_acls
+        - ignore_public_acls
+        - block_public_policy
+        - restrict_public_buckets
+        - verdict
+        - resource
+        - failed_fields
+        - reviewed
+        - auto_approved
+        - reviewer
+        - control_id
+        - changed_files
+      properties:
+        bucket:
+          type: string
+        check_id:
+          type: string
+        scenario:
+          type: string
+        source:
+          type: string
+        block_public_acls:
+          type: boolean
+        ignore_public_acls:
+          type: boolean
+        block_public_policy:
+          type: boolean
+        restrict_public_buckets:
+          type: boolean
+        verdict:
+          type: string
+        resource:
+          type: string
+        failed_fields:
+          type: array
+          items:
+            type: string
+        reviewed:
+          type: boolean
+        auto_approved:
+          type: boolean
+        reviewer:
+          type: string
+        control_id:
+          type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+verify:
+  - id: evidence-log-written
+    type: checkout_changes
+    path_fields: [changed_files]
+    when: [after]

package/examples/conditional-fork/README.md

@@ -0,0 +1,89 @@
+# conditional-fork
+
+Operator HITL, then exclusive Route `if`. The `decide` stage asks for **branch-a** or **branch-b**, emits that value on `payload.branch`, and listed successors stay on the DAG. After success, each `if` runs against that payload: the matching arm runs; the other is skipped. The completing agent does not pick YAML successors.
+
+See [YAML catalog — Route wiring](../../docs/yaml-catalog.md#route) (Route `if`). `if.field` must be a required output property — optional fields cannot be used in `if`.
+
+## 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 …`)
+- Operator console for the gate: `sf ui` (default `http://127.0.0.1:3847`)
+
+## Manual test
+
+Commands run from the **repository git root**. Run state lives in `<repo>/.stageflow` even if you start `sf ui` from a subdirectory.
+
+### Terminal 1 — operator console
+
+```bash
+cd examples/conditional-fork
+sf ui
+```
+
+### Terminal 2 — validate and run (repo root)
+
+```bash
+sf validate --pipeline examples/conditional-fork/fork-demo.pipeline.yaml --strict
+sf run \
+  --pipeline examples/conditional-fork/fork-demo.pipeline.yaml \
+  --task examples/conditional-fork/fork-demo.task.yaml
+```
+
+### From the Stageflow repo (no global install)
+
+```bash
+npm run build
+npm run dev -- validate --pipeline examples/conditional-fork/fork-demo.pipeline.yaml --strict
+npm run dev -- run \
+  --pipeline examples/conditional-fork/fork-demo.pipeline.yaml \
+  --task examples/conditional-fork/fork-demo.task.yaml
+```
+
+### At the HITL gate
+
+When `decide` blocks, open the run in the console and answer the free-text prompt with exactly:
+
+- `branch-a`, or
+- `branch-b`
+
+Exit code `2` means waiting on operator input. See [docs/hitl.md](../../docs/hitl.md).
+
+### What to verify in the UI
+
+After you answer:
+
+1. The chosen branch stage (`branch-a` or `branch-b`) reaches **succeeded**
+2. The other branch is **skipped**
+3. The run overall **succeeded**
+
+### Re-test the other branch
+
+Start a **new** run and answer the opposite id at the gate.
+
+## How it works
+
+`decide` is `entry: true` with two `route` targets, each gated by `if` (`field: branch`, `op: eq`). After the operator answers, the agent emits `payload: { "branch": "branch-a" }` or `{ "branch": "branch-b" }`. Stageflow evaluates those predicates against the success payload: the matching successor runs; the miss is skipped. Both `to:` stay on the DAG.
+
+`io.output.schema` requires `branch` as a string so `if.field: branch` is valid. Branch stage `io.input` is an empty object (a subset of decide output).
+
+Validate may warn `pipeline.route_all_gated` because every forward `to:` on `decide` has `if`. That warning keeps `ok: true`; `--strict` does not promote it.
+
+## Layout
+
+```
+examples/conditional-fork/
+  fork-demo.pipeline.yaml
+  fork-demo.task.yaml
+  decide.yaml
+  branch-a.yaml
+  branch-b.yaml
+```
+
+## References
+
+- [YAML catalog — Route wiring](../../docs/yaml-catalog.md#route)
+- [YAML catalog — Upgrading older catalogs](../../docs/yaml-catalog.md#upgrading-older-catalogs)
+- [HITL](../../docs/hitl.md)
+- Fixtures: [`route-if-eq.pipeline.yaml`](../../tests/fixtures/pipelines/route-if-eq.pipeline.yaml)
+- Related walkthrough: [`../route-if-tour/`](../route-if-tour/)

package/examples/conditional-fork/branch-a.yaml

@@ -0,0 +1,13 @@
+id: branch-a
+system_prompt: |
+  You are branch-a. Call emit_stage_envelope exactly once with status success,
+  a short summary that acknowledges branch-a ran, and artifacts []. Do not call
+  ask_operator.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/conditional-fork/branch-b.yaml

@@ -0,0 +1,13 @@
+id: branch-b
+system_prompt: |
+  You are branch-b. Call emit_stage_envelope exactly once with status success,
+  a short summary that acknowledges branch-b ran, and artifacts []. Do not call
+  ask_operator.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/conditional-fork/decide.yaml

@@ -0,0 +1,35 @@
+id: decide
+gate_kinds:
+  - free_text
+system_prompt: |
+  You are the deciding stage for exclusive Route if branching. The operator
+  chooses which branch runs. Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask which branch to take. Tell the
+     operator to reply with exactly one of: branch-a or branch-b.
+  2. Wait for the operator answer. Do not call emit_stage_envelope before you
+     have that answer.
+  3. After the operator answers, call emit_stage_envelope exactly once with:
+     - status: success
+     - a non-empty summary
+     - artifacts: []
+     - payload: { "branch": "branch-a" } or { "branch": "branch-b" }, matching
+       the operator reply exactly
+
+  Rules:
+  - Never emit before the operator answers.
+  - Do not emit fork_choice. Routing is deterministic from payload.branch.
+  - Never invent other branch values.
+  - Put only the id the operator chose in payload.branch.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [branch]
+      properties:
+        branch:
+          type: string

package/examples/conditional-fork/fork-demo.pipeline.yaml

@@ -0,0 +1,20 @@
+id: fork-demo
+stages:
+  - id: decide
+    uses: ./decide.yaml
+    entry: true
+    route:
+      - to: branch-a
+        if:
+          field: branch
+          op: eq
+          value: branch-a
+      - to: branch-b
+        if:
+          field: branch
+          op: eq
+          value: branch-b
+  - id: branch-a
+    uses: ./branch-a.yaml
+  - id: branch-b
+    uses: ./branch-b.yaml

package/examples/conditional-fork/fork-demo.task.yaml

@@ -0,0 +1,8 @@
+id: fork-demo
+goal: |
+  Operator chooses branch-a or branch-b at the decide gate; the pipeline routes
+  to that branch and skips the other.
+context: |
+  Manual HITL then Route if walkthrough. At decide, answer the free_text gate
+  with exactly branch-a or branch-b. The chosen branch should succeed; the other
+  should be skipped.

package/examples/context7-mcp/README.md

@@ -0,0 +1,42 @@
+# context7-mcp
+
+Three-stage walkthrough: **resolve a library**, **fetch docs**, then **write a brief**, using Context7 MCP (`https://mcp.context7.com/mcp`) from git-root `.mcp.json`.
+
+Each MCP stage is a **fresh Pi session**. Stage 1 cannot leave a live Context7 connection for stage 2. The `library_id` travels in the envelope; stage 2 calls `query-docs`. Stage 3 has **no** `mcp:` list — it only turns the excerpt into an artifact.
+
+| Stage | MCP | What it does |
+|-------|-----|----------------|
+| `resolve-library` | `context7` | `resolve-library-id` → emit `library_id` |
+| `fetch-docs` | `context7` | `query-docs` → `docs.md` + `excerpt` |
+| `write-brief` | — | `brief.md` from the excerpt (no MCP) |
+
+## Prerequisites
+
+- Node.js ≥ 20 and this repo's CLI (`npm run build`), not an older global `sf`
+- Provider auth (`sf ui` → Settings → Providers)
+- `CONTEXT7_API_KEY` in the environment of the `sf run` / `sf ui` process (free key at [context7.com/dashboard](https://context7.com/dashboard)). The catalog interpolates `Authorization: Bearer ${CONTEXT7_API_KEY}`. `sf validate` does not require the var; the run does.
+
+Git-root `.mcp.json` already names `context7`. Stages still pass `mcp: [context7]` — listing it in the catalog is not attach.
+
+Optional: Settings → **Project MCP servers** → Check `context7` before the run.
+
+## Run (repo root)
+
+```bash
+export CONTEXT7_API_KEY=...   # from context7.com/dashboard
+npm run build
+node dist/cli.js validate --pipeline examples/context7-mcp/context7-mcp.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/context7-mcp/context7-mcp.pipeline.yaml \
+  --task examples/context7-mcp/context7-mcp.task.yaml
+```
+
+Inspect:
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage resolve-library --json
+node dist/cli.js envelope get --run <runId> --stage fetch-docs --json
+node dist/cli.js envelope get --run <runId> --stage write-brief --json
+```
+
+The operator-facing write-up is the `write-brief` Files row `brief.md`.

package/examples/context7-mcp/context7-mcp.pipeline.yaml

@@ -0,0 +1,15 @@
+id: context7-mcp
+stages:
+  - id: resolve-library
+    entry: true
+    route:
+      - to: fetch-docs
+    uses: ./resolve-library.yaml
+    mcp: [context7]
+  - id: fetch-docs
+    route:
+      - to: write-brief
+    uses: ./fetch-docs.yaml
+    mcp: [context7]
+  - id: write-brief
+    uses: ./write-brief.yaml

package/examples/context7-mcp/context7-mcp.task.yaml

@@ -0,0 +1,4 @@
+id: context7-mcp
+goal: Look up how to register a GET route in Express, using current Context7 docs, then write a one-page brief.
+context: Three-stage Context7 MCP walkthrough. Resolve a library id, fetch docs, then write a brief without MCP. Each MCP stage is a fresh session.
+constraints: Use only the context7 server named on the stage. Do not call ask_operator. Do not invent APIs missing from the fetched docs.

package/examples/context7-mcp/fetch-docs.yaml

@@ -0,0 +1,52 @@
+id: fetch-docs
+system_prompt: |
+  Fetch current docs for the library_id from the prior resolve-library
+  envelope. This stage has a new Context7 MCP session. Call query-docs
+  with that libraryId and the task question. Do not call
+  resolve-library-id unless the id is unusable. Do not call ask_operator.
+
+  Write docs.md via write_stage_artifact with the retrieved snippets
+  (trimmed to what answers the question). Checkout write/edit does not
+  satisfy the artifact.
+
+  When finished, call emit_stage_envelope exactly once with status success,
+  artifacts ["docs.md"], a short summary, and payload
+  { "library_id": "<id>", "query": "<question>", "excerpt": "<short answer
+  plus one code sample from the docs>" }. summary and payload are handed
+  downstream verbatim. State outcomes and artifact pointers only.
+
+  Your last tool call in this attempt must be emit_stage_envelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - library_id
+        - library_name
+      properties:
+        library_id:
+          type: string
+        library_name:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - library_id
+        - query
+        - excerpt
+      properties:
+        library_id:
+          type: string
+        query:
+          type: string
+        excerpt:
+          type: string
+verify:
+  - id: docs
+    type: artifact
+    path: docs.md
+    nonempty: true
+    when:
+      - after

package/examples/context7-mcp/resolve-library.yaml

@@ -0,0 +1,31 @@
+id: resolve-library
+system_prompt: |
+  Resolve the library named in the task with Context7 MCP. Call
+  resolve-library-id with libraryName and the task question as query.
+  Pick one libraryId (prefer an official high-reputation match). Do not
+  call query-docs. Do not call ask_operator.
+
+  When finished, call emit_stage_envelope exactly once with status success,
+  artifacts [], a short summary, and payload
+  { "library_id": "<id like /org/project>", "library_name": "<name>" }.
+  summary and payload are handed to the next stage verbatim. State outcomes
+  only.
+
+  Your last tool call in this attempt must be emit_stage_envelope.
+  The next stage starts a fresh MCP session — pass the id in the envelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - library_id
+        - library_name
+      properties:
+        library_id:
+          type: string
+        library_name:
+          type: string

package/examples/context7-mcp/write-brief.yaml

@@ -0,0 +1,52 @@
+id: write-brief
+system_prompt: |
+  Turn the fetch-docs envelope into a one-page operator brief. You do not
+  have Context7 MCP on this stage. Use payload.excerpt, library_id, and
+  query only. Do not invent APIs that are not in the excerpt. Do not call
+  ask_operator.
+
+  Write brief.md via write_stage_artifact: the question, the library id,
+  a short answer, and the code sample from the excerpt. Checkout write/edit
+  does not satisfy the artifact.
+
+  When finished, call emit_stage_envelope exactly once with status success,
+  artifacts ["brief.md"], a short summary, and payload
+  { "library_id": "<id>", "brief_artifact": "brief.md" }. summary and
+  payload are handed downstream verbatim. State outcomes and artifact
+  pointers only.
+
+  Your last tool call in this attempt must be emit_stage_envelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - library_id
+        - query
+        - excerpt
+      properties:
+        library_id:
+          type: string
+        query:
+          type: string
+        excerpt:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - library_id
+        - brief_artifact
+      properties:
+        library_id:
+          type: string
+        brief_artifact:
+          type: string
+verify:
+  - id: brief
+    type: artifact
+    path: brief.md
+    nonempty: true
+    when:
+      - after