@gobing-ai/spur 0.2.5 → 0.2.9

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.2.5",
+    "version": "0.2.9",
     "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",
@@ -49,16 +49,13 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/spur-app": "^0.1.0",
-        "@gobing-ai/spur-config": "^0.1.0",
-        "@gobing-ai/spur-domain": "^0.1.0",
-        "@gobing-ai/ts-ai-runner": "^0.3.11",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.3.11",
-        "@gobing-ai/ts-infra": "^0.3.11",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.3.11",
-        "@gobing-ai/ts-rule-engine": "^0.3.11",
-        "@gobing-ai/ts-runtime": "^0.3.11",
-        "@gobing-ai/ts-utils": "^0.3.11",
+        "@gobing-ai/ts-ai-runner": "^0.4.2",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.2",
+        "@gobing-ai/ts-infra": "^0.4.2",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.2",
+        "@gobing-ai/ts-rule-engine": "^0.4.2",
+        "@gobing-ai/ts-runtime": "^0.4.2",
+        "@gobing-ai/ts-utils": "^0.4.2",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/schemas/section-matrix.schema.json

@@ -0,0 +1,68 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://gobing.ai/spur/schemas/section-matrix.schema.json",
+    "title": "Section-Status-Matrix Schema",
+    "description": "Validates config/tasks/section-matrix.yaml — which sections are required/optional/forbidden per task status. Design §3.2. Authored for ts-runtime's loadStructuredConfig validator (supports properties/required/additionalProperties + $defs/$ref/enum; NOT patternProperties/uniqueItems).",
+    "type": "object",
+    "required": ["variants"],
+    "additionalProperties": false,
+    "properties": {
+        "$schema": {
+            "type": "string",
+            "description": "JSON Schema ref this file validates against (loadStructuredConfig reads it)."
+        },
+        "variants": {
+            "type": "object",
+            "description": "Map of template variant → per-status matrix. Variant names are extensible (user-defined variants allowed); each value is a variant.",
+            "additionalProperties": { "$ref": "#/$defs/variant" }
+        }
+    },
+    "$defs": {
+        "section": {
+            "enum": [
+                "Background",
+                "Requirements",
+                "Acceptance Criteria",
+                "Q&A",
+                "Design",
+                "Plan",
+                "Solution",
+                "Root Cause",
+                "Testing",
+                "Review",
+                "References",
+                "Notes",
+                "History"
+            ],
+            "description": "Canonical task section vocabulary (DD-08). Any other value is a typo."
+        },
+        "sectionList": {
+            "type": "array",
+            "items": { "$ref": "#/$defs/section" }
+        },
+        "entry": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "required": { "$ref": "#/$defs/sectionList" },
+                "optional": { "$ref": "#/$defs/sectionList" },
+                "forbidden": { "$ref": "#/$defs/sectionList" },
+                "gate": { "type": "boolean" }
+            }
+        },
+        "variant": {
+            "type": "object",
+            "additionalProperties": false,
+            "description": "A variant may declare any subset of the 7 canonical statuses (enumerated below); an unknown status key is rejected.",
+            "properties": {
+                "backlog": { "$ref": "#/$defs/entry" },
+                "todo": { "$ref": "#/$defs/entry" },
+                "wip": { "$ref": "#/$defs/entry" },
+                "testing": { "$ref": "#/$defs/entry" },
+                "blocked": { "$ref": "#/$defs/entry" },
+                "done": { "$ref": "#/$defs/entry" },
+                "cancelled": { "$ref": "#/$defs/entry" }
+            }
+        }
+    }
+}

package/schemas/spur-config.schema.json

