@gobing-ai/spur 0.3.23 → 0.3.25

package/config/config.example.yaml

@@ -1,13 +1,18 @@
-# Spur project configuration for spur-new
-# Generated by `spur init`
+# Spur project configuration example
+# Seeded by `spur init` as ~/.config/spur/config.yaml on first run (never overwritten).
+# Copy / adapt into a project as `.spur/config.yaml`.
 
 $schema: "@gobing-ai/spur/schemas/spur-config.schema.json"
-version: "1"
-name: spur-new
+# Config schema version (string). Current recommended: "1.1".
+# "1" remains accepted; there is no hard migrator yet. Prefer "1.1" for new projects
+# so editors and operators know the file targets the ADR-033 + planning shape.
+version: "1.1"
+name: my-project
 
 # ── Portable bootstrap (consumed by @gobing-ai/ts-infra runNodeApplication) ──
 # Shared across spur and (future) spur-server. Keys map 1:1 to ts-infra's
 # LoggingOptions / TelemetryOptions / database / SchedulerOptions.
+# Not validated by spurConfigSchema (bootstrap is owned by runNodeApplication).
 bootstrap:
   logging:
     enabled: true
@@ -28,40 +33,65 @@ 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) ──
+# ── Spur app section (validated by spurConfigSchema in @gobing-ai/spur-config) ──
+# Server runtime (port/host/openBrowser) is env-backed via PORT/HOST — not a
+# project-config key. See design §2.2.
 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` is the executor selector for `--agent auto` when stage-registry
+  # routing does not apply (or as a fallback). Resolved as an executor name
+  # first, then a legacy agent name.
   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:
-  #   - name: omp
-  #     agent: omp
-  #   - name: omp-zai
-  #     agent: omp
-  #     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`.
+
+  # Named executor profiles (ADR-033 / 0343). Each pairs a canonical agent with
+  # an optional opaque model override and an explicit capability tier.
+  # Live tiers: cheap | standard | capable-1 | capable-2 | capable-3
+  # (1=low quality within capable, 3=high). DECLARE tier — inference never
+  # invents capable-2/3. Stage routing starts on the cheapest executor whose
+  # tier >= min_tier; same exact tier ties break by array order.
+  # Legacy bare `capable` is accepted at runtime as synonym for capable-1.
+  executors:
+    - name: omp
+      agent: omp
+      tier: standard
+    # - name: omp-zai
+    #   agent: omp
+    #   model: zai/glm-5.2
+    #   tier: standard
+    - name: grok
+      agent: grok
+      tier: capable-2
+    - name: claude
+      agent: claude
+      tier: capable-3
+    - name: codex
+      agent: codex
+      tier: capable-3
+    # - name: pi
+    #   agent: pi
+    #   tier: capable-1
+
+  # `default-by-phase` is a deprecated backward-compat shim (ADR-033). Prefer
+  # executor `tier` + stage-registry model_policy. When present, a matching
+  # phase mapping is still authoritative (fail-fast; no fall back to default)
+  # and shadows stage routing for that phase.
   # default-by-phase:
-  #   dev-run: omp-zai
+  #   dev-run: omp
   #   dev-review: claude
-  #   # dev-run: grok
+
+  # Declarative teams (feature M) — materialize with `spur team up <teamId>`.
+  # team:
+  #   demo:
+  #     name: "Demo Team"
+  #     work_dir: ~/path/to/project
+  #     members:
+  #       - executor: claude
+  #         purpose: "Lead — planning & review"
+  #       - executor: omp
+  #         purpose: "Implementer"
 
 rules:
   paths:
@@ -73,3 +103,16 @@ workflows:
 
 redaction:
   enabled: false
+
+# ── Planning (design §2.1 / §9) ──
+tasks:
+  active: docs/tasks
+  folders:
+    docs/tasks:
+      baseCounter: 0
+      label: Core
+  # severity:
+  #   L3.plan-format: off   # error | warning | off (known finding codes only)
+
+features:
+  dir: docs/features

package/config/templates/AGENTS.md

@@ -37,6 +37,7 @@ All product development work goes through the harness by default.
 | 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 |
