@gobing-ai/spur 0.4.21 → 0.4.22

package/.claude-plugin/marketplace.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.4.21",
+    "version": "0.4.22",
     "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/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.21",
+    "version": "0.4.22",
     "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/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/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/wayfinder/SKILL.md

@@ -142,6 +142,8 @@ Invoked when a map already exists (operator provides the feature ID). A ticket i
    | **Prototype** | Cheap, rough, concrete artifact to react to — an outline, stub, or rough implementation via `sp:code-implementation`. | Linked prototype as a task artifact |
    | **Task** | Literal manual work — nothing to prototype or research. Moving data, provisioning access. | Checklist in task body; resolved when done |
 
+   **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`.
+
    An open question from the map is **not** resolved this way. It is settled with the operator in
    conversation (`AskUserQuestion` where available) and recorded straight into **## Decisions so far**
    — no task is claimed, and it does not consume the session's one ticket.