@@ -103,7 +103,39 @@
             "properties": {
                 "default": {
                     "type": "string",
-                    "description": "Default coding agent (e.g. pi, claude, codex)."
+                    "description": "Default executor selector for `--agent auto` (resolved as an executor name first, then a legacy agent name e.g. pi, claude, codex)."
+                },
+                "executors": {
+                    "type": "array",
+                    "description": "Named executor profiles: each pairs a canonical agent with an optional model override. Referenced by name from `default` and `default-by-phase`.",
+                    "items": {
+                        "type": "object",
+                        "required": ["name", "agent"],
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Executor selector name (unique across the list)."
+                            },
+                            "agent": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Canonical coding agent (claude, codex, gemini, pi, opencode, antigravity-cli, openclaw, hermes, omp)."
+                            },
+                            "model": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Opaque model override passed straight to the agent (e.g. zai//glm-5.2). Applied only when the user passes no explicit --model."
+                            }
+                        }
+                    }
+                },
+                "default-by-phase": {
+                    "type": "object",
+                    "description": "Map of dev phase (e.g. dev-run, dev-review) to executor selector. A configured phase mapping is authoritative — a broken mapping fails fast and does NOT fall back to `default`.",
+                    "additionalProperties": {
+                        "type": "string"
+                    }
                 }
             }
         },
@@ -135,6 +167,44 @@
                     "description": "Enable sensitive-data redaction in CLI output."
                 }
             }
+        },
+        "tasks": {
+            "type": "object",
+            "description": "Task-folder registration (design §9). Absorbs the legacy docs/.tasks/config.json folders + base_counter concepts. Mirrors @gobing-ai/spur-config tasksConfigSchema (Zod is SSOT).",
+            "properties": {
+                "folders": {
+                    "type": "object",
+                    "description": "Map of task-folder path → folder config.",
+                    "additionalProperties": {
+                        "type": "object",
+                        "properties": {
+                            "baseCounter": {
+                                "type": "integer",
+                                "minimum": 0,
+                                "description": "WBS base counter for new tasks in this folder. Default 0."
+                            },
+                            "label": {
+                                "type": "string",
+                                "description": "Human-readable folder label."
+                            }
+                        }
+                    }
+                },
+                "active": {
+                    "type": "string",
+                    "description": "Default folder for `spur task create`. Default: docs/tasks."
+                }
+            }
+        },
+        "features": {
+            "type": "object",
+            "description": "Feature directory location (design §9). Mirrors @gobing-ai/spur-config featuresConfigSchema (Zod is SSOT).",
+            "properties": {
+                "dir": {
+                    "type": "string",
+                    "description": "Feature files directory. Default: docs/features."
+                }
+            }
         }
     }
 }

package/schemas/state-machine-workflow.schema.json

@@ -35,6 +35,10 @@
                 "properties": {
                     "id": { "type": "string", "minLength": 1 },
                     "description": { "type": "string" },
+                    "pause": {
+                        "type": "boolean",
+                        "description": "When true, the engine pauses the run at this state for HITL (E3); resume with `spur workflow continue`."
+                    },
                     "onEnter": { "type": "array", "items": { "$ref": "#/$defs/action" } },
                     "onExit": { "type": "array", "items": { "$ref": "#/$defs/action" } }
                 }

package/schemas/task-batch.schema.json

@@ -0,0 +1,53 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/gobing-ai/spur/schemas/task-batch.schema.json",
+    "title": "Task Batch Create Input",
+    "description": "Editor/CI aid for spur task batch-create --file input — the contract gating LLM decomposition output before any write. Every item is validated; any failure means nothing is written. RUNTIME SOURCE OF TRUTH is the Zod taskBatchSchema in @gobing-ai/spur-domain (packages/domain/src/planning/schema.ts); keep this file in sync with it.",
+    "type": "array",
+    "minItems": 1,
+    "items": {
+        "type": "object",
+        "required": ["name"],
+        "properties": {
+            "name": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Task title — used in slug and heading."
+            },
+            "background": {
+                "type": "string",
+                "description": "Context and motivation for the task."
+            },
+            "requirements": {
+                "type": "string",
+                "description": "R-numbered requirement items (R1. R2. …) — a referenceable list."
+            },
+            "feature_id": {
+                "type": "string",
+                "pattern": "^[A-Z][1-9]*$",
+                "description": "Feature ID for traceability and Goal→Background derivation (DD-14)."
+            },
+            "parent_wbs": {
+                "type": "string",
+                "pattern": "^\\d{4}$",
+                "description": "Parent WBS for sub-task grouping (the single sub-task convention, X02)."
+            },
+            "priority": {
+                "type": "string",
+                "enum": ["P0", "P1", "P2", "P3"],
+                "description": "Task priority aligned with the feature priority scale."
+            },
+            "tags": {
+                "type": "array",
+                "items": { "type": "string" },
+                "description": "Free-form filtering tags."
+            },
+            "template": {
+                "type": "string",
+                "enum": ["feature-impl", "issue", "review", "meta"],
+                "description": "Template variant for section structure (default: the standard template)."
+            }
+        },
+        "additionalProperties": false
+    }
+}

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

