stageflow 0.25.0 → 0.30.0

package/examples/ship-feature/feat-review.yaml

@@ -0,0 +1,109 @@
+id: feat-review
+system_prompt: |
+  Answer your assigned review questions against the actual code and record a
+  verdict with file:line evidence. This stage is strictly read-only: do not
+  edit files, rerun formatters that write files, commit, push, or open a
+  pull request.
+
+  Reading upstream evidence. The user prompt contains a line
+  "Factory run workspace: <absolute path>". Prior artifacts arrive in the
+  prior envelope's artifacts[] as run-relative paths; read each one at
+  <Factory run workspace>/<artifact path>. implementation-plan.md is the
+  authoritative statement of what was approved, and implementation-report.md
+  is the authoritative record of what actually changed and how it was
+  validated. Prose summaries are secondary.
+
+  Definition of done, checked before you emit:
+  - You read every path in your assigned paths list in the checkout, plus
+    implementation-plan.md and implementation-report.md at their resolved
+    absolute paths.
+  - Every question in your assigned questions list has an answer recorded in
+    review.md.
+  - review.md was written through write_stage_artifact and appears in the
+    emitted artifacts list, alongside all inherited evidence artifacts.
+  - Every finding that would block shipping appears in blocking_findings.
+  - The checkout working tree is unchanged by this stage.
+
+  1. Read the task and your assigned prior envelope payload: review_id,
+     objective, paths, questions, and constraints. Print the current diff
+     (git diff) in the checkout.
+  2. Inspect the implementation and tests deeply enough to answer every
+     assigned question. Read the real files at the assigned paths; do not
+     answer from the diff hunk alone when surrounding code decides
+     correctness.
+  3. Classify actionable findings as blocking or non-blocking. A blocking
+     finding is a correctness, regression, missing-test, security, or
+     compatibility problem that should prevent shipping. Any such finding
+     MUST appear in blocking_findings, even when verdict is pass. Describing
+     a correctness or regression problem only in prose findings while
+     leaving blocking_findings empty is a contract violation; if you believe
+     a described problem is not shipping-blocking, say why in findings and
+     keep the verdict consistent with that.
+  4. Call write_stage_artifact with path review.md containing verdict pass
+     or changes_required, the answer to each assigned question, findings,
+     evidence, and concrete remediation for each blocking finding.
+  5. Emit exactly one success envelope whenever the review completed, even
+     when changes are required. List review.md plus all inherited evidence
+     artifacts. Put the verdict and blockers in the payload so the fixup
+     stage receives every review. Use failure only if the review itself
+     could not be performed.
+
+  Payload discipline. evidence entries must cite concrete references such as
+  path/to/file.ts:120-134 or a test node id; "see diff", "the
+  implementation", n/a, none, tbd, and pending are contract violations.
+  findings, suggestions, and blocking_findings must hold substantive
+  entries, never placeholders. Writing review.md is never a substitute for
+  actually reading the code and answering the questions.
+
+  Summary authoring. The emitted summary describes outcomes and state for
+  the fixup stage: your review_id, verdict, whether blocking findings exist,
+  and what they are. Do not restate this stage's own prohibitions or scope
+  limits in the summary. Downstream stages receive this summary verbatim and
+  will mistake stage-local prohibitions for their own instructions.
+model: omniroute/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - review_id
+        - verdict
+        - findings
+        - blocking_findings
+        - suggestions
+        - evidence
+      properties:
+        review_id:
+          type: string
+        verdict:
+          type: string
+          enum:
+            - pass
+            - changes_required
+        findings:
+          type: array
+          items:
+            type: string
+        blocking_findings:
+          type: array
+          items:
+            type: string
+        suggestions:
+          type: array
+          items:
+            type: string
+        evidence:
+          type: array
+          items:
+            type: string
+verify:
+  - id: review
+    type: artifact
+    path: review.md
+    nonempty: true
+    when:
+      - after
+gate_kinds: []

package/examples/ship-feature/feat-ship.yaml

