@gobing-ai/spur 0.3.47 → 0.3.49

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.3.47",
+            "version": "0.3.49",
             "name": "sp",
             "source": "./plugins/sp",
             "description": "Spur - my harness toolkits"

package/config/config.example.yaml

@@ -1,15 +1,18 @@
 # Spur project configuration example
-# Seeded by `spur init` as ~/.config/spur/config.yaml on first run (never overwritten).
+# 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"
 # 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.
+# "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) ──
+# ── 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).
@@ -33,46 +36,100 @@ bootstrap:
   scheduler:
     enabled: false # CLI is run-once; no scheduler
 
-# ── Spur app section (validated by spurConfigSchema in @gobing-ai/spur-config) ──
+# ── 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` when stage-registry
-  # routing does not apply (or as a fallback). Resolved as an executor name
-  # first, then a legacy agent name.
-  default: omp
+  # `default` is the role used for `--agent auto` when the caller declares
+  # nothing (task 0542 R2 — the value domain moved from executor names to
+  # roles). A role id selects its tier's cheapest eligible executor; a
+  # configured executor name still resolves during the transition with a
+  # one-time warning (shim agent-default-executor); any other value fails
+  # naming both accepted sets.
+  default: coder
+
+  # Role → tier map (SSOT: DEFAULT_AGENT_ROLES in packages/config, task 0572 /
+  # ADR-061; plugins/sp/references/roles.md is a parity-gated projection).
+  # Resolution: role → tier → cheapest USABLE executor whose tier >= the role's
+  # tier, climbing the ladder across gaps. Declare at least one usable executor
+  # at or above each rung or that role fails loudly at dispatch:
+  #   scribe=cheap · coder=standard · reviewer=capable-1 · planner=capable-2
+  # Stage floors (stage-registry model_policy): changelog=cheap;
+  # implement/test/wrap/review/refine/brainstorm=standard;
+  # verify/dogfood=capable-1; plan=capable-2. A stage's fallback ladder
+  # (auth / resource-exhaustion / gate-fail) only advances when a higher rung
+  # has a usable executor — an empty rung turns a quota failure into a hang.
+  #
+  # Optional per-project override (0572): re-tier / re-stage a KNOWN role only —
+  # the vocabulary is closed; a config naming any other key fails at config load
+  # naming the accepted four. Per-field merge over the defaults (restate only
+  # what you override; a role you omit keeps its default wholesale):
+  # roles:
+  #   reviewer:
+  #     tier: capable-2        # e.g. pin review work one rung higher
+  #   coder:
+  #     stages: [implement]    # e.g. stop folding test/wrap into coder
 
   # 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).
+  #   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 (ADR-033 / 0343). Each pairs a canonical agent with
-  # an optional opaque model override and an explicit capability tier.
+  # an explicit model override and an explicit capability tier.
+  # `model` is pinned on every entry: omitting it defers to the agent CLI's own
+  # default, which drifts with CLI upgrades and account state — pin what your
+  # CLI would resolve today (`grok models`, omp config.yml modelRoles.default,
+  # ~/.codex/config.toml, ~/.claude.json). The ids below are working examples,
+  # not vendor defaults — re-pin for your accounts.
+  #
+  # Pairing philosophy (operator guidance, 2026-08): a `native` pair — a vendor's
+  # model served by that vendor's own CLI (gpt-5.6-* via codex, claude-*-5 via
+  # claude, grok-4.6 via grok, gemini-3.x via agy) — consistently outperforms the
+  # same model routed through a third-party CLI, and belongs at the capable rungs.
+  # `portable` models (glm-5.x, deepseek-v4-*, …) are provider-agnostic and best
+  # carried by omp or pi at the cheap/standard rungs. The ladder below mixes both
+  # classes on purpose; measure pairings with the history plane before promoting
+  # a portable model into a capable rung.
   # 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:
