@gobing-ai/spur 0.3.47 → 0.3.48

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
     },
     "plugins": [
         {
-            "version": "0.3.47",
+            "version": "0.3.48",
             "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,18 +36,24 @@ 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
 
   # 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.
@@ -92,6 +101,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 +132,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}
 

package/config/workflows/task-pipeline.yaml

@@ -262,6 +262,8 @@ states:
         options:
           agent: ${vars.implementAgent}
           # Pure slash command only (ADR-043). Anti-recursion / implement discipline
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           # lives in /sp:dev-run --mode implement → sp:code-implementation, not YAML prose.
           input: /sp:dev-run --mode implement ${vars.wbs} --auto
           timeoutMs: ${vars.implementTimeoutMs}
@@ -374,6 +376,8 @@ states:
         options:
           agent: ${vars.agent}
           # R3 (0482): `--findings` names the failing anchors inline; `--gate-log` remains
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           # the full-context escape hatch when the digest is not enough.
           input: /sp:dev-fixall "${vars.qualityGateCmd}" --gate-log .spur/run/${vars.wbs}-test-gate.log --findings "${vars.gateFindings}"
           timeoutMs: ${vars.stepTimeoutMs}
@@ -422,6 +426,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-review ${vars.wbs} --auto
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: approve
@@ -452,6 +458,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-verify ${vars.wbs} --auto --fix all --focus all
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           timeoutMs: ${vars.stepTimeoutMs}
           answerFile: .spur/run/${vars.wbs}-verify-answer.txt
       - kind: shell

package/config/workflows/wayfinder-resolution.yaml

@@ -82,6 +82,8 @@ states:
         options:
           agent: ${vars.agent}
           capture: true
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           mode: text
           input: >-
             Resolve task ${vars.wbs} in resolution mode ${vars.resolutionMode} using the prepared
@@ -115,6 +117,8 @@ states:
         options:
           agent: ${vars.agent}
           capture: true
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           mode: text
           input: >-
             Verify resolved task ${vars.wbs} using only local reads and `spur` CLI. Check its

package/config/workflows/wrapup-pipeline.yaml

@@ -80,7 +80,9 @@ states:
       - kind: agent.run
         options:
           agent: ${vars.agent}
-          input: "Skill(skill=\"sp:doc-evolve\", args=\"wrapup tasks=${vars.tasks}\"). Repair drift in docs/00_ADR.md, docs/03_ARCHITECTURE.md, docs/04_DESIGN.md, docs/design/* per constitution edit rules. Do not write task/feature corpus."
+          input: 'Skill(skill="sp:doc-evolve", args="wrapup tasks=${vars.tasks}"). Repair drift in docs/00_ADR.md, docs/03_ARCHITECTURE.md, docs/04_DESIGN.md, docs/design/* per constitution edit rules. Do not write task/feature corpus.'
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: learning-capture
@@ -93,6 +95,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Extract working learnings from tasks ${vars.tasks}. Output raw markdown (no fences) grouped by date and task WBS: conventions, errors fixed, patterns, gotchas. Captured to .spur/run/wrapup-learnings.md."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           answerFile: .spur/run/wrapup-learnings.md
           expectFile: .spur/run/wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
@@ -103,6 +107,8 @@ states:
             if test -s .spur/run/wrapup-learnings.md; then
               cat .spur/run/wrapup-learnings.md >> .spur/memory/learnings.md &&
               printf '\n' >> .spur/memory/learnings.md;
+            else
+              echo "wrapup: learning capture missing or empty at $PWD/.spur/run/wrapup-learnings.md - append skipped" >&2;
             fi &&
             exit 0
 
@@ -115,6 +121,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "For each task in ${vars.tasks}, output one JSONL line (no fences) with fields: wbs, feature_id, status, verdict, timestamp. Captured to .spur/run/wrapup-metrics.jsonl."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: scribe
           answerFile: .spur/run/wrapup-metrics.jsonl
           expectFile: .spur/run/wrapup-metrics.jsonl
           timeoutMs: ${vars.stepTimeoutMs}
@@ -124,6 +132,8 @@ states:
             mkdir -p .spur/memory &&
             if test -s .spur/run/wrapup-metrics.jsonl; then
               cat .spur/run/wrapup-metrics.jsonl >> .spur/memory/wrapup-metrics.jsonl;
+            else
+              echo "wrapup: metrics capture missing or empty at $PWD/.spur/run/wrapup-metrics.jsonl - append skipped" >&2;
             fi &&
             exit 0
 
@@ -131,6 +141,9 @@ states:
     description: >
       If vars.feature is set, sync feature status via bounded feature-sync-bounded
       (0411). Soft shell — blocked/failed sync must not abort wrap-up after metrics.
+      Empty vars.feature is NOT a blocked sync but a mis-invocation (the engine only
+      enters this state when vars.feature is set) and fails loud (dogfood 2026-08-15,
+      feature I3: a silent exit 0 made the wrap look complete with no transition).
     onEnter:
       # Genuinely soft: the terminating `exit 0` must be reached on BOTH branches, so
       # the sync is chained with `;` — with `&&` a non-zero sync skipped `exit 0` and
@@ -142,6 +155,10 @@ states:
       - kind: shell
         options:
           command: >-
+            if [ -z "$feature" ]; then
+              echo "feature-transition: vars.feature is empty — refusing no-op feature sync (mis-invocation, not a blocked sync)" >&2;
+              exit 1;
+            fi;
             if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then
               bun plugins/sp/scripts/feature-sync-bounded.ts "$feature" --spur-bin "$spurBin" --json;
             else

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.47",
+    "version": "0.3.48",
     "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",
@@ -54,7 +54,7 @@
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
         "@gobing-ai/ts-db": "^0.4.31",
-        "@gobing-ai/ts-ai-runner": "^0.4.31",
+        "@gobing-ai/ts-ai-runner": "^0.4.32",
         "@gobing-ai/ts-dual-workflow-engine": "^0.4.31",
         "@gobing-ai/ts-infra": "^0.4.31",
         "@gobing-ai/ts-llm-jsonl-importer": "^0.4.31",

package/plugins/sp/agents/expert-spur.md

@@ -66,6 +66,7 @@ Invoke `sp:spur-cli` for verb guidance and per-noun conventions:
 
 - [ ] Delegate verb guidance to `sp:spur-cli`; use the `spur` CLI for all mutations.
 - [ ] Run the noun's `check`/`validate` verb before and after editing (e.g. `spur task check <wbs> --json`).
+- [ ] Run the corpus-wide sweep after batch edits: `spur task check --corpus --json` (fails on structural errors outside `config/corpus-baseline.json`).
 - [ ] Use `spur task update --section --from-file` for all task section edits.
 - [ ] Run the noun's `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh`).
 

package/plugins/sp/commands/dev-arch.md

@@ -1,5 +1,6 @@
 ---
 description: Survey a codebase (or module tree) for shallow modules and deepening opportunities — emit a ranked MARKDOWN candidate report that feeds the planning half; never auto-refactors
+role: planner
 argument-hint: "[<module-path>] [--scope <all|path>] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 ---
@@ -14,7 +15,7 @@ Wraps the **sp:sys-architecture** skill.
 | --- | --- | --- |
 | `[<module-path>]` | Module path to scope the architecture survey. | omitted (whole repo) |
 | `--scope` `<all\|path>` | Limit the survey to a path or expand to the whole repo. | all |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing survey work. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing survey work. | omit |
 | `--json` | Emit structured JSON instead of markdown. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

package/plugins/sp/commands/dev-brainstorm.md

@@ -1,5 +1,6 @@
 ---
 description: Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring
+role: planner
 argument-hint: "<topic> [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:brainstorm** and **sp:wayfinder** skills.
 | `<topic>` | Topic or problem statement to explore. | required |
 | `--depth` `<basic\|detailed\|comprehensive>` | Breadth vs. depth of the exploration. | detailed |
 | `--options` `<n>` | Number of solution options to generate. | 3 |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. | omit |
 | `--skip-discovery` | Skip the discovery interview; ideate immediately. | off |
 | `--wayfind` | Spawn a wayfinder feature for multi-session routing. | off |
 | `--task` `[<feature-id>]` | Create a tracking task under a feature. | omitted |

package/plugins/sp/commands/dev-changelog.md

@@ -1,5 +1,6 @@
 ---
 description: Generate changelog from git commits
+role: scribe
 argument-hint: "[--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
 allowed-tools: ["Bash", "Read"]
 ---

package/plugins/sp/commands/dev-daily.md

@@ -1,5 +1,6 @@
 ---
 description: "Generate a daily summary report from agent usage data, git history, and notes"
+role: scribe
 argument-hint: "[--date <YYYY-MM-DD>] [--dry-run] [--output <path>] [--no-git] [--no-ccusage]"
 allowed-tools: ["Bash", "Read"]
 ---

package/plugins/sp/commands/dev-debug.md

@@ -1,5 +1,6 @@
 ---
 description: "Systematic debugging protocol — reproduce, isolate, diagnose root cause, apply minimal fix, and verify with regression tests"
+role: coder
 argument-hint: "\"<symptom | failing command>\" [--scope <path>] [--task [<wbs>]] [--agent <inline|auto|name>]"
 allowed-tools: ["Bash", "Read", "Write", "Skill"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:sys-debugging** skill.
 | `"<symptom \| failing command>"` | Symptom or failing command to diagnose. | required |
 | `--scope` `<path>` | Scope the reproduction/isolation to a path. | cwd |
 | `--task` `[<wbs>]` | Attach findings to a task. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing diagnosis. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing diagnosis. | omit |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

package/plugins/sp/commands/dev-dogfood.md

@@ -1,5 +1,6 @@
 ---
 description: Dogfood an agent skill/command/CLI — drive it end-to-end with bounded auto-fix, self-monitor, and emit a comprehensive report
+role: reviewer
 argument-hint: "<testee> [--agent <inline|auto|name>] [--max-retry <n>] [--save] [--task] [--chain-follow] [--full]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob", "Skill"]
 ---
@@ -13,7 +14,7 @@ Wraps the **sp:dogfood-testing** skill.
 | Flag | Description | Default |
 | --- | --- | --- |
 | `<testee>` | Skill / command / CLI to exercise end-to-end. | required |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing dogfood work. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing dogfood work. | omit |
 | `--max-retry` `<n>` | Max auto-fix retries per stage. | 3 |
 | `--save` | Compatibility no-op; saving is now default. Retained until evidenced retirement. | off |
 | `--task` | Record outcomes against a task. | omitted |

package/plugins/sp/commands/dev-featurechange.md

@@ -1,5 +1,6 @@
 ---
 description: >-
+role: planner
   Restructure the feature tree from a mapping file — dry-run then apply via
   spur feature move / task feature_id edges / root docs/*.md reference rewrites
   (CLI-gated; no raw Write on docs/features or docs/tasks)

package/plugins/sp/commands/dev-find-conflict.md

@@ -1,5 +1,6 @@
 ---
 description: "Authority-aware semantic audit across source, task files, feature files, and project authority files — discover conflicts, resolve claim-specific authority, collect reproducible evidence, and route confirmed repairs through owner surfaces. Triggers: find conflict, conflict audit, semantic conflict, authority mismatch, stale projection."
+role: reviewer
 argument-hint: "[<scope>] [--pillar <source|tasks|features|authority|all>] [--mode <adaptive|full>] [--resolve] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
@@ -18,7 +19,7 @@ owner-routed remediation.
 | `--pillar` `<source\|tasks\|features\|authority\|all>` | Limit the internal audit to one pillar; the minimum authorities needed to judge it still load.                                           | all             |
 | `--mode` `<adaptive\|full>`                            | Scan protocol — adaptive reuses fresh indexed context and discloses skipped areas; full forces a cold comprehensive scan.                | adaptive        |
 | `--resolve`                                            | Enable the proposal, confirmation, and owner-routed remediation workflow. Its absence guarantees no source/corpus/numbered-doc mutation. | off             |
-| `--agent` `<inline\|auto\|name>`                       | Who runs the model-bearing analysis.                                                                                                     | inline          |
+| `--agent` `<inline\|auto\|name>`                       | Who runs the model-bearing analysis.                                                                                                     | omit           |
 | `--json`                                               | Emit the same result envelope as Markdown as JSON.                                                                                       | off             |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

package/plugins/sp/commands/dev-find-issue.md

@@ -1,13 +1,15 @@
 ---
-description: "Review agent session logs, identify performance bottlenecks and behavioral anti-patterns, and generate a structured task file with proposed fixes. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
-argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|omp|claude|codex|gemini|opencode|antigravity|openclaw|pi>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--use-history] [--no-task] [--agent <inline|auto|name>] [--json]"
+description: "Render the session-forensics report from imported history data (8 CLI-derivable sections plus 6 model-authored), identify bottlenecks and behavioral anti-patterns, and optionally create a structured fix task behind --create-task. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
+role: reviewer
+argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|omp|claude|codex|gemini|opencode|antigravity|openclaw|pi>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--create-task] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
 
 # Dev Find Issue
 
-Wraps the **sp:issue-finding** skill — forensic session log analysis that identifies performance
-bottlenecks, ranks root causes by time cost, proposes targeted fixes, and generates a structured
+Wraps the **sp:issue-finding** skill — report-first session forensics over the history data plane.
+The CLI renders the 8 derivable report sections (`spur history report --mode forensics`); the skill
+identifies bottlenecks, proposes fixes, and — only with `--create-task` — generates a structured
 task file via `spur task create`.
 
 ## Argument Flags
@@ -15,21 +17,20 @@ task file via `spur task create`.
 | Flag                                                                                 | Description                          | Default    |
 | ------------------------------------------------------------------------------------ | ------------------------------------ | ---------- |
 | `[<topic>]`                                                                          | Narrow the analysis to a topic.      | omitted    |
-| `--sessions` `<glob>`                                                                | Session log glob to scan.            | recent     |
+| `--sessions` `<glob>`                                                                | Session log glob (fallback input).   | recent     |
 | `--source` `<auto\|omp\|claude\|codex\|gemini\|opencode\|antigravity\|openclaw\|pi>` | Agent source to scan.                | auto       |
-| `--feature` `<id>`                                                                   | Attach findings to a feature.        | omitted    |
-| `--template` `<meta\|issue\|standard>`                                               | Output template shape.               | standard   |
-| `--priority` `<P0\|P1\|P2\|P3>`                                                      | Filter / assign priority.            | omitted    |
-| `--severity` `<S0\|S1\|S2>`                                                          | Filter / assign severity.            | omitted    |
+| `--feature` `<id>`                                                                   | Attach the generated task to a feature. | omitted |
+| `--template` `<meta\|issue\|standard>`                                               | Task template shape (`--create-task` only). | standard |
+| `--priority` `<P0\|P1\|P2\|P3>`                                                      | Filter / assign task priority.       | P2         |
+| `--severity` `<S0\|S1\|S2>`                                                          | Filter / assign severity.            | all        |
 | `--category` `<list>`                                                                | Comma list of categories to keep.    | all        |
 | `--since` `<iso>`                                                                    | Start of the scan window.            | configured |
 | `--until` `<iso>`                                                                    | End of the scan window.              | now        |
 | `--top` `<n>`                                                                        | Limit to top N findings.             | omitted    |
 | `--min-cost` `<duration>`                                                            | Minimum wasted duration to report.   | omitted    |
 | `--strict-topic`                                                                     | Drop findings off-topic.             | off        |
-| `--use-history`                                                                      | Incorporate indexed history.         | off        |
-| `--no-task`                                                                          | Do not create a task for findings.   | off        |
-| `--agent` `<inline\|auto\|name>`                                                     | Who runs the model-bearing analysis. | inline     |
+| `--create-task`                                                                      | Generate a fix task for findings.    | off        |
+| `--agent` `<inline\|auto\|name>`                                                     | Who runs the model-bearing analysis. | omit       |
 | `--json`                                                                             | Emit structured JSON.                | off        |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
@@ -41,28 +42,15 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 /sp:dev-find-issue "test-loop spinning"
 /sp:dev-find-issue --sessions "~/.omp/agent/sessions/-xprojects-spur-new/2026-07-29T*"
 /sp:dev-find-issue "L3 guard format discovery" --feature H51 --priority P1 --severity S1
-/sp:dev-find-issue --category test-loop,guard --min-cost 30m --no-task
-/sp:dev-find-issue --source claude --since 2026-07-28 --json
-/sp:dev-find-issue --sessions plugins/sp/skills/issue-finding/examples/session-test-loop.jsonl --no-task
+/sp:dev-find-issue --category test-loop,guard --min-cost 30m
+/sp:dev-find-issue --source claude --since 2026-07-28 --create-task --json
 ```
 
-| Argument                      | Description                                                                              | Default                         |
-| ----------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------- |
-| `[topic]`                     | Optional focus text or smart positional (path/glob → sessions; category phrase → filter) | (full taxonomy)                 |
-| `--sessions <glob>`           | Session JSONL file(s) or directory                                                       | most recent for resolved source |
-| `--source <name>`             | `auto`, `omp`, `claude`, `codex`, `gemini`, `opencode`, `antigravity`, `openclaw`, `pi`  | `auto`                          |
-| `--feature <id>`              | Feature ID to link the generated task to                                                 | (none)                          |
-| `--template <name>`           | `meta` (umbrella), `issue` (single), or `standard`                                       | `meta`                          |
-| `--priority <P0\|P1\|P2\|P3>` | Task frontmatter priority (not bottleneck severity)                                      | `P2`                            |
-| `--severity <S0\|S1\|S2>`     | Minimum bottleneck severity to keep                                                      | (all)                           |
-| `--category <list>`           | Comma-separated category ids (`test-loop`, `guard`, …)                                   | `all`                           |
-| `--since` / `--until`         | Session start time bounds                                                                | (none)                          |
-| `--top <n>`                   | Cap number of fixes/requirements                                                         | (no cap)                        |
-| `--min-cost <duration>`       | Drop findings under this waste floor (`30m`, `2h`)                                       | (none)                          |
-| `--strict-topic`              | Drop off-topic findings even if severe                                                   | off                             |
-| `--use-history`               | Optional `spur history` import/analyze for cost aggregates                               | off                             |
-| `--no-task`                   | Markdown report only                                                                     | off                             |
-| `--json`                      | JSON findings only (no task)                                                             | off                             |
+**Report-first (task 0556).** Default output is the markdown report to stdout; no task file is
+written. Task creation moved behind `--create-task`. `--use-history` and `--no-task` are removed:
+the history data plane is now the primary source (no flag needed), and the old report-only behavior
+is the new default. Raw JSONL remains a fallback under the three conditions documented in
+`sp:issue-finding`.
 
 **See also:** skill `sp:issue-finding` (SSOT), `/sp:dev-runall`, `/sp:dev-dogfood`,
 `sp:daily-summary`, `sp:reverse-engineering`.

package/plugins/sp/commands/dev-find-next.md

@@ -1,5 +1,6 @@
 ---
 description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' with a ranked, evidence-carrying frontier, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+role: planner
 argument-hint: "[--task [<feature-id>]] [--agent <inline|auto|name>] [--auto] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
@@ -19,7 +20,7 @@ Answers *"which X"* — the question `/sp:dev-next` deliberately does not (next-
 | Flag | Description | Default |
 | --- | --- | --- |
 | `--task` `[<feature-id>]` | After the report, confirm one target and dispatch the planning half to produce implement-ready tasks. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | omit |
 | `--auto` | Skip the `--task` confirm (accept the offered target) and forward into dispatched children. | off |
 | `--json` | Emit the ranked frontier, gated list, and proposals as a JSON envelope. | off |