@@ -0,0 +1,203 @@
+id: feat-ship
+system_prompt: |
+  Produce one operator-approved ship-package.md that states the verified
+  facts of the change, then — once the operator accepts it — push the
+  current branch and open the pull request yourself in this same stage. Do
+  not edit source files. The checkout is already on the correct feature
+  branch; never create, rename, or switch branches.
+
+  Reading upstream evidence. The user prompt contains a line "Factory run
+  workspace: <absolute path>". Prior artifacts arrive in the prior
+  envelope's artifacts[] as run-relative paths; read each one at
+  <Factory run workspace>/<artifact path>. implementation-report.md is the
+  authoritative record of what was changed and how it was validated,
+  implementation-plan.md of what was approved, review-feedback-report.md of
+  what feat-address-feedback fixed after review, and each feat-review
+  envelope/review.md of what each reviewer originally found. Prose summaries
+  are secondary.
+
+  Trust but verify feat-address-feedback. Its report is a claim, not proof
+  by itself: cross-check addressed_all_blocking against the original
+  feat-review envelopes' blocking_findings and confirm the specific
+  checks they cited actually pass now, rather than accepting the claim at
+  face value.
+
+  publish_repo and the base branch are exactly what the task goal/context
+  name as the ship target; never guess or invent one. If the task does not
+  explicitly name a target repository, emit failure instead of guessing.
+
+  Definition of done, checked before you emit:
+  - Every feat-review envelope, its review.md, and
+    review-feedback-report.md have been read.
+  - ship-package.md was written through write_stage_artifact and appears in
+    the emitted artifacts list, and contains the PR title, PR body, tests
+    run with their results, changed files, and the exact publish commands.
+  - changed_files matches git diff --name-only in the checkout against the
+    branch's merge base.
+  - tests are the commands and node ids recorded in the implement/review
+    evidence.
+  - publish_repo and base_branch are exactly what the task names as the ship
+    target, and the artifact says so explicitly.
+  - head_branch is the checkout's actual current branch (git rev-parse
+    --abbrev-ref HEAD) — never a branch you created.
+  - The operator accepted the package through the artifact_backed gate
+    before any publish command runs.
+  - opened is true only if gh pr view confirms the PR exists after you
+    created it; pull-request.md was written through write_stage_artifact and
+    appears in the emitted artifacts list.
+
+  1. Read every feat-review envelope/artifact, review-feedback-
+     report.md, the task, implementation-plan.md, and
+     implementation-report.md via the recipe above. Run git rev-parse
+     --abbrev-ref HEAD, git diff --name-only, and git diff --stat in the
+     checkout.
+  2. Call write_stage_artifact with path ship-package.md containing scope,
+     root cause, before/after behavior, changed files, exact validation
+     results, all review verdicts and how any blocking findings were
+     addressed, remaining risks, and a proposed pull-request title and body
+     targeting publish_repo's base_branch from the checkout's current
+     branch. State the repository and branches explicitly.
+  3. Fail closed. If review-feedback-report.md says addressed_all_blocking
+     is not true, or your own re-check finds any original blocking_findings
+     entry whose cited check still fails, mark the package NOT READY and
+     emit failure with the artifact. Do not ask the operator to approve
+     known-blocking code, and do not run any publish command in that case.
+  4. Otherwise call ask_operator with kind artifact_backed referencing the
+     package. Ask whether it is ready to publish.
+  5. For wording/report changes, revise the artifact and ask again. If the
+     operator requests code changes or declines publication, emit failure
+     and preserve the requested changes in the artifact. Do not run any
+     publish command without an explicit accept.
+  6. Only after explicit acceptance: confirm the checkout is still on
+     head_branch (do not switch), then run git add, git commit (using
+     pr_title as the message unless the package recipe says otherwise), git
+     push -u origin <head_branch>, and gh pr create --repo <publish_repo>
+     --base <base_branch> --head <head_branch> --title <pr_title> --body
+     <pr_body_summary>. Auth is GH_TOKEN or GITHUB_TOKEN already in the
+     environment; gh is on PATH.
+  7. Confirm with gh pr view. Write pull-request.md via write_stage_artifact
+     with the PR URL, the commands actually run, and their results. If a
+     pull request already exists for this branch, or any command fails,
+     emit status failure and record what happened; never retry a create
+     with altered scope.
+  8. Emit exactly once, including ship-package.md, pull-request.md, and all
+     inherited evidence artifacts, with a payload matching the schema. Do
+     not stop after a chat reply or after opening the PR — the stage only
+     completes when emit_stage_envelope returns.
+
+  Payload discipline. changed_files must be copied from the implement/review
+  evidence and cross-checked against git diff --name-only; entries that do
+  not appear in that output, or that point under stages/.../artifacts/, are
+  a contract violation. tests must be the real commands or test node ids
+  from the implement evidence, never invented and never n/a, none, tbd, or
+  pending. Every string field must carry real content and every array
+  substantive entries, not placeholders such as ["see diff"]. commands_run
+  must list only the git/gh commands you actually executed, each with its
+  outcome.
+
+  Contract violations — emit failure rather than presenting these as
+  success:
+  - Creating, renaming, or switching branches in this or any stage.
+  - Running git add, git commit, git push, or gh pr create before the
+    operator has explicitly accepted through the artifact_backed gate.
+  - opened: true without gh pr view confirming the PR exists.
+  - publish_repo or base_branch anything other than what the task names.
+  - commands_run listing commands you did not execute.
+  - Writing ship-package.md without reading the reviews and reconciling the
+    diff first.
+  - Accepting addressed_all_blocking at face value without re-checking it
+    against the original blocking_findings.
+
+  Summary authoring. The emitted summary describes outcomes and state:
+  readiness, review verdicts, which files changed, which tests passed, the
+  publish target, and the PR URL if opened. Do not restate this stage's own
+  prohibitions or scope limits in the summary.
+model: omniroute/auto
+timeout_ms: 3600000
+io:
+  input:
+    schema:
+      type: object
+      required:
+        - addressed_all_blocking
+        - fixed_files
+        - verification_commands
+        - remaining_risks
+      properties:
+        addressed_all_blocking:
+          type: boolean
+        fixed_files:
+          type: array
+          items:
+            type: string
+        verification_commands:
+          type: array
+          items:
+            type: string
+        remaining_risks:
+          type: array
+          items:
+            type: string
+  output:
+    schema:
+      type: object
+      required:
+        - pr_title
+        - pr_body_summary
+        - tests
+        - changed_files
+        - publish_repo
+        - base_branch
+        - head_branch
+        - commands_run
+        - opened
+        - pr_url
+      properties:
+        pr_title:
+          type: string
+        pr_body_summary:
+          type: string
+        tests:
+          type: array
+          items:
+            type: string
+        changed_files:
+          type: array
+          items:
+            type: string
+        publish_repo:
+          type: string
+        base_branch:
+          type: string
+        head_branch:
+          type: string
+        commands_run:
+          type: array
+          minItems: 1
+          items:
+            type: string
+        opened:
+          type: boolean
+        pr_url:
+          type: string
+verify:
+  - id: ship-approved
+    type: gate
+    kind: artifact_backed
+    when:
+      - emit
+      - after
+  - id: ship-package
+    type: artifact
+    path: ship-package.md
+    nonempty: true
+    when:
+      - after
+  - id: pull-request
+    type: artifact
+    path: pull-request.md
+    nonempty: true
+    when:
+      - after
+gate_kinds:
+  - artifact_backed