+    # cheap rung is optional: with none declared, scribe-role work starts one
+    # rung up at the cheapest standard executor. Add one when transcript-heavy
+    # mechanical commands (changelog/gitmsg/handover) get noisy on cost.
+    # - name: minimax
+    #   agent: omp
+    #   model: minimax/MiniMax-M3
+    #   tier: cheap
     - name: omp
       agent: omp
+      model: opencode/deepseek-v4-flash
       tier: standard
     # - name: omp-zai
     #   agent: omp
     #   model: zai/glm-5.2
     #   tier: standard
+    - name: pi
+      agent: pi
+      model: "k3"
+      tier: capable-1
     - name: grok
       agent: grok
+      model: grok-4.6
       tier: capable-2
     - name: claude
       agent: claude
+      model: k3
       tier: capable-3
     - name: codex
       agent: codex
+      model: gpt-5.6
       tier: capable-3
-    # - name: pi
-    #   agent: pi
-    #   tier: capable-1
 
   # `default-by-phase` is a REMOVED (0452). Prefer
   # executor `tier` + stage-registry model_policy. When present, a matching
@@ -92,6 +149,13 @@ agent:
   #         purpose: "Lead — planning & review"
   #       - executor: omp
   #         purpose: "Implementer"
+  #       # Role is the primary axis (0543): a role-only member resolves an
+  #       # executor through the tier ladder at materialization; the resolved
+  #       # executor and the role are both recorded on the materialized spec.
+  #       - role: reviewer
+  #       - role: coder
+  #         executor: omp
+  #         purpose: "Pinned executor, role recorded alongside (pin beats policy)"
 
 rules:
   paths:
@@ -116,3 +180,18 @@ tasks:
 
 features:
   dir: docs/features
+
+# ── History (task 0549 — completion-triggered refresh) ──
+# Opt-in: when work completes (task → done, pipeline run reaching
+# terminal status), enqueue ONE coalesced `history.refresh` job on the
+# embedded job queue (never inline). Bursts inside debounce_ms join the
+# pending job; the covered window spans all completions. The job reuses
+# `spur history daily` semantics (import-all fan-out with per-source
+# isolation + analyze + artifact write) and is consumed by `spur serve`'s
+# job worker. Debounce default 600000 ms (10 min) follows
+# docs/tasks4/0548-import-cost-measurement.md (steady-state all-fanout
+# import ≈ 20.6 s; 10 min comfortably bounds burst coalescing).
+# history:
+#   refresh:
+#     on_completion: false # set true to enable; disable with no code edits
+#     debounce_ms: 600000  # coalescing window; floor 1000 ms

package/config/transition-shims.json

@@ -0,0 +1,33 @@
+{
+    "note": "Transition-shim manifest (task 0541, feature B2). Each entry records one compatibility path marked @transition-shim(<id>) in source. Every field is required. The gate (bun run transition-shim-check, inside `spur-check`) is two-sided: an unregistered marker fails, and a listed entry whose marker is gone fails. Emptying this file is the definition of the transition being complete (docs/04_DESIGN.md §2.5). Removal conditions must be objectively checkable against the repository, not 'when convenient'. Shims are registered by the tasks that create them (0536/0537/0538/0542).",
+    "entries": [
+        {
+            "id": "agent-bare-binary-name",
+            "wbs": "0536",
+            "file": "packages/app/src/services/agent-service.ts",
+            "keepsWorking": "a bare coding-agent binary name (codex, omp, claude with no matching agent.executors entry) remains a valid --agent value during the role transition, with a one-time warning emitted by warnBareBinaryOnce",
+            "removalCondition": "no bare-binary --agent value remains in docs/, config/workflows/, or plugins/sp/ (scan for --agent <binary-name> usages against agent.executors names)"
+        },
+        {
+            "id": "spec-without-executor-field",
+            "wbs": "0537",
+            "file": "apps/cli/src/commands/agent.ts",
+            "keepsWorking": "a pre-existing agent spec carrying only type (no executor field) still drains: --agent <specId> falls back to the spec's coding-agent type instead of resolving a missing executor",
+            "removalCondition": "every spec under .spur/agents/ records an executor field (scan .spur/agents/*.yaml for the key; re-materialize the demo team first)"
+        },
+        {
+            "id": "agent-flag-spec-id",
+            "wbs": "0542",
+            "file": "apps/cli/src/commands/agent.ts",
+            "keepsWorking": "a team spec id passed to --agent <spec-id> still addresses the spec and drives the drain path, warned once by warnAgentSpecIdOnce; --spec <id> is the canonical carrier",
+            "removalCondition": "no --agent <spec-id> usage remains in config/workflows/, plugins/sp/, or docs/ (scan for --agent values that match a .spur/agents/ spec id)"
+        },
+        {
+            "id": "agent-default-executor",
+            "wbs": "0542",
+            "file": "packages/app/src/services/agent-service.ts",
+            "keepsWorking": "a configured executor name in agent.default still resolves during the transition, warned once by warnAgentDefaultExecutorOnce; the value domain moved to roles (recommended default: coder)",
+            "removalCondition": "no agent.default value names an agent.executors entry (scan .spur/config.yaml and config/config.example.yaml against the agent.executors names)"
+        }
+    ]
+}

