@gobing-ai/spur 0.2.2 → 0.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.2.2",
+    "version": "0.2.4",
     "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",
@@ -52,17 +52,21 @@
         "@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.7",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.3.7",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.3.7",
-        "@gobing-ai/ts-rule-engine": "^0.3.7",
-        "@gobing-ai/ts-runtime": "^0.3.7",
-        "@gobing-ai/ts-infra": "^0.3.7",
-        "@gobing-ai/ts-utils": "^0.3.7",
+        "@gobing-ai/ts-ai-runner": "^0.3.10",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.3.10",
+        "@gobing-ai/ts-infra": "^0.3.10",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.3.10",
+        "@gobing-ai/ts-rule-engine": "^0.3.10",
+        "@gobing-ai/ts-runtime": "^0.3.10",
+        "@gobing-ai/ts-utils": "^0.3.10",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "commander": "^14.0.3",
-        "zod": "4.4.3",
-        "figlet": "^1.11.0"
+        "figlet": "^1.11.0",
+        "zod": "4.4.3"
+    },
+    "dependencies": {
+        "@clack/prompts": "1.5.1",
+        "node-notifier": "10.0.1"
     }
 }

package/schemas/preset.schema.json

@@ -0,0 +1,54 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/gobing-ai/spur/schemas/preset.schema.json",
+    "title": "@gobing-ai/ts-rule-engine Preset",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "name": { "type": "string", "minLength": 1 },
+        "extends": { "type": "array", "items": { "type": "string" } },
+        "disable": { "type": "array", "items": { "type": "string" } },
+        "overrides": {
+            "type": "object",
+            "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                    "fix": {
+                        "type": "object",
+                        "additionalProperties": false,
+                        "properties": {
+                            "mode": { "enum": ["none", "suggest", "auto"] }
+                        }
+                    }
+                }
+            }
+        },
+        "extensions": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "resolvers": { "type": "array", "items": { "$ref": "#/$defs/relativeExtensionPath" } },
+                "evaluators": { "type": "array", "items": { "$ref": "#/$defs/relativeExtensionPath" } },
+                "fixers": { "type": "array", "items": { "$ref": "#/$defs/relativeExtensionPath" } },
+                "formatters": { "type": "array", "items": { "$ref": "#/$defs/relativeExtensionPath" } }
+            }
+        }
+    },
+    "$defs": {
+        "relativeExtensionPath": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Relative module path; absolute paths and '..' traversal are forbidden.",
+            "not": {
+                "anyOf": [
+                    { "pattern": "^[/\\\\]" },
+                    { "pattern": "^[A-Za-z]:[/\\\\]" },
+                    { "pattern": "(^|[/\\\\])\\.\\.([/\\\\]|$)" }
+                ]
+            }
+        }
+    }
+}

package/schemas/rule-file.schema.json

@@ -0,0 +1,49 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/gobing-ai/spur/schemas/rule-file.schema.json",
+    "title": "@gobing-ai/ts-rule-engine Rule File",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["rules"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "severity": { "enum": ["error", "warning", "info"] },
+        "rules": { "type": "array", "items": { "$ref": "#/$defs/rule" } }
+    },
+    "$defs": {
+        "rule": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["id", "evaluator"],
+            "properties": {
+                "id": { "type": "string" },
+                "description": { "type": "string" },
+                "enabled": { "type": "boolean" },
+                "severity": { "enum": ["error", "warning", "info"] },
+                "include": { "type": "array", "items": { "type": "string" } },
+                "exclude": { "type": "array", "items": { "type": "string" } },
+                "evaluator": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["type"],
+                    "properties": {
+                        "type": { "type": "string" },
+                        "config": { "type": "object", "additionalProperties": true }
+                    }
+                },
+                "fix": { "$ref": "#/$defs/fix" }
+            }
+        },
+        "fix": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "mode": { "enum": ["none", "suggest", "auto"] },
+                "replacement": { "type": "string" },
+                "params": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

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

@@ -0,0 +1,79 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/gobing-ai/spur/schemas/state-machine-workflow.schema.json",
+    "title": "@gobing-ai/ts-dual-workflow-engine State-machine Workflow",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["name", "initialState", "states", "transitions"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "state-machine" },
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "initialState": { "type": "string", "minLength": 1 },
+        "terminalStates": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "iterationBound": { "type": "integer", "exclusiveMinimum": 0 },
+        "vars": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": { "type": "string" }
+        },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } }
+            }
+        },
+        "states": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "onEnter": { "type": "array", "items": { "$ref": "#/$defs/action" } },
+                    "onExit": { "type": "array", "items": { "$ref": "#/$defs/action" } }
+                }
+            }
+        },
+        "transitions": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["from", "to"],
+                "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "trigger": { "type": "string" },
+                    "guard": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

package/schemas/transition-flow-workflow.schema.json