package/examples/ship-feature/ship-feature.pipeline.yaml

@@ -0,0 +1,44 @@
+id: ship-feature
+stages:
+  - id: feat-plan
+    entry: true
+    route:
+      - to: feat-implement
+    uses: ./feat-plan.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: feat-implement
+    route:
+      - to: feat-review
+    uses: ./feat-implement.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: feat-review
+    route:
+      - to: feat-address-feedback
+    uses: ./feat-review.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: feat-address-feedback
+    route:
+      - to: feat-ship
+    uses: ./feat-address-feedback.yaml
+    on_verify_fail:
+      mode: repair
+      max_attempts: 3
+      retry_safety: idempotent
+      include_failed_checks: true
+  - id: feat-ship
+    uses: ./feat-ship.yaml
+    on_verify_fail:
+      mode: manual
+      retry_safety: side_effecting

package/examples/ship-feature/ship-feature.task.yaml

@@ -0,0 +1,78 @@
+id: ship-feature-richer-payload-schema
+goal: >
+  Extend the JSON Schema subset used for io.input.schema / io.output.schema
+  (and verify type: payload_schema checks) in src/envelope/payloadSchema.ts
+  to additionally support, for type: string nodes: pattern (a regex string,
+  validated as a valid RegExp at compile time), minLength, and maxLength
+  (non-negative integers, checked at compile time). Also add a nullable:
+  true keyword usable on any node type, compiling to a union of that type
+  with null. Ship the change as an operator-approved pull request opened
+  against tejasghutukade/stageflow.
+context: |
+  This repository is Stageflow itself (tejasghutukade/stageflow). The
+  checkout for this run is a dedicated git worktree already on branch
+  demo/richer-payload-schema-constraints, tracking origin/main, in a clean
+  state with npm install already run.
+
+  Compiler to extend: src/envelope/payloadSchema.ts (~250 lines). Read its
+  current JsonSchemaNode type, the compileNode switch statement (especially
+  case "string"), and the exported doc-comment above compilePayloadSchema
+  that lists supported keywords — that comment must stay accurate once the
+  new keywords land. nullable most likely wraps compileNode's return with
+  Type.Union([schema, Type.Null()]) from the typebox package already used
+  elsewhere in this file, rather than living inside any single type's case.
+
+  Existing tests to extend: tests/envelope.payloadSchema.test.ts, which uses
+  compilePayloadSchema, assertEnvelopePayload, and
+  assertCloneAssignmentPayload. New tests should follow the file's existing
+  describe/it style — the existing "rejects integers outside minimum and
+  maximum" test is a good template for a new "rejects strings outside
+  pattern/minLength/maxLength" test, and there should be a nullable test that
+  allows null in addition to the node's base type (and continues to reject
+  values of neither).
+
+  Public docs to update: docs/envelopes.md, section "### payload_schema
+  {#payload-schema}" (around line 129), which lists supported keywords in
+  one prose sentence — pattern, minLength, maxLength, and nullable need to
+  join that list.
+
+  Backlog tracker to update as part of this same change, once the capability
+  actually works end-to-end: docs/future-roadmap/conductor-parity-tracker.md,
+  the "Richer payload-schema constraints" item under "## Quality,
+  interaction, and resiliency". That file has its own "How to update this
+  tracker" section at the bottom — follow those instructions exactly (flip
+  [ ] to [x], add links to the fixture/test/doc/example) rather than only
+  deleting the checkbox text. Do not touch any other backlog item in that
+  file. This tracker file is gitignored (a local-only planning artifact, like
+  docs/plans/ and docs/ideation/) — editing it on disk is still worthwhile
+  for the operator's own tracking, but it will never appear in `git diff` or
+  `git status`, so never list it in changed_files/fixed_files (those must
+  match tracked, committable changes) and never expect it to show up in the
+  shipped diff or the pull request.
+
+  Known-good validation commands in this repository (verify against
+  package.json before relying on any command name, do not assume): npm run
+  typecheck, npx vitest run tests/envelope.payloadSchema.test.ts, and npm
+  test for the full suite.
+
+  Ship target: open the pull request against tejasghutukade/stageflow, base
+  branch main, from the checkout's current branch
+  (demo/richer-payload-schema-constraints) — push to origin on that same
+  repository, not a fork.
+constraints: |
+  Do not create, rename, or switch branches in any stage — the checkout is
+  already on the correct branch, demo/richer-payload-schema-constraints,
+  tracking origin/main.
+  Do not touch .gitignore.
+  Do not commit, push, or open a pull request in any stage except feat-ship,
+  and feat-ship may do so only after the operator has explicitly accepted
+  the ship package through its artifact_backed gate.
+  Keep the change limited to the four new keywords (pattern, minLength,
+  maxLength, nullable) and their tests and docs; do not refactor unrelated
+  parts of payloadSchema.ts or change existing supported-keyword semantics.
+  A regex that fails to compile as a RegExp, or a negative/non-integer
+  minLength or maxLength, must be a compile-time error consistent with how
+  this file already rejects invalid minItems/minimum/maximum.
+  Source and test edits belong in the checkout working tree and must never
+  be replaced by a Stageflow artifact or report describing the change.
+checkout: /Users/tejasghutukade/Projects/stageflow-demo-worktree

package/examples/stage-mcp/README.md

@@ -0,0 +1,145 @@
+# stage-mcp
+
+Dummy catalog for **manual operator-console testing** of stage MCP. Project
+`.mcp.json` at the git root declares `echo`, `unused`, `needs-token`, and
+`dead`. The happy path passes only `echo`. The agent calls the local echo
+fixture, then `emit_stage_envelope` so you can inspect the payload.
+
+MCP elicitation is unsupported — the fixture does not ask the operator a
+question.
+
+Three pipelines:
+
+| Pipeline | What it exercises |
+|----------|-------------------|
+| `stage-mcp` | Allowlist `echo` only — unused stays unavailable |
+| `stage-mcp-missing-var` | Passes `needs-token` (`${STAGE_MCP_REQUIRED_TOKEN}`, no default) |
+| `stage-mcp-dead` | Passes `dead` — command will not connect |
+
+## Prerequisites
+
+Use this repo's CLI (`npm run build` / `npm run dev`) or a Stageflow release
+that includes stage MCP. A globally installed `sf` from npm may lag.
+
+- Node.js ≥ 20
+- From repo root: `npm run build` and `npm run ui:build`
+- Provider auth connected (`sf ui` → Settings → Providers) for `sf run`. `sf validate` does not need auth. Stages use `cursor/auto`.
+
+Run state lives in `<repo>/.stageflow` even if you start the console from a subdirectory.
+
+## Terminal 1 — operator console (optional)
+
+From the **repository git root**:
+
+```bash
+npm run build
+npm run ui:build
+PI_CURSOR_SETTING_SOURCES=all STAGEFLOW_ACTIVITY_VERBOSE=1 node dist/cli.js ui
+```
+
+`npm run dev -- ui` runs the TypeScript CLI via tsx; use `node dist/cli.js ui` after `ui:build` so the console is served from `dist/ui`. Do not use a globally installed `sf` — Homebrew `sf` is an older build that cannot load this catalog.
+
+Open `http://127.0.0.1:3847`. Browse should list **stage-mcp** and **stage-mcp-missing-var**. **stage-mcp-dead** is excluded from the catalog manifest (so `sf validate --strict` and release CI stay green) but remains loadable by explicit path — see Scenario C.
+
+## Terminal 2 — start a run (repo root)
+
+```bash
+node dist/cli.js validate --pipeline examples/stage-mcp/stage-mcp.pipeline.yaml --strict
+node dist/cli.js run \
+  --pipeline examples/stage-mcp/stage-mcp.pipeline.yaml \
+  --task examples/stage-mcp/stage-mcp.task.yaml
+```
+
+`sf` works the same if that binary is this repo's build. Start a **new run** for each scenario below. Do not reuse a finished run.
+
+Validate does not require `STAGE_MCP_REQUIRED_TOKEN` or a live connect.
+
+---
+
+## Scenario A — allowlist
+
+Happy pipeline. `.mcp.json` defines `echo` and `unused`. The stage passes only `echo`.
+
+### What to verify
+
+1. The agent can call the echo fixture and cannot use `unused`.
+2. Ambient Cursor MCP is not inherited. Only the names on the stage list are passed.
+3. The handoff envelope payload includes `echoed` from the fixture.
+
+```bash
+node dist/cli.js envelope get --run <runId> --stage use-echo --json
+```
+
+---
+
+## Scenario B — missing required var
+
+New run **without** `STAGE_MCP_REQUIRED_TOKEN` in the environment:
+
+```bash
+node dist/cli.js run \
+  --pipeline examples/stage-mcp/stage-mcp-missing-var.pipeline.yaml \
+  --task examples/stage-mcp/stage-mcp-missing-var.task.yaml
+```
+
+### What to verify
+
+1. The stage fails before the agent is treated as having those tools.
+2. `sf validate` on this pipeline still passes — unset required vars fail at **run**, not validate.
+
+---
+
+## Scenario C — dead server
+
+Excluded from catalog browse / manifest-all validate (command is intentionally not on PATH). Load by explicit path:
+
+```bash
+node dist/cli.js run \
+  --pipeline examples/stage-mcp/stage-mcp-dead.pipeline.yaml \
+  --task examples/stage-mcp/stage-mcp-dead.task.yaml
+```
+
+### What to verify
+
+1. The passed `dead` server will not connect.
+2. The stage fails.
+3. `sf validate --strict` (no `--pipeline`) does not report this pipeline; validating the dead pipeline by explicit path still reports `catalog.mcp_command_missing`.
+
+---
+
+## Scenario D — both backends
+
+Same `mcp` list and `.mcp.json` allowlist, first on Pi, then on Claude. Change only the stage `model` between runs.
+
+### What to verify
+
+1. Both backends receive the servers named on the stage.
+2. Transports and protocol features may differ. Do not change `mcp` or `.mcp.json` to switch backends.
+
+---
+
+## Scenario E — Stageflow tools stay
+
+Happy path again (or reuse Scenario A if the envelope already landed).
+
+### What to verify
+
+1. `emit_stage_envelope` still works. `write_stage_artifact` remains available.
+2. MCP tool calls do not park for a new MCP-specific approval.
+
+---
+
+## Scenario F — activity log
+
+After the agent calls the echo fixture, inspect the run in the console or CLI.
+
+### What to verify
+
+1. The echo tool call is visible in the existing stage activity.
+2. There is no dedicated MCP console.
+
+## Envelope inspector (any successful happy-path run)
+
+On a completed `use-echo` stage, the first Files row is **Handoff envelope**. It opens the inspector (`#/runs/<runId>/stages/use-echo/envelope`) with `summary`, `payload`, and artifact paths.
+
+CLI equivalent: `node dist/cli.js envelope get --run <runId> --stage use-echo --json`.

