@gobing-ai/spur 0.3.6 → 0.3.8

package/README.md

@@ -1,9 +1,9 @@
 # @gobing-ai/spur
 
 **The `spur` command** — a local-first harness for mainstream coding agents (Claude Code, Codex,
-Gemini CLI, Antigravity, pi, OpenCode, OpenClaw). Spur is **not** a coding agent; it wraps the agents
-you already have with constraint checking, workflow orchestration, agent health checks, and
-conversation-history analytics.
+Gemini CLI, pi, omp, OpenCode, Antigravity, OpenClaw, Hermes, Grok). Spur is **not** a coding agent;
+it wraps the agents you already have with constraint checking, workflow orchestration, agent health
+checks, and conversation-history analytics.
 
 ## Install
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.6",
+    "version": "0.3.8",
     "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",
@@ -40,7 +40,7 @@
     },
     "scripts": {
         "dev": "bun run src/index.ts",
-        "build": "bun build src/index.ts --compile --outfile ../../dist/cli/spur",
+        "build": "bun run ../../scripts/spur-dev.ts build-cli",
         "build:binaries": "bun run ../../scripts/spur-dev.ts build-binaries",
         "build:bundle": "bun build src/index.ts --target=bun --outfile spur.js && bun run ../../scripts/spur-dev.ts bundle-config spur-cli/config",
         "test": "bun test tests --coverage --coverage-dir=../../.coverage --pass-with-no-tests",
@@ -49,13 +49,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-ai-runner": "^0.4.4",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.4",
-        "@gobing-ai/ts-infra": "^0.4.4",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.4",
-        "@gobing-ai/ts-rule-engine": "^0.4.4",
-        "@gobing-ai/ts-runtime": "^0.4.4",
-        "@gobing-ai/ts-utils": "^0.4.4",
+        "@gobing-ai/ts-db": "^0.4.8",
+        "@gobing-ai/ts-ai-runner": "^0.4.8",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.8",
+        "@gobing-ai/ts-infra": "^0.4.8",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.8",
+        "@gobing-ai/ts-rule-engine": "^0.4.8",
+        "@gobing-ai/ts-runtime": "^0.4.8",
+        "@gobing-ai/ts-utils": "^0.4.8",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/spur-cli/config/config.example.yaml

@@ -39,6 +39,9 @@ agent:
   # `default` is the executor selector for `--agent auto` (resolved as an executor
   # name first, then a legacy agent name). Keep it simple, or define richer profiles:
   default: omp
+  # Canonical coding-agent ids (ts-ai-runner DISPLAY_ORDER, 0.4.8+):
+  #   claude, codex, gemini, pi, omp, opencode, antigravity-cli, openclaw, hermes, grok
+  # Grok auth: non-empty XAI_API_KEY and/or ~/.grok/auth.json (no CLI auth-status verb).
   # Named executor profiles: pair a canonical agent with an optional opaque model
   # override. Referenced by name from `default` and `default-by-phase`.
   # executors:
@@ -49,12 +52,16 @@ agent:
   #     model: zai//glm-5.2
   #   - name: claude
   #     agent: claude
+  #   - name: grok
+  #     agent: grok
+  #     # model: grok-…   # optional; passed as grok -m <model>
   # Per-phase auto routing — a MAP of dev phase → executor selector. A configured
   # phase mapping is authoritative: a broken mapping fails fast (unknown executor →
   # exit 2; unusable agent → exit 1) and does NOT fall back to `default`.
   # default-by-phase:
   #   dev-run: omp-zai
   #   dev-review: claude
+  #   # dev-run: grok
 
 rules:
   paths:

package/spur-cli/config/rules/boundary/dao-boundary.yaml

@@ -26,6 +26,12 @@ rules:
           exclude:
             - "**/node_modules/**"
             - "**/tests/**"
+            # apps/cli/src/index.ts carries a side-effect import of ts-db as a
+            # bundler hint for Bun --compile. The import does not use ts-db APIs;
+            # it ensures the dynamic import('@gobing-ai/ts-db') calls from within
+            # ts-runtime resolve at runtime from the compiled binary's bunfs.
+            # Spur-domain still owns all functional ts-db usage.
+            - "apps/cli/src/index.ts"
 
   - id: drizzle-only-in-domain-schema
     description: >

package/spur-cli/config/rules/strict/http-boundaries.yaml

@@ -28,12 +28,31 @@ rules:
 
   - id: no-globalthis-fetch
     description: "Avoid globalThis.fetch(...); route HTTP through a client seam when one exists."
-    severity: warning
+    severity: error
     evaluator:
       type: rg
       config:
         pattern: "globalThis\\.fetch\\("
+    include:
+      - "apps/**/src/**/*.ts"
+      - "packages/**/src/**/*.ts"
+      - "apps/**/tests/**/*.ts"
+      - "apps/**/tests/**/*.tsx"
+      - "packages/**/tests/**/*.ts"
+      - "packages/**/tests/**/*.tsx"
 
+  - id: no-globalthis-fetch-mutation
+    description: "Avoid mutating globalThis.fetch in tests; use the injectable fetch seam (rpc-client.ts setFetchForTesting / resetFetchForTesting)."
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "globalThis\\.fetch\\s*="
+    include:
+      - "apps/**/tests/**/*.ts"
+      - "apps/**/tests/**/*.tsx"
+      - "packages/**/tests/**/*.ts"
+      - "packages/**/tests/**/*.tsx"
   - id: no-xml-http-request
     description: "Do not use XMLHttpRequest in a Bun/Node codebase."
     severity: error

package/spur-cli/config/templates/AGENTS.md

@@ -1,40 +1,151 @@
 # AGENTS.md
 
-Guidance for AI coding agents working in this repository.
+Entry point for AI coding agents in this repository. Symlink `CLAUDE.md` / `GEMINI.md` (and
+equivalents) here when the platform expects those names.
+
+**Read this first every session.** Lean: harness routing + project facts + where depth lives.
+Does **not** restate skill runbooks or the full `spur` verb catalog.
+
+---
 
 ## Project
 
-<!-- Replace the line below with your project name and a one-line description. -->
-**{project-name}** — (one-line description).
+<!-- PROJECT-SPECIFIC: filled by `spur init` (`{project-name}` / `{project-description}`). -->
+**{project-name}** — {project-description}.
+
+This project uses **Spur** as its harness: the `spur` CLI for deterministic corpus/ops, and Spur’s
+agent surface (`/sp:dev-*` commands + `sp:*` subagents/skills) for planning, execution, review, and
+docs hygiene. Prefer the harness over ad-hoc process unless the operator overrides for a one-off.
+
+---
+
+## Harness-first contract
+
+All product development work goes through the harness by default.
+
+### Harness tool routing
+
+| Need | Route to | Avoid |
+|------|----------|--------|
+| Plan a feature (intake → AC → tasks) | `/sp:dev-plan`, `/sp:dev-idea` | Freeform feature files without gates |
+| Drive one task end-to-end | `/sp:dev-run <wbs>` or **`sp:super-coder`** | Implement with no task / no pipeline |
+| Batch or parallel task runs | `/sp:dev-runall`, `/sp:dev-parallel` → **`sp:super-coder`** | Unordered multi-task thrash |
+| Multi-step corpus CLI (tasks/features/rules/workflows) | **`sp:expert-spur`** | Raw Write/Edit on corpus files |
+| Look up `spur` verbs / flags / `--json` | Skill **`sp:spur-cli`** | Inventing flags from memory |
+| Create/edit/list tasks or features | **`spur task` / `spur feature`** (`--section --from-file`) | Direct-writing task/feature corpus files |
+| Verify requirements / AC | `/sp:dev-verify` | Self-reported “done” |
+| Review (SECUA + traceability + architecture) | `/sp:dev-review` or **`sp:super-reviewer`** | Unstructured “LGTM” |
+| Tests / coverage | `/sp:dev-unit` | Untested production paths as done |
+| Constraint gate / rule authoring | **`spur rule`**; `/sp:rule-scan`, `/sp:rule-add`, `/sp:rule-refine` | Skipping `spur rule run` |
+| Workflow author / run | **`spur workflow`**; `/sp:workflow-add`, `/sp:workflow-refine` | Ad-hoc shell as the lifecycle |
+| Docs drift / sync / lessons | Skill **`sp:doc-evolve`** + `docs/99_PROJECT_CONSTITUTION.md` | Patching derived docs over authority |
+| Wrap completed work | `/sp:dev-wrap`, `/sp:dev-wrapall` | Skipping learnings / doc sync |
+| Session index / memory | Skill **`sp:indexed-context`** + `.spur/context/` | Full-tree re-reads every turn |
+
+**Non-negotiable (unless operator overrides):**
+
+1. **CLI-gated corpus writes** — `spur task update` / `spur feature update` (etc.). Never direct-write
+   task/feature corpus files.
+2. **Gates before done** — `spur task check` / `spur feature check` / `spur rule run`; pipeline done
+   needs a real verify **PASS**.
+3. **`--json` for machines** — parse CLI with `--json`.
+4. **Route, don’t invent** — verbs → `sp:spur-cli`; lifecycle → `/sp:dev-*` / `sp:super-coder`;
+   multi-noun corpus → `sp:expert-spur`; review → `sp:super-reviewer`; docs process → `sp:doc-evolve`.
+
+**Platform fallback:** Platforms without slash commands and/or subagents still use the harness.
+Equivalent path: skills `sp:spur-dev`, `sp:spur-cli`, `sp:code-verification` (and related) plus the
+`spur` CLI. Do not invent a parallel process because `/sp:dev-*` is unavailable.
+
+Invoke CLI: `spur <noun> <verb> … --json` (or the project’s documented dev entry).
+
+---
+
+## Documentation
+
+**Process SSOT:** `docs/99_PROJECT_CONSTITUTION.md`. Operate with **`sp:doc-evolve`**
+(`drift-audit`, `sync-check`, `contract-verify`, `lesson-append`).
+
+**Conflict rule:** lower number wins on content (`00` decisions, `01` scope, `99` process). Fix
+authority first, then derived docs, then this file.
+
+### Doc map (constitution §4.1)
 
-## Commands
+| Doc | Owns | Authority | When |
+|------|------|-----------|------|
+| `docs/00_ADR.md` | **WHY** | Authoritative (content) | Structural change; dated entry before diverging |
+| `docs/01_PRD.md` | **WHAT** | Authoritative on scope | New feature/command |
+| `docs/02_ROADMAP.md` | **WHEN** | Derived | Phase placement |
+| `docs/03_ARCHITECTURE.md` | **HOW** | Derived (ADR wins) | Cross-module / seam / schema |
+| `docs/04_DESIGN.md` | **SURFACE** (+ `docs/design/`) | Derived | Same commit as surface code (T3) |
+| `docs/05_FEATURES.md` | **STATUS** (+ `docs/features/`) | Derived | Feature status (T4) |
+| `docs/99_PROJECT_CONSTITUTION.md` | **PROCESS** | Authoritative on process | Before editing numbered docs |
+| `AGENTS.md` (this file) | **ENTRY** | Derived | First every session |
+
+**Routing:** decision → `00`; scope → `01`; mechanism → `03`; surface → `04`; phase → `02`;
+feature status → `05`. Working layers §4.2; audits §7; satellites §4.5.
+
+---
+
+## Stack & layout
+
+<!-- PROJECT-SPECIFIC: monorepo layout, package manager, key frameworks. -->
+_(Fill from package manifests / README — or during `sp:doc-evolve` customize.)_
+
+---
+
+## Build & verification
+
+<!-- PROJECT-SPECIFIC: lint / test / build commands. -->
+```bash
+# Fill with this project's lint, test, and build commands.
+```
+
+**Done gate (minimum):** lint + tests clean; only intentional `git status` changes; no
+`--no-verify` / silent suppressions. Harness task done ⇒ real verify **PASS** when the pipeline ran.
+
+---
+
+## Spur CLI surface
+
+**Not the verb catalog.** For `task` / `feature` / `rule` / `workflow` flags, exit codes, and
+`--json` shapes → skill **`sp:spur-cli`**. Lifecycle → `/sp:dev-*` / **`sp:super-coder`**.
+Multi-noun corpus campaigns → **`sp:expert-spur`**.
 
-<!-- Fill in the build/test/lint commands for this project. Examples: -->
 ```bash
-# build
-# test
-# lint
+spur <noun> <verb> … --json
+spur <noun> --help
 ```
 
+**Long-tail:** Additional `/sp:dev-*` commands (handover, gitmsg, fixall, dogfood, reverse, arch,
+…) are indexed in the project plugin README (`plugins/sp/README.md` when present).
+
+**Outside spur-cli:** Nouns not fully documented in `sp:spur-cli` (`agent`, `history`, `message`,
+`team`, `status`, `migrate`, `serve`, `init`, …) — use only `spur <noun> --help` and
+`docs/04_DESIGN.md`. Never guess flags.
+
+---
+
 ## Conventions & boundaries
 
-- Conventional Commits required (`feat:`, `fix:`, `docs:`, `chore:`, ...). Breaking changes in a `BREAKING CHANGE:` footer.
-- Never commit secrets, `.env*`, or credentials.
-- Surgical changes only: touch what the task needs; no drive-by refactors, no speculative abstractions,
-  no comments that restate what the code already says.
+- Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, …); breaking changes in a
+  `BREAKING CHANGE:` footer.
+- Never commit secrets or `.env*`.
+- Surgical changes only — no drive-by refactors or speculative abstractions.
+- Surface changes keep `docs/04_DESIGN.md` in the **same commit** (T3); run `sp:doc-evolve`
+  sync-check when unsure.
+<!-- PROJECT-SPECIFIC: import aliases, forbidden paths, CI rules. -->
 
 ---
 
 ## Indexed context
 
-Project context lives in `.spur/context/` (gitignored) and is surfaced by the `sp:indexed-context` skill.
-Check it before re-reading files you may already have indexed:
+Project context under `.spur/context/` (gitignored), via **`sp:indexed-context`**:
 
-1. `.spur/context/anatomy.md` — one-line description + token estimate per file. Read before opening a file.
-2. `.spur/context/learnings.md` — project conventions, decisions, preferences. Read before generating code.
-3. `.spur/context/pitfalls.md` — dated "do-not-repeat" entries. Read before generating code.
-4. `.spur/context/buglog.md` — historical bug log. Read before fixing a bug.
-5. `.spur/context/memory.md` — session log. Append one line per significant action.
-6. `.spur/context/token-ledger.jsonl` — auto-tracked by hooks; never hand-edit.
+1. `anatomy.md` — file one-liners + token estimates  
+2. `learnings.md` — conventions / decisions  
+3. `pitfalls.md` — do-not-repeat  
+4. `buglog.md` — historical bugs  
+5. `memory.md` — session log  
+6. `token-ledger.jsonl` — auto; never hand-edit  
 
-If `.spur/context/` is absent, proceed normally. Never block work on its absence.
+If `.spur/context/` is absent, continue; do not block.