stageflow 0.23.0 → 0.27.0

package/examples/generic-fan-in/research.yaml

@@ -0,0 +1,45 @@
+id: research
+system_prompt: |
+  You are the research branch of a diamond join. Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask the operator to reply with
+     exactly one of:
+       ok <finding>
+       fail
+     Tell them <finding> is one token (letters, digits, or hyphen). Examples:
+     ok glaciers
+     fail
+  2. Wait for the operator answer. Do not emit before you have that answer.
+  3. If the answer is fail (optionally with surrounding whitespace), emit
+     emit_stage_envelope with status failure, a short summary that research
+     failed, artifacts [], and no payload.
+  4. If the answer is ok followed by a finding token:
+     emit status success, artifacts [], payload { "finding": "<that token>" },
+     and a summary that includes the word research and the finding token.
+     Use the token after ok as-is; do not invent a different word.
+  5. If the answer is ok with no token, or anything else, emit status failure
+     explaining the reply was not ok <finding> or fail.
+
+  Rules:
+  - Never emit before the operator answers.
+  - Do not call ask_operator more than once.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - finding
+      properties:
+        finding:
+          type: string
+gate_kinds:
+  - free_text

package/examples/generic-fan-in/synthesize.yaml

@@ -0,0 +1,66 @@
+id: synthesize
+system_prompt: |
+  You are the diamond join. The prompt includes priorEnvelopesByStage — a
+  record keyed in YAML declaration order (research, then validation).
+  priorEnvelope is null. There is no clone-list priorEnvelopes field.
+
+  Call emit_stage_envelope exactly once. Do not call ask_operator.
+
+  1. Read priorEnvelopesByStage.research and priorEnvelopesByStage.validation.
+     Do not invent keys. Do not reorder keys.
+  2. For each parent, copy status, summary, and payload.finding when present.
+     If a parent is a failure envelope with no finding, omit finding.
+  3. Emit status success, artifacts [], and payload:
+     {
+       "received": {
+         "research": { "status": "…", "summary": "…", "finding": "…" },
+         "validation": { "status": "…", "summary": "…", "finding": "…" }
+       }
+     }
+     Include finding only when that parent payload had it.
+  4. Summary must mention both parent keys and their status values, for
+     example: received research=success glaciers; validation=success citations
+
+  Rules:
+  - Copy from priorEnvelopesByStage only. Do not use a single priorEnvelope.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - received
+      properties:
+        received:
+          type: object
+          required:
+            - research
+            - validation
+          properties:
+            research:
+              type: object
+              required:
+                - status
+                - summary
+              properties:
+                status:
+                  type: string
+                summary:
+                  type: string
+                finding:
+                  type: string
+            validation:
+              type: object
+              required:
+                - status
+                - summary
+              properties:
+                status:
+                  type: string
+                summary:
+                  type: string
+                finding:
+                  type: string

package/examples/generic-fan-in/validation.yaml

@@ -0,0 +1,45 @@
+id: validation
+system_prompt: |
+  You are the validation branch of a diamond join. Follow these steps exactly:
+
+  1. Call ask_operator with kind free_text. Ask the operator to reply with
+     exactly one of:
+       ok <finding>
+       fail
+     Tell them <finding> is one token (letters, digits, or hyphen). Examples:
+     ok citations
+     fail
+  2. Wait for the operator answer. Do not emit before you have that answer.
+  3. If the answer is fail (optionally with surrounding whitespace), emit
+     emit_stage_envelope with status failure, a short summary that validation
+     failed, artifacts [], and no payload.
+  4. If the answer is ok followed by a finding token:
+     emit status success, artifacts [], payload { "finding": "<that token>" },
+     and a summary that includes the word validation and the finding token.
+     Use the token after ok as-is; do not invent a different word.
+  5. If the answer is ok with no token, or anything else, emit status failure
+     explaining the reply was not ok <finding> or fail.
+
+  Rules:
+  - Never emit before the operator answers.
+  - Do not call ask_operator more than once.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - brief
+      properties:
+        brief:
+          type: string
+  output:
+    schema:
+      type: object
+      required:
+        - finding
+      properties:
+        finding:
+          type: string
+gate_kinds:
+  - free_text

package/examples/github-release/README.md

@@ -0,0 +1,78 @@
+# github-release
+
+Dogfood release automation: draft operator-facing GitHub release notes, then publish with `gh`. This is an **ops / release example** — not SDLC planning.
+
+Stageflow uses this catalog in `.github/workflows/publish.yml` and `release.yml` when publishing new npm versions.
+
+One GitHub Release is created for the current tag. The notes body includes **every CHANGELOG version since the last GitHub Release**, not only the latest `package.json` bump. A publish that jumps from `0.3.0` to `0.8.0` therefore includes headings for `0.4.0` through `0.8.0`. Intermediate versions are not tagged or published as extra GitHub Releases.
+
+## Layout
+
+| Path | Role |
+|------|------|
+| `github-release.pipeline.yaml` | Two-stage linear pipeline |
+| `draft-release-notes.yaml` | Collect changelog, write `RELEASE_NOTES.md` artifact |
+| `publish-github-release.yaml` | `gh release create` from prior artifact |
+| `github-release.task.yaml` | Task bound at run time |
+
+CI helpers: `scripts/release-range.mjs` resolves previous from published GitHub Releases (git tags if `gh` is unavailable) and extracts the CHANGELOG slice.
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed
+- **Cursor** (`cursor/composer-2-5`) — set `CURSOR_API_KEY` and install `pi-cursor-sdk` (`pi install npm:pi-cursor-sdk`, or `npm i --prefix ~/.pi/agent/npm pi-cursor-sdk`)
+- **`gh` CLI** and `GH_TOKEN` or `GITHUB_TOKEN` for publish stage
+- Git checkout of the Stageflow repo (stages read version/tags from the bound checkout)
+
+Optional env vars (set by publish workflow): `RELEASE_VERSION`, `RELEASE_TAG`, `RELEASE_PREVIOUS`, `RELEASE_CHANGELOG_SLICE`, `GITHUB_SHA`, `DRY_RUN=1` to skip actual release creation.
+
+`RELEASE_PREVIOUS` is the last published GitHub Release version, not `HEAD^` `package.json`. `RELEASE_CHANGELOG_SLICE` is a markdown file of CHANGELOG sections in that range (workflows write `changelog-slice.md` before `sf run`).
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --strict
+export CURSOR_API_KEY=…
+export GH_TOKEN=…
+CURRENT="$(node -p "require('./package.json').version")"
+PREVIOUS="$(node scripts/release-range.mjs previous --current "$CURRENT")"
+if [ -n "$PREVIOUS" ]; then
+  node scripts/release-range.mjs changelog --after "$PREVIOUS" --through "$CURRENT" > changelog-slice.md
+else
+  node scripts/release-range.mjs changelog --through "$CURRENT" > changelog-slice.md
+fi
+export RELEASE_VERSION="$CURRENT" RELEASE_TAG="v${CURRENT}" RELEASE_PREVIOUS="$PREVIOUS" RELEASE_CHANGELOG_SLICE="$PWD/changelog-slice.md"
+sf run \
+  --pipeline examples/github-release/github-release.pipeline.yaml \
+  --task examples/github-release/github-release.task.yaml \
+  --checkout "$PWD"
+```
+
+For a dry run (no GitHub release created):
+
+```bash
+DRY_RUN=1 sf run \
+  --pipeline examples/github-release/github-release.pipeline.yaml \
+  --task examples/github-release/github-release.task.yaml \
+  --checkout "$PWD"
+```
+
+## Repair published notes
+
+If a GitHub Release was published with only the latest version's notes, run **Repair GitHub Release notes** from the Actions tab (`workflow_dispatch`). It overwrites that release's body with every CHANGELOG section since the previous GitHub Release. It does not create tags.
+
+| Input | Effect |
+|-------|--------|
+| *(empty)* | Repair the latest GitHub Release (closes the current `v0.8.0` gap) |
+| `tag` | Repair one tag (`v0.8.0` or `0.8.0`) |
+| `all` | Repair every published GitHub Release |
+| `dry_run` | Print notes in the job log; do not edit GitHub |
+
+Use the branch that contains `scripts/release-range.mjs` (this change must be on the branch you run). Locally:
+
+```bash
+node scripts/release-range.mjs repair --dry-run true
+node scripts/release-range.mjs repair --tag v0.8.0
+```

package/examples/github-release/draft-release-notes.yaml

@@ -0,0 +1,64 @@
+id: draft-release-notes
+system_prompt: |
+  Do exactly one thing: write GitHub release notes for this publish.
+
+  The bound checkout is the Stageflow git repository (agent cwd). Read
+  RELEASE_VERSION, RELEASE_TAG, RELEASE_PREVIOUS, and
+  RELEASE_CHANGELOG_SLICE from the environment when they are set.
+
+  RELEASE_PREVIOUS is the last published GitHub Release (or last v* git
+  tag), not the previous package.json bump. If it is missing, read
+  version from package.json, use tag v<version>, and resolve previous
+  the same way: last GitHub Release, else latest v* git tag that is
+  strictly older than the current version. Do not use HEAD^ package.json
+  as previous.
+
+  Notes must cover every version after previous through current,
+  inclusive. A jump from 0.3.0 to 0.8.0 must include 0.4.0, 0.5.0,
+  0.6.0, 0.7.0, and 0.8.0 as separate headings. Do not collapse the
+  range into the latest version only.
+
+  Source of truth for those sections:
+  - If RELEASE_CHANGELOG_SLICE is set, read that file first (absolute
+    or repo-relative). Keep every ## [x.y.z] section it contains.
+  - Else read CHANGELOG.md and take every ## [x.y.z] heading where
+    version is greater than previous and less than or equal to current.
+  You may polish wording for GitHub (short summary, Features / Fixes /
+  Docs) but do not drop a version or invent commits, PRs, or features.
+  If CHANGELOG is missing a version in the range, fill that version
+  from git log v$PREVIOUS..HEAD (or the first commit of previous
+  through HEAD). You may also use gh to list merged PRs in that range.
+
+  Write RELEASE_NOTES.md via write_stage_artifact. Newest version first.
+  Not a raw git log dump. Not "bumped the version" as the only content.
+  Do not create a git tag. Do not call gh release create. Do not call
+  ask_operator. Do not stop after a chat reply.
+
+  Call emit_stage_envelope exactly once with status success, that artifact
+  path, a one-sentence summary, and a payload matching the stage schema.
+  included_versions lists every x.y.z heading in the notes, newest first.
+model: cursor/composer-2-5
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - version
+        - tag
+        - previous_version
+        - included_versions
+      properties:
+        version:
+          type: string
+        tag:
+          type: string
+        previous_version:
+          type: string
+        included_versions:
+          type: array
+          items:
+            type: string
+      additionalProperties: false

package/examples/github-release/github-release.pipeline.yaml

@@ -0,0 +1,11 @@
+id: github-release
+stages:
+  - id: draft-release-notes
+    entry: true
+    route:
+      - to: publish-github-release
+    uses: ./draft-release-notes.yaml
+  - id: publish-github-release
+    uses: ./publish-github-release.yaml
+    secrets:
+      - GITHUB_TOKEN

package/examples/github-release/github-release.task.yaml

@@ -0,0 +1,13 @@
+id: github-release
+goal: Draft operator-facing GitHub release notes for every version since the last GitHub Release, then publish them as one GitHub Release for the current tag.
+context: |
+  Bound checkout is the Stageflow repository. Current version, tag,
+  previous published GitHub Release, and optional changelog slice path
+  are in RELEASE_VERSION, RELEASE_TAG, RELEASE_PREVIOUS, and
+  RELEASE_CHANGELOG_SLICE when those env vars are set; otherwise read
+  them from package.json, git tags / GitHub Releases, and CHANGELOG.md.
+constraints: |
+  No HITL. Do not call ask_operator. Stage 1 writes notes that include
+  a heading for every CHANGELOG version after previous through current.
+  Stage 2 only publishes those notes with gh for the current tag. Do
+  not use GitHub auto-generated notes. Do not create extra tags.

package/examples/github-release/publish-github-release.yaml

@@ -0,0 +1,64 @@
+id: publish-github-release
+system_prompt: |
+  Do exactly one thing: publish the prior stage's release notes as a
+  GitHub Release.
+
+  Use the prior envelope for version, tag, previous_version, and the
+  RELEASE_NOTES.md artifact path. Read that file from the factory run
+  workspace (STAGEFLOW_RUN_WORKSPACE plus the run-relative artifact
+  path). Do not rewrite or regenerate the notes. Do not call
+  --generate-notes. Do not call ask_operator.
+
+  Target commit is GITHUB_SHA if set, otherwise git rev-parse HEAD.
+  Auth uses GIT_ASKPASS from a declared secrets: [GITHUB_TOKEN] grant
+  (file-backed helper — not ambient GH_TOKEN/GITHUB_TOKEN). gh is on PATH.
+
+  If DRY_RUN is 1, do not create the release. Write publish.md via
+  write_stage_artifact recording the gh command you would have run,
+  then emit success with published false and html_url empty.
+
+  Otherwise run:
+  gh release create "$TAG" --title "$TAG" --target "$SHA" --notes-file "$NOTES_PATH"
+  Confirm with gh release view. Write publish.md via write_stage_artifact
+  with the tag and html_url. If the release already exists, emit status
+  failure. Do not stop after a chat reply.
+
+  Call emit_stage_envelope exactly once with status, that artifact path,
+  a one-sentence summary, and a payload matching the stage schema.
+model: cursor/composer-2-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - version
+        - tag
+        - previous_version
+        - included_versions
+      properties:
+        version:
+          type: string
+        tag:
+          type: string
+        previous_version:
+          type: string
+        included_versions:
+          type: array
+          items:
+            type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object
+      required:
+        - tag
+        - published
+        - html_url
+      properties:
+        tag:
+          type: string
+        published:
+          type: boolean
+        html_url:
+          type: string
+      additionalProperties: false

package/examples/hello-world/README.md

@@ -0,0 +1,28 @@
+# hello-world
+
+Minimal single-stage pipeline. Domain-neutral — the stage id and prompts are yours to define.
+
+## What this demonstrates
+
+- **`task.input` ↔ entry `io.input.schema`** — `my-task.task.yaml` supplies a structured `input` object; the entry stage (`research.yaml`) declares matching `io.input.schema`.
+- **Unmet entry input** — if the entry stage declares `io.input` and the task omits `input`, `sf validate` of each file alone still succeeds; start-run / `preparePipeline` warn with `task.entry_input_unmet` and continue (existing product behavior).
+
+This catalog uses `io` only (no `verify` / `on_verify_fail`). For upgrading older field names, see [YAML catalog — Upgrading older catalogs](../../docs/yaml-catalog.md#upgrading-older-catalogs).
+
+## Prerequisites
+
+- Node.js ≥ 20, Stageflow installed (`npm i -g stageflow`)
+- A Pi-compatible provider connected via `sf ui` or `sf providers login`
+
+## Commands
+
+From the **repository git root**:
+
+```bash
+sf validate --pipeline examples/hello-world/hello.pipeline.yaml --strict
+sf run \
+  --pipeline examples/hello-world/hello.pipeline.yaml \
+  --task examples/hello-world/my-task.task.yaml
+```
+
+Use `sf ui` (from any subdirectory) to watch the run and inspect the stage envelope.

package/examples/hello-world/hello.pipeline.yaml

@@ -0,0 +1,4 @@
+id: hello
+stages:
+  - id: research
+    uses: ./research.yaml

package/examples/hello-world/my-task.task.yaml

@@ -0,0 +1,6 @@
+id: my-task
+goal: Draft a one-page brief on a topic of your choice
+context: Domain-neutral hello-world run
+constraints: Docs only; no implementation code
+input:
+  topic: Calendar apps for personal productivity

package/examples/hello-world/research.yaml

@@ -0,0 +1,18 @@
+id: research
+system_prompt: |
+  Summarize the task goal for the given topic and list open questions.
+  The topic arrives as task input (and as this stage's io.input payload).
+model: anthropic/claude-sonnet-4-5
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - topic
+      properties:
+        topic:
+          type: string
+      additionalProperties: false
+  output:
+    schema:
+      type: object

package/examples/mcp-hitl-tour/README.md

@@ -0,0 +1,113 @@
+# mcp-hitl-tour
+
+MCP-first walkthrough: **HITL**, an ungated **fan-out/join**, a small **Clone
+Chain**, a **guaranteed feedback loop** that parks for `decide_feedback_loop`,
+and **artifacts** you can read back with `read_artifact`.
+
+Domain-neutral — it writes a short brief. Use it to see how an operator-host
+MCP client starts a run, asks the operator at each HITL gate, inspects a
+stage, and decides the loop.
+
+This DAG does **not** exclusive-route. Exclusive Route `if` into a shared join
+can leave the unused arm `pending`, so the join never becomes runnable. Here
+both arms always run; `polish` waits for two successes, not a skip.
+
+```
+start_run → wait_run → answer_gate (intake) → wait_run
+         → review send_back → polish replay → review send_back
+         → decide_feedback_loop → wait_run until terminal
+         → get_run / list_stage_events / get_envelope / read_artifact
+```
+
+## What it exercises
+
+| Stage | Why it is here |
+|-------|----------------|
+| `intake` | `gate_kinds: [free_text]` — MCP `answer_gate`. Emits `payload.audience`. Writes `intake.md`. |
+| Fan-out | Intake lists `emit-angles` and `draft-short` with **no** `if`. Both always run. |
+| `emit-angles` → `draft-angle` → `gather` | Sequential Clone Chain, `clone_cap: 2`. Clone workers write `angle.md`. |
+| `draft-short` | Parallel short take. Writes `short.md`. |
+| `polish` | Join of `gather` and `draft-short`. Writes `brief.md`. Loop target. |
+| `review` | Always `send_back` polish. `{ type: loop }`, `max_replays: 1`, `on_max_replays: wait_for_human` — one replay, then operator HITL. |
+| `ship` | `replay_safe: false`. Writes `ship.md`. |
+
+`describe_pipeline` should show `entry`, clone fields, `feedback_loop`,
+`gate_kinds` on intake, and `replay_safe` on ship. It should **not** show
+inbound `if` on the intake children.
+
+```
+intake (free_text HITL)
+  ├─ emit-angles → draft-angle×2 → gather ─┐
+  └─ draft-short ──────────────────────────┴→ polish ► review ⇄ polish ► ship
+```
+
+## Prerequisites
+
+- This Stageflow checkout, built (`npm run build && npm run ui:build`)
+- Provider auth connected
+- An MCP client (Cursor on **another** project is fine) pointed at `http://127.0.0.1:3847/mcp`
+
+Host the catalog from **this git root** so `list_pipelines` includes this example:
+
+```bash
+cd /path/to/stageflow
+node dist/cli.js ui
+```
+
+## MCP walkthrough
+
+From a consumer Cursor chat with Stageflow MCP loaded:
+
+1. `describe_pipeline` `{ "pipeline": "examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml" }`
+2. `start_run` with
+   - `pipeline`: `examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml`
+   - `task_path`: `examples/mcp-hitl-tour/mcp-hitl-tour.task.yaml`
+3. `wait_run` `{ "runId": "…", "until": "waiting" }`
+4. Present the intake prompt to the operator. `answer_gate` — `stageId` is
+   `intake`, `kind` is `free_text`, `text` is `operators` or `executives`,
+   `promptId` from the pending prompt. Do not invent the reply.
+5. `wait_run` `{ "runId": "…", "until": "waiting" }` — review sends the brief
+   back once (polish replays), then parks (`waiting_kind` is
+   `feedback_loop_decision`)
+6. Present the loop decision to the operator. `decide_feedback_loop` with
+   `decision: "continue"` (or `extend` / `abandon`)
+7. `wait_run` `{ "runId": "…", "until": "terminal" }`
+8. `get_run` — artifact paths, `total_cost_usd` when the store has it
+9. `read_artifact` `intake.md` / `short.md` / `angles-brief.md` / `brief.md` /
+   `ship.md` (use the paths `get_run` returned)
+10. `list_stage_events` `{ "runId": "…", "stageId": "intake" }`
+11. `get_envelope` `{ "runId": "…", "stageId": "intake" }` — `payload.audience`
+    matches the gate reply
+
+The exhaust task (`mcp-hitl-tour-exhaust.task.yaml`) is the same walkthrough.
+
+## Validate
+
+```bash
+node dist/cli.js validate --pipeline examples/mcp-hitl-tour/mcp-hitl-tour.pipeline.yaml --strict
+```
+
+## Layout
+
+```
+examples/mcp-hitl-tour/
+  mcp-hitl-tour.pipeline.yaml
+  mcp-hitl-tour.task.yaml
+  mcp-hitl-tour-exhaust.task.yaml
+  intake.yaml
+  emit-angles.yaml
+  draft-angle.yaml
+  gather.yaml
+  draft-short.yaml
+  polish.yaml
+  review.yaml
+  ship.yaml
+```
+
+## References
+
+- [MCP](../../docs/mcp.md)
+- [HITL](../../docs/hitl.md)
+- [YAML catalog — Generic fan-in](../../docs/yaml-catalog.md#generic-fan-in)
+- [YAML catalog — Clone Chain](../../docs/yaml-catalog.md#clone-chain)
+- [YAML catalog — Feedback loops](../../docs/yaml-catalog.md#feedback-loops)

package/examples/mcp-hitl-tour/draft-angle.yaml

@@ -0,0 +1,33 @@
+id: draft-angle
+system_prompt: |
+  Draft one clone angle. Your io.input is a single Angle (id, title, topic).
+  Write 5–8 sentences. Do not cover the other clone's title.
+
+  1. Call write_stage_artifact with path angle.md for this id and title.
+  2. Emit success with artifacts [angle.md] and payload
+     { "id": "<input id>", "title": "<input title>" }.
+io:
+  input:
+    schema:
+      $ref: "#/schemas/Angle"
+  output:
+    schema:
+      type: object
+      required: [id, title]
+      properties:
+        id:
+          type: string
+        title:
+          type: string
+verify:
+  - id: angle-declared
+    type: artifact
+    basename: angle.md
+    when:
+      - emit
+  - id: angle-on-disk
+    type: artifact
+    path: angle.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/draft-short.yaml

@@ -0,0 +1,32 @@
+id: draft-short
+system_prompt: |
+  Write one short take on the intake topic for payload.audience.
+
+  This arm always runs alongside the Clone Chain. Do not skip clone work;
+  just write this one-page take.
+
+  1. Call write_stage_artifact with path short.md (one page, headings allowed).
+  2. Emit success with artifacts [short.md] and payload { "kind": "short" }.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [kind]
+      properties:
+        kind:
+          type: string
+verify:
+  - id: short-declared
+    type: artifact
+    basename: short.md
+    when:
+      - emit
+  - id: short-on-disk
+    type: artifact
+    path: short.md
+    nonempty: true
+    when:
+      - after

package/examples/mcp-hitl-tour/emit-angles.yaml

@@ -0,0 +1,45 @@
+id: emit-angles
+system_prompt: |
+  Split the intake topic into exactly two short angles for sequential clone
+  workers. Do not write the briefs here.
+
+  1. Read payload.topic from the intake envelope.
+  2. Invent two non-overlapping angles (id kebab-case, title, same topic).
+  3. Call write_stage_artifact with path angles.md listing both ids and titles.
+  4. Emit exactly one success envelope with artifacts [angles.md] and payload:
+     {
+       "items": [
+         { "id": "…", "title": "…", "topic": "<intake topic>" },
+         { "id": "…", "title": "…", "topic": "<intake topic>" }
+       ],
+       "summary": "two angles"
+     }
+
+  Emit exactly two items. Never zero, never more than two.
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required: [items]
+      properties:
+        items:
+          type: array
+          items:
+            $ref: "#/schemas/Angle"
+        summary:
+          type: string
+verify:
+  - id: angles-declared
+    type: artifact
+    basename: angles.md
+    when:
+      - emit
+  - id: angles-on-disk
+    type: artifact
+    path: angles.md
+    nonempty: true
+    when:
+      - after