@gobing-ai/spur 0.3.99 → 0.4.1

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

@@ -35,9 +35,43 @@ interface VerifyVerdict {
     status: 'pass' | 'fail' | 'warn';
     evidence: string;
   }>;
+  /** Verifier confidence (task 1068 R3). REQUIRED for PASS — the done gate denies
+   *  a confidence-less PASS. Accepted case-insensitively, normalized to uppercase. */
+  confidence?: 'HIGH' | 'MEDIUM' | 'LOW';
 }
 ```
 
+## Confidence level (task 1068 R3)
+
+A PASS verdict must state the verifier's confidence: `"confidence": "HIGH" | "MEDIUM" | "LOW"`.
+The value is case-insensitive on read (normalized to uppercase), but a present value outside the
+enum invalidates the artifact, and a PASS with the field absent is denied at the `* → done`
+transition with a remediation naming the field (`--force-done` remains the documented escape).
+The verify answer's `Confidence:` lint rule (producer side) already guarantees the field for
+pipeline-produced artifacts; this closes the hand-authored / pre-1068 artifact hole.
+
+### Coherence: the level must be earned (task 1133)
+
+Presence and vocabulary are not enough — the level has to match the rows in the same answer, so the
+lint rejects a level that contradicts its own evidence. Two rejection classes, both addressed to the
+`Confidence:` line and both capped by the shared `ANSWER_LINT_MAX_FINDINGS` budget:
+
+- `confidence-unwarranted` — `HIGH` while any requirement row normalizes to `PARTIAL`/`UNMET`, any
+  acceptance-criteria row does not normalize to `MET`, or any `MET` row's evidence is hedged.
+  A `HIGH` claim says the evidence needs no re-check; a non-MET or hedged row says the opposite.
+- `confidence-understated` — `LOW` while at least one requirement row exists and every requirement
+  and acceptance-criteria row normalizes to `MET`. The evidence already did the work, so `LOW`
+  misreports the state as unproven.
+
+`MEDIUM` carries no coherence rule in either direction: it is the level a verifier uses for a caveat
+with no row to point at, and closing it would force either an overclaimed `HIGH` or an unusable
+`LOW`. The level is normalized to uppercase before the decision, so `high` is judged as `HIGH`.
+
+Set the level from the rows, not the mood: all rows `MET` with fresh evidence is `HIGH`; a
+`PARTIAL`/`UNMET` row or a hedge means `MEDIUM`, not `HIGH`. An unwarranted level does not merely
+warn — the lint rejects the answer and no verdict artifact is written, so the level is worth
+choosing deliberately before the verdict line is finalized.
+
 ## Compatibility alias: `scenario` row key
 
 Task 0410 hardened the verdict reader. Producers SHOULD use the canonical `id` field for every
@@ -138,6 +172,23 @@ 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.
 
+## Basename-only anchors are unresolved anchors (task 1110 R1)
+
+`spur task verdict --from-answer` accepts the citation *shape*, but the `--as done` gate resolves
+every Testing/Solution anchor against the repo root. A basename citation — `decision-events.ts:83`,
+`task.test.ts:42` — reports `L4.anchor-unresolved` at **error** and blocks
+`spur task update <wbs> done`, because the gate cannot tell which file the row meant. Write the
+repo-root-relative form from the first pass:
+
+- Right: `packages/app/src/decision/decision-events.ts:83`, `apps/cli/tests/commands/task.test.ts:42`
+- Wrong: `decision-events.ts:83`, `../services/foo.ts:12`, `@gobing-ai/ts-x/src/persistence.ts:108`
+  (a scoped package is never repo-relative — use the external named-origin form below)
+
+The pipeline's implement stage also runs a scoped `spur task migrate-anchors --wbs <wbs>` pass
+before the proof capture (task 1109), but it qualifies **unique** basenames only: an ambiguous
+basename (two tracked files share it) is reported and left untouched, and line drift and
+`L4.anchor-subject-mismatch` are never repaired by that pass — those remain the author's rows.
+
 ## Source citations for external claims (task 1070)
 
 A Requirement/AC evidence cell that asserts an external API/library claim must carry a verifiable
@@ -152,6 +203,23 @@ citation in the SAME cell, or lint rejects the row with `evidence-citation` (blo
   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.
 
+## Hedged evidence is rejected on MET rows
+
+A MET row asserts the requirement is satisfied; evidence that hedges ("the guard likely prevents
+the leak") contradicts the assertion the row is making. The lint rejects such rows with
+`evidence-hedged`, naming the detected phrase, with two remedies: state the deterministic fact
+with a concrete anchor, or downgrade the row to PARTIAL (which is what suspected-but-unproven
+behavior actually is).
+
+- Detected phrases (closed set, word-anchored, case-insensitive): `likely`, `unlikely`,
+  `probably`, `presumably`, `apparently`, `seems/seeming/seemingly to`, `appears to`. Modal verbs
+  (`might`/`may`/`could`/`should`) are deliberately out of set — they are constant in remediation
+  prose and would drown the signal.
+- Only MET rows are scanned. Hedging a gap in an UNMET row ("the stale path likely still loads
+  the old bundle") is honest reporting and stays clean.
+- Citation spans are stripped before scanning, so a filename or test name containing a hedge
+  word (`likely-match.test.ts`) cannot fire.
+
 ## 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 `queued`.
+
+## 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.3.0
 metadata:
   author: spur
   platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
@@ -24,14 +24,17 @@ compact, evidence-backed report of outcomes, resolved issues, remaining risks, a
 
 Use this skill immediately after focused operations when the operator asks what happened, what was
 resolved, or how the session could improve. Use imported-history analysis for ended sessions,
-cross-agent windows, recurrence, trends, or quantitative performance forensics.
+cross-agent windows, recurrence, trends, or quantitative performance forensics: on pi, run
+`spur history analyze --source pi --session <file-stem>` where `<file-stem>` is the transcript
+basename without `.jsonl` (e.g. `2026-10-07T22-44-33-625Z_01a1188a-…`), not the bare uuid.
 
 ## Arguments
 
 | 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 +49,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 +79,31 @@ 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. On pi the transcript is `$PI_SESSION_FILE` (pass it as `--transcript` when
+   the run reports no host session id). **A measurement that returns `segments: []` with zero totals
+   while the session had operator prompts is an unreadable or stale adapter, not an empty session:**
+   compare the installed copy against this tree's `plugins/sp/scripts/session-timeline.mjs` and
+   refresh it with `superskill install sp` before reporting numbers; report `n/a` until then.
+   The transcript resolves from `--transcript`, else `CLAUDE_CODE_SESSION_ID`, else `PI_SESSION_FILE`
+   (the pi host sets it and no Claude session id); with none of them the measurement reports
+   `available:false` with a reason and the table renders `n/a` instead of guessing. A
+   skill-injected body (`<skill name="…">`) is counted as activity in `injectedPrompts`, never as a
+   segment — only the operator's own prompts segment the session.
 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 +134,52 @@ 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.
 
-### Open issues and risks
+**Confidence** is `HIGH`, `MEDIUM`, or `LOW` for that row's claim. The level is **derived from the
+check that produced the claim, never assessed from how the row reads**, and the cell carries that
+verifier (e.g. `HIGH — gate exit 0, /tmp/g0.log re-run this session`). Add the row's **falsifier**
+when the level is not `HIGH`: what would have made it fail, or what moves it up. The same ladder
+grades this report's Open-issues table.
 
-| Issue or risk | State | Evidence or confirmation needed |
+| Level | Verifies when | Not this |
 | --- | --- | --- |
+| `HIGH` | An executed check in this session produced the result and its raw output is reachable (command + exit code, test counts, query row, gate log). Re-runnable now. | The code or change "looks correct"; a claim asserted only in prose. |
+| `MEDIUM` | The claim is inferred from observed facts, rests on prior-session or delegated evidence, or names state that moved after the check (stale by construction). Name which of the three. | Presenting an inference as an observation. |
+| `LOW` | No executable check was run. Name the missing evidence **and** the command that would ground it. | Dropping the row instead of marking it. |
+
+Two guards against level inflation:
+
+- Evidence that cannot be re-run, or that is only the agent's own summary, **caps the row at
+  `MEDIUM`** — a re-run is what promotes it.
+- An all-`HIGH` multi-finding review is a signal the ladder was not applied, not a clean session.
+  Where every row genuinely is `HIGH`, the cells show distinct check results rather than repeated
+  phrasing.
+
+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 | Confidence |
+| --- | --- | --- | --- |
 
 ### Process and environment improvements
 
@@ -137,13 +189,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 +209,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/source-driven-development/SKILL.md

@@ -101,6 +101,11 @@ line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or
 - **Honest confidence** — the stated HIGH/MEDIUM/LOW matches the evidence: HIGH requires a check against the pinned source this session; MEDIUM/LOW items are labeled, and LOW is never presented as fact.
 - **HIGH** — all three checks pass. **MEDIUM** — coverage intact but some citations are off-version (latest docs for a pinned dependency) or secondary-source only. **LOW** — an API/library claim lacks any citation, or a LOW-confidence claim was asserted as fact.
 
+Deterministic backstop: the `cited-version-strings` / `cited-api-claims` rules
+(`.spur/rules/docs/sourced-api-claims.yaml`, run in `recommended-pre-check`) flag markdown lines that
+assert version strings or time-anchored API claims with no citation anchor on the same line. They
+are an info-severity advisory backstop for this contract (they do not gate; the checks above and the SECUA checklist are the enforcement points).
+
 ## Common Rationalizations
 
 | Rationalization | Reality |

package/plugins/sp/skills/spec-decomposition/references/decomposition.md

@@ -562,9 +562,11 @@ schema before emitting.
 
 **Pass the deterministic task check.** Each `acceptance_criteria` bullet must be an exact feature
 scenario title (L4.uncovered-task-scenario); add task-local checks as prose after the bullets, not
-as extra bullets. No section body may use `HITL`, `approval`/`approved`, `merged`/`merge event`,
-`content-gate`, `GATED`, or `capstone` as standalone words (L4.gate-language) — say "operator
-answer" / "accepted" instead, and keep enum values out of that list too.
+as extra bullets. No section body may use `HITL`, `merge event`, `content-gate`, `GATED`, or
+`capstone` as standalone words (L4.gate-language); ambiguous words (`approval`, `approved`,
+`merged`) warn only with a gating cue (`until`, `after`, `once`, `before`, `pending`, `blocked`,
+`wait for`, `requires`) in the same sentence, so plain composition prose stays silent — say
+"operator answer" / "accepted" instead, and keep enum values out of that list too.
 
 **The order sidecar.** Also emit the private task-order sidecar at
 `.spur/run/<runId>-idea-task-order.json`: a JSON array (one entry per batch item) of

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

@@ -1,6 +1,6 @@
 ---
 name: spur-cli
-description: "Reference and operate the complete `spur` CLI surface: task, feature, rule, workflow, builder, agent, message, self, history, and projects. Use for verb or flag lookup, machine-readable output and exit contracts, or CLI-gated corpus writes. Triggers: \"spur task\", \"spur history\", \"spur projects\", \"create a task\", \"task check\", and any Spur CLI convention. Not for planning or execution lifecycle orchestration (`sp:spur-dev`)."
+description: "Reference and operate the complete `spur` CLI surface: task, feature, rule, workflow, builder, agent, message, decision, self, history, and projects. Use for verb or flag lookup, machine-readable output and exit contracts, or CLI-gated corpus writes. Triggers: \"spur task\", \"spur history\", \"spur projects\", \"spur decision\", \"spur agent join\", \"create a task\", \"task check\", and any Spur CLI convention. Not for planning or execution lifecycle orchestration (`sp:spur-dev`)."
 license: Apache-2.0
 metadata:
   author: spur
@@ -17,6 +17,7 @@ metadata:
     - builder
     - agent
     - message
+    - decision
     - self
     - history
     - projects
@@ -44,11 +45,12 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 | **Tier A** | **rule** | Constraint quality gate: run presets, author rules, fine-tune, validate rule files/presets, extend engine | [references/rules.md](references/rules.md) |
 | **Tier A** | **workflow** | Dual-mode workflow runtime: author state-machine / transition-flow workflows, validate, run, read traces | [references/workflows.md](references/workflows.md) |
 | **Tier A** | **builder** | Release plumbing: bump a package (or the `workspace:`-pinned set) with `bump-ver`, delete release tags with `drop-tags`, commit + tag + optional push | [references/builder.md](references/builder.md) |
-| **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, list agent specs, start/stop supervised processes, readiness check | [references/agent.md](references/agent.md) |
+| **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, list agent specs (incl. `agent.fleet` members), start/stop supervised processes, fleet `report`/`join`/`leave`/`wait`/`trace`, readiness check | [references/agent.md](references/agent.md) |
 | **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
 | **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
@@ -141,6 +143,8 @@ and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.
   [dispatch-surface rule](../parallel-execution/references/dispatch-surface.md).
 - **[references/message.md](references/message.md)** - durable inter-agent messaging (`send`,
   `inbox`, `reply`, `watch`).
+- **[references/decision.md](references/decision.md)** - decision catalog (`list`, `show`, `run`,
+  `status`); offline by default via the built-in `typesafe` maker.
 - **[references/self.md](references/self.md)** - `spur self init|maintain|migrate|serve|status` CLI verbs
   (the five legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
   validation (Phase 1.5/1.6 probes).

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

@@ -22,15 +22,19 @@ that before using `run` for fan-out dispatch.
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
 | `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` |
+| `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>` `--inbox <id>` `--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 `queued` | `[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
+Every verb except `trace` accepts `--json` plus `--json-envelope`; `trace` is `--json` only. 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)
 
@@ -136,23 +142,27 @@ exits 2 naming the accepted vocabulary. Resolution collapses onto the same ident
 
 ```bash
 spur agent list              # detected coding agents on this machine
