stageflow 0.25.0 → 0.27.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-Da5EHU6M.js"></script>
+    <script type="module" crossorigin src="/assets/index-B6hlSXXn.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-CSsDued1.css">
   </head>
   <body>

package/examples/README.md

@@ -0,0 +1,98 @@
+# Examples
+
+Runnable Stageflow catalogs. Each directory is **pipeline-owned** (co-located `*.pipeline.yaml`, stage YAML, `*.task.yaml`). Run commands use **paths from the repository git root**.
+
+Stages are **author-defined** in YAML; these walkthroughs show domain-neutral flows, release automation, and an SDLC-style plan review — not built-in product types. Author contracts with `io` / `verify` / `on_verify_fail` — see [YAML catalog](../docs/yaml-catalog.md).
+
+Upgrading older YAML: [`sf migrate-yaml`](../docs/cli-reference.md#sf-migrate-yaml) converts contract keys to `io` / `verify` / `on_verify_fail`. Wiring (`needs` / `fork` / `feedback_loop`) is a hard cutover to `route` / `entry` / `{ type: loop }` — see [Upgrading older catalogs](../docs/yaml-catalog.md#upgrading-older-catalogs) (wiring subsection). `sf migrate-yaml` does not rewrite wiring.
+
+[Clone Chain](../docs/yaml-catalog.md#clone-chain) (one Clone Instance per Clone Array element) is documented in the YAML catalog. Walkthrough: [`feature-loop/`](feature-loop/). Canonical shapes: [`tests/fixtures/pipelines/clone-chain-*.pipeline.yaml`](../tests/fixtures/pipelines/).
+
+## Featured example: Archify on PR
+
+**[`archify-on-pr/`](archify-on-pr/)** is the flagship CI dogfood walkthrough. It shows what configurable stages look like in production:
+
+- **Route `if`** — `detect-changes` emits `author_diagrams` and skips `author-diagrams` when the PR diff has no diagram-relevant types
+- **Multi-type output** — one pipeline authors 1–5 Archify diagram specs (`architecture`, `workflow`, `sequence`, `dataflow`, `lifecycle`)
+- **Skill binding** — `skill: archify` on the pipeline stage entry; GHA provisions the skill via `sf skills install`
+- **Deterministic handoff** — agents emit JSON specs; GHA runs `sf envelope get --format handoff` and Archify `deliver` outside the agent
+- **Real automation** — [`.github/workflows/archify-pr-diagrams.yml`](../.github/workflows/archify-pr-diagrams.yml) posts sticky PR comments with browser-viewable HTML artifacts
+
+Start here: [archify-on-pr/README.md](archify-on-pr/README.md) · CI overview: [docs/ci.md#pr-diagrams-archify](../docs/ci.md#pr-diagrams-archify)
+
+More CI-focused examples will follow this pattern (prepare context → run pipeline → consume envelope in shell).
+
+| Example | Description | Commands |
+|---------|-------------|----------|
+| [hello-world](hello-world/) | Single stage; demos `task.input` ↔ entry `io.input.schema` | `sf validate --strict`, `sf run` with paths below |
+| [plan-review](plan-review/) | Multi-stage with operator gate | `sf ui`, then `sf run` |
+| [conditional-fork](conditional-fork/) | HITL then exclusive Route `if`; operator chooses branch | `sf ui`, then `sf run` |
+| [generic-fan-in](generic-fan-in/) | Dummy diamond join; inspect keyed parent envelopes | `sf ui`, then `sf run` |
+| [stage-mcp](stage-mcp/) | Stage MCP via project `.mcp.json` and a local echo fixture | `sf validate`, then `sf run` from git root |
+| [playwright-mcp](playwright-mcp/) | One stage: open a page and save a PNG screenshot (Playwright MCP) | `sf validate`, then `sf run` from git root |
+| [context7-mcp](context7-mcp/) | Three stages: resolve a library, fetch docs, write a brief (Context7 MCP) | `sf validate`, then `sf run` from git root |
+| [feedback-loop](feedback-loop/) | Source-owned review loop (`continue` / `send_back`) | `sf validate`, then `sf run` |
+| [feature-loop](feature-loop/) | Epic-to-PR; two Clone Chains + `{ type: loop }` | `sf validate`, then `sf run` |
+| [ship-feature](ship-feature/) | Plan → implement → parallel review → operator-approved PR | `sf validate`, then `sf run` |
+| [oss-issue-contribution](oss-issue-contribution/) | Real upstream issue: reproduce, parallel investigation, gated fix, verification, parallel review | [README](oss-issue-contribution/README.md), then `sf run` |
+| [oss-quick-fix](oss-quick-fix/) | Unattended sibling of oss-issue-contribution: straight-line fix with no operator gate | [README](oss-quick-fix/README.md), then `sf run` |
+| [github-release](github-release/) | Dogfood: draft + publish GitHub Release | Used in publish/release workflows |
+| [archify-on-pr](archify-on-pr/) | **Featured** — PR diagrams via Route `if` + Archify handoff | [README](archify-on-pr/README.md), archify-pr-diagrams workflow |
+| [ci-validate](ci-validate/) | Strict manifest validate in CI | `./validate.sh` |
+| [route-if-tour](route-if-tour/) | Deterministic `if` tour: operators, composition, skip, join fire/miss | `sf ui`, then pick `route-if-tour` |
+| [verify-tour](verify-tour/) | Verify check types: artifact, command, checklist, payload_schema, gate, checkout_changes | `sf ui`, then pick `verify-tour` |
+| [retry-tour](retry-tour/) | Retry surfaces: emit soft-reject, automatic repair, manual recover, ordinary Retry | `sf ui`, then pick `retry-tour` |
+| [mcp-hitl-tour](mcp-hitl-tour/) | MCP HITL tour: free_text gate, ungated fan-out + Clone Chain join, wait_for_human loop, artifacts | `sf ui` / MCP `start_run`, then [README](mcp-hitl-tour/README.md) |
+
+Current wiring tours: [`route-wiring-smoke-test`](route-wiring-smoke-test/), [`route-if-tour`](route-if-tour/).
+
+Browse scope is declared in repo-root [`stageflow.yaml`](../stageflow.yaml). **`sf ui` started from any subdirectory** still uses `<repo>/.stageflow` for run state.
+
+## Prerequisites (all examples)
+
+- **Node.js ≥ 20**
+- Stageflow CLI: `npm i -g stageflow` (or `npm run build` in this repo)
+- **Provider auth** for `sf run` (not required for `sf validate`)
+
+## Validate all examples
+
+From repo root after `npm run build`:
+
+```bash
+npm run validate:examples
+```
+
+## Run an example (repo root)
+
+```bash
+sf validate --strict
+sf run \
+  --pipeline examples/hello-world/hello.pipeline.yaml \
+  --task examples/hello-world/my-task.task.yaml
+```
+
+Current wiring north star: [`examples/route-wiring-smoke-test/`](route-wiring-smoke-test/) and [`examples/route-if-tour/`](route-if-tour/). HITL then exclusive Route `if`: [`examples/conditional-fork/`](conditional-fork/).
+
+```bash
+sf run \
+  --pipeline examples/conditional-fork/fork-demo.pipeline.yaml \
+  --task examples/conditional-fork/fork-demo.task.yaml
+```
+
+Archify-on-PR local dry-run (requires `OPENAI_API_KEY` + Archify skill — see example README):
+
+```bash
+./scripts/prepare-ci-context.sh ci-context.json
+sf run \
+  --pipeline examples/archify-on-pr/archify-on-pr.pipeline.yaml \
+  --task examples/archify-on-pr/archify-on-pr.task.yaml \
+  --skip-gates --json > sf-run.json
+```
+
+Terminal 1 (optional console, from any subdirectory):
+
+```bash
+cd examples/conditional-fork && sf ui
+```
+
+See [docs/quickstart.md](../docs/quickstart.md) and [docs/providers.md](../docs/providers.md).

package/examples/archify-on-pr/README.md

@@ -0,0 +1,213 @@
+# archify-on-pr
+
+Manually triggered Archify diagrams: prepare deterministic PR context (paths +
+diagram types), copy that into a detect-changes handoff, and author JSON specs
+for GHA to deliver as HTML.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `archify-on-pr.pipeline.yaml` | detect-changes Route `if` → author-diagrams; `verify` + `on_verify_fail` on detect |
+| `detect-changes.yaml` | Thin copy/emit from `ci-context.json` → `changes.json` + envelope |
+| `author-diagrams.yaml` | Writes `{type}.spec.json` per selected type (skill: archify on pipeline entry) |
+| `archify-on-pr.task.yaml` | Task bound at run time |
+| `../../scripts/prepare-ci-context.sh` | Deterministic PR/git context + diagram type selection before `sf run` |
+| `../../scripts/validate-detect-envelope.mjs` | Verify helper: `changes.json` / envelope match `ci-context.json` |
+
+## Diagram types
+
+Selection is **deterministic** in `prepare-ci-context.sh` from path rules on
+`relevant_files` (not the detect agent). The table documents those rules:
+
+| Type | Path rules (typical) |
+|------|----------------------|
+| `architecture` | `src/agent`, `src/server`, `src/mcp`, `src/runstore`, `ui/`, `skills/`, `stageflow.yaml`, `package.json` |
+| `workflow` | `*.pipeline.yaml`, `examples/`, `.github/workflows/`, `scripts/`, `src/runtime`, `src/config` |
+| `sequence` | `src/server`, `src/mcp`, `src/cli/runs*`, `ui/` |
+| `dataflow` | `src/envelope`, `src/runstore`, `src/projection`, `src/config` |
+| `lifecycle` | `src/runtime`, `src/tools` |
+
+A path may map to more than one type. If `relevant_files` is non-empty but no
+rule matches, the script defaults to `architecture`. Empty `relevant_files`
+yields empty `diagram_types` / `author_diagrams: false` (and empty
+`expected_fork_choice` as a CI-side signal).
+
+detect-changes copies those types into `changes.json` and the envelope and
+sets `author_diagrams` true iff `diagram_types` is non-empty. The pipeline
+gates a single author-diagrams session with Route `if` (not a Clone Chain):
+
+```yaml
+route:
+  - to: author-diagrams
+    if:
+      field: author_diagrams
+      op: eq
+      value: true
+```
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow built (`npm run build`)
+- **OpenRouter** provider
+  (`openrouter/nvidia/nemotron-3-ultra-550b-a55b:free`) — set
+  `OPENROUTER_API_KEY`, then:
+  `sf providers login openrouter --type api_key --api-key-env OPENROUTER_API_KEY`
+- **Archify skill** at `.pi/skills/archify/` (see below)
+- Git checkout at the target head; run `prepare-ci-context.sh` before `sf run`
+  (GHA does this automatically)
+
+## CI context (`ci-context.json`)
+
+Before Stageflow runs, GHA executes `scripts/prepare-ci-context.sh`. It resolves
+`head_sha`, `repo_url`, file lists, and diagram selection:
+
+| Field | Meaning |
+|-------|---------|
+| `changed_files` | Full three-dot diff vs base |
+| `relevant_files` | Filtered subset for diagram decisions |
+| `content_hash` | Hash of `relevant_files` only (empty string when none) |
+| `verified_paths` | Whether each changed path exists at `head_sha` |
+| `diagram_types` | Deterministic types from path rules on `relevant_files` |
+| `change_summary` | Short summary derived from the relevant set |
+| `expected_fork_choice` | CI-side list: `["author-diagrams"]` when types non-empty, else `[]` |
+
+`relevant_files` excludes `docs/**`, `*.md` (except `skills/**`), lockfiles,
+`tests/**` except `tests/fixtures/**/*.{yaml,yml}`, pitch-deck / pitch-assets,
+and editor noise (`.editorconfig`, `.vscode/`, `.idea/`). When that list is
+empty, `diagram_types` and `expected_fork_choice` are empty and GHA early-skips
+the `sf-run` step. detect-changes copies `relevant_files` into
+`changes.json` as `changed_files` and emits `author_diagrams` true iff
+`diagram_types` is non-empty. Catalog routing uses that boolean, not
+`fork_choice`.
+
+Both pipeline stages read this file — agents do not use `GITHUB_SHA` or run
+their own git diff. detect-changes does not re-derive types; it only copies and
+emits. The pipeline enforces that with body `verify` (`type: artifact` on
+`changes.json` at emit and after, plus after-phase payload and command checks)
+and wiring `on_verify_fail: repair`.
+
+Local dry-run:
+
+```bash
+PR_HEAD_SHA="$(git rev-parse HEAD)" \
+GITHUB_REPOSITORY="$(git remote get-url origin | sed -E 's#.*github.com[:/]([^/]+/[^/.]+).*#\1#')" \
+GITHUB_BASE_REF=main \
+./scripts/prepare-ci-context.sh ci-context.json
+```
+
+## Install Archify skill
+
+From the repository git root (after `npm run build`):
+
+```bash
+node dist/cli.js skills install \
+  --from-zip "https://github.com/tt-a1i/archify/releases/download/v2.15.0/archify.zip" \
+  --skill-name archify
+```
+
+For local development, install from an existing skill tree:
+
+```bash
+node dist/cli.js skills install --from-path ~/.agents/skills/archify --skill-name archify
+```
+
+Install runs `archify doctor` after copying to `.pi/skills/archify/`.
+
+## Commands
+
+Local dry-run from repo root:
+
+```bash
+sf validate --strict
+export OPENROUTER_API_KEY=…
+sf providers login openrouter --type api_key --api-key-env OPENROUTER_API_KEY
+./scripts/prepare-ci-context.sh ci-context.json
+sf run \
+  --pipeline examples/archify-on-pr/archify-on-pr.pipeline.yaml \
+  --task examples/archify-on-pr/archify-on-pr.task.yaml \
+  --checkout "$PWD" \
+  --skip-gates \
+  --json > sf-run.json
+```
+
+When prepare-ci-context selects no types (`author_diagrams: false`),
+Route `if` skips `author-diagrams`. When types are selected, inspect
+`{type}.spec.json` files in the run workspace.
+
+### Extract envelope
+
+Mirrors the GHA deliver step — reads the author stage envelope via the CLI:
+
+```bash
+node dist/cli.js envelope get --from sf-run.json --stage author-diagrams \
+  --detect-stage detect-changes --format handoff --json > envelope.json
+```
+
+When author-diagrams ran, output is
+`{ "skipped": false, "diagrams": [{ diagram_type, spec_path, summary }, …] }`.
+When `author_diagrams` is false, Route `if` skips that stage; GHA usually
+early-skips the whole `sf-run` step when `relevant_files` is empty.
+Deliver manually:
+
+```bash
+node dist/cli.js envelope get --from sf-run.json --stage author-diagrams \
+  --detect-stage detect-changes --format handoff --json > envelope.json
+./scripts/deliver-diagrams.sh envelope.json diagrams
+```
+
+Or per diagram:
+
+```bash
+mkdir -p diagrams
+while IFS= read -r d; do
+  TYPE=$(jq -r .diagram_type <<<"$d")
+  SPEC=$(jq -r .spec_path <<<"$d")
+  node .pi/skills/archify/bin/archify.mjs deliver \
+    "$TYPE" "$SPEC" "diagrams/${TYPE}.html" --quality showcase
+done < <(jq -c '.diagrams[]' envelope.json)
+```
+
+## Environment variables
+
+| Variable | Used by | Description |
+|----------|---------|-------------|
+| `OPENROUTER_API_KEY` | `sf run` | OpenRouter provider auth (required) |
+| `PR_NUMBER` | prepare-ci-context | PR number override (enables sticky comment in GHA when set) |
+| `PR_HEAD_SHA` | prepare-ci-context | PR head commit SHA |
+| `GITHUB_REPOSITORY` | prepare-ci-context | `owner/repo` |
+| `GITHUB_BASE_REF` | prepare-ci-context | PR base branch (default: `main`) |
+| `GITHUB_HEAD_REF` | prepare-ci-context | PR head branch name |
+| `CI_CONTEXT_FILE` | deliver-diagrams.sh / validate-detect-envelope.mjs | Path to context JSON (default: `ci-context.json`) |
+| `ARCHIFY_SOURCE_DIR` | GHA secret | Local Archify skill path (`sf skills install --from-path`) |
+| `ARCHIFY_ZIP_URL` | GHA variable | Release zip URL (`sf skills install --from-zip`; defaults to Archify v2.15.0) |
+
+## Fork PR limitation
+
+The workflow posts a sticky PR comment with `pull-requests: write` only when
+`pr_number` is provided. On **fork PRs**, GitHub downgrades `GITHUB_TOKEN` — the
+job may succeed but cannot post or update the comment. Same-repo branch PRs are
+supported; fork comment posting is deferred.
+
+## GitHub Actions
+
+See [`.github/workflows/archify-pr-diagrams.yml`](../../.github/workflows/archify-pr-diagrams.yml).
+
+**Manual trigger only** (`workflow_dispatch` — not automatic on every PR).
+
+1. Open **Actions** → **Archify PR diagrams** → **Run workflow**
+2. Provide **one of**:
+   - `pr_number` — resolves head/base from the PR; enables the sticky PR comment
+   - `head_ref` — branch or commit SHA when not targeting a PR
+3. Optionally set `base_ref` (default: `main`) for the three-dot diff
+
+The workflow uses the [`.github/actions/sf-run`](../../.github/actions/sf-run)
+composite to run the pipeline and extract a handoff envelope via
+`sf envelope get --format handoff`. `prepare-ci-context.sh` runs before the
+pipeline; if `relevant_files` is empty, GHA skips `sf-run`, deliver, upload, and
+comment. detect-changes only copies/validates against that context; agents
+author JSON only in author-diagrams. GHA runs `deliver-diagrams.sh` (Archify
+`deliver` per type), uploads each `{type}.html` unzipped (`upload-artifact@v7`,
+`archive: false`) for in-browser viewing, also uploads a zipped `diagrams/`
+bundle, and updates the sticky comment when `pr_number` is set. Debug artifacts
+include `ci-context.json`, `sf-run.json`, `envelope.json`, and `run-export.json`.

package/examples/archify-on-pr/archify-on-pr.pipeline.yaml

@@ -0,0 +1,19 @@
+id: archify-on-pr
+stages:
+  - id: detect-changes
+    uses: ./detect-changes.yaml
+    entry: true
+    route:
+      - to: author-diagrams
+        if:
+          field: author_diagrams
+          op: eq
+          value: true
+    on_verify_fail:
+      mode: repair
+      max_attempts: 2
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: author-diagrams
+    uses: ./author-diagrams.yaml
+    skill: archify

package/examples/archify-on-pr/archify-on-pr.task.yaml

@@ -0,0 +1,19 @@
+id: archify-on-pr
+goal: |
+  Detect pull-request changes that warrant diagrams and author one or more Archify
+  JSON specs (architecture, workflow, sequence, dataflow, lifecycle) when warranted.
+context: |
+  GHA runs scripts/prepare-ci-context.sh before this pipeline, writing ci-context.json
+  at the repo root with head_sha, repo_url, changed_files, relevant_files,
+  diagram_types, change_summary, expected_fork_choice, and verified_paths.
+  Diagram type selection is deterministic in prepare-ci-context — detect-changes only
+  copies those fields into the envelope and sets author_diagrams from diagram_types.
+  CI uses OpenRouter (OPENROUTER_API_KEY).
+  Stage 1 emits the detect handoff (after-phase verify). Route if runs a single
+  author-diagrams session when author_diagrams is true. Stage 2 writes one spec
+  artifact per selected type for GHA to deliver as HTML outside the agent.
+constraints: |
+  No HITL. Do not call ask_operator. Stages use OpenRouter models; ensure
+  OPENROUTER_API_KEY is available in CI. detect-changes must not invent diagram_types
+  or paths. The author stage must not install Archify, run npm install, or call
+  deliver or doctor — GHA owns tool provisioning and HTML delivery after the run.

package/examples/archify-on-pr/author-diagrams.yaml

@@ -0,0 +1,106 @@
+id: author-diagrams
+system_prompt: |
+  Author Archify diagram specs for every diagram type selected by detect-changes.
+
+  Read ci-context.json from the repository root and the detect-changes envelope for
+  pr_number, changed_files, diagram_types, change_summary, and content_hash. Use
+  verified_paths from ci-context.json — only cite source paths marked true.
+
+  When evidence exists in relevant paths, authored diagrams may reflect modern
+  verified stage execution, dual AgentPort (Pi/Claude), MCP + sf runs host-down,
+  and skills binding. Still require verified_paths and repo evidence; do not
+  invent components without source.
+
+  For each entry in diagram_types (architecture, workflow, sequence, dataflow,
+  lifecycle), write a separate spec artifact via write_stage_artifact:
+  architecture.spec.json, workflow.spec.json, sequence.spec.json,
+  dataflow.spec.json, or lifecycle.spec.json. Each JSON must be valid Archify IR
+  for that type with schema_version and meta.quality_profile set to showcase.
+
+  Read the Archify skill schema and one matching example for each type before
+  authoring. Keep layouts sparse: at most 12 primary nodes, short labels and
+  sublabels, and node widths/heights that fit the text (workflow nodes often
+  need width >= 140). Leave at least 8px between adjacent nodes in the same lane.
+
+  Do not set meta.repository in specs — GHA deliver injects it from ci-context.json
+  when sources[] are present. Omit component sources[] unless the path is true in
+  ci-context.json verified_paths and validate passes with --repo-root.
+
+  After each spec edit, run validate and fix every diagnostic before continuing:
+    node .pi/skills/archify/bin/archify.mjs validate <type> <spec.json> --quality showcase --json
+  For architecture with sources[], also pass --repo-root to the PR head checkout.
+  Require ok:true with 9/9 artifact checks and 0 composition errors per spec.
+
+  FORBIDDEN: deliver, npm install, doctor, ask_operator. Do not invoke deliver;
+  GHA runs deliver after this stage completes.
+
+  Call emit_stage_envelope exactly once with status success, every spec artifact
+  in artifacts, a one-sentence summary, and a payload matching the stage schema
+  with a diagrams array — one object per authored type:
+  { diagram_type, spec_artifact, summary }.
+  Do not stop after a chat reply.
+model: openrouter/nvidia/nemotron-3-ultra-550b-a55b:free
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - pr_number
+        - base_ref
+        - head_sha
+        - changed_files
+        - diagram_types
+        - change_summary
+        - content_hash
+        - author_diagrams
+      properties:
+        pr_number:
+          type: string
+        base_ref:
+          type: string
+        head_sha:
+          type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        diagram_types:
+          type: array
+          items:
+            type: string
+            enum:
+              - architecture
+              - workflow
+              - sequence
+              - dataflow
+              - lifecycle
+        change_summary:
+          type: string
+        content_hash:
+          type: string
+        author_diagrams:
+          type: boolean
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - diagrams
+      properties:
+        diagrams:
+          type: array
+          items:
+            type: object
+            required:
+              - diagram_type
+              - spec_artifact
+              - summary
+            properties:
+              diagram_type:
+                type: string
+              spec_artifact:
+                type: string
+              summary:
+                type: string
+            additionalProperties: false
+      additionalProperties: false

package/examples/archify-on-pr/detect-changes.yaml

@@ -0,0 +1,89 @@
+id: detect-changes
+system_prompt: |
+  Emit the detect-changes handoff from ci-context.json. Do not invent types or paths.
+
+  1. Read ci-context.json at the repository root. It already has pr_number, base_ref,
+     head_sha, relevant_files, diagram_types, change_summary, and content_hash.
+     Do not run git diff or re-derive diagram types. Ignore expected_fork_choice.
+
+  2. Write changes.json via write_stage_artifact with exactly:
+     - pr_number, base_ref, head_sha, content_hash — copied from ci-context.json
+     - changed_files — copy relevant_files as-is (same order)
+     - diagram_types — copy diagram_types as-is
+     - change_summary — copy change_summary as-is
+     - author_diagrams — true when diagram_types is non-empty, false when empty
+
+  3. Call emit_stage_envelope exactly once with status success, changes.json in
+     artifacts, a one-sentence summary, and payload matching the stage schema
+     (same field values as changes.json). Set author_diagrams true iff
+     diagram_types is non-empty, false iff empty. Do not put fork_choice on
+     the envelope or in changes.json.
+
+  Do not call ask_operator. Do not stop after a chat reply. Do not select types yourself.
+model: openrouter/nvidia/nemotron-3-ultra-550b-a55b:free
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - pr_number
+        - base_ref
+        - head_sha
+        - changed_files
+        - diagram_types
+        - change_summary
+        - content_hash
+        - author_diagrams
+      properties:
+        pr_number:
+          type: string
+        base_ref:
+          type: string
+        head_sha:
+          type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        diagram_types:
+          type: array
+          items:
+            type: string
+            enum:
+              - architecture
+              - workflow
+              - sequence
+              - dataflow
+              - lifecycle
+        change_summary:
+          type: string
+        content_hash:
+          type: string
+        author_diagrams:
+          type: boolean
+      additionalProperties: false
+verify:
+  - id: changes-json-declared
+    type: artifact
+    basename: changes.json
+    when:
+      - emit
+  - id: changes-on-disk
+    type: artifact
+    path: changes.json
+    nonempty: true
+    when:
+      - after
+  - id: payload-ok
+    type: payload_schema
+    when:
+      - after
+  - id: matches-ci-context
+    type: command
+    run: node scripts/validate-detect-envelope.mjs
+    timeout_ms: 30000
+    when:
+      - after

package/examples/ci-validate/README.md

@@ -0,0 +1,35 @@
+# ci-validate
+
+Validate-only CI demo. Checks the repo manifest and example catalogs with `sf validate --strict` — no provider auth or agent run required.
+
+## Prerequisites
+
+- Node.js ≥ 20
+- Stageflow CLI (`npm i -g stageflow` or built from this repo)
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+chmod +x examples/ci-validate/validate.sh
+./examples/ci-validate/validate.sh
+```
+
+Or directly:
+
+```bash
+sf validate --strict --json
+```
+
+## GitHub Actions snippet
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: "24"
+- run: npm i -g stageflow
+- run: sf validate --strict --json
+```
+
+Run from the workspace root where `stageflow.yaml` lives.

package/examples/ci-validate/check.yaml

@@ -0,0 +1,13 @@
+id: check
+system_prompt: |
+  Validate-only CI demo stage. In real CI you typically run sf validate
+  without invoking agents; this stage exists so the catalog is a valid,
+  runnable example if you extend it later.
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object

package/examples/ci-validate/ci-demo.pipeline.yaml

@@ -0,0 +1,4 @@
+id: ci-demo
+stages:
+  - id: check
+    uses: ./check.yaml

package/examples/ci-validate/validate.sh

@@ -0,0 +1,5 @@
+#!/usr/bin/env bash
+set -euo pipefail
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+cd "$ROOT"
+sf validate --strict --json