stageflow 0.25.0 → 0.30.0

package/examples/stageflow.yaml

@@ -0,0 +1,51 @@
+version: 1
+catalog:
+  pipelines:
+    - generic-fan-in
+    - stage-mcp
+    - playwright-mcp
+    - context7-mcp
+    - conditional-fork
+    - hello-world
+    - plan-review
+    - github-release
+    - ci-validate
+    - archify-on-pr
+    - feedback-loop
+    - oss-issue-contribution
+    - oss-quick-fix
+    - route-wiring-smoke-test
+    - route-if-tour
+    - verify-tour
+    - retry-tour
+    - mcp-hitl-tour
+    - feature-loop
+    - ship-feature
+  tasks:
+    - generic-fan-in
+    - stage-mcp
+    - playwright-mcp
+    - context7-mcp
+    - conditional-fork
+    - hello-world
+    - plan-review
+    - github-release
+    - ci-validate
+    - archify-on-pr
+    - feedback-loop
+    - oss-issue-contribution
+    - oss-quick-fix
+    - route-wiring-smoke-test
+    - route-if-tour
+    - verify-tour
+    - retry-tour
+    - mcp-hitl-tour
+    - feature-loop
+    - ship-feature
+  patterns:
+    pipeline: "*.pipeline.yaml"
+    task: "*.task.yaml"
+  exclude:
+    - route-wiring-smoke-test/rejected
+    - stage-mcp/stage-mcp-dead.pipeline.yaml
+    - stage-mcp/stage-mcp-dead.task.yaml

package/examples/verify-tour/README.md

