@gobing-ai/spur 0.3.5 → 0.3.7

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.5",
+    "version": "0.3.7",
     "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/rules/typescript/no-unmocked-module-eval-side-effects.yaml

@@ -55,6 +55,13 @@ rules:
     evaluator:
       type: rg
       config:
-        # Match imports from modules with known module-eval side effects.
-        # Add new patterns here as alternations (|) when new cases are discovered.
-        pattern: "from ['\"].*task-kanban/useTasks['\"]"
+        # Match imports from modules with KNOWN, ACTIVE module-eval side effects.
+        # IMPORTANT: this rule is INERT unless a pattern is present. When a new
+        # side-effect module is discovered (CI-only ordering failure traced to
+        # an import-time call), add its import pattern here as a string. Remove
+        # the pattern once the source module is fixed (side effects made lazy).
+        #
+        # RESOLVED modules (patterns removed after fix — kept as history):
+        #   - task-kanban/useTasks — fixed 2026-07-08, commit 3937d31
+        #     (resolveApiUrl/api.task.list converted to lazy dynamic imports)
+        pattern: "__no_active_side_effect_modules__"

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

@@ -0,0 +1,151 @@
+# AGENTS.md
+
+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
+
+<!-- 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)
+
+| 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`**.
+
+```bash
+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 (`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 under `.spur/context/` (gitignored), via **`sp:indexed-context`**:
+
+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, continue; do not block.

package/spur-cli/config/templates/docs/00_ADR.md

@@ -12,6 +12,9 @@ updated_at: 1970-01-01T00:00:00.000Z
 
 > Authoritative on **decisions**. Lower number wins — this doc overrides all others on decisions.
 > Each entry is append-only; supersession is by a new dated entry, never by editing an old one.
+> Only real cross-cutting decisions belong here — not implementation notes, not feature status, not
+> how-to guidance. Entries that grow past decision + reason are carrying mechanism that belongs in
+> `03`/`04`; link it instead of inlining it.
 
 ## ADR-001 — (example) Adopt this doc structure
 
@@ -24,4 +27,6 @@ updated_at: 1970-01-01T00:00:00.000Z
 <!--
 Add new ADRs here. Copy the entry shape above (Date, Status, Context, Decision, Reason).
 A decision that reverses a prior ADR adds a new entry that says "supersedes ADR-NNN".
+An Amendment records the decision delta + one-line reason — not the mechanism. Implementation
+paths, detailed semantics, and multi-paragraph rationale belong in 03/04, not in the amendment.
 -->

package/spur-cli/config/templates/docs/99_PROJECT_CONSTITUTION.md

@@ -53,7 +53,7 @@ When a change touches one of these, the listed doc MUST be updated in the **same
 
 | ID | Trigger | Doc(s) |
 |----|---------|--------|
-| T1 | New cross-cutting decision | `00` first, then `03` mechanism |
+| T1 | New cross-cutting decision (entry = decision + one-line reason; amendment = decision delta only — mechanism goes in `03`/`04`, not the amendment) | `00` first, then `03` mechanism |
 | T3 | Command/flag/config/schema/DTO added/changed | `04` + `AGENTS.md` |
 | T4 | Feature ships or changes state | `05` row |
 | T6 | Scope added / cut / deferred | `01` |