@gobing-ai/spur 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.4",
+    "version": "0.3.6",
     "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",

package/spur-cli/config/rules/typescript/guarded-happy-dom-register.yaml

@@ -0,0 +1,64 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Require try/catch guard around GlobalRegistrator.register() in web tests.
+#
+# WHY: GlobalRegistrator.register() sets up happy-dom globals (window, document,
+# etc.). In a full bun test suite, multiple test files call it. The first call
+# succeeds; subsequent calls throw "Happy DOM has already been globally
+# registered" and the error kills the test file (4 test files × ~13 tests each
+# = 52 tests lost). This only surfaces when ALL tests run together (CI, or
+# `bun test ./apps/web/`), not when a single file runs in isolation.
+# Real incident: 52 CI-only failures across 4 test files, 2026-07-09.
+#
+# FIX: wrap in try/catch:
+#
+#   try { GlobalRegistrator.register(); } catch {} // already registered in suite
+#
+# The teardown helper (apps/web/tests/happy-dom.ts) is the sanctioned unregister
+# caller (see happy-dom-teardown.yaml). This rule guards the register side.
+#
+# Severity warning: the file may pass in isolation but will fail in the full
+# suite; fix before merge.
+include:
+  - "apps/web/tests/**/*.test.ts"
+  - "apps/web/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  # Helper that manages happy-dom lifecycle — not a raw register call.
+  - "apps/web/tests/happy-dom.ts"
+  # These files already wrap register() in try/catch; they are compliant.
+  - "apps/web/tests/modules/task-kanban/board.test.tsx"
+  - "apps/web/tests/modules/task-kanban/components.test.tsx"
+  - "apps/web/tests/modules/task-kanban/task-detail.test.tsx"
+  - "apps/web/tests/modules/task-kanban/index.test.tsx"
+  - "apps/web/tests/modules/task-kanban/new-task-panel.test.tsx"
+  - "apps/web/tests/modules/task-kanban/markdown-body.test.tsx"
+  - "apps/web/tests/modules/task-kanban/useTaskParams.test.tsx"
+  - "apps/web/tests/modules/task-kanban/task-filters.test.tsx"
+  - "apps/web/tests/modules/task-kanban/useTasks.test.ts"
+  - "apps/web/tests/modules/features/components.test.tsx"
+  - "apps/web/tests/lib/theme.test.ts"
+  - "apps/web/tests/components/BoardLayout.test.tsx"
+  - "apps/web/tests/modules/observability/components.test.tsx"
+  - "apps/web/tests/components/ThemeToggle.test.tsx"
+  - "apps/web/tests/components/ResponsiveAndTheme.test.tsx"
+
+rules:
+  - id: guarded-happy-dom-register
+    description: >
+      GlobalRegistrator.register() must be wrapped in try/catch — without
+      it, the second test file that calls it throws "already been globally
+      registered" and all tests in that file are lost (a CI-only failure
+      that never reproduces when a single file runs in isolation). Wrap:
+      `try { GlobalRegistrator.register(); } catch {}`. 52-real CI incidents,
+      2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match bare GlobalRegistrator.register() — NOT inside try/catch
+        # Negative lookbehind: line does NOT start with "try" before the call
+        pattern: "GlobalRegistrator\\.register\\(\\)"
+        # Only flag lines where the call is NOT preceded by try{ on the same line
+        # (the fixed version is `try { GlobalRegistrator.register(); } catch {}`)
+        # We match the call itself and let the description guide the fix

package/spur-cli/config/rules/typescript/no-leaky-module-mocks.yaml

@@ -35,21 +35,20 @@ include:
 exclude:
   - "**/node_modules/**"
   - "**/dist/**"