@@ -28,9 +28,33 @@ bootstrap:
   scheduler:
     enabled: false # CLI is run-once; no scheduler
 
+# ── Server runtime (env-backed: PORT / HOST override; consumed by spur serve) ──
+server:
+  port: 3000          # env: PORT
+  host: localhost     # env: HOST
+  openBrowser: true   # spur serve only; skip with --no-open
+  webDistPath: null   # S5 local static asset path
 # ── Spur app section (validated by a local zod schema — UNCHANGED keys) ──
 agent:
-  default: pi
+  # `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
+  # Named executor profiles: pair a canonical agent with an optional opaque model
+  # override. Referenced by name from `default` and `default-by-phase`.
+  # executors:
+  #   - name: omp
+  #     agent: omp
+  #   - name: omp-zai
+  #     agent: omp
+  #     model: zai//glm-5.2
+  #   - name: claude
+  #     agent: claude
+  # 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
 
 rules:
   paths:

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

@@ -0,0 +1,54 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Config-loading ownership boundary — `.spur/config.yaml` has exactly ONE loader:
+# `loadSpurConfig` (+ helpers) in @gobing-ai/spur-config (ADR-027). Every other surface
+# consumes the typed, validated result through that facade; none parses or schema-validates
+# the config itself. Before ADR-027 there were five parallel loaders (CLI structured-config,
+# app raw-yaml, CLI resolveConfigFile, server inline literals, server JSONC read) — the drift
+# behind the phase-folder bugs. These rules block that class from returning.
+#
+# NOTE: a bare `config.yaml` string is NOT banned — `CLI_CONFIG.configFile`, the init seeder,
+# and existence checks legitimately name the path. The anti-pattern is *parsing config into a
+# typed shape outside the facade*, caught precisely below (no false positives on frontmatter /
+# workflow YAML parsing, which share `parseYaml` for unrelated inputs). Pattern is the ripgrep
+# dialect (no lookbehind/backrefs).
+rules:
+  - id: structured-config-loader-only-in-config
+    description: >
+      ts-runtime's `loadStructuredConfig` is the schema-validating config loader and may be
+      called ONLY inside packages/config — it is the single implementation behind
+      @gobing-ai/spur-config's `loadSpurConfig`/`loadStructuredSpurConfig`. Any other surface
+      must consume the typed result through that facade, never re-invoke the raw loader (that
+      was the CLI-vs-app divergence ADR-027 removed). (ADR-027)
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "loadStructuredConfig\\("
+    include:
+      - "apps/**/src/**/*.ts"
+      - "packages/**/src/**/*.ts"
+    exclude:
+      - "packages/config/src/**"
+      - "**/node_modules/**"
+      - "**/tests/**"
+
+  - id: no-legacy-tasks-config-jsonc
+    description: >
+      The rd3 `docs/.tasks/config.jsonc` config location is retired — task/feature folders come
+      from `.spur/config.yaml` via the spur-config facade. Do not read, reference, or recreate it
+      (the server folders endpoint regressed onto it once). Matches code-context uses, not prose
+      that merely names the retired path. (ADR-027)
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        # Require a code-context prefix ( = ( , quote join readFile ) before the literal so a
+        # comment noting the path is retired does not trip the rule. ripgrep dialect.
+        pattern: "[=(,]\\s*['\"`][^'\"`]*config\\.jsonc['\"`]|['\"`][^'\"`]*\\.tasks/config['\"`]"
+    include:
+      - "apps/**/src/**/*.ts"
+      - "apps/**/src/**/*.tsx"
+      - "packages/**/src/**/*.ts"
+    exclude:
+      - "**/node_modules/**"
+      - "**/tests/**"

package/spur-cli/config/rules/boundary/planning-folder-hardcode.yaml

