@gobing-ai/spur 0.3.87 → 0.3.88

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
     "plugins": [
         {
             "name": "sp",
-            "version": "0.3.87",
+            "version": "0.3.88",
             "source": "./plugins/sp"
         }
     ]

package/config/config.example.yaml

@@ -133,9 +133,18 @@ agent:
     # A disabled profile stays visible to `spur agent doctor` but never routes
     # (no role, team, stage, or explicit selection). Flip back to enabled by
     # removing the line or setting disabled: false.
+    # Quota refresh is external: schedule `spur agent usage` (cron/launchd) to
+    # capture provider usage and record quota-owned availability observations.
+    # spur serve never runs it (B6 0892; docs/design/session-pinned-dispatch.md §3.4).
+    # A bare `true` is operator-owned (only humans write booleans). Automatic
+    # writers (quota/probe checks) emit the ownership object instead; an
+    # operator-owned disable is never auto-re-enabled (B6 0890).
     # - name: retired-profile
     #   agent: omp
     #   disabled: true
+    # - name: quota-limited
+    #   agent: omp
+    #   disabled: { owner: quota, since: 2026-02-14T09:30:00.000Z, reason: agent.quota.exhausted quota-limited }
     - name: pi-dsv4-flash-volc
       agent: pi
     #   tier: standard

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

@@ -58,6 +58,7 @@ rules:
             - "packages/app/src/services/token-ledger-watcher.ts" # node:fs watch() live watcher
             - "packages/app/src/services/project-registry.ts" # atomic projects.json persistence
             - "packages/app/src/services/slash-commands-service.ts" # synchronous ~/.config/spur/slash_commands.json persistence (mirrors project-registry.ts)
+            - "packages/app/src/services/agent-usage-producer.ts" # atomic agent-usage snapshot write (tmp + rename, mirrors project-registry.ts; task 0892 R1)
             - "packages/app/src/services/history-service.ts" # versioned analyze artifact + bounded-errors sidecar + latest.json symlink pointer (task 0474); ts-runtime FileSystem seam has no symlink, so the pointer uses node:fs directly (mirrors project-registry.ts persistence exemption)
             - "packages/app/src/observability/workflow-run-log-sink.ts" # sync FD append for mid-run tail-able all-in-one run log (task 0426 / feature D2); append() is sync from the observability bus
             - "apps/cli/src/commands/workflow.ts" # FD byte-window tail of the mid-run run log for `workflow trace --follow` streaming (task 0428 / feature D2); readSync at offset over the observability sink's FDs

package/config/workflows/idea-pipeline.yaml

@@ -94,6 +94,10 @@ states:
           agent: "${vars.agent}"
           role: planner
           resolvedAgentVar: planningAgent
+          # B7 R1 (0894): also pin the role once — __executor.planner feeds stage
+          # dispatch so no later idea stage re-walks the doctor ladder.
+          roles:
+            planner: "${vars.agent}"
       - kind: shell
         options:
           command: >-
@@ -122,6 +126,9 @@ states:
           input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative, read it first (${vars.idea} is a convenience echo). Run sp:brainstorm. 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}) plus the design summary per its `Design Approval Gate` / `The needs_design signal` sections. Also emit the idea-evaluation report to .spur/run/${vars.__runId}-idea-eval-report.md per the `sp:spur-dev` skill's `idea-evaluation` reference (urgency/necessity 0–5, premises, pros/cons, alternatives, enhanced idea, recommendation, plus mandatory `## Requirement inventory`: numbered I<n> items quoting/paraphrasing idea-input lines; `[unclear: ...]` marks ambiguity, `[deferred: <reason>]` marks out-of-scope). End with this exact footer: `---\\nrun_id: ${vars.__runId}\\ngenerated_at: <RFC3339>\\n---` (omit if run_id is empty)."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
+          # B7 R6 (0894): planner stages declare fresh — the role default is stated
+          # explicitly so the definition is self-documenting.
+          session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-eval-report.md
           timeoutMs: ${vars.stepTimeoutMs}
 
@@ -158,6 +165,8 @@ states:
           input: 'Create a feature for the idea. The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md — the idea argument persisted verbatim at start; treat it as the authoritative ask. 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; with --json the feature id is returned under the .ref.id envelope (n), not a top-level .id — read it from there. 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
+          # B7 R6 (0894): declared fresh policy (planner default).
+          session: fresh
           expectFile: .spur/run/${vars.__runId}-idea-feature-id.txt
           timeoutMs: ${vars.stepTimeoutMs}
       - kind: file.read.into-var
