@gobing-ai/spur 0.4.21 → 0.4.23

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.4.21",
+            "version": "0.4.23",
             "source": "./plugins/sp"
         }
     ]

package/config/pipeline-budgets.json

@@ -32,7 +32,7 @@
             "modelQueries": 3,
             "wallClockMs": null,
             "tokenCostUsd": null,
-            "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0. 0920 recount 2026-09-23: 4 -> 3 — the resolve-scope model hop was removed; scope/window validation is deterministic in the `spur history anatomy paths` op (history-anatomy-cache before script-absorption PR-6).",
+            "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0. 0920 recount 2026-09-23: 4 -> 3 — the resolve-scope model hop was removed; scope/window validation is deterministic in the `spur history anatomy-paths` op (history-anatomy-cache before script-absorption PR-6).",
             "decision": null
         }
     }

package/config/rules/boundary/config-loading-ownership.yaml

@@ -67,7 +67,7 @@ rules:
     exclude:
       - "packages/config/src/**"
       - "apps/cli/src/index.ts"
-      - "apps/cli/src/workflow-transport.ts" # boot-free composition root of `spur workflow commit-guard|persist-*` (PR-4)
+      - "apps/cli/src/workflow-transport.ts" # boot-free composition root of `spur workflow commit-guard-*|persist-*` (PR-4)
       - "apps/server/src/serve.ts"
       - "apps/server/src/context.ts"
       - "**/tests/**"

package/config/rules/strict/runtime-boundaries.yaml

@@ -37,7 +37,7 @@ rules:
             - "apps/desktop/src/server-process.ts"
 
             # Low-level system primitives:
-            # `spur builder pr` spine (script-absorption PR-7, moved from plugins/sp/scripts/pr-reviewing.ts):
+            # `spur builder pr-*` spine (script-absorption PR-7, moved from plugins/sp/scripts/pr-reviewing.ts):
             # every git/gh call goes through ONE synchronous, test-injectable CommandRunner seam
             # (`setCommandRunner`); the spine is synchronous end to end (wait polls with a sync sleep).
             # The ts-runtime sync executors cannot stand in: NodeSyncProcessExecutor maps a spawn
@@ -101,7 +101,7 @@ rules:
             - "packages/app/src/services/history-anatomy.ts" # deterministic history-anatomy cache core (task 1005 R2): fsync'd tmp+rename atomic publish, readdir digest scans and sync report reads must stay byte-stable; bundled standalone for the bare-node plugin twin (mirrors agent-usage-producer.ts / history-service.ts exemptions)
             - "packages/app/src/observability/workflow-run-log-sink.ts" # sync FD append for mid-run tail-able all-in-one run log (task 0426 / feature D2); append() is sync from the observability bus
             - "packages/app/src/observability/agent-run-log.ts" # same primitive as the sink above for the per-run agent stream (task 1076 R1, ADR-132); append() is sync from the agent service's own onOutput hook, and the byte cap needs the FD position it tracks
-            # Workflow transports (script-absorption PR-4, `spur workflow commit-guard`): moved
+            # Workflow transports (script-absorption PR-4, `spur workflow commit-guard-*`): moved
             # verbatim from the plugin scripts; synchronous probes and
             # atomic tmp+rename snapshot writes inside one short-lived CLI process.
             - "packages/app/src/workflow/commit-guard.ts" # .spur/run/<run>-tree-start.json atomic snapshot + target conflict-marker reads
@@ -121,7 +121,7 @@ rules:
             - "packages/app/src/services/residual-scan-run.ts"
             - "packages/app/src/workflow/task-diffstat.ts"
             - "packages/app/src/workflow/feature-verification-run.ts" # the pass opens the run's single merged log fd (`openSync(path,'a')`) and mkdirs the run dir beside the receipt writer, exactly as the plugin entry did before the move; the fd cannot be expressed through the FileSystem seam (task 1176 R2; same class as the quality-gate exemption above)
-            - "packages/app/src/services/pr-review/index.ts" # `spur builder pr` (PR-7): sync --status-file verdict writes and the AGENTS.md review-rules probe inside the synchronous spine (same exemption as its process seam above)
+            - "packages/app/src/services/pr-review/index.ts" # `spur builder pr-*` (PR-7): sync --status-file verdict writes and the AGENTS.md review-rules probe inside the synchronous spine (same exemption as its process seam above)
             - "packages/app/src/services/run-storage.ts" # durable-evidence migration core (task 1025 R4): atomic tmp+rename byte copies with digest reread and atomic manifest publish must stay byte-stable (mirrors agent-usage-producer.ts / project-registry.ts exemptions)
             - "packages/app/src/services/durable-plane-ignore.ts" # .git/info/exclude append moved verbatim out of run-storage.ts to break an import cycle (same exemption)
 

package/config/rules/surface/check-cli-surface.yaml

@@ -62,7 +62,7 @@ rules:
       - "apps/cli/src/commands/task/wrapup.ts"
       - "apps/cli/src/commands/feature/handoff.ts"
       - "apps/cli/src/commands/feature/verify.ts"