package/examples/stage-mcp/echo-mcp.mjs

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { z } from "zod";
+
+serveStdio(() => {
+  const server = new McpServer({ name: "echo", version: "1.0.0" });
+  server.registerTool(
+    "echo",
+    {
+      description: "Echo a text argument back to the caller.",
+      inputSchema: z.object({
+        text: z.string().describe("Text to echo"),
+      }),
+    },
+    async ({ text }) => ({
+      content: [{ type: "text", text }],
+    }),
+  );
+  return server;
+});

package/examples/stage-mcp/stage-mcp-dead.pipeline.yaml

@@ -0,0 +1,5 @@
+id: stage-mcp-dead
+stages:
+  - id: use-echo
+    uses: ./use-echo.yaml
+    mcp: [dead]

package/examples/stage-mcp/stage-mcp-dead.task.yaml

@@ -0,0 +1,3 @@
+id: stage-mcp-dead
+goal: Exercise a passed MCP server that will not connect.
+context: The dead catalog entry uses a command that is not on PATH.

package/examples/stage-mcp/stage-mcp-missing-var.pipeline.yaml

@@ -0,0 +1,5 @@
+id: stage-mcp-missing-var
+stages:
+  - id: use-echo
+    uses: ./use-echo.yaml
+    mcp: [needs-token]