@@ -0,0 +1,80 @@
+# Verify tour
+
+One short spine that walks every **verify check type** in a single successful run. Each stage does one type. Prompts spell the tool calls so the checks we claim actually pass.
+
+This catalog is a **deep spine**: ungated `to:` is the next stop. Open the stage in the operator console and inspect that attempt’s verify evidence.
+
+Illegal catalogs (emit-only `command`, artifact without `when`, `if` on a loop, …) cannot live here — validate would reject the whole pipeline.
+
+## Run
+
+From the repo git root, after `sf ui` is up, pick pipeline `verify-tour` and task `verify-tour`.
+
+The task binds `checkout: .` (this git tree, resolved from the factory cwd). `checkout-check` writes `verify-tour-marker.txt` at that checkout root. Delete the file when you are done; do not commit it.
+
+Or:
+
+```bash
+npx tsx src/cli.ts validate --pipeline examples/verify-tour/verify-tour.pipeline.yaml
+npx tsx src/cli.ts run \
+  --pipeline examples/verify-tour/verify-tour.pipeline.yaml \
+  --task examples/verify-tour/verify-tour.task.yaml
+```
+
+Validate should succeed (`ok: true`). You may see `pipeline.model_applies` because `model` is set on the pipeline, not on each stage.
+
+The run should **succeed**. Every stage should **succeed**. `gate-check` pauses for a **confirm** accept in the operator console (or `--skip-gates` on the CLI).
+
+## Walk (follow-along order)
+
+| Level | Stage | Verify type | What the agent does | What Stageflow checks |
+|-------|-------|-------------|---------------------|------------------------|
+| 1 | `kickoff` | none | Emit empty success | — |
+| 2 | `artifact-check` | `artifact` emit + after | `write_stage_artifact` `note.md`, list it on emit | Basename on `artifacts`; file exists nonempty under the attempt artifacts dir |
+| 3 | `command-check` | `command` after | Emit empty success | Stageflow runs `echo verify-tour-ok` (exit 0) |
+| 4 | `checklist-check` | `checklist` after | Emit `checklist_attestations` for `self-review` | Items match the declared list exactly |
+| 5 | `payload-check` | `payload_schema` after | Emit `{"ok": true}` | Re-check captured payload against `io.output.schema` |
+| 6 | `gate-check` | `gate` confirm emit + after | `ask_operator` confirm, then emit | Last confirm this attempt is accept |
+| 7 | `checkout-check` | `checkout_changes` after | Write `verify-tour-marker.txt` in the checkout | Diff vs pre-attempt snapshot; `changed_files` matches exactly |
+
+## Scenario table
+
+| Scenario | How this pipeline covers it | Evidence |
+|----------|------------------------------|----------|
+| `type: artifact` emit | `note-declared` `when: [emit]` | Emit lists `note.md` (basename / suffix match, no disk I/O) |
+| `type: artifact` after | `note-on-disk` `when: [after]` `nonempty: true` | File on disk under attempt artifacts |
+| `type: command` | `echo-ok` `run: echo verify-tour-ok` | After-phase exit 0; stdout in verify evidence |
+| `type: checklist` | `self-review` two items | Envelope `checklist_attestations` match |
+| `type: payload_schema` | `payload-ok` after `{"ok": true}` | After-phase re-check of `io.output.schema` |
+| `type: gate` emit | `operator-ok` `kind: confirm` `when` includes `emit` | Soft reject until confirm accept |
+| `type: gate` after | same check `when` includes `after` | After-phase sees the accepted confirm on this attempt |
+| `type: checkout_changes` | `repo-touched` `path_fields: [changed_files]` | Marker file appears in the attempt diff and payload |
+| Bound checkout required | task `checkout: .` | Without a git checkout this last stage errors |
+| No `on_verify_fail` | omitted | A failed after-check fails the stage (no silent repair) |
+
+## Expected stage status
+
+| Stage | Status | Why |
+|-------|--------|-----|
+| `kickoff` | succeeded | entry |
+| `artifact-check` | succeeded | both artifact checks passed |
+| `command-check` | succeeded | command exited 0 |
+| `checklist-check` | succeeded | attestation matched |
+| `payload-check` | succeeded | payload matched schema |
+| `gate-check` | succeeded | confirm accepted |
+| `checkout-check` | succeeded | marker file changed the checkout |
+
+## Not in this pipeline
+
+These are real cases, but putting them here would fail validate or fail the run.
+
+| Scenario | Why it is absent | Where to see it |
+|---------|------------------|-----------------|
+| Failing after-phase verify | would fail the stage / run | [Verified Stage Execution](../../docs/verified-stage-execution.md) |
+| `on_verify_fail.mode: repair` | recovery policy, not a check type | `tests/fixtures/target-dialect/demo.pipeline.yaml` |
+| `on_verify_fail.mode: manual` | needs an operator recover decision after a failed check | [Verified Stage Execution — Manual recovery](../../docs/verified-stage-execution.md#manual-recovery) |
+| Other gate kinds (`free_text`, `multi_question`, `artifact_backed`) | `type: gate` is covered; kinds are HITL widgets | `examples/plan-review/`, `tests/fixtures/stages/hitl-four-kinds.yaml` |
+| `command` / `checklist` / `payload_schema` / `checkout_changes` with `when: [emit]` | illegal | yaml-catalog Verify |
+| Artifact without `when` | illegal | yaml-catalog Verify |
+| Gitignored marker file | `--exclude-standard` hides it; the check would fail | git checkout capability |
+| Unbound checkout | `checkout_changes` errors without `task.checkout` | [Verified Stage Execution](../../docs/verified-stage-execution.md) |

package/examples/verify-tour/verify-tour.pipeline.yaml

@@ -0,0 +1,162 @@
+id: verify-tour
+model: cursor/auto
+schemas:
+  empty:
+    type: object
+  ok-flag:
+    type: object
+    required: [ok]
+    properties:
+      ok:
+        type: boolean
+  changed:
+    type: object
+    required: [changed_files]
+    properties:
+      changed_files:
+        type: array
+        items:
+          type: string
+stages:
+  - id: kickoff
+    entry: true
+    route:
+      - to: artifact-check
+    system_prompt: |
+      Start the verify tour in one sentence.
+      Then emit a success envelope via emit_stage_envelope with status: success, a short summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+
+  - id: artifact-check
+    route:
+      - to: command-check
+    system_prompt: |
+      Cover type: artifact (emit list check and after on-disk check).
+      1. Call write_stage_artifact with path note.md and a short nonempty markdown body.
+      2. Call emit_stage_envelope with status: success, a one-sentence summary, artifacts listing the path returned by write_stage_artifact, and payload: {}.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: note-declared
+        type: artifact
+        basename: note.md
+        when: [emit]
+      - id: note-on-disk
+        type: artifact
+        path: note.md
+        nonempty: true
+        when: [after]
+
+  - id: command-check
+    route:
+      - to: checklist-check
+    system_prompt: |
+      Cover type: command. Stageflow runs the declared command after you emit. Do not run it yourself.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: echo-ok
+        type: command
+        run: echo verify-tour-ok
+
+  - id: checklist-check
+    route:
+      - to: payload-check
+    system_prompt: |
+      Cover type: checklist. The attestation must match the declared items exactly.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], payload: {}, and checklist_attestations:
+        - check_id: self-review
+          items:
+            - Tour steps completed
+            - No extra checkout edits
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: self-review
+        type: checklist
+        items:
+          - Tour steps completed
+          - No extra checkout edits
+
+  - id: payload-check
+    route:
+      - to: gate-check
+    system_prompt: |
+      Cover type: payload_schema. Emit a payload that matches io.output.schema.
+      Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: { "ok": true }.
+      Do not call ask_operator. Do not edit the project checkout.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/ok-flag"
+    verify:
+      - id: payload-ok
+        type: payload_schema
+
+  - id: gate-check
+    route:
+      - to: checkout-check
+    gate_kinds: [confirm]
+    system_prompt: |
+      Cover type: gate kind confirm (emit and after).
+      1. Call ask_operator with kind: confirm and message: "Accept to continue the verify tour."
+      2. Wait for the operator to accept. If they reject, ask again. Do not emit until accepted.
+      3. After accept, call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: {}.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/empty"
+    verify:
+      - id: operator-ok
+        type: gate
+        kind: confirm
+        when: [emit, after]
+
+  - id: checkout-check
+    system_prompt: |
+      Cover type: checkout_changes. Edit the project checkout, not a stage artifact.
+      1. Create or overwrite verify-tour-marker.txt at the checkout root (the Project checkout path in this prompt) with one unique line (include a timestamp or random token).
+      2. Call emit_stage_envelope with status: success, a one-sentence summary, artifacts: [], and payload: { "changed_files": ["verify-tour-marker.txt"] }.
+      Do not gitignore that file. Do not commit, push, or delete other files. Do not call ask_operator.
+    io:
+      input:
+        schema:
+          $ref: "#/schemas/empty"
+      output:
+        schema:
+          $ref: "#/schemas/changed"
+    verify:
+      - id: repo-touched
+        type: checkout_changes
+        path_fields: [changed_files]

