@gobing-ai/spur 0.3.87 → 0.3.88

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.87",
+    "version": "0.3.88",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

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

@@ -23,12 +23,14 @@ that before using `run` for fan-out dispatch.
 | ---- | ------- | --------- |
 | `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` |
 | `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 agent specs with `--specs` (live run status merged from `spur serve`) | `--specs` `--server <url>` `--json` |
+| `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur serve`) | `--specs` `--server <url>` `--json` |
+| `status` | Agent specs with live process status and member session (requires `spur serve`) | `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
+| `usage` | Run-once provider usage capture (codexbar) → quota-owned availability refresh; scheduled externally | `--dry-run` `--source <name>` `--json` |
 | `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`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+`list`, `status`, `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.
 
@@ -141,16 +143,30 @@ spur agent list --json       # machine-readable
 Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
 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>`
+(`running` / `stopped` / `errored` / `unknown`), `pid=<n>` where a process exists, and the member
+session (0897): the session mode plus a shortened resume id (`resume id=3f9c2a1d`), or `-` when the
+member has no recorded session. 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
+# planner	claude	reviewer	claude	plans the work	running pid=4132	resume id=3f9c2a1d
+# worker-1	pi	worker	pi	implements	stopped	one-shot
 ```
 
+## `status` - live status + member session per spec
+
+```bash
+spur agent status            # id, type, status, pid, session — one row per spec
+spur agent status --json     # full objects, session carried whole ({ mode, id })
+```
+
+Reads the same supervisor feed as `list --specs` (liveness **and** session come from
+`GET /api/processes`; the served project's ledger is the source of the session state). An
+unreachable server reports every spec `stopped` with no session. See
+[Member sessions](#member-sessions-g66) for what the modes mean.
+
 ## `doctor` - readiness check
 
 ```bash
