@gobing-ai/spur 0.3.47 → 0.3.49

package/plugins/sp/skills/pr-reviewing/SKILL.md

@@ -0,0 +1,285 @@
+---
+name: pr-reviewing
+description: "GitHub Codex PR-review workflow — prepare/reuse a PR, request `@codex review`, collect findings, and optionally validate/fix/re-review them. Backs /sp:dev-pr-review. Triggers: PR review, codex review, @codex review, review my PR, codex findings, dev-pr-review."
+license: Apache-2.0
+version: 1.0.0
+metadata:
+  author: spur
+  platforms: "claude-code,codex,openclaw,opencode,antigravity,pi"
+  category: engineering-core
+  interactions:
+    - workflow
+    - review
+  pipeline_steps:
+    - preflight
+    - hygiene
+    - request
+    - wait
+    - collect
+    - triage
+see_also:
+  - sp:code-verification
+  - sp:functional-review
+  - sp:spur-cli
+  - sp:spur-dev
+---
+
+# sp:pr-reviewing — GitHub Codex PR Review
+
+Backend for `/sp:dev-pr-review`. The invoking coding agent is the local orchestrator and
+implementer; **GitHub Codex Code Review** is the independent reviewer. The point of the route is
+that review effort happens on the PR, through Codex — not in the local session.
+
+## Architecture
+
+```text
+/sp:dev-pr-review (thin command)
+      │  Skill(skill="sp:pr-reviewing", args=...)
+      ▼
+sp:pr-reviewing (this skill — mode routing, triage, fix, rules)
+      │  deterministic spine, state order + guards:
+      ▼
+.spur/workflows/pr-review.yaml ← workflow SSOT (seeded by spur init; project-tunable)
+      │  every state resolves with `superskill script path` and shells out to:
+      ▼
+staged pr-reviewing.ts         ← Bun entrypoint for the tested git/gh core
+```
+
+- **State order and guards** are defined once, in the workflow YAML. Do not re-derive them in
+  prose; when the YAML and this file disagree, the YAML wins and this file gets fixed.
+- **Deterministic work** (every git/gh call) goes through the script subcommands — never
+  hand-rolled `gh` invocations that drift from the tested core.
+- **Model-bearing work** (finding triage, `fix` edits, `rules` authoring) is this skill's job and
+  never enters the workflow machine.
+- The workflow YAML exposes only its declared spine modes (`full`, `submit`, and `rerun`). The
+  direct-mode routes below own `collect`, `fix`, `status`, and `rules`; keep those modes outside
+  the workflow `mode` variable.
+
+## Non-negotiable Codex routing
+
+The external review MUST go through the GitHub pull request and an `@codex review` request.
+Never substitute a local Codex review mechanism — no Codex CLI `/review`, no `codex review`, no
+vendor-specific local review commands. If GitHub Codex Code Review is unavailable, stop and report
+the setup/access problem; never silently fall back to a local review.
+
+Never claim a request consumed a specific billing/quota bucket unless the platform exposes that
+fact. The guarantee of this workflow is the route: GitHub Codex Code Review on the PR.
+
+## Modes and routing
+
+Parse the first positional argument as the mode; default `full`.
+
+| Mode | Route | Behavior |
+| --- | --- | --- |
+| `full` | Workflow YAML | Preflight → hygiene → precheck → push → ensure-pr → request (reviewed/in-flight HEAD dedupe) → wait → collect → report. No source edits. |
+| `submit` | Workflow YAML | Run the spine through `request`; return pending for a new request (`--no-wait` has the same effect). If the exact current HEAD was already reviewed, collect that result instead of requesting a duplicate. |
+| `rerun` | Workflow YAML | Run the spine and request a fresh review of the current pushed HEAD with `--force`. No source edits. |
+| `collect` | Direct script | Do not start the workflow or request a review. Collect the current PR's result and composite status; a missing current-HEAD result is **pending**, never clean. |
+| `fix` | Direct script + model work | Collect first, independently validate current-HEAD findings, fix legitimate issues, verify, make one focused commit, push, then force-request/review/collect the new HEAD. Do not pass `mode=fix` to the workflow. |
+| `status` | Direct script | Read-only composite: repository, branch, local HEAD, PR/base, local changes, CI, and Codex state for the current PR HEAD. Do not start the workflow. |
+| `rules` | Model work only | Create or improve the repo-root `AGENTS.md` section `## Code Review Rules`; do not invoke the workflow, request a review, commit, or push. |
+
+## Arguments
+
+- `--base <branch>` — base for a newly created PR. Default: existing PR's base, else repo default.
+- `--no-wait` — after a successful request, return pending instead of polling.
+- `--agent <inline|auto|name>` — names **who performs model-bearing work**, per the
+  [inline-default execution-surface contract](../spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+  Omit: the current agent is the default owner (eligible model stages may use one native subagent
+  under the shared contract). `inline` keeps all model work in the host session as the hard
+  zero-dispatch guarantee. `auto` resolves the command's declared role; a named executor pins that executor.
+  An alternate executor gets one `spur agent run --agent <value>` dispatch with the selector removed
+  from child args; that child owns model work. Current-agent selection stays inline.
+  Headless surfaces reject explicit `inline` with the shared stable error.
+- `--agent` describes the model owner only; it is independent of the deterministic git/GitHub spine
+  and the workflow/direct route. Run the selected route in that resolved skill context. A separate
+  workflow subprocess belongs to the caller's execution surface or an objective trigger (for example,
+  a required durable run record), not to `--agent auto` or a name by itself.
+- Remaining free text — extra review focus, appended to the Codex request without weakening
+  repository-defined rules (e.g. `security and authorization boundaries`, `migration safety`).
+
+## Safety rules
+
+**Git history — never:** force-push (`--force`/`--force-with-lease`), destructive `git reset`,
+`git clean`, rewriting published history, merging the PR, deleting branches, discarding unrelated
+user changes.
+
+**Local changes.** A GitHub PR only reviews pushed commits. If relevant changes are uncommitted:
+inspect the tree, separate relevant from unrelated, never `git add .` blindly, and ask the user
+before creating any commit outside `fix` mode. If safe separation is ambiguous, stop and explain.
+In `fix` mode the user pre-authorized one focused fix commit for verified findings — still stop if
+unrelated uncommitted changes make safe editing or committing ambiguous.
+
+**Current-HEAD invariant.** Treat the PR's pushed `headRefOid` as the review identity. After every
+preflight, push, commit, and request, record the returned HEAD and require `wait`, `collect`, and
+the report to match that exact HEAD. A result for an older commit is stale; a result absent for the
+current HEAD is pending, not clean. Reject uncorrelated issue/conversation comments rather than
+using them to manufacture a current-HEAD result. In `fix` mode, discard the old result after the
+fix commit and judge only the forced re-review for the new pushed HEAD.
+
+**Reviewer authority.** Codex is an independent reviewer, not an authority. For every finding that
+may lead to a code change: inspect the referenced code, verify reachability and intended behavior,
+inspect callers/callees where needed, check existing tests, classify, reject false positives, fix
+root causes rather than wording, prefer the smallest coherent patch, avoid drive-by refactors.
+
+## Workflow-backed spine (`full`, `submit`, `rerun`)
+
+Run the workflow YAML's declared states in order. Every deterministic state invokes the
+staged entrypoint below, supports `--json`, and must be parsed. Stop at the first red gate and
+report its artifact. The canonical installed invocation is:
+
+```sh
+bun "$(superskill script path sp pr-reviewing.ts)" <subcommand> [flags]
+```
+
+Installed targets resolve the staged TypeScript source and execute it with Bun, matching the rest
+of `plugins/sp/scripts`.
+
+1. **Preflight** — `<script> preflight --json`. Hard-fails on a
+   detached HEAD, missing `gh` auth, no GitHub remote, or a dirty tree. On a dirty tree, triage
+   with the user (commit/stash/exclude) before continuing — the workflow refuses to guess.
+2. **Hygiene** — `<script> hygiene --base "$base" --json`. `BLOCK` (secrets, `.env`, conflict markers,
+   private keys) stops the run — never submit a tainted diff. `WARN` (debug residue) rides along
+   into the report. This is a submission sanity check, not a second local review.
+3. **Precheck** — if the workflow YAML's `preReviewCmd` var is set, run it; a red check stops the
+   run (do not spend a review request on code that fails its own gate). When unset, report that
+   pre-review verification was not configured rather than inventing project commands.
+4. **Push** — `<script> push --json`. Normal push only; sets upstream when missing.
+5. **Ensure PR** — `<script> ensure-pr --base "$base" --json`. Reuses the branch's PR; creates with
+   `gh pr create --fill` only when absent. Never a duplicate PR.
+6. **Request** — `<script> request --focus "<focus>" --json` (`--force` in `rerun` mode). Dedupes when
+   Codex already reviewed the exact pushed HEAD (`ALREADY_REVIEWED` → skip to collect) or a marked
+   request by the current GitHub user is still in flight (`ALREADY_REQUESTED` → pending). The
+   request body is concise when the repo has `## Code Review Rules`, else carries the default
+   actionable-issues focus. Records PR, URL, HEAD, and request time.
+7. **Wait** (full/rerun unless `--no-wait`; submit stops before it) —
+   `<script> wait --since "$requestedAt" --head "$requestHead" --json`, using the request result so
+   a fast response is not missed, `rerun` cannot reuse the prior review, and a moved HEAD fails loud.
+   Polls every ~30s for up to
+   ~10 minutes across the current HEAD's PR review and inline comments. Uncorrelated conversation
+   comments are ignored. A current-HEAD clean review is a completed `CLEAN` outcome; findings are
+   `FOUND`; timeout or no current-HEAD result is **pending, not failed** — collect later.
+8. **Collect** — `<script> collect --since "$requestedAt" --head "$requestHead" --json`. Normalize
+   only the requested HEAD and request window; then invoke `status` with the same bounds for
+   PR/base/CI/local state. Never turn an absent, stale, or moved-HEAD result into `clean`.
+
+## Fix mode
+
+Only in `fix` mode:
+
+1. **Collect before editing.** Invoke direct `collect --json` plus `status --json` and require a
+   completed result for the current pushed HEAD. If the result is pending, stale, or unavailable,
+   report it and stop without source edits. If it is explicitly clean, report no fixes and stop.
+2. **Validate each finding.** Open the referenced code; trace callers/callees; verify the problem
+   is reachable; check intended behavior and existing tests. Classify: `Confirmed`,
+   `Likely valid`, `Needs investigation`, `Likely false positive`. Never edit for a likely false
+   positive; investigate further before editing a `Needs investigation`.
+3. **Fix legitimate issues** with the smallest coherent change. Preserve existing interfaces
+   unless the defect requires otherwise; no unrelated refactoring; add or update tests when they
+   materially demonstrate the fix; follow repository conventions. Inspect `git diff` — the patch
+   must contain only intended review fixes.
+4. **Verify** with repository-defined targeted tests/type checks/linters. Never claim a check
+   passed unless it actually ran successfully.
+5. **Commit** one focused review-fix commit. The message describes the actual defect
+   (`fix: prevent duplicate transaction retry`), never `fix codex comments`. No unrelated files.
+6. **Push** normally to the existing PR branch (never force), record the new HEAD, and discard the
+   previous review identity.
+7. **Re-review:** invoke the staged `request --force`, then wait/collect as usual. The new review
+   must correspond to the new pushed HEAD — never present stale findings from the previous HEAD as
+   the new result. Include composite CI/status fields in the final report.
+
+## Rules mode
+
+Only in `rules` mode. Inspect the architecture, existing instructions, and current root
+`AGENTS.md`, then create or improve a section named exactly `## Code Review Rules`, preserving
+unrelated content. Prefer repository-specific invariants over generic advice, using only categories
+that matter to the project: data safety (atomic multi-step writes, idempotency, transaction
+boundaries), security (server-side authorization, untrusted client identifiers, secrets in logs),
+API compatibility (public contracts, CLI, serialized formats, event payloads, schema), concurrency
+(races, stale writes, retry semantics), migration safety (backward-compatible rollout,
+mixed-version operation), tests (which high-risk changes require regression coverage), and project
+invariants a reviewer unfamiliar with the codebase could miss. Avoid generic advice (`write clean
+code`) and anything lint/format already enforces mechanically. Keep it concise and actionable.
+Show the diff, summarize the meaningful rules added, and do not commit or push.
+
+## Reporting
+
+Findings report:
+
+```text
+PR
+  #<number> <url>
+
+HEAD
+  <short SHA>
+
+Codex review
+  Clean | Findings | Pending | Unavailable
+
+Findings
+
+1. [severity] path:line
+   Classification: Confirmed | Likely valid | Needs investigation | Likely false positive
+   Problem:
+   Why it matters:
+   Evidence:
+   Recommended next action:
+
+CI
+  <status summary>
+```
+
+Preserve filenames, line references, severity, and the important technical reasoning. Do not
+inflate suggestions into confirmed bugs. If the review completed without actionable findings, say
+so clearly.
+
+`wait` and `collect` must distinguish an explicit current-HEAD clean result from pending, stale, or
+unavailable data. `collect` and `fix` reports also include the composite PR/base/branch/HEAD/local/CI
+status; an unavailable CI signal remains `unavailable`, never an inferred pass.
+
+Always end with the compact summary:
+
+```text
+PR:        <number + URL | none>
+Branch:    <branch>
+HEAD:      <short SHA>
+Base:      <base>
+CI:        <status>
+Codex:     clean | findings | pending | not requested | unavailable
+Findings:  <count>
+```
+
+`fix` mode appends: `Fixed: <n>`, `Rejected: <n>`, `New HEAD: <sha>`,
+`Re-review: clean | findings | pending | unavailable`. If findings remain, state the recommended
+next action.
+
+`status` mode prints the same summary block and nothing else — no file edits, PR creation, pushes,
+or review requests.
+
+## Failure handling
+
+- **`gh` missing or unauthenticated** — stop and report; do not switch to browser automation.
+- **GitHub Codex unavailable** (not enabled/authorized for the repo) — preserve the error, explain
+  the required repository/account setup, do not fall back to local Codex.
+- **PR creation failure** — report the actual git/GitHub state; never rewrite history as a
+  workaround.
+- **Review timeout** — return `pending`, not `failed`, unless GitHub explicitly reports a failure.
+- **CI failure** — Codex review and CI are independent signals; always surface failing checks even
+  when Codex reports clean.
+
+## Platform notes
+
+- The skill, command, workflow YAML, and script are platform-neutral; per-platform emission is
+  owned by superskill. On platforms without a Skill tool, read this file and follow the protocol
+  manually — the script subcommands are plain CLI invocations.
+- Prerequisites on any platform: `git`, GitHub CLI (`gh`) authenticated, and GitHub Codex Code
+  Review enabled for the repository.
+
+## Additional Resources
+
+- **Workflow SSOT:** `.spur/workflows/pr-review.yaml` (seeded by `spur init`; tune per project —
+  wait budget, `preReviewCmd`, dedupe policy)
+- **Script source:** [scripts/pr-reviewing.ts](../../scripts/pr-reviewing.ts) — subcommand CLI
+- **Tests:** [tests/pr-reviewing.test.ts](../../tests/pr-reviewing.test.ts) — stubbed git/gh suites
+- **Related skills:** `sp:code-verification` (local SECUA review), `sp:functional-review`
+  (requirements traceability) — complements, never substitutes, the independent Codex review

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/features/hierarchy-mece.md