package/examples/verify-tour/verify-tour.task.yaml

@@ -0,0 +1,11 @@
+id: verify-tour
+goal: Walk each verify type and leave a checkout marker file.
+context: |
+  Verify tour — each stage covers one check type. Payloads and tool calls
+  are spelled in the stage prompts. checkout_changes needs this bound git
+  checkout; Stageflow compares it before and after checkout-check.
+constraints: |
+  Docs and one marker file only. Do not commit or push.
+  One-sentence summaries. Use each prompt's payload and attestations verbatim.
+  Never emit fork_choice. On gate-check, wait for confirm accept before emit.
+checkout: .

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stageflow",
-  "version": "0.25.0",
+  "version": "0.30.0",
   "description": "Stageflow — CLI pipeline runtime for configurable stages on Pi",
   "type": "module",
   "bin": {
@@ -10,6 +10,8 @@
   "files": [
     "dist",
     "skills",
+    "builtin-skills",
+    "examples",
     "README.md",
     "LICENSE"
   ],
@@ -56,6 +58,7 @@
   "devDependencies": {
     "@types/better-sqlite3": "^9.6.0",
     "@types/node": "^26.2.0",
+    "@types/semver": "^7.8.0",
     "tsx": "^4.23.11",
     "typescript": "^7.0.2",
     "vitest": "^4.1.10"
@@ -69,9 +72,14 @@
     "@modelcontextprotocol/node": "^2.0.0",
     "@modelcontextprotocol/server": "^2.0.0",
     "better-sqlite3": "^13.0.3",
+    "croner": "^10.0.1",
+    "imapflow": "^2.1.2",
     "jiti": "^2.7.0",
+    "octokit": "^5.0.5",
     "pi-mcp-adapter": "^2.32.1",
+    "semver": "^7.8.5",
     "typebox": "^1.3.7",
+    "undici": "^7.29.1",
     "yaml": "^2.9.0",
     "zod": "^4.4.3"
   },

package/skills/stageflow/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: stageflow
 description: >-
-  Routes Stageflow work to one job: setup (install, catalog, or provider),
-  session-capture (reuse this chat or a past session), author (a loop the human
-  can explain), run (start, watch, or answer a pipeline), or delegate (a
-  repeating pattern). Use when the user mentions Stageflow, sf, a pipeline,
-  HITL, or a repeating Stageflow workflow.
+  Routes Stageflow work to one job: setup (install, catalog, provider, or
+  optional Docker Compose local try), session-capture (reuse this chat or a past
+  session), author (a loop the human can explain), run (start, watch, or answer
+  a pipeline), or delegate (a repeating pattern). Use when the user mentions
+  Stageflow, sf, a pipeline, HITL, or a repeating Stageflow workflow.
 compatibility: Requires the Stageflow CLI (sf). An MCP host (sf ui or sf mcp) is optional.
 ---
 
@@ -17,7 +17,7 @@ Read the matching job `SKILL.md` and follow it. Do not invent job behavior in th
 
 | Reach this job when | Read |
 |---|---|
-| Install is missing, there is no catalog, or a provider is not logged in | [../stageflow-setup/SKILL.md](../stageflow-setup/SKILL.md) |
+| Install is missing, there is no catalog, a provider is not logged in, or the operator wants Docker Compose local try | [../stageflow-setup/SKILL.md](../stageflow-setup/SKILL.md) |
 | The request should reuse a past session or this chat | [../stageflow-session-capture/SKILL.md](../stageflow-session-capture/SKILL.md) |
 | The request describes a loop the human can explain | [../stageflow-author/SKILL.md](../stageflow-author/SKILL.md) |
 | The request needs to start, watch, or answer a run | [../stageflow-run/SKILL.md](../stageflow-run/SKILL.md) |

package/skills/stageflow/references/control-surface.md

@@ -11,18 +11,26 @@ node ../scripts/detect-host.mjs
 node ../scripts/detect-host.mjs --base-url http://127.0.0.1:3847
 ```
 
-The script `GET`s `{baseUrl}/api/health` (default `http://127.0.0.1:3847`, 1500 ms timeout). **up** means HTTP 200 and parseable JSON. Non-200, non-JSON, or timeout is **down**. This probe is Stageflow host up/down only — it does not detect a coding-agent question UI. Gate presentation lives in [`../../stageflow-run/references/native-question-ui.md`](../../stageflow-run/references/native-question-ui.md).
+The script `GET`s `{baseUrl}/api/health` (default `http://127.0.0.1:3847`, 1500 ms timeout). **up** means HTTP 200 and parseable JSON. Non-200, non-JSON, or timeout is **down**. Health stays Host/Origin-only (no bearer), so loopback probes keep working when a control token is configured. This probe is Stageflow host up/down only — it does not detect a coding-agent question UI. Gate presentation lives in [`../../stageflow-run/references/native-question-ui.md`](../../stageflow-run/references/native-question-ui.md).
 
-Stdout is one line: `up <baseUrl>` or `down <baseUrl>`. Exit `0` when up, `1` when down, `2` on usage error.
+Stdout is one line: `up <baseUrl>` or `down <baseUrl>`, with an optional trailing `bearer` when `STAGEFLOW_CONTROL_TOKEN` or `STAGEFLOW_CONTROL_TOKEN_FILE` is set in this environment (MCP/Compose need `Authorization: Bearer` — see [`../../stageflow-run/references/mcp-call.md`](../../stageflow-run/references/mcp-call.md)). Exit `0` when up, `1` when down, `2` on usage error.
 
-Start a host with `sf ui` or `sf mcp` when the user wants MCP. Do not auto-start one.
+**Health is not auth.** `GET /api/health` is ungated (Host/Origin only — no bearer). Do **not** treat a health 200 as authenticated MCP. Non-loopback and Compose Hosts require a drive bearer (`STAGEFLOW_CONTROL_TOKEN`); MCP and protected API calls need `Authorization: Bearer <drive-token>` when a control token is set. See Stageflow docs: MCP (Access control); Docker and self-hosting — Local try.
+
+Start a host with `sf ui` or `sf mcp` when the user wants MCP. Do not auto-start one. Compose local try is the standing-Host path — see `stageflow-setup` and Stageflow docs: Docker and self-hosting.
 
 ## When the host is up
 
-Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Tool names and payloads live in [docs/mcp.md](../../../docs/mcp.md). Typical talking-job tools: `list_pipelines`, `list_tasks`, `start_run`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `validate`, `describe_pipeline`, `get_health`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`.
+Use MCP tools over the Streamable HTTP endpoint at `{baseUrl}/mcp`. Send `Authorization: Bearer <drive-token>` when `STAGEFLOW_CONTROL_TOKEN` (or a named drive token) is configured. Tool names and payloads live in Stageflow docs: MCP (checkout: [docs/mcp.md](../../../docs/mcp.md)). Typical talking-job tools: `list_pipelines`, `list_tasks`, `start_run`, `run_stage`, `get_run`, `wait_run`, `list_waiting`, `answer_gate`, `decide_feedback_loop`, `get_envelope`, `read_artifact`, `list_checkout_changes`, `get_run_diff`, `read_checkout_file`, `validate`, `describe_pipeline`, `get_health`, `list_providers`, `list_models`, `list_project_mcp`, `probe_project_mcp`, `export_run`, `list_skills`, `list_stage_events`, `get_stage_verification`.
+
+`get_health` returns capacity fields plus `stageflow_home`, `boot_providers` / `providers_live` (prefer `list_providers` for live auth), and an on-demand `disk` breakdown (`runs_bytes`, `worktrees_bytes`, `repos_bytes`, `state_db_bytes`, `a2a_artifacts_bytes`, `free_bytes`) for the durable root. When `slotsAvailable` is `0`, starts may still succeed as queued until `STAGEFLOW_MAX_QUEUED` is full — see `start_run` in the MCP docs.
+
+**Skills cwd ≠ catalog root:** `STAGEFLOW_OPERATOR_CWD` resolves operator skills; MCP/HTTP catalog browse uses seeded ∪ registered `project_root` values. See Stageflow docs: MCP — Skills cwd vs catalog project_root.
+
+Some capabilities stay **CLI-only** (or `docker exec` on a container Host): `sf graph`, `sf migrate-yaml`, `sf skills install` (durable host install; prefer `start_run.skills` for harnesses), A2A config mutate/validate, and provider OAuth login. Provider API keys for Host boot use `STAGEFLOW_PROVIDER_<ID>_API_KEY(_FILE)`, not an MCP login tool. Use the MCP **CLI-only capabilities** decision table (Stageflow docs: MCP) instead of inventing MCP substitutes.
 
 ## When the host is down
 
-Use the `sf` CLI. Command names and flags live in [docs/cli-reference.md](../../../docs/cli-reference.md). Typical talking-job commands: `sf run`, `sf runs waiting`, `sf runs answer`, `sf runs feedback-decide`, `sf runs wait`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
+Use the `sf` CLI. Command names and flags live in Stageflow docs: CLI reference (checkout: [docs/cli-reference.md](../../../docs/cli-reference.md)). Typical talking-job commands: `sf run`, `sf runs waiting`, `sf runs answer`, `sf runs feedback-decide`, `sf runs wait`, `sf validate`, `sf envelope get`, `sf artifact read`, `sf providers`.
 
 Probe before each mutating `sf runs` verb. If the probe is **up** or the command refuses because a host is up, continue that gate via MCP — do not start a second mutating writer, and do not start `sf mcp` as a disposable bridge.

package/skills/stageflow/scripts/detect-host.mjs

@@ -33,6 +33,15 @@ function parseArgs(argv) {
   return { baseUrl };
 }
 
+function clientHasControlToken(env = process.env) {
+  const plain = env.STAGEFLOW_CONTROL_TOKEN;
+  const filePath = env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  return (
+    (plain !== undefined && plain.length > 0) ||
+    (filePath !== undefined && filePath.length > 0)
+  );
+}
+
 async function probe(baseUrl) {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), TIMEOUT_MS);
@@ -50,5 +59,9 @@ async function probe(baseUrl) {
 
 const { baseUrl } = parseArgs(process.argv.slice(2));
 const status = await probe(baseUrl);
-console.log(`${status} ${baseUrl}`);
+const parts = [status, baseUrl];
+if (clientHasControlToken()) {
+  parts.push("bearer");
+}
+console.log(parts.join(" "));
 process.exit(status === "up" ? 0 : 1);

package/skills/stageflow/scripts/detect-host.test.mjs

@@ -7,10 +7,18 @@ import { test } from "node:test";
 
 const script = path.join(path.dirname(fileURLToPath(import.meta.url)), "detect-host.mjs");
 
-function run(baseUrl) {
+function cleanEnv(extra = {}) {
+  const env = { ...process.env };
+  delete env.STAGEFLOW_CONTROL_TOKEN;
+  delete env.STAGEFLOW_CONTROL_TOKEN_FILE;
+  return { ...env, ...extra };
+}
+
+function run(baseUrl, opts = {}) {
   return new Promise((resolve) => {
     const child = spawn(process.execPath, [script, "--base-url", baseUrl], {
       stdio: ["ignore", "pipe", "pipe"],
+      env: opts.env ?? cleanEnv(),
     });
     let stdout = "";
     let stderr = "";
@@ -95,3 +103,23 @@ test("classifies a hung /api/health as down", async () => {
     server.close();
   }
 });
+
+test("notes bearer when STAGEFLOW_CONTROL_TOKEN is set without changing health probe", async () => {
+  const { server, baseUrl } = await listen((req, res) => {
+    assert.equal(req.url, "/api/health");
+    assert.equal(req.headers.authorization, undefined);
+    res.writeHead(200, { "content-type": "application/json" });
+    res.end(JSON.stringify({ ok: true }));
+  });
+  try {
+    const result = await run(baseUrl, {
+      env: cleanEnv({
+        STAGEFLOW_CONTROL_TOKEN: "b".repeat(32),
+      }),
+    });
+    assert.equal(result.status, 0);
+    assert.equal(result.stdout.trim(), `up ${baseUrl} bearer`);
+  } finally {
+    server.close();
+  }
+});

package/skills/stageflow-author/SKILL.md

@@ -35,9 +35,9 @@ 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`, optional `model`, `io`, `verify`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan body `verify` and wiring `on_verify_fail`. When a review can demand changes, include an address-feedback stage before approve/ship.
+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`, optional `model`, `io`, `verify`, and `gate_kinds`. Apply the Anti-patterns section below while mapping. When the human needs hard advance gates, plan body `verify` and wiring `on_verify_fail`. When a stage needs git/`gh`/registry credentials, plan `secrets:` (do not assume ambient Host env). 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, `route` / `entry` wiring (optional `if`, `{ type: loop }`, sealed Clone Chain when the human wants one run per list item), a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages the structure requires.
+**Done when** you have a pipeline id, one stage id per step, `route` / `entry` wiring (optional `if`, `{ type: loop }`, sealed Clone Chain when the human wants one run per list item), a prompt plan per stage, and any `verify` / `on_verify_fail` / remediation stages / `secrets` the structure requires.
 
 ## Anti-patterns
 
@@ -52,7 +52,8 @@ Author these contracts explicitly. They come from long runs that failed after ho
 | Give review blockers a place to land | Wire `review → address-feedback → approve/ship`. Put `verdict` / `blocking_findings` (or equivalent) in the review `io.output.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 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. |
+| Finish publish in the accept attempt | After `artifact_backed` accept: side effects (commit/push/PR) → final artifact → emit in the same attempt. Declare `secrets:` for those side effects; do not assume ambient `GITHUB_TOKEN`. Fix emit/schema errors by re-emitting. |
+| Declare credentials the stage needs | Stages get a curated env — not Host `process.env`. Put `secrets:` on the stage body or pipeline entry. Never put `STAGEFLOW_CONTROL_TOKEN` / read tokens in `secrets:`. See [`catalog-mapping.md`](references/catalog-mapping.md#stage-secrets). |
 | Author a sealed Clone Chain | One run per list item is emitter → clone child → Join. Never write `clonable`, `clone_forks`, or emit-time `skip` / `once` / `fanout`. See [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain). |
 
 Throwaway checkout deliverables (HTML spike, scratch file): prompt builtin `write` at a checkout-relative path, `artifacts: []` on emit, path in `payload`.

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

@@ -114,6 +114,22 @@ See [YAML catalog — Clone Chain](../../../docs/yaml-catalog.md#clone-chain) an
 
 Do not author `clonable`, `clone_actions`, or envelope `clone_forks`. Do not put `clone_cap` / `clone_mode` on a stage that is not a Clone Chain emitter.
 
+## Stage secrets
+
+Stages receive a **curated** environment — not Host `process.env`. Credentials reach a stage only via `secrets:` on the stage body or the pipeline `uses:` entry. Do not assume ambient `GITHUB_TOKEN` in the stage.
+
+```yaml
+secrets:
+  - GITHUB_TOKEN                      # GIT_ASKPASS + materialised token file (no raw env)
+  - { name: GITHUB_TOKEN, as: env }   # when gh/MCP need the env var (askpass still set)
+```
+
+`GITHUB_TOKEN` / `GH_TOKEN` default to askpass (no raw env). Prefer `{ name: GITHUB_TOKEN, as: env }` when `gh` or MCP needs the env var — askpass remains set for plain HTTPS `git`. Never put `STAGEFLOW_CONTROL_TOKEN` or read tokens in `secrets:` (never grantable). The Host still needs `GITHUB_TOKEN` / `GH_TOKEN` for clone/fetch materialize even for public repos; that Host token is separate from stage grants.
+
+When a publish stage calls `gh`, add `requires: [{ tool: gh }]`. The base Docker image has no `gh` — operators derive an image. Stageflow never installs tools from `requires:`.
+
+Full reference: [YAML catalog — Stage secrets](../../../docs/yaml-catalog.md#stage-secrets), [migration-stage-environment.md](../../../docs/migration-stage-environment.md). Legacy contract-key catalogs → `sf migrate-yaml` (laptop / `docker exec`, not MCP).
+
 ## Models
 
 Confirm providers before writing. After fan-out, give every sibling the same configured `model` unless the human asks for different ones. Prefer a reliable configured model on side-effecting final stages.

package/skills/stageflow-author/references/catalog-write-conventions.md

@@ -20,7 +20,7 @@ One directory (or the project root) holds:
 | `<pipeline-id>.pipeline.yaml` | `id` matching the filename stem; `stages:` array of object entries |
 | `<stage-id>.yaml` | `id`, `system_prompt`; `model` when not inherited; required `io.input.schema` and `io.output.schema`; `verify` / `gate_kinds` when the step needs them |
 
-Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). At least one root marks `entry: true`. Sources list forward `route: [{ to: <id> }, …]`. Optional `on:` is skip-cascade policy (default succeeded-only); it does not launch from skipped/failed. Optional `if` gates a successor after the source succeeds (predicate on required `io.output.schema` fields). A review that can send work back adds `{ type: loop, to, max_replays, on_max_replays, replay_session }` inside `route`. A Clone Chain emitter puts `clone_cap` and `clone_mode` on that **pipeline entry**, never on the reusable stage body. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. Filename stem matches `id`. Optional pipeline-root `model` fills stages that omit `model`. Sequencing rules: [`catalog-mapping.md`](catalog-mapping.md). Catalog load rejects `needs`, `fork`, and `feedback_loop` as YAML keys.
+Each pipeline stage entry has `id` and `uses: ./<id>.yaml` (path relative to the pipeline file). At least one root marks `entry: true`. Sources list forward `route: [{ to: <id> }, …]`. Optional `on:` is skip-cascade policy (default succeeded-only); it does not launch from skipped/failed. Optional `if` gates a successor after the source succeeds (predicate on required `io.output.schema` fields). A review that can send work back adds `{ type: loop, to, max_replays, on_max_replays, replay_session }` inside `route`. A Clone Chain emitter puts `clone_cap` and `clone_mode` on that **pipeline entry**, never on the reusable stage body. Put `on_verify_fail` on the pipeline entry when after-phase `verify` should repair or wait for an operator. `secrets` and `requires` may sit on the stage body or the `uses:` wrapper — stages get a curated env, not Host ambient credentials; see [`catalog-mapping.md`](catalog-mapping.md#stage-secrets). Filename stem matches `id`. Optional pipeline-root `model` fills stages that omit `model`. Sequencing rules: [`catalog-mapping.md`](catalog-mapping.md). Catalog load rejects `needs`, `fork`, and `feedback_loop` as YAML keys.
 
 ## Collisions
 

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

@@ -1,6 +1,6 @@
 # Stage prompt template
 
-Every external stage file has `id`, `system_prompt`, `io.input.schema`, and `io.output.schema`. Filename stem matches `id`. `model` is optional when the pipeline or `stageflow.yaml` supplies it — otherwise set it on the stage. Default when writing a concrete string 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 fan-out should use the same configured model family unless the human asks otherwise.
+Every external stage file has `id`, `system_prompt`, `io.input.schema`, and `io.output.schema`. Filename stem matches `id`. `model` is optional when the pipeline or `stageflow.yaml` supplies it — otherwise set it on the stage. Prefer the **configured** provider's model id (`sf providers status` — use that family's default, e.g. `openrouter/auto` or `anthropic/claude-sonnet-4-5` only when that provider is configured). When no provider is configured or more than one is, write a loud placeholder `CHANGE_ME/<provider-model>` and stop for the human — do not silently hardcode Anthropic. 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 fan-out should use the same configured model family unless the human asks otherwise.
 
 ## Base
 
@@ -17,7 +17,7 @@ system_prompt: |
   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
+model: CHANGE_ME/<provider-model>
 io:
   input:
     schema:
@@ -27,7 +27,7 @@ io:
       type: object
 ```
 
-The prompt has no `ask_operator` line. It ends on the `emit_stage_envelope` instruction. Call `emit_stage_envelope` once per attempt.
+Replace `CHANGE_ME/<provider-model>` with the configured provider's model id before validate/run (Anthropic example only when that provider is configured).
 
 When the pipeline entry will carry after-phase `verify` with `type: artifact`, add this line after the goal:
 
@@ -81,7 +81,7 @@ system_prompt: |
      with artifact_backed in this same stage. Do not complete yet.
   4. Call emit_stage_envelope with an advancing success status only after the
      operator accepts. Never emit before accept.
-model: anthropic/claude-sonnet-4-5
+model: CHANGE_ME/<provider-model>
 io:
   input:
     schema: