@gobing-ai/spur 0.3.95 → 0.3.96

package/plugins/sp/scripts/wrapup-steps.ts

@@ -30,9 +30,10 @@
  */
 
 import { spawnSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { getEnvVars } from '../lib/env';
+import { spurCommand } from '../lib/spur-bin';
 
 export interface WrapupStepsEnv {
     __runId?: string;
@@ -64,15 +65,6 @@ function jqText(value: unknown): string {
 /** Canonical four-digit WBS string: whitespace is rejected, not trimmed (0783 R1). */
 export const WBS_PATTERN = /^[0-9]{4}$/;
 
-/** `spurBin` splits on whitespace into a command plus prefix args (so `bun x.ts` works). */
-export function spurCommand(spurBin: string | undefined): { cmd: string; prefix: string[] } {
-    const parts = (spurBin ?? 'spur')
-        .trim()
-        .split(/\s+/)
-        .filter((p) => p.length > 0);
-    return { cmd: parts[0] ?? 'spur', prefix: parts.slice(1) };
-}
-
 function spur(
     env: WrapupStepsEnv,
     args: string[],
@@ -484,34 +476,14 @@ export function runFeatureTransition(env: WrapupStepsEnv, options: WrapupStepsOp
         return { status: 'FAIL', statusFile: relStatusFile, exitCode: 1 };
     }
 
-    // Three branches, first that exists relative to the cwd; current arguments including --spur-bin.
+    // 1004 R5: one direct service sync (stderr streams through, stdout is the JSON payload).
+    // Repeated-BLOCKED suppression (0411) lives in the feature sync service itself (1004 R3),
+    // so the bounded-wrapper resolution branches are gone.
     let syncOutput = '';
     let syncRc = 1;
-    const boundedTs = join('plugins', 'sp', 'scripts', 'feature-sync-bounded.ts');
-    const boundedArgs = [feature, '--spur-bin', env.spurBin ?? 'spur', '--json'];
-    if (existsSync(cwd ? join(cwd, boundedTs) : boundedTs)) {
-        const result = spawnSync('bun', [boundedTs, ...boundedArgs], { cwd, encoding: 'utf8' });
-        syncOutput = result.stdout ?? '';
-        syncRc = result.status ?? 1;
-        if (result.stderr !== null && result.stderr.length > 0) process.stderr.write(result.stderr);
-    } else {
-        const probe = spawnSync('superskill', ['script', 'path', 'sp', 'feature-sync-bounded.mjs'], {
-            cwd,
-            encoding: 'utf8',
-        });
-        const twin = probe.status === 0 ? (probe.stdout ?? '').trim() : '';
-        if (twin.length > 0 && existsSync(twin)) {
-            const result = spawnSync('node', [twin, ...boundedArgs], { cwd, encoding: 'utf8' });
-            syncOutput = result.stdout ?? '';
-            syncRc = result.status ?? 1;
-            if (result.stderr !== null && result.stderr.length > 0) process.stderr.write(result.stderr);
-        } else {
-            // Last branch: stderr streams through (visible), stdout is the JSON payload.
-            const result = spur(env, ['feature', 'sync', feature, '--json'], { cwd, stderr: 'inherit' });
-            syncOutput = result.stdout;
-            syncRc = result.status;
-        }
-    }
+    const sync = spur(env, ['feature', 'sync', feature, '--json'], { cwd, stderr: 'inherit' });
+    syncOutput = sync.stdout;
+    syncRc = sync.status;
     process.stdout.write(`${syncOutput}\n`);
 
     const shown = spur(env, ['feature', 'show', feature, '--json'], { cwd });

package/plugins/sp/skills/code-improvement/SKILL.md

@@ -105,9 +105,9 @@ spur task show <wbs> --json    # for a pipeline run
 # scope = 'src/api/' | 'packages/domain/' | 'plugins/sp/'
 ```
 
-For a pipeline run, derive the diff scope the same way `sp:code-verification` Step 3 does (the
-task's last commit → changed `*.ts/*.tsx/*.js/*.jsx`). For standalone, the `path` argument is the
-scope.
+For a pipeline run, derive the diff scope the same way `sp:code-verification` Step 3 does (the SSOT
+recipe: tagged-commit task diff — defined there, not restated here). For standalone, the `path`
+argument is the scope.
 
 ### Step 2 — Explore (read the map)
 
@@ -188,7 +188,8 @@ When invoked as the `--focus architecture` dimension of `/sp:dev-review`:
 - `blocker`/`major` candidates block the `approve(HITL)` gate alongside any SECUA blockers from
   `sp:code-verification`.
 - The candidate list is returned as a **review fragment**; the review coordinator
-  (`sp:super-reviewer` under `/sp:dev-review`) merges it into the combined `## Review` section —
+  (`sp:super-reviewer` — the invoking session under `/sp:dev-review`) merges it into the combined
+  `## Review` section —
   it is never written by `record`, which backfills `## Review` only when the section is bare
   (fallback-only, F92 0593 R1).
 - This skill does **not** write to the task file directly — the coordinator (or the operator) does.

package/plugins/sp/skills/code-verification/SKILL.md

@@ -36,7 +36,7 @@ It backs two commands:
 | Command | Mode | Input | Output |
 |---------|------|-------|--------|
 | `/sp:dev-verify <wbs>` | **verify** | a task WBS | `.spur/run/<wbs>-verdict.json`; `record` transcribes `## Testing` |
-| `/sp:dev-review <wbs>` | **review** (coordinator) | a task WBS (diff scope) | merged three-dimensional findings → `## Review` |
+| `/sp:dev-review --tasks <wbs>` | **review** (coordinator) | a task WBS (diff scope) | merged three-dimensional findings → `## Review` |
 
 The verify mode is the **completion gate's evidence source**: it emits a machine verdict the
 `task-pipeline.yaml` workflow reads before allowing `record → done`. A `PASS` clears the gate; a
@@ -96,16 +96,39 @@ no-op there; `--force` matters for re-auditing completed tasks.)
 
 ### Step 3 — Establish the change scope
 
-Determine which files the task changed (the evidence surface):
+Determine which files the task changed. This step is the SSOT scope recipe:
+`sp:functional-review` Step 3, `sp:code-improvement` Step 1, and `sp:super-reviewer` "Establish
+scope first" defer here and must not restate it.
+
+WBS mode — the union of files changed by the task's implementation commits, identified by the
+`(<wbs>)` subject tag, excluding the task file itself:
 
 ```bash
-TASK_FILE=$(spur task show <wbs> --json | jq -r .filePath)
-COMMIT=$(git log -1 --format=%H -- "$TASK_FILE")
-git diff --name-only "${COMMIT}~1"..HEAD -- '*.ts' '*.tsx' '*.js' '*.jsx'
-# Fallback when the task file is uncommitted: use the working-tree diff.
+ROOT=$(git rev-parse --show-toplevel)
+TASK_FILE=$(cd "$ROOT" && spur task show <wbs> --json | jq -r .filePath)
+COMMITS=$(git log --format='%H %s' | grep -F "(<wbs>)" | cut -d' ' -f1)
+for c in $COMMITS; do git diff-tree --no-commit-id --name-only -r "$c"; done \
+  | sort -u | grep -vxF "${TASK_FILE#$ROOT/}"
+# Empty scope → working-tree diff.
 git status --porcelain
 ```
 
+- No file-extension filter — `.md`/`.yaml` are first-class harness surfaces. Generated/lock files
+  (`*.generated.mjs`, `bun.lock`) may be excluded by name, stated in the Scope line.
+- Empty scope (no tagged commit, or tagged commits touch only the task file) degrades visibly:
+  state `working tree` and the reason in the Scope line.
+
+### Step 3p — Path scope (review mode only)
+
+When the review target is a path, not a WBS, Step 3 does not apply — derive the scope from the
+path: the tracked files under it, with the file count reported in the Scope line.
+
+```bash
+git ls-files -- <path>
+```
+
+Large scopes are fanned out by the review coordinator, not here.
+
 ### Step 4 — Requirements traceability gate (Phase 8)
 
 For each `R{n}` in `## Requirements`, find implementation evidence in the changed files / tests and
@@ -338,7 +361,8 @@ canonical.
 Under the pipeline, the verifier owns the answer file `.spur/run/<wbs>-verify-answer.txt` (0726
 R3): `Verdict: PARTIAL` first, append one row at a time, replace the verdict line only when all
 rows are certified — interruptions leave lintable partial rows; retries fill only missing IDs.
-Host: `expectFile` → `verify-answer-lint.ts` → verdict + `spur task check` (R9). Vocabularies,
+Host: `spur task verdict --from-answer` lints the answer file, then derives the verdict +
+`spur task check` (R9). Vocabularies,
 rejection classes, and the AC identity rule: `references/verdict-schema.md`. Sections follow the
 Step 10 contract.
 
@@ -481,10 +505,11 @@ re-audit is never misread as a successful `testing -> done` (dev-verify.md `--ne
 ## Mode: review (`/sp:dev-review`)
 
 The source-oriented path: SECUA review of a task's diff without the full traceability verdict. Runs
-Steps 3 + 7 and returns a **review fragment** — no verdict artifact, no section write, no `done`
+Step 3 (WBS target) or Step 3p (path target — a path target never derives scope from Step 3) plus
+Step 7, and returns a **review fragment** — no verdict artifact, no section write, no `done`
 gate (F92 0593 R1); the coordinator (`sp:super-reviewer`) merges fragments into `## Review`.
 
-Flags: `--agent <inline|auto|name>` (execution surface — inline default, with named escalation triggers taking precedence), `--auto` (no confirmations), `--fix <none|blockers-first|all>` (post-review repair), and `--focus <all|security|efficiency|correctness|usability|architecture>` (SECUA dimensions). Apply the [central contract](../spur-dev/references/cross-cutting.md#inline-default-execution-surface) before starting the review.
+Flags: `--agent <inline|auto|name>` (execution surface — inline default, with named escalation triggers taking precedence), `--auto` (no confirmations), and `--focus <all|functional|security|efficiency|correctness|usability|architecture>` (review dimensions — **the single review `--focus` vocabulary is declared here (SSOT)**: `functional` routes to `sp:functional-review`, `architecture` to `sp:code-improvement` + SECUA-A, the SECUA lenses to Step 7; `dev-review.md`, `dev-operations.md` §2 and `flag-glossary.md#flag-focus` link here instead of restating a second list). Apply the [central contract](../spur-dev/references/cross-cutting.md#inline-default-execution-surface) before starting the review.
 
 ---
 

package/plugins/sp/skills/code-verification/references/verdict-schema.md

@@ -108,8 +108,8 @@ For answer files, emit a matching parseable table:
 
 **Authoring contract under the pipeline (0726 R3).** The verifier owns the answer file: write
 `Verdict: PARTIAL` first, append one complete row at a time, and replace the first verdict line only
-after every row is certified. `verify-answer-lint.ts` gates the file before `spur task verdict
---from-answer` and rejects, with row-level diagnostics: missing/duplicate/unknown requirement IDs,
+after every row is certified. `spur task verdict --from-answer` lints the file before deriving the
+verdict and rejects, with row-level diagnostics: missing/duplicate/unknown requirement IDs,
 AC ids that do not resolve to one accepted identity — a task AC checklist label or its declared
 `AC-N`/checklist-token alias, or a linked feature scenario title, in the ac-style-guide forms
 (exact/bare title, `Scenario:` prefix, bracket tags, `AC-N`); paraphrases and ambiguous aliases
@@ -119,7 +119,7 @@ manual-review | llm-judge | n/a`, or a `+` compound), and empty evidence. Interr
 rows that pass the lint and complete only the missing IDs on retry.
 
 **Feature-credited AC ids are narrower than the lint's accepted set (task 0966 finding).** A row keyed
-by a bare checklist ordinal (`AC1`) passes `verify-answer-lint` — it resolves to the task's AC
+by a bare checklist ordinal (`AC1`) passes the `spur task verdict` answer lint — it resolves to the task's AC
 checklist label — but `feature-check.rowMatchesScenario` credits a linked feature scenario only by the
 scenario's normalized title or its `AC-N` ordinal alias. Such a row therefore carries a PASS verdict
 while crediting no scenario, and the feature's `verifying → done` gate denies with

package/plugins/sp/skills/functional-review/SKILL.md

@@ -11,6 +11,7 @@ metadata:
     - pipeline
   modes:
     - verify
+    - review
   verdicts:
     - PASS
     - PARTIAL
@@ -214,8 +215,8 @@ return `verdict = PASS` with "No requirements to verify" (zero-requirements case
 ### Step 3 — Establish the change scope
 
 If `--source-paths` is given, use it. Otherwise derive the diff scope exactly as
-`sp:code-verification` Step 3 does (the task file's last commit → `git diff --name-only` for
-`*.ts`/`*.tsx`/`*.js`/`*.jsx`, fallback to working-tree diff).
+`sp:code-verification` Step 3 does (the SSOT recipe: the `(<wbs>)`-tagged implementation commits'
+changed files, fallback to the working-tree diff — defined there, not restated here).
 
 ### Step 4 — Track A: BDD mapping (if `--bdd-report`)
 
@@ -268,7 +269,8 @@ The priority table leads; the traceability table follows for per-requirement det
 **Fragment-only discipline (F92 0593 R1).** In coordinated mode (dispatched by `/sp:dev-review` /
 `sp:super-reviewer`), do **not** write `## Review` — return the fragment to the coordinator, which
 merges the functional + SECUA + architecture fragments into the combined `## Review` section. Only
-`sp:super-reviewer` (the review coordinator) writes `## Review`; direct component-skill use is
+`sp:super-reviewer` (the invoking session under `/sp:dev-review` acting as review coordinator)
+writes `## Review`; direct component-skill use is
 advisory output. `spur task record` backfills a **bare** `## Review` from the verdict artifact as a
 standalone compatibility fallback only and never overwrites authored Review (F92 0593 R1).
 
@@ -291,7 +293,8 @@ Include the per-requirement traceability table in the report:
 ```
 
 **Under the pipeline**, `sp:functional-review` is a component of `/sp:dev-review`: it returns its
-fragment to the coordinator (`sp:super-reviewer`), which writes the combined `## Review`. The
+fragment to the coordinator (`sp:super-reviewer` — the invoking session under `/sp:dev-review`),
+which writes the combined `## Review`. The
 `record` step transcribes only `## Testing` from the verdict artifact and backfills `## Review`
 only when the section is bare (`sectionIsBare` guard, `task-service.ts`); it never overwrites the
 coordinator's authored Review. Keep the priority-table lead stable in the fragment so the L3 gate

package/plugins/sp/skills/functional-review/references/verdict-schema.md

@@ -27,7 +27,7 @@ interface FunctionalVerdict {
     bddReportPath: string | null;
     /**
      * Explicit source scope (if --source-paths given) or derived diff scope
-     * (the changed *.ts/*.tsx/*.js/*.jsx files for the task's last commit).
+     * (tagged-commit recipe; SSOT = code-verification SKILL Step 3/3p).
      */
     sourcePaths: string[];
 }

package/plugins/sp/skills/history-anatomy/references/modes.md

@@ -3,7 +3,8 @@
 The skill resolves exactly two modes. Everything else fails loud. This matrix is the enforcement
 surface the workflow (0660) and the skill share; keep the vocabulary frozen. Execution note
 (0920): argument validation runs deterministically in the `history-anatomy-cache` helper `paths`
-command before the workflow starts; the model hop no longer performs it.
+command (logic core: `packages/app/src/services/history-anatomy.ts`, task 1005) before the
+workflow starts; the model hop no longer performs it.
 
 ## Mode vocabulary (frozen)
 

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

@@ -78,7 +78,7 @@ survivors would make its primary case unreachable. Offer the rank-1 ranked candi
 **Why this is not a Principle #5 taste auto-click.** The ranking already produced the recommendation;
 `--auto` only skips the *proceed-with-offer* pause. Overriding the ranking (picking a non-offered
 candidate) still requires the interactive confirm path. Architecture / design-approval taste gates
-inside dispatched children remain governed by their own contracts (`--approve-taste` where applicable).
+inside dispatched children remain governed by their own contracts (`--auto` where applicable).
 
 ### What `--task` does not change
 

package/plugins/sp/skills/next-router/references/routing-table.md

@@ -131,7 +131,7 @@ call; no git dirtiness as a route (optional advisory print only).
 | C2 and C3 both true | lint vs tests both red | (1) fixall (2) unit (3) abort |
 | Feature B3 pick ambiguous because two `todo` same rank — **should not happen** after WBS sort | — | N/A — WBS tie-break is total |
 | Task `todo` but also feature-level AC invalid when invoked via feature id | feature health vs task progress | (1) fix feature AC (2) proceed with task A3 |
-| `testing` with open P1 in Review section | verify vs review-fix | (1) `/sp:dev-review <wbs> --fix blockers-first` (2) verify anyway |
+| `testing` with open P1 in Review section | verify vs review-fix | (1) `/sp:dev-review --tasks <wbs> --triage` (2) verify anyway |
 | `wip` with both checkpoint and dirty Solution L3 | resume vs re-implement | (1) `--continue` (2) implement `--next` |
 
 When HITL STOP fires: print decision-brief (question, stakes, recommended option, alternatives).

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

@@ -46,7 +46,7 @@ Pick the noun, read its reference. Each Tier A and Tier B reference owns that no
 | **Tier A** | **builder** | Release plumbing: bump a package (or the `workspace:`-pinned set) with `bump-ver`, delete release tags with `drop-tags`, commit + tag + optional push | [references/builder.md](references/builder.md) |
 | **Tier B** | **agent** | Coding-agent execution surface: run prompts via detected/named agents, list agent specs, start/stop supervised processes, readiness check | [references/agent.md](references/agent.md) |
 | **Tier B** | **message** | Durable inter-agent messaging: send, inbox, reply, watch | [references/message.md](references/message.md) |
-| **Tier B** | **self** | Self-management verbs: scaffold (`init`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
+| **Tier B** | **self** | Self-management verbs: scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), status overview (`status`); `self init` runs post-scaffold validation probes & layout classification | [references/self.md](references/self.md) |
 | **Tier B** | **history** | Import agent histories, aggregate forensic artifacts, render reports, and run the checkpoint-resumed daily pipeline | [references/history.md](references/history.md) |
 | **Tier B** | **projects** | Manage the local multi-project registry and start/stop project servers | [references/projects.md](references/projects.md) |
 | **Tier C** | **help** | Commander-generated help command; not a Spur noun | Generated `--help` |
@@ -141,8 +141,8 @@ and spreading it; full contract in `docs/04_DESIGN.md` §1.0.1.
   [dispatch-surface rule](../parallel-execution/references/dispatch-surface.md).
 - **[references/message.md](references/message.md)** - durable inter-agent messaging (`send`,
   `inbox`, `reply`, `watch`).
-- **[references/self.md](references/self.md)** - `spur self init|migrate|serve|status` CLI verbs
-  (the four legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
+- **[references/self.md](references/self.md)** - `spur self init|maintain|migrate|serve|status` CLI verbs
+  (the five legacy top-level nouns remain hidden aliases). `self init` runs post-scaffold init
   validation (Phase 1.5/1.6 probes).
 - **[references/history.md](references/history.md)** - history import, forensic artifact analysis,
   pure report rendering, and the daily pipeline.

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

@@ -23,12 +23,12 @@ 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 + 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` |
+| `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur self serve`) | `--specs` `--server <url>` `--json` |
+| `status` | Agent specs with live process status and member session (requires `spur self 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` |
+| `start <spec-id>` | Start a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
+| `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 
 `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`
@@ -85,7 +85,7 @@ justify it - but ensure the run executes in a context that can write the target
 
 ## `loop` - supervisor-internal self-draining wrapper (hidden)
 
-`spur agent loop --spec <id> [--poll <ms>]` is spawned by the `spur serve` supervisor for each
+`spur agent loop --spec <id> [--poll <ms>]` is spawned by the `spur self serve` supervisor for each
 materialized agent spec; it is hidden from `--help` and not an operator verb (use `spur agent start`).
 It waits for a wake on the `system_events` ledger — a human request (`message.sent`), a strategy
 change (`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
@@ -145,7 +145,7 @@ lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the
 supervisor**: each row carries a trailing status column
 (`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
+member has no recorded session. When `spur self 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.
 
@@ -200,9 +200,9 @@ spur agent start worker-1
 spur agent start worker-1 --json
 ```
 
-Posts to the `spur serve` supervisor API
+Posts to the `spur self serve` supervisor API
 (`POST /api/agents/:id/start`) and prints `started <id> (pid=<n>, status=<s>)`. Requires a
-reachable `spur serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
+reachable `spur self serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
 when the server is unreachable or the start fails.
 
 ## `stop` - stop a supervised process
@@ -250,7 +250,7 @@ unconfirmed or failed. For `skipped`/`pending` the printed target is intent only
 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).
+`spur self serve` never invokes the producer (asserted by a test, design R4).
 
 ### Flags
 
@@ -285,7 +285,7 @@ one never re-sends settled work; only never-started deliveries release and redel
 - **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the
   **[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
   reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
-- **Not the fleet orchestrator.** The `spur serve` supervisor drives the lifecycle: `spur agent
+- **Not the fleet orchestrator.** The `spur self serve` supervisor drives the lifecycle: `spur agent
   start` / `stop` manage supervised processes and `agent list --specs` reports live state.
 
 ## See also

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

@@ -181,11 +181,16 @@ planning reference, then apply accepted deterministic changes through `spur feat
 ## The gate — `check --json`
 
 ```bash
-spur feature check H2 --json        # one feature
-spur feature check --json           # whole tree
-spur feature check --strict --json  # warnings → failures
+spur feature check H2 --json                       # one feature
+spur feature check --json                          # whole tree
+spur feature check --strict --json                 # warnings → failures
+spur feature check H2 --inventory <eval-report.md> # also cross-check AC ↔ requirement inventory
 ```
 
+With `--inventory <report>`, the `inventory-coverage` finding (1004 R1, unsuppressible error layer)
+fails the check when a `## Requirement inventory` item has no covering scenario (`# covers: I<n>`)
+and is not `[deferred: ...]`; a missing/empty inventory section is itself an error.
+
 The 4-layer validator (frontmatter, AC syntax, children-limit/structure, L4 traceability) emits its
 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
@@ -207,15 +212,21 @@ see the proposed status hop.
 spur feature sync H2 --json                    # one feature
 spur feature sync H2 --dry-run --json          # propose only, no write
 spur feature sync --all --json                 # every feature with linked tasks
-spur feature sync H2 --force                   # apply a reopen proposal without confirmation
+spur feature sync H2 --force                   # re-derive live: bypass replay + apply a reopen without confirmation
 spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks folder
 ```
 
 - **`[id]`** syncs one feature; **`--all`** syncs every feature with linked tasks. One of the two is
   required - exit `2` if neither is given.
 - **`--dry-run`** reports proposed transitions without applying. **`--force`** applies a *reopen*
-  proposal (status moving backward) without interactive confirmation.
-- **`--json`** single-feature emits `{ proposal, applied, appliedHops[] }`; `--all` emits
+  proposal (status moving backward) without interactive confirmation **and** bypasses blocked-sync
+  replay (below).
+- **Blocked-sync suppression (1004 R3):** a BLOCKED outcome is persisted at
+  `.spur/run/feature-sync-blocked-<id>.json` with an input fingerprint (feature content, linked
+  task statuses, verdict mtimes); an identical next call replays the prior result
+  (`suppressed: true`) instead of re-deriving. A changed input, `--force`, or a non-blocked
+  outcome re-derives/clears. Dry-run never reads or writes the state.
+- **`--json`** single-feature emits `{ proposal, applied, appliedHops[], suppressed? }`; `--all` emits
   `{ totalFeatures, evaluated, updatedCount, results[] }` where each result is the single-feature
   shape. `proposal` is
   `{ featureId, from, to, reason, requiresConfirm?, gateBlocked?, gateFindings?, hops? }`.

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

@@ -1,11 +1,11 @@
 ---
 name: init
-description: "spur-cli noun reference for `spur init` and `spur status`: CLI verbs (init scaffold with --name/--force/--minimal, status with --json) plus post-scaffold init validation for /sp:spur-init - Phase 1.5 functional-validation probes and Phase 1.6 rule-glob adaptation."
+description: "spur-cli noun reference for `spur self init` and `spur self status`: CLI verbs (init scaffold with --name/--force/--minimal, status with --json) plus post-scaffold init validation for /sp:spur-init - Phase 1.5 functional-validation probes and Phase 1.6 rule-glob adaptation."
 see_also:
   - spur-cli
 ---
 
-# spur init / spur status - CLI verbs and post-scaffold validation
+# spur self init / spur self status - CLI verbs and post-scaffold validation
 
 ## CLI verbs
 
@@ -14,14 +14,14 @@ see_also:
 | `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--json` |
 | `status [path]` | Show project and git status for a Spur project | `--json` |
 
-### `spur init` - scaffold a Spur project
+### `spur self init` - scaffold a Spur project
 
 ```bash
-spur init                            # interactive: prompt for project name
-spur init --name my-project          # non-interactive
-spur init --name my-project --force  # overwrite existing .spur/ files
-spur init --minimal                  # skip optional scaffolding (rules, workflows)
-spur init --json                     # machine-readable
+spur self init                            # interactive: prompt for project name
+spur self init --name my-project          # non-interactive
+spur self init --name my-project --force  # overwrite existing .spur/ files
+spur self init --minimal                  # skip optional scaffolding (rules, workflows)
+spur self init --json                     # machine-readable
 ```
 
 Materializes the `.spur/` directory tree with config, docs, rules, and workflow templates. The
@@ -34,14 +34,15 @@ post-scaffold validation probes (Phase 1.5 / 1.6, below) run immediately after t
 | `--name <name>` | Project name (skips interactive prompt). |
 | `--force` | Overwrite existing `.spur/` files. Without it, existing files are preserved. |
 | `--minimal` | Skip optional scaffolding (rules presets, workflow templates). Core config + docs only. |
+| `--adopt-global-config` | Also rewrite `~/.config/spur/config.yaml` from the shipped global default (backed up first). Opt-in only. |
 | `--json` | Output machine-readable JSON instead of interactive summary. |
 
-### `spur status [path]` - project and git status
+### `spur self status [path]` - project and git status
 
 ```bash
-spur status                          # current directory
-spur status /path/to/project         # specific project
-spur status --json                   # machine-readable
+spur self status                          # current directory
+spur self status /path/to/project         # specific project
+spur self status --json                   # machine-readable
 ```
 
 Reports the project's Spur configuration state (init status, feature/task counts, rule preset
@@ -50,11 +51,11 @@ directory.
 
 ## Post-scaffold validation
 
-Two probes sit between the deterministic scaffold (`spur init`) and the non-deterministic doc
+Two probes sit between the deterministic scaffold (`spur self init`) and the non-deterministic doc
 customization: Phase 1.5 (functional validation) confirms the fresh tree is immediately functional;
 Phase 1.6 (rule glob adaptation) rewrites layout-dependent rule globs so `recommended-pre-check`
 runs clean on this project's layout. The executing agent owns content *adaptation* only — `spur
-init` owns *file materialization* (`04_DESIGN.md` §1.1 "Init ownership contract").
+self init` owns *file materialization* (`04_DESIGN.md` §1.1 "Init ownership contract").
 
 ### Phase 1.5 — Functional validation probe
 
@@ -62,8 +63,8 @@ Before any customization, confirm the fresh scaffold is immediately functional.
 fails, STOP and report the gap rather than papering over it with customization:
 
 ```
-spur status
-spur task create "__probe__" --template standard   # confirms task template + matrix resolve
+spur self status
+spur task create "__probe__" --template standard --skip-ready   # no model dispatch; confirms task template + matrix resolve
 spur workflow validate task-pipeline.yaml
 ```
 

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

@@ -17,7 +17,7 @@ top-level forms are omitted from `spur --help`, leaving `self` as the visible su
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
-| `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--json` |
+| `init` | Scaffold a new Spur project in the current directory | `--name <name>` `--force` `--minimal` `--adopt-global-config` `--json` |
 | `maintain` | Run database maintenance: PRAGMA optimize, WAL truncation, optional VACUUM | `--vacuum` `--json` |
 | `migrate` | Apply CLI-owned schema migrations | `--json` |
 | `serve` | Start the Spur web server (local fallback) | `--port <n>` `--host <addr>` `--no-open` `--cwd <path>` `--json` |
@@ -40,7 +40,8 @@ spur self init --json                 # machine-readable
 
 Materializes the `.spur/` directory tree with config, docs, rules, and workflow templates. Flags:
 `--name <name>` (default: current directory name), `--force` (recreate existing files), `--minimal`
-(skip optional scaffolding), `--json` (machine-readable output). Post-scaffold validation probes
+(skip optional scaffolding), `--adopt-global-config` (also rewrite `~/.config/spur/config.yaml` from
+the shipped global default, backed up first), `--json` (machine-readable output). Post-scaffold validation probes
 (Phase 1.5 / 1.6) run immediately after this verb completes — see **[init.md](init.md)** for the
 probe protocol and rule-glob adaptation procedure.
 

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

@@ -1,13 +1,13 @@
 ---
 name: spur-cli-serve
-description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the supervisor API. Single verb, five flags."
+description: "spur-cli noun reference: operate `spur self serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the supervisor API. Single verb, five flags."
 see_also:
   - spur-cli
 ---
 
-# spur serve - local web server
+# spur self serve - local web server
 
-`spur serve` starts the **Spur web server** - a local Hono / Cloudflare-Worker server that serves
+`spur self serve` starts the **Spur web server** - a local Hono / Cloudflare-Worker server that serves
 the web Task Kanban and exposes the supervisor API (`/api/processes/*` + `/api/agents/*`). It is the local fallback
 when no remote server is configured.
 
@@ -22,10 +22,10 @@ when no remote server is configured.
 ## `serve` - start the web server
 
 ```bash
-spur serve                          # default: localhost:3000, opens browser
-spur serve --port 8080 --host 0.0.0.0
-spur serve --no-open                # skip browser
-spur serve --json                   # dry probe: print { port, url, pid, running } and exit
+spur self serve                          # default: localhost:3000, opens browser
+spur self serve --port 8080 --host 0.0.0.0
+spur self serve --no-open                # skip browser
+spur self serve --json                   # dry probe: print { port, url, pid, running } and exit
 ```
 
 Starts the server with the Hono app backed by the local SQLite database. The web Task Kanban and
@@ -46,14 +46,14 @@ the supervisor API become available at `http://<host>:<port>`.
 
 ## What this skill is NOT
 
-- **Not the agent supervisor.** `spur serve` hosts the supervisor API; `spur agent start` / `stop` /
+- **Not the agent supervisor.** `spur self serve` hosts the supervisor API; `spur agent start` / `stop` /
   `agent list --specs` are the verbs that drive and inspect it (0848). See
   **[agent.md](agent.md)**.
 - **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
-  Worker build (`apps/server/`), not `spur serve`.
+  Worker build (`apps/server/`), not `spur self serve`.
 
 ## See also
 
-- **`spur agent` (see [agent.md](agent.md))** - `start`/`stop`/`list --specs` require `spur serve`
+- **`spur agent` (see [agent.md](agent.md))** - `start`/`stop`/`list --specs` require `spur self serve`
   for the supervisor API.
 - **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.

package/plugins/sp/skills/spur-cli/references/tasks/verbs.md

@@ -24,8 +24,16 @@ blocking retry).
 | `--feature <id>` | Records `feature_id` in frontmatter; derives `Background` from the feature's `Goal` (L4 edge). |
 | `--parent <wbs>` | Groups under a parent WBS for sub-task decomposition. |
 | `--template <variant>` | Selects the section-matrix variant for the new file. |
+| `--skip-ready` | Keep the capture as-is: no ready preparation, no model dispatch. |
+| `--agent <selector>` | Agent used for ready preparation (default: the configured agent). Exit `2` when combined with `--skip-ready`. |
 | `--folder <path>` | Target a non-default tasks folder. |
-| `--json` | Emit `{ ref: { id, filePath } }`. |
+| `--json` | Emit `{ ref: { id, filePath }, wbs, filePath, readiness: { status, depth } }`. |
+
+**Ready by default (ADR-109):** after the capture is saved, `create` prepares the same WBS in place —
+model refine → deterministic post-check (`task check --as todo`) → promotion to `todo`.
+`readiness.status` is `ready`, `skipped` (`--skip-ready`), or `failed`. A failed preparation exits `1`
+with error code `preparation-failed` (`failedStage`, `recoveryCommand`, `findings`); the task file and
+its WBS are kept. `batch-create` takes the same two flags.
 
 (See also the full verb map in [tasks.md](../tasks.md).)
 
@@ -67,6 +75,10 @@ frontmatter scalar.
   wholesale. No inline-body flag. Section names: `Background`, `Requirements`, `Acceptance Criteria`, `Q&A`, `Design`, `Plan`, `Solution`, `Testing`, `Review`, `References`, `History`, `Notes`.
 - **Frontmatter** (`--feature <id>`, `--priority <p>`): sets the scalar frontmatter field on an
   existing task — the only post-create path, allow-listed to `feature_id` / `parent_wbs` / `priority`.
+- **Estimate** (`--estimate-hours <n>`): sets the `estimate_hours` frontmatter field (positive number) —
+  the decomposition size estimate the inline pipeline driver reads.
+- **`--provenance-bypass`** (pair with `--force-done` and `--reason`): records an audited
+  provenance-bypass link when no pipeline run exists. Replaces the `SPUR_PROVENANCE_OVERRIDE` env var.
 - **AC controls** (`--ac-altitude <graduating|task-local>`, `--ac-numbering task-local`) — independent
   of each other (task 0818 R5). `--ac-altitude task-local` skips the **DD-09 feature-AC subset** rule
   because the task's scenarios are intentionally not the feature's ship criteria; `--ac-numbering
@@ -339,8 +351,11 @@ column to distinguish AC rows from requirement rows:
 `AC-<i>` (which credits the scenario) and the task checkbox id `AC<i>` (which the box flip needs).
 Key the row **`AC<n> — <scenario title>`**, omitting the scenario's own `R<n>` label — then one row
 does both: `normalizeTitle` strips the `AC<n>` prefix so the row still matches the scenario title,
-and `prefixId` normalizes `AC<n>` so the box flips. A bare `AC<n>` credits no scenario; a bare
-`AC-<i>` flips no box; a title carrying the scenario's `R<n>` label matches neither.
+and `prefixId` normalizes `AC<n>` so the box flips. A bare `AC-<i>` also does both: `record`
+resolves it through the feature's scenario order to the AC line aliasing scenario *i*
+(`AC<k> — [R<n> — ]<scenario title>`) and flips that box — never the same-numbered `AC<i>`; with no
+aliasing line it flips nothing. A bare `AC<n>` credits no scenario; a title carrying the scenario's
+`R<n>` label matches neither.
 
 **Evidence rule (behavior-bearing AC):** an AC row with `status: MET` on a behavior-bearing id
 (no `[advisory]`/`[non-core]`/`[non-behavior]`/`[docs-only]` marker) MUST carry `test` or
@@ -410,9 +425,9 @@ unallocated.
 ## Command surface (quick)
 
 ```
-spur task create   <title> [--feature <id>] [--parent <wbs>] [--template <v>] [--dedupe-within <seconds>] [--allow-duplicate-name] [--folder] [--json]
+spur task create   <title> [--feature <id>] [--parent <wbs>] [--template <v>] [--dedupe-within <seconds>] [--allow-duplicate-name] [--skip-ready | --agent <selector>] [--folder] [--json]
 spur task show     <wbs> [--folder] [--json]
-spur task update   <wbs> [status] [--section <n> --from-file <p>] [--feature <id>] [--priority <p>] [--no-lifecycle] [--folder] [--json]
+spur task update   <wbs> [status] [--section <n> --from-file <p>] [--feature <id>] [--priority <p>] [--ac-numbering task-local] [--ac-altitude <a>] [--estimate-hours <n>] [--assignee <spec-id>] [--no-lifecycle] [--force-done --reason <text> [--provenance-bypass] [--verdict-dir <path>]] [--folder] [--json]
 spur task deps     <wbs> <set|add|remove|clear> [values...] [--folder] [--json]
 spur task sections <wbs> <init|add|list> [name] [--folder] [--json]
 spur task list     [--status <s>] [--phase <p>] [--parent <wbs>] [--feature <id>] [--folder] [--json]
@@ -420,7 +435,7 @@ spur task refresh  [--folder] [--json]
 spur task migrate  [--dry-run] [--folder] [--json]
 spur task migrate-anchors [--dry-run] [--json]
 spur task refresh-roster <wbs> [--folder] [--json]
-spur task batch-create --file <path> [--folder] [--json]
+spur task batch-create --file <path> [--skip-ready | --agent <selector>] [--folder] [--json]
 spur task record   <wbs> [--verdict-file <p>] [--solution-from-diff] [--transition <s>] [--folder] [--json]
 spur task verdict  <wbs> [--from-answer <p>] [--folder] [--json]
 spur task verifyall-aggregate [--from-file <path>] [--json]