+| Batch-refine tasks under a feature | `/sp:dev-refineall --feature <id> --auto` | Hand-looping `/sp:dev-refine` per WBS |
 | 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 |

package/config/workflows/docs-pipeline.yaml

@@ -65,6 +65,15 @@ states:
   - id: done
     description: Terminal — docs deliverable reviewed and recorded.
     onEnter:
+      # Done gate requires a PASS verdict artifact (no silent no-artifact allow).
+      # Docs-only pipelines do not run /sp:dev-verify; write a docs-only PASS stub
+      # then transition. Override path remains: --force-done --reason.
+      - kind: shell
+        options:
+          command: >
+            mkdir -p .spur/run &&
+            printf '%s\n' "{\"wbs\":\"${vars.wbs}\",\"verdict\":\"PASS\",\"source\":\"docs-pipeline\",\"requirements\":[{\"id\":\"docs-deliverable\",\"status\":\"MET\",\"evidence\":\"docs-pipeline record step\"}],\"acceptanceCriteria\":[],\"checks\":[{\"name\":\"docs-only\",\"status\":\"pass\",\"evidence\":\"docs-pipeline\"}]}"
+            > ".spur/run/${vars.wbs}-verdict.json"
       - kind: shell
         options:
           command: "${vars.spurBin} task update ${vars.wbs} done --no-lifecycle"

package/config/workflows/idea-pipeline.yaml

@@ -7,18 +7,24 @@
 # No state in this pipeline inlines another pipeline's state graph (no-nesting principle,
 # design §System Principles 4).
 #
-# Shape: start -> discovery -> feature-create -> ac-generate -> feature-check
-#          -> system-design (conditional: needs_design signal or --design)
+# Shape: start -> discovery -> idea-eval -> feature-create -> ac-generate -> feature-check
+#          -> system-design (conditional: needs_design signal)
 #          -> design-approval (taste HITL gate; not auto-clicked by --auto)
 #          -> decompose -> batch-create -> handoff
+#        (idea-eval rejection -> cancelled)
 #        (feature-check failure routes back to ac-generate; batch-create failure to decompose).
 #
 # Vars (passed as a JSON object via `--vars`):
 #   idea     — the idea text (required), e.g. --vars '{"idea":"add a --dry-run flag to dev-wrap"}'
 #   profile  — set --vars '{"profile":"auto"}' to skip objective HITL gates (feature-check, batch-create)
-#   design   — "auto" (default, signal-driven), "force" (--design), "skip" (--skip-design)
-#   design_approved — "true" only when the operator explicitly approved the design in-session;
+#   design   — "auto" (default, signal-driven) or "skip" (--skip-design). No force path.
+#              Unified: skip also means omit per-task Design in batch-create (scaffold only;
+#              refine fills later). Default: decompose must author batch item `design`.
+#   design_approved — "true" when taste pre-cleared (CLI --approve-taste or alias --design-approved);
 #              lets profile=auto route around the design-approval taste gate (default "false")
+#   idea_approved — "true" when taste pre-cleared (CLI --approve-taste or alias --idea-approved);
+#              lets profile=auto route around the idea-eval taste gate (default "false")
+#   CLI --approve-taste sets both design_approved and idea_approved to true.
 #   spurBin  — PATH-independent spur invocation (overridden by CLI at run start)
 #   agent    — agent for agent.run steps (default: omp)
 #
@@ -27,9 +33,9 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: idea-pipeline
-description: "Idea to feature + AC + task batch: discovery, feature-create, ac-generate, feature-check, system-design, decompose, batch-create, handoff"
-# Worst legal auto path with advertised caps: start/discovery/feature/ac plus 2 AC retries,
-# design, one design rejection, decompose plus 2 batch retries, handoff ≈22 transitions.
+description: "Idea to feature + AC + task batch: discovery, idea-eval, feature-create, ac-generate, feature-check, system-design, decompose, batch-create, handoff"
+# Worst legal auto path with advertised caps: start/discovery/idea-eval/feature/ac plus 2 AC
+# retries, design, one design rejection, decompose plus 2 batch retries, handoff ≈24 transitions.
 # Keep a small cushion so the explicit retry caps fail first, not the engine bound.
 iterationBound: 25
 initialState: start
