@gobing-ai/spur 0.3.47 → 0.3.49

package/plugins/sp/skills/issue-finding/references/session-formats.md

@@ -1,37 +1,38 @@
 ---
 name: session-formats
-description: "Multi-source session log roots, tool-call field maps, OMP deep dive, and spur history bridge for sp:issue-finding."
+description: "Source → session-log root-path table and spur history bridge for sp:issue-finding."
 see_also:
   - issue-finding
 ---
 
-# Session log formats — multi-source discovery
+# Session log formats — source discovery
 
-`sp:issue-finding` analyzes **raw session JSONL** for tool-loop forensics. Layout and event
-shapes differ by coding agent. This file is the SSOT for DISCOVER path selection and ANALYZE
-field mapping.
+`sp:issue-finding` analyzes **raw session JSONL** for tool-loop forensics — as the **fallback**
+path only (task 0556): the primary REPORT path is the typed data plane
+(`spur history report --mode forensics`). Layout and event shapes differ by coding agent. This
+file covers **DISCOVER path** (where logs live) and the **history bridge**.
 
-**Confidence legend**
-
-| Level | Meaning |
-|-------|---------|
-| High | Documented adapter used successfully on real sessions (OMP) |
-| Medium | Default roots from Spur history help / importer sources; parse best-effort |
-| Low | Operator must pass `--sessions`; field map incomplete |
+**What typed tables retain is owned by `mappers.ts`.** The importer
+`@gobing-ai/ts-llm-jsonl-importer/src/mappers.ts` is the single code authority for which JSONL
+fields each source populates on `history_message` / `history_tool_call` — including the
+todo-tool `args_raw` retention allowlist (task 0553 R1). This skill holds **no duplicate field
+map**; two maps that can disagree is the defect closed by 0553 R5.
 
 ## Source → default root
 
