@gobing-ai/spur 0.3.61 → 0.3.63

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -237,6 +237,36 @@ downstream task creation does not inherit an unactionable acceptance criterion:
 
 The tag is a prompt to whoever turns findings into tasks: `[stale]` → drop, `[unverifiable]` →
 reframe or defer, `[feasible]` → proceed. A finding without a tag is treated as `[feasible]`.
+
+**Optional class tag (environment lens, task 0686).** A finding line may carry one closed class
+tag — `environment` | `testee` | `waste` — positioned immediately after the em dash and distinct
+from the trailing feasibility tag:
+
+```
+- **P2** — [environment] <what's wrong>. → **Action:** <concrete change>.  (`file:line`, ~effort)  `[feasible]`
+```
+
+Omitting the class preserves the current line shape; untagged findings remain valid and the
+protocol stays `sp:dogfood-testing@1.2` (the validator gains no required field; the cache-health
+P3 above needs no class).
+
+- `testee` — a defect in the testee's contract (the protocol the run grades). Bounded fix-mode
+  may repair it, unchanged.
+- `environment` — a steering/placement/check-shaped observation projected from the
+  [environment-improvement lens](../../../references/environment-lens.md), which owns the
+  category table and the placement rule. **Proposal-only:** even under `--max-retry N`, bounded
+  retries never `Edit` or `Write` `AGENTS.md`, `CLAUDE.md`, skills, rules, numbered docs, or
+  plugin references for an environment-tagged finding — it stays a recommended action here.
+- `waste` — a token/tool-waste diagnostic with no missing environment affordance behind it.
+
+Class, not the cited file path, decides whether bounded fix may mutate. A session mistake a
+linter, typechecker, test, or filesystem gate could have caught is `environment`, and its
+recommended action proposes a new-or-tighter automated check — never another sentence in an
+always-loaded steering file. Missed coding standards are `environment` owned by a review path
+(`sp:code-verification`, `sp:code-review`, or pipeline review) — never the implementer skill;
+navigation friction and dead always-loaded instructions are likewise `environment`, not
+`testee`.
+
 Severity scale:
 
 - **P1** — blocks correct use or causes drift/wrong output; fix before shipping the testee.

package/plugins/sp/skills/history-anatomy/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: history-anatomy
+description: "Independent owner of diagnostic interpretation over already-imported history — the daily/ad-hoc mode contract, a closed finding taxonomy, the twelve-section report contract, and the enrich/validate rubrics. Triggers: history-anatomy, run the daily report, ad-hoc diagnosis, find issues over history."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: analysis-core
+  interactions:
+    - pipeline
+    - inversion
+  pipeline_steps:
+    - report
+    - identify
+    - propose
+    - generate
+  openclaw:
+    emoji: "🩺"
+see_also:
+  - sp:issue-finding
+  - sp:spur-cli
+  - sp:spur-dev
+---
+
+# sp:history-anatomy
+
+Owns **interpretation only** over already-imported history. It decides which arguments are legal
+in which mode, what counts as evidence, how findings are keyed and graded, and what a published
+report must contain, plus the rubrics its `enrich` and `validate` operations follow. It never
+launches a workflow, never reprocesses raw history files, and never mutates the corpus, docs, or sources —
+all orchestration lives in `history-anatomy.yaml` (0660), not here.
+
+This body routes to the three references; the procedure lives there (the BODY_BUDGET shape — a
+fresh skill cannot be added to the BASELINE exemption map).
+
+**Choose the mode first.** The single entry is `--mode daily|ad-hoc` (default `daily`):
+`references/modes.md`.
+
+**Then hold the report to the contract.** Every report must contain the twelve sections and every
+finding the full field set, with evidence rules and an explicit comparability verdict:
+`references/report-contract.md`.
+
+**Then apply the operations.** The workflow calls `enrich` to author the model half, and
+`validate` to gate a candidate report; neither operation launches a workflow:
+`references/operations.md`.
+
+## Primary directive
+
+- The artifact is the only evidence plane. A dimension the forensics artifact cannot support is a
+  **telemetry gap** reported as `not available` — never a raw history-file fallback.
+- Every causal claim needs **two independent signals** (or one labelled hypothesis with a
+  confirmation path). Every finding carries at least one evidence anchor. No anchor, no finding.
+- The report never states a trend, delta, or percentage it cannot support — an insufficient or
+  materially different baseline renders `not comparable`, with no fabricated comparison.
+- Findings are keyed on a **stable key**, never the prose title, so rewording never reclassifies
+  recurrence.
+- Remediation options are **proposals only**: an owner surface, expected impact, a verification
+  method, and reversibility. No applied change, diff, or command the report claims to have run.
+
+## Read the references
+
+| Reference | Owns |
+| --- | --- |
+| [`references/modes.md`](references/modes.md) | The daily/ad-hoc mode matrix, bounds normalization, the DST-aware calendar-day rule, and the fail-loud message shape. |
+| [`references/report-contract.md`](references/report-contract.md) | The twelve sections (in order), the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards. |
+| [`references/operations.md`](references/operations.md) | The `enrich` and `validate` operation rubrics; neither launches a workflow. |

