@gobing-ai/spur 0.3.47 → 0.3.48

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,70 @@ 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
+spur history import --source omp --file <absolute-file> --mode force-file --json
+spur 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-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.

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

@@ -120,6 +120,9 @@ the whole point of this facade is that the CLI surface has a single, scalable ho
   post-scaffold init validation (Phase 1.5/1.6 probes).
 - **`sp:spur-dev`** - the spine that dispatches these verbs into the planning +
   execution lifecycle. Use it to *drive* work; use this facade to *look up or operate a verb*.
+- **`plugins/sp/references/roles.md`** — the Layer-1 role→tier table (`scribe` / `coder` /
+  `reviewer` / `planner`, one per tier). The facade's nouns/verbs serve those roles; the table is
+  the role vocabulary, the operator config maps tiers to executors.
 - **`sp:expert-spur`** — the subagent that loads this facade for multi-step, multi-noun corpus work
   in its own context window.
 

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

@@ -21,8 +21,8 @@ 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>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
-| `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--agent <id>` `--poll <ms>` |
+| `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
+| `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--spec <id>` `--agent <id>` `--poll <ms>` |
 | `wait <specId>` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2) | `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or team agent specs with `--specs` | `--specs` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` |
@@ -36,8 +36,8 @@ invalid usage.
 ## `run` - execute a prompt via a coding agent
 
 ```bash
-spur agent run "Fix the login bug in src/auth/" --agent claude
-spur agent run "verify on o3" --agent codex --model o3
+spur agent run "Fix the login bug in src/auth/" --agent coder
+spur agent run "verify on o3" --agent reviewer --model o3
 spur agent run "/sp:dev-verify 0040" --agent omp --drain
 ```
 
@@ -48,14 +48,19 @@ through a coding agent as an external process, producing a persisted run record
 
 | Flag | Purpose |
 | ------ | --------- |
-| `--agent <name>` | Agent name or `auto`. Selects which installed coding agent executes the prompt. |
+| `--agent <name>` | Role, executor, agent binary, `auto`, or `inline`. A **role** (`scribe`/`coder`/`reviewer`/`planner`, from `plugins/sp/references/roles.md`) selects the starting tier; an **executor** (an `agent.executors` entry) is a permanent pin; a **bare binary name** works with a one-time warning (transition shim); `auto` uses the declared/default role. **`inline` is host-session-only** (G5 / ADR-047 amendment): `agent run` is a headless subprocess surface, so explicit `inline` is rejected with exit 2 and a stable error message — it never normalizes to `agent.default`. |
 | `--model <name>` | Agent model argument (e.g. `o3`, `sonnet`). Passed through to the agent's model flag. |
 | `--mode <mode>` | Agent output mode: `text` or `json`. |
 | `--continue` | Resume the previous agent session instead of starting fresh. |
 | `--cwd <path>` | Working directory for agent execution (default: current directory). |
-| `--drain` | Prepend pending inbox messages addressed to `--agent <id>` before the prompt. |
+| `--spec <id>` | Team agent spec id (occupant addressing, 0542 R1). Pairs with `--drain`; with `--spec` alone the run is addressed to the occupant without touching the inbox. A legacy `--agent <spec-id>` still works during the transition with a one-time warning (shim `agent-flag-spec-id`). |
+| `--drain` | Prepend pending inbox messages addressed to `--spec <id>` before the prompt. |
 | `--json` | Output machine-readable JSON where supported. |
 
+`--json` adds a `resolved` block (`{ role?, tier?, executor?, agent, source }`) reporting the
+resolution decision — the role, its tier, and the executor that won for role routing; the pin for
+an explicit executor; the canonical agent; and the resolution source.
+
 ### Dispatch-surface cross-reference
 
 `--agent` and `--model` are the **concrete levers** behind dispatch-surface trigger 1 ("Different
@@ -91,7 +96,7 @@ under supervision.
 
 | Flag | Purpose |
 |------|---------|
-| `--agent <id>` | **Required.** Agent spec id / message recipient. |
+| `--spec <id>` | **Required.** Team agent spec id / message recipient (0542 R1; legacy `--agent <spec-id>` still read with a one-time warning). |
 | `--poll <ms>` | Idle poll interval in milliseconds (default: `2000`). |
 
 The loop runs until `SIGINT` / `SIGTERM`. Each iteration: check inbox -> if messages, drain each

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

@@ -49,7 +49,8 @@ spur team status --json             # machine-readable
 
 Lists agent specs and their live run status. When `spur serve` is reachable, enriches each spec with
 the supervisor's process status (`running` / `stopped` / etc.); otherwise falls back to local spec
-metadata. `--by-team` groups specs by their `agent.team.<id>` tag.
+metadata. Each row carries the member's declared `role` (rendered `unset` when undeclared, 0544)
+and the spec's `executor`. `--by-team` groups specs by their `agent.team.<id>` tag.
 
 ### Flags
 
@@ -67,8 +68,14 @@ spur team up alpha --check          # dry-run: show add/prune diff, no writes
 spur team up alpha --json
 ```
 
