@gobing-ai/spur 0.3.62 → 0.3.63

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

@@ -15,7 +15,7 @@ duplicated into the YAML: the rubric cannot recurse.
 
 | 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, Positive patterns) meeting the report contract |
+| `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.
@@ -31,13 +31,23 @@ Given the current and baseline artifacts, author the model half of the report. A
    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). Categories from the closed
-   vocabulary; stable keys of the form `<category>:<owner-surface>:<signal>`.
+   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). No applied change/diff/command.
-7. **Positive patterns** — same evidence standard as problems.
+   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.
 
@@ -45,11 +55,14 @@ Never fabricate a value, a trend, an anchor, or an applied fix. Never launch a w
 
 Given a candidate report and the artifacts, independently verify:
 
-- **Eleven-section completeness and order** — all eleven section names present in the frozen
+- **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; category in the closed
-  vocabulary; stable-key grammar.
+  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.

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

@@ -1,10 +1,10 @@
 # Report contract — `sp:history-anatomy` (HA-S1, 0658)
 
-The published report is the skill's contract. This reference owns the eleven sections (in order),
+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.
 
-## Eleven required sections (in order, frozen)
+## Twelve required sections (in order, frozen)
 
 1. Scope and provenance
 2. Executive summary
@@ -15,8 +15,9 @@ rules, comparison semantics, recurrence classes, and the positive-pattern / reme
 7. Remediation options
 8. Performance analysis
 9. Workflow and process improvements
-10. Positive patterns
-11. Evidence ledger
+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.
@@ -26,7 +27,13 @@ rename, reorder, omit, or restate them.
 - Categories: `reliability` | `repetition` | `workflow` | `performance` | `coverage` |
   `telemetry` | `positive`.
 
-Every finding's category is drawn from this closed set. No category is invented.
+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)
 
@@ -58,6 +65,9 @@ Every finding — problem and positive alike — carries the full field set:
 | `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
 
@@ -120,6 +130,46 @@ Each option is a **proposal** that names:
 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`,

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