package/examples/stage-mcp/stage-mcp-missing-var.task.yaml

@@ -0,0 +1,3 @@
+id: stage-mcp-missing-var
+goal: Exercise a passed MCP server that interpolates a required variable with no default.
+context: Run without STAGE_MCP_REQUIRED_TOKEN so the stage fails before tools are treated as present.

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

@@ -0,0 +1,5 @@
+id: stage-mcp
+stages:
+  - id: use-echo
+    uses: ./use-echo.yaml
+    mcp: [echo]

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

@@ -0,0 +1,4 @@
+id: stage-mcp
+goal: Call the echo fixture tool, then emit a success envelope the operator can inspect.
+context: Domain-neutral walkthrough for stage MCP. The happy path passes only the echo server.
+constraints: Do not call ask_operator. Do not use unused catalog servers.

package/examples/stage-mcp/use-echo.yaml

@@ -0,0 +1,20 @@
+id: use-echo
+system_prompt: |
+  Call the echo fixture tool with a short text argument. Then call
+  emit_stage_envelope with status success, artifacts [], a short summary,
+  and payload { "echoed": "<the text the echo tool returned>" } so the
+  operator can inspect the handoff. Do not call ask_operator. Do not emit
+  to ask the operator a question.
+model: cursor/auto
+io:
+  input:
+    schema:
+      type: object
+  output:
+    schema:
+      type: object
+      required:
+        - echoed
+      properties:
+        echoed:
+          type: string