-  # These tests mock the FIRST-PARTY oRPC `api` client (`../../../src/lib/rpc-client`).
-  # That client is a callable Proxy, so spyOn cannot intercept it (the call regenerates
-  # and hits the network) — `mock.module()` is the only working mechanism. They are safe
-  # because they sort AFTER both rpc-client unit-test files (`lib/rpc-client.test.ts`,
-  # `rpc-client.test.ts`), so the override never leaks back into a real-import reader.
-  # Keep this list minimal: only files that mock a first-party module and have no
-  # spyOn-able alternative belong here. (markdown-body mocks only third-party modules —
-  # mermaid/dompurify — which the narrowed pattern no longer flags, so it is not listed.)
+  # Shared full-surface mock helpers are the CORRECT pattern — they ensure every
+  # test file registers the same compatible surface, neutralizing "last mock wins."
+  - "apps/web/tests/test-helpers/rpc-client-mock.ts"
+  # These files use beforeEach restoreMock() atop the shared baseline — the mock.module
+  # call is in a runtime function, not at module scope, and always registers the full surface.
   - "apps/web/tests/modules/task-kanban/board.test.tsx"
   - "apps/web/tests/modules/task-kanban/components.test.tsx"
   - "apps/web/tests/modules/task-kanban/new-task-panel.test.tsx"
   - "apps/web/tests/modules/features/components.test.tsx"
   - "apps/web/tests/modules/task-kanban/task-detail.test.tsx"
   - "apps/web/tests/modules/task-kanban/index.test.tsx"
-
+  # index.test.tsx no longer mocks useTasks/useTaskParams/TaskDetail; useTasks.test.ts
+  # uses custom listFn (isolated store), not mock.module for first-party modules.
+  - "apps/web/tests/modules/task-kanban/useTasks.test.ts"
 rules:
   - id: no-leaky-mock-module
     description: >

package/spur-cli/config/rules/typescript/no-module-scope-import-calls.yaml

@@ -0,0 +1,61 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Forbid calling imported functions at module-evaluation scope in source files.
+#
+# WHY: calling an imported function at module scope (outside any function/class
+# body) creates an evaluation-time side effect that captures the depencency
+# before any test mock can intercept it. If the first test file that evaluates
+# this module has a mock active, the module caches with that mock's state; in
+# CI (where test-file order differs from local), a different test may evaluate
+# it first with NO mock or a different mock, causing CI-only failures that pass
+# locally every time. Real incidents:
+#
+#   2026-07-09: useTasks.ts:6   — const SSE_URL = `${resolveApiUrl()}/...`  (73 failures)
+#   2026-07-09: SystemEventsTab.tsx:42-43 — const HISTORY_URL = `${resolveApiUrl()}/...`;
+#              const SSE_URL = `${resolveApiUrl()}/...`  (1 failure)
+#
+# The pattern is always the same: a top-level `const` or `let` whose initializer
+# calls a function imported from another module. Defer the call to a function:
+#
+#   // BEFORE (broken):
+#   const SSE_URL = `${resolveApiUrl()}/events/planning`;
+#
+#   // AFTER (fixed):
+#   const sseUrl = () => `${resolveApiUrl()}/events/planning`;
+#
+# FIX: wrap the initializer in an arrow function and call it lazily at the
+# point of use. If the value is used as a default parameter or a constant
+# reference, convert it to a getter function or compute it in the
+# constructor/init method.
+#
+# Severity: warning. A hit may pass locally but WILL fail in CI if a mock is
+# involved; justify with a comment or convert to lazy.
+include:
+  - "apps/**/src/**/*.ts"
+  - "apps/**/src/**/*.tsx"
+  - "packages/**/src/**/*.ts"
+  - "packages/**/src/**/*.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/tests/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+
+rules:
+  - id: no-module-scope-import-calls
+    description: >
+      Calling an imported function at module scope (outside any function or
+      class body) creates an evaluation-time side effect that captures the
+      dependency before any test mock can intercept it — a CI-only,
+      ordering-dependent failure. Defer the call: wrap the value in an arrow
+      function and call it lazily at the point of use. Real incidents:
+      useTasks.ts:6 (73 CI failures), SystemEventsTab.tsx:42 (1 CI failure),
+      2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match top-level const/let whose initializer is a template literal
+        # calling an import (e.g. resolveApiUrl(), api.*, ...).
+        # The pattern: line starts with `const`/`let`, contains `${...()}`.
+        pattern: "^(const|let)\\s+\\w+\\s*=\\s*`[^`]*\\$\\{[^}]*\\([^)]*\\)[^}]*\\}[^`]*`"