@@ -0,0 +1,46 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Planning-folder hardcode boundary — phase folders (rd3:tasks heritage) require
+# that every task/feature folder be DERIVED from `.spur/config.yaml` (tasks.active
+# / features.dir), never written as an inline `docs/tasks` / `docs/features` string.
+# A hardcode makes tasks created in a non-active phase folder (e.g. docs/tasks2)
+# invisible to the hardcoded surface — the class of bug behind the false-positive
+# write-guard deny and the server/web/team-service folder drift.
+#
+# The ONLY sanctioned literal lives in @gobing-ai/spur-config as DEFAULT_TASKS_DIR /
+# DEFAULT_FEATURES_DIR. Everything else derives via resolvePlanningFolders (app),
+# loadTaskFoldersConfig (CLI), or the task.folders endpoint (web). Pattern is the
+# ripgrep dialect (no lookbehind/backrefs).
+include:
+  - "apps/**/src/**/*.ts"
+  - "apps/**/src/**/*.tsx"
+  - "packages/**/src/**/*.ts"
+exclude:
+  - "**/node_modules/**"
+  - "**/tests/**"
+  # The single source of truth — the literal is allowed to exist here.
+  - "packages/config/src/index.ts"
+  # The web board's documented first-paint placeholder (BOOTSTRAP_FOLDER), replaced
+  # on mount by the task.folders endpoint; the browser bundle stays config-dep-free.
+  - "apps/web/src/modules/task-kanban/KanbanBoard.tsx"
+  # Cloudflare Workers path: context.ts imports DEFAULT_* from the CF-safe core entry of
+  # @gobing-ai/spur-config (plain string constants, no yaml/node:fs). No inline literal
+  # remains — the former exception narrowed to a core-only import (ADR-027).
+  # The folders endpoint derives its response from ctx.planningFolders(), never from a
+  # hardcoded path or the retired docs/.tasks/config.jsonc.
+rules:
+  - id: no-hardcoded-planning-folder
+    description: >
+      Do not hardcode the `docs/tasks` or `docs/features` folder path as a string
+      literal used as a VALUE (assignment, argument, fallback, or property). Phase
+      folders mean the active/registered folders come from `.spur/config.yaml` —
+      derive them via resolvePlanningFolders (app), loadTaskFoldersConfig (CLI), or
+      the DEFAULT_TASKS_DIR/DEFAULT_FEATURES_DIR constants in @gobing-ai/spur-config.
+      A literal silently ignores phase folders and loses tasks created outside the
+      active one. (Matches only code-context uses, not comments mentioning the path.)
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        # Require a code-context prefix ( = ?? ( , : ) before the literal so prose
+        # comments that merely name the path do not trip the rule. ripgrep dialect.
+        pattern: "[=(,:]\\s*['\"`]docs/(tasks|features)2?['\"`]|fs\\.resolve\\(\\s*['\"`]docs['\"`]\\s*,\\s*['\"`](tasks|features)['\"`]"

package/spur-cli/config/rules/recommended-pre-check.yaml

@@ -3,11 +3,12 @@ $schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # Use with: spur rule run --preset recommended-pre-check
 #
 # Runs BEFORE tests (test-pre-check). TypeScript quality, structural, DB
-# boundary, and CLI surface consistency rules. TSDoc exports run in post-check
-# alongside coverage-gate.
+# boundary, CLI surface consistency, and UI seam-boundary rules. TSDoc exports
+# run in post-check alongside coverage-gate.
 name: recommended-pre-check
 extends:
   - typescript
   - structure
   - boundary
   - surface
+  - ui

package/spur-cli/config/rules/structure/test-location.yaml

@@ -33,13 +33,23 @@ rules:
         requireCorrespondingTest: true
     include:
       - "packages/**/src/**/*.ts"
+      - "packages/**/src/**/*.tsx"
       - "apps/**/src/**/*.ts"
+      - "apps/**/src/**/*.tsx"
+
     exclude:
       - "**/index.ts"
+      - "**/*.tsx"
       - "**/*.d.ts"
       - "**/types.ts"
       - "**/schema/**"
+      - "**/schema.ts"
       - "**/migrations.ts"
       - "**/db.ts"