-Materializes a team roster (defined by specs sharing `agent.team.<team>`) into `.spur/agents/`
-specs - adding missing specs and pruning stale `spur:generated` ones. When `spur serve` is
+Materializes the roster declared under `agent.team` in the project config for `<team>` into
+`.spur/agents/` specs - adding missing specs and pruning stale `spur:generated` ones. **Role is
+the primary axis (0543):** a member declares `role` (`scribe`/`coder`/`reviewer`/`planner`,
+from `plugins/sp/references/roles.md`) and/or `executor`; a role-only member resolves an executor
+through the shared tier ladder at materialization, and the written spec records both `role` and
+the resolved `executor` so the decision is inspectable. A member declaring neither fails config
+load naming the team and position. Local id stays `id ?? executor`; role-only members derive
+`<role>-<n>` by declaration order. Generated specs carry the `agent.team.<team>` tag. When `spur serve` is
 reachable, best-effort starts each member. `--check` is a dry-run that shows the add/prune diff
 without writing.
 

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

@@ -211,6 +211,8 @@ for "what's actually in file Y" or for resources that sit outside the step seque
 
 **Config & companions (no single pipeline step owns these):**
 
+- `plugins/sp/references/roles.md` — the Layer-1 role→tier table (`scribe` / `coder` / `reviewer` /
+  `planner`, one per tier); the role vocabulary this spine's operations route under.
 - `.spur/workflows/task-pipeline.yaml` — the execution pipeline definition.
 - `.spur/workflows/planning-pipeline.yaml` — the front-half state machine.
 - `.spur/templates/bdd/gherkin.md` — the BDD scenario template.

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -113,6 +113,23 @@ Any of the four may additionally carry a **bracket tag** in any position — `[d
 `Scenario: [advisory] Foo`. Tags are stripped before matching (0398 R7), so tagging never breaks
 the linkage.
 
+### The id is exactly the scenario title — no Gherkin body appended
+
+An AC row id must be **exactly** the scenario title (plus any of the four forms above), with the
+Gherkin body left in the task's `### Acceptance Criteria` block. Never append the scenario's
+`Given … / When … / Then …` steps to the row id:
+
+```markdown
+| R3 — Foo | MET | test | `tests/foo.test.ts:12` |        ← correct
+| Scenario: R3 — Foo (Given … / When … / Then …) | MET | test | … |  ← never
+```
+
+The verifier preserves row ids verbatim in the verdict artifact (evidence is not rewritten), and
+the feature scenario gate strips a trailing parenthetical only as a *backstop* for artifacts that
+already carry one (0561). Appending the body is still a contract violation and makes the row
+unmatchable in edge cases (a title that legitimately ends in `(...)` plus a body), so keep ids
+clean at authoring time.
+
 ### Which tags exempt a row from executable evidence
 
 A `MET` row is silently demoted to `PARTIAL` unless it carries `test` or `command` evidence — the

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

@@ -36,13 +36,23 @@ answer. Everything below is a consequence of that sentence, not an additional ru
 
 **Default: execute the backing skill directly in the current coding-agent session.** Do not invoke
 `spur agent run` when no escalation trigger applies and the operator did not select subprocess via
