@gobing-ai/spur 0.3.80 → 0.3.81

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 (0848 moved home of `spur team assign`).
 - **`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,9 +19,10 @@ 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` |
+| `migrate [path]` | Preview (default) or apply the legacy `agent.team` → `fleet.json` conversion (0847) | `--dry-run` `--apply` `--json` |
 
 Every verb also advertises `--json-envelope`; use the facade's machine-output contract. Success is
 exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
@@ -36,6 +37,49 @@ 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) additionally resolves each project's fleet declaration at
+  `<project>/.spur/fleet.json` 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 (.spur/fleet.json)`; an all-disabled roster reports `no enabled members`; a project
+  whose executors fail resolution reports the error 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`.
+- `migrate [path]` (0847) converts the single legacy `agent.team.<id>` roster whose
+  `work_dir` resolves to the project into `<project>/.spur/fleet.json`, preserving
+  every spec id verbatim (explicit member ids freeze the `<role>-<n>` derivation).
+  Dry-run is the default: it emits the 0846 plan (steps + conflicts + warnings) and
+  writes nothing — an existing project db is opened read-only without migrations;
+  an absent db or table contributes no addressed identities.
+  `--apply` validates first, deep-equals an existing declaration (`unchanged`, no
+  rewrite), backs up a differing prior file to `.bak`, then atomically writes the
+  declaration (`converted`). It is purely additive — specs, `config.yaml`, and the
+  database are never touched — and it refuses to write while any conflict exists
+  (`addressed-id-without-spec`, `two-teams-one-project`, …). A registry name that
+  differs from the legacy team ID is `project-name-mismatch`: align that name
+  explicitly before conversion so fleet resolution preserves the spec-id prefix.
+  Exit codes: `0` for a
+  clean preview or `converted`/`unchanged`/`nothing-to-convert`; `2` when blocked
+  (the JSON payload still carries the full plan/result); `1` on error. Under
+  `--json` the payload is the raw `MigrationPlan` (preview) or `ConversionResult`
+  (apply). `rollback` is a service-level API (no CLI verb): restore the `.bak` a
+  previous apply created, remove a file that apply created when no `.bak` exists,
+  or report `nothing-to-roll-back`.
 
 ## Server lifecycle
 

package/plugins/sp/skills/spur-cli/references/self.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 team 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