+      ## Entity declarations — contracts are transport DTOs tested by the single contract.test.ts
+      - "packages/contracts/src/**"
       - "**/node_modules/**"
       - "**/tests/**"
+      ## pure re-export for UI components
+      - "apps/web/src/ui.ts"
+      - "apps/web/src/modules/config.ts"

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

@@ -0,0 +1,43 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Enforce draining React's scheduler before tearing down happy-dom in web tests.
+#
+# WHY: React 19's scheduler defers render work onto a macrotask (MessageChannel →
+# performWorkUntilDeadline). A web test's `afterAll` that calls
+# `GlobalRegistrator.unregister()` directly removes `globalThis.window` while that
+# work may still be queued; the deferred callback then fires with no `window` and
+# throws `ReferenceError: window is not defined`, surfacing as bun's "Unhandled
+# error between tests". It is timing-dependent — a fast dev box drains the queue
+# before teardown, a loaded CI runner does not — so it passes locally and fails
+# only in CI. (Real incident: task-detail.test.tsx, 1 CI-only error.)
+#
+# FIX: route teardown through the shared `teardownHappyDom` helper
+# (apps/web/tests/happy-dom.ts), which unmounts, yields macrotasks so the scheduler
+# drains while `window` still exists, and only then unregisters. Use it as the
+# `afterAll` body in every web React test:  `afterAll(teardownHappyDom);`
+#
+# The helper itself is the one legitimate caller of `unregister()` and is excluded.
+# Severity is `warning`: convert to the helper or justify, not an automatic block.
+include:
+  - "apps/web/tests/**/*.test.ts"
+  - "apps/web/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  # The shared teardown helper is the sanctioned place that calls unregister().
+  - "apps/web/tests/happy-dom.ts"
+
+rules:
+  - id: happy-dom-teardown-via-helper
+    description: >
+      Do not call `GlobalRegistrator.unregister()` directly in a web test. React 19
+      schedules render work on a macrotask; unregistering happy-dom before it drains
+      removes `window` and throws "window is not defined" — a CI-only, timing-
+      dependent failure. Use `afterAll(teardownHappyDom)` from apps/web/tests/happy-dom.ts,
+      which drains the scheduler before tearing the DOM down.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match the call anywhere on a line (it usually sits inside an afterAll body),
+        # so both `await GlobalRegistrator.unregister()` and a bare call are caught.
+        pattern: "GlobalRegistrator\\.unregister\\("

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

