@gobing-ai/spur 0.3.86 → 0.3.88

package/plugins/sp/skills/code-refactoring/references/fix-ladder.md

@@ -0,0 +1,52 @@
+# Fix ladder and eligibility
+
+Authority: `docs/design/dev-refactor-command.md` §6. The ladder ranks what may be applied
+mechanically versus what needs an operator answer. It reuses the repository severity meaning
+(P1 blocker / P2 major — see [finding-schema.md](./finding-schema.md)) so `--fix blockers-first`
+keeps the glossary sense.
+
+## Rungs
+
+| Rung | Example | `preservation` | `fix_eligibility` |
+| --- | --- | --- | --- |
+| Rename / move / dedupe / inline with identical behavior | A3 consolidate, T3 fixture cleanup, ui token normalization | preserving | `auto` |
+| Add missing test, contract field, a11y attribute | T4, api additive, ui P3 | preserving | `auto` |
+| Remove dead code with zero references | A1 direct removal proven dead | preserving | `auto` only when a reference search finds no caller; else `confirm` |
+| Remove a test, endpoint, control, or code path with callers | T1, A1/A2 live, api removal, ui control removal | cutting | `confirm` |
+| Change a contract or observable behavior | api breaking, A5–A7 seam moves | breaking | `confirm` (or `suggest` when multi-task) |
+| Architectural migration plan | A6–A7, ADR candidates | — | `suggest` |
+
+Hard rules:
+
+- An `auto` fix **never deletes or weakens a test** (no skipped assertions, no loosened
+  expectations, no deleted cases).
+- `cutting` and `breaking` findings are **never `auto`** and **never below P2**.
+
+## Apply policies (`--fix`)
+
+| Policy | Meaning |
+| --- | --- |
+| `none` (default) | Write both artifacts, perform no edit. |
+| `blockers-first` | Apply P1/P2 findings with `fix_eligibility: auto`. |
+| `all` | Apply every `auto` finding, then queue every `confirm` finding for the taste gate. |
+
+## Apply loop (mirrors `sp:code-simplification` / `dev-simplify`: test-after-each, revert on regression)
+
+1. **Green baseline first.** Run the `--check` command before any edit. A red baseline is a hard
+   stop: write the report, apply nothing.
+2. **One finding at a time.** Apply a single finding (highest severity first: P1 → P4), limited to
+   the finding's evidence files.
+3. **Re-run `--check`.**
+   - Passes → mark the finding `status: applied`, continue with the next.
+   - Fails → revert **only that finding's own edits**: reverse-apply the exact hunks the finding
+     introduced (keep the finding's diff; `git apply -R`, or re-edit the specific lines). Never
+     `git checkout -- <file>` a whole evidence file — a later finding may share that file with an
+     earlier **applied** finding, and a file-level checkout would revert that applied work too.
+     Mark the finding `status: reverted`, continue with the next. Never revert another finding's
+     work.
+4. After the last finding: re-run the structural check on the findings artifact, then write the
+   report (see `SKILL.md` phase 5).
+
+`confirm` findings in the `all` policy follow the taste gate: applied only after an explicit
+operator `yes` (see the gate matrix in `SKILL.md`). A declined finding is marked `status: rejected`
+or `status: deferred` (headless) per the operator answer — never silently dropped.

package/plugins/sp/skills/code-refactoring/references/focus-detection.md

@@ -0,0 +1,44 @@
+# Focus auto-detection
+
+Authority: `docs/design/dev-refactor-command.md` §8. Lens selection is **deterministic globs, not
+model judgment**, so a misroute is auditable: re-running detection on the same tree yields the same
+set.
+
+## Classification
+
+First matching table row per file; the lens set is the **union** across all files in `--scope`.
+
+| Order | Glob | Lens |
+| --- | --- | --- |
+| 1 | `**/tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**` | tests |
+| 2 | `apps/web/**`, `**/*.astro`, `**/*.tsx`, `**/*.jsx`, `**/*.css`, `**/*.vue` | ui |
+| 3 | `packages/contracts/**`, `**/routes/**`, `**/openapi*`, `**/*.proto`, `**/*.graphql`, `apps/cli/src/commands/**`, `apps/server/src/**` | api |
+| 4 | anything else (fallback) | architect |
+
+Rules:
+
+- Evaluate rows in order; a file matching an earlier row is never classified by a later one
+  (a `*.test.tsx` file is a **tests** file, not ui).
+- Every file in scope resolves to exactly one lens; the scope set is the union of resolved lenses.
+- An empty scope set (no files matched anything) collapses to the `architect` fallback for the
+  whole scope only when scope itself is non-empty; an empty scope is a resolve-phase error.
+
+## `--focus` flag
+
+| Value | Behavior |
+| --- | --- |
+| `auto` (default) | Run detection above and use its lens set. |
+| single lens (`api` \| `architect` \| `tests` \| `ui`) | Run only that lens. |
+| comma list (`api,tests`) | Run exactly the listed lenses, in the operator's order. |
+
+## Report before run
+
+The resolved lens set **must be reported before any lens runs** — one line naming the chosen
+lenses and, for `auto`, the per-file counts that selected them, e.g.:
+
+```text
+focus=auto → lenses: tests (14 files), api (3 files)
+```
+
+Under `--auto` this line is still written (to the report and the session output); what `--auto`
+skips is only the *interactive* confirmation of scope and lens set, never the report.

package/plugins/sp/skills/code-refactoring/references/refactor-finding.schema.json

@@ -0,0 +1,95 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://spur.gobing.ai/schemas/refactor-finding.schema.json",
+    "title": "Refactor findings artifact (bare array of findings, design H13 §4)",
+    "description": "One JSON object per refactoring finding; the artifact written to .spur/run/<run-id>-refactor-findings.json is a bare array of these objects.",
+    "type": "array",
+    "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+            "id",
+            "focus",
+            "severity",
+            "rung",
+            "title",
+            "evidence",
+            "preservation",
+            "fix_eligibility",
+            "proposal",
+            "verify",
+            "status"
+        ],
+        "properties": {
+            "id": {
+                "type": "string",
+                "pattern": "^RF-(api|architect|tests|ui)-[0-9]{3}$",
+                "description": "RF-<focus>-<nnn>, e.g. RF-api-001."
+            },
+            "focus": {
+                "type": "string",
+                "enum": ["api", "architect", "tests", "ui"],
+                "description": "The lens that produced the finding."
+            },
+            "severity": {
+                "type": "string",
+                "enum": ["P1", "P2", "P3", "P4"],
+                "description": "Repository-authority severity after the lens-native → P1–P4 map (finding-schema.md §5). P0 is outside the map."
+            },
+            "rung": {
+                "type": "string",
+                "description": "Lens-native rung kept verbatim: architect A0–A7, tests T0–T7, api compatibility class, ui pass name."
+            },
+            "title": {
+                "type": "string",
+                "minLength": 1,
+                "description": "One line."
+            },
+            "evidence": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["file", "line"],
+                    "properties": {
+                        "file": {
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        "line": {
+                            "type": "integer",
+                            "minimum": 1
+                        }
+                    }
+                },
+                "description": "At least one file:line inside --scope."
+            },
+            "preservation": {
+                "type": "string",
+                "enum": ["preserving", "cutting", "breaking"],
+                "description": "preserving: behavior identical; cutting: a user-visible feature/test/endpoint/control is removed; breaking: contract or behavior changes for a consumer."
+            },
+            "fix_eligibility": {
+                "type": "string",
+                "enum": ["auto", "confirm", "suggest"],
+                "description": "auto: mechanical, behavior-preserving, checkable; confirm: needs an operator answer; suggest: report only."
+            },
+            "proposal": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What to change, imperative."
+            },
+            "verify": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Command or check that proves the fix; defaults to the --check command."
+            },
+            "status": {
+                "type": "string",
+                "enum": ["open", "applied", "reverted", "deferred", "rejected"],
+                "description": "Lifecycle of the finding through the gate/apply loop."
+            }
+        }
+    }
+}

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