-| `--source` | Default root (expand `~`) | History import source | Fidelity |
-|------------|---------------------------|----------------------|----------|
-| `omp` | `~/.omp/agent/sessions/-<project-slug>/` | *(not a history source name)* | High |
-| `claude` | `~/.claude/projects/` | `claude` | Medium |
-| `codex` | `~/.codex/sessions/` | `codex` | Medium |
-| `gemini` | `~/.gemini/sessions/` | `gemini` | Medium |
-| `opencode` | agent-specific OpenCode session store (varies by install) | `opencode` | Low–Medium |
-| `antigravity` | agent-specific Antigravity session store | `antigravity` | Low–Medium |
-| `openclaw` | OpenClaw / `~/.agents/` session trees when present | `openclaw` | Low–Medium |
-| `pi` | Pi conversation/session roots (see `spur history` examples) | `pi` | Medium |
-| `auto` | Detect: prefer explicit agent if known; else first existing root among `omp`, `claude`, `codex`, `pi`, `gemini` | maps when importing | — |
+| `--source` | Default root (expand `~`) | History import source |
+|------------|---------------------------|----------------------|
+| `omp` | `~/.omp/agent/sessions/-<project-slug>/` | *(not a history source name)* |
+| `claude` | `~/.claude/projects/` | `claude` |
+| `codex` | `~/.codex/sessions/` | `codex` |
+| `gemini` | `~/.gemini/sessions/` | `gemini` |
+| `opencode` | agent-specific OpenCode session store (varies by install) | `opencode` |
+| `antigravity` | agent-specific Antigravity session store | `antigravity` |
+| `openclaw` | OpenClaw / `~/.agents/` session trees when present | `openclaw` |
+| `pi` | Pi conversation/session roots (see `spur history` examples) | `pi` |
+| `grok` | `~/.grok/sessions/<url-encoded-workspace-path>/<session-uuid>/chat_history.jsonl` | `grok` |
+| `agy` | *(no discoverable on-disk session format — VS Code fork)* | `agy` |
+| `auto` | Detect: prefer explicit agent if known; else first existing root among `omp`, `claude`, `codex`, `pi`, `gemini` | maps when importing |
 
 **Project slug (OMP):** path under the sessions root is typically the project path with `/`
 replaced (e.g. `/Users/…/xprojects/spur-new` → `-Users-…-xprojects-spur-new` or
@@ -41,71 +42,20 @@ that matches the cwd project when ambiguous.
 **When the default root is missing or empty:** stop guessing. Ask for a path or require
 `--sessions <glob>`.
 
-## Portable tool-call map
-
-When parsing a line of JSONL, look for tool/function invocations under common shapes:
-
-| Source family | Typical tool block type / path | Bash/command field |
-|---------------|--------------------------------|--------------------|
-| OMP / omp-agent | `message.content[]` entries with `type: "toolCall"` | `arguments.command` |
-| Claude Code | `type: "tool_use"` (or nested message content) | `input.command` / `input` |
-| Codex / others | Importer-normalized or vendor-specific; search for `command`, `tool_name`, `name` | best-effort |
-
-Always record **what field path you used** in the inventory Notes so evidence is auditable.
-
-**Fail-loud rule:** a zero tool-command count across a **non-empty** session set means the field map
-is wrong, not that the sessions were idle. Report a probable field-map error instead of an
-idle-session / no-waste finding — a parser that matches nothing must never produce a clean verdict
-(0534 R3; the OMP shape is `arguments.command`, verified: a toolCall block's keys are
-`['arguments','id','intent','name','partialArgs','streamIndex','type']`).
-
-**Loop detection (all sources):** normalize the shell command string and count consecutive or
-near-consecutive identical invocations (≥3) without an intervening source-file edit tool call.
-
-## OMP deep dive (High fidelity)
-
-OMP/agent session logs are JSONL under `~/.omp/agent/sessions/-<project>/`:
-
-- Each line is a JSON object with a `type` field
-- Key event types: `session`, `message`, `compaction`, `title`, `title_change`, `custom`
-- Tool calls live in `message.content` as blocks with `type: "toolCall"` (**not** `tool_use`)
-- Bash tool calls expose `arguments.command` (verified live against OMP JSONL: a toolCall block's
-  keys are `['arguments','id','intent','name','partialArgs','streamIndex','type']`)
-- Subagent sessions live in subdirectories (e.g. `Run0376/`, `Refine0378/`)
-- Subagents may have `*.log` beside the JSONL session file
-- Session start: `session.timestamp`
-- Session title: `title.title` (often auto-generated from the first user message)
-- Session id pattern: `<ISO-timestamp>_<UUID>.jsonl`
-- Cross-session: subagent messages may carry `parentId` linking to the parent session
-
-**Discovery without `--sessions`:** list the project sessions directory; take the newest
-timestamped main session file; include sibling subagent JSONL under that session’s tree.
-
-## Claude / Codex / Pi / Gemini (Medium)
-
-Documented import examples (see `docs/help/cmd_history.md`):
-
-```bash
-spur history import --source claude --root ~/.claude/projects --mode incremental
-spur history import --source codex --root ~/.codex/sessions/ --mode incremental
-spur history import --source gemini --root ~/.gemini/sessions/ --mode full
-spur history import --source pi --file ~/pi/logs/conversation.jsonl
-```
-
-For issue-finding:
-
-1. Prefer raw JSONL under those roots for tool-loop analysis.
-2. Use `--sessions` when multiple projects share a root.
-3. Tool event shapes may differ from OMP — use the portable map; do not force `toolCall`-only parsing.
+**Fail-loud rule:** a zero tool-command count across a **non-empty** session set means the field
+map is wrong, not that the sessions were idle. Report a probable field-map error instead of an
+idle-session / no-waste finding — a parser that matches nothing must never produce a clean
+verdict (0534 R3).
 
-## History bridge (`--use-history`)
+## History bridge
 
-`spur history` holds **validated ETL + ledger**, not a full replacement for forensic JSONL:
+`spur history` holds **validated ETL + ledger**. It is the primary REPORT path
+(`spur history report --mode forensics`). Raw session JSONL is the named fallback only.
 
 | Need | Use |
 |------|-----|
-| Token / cost aggregates | `spur history analyze [--since …] --json` after import |
-| Identical test-command loops, guard retries, git red herrings | Raw session JSONL (this skill’s primary path) |
+| Token / cost aggregates, derived forensics | `spur history analyze` then `spur history report --mode forensics` |
+| Identical test-command loops, guard retries, git red herrings | Raw session JSONL (fallback — primitives the typed tables do not retain) |
 | Multi-agent cost rollups | Import per source, then analyze |
 
 Import does not invent bottleneck categories. If import fails or the DB is empty, continue with
@@ -120,13 +70,13 @@ queries from that result:
 ```bash
 # one introspection pass, then write data queries against what it reports
 sqlite3 <db> "SELECT name, sql FROM sqlite_schema WHERE type='table' AND name LIKE 'history_%';"
-# (or a single `.schema history_<table>` invocation per referenced table)
 ```
 
 If a column you expected is absent, trust the live schema — do not guess. The importer's
-`HISTORY_IMPORT_SCHEMA_SQL` is the authority; this skill holds no duplicate column contract.
+`HISTORY_IMPORT_SCHEMA_SQL` + `mappers.ts` are the authority; this skill holds no duplicate
+column contract.
 
-**Selected-file bridge (task 0507 R3):** `--use-history` imports the frozen Phase-1 file set one
+**Selected-file bridge (task 0507 R3):** the data-plane path imports the frozen Phase-1 file set one
 file at a time — never a root scan, never a full reconciliation. Ambient discovery covers the
 normal OMP root (`~/.omp/agent/sessions/`) **and** workflow subprocess sessions under
 `.spur/run/<run-id>/agent-sessions/<omp-executor>/*.jsonl` (same `type: "message"` envelope). For
@@ -134,25 +84,72 @@ each file, the session key is the JSONL filename stem (importer `sessionIdFromCo
 analyze per key:
 
 ```bash
-bun run apps/cli/src/index.ts history import --source omp --file <absolute-file> --mode force-file --json
-bun run apps/cli/src/index.ts history analyze --session <filename-stem> --json
+# Monorepo-safe spur resolution (0568 R6): SPUR_BIN env > monorepo-local CLI > PATH.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+$SPUR_BIN history import --source omp --file <absolute-file> --mode force-file --json
+$SPUR_BIN history analyze --session <filename-stem> --json
 ```
 
 ETL owns token/cost/message/tool/loop/assistant-duration aggregates; raw JSONL stays authoritative
 for command text, compactions, test/guard retries, and tool execution duration/status/errors.
 
+## OMP tool-call block shapes (task 0564 R5)
+
+Live OMP assistant messages emit **flat** toolCall blocks whose argument bag sits under
+`arguments`; older sessions emit the **legacy nested** `{toolCall:{…}}` envelope, and an
+intermediate shape used `input` as the argument key. The fallback parser and this skill must
+read all three the way the importer does — **`mappers.ts` (`normalizeOmpToolCall`,
+`call.input ?? call.arguments`) is the single field-map authority**; this section records the
+shapes for recognition, it is not a second map.
+
+1. **Legacy nested block** — argument bag under a `toolCall` envelope:
+
+```json
+{"type":"message","message":{"role":"assistant","content":[
+  {"toolCall":{"id":"call_x","name":"bash","arguments":{"command":"git status","i":"Check state"}}}
+]}}
+```
+
+2. **Flat block, legacy `input` key**:
+
+```json
+{"type":"message","message":{"role":"assistant","content":[
+  {"type":"toolCall","id":"call_x","name":"bash","input":{"command":"git status","i":"Check state"}}
+]}}
+```
+
+3. **Flat block, current `arguments` key (live shape)** — `{type, id, name, arguments, intent,
+   partialArgs, streamIndex}`:
+
+```json
+{"type":"message","message":{"role":"assistant","content":[
+  {"type":"toolCall","id":"call_x","name":"bash","arguments":{"command":"git status","i":"Check state"},
+   "intent":"Check state","partialArgs":"{\"command\":\"git status\",\"i\":\"Check state\"}","streamIndex":0}
+]}}
+```
+
+The command text is the `command` field inside the argument bag: `call.input ?? call.arguments`
+then `.command` — never a hardcoded key choice.
+
+**toolResult messages** are `role: "toolResult"` message envelopes (not content blocks) carrying
+`{toolCallId, toolName, content, details, isError, timestamp}` — `details.wallTimeMs` is the
+tool's own measured wall time when present; `toolCallId` joins the originating `toolCall.id`.
+The importer retains the timing (`history_tool_call.duration_ms` / `started_at` /
+`completed_at`, task 0564 R1); raw logs stay authoritative for result text, which lives in
+`content[].text` — not a `block.output` field.
+
 ## Edge cases
 
 | Scenario | Handling |
 |----------|----------|
 | No session root found | Fail DISCOVER with a clear message; request `--sessions` |
 | Huge multi-hour JSONL | Prefer Grep/rg for signal patterns first; sample then deep-read hot regions |
-| Mixed agents in one investigation | Run per `--source` or pass an explicit multi-file `--sessions` glob; label each session’s source |
-| Only transcript markdown available | Medium/Low confidence; extract commands from fenced blocks if present; mark evidence quality |
+| Mixed agents in one investigation | Run per `--source` or pass an explicit multi-file `--sessions` glob; label each session's source |
 | Redacted / truncated logs | Analyze what remains; do not invent tool counts |
 
 ## Related
 
 - Skill entry: [../SKILL.md](../SKILL.md)
 - History CLI: `spur history --help`, `docs/help/cmd_history.md`
+- Typed-table field authority: `@gobing-ai/ts-llm-jsonl-importer/src/mappers.ts`
 - Daily usage (not session forensics): `sp:daily-summary` / ccusage

package/plugins/sp/skills/next-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: next-feature
-description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' by deriving importance/urgency from corpus, git, and authority-doc evidence, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' by deriving importance/urgency from corpus, git, and authority-doc evidence, and emits rank-distorting tree defects as proposals /sp:dev-feature-change consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -30,7 +30,7 @@ A prompt-first prioritizer that answers **"which feature should we work on now?"
 `sp:next-router` deliberately does not answer (`routing-table.md` §0 step 1c: target omitted → not
 v1). It derives importance and urgency from evidence already in the corpus, ranks the actionable
 frontier in **tiers with per-candidate evidence**, and emits rank-distorting tree defects as
-**proposals** `/sp:dev-featurechange` consumes.
+**proposals** `/sp:dev-feature-change` consumes.
 
 **Honesty contract:** prompt-first. The model applies the rubric; existing deterministic tools
 (`spur feature|task … --json`, `git`, `rg`) gather facts. No TypeScript analyzer, no numeric scores,
@@ -39,7 +39,7 @@ in this corpus it is 76% one value (0493 measurement).
 
 **Propose, never apply.** This skill performs no `spur feature move` and writes nothing under
 `docs/features/**`. The only path from a structure proposal to a changed tree is
-`/sp:dev-featurechange` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
+`/sp:dev-feature-change` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
 `--task`, which after an **operator confirm** (interactive, or auto-accepted under `--auto`)
 dispatches `/sp:dev-plan` and `/sp:dev-refineall` — commands that write `docs/tasks*/` through their
 own gates. This skill still creates no tasks itself.
@@ -52,7 +52,7 @@ own gates. This skill still creates no tasks itself.
 **Do NOT use for:**
 
 - Advancing an already-chosen task or feature — that is `/sp:dev-next` (`sp:next-router`).
-- Applying tree changes — that is `/sp:dev-featurechange` (feature F31).
+- Applying tree changes — that is `/sp:dev-feature-change` (feature F31).
 - Task-level ordering inside a feature — next-router's TABLE A owns that.
 
 ## Protocol
@@ -106,7 +106,7 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
 - Ranking a feature whose actionability gate fails. Gate first, rank second.
 - Emitting a numeric score (WSJF/RICE arithmetic) from absent value/effort estimates.
 - Copying the B3 predicate into this skill. Cite it; read it at runtime.
-- Any `spur feature move`, or writing proposals anywhere `docs/features/**` — featurechange owns apply.
+- Any `spur feature move`, or writing proposals anywhere `docs/features/**` — feature-change owns apply.
 - Decomposing a feature here, or calling `spur task create` / `spur task batch-create` under `--task`.
   Dispatch `/sp:dev-plan`; it owns decomposition and the batch-create schema gate. Equally:
   dispatching under `--auto` without `--task` (there is no confirm to skip), auto-accepting a target
@@ -123,7 +123,7 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
 | [references/signal-derivation.md](references/signal-derivation.md) | Sync precondition, B3 runtime citation, per-signal derivation commands, degenerate-spread rejection |
 | [references/ranking-rubric.md](references/ranking-rubric.md) | Tier definitions, tie-breaks, evidence-per-candidate output contract |
 | [references/proposal-contract.md](references/proposal-contract.md) | D1–D4 defect set, evidence bar, mapping-schema conformance, silence |
-| [references/handoff-routing.md](references/handoff-routing.md) | featurechange handoff, next-router seam, the `--task` tier→hop routing table and its confirm contract |
+| [references/handoff-routing.md](references/handoff-routing.md) | feature-change handoff, next-router seam, the `--task` tier→hop routing table and its confirm contract |
 
 Grounding: tickets 0493 (measured signals), 0494 (reuse ledger), 0495 (defect contract) under
 feature H12.

package/plugins/sp/skills/next-feature/references/handoff-routing.md

@@ -1,4 +1,4 @@
-# Handoff routing — featurechange handoff, next-router seam, conditional dispatch
+# Handoff routing — feature-change handoff, next-router seam, conditional dispatch
 
 ## The seam with `/sp:dev-next` (next-router)
 
@@ -8,7 +8,7 @@
 - When the operator picks a winner from the ranked report, the printed handoff line is:
   `/sp:dev-next <feature-id>`.
 
-## The handoff to `/sp:dev-featurechange` (feature F31)
+## The handoff to `/sp:dev-feature-change` (feature F31)
 
 Defect proposals follow the 0495 Artifact C boundary, traced end to end:
 
@@ -16,9 +16,9 @@ Defect proposals follow the 0495 Artifact C boundary, traced end to end:
 | --- | --- | --- |
 | 1. Detect + emit proposal rows | this skill | No |
 | 2. Handoff | printed inline in the report (report reading of OQ1) | No |
-| 3. `--dry-run` | `/sp:dev-featurechange` | No |
+| 3. `--dry-run` | `/sp:dev-feature-change` | No |
 | 4. Confirm | operator | — |
-| 5. `--apply` (`spur feature move`) | `/sp:dev-featurechange` only | **Yes — sole writer** |
+| 5. `--apply` (`spur feature move`) | `/sp:dev-feature-change` only | **Yes — sole writer** |
 
 There is no path from this skill to a mutated tree that bypasses step 4. Proposal rows are printed
 inline in the default report; writing them into `docs/plans/feature-tree-restructure-map.md` as new
@@ -83,7 +83,7 @@ inside dispatched children remain governed by their own contracts (`--approve-ta
 ### What `--task` does not change
 
 The defect half is untouched: still no `spur feature move`, still nothing written under
-`docs/features/**`, still `/sp:dev-featurechange` as the sole applier of structure proposals. `--task`
+`docs/features/**`, still `/sp:dev-feature-change` as the sole applier of structure proposals. `--task`
 adds one gated path to `docs/tasks*/`, through commands that own their own gates.
 
 ## Where outputs go

package/plugins/sp/skills/next-feature/references/signal-derivation.md

@@ -7,7 +7,10 @@ cannot be derived is reported as **unavailable**, never fabricated.
 ## §0 — Sync-first precondition (step zero)
 
 ```bash
-spur feature sync --all --dry-run --json
+# Monorepo-safe spur resolution (0568 R6): SPUR_BIN env > monorepo-local CLI > PATH.
+# Defined once here; §1+ reuse $SPUR_BIN — §0 runs first by construction.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+$SPUR_BIN feature sync --all --dry-run --json
 ```
 
 Feature `status` is manual bookkeeping and drifts (0493: 24 of 25 rankable features would change
@@ -34,7 +37,7 @@ renamed, the fallback key is its content: "frontier = open ∧ unblocked".)
 Inputs per candidate feature:
 
 ```bash
-spur task list --feature <id> --json
+$SPUR_BIN task list --feature <id> --json
 ```
 
 `task list --feature` is **active-folder-only**: it enumerates tasks in the active task folder
@@ -52,9 +55,11 @@ is not authoritative — a frontier task may be archived outside it. Run the fal
    the feature's row as an **anomaly hint** only: it may flag the feature without naming a WBS. The
    sync reason is never treated as a WBS source — no WBS is ever inferred from sync prose.
 2. Scan the whole corpus for linked tasks:
+
    ```bash
    rg -l '^feature_id: "?<id>"?$' docs/tasks*/
    ```
+
    Corpus ids are `[A-Z][0-9]+`-shaped, so `<id>` is regex-safe as-is; escape metacharacters if a
    non-conforming id ever appears.
 3. Parse the leading WBS from each matched basename; resolve every corpus-only WBS (not present in

package/plugins/sp/skills/next-router/SKILL.md

@@ -47,7 +47,7 @@ silently (that is a HITL stop).
 | `--dry-run` | Print the resolved plan (**P1**) and do not dispatch. |
 | `--once` | Strip `--next` from the shaped child argv so only the current step runs; no router re-entry. |
 | `--auto` | Forward into dispatched children that support it. **Never** breaks multi-candidate HITL ties. |
-| `--agent <inline\|auto\|name>` | Execution-surface selector forwarded into the dispatched child when that child documents `--agent`. Router defaults inline; a named escalation trigger overrides `--agent inline`. Omit → forward nothing. |
+| `--agent <inline\|auto\|name>` | Execution-surface selector forwarded into the dispatched child when that child documents `--agent`. Router defaults to omit semantics: Omit forwards nothing, and the dispatched child applies its own default (host session, 0508 eligibility). Explicit `--agent inline` is the zero-dispatch carve-out, forwarded as-is; escalation triggers reject `inline` (no override). |
 | `--full` | When the primary route is `dev-run … --next`, substitute `dev-run <wbs> --mode full` (no `--next`). No effect on non-run routes → warning **W-FULL**. |
 
 ## Protocol (deterministic)

package/plugins/sp/skills/parallel-execution/references/dispatch-surface.md

@@ -57,8 +57,8 @@ wrong choice visible in the transcript.
 `model_policy` (`min_tier` + ordered `fallback` chain, keyed on the canonical `stage_id`). This
 reference owns **execution-surface selection**. The two axes are orthogonal and vary independently:
 
-- A `cheap`-tier step can run in-session on a native subagent.
-- A `capable-3`-tier step can run headless through `spur agent run`.
+- A `cheap`-floor step (e.g. the `scribe` role) can run in-session on a native subagent.
+- A capable-band step (a role at or above `reviewer`, per [`roles.md`](../../../references/roles.md)) can run headless through `spur agent run`.
 
 Do not fold surface choice into `model_policy` - that would couple two axes that vary independently
 and put prompt-layer routing policy into a domain-layer registry. This reference decides *which
@@ -98,6 +98,44 @@ native subagent with shared-worktree capability); the inline driver remains the
 provenance, artifact validation, and no-replay guarantees. This reference stays the authority for
 the native-subagent versus `spur agent run` choice everywhere else.
 
+## Role propagation across fan-out (task 0551, feature I4)
+
+When a run dispatches subagents, the **effective role** each subagent resolves through follows one
+rule: **a declared role wins; absent a declaration, the subagent inherits the dispatcher's.**
+Propagation is recorded, never implied: the resolution envelope carries `roleOrigin:
+'declared' | 'inherited'` per dispatched subagent (R3), so a wrong inheritance is observable
+without reading the dispatcher's source. The role travels on the existing `--agent` selector —
+no new flag (feature I4 § Notes).
+
+Mechanism: `AgentService` stamps the dispatcher's resolved role into every spawned subprocess
+environment as `SPUR_ROLE` (`RolePropagatingProcessExecutor`,
+`packages/app/src/services/agent-service.ts`). A child `spur agent run` reads it at resolution;
+a subagent that declares its own role (role selector, workflow `role:` step, explicit
+`--agent <role>`) resolves through that role's tier and records `roleOrigin: 'declared'`; one
+that declares nothing resolves through the inherited role's tier and records
+`roleOrigin: 'inherited'` (stage context is engine-internal — stage-registry policy and
+escalation — with no `--stage` CLI flag and no workflow step input; 0539 surface sweep).
+Nested fan-out applies the rule recursively by construction — a grandchild reads
+its parent's `SPUR_ROLE`, which the parent already set. An unknown inherited role (stale env)
+warns once and falls through to `agent.default`/priority — inheritance never hard-fails a
+dispatch (task 0536 R3 precedent).
+
+**Dispatch-path inventory (R4)** — every path that shells out to `spur agent run` applies the
+rule at the source, so no per-path shim is needed:
+
+| Path | Where it dispatches | Rule coverage |
+| --- | --- | --- |
+| `spur agent run` (CLI) | `AgentService.run` → resolution → child process | Declared wins; absent inherits via `SPUR_ROLE`; envelope carries `roleOrigin` |
+| Workflow `agent.run` step | `AgentRunActionRunner` → `AgentService.runTraced` | Step `role:` is **mandatory** (0538 R2, `agent-run.ts` fails a role-less step before dispatch) — always a declaration (`roleOrigin: 'declared'`); inheritance applies at the next fan-out boundary the step's subagent itself dispatches |
+| `spur agent loop` | `AgentService.run` per drained iteration | Same resolution path as `spur agent run`; inherits its own `SPUR_ROLE` |
+| `spur team` supervisor → member | spawns `spur agent loop` | Member inherits the supervisor's `SPUR_ROLE` (recursive by construction) |
+| Native subagent fan-out (this skill's default) | in-session `Task()`/`Skill()` | In-session subagents share the host session; when they themselves dispatch, the host's role is already in the session env — the rule holds at the next `spur agent run` boundary |
+| `plugins/sp/evals/run-eval.ts` | `spawnSync('spur agent run', …)` per scenario | Out of scope: a top-level eval harness, not a fan-out — no dispatcher role exists to inherit; each scenario is an independent top-level run (documented, no shim) |
+
+The inventory is recorded in `docs/04_DESIGN.md` § `spur agent run` envelope (`roleOrigin`).
+Paths that shell out to `spur agent run` without the rule would silently drop or double-attribute
+a role; this table is the check that none do.
+
 ## See also
 
 - **`parallel-execution`** SKILL.md - the dispatch disciplines this rule sits beside.