package/config/workflows/basic.yaml

@@ -80,6 +80,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-fixall "${vars.qualityGateCmd}"
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: done

package/config/workflows/docs-pipeline.yaml

@@ -67,6 +67,8 @@ states:
         options:
           agent: ${vars.agent}
           # Pure slash only (ADR-043). Do not bolt docs-only prose onto the input line.
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           input: /sp:dev-run --mode implement ${vars.wbs} --auto
           timeoutMs: ${vars.stepTimeoutMs}
           # Fail a silent no-op draft (same empty-implement class as task-pipeline R3).

package/config/workflows/feature-dev.yaml

@@ -84,6 +84,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-brainstorm --feature ${vars.featureId}
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: plan
@@ -95,6 +97,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-plan --feature ${vars.featureId}
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           timeoutMs: ${vars.stepTimeoutMs}
 
   # Two pure-slash execute hops so vars.profile actually controls --auto (ADR-043).
@@ -109,6 +113,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-runall --feature ${vars.featureId} --auto
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: execute-tasks
@@ -120,6 +126,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-runall --feature ${vars.featureId}
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: feature-verify

package/config/workflows/idea-pipeline.yaml

@@ -108,6 +108,8 @@ states:
         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/${vars.__runId}-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/${vars.__runId}-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)."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           expectFile: .spur/run/${vars.__runId}-idea-eval-report.md
           timeoutMs: ${vars.stepTimeoutMs}
 
@@ -140,6 +142,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Create a feature for the idea: ${vars.idea}. Read .spur/run/${vars.__runId}-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/${vars.__runId}-idea-feature-id.txt. If an existing feature is appropriate, use its id instead. Also write two body-only intent artifacts: .spur/run/${vars.__runId}-idea-goal.md with concise Goal intent only (a short statement of what the feature achieves; never task breakdowns, checklists, or how-to steps), and .spur/run/${vars.__runId}-idea-scope.md with explicit in-scope and out-of-scope boundary bullets."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           expectFile: .spur/run/${vars.__runId}-idea-feature-id.txt
           timeoutMs: ${vars.stepTimeoutMs}
       - kind: file.read.into-var
@@ -179,6 +183,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Generate acceptance criteria for feature ${vars.featureId}. Read the feature file and author R-numbered BDD Gherkin scenarios per ac-style-guide.md. Output only the complete Acceptance Criteria section body, including the gherkin code fence, with no surrounding commentary and no section heading."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           answerFile: .spur/run/${vars.__runId}-idea-ac-content.md
           expectFile: .spur/run/${vars.__runId}-idea-ac-content.md
           timeoutMs: ${vars.stepTimeoutMs}