@@ -42,9 +48,12 @@ vars:
   profile: "standard"
   design: "auto"
   design_approved: "false"
+  idea_approved: "false"
   featureId: ""
   __hitlAnswer: ""
   spurBin: "spur"
+  # R8 (0366): injected by WorkflowAppService.run(); stamps discovery artifact provenance.
+  __runId: ""
   agent: "omp"
   stepTimeoutMs: "600000"
 
@@ -62,7 +71,7 @@ states:
           command: "${vars.spurBin} agent doctor ${vars.agent}"
       - kind: shell
         options:
-          command: 'mkdir -p .spur/run && rm -f .spur/run/idea-ac-retry-count .spur/run/idea-decompose-retry-count .spur/run/idea-feature-id.txt .spur/run/idea-ac-content.md .spur/run/idea-ac-done.txt .spur/run/idea-task-batch.json .spur/run/idea-batch-create.done .spur/run/idea-batch-create.failed'
+          command: 'mkdir -p .spur/run && { [ -f .spur/run/idea-eval-report.md ] || [ -f .spur/run/idea-needs-design.json ]; } && { a=".spur/run/idea-archive/$(date +%Y%m%d-%H%M%S)"; mkdir -p "$a"; mv -f .spur/run/idea-eval-report.md "$a/" 2>/dev/null; mv -f .spur/run/idea-needs-design.json "$a/" 2>/dev/null; } ; rm -f .spur/run/idea-ac-retry-count .spur/run/idea-decompose-retry-count .spur/run/idea-feature-id.txt .spur/run/idea-ac-content.md .spur/run/idea-ac-done.txt .spur/run/idea-task-batch.json .spur/run/idea-batch-create.done .spur/run/idea-batch-create.failed'
 
   - id: discovery
     description: >
@@ -70,24 +79,41 @@ states:
       and record a design summary. The brainstorm ALWAYS records a design summary
       ("nothing is too simple" pattern). The brainstorm also emits a needs_design
       boolean signal written to .spur/run/idea-needs-design.json — this determines
-      whether the system-design state runs.
+      whether the system-design state runs. As its terminal artifact for the idea path,
+      brainstorm also emits the idea-evaluation report to .spur/run/idea-eval-report.md
+      (template: plugins/sp/skills/spur-dev/references/idea-evaluation.md).
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.agent}
-          input: "Run sp:brainstorm for the idea: ${vars.idea}. The skill owns the approach-generation, design summary, and `needs_design` signal criteria; emit .spur/run/idea-needs-design.json ({\"needs_design\": true|false}) and the design summary per the skill's `Design Approval Gate` and `The needs_design signal` sections."
+          input: "Run sp:brainstorm for the idea: ${vars.idea}. The skill owns the approach-generation, design summary, and `needs_design` signal criteria; emit .spur/run/idea-needs-design.json ({\"needs_design\": true|false}) and the design summary per the skill's `Design Approval Gate` and `The needs_design signal` sections. Also emit the idea-evaluation report to .spur/run/idea-eval-report.md per plugins/sp/skills/spur-dev/references/idea-evaluation.md (urgency/necessity 0–5, premises, pros/cons, alternatives, enhanced idea, recommendation). At the END of the report, append a provenance footer block of the exact form: `---\\nrun_id: ${vars.__runId}\\ngenerated_at: <RFC3339 timestamp>\\n---` (omit the footer only if run_id is empty)."
           timeoutMs: ${vars.stepTimeoutMs}
 
+  - id: idea-eval
+    description: >
+      HITL taste gate. Discovery has produced the idea-evaluation report
+      (.spur/run/idea-eval-report.md) with urgency/necessity scores, premises,
+      pros/cons, and a recommendation. The operator reviews and approves or
+      rejects. This gate is NOT auto-clicked by --auto (taste gate, like
+      design-approval). Only routes around when vars.idea_approved=true
+      (explicit prior approval).
+    pause: true
+    onEnter:
+      - kind: hitl.confirm
+        options:
+          prompt: "Review the idea evaluation report (.spur/run/idea-eval-report.md). Approve to create a feature, or reject to cancel? (Reject creates no feature.)"
+
   - id: feature-create
     description: >
       Create a feature via spur feature create, or select an existing feature id.
       The agent writes the feature id to .spur/run/idea-feature-id.txt for subsequent