@@ -4,7 +4,7 @@ description: >-
   Explicit rules for creating new feature nodes or extending existing ones —
   MECE roots, cautious root creation, reparent vs merge, depth limits.
   Consumed by spur feature authoring, /sp:dev-plan, /sp:dev-idea, and
-  /sp:dev-featurechange.
+  /sp:dev-feature-change.
 see_also:
   - spur-cli
   - feature-verbs
@@ -15,7 +15,7 @@ see_also:
 # Feature hierarchy: MECE roots and extension rules
 
 This is the **normative checklist** before `spur feature create` or any restructure
-(`/sp:dev-featurechange`, `spur feature move`). CLI enforces ID shape (DD-14) and
+(`/sp:dev-feature-change`, `spur feature move`). CLI enforces ID shape (DD-14) and
 ≤9 children; **judgment** here keeps the tree neat for humans and agents.
 
 ## Goals of a good tree
@@ -86,7 +86,7 @@ If any check fails → **child of best parent** or **task under existing feature
 | **Create child** | New deliverable under clear parent | `spur feature create "…" --parent <id>` |
 | **Reparent / move** | Node lives under wrong parent; Goal still valid | `spur feature move <id> --parent <new>` (cascade rename) |
 | **Rename-only** | Goal OK; title misleading | Prefer `update --field name` if supported, or document + move only if ID depth must change |