-the `--agent` selector. Omitting `--agent` is exactly `--agent inline`; the explicit value is useful
-in scripts and audit output but does not change the default.
+the `--agent` selector. Omitting `--agent` keeps the default — the backing skill runs in the
+current session, and eligible model stages may dispatch once to a native subagent (task 0508). The
+explicit value is useful in scripts and audit output but is not the default: explicit `inline`
+selects the zero-dispatch carve-out below.
+
+> **Explicit `--agent inline` is a hard host-session guarantee: all model-bearing work executes in
+> the invoking host session — never a native subagent, never a subprocess, never a workflow hop.
+> The 0508 native-subagent eligibility applies to **omitted** `--agent` only. Headless surfaces
+> (`spur agent run`, workflow `agent.run`, serve-side dispatch) reject `inline` with the stable
+> special error (exit 2 at the CLI) and take no further action — no dispatch, no `agent.default`
+> fallback.**
 
 | Value | Who does the work | Derived surface |
 |---|---|---|
-| `inline` (default when omitted) | Whoever is running this session (interactive) or `agent.default` (headless) | Interactive: inline — host-controlled, eligible model stages may use a native subagent (0508); headless: subprocess of `agent.default` |
-| `auto` | Tier-resolved from the stage's `min_tier` + `fallback` | Subprocess — a tier-resolved executor pins a specific agent/model, which the host session cannot supply |
+| `(omitted)` | The agent running this session | Host session — host-controlled; eligible model stages may use a native subagent (0508) |
+| `inline` | The agent running this session | Host session — hard guarantee: zero dispatch, never a subprocess, never a workflow hop; headless surfaces reject `inline` (exit 2, stable special error) |
+| `auto` | The role the caller declared — this command's `role:` frontmatter or the workflow step's `role:` (Layer 1, `plugins/sp/references/roles.md`); with nothing declared, `agent.default`'s role (0542) | Subprocess — a tier-resolved executor pins a specific agent/model, which the host session cannot supply |
 | `<name>` (coding agent or configured executor) | That executor | Inline when it resolves to the current session's agent; subprocess otherwise |
 
 The previous `--inline` and `--subprocess` flags (feature H82, task 0413) are collapsed into this
@@ -53,8 +63,11 @@ This is a prompt-runtime rule owned by the command wrapper and its backing skill
 `AgentService`: the current coding agent is already executing the command, so inline means continuing
 in that session. Threading an `inline` option through `AiRunner` would still start a subprocess and
 would therefore be a false implementation. On a headless surface (`spur agent run` / workflow
-`agent.run`) `inline` is **not** rejected (ADR-047): it resolves exactly like omitting the flag to a
-subprocess of `agent.default`.
+`agent.run`) explicit `inline` is **rejected** (ADR-047 G5 amendment) with the stable special error —
+headless surfaces cannot host a session: `--agent inline requires a host session: this surface is
+headless and never dispatches inline runs (no fallback to agent.default). Use 'auto', a role, or an
+executor name.` (exit 2 at the CLI; the exported `AGENT_INLINE_HEADLESS_MESSAGE` in
+`agent-service`). No further action is taken — no dispatch, no `agent.default` fallback.
 
 ### Objective triggers override the answer
 
@@ -68,8 +81,10 @@ cannot satisfy, so it wins regardless:
 | **Durable auditable run record required** | The caller requires a persisted cost/trace/exit-code record. | `trigger 3: durable auditable run record required` |
 | **Workspace or credential isolation required** | The work must not share the host workspace or credentials. | `trigger 4: workspace or credential isolation required` |
 
-A trigger selects subprocess even when `--agent inline` was supplied, and the applied trigger must be
-named in the dispatch or result. When the operator selected a non-current executor and no objective trigger
+A trigger selects subprocess when the selector is omitted, `auto`, or a name, and the applied trigger
+must be named in the dispatch or result. Explicit `--agent inline` is the hard host-session carve-out:
+a trigger requirement that cannot be satisfied in-session rejects with the stable special error rather
+than dispatching a subprocess. When the operator selected a non-current executor and no objective trigger
 applies, report `operator override` rather than inventing one of the four. The trigger vocabulary and
 evidence standard are owned by
 [dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md). If none can be named
@@ -103,20 +118,23 @@ the thinking happens in the stages. Selecting an executor for a loop that runs n
 meaningless.
 
 **Interactive task pipelines invert control into the host session (ADR-047 amendment).**