-      states to read.
+      states to read. Prefer the enhanced idea from .spur/run/idea-eval-report.md as
+      context; do not overwrite vars.idea.
     onEnter:
       - kind: agent.run
         options:
           agent: ${vars.agent}
-          input: "Create a feature for the idea: ${vars.idea}. Use 'spur feature create \"<name>\" --json' to create it. Write the feature id to .spur/run/idea-feature-id.txt. If an existing feature is appropriate, use its id instead."
+          input: "Create a feature for the idea: ${vars.idea}. Read .spur/run/idea-eval-report.md if present for the enhanced idea and scores. Use 'spur feature create \"<name>\" --json' to create it. Write the feature id to .spur/run/idea-feature-id.txt. If an existing feature is appropriate, use its id instead."
           expectFile: .spur/run/idea-feature-id.txt
           timeoutMs: ${vars.stepTimeoutMs}
       - kind: file.read.into-var
@@ -138,7 +164,7 @@ states:
   - id: system-design
     description: >
       Dispatch sp:sys-architecture to produce the system design. This state runs
-      only when needs_design=true (or --design forces it). The agent creates ADR
+      only when needs_design=true (design=auto signal path). The agent creates ADR
       entries, architecture updates, and design satellites through constitution rules.
       The design-approval state follows (taste gate).
     onEnter:
@@ -230,13 +256,47 @@ transitions:
     guard:
       kind: always
 
-  # ── discovery -> feature-create ──
+  # ── discovery: auto-skip (profile=auto + idea_approved) OR enter idea-eval taste gate ──
+  # Declaration order: auto-skip FIRST (same pattern as system-design → design-approval).
+  # Without this edge, discovery always enters idea-eval (pause: true), rendering the prompt
+  # and persisting an avoidable pause before the in-state auto-skip guard can fire (0366 R4/R5).
   - from: discovery
     to: feature-create
-    description: Discovery complete — create or select a feature.
+    description: profile=auto AND idea_approved=true — skip idea-eval taste gate entirely.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto && test "${vars.idea_approved}" = true'
+  - from: discovery
+    to: idea-eval
+    description: Discovery complete — gate on idea evaluation taste decision.
     guard:
       kind: always
 
+  # ── idea-eval: auto-skip (profile=auto + idea_approved) OR approve/reject HITL ──
+  # Declaration order: auto-skip FIRST (same pattern as system-design → design-approval).
+  - from: idea-eval
+    to: feature-create
+    description: profile=auto AND idea_approved=true — skip idea-eval taste gate.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.profile}" = auto && test "${vars.idea_approved}" = true'
+  - from: idea-eval
+    to: feature-create
+    description: Idea evaluation approved — create or select a feature.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = yes'
+  - from: idea-eval
+    to: cancelled
+    description: Idea evaluation rejected or cancelled — no feature created.
+    guard:
+      kind: shell
+      options:
+        command: 'test "${vars.__hitlAnswer}" = no || test "${vars.__hitlAnswer}" = cancel'
+
   # ── feature-create -> ac-generate ──
   - from: feature-create
     to: ac-generate
@@ -250,14 +310,14 @@ transitions:
   # routes directly to the appropriate next state. Under interactive, the always fallback enters
   # the feature-check state whose onEnter hitl.confirm pauses for operator confirmation.
   #
-  # Auto-skip 1: pass + design route → system-design
+  # Auto-skip 1: pass + design route → system-design (design=auto + needs_design != false)
   - from: ac-generate
     to: system-design
     description: "profile=auto, check passed, design route — run system design."
     guard:
       kind: shell
       options:
-        command: 'test "${vars.profile}" = auto && ${vars.spurBin} feature check ${vars.featureId} --strict && (test "${vars.design}" = force || (test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" != false))'
+        command: 'test "${vars.profile}" = auto && ${vars.spurBin} feature check ${vars.featureId} --strict && test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" != false'
   # Auto-skip 2: pass + skip-design route → decompose
   - from: ac-generate
     to: decompose