package/plugins/sp/skills/history-anatomy/references/modes.md

@@ -0,0 +1,82 @@
+# Mode contract — `sp:history-anatomy` (HA-S1, 0658)
+
+The skill resolves exactly two modes. Everything else fails loud. This matrix is the enforcement
+surface the workflow (0660) and the skill share; keep the vocabulary frozen.
+
+## Mode vocabulary (frozen)
+
+- Modes: `daily` | `ad-hoc`.
+- Unsupported value literal: `not available`.
+
+## Resolution rule
+
+`--mode <value>` selects the mode. If `--mode` is omitted, the resolved mode is **`daily`** and the
+resolved window is the **current local calendar day**.
+
+## `--mode daily` (default)
+
+| Allowed | Behavior |
+| --- | --- |
+| (none) | Default window = the current local calendar day. |
+| `--date <YYYY-MM-DD>` | Selects that local calendar day as the window. |
+
+Rejected arguments (each fails loud, naming the offending argument):
+
+| Argument | Why rejected |
+| --- | --- |
+| focus text (positional) | Daily mode has no focus string. |
+| `--since` / `--until` | Daily always uses the calendar-day window. |
+| `--output` | Daily always writes to the run directory (see 0660). |
+
+A daily invocation must print the normalized **inclusive ISO bounds** and the timezone used, so the
+wall-clock window is auditable.
+
+## `--mode ad-hoc`
+
+Requires a **non-empty focus** and **two ordered inclusive bounds**.
+
+| Argument | Rule |
+| --- | --- |
+| focus (positional) | Required; a missing or empty focus fails loud. |
+| `--since <iso>` | Required; the inclusive lower bound. |
+| `--until <iso>` | Required; must be present with `--since`; must not be earlier than `--since`. |
+| `--output <path>` | Optional; when present, writes to that explicit path. When absent, writes to the run directory. |
+
+Rejected arguments (each fails loud, naming the offending argument):
+
+| Argument | Why rejected |
+| --- | --- |
+| `--date` | Ad-hoc windows are explicit bounds, not a single date. |
+| `--recompute` | Ad-hoc never recomputes a cache (0660 owns the cache branch). |
+
+## Bounds normalization
+
+Normalize both bounds to inclusive ISO-8601 instants. The report prints the normalized bounds and
+the timezone used.
+
+## DST-aware calendar-day rule
+
+`--date <YYYY-MM-DD>` must span the **full local calendar day including any DST shift** — it is
+never a fixed 24-hour offset from local midnight.
+
+- Resolve the local timezone (the operator's configured zone; state it in the report).
+- The interval runs from the day's first local instant to the day's last local instant.
+- On a 23-hour or 25-hour daylight-saving day, the interval is that actual length, not 24 hours.
+- The bounds are NOT computed as `midnight + 24h`.
+
+This is what makes a daily report's window reproducible across DST transitions.
+
+## Fail-loud message shape
+
+Every rejection names the offending argument and the rule it violated, e.g.:
+
+```
+--mode daily rejects "focus text" (daily mode has no focus string)
+--mode ad-hoc requires a non-empty focus
+--mode ad-hoc: --until is missing --since
+--mode ad-hoc: --until (2026-08-01T00:00:00Z) is earlier than --since (2026-08-02T00:00:00Z)
+--mode ad-hoc rejects --date (ad-hoc uses explicit --since/--until bounds)
+```
+
+A combined conflict (e.g. `--mode daily --since X`) reports **each** offending argument it can
+attribute; at minimum it names the first conflicting one.

package/plugins/sp/skills/history-anatomy/references/operations.md

@@ -0,0 +1,80 @@
+# Operations — `sp:history-anatomy` (HA-S1, 0658)
+
+The skill exposes exactly two operations, invoked by `history-anatomy.yaml` (0660):
+
+- `enrich` — the model is given the rendered forensics artifacts (current + baseline) and authors
+  the model half of the report.
+- `validate` — the model is given a candidate report and independently checks its evidence claims
+  against the artifacts.
+
+Both are **skill operations**, not workflows. **Neither operation launches a workflow** — that is
+the recursion guard. This is why the rubric lives here, single-sourced, rather than being
+duplicated into the YAML: the rubric cannot recurse.
+
+## Invocation contract
+
+| Operation | Input | Output |
+| --- | --- | --- |
+| `enrich` | current forensics artifact + baseline artifact (plain `HistoryArtifact` JSON) | the model-authored report sections (Baseline comparison, Findings, Recurrence ledger, Remediation options, Performance analysis, Workflow and process improvements, Report-only advisories, Positive patterns) meeting the report contract |
+| `validate` | a candidate report + the current/baseline artifacts | a PASS / FAIL verdict with per-finding and per-section evidence checks, naming any failing rule |
+
+Freeze these operation names and this input/output contract — 0660 consumes them verbatim.
+
+## `enrich` rubric
+
+Given the current and baseline artifacts, author the model half of the report. Apply, in order:
+
+1. **Scope and provenance** + **Executive summary** + **Evidence ledger** are populated from the
+   artifact and rendered deterministically (or stated as the artifact's own data). The model
+   authors only the sections listed as model-authored.
+2. **Baseline comparison** — apply the comparison semantics: daily → immediately preceding local
+   calendar day; ad-hoc → immediately preceding equal-duration window. If baseline coverage is
+   insufficient or materially different, emit `not comparable` and **no** trend/delta/percentage.
+3. **Findings** — each with the full per-finding field set (key, category, impact, trend,
+   observation, inference, confidence, contradictions, evidenceAnchor, severity, reproCommand,
+   ownerSurface). Categories from the closed vocabulary; stable keys of the form
+   `<category>:<owner-surface>:<signal>`. Severity is the closed P1/P2/P3 vocabulary and is
+   orthogonal to confidence; reproCommand reproduces the observation verbatim; ownerSurface names
+   the concrete owning surface (file/package/command), consistent with the key's middle segment.
+4. **Recurrence ledger** — classify every finding against the baseline on the **stable key**.
+5. **Telemetry gaps** — every dimension the artifact cannot support, rendered `not available`.
+6. **Remediation options** — proposals only (owner surface, expected impact, verification method,
+   reversibility), plus the printed `spur task create` handoff invocation carrying the finding's
+   stable key for accepted proposals. No applied change/diff/auto-write to the corpus.
+7. **Report-only advisories** — repeated identical tool-and-argument signatures surfaced with
+   repetition counts; proposes no automatic interruption (report-only, 0680 R5).
+8. **Positive patterns** — same evidence standard as problems.
+
+Run-cost note (0680 R6): Performance analysis reports what this run's chained `agent.run`
+stages cost using the pairing analytics fold (totalCostUsd / meanDurationMs per pairing); a
+pairing without cost signal renders `not available`, never zero.
+
+Never fabricate a value, a trend, an anchor, or an applied fix. Never launch a workflow.
+
+## `validate` rubric
+
+Given a candidate report and the artifacts, independently verify:
+
+- **Twelve-section completeness and order** — all twelve section names present in the frozen
+  order; none renamed/omitted.
+- **Per-finding fields** — every finding (problem and positive) carries key, category, impact,
+  trend, observation, inference, confidence, contradictions, evidenceAnchor, severity (P1/P2/P3),
+  reproCommand, ownerSurface; category in the closed vocabulary; stable-key grammar. A finding
+  missing any triage field FAILs (the deterministic gate enforces the same set).
+- **Remediation handoff** — each accepted-proposal handoff carries a `spur task create`
+  invocation naming the finding's stable key; no auto-written tasks.
+- **Evidence anchors** — every finding has at least one verifiable anchor; no anchor → FAIL.
+- **Causality gate** — a causal claim with one signal must be labelled a hypothesis with a
+  confirmation path; otherwise FAIL.
+- **Inference names observations** — an inference that does not name its supporting observations
+  FAILs.
+- **Comparability** — a `not comparable` baseline must state no trend/delta/percentage; a stated
+  trend must be supported by a comparable baseline.
+- **Recurrence integrity** — classification is consistent with the stable keys (a rewording must
+  not flip a recurring finding to new).
+- **Positive patterns** — held to the same standard; an anchor-less entry FAILs.
+- **Remediation** — proposals only; any applied change, diff, or command the report claims to have
+  run FAILs.
+
+Emit `PASS` only when every rule holds. On FAIL, name the section, the finding key, and the rule
+violated. Never launch a workflow.

package/plugins/sp/skills/history-anatomy/references/report-contract.md

@@ -0,0 +1,183 @@
+# Report contract — `sp:history-anatomy` (HA-S1, 0658)
+
+The published report is the skill's contract. This reference owns the twelve sections (in order),
+the per-finding field set, the closed category vocabulary, the stable-key grammar, the evidence
+rules, comparison semantics, recurrence classes, and the positive-pattern / remediation standards.
+
+## Twelve required sections (in order, frozen)
+
+1. Scope and provenance
+2. Executive summary
+3. Baseline comparison
+4. Findings
+5. Recurrence ledger
+6. Telemetry gaps
+7. Remediation options
+8. Performance analysis
+9. Workflow and process improvements
+10. Report-only advisories (0680 R5)
+11. Positive patterns
+12. Evidence ledger
+
+These names are consumed verbatim by 0659's structure gate and 0660's validation stage. Do not
+rename, reorder, omit, or restate them.
+
+## Closed category vocabulary (frozen)
+
+- Categories: `reliability` | `repetition` | `workflow` | `performance` | `coverage` |
+  `telemetry` | `positive`.
+
+Every finding's category is drawn from this closed set. No category is invented — explicit
+`category` values outside it fail the structure gate (`finding-invalid-category:<value>`), and so
+do stable keys whose first segment falls outside it (`finding-invalid-key-category:<value>`,
+task 0686). Environment-lens retro category names are encoded only in `<signal>` or the
+owner-surface segment — never as a category. The authoritative seven-name projection table lives
+in the [environment-improvement mapping](../../../references/environment-lens.md), which this
+reference defers to rather than restates.
+
+## Stable finding key (frozen)
+
+Each finding carries a stable key of the form:
+
+```
+<category>:<owner-surface>:<signal>
+```
+
+- `category` — one of the closed vocabulary above.
+- `owner-surface` — the surface that would own a change (e.g. a module, command, or skill; free
+  text is allowed but must be stable across runs).
+- `signal` — a concise, stable machine-readable identifier of the finding.
+
+The key is the recurrence identity. Rewording a finding's title must **never** reclassify it.
+
+## Per-finding field set
+
+Every finding — problem and positive alike — carries the full field set:
+
+| Field | Requirement |
+| --- | --- |
+| `key` | Stable `<category>:<owner-surface>:<signal>` key. |
+| `category` | From the closed vocabulary, matching the key's first segment. |
+| `impact` | What the situation costs or enables (qualitative, or a concrete number where supported). |
+| `trend` | `new` / `recurring` / `regressed` / `improved` / `resolved` / `not-comparable` (see recurrence). |
+| `observation` | What the artifacts show — evidence, not interpretation. |
+| `inference` | What the observation is reasoned to mean; names its supporting observations. |
+| `confidence` | Per-finding: `high` / `medium` / `low`. Never one blanket report-level score. |
+| `contradictions` | Any contradicting signal shown beside the finding, not silently reconciled. |
+| `evidenceAnchor` | At least one anchor to the forensics artifact or cited `file:line`. An entry with no anchor is invalid. |
+| `severity` | Closed vocabulary `P1` / `P2` / `P3` — how much the finding matters. Orthogonal to `confidence`: severity orders work, confidence says how sure we are (0680 R1). The structure gate fails a finding without one. |
+| `reproCommand` | The invocation that reproduces the observation — one command a reader can run verbatim (0680 R2). Gate-enforced. |
+| `ownerSurface` | The concrete surface that owns the fix (a file path, package, or command), consistent with the key's `<owner-surface>` segment but named as a target rather than a slug (0680 R3). Gate-enforced. |
+
+## Evidence rules
+
+Enforcement rail for every claim:
+
+1. **Causality needs two independent signals.** A causal claim supported by two or more
+   independent signals passes. Exactly one signal is not causation — it must be labelled a
+   **hypothesis** with a stated confirmation path.
+2. **A process/workflow change needs recurrence** across two independent sessions, or a single
+   **high-impact contract violation cited at `file:line`**.
+3. **Unsupported dimensions read `not available`** and are mirrored into the telemetry-gaps
+   section. Never a fabricated value, never a raw history-file fallback.
+4. **Focus biases ranking, not collection.** A focus string changes finding ranking and emphasis;
+   it never suppresses material off-topic findings within the window.
+5. **Every inference names its supporting observations.** An inference that does not name its
+   observations fails validation.
+6. **Every finding has an evidence anchor.** No anchor, no finding — no row may be dropped because
+   it "lacks evidence" while still appearing in a summary.
+
+## Comparison semantics
+
+The baseline comparison states an explicit comparability verdict.
+
+- **Daily** compares against the **immediately preceding local calendar day**.
+- **Ad-hoc** compares against the **immediately preceding equal-duration window**.
+- **Insufficient or materially different coverage** renders **`not comparable`**.
+- A `not comparable` baseline states no trend, no delta, and no percentage. An unsupported
+  comparison is never fabricated.
+
+## Recurrence ledger
+
+Every finding is classified against the baseline using the **stable key**:
+
+- `new` — not present in the baseline.
+- `recurring` — present in the baseline with comparable severity.
+- `regressed` — present but worse (severity, count, or impact increased).
+- `improved` — present but better.
+- `resolved` — present in the baseline but absent now.
+- `not-comparable` — the baseline was `not comparable`.
+
+Matching is on the stable key, never the prose title. Rewording a title between two runs must not
+reclassify a recurring finding as new.
+
+## Positive patterns
+
+Positive entries are held to the **same evidence standard as problems**: they carry observation,
+inference, confidence, and at least one evidence anchor. An entry without an anchor is invalid. The
+section renders successful workflows, resolved past issues that stay resolved, and healthy,
+repeating behavior worth keeping.
+
+## Remediation options (proposals only)
+
+Each option is a **proposal** that names:
+
+- **owner surface** — who would apply it.
+- **expected impact** — what it is expected to change.
+- **verification method** — how the change would be confirmed.
+- **reversibility** — whether and how it can be rolled back.
+
+The report must contain **no applied change, no diff, and no command it claims to have run**. The
+skill never applies a fix; it proposes one.
+
+### Remediation handoff route (0680 R4)
+
+For each proposal an operator accepts, the report supplies — printed in the report itself, never
+executed — the `spur task create` invocation that lands it, carrying the proposal's finding
+`key` in the task body so the next report classifies that finding as `resolved`. Auto-writing
+to the task corpus from a model-authored report would bypass the CLI-gated write contract; the
+operator remains the gate.
+
+### Report-only advisories (0680 R5)
+
+Section 10 is the standing home for observations that inform workflow hygiene but must never
+trigger automatic interruption: repeated identical tool-and-argument signatures are surfaced
+here with their repetition counts, proposing at most human-decided process changes. Nothing in
+this section may drive automated behavior.
+
+### Run-cost reporting (0680 R6)
+
+Performance analysis states what the run itself cost: per-pairing `totalCostUsd` /
+`meanDurationMs` figures flow from the pairing analytics fold (0679 repaired the payload
+paths), so chained `agent.run` stages are reportable instead of "~unknown". Where no cost
+signal exists for a pairing it renders `not available`, never zero.
+
+## Projected candidates — section 9 (environment lens, task 0686)
+
+Section 9 (Workflow and process improvements) stays additive report grammar: unprojected numbered
+prose remains valid and gains no required fields. A candidate **projected** through the
+[environment-improvement lens](../../../references/environment-lens.md) is a bullet beginning with
+a backticked stable key (retro name in `<signal>` or owner surface, closed category first — e.g.
+`workflow:agents-md:navigation`) and carries four bold fields, the same names remediation options
+use:
+
+```text
+- `workflow:agents-md:navigation` — **owner surface:** `AGENTS.md` see_also. **expected impact:**
+  shorter file hunt. **verification method:** subsequent daily report key `resolved` or absent.
+  **reversibility:** revert the pointer.
+```
+
+A projected candidate cites its section-4 finding `key` when one exists. Reports remain
+proposal-only: no applied change, no diff, and no command the report claims to have run.
+
+## Evidence ledger
+
+The final section lists, for every finding, the artifact anchor(s) and any cited `file:line`,
+so a reader can verify the report's claims against the evidence plane.
+
+## Truthfulness invariants
+
+- `not available` is the true rendering for an unsupported dimension, never a masked gap.
+- `not comparable` is the true rendering for an unsupported comparison, never a computed delta.
+- No bounded leaderboard length is presented as a population total (see 0657 / ADR-080: the
+  coverage section reads `artifact.population` and renders `top N of M`).

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

@@ -23,9 +23,9 @@ 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` |
 | `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) | `--run <runId>` `--until <state>...` `--timeout <ms>` `--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 team agent specs with `--specs` | `--specs` `--json` |
-| `doctor [agent]` | Check agent readiness | `--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` |
@@ -108,12 +108,18 @@ into `run` with `--drain` -> else sleep for `--poll` ms.
 spur agent wait reviewer                          # default --until idle
 spur agent wait reviewer --run R3 --until invoke-exit
 spur agent wait reviewer --until working --until invoke-exit --timeout 30000 --json
+spur agent wait --role reviewer                   # role-addressed: resolves to exactly one instance
 ```
 
 `wait` pins an occupant's identity (`specId` + `runId` + `generation`) from the snapshot at wait
 start, then polls until the first satisfied `--until` (OR). `--run` pins an explicit run; default
 is the spec's latest run. Replacement, generation bump, or disappearance fails fast; a non-working
 occupant that makes no progress inside the stall budget fails `wait_stalled`.
+Addressing takes `<specId>` **or** `--role` — never both. `--role` resolves against materialized
+instances (vocabulary = `AGENT_ROLE_NAMES` ∪ executor names); zero/multi matches are hard errors
+naming `count=0` + candidates `none` or `count=N` + candidate ids
+(`selector_unmatched` / `selector_ambiguous`, exit 1), an unknown name
+exits 2 naming the accepted vocabulary. Resolution collapses onto the same identity pin.
 
 ### Flags
 
@@ -149,12 +155,15 @@ lists team agent specs (`.spur/agents/*.yaml`).
 
 ```bash
 spur agent doctor            # all detected agents
-spur agent doctor claude     # one agent
-spur agent doctor --json     # machine-readable
+spur agent doctor claude     # one agent (executor/agent name → detail block)
+spur agent doctor coder      # pipeline role id → eligible ladder with ELECTED marker
+spur agent doctor --json     # machine-readable (role selector: elected-first ordering)
 ```
 
-Checks whether each agent is installed and ready to run. Returns exit `1` if any checked agent is
-not ready.
+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.
 
 ## `create` - author a team agent spec
 

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

@@ -19,7 +19,7 @@ use it well*.
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
-| `send <body>` | Enqueue a message for an agent | `--to <id>` `--from <id>` `--wait` `--until <state>` `--timeout <ms>` `--json` |
+| `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` |
 | `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 "Start the pass" --role reviewer          # resolves to exactly one instance
 ```
 
 Enqueues a durable message addressed to `--to <id>`. The recipient drains it on its next `agent run
@@ -47,7 +48,8 @@ wait; enqueue is **not** rolled back if the wait later fails.
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--to <id>` | **Required.** Recipient agent id. |
+| `--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`). |
 | `--wait` | Block until the recipient reaches `--until` (snapshots occupant before send). |
 | `--until <state>` | Wait target: `injected` \| `invoke-exit` (repeatable OR). Default `invoke-exit`. |

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -185,11 +185,13 @@ recovery (0482 R1). To confirm recovery is wired, watch the run log for
 `Escalating: <executor> (tier <t>) failed with resource-exhaustion; retrying on <executor>` — that
 line, not quota state, is the signal that the fallback ladder fired.
 