-`dev-run --mode full` and sequential `dev-runall` with omit/`inline` interpret the existing
-`task-pipeline.yaml` in the host session; they do not launch `spur workflow run` and never redirect
-silently to `agent.default`. Interactive inline is **host-controlled and non-subprocess**, but no
-longer guarantees host-context execution for every model stage (task 0508): an eligible `agent.run`
-stage — pure-slash input, non-interactive state, native subagent with shared-worktree
-read/write/shell capability — dispatches **once** to that native subagent and joins before the
-driver continues; any pre-dispatch eligibility failure falls back to one host execution, and a
-failure after dispatch follows the stage's error policy with no automatic host replay. Operator
+`dev-run --mode full` and sequential `dev-runall` with omitted `--agent` or explicit `--agent
+inline` interpret the existing `task-pipeline.yaml` in the host session; they do not launch `spur
+workflow run` and never redirect silently to `agent.default`. Interactive **omit** is
+**host-controlled and non-subprocess**, but no longer guarantees host-context execution for every
+model stage (task 0508): an eligible `agent.run` stage — pure-slash input, non-interactive state,
+native subagent with shared-worktree read/write/shell capability — dispatches **once** to that
+native subagent and joins before the driver continues; any pre-dispatch eligibility failure falls
+back to one host execution, and a failure after dispatch follows the stage's error policy with no
+automatic host replay. Explicit `--agent inline` is the zero-dispatch carve-out: every model stage
+executes in the invoking host session — no native-subagent leg. Operator
 confirmation actions, `pause: true`, and approve/taste/ask decisions stay host-owned. Each inline
 model stage appends `stage <id> executed inline in session <session-id>` to its run log; a
 subagent-dispatched stage appends `stage <id> executed via subagent <agent-id> (host session
 <session-id>)` instead. `dev-plan` remains a workflow subprocess, as do `dev-run`/`dev-runall` with
 `--agent auto` or a name, parallel batches, and every headless `spur workflow run` / `spur agent
-run`. `dev-run --mode implement` continues to run its single competency in-session under omit/`inline`.
+run`. `dev-run --mode implement` continues to run its single competency in-session under omitted
+`--agent` or explicit `--agent inline` (zero-dispatch).
 
 ### Executor precedence chain (R7)
 
@@ -133,10 +151,11 @@ resolved in this order; first match wins:
 
 `--agent auto` tier-resolves an executor (stage `model_policy` → `agent.default` → tier priority)
 **before** merging, so it enters the chain at step 1 already resolved to a concrete name.
-On a headless workflow surface, `--agent inline` resolves like omit to `agent.default`. Interactive
-task wrappers consume omit/`inline` before this chain and use the host driver. Omitting the flag on a
-headless surface forwards nothing, so the spawned step resolves to `agent.default` (step 2) or the
-YAML literal (step 3).
+On a headless workflow surface, explicit `--agent inline` is rejected with the stable special error
+— the surface cannot host a session. Interactive task wrappers consume omitted `--agent` (0508
+eligibility) and explicit `inline` (zero-dispatch carve-out) before this chain and use the host
+driver. Omitting the flag on a headless surface forwards nothing, so the spawned step resolves to
+`agent.default` (step 2) or the YAML literal (step 3).
 
 ### Implement-only executor override (R6)
 
@@ -181,8 +200,10 @@ explicit process boundary and retain their existing resolution, output, timeout,
 contracts. The interactive task wrapper does not change the YAML or engine; it reads the YAML as
 SSOT and interprets the actions in-session before any workflow subprocess exists. It records inline
 provenance without fabricating an `AgentRunTracedResult`.
-`spur agent run` itself resolves omit/`inline` to `agent.default` and `--agent auto` tier-resolves —
-the unified `--agent` selector on the dev command surface does not change the CLI's resolution.
+`spur agent run` itself resolves omitted `--agent` to `agent.default`, rejects explicit `--agent
+inline` with the stable special error (a headless surface cannot host a session), and `--agent
+auto` tier-resolves — the unified `--agent` selector on the dev command surface does not change the
+CLI's resolution.
 
 ### Inline trade-off