-      # commit-guard declares no --json: its {staged, foreign} / {foreign} lines are rendered by
+      # commit-guard-* declare no --json: its {staged, foreign} / {foreign} lines are rendered by
       # @gobing-ai/spur-app/commit-guard (byte-identical to the retired script, PR-4 golden).
       - "apps/cli/src/commands/workflow/commit-guard.ts"
       # WT-4 worktree-landing transports (D65 1242, flat since the inline group was deleted): they

package/config/workflow-candidates.json

@@ -39,7 +39,7 @@
             "canonical": "wrapup-pipeline",
             "deadline": "2026-11-24",
             "createdAt": "2026-09-25",
-            "rationale": "0944 (feature D64): a deterministic probe (`spur task wrapup drift-probe`, packages/app/src/workflow/wrapup/drift-probe.ts since script-absorption PR-5) runs only when the caller leaves wrapup mode empty and projects mode=fast when no changed path matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md ownership table) and every task's Solution change map parsed — clean wraps then skip doc-sync via the existing fast edge (fast:drift-probe-clean), any doubt stays on the safety path. Projected basis: doc-sync costs exactly 1 agent.run per wrapup (wrapup-pipeline declares one model query; 0938 baseline docs/reports/2026-09-workflow-cost-baseline.json has 0 recorded wrapup runs — agentRunCountMedian null — so the 1 is structural, never a measured median). Measurement gap honestly named: skipping doc-sync also skips learnings capture (0607 R2 merge), so clean wraps lose per-task learnings rows; measured post-promotion by comparing .spur/memory/wrapup-routes.log fast:drift-probe-clean counts against captured <runId>-wrapup-learnings.md files. For 0946 (measurement-only confirmation): the 0938 snapshot carries per-state rows in states[] but history-anatomy has zero of them (0 recorded runs — only task-pipeline/record exists), and cache hit/miss disposition lives in the history-anatomy provenance stamp (0659/0660, `spur history anatomy`, formerly history-anatomy-cache.ts), not in real-run-cost.ts; terminalReasonMix exists per workflow but history-anatomy's is empty. Measured-benefit status: projected from structure + 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
+            "rationale": "0944 (feature D64): a deterministic probe (`spur task wrapup drift-probe`, packages/app/src/workflow/wrapup/drift-probe.ts since script-absorption PR-5) runs only when the caller leaves wrapup mode empty and projects mode=fast when no changed path matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md ownership table) and every task's Solution change map parsed — clean wraps then skip doc-sync via the existing fast edge (fast:drift-probe-clean), any doubt stays on the safety path. Projected basis: doc-sync costs exactly 1 agent.run per wrapup (wrapup-pipeline declares one model query; 0938 baseline docs/reports/2026-09-workflow-cost-baseline.json has 0 recorded wrapup runs — agentRunCountMedian null — so the 1 is structural, never a measured median). Measurement gap honestly named: skipping doc-sync also skips learnings capture (0607 R2 merge), so clean wraps lose per-task learnings rows; measured post-promotion by comparing .spur/memory/wrapup-routes.log fast:drift-probe-clean counts against captured <runId>-wrapup-learnings.md files. For 0946 (measurement-only confirmation): the 0938 snapshot carries per-state rows in states[] but history-anatomy has zero of them (0 recorded runs — only task-pipeline/record exists), and cache hit/miss disposition lives in the history-anatomy provenance stamp (0659/0660, `spur history anatomy-*`, formerly history-anatomy-cache.ts), not in real-run-cost.ts; terminalReasonMix exists per workflow but history-anatomy's is empty. Measured-benefit status: projected from structure + 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
             "measurement": {
                 "workflow": "wrapup-pipeline"
             },

package/config/workflows/history-anatomy.yaml

@@ -4,7 +4,7 @@
 # Orchestration is configuration (ADR-022): a state machine over the existing dual-workflow
 # engine. The YAML owns ONLY the cache branch, deterministic stage ordering, executor dispatch,
 # bounded correction, and atomic publication sequencing. The deterministic cache/digest/
-# structure/publish work is `spur history anatomy <op>` (0659's helper, absorbed by script-absorption PR-6); the judgment (mode validity,
+# structure/publish work is `spur history anatomy-<op>` (0659's helper, absorbed by script-absorption PR-6); the judgment (mode validity,
 # what counts as evidence, the report contract, enrich/validate rubrics) is 0658's skill. Per
 # ADR-069 R1, cache-decide / digest / structure-check / publish must NOT be inline shell — every
 # shell action here is glue length (a single helper invocation), because each of those programs
@@ -108,11 +108,11 @@ states:
     onEnter:
       - kind: shell
         options:
-          # Path arithmetic lives in `spur history anatomy paths` (ADR-069 R1; script-absorption
+          # Path arithmetic lives in `spur history anatomy-paths` (ADR-069 R1; script-absorption
           # PR-6 — HA_HELPER is the running spur, HA_SKILL the resolved skill dir). Avoid
           # `${...}` here — that syntax collides with the engine's own template interpolation.
           command: >-
-            $spurBin history anatomy paths --report-dir "$reportDir" --date "$date"
+            $spurBin history anatomy-paths --report-dir "$reportDir" --date "$date"
             --output "$output" --mode "$mode" --since "$since" --until "$until"
             --focus "$focus" --recompute "$recompute" --run-id "$__runId"
             --out .spur/run/$__runId-paths.txt
