@gobing-ai/spur 0.3.47 → 0.3.49

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -33,10 +33,13 @@ each would be scope creep for one-liner procedures.
 > it does not map to a numbered dev-\* operation. See its command file and the backing skill for details.
 
 > **`dev-find-issue`** is not in this table. It is a thin `Skill()` wrapper over **`sp:issue-finding`**
-> (session-log forensics → optional CLI-gated fix task). Hygiene / post-batch analysis — not a spine
-> pipeline stage. See `plugins/sp/commands/dev-find-issue.md` and
-> `plugins/sp/skills/issue-finding/SKILL.md`. After a slow `/sp:dev-runall`, prefer
-> `/sp:dev-find-issue [<topic>]` before re-running the batch.
+>(session-log forensics report → optional CLI-gated fix task via `--create-task`). Hygiene /
+>post-batch analysis — not a spine pipeline stage. Report-first (task 0556): the default run
+>renders the `spur history report --mode forensics` data plane plus model-authored analysis and
+>creates nothing; task creation is opt-in behind `--create-task` (`--use-history`/`--no-task` are
+>removed). See `plugins/sp/commands/dev-find-issue.md` and
+>`plugins/sp/skills/issue-finding/SKILL.md`. After a slow `/sp:dev-runall`, prefer
+>`/sp:dev-find-issue [<topic>]` before re-running the batch.
 
 > **`dev-find-conflict`** is not in this table. It is a thin `Skill()` wrapper over
 > **`sp:conflict-finding`** (authority-aware four-pillar semantic audit → optional confirmed,
@@ -137,12 +140,12 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` with omit/`--agent inline` reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with eligible `agent.run` stages dispatching once to a native subagent and host fallback (task 0508); `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
+- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` with omitted `--agent` or explicit `--agent inline` reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess; **omitted** `--agent` keeps 0508 eligibility (eligible `agent.run` stages dispatch once to a native subagent, host fallback), while explicit `--agent inline` is the zero-dispatch carve-out (every stage executes in the invoking session). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
   - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline uses [inline-pipeline-driver.md](inline-pipeline-driver.md) (host-controlled; eligible stages may use a native subagent); explicit/headless executor selection invokes `spur workflow run .spur/workflows/task-pipeline.yaml --vars '{"wbs":"<wbs>"}'` (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
   - **`implement`** (explicit `--mode implement` only): Execute only the implement step. Read the task's `## Requirements` / `## Design` / `## Plan`, write the code that satisfies them, author the `## Solution` change-map section (file:line + what/why per changed file) via `spur task update <wbs> --section Solution --from-file`. This is the implement step the pipeline calls — it is NOT the pipeline driver. With `--next`: on success, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`; on a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` and `## Review` sections MUST carry a `⚠️ PARTIAL` marker naming the deferred part and the follow-up WBS — see `plugins/sp/commands/dev-run.md` → "Section ownership".
-- **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline; `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
+- **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline (explicit `inline` = zero-dispatch carve-out); `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
 
 ### 5. refine
 
@@ -249,11 +252,11 @@ must not be changed without updating the backing skill.
 ### 6. plan
 
 - **Purpose:** Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (with **Design by default**).
-- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. The planning pipeline's `agent.run` stages always dispatch a subprocess; `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). **Design package flags (unified with `/sp:dev-idea`):**
+- **Inputs:** `"<description>"` (required). `--feature <id>` links to an existing feature. `--parent <feature-id>` nests under a parent. The planning pipeline's `agent.run` stages always dispatch a subprocess; `--agent <inline|auto|name>` selector accepted — explicit `inline` is rejected on this headless surface with the stable special error (see [SSOT](cross-cutting.md#inline-default-execution-surface)). **Design package flags (unified with `/sp:dev-idea`):**
   - **Default:** author task `design` on every batch item + feature satellite when the seam heuristic fires (**ties lean design**). There is **no** `--design` force flag.
   - `--skip-design` — skip feature satellite **and** omit task `design` fields (scaffold only; refine fills later). Sole design opt-out.
   - `--approve-taste` — with `--auto`, pre-clear design-approval taste pause when that gate is used (`design_approved=true`). Alias: `--design-approved`.
-- **Backing:** `sp:spur-dev` skill, `plan` operation. Stage `plan` floors at `capable-2` (fallback `capable-3`).
+- **Backing:** `sp:spur-dev` skill, `plan` operation. Stage floor: the `planner` role per [`roles.md`](../../../references/roles.md) — this file names roles, never tiers (0538 R4).
 - **Behavior:** Clarify scope → `spur feature create` → author BDD AC → `spur feature check` gate → decompose into task-batch JSON **including `design` (unless `--skip-design`)** → `spur task batch-create` gate. Design package details: [planning-workflow.md](planning-workflow.md) Step 5.5.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="plan $ARGUMENTS")`
 
@@ -297,7 +300,7 @@ must not be changed without updating the backing skill.
 ### 14. wrap
 
 - **Purpose:** Wrap up a single completed task — capture learnings, record metrics, sync docs, and optionally advance the feature / clean up the branch.
-- **Inputs:** `<wbs>` (required, positional). `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omit/`inline` resolves to `agent.default` under objective trigger 3 (durable auditable run record required), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations (the branch-cleanup HITL gate still pauses — irreversible). `--merge` triggers branch cleanup (irreversible HITL gate).
+- **Inputs:** `<wbs>` (required, positional). `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omitted `--agent` resolves to `agent.default` under objective trigger 3 (durable auditable run record required) while explicit `--agent inline` is rejected with the stable special error (headless workflow surface), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations (the branch-cleanup HITL gate still pauses — irreversible). `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run .spur/workflows/wrapup-pipeline.yaml` — direct workflow invocation (no backing skill; the pipeline IS the procedure).
 - **Behavior:** Resolves the executor (`agent.default` for omit/`inline`, tier-resolved for `auto`, unchanged for a name), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[\"<wbs>\"]","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs: task-resolve → doc-sync → learning-capture → metrics-record → (feature-transition) → (branch-cleanup) → done. Task statuses are NOT mutated. Branch cleanup is an irreversible HITL gate that always pauses, even under `--auto`.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `spur workflow run --vars` accepts only string values (`--vars values must be strings`); the pipeline's guards parse the string with `jq length`. `jq -nc` guarantees the shape:
@@ -313,9 +316,9 @@ must not be changed without updating the backing skill.
 ### 15. wrapall
 
 - **Purpose:** Wrap up a batch of completed tasks — capture learnings, record metrics, sync docs, advance a feature through legal lifecycle edges, and optionally clean up branches.
-- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature AND advances the feature through legal lifecycle edges (`backlog → active → verifying → done`, guards honored). `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omit/`inline` resolves to `agent.default` under objective trigger 3 (durable auditable run record required), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
+- **Inputs:** `--since <iso-date>` filters done tasks by frontmatter `updated_at >= date` (v1 approximation). `--feature <id>` selects all tasks under a feature AND advances the feature through legal lifecycle edges (`backlog → active → verifying → done`, guards honored). `--status <s>` (default: `done`) filters by task status. `--agent <inline|auto|name>` names the wrap's model-bearing executor (default: `agent.default`); wrap is workflow-backed, so omitted `--agent` resolves to `agent.default` under objective trigger 3 (durable auditable run record required) while explicit `--agent inline` is rejected with the stable special error (headless workflow surface), `auto` tier-resolves an executor, and a name pins that executor into `vars.agent` (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips objective confirmations. `--merge` triggers branch cleanup (irreversible HITL gate).
 - **Backing:** `spur workflow run .spur/workflows/wrapup-pipeline.yaml` — direct workflow invocation.
-- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (`agent.default` for omit/`inline`, tier-resolved for `auto`, unchanged for a name), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","feature":"<id>","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` but with the full task list and optional feature transition. Task statuses are NOT mutated. Feature transitions go through `spur feature update` so lifecycle guards apply. Branch cleanup is an irreversible HITL gate.
+- **Behavior:** Resolves the task list via `spur task list --json` (filtered by `--feature`, `--since`, `--status`), resolves the executor (`agent.default` for omitted `--agent`, tier-resolved for `auto`, unchanged for a name; explicit `--agent inline` is rejected with the stable special error), emits a pre-dispatch notice naming the subprocess override — `execution surface: subprocess`, `reason: trigger 3 — durable auditable run record required`, `requested agent: <selector>`, `executor: <resolved>` — then builds `--vars '{"tasks":"[...]","feature":"<id>","agent":"<resolved>","profile":"interactive|auto","merge":"true|false"}'` and invokes the wrapup pipeline. The pipeline runs the same states as `wrap` but with the full task list and optional feature transition. Task statuses are NOT mutated. Feature transitions go through `spur feature update` so lifecycle guards apply. Branch cleanup is an irreversible HITL gate.
 - **Vars string typing:** `tasks` is a JSON-encoded **string**, not a JSON array — `--vars` values must be strings (the CLI rejects raw arrays); `jq -nc` passes the array text through as a string value:
 
   ```bash

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -134,7 +134,7 @@ On the subprocess path, when `--agent <value>` is set (passed through from the t
 `--vars '{"wbs":"<wbs>","agent":"<value>","implementAgent":"<value>"}'`. The pipeline YAML reads
 `${vars.agent}` for review/verify/test-fix and `${vars.implementAgent}` for implement — setting
 both keys ensures the pinned executor reaches every hop. The full value-semantics contract (one
-rule, value table, objective triggers, and headless `inline`→`agent.default` resolution per ADR-047)
+rule, value table, objective triggers, and headless `inline` rejection (stable special error) per the ADR-047 G5 amendment)
 lives in [cross-cutting.md](cross-cutting.md#inline-default-execution-surface) — the SSOT.
 This file documents only the **workflow-pipeline mechanics**: how the selector reaches `agent.run`
 steps. Precedence chain: `--agent` / explicit `--vars` → `agent.default` → YAML literal (see SSOT
@@ -245,12 +245,13 @@ an executor failed — the executor is swappable via config, the pipeline is not
 **When an `agent.run` step fails (timeout, non-zero exit, empty output):**
 
 1. **Diagnose, don't bypass.** Check `spur agent doctor <executor>` — is the agent
-   installed? Is auth present? Then check `.spur/config.yaml` → which executor does the
-   phase resolve to? Which model does that executor use? Could that model be out of tokens,
-   rate-limited, or deprecated?
+   installed? Is auth present? Then check `.spur/config.yaml` → which role/executor does the
+   run resolve to (`agent.default` role → stage-registry tier ladder)? Which model does that
+   executor use? Could that model be out of tokens, rate-limited, or deprecated?
 2. **Switch executors, don't abandon the pipeline.** Override the agent for the run:
-   `spur workflow run ... --vars '{"wbs":"<wbs>","agent":"<alt-executor>"}'` or re-run with
-   a different `default-by-phase` mapping. The operator can also update config in-flight.
+   `spur workflow run ... --vars '{"wbs":"<wbs>","agent":"<alt-executor-or-role>"}'`, or change
+   the `agent.default` role / stage-registry tier floor in config. The operator can also update
+   config in-flight.
 3. **Surface to the operator.** If you cannot determine the cause, ask. Do NOT silently
    fall back to direct implementation. A pipeline step failure is a recoverable event; a
    bypass is an irrecoverable provenance loss.
@@ -299,17 +300,18 @@ the partial work still in the working tree. The failure output names the partial
    (honest `done_reason`, verdict regeneration).
 
 **3. Match the executor to the size (task 0487 R3).** Size and executor capability are one
-decision, not two. **≥ 6 requirements or ≥ 9 Plan items → a `capable-1`+ executor, or split the
+decision, not two. **≥ 6 requirements or ≥ 9 Plan items → a `reviewer`-role executor (the
+`reviewer` row of [`roles.md`](../../../references/roles.md) declares the floor), or split the
 task.** A `cheap`/`standard`-tier model handed a task that big does not fail fast: it consumes the
 entire `implementTimeoutMs` and exits 3 with a partial tree (run `ca130182` — 7 reqs / 9 plan
 items / 12+ files → 30 minutes, 6 of 12 files, no tests, no docs, no `## Solution`).
 
 The precheck size gate enforces this: it resolves `$implementAgent`'s capability tier
-(`spur agent doctor <exec> --json` → `capabilityTier`) and writes FAIL for a large task on a
-sub-`capable-1` executor, naming the executor and its tier. An unknown or undeclared tier reads as
-`standard`, so the block is the default. Clear it deliberately — `--agent <capable>` /
-`--vars '{"implementAgent":"<capable>"}'`, or split — never by raising `maxImplementReqs`: the caps
-accept a big task, they do not make a flash model able to finish one.
+(`spur agent doctor <exec> --json` → `capabilityTier`) and writes FAIL for a large task on an
+executor below the `reviewer` role's floor, naming the executor and its tier. An unknown or
+undeclared tier reads as the `coder` floor, so the block is the default. Clear it deliberately —
+`--agent <capable>` / `--vars '{"implementAgent":"<capable>"}'`, or split — never by raising
+`maxImplementReqs`: the caps accept a big task, they do not make a flash model able to finish one.
 
 The empty-implement guard (`requireDiff` on the task-pipeline `implement` step, R3) fails the
 run fast when an implement exits 0 with zero non-corpus changes — a no-op never drifts into

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -47,14 +47,25 @@ The value table below is the C3a cross-file parity surface (kept in lockstep wit
 
 | 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                                                                  |
+| `(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                                                                  |
 | `<name>`                        | That coding agent or configured executor                                    | Inline when it is the current session's agent; subprocess otherwise         |
 
+**Declared-role threading (0538 R1).** Every command file declares `role: <scribe|coder|reviewer|planner>`
+in its YAML frontmatter, taken from its row in `plugins/sp/references/roles.md`; the dispatcher
+threads it into `--agent` so subprocess dispatch routes by the declared role. An explicit `--agent`
+value always wins; the declared role is the default when the flag is `auto`/omitted at a subprocess
+boundary. The same declaration exists on workflow `agent.run` steps (`role:` beside `agent:`) and is
+threaded by `AgentRunActionRunner`; a pin still beats role routing permanently (0536 R2).
+
 The previous `--inline` and `--subprocess` flags (feature H82, task 0413) are collapsed into this
 selector: `--inline` → `--agent inline`, `--subprocess` → `--agent auto`. Those two flags are no
 longer part of the command surface; their anchors (`#flag-inline`, `#flag-subprocess`) are retained
-as stubs below so external links do not dangle. Operator-layer vocabulary (task 0405): `agent` names
+as stubs below so external links do not dangle. **Superseded (feature G5):** the `--inline` →
+`--agent inline` leg of the collapse no longer means "equivalent to omitting the flag" — explicit
+`inline` is the zero-dispatch host-session carve-out (see
+[cross-cutting.md](cross-cutting.md#inline-default-execution-surface)). Operator-layer vocabulary (task 0405): `agent` names
 the concrete coding-agent tool; `executor` remains the domain-layer role and is not a command flag.
 `inline` and `auto` are reserved values — config validation rejects an executor claiming either.
 
@@ -193,13 +204,13 @@ Select an execution mode: `full|implement` on `dev-run` (full pipeline vs implem
 `briefing|structure|architecture|design|full` on `dev-reverse`. Mode selection is explicit and orthogonal
 to `--next`.
 
-### `--task [<feature-id>]` — seed a task from the current result
+### `--task <wbs>` — task work or task narrowing
 
 **Anchor:** `#flag-task`.
 
-Connect the current command's result to task work (`dev-brainstorm`, `dev-debug`, `dev-dogfood`,
-`dev-find-next`). The optional value and the effect are per-command — this flag is a family, not one
-behavior:
+Connect the current command's result to task work, or narrow a history analysis to one task
+(`dev-brainstorm`, `dev-debug`, `dev-dogfood`, `dev-find-next`, `dev-history-load`). The value and
+the effect are per-command — this flag is a family, not one behavior:
 
 - `dev-brainstorm` `[<feature-id>]` — **creates** one task from the chosen approach, landing at
   `todo` ready for refine. Optional feature id scopes it.
@@ -210,6 +221,7 @@ behavior:
   id names the target instead of offering rank 1.
 - `dev-debug` `[<wbs>]` — **attaches** findings to an existing task. Optional WBS names it.
 - `dev-dogfood` (no value) — **records** run outcomes against the task under test.
+- `dev-history-load` `<wbs>` — narrows the `analyze` step to that task's messages.
 
 ### `--since <ref>` — lower bound on a range
 
@@ -234,6 +246,15 @@ Remediation policy on verify-family commands (`dev-verify`, `dev-verifyall`):
 Upper bound on a range: a git ref on `dev-changelog` (defaults to `HEAD`), or an ISO date on
 `dev-find-issue` (defaults to now).
 
+### `--source <source>` — agent source to scope the operation
+
+**Anchor:** `#flag-source`.
+
+Scope the operation to one agent source (`dev-find-issue`, `dev-history-load`): one of
+`pi|claude|codex|gemini|opencode|antigravity|openclaw|omp|grok|agy` (or `all`). On
+`dev-history-load` the value is forwarded to **both** `spur history import` and
+`spur history analyze`; on `dev-find-issue` it narrows the report scan to that source's sessions.
+
 ### `--status <s>` — filter by task status
 
 **Anchor:** `#flag-status`.

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -153,6 +153,8 @@ transition to `done`.
 > an answer file or debugging an UNKNOWN verdict.
 
 > **Corpus baseline discipline (`corpus-check`).** `corpus-check` sweeps every task/feature and fails on any structural finding outside `config/corpus-baseline.json`. The baseline is two-sided: an unlisted finding fails, **and** a listed entry that no longer reproduces fails. When introducing or tightening finding rules, reconcile the fallout in the same commit (constitution **T10**).
+>
+> **Transition-shim discipline (`transition-shim-check`, task 0541 / ADR-058).** Wired as the last step of `spur-check` / `spur-check-new`. Two-sided against `config/transition-shims.json`: an `@transition-shim(<id>)` marker with no manifest entry fails as a **new unregistered shim**, **and** a listed entry whose marker is gone from source fails as a **stale entry**. Emptying the manifest is the definition of the agent-role transition being complete. A removal condition must be objectively checkable against the repository. Shapes: `docs/04_DESIGN.md` §2.5.
 
 > **Sandbox test baseline (`bun run test` / `spur-check`).** In the restricted Bash sandbox
 > `bun run spur-check` exits **1 regardless of code health**: ~24 tests bind real ports and the

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -62,7 +62,9 @@ Action semantics come from the YAML and the workflow action contract:
 **Native-subagent dispatch (R2 eligibility, evaluated before each action):**
 
 1. The invocation is one of the two interactive inline full-pipeline surfaces (`dev-run --mode full`
-   or sequential `dev-runall`, omit/`inline`).
+   or sequential `dev-runall`) with the `--agent` flag **omitted**. Explicit `--agent inline` is the
+   zero-dispatch carve-out: every model stage executes in the invoking host session — the
+   native-subagent leg below never applies to it.
 2. The YAML action kind is `agent.run` and its input is a pure slash command. Shell, note, file,
    guard, and operator-interaction actions remain host-executed.
 3. The current state/action has no operator-confirmation action, `pause: true`, approve/taste/ask
@@ -71,10 +73,18 @@ Action semantics come from the YAML and the workflow action contract:
    and Spur task/run-artifact access.
 
 All four pass → dispatch. Any pre-dispatch failure → execute the stage **once** in the host session.
+An `agent.run` whose `input` is free-form prose rather than a pure slash command fails condition 2
+and is never dispatch-eligible: the driver executes it in the host session and logs it with the
+existing host-fallback line `stage <id> executed inline in session <session-id>` — it does not
+reformulate the prose into a command, spawn a subagent for it, or silently promote it to dispatch.
 No token estimate, stage-size threshold, model heuristic, or configuration switch is added.
 
 **Dispatch and join:** before dispatch, capture the same pre-action git snapshot used by
-`requireDiff` enforcement. Send only: the stage id, the YAML's exact pure slash command, and
+`requireDiff` enforcement, and resolve `answerFile`/`expectFile` against the worktree root — the
+resolved absolute path, not the YAML's relative string, is what the dispatched agent is instructed
+to write and what post-join validation reads. Resolving once at the dispatch boundary fixes every
+surface at once; a relative path would resolve against whatever cwd the writer process happens to
+have. Send only: the stage id, the YAML's exact pure slash command, and
 `execution surface already resolved: native subagent; do not dispatch this stage again`. The WBS/path
 already carried by the slash command is the handoff — do not paste task/session transcripts or embed
 machine-specific session paths. Dispatch exactly one native subagent and wait for it; the inline FSM

package/schemas/spur-config.schema.json

@@ -103,7 +103,7 @@
             "properties": {
                 "default": {
                     "type": "string",
-                    "description": "Default executor selector for `--agent auto` (resolved as an executor name first, then a legacy agent name e.g. pi, claude, codex)."
+                    "description": "Default role for `--agent auto` when nothing is declared (0542 R2). A role id (scribe, coder, reviewer, planner) selects its tier's cheapest eligible executor; a configured executor name still resolves during the transition with a one-time warning; any other value is rejected naming both accepted sets."
                 },
                 "executors": {
                     "type": "array",
@@ -135,6 +135,26 @@
                         }
                     }
                 },
+                "roles": {
+                    "type": "object",
+                    "description": "Per-role tier/stage overrides over DEFAULT_AGENT_ROLES (0572 / ADR-061). Keys are the closed role vocabulary (scribe, coder, reviewer, planner); a present field replaces the default for that role, an omitted field keeps it. Mirrors @gobing-ai/spur-config AgentRoleConfigSchema (Zod is SSOT).",
+                    "additionalProperties": {
+                        "type": "object",
+                        "properties": {
+                            "tier": {
+                                "type": "string",
+                                "enum": ["cheap", "standard", "capable-1", "capable-2", "capable-3"],
+                                "description": "Replacement capability tier for the role. Must not sit below the highest min_tier among the role's folded stages (enforced at the CLI boundary)."
+                            },
+                            "stages": {
+                                "type": "array",
+                                "minItems": 1,
+                                "items": { "type": "string", "minLength": 1 },
+                                "description": "Replacement folded-stage list for the role. Ids must come from the canonical stage registry (validated at the CLI boundary). Omit the field to keep the default — an empty array is rejected."
+                            }
+                        }
+                    }
+                },
                 "team": {
                     "type": "object",
                     "description": "Declarative agent teams keyed by team id (the map key is the teamId). Each team materializes a roster of agent specs (feature M). Mirrors @gobing-ai/spur-config TeamConfigSchema (Zod is SSOT).",
@@ -168,12 +188,11 @@
                                         },
                                         {
                                             "type": "object",
-                                            "required": ["executor"],
                                             "properties": {
                                                 "executor": {
                                                     "type": "string",
                                                     "minLength": 1,
-                                                    "description": "Executor name \u2014 resolved against agent.executors first, else a raw canonical agent type."
+                                                    "description": "Executor name \u2014 resolved against agent.executors first, else a raw canonical agent type. Optional since 0543: a role-only member (no executor) resolves one through the tier ladder at materialization; at least one of role or executor is required."
                                                 },
                                                 "id": {
                                                     "type": "string",
@@ -183,6 +202,11 @@
                                                 "purpose": {
                                                     "type": "string"
                                                 },
+                                                "role": {
+                                                    "type": "string",
+                                                    "enum": ["scribe", "coder", "reviewer", "planner"],
+                                                    "description": "Layer-1 role id (0538 R3): typed routing field carried onto the materialized spec; purpose stays prose."
+                                                },
                                                 "workspace": {
                                                     "type": "string",
                                                     "minLength": 1,
@@ -251,6 +275,26 @@
                 }
             }
         },
+        "history": {
+            "type": "object",
+            "description": "History import/analyze configuration (feature E3). Opt-in operation-triggered refresh.",
+            "properties": {
+                "refresh": {
+                    "type": "object",
+                    "properties": {
+                        "on_completion": {
+                            "type": "boolean",
+                            "description": "Enqueue a coalesced history refresh when a task or pipeline run completes. Default false (opt-in; hidden automation is out of contract)."
+                        },
+                        "debounce_ms": {
+                            "type": "integer",
+                            "minimum": 0,
+                            "description": "Coalescing window in milliseconds. Completions inside the window join one pending refresh. Default 60000."
+                        }
+                    }
+                }
+            }
+        },
         "tasks": {
             "type": "object",
             "description": "Task-folder registration (design \u00a79). Absorbs the legacy docs/.tasks/config.json folders + baseCounter concepts. Mirrors @gobing-ai/spur-config tasksConfigSchema (Zod is SSOT).",