@@ -134,14 +134,13 @@ single run-on paragraph on render, even though they look like separate items in
 "requirements": "- [ ] R1. <text>\n- [ ] R2. <text>\n- [ ] R3. <text>"
 ```
 
-`R1. <text>\nR2. <text>` (no marker) is the trap. `spur task check` **accepts** it — the L3
-R-numbering rule matches the bare `Rn.` token — so nothing fails, and the defect only surfaces later
-as an unreadable paragraph in Board preview. Do not rely on `check` to catch this. Keep the `Rn.`
+`R1. <text>\nR2. <text>` and `- R1 — <text>` are the traps: `spur task check` reports
+`L3.requirements-checkbox` and a bare run renders as one paragraph in Board preview. Keep the `Rn.`
 (period) token inside the marker so R-numbering still resolves; see the canonical rule in
 `sp:spur-dev` → `references/planning-workflow.md`.
 
 Applies to the other body fields too: `plan` as an ordered list (`1. …\n2. …`), `acceptance_criteria`
-as a fenced ```` ```gherkin ```` block, and any enumeration inside `background` or `design` as a
+as `- [ ] AC1 — <feature scenario title without its R-number>` bullets (see § Idea-pipeline emission), and any enumeration inside `background` or `design` as a
 `- ` list.
 
 ### Design at create (default) vs `--skip-design`