@@ -146,7 +146,7 @@ states:
         options:
           command: >-
             . .spur/run/$__runId-paths.txt;
-            $spurBin history anatomy probe --artifact .spur/run/$__runId-history-anatomy-current.json
+            $spurBin history anatomy-probe --artifact .spur/run/$__runId-history-anatomy-current.json
             --baseline .spur/run/$__runId-history-anatomy-baseline.json --target "$HA_TARGET"
             --mode "$mode" --date "$HA_DATE" --recompute "$recompute" --executor "$agent"
             --skill-dir "$HA_SKILL" --contract "$HA_SKILL/references/report-contract.md"
@@ -187,7 +187,7 @@ states:
       - kind: shell
         options:
           command: >-
-            $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-enrich.txt --expect .spur/run/$__runId-candidate.md
+            $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-enrich.txt --expect .spur/run/$__runId-candidate.md
 
   - id: structure-gate
     description: >
@@ -198,7 +198,7 @@ states:
       - kind: shell
         options:
           command: >-
-            $spurBin history anatomy check \
+            $spurBin history anatomy-check \
               .spur/run/$__runId-candidate.md > .spur/run/$__runId-structure-gate.txt 2>&1 || true
 
   - id: validate
@@ -264,7 +264,7 @@ states:
       - kind: shell
         options:
           command: >-
-            $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-validate.txt --expect .spur/run/$__runId-validation.txt
+            $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-validate.txt --expect .spur/run/$__runId-validation.txt
 
   - id: correct
     description: >
@@ -301,7 +301,7 @@ states:
       - kind: shell
         options:
           command: >-
-            $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-correct.txt --expect .spur/run/$__runId-candidate.md
+            $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-correct.txt --expect .spur/run/$__runId-candidate.md
 
   - id: refresh-provenance
     description: >
@@ -314,7 +314,7 @@ states:
         options:
           command: >-
             . .spur/run/$__runId-paths.txt;
-            $spurBin history anatomy refresh --report "$HA_TARGET"
+            $spurBin history anatomy-refresh --report "$HA_TARGET"
             --out .spur/run/$__runId-publishable.md --disposition hit
 
   - id: stamp
@@ -328,7 +328,7 @@ states:
         options:
           command: >-
             . .spur/run/$__runId-paths.txt;
-            $spurBin history anatomy stamp --candidate .spur/run/$__runId-candidate.md
+            $spurBin history anatomy-stamp --candidate .spur/run/$__runId-candidate.md
             --provenance .spur/run/$__runId-provenance.json
             --out .spur/run/$__runId-publishable.md
 
@@ -343,7 +343,7 @@ states:
           command: >-
             . .spur/run/$__runId-paths.txt;
             mkdir -p "$(dirname "$HA_TARGET")";
-            $spurBin history anatomy publish .spur/run/$__runId-publishable.md "$HA_TARGET"
+            $spurBin history anatomy-publish .spur/run/$__runId-publishable.md "$HA_TARGET"
 
   - id: published
     description: Terminal — report published atomically after a passing validation.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.4.21",
+    "version": "0.4.23",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -57,19 +57,19 @@
         "prepublishOnly": "cd ../.. && bun run apps/cli/src/index.ts builder bump-ver --check spur --no-logo"
     },
     "devDependencies": {
-        "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.7.1",
-        "@gobing-ai/ts-ai-runner": "^0.7.1",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.7.1",
-        "@gobing-ai/ts-infra": "^0.7.1",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.7.1",
-        "@gobing-ai/ts-rule-engine": "^0.7.1",
-        "@gobing-ai/ts-runtime": "^0.7.1",
-        "@gobing-ai/ts-utils": "^0.7.1",
+        "@commander-js/extra-typings": "14.0.0",
+        "@gobing-ai/ts-db": "0.7.1",
+        "@gobing-ai/ts-ai-runner": "0.7.1",
+        "@gobing-ai/ts-dual-workflow-engine": "0.7.1",
+        "@gobing-ai/ts-infra": "0.7.1",
+        "@gobing-ai/ts-llm-jsonl-importer": "0.7.1",
+        "@gobing-ai/ts-rule-engine": "0.7.1",
+        "@gobing-ai/ts-runtime": "0.7.1",
+        "@gobing-ai/ts-utils": "0.7.1",
         "@types/bun": "1.4.3",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",
-        "commander": "^14.0.3",
+        "commander": "14.0.3",
         "figlet": "^1.11.0",
         "zod": "4.4.3"
     },

package/plugins/sp/commands/dev-runall.md

@@ -102,7 +102,7 @@ full distinction.
 - **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — the section whose trigger has not fired is on demand.
 - **Publish the visible batch plan first (1105):** publish `A Prepare batch` (A1–A4) and `Z Batch
   report` before the first task, then one letter per task from `spur task batch-plan waves` after
-  freeze/order and digit children from `spur task batch-plan task-children` at task start —
+  freeze/order and digit children from `spur task batch-plan-children` at task start —
   [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
   § 2.7 Visible batch plan.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the engine loop (`spur workflow run --vars '{"executor":"host"}'` → work item → `spur workflow continue`); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.

package/plugins/sp/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.21",
+    "version": "0.4.23",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
 }

