stageflow 0.25.0 → 0.30.0

package/examples/README.md

@@ -0,0 +1,99 @@
+# 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 |
+| [browser-session](browser-session/) | Saved browser login: check, human login only when logged out, then work; local fixture site | [README](browser-session/README.md), then `sf run` |
+| [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). Cold Host (`sf ui` / `sf mcp`) also browses the packaged seeded root via [`examples/stageflow.yaml`](stageflow.yaml) (paths relative to `examples/`; wire `project_root: "examples"`). **`sf ui` started from any subdirectory** still uses the global durable root (`$STAGEFLOW_HOME`) 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/browser-session/README.md

@@ -0,0 +1,77 @@
+# browser-session
+
+Stages that keep one browser login across runs: **check the login, ask a person to log in only when needed, then do the work in two parallel stages that share the login, then merge.** The target is a tiny local fixture site, so nothing here touches a third-party service.
+
+| Stage | What it does |
+|-------|--------------|
+| `check-login` | The Host opens `/home` with the saved profile and computes `{ logged_in, url }`. The stage reports it. Routes to `human-login` only when `logged_in` is `false`. |
+| `human-login` | Opens a visible window on `/login`, stops at a `confirm` gate. The operator logs in and confirms. The Host checks the login again (`browser_login` verify, repair policy, up to 3 attempts). |
+| `work-a` | Reads `/a` with the same profile in its own tab and writes `result.md`. Joins `check-login` and `human-login`. |
+| `work-b` | Reads `/b` with the same profile in its own tab, at the same time as `work-a`. Joins `check-login` and `human-login`. |
+| `merge` | No browser. Joins `work-a` and `work-b` and writes one merged `result.md`. |
+
+Only the `check-login` to `human-login` edge has an `if`. The work stages are joins, so their inbound edges carry none. See [docs/browser.md](../../docs/browser.md#login-pattern).
+
+## Prerequisites
+
+- Node.js 20 or newer and this repo's CLI (`npm run build`)
+- Provider auth for `sf run`
+- agent-browser: `npm i -g agent-browser && agent-browser install`
+- A screen on this machine. The login window is visible (headed is the default). A Host with no screen, including the Docker image, cannot run `human-login` yet.
+
+## Run (repo root)
+
+Start the fixture site in one terminal:
+
+```bash
+node examples/browser-session/fixture-server.mjs
+```
+
+It listens on `http://localhost:4173`. Set `PORT` to change it, and update the URLs in `browser-session.pipeline.yaml` to match.
+
+In another terminal:
+
+```bash
+npm run build
+node dist/cli.js validate --pipeline examples/browser-session/browser-session.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/browser-session/browser-session.pipeline.yaml \
+  --task examples/browser-session/browser-session.task.yaml
+```
+
+Use `sf ui` instead of `sf run` if you want to answer the gate in the console.
+
+## First run
+
+1. `check-login` finds no login (`/home` redirects to `/login`). It reports `logged_in: false`.
+2. `human-login` opens a browser window on the fixture login page and asks you to confirm.
+3. Press **Log in** in that window, then answer the gate with accept. You never give a password to the agent.
+4. The Host checks again. If you confirmed too early, the stage asks again.
+5. `work-a` and `work-b` start together. They share one Chrome, each in its own tab, and both see the login.
+6. `merge` joins them and writes `result.md`.
+
+## Next run
+
+`check-login` finds the saved login and reports `logged_in: true`. `human-login` is skipped. There is no question. `work-a` and `work-b` run straight away.
+
+The fixture sets two cookies. The persistent one (`fixture_login`) is what keeps you logged in across runs. The session-only one (`fixture_session`) is shared by all stages of one run because the browser stays open for the whole run. Do not rely on a session-only cookie across runs. See [docs/browser.md](../../docs/browser.md#cookies-across-runs).
+
+The run holds the profile until it ends. A second run that needs `fixture-site` waits for the whole first run.
+
+## What is stored where
+
+- The profile (a Chrome folder with the cookies) lives under the Stageflow home: `$STAGEFLOW_HOME/browser/local/fixture-site/` (default `~/.stageflow/browser/local/fixture-site/`), owner-only permissions.
+- Nothing is written into this repo. Run state and envelopes hold the profile name, never cookie values or paths.
+- Profile uses are recorded in `$STAGEFLOW_HOME/browser/audit.jsonl`.
+
+## Clean up
+
+Clear the login with `sf browser clear fixture-site` (see [CLI reference](../../docs/cli-reference.md)).
+
+## Headed and headless
+
+Stages are headed by default. All stages that share a profile should use the same mode, because headless Chrome reports a different user agent. `human-login` must stay headed. To run the check and work stages headless, set `headed: false` on all four `browser` blocks and log in once with a headed run first.
+
+## Real sites
+
+This example is neutral on purpose. Some sites forbid automation in their terms. Read the rules of any site before you point a stage at it. See [docs/browser.md](../../docs/browser.md#sites-can-forbid-automation).

package/examples/browser-session/browser-session.pipeline.yaml

@@ -0,0 +1,50 @@
+id: browser-session
+stages:
+  - id: check-login
+    uses: ./check-login.yaml
+    entry: true
+    browser:
+      profile: fixture-site
+      check:
+        url: http://localhost:4173/home
+        logged_in_url: http://localhost:4173/home*
+        logged_out_url: [http://localhost:4173/login*]
+    route:
+      - to: human-login
+        if:
+          field: logged_in
+          op: eq
+          value: false
+      - to: work-a
+      - to: work-b
+  - id: human-login
+    uses: ./human-login.yaml
+    browser:
+      profile: fixture-site
+      login_url: http://localhost:4173/login
+      check:
+        url: http://localhost:4173/home
+        logged_in_url: http://localhost:4173/home*
+        logged_out_url: [http://localhost:4173/login*]
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+    route:
+      - to: work-a
+      - to: work-b
+  - id: work-a
+    uses: ./work-a.yaml
+    browser:
+      profile: fixture-site
+    route:
+      - to: merge
+  - id: work-b
+    uses: ./work-b.yaml
+    browser:
+      profile: fixture-site
+    route:
+      - to: merge
+  - id: merge
+    uses: ./merge.yaml