-spur agent list --specs      # agent specs under .spur/agents/
+spur agent list --specs      # agent specs: .spur/agents/*.yaml + agent.fleet members
 spur agent list --json       # machine-readable
 ```
 
 Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
-lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the server's
+lists agent specs — hand-authored `.spur/agents/*.yaml` merged with the members declared under
+`agent.fleet.members` (derived in memory, never written to disk; the fleet declaration wins on an
+id clash; stale `fleet:generated` files are ignored) — **with live run status merged from the server's
 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.
+member has no recorded session. `--json` rows carry `source: file` (plus `path`) or `source: fleet`
+(no backing file, so no `path`). When `spur self serve` is unreachable, the listing falls back to all
+`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
-# planner	claude	reviewer	claude	plans the work	running pid=4132	resume id=3f9c2a1d
-# worker-1	pi	worker	pi	implements	stopped	one-shot
+# myapp-planner-1	claude	planner	claude	orchestrator	running pid=4132	resume id=3f9c2a1d
+# myapp-coder-1	pi	coder	pi	implements	stopped	one-shot
 ```
 
 ## `status` - live status + member session per spec
@@ -164,9 +174,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 myapp-coder-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 `queued` 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,23 +271,50 @@ 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
-spur agent start worker-1
-spur agent start worker-1 --json
+spur agent start myapp-coder-1
+spur agent start myapp-coder-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
 
 ```bash
-spur agent stop worker-1
-spur agent stop worker-1 --json
+spur agent stop myapp-coder-1
+spur agent stop myapp-coder-1 --json
 ```
 
 Posts to the supervisor API
@@ -286,7 +391,9 @@ one never re-sends settled work; only never-started deliveries release and redel
   **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
   reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
 - **Not the fleet orchestrator.** The `spur self serve` supervisor drives the lifecycle: `spur agent
-  start` / `stop` manage supervised processes and `agent list --specs` reports live state.
+  start` / `stop` manage supervised processes and `agent list --specs` reports live state. Dispatch
+  policy (`agent.fleet.strategy` `rest|gtd`, the `orchestrator` member, `--agent fleet` routing)
+  lives in project config and the workflow executor, not in these verbs.
 
 ## See also