@@ -202,6 +211,8 @@ states:
           input: "Generate acceptance criteria for feature ${vars.featureId}. The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md — idea persisted verbatim at start; authoritative. Read the feature file and author R-numbered BDD Gherkin scenarios per ac-style-guide.md. Tie every scenario to the `## Requirement inventory` of .spur/run/${vars.__runId}-idea-eval-report.md: under each `Scenario:` heading add a comment `# covers: I1, I3` listing covered ids — every non-`[deferred: ...]` item needs at least one covering scenario. Two `spur task check` rules bind AC text: (1) AC bullets copy scenario titles verbatim — the title is the byte-identical identity key of its bullet; (2) gate-language words (HITL, approval/approved, merged/merge event, content-gate, GATED, capstone standalone) are forbidden in titles, bodies, and enum values (L4.gate-language) — rephrase around them. Output only the Acceptance Criteria section body (gherkin fence included), no commentary, no heading."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
+          # B7 R6 (0894): declared fresh policy (planner default).
+          session: fresh
           answerFile: .spur/run/${vars.__runId}-idea-ac-content.md
           expectFile: .spur/run/${vars.__runId}-idea-ac-content.md
           timeoutMs: ${vars.stepTimeoutMs}
@@ -298,6 +309,8 @@ states:
           input: 'The operator''s ask of record is .spur/run/${vars.__runId}-idea-input.md (idea persisted verbatim at start; authoritative). 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) per the constitution edit rules; never write task or feature corpus files directly. Design-review contract (fixed headings `## Proposed design`, `## Operator feedback`, `## Reconciliation`): first pass — write the proposed summary under `## Proposed design`, leave `## Operator feedback` empty; retry after operator feedback — revise the design/ADR artifacts, document changes under `## Reconciliation`, and when feedback invalidates an Acceptance Criteria scenario write the revised AC section body to a file, persist via `$spurBin feature update "$featureId" --section "Acceptance Criteria" --from-file <file>`.'
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
+          # B7 R6 (0894): declared fresh policy (planner default).
+          session: fresh
           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
@@ -365,6 +378,8 @@ states:
           input: "The operator's ask of record is .spur/run/${vars.__runId}-idea-input.md (the idea argument persisted verbatim at start; authoritative). Run sp:spec-decomposition for feature ${vars.featureId} per skill references/decomposition.md § Idea-pipeline emission: sizing first, then the batch JSON at .spur/run/${vars.__runId}-idea-task-batch.json and the private task-order sidecar at .spur/run/${vars.__runId}-idea-task-order.json."
           # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
           role: planner
+          # B7 R6 (0894): declared fresh policy (planner default).
+          session: fresh
           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.
@@ -448,6 +463,8 @@ states:
           agent: ${vars.planningAgent}
           # Declared Layer-1 role (0538 R2), same planner executor as decompose.
           role: planner
+          # B7 R6 (0894): declared fresh policy (planner default).
+          session: fresh
           timeoutMs: ${vars.stepTimeoutMs}
           # (warn) non-slash pointer: the 0788 checklist is per-checkout (digest via the
           # project's own computePlanningDigest), so the bounded prompt pins the skill

package/config/workflows/task-pipeline.yaml