package/plugins/sp/skills/conflict-finding/SKILL.md

@@ -234,6 +234,8 @@ findings, unresolved, coverage, cost, remediation, errors`.
 | `Bash`          | `git`, `rg`, `spur task/feature ... --json`, `spur ... check`, `sp:doc-evolve` audit     |
 | `Write`         | Only for temp files / owner-routed repair payloads after confirmation (with `--resolve`) |
 
+**Search routing** (hybrid search, ADR-147): concept, cross-file, or "how does X work" questions → semantic first — the zg MCP tool `zvec_grep_search` when the host exposes it, else `spur self search "<query>" --mode fuzzy --json`. Literal, symbol, regex, or exhaustive occurrence lists → `rg`. If zg is absent or the search response carries a `skipped` reason → fall back to `rg`.
+
 ## Platform Notes
 
 ### Claude Code

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -82,11 +82,11 @@ The command forwards these via `$ARGUMENTS`:
 >   <!-- pipeline-tokens:end -->
 >   matched as a **distinct hyphen-word**
 >   (machine-checked by
->   `detectPipelineDriving` (`spur agent dogfood gate`);
+>   `detectPipelineDriving` (`spur agent dogfood-gate`);
 >   see [§Pipeline-driving word-boundary contract](#pipeline-driving-word-boundary-contract))
 >   → `⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)`.
 > - **Mutating `--fix` modes** — `--fix all` / `--fix blockers-first`, boundary-guarded via
->   `hasMutatingFixMode` (`spur agent dogfood gate`) (never matches
+>   `hasMutatingFixMode` (`spur agent dogfood-gate`) (never matches
 >   `--fix none` / `--focus all` / `--prefix all`). No pipeline token required: a verify/review leg
 >   with `--fix all` mutates the tree on its own (0280 dogfood P2, task 0293). Honesty note:
 >   `--max-retry 0` here bounds **the driver only** — the testee still mutates the tree — so the
@@ -100,7 +100,7 @@ The command forwards these via `$ARGUMENTS`:
    in-agent):
 
    ```bash
-   spur agent dogfood gate \
+   spur agent dogfood-gate \
      --testee "<raw testee string>" \
      [--max-retry-present]
    ```
@@ -121,7 +121,7 @@ The command forwards these via `$ARGUMENTS`:
     re-run the gate with the derived step labels:
 
     ```bash
-    spur agent dogfood gate \
+    spur agent dogfood-gate \
       --testee "<raw testee string>" \
       --max-retry-present \
       --steps "step1 label||step2 label||..."
@@ -232,7 +232,7 @@ contract violation**.
    **before** claiming `status: complete`:
 
    ```bash
-   spur agent dogfood validate-report --file <report-path>
+   spur agent dogfood-validate-report --file <report-path>
    ```
 
    Exit **0** → proceed. Exit **2** → set `status: aborted`, list every error code under §5
@@ -338,7 +338,7 @@ Do **not** use this skill for:
 Pipeline-driving detection is **word-boundary**, not leading-space substring. The live gate is:
 
 ```bash
-spur agent dogfood gate --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
+spur agent dogfood-gate --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
 ```
 
 | Token shape | Examples | Matches | Rejects |