@@ -297,7 +357,7 @@ transitions:
     guard:
       kind: shell
       options:
-        command: 'test "${vars.__hitlAnswer}" = yes && ${vars.spurBin} feature check ${vars.featureId} --strict && (test "${vars.design}" = force || (test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" != false))'
+        command: 'test "${vars.__hitlAnswer}" = yes && ${vars.spurBin} feature check ${vars.featureId} --strict && test "${vars.design}" = auto && test "$(jq -r .needs_design .spur/run/idea-needs-design.json 2>/dev/null)" != false'
   - from: feature-check
     to: decompose
     description: Feature check passed, skip-design route — go directly to decompose.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.23",
+    "version": "0.3.25",
     "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",
@@ -50,14 +50,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.11",
-        "@gobing-ai/ts-ai-runner": "^0.4.11",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.11",
-        "@gobing-ai/ts-infra": "^0.4.11",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.11",
-        "@gobing-ai/ts-rule-engine": "^0.4.11",
-        "@gobing-ai/ts-runtime": "^0.4.11",
-        "@gobing-ai/ts-utils": "^0.4.11",
+        "@gobing-ai/ts-db": "^0.4.14",
+        "@gobing-ai/ts-ai-runner": "^0.4.14",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.14",
+        "@gobing-ai/ts-infra": "^0.4.14",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.14",
+        "@gobing-ai/ts-rule-engine": "^0.4.14",
+        "@gobing-ai/ts-runtime": "^0.4.14",
+        "@gobing-ai/ts-utils": "^0.4.14",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/schemas/spur-config.schema.json

@@ -12,7 +12,7 @@
         },
         "version": {
             "type": "string",
-            "description": "Config schema version. Currently '1'."
+            "description": "Config schema version (string, not integer). Current recommended: '1.1' (ADR-033 executor tiers + planning blocks). '1' remains accepted for backward compatibility."
         },
         "name": {
             "type": "string",
@@ -129,15 +129,15 @@
                             },
                             "tier": {
                                 "type": "string",
-                                "enum": ["cheap", "standard", "capable"],
-                                "description": "Capability tier for stage-registry adaptive model routing (ADR-033). A stage starts on the cheapest eligible executor meeting its model_policy min_tier and escalates along the fallback chain on objective signals."
+                                "enum": ["cheap", "standard", "capable-1", "capable-2", "capable-3"],
+                                "description": "Capability tier for stage-registry adaptive model routing (ADR-033, 0343). Live values: cheap | standard | capable-1 | capable-2 | capable-3 (1=low output quality, 3=high within the capable band). A stage starts on the cheapest eligible executor meeting its model_policy min_tier. Bare legacy `capable` is accepted at runtime (zod preprocess → capable-1) during the deprecation window but is not part of this editor enum."
                             }
                         }
                     }
                 },
                 "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`.",
+                    "description": "DEPRECATED (ADR-033). Backward-compat map of dev phase (e.g. dev-run, dev-review) to executor selector. Prefer executor `tier` + stage-registry model_policy. When present, a matching phase mapping is still authoritative (fail-fast; no fall back to `default`) and shadows stage routing for that phase.",
                     "additionalProperties": {
                         "type": "string"
                     }

package/schemas/task-batch.schema.json

@@ -22,6 +22,18 @@
                 "type": "string",
                 "description": "R-numbered requirement items (R1. R2. …) — a referenceable list."
             },
+            "design": {
+                "type": "string",
+                "description": "Pre-filled ### Design body (WHAT/WHY decision record). Default for plan/decompose unless --skip-design."
+            },
+            "plan": {
+                "type": "string",
+                "description": "Pre-filled ### Plan body (ordered checklist)."
+            },
+            "acceptance_criteria": {
+                "type": "string",
+                "description": "Pre-filled ### Acceptance Criteria body (Gherkin or checklist)."
+            },
             "feature_id": {
                 "type": "string",
                 "pattern": "^[A-Z][1-9]*$",