@@ -0,0 +1,71 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Guard against process-global module-mock leakage in bun:test.
+#
+# WHY: Bun's `mock.module()` installs a process-wide override that
+# `mock.restore()` does NOT revert (per Bun docs). A `mock.module()` in one
+# test file therefore leaks into every later file in the same `bun test`
+# process. Because Bun discovers test files in filesystem order (sorted on
+# macOS, inode order on Linux/CI), this surfaces as tests that pass locally
+# but fail only in CI — exactly the 51-failure regression in
+# apps/cli/tests/commands/{command,content-command-modules}.test.ts.
+#
+# SCOPE: only FIRST-PARTY mocks (relative `./`/`../` or `@gobing-ai/*` specifiers)
+# are flagged. A `mock.module()` only leaks harmfully when another test file
+# statically imports the SAME module expecting the real implementation — which only
+# happens for the project's own modules. Third-party module swaps (e.g. `mermaid`,
+# `@dnd-kit/core`, `@uiw/react-md-editor`) are never asserted-real by another test,
+# so they cannot cause this failure and are intentionally NOT flagged.
+#
+# FIX: prefer `spyOn(namespaceImport, 'export')` over `mock.module()` — spyOn IS
+# reverted by `mock.restore()`/`mockRestore()` in afterEach, so it cannot leak.
+# CAVEAT: spyOn does NOT work on a callable Proxy (e.g. the oRPC `api` client) —
+# property access regenerates the method, bypassing the spy and hitting the network.
+# For such modules `mock.module()` is the only working option; keep it file-local and
+# ensure no later test statically imports the real module (dynamic `await import()`
+# in the reader is immune). This rule is a `warning`, not an `error`: treat a hit as
+# "justify or convert," not an automatic block.
+include:
+  # Both .ts and .tsx — the React component tests (.tsx) are where mock.module is
+  # most common, and they were previously invisible to this rule (the original globs
+  # only matched .test.ts), letting a cross-file leak ship undetected.
+  - "apps/**/tests/**/*.test.ts"
+  - "apps/**/tests/**/*.test.tsx"
+  - "packages/**/tests/**/*.test.ts"
+  - "packages/**/tests/**/*.test.tsx"
+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.)
+  - "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/task-kanban/task-detail.test.tsx"
+
+rules:
+  - id: no-leaky-mock-module
+    description: >
+      Avoid `mock.module()` of a first-party module (relative path or @gobing-ai/*)
+      in bun:test files — it is process-global, is not reverted by mock.restore(),
+      and leaks into any later test file that statically imports the same module,
+      causing CI-only, file-order-dependent failures. Prefer spyOn() on a namespace
+      import (`import * as ns; spyOn(ns, 'fn')`), restored in afterEach. If the target
+      is a callable Proxy (e.g. the oRPC api client) spyOn cannot intercept it; keep
+      the mock.module() file-local and ensure readers use dynamic `await import()`.
+      Third-party module swaps are not flagged (they never leak harmfully).
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # First-party only: line-anchored `mock.module(` whose specifier starts with a
+        # relative path (`.`) or the `@gobing-ai/` scope. Third-party bare specifiers
+        # (mermaid, @dnd-kit/*, @uiw/*) are excluded — they cannot cause the leak. The
+        # line anchor keeps prose mentions in comments from false-positiving.
+        pattern: "^\\s*mock\\.module\\(\\s*['\"](\\.|@gobing-ai/)"
+        flags: "m"

package/spur-cli/config/rules/ui/ui-import-boundary.yaml

@@ -0,0 +1,51 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# UI import + class-leak boundary rules — keep `apps/web/src/ui.ts` the single UI
+# import seam and keep daisyUI component classes confined to `components/ui/`.
+# Both rules are `error` (promoted from warning in Task 0104) and wired into the
+# recommended-pre-check preset, so regressions are blocked at the standing gate.
+# Two distinct seams: `ui.ts` is the single IMPORT seam (Rule A); `components/ui/`
+# is the single daisyUI-CLASS-authoring seam (Rule B) — a re-export barrel cannot
+# hold a className, so Rule B alone keeps the `components/ui/**` exclude.
+# Evaluators proven in boundary/dao-boundary.yaml.
+rules:
+  - id: ui-import-seam-only
+    description: >
+      Third-party UI libraries (daisyui, @uiw/react-md-editor, future UI libs)
+      may only be imported through the `apps/web/src/ui.ts` seam. Everything else
+      in apps/web — including the wrappers under `components/ui/` — imports from
+      `@/ui`, never the raw library. `ui.ts` is the single UI import point.
+    severity: error
+    evaluator:
+      type: forbidden-import
+      config:
+        forbidden:
+          - specifier: "daisyui"
+          - specifier: "@uiw/react-md-editor"
+        scope:
+          include:
+            - "apps/web/src/**/*.ts"
+            - "apps/web/src/**/*.tsx"
+          exclude:
+            - "apps/web/src/ui.ts"
+            - "**/tests/**"
+            - "**/node_modules/**"
+
+  - id: no-daisyui-class-leak
+    description: >
+      daisyUI COMPONENT classes (btn, card, badge, modal, ...) must not appear in
+      className strings outside `apps/web/src/components/ui/`. Layout/utility classes
+      (flex, grid, gap-*, p-*) are unaffected — the pattern is anchored to a
+      className context and word-bounded to the component-class allowlist only.
+      `components/ui/` stays excluded: it is the sanctioned class-authoring site.
+    severity: error
+    evaluator:
+      type: rg
+      config:
+        pattern: "className=[\"'][^\"']*\\b(btn|card|badge|modal|menu|navbar|drawer|tabs|alert|dropdown|collapse|join|tooltip|loading|select|checkbox|toggle)\\b"
+    include:
+      - "apps/web/src/**/*.tsx"
+    exclude:
+      - "apps/web/src/components/ui/**"
+      - "apps/web/src/ui.ts"
+      - "**/tests/**"
+      - "**/node_modules/**"