@@ -349,7 +349,7 @@ spur agent dogfood gate --testee "<testee>" [--max-retry-present] [--steps "…"
 `-` is a **word character** for boundaries: a token must be a distinct hyphen-word. Contract tests:
 `packages/app/tests/services/dogfood/pipeline-detect.test.ts`. Helpers:
 `detectPipelineDriving`, `isImplementHeavyStep`, `detectImplementHeavy`, `evaluateDogfoodGate` in
-`spur agent dogfood gate` (absorbed into the CLI; was `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts`).
+`spur agent dogfood-gate` (absorbed into the CLI; was `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts`).
 
 ## Mutating `--fix` mode contract
 

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -336,7 +336,7 @@ Before the skill may stop (success, partial, fail, observe-only end, or abort),
    and mirror the footer block at the **end of the report file**. A report whose body lacks the
    footer cannot set `status: complete`.
 8. **Self-validate (task 0278 R6):** run
-   `spur agent dogfood validate-report --file <report-path>` before
+   `spur agent dogfood-validate-report --file <report-path>` before
    claiming `status: complete`. Exit 2 → `status: aborted` + list error codes under
    `#### Unresolved` (never force complete on a non-@1.2 shape).
 9. **Refusal rule (@1.2):** when any check above fails, set `status: aborted` and list every

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

@@ -2,7 +2,7 @@
 
 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 `spur history anatomy paths`
+(0920): argument validation runs deterministically in `spur history anatomy-paths`
 (formerly the `history-anatomy-cache` helper) (logic core: `packages/app/src/services/history-anatomy.ts`, task 1005) before the
 workflow starts; the model hop no longer performs it.
 

package/plugins/sp/skills/issue-finding/SKILL.md

@@ -367,6 +367,8 @@ With `--create-task`, include `"task": { "wbs": "…", "file": "…", "status":
 | `Bash`          | `spur history` + `spur task` CLI     |
 | `Write`         | Temp files for section bodies        |
 
+**Search routing** (hybrid search, ADR-147): concept, cross-file, or "how does X work" questions → semantic first — the zg MCP tool `zvec_grep_search` when the host exposes it, else `spur self search "<query>" --mode fuzzy --json`. Literal, symbol, regex, or exhaustive occurrence lists → `rg`. If zg is absent or the search response carries a `skipped` reason → fall back to `rg`.
+
 ## Platform Notes
 
 - **Claude Code** — invoke via `/sp:dev-find-issue …` or `Skill(skill="sp:issue-finding",

package/plugins/sp/skills/reverse-engineering/SKILL.md

@@ -141,6 +141,8 @@ Execute phases in order. Stop at the phase boundary required by the selected mod
 3. Exclude or de-prioritize generated, vendored, build output, dependency cache, lockfile-only, binary-heavy, and snapshot-heavy paths unless they are directly relevant.
 4. For monorepos, identify packages/apps and either ask for scope or analyze each package at the requested depth if feasible.
 
+**Search routing** (hybrid search, ADR-147): concept, cross-file, or "how does X work" questions → semantic first — the zg MCP tool `zvec_grep_search` when the host exposes it, else `spur self search "<query>" --mode fuzzy --json`. Literal, symbol, regex, or exhaustive occurrence lists → `rg`. If zg is absent or the search response carries a `skipped` reason → fall back to `rg`.
+
 ### Phase 3: Classify
 
 Classify the codebase as one or more archetypes:

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

@@ -30,7 +30,8 @@ that before using `run` for fan-out dispatch.
 | `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to `queued` | `[id]` `--session-id <sid>` `--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` |
-| `dogfood <gate\|validate-report>` | `sp:dogfood-testing` gates: pipeline-driving refusal (exit 2) and report-contract validation (exit 2) | `--testee` `--max-retry-present` `--steps` `--file` `--json` |
+| `dogfood-gate` | `sp:dogfood-testing` gate: pipeline-driving refusal (exit 2) | `--testee` `--max-retry-present` `--steps` `--json` |
+| `dogfood-validate-report` | `sp:dogfood-testing` report-contract validation (exit 2) | `--file` `--json` |
 | `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 self serve`) | `--server <url>` `--json` |
 | `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
@@ -332,12 +333,12 @@ Posts to the supervisor API
 (`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
 `start`.
 
-## `dogfood` - dogfood-testing gates
+## `dogfood-gate` / `dogfood-validate-report` - dogfood-testing gates
 
 ```bash
-spur agent dogfood gate --testee "/sp:dev-run 0123" --json        # exit 2 = refuse (pipeline-driving, no --max-retry)
-spur agent dogfood gate --testee "…" --steps "plan||implement"     # Phase 1 W8 re-check
-spur agent dogfood validate-report --file report.md --json         # exit 2 = contract errors
+spur agent dogfood-gate --testee "/sp:dev-run 0123" --json        # exit 2 = refuse (pipeline-driving, no --max-retry)
+spur agent dogfood-gate --testee "…" --steps "plan||implement"     # Phase 1 W8 re-check
+spur agent dogfood-validate-report --file report.md --json         # exit 2 = contract errors
 ```
 
 Absorbed from `plugins/sp/scripts/dogfood-testing/` (script-absorption PR-7). `--json` here prints

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

@@ -20,8 +20,7 @@ This noun is **frozen at exactly eight verbs** (`bump-ver`, `drop-tags`, `publis
 script-absorption entries; `show-branches` and the four flat PR verbs `pr-status`, `pr-check`,
 `pr-open`, `pr-review` from the 2026-10-16 feature-L1 entries) by operator consent
 (`docs/design/harness-surface-governance.md` §3) — do not invent additional `builder` subcommands.
-The former `pr <op>` pass-through stays registered as a **hidden, deprecated alias** for one release
-(it prints one stderr deprecation line naming the replacement verb), so it is not listed here.
+The former `pr <op>` pass-through was removed by task 1290 (two-level `spur <noun> <verb>` rule).
 
 ## Verb map
 
@@ -96,12 +95,6 @@ PR); `pr-check` → `{ ok, verdict, preflight, hygiene }`; `pr-open` → `{ ok,
   and returns `PENDING` when a marked request is still in flight; `--force` requests a fresh review
   of the current HEAD regardless. Never force-pushes.
 
-```bash
-# deprecated alias, one release: maps the old op names to the verbs above
-spur builder pr preflight --json     # -> spur builder pr-check
-spur builder pr status --json        # -> spur builder pr-status
-```
-
 ## `show-branches` - read-only branch topology report
 
 ```bash

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

@@ -23,7 +23,14 @@ live in `packages/app/src/services/history-service.ts` (`FanOutResult`, `DailyRe
 | `report [path]` | Purely render an existing artifact; default to `latest.json` | `--mode <name>` `--task <wbs>` `--top <n>` `--json` |
 | `daily` | Run import-all → analyze → artifact → 90-day report pruning once | `--since <iso>` `--until <iso>` `--root <path>` `--source-timeout <ms>` `--mode <name>` `--json` |
 | `reset` | Destructively wipe every `history_*` table for a clean re-import; refuses without `--yes` | `--yes` `--json` |
-| `anatomy <op>` | history-anatomy cache ops behind the `history-anatomy` workflow (`digest`, `check`, `paths`, `assert-clean`, `probe`, `stamp`, `refresh`, `publish`) | op argv (see `spur history anatomy --help`) |
+| `anatomy-digest` | history-anatomy cache op `digest` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-digest --help`) |
+| `anatomy-check` | history-anatomy cache op `check` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-check --help`) |
+| `anatomy-paths` | history-anatomy cache op `paths` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-paths --help`) |
+| `anatomy-assert-clean` | history-anatomy cache op `assert-clean` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-assert-clean --help`) |
+| `anatomy-probe` | history-anatomy cache op `probe` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-probe --help`) |
+| `anatomy-stamp` | history-anatomy cache op `stamp` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-stamp --help`) |
+| `anatomy-refresh` | history-anatomy cache op `refresh` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-refresh --help`) |
+| `anatomy-publish` | history-anatomy cache op `publish` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-publish --help`) |
 | `timeline` | Per-prompt work/wait time and tokens from the host transcript (JSON), for `sp:session-review` | `--transcript <path>` `--group <spec>` |
 | `summary` | Daily summary report for `sp:daily-summary` (tokens, git, history health, annotations) | `--date <d>` `--dry-run` `--output <path>` `--no-git` `--no-ccusage` |
 

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

@@ -1,6 +1,6 @@
 ---
 name: spur-cli-self
-description: "spur-cli noun reference for `spur self`: self-management verbs — SDLC action runner (`exec`), scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), local web server (`serve`), and status overview (`status`). The five legacy verbs (`init`, `maintain`, `migrate`, `serve`, `status`) each mount the same command builder as their legacy top-level noun, which remains a hidden alias; `exec` has no top-level alias."
+description: "spur-cli noun reference for `spur self`: self-management verbs — SDLC action runner (`exec`), scaffold (`init`), database maintenance (`maintain`), schema migrations (`migrate`), hybrid rg/zg search (`search`), local web server (`serve`), and status overview (`status`). The five legacy verbs (`init`, `maintain`, `migrate`, `serve`, `status`) each mount the same command builder as their legacy top-level noun, which remains a hidden alias; `exec` and `search` have no top-level alias."
 see_also:
   - spur-cli
 ---
@@ -14,7 +14,8 @@ Both paths share the same command builder: identical flags, output, and exit cod
 top-level forms are omitted from `spur --help`, leaving `self` as the visible surface.
 
 `exec` is the exception: it exists only as `spur self exec` — there is no `spur exec` top-level
-alias (`spur exec <action>` is an unknown command), so nothing depends on a legacy path.
+alias (`spur exec <action>` is an unknown command), so nothing depends on a legacy path. `search`
+is the second such verb: `spur self search` only.
 
 ## Verb map
 
@@ -24,6 +25,7 @@ alias (`spur exec <action>` is an unknown command), so nothing depends on a lega
 | `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 (or `--check` the importer schema) | `--check` `--json` |
