@gobing-ai/spur 0.3.80 → 0.3.82

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-agent
-description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts, wait on pinned occupants, manage team agent specs, run the persistent self-draining loop, and check readiness."
+description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts, wait on pinned occupants, list agent specs, start/stop supervised processes, and check readiness."
 see_also:
   - spur-cli
 ---
@@ -9,7 +9,7 @@ see_also:
 
 `spur agent` is the CLI for **running and inspecting coding agents**. It wraps the agents the
 operator already has installed (Claude Code, Codex, omp, OpenCode, Antigravity, etc.) behind a
-uniform run, wait, loop, and spec-management surface, so the rest of the harness can dispatch work without
+uniform run, wait, and supervision surface, so the rest of the harness can dispatch work without
 hard-coding a specific agent.
 
 This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
@@ -22,16 +22,14 @@ that before using `run` for fan-out dispatch.
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
-| `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--spec <id>` `--agent <id>` `--poll <ms>` |
 | `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
-| `list` | List detected coding agents, or team agent specs with `--specs` | `--specs` `--json` |
+| `list` | List detected coding agents, or agent specs with `--specs` (live run status merged from `spur serve`) | `--specs` `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
-| `create <id>` | Write a team agent spec to `.spur/agents/<id>.yaml` | `--type` `--tags` `--model` `--autonomy` `--system-prompt` `--name` `--workspace` `--purpose` `--auto-start` `--no-identity-preamble` `--json` |
-| `edit <id>` | Open an agent spec in `$EDITOR`, or print its path | - |
-| `delete <id>` | Remove an agent spec | `--force` |
+| `start <spec-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
+| `stop <spec-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 
-`list`, `doctor`, `run`, `wait`, and `create` accept `--json` plus `--json-envelope`. `loop`, `edit`,
-and `delete` are human/process-control surfaces. **Exit codes:** `0` success, `1` failure, and `2`
+`list`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+`loop` is a supervisor-internal process surface. **Exit codes:** `0` success, `1` failure, and `2`
 invalid usage; `run` can also propagate the invoked agent's non-zero result.
 
 ## `run` - execute a prompt via a coding agent
@@ -54,7 +52,7 @@ through a coding agent as an external process, producing a persisted run record
 | `--mode <mode>` | Agent output mode: `text` or `json`. |
 | `--continue` | Resume the previous agent session instead of starting fresh. |
 | `--cwd <path>` | Working directory for agent execution (default: current directory). |
-| `--spec <id>` | Team agent spec id (occupant addressing, 0542 R1). Pairs with `--drain`; with `--spec` alone the run is addressed to the occupant without touching the inbox. A legacy `--agent <spec-id>` still works during the transition with a one-time warning (shim `agent-flag-spec-id`). |
+| `--spec <id>` | Agent spec id (occupant addressing, 0542 R1). Pairs with `--drain`; with `--spec` alone the run is addressed to the occupant without touching the inbox. A legacy `--agent <spec-id>` is still accepted as fallback addressing (task 0849 retired the `agent-flag-spec-id` deprecation warning). |
 | `--drain` | Prepend pending inbox messages addressed to `--spec <id>` before the prompt. |
 | `--json` | Output machine-readable JSON where supported. |
 | `--json-envelope` | Wrap JSON using the facade's standard output contract. |
@@ -83,26 +81,15 @@ can fail when the external agent writes its own storage outside the sandbox's al
 `AgentStorage` SQLite DB). This is not a reason to abandon `spur agent run` - triggers 1-4 still
 justify it - but ensure the run executes in a context that can write the target agent's storage.
 
-## `loop` - persistent self-draining wrapper
+## `loop` - supervisor-internal self-draining wrapper (hidden)
 
