@gobing-ai/spur 0.3.98 → 0.4.0

package/plugins/sp/scripts/task-diffstat.ts

@@ -19,13 +19,17 @@
  * other probe problem writes `sensitive: true` (and exits 0) so the lane degrades to
  * safety, never to fast.
  *
+ * The artifact is written atomically (tmp + rename), so redirecting stdout onto the artifact path
+ * cannot corrupt it — the rename swaps in the real JSON after the shell's redirect truncates the
+ * old inode (1067 R3); that redirect is still refused with a nonzero exit. Normal output is silent.
+ *
  * Node-builtin imports only; the git lookup is a spawnable `GitRunner` so tests can fake
  * it; `main(argv, env, options)` is the same injection point the workflow wrapper and its
  * node twin exercise. Only an empty `wbs` (mis-invocation) exits nonzero.
  */
 
 import { spawnSync } from 'node:child_process';
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { fstatSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
 
@@ -166,10 +170,18 @@ export function runDiffstat(
     const failSafe = (reason: string): DiffstatResult => {
         process.stderr.write(`task-diffstat: ${reason} — failing safe (sensitive)\n`);
         const row: Diffstat = { files: 0, insertions: 0, deletions: 0, paths: [], sensitive: true };
-        writeFileSync(abs(relResult), `${JSON.stringify(row)}\n`);
+        writeArtifact(abs(relResult), row);
         return { ...row, resultFile: relResult, exitCode: 0 };
     };
 
+    let stdoutIsArtifact = false; // 1067 R3: stdout redirected onto the artifact itself clobbered it once
+    try {
+        const [out, art] = [fstatSync(1), statSync(abs(relResult))];
+        stdoutIsArtifact = out.dev === art.dev && out.ino === art.ino;
+    } catch {
+        /* artifact absent or stdout not a regular file — nothing to compare */
+    }
+
     let base = '';
     try {
         base = readFileSync(abs(join(relRun, `${wbs}-base.sha`)), 'utf8').trim();
@@ -203,8 +215,17 @@ export function runDiffstat(
     const all = [...paths].filter((p) => p.length > 0).sort();
     const sensitive = all.some((p) => sensitiveReasonForPath(p) !== null);
     const row: Diffstat = { files: all.length, insertions, deletions, paths: all, sensitive };
-    writeFileSync(abs(relResult), `${JSON.stringify(row)}\n`);
-    return { ...row, resultFile: relResult, exitCode: 0 };
+    writeArtifact(abs(relResult), row);
+    if (stdoutIsArtifact)
+        process.stderr.write('task-diffstat: stdout redirected onto the artifact — kept; redirect stdout elsewhere\n');
+    return { ...row, resultFile: relResult, exitCode: stdoutIsArtifact ? 1 : 0 };
+}
+
+/** Atomic artifact write (tmp + rename): a stdout redirect onto the path cannot interleave (1067 R3). */
+function writeArtifact(absPath: string, row: Diffstat): void {
+    const tmp = `${absPath}.tmp`;
+    writeFileSync(tmp, `${JSON.stringify(row)}\n`);
+    renameSync(tmp, absPath);
 }
 
 export const TASK_DIFFSTAT_USAGE = 'usage: task-diffstat  (env: wbs)';

package/plugins/sp/skills/code-verification/SKILL.md

@@ -315,6 +315,11 @@ node "$RESIDUAL" fold <wbs>
 > for each dropped MET-matched scenario key and when the new rows match no feature scenario —
 > treat those warnings as a re-key instruction, not noise.
 
+> **Keying rule for feature-linked tasks (1086/1089 re-audits).** Key AC rows by the exact feature
+> scenario title (`R1 — …`): feature `Scenario:` titles are declared identities and satisfy L4
+> scenario matching directly. Bare `AC1` fails `ac-identity` on Gherkin AC sections, and checklist
+> labels truncate at the first colon (a `(req: …)` suffix), so the task's own AC title may not resolve.
+
 > **Do not write `## Review` directly, ever.** The `## Review` section is owned by the
 > `review` coordinator (`/sp:dev-review` → `sp:super-reviewer`), which merges
 > `functional-review` + `code-verification` review mode + `code-improvement` fragments. The
@@ -336,6 +341,7 @@ Verdict: PASS    (or PARTIAL / FAIL)
 
 ```markdown
 Verdict: PASS
+Confidence: HIGH
 
 ### Per-Requirement Traceability
 | Req | Status | Evidence |
@@ -354,6 +360,8 @@ Verdict: PASS
 ```
 
 The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant — `Status` in column 2 — and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
+The answer MUST carry exactly one `Confidence: HIGH|MEDIUM|LOW` line (task 1068): the verifier's stated confidence in the verdict — HIGH = fresh executable evidence + re-read anchors this run; MEDIUM = partial reliance on prior evidence, external/delegated outcomes, or an unstable tree; LOW = key evidence not re-executed. A missing or out-of-vocabulary line fails lint (`confidence-missing` / `confidence-value`) and blocks derivation; the value lands in the verdict artifact's `confidence` field and the recorded `## Testing` section.
+The answer MUST cite a source for external API/library claims in Requirement/AC evidence cells: a cell asserting a scoped-package (`@scope/name`), `node_modules/`, semver-version (`x.y.z`), or backticked function-call (`` `name(args)` ``) claim is rejected with `evidence-citation` unless the SAME cell carries a citation — a repo `path:line(-end)` (backticked or bare), the external named-origin form (@origin `path` line N), or a URL. Cross-cell references ("receipt above") do not count; marker-free receipts ("bun test 398 pass / 0 fail") need no citation.
 **MUST NOT:** place a `Severity` column between `Req` and `Status` in the authoring contract.
 The parser is tolerant of these variants (defense-in-depth), but the authoring contract is
 canonical.

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -115,7 +115,9 @@ AC ids that do not resolve to one accepted identity — a task AC checklist labe
 (exact/bare title, `Scenario:` prefix, bracket tags, `AC-N`); paraphrases and ambiguous aliases
 fail — invalid status (`MET | PARTIAL | UNMET` for requirements;
 `N/A` additionally allowed for AC), invalid evidence type (`test | command | static-ref |
-manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Interrupted runs keep the
+manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Evidence cells that assert an
+external API/library claim without a same-cell citation are rejected with `evidence-citation` (see
+"Source citations for external claims" below). Interrupted runs keep the
 rows that pass the lint and complete only the missing IDs on retry.
 
 **Feature-credited AC ids are narrower than the lint's accepted set (task 0966 finding).** A row keyed
@@ -136,6 +138,20 @@ the run actually verified. Since 0804 R9 the checker ignores complete parsed cit
 scanning for subjects, so a citation's filename (including snake_case paths) can never become a
 false subject — a real absent symbol, nonexistent file, or invalid range still reports.
 
+## Source citations for external claims (task 1070)
+
+A Requirement/AC evidence cell that asserts an external API/library claim must carry a verifiable
+citation in the SAME cell, or lint rejects the row with `evidence-citation` (blocking derivation).
+
+- Claim markers (closed set): a scoped-package mention (`@scope/name`), a `node_modules/` reference,
+  a semver version claim (`x.y.z`), or a backticked function-call-shaped token (`` `name(args)` ``).
+- Accepted citation forms (any one clears the cell): a repo `path:line(-end)` (backticked or bare),
+  the external named-origin form (@origin `path` line N — line number outside the backticks), or an
+  http(s) URL.
+- The rule is cell-local: a citation in another row or a "receipt above" cross-reference does not
+  satisfy it. Marker-free receipts (test counts, reviewed-log notes) need no citation. The check is
+  presence-only — which citation proves which claim is not deterministically decidable.
+
 ## Checks evidence
 
 Wave C verification can emit the following additive `checks[]` rows:

package/plugins/sp/skills/fleet-join/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: fleet-join
+description: >-
+  Join a project fleet as a guest occupant and pull its work. Use when the operator asks to
+  "join the fleet", "become a fleet guest", "pull fleet inbox work in this session", or when a
+  session should receive fleet messages without being supervised. Runs `spur agent join`, then
+  loops `spur agent wait --inbox`, and releases the lease with `spur agent leave`.
+---
+# fleet-join — a live session as a fleet guest (G73, task 1081)
+
+A guest is a session that **pulls** work: it is neither supervised nor restarted, it is addressed
+by concrete id only, and it never receives a stage (`requiresCapabilities` stages can never route
+to it — a guest carries no attestation). Joining registers an occupant row plus a heartbeat lease;
+leaving (or an expired lease) releases it and returns any claimed messages to `pending`.
+
+## Join
+
+```bash
+spur agent join --role reviewer --json      # id defaults to <role>-g<n>
+spur agent join --role coder --id my-session --json
+```
+
+Pick the role whose work this session can actually do. `--session-id` defaults to
+`CLAUDE_CODE_SESSION_ID`, which is what the Stop hook matches against — without it the hook cannot
+find this session, though the `wait --inbox` loop still works.
+
+## Pull loop
+
+`spur agent wait --inbox <id> --timeout 540000` returns **0** the moment queued work exists and
+**1** on timeout. Each call heartbeats the lease, so a looping session stays joined. The Bash tool's
+own ~10-minute limit is why the timeout stays under it: one bounded call per turn, re-armed after
+the work is done.
+
+1. `spur agent wait --inbox <id> --timeout 540000 --json` → exit 0 means work is waiting.
+2. `spur message inbox --agent <id> --json` → read the messages.
+3. Do the work the message asks for.
+4. `spur message reply <msgId> "<result>"` → reply to each one.
+5. Re-arm: go back to step 1 while the operator wants this session in the fleet.
+
+## Leave
+
+```bash
+spur agent leave --json                     # the guest joined by this session
+spur agent leave my-session --json           # an explicit id
+```
+
+Leaving releases the lease immediately. If the session dies without leaving, the lease expires and
+the reconciler pass retires the guest — pending work is never lost, it returns to `queued`.
+
+## Stop-hook delivery (opportunistic)
+
+When the host fires a `Stop` hook and the host supports the block contract, the
+`fleet-guest-stop` plugin hook delivers pending messages at turn end by replying
+`{"decision":"block","reason":"Pending fleet messages: …"}` — only for a session whose id matches a
+joined guest, never twice in one continued turn, and always fail-open. Claude Code supports this;
+Codex `exec` on 0.160.0 does not deliver `Stop` at all (`docs/plans/2026-10-05-codex-guest-spike.md`),
+so the pull loop above — not the hook — is what makes a guest work anywhere.
+
+## Boundaries
+
+- Guests are **not** supervised: do not expect restart, pid ownership, or `--drain` injection.
+- Never dispatch a stage to a guest id: `spur agent run --spec <guest-id>` is refused on purpose.
+- Never hold the write slot through a guest: the guest lease is the only heartbeat (R5).

package/plugins/sp/skills/session-review/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: session-review
-description: "Review the active coding-agent session: separate resolved from open issues with evidence, propose bounded improvements. With --triage, apply pure-doc / 1–2-line fixes inline and file the rest as one or more tasks. Triggers: review this session, wrap-up, triage findings."
+description: "Review the active coding-agent session: separate resolved from open issues with evidence, propose bounded improvements. With --fix auto (alias --triage), apply pure-doc / 1–2-line fixes inline and file the rest as tasks; with --fix all, fix every actionable finding inline and file none. Triggers: review this session, wrap-up, triage findings."
 license: Apache-2.0
-version: 1.1.0
+version: 1.2.0
 metadata:
   author: spur
   platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
@@ -31,7 +31,8 @@ cross-agent windows, recurrence, trends, or quantitative performance forensics.
 | Argument | Description | Default |
 | --- | --- | --- |
 | `[focus]` | Question or operation to emphasize. It changes ordering, not evidence collection. | full active session |
-| `--triage` | Opt into bounded remediation after the report: apply direct fixes (pure docs / one-to-two-line fixes) inline, then file all remaining actionable findings as one or more implement-ready tasks via the CLI-gated corpus surface. | off (report-only) |
+| `--fix <none\|auto\|all>` | Remediation after the report. `none`: report-only. `auto`: apply direct fixes (pure docs / one-to-two-line fixes) inline, then file all remaining actionable findings as one or more implement-ready tasks via the CLI-gated corpus surface. `all`: fix every actionable finding inline and file no task. | `none` |
+| `--triage` | `--triage` is an alias of `--fix auto`; an explicit `--fix` wins when both are passed. | off |
 
 ## Evidence boundary
 
@@ -46,14 +47,16 @@ cross-agent windows, recurrence, trends, or quantitative performance forensics.
   name the confirmation needed.
 - State `not available` when compaction or missing output removed evidence. Never reconstruct it from
   memory or claim a verification that did not run.
-- Derive timing only from timestamps and tool-call records visible in the active session. Use
-  non-overlapping stages whose durations sum to elapsed time; render unavailable duration or call
-  counts as `n/a` instead of estimating them.
+- Derive timing and tokens only from the host transcript measurement (Protocol step 1): the visible
+  conversation carries no timestamps or usage, so never estimate them from it. Use non-overlapping
+  stages whose durations sum to elapsed time; render a value as `n/a` only when the measurement
+  reports `available: false` or omits it.
 
-## Triage mode (`--triage`)
+## Fix modes (`--fix auto|all`)
 
-Report-only stays the default. With `--triage`, run the same evidence pass, then remediate in
-three buckets — never skip triage and start fixing from the raw findings list.
+Report-only stays the default. With `--fix auto` or `--fix all`, run the same
+evidence pass, then remediate in three buckets — never skip triage and start fixing from the raw
+findings list. Steps 1–4 below are `--fix auto`; `--fix all` differs only as stated after them.
 
 1. **Triage every finding into exactly one bucket:**
    - **Direct fix** — pure documentation work, or a one-to-two-line fix with obvious, local,
@@ -74,10 +77,22 @@ three buckets — never skip triage and start fixing from the raw findings list.
 4. **Report** — add a Triage section: applied fixes (path + one-line what + verification) and
    each created task WBS. The Resolved/Open tables keep their evidence rules unchanged.
 
+**`--fix all` (defer nothing).** Triage still runs, but the Task bucket is fixed inline instead of
+filed, so the mode creates no task. Fix in dependency order with the same surgical-diff and
+per-fix re-verification rule as direct fixes, then run the project gate once at the end. A finding
+that needs a design or operator decision is asked through the host question tool, never deferred;
+one that still cannot be fixed (failed re-verification, blocked by the environment) stays in Open
+issues with its evidence. Notes stay report-only.
+
 ## Protocol
 
 1. **Resolve scope.** Review the active session from the operator's initiating request through the
-   latest result. Use `[focus]` only to rank relevant material.
+   latest result. Use `[focus]` only to rank relevant material. Measure it with
+   `node "$(superskill script path sp session-timeline.mjs)" --group "<ranges>"`: one segment per
+   operator prompt, read-only from the host transcript. Run it once without `--group` to list the
+   segments, then map them to stages (`"1-3,4,5-6"`). It splits each segment into `work` and
+   operator `wait` (idle before the next prompt plus AskUserQuestion answer time) and counts tokens
+   once per message id.
 2. **Inventory outcomes.** List requested outcomes and classify each as completed, partial, blocked,
    or not attempted. Collapse repeated attempts into one outcome.
 3. **Classify issues.** For every material issue, distinguish resolved, open, or attempted. Record
@@ -108,26 +123,32 @@ State the overall result in one to three sentences, including partial or blocked
 Summarize elapsed time and, when supported by evidence, productive work, avoidable setup/recovery,
 and operator wait time. Then render non-overlapping stages:
 
-| Stage | Time | Tool calls | Assessment |
-| --- | ---: | ---: | --- |
+| Stage | Time | Wait | Tool calls | Token | Assessment |
+| --- | ---: | ---: | ---: | ---: | --- |
 
 Format durations as `M:SS` below one hour and `H:MM:SS` at one hour or above (`1:44`, not `1m44s`;
 `0:33`, not `33s`). Include a `Total` row when elapsed time is available. Keep operator approval
-waits separate from execution bottlenecks. Use `n/a` for any value not supported by the active
-session evidence.
+waits separate from execution bottlenecks. Time is the stage `work` and Wait its operator `wait`.
+Token renders `<total> / <non-cached>` in compact units (`28.7M / 717k`) — the measurement's
+`token` field: total = input + cache creation + cache read + output; non-cached = total minus cache
+read (fresh input, cache writes and output). These are measured session counts, not the 0912 baseline token/USD claims that
+step 4 excludes. Use `n/a` for any value not supported by the measurement.
 
 ### Resolved issues
 
-| Issue | Root cause | Resolution | Evidence |
-| --- | --- | --- | --- |
+| Issue | Root cause | Resolution | Evidence | Confidence |
+| --- | --- | --- | --- | --- |
 
 Evidence names the tool result, verification command, or concrete repository state visible in the
-session. Do not list ordinary implementation steps as issues.
+session. Do not list ordinary implementation steps as issues. **Confidence** is `HIGH`, `MEDIUM`, or
+`LOW` for that row's claim, with its grounds in the cell (a level without grounds is not
+verification); any API/library statement in a row cites the installed source as `path:line` or a URL,
+and a claim the session could not ground is written `LOW` with the missing evidence named.
 
 ### Open issues and risks
 
-| Issue or risk | State | Evidence or confirmation needed |
-| --- | --- | --- |
+| Issue or risk | State | Evidence or confirmation needed | Confidence |
+| --- | --- | --- | --- |
 
 ### Process and environment improvements
 
@@ -137,13 +158,13 @@ observation adopted from the 0912 workflow baseline cites its anchor
 (`docs/reports/i31/0912-workflow-baseline.md`) and owner handoff, and carries no unsupported
 performance claim.
 
-### Triage (only when `--triage` was passed)
+### Triage (only with `--fix auto|all`)
 
 | Applied fix / created task | Bucket | What + verification |
 | --- | --- | --- |
 
-One row per applied fix and one per created task (with its WBS). Omit the section entirely when
-`--triage` was not passed.
+One row per applied fix and one per created task (with its WBS; `--fix all` has none). Omit the
+section entirely under `--fix none`.
 
 ### Next actions
 
@@ -157,8 +178,9 @@ improvement. Use `None` when the session is complete and no follow-up is justifi
   comparison or recurrence classification, or emit a twelve-section forensic report; those belong
   to imported-history analysis.
 - Report-only by default: do not create or update corpus items or edit files. The single exception
-  is `--triage` mode, which permits exactly two mutation classes — direct fixes from the triage
-  bucket, and the triage tasks. Anything beyond that stays a proposal.
+  is `--fix auto|all`: `auto` permits exactly two mutation classes — direct fixes from the triage
+  bucket, and the triage tasks; `all` permits one — inline fixes of actionable findings. Anything
+  beyond that stays a proposal.
 - Do not turn a single low-impact observation into a new policy. Report it as a candidate until it
   recurs or demonstrates a high-impact contract violation.
 

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

@@ -49,6 +49,7 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 | **Tier B** | **self** | Self-management verbs: scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
 | **Tier B** | **history** | Import agent histories, aggregate forensic artifacts, render reports, and run the checkpoint-resumed daily pipeline | [references/history.md](references/history.md) |
 | **Tier B** | **projects** | Manage the local multi-project registry and start/stop project servers | [references/projects.md](references/projects.md) |
+| **Tier B** | **decision** | Decision-catalog transport: list visible decisions, show a served contract, run a decision to a served outcome, audit catalog health | [references/decision.md](references/decision.md) |
 | **Tier C** | **help** | Commander-generated help command; not a Spur noun | Generated `--help` |
 
 **Execute-First Contract:** Load the noun reference first and execute Tier A or Tier B commands

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

@@ -23,14 +23,18 @@ 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` |
+| `trace <runId>` | Print one execution record's lineage — the run, its dispatch parents, agent session ids and streams (1076 R4, ADR-132) | `--follow` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur self serve`) | `--specs` `--server <url>` `--json` |
+| `report` | Report a fleet member lifecycle state (`working`/`idle`/`blocked`) from a host hook (G73 R1/R2, task 1080) | `--state <state>` `--seq <ns>` `--spec <id>` `--json` |
+| `join` | Join the fleet as a guest occupant — a live session that pulls its own work (G73 R2, task 1081) | `--role <name>` `--id <id>` `--session-id <sid>` `--pid <n>` `--executor <name>` `--json` |
+| `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to pending | `[id]` `--session-id <sid>` `--json` |
 | `status` | Agent specs with live process status and member session (requires `spur self 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 self serve`) | `--server <url>` `--json` |
 | `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 
-`list`, `status`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+`list`, `status`, `doctor`, `run`, `wait`, `trace`, `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.
 
@@ -91,7 +95,9 @@ It waits for a wake on the `system_events` ledger — a human request (`message.
 change (`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
 (`agent.invoke.exit`) — then drains the inbox into an `agent run` invocation. An idle wake records
 the hold reason instead of dispatching; with no wake event it still drains every `--poll` ms
-(default `2000`). It runs until `SIGINT` / `SIGTERM`.
+(default `2000`). It runs until `SIGINT` / `SIGTERM`, or until its parent `spur serve` disappears —
+the parent is re-read each poll and a change aborts the loop, so a `SIGKILL`ed serve leaves no
+orphan loop (1088 R2).
 
 ## `wait` - identity-pinned occupant wait (G4 wave 2)
 
@@ -146,8 +152,9 @@ supervisor**: each row carries a trailing status column
 (`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 self 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.
+`stopped` with a stderr warning. `--server <url>` targets the supervisor API; without it the URL is
+this project's serve — the port in the cwd's project-registry entry (`http://localhost:<port>/api`),
+falling back to `http://localhost:3000/api` only when the project has no live entry (1088 R1).
 
 ```bash
 spur agent list --specs
@@ -164,9 +171,77 @@ 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
+unreachable server reports every spec `stopped` with no session. `--server <url>`
+(default: this project's registry serve port, `http://localhost:<port>/api`; else
+`http://localhost:3000/api` — 1088 R1) targets it. See
 [Member sessions](#member-sessions-g66) for what the modes mean.
 
+## `report` - fleet lifecycle state from a host hook (G73, task 1080)
+
+```bash
+spur agent report --state working --seq 1759665600000000000
+spur agent report --state blocked --seq 1759665600000000000 --spec proj-worker-1 --json
+```
+
+| Flag | Description |
+| --- | --- |
+| `--state <state>` | Lifecycle state: `working` \| `idle` \| `blocked` (required) |
+| `--seq <ns>` | Monotonic report sequence in nanoseconds (required); not greater than the last accepted one → ignored |
+| `--spec <id>` | Member spec id; defaults to `SPUR_SPEC_ID` |
+| `--json` | Machine-readable result (`accepted`, `observation`) |
+| `--json-envelope` | Wrap the JSON in the standard output envelope |
+
+An accepted report writes the cataloged `agent.lifecycle.changed` ledger row — the newest
+accepted row for the member is its current state, so there is no separate state store. The
+dispatch strategy treats `blocked` as unavailable (hold reason `member-blocked`), and the Board
+shows `needs human` on that member.
+
+Exit `2` when `--state`/`--seq` is missing or malformed, or when no member id resolves
+(`SPUR_SPEC_ID` unset and no `--spec`). The `sp` plugin's `agent-lifecycle` host hook calls this
+in the background on `SessionStart` (idle), `UserPromptSubmit` (working), `Notification`
+(`permission_prompt` → blocked) and `Stop` (idle); outside a fleet it makes no call at all.
+
+## `join` / `leave` - guest occupancy (G73 R2/R5, task 1081)
+
+```bash
+spur agent join --role reviewer --json          # id defaults to <role>-g<n>
+spur agent join --role coder --id my-session --json
+spur agent leave --json                          # the guest joined by this session
+```
+
+A guest is a live session that **pulls** work: never supervised, never restarted, addressable by
+concrete id only (role/executor selectors count declared members, so a guest is invisible to them).
+`join` writes an occupant row in `coordination_runs`, claims a `guest:<id>` lease on the shared
+claim table (same TTL/heartbeat semantics as the write slot — R5) and writes
+`.spur/run/guests/<id>.json` so a host Stop hook can recognize its own session without a CLI call.
+`leave`, or lease expiry in the reconciler pass, releases the lease, marks the occupant exited,
+returns its claimed messages to `pending` and removes the record.
+
+| Flag | Description |
+| --- | --- |
+| `--role <name>` | Layer-1 role (`scribe` \| `coder` \| `reviewer` \| `planner`); required for `join` |
+| `--id <id>` | Guest id (defaults to `<role>-g<n>`); colliding with a declared member or a joined guest exits 2 |
+| `--session-id <sid>` | Host session id (defaults to `CLAUDE_CODE_SESSION_ID`) |
+| `--pid <n>` | Process id to record |
+| `--executor <name>` | Executor name to record (informational — a guest is never dispatched to) |
+| `--json` | Machine-readable result |
+
+A guest carrying no executor attestation is never a stage target: `spur agent run --spec <guest-id>`
+is refused (R3), and `requiresCapabilities` stages therefore can never reach one.
+
+## `wait --inbox <id>` - the guest pull primitive (G73 R4)
+
+```bash
+spur agent wait --inbox reviewer-g1 --timeout 540000 --json
+```
+
+Returns `0` as soon as queued inbox work exists for the guest and `1` on timeout or when the id is
+not a joined guest — never a silent hang. Every call heartbeats the guest's lease, so a session that
+keeps looping stays joined; the timeout stays under the Bash tool's ~10-minute limit. The
+`fleet-join` skill loops it (wait → `spur message inbox --agent <id>` → work → `spur message reply`),
+and the `fleet-guest-stop` plugin hook delivers the same messages at a turn boundary on hosts that
+support a blocking Stop hook.
+
 ## `doctor` - readiness check
 
 ```bash
@@ -193,6 +268,31 @@ stderr-clean and carries `capabilities`, `capabilityStale: {verifiedAgainst, det
 normalized `availability` object, and a top-level `usage` per agent row instead. Exit `1` if any
 checked agent is not ready.
 
+## `trace` - one execution record's lineage (1076 R4, ADR-132)
+
+```bash
+spur agent trace <runId>              # the run, its parents, its children
+spur agent trace <rootId> --follow    # poll until every run in the lineage is terminal
+spur agent trace <runId> --json
+```
+
+`trace` reports ADR-132's execution record as one lineage. A node is a run: a workflow run comes from
+the `runs` table, an agent run from `coordination_runs`, and the dispatch edge is
+`coordination_runs.parent_run_id` — set from a workflow dispatch key (`<runId>/<state>`) or the
+inherited `SPUR_RUN_ID`. `trace <runId>` first walks that edge UP to the root and then DOWN to the
+leaves, so any id in the chain yields the whole picture. Each node carries its status, the agent
+session ids recorded for it (`history_run_session`, exact rows only) and its durable stream under
+`.spur/memory/runs/<runId>.md` when one was written. The stream is the record; the supervisor's ring
+buffer is only a live view.
+
+### Flags
+
+| Flag | Purpose |
+| ------ | --------- |
+| `--follow` | Poll until every run in the lineage reaches a terminal status. |
+| `--timeout <ms>` | `--follow` budget (default 600000). On expiry one checkpoint line is printed and the command exits 1; the runs continue. |
+| `--json` | `{ rootRunId, nodes: [{ runId, kind, status, parentRunId, sessionIds, logPath }] }` — root first, depth-first. |
+
 ## `start` - start a supervised process
 
 ```bash
@@ -202,7 +302,9 @@ spur agent start worker-1 --json
 
 Posts to the `spur self serve` supervisor API
 (`POST /api/agents/:id/start`) and prints `started <id> (pid=<n>, status=<s>)`. Requires a
-reachable `spur self serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
+reachable `spur self serve`; `--server <url>` targets it, defaulting to this project's registry
+serve port (`http://localhost:<port>/api`, else `http://localhost:3000/api` when the project has no
+live entry — 1088 R1). Exit `1`
 when the server is unreachable or the start fails.
 
 ## `stop` - stop a supervised process

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

@@ -0,0 +1,97 @@
+---
+name: spur-cli-decision
+description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers. Backed by @gobing-ai/ts-ai-decision 0.5.16 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093."
+see_also:
+  - spur-cli
+---
+
+# spur decision - decision catalog surface
+
+`spur decision` exposes the **decision catalog** (ADR-117 trace discipline, task 1092) to agents
+and scripts: discover which decisions exist, inspect one's contract, serve one outcome, and audit
+catalog health. It is a thin transport over `DecisionService` (`packages/app`); the decision hub
+lives in `@gobing-ai/ts-ai-decision`.
+
+**Frozen at exactly four verbs** (`list`, `show`, `run`, `status`) by task 1093's design
+(`docs/design/decision-catalog.md` §3.4) — do not invent additional subcommands.
+
+## Catalog layers
+
+Decisions resolve first-wins across three layers:
+
+| Layer | Root | Notes |
+| ----- | ---- | ----- |
+| `project` | `<cwd>/.spur/decisions/*.yaml` | Highest precedence |
+| `registered` | programmatic catalog registrations | Agents register in-process |
+| `shared` | `decisions/` under the bundled config root | Shipped catalogs (`config/decisions/` in-repo) |
+
+The bundled shared catalog ships `task-triage`, `failure-class`, and `review-failure-class` (all
+`choice` type, param `wbs`). Duplicate ids across layers keep the higher layer; duplicates inside
+one file are a load error.
+
+**Config keys** (under `decisions:` in `config.global.yaml` or project config):
+`paths` (extra catalog folders joined to the registered layer), `maker` (default DecisionMaker
+for every decision point), `makers` (per-decision-id overrides). An unregistered maker name is a
+config error, never a silent fallback (design §3.6).
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `list` | Every visible decision: id, type, layer, catalog file, description | `--layer <layer>`, `--json` |
+| `show <id>` | One served contract: type, parameters, criteria, fallback, minConfidence, effective maker + source | `--json` |
+| `run <id>` | Serve one outcome (closed vocabulary; **never writes a resultFile**) | `--param <pairs...>`, `--evidence <files...>`, `--maker <name>`, `--json` |
+| `status` | Layer counts, registered makers, per-decision maker resolution, load errors | `--json` |
+
+All verbs support `--json` (bare payload) and `--json-envelope` (`{ok, data|error}` envelope,
+ADR-091). Failure output for `--json` commands uses the canonical error envelope only under
+`--json-envelope`; plain `--json` keeps the human message on stderr.
+
+**Exit codes:** `status` exits 1 on catalog load errors; `show` exits 1 on unknown id; `list` always
+exits 0 (design §3.4 — load errors surface via `status`).
+
+**Exit contract for `run` (design §3.4):** any backend-observed outcome — low confidence, model
+error surfaced as fallback, declined — is still a **successful serve** (exit 0, envelope carries
+`source`/`confidence` so callers can see why). Exit 1 is reserved for caller mistakes caught
+**before** the backend: unknown id, unknown parameter, missing required parameter, type-invalid
+parameter, unregistered `--maker`, unreadable evidence file.
+
+## Parameters and evidence
+
+`--param k=v` is repeatable and validated against the decision's declared parameters: values for
+`number`/`boolean`/`json` params are parsed accordingly (`json` accepts inline JSON objects);
+string/enum params pass through verbatim. A parameter with no `default` is **required** (hub
+loader derives `required: !hasDefault`). Undeclared keys exit 1.
+
+`--evidence <file>` is repeatable; each file is read, **redacted and bounded to
+`DECIDE_EVIDENCE_MAX_CHARS` (2000 chars)** via the same `redactAndBound` used by workflow
+agent execution. Evidence rides the hub's implicit `instructions` input parameter — it reaches the
+maker through the rendered question, never as a raw input key (the hub rejects undeclared input
+keys). An unreadable evidence file exits 1 before any backend call.
+
+## Effective maker resolution
+
+Makers resolve `flag → config-decision → config-default → catalog-decision → catalog-default`;
+`decision show` reports the effective maker as `{name, source}` with that source precedence
+(operator config outranks the shipped catalog because only the machine owner knows which backends
+exist there). The final `catalog-default` maker is the hub built-in `typesafe` — decisions served
+without a configured backend still produce deterministic closed-vocabulary outcomes, which is why
+`run` is usable in tests and scripts with no model access.
+
+## Examples
+
+```bash
+spur decision list --json | jq -r '.[].id'
+spur decision show task-triage                      # inspect contract before serving
+spur decision run task-triage --param wbs=1093 --json
+spur decision run failure-class --param wbs=1093 \
+    --evidence .spur/run/<runId>-test-output.txt    # redacted evidence -> instructions
+spur decision status --json | jq '.data.errors'     # audit catalog health
+```
+
+## References
+
+- Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface)
+- Hub: `@gobing-ai/ts-ai-decision` 0.5.16 (`DecisionService`, catalog schema, maker registry)
+- App service: `packages/app/src/decision/decision-service.ts`
+- Shipped catalogs: `config/decisions/*.yaml`

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

@@ -448,3 +448,25 @@ spur task path     <wbs> [--folder] [--json]
 spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
 spur task scaffold-tests <wbs> [--file <path>] [--folder] [--json]
 ```
+
+**No `delete` verb — and that is the surface's shape, not an oversight.** The corpus is
+append-only history: a task that is no longer wanted is a *decision*, and the lifecycle already owns
+it. Use
+
+```
+spur task update <wbs> cancelled [--json]      # the in-band terminal; the file stays as the record
+```
+
+Removing the file entirely is reserved for a task that should never have existed (a duplicate WBS, a
+mis-scaffolded capture) — a **corpus repair**, not a lifecycle move. Do it as a tracked deletion so
+the removal itself is auditable:
+
+```
+git rm docs/tasks<N>/<wbs>_<slug>.md
+git commit -m "chore(corpus): drop <wbs> — <why it never existed>"
+```
+
+Check for inbound references before deleting (`grep -rn "<wbs>" docs/ config/ plugins/`, plus any
+`dependencies[]` edge via `spur task list --json`). The `deps remove` verb clears an edge. A deleted
+WBS must not stay referenced: a dangling `dependencies[]` entry is a broken traceability edge, not a
+harmless leftover.