@@ -0,0 +1,78 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://github.com/gobing-ai/spur/schemas/transition-flow-workflow.schema.json",
+    "title": "@gobing-ai/ts-dual-workflow-engine Transition-flow Workflow",
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["kind", "name", "initialNode", "nodes", "edges"],
+    "properties": {
+        "$schema": { "type": "string" },
+        "kind": { "const": "transition-flow" },
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string" },
+        "description": { "type": "string" },
+        "initialNode": { "type": "string", "minLength": 1 },
+        "terminalNodes": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "iterationBound": { "type": "integer", "exclusiveMinimum": 0 },
+        "vars": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": { "type": "string" }
+        },
+        "env": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+                "allow": { "type": "array", "items": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } }
+            }
+        },
+        "nodes": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["id"],
+                "properties": {
+                    "id": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "type": { "enum": ["action", "gate", "parallel", "decision"] },
+                    "action": { "$ref": "#/$defs/action" }
+                }
+            }
+        },
+        "edges": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["from", "to"],
+                "properties": {
+                    "from": { "type": "string", "minLength": 1 },
+                    "to": { "type": "string", "minLength": 1 },
+                    "description": { "type": "string" },
+                    "condition": { "$ref": "#/$defs/guard" }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "action": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        },
+        "guard": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["kind"],
+            "properties": {
+                "kind": { "type": "string", "minLength": 1 },
+                "options": { "type": "object", "additionalProperties": true }
+            }
+        }
+    }
+}

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # DAO / database boundary rules — keep DB access centralized in packages/domain,
 # drizzle confined to schema authoring, and table DDL derived (not hand-written).
 # Enforces ADR-011 (ts-db consumed as a facade; tables are a single source of truth).

package/spur-cli/config/rules/migration/rg-dialect.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # One-off migration guard for the `regex` → `rg` (ripgrep) evaluator move.
 #
 # NOT part of recommended-pre-check — it is a transitional check, run on demand:

package/spur-cli/config/rules/quality/coverage-gate.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Coverage gate — per-file line coverage meets threshold from Bun's lcov output.
 # Absorbed from ts-libs/.spur/rules/quality/coverage-gate.yaml, re-scoped to
 # Spur's monorepo layout:

package/spur-cli/config/rules/quality/tsdoc-exports.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # TSDoc-on-exports — enforced by Spur's post-check gate.
 # Absorbed from ts-libs/.spur/rules/quality/tsdoc-exports.yaml.
 #

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # Recommended post-check preset — coverage gate and exported-symbol docs.
 # Use with: spur rule run --preset recommended-post-check --fail-on warning
 #

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # Recommended pre-check preset — portable rule categories from global install.
 # Use with: spur rule run --preset recommended-pre-check
 #

package/spur-cli/config/rules/rg-migration.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # rg-migration preset — on-demand guard for the regex → rg (ripgrep) evaluator move.
 #
 # Run explicitly when migrating rule files onto the `rg` evaluator:

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # [STRICT — opt-in] HTTP-client boundaries. Absorbed from
 # ts-libs/.spur/rules/typescript/external-api-boundaries.yaml. NOT in
 # recommended-pre-check: Spur has no central api-client seam yet, and the

package/spur-cli/config/rules/strict/rule-files-structural.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # [STRICT — opt-in] Meta-validation for local .spur/rules YAML. Absorbed from
 # ts-libs/.spur/rules/meta/rule-files-structural.yaml. The engine already
 # validates rule files on load, so this is a redundant pre-commit self-check;

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # [STRICT — opt-in] Runtime boundaries. Absorbed from
 # ts-libs/.spur/rules/typescript/runtime-boundaries.yaml. NOT in
 # recommended-pre-check: Spur consumes ts-runtime's ProcessExecutor/FileSystem

package/spur-cli/config/rules/strict-check.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/preset.schema.json"
 # Strict-check preset — opt-in hygiene rules absorbed from ts-libs but kept OUT
 # of the default recommended-pre-check gate (they need project-specific tuning
 # or are redundant with engine-level validation). Run explicitly:

package/spur-cli/config/rules/structure/protected-files.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Protected-file rules — secret detection and git/repo safety. Absorbed from
 # ts-libs/.spur/rules/structure/protected-files.yaml, re-scoped for apps/** +
 # packages/** + scripts/** (release/dev tooling is a prime secret-leak site).

package/spur-cli/config/rules/structure/test-focus-skip.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # No focused or skipped tests committed to the suite.
 # Part of the recommended-pre-check preset — caught BEFORE the suite runs so a
 # narrowed or disabled test never lands on a branch and silently shrinks

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

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Local override of the global structure/test-location.yaml — same relative path,
 # so it shadows the global copy (local wins in the layered merge) and the
 # `require-corresponding-test` rule is defined exactly once. Keeps `no-tests-dir`

package/spur-cli/config/rules/surface/check-cli-surface.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # CLI surface consistency — structural checks that every command file follows
 # the registerXxxCommand convention and that --json claims are backed by real
 # output serialization (toJson or JSON.stringify).