-| **Merge (absorb)** | Two nodes share one Goal; bodies should be one | Prefer: move children under survivor → fold Scope/AC into survivor → cancel or archive source. **Not** a casual `move`. Use mapping + `/sp:dev-featurechange` when batching. |
+| **Merge (absorb)** | Two nodes share one Goal; bodies should be one | Prefer: move children under survivor → fold Scope/AC into survivor → cancel or archive source. **Not** a casual `move`. Use mapping + `/sp:dev-feature-change` when batching. |
 | **Archive** | Capability retired | `cancelled` or leave `done`; do not delete history |
 
 ---
@@ -160,7 +160,7 @@ work under H.
 - [ ] Will attach tasks with `--feature <new-id>` (or parent if intentionally epic-only).
 - [ ] After create: `spur feature refresh` if INDEX must update; `spur feature check <id>`.
 
-## Checklist: before restructure / `/sp:dev-featurechange`
+## Checklist: before restructure / `/sp:dev-feature-change`
 
 - [ ] Mapping file lists disposition per node (`keep` / `reparent-under` / `merge-into` / `rename-only` / `archive`).
 - [ ] False merges rejected (name overlap ≠ one Goal).
@@ -177,6 +177,6 @@ work under H.
 | **This reference** | Agent/human judgment — MECE, root gate, merge vs reparent |
 | **`spur feature create/move/check`** | Deterministic DD-14, children limit, lifecycle |
 | **`/sp:dev-plan` / `/sp:dev-idea`** | Must run the decision procedure before allocate |
-| **`/sp:dev-featurechange`** | Batch restructure against a mapping; must not invent roots |
+| **`/sp:dev-feature-change`** | Batch restructure against a mapping; must not invent roots |
 
 Agents authoring features **must load this file** (via `sp:spur-cli` features references) before creating a root or proposing merges.

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

@@ -64,7 +64,7 @@ subtree and **cascade-renames** every descendant; omit `--parent` to lift it to
 **Before create or restructure (judgment, not CLI):** load
 [features/hierarchy-mece.md](features/hierarchy-mece.md) — MECE sibling sets, **sparse cautious
 roots**, extend-vs-create decision procedure, merge vs reparent, depth/width limits. `/sp:dev-plan`,
-`/sp:dev-idea`, and `/sp:dev-featurechange` must follow that checklist so new work prefers an
+`/sp:dev-idea`, and `/sp:dev-feature-change` must follow that checklist so new work prefers an
 existing parent over a new letter.
 
 ## Editing a feature: status, fields, and sections

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