-```bash
-spur agent loop --agent worker-1 --poll 2000
-```
-
-`loop` is the **persistent self-draining wrapper** used by the team supervisor. It polls the
-addressed agent's inbox, drains each pending message into an `agent run` invocation, and idles
-between drains. It is not typically invoked directly by the operator - `spur team start` launches it
-under supervision.
-
-### Flags
-
-| Flag | Purpose |
-|------|---------|
-| `--spec <id>` | **Required.** Team agent spec id / message recipient (0542 R1; legacy `--agent <spec-id>` still read with a one-time warning). |
-| `--poll <ms>` | Idle poll interval in milliseconds (default: `2000`). |
-
-The loop runs until `SIGINT` / `SIGTERM`. Each iteration: check inbox -> if messages, drain each
-into `run` with `--drain` -> else sleep for `--poll` ms.
+`spur agent loop --spec <id> [--poll <ms>]` is spawned by the `spur serve` supervisor for each
+materialized agent spec; it is hidden from `--help` and not an operator verb (use `spur agent start`).
+It waits for a wake on the `system_events` ledger — a human request (`message.sent`), a strategy
+change (`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
+(`agent.invoke.exit`) — then drains the inbox into an `agent run` invocation. An idle wake records
+the hold reason instead of dispatching; with no wake event it still drains every `--poll` ms
+(default `2000`). It runs until `SIGINT` / `SIGTERM`.
 
 ## `wait` - identity-pinned occupant wait (G4 wave 2)
 
@@ -143,16 +130,26 @@ exits 2 naming the accepted vocabulary. Resolution collapses onto the same ident
 | `timeout` | 1 | Caller `--timeout` elapsed (or aborted via SIGINT). |
 | `usage` | 2 | Invalid flags, or `--until blocked` as the sole target (no first-class signal in wave 2). |
 
-## `list` - detected agents and team specs
+## `list` - detected agents and agent specs
 
 ```bash
 spur agent list              # detected coding agents on this machine
-spur agent list --specs      # team agent specs under .spur/agents/
+spur agent list --specs      # agent specs under .spur/agents/
 spur agent list --json       # machine-readable
 ```
 
 Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
-lists team agent specs (`.spur/agents/*.yaml`).
+lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the server's
+supervisor**: each row carries a trailing status column
+(`running` / `stopped` / `errored` / `unknown`) and `pid=<n>` where a process exists. When `spur serve`
+is unreachable, the listing falls back to all `stopped` with a stderr warning. `--server <url>`
+(default `http://localhost:3000/api`) targets the supervisor API.
+
+```bash
+spur agent list --specs
+# planner	claude	reviewer	claude	plans the work	running pid=4132
+# worker-1	pi	worker	pi	implements	stopped
+```
 
 ## `doctor` - readiness check
 
@@ -168,63 +165,41 @@ Checks whether each agent is installed and ready to run. Text mode renders a cap
 (`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), and ROLES lists
 candidate pipeline roles with `*` on the elected one. Exit `1` if any checked agent is not ready.
 
-## `create` - author a team agent spec
-
-```bash
-spur agent create worker-1 --type claude --tags team:alpha --model sonnet
-spur agent create reviewer --type codex --autonomy review --auto-start
-```
-
-Writes a team agent spec to `.spur/agents/<id>.yaml`. The spec captures the agent's identity
-(type, model, autonomy, system prompt, tags) so `spur team up` can materialize a roster and `spur
-agent loop` can self-drain its inbox.
-
-### Flags
-
-| Flag | Purpose |
-| ------ | --------- |
-| `--type <agent-type>` | Agent spec type (e.g. `claude`, `codex`, `omp`). |
-| `--tags <a,b>` | Comma-separated team identity tags (e.g. `team:alpha,role:worker`). |
-| `--model <name>` | Agent model argument. |
-| `--autonomy <level>` | Autonomy level (e.g. `full`, `review`). |
-| `--system-prompt <text>` | Team identity system prompt. |
-| `--name <name>` | Agent display name. |
-| `--workspace <path>` | Workspace path for this agent. |
-| `--purpose <text>` | Team identity purpose. |
-| `--auto-start` | Auto-start flag (start on `team up` without manual `team start`). |
-| `--no-identity-preamble` | Disable the identity preamble prepended to prompts. |
-| `--json` | Output machine-readable JSON. |
-
-## `edit` - open a spec in `$EDITOR`
+## `start` - start a supervised process
 
 ```bash
-spur agent edit worker-1
+spur agent start worker-1
+spur agent start worker-1 --json
 ```
 
-Opens `.spur/agents/<id>.yaml` in `$EDITOR`. If `$EDITOR` is unset, prints the spec path instead.
+Posts to the `spur serve` supervisor API
+(`POST /api/agents/:id/start`) and prints `started <id> (pid=<n>, status=<s>)`. Requires a
+reachable `spur serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
+when the server is unreachable or the start fails.
 
-## `delete` - remove a spec
+## `stop` - stop a supervised process
 
 ```bash
-spur agent delete worker-1 --force
+spur agent stop worker-1
+spur agent stop worker-1 --json
 ```
 
-`--force` is required (guards against accidental deletion). Removes `.spur/agents/<id>.yaml`.
+Posts to the supervisor API
+(`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
+`start`.
 
 ## What this skill is NOT
 
 - **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the
   **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
   reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
-- **Not the team orchestrator.** `spur team up` / `spur team start` drive the supervisor lifecycle;
-  `spur agent` provides the execution primitives they compose.
+- **Not the fleet orchestrator.** The `spur serve` supervisor drives the lifecycle: `spur agent
+  start` / `stop` manage supervised processes and `agent list --specs` reports live state.
 
 ## See also
 
 - **[dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md)** - native
   subagent vs `spur agent run` decision rule. `--model` and `--agent` are its escalation levers.
-- **`spur team` (see [team.md](team.md))** - team lifecycle that launches `agent loop` under
-  supervision.
 - **`spur message` (see [message.md](message.md))** - the inbox `--drain` reads from.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
 

package/plugins/sp/skills/spur-cli/references/message.md

@@ -19,8 +19,8 @@ use it well*.
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
-| `send <body>` | Enqueue a message for an agent | `--to <id>` `--role <name>` `--from <id>` `--wait` `--until <state>` `--timeout <ms>` `--json` |
-| `inbox` | List messages addressed to an agent | `--agent <id>` `--json` |
+| `send <body>` | Enqueue a message for an agent | `--to <id>` `--role <name>` `--from <id>` `--request-key <key>` `--wait` `--until <state>` `--timeout <ms>` `--json` |
+| `inbox` | List messages addressed to an agent | `--agent <id>` `--unresolved` `--json` |
 | `reply <msg-id> <body>` | Thread a reply to a message | `--json` |
 | `watch` | Follow an agent inbox - surface new messages as they arrive | `--agent <id>` `--interval <ms>` `--json` |
 
@@ -34,6 +34,7 @@ spur message send "Please review PR 42" --to reviewer
 spur message send "Task 0040 is blocked" --to worker-1 --from operator
 spur message send "Done" --to planner --json
 spur message send "Review 0042" --to reviewer --wait --until invoke-exit --timeout 30000
+spur message send "Done" --to manager --request-key 0695-report-42      # retry-safe: same key replays the original receipt
 spur message send "Start the pass" --role reviewer          # resolves to exactly one instance
 ```
 
@@ -51,6 +52,9 @@ wait; enqueue is **not** rolled back if the wait later fails.
 | `--to <id>` | Recipient agent id. Mutually exclusive with `--role`; exactly one of the two is required. |
 | `--role <name>` | Address by Layer-1 role or executor name. Must resolve to exactly one materialized instance; zero (`count=0`, candidates `none`) or multi (`count=N` + candidates) matches are hard errors (exit 1); unknown name exits 2 naming the accepted vocabulary (`AGENT_ROLE_NAMES` ∪ executor names). Resolution yields the same spec-id path as `--to`; `--wait` snapshots that occupant pin. (0685 R6 / ADR-075 amendment) |
 | `--from <id>` | Sender id (default: `operator`). |
+| `--request-key <key>` | Caller-minted idempotency key. The same key with the same body + recipient replays the original receipt (`replayed: true`, no second row/delivery); the same key with a different payload fails with a request-key-conflict error (0832). |
+| `replayed` receipt field | Present on keyed sends: `true` when this submission was a replay of an earlier accepted send. |
+| `requestKey` receipt field | Present on keyed sends, including replays; echoes the accepted key. Blank keys are rejected. |
 | `--wait` | Block until the recipient reaches `--until` (snapshots occupant before send). |
 | `--until <state>` | Wait target: `injected` \| `invoke-exit` (repeatable OR). Default `invoke-exit`. |
 | `--timeout <ms>` | Caller deadline in milliseconds. |
@@ -64,11 +68,33 @@ wait; enqueue is **not** rolled back if the wait later fails.
 ```bash
 spur message inbox --agent worker-1
 spur message inbox --agent worker-1 --json
+spur message inbox --agent worker-1 --unresolved --json
 ```
 
 Lists messages addressed to `--agent <id>`, oldest first. The body is truncated in plain-text output;
 `--json` returns the full body.
 
+### Delivery failure states (0834)
+
+`--unresolved` filters the listing to messages the delivery reconciler holds, and every `--json` row
+gains the operator-read fields: `injectAttempts`, `injectError`, `reason`, `runId`, `taskId`, `runStatus`,
+`artifacts`. The hold reasons are distinct and durable — never one overloaded status column:
+
+Delivered messages remain eligible for holds until their receipt is verified. Interrupted runs
+carry their persisted origin and run status; exhausted attempts keep the same reason on repeated reads.
+
+| `reason` | Meaning |
+| -------- | --------- |
+| `delivery-failed` | The drain marked the delivery failed (`injectError` carries why), or its run's receipt outcome is `errored`. |
+| `attempts-exhausted` | The message burned its bounded redelivery budget (`MAX_INJECT_ATTEMPTS`, 0831); the reconciler marks it `failed` — the reconciler's only write. |
+| `outcome-unknown` | The drain consumed it and no completion receipt ever arrived: the agent may have edited files. **Never requeued, never auto-released** — a human decides. |
+| `run-exit-only` | Its run exited (receipt outcome `run-exit-only`) with no workflow verification result. |
+
+`runId`, `taskId`, and `artifacts` (path-only refs) come only from the persisted run row that lists
+the message in its receipt; nothing is inferred from terminal output or process lists. The same
+reconciler runs once at `spur agent loop` startup and writes a `reconcile:` summary to the run log
+before the first drain.
+
 ## `reply` - thread a reply
 
 ```bash
@@ -107,7 +133,8 @@ lines.
 ## See also
 
 - **`spur agent` (see [agent.md](agent.md))** - `run --drain` and `loop` consume the inbox.
-- **`spur team` (see [team.md](team.md))** - team lifecycle that assigns agents to tasks.
+- **`spur task` (see [tasks.md](tasks.md))** - `task update --assignee` wires an agent spec to a
+  task.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
 
 > **Shared option declarations (0618):** options shared across command modules resolve from

package/plugins/sp/skills/spur-cli/references/projects.md

@@ -19,7 +19,7 @@ shapes live in `apps/cli/src/commands/projects.ts`.
 | ---- | ------- | --------- |
 | `add <path>` | Upsert an existing path in the registry | `--name <name>` `--json` |
 | `remove <target>` | Remove an entry by display name or path | `--json` |
-| `list` | List entries with live running status | `--json` |
+| `list` | List entries with live running status | `--json` `--fleet` |
 | `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
 | `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
 
@@ -36,6 +36,30 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
   defaults the display name to its basename. It upserts; it does not start a server. The current
   source does not enforce a `.spur/` marker or directory type.
 - `list` probes recorded ports and heals stale entries to `port: 0` before reporting `running`.
+- `list --fleet` (0835/0858) additionally resolves each project's `agent.fleet` section from that
+  project's `.spur/config.yaml` under the existing verb (no new noun). Per project it prints one line
+  per member: instance id (the spec id / mailbox identity), `role`, resolved `executor`,
+  `fsWrite` capability state, and derived `write` flag. A project with no declaration reports
+  `no declaration (agent.fleet)`; a declared but switched-off fleet reports
+  `disabled (agent.fleet.enabled: false)` and still lists its roster; an all-disabled roster reports
+  `no enabled members`; a project whose config fails to load (a retired source, an invalid section)
+  reports the loader's message without failing the listing. Under `--json` each project gains `fleet`
+  (the resolved fleet, `null` on resolution failure) and, on failure, `fleetError`.
+- `list --fleet` (0836) also reports the project's orchestrator binding: one
+  `orchestrator:` line per project with state `bound-online <id> (holder <spec-id>)`,
+  `bound-offline <id> (no live claim)`, `missing (no-orchestrator-declared)`, or
+  `unresolvable (<reason>)` — missing (nothing bound) and bound-offline (bound, no live
+  claim) are distinct states with distinct next actions, and an unresolvable pointer is an
+  error, never inferred. Reading the live claim touches the project's own `.spur/spur.db`
+  (lazily; only when the pointer resolves). Under `--json` each project gains
+  `orchestrator` (the binding, `null` on resolution failure) and, on failure,
+  `orchestratorError`.
+- `list --fleet` (0838) also reports the project's persisted strategy (0838): one
+  `strategy:` line — `rest (default)` when nothing is persisted (the read never
+  writes; only the runtime's `setStrategy`/`resume` persist), `<name> (v<n>)` for a
+  persisted row, or `unavailable (<error>)` on a db failure. Under `--json` each
+  project gains `strategy` (`{ strategy, strategyVersion }`, `null` when
+  unpersisted) and, on failure, `strategyError`.
 
 ## Server lifecycle
 

package/plugins/sp/skills/spur-cli/references/self.md

@@ -77,7 +77,7 @@ spur self serve --json                # dry probe: print { port, url, pid, runni
 ```
 
 Starts the Hono/Cloudflare-Worker server that serves the web Task Kanban and exposes the team
-supervisor API (`/api/team/*`). It is the local fallback when no remote server is configured.
+supervisor API (`/api/processes/*` + `/api/agents/*`). It is the local fallback when no remote server is configured.
 Flags: `--port <n>`, `--host <addr>`, `--no-open`, `--cwd <path>`, `--json` (a dry probe — reports
 the resolved port/url without starting the server). Full flag semantics: **[serve.md](serve.md)**.
 
@@ -95,8 +95,9 @@ directory. Only flag is `--json`.
 
 ## What this skill is NOT
 
-- **Not the team supervisor.** `self serve` hosts the supervisor API; `spur team start` / `stop` /
-  `status` are the verbs that drive it. See **[team.md](team.md)**.
+- **Not the agent supervisor.** `self serve` hosts the supervisor API; `spur agent start` / `stop` /
+  `agent list --specs` are the verbs that drive and inspect it (0848). See
+  **[agent.md](agent.md)**.
 - **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
   Worker build (`apps/server/`), not `self serve`.
 
@@ -105,8 +106,8 @@ directory. Only flag is `--json`.
 - **[init.md](init.md)** - `init` / `status` verbs: scaffold semantics and the Phase 1.5 / 1.6
   post-scaffold validation probes.
 - **[serve.md](serve.md)** - `serve` verb: server flags and the `--json` dry-probe contract.
-- **`spur team` (see [team.md](team.md))** - `start`/`stop`/`status` require `self serve` for the
-  supervisor API.
+- **`spur agent` (see [agent.md](agent.md))** - `start`/`stop`/`list --specs` require `self serve`
+  for the supervisor API.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
 
 > **Shared option declarations (0618):** options shared across command modules resolve from

package/plugins/sp/skills/spur-cli/references/serve.md

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-serve
-description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the team supervisor API. Single verb, five flags."
+description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the supervisor API. Single verb, five flags."
 see_also:
   - spur-cli
 ---
@@ -8,7 +8,7 @@ see_also:
 # spur serve - local web server
 
 `spur serve` starts the **Spur web server** - a local Hono / Cloudflare-Worker server that serves
-the web Task Kanban and exposes the team supervisor API (`/api/team/*`). It is the local fallback
+the web Task Kanban and exposes the supervisor API (`/api/processes/*` + `/api/agents/*`). It is the local fallback
 when no remote server is configured.
 
 ## Verb map
@@ -29,7 +29,7 @@ spur serve --json                   # dry probe: print { port, url, pid, running
 ```
 
 Starts the server with the Hono app backed by the local SQLite database. The web Task Kanban and
-the team supervisor API become available at `http://<host>:<port>`.
+the supervisor API become available at `http://<host>:<port>`.
 
 ### Flags
 
@@ -46,13 +46,14 @@ the team supervisor API become available at `http://<host>:<port>`.
 
 ## What this skill is NOT
 
-- **Not the team supervisor.** `spur serve` hosts the supervisor API; `spur team start` / `stop` /
-  `status` are the verbs that drive it. See **[team.md](team.md)**.
+- **Not the agent supervisor.** `spur serve` hosts the supervisor API; `spur agent start` / `stop` /
+  `agent list --specs` are the verbs that drive and inspect it (0848). See
+  **[agent.md](agent.md)**.
 - **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
   Worker build (`apps/server/`), not `spur serve`.
 
 ## See also
 
-- **`spur team` (see [team.md](team.md))** - `start`/`stop`/`status` require `spur serve` for the
-  supervisor API.
+- **`spur agent` (see [agent.md](agent.md))** - `start`/`stop`/`list --specs` require `spur serve`
+  for the supervisor API.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.

package/plugins/sp/skills/spur-cli/references/tasks.md

@@ -40,7 +40,7 @@ re-reading or re-tokenizing the task.
 | ---- | ------- | --------- |
 | `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--folder` `--json` |
 | `show <wbs>` | Print one task's frontmatter + body | `--folder` `--json` |
-| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--feature <id>` `--priority <p>` `--no-lifecycle` `--force-done` `--reason <text>` `--verdict-dir <path>` `--folder` `--json` |
+| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (exclusive with `--section`) `--feature <id>` `--priority <p>` `--no-lifecycle` `--force-done` `--reason <text>` `--verdict-dir <path>` `--folder` `--json` |
 | `deps <wbs> <op> [values...]` | Mutate `dependencies[]` frontmatter array (ops: `set`, `add`, `remove`, `clear`) | `--folder` `--json` |
 | `sections <wbs> <op> [name]` | Initialize, add, or list canonical task sections (ops: `init`, `add`, `list`) | `--folder` `--json` |
 | `list` | List tasks, filtered | `--status <s>` `--phase <p>` `--parent <wbs>` `--feature <id>` `--folder` `--json` |

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -65,9 +65,12 @@ Reconciliation core — run this **before authoring anything**. Authoring withou
 workflows breeds redundant, diverged definitions (two near-identical approval flows, an import flow
 re-implemented under a new name). Inputs: the clarified process intent. Steps:
 
-1. **Enumerate existing workflows** — list `.spur/workflows/*.yaml` (and any `--file`-adjacent
-   directory); read each one's `name`, `kind`, and the states/nodes it defines so matches are found by
-   *substance*, not just by filename.
+1. **Enumerate existing workflows** — `spur workflow list --json` across **all layers**
+   (`project`, `registered`, `shared` — the listed `layers` are the folders a name can resolve
+   from). Never glob `.spur/workflows`: a folder scan misses the registered and shared layers.
+   Match from each entry's `name`, `kind`, `source` (the layer it came from) and `description`
+   (the intent), then read the strongest candidates' definitions — states/nodes — so matches are
+   found by *substance*, not just by filename.
 2. **Classify the strongest match** against the new intent:
 
    | Match | Meaning | Action |

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -130,24 +130,63 @@ The flags (`--detail`, `--verbose`, `--trace-file`, `--follow`, `--output`) are
 ## 3. Node simplicity budget
 
 Simplicity is the operating constraint, and it is already measurable — `spur workflow validate`
-reports it. Do not invent a second threshold; author to the one that is frozen (ADR-069, task 0614).
-
-| Element | Budget | What breaching it means |
-| --- | --- | --- |
-| `shell` action `command` | **<= 5** non-comment units (split on newline and `;`) | >= 6 flags the composition advisory: the program holds reusable behavior that wants an owner |
-| `agent.run` action `input` | A **slash command or skill invocation** | A raw prose prompt flags: the operation belongs behind a centralized command (ADR-043). Prompt length sets severity only |
-| Transition guard | **One** boolean predicate | Guards are exempt from the shell measure by design. A guard needing five lines is a probe node in disguise — make it one |
-| Node count | Every node earns its transition round-trip | A node that always runs immediately after another, with no guard between them, is one node |
-
-**When a node breaches the budget, do not reformat to dodge the measure.** Joining five lines with
-`&&` moves the complexity, not the ownership. Pick one of the four remaining owners from
-`docs/design/workflow-shell-ownership.md`: public `spur` verb (consent-gated), application service,
-least-privilege built-in action kind, or workflow-relative external extension. (0775 retired the
-recorded stays-shell exception along with the suppression snapshot.)
-
-**Advisory posture is binding.** Composition findings never block a run, never change a `validate`
-exit status, and are never a reason to hot-edit an executing pipeline. Surface them; fix on operator
-acceptance.
+reports it with a `warn`/`error` level. Do not invent a second threshold; author to the ADR-115
+tiers frozen in [surface governance §1.2](../../../../../../docs/design/harness-surface-governance.md).
+
+| Element | Clean | Warn (advisory) | Error |
+| --- | --- | --- | --- |
+| `shell` action `command` | ≤5 logical commands (split on newline, `;`, `&&`, `||`; blank/`#`/structure tokens skipped) | **6–10** | **>10** commands or **>800** characters |
+| Shell transition guard | ≤3 logical commands — one predicate over a result file | **4–5** | **>5** |
+| `agent.run` `input` | A slash command or skill invocation (ADR-043), ≤1000 chars | non-slash prompt (severity by raw length: <200 low, ≤1000 medium) | **>1000** chars, slash-led or not |
+| `agent.run` output check | `expectFile` or `requireDiff` declared | neither declared | — |
+| Node count | Every node earns its transition round-trip | A node that always runs immediately after another, with no guard between them, is one node | — |
+
+**When a program breaches a cap, do not reformat to dodge the measure.** Joining lines with `&&`
+moves the complexity, not the ownership. Move the program to one of the five recorded owners from
+`docs/design/workflow-shell-ownership.md`: (a) public `spur` verb (consent-gated), (b) application
+service, (c) least-privilege built-in action kind, (d) workflow-relative external extension, or
+(e) a deliberately-stays-shell exception. (e) is valid only inside the warn band — above an error
+cap the program moves to (a)–(d).
+
+**Every remaining warn-band shell program carries a one-line `#` reason**: a YAML comment directly
+above the action or guard, e.g. `# (e) <why it stays shell>` or `# (d) <script> owns <what>`. Never
+write it as a shell `#` line inside a folded `>-` scalar — folding joins the lines, so the `#`
+comments out the rest of the program. YAML comments do not count toward the measure.
+
+**Posture is binding (ADR-115).** Warn-level findings never change a `validate` exit status and
+never block a run. An error-level finding makes `validate` exit 1 and gates the spur repository's
+shipped shared workflow layer (layer id `shared` in `spur workflow list --json`) in `spur-check`
+(task 0826). No composition finding ever blocks `run`, `run --dry-run` or `continue`, and a finding
+is never a reason to hot-edit an executing pipeline.
+
+### Consolidation and cache windows (ADR-115)
+
+Two composition rules sit next to this budget: the table above stays the measure surface, these
+decide where steps are cut. The rules are owned by the
+[workflow composition contract](../../../../../../docs/design/workflow-composition-contract.md#composition-budgets-adr-115);
+the text below is the operating summary, not a second owner.
+
+**Consolidation — one model step per judgment.** Merge adjacent `agent.run` steps only when they
+share a role and an executor **and** nothing between them must stay separate: a deterministic gate,
+a HITL state, or an independence boundary. Never merge an author step with the review or verify
+step that certifies it — those keep `freshSession: true`. A new model step in a shared workflow
+raises its `pipeline-budgets` `modelQueries`, which needs a recorded decision, and every shared
+workflow with a model query carries a budget entry.
+
+**Cache windows — step boundaries follow the cache window, not the clock.** Provider prompt caches
+expire after an idle window and refresh on every hit (Anthropic: 5 minutes by default; OpenAI:
+5–10 minutes in memory). The window W defaults to 300 s, the shortest common default:
+
+- A tool call inside `agent.run` that runs longer than W idles the model — its next request
+  re-reads a cold prefix. Run that work in a deterministic step instead.
+- An `agent.run` that resumes the inherited session after a gap longer than W (a HITL wait, a slow
+  deterministic step) rewrites the whole session into the cache. When the prior step's artifact
+  carries what the step needs, prefer `freshSession: true` with that artifact as the handoff.
+- A deterministic step should finish within W at p50. An `agent.run` with p50 above 2W is a split
+  candidate only at a real artifact seam — each split adds a model query and a cold prefix, so it
+  must pay for itself in retry granularity or observability.
+
+These are runtime budgets, judged from run traces and step profiles — never `validate` findings.
 
 ---