package/spur-cli/config/rules/typescript/no-unmocked-module-eval-side-effects.yaml

@@ -0,0 +1,67 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Require test files to mock dependencies of modules with module-eval side effects.
+#
+# WHY (the general pattern): some source modules run code at module-evaluation
+# time — creating singletons, computing constants from imports, calling functions
+# from other modules at module scope (not inside a function/class body). When a
+# test file imports such a module, it triggers the side effect. If the dependency
+# modules are not mocked, the side effect captures the real API and that state
+# persists across the entire test suite — a CI-only, file-ordering-dependent
+# failure that never reproduces locally. The sibling rule `no-leaky-module-mocks`
+# handles the mirror problem (mock.module leaking into real-import readers).
+#
+# KNOWN MODULES WITH MODULE-EVAL SIDE EFFECTS:
+#
+#   (None currently active — the useTasks.ts singleton side effect was fixed by
+#    commit 3937d31 which converted resolveApiUrl() and api.task.list() calls to
+#    lazy dynamic imports. The singleton _sharedStore = new TaskStore() no longer
+#    triggers an API call at module-eval time. When a new side-effect module is
+#    discovered, add it here with the pattern shown below.)
+#
+#   RESOLVED — src/modules/task-kanban/useTasks.ts (fixed 2026-07-08)
+#     - Line 6: was const SSE_URL = `${resolveApiUrl()}/events/planning`;
+#       → now: const sseUrl = async () => { const { resolveApiUrl } = await import(...); return ...; };
+#     - Line 159: was const sharedStore = new TaskStore(); (calls defaultListTasks
+#       which statically imported api.task.list) → now: defaultListTasks uses
+#       dynamic await import('../../lib/rpc-client'), so construction is lazy.
+#     - 73 CI failures, 2026-07-08. Fix: commit 3937d31.
+#
+# To ADD a new module to this list when another CI-only failure is traced to a
+# module-eval side effect: append its import pattern to `rules[].evaluator.config.pattern`
+# (alternation) and add the corresponding entry above.
+include:
+  - "apps/**/tests/**/*.test.ts"
+  - "apps/**/tests/**/*.test.tsx"
+  - "packages/**/tests/**/*.test.ts"
+  - "packages/**/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  # All known side-effect modules are resolved. When a new one is discovered,
+  # exclude files that already mock the dependency before importing it.
+
+rules:
+  - id: no-unmocked-module-eval-side-effects
+    description: >
+      Test files that import a module with module-evaluation side effects
+      (singletons created at module scope, imports called at eval time, etc.)
+      MUST mock the dependency modules BEFORE the import. Without the mock,
+      the side effect captures the real API and leaks into every subsequent
+      test file — a CI-only, ordering-dependent failure. Add mock.module()
+      for the listed dependency before any import of the side-effect module.
+      See the file header for the list of known side-effect modules and their
+      dependencies. 73-real CI incidents (useTasks → rpc-client), 2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # 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,40 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in this repository.
+
+## Project
+
+<!-- Replace the line below with your project name and a one-line description. -->
+**{project-name}** — (one-line description).
+
+## Commands
+
+<!-- Fill in the build/test/lint commands for this project. Examples: -->
+```bash
+# build
+# test
+# lint
+```
+
+## 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.
+
+---
+
+## 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:
+
+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.
+
+If `.spur/context/` is absent, proceed normally. Never block work on its absence.

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` |

package/spur.js

@@ -70181,7 +70181,7 @@ import { join as join13, resolve as resolve5 } from "path";
 var CLI_CONFIG = {
   binaryName: "spur",
   binaryLabel: "spur",
-  binaryVersion: "0.3.4",
+  binaryVersion: "0.3.6",
   configDir: ".spur",
   configFile: ".spur/config.yaml",
   databaseFile: ".spur/spur.db"
@@ -70227,7 +70227,8 @@ var SCAFFOLD_MANIFEST = [
   { source: "templates/docs/02_ROADMAP.md", target: "templates/docs/02_ROADMAP.md" },
   { source: "templates/docs/03_ARCHITECTURE.md", target: "templates/docs/03_ARCHITECTURE.md" },
   { source: "templates/docs/04_DESIGN.md", target: "templates/docs/04_DESIGN.md" },
-  { source: "templates/docs/05_FEATURES.md", target: "templates/docs/05_FEATURES.md" }
+  { source: "templates/docs/05_FEATURES.md", target: "templates/docs/05_FEATURES.md" },
+  { source: "templates/AGENTS.md", target: "AGENTS.md", root: true, preserve: true }
 ];
 
 // src/commands/init.ts
@@ -70235,6 +70236,24 @@ var GLOBAL_CONFIG_DIR2 = join13(".config", "spur");
 var GLOBAL_RULES_DIR2 = join13(GLOBAL_CONFIG_DIR2, "rules");
 var GLOBAL_CONFIG_EXAMPLE = "config.example.yaml";
 var GLOBAL_CONFIG_FILE2 = "config.yaml";
+var INDEXED_CONTEXT_MARKER = "## Indexed context";
+var INDEXED_CONTEXT_BLOCK = `
+---
+
+## 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:
+
+1. \`.spur/context/anatomy.md\` \u2014 one-line description + token estimate per file. Read before opening a file.
+2. \`.spur/context/learnings.md\` \u2014 project conventions, decisions, preferences. Read before generating code.
+3. \`.spur/context/pitfalls.md\` \u2014 dated "do-not-repeat" entries. Read before generating code.
+4. \`.spur/context/buglog.md\` \u2014 historical bug log. Read before fixing a bug.
+5. \`.spur/context/memory.md\` \u2014 session log. Append one line per significant action.
+6. \`.spur/context/token-ledger.jsonl\` \u2014 auto-tracked by hooks; never hand-edit.
+
+If \`.spur/context/\` is absent, proceed normally. Never block work on its absence.
+`;
 function globalRulesRoot(context3) {
   const override = context3.env.SPUR_GLOBAL_RULES_DIR;
   return override !== undefined && override.length > 0 ? resolve5(context3.cwd, override) : join13(homedir5(), GLOBAL_RULES_DIR2);
@@ -70336,6 +70355,22 @@ function registerInitCommand(program2, context3) {
     const agentsDir = join13(context3.cwd, CLI_CONFIG.configDir, "agents");
     await context3.fs.ensureDir(agentsDir);
     await writeIfNew(context3, join13(agentsDir, ".gitkeep"), "", force, result);
+    const gitignorePath = join13(context3.cwd, ".gitignore");
+    const contextEntry = ".spur/context/";
+    if (await context3.fs.exists(gitignorePath)) {
+      const existing = await context3.fs.readFile(gitignorePath);
+      if (!existing.includes(contextEntry)) {
+        await context3.fs.writeFile(gitignorePath, `${existing.trimEnd()}
+
+# Spur indexed-context (machine-generated)
+${contextEntry}
+`);
+      }
+    } else {
+      await context3.fs.writeFile(gitignorePath, `# Spur indexed-context (machine-generated)
+${contextEntry}
+`);
+    }
     if (!minimal) {
       const configRoot = bundledConfigRoot();
       if (configRoot !== null) {
@@ -70351,6 +70386,14 @@ function registerInitCommand(program2, context3) {
         }
       }
     }
+    const agentsMdPath = join13(context3.cwd, "AGENTS.md");
+    if (await context3.fs.exists(agentsMdPath)) {
+      const existing = await context3.fs.readFile(agentsMdPath);
+      if (!existing.includes(INDEXED_CONTEXT_MARKER)) {
+        await context3.fs.writeFile(agentsMdPath, `${existing.trimEnd()}${INDEXED_CONTEXT_BLOCK}`);
+        result.created.push(agentsMdPath);
+      }
+    }
     const db2 = await context3.getDb();
     await new ArtifactDao(db2).record({ path: configPath, kind: "config" });
     const rulesSeeded = await seedGlobalRules(context3);