-Do not read provider quota from `spur agent doctor`. The doctor resolves provider keys from
+Do not read provider auth or quota from `spur agent doctor`. The doctor resolves provider keys from
 `${PROVIDER}_API_KEY` env vars and cannot see an agent-owned credential store (e.g. omp's models
-config), so its row degrades to `status: usable · auth: no · model: unknown` for GLM-style executors
-and is useless as a preflight gate. Exhaustion is detected mid-run by the escalation classifier, not
-by any preflight probe.
+config), so it historically degraded to `status: usable · auth: no · model: unknown` for GLM-style
+executors and was useless as a preflight gate. Feature B4 removed the auth signal from the surface
+entirely (no column, no `authenticated` in `--json`) precisely so nothing can read it by mistake;
+the precheck probe classifies on usability alone. Exhaustion is detected mid-run by the escalation
+classifier, not by any preflight probe.
 
 ### Explicit subprocess surfaces are unchanged
 

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

@@ -68,7 +68,7 @@ each would be scope creep for one-liner procedures.
 | 2   | review     | `dev-review`        | `Skill()`         | `sp:code-verification` (`review`) + `sp:functional-review` + `sp:code-improvement` | `[<wbs\|path>] [--agent <inline\|auto\|name>] [--focus <dims>] [--fix (deprecated)]`                                                                                                                   |
 | 3   | verify     | `dev-verify`        | `Skill()`         | `sp:code-verification` (`verify`)                                                  | `<wbs> [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]`                                                     |
 | 3a  | verifyall  | `dev-verifyall`     | `Skill()` → agent | `sp:spur-dev` (`verifyall`)                                                        | `--tasks <selector> [--feature <id>] [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]` |
-| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue]`                                                                                              |
+| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]`                                                                                              |
 | 5   | refine     | `dev-refine`        | `Skill()`         | `sp:spur-dev` (`refine`)                                                           | `<wbs> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--next]`                                                                           |
 | 5a  | refineall  | `dev-refineall`     | `Skill()`         | `sp:spur-dev` (`refineall`)                                                        | `--feature <id> \| --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]` |
 | 6   | plan       | `dev-plan`          | `Skill()`         | `sp:spur-dev` (`plan`)                                                             | `"<description>" [--feature <id>] [--parent <feature-id>] [--agent <inline\|auto\|name>] [--skip-design] [--auto] [--approve-taste]`                                                                   |
@@ -140,7 +140,7 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` with omitted `--agent` or explicit `--agent inline` reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess; **omitted** `--agent` keeps 0508 eligibility (eligible `agent.run` stages dispatch once to a native subagent, host fallback), while explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
+- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` with omitted `--agent` or explicit `--agent inline` reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess; **omitted** `--agent` keeps 0508 eligibility (eligible `agent.run` stages dispatch once to a native subagent, host fallback), while explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
   - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline uses [inline-pipeline-driver.md](inline-pipeline-driver.md) (host-controlled; eligible stages may use a native subagent); explicit/headless executor selection invokes `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>"}'` (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -421,6 +421,15 @@ isolated git worktree instead of the operator's working directory. This section
 lifecycle for the sequential batch loop. Per-task worktrees and `--mode parallel` isolation stay out
 of scope (task 0142 Slice A); `--worktree --mode parallel` is rejected.
 
+**Single-task `dev-run` (batch of one).** `/sp:dev-run <wbs> --worktree [<name>]` runs this same
+lifecycle with a one-task loop: WT-1…WT-6 apply unchanged, the marker's `command` is `dev-run` and
+its `selector` is the `<wbs>` (so WT-6's command+selector fallback resolves the resume), and the
+derived branch/directory slug is the WBS — `sp/run-<wbs>-<short-id>`. The WT-4 success condition
+"no failed task" reads as "the task reached terminal `done` with no failed stage"; a failing gate, a
+non-PASS verify verdict, or a HITL pause that ends the run take the WT-5 retention path. Only the
+full pipeline is eligible — `--worktree --mode implement` is rejected (WT-7), because that mode is
+the pipeline's implement stage and already runs in the driver's tree.
+
 One flag, two modes (see the glossary entry for the ownership rule). Bare `--worktree` is **create
 mode** (cut a fresh branch + sibling tree). `--worktree <name>` is **reuse mode** (attach to a tree
 that already exists); name resolution (§ WT-2 below) runs before WT-1. The deltas each mode applies
@@ -714,9 +723,13 @@ fallback, because `<name>` was explicit and unambiguous intent.
 ### WT-7 — Exclusions (R8)
 
 - **`dev-next`** does not get `--worktree` — it dispatches a single step; per-step isolation is not
-  worth the worktree cost.
+  worth the worktree cost. `dev-run` is different: it drives a whole task pipeline, so it does get
+  the flag.
 - **`--mode parallel`** is rejected when combined with `--worktree` — per-task worktrees and
   parallel isolation remain task 0142 Slice A.
+- **`--mode implement`** is rejected when combined with `--worktree` on `dev-run` — that mode *is*
+  the pipeline's implement stage (bug-742) and runs in whatever tree the driver set up; a second
+  worktree would split one task's evidence across two trees.
 - **No** create-with-name (`--worktree <name>` never creates; an unresolvable name is an error),
   no `--worktree-keep` variant, no auto-cleanup of stale worktrees or markers from prior runs.
 

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

@@ -100,6 +100,13 @@ cache-conservation discipline (`plugins/sp/skills/dogfood-testing/references/mon
 > - Without `--auto`: warn the operator before calling `spur workflow run` and prompt for confirmation or a plan-item override via `--vars '{"maxImplementPlanItems":"<count>"}'`.
 > - With `--auto`: automatically append `"maxImplementPlanItems": "<count>"` to `--vars` and log a single-line notice (e.g. `Notice: task <wbs> has N plan items (>8 default cap); injecting maxImplementPlanItems override`).
 
+**`--worktree [<name>]` wraps Step 2, on either surface.** When `/sp:dev-run --mode full` carries
+[`--worktree`](flag-glossary.md#flag-worktree), create or adopt the worktree *before* launching the
+pipeline, `cd` into it (`spur workflow run` and the inline driver both resolve cwd from the process),
+and merge-or-retain after the run reports. The lifecycle is
+[execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name)
+applied to a batch of one. Rejected with `--mode implement`.
+
 **Choose the surface before execution.** In an interactive `/sp:dev-run --mode full` invocation,
 omit/`--agent inline` selects the [inline pipeline driver](inline-pipeline-driver.md). Read the YAML
 at invocation time, allocate the inline run id/session provenance, record `task run-link`, and walk