@@ -207,20 +206,22 @@ scenarios are numbered in the **feature's** namespace. Both appear in a task's
 
 The rule:
 
-- **Scenarios covering the task's own requirements carry the task-local R-prefix** —
-  `Scenario: R3 — <observable outcome>`. Tasks declaring `ac_numbering: task-local` in frontmatter
-  get these cross-checked by `spur task check` (`L3.ac-requirement-coverage`): a requirement with no
-  scenario, or a scenario citing a requirement that does not exist, is reported.
-- **Scenarios carried verbatim from the feature (for DD-09 traceability) carry NO R-prefix** — copy
-  the title text only. `normalizeTitle` (`packages/domain/src/bdd/coverage.ts:58`) strips `R\d+`
-  before matching, so the prefix is invisible to feature coverage anyway; dropping it keeps the
-  feature's number from being read as a task requirement id. Verified empirically: removing the
-  prefix from a carried scenario left the feature's orphan count unchanged.
+- **Task AC items are numbered `AC1, AC2, …` (task-local), never `R<n>`** — `R<n>` is the
+  Requirements namespace, and two R-numberings in one file is how they get confused.
+- **Bind a scenario to the task requirement it covers with `(req: R<n>)`** —
+  `Scenario: AC1 — <observable outcome> (req: R3)` (semicolons for several: `R1; R2`). Tasks
+  declaring `ac_numbering: task-local` get these cross-checked by `spur task check`
+  (`L3.ac-requirement-coverage`): a requirement with no scenario, or a scenario citing a requirement
+  that does not exist, is reported.
+- **Scenarios carried from the feature (for DD-09 traceability) copy the title text after the
+  feature's `R<n> —`** — `- [ ] AC2 — <title>`. `normalizeTitle`
+  (`packages/domain/src/bdd/coverage.ts`) strips both `AC\d+` and `R\d+` before matching, so the
+  prefix is invisible to feature coverage; the feature's number is never read as a task id.
 
 **Legacy tasks are exempt.** Most existing tasks predate this and copied feature AC wholesale,
 carrying the feature's numbers. The coverage check is opt-in precisely so they emit nothing —
-absent `ac_numbering`, only DD-09 applies. Opting an old task in is a pure prefix renumber; it cannot
-break traceability. New tasks get `ac_numbering: task-local` from the templates automatically;
+absent `ac_numbering`, only DD-09 applies. Legacy `Scenario: R<n> —` titles still bind by prefix, so
+opting an old task in cannot break traceability. New tasks get `ac_numbering: task-local` from the templates automatically;
 `spur task update <wbs> --ac-numbering task-local` opts in an existing one.
 
 Edge-case scenarios may map to tasks, merge into a sibling, or be deferred. Record deferrals
@@ -523,7 +524,7 @@ The payload is a top-level JSON **array** (no `tasks` wrapper):
     "requirements": "- [ ] R1. Accept a title and an optional description on POST /tasks.\n- [ ] R2. Reject an empty title with a 400 and a reason.\n- [ ] R3. Allocate the task file through the CLI-gated write path.",
     "design": "Approach: POST /tasks via existing TaskService.create.\nRejected: ad-hoc SQL in handler.\nInvariants: CLI-gated corpus writes only.",
     "plan": "1. Contract\n2. Handler\n3. Tests",