@@ -239,6 +245,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Run sp:sys-architecture for feature ${vars.featureId}. Read the brainstorm artifact, feature AC, and .spur/run/${vars.__runId}-idea-design-review.md. Produce ADR entries, architecture updates, and design satellites (docs/design/<slug>.md) following the constitution edit rules. Do not write task or feature corpus files directly. Design-review contract (.spur/run/${vars.__runId}-idea-design-review.md, fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation`): on the first pass write the proposed design summary under `## Proposed design` and leave `## Operator feedback` empty; on retry with operator feedback present, revise the design/ADR artifacts, document the changes under `## Reconciliation`, and when the feedback invalidates an Acceptance Criteria scenario write the revised AC section body to a file and persist it via `$spurBin feature update \"$featureId\" --section \"Acceptance Criteria\" --from-file <file>` — never edit feature corpus files directly."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           expectFile: .spur/run/${vars.__runId}-idea-design-review.md
           timeoutMs: ${vars.stepTimeoutMs}
       # expectFile proves existence only, and the onEnter skeleton pre-creates the file — so an
@@ -293,6 +301,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Run sp:spec-decomposition for feature ${vars.featureId}. Read the brainstorm artifact, feature AC, and design doc. SIZING FIRST, before any JSON: apply the skill's `Default to NOT decomposing` rubric to the whole unit of work — if it scores 0-2 the correct output is a ONE-entry batch, not many. Scenario count is not task count: merge scenarios that one task delivers (same file surface, same subsystem, or unreadable apart in review), and list every scenario a task covers in its background. Merging never costs AC coverage — one task may carry several scenarios. Do not emit one entry per scenario or per requirement by reflex. Then produce a task-batch JSON array at .spur/run/${vars.__runId}-idea-task-batch.json, validated against apps/cli/schemas/task-batch.schema.json. Schema-permitted fields per entry: `name`, `background`, `requirements`, `feature_id`, `parent_wbs`, `priority`, `tags`, `template` — schema validation rejects anything else. Acceptance Criteria, Design, and Plan sections are filled in by the per-task refine step after batch-create, NOT at decompose time. Validate locally against the schema before emitting. Also emit the private task-order sidecar at .spur/run/${vars.__runId}-idea-task-order.json: a JSON array (one entry per batch item) of `{ name: <exact batch item name>, depends_on_names: [<batch item names>] }` declaring ordering/dependencies between the batch items; use `[]` when no ordering exists. Every `name` and every dependency must match exactly one batch item `name` — it is private workflow data, not part of task-batch.schema.json."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           expectFile: .spur/run/${vars.__runId}-idea-task-batch.json
           timeoutMs: ${vars.stepTimeoutMs}
       # R1 (0518): the task-order sidecar is the ordering contract for handoff-finalize.

package/config/workflows/planning-pipeline.yaml

@@ -102,6 +102,8 @@ states:
         options:
           agent: ${vars.agent}
           # `vars.feature` is optional and defaults to "" — the parent flag must be
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           # described conditionally, never interpolated bare. `--parent <empty> --json`
           # makes commander swallow `--json` as the parent value.
           input: "Skill(skill=\"sp:spur-cli\", args=\"feature create for slug ${vars.slug}\"). Run `${vars.spurBin} feature create \"${vars.slug}\" --json` (or reuse an existing id); append `--parent \"${vars.feature}\"` ONLY if the parent id between those quotes is non-empty — if it is empty, omit the --parent flag entirely. Write the feature id alone to .spur/run/${vars.__runId}-plan-feature-id.txt."
@@ -118,6 +120,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Skill(skill=\"sp:doc-evolve\", args=\"design-gen slug=${vars.slug}\"). Author docs/design/${vars.slug}.md from docs/plans/${vars.slug}-drafted.md; stage 04_DESIGN index edit only."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           expectFile: docs/design/${vars.slug}.md
           timeoutMs: ${vars.stepTimeoutMs}