@@ -196,6 +196,18 @@ states:
                 command: >-
                     mkdir -p .spur/run .spur/memory; RUN_ID="$__runId"; [ -n "$RUN_ID" ] || RUN_ID="pipeline-$wbs"; case "$RUN_ID" in *'$'*|*'{'*|*'}'*|*vars.*|*/*|*'\'*|*..*) echo "route-reason: refusing unsafe run id: $RUN_ID" >&2; exit 1 ;; esac; REASON_FILE=".spur/run/$RUN_ID-route-reason.txt"; jq -rn --arg m "$mode" '{"fast":"fast:evidence complete+consistent","":"safety:standard verification","unknown":"safety:unknown evidence quality","conflict":"safety:conflicting evidence"}[$m] // "safety:unrecognized evidence (mode=\($m))"' > "$REASON_FILE"; printf '%s %s %s\n' "$RUN_ID" "$wbs" "$(cat "$REASON_FILE")" >> .spur/memory/task-pipeline-routes.log; exit 0
 
+          # (e) B7 R1 (0894): resolve every declared role ONCE at precheck — pins land
+          # in __executor.<role> run vars so stage dispatch performs no doctor call.
+          # Soft probe: failures mark the status file and stages degrade to their own
+          # resolution; nothing here aborts the run.
+          - kind: doctor.probe
+            options:
+                resultFile: ".spur/run/${vars.__runId}-precheck-roles.status"
+                spurBin: "${vars.spurBin}"
+                roles:
+                    coder: "${vars.implementAgent}"
+                    reviewer: "${vars.agent}"
+
     - id: implement
       description: >
           Run agent-driven implementation via /sp:dev-run --mode implement, THEN move the
@@ -216,6 +228,9 @@ states:
                 # Pure slash command only (ADR-043). Anti-recursion / implement discipline
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: coder
+                # B7 R3/R6 (0894): coder stages reuse the role session — the test-fix hop
+                # resumes the implement session instead of re-reading the task cold.
+                session: reuse
                 # 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}
@@ -356,6 +371,9 @@ states:
                 # R3 (0482): `--findings` names the failing anchors inline; `--gate-log` remains
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: coder
+                # B7 R3/R6 (0894): coder stages reuse the role session — the fix hop
+                # continues the implement session it is repairing.
+                session: reuse
                 # 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}
@@ -417,7 +435,11 @@ states:
                 expectFile: .spur/run/${vars.__runId}-review-answer.txt
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: reviewer
+                # B7 R3/R6 (0894): declared fresh policy (reviewer default) — the action
+                # result records this as declared, not defaulted. `freshSession: true` is
+                # kept as the action-level hard guarantee (0710 R2 structural assertion).
                 freshSession: true
+                session: fresh
                 priority: ${vars.taskPriority}
                 compareExecutorWith: implement
                 timeoutMs: ${vars.stepTimeoutMs}
@@ -477,7 +499,10 @@ states:
                 input: /sp:dev-verify ${vars.wbs} --auto --fix none --focus all
                 # Declared Layer-1 role (0538 R2/0710 R7): routing reason; no executor pin — role routing feeds the distinctness gate.
                 role: reviewer
+                # B7 R3/R6 (0894): declared fresh policy (reviewer default).
+                # `freshSession: true` kept as the action-level hard guarantee (0710 R2).
                 freshSession: true
+                session: fresh
                 priority: ${vars.taskPriority}
                 compareExecutorWith: implement
                 timeoutMs: ${vars.stepTimeoutMs}

package/package.json

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

package/plugins/sp/README.md

@@ -94,7 +94,7 @@ list this README is checked against.
 | `dev-idea`       | Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create, handoff |
 | `dev-plan`       | Plan a feature from a written description — intake → feature create → AC generation → feature check gate → decomposition → batch-create                                         |
 | `dev-brainstorm` | Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring                                              |
-| `dev-refine`     | Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; `--depth ready` for implement-ready freeze                    |
+| `dev-refine`     | Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; `--depth ready` audits and corrects existing claims, freezes the spec, promotes to todo |
 
 #### Lifecycle — execution
 
@@ -116,7 +116,7 @@ list this README is checked against.
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dev-runall`    | Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via task-pipeline.yaml, emit a batch report              |
 | `dev-parallel`  | Fan out independent tasks or investigations in parallel via subagents — choose the right pattern and synthesize results                                                |
-| `dev-refineall` | Batch-refine tasks (feature or selector) — planning-half bulk fill of Background/Requirements/AC/Design/Plan before runall; `--depth ready` for implement-ready freeze |
+| `dev-refineall` | Batch-refine tasks (feature or selector) — planning-half bulk fill of Background/Requirements/AC/Design/Plan before runall; `--depth ready` audits, corrects, freezes and promotes each task |
 | `dev-verifyall` | Batch-verify tasks against requirements and AC — resolves a set, runs per-task verification, produces consolidated PASS/PARTIAL/FAIL summary report                    |
 | `dev-wrapall`   | Wrap up a batch of completed tasks — learnings, metrics, doc-sync, feature transition, optional branch cleanup                                                         |
 

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

@@ -1,5 +1,5 @@
 ---
-description: Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; optional implement-ready depth
+description: Refine or re-audit a task — fill missing sections via Q&A, or with --depth ready verify existing claims and fixes against the tree, correct them, and promote to todo
 role: planner
 argument-hint: "<wbs> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
@@ -7,17 +7,24 @@ allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 
 # Dev Refine
 
-Wraps the **sp:spur-dev** skill. Prefer Design at plan/create (default); refine is the **fallback**
-for blank Design/AC/Plan after `--skip-design` or incomplete create. Use `--depth ready` when another
-agent will implement and L3-clean is not enough (frozen APIs, anti-patterns, file targets, handoffs).
+Wraps the **sp:spur-dev** skill. Three jobs:
+
+| Job | Invocation |
+| --- | --- |
+| Fill blank Design/AC/Plan after `--skip-design` or an incomplete create (fallback; Design normally comes from plan/create) | `/sp:dev-refine <wbs> --auto` |
+| Evaluate and correct an existing task: a review-triage filing, a stale backlog item, anything whose claims or proposed fixes may no longer hold | `/sp:dev-refine <wbs> --depth ready` (add `--auto` to skip Q&A) |
+| Freeze a spec for another implementer; also the recovery command when `spur task create` ready preparation fails | `/sp:dev-refine <wbs> --auto --depth ready` |
+
+`standard` checks only that target sections are structurally complete. It never re-checks what
+they say. Use `ready` whenever the existing content itself is in doubt.
 
 ## Argument Flags
 
 | Flag | Description | Default |
 | --- | --- | --- |
 | `<wbs>` | Task WBS to refine. | required |
-| `--focus` `<mode>` | Refinement focus mode. | omitted |
-| `--description` `<text>` | Override the task description. | omitted |
+| `--focus` `<mode>` | Gap-analysis focus: `all\|requirements\|background\|constraints\|acceptance\|quick`. | `all` |
+| `--description` `<text>` | Operator framing injected into Q&A/synthesis. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
@@ -35,7 +42,18 @@ Under `--auto` with **`--depth standard`** (default), SKIP only when target sect
 findings: Background, Requirements, Acceptance Criteria, Design, Plan. Solution is not a refine
 target. Under **`--depth ready`**, do **not** SKIP on L3-clean alone — run the implement-ready
 checklist (dev-operations § refine) and rewrite Design/Requirements/Plan until another agent can
-implement without inventing design. Stage floor: the `planner` role per
+implement without inventing design:
+
+1. Audit every existing claim against the current tree: facts, cited sources, fix soundness across
+   all callers, test observability, environment, concurrent work, and scope.
+2. Correct what is wrong and record each change in a dated `**Refine corrections (<date>)**` block
+   in Background.
+3. Run `spur task check <wbs> --as todo --json`, fill unset priority/estimate, and promote
+   `backlog → todo`.
+4. Report checklist rows `{id, pass, evidence}`.
+
+Refine targets `backlog`/`todo` tasks; a `wip`-or-later task needs explicit operator consent and is
+never demoted. Stage floor: the `planner` role per
 [`roles.md`](../references/roles.md) — this command names roles, never tiers (0538 R4);
 ready synthesis may use a higher tier when the task spans packages/seams.
 

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

@@ -1,5 +1,5 @@
 ---
-description: Refine a batch of tasks via structured Q&A — resolve a set (feature or selector), refine each in dependency-correct order, emit a batch report; optional implement-ready depth
+description: Refine a batch of tasks via structured Q&A — resolve a set (feature or selector), refine each in dependency-correct order, emit a batch report; --depth ready audits, corrects and promotes each task
 role: planner
 argument-hint: "--feature <id> | --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
@@ -9,7 +9,9 @@ allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 
 Wraps the **sp:spur-dev** skill. Batch counterpart of `/sp:dev-refine` — same per-task refine
 operation, applied to a resolved set (typically every task under a feature). Pass
-`--depth ready` to force an implement-ready freeze on every task (does not L3-SKIP).
+`--depth ready` to force an implement-ready freeze on every task (does not L3-SKIP). Each task's
+existing claims are audited against the current tree and corrected, and passing tasks are promoted
+`backlog → todo`. Use it to re-audit a feature's filed or stale tasks as well as before handoff.
 
 ## Argument Flags
 
@@ -17,8 +19,8 @@ operation, applied to a resolved set (typically every task under a feature). Pas
 | --- | --- | --- |
 | `--feature` `<id>` | Refine all tasks in a feature. | required (one of `--feature` / `--tasks`) |
 | `--tasks` `<selector>` | Task selector to refine (alternative to `--feature`). | required (one of `--feature` / `--tasks`) |
-| `--focus` `<mode>` | Refinement focus mode. | omitted |
-| `--description` `<text>` | Override description for each task. | omitted |
+| `--focus` `<mode>` | Gap-analysis focus: `all\|requirements\|background\|constraints\|acceptance\|quick`. | `all` |
+| `--description` `<text>` | Operator framing injected into each task's Q&A/synthesis. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
@@ -50,8 +52,9 @@ worktree copy; your main tree still shows pre-run statuses until the FF-merge on
 not a bug.
 
 **Depth:** default `standard` keeps the cheap L3 SKIP gate under `--auto`. Use
-`--depth ready` when handing a feature to another implementer (frozen Design/Requirements/Plan);
-thread `--depth` into each per-task refine.
+`--depth ready` when handing a feature to another implementer (frozen Design/Requirements/Plan),
+or when the tasks' existing content is in doubt; thread `--depth` into each per-task refine. Ready
+report rows add corrections count, status before → after, and failed checklist ids.
 
 > **`--next` dropped** (feature H8, 2026-07-31). Batch-level chaining was a token bomb — each refine
 > hop is an LLM call, and a large feature means N refine chains fanned out at once. For batch