@@ -161,9 +177,21 @@ spur agent doctor --json     # machine-readable (role selector: elected-first or
 ```
 
 Checks whether each agent is installed and ready to run. Text mode renders a capability table —
-`STATUS EXECUTOR AGENT MODEL TIER VERSION ROLES` where TIER is the executor's *capability* tier
-(`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.
+`STATUS EXECUTOR AGENT MODEL TIER VERSION CAPS ROLES OWNER SINCE REASON` where TIER is the executor's *capability* tier
+(`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), ROLES lists
+candidate pipeline roles with `*` on the elected one, CAPS is the runner-declared session
+capability for the underlying agent binary (`r`esume/`d`ir/`s`tdin/`o`utput as ✓/✗; `—` when the
+binary is unknown to the runner; a trailing `⚠` when the detected version core differs from the
+record's `verifiedAgainst` core — branding decorations are not drift, and a record/detection with
+no version core (e.g. `unverified (CLI not installed)`) is unverifiable and never warns; a stale
+executor also emits a `capability-declaration-stale` warning
+on stderr in text mode), and OWNER/SINCE/REASON (0893) show availability provenance on `disabled`
+rows — bare `disabled: true` renders owner `operator` with `—` since/reason; object-form disables
+render their recorded values. A `usage:` footer reports the `agent usage` snapshot (`capturedAt
+(age)`, `(stale)` past 6 h, or `usage: none` when the producer has never run). `--json` stays
+stderr-clean and carries `capabilities`, `capabilityStale: {verifiedAgainst, detected}`, the
+normalized `availability` object, and a top-level `usage` per agent row instead. Exit `1` if any
+checked agent is not ready.
 
 ## `start` - start a supervised process
 
@@ -188,6 +216,61 @@ Posts to the supervisor API
 (`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
 `start`.
 
+## `usage` - run-once provider usage capture (quota-owned availability refresh)
+
+```bash
+spur agent usage            # capture, record quota observations, drain them
+spur agent usage --dry-run  # print would-be changes; write nothing
+spur agent usage --json
+```
+
+Runs `codexbar usage --format json --provider all` once, writes the snapshot to
+`~/.config/spur/agent-usage.json` (`captured_at`, `source`, `providers[]`, `raw`), maps providers
+to executors via `agent.executors[].agent` (or the model's `<provider>/` prefix), and records
+`owner: quota` availability observations that the standard drain applies — the single availability
+write path. A provider is exhausted when any `primary|secondary|tertiary` window reports
+`usedPercent >= 100`; the window name and `resetsAt` go into the observation reason. Per-provider
+`{ "error": … }` entries are skipped (listed, never treated as recovery); healthy entries still
+apply. A missing codexbar binary or an unparsable payload exits `1` and changes nothing.
+Unmapped providers are listed and never guessed.
+
+**Scheduling is external** (cron/launchd, same pattern as `spur history daily`):
+
+```bash
+# launchd/cron example — hourly
+0 * * * * /opt/homebrew/bin/spur agent usage >> /tmp/spur-agent-usage.log 2>&1
+```
+
+`spur serve` never invokes the producer (asserted by a test, design R4).
+
+### Flags
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--dry-run` | Print would-be changes (executor, from → to, owner, reason); write neither the snapshot nor any config |
+| `--source <name>` | Usage source implementation; only `codexbar` exists (default) |
+| `--json` | Machine-readable result payload |
+
+## Member sessions (G66)
+
+Every fleet member loop keeps ONE coding-agent session for its lifetime, in the warmest mode the
+agent supports (`docs/design/session-pinned-dispatch.md` §6):
+
+| Mode | Mechanism | `id` |
+| ---- | --------- | ---- |
+| `persistent` | One long-lived stdin process; each drained prompt is injected through `send()` | none — the live process IS the session |
+| `resume` | Each drain re-opens the previous drain's session id | the resume id (rendered shortened) |
+| `one-shot` | A fresh session per drain (one lifetime warning per member) | none |
+
+A session **resets** (the ledger records a reason-named `fleet.member-session-reset` row) on:
+`restart` — the persistent process exited and the supervisor's restart policy respawns it;
+`operator` — `spur agent stop` / serve shutdown ended the loop; `failed-drains` — 3 consecutive
+failed drains marked the session poisoned. The next drain opens a fresh session.
+
+**No-redelivery invariant:** delivery state lives in the DB, session continuity is agent memory
+only. A settled (delivered) inbox message is never redelivered — resuming a session or resetting
+one never re-sends settled work; only never-started deliveries release and redeliver (0831/0834).
+
 ## What this skill is NOT
 
 - **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the

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

@@ -1,6 +1,6 @@
 ---
 name: spur-dev
-description: "The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: \"run the pipeline\", \"drive this task\", \"plan a feature end to end\", \"continue the pipeline run\", or operating the full lifecycle."
+description: 'The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: "run the pipeline", "drive this task", "plan a feature end to end", "continue the pipeline run", or operating the full lifecycle.'
 license: Apache-2.0
 metadata:
   author: spur
@@ -36,11 +36,11 @@ metadata:
 # Spur Dev — The Orchestration Spine
 
 `sp:spur-dev` is the **thin orchestration spine** that drives the full planning→execution lifecycle.
-It converts vague intent into shipped work by *orchestrating*, not by doing the work itself: it runs
+It converts vague intent into shipped work by _orchestrating_, not by doing the work itself: it runs
 the gates (feature-check, batch-create) and the execution pipeline with human-in-the-loop control,
 and **dispatches deep competency skills** for each unit of work — it never inlines them. Every write
-to the corpus goes through a CLI verb that validates before writing — the spine knows *how to drive
-the lifecycle*; the competency skills know *how to do each job*; the CLI knows *what is valid*.
+to the corpus goes through a CLI verb that validates before writing — the spine knows _how to drive
+the lifecycle_; the competency skills know _how to do each job_; the CLI knows _what is valid_.
 
 The skill was decomposed **by function** (ADR-028): design, decomposition, implementation, testing,
 and verification each became a standalone competency skill, leaving this spine to orchestrate them.
@@ -51,14 +51,14 @@ status-transition verbs, are the facade's (`sp:spur-cli`), never this skill's.
 
 **The competencies the spine dispatches:**
 
-| Unit of work | Competency skill |
-| -------------- | ------------------ |
-| Design / ADR judgment (shape a task) | `sp:sys-architecture` |
-| Feature/spec → task batch | `sp:spec-decomposition` |
-| Implement to spec | `sp:code-implementation` |
-| Coverage / test extension | `sp:code-testing` |
-| Review (multi-dimensional) | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` |
-| Test-first discipline (composed in) | `sp:test-driven-development` |
+| Unit of work                         | Competency skill                                                        |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| Design / ADR judgment (shape a task) | `sp:sys-architecture`                                                   |
+| Feature/spec → task batch            | `sp:spec-decomposition`                                                 |
+| Implement to spec                    | `sp:code-implementation`                                                |
+| Coverage / test extension            | `sp:code-testing`                                                       |
+| Review (multi-dimensional)           | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` |
+| Test-first discipline (composed in)  | `sp:test-driven-development`                                            |
 
 CLI verb usage for any `spur` noun lives in the `sp:spur-cli` facade. This spine owns only the
 lifecycle, the gates, and the section-write contract (`cross-cutting.md`).
@@ -103,26 +103,26 @@ Host-session procedure: **[references/inline-pipeline-driver.md](references/inli
 Each step delegates to a CLI verb and is documented in exactly one reference file. Read the
 reference for the half you're operating; do not duplicate its content here.
 
-| Step | Half | CLI gate | Reference |
-| ------ | ------ | ---------- | ----------- |
-| Intake | planning | — (prompt work) | [planning-workflow.md](references/planning-workflow.md) · [product-planning.md](references/product-planning.md) |
-| Feature create + AC | planning | `spur feature create` | [planning-workflow.md](references/planning-workflow.md) · [ac-style-guide.md](references/ac-style-guide.md) |
-| Feature check gate | planning | `spur feature check` | [planning-workflow.md](references/planning-workflow.md) |
-| Decomposition (dispatch) | planning | `task-batch.schema.json` | `sp:spec-decomposition` competency — the spine dispatches, does not inline |
-| Batch-create gate | planning | `spur task batch-create` | [planning-workflow.md](references/planning-workflow.md) |
-| Design doc | planning | — (prompt work; §4.5/T9) | [planning-workflow.md](references/planning-workflow.md) |
-| Refine | planning | `spur task update --section` | [planning-workflow.md](references/planning-workflow.md) |
-| Batch refine | planning | `sp:dev-refineall` → per-task `refine` | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md) |
-| Task selection | execution | `spur task list` | [execution-workflow.md](references/execution-workflow.md) |
-| Pipeline run | execution | inline YAML driver or `spur workflow run` | [execution-workflow.md](references/execution-workflow.md) · [inline-pipeline-driver.md](references/inline-pipeline-driver.md) |
-| Implement (dispatch) | execution | `sp:code-implementation` | competency skill — the spine dispatches, does not inline |
-| Test (dispatch) | execution | `sp:code-testing` | competency skill — the spine dispatches, does not inline |
-| Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline |
-| Operation catalog | execution | `sp:dev-*` operations | [dev-operations.md](references/dev-operations.md) (spine dispatch table) |
-| Continue | execution | `spur feature update` / `refresh` | [execution-workflow.md](references/execution-workflow.md) |
-| Batch run | execution | `sp:super-planner` + `spur workflow run` | [execution-batch.md](references/execution-batch.md) |
-| Parallel fan-out | execution | `sp:parallel-execution` decision framework | [execution-batch.md](references/execution-batch.md) |
-| All writes (both halves) | — | CLI-gated section editing | [cross-cutting.md](references/cross-cutting.md) · [section-batching.md](references/section-batching.md) (one-writer protocol, F92 0593) |
+| Step                       | Half      | CLI gate                                                                                  | Reference                                                                                                                               |
+| -------------------------- | --------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Intake                     | planning  | — (prompt work)                                                                           | [planning-workflow.md](references/planning-workflow.md) · [product-planning.md](references/product-planning.md)                         |
+| Feature create + AC        | planning  | `spur feature create`                                                                     | [planning-workflow.md](references/planning-workflow.md) · [ac-style-guide.md](references/ac-style-guide.md)                             |
+| Feature check gate         | planning  | `spur feature check`                                                                      | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Decomposition (dispatch)   | planning  | `task-batch.schema.json`                                                                  | `sp:spec-decomposition` competency — the spine dispatches, does not inline                                                              |
+| Batch-create gate          | planning  | `spur task batch-create`                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Design doc                 | planning  | — (prompt work; §4.5/T9)                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Refine                     | planning  | `spur task update --section`                                                              | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Batch refine               | planning  | `sp:dev-refineall` → per-task `refine`                                                    | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md)                 |
+| Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
+| Pipeline run               | execution | inline YAML driver or `spur workflow run`                                                 | [execution-workflow.md](references/execution-workflow.md) · [inline-pipeline-driver.md](references/inline-pipeline-driver.md)           |
+| Implement (dispatch)       | execution | `sp:code-implementation`                                                                  | competency skill — the spine dispatches, does not inline                                                                                |
+| Test (dispatch)            | execution | `sp:code-testing`                                                                         | competency skill — the spine dispatches, does not inline                                                                                |
+| Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline                                                                               |
+| Operation catalog          | execution | `sp:dev-*` operations                                                                     | [dev-operations.md](references/dev-operations.md) (spine dispatch table)                                                                |
+| Continue                   | execution | `spur feature update` / `refresh`                                                         | [execution-workflow.md](references/execution-workflow.md)                                                                               |
+| Batch run                  | execution | `sp:super-planner` + `spur workflow run`                                                  | [execution-batch.md](references/execution-batch.md)                                                                                     |
+| Parallel fan-out           | execution | `sp:parallel-execution` decision framework                                                | [execution-batch.md](references/execution-batch.md)                                                                                     |
+| All writes (both halves)   | —         | CLI-gated section editing                                                                 | [cross-cutting.md](references/cross-cutting.md) · [section-batching.md](references/section-batching.md) (one-writer protocol, F92 0593) |
 
 ## When to use
 
@@ -180,7 +180,7 @@ CLI does.
    section.
 3. **Resolve task IDs through the CLI.** Read a known WBS with `spur task show <wbs> --json`; it
    returns metadata, full content, and `filePath` across configured task folders. Use `spur task
-   path <wbs> --json` only when another tool needs the absolute path. Never search `docs/tasks*` or
+path <wbs> --json` only when another tool needs the absolute path. Never search `docs/tasks*` or
    guess `--folder`; reuse the first `show` response throughout the run.
 4. **Check before every write.** Run `spur task check <wbs> --json` to know what sections
    the task needs at its current status. Guessing produces matrix violations.

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -153,10 +153,23 @@ must not be changed without updating the backing skill.
 
 ### 5. refine
 
-- **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design.
-- **Inputs:** `<wbs>` (required). `--focus <mode>` narrows the gap analysis. `--depth <standard|ready>` (default **`standard`**) sets the depth bar — see [flag-glossary.md](flag-glossary.md#flag-depth). Execution defaults to inline (in-session); `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips interactive Q&A (synthesis only) and propagates down the `--next` chain. `--next`: advance to the next step — transition `backlog → todo` through the FSM **idempotently** (only when `status == backlog`; a task already at `todo` or past it skips the transition and chains anyway — `status >= todo` ⇒ already advanced) and invoke `/sp:dev-run <wbs> --mode implement --auto --next`. On a guard/refine failure, stop as review-pending.
+- **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design, and is also the path for **evaluating and correcting an existing task** — a review-triage filing, a stale backlog capture, or any task whose claims and proposed fixes may no longer hold.
+- **Inputs:** `<wbs>` (required). `--focus <mode>` narrows the gap analysis (values below). `--description <text>` injects operator framing into the Q&A/synthesis. `--depth <standard|ready>` (default **`standard`**) sets the depth bar — see [flag-glossary.md](flag-glossary.md#flag-depth). Execution defaults to inline (in-session); `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips interactive Q&A (synthesis only) and propagates down the `--next` chain. `--next`: advance to the next step — transition `backlog → todo` through the FSM **idempotently** (only when `status == backlog`; a task already at `todo` or past it skips the transition and chains anyway — `status >= todo` ⇒ already advanced) and invoke `/sp:dev-run <wbs> --mode implement --auto --next`. On a guard/refine failure, stop as review-pending.
+- **Status scope:** refine targets `backlog`/`todo` tasks (the same rule `batch-preflight` applies to refineall). A task at `wip` or later has an implementation built on its current spec. Refine it only on an explicit operator request, never under `--auto` alone, and never move its status backwards.
+- **`--focus` values** (hint bundles for the gap analysis/Q&A; default `all`):
+
+  | Value | Domain hints | When |
+  | --- | --- | --- |
+  | `all` | purpose, scope, constraints, dependencies, acceptance criteria, users, timeline | Complete refinement |
+  | `requirements` | purpose, scope, acceptance criteria | Standard refinement |
+  | `background` | purpose, scope | Thin tasks needing context |
+  | `constraints` | constraints, dependencies, timeline | Technical depth |
+  | `acceptance` | acceptance criteria, users | Verification focus |
+  | `quick` | scope, acceptance criteria | Fast pass |
+
+  Focus narrows what `--depth standard` looks at. Under `--depth ready` the full checklist still runs, and focus only orders the work.
 - **Backing:** `sp:spur-dev` skill, `refine` operation. Q&A clarifications are presented as decision briefs per [decision-brief.md](decision-brief.md).
-- **Behavior:** Read the task → elicit missing AC/Design/Plan through targeted Q&A (or auto-synthesis) → write each via `spur task update <wbs> --section <name> --from-file`. Done just-in-time, per task, immediately before execution. With `--next`: on success, transition status (idempotently — see Inputs) + chain to dev-run; on failure, stop and surface error.
+- **Behavior:** Read the task → (ready depth) audit the existing content against the current tree → elicit missing or wrong Background/Requirements/AC/Design/Plan through targeted Q&A (or auto-synthesis) → write each via `spur task update <wbs> --section <name> --from-file`. Done just-in-time, per task, immediately before execution. With `--next`: on success, transition status (idempotently — see Inputs) + chain to dev-run; on failure, stop and surface error.
 - **Pre-synthesis skip gate (under `--auto` + `--depth standard` only):** Before invoking synthesis, run `spur task check <wbs> --json`. Filter the findings to the **refine target sections** only:
   `{Background, Requirements, Acceptance Criteria, Design, Plan}`.
   These are the anti-drift surfaces: constraints + planning that cheaper implementers must follow.
@@ -206,28 +219,72 @@ must not be changed without updating the backing skill.
   SKIP — sections already meet implement-ready checklist: depth=ready, sections-considered=[…]
   ```
 
-  **Implement-ready checklist (all must hold for allowed target sections):**
-  1. **Requirements** — R-items are observable outcomes; explicit out-of-scope / non-goals; no
+  **Implement-ready checklist (all must hold for allowed target sections).** Each item's `id` is
+  the `READY_CHECKLIST_IDS` value (`packages/app/src/services/task-readiness.ts`) that the
+  create-time ready preparation and the idea-pipeline ready-prepare stage also use:
+  1. **`requirements`** — R-items are observable outcomes; explicit out-of-scope / non-goals; no
      ambiguous “wire it up” without a named seam or file area.
-  2. **Design** — WHAT / WHY / WHERE; **frozen names** (types, flags, vars, paths) **or** explicit
+  2. **`design`** — WHAT / WHY / WHERE; **frozen names** (types, flags, vars, paths) **or** explicit
      “no new API”; precedence / algorithm when behavior is non-obvious; **anti-patterns** (what not
      to implement); primary file/package targets; handoff to dependent tasks (WBS) if any.
-  3. **Plan** — ordered checklist mappable to R-items; test/verification intent called out.
-  4. **Acceptance Criteria** — scenarios still match feature R-titles when `feature_id` is set;
-     Given/When/Then still executable as a verify lens.
-  5. **Q&A / References** — open decisions closed or explicitly deferred with owner; links to ADR /
+  3. **`plan`** — ordered checklist mappable to R-items; test/verification intent called out.
+  4. **`ac`** — every scenario uses an [ac-style-guide.md](ac-style-guide.md) task-side form
+     (`- [ ] AC<n> — <title>` or `Scenario: AC<n> — <title>`, with `(req: R<n>)`). `spur task check`
+     parses only checkbox and `Scenario:` lines, so any other shape (a plain `- AC1 —` bullet, a bold
+     heading) silently escapes its AC checks. When `feature_id` is set, each AC
+     title matches a feature scenario title, unless the task is deliberately `ac_altitude:
+     task-local`. Given/When/Then stays executable as a verify lens.
+  5. **`decisions`** — Q&A open decisions closed or explicitly deferred with owner; links to ADR /
      feature / upstream tasks present when the design depends on them.
-  6. **Cross-task** — if `dependencies[]` exist, Design states what this task assumes from deps and
-     what it must leave for dependents (no silent re-ownership of upstream contracts).
-  7. **Premise verification** — every factual claim in Background and Requirements that the Design
-     depends on (a status, a file/table/location, an already-landed fix, a count) is checked against
-     the **current tree** — read the file, run the query, grep the corpus. Contradictions are
-     corrected in **this** refine (rewrite the claim, or re-point the design at ground truth), never
-     deferred to the implementer. `--depth ready` exists so a downstream agent does not re-derive the
-     analysis; a frozen design built on a false premise is the worst available outcome.
-
-  Ready depth is for multi-package work, multi-agent implement handoffs, and costly pipeline
-  failures — not for every small task. Default remains `standard`.
+  6. **`dependencies`** — if `dependencies[]` exist, Design states what this task assumes from deps
+     and what it must leave for dependents (no silent re-ownership of upstream contracts). A
+     dependency the Design relies on but `dependencies[]` lacks is added with `spur task deps`.
+  7. **`premises`** — every factual claim in Background, Requirements, Design and Plan is checked
+     against the **current tree** (read the file, run the query, grep the corpus), not only the gaps.
+     This is the **audit pass**; it matters most for a task written earlier or by another agent
+     (review-triage filings, stale backlog). Lenses:
+     - **Facts** — statuses, `file:line` references, type/field/flag names, counts, "already fixed"
+       or "not yet implemented" claims.
+     - **Sources** — a cited run, artifact, session or doc exists and says what the task claims. If
+       it is gone, say so and restate the claim from code.
+     - **Fix soundness** — each proposed fix holds for every caller and mode of the seam it touches,
+       does not break a currently valid path, and reuses an existing mechanism before adding one.
+     - **Test observability** — each AC names a test layer (and file) that can actually observe the
+       behavior. A test that mocks the collaborator carrying the behavior cannot.
+     - **Environment** — installed dependency versions match the lockfile and generated artifacts
+       are current. If not, the Plan gets a step-0 precondition.
+     - **Concurrency** — active worktrees or `wip` tasks touching the same files (`git worktree
+       list`, `spur task list --status wip --json`) are recorded in References/Design.
+     - **Scope** — the work is not already done, and not owned by another task.
+
+     Contradictions are corrected in **this** refine (rewrite the claim, or re-point the design at
+     ground truth), never deferred to the implementer. `--depth ready` exists so a downstream agent
+     does not re-derive the analysis; a frozen design built on a false premise is the worst
+     available outcome.
+
+  **Correction record.** When the audit changes a claim, append a dated block to Background —
+  `**Refine corrections (<YYYY-MM-DD>)**`, one line per correction: claim → verified reality →
+  resolution. Never delete an earlier block, so the next reader sees what changed and why. Scope
+  decisions made along the way also go into Q&A as closed decisions.
+
+  **Ready finalization.** Once every item holds:
+  1. Run `spur task check <wbs> --as todo --json`. Any error means the task is not ready. Fix it,
+     or report `failed`.
+  2. Fill metadata that is still unset: `spur task update <wbs> --priority <P0–P3>` and
+     `--estimate-hours <n>` (both `--json`). Never overwrite a value the operator set.
+  3. Promote `backlog → todo` idempotently with `spur task update <wbs> todo --json`, the same FSM
+     transition `--next` uses. Create-time ready preparation skips its own promotion when the task
+     is already `todo`, and next-router stops routing the task back to refine. Without `--next`,
+     refine does not chain into run.
+  4. Report the checklist as rows `{id, pass, evidence}`, one per id, in the markdown result and in
+     the `--json` object, alongside the corrections count and status before → after.
+
+  A decision refine cannot close under `--auto` makes the outcome `failed`. Report the concrete
+  question, and leave the task at `backlog`.
+
+  Ready depth is the canonical path for three jobs: the ready competency behind `spur task create`
+  (its recovery command), evaluating and correcting an existing task, and freezing multi-package or
+  multi-agent handoffs. It is not for every small task. Default remains `standard`.
 
 - **SKIP short-circuits synthesis, not `--next`.** A SKIP means no synthesis was needed — it does **not** cancel the `--next` chain. Under `--auto --next`, a SKIP still flows into the (idempotent) status transition and the chained `/sp:dev-run --mode implement`. "`refine --auto --next` on a well-specified task" is therefore effectively "run the implement→verify chain"; an operator who wanted refinement only should drop `--next`.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="refine $ARGUMENTS")`
@@ -244,13 +301,13 @@ must not be changed without updating the backing skill.
   1. Resolve + **freeze** the set at kickoff (never re-query membership mid-batch).
   2. Apply `--status` filter (default `backlog` + `todo`; applied in-agent against the frozen set; `spur task list --status` takes exactly one canonical status per call — see `execution-batch.md` Step 1). Tasks already `done`/`cancelled`/`testing` are excluded unless the operator widens `--status`. Report each exclusion with reason.
   3. Topo-sort by `dependencies[]` (Kahn, WBS-ascending tie-break). Cycle → abort entire batch before any refine. Out-of-set deps: `done` → allow; else → block subtree (same as runall).
-  4. For each WBS in order: invoke single-task refine with shared flags **including `--depth`**. Under `--auto` + **`--depth standard`** (default), the per-task **L3 pre-synthesis SKIP gate** still applies. Under **`--depth ready`**, each task runs the implement-ready checklist (no L3-only SKIP).
+  4. For each WBS in order: invoke single-task refine with shared flags **including `--depth`**. Under `--auto` + **`--depth standard`** (default), the per-task **L3 pre-synthesis SKIP gate** still applies. Under **`--depth ready`**, each task runs the implement-ready checklist (no L3-only SKIP). That includes the premises audit, the correction record and ready finalization, so a passing task leaves at `todo`.
   5. Failure policy: **stop-the-batch** (default) or `--keep-going` (skip in-batch dependents of a failed refine; continue independents).
-  6. Emit a batch report (markdown or `--json`) that records `depth` once at the header.
+  6. Emit a batch report (markdown or `--json`) that records `depth` once at the header. Under `--depth ready`, each row also carries the corrections count, status before → after, and failed checklist ids.
 - **Per-task outcome vocabulary:** `refined` (synthesis wrote sections) | `SKIP` (already meets the active depth bar under `--auto`) | `failed` | `skipped` (dep failed under `--keep-going`) | `not-attempted` (halted) | `blocked` (unmet out-of-set dep).
 - **Batch verdict:** `clean` (all attempted tasks `refined` or `SKIP`) | `halted` (a failure stopped the batch) | `aborted` (cycle / unknown selector / empty set after filter).
 - **`--next` is not accepted** (dropped by feature H8, 2026-07-31 — see `plugins/sp/commands/dev-refineall.md` for the removal record). Chain execution explicitly: refineall, then `/sp:dev-runall --feature <id>`.
-- **`--auto` recommendation:** Batch refine without `--auto` requires per-task interactive Q&A and does not scale. Default operator path: `/sp:dev-refineall --feature <id> --auto`. For implement handoffs: `/sp:dev-refineall --feature <id> --auto --depth ready`.
+- **`--auto` recommendation:** Batch refine without `--auto` requires per-task interactive Q&A and does not scale. Default operator path: `/sp:dev-refineall --feature <id> --auto`. For implement handoffs, or to re-audit a feature's filed tasks: `/sp:dev-refineall --feature <id> --auto --depth ready`.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="refineall $ARGUMENTS")` → per task `Skill(skill="sp:spur-dev", args="refine <wbs> $SHARED_FLAGS")` (shared flags include `--depth` when set).
 
 ### 6. plan

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -174,7 +174,8 @@ establishes a baseline with it before the first change and re-runs it after each
 Constrain the operation to a named subset of dimensions — review dimensions on `dev-review`/
 `dev-verify`/`dev-verifyall` (`all|stack|dependencies|data|flows|api|security|quality|performance`),
 a refactor lens set on `dev-refactor` (`api|architect|tests|ui|auto`), a refine focus mode on
-`dev-refine`/`dev-refineall`, or a reconstruction lens on `dev-reverse`.
+`dev-refine`/`dev-refineall` (`all|requirements|background|constraints|acceptance|quick` —
+[dev-operations.md](dev-operations.md) § refine), or a reconstruction lens on `dev-reverse`.
 Narrowing reduces token cost; omitting runs
 all dimensions.
 
@@ -372,10 +373,12 @@ Orthogonal to `--focus` (which _narrows_ domains) and to `--mode` on other comma
 | Value (refine family)             | Bar                                                                                                                                                                                | `--auto` SKIP behavior                                                                             |
 | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | `standard` (default when omitted) | L3 structural completeness (not empty/placeholder; check-clean for target sections)                                                                                                | **SKIP** when no L3 findings on target sections                                                    |
-| `ready`                           | **Implement-ready** freeze: another agent can implement without inventing design (frozen names/APIs or explicit "no new API", anti-patterns, file targets, handoffs, out-of-scope) | **Do not SKIP** on L3-clean alone — run the ready checklist; rewrite sections until the bar is met |
+| `ready`                           | **Implement-ready** freeze: another agent can implement without inventing design (frozen names/APIs or explicit "no new API", anti-patterns, file targets, handoffs, out-of-scope) | **Do not SKIP** on L3-clean alone — audit existing claims, run the ready checklist, rewrite sections until the bar is met, then promote `backlog → todo` |
 
 Default for refine stays `standard` so ordinary `refineall --auto` remains cheap. Use `ready` for
-multi-package / multi-agent handoffs and flaky-pipeline features where a wrong implement is costly.
+multi-package / multi-agent handoffs, flaky-pipeline features where a wrong implement is costly, and
+evaluating/correcting an existing task (review-triage filing, stale backlog) whose claims may no
+longer hold.
 Full checklist: [dev-operations.md](dev-operations.md) § refine (depth ready).
 
 ### `--bdd` — use BDD scenarios as the verification lens

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

@@ -301,10 +301,12 @@ the handoff degrades to refineall.
 (and preferably Plan/AC) so tasks land **content-ready**. **`--skip-design`:** leave `design`
 empty — headings only.
 
-**Refine is the fallback**, not the primary Design author:
+**Refine is the fallback** Design author, not the primary one. It is also the audit path for
+tasks that already have content:
 
 ```text
 /sp:dev-refine <wbs>          # single task — fills blank Design/AC/Plan if L3 gaps
+/sp:dev-refine <wbs> --depth ready    # evaluate + correct an existing/filed task, then promote to todo
 /sp:dev-refineall --feature X --auto
 /sp:dev-refineall --feature X --auto --depth ready   # implement-ready freeze (no L3-only SKIP)
 ```
@@ -314,7 +316,9 @@ Under `--auto` + **`--depth standard`** (default), refine **SKIP**s when target
 placeholder, synthesis runs (standard tier by default; escalates only on gate-fail). Under
 **`--depth ready`**, do not SKIP on L3-clean alone — run the implement-ready checklist in
 [dev-operations.md](dev-operations.md) § refine (frozen APIs, anti-patterns, file targets, handoffs)
-so another agent can implement without inventing design.
+so another agent can implement without inventing design. Ready depth also audits every existing
+claim against the current tree, records corrections in Background, and promotes a passing task
+`backlog → todo`.
 
 **Check the variant before you write.** Which sections a task carries is decided by its `template:`
 frontmatter against `.spur/tasks/section-matrix.yaml` — NOT a fixed list. Before authoring any
@@ -344,16 +348,16 @@ feature filled before a runall, use `/sp:dev-refineall --feature <id> --auto` (b
 of `/sp:dev-refine`). It reuses the same per-task refine operation, freezes the set, topo-sorts by
 `dependencies[]`, and emits a batch report — see [dev-operations.md](dev-operations.md) § refineall.
 This does **not** replace just-in-time refine before each implement; it is a bulk pre-pass when the
-feature's tasks are still `backlog`/`todo` placeholders. Prefer `--auto` for batch scale; avoid
-`--next` on large features (that chains each task into run).
+feature's tasks are still `backlog`/`todo` placeholders. Prefer `--auto` for batch scale.
+`/sp:dev-refineall` takes no `--next`; chain with `/sp:dev-runall --feature <id>` afterwards.
 
 **Refine arguments** (defined on the `/sp:dev-refine` entry point, passed through verbatim; also
 shared flags on `/sp:dev-refineall`):
 
 | Argument | Effect |
 |----------|--------|
-| `--focus <mode>` | Narrows the gap analysis to a subset of domain hints. See the `sp:dev-refine` skill for the full value table (`all`, `requirements`, `background`, `constraints`, `acceptance`, `quick`). Default `all`. |
-| `--depth <standard\|ready>` | Spec depth bar. `standard` (default) = L3 structural completeness + L3 SKIP under `--auto`. `ready` = implement-ready freeze (never L3-only SKIP). See [flag-glossary.md](flag-glossary.md#flag-depth). |
+| `--focus <mode>` | Narrows the gap analysis to a subset of domain hints. Values `all`, `requirements`, `background`, `constraints`, `acceptance`, `quick` — hint table in [dev-operations.md](dev-operations.md) § refine. Default `all`. Under `--depth ready` it only orders the work. |
+| `--depth <standard\|ready>` | Spec depth bar. `standard` (default) = L3 structural completeness + L3 SKIP under `--auto`. `ready` = audit + implement-ready freeze + promote to `todo` (never L3-only SKIP). See [flag-glossary.md](flag-glossary.md#flag-depth). |
 | `--auto` | Skip interactive Q&A — synthesize improvements from the task content alone. Use for well-scoped tasks where the agent can fill gaps without operator input. **Required for practical batch use** via `dev-refineall`. |
 
 **Pre-synthesis skip gate (under `--auto` + `--depth standard`).** Before synthesizing, run `spur task check <wbs> --json`. When the **refine target sections** show no L3 findings, emit a structured SKIP instead of calling the synthesis agent. **Not applied when `--depth ready`.**

package/schemas/spur-config.schema.json

@@ -167,8 +167,20 @@
                                 "description": "Capability tier for stage-registry adaptive model routing (ADR-033, 0343). Live values: cheap | standard | capable-1 | capable-2 | capable-3 (1=low output quality, 3=high within the capable band). A stage starts on the cheapest eligible executor meeting its model_policy min_tier. Bare legacy `capable` is accepted at runtime (zod preprocess \u2192 capable-1) during the deprecation window but is not part of this editor enum."
                             },
                             "disabled": {
-                                "type": "boolean",
-                                "description": "Routing kill-switch (111): a disabled profile never serves a role, team, stage, or explicit selection, and doctor inventories it without probing. Omitted = enabled; only true/false accepted (no string/number/null coercion)."
+                                "description": "Routing kill-switch (111; ownership widened 0890): a disabled profile never serves a role, team, stage, or explicit selection, and doctor inventories it without probing. Omitted = enabled. Bare `true` is operator-owned (only humans write booleans); automatic writers emit the object form carrying owner (operator|quota|probe), since (RFC 3339) and reason.",
+                                "anyOf": [
+                                    { "type": "boolean" },
+                                    {
+                                        "type": "object",
+                                        "additionalProperties": false,
+                                        "required": ["owner", "since", "reason"],
+                                        "properties": {
+                                            "owner": { "enum": ["operator", "quota", "probe"] },
+                                            "since": { "type": "string", "format": "date-time", "minLength": 1 },
+                                            "reason": { "type": "string", "minLength": 1 }
+                                        }
+                                    }
+                                ]
                             }
                         }
                     }