package/spur-cli/config/rules/typescript/bun-tooling.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Bun/tooling rules — Spur standardizes on Bun + bun:test (AGENTS.md "Stack").
 # Absorbed from ts-libs/.spur/rules/typescript/bun-only.yaml, re-scoped for the
 # apps/** + packages/** + scripts/** app-monorepo layout and the server's

package/spur-cli/config/rules/typescript/no-biome-suppressions.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # No Biome suppression comments in production source.
 # Absorbed from ts-libs/.spur/rules/typescript/no-biome-suppressions.yaml,
 # re-scoped to Spur's monorepo layout:

package/spur-cli/config/rules/typescript/no-debugger.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # No `debugger` statements in production source.
 # Part of the recommended-pre-check preset — a debugger left in shipped source
 # halts execution under an attached inspector and is never intended for commit.

package/spur-cli/config/rules/typescript/output-boundaries.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
 # Output boundary rules — terminal writes go through the output seam
 # (apps/cli/src/output.ts → ts-utils echo/echoError), never raw console/stdout.
 # Absorbed from ts-libs/.spur/rules/typescript/no-raw-output.yaml, re-scoped to

package/spur-cli/config/workflows/basic.yaml

@@ -1,3 +1,4 @@
+$schema: "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 # Canonical basic workflow: implement -> check -> fix until the check passes or the
 # iteration bound is exhausted. Authored for the @gobing-ai/ts-dual-workflow-engine
 # state-machine schema (initialState / states[].id / onEnter / top-level transitions).

package/spur-cli/config/workflows/feature-dev.yaml

@@ -0,0 +1,117 @@
+$schema: "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+"$schema": "@gobing-ai/ts-dual-workflow-engine/schemas/state-machine-workflow.schema.json"
+kind: state-machine
+name: feature-dev
+description: >
+  End-to-end feature-development loop: brainstorm → new-task → refine → implement →
+  check (autofix+spur-check) → fix (until clean) → verify. Agent-driven steps use
+  agent.run; the check gate uses rule.check for deterministic constraint gating.
+  The session latch (Q8) auto-continues agent sessions across steps — no per-step
+  `continue` wiring needed.
+iterationBound: 20
+initialState: brainstorm
+terminalStates:
+  - done
+  - failed
+vars:
+  taskId: TASK-ID
+
+states:
+  - id: brainstorm
+    description: Turn vague intent into a structured feature list via /rd3:dev-brainstorm
+    onEnter:
+      - kind: agent.run
+        options:
+          input: /rd3:dev-brainstorm
+
+  - id: new-task
+    description: Convert the feature list into a task file via /rd3:dev-new-task
+    onEnter:
+      - kind: agent.run
+        options:
+          input: /rd3:dev-new-task
+
+  - id: refine
+    description: Auto-refine the task definition via /rd3:dev-refine
+    onEnter:
+      - kind: agent.run
+        options:
+          input: /rd3:dev-refine ${vars.taskId} --focus all --auto
+
+  - id: implement
+    description: Implement + verify the task via /rd3:dev-run
+    onEnter:
+      - kind: agent.run
+        options:
+          input: /rd3:dev-run ${vars.taskId} --auto --verify
+
+  - id: check
+    description: >
+      Deterministic constraint gate via rule.check (recommended-pre-check preset).
+      Catches formatting, type, and structural issues before verification.
+    onEnter:
+      - kind: rule.check
+        options:
+          preset: recommended-pre-check
+          failOn: warning
+
+  - id: fix
+    description: >
+      Fix failures from the check gate. The latched agent session carries context
+      from the previous steps so the fixer knows what went wrong.
+    onEnter:
+      - kind: agent.run
+        options:
+          input: "Fix the failures from the previous check pass for task ${vars.taskId}; run /rd3:dev-fixall or /rd3:dev-unit as appropriate."
+
+  - id: verify
+    description: Cross-agent verification via /rd3:dev-verify
+    onEnter:
+      - kind: agent.run
+        options:
+          input: /rd3:dev-verify ${vars.taskId} --auto --fix all --force --channel codex/auto
+
+  - id: done
+    description: Terminal — feature implemented, checked, and verified successfully.
+
+  - id: failed
+    description: Terminal — check loop exhausted iterationBound without passing.
+
+transitions:
+  # Linear prefix: brainstorm → new-task → refine → implement → check
+  - from: brainstorm
+    to: new-task
+    description: Feature list captured; create the task file
+
+  - from: new-task
+    to: refine
+    description: Task file created; refine it
+
+  - from: refine
+    to: implement
+    description: Task refined; implement it
+
+  - from: implement
+    to: check
+    description: Implementation done; run the gate
+
+  # Check gate: action-ok guard FIRST so a passing check short-circuits to verify.
+  - from: check
+    to: verify
+    description: Check passed — advance to cross-agent verification
+    guard:
+      kind: action-ok
+
+  - from: check
+    to: fix
+    description: Check failed — route to a fix attempt
+
+  # Fix loop: always return to check after a fix attempt
+  - from: fix
+    to: check
+    description: Fix applied; re-run the gate
+
+  # Verify → done
+  - from: verify
+    to: done
+    description: Verification passed — workflow complete