-    "acceptance_criteria": "Scenario: create succeeds\n  Given a valid title\n  When POST /tasks\n  Then a task file is allocated"
+    "acceptance_criteria": "- [ ] AC1 — User can create a task with required fields"
   },
   {
     "name": "Implement task listing endpoint",
@@ -559,6 +560,12 @@ fields and normal default planning fills them from your analysis; the per-task r
 batch-create still deepens them when a task needs more detail. Validate locally against the
 schema before emitting.
 
+**Pass the deterministic task check.** Each `acceptance_criteria` bullet must be an exact feature
+scenario title (L4.uncovered-task-scenario); add task-local checks as prose after the bullets, not
+as extra bullets. No section body may use `HITL`, `approval`/`approved`, `merged`/`merge event`,
+`content-gate`, `GATED`, or `capstone` as standalone words (L4.gate-language) — say "operator
+answer" / "accepted" instead, and keep enum values out of that list too.
+
 **The order sidecar.** Also emit the private task-order sidecar at
 `.spur/run/<runId>-idea-task-order.json`: a JSON array (one entry per batch item) of
 `{ name: <exact batch item name>, depends_on_names: [<batch item names>] }` declaring

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

@@ -23,12 +23,14 @@ that before using `run` for fan-out dispatch.
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
 | `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
-| `list` | List detected coding agents, or agent specs with `--specs` (live run status merged from `spur serve`) | `--specs` `--server <url>` `--json` |
+| `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur serve`) | `--specs` `--server <url>` `--json` |
+| `status` | Agent specs with live process status and member session (requires `spur serve`) | `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
+| `usage` | Run-once provider usage capture (codexbar) → quota-owned availability refresh; scheduled externally | `--dry-run` `--source <name>` `--json` |
 | `start <spec-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 | `stop <spec-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
 
-`list`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+`list`, `status`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
 `loop` is a supervisor-internal process surface. **Exit codes:** `0` success, `1` failure, and `2`
 invalid usage; `run` can also propagate the invoked agent's non-zero result.
 
@@ -141,16 +143,30 @@ spur agent list --json       # machine-readable
 Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
 lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the server's
 supervisor**: each row carries a trailing status column
-(`running` / `stopped` / `errored` / `unknown`) and `pid=<n>` where a process exists. When `spur serve`
-is unreachable, the listing falls back to all `stopped` with a stderr warning. `--server <url>`
+(`running` / `stopped` / `errored` / `unknown`), `pid=<n>` where a process exists, and the member
+session (0897): the session mode plus a shortened resume id (`resume id=3f9c2a1d`), or `-` when the
+member has no recorded session. When `spur serve` is unreachable, the listing falls back to all
+`stopped` with a stderr warning. `--server <url>`
 (default `http://localhost:3000/api`) targets the supervisor API.
 
 ```bash
 spur agent list --specs
-# planner	claude	reviewer	claude	plans the work	running pid=4132
-# worker-1	pi	worker	pi	implements	stopped
+# planner	claude	reviewer	claude	plans the work	running pid=4132	resume id=3f9c2a1d
+# worker-1	pi	worker	pi	implements	stopped	one-shot
 ```
 
+## `status` - live status + member session per spec
+
+```bash
+spur agent status            # id, type, status, pid, session — one row per spec
+spur agent status --json     # full objects, session carried whole ({ mode, id })
+```
+
+Reads the same supervisor feed as `list --specs` (liveness **and** session come from
+`GET /api/processes`; the served project's ledger is the source of the session state). An
+unreachable server reports every spec `stopped` with no session. See
+[Member sessions](#member-sessions-g66) for what the modes mean.
+
 ## `doctor` - readiness check
 
 ```bash
@@ -161,9 +177,21 @@ spur agent doctor --json     # machine-readable (role selector: elected-first or
 ```
 
 Checks whether each agent is installed and ready to run. Text mode renders a capability table —
-`STATUS EXECUTOR AGENT MODEL TIER VERSION ROLES` where TIER is the executor's *capability* tier
-(`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), and ROLES lists
-candidate pipeline roles with `*` on the elected one. Exit `1` if any checked agent is not ready.
+`STATUS EXECUTOR AGENT MODEL TIER VERSION CAPS ROLES OWNER SINCE REASON` where TIER is the executor's *capability* tier
+(`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), ROLES lists
+candidate pipeline roles with `*` on the elected one, CAPS is the runner-declared session
+capability for the underlying agent binary (`r`esume/`d`ir/`s`tdin/`o`utput as ✓/✗; `—` when the
+binary is unknown to the runner; a trailing `⚠` when the detected version core differs from the
+record's `verifiedAgainst` core — branding decorations are not drift, and a record/detection with
+no version core (e.g. `unverified (CLI not installed)`) is unverifiable and never warns; a stale
+executor also emits a `capability-declaration-stale` warning
+on stderr in text mode), and OWNER/SINCE/REASON (0893) show availability provenance on `disabled`
+rows — bare `disabled: true` renders owner `operator` with `—` since/reason; object-form disables
+render their recorded values. A `usage:` footer reports the `agent usage` snapshot (`capturedAt
+(age)`, `(stale)` past 6 h, or `usage: none` when the producer has never run). `--json` stays
+stderr-clean and carries `capabilities`, `capabilityStale: {verifiedAgainst, detected}`, the
+normalized `availability` object, and a top-level `usage` per agent row instead. Exit `1` if any
+checked agent is not ready.
 
 ## `start` - start a supervised process
 
@@ -188,6 +216,61 @@ Posts to the supervisor API
 (`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
 `start`.
 
+## `usage` - run-once provider usage capture (quota-owned availability refresh)
+
+```bash
+spur agent usage            # capture, record quota observations, drain them
+spur agent usage --dry-run  # print would-be changes; write nothing
+spur agent usage --json
+```
+
+Runs `codexbar usage --format json --provider all` once, writes the snapshot to
+`~/.config/spur/agent-usage.json` (`captured_at`, `source`, `providers[]`, `raw`), maps providers
+to executors via `agent.executors[].agent` (or the model's `<provider>/` prefix), and records
+`owner: quota` availability observations that the standard drain applies — the single availability
+write path. A provider is exhausted when any `primary|secondary|tertiary` window reports
+`usedPercent >= 100`; the window name and `resetsAt` go into the observation reason. Per-provider
+`{ "error": … }` entries are skipped (listed, never treated as recovery); healthy entries still
+apply. A missing codexbar binary or an unparsable payload exits `1` and changes nothing.
+Unmapped providers are listed and never guessed.
+
+**Scheduling is external** (cron/launchd, same pattern as `spur history daily`):
+
+```bash
+# launchd/cron example — hourly
+0 * * * * /opt/homebrew/bin/spur agent usage >> /tmp/spur-agent-usage.log 2>&1
+```
+
+`spur serve` never invokes the producer (asserted by a test, design R4).
+
+### Flags
+
+| Flag | Purpose |
+| ---- | ------- |
+| `--dry-run` | Print would-be changes (executor, from → to, owner, reason); write neither the snapshot nor any config |
+| `--source <name>` | Usage source implementation; only `codexbar` exists (default) |
+| `--json` | Machine-readable result payload |
+
+## Member sessions (G66)
+
+Every fleet member loop keeps ONE coding-agent session for its lifetime, in the warmest mode the
+agent supports (`docs/design/session-pinned-dispatch.md` §6):
+
+| Mode | Mechanism | `id` |
+| ---- | --------- | ---- |
+| `persistent` | One long-lived stdin process; each drained prompt is injected through `send()` | none — the live process IS the session |
+| `resume` | Each drain re-opens the previous drain's session id | the resume id (rendered shortened) |
+| `one-shot` | A fresh session per drain (one lifetime warning per member) | none |
+
+A session **resets** (the ledger records a reason-named `fleet.member-session-reset` row) on:
+`restart` — the persistent process exited and the supervisor's restart policy respawns it;
+`operator` — `spur agent stop` / serve shutdown ended the loop; `failed-drains` — 3 consecutive
+failed drains marked the session poisoned. The next drain opens a fresh session.
+
+**No-redelivery invariant:** delivery state lives in the DB, session continuity is agent memory
+only. A settled (delivered) inbox message is never redelivered — resuming a session or resetting
+one never re-sends settled work; only never-started deliveries release and redeliver (0831/0834).
+
 ## What this skill is NOT
 
 - **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the

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

@@ -47,8 +47,10 @@ Every scenario/item carries an `R1, R2, …` prefix:
 
 - **Sequential within a feature**, starting at R1.
 - **Stable forever.** Never renumber once tasks exist — tasks match AC by **normalized scenario
-  title** (the `R<n> —` prefix is stripped on comparison), so renumbering around a title is safe
-  but *rewording* a title breaks the coverage edge.
+  title** (the `R<n> —` prefix is stripped on comparison, as is the task side's `AC<n> —`), so
+  renumbering around a title is safe but *rewording* a title breaks the coverage edge.
+- **`R<n>` is the feature's namespace.** Task AC items are numbered `AC<n>` (task-local) and copy
+  the feature title after their own prefix; task Requirements own `R<n>.` inside the task.
 - **One R-number = one scenario.** Don't split one requirement across scenarios under a single
   R-number; don't merge two requirements into one scenario.
 

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

@@ -58,6 +58,9 @@ spur feature create "Planning layer" --parent H      # → H<n>
 spur feature create "Task CLI" --parent H1            # → H1<n>
 ```
 
+`create --json` returns `{ ref: { kind, id, filePath, folder }, content }` — read the id from
+`.ref.id`, not a top-level `.id`.
+
 To restructure, use `move` — never hand-edit an ID. `move <id> --parent <new>` re-parents the
 subtree and **cascade-renames** every descendant; omit `--parent` to lift it to a top-level group.
 
@@ -184,7 +187,9 @@ spur feature check --strict --json  # warnings → failures
 ```
 
 The 4-layer validator (frontmatter, AC syntax, children-limit/structure, L4 traceability) emits its
-verdict and findings as JSON. **Query this, don't re-derive it** — the rules live in the CLI, never
+verdict and findings as a JSON **array**, one entry per feature (`jq '.[0].pass'`, `.[0].findings[].code`),
+like `spur task check --json`. Gherkin AC must keep its `Feature:` line (`L3.ac-bdd-error`) and
+every `Scenario:` title is the identity key tasks reference verbatim. **Query this, don't re-derive it** — the rules live in the CLI, never
 restated as prose here. This is what `sp:spur-dev`'s feature-check gate loop runs.
 
 ## Status sync - `sync`

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -137,8 +137,8 @@ runner (see [validation-and-extension.md](validation-and-extension.md)).
 Order matters for both guards and conditions: **the first that passes wins.** Put the discriminating
 guard before the unconditional fallback (`always` / no-guard edge). For multi-condition gates (doctor
 + task check, quality gate + attempt cap), prefer a **soft probe** shell that writes PASS|FAIL and
-always exits 0, then branch with ordered status-file guards — see shipped `basic.yaml` /
-`task-pipeline.yaml` (more reliable than `action-ok` alone when more than one condition decides the edge).
+always exits 0, then branch with ordered status-file guards — see shipped
+`task-pipeline.yaml` / `wrapup-pipeline.yaml` (more reliable than `action-ok` alone when more than one condition decides the edge).
 
 ## Template variables
 

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -28,9 +28,9 @@ Authored workflows default to a project-local directory, grouped by purpose:
 ```
 
 A `--file <path>` argument overrides the default. Keep one workflow per file, named for what it does
-(`approval.yaml`, `import-file.yaml`), not for its mode. The canonical example
-(`basic.yaml`) lives here; copy real schema shapes from it rather than from a
-half-remembered snippet.
+(`approval.yaml`, `import-file.yaml`), not for its mode. Copy real schema shapes from a
+retained definition such as `task-pipeline.yaml` rather than from a half-remembered
+snippet.
 
 ## Sub-procedure: mode-selection gate
 

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -95,7 +95,7 @@ and orders capabilities, it does not contain them** (ADR-069).
       between them are one judgment step.
 - [ ] **Soft status-file probe over repeated probing.** Run the expensive check once in an action
       that always exits 0 and writes its verdict to a run-scoped file; branch with ordered cheap
-      guards that read that file. One subprocess instead of one per branch — the `basic.yaml` and
+      guards that read that file. One subprocess instead of one per branch — the
       `task-pipeline.yaml` quality-gate idiom.
 - [ ] **Order guards cheapest-discriminating-first.** The first passing guard wins, so a `test -f`
       ahead of a `spur … --json` parse skips the expensive call on the common path.

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

@@ -1,6 +1,6 @@
 ---
 name: spur-dev
-description: "The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: \"run the pipeline\", \"drive this task\", \"plan a feature end to end\", \"continue the pipeline run\", or operating the full lifecycle."
+description: 'The thin orchestration spine for the planning→execution lifecycle: intake, feature-check/batch-create gates, the execution pipeline (precheck→implement→test→review→verify→record→done), HITL gating. Dispatches competency skills; never inlines them. Triggers: "run the pipeline", "drive this task", "plan a feature end to end", "continue the pipeline run", or operating the full lifecycle.'
 license: Apache-2.0
 metadata:
   author: spur
@@ -36,11 +36,11 @@ metadata:
 # Spur Dev — The Orchestration Spine
 
 `sp:spur-dev` is the **thin orchestration spine** that drives the full planning→execution lifecycle.
-It converts vague intent into shipped work by *orchestrating*, not by doing the work itself: it runs
+It converts vague intent into shipped work by _orchestrating_, not by doing the work itself: it runs
 the gates (feature-check, batch-create) and the execution pipeline with human-in-the-loop control,
 and **dispatches deep competency skills** for each unit of work — it never inlines them. Every write
-to the corpus goes through a CLI verb that validates before writing — the spine knows *how to drive
-the lifecycle*; the competency skills know *how to do each job*; the CLI knows *what is valid*.
+to the corpus goes through a CLI verb that validates before writing — the spine knows _how to drive
+the lifecycle_; the competency skills know _how to do each job_; the CLI knows _what is valid_.
 
 The skill was decomposed **by function** (ADR-028): design, decomposition, implementation, testing,
 and verification each became a standalone competency skill, leaving this spine to orchestrate them.
@@ -51,14 +51,14 @@ status-transition verbs, are the facade's (`sp:spur-cli`), never this skill's.
 
 **The competencies the spine dispatches:**
 
-| Unit of work | Competency skill |
-| -------------- | ------------------ |
-| Design / ADR judgment (shape a task) | `sp:sys-architecture` |
-| Feature/spec → task batch | `sp:spec-decomposition` |
-| Implement to spec | `sp:code-implementation` |
-| Coverage / test extension | `sp:code-testing` |
-| Review (multi-dimensional) | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` |
-| Test-first discipline (composed in) | `sp:test-driven-development` |
+| Unit of work                         | Competency skill                                                        |
+| ------------------------------------ | ----------------------------------------------------------------------- |
+| Design / ADR judgment (shape a task) | `sp:sys-architecture`                                                   |
+| Feature/spec → task batch            | `sp:spec-decomposition`                                                 |
+| Implement to spec                    | `sp:code-implementation`                                                |
+| Coverage / test extension            | `sp:code-testing`                                                       |
+| Review (multi-dimensional)           | `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` |
+| Test-first discipline (composed in)  | `sp:test-driven-development`                                            |
 
 CLI verb usage for any `spur` noun lives in the `sp:spur-cli` facade. This spine owns only the
 lifecycle, the gates, and the section-write contract (`cross-cutting.md`).
@@ -103,26 +103,26 @@ Host-session procedure: **[references/inline-pipeline-driver.md](references/inli
 Each step delegates to a CLI verb and is documented in exactly one reference file. Read the
 reference for the half you're operating; do not duplicate its content here.
 
-| Step | Half | CLI gate | Reference |
-| ------ | ------ | ---------- | ----------- |
-| Intake | planning | — (prompt work) | [planning-workflow.md](references/planning-workflow.md) · [product-planning.md](references/product-planning.md) |
-| Feature create + AC | planning | `spur feature create` | [planning-workflow.md](references/planning-workflow.md) · [ac-style-guide.md](references/ac-style-guide.md) |
-| Feature check gate | planning | `spur feature check` | [planning-workflow.md](references/planning-workflow.md) |
-| Decomposition (dispatch) | planning | `task-batch.schema.json` | `sp:spec-decomposition` competency — the spine dispatches, does not inline |
-| Batch-create gate | planning | `spur task batch-create` | [planning-workflow.md](references/planning-workflow.md) |
-| Design doc | planning | — (prompt work; §4.5/T9) | [planning-workflow.md](references/planning-workflow.md) |
-| Refine | planning | `spur task update --section` | [planning-workflow.md](references/planning-workflow.md) |
-| Batch refine | planning | `sp:dev-refineall` → per-task `refine` | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md) |
-| Task selection | execution | `spur task list` | [execution-workflow.md](references/execution-workflow.md) |
-| Pipeline run | execution | inline YAML driver or `spur workflow run` | [execution-workflow.md](references/execution-workflow.md) · [inline-pipeline-driver.md](references/inline-pipeline-driver.md) |
-| Implement (dispatch) | execution | `sp:code-implementation` | competency skill — the spine dispatches, does not inline |
-| Test (dispatch) | execution | `sp:code-testing` | competency skill — the spine dispatches, does not inline |
-| Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline |
-| Operation catalog | execution | `sp:dev-*` operations | [dev-operations.md](references/dev-operations.md) (spine dispatch table) |
-| Continue | execution | `spur feature update` / `refresh` | [execution-workflow.md](references/execution-workflow.md) |
-| Batch run | execution | `sp:super-planner` + `spur workflow run` | [execution-batch.md](references/execution-batch.md) |
-| Parallel fan-out | execution | `sp:parallel-execution` decision framework | [execution-batch.md](references/execution-batch.md) |
-| All writes (both halves) | — | CLI-gated section editing | [cross-cutting.md](references/cross-cutting.md) · [section-batching.md](references/section-batching.md) (one-writer protocol, F92 0593) |
+| Step                       | Half      | CLI gate                                                                                  | Reference                                                                                                                               |
+| -------------------------- | --------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| Intake                     | planning  | — (prompt work)                                                                           | [planning-workflow.md](references/planning-workflow.md) · [product-planning.md](references/product-planning.md)                         |
+| Feature create + AC        | planning  | `spur feature create`                                                                     | [planning-workflow.md](references/planning-workflow.md) · [ac-style-guide.md](references/ac-style-guide.md)                             |
+| Feature check gate         | planning  | `spur feature check`                                                                      | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Decomposition (dispatch)   | planning  | `task-batch.schema.json`                                                                  | `sp:spec-decomposition` competency — the spine dispatches, does not inline                                                              |
+| Batch-create gate          | planning  | `spur task batch-create`                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Design doc                 | planning  | — (prompt work; §4.5/T9)                                                                  | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Refine                     | planning  | `spur task update --section`                                                              | [planning-workflow.md](references/planning-workflow.md)                                                                                 |
+| Batch refine               | planning  | `sp:dev-refineall` → per-task `refine`                                                    | [dev-operations.md](references/dev-operations.md) § refineall · [planning-workflow.md](references/planning-workflow.md)                 |
+| Task selection             | execution | `spur task list`                                                                          | [execution-workflow.md](references/execution-workflow.md)                                                                               |
+| Pipeline run               | execution | inline YAML driver or `spur workflow run`                                                 | [execution-workflow.md](references/execution-workflow.md) · [inline-pipeline-driver.md](references/inline-pipeline-driver.md)           |
+| Implement (dispatch)       | execution | `sp:code-implementation`                                                                  | competency skill — the spine dispatches, does not inline                                                                                |
+| Test (dispatch)            | execution | `sp:code-testing`                                                                         | competency skill — the spine dispatches, does not inline                                                                                |
+| Review / verify (dispatch) | execution | `sp:dev-review` → `sp:code-verification` + `sp:functional-review` + `sp:code-improvement` | competency skills — the spine dispatches, does not inline                                                                               |
+| Operation catalog          | execution | `sp:dev-*` operations                                                                     | [dev-operations.md](references/dev-operations.md) (spine dispatch table)                                                                |
+| Continue                   | execution | `spur feature update` / `refresh`                                                         | [execution-workflow.md](references/execution-workflow.md)                                                                               |
+| Batch run                  | execution | `sp:super-planner` + `spur workflow run`                                                  | [execution-batch.md](references/execution-batch.md)                                                                                     |
+| Parallel fan-out           | execution | `sp:parallel-execution` decision framework                                                | [execution-batch.md](references/execution-batch.md)                                                                                     |
+| All writes (both halves)   | —         | CLI-gated section editing                                                                 | [cross-cutting.md](references/cross-cutting.md) · [section-batching.md](references/section-batching.md) (one-writer protocol, F92 0593) |
 
 ## When to use
 
@@ -180,7 +180,7 @@ CLI does.
    section.
 3. **Resolve task IDs through the CLI.** Read a known WBS with `spur task show <wbs> --json`; it
    returns metadata, full content, and `filePath` across configured task folders. Use `spur task
-   path <wbs> --json` only when another tool needs the absolute path. Never search `docs/tasks*` or
+path <wbs> --json` only when another tool needs the absolute path. Never search `docs/tasks*` or
    guess `--folder`; reuse the first `show` response throughout the run.
 4. **Check before every write.** Run `spur task check <wbs> --json` to know what sections
    the task needs at its current status. Guessing produces matrix violations.