@@ -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 team 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>` (moved home of `spur team assign`; 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/team.md

@@ -5,7 +5,27 @@ see_also:
   - spur-cli
 ---
 
-# spur team - team coordination and supervision
+# spur team - team coordination and supervision (DEPRECATED — 0848)
+
+> **Deprecated (0848, feature G64):** every `spur team` capability has moved to its owning noun.
+> The noun keeps working until the G64 cutover window is recorded, emitting a one-time stderr
+> warning per process. Migrate invocations now:
+>
+> | Old verb | New home |
+> | --- | --- |
+> | `spur team assign <task-id> <agent-id>` | `spur task update <wbs> --assignee <spec-id>` |
+> | `spur team status` | `spur agent list --specs` (same live-run merge) |
+> | `spur team status --by-team` | dropped — one project has one fleet; `spur agent list --specs` is the single fleet listing |
+> | `spur team up <team>` | fleet materialization at `spur serve` start (`.spur/fleet.json`); `up --check` diff → `spur projects list --fleet` |
+> | `spur team down <team> [--purge]` | `spur agent stop <spec-id>` per member (`spur agent delete <id>` replaces `--purge`) |
+> | `spur team start <agent-id>` | `spur agent start <spec-id>` |
+> | `spur team stop <agent-id>` | `spur agent stop <spec-id>` |
+
+> **Retiring:** `spur team` is a retiring surface for spur-* guidance. `sp:expert-spur`,
+> `sp:spur-composer` and `sp:spur-doctor` forbid it, and coordination or recurring loops belong to
+> `sp:super-planner` or a workflow. Reach agent specs through `spur agent ... --specs` and use
+> `spur message` for coordination transport. This reference is retained for CLI parity while the
+> noun still ships; do not build new guidance on it.
 
 `spur team` is the CLI for **coordinating team agent assignments and supervision**. It sits above
 `spur agent` specs: `up` / `down` materialize and tear down rosters, `start` / `stop` manage

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.
 
 ---
 

package/plugins/sp/skills/spur-composer/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: spur-composer
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows and agent specs. Owns workflow catalog selection, the ephemeral→project→shared ladder, the ADR-115 budgets, trace-driven rule tuning, and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, apply doctor proposals."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: artifact-composition
+  interactions:
+    - inversion
+    - companion
+  operations:
+    - select
+    - compose
+    - tune
+    - apply
+  openclaw:
+    emoji: "🎼"
+see_also:
+  - sp:spur-cli
+  - sp:spur-doctor
+  - sp:super-planner
+---
+
+# sp:spur-composer — compose, select and tune spur artifacts
+
+One cross-noun method (ADR-114, [spur artifact evolution](../../../../docs/design/spur-artifact-evolution.md)
+§2): **select** an existing artifact, **compose** a new one up the ladder, **tune** it against
+evidence, and **apply** the proposals the operator accepts from `sp:spur-doctor`. It never judges
+its own output and never runs a recurring loop — evaluation is the doctor's job.
+
+## Boundary — read before composing
+
+- **Verbs and flags live in `sp:spur-cli`.** This skill links references; it never restates a verb
+  or flag catalog: [../spur-cli/SKILL.md](../spur-cli/SKILL.md).
+- **Recurring loops and coordination go to `sp:super-planner`** or a workflow — not here. This skill
+  runs one bounded composition or tuning pass per invocation.
+- **Forbidden surfaces: `spur team` and `spur agent loop`.** Agent specs are reached only through
+  `spur agent create|edit|delete|list --specs`.
+- **Writes land only through `spur` verbs** and the ladder's gated file steps (§ below). The shared
+  step additionally needs recorded operator consent plus `build:bundle` parity.
+
+## Covered nouns
+
+| Noun | Composition / tuning method | Verb reference |
+| --- | --- | --- |
+| task | Apply accepted doctor rows via the CLI-gated corpus surface; author variants through the task reference's conventions | [../spur-cli/references/tasks.md](../spur-cli/references/tasks.md) |
+| feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
+| rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
+| workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
+| agent spec | Compose and edit `.spur/agents/<id>.yaml` only through `spur agent create|edit|delete|list --specs` | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
+
+Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.
+
+## Workflow catalog selection
+
+Run this **before composing anything new**, exactly as the
+[find-existing-workflow](../spur-cli/references/workflows/operations.md#sub-procedure-find-existing-workflow)
+procedure: the catalog is `spur workflow list --json` across all layers, and each entry's
+`description` is its intent.
+
+| Catalog match | Action |
+| --- | --- |
+| Matches the intent | **Run it as is.** No new artifact. |
+| Near match | **Same-name override in the project layer** (`.spur/workflows/<name>.yaml`) — the project layer wins name resolution — and tune from there. |
+| No match | **Compose** up the ladder (§ Composition ladder). |
+
+Never glob a folder to enumerate candidates: layers you skip that way are layers a bare name
+cannot resolve from.
+
+## Composition ladder
+
+| Step | Location | Gate before use |
+| --- | --- | --- |
+| ephemeral | A scratch file outside every layer (for example under `.spur/run/`), run by explicit path | `spur workflow validate`, `spur workflow run --dry-run`, a `spur workflow show` preview |
+| project | `.spur/workflows/<name>.yaml` | The same gates |
+| shared | the spur repository's shipped shared workflow layer (layer id `shared` in `spur workflow list --json`) as `<name>.yaml` | The same gates, **plus recorded operator consent and `build:bundle` parity** |
+
+- `spur workflow validate --json` exits 1 on an error-level composition finding, so a definition
+  over a cap cannot climb. Warn-level findings do not block a step.
+- Verify each step through the shared
+  [validate-and-dry-run](../spur-cli/references/workflows/operations.md#sub-procedure-validate-and-dry-run)
+  core. The shared step is a promotion, not a copy: record the operator consent that authorizes it,
+  then rebuild the bundle (`bun run --filter @gobing-ai/spur build:bundle`) so the shipped config
+  matches.
+- In an adopting project the shared layer is the installed package and is read-only — the project
+  step is the tuning path there.
+
+## Composition budgets (ADR-115)
+
+The consolidation and cache-window rules are taught once in
+[workflow-fit-and-tuning.md](../spur-cli/references/workflows/workflow-fit-and-tuning.md#consolidation-and-cache-windows-adr-115)
+and owned by the
+[workflow composition contract](../../../../docs/design/workflow-composition-contract.md#composition-budgets-adr-115);
+link them, never restate them. While composing or tuning a workflow, apply them with the ADR-115
+budgets:
+
+- **Merge adjacent model steps** only when they share a role and an executor **and** no gate, HITL
+  state or independence boundary sits between them.
+- **Never merge an author step with the review or verify step that certifies it** — those keep
+  `freshSession: true`.
+- **Run long deterministic work outside `agent.run`** — an in-step tool call that outlasts the
+  cache window idles the model and cold-rewrites the prefix.
+
+A new model step in a shared workflow raises its `pipeline-budgets` `modelQueries`; that needs a
+recorded decision before the shared step.
+
+## Rule tuning loop
+
+Start from trace evidence, never from a guess:
+
+1. `spur rule trace <runId> --json` — read the per-rule `evaluations` findings and severities.
+2. Classify each hit: true positive, false positive, or noise.
+3. Tune with the [fine-tuning levers](../spur-cli/references/rules/fine-tuning.md) — severity,
+   glob scoping, exemptions, preset composition.
+4. `spur rule validate` on the tuned rule files.
+5. `spur rule run` on the affected inputs (constitution T11 — affected inputs, not a corpus sweep).
+6. Trace again and compare. A tuning with no trace pair behind it is a preference.
+
+## Applying doctor proposals
+
+`sp:spur-doctor` ([../spur-doctor/SKILL.md](../spur-doctor/SKILL.md)) returns a proposal table;
+the operator accepts rows; **this skill applies them**:
+
+1. For each accepted row, run its `apply` route — always the `spur` verb or ladder step named in
+   the row. Composer never invents a write route.
+2. Re-run that row's `verify` evidence and confirm it clears. An accepted row that cannot verify
+   is reported as not applied, never waved through.
+3. A `task` row carries the history-anatomy finding `key` in the task body — the existing handoff
+   route. Keep it.
+4. A row that changes a shared workflow goes through the ladder's shared step and its recorded
+   consent.
+
+A caller that wants a record saves the accepted table under `docs/reports/`; this skill creates no
+artifact store.
+
+## What this skill is not
+
+- **Not the judge.** `sp:spur-doctor` evaluates artifacts and proposes; code review is
+  `sp:super-reviewer`.
+- **Not a loop.** Recurring evolution loops and multi-agent coordination belong to
+  `sp:super-planner` or a workflow definition.
+- **Not a catalog.** Verb, flag, output and exit semantics live in the `sp:spur-cli` references
+  linked above.

package/plugins/sp/skills/spur-dev/references/planning-workflow.md

@@ -270,6 +270,30 @@ missing title match. After batch creation, `handoff-finalize`:
    (runall is then omitted), otherwise `/sp:dev-runall --feature <id> --auto`. The terminal
    handoff note points at this report.
 
+**Ready preparation (ready-prepare, 0788).** The input is the `.wbs` array in
+`.spur/run/<runId>-idea-batch-create-result.json`. For EACH wbs: resolve the task file with
+`spur task path <wbs> --json` and apply the ready-refinement checklist — make requirements,
+design, plan, acceptance criteria, decisions, dependencies and premises present and
+non-placeholder so `spur task check <wbs> --json` exits 0. Write planning sections only, through
+`spur task update <wbs> --section <Name> --from-file <file>` — never Solution, Testing, Review
+or History. Record one checklist row per id, with concrete evidence of how you verified it.
+Compute the planning digest with the project's own implementation when this is a monorepo
+checkout — resolve the file with `spur task path <wbs> --json`, then run:
+
+```bash
+bun -e 'const m = await import("./packages/app/src/services/task-readiness"); console.log(m.computePlanningDigest(await Bun.file(process.argv[1]).text()))' <task-file>
+```
+
+When that is impossible in this checkout, set status `skipped` instead of guessing a digest.
+Finally write `.spur/run/<runId>-idea-ready.json` with exactly this shape:
+
+```json
+{"runId":"<runId>","depth":"ready","tasks":[{"wbs":"<wbs>","status":"ready" | "failed" | "skipped","planningDigest":"<sha256 hex>","checks":[{"id":"requirements" | "design" | "plan" | "ac" | "decisions" | "dependencies" | "premises","pass":true,"evidence":"<how verified>"}]}]}
+```
+
+A task you cannot fully prepare gets status `failed` or `skipped` — never fabricate evidence;
+the handoff degrades to refineall.
+
 ## Step 6: Refine before execute (the spec-completion gate)
 
 `batch-create` accepts optional `design` / `plan` / `acceptance_criteria` fields (plus