+| `search` | Hybrid exact (`rg`) and semantic (`zg`) search over project docs and code | `--mode` `--scope` `--glob` `--limit` `--regex` `--status` `--json` |
 | `serve` | Start the Spur web server (local fallback) | `--port <n>` `--host <addr>` `--no-open` `--cwd <path>` `--json` |
 | `status [path]` | Show project and git status for a Spur project | `--json` |
 
@@ -63,6 +65,39 @@ first non-zero exit.
 `--json` without `--list` or `--dry-run` prints a final `{ action, steps: [{ name, exitCode, durationMs }], exitCode }`
 after the streaming output. Full surface: `docs/design/sdlc-actions.md` §3.3.
 
+## `self search` - hybrid exact and semantic search
+
+```bash
+spur self search "how is a paused workflow resumed"       # auto: exact + fuzzy where available
+spur self search Bun.which --mode exact                   # ripgrep only
+spur self search 'runCost' --mode fuzzy --limit 5         # zg semantic only
+spur self search resum --mode exact --scope docs --glob '*.md'
+spur self search --status                                 # backend readiness, no query
+spur self search Bun.which --mode exact --json            # raw SearchResponse payload
+```
+
+One verb over the hybrid search service (`docs/design/hybrid-search.md` §4, ADR-147). `--mode` is
+`exact` | `fuzzy` | `auto` (default `auto`), `--scope` is `docs` | `code` | `all` (default `all`),
+`--limit` is 1–100 (default 20), `--glob` adds a backend glob (repeatable; prefix `!` to negate),
+and `--regex` switches the exact route from fixed string to pattern. `--status` prints the `rg`/`zg`
+readiness payload and takes no query.
+
+The groups are `exact` (ripgrep `--json` events) and `fuzzy` (zg `--hybrid`); a group is `null` when
+that route did not run, and `skipped[]` names the degraded route with its reason
+(`zg-not-installed`, `zg-index-missing`, `zg-timeout`, `zg-failed`, `zg-output-error`) plus an exact
+hint string. Hints are printed, never executed — Spur installs and indexes nothing. Human output
+prints `exact (n)` / `fuzzy (n)` headers with `path:start[-end]  [matchedBy]` rows, the first three
+snippet lines indented, then the skip lines; zero hits print `no matches`. `--json` emits the
+`SearchResponse` verbatim (`--json-envelope` for the ADR-091 envelope).
+
+| Exit | When |
+| ---- | ---- |
+| `0` | results, empty results, or a degraded fuzzy route |
+| `1` | invalid request (empty query, bad mode/scope/limit), rg missing or rg failed |
+| `2` | no query and no `--status` (usage) |
+
+Raw zg/rg passthrough flags are deliberately absent: they would leak the adapter.
+
 ## `self init` - scaffold a Spur project
 
 ```bash

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

@@ -49,7 +49,8 @@ re-reading or re-tokenizing the task.
 | `migrate-anchors` | Qualify in-repo evidence anchors to repo-relative paths (0583 R1–R3); `--wbs` scopes to one task file (1109 R1); retargets scratch `done_reason` verdict pointers (1140) | `--wbs` `--dry-run` `--json` |
 | `refresh-roster <wbs>` | Regenerate a parent task's sub-task roster block in `## Plan` | `--folder` `--json` |
 | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--skip-ready` `--agent <selector>` `--folder` `--json` |
-| `batch-plan <mode>` | Batch plan projection: `waves` / `order` / `task-children` (JSON on stdout; the batch driver's visible plan) | `--tasks <file>` `--concurrency <n>` `--letter <A-Z>` `--plan <file>` |
+| `batch-plan <mode>` | Batch plan projection: `waves` / `order` (JSON on stdout; the batch driver's visible plan) | `--tasks <file>` `--concurrency <n>` |
+| `batch-plan-children` | One task row's phase digits from the visible plan (JSON on stdout) | `--letter <A-Z>` `--plan <file>` |
 | `preflight [wbs]` | Read-only batch admission: TABLE A STOP check, quick readiness (`--operation`), one-shot recovery hop; status/deps read from the corpus unless given | `--status <s>` `--deps <list>` `--dep-status <map>` `--operation <op>` `--filtered-count <n>` `--required-sections <list>` `--present-sections <list>` `--force` `--recovery` `--classify-feature <json>` `--folder` `--json` |
 | `wrapup <op>` | One deterministic `wrapup-pipeline` step (`resolve`, `route-reason`, `metrics`, `doc-sync-snapshot`, `doc-sync-scope`, `doc-supersession`, `drift-probe`) — workflow-internal | `--run-id <id>` `--tasks <json>` `--mode <m>` `--spur-bin <cmd>` |
 | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |

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

@@ -121,7 +121,9 @@ The skill's logic divides by **whether the LLM adds value**:
 | `cost` | `spur workflow cost` (CLI) | `[--workflow <name>]… [--by-state] [--include-bookkeeping] [--since <date>] [--budget <file>] [--measured-file <json>] [--json]` | Real terminal non-dry run measurements, or a budget result; unknown measurements stay null. Budget failures exit 1 |
 | `persist-out` | `spur workflow persist-out` (CLI) | `--from <worktree> [--task-file <path>]…` | WT-4 landing: copy a worktree's run rows, two-file records and cited/owned evidence into the invoking tree before teardown; exit 1 fail closed (retain the worktree) |
 | `persist-check` | `spur workflow persist-check` (CLI) | `--from <worktree> [--task-file <path>]… [--run-id <id>]… [--root <tree>] [--success-json <path>]` | WT-4 pre-removal assertion that the worktree owns no unpersisted durable evidence; exit 0 ok / 1 blocked or divergent / 2 usage |
-| `commit-guard` | `spur workflow commit-guard <op>` (CLI) | `start\|stage\|check --run <id> [--base <sha>] [-- <paths…>]` | Stages only paths this run wrote; exit 2 when a listed path is refused, 3 on unmerged/conflict-marked targets |
+| `commit-guard-start` | `spur workflow commit-guard-start` (CLI) | `--run <id>` | Fingerprint HEAD and the dirty working files into `.spur/run/<run>-tree-start.json` |
+| `commit-guard-stage` | `spur workflow commit-guard-stage` (CLI) | `--run <id> [--base <sha>] [-- <paths…>]` | Stages only paths this run wrote; exit 2 when a listed path is refused, 3 on unmerged/conflict-marked targets |
+| `commit-guard-check` | `spur workflow commit-guard-check` (CLI) | `--run <id> [--base <sha>]` | Report working-tree changes this run did not write; stage nothing. The nested `commit-guard <op>` spelling was removed (task 1290) |
 | `add` | agent procedure | `"<nl-description>" [--kind <state-machine\|transition-flow>] [--file <path>]` | **Mode chosen (confirmed)** → first reconciled against existing workflows (extend an existing flow rather than duplicate) → YAML authored in real schema shape → **validated AND dry-run** (reaches the expected terminal state) → [add](workflows/operations.md#add) |
 | `refine` | agent procedure | `<workflow-file> [--intent "<goal>"] [--dry-run]` | Smallest change meeting the intent, re-validated and re-dry-run; `--dry-run` emits a diff only → [refine](workflows/operations.md#refine) |
 
@@ -277,7 +279,9 @@ spur workflow profile  <workflow> [--last <n>] [--window <sec>] [--spur-bin <cmd
 spur workflow cost     [--workflow <name>]... [--by-state] [--include-bookkeeping] [--since <YYYY-MM-DD>] [--budget <file>] [--measured-file <json>] [--json]
 spur workflow persist-out   --from <worktree> [--task-file <path>]...
 spur workflow persist-check --from <worktree> [--task-file <path>]... [--run-id <id>]... [--root <tree>]
-spur workflow commit-guard <op> [options]
+spur workflow commit-guard-start --run <id>
+spur workflow commit-guard-stage --run <id> [--base <sha>] [-- <paths>...]
+spur workflow commit-guard-check --run <id> [--base <sha>]
 ```
 
 ### `cost` — real-run measurements and budgets

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

@@ -185,11 +185,11 @@ batch tip — the step that makes the close-out the report's own contradiction).
 is never a point on the base ref.
 Stage them through the guard — never a free-form `git add` — so a concurrent writer's file cannot
 ride into the close-out commit (incident `36f274590`). `$RUN_ID` is the id Step 3 fixed before
-`spur workflow commit-guard start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:
+`spur workflow commit-guard-start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:
 
 ```bash
-spur workflow commit-guard check --run "$RUN_ID"      # 1129 R3: a non-empty foreign list goes in the batch report
-spur workflow commit-guard stage --run "$RUN_ID" -- <files the wrap wrote> \
+spur workflow commit-guard-check --run "$RUN_ID"      # 1129 R3: a non-empty foreign list goes in the batch report
+spur workflow commit-guard-stage --run "$RUN_ID" -- <files the wrap wrote> \
   || { echo "close-out halt: commit-guard refused a path (foreign, unmerged or conflict-marked); nothing committed" >&2; exit 1; }
 git commit -m "chore(wrap): <command> <selector> close-out writes"
 ```

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

@@ -311,7 +311,7 @@ per-task letter is ever hand-assigned.
    `spur workflow show task-pipeline.yaml --no-logo --format todo --json` payload:
 
    ```bash
-   spur task batch-plan task-children --letter <task-letter> --plan <plan.json>
+   spur task batch-plan-children --letter <task-letter> --plan <plan.json>
    ```
 
 4. **When a task ends:** mark the task's letter (and its published digits) with the task's terminal
@@ -327,7 +327,7 @@ plan = resolve(--tasks) → freeze → order(deps)        # may abort (cycle) or
 report = []
 publish visible plan §2.7: A/Z rows now; one letter per task after this freeze (task batch-plan waves)
 RUN_ID = WT-3 marker id under --worktree, else "batch-$(date -u +%Y%m%dT%H%M%SZ)"   # fixed ONCE here; the close-out reuses it
-spur workflow commit-guard start --run "$RUN_ID"       # 1129 R1: fingerprint before the first task writes; the close-out commit stages through it
+spur workflow commit-guard-start --run "$RUN_ID"       # 1129 R1: fingerprint before the first task writes; the close-out commit stages through it
 for wbs in plan:                                       # default sequential mode
     if any dependency of wbs failed earlier in THIS batch:
         report += skipped(wbs, reason); continue       # only relevant under --keep-going
@@ -338,7 +338,7 @@ for wbs in plan:                                       # default sequential mode
     preflight = spur task preflight <wbs>              # Step 2.6 — TABLE A STOP
     if preflight.action == skip:
         report += preflight-skip(wbs, preflight); continue
-    visible plan (§2.7): letter in_progress + task-children digits at start; letter ← outcome at end
+    visible plan (§2.7): letter in_progress + batch-plan-children digits at start; letter ← outcome at end
     run: if interactive sequential omit/inline:
              spur workflow run task-pipeline.yaml --vars <vars with executor=host> --json
              perform the returned work item; spur workflow continue <run-id> --answer-text <receipt>

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

@@ -453,14 +453,14 @@ git checkout <base-ref> && git merge --no-ff -m "<prepared message>" <branch>
 #     the batch's run id, the same one WT-3b's worktree fingerprint used — the two trees keep two
 #     artifacts under the same id):
 #       RUN_ID="<marker-id>"   # the WT-3 marker's id
-#       spur workflow commit-guard start --run "$RUN_ID"
+#       spur workflow commit-guard-start --run "$RUN_ID"
 #     git checkout <base-ref> && git merge --no-commit <branch>
 # 2. resolve source conflicts by hand; generated files are then regenerated with the project's
 #    generator, never hand-merged
 #    (this repo: bun run --filter @gobing-ai/spur build:bundle)
 # 3. stage every resolved path and regenerated bundle through the guard — an unmerged or
 #    unstaged path makes step 5 abort, and a conflict-marked path exits 3 (resolve, then retry):
-#      spur workflow commit-guard stage --run "$RUN_ID" -- <resolved paths and regenerated bundles>
+#      spur workflow commit-guard-stage --run "$RUN_ID" -- <resolved paths and regenerated bundles>
 #    Forbidden here as in every driver commit step: `git add -A` and `git add .`.
 # 4. run qualityGateCmd once, after ALL conflicts are resolved
 # 5. commit the merge with the prepared message file — CHECK THE PARENTS FIRST (step 5a)