@gobing-ai/spur 0.4.22 → 0.4.24

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/.claude-plugin/marketplace.json +1 -1
  2. package/config/pipeline-budgets.json +1 -1
  3. package/config/rules/boundary/config-loading-ownership.yaml +1 -1
  4. package/config/rules/strict/runtime-boundaries.yaml +3 -3
  5. package/config/rules/surface/check-cli-surface.yaml +6 -1
  6. package/config/workflow-candidates.json +1 -1
  7. package/config/workflows/history-anatomy.yaml +11 -11
  8. package/package.json +1 -1
  9. package/plugins/sp/commands/dev-runall.md +1 -1
  10. package/plugins/sp/plugin.json +1 -1
  11. package/plugins/sp/skills/dogfood-testing/SKILL.md +7 -7
  12. package/plugins/sp/skills/dogfood-testing/references/report-template.md +1 -1
  13. package/plugins/sp/skills/history-anatomy/references/modes.md +1 -1
  14. package/plugins/sp/skills/spur-cli/references/agent.md +6 -5
  15. package/plugins/sp/skills/spur-cli/references/builder.md +1 -8
  16. package/plugins/sp/skills/spur-cli/references/history.md +9 -2
  17. package/plugins/sp/skills/spur-cli/references/tasks.md +2 -1
  18. package/plugins/sp/skills/spur-cli/references/workflows.md +6 -2
  19. package/plugins/sp/skills/spur-dev/references/execution-batch-report.md +3 -3
  20. package/plugins/sp/skills/spur-dev/references/execution-batch.md +3 -3
  21. package/plugins/sp/skills/spur-dev/references/execution-worktree-landing.md +2 -2
  22. package/plugins/sp/skills/spur-dev/references/execution-worktree-setup.md +4 -4
  23. package/spur.js +882 -789
package/.claude-plugin/marketplace.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "plugins": [
8
8
  {
9
9
  "name": "sp",
10
- "version": "0.4.22",
10
+ "version": "0.4.24",
11
11
  "source": "./plugins/sp"
12
12
  }
13
13
  ]
package/config/pipeline-budgets.json CHANGED
@@ -32,7 +32,7 @@
32
32
  "modelQueries": 3,
33
33
  "wallClockMs": null,
34
34
  "tokenCostUsd": null,
35
- "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0. 0920 recount 2026-09-23: 4 -> 3 — the resolve-scope model hop was removed; scope/window validation is deterministic in the `spur history anatomy paths` op (history-anatomy-cache before script-absorption PR-6).",
35
+ "source": "Coverage entry (0826 R2): the live definition's model-query count (extractResolvedWorkflowFacts, 2026-09-11). No real-run measurement yet: wall-clock and cost are unenforced until measured, never 0. 0920 recount 2026-09-23: 4 -> 3 — the resolve-scope model hop was removed; scope/window validation is deterministic in the `spur history anatomy-paths` op (history-anatomy-cache before script-absorption PR-6).",
36
36
  "decision": null
37
37
  }
38
38
  }
package/config/rules/boundary/config-loading-ownership.yaml CHANGED
@@ -67,7 +67,7 @@ rules:
67
67
  exclude:
68
68
  - "packages/config/src/**"
69
69
  - "apps/cli/src/index.ts"
70
- - "apps/cli/src/workflow-transport.ts" # boot-free composition root of `spur workflow commit-guard|persist-*` (PR-4)
70
+ - "apps/cli/src/workflow-transport.ts" # boot-free composition root of `spur workflow commit-guard-*|persist-*` (PR-4)
71
71
  - "apps/server/src/serve.ts"
72
72
  - "apps/server/src/context.ts"
73
73
  - "**/tests/**"
package/config/rules/strict/runtime-boundaries.yaml CHANGED
@@ -37,7 +37,7 @@ rules:
37
37
  - "apps/desktop/src/server-process.ts"
38
38
 
39
39
  # Low-level system primitives:
40
- # `spur builder pr` spine (script-absorption PR-7, moved from plugins/sp/scripts/pr-reviewing.ts):
40
+ # `spur builder pr-*` spine (script-absorption PR-7, moved from plugins/sp/scripts/pr-reviewing.ts):
41
41
  # every git/gh call goes through ONE synchronous, test-injectable CommandRunner seam
42
42
  # (`setCommandRunner`); the spine is synchronous end to end (wait polls with a sync sleep).
43
43
  # The ts-runtime sync executors cannot stand in: NodeSyncProcessExecutor maps a spawn
@@ -101,7 +101,7 @@ rules:
101
101
  - "packages/app/src/services/history-anatomy.ts" # deterministic history-anatomy cache core (task 1005 R2): fsync'd tmp+rename atomic publish, readdir digest scans and sync report reads must stay byte-stable; bundled standalone for the bare-node plugin twin (mirrors agent-usage-producer.ts / history-service.ts exemptions)
102
102
  - "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
103
103
  - "packages/app/src/observability/agent-run-log.ts" # same primitive as the sink above for the per-run agent stream (task 1076 R1, ADR-132); append() is sync from the agent service's own onOutput hook, and the byte cap needs the FD position it tracks
104
- # Workflow transports (script-absorption PR-4, `spur workflow commit-guard`): moved
104
+ # Workflow transports (script-absorption PR-4, `spur workflow commit-guard-*`): moved
105
105
  # verbatim from the plugin scripts; synchronous probes and
106
106
  # atomic tmp+rename snapshot writes inside one short-lived CLI process.
107
107
  - "packages/app/src/workflow/commit-guard.ts" # .spur/run/<run>-tree-start.json atomic snapshot + target conflict-marker reads
@@ -121,7 +121,7 @@ rules:
121
121
  - "packages/app/src/services/residual-scan-run.ts"
122
122
  - "packages/app/src/workflow/task-diffstat.ts"
123
123
  - "packages/app/src/workflow/feature-verification-run.ts" # the pass opens the run's single merged log fd (`openSync(path,'a')`) and mkdirs the run dir beside the receipt writer, exactly as the plugin entry did before the move; the fd cannot be expressed through the FileSystem seam (task 1176 R2; same class as the quality-gate exemption above)
124
- - "packages/app/src/services/pr-review/index.ts" # `spur builder pr` (PR-7): sync --status-file verdict writes and the AGENTS.md review-rules probe inside the synchronous spine (same exemption as its process seam above)
124
+ - "packages/app/src/services/pr-review/index.ts" # `spur builder pr-*` (PR-7): sync --status-file verdict writes and the AGENTS.md review-rules probe inside the synchronous spine (same exemption as its process seam above)
125
125
  - "packages/app/src/services/run-storage.ts" # durable-evidence migration core (task 1025 R4): atomic tmp+rename byte copies with digest reread and atomic manifest publish must stay byte-stable (mirrors agent-usage-producer.ts / project-registry.ts exemptions)
126
126
  - "packages/app/src/services/durable-plane-ignore.ts" # .git/info/exclude append moved verbatim out of run-storage.ts to break an import cycle (same exemption)
127
127
 
package/config/rules/surface/check-cli-surface.yaml CHANGED
@@ -62,7 +62,12 @@ rules:
62
62
  - "apps/cli/src/commands/task/wrapup.ts"
63
63
  - "apps/cli/src/commands/feature/handoff.ts"
64
64
  - "apps/cli/src/commands/feature/verify.ts"
65
- # commit-guard declares no --json: its {staged, foreign} / {foreign} lines are rendered by
65
+ # Per-noun shared.ts files that hold service factories only and declare no options
66
+ # (feature/history split, 03 §3 layout); `builder publish` declares no --json.
67
+ - "apps/cli/src/commands/feature/shared.ts"
68
+ - "apps/cli/src/commands/history/shared.ts"
69
+ - "apps/cli/src/commands/builder/publish.ts"
70
+ # commit-guard-* declare no --json: its {staged, foreign} / {foreign} lines are rendered by
66
71
  # @gobing-ai/spur-app/commit-guard (byte-identical to the retired script, PR-4 golden).
67
72
  - "apps/cli/src/commands/workflow/commit-guard.ts"
68
73
  # WT-4 worktree-landing transports (D65 1242, flat since the inline group was deleted): they
package/config/workflow-candidates.json CHANGED
@@ -39,7 +39,7 @@
39
39
  "canonical": "wrapup-pipeline",
40
40
  "deadline": "2026-11-24",
41
41
  "createdAt": "2026-09-25",
42
- "rationale": "0944 (feature D64): a deterministic probe (`spur task wrapup drift-probe`, packages/app/src/workflow/wrapup/drift-probe.ts since script-absorption PR-5) runs only when the caller leaves wrapup mode empty and projects mode=fast when no changed path matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md ownership table) and every task's Solution change map parsed — clean wraps then skip doc-sync via the existing fast edge (fast:drift-probe-clean), any doubt stays on the safety path. Projected basis: doc-sync costs exactly 1 agent.run per wrapup (wrapup-pipeline declares one model query; 0938 baseline docs/reports/2026-09-workflow-cost-baseline.json has 0 recorded wrapup runs — agentRunCountMedian null — so the 1 is structural, never a measured median). Measurement gap honestly named: skipping doc-sync also skips learnings capture (0607 R2 merge), so clean wraps lose per-task learnings rows; measured post-promotion by comparing .spur/memory/wrapup-routes.log fast:drift-probe-clean counts against captured <runId>-wrapup-learnings.md files. For 0946 (measurement-only confirmation): the 0938 snapshot carries per-state rows in states[] but history-anatomy has zero of them (0 recorded runs — only task-pipeline/record exists), and cache hit/miss disposition lives in the history-anatomy provenance stamp (0659/0660, `spur history anatomy`, formerly history-anatomy-cache.ts), not in real-run-cost.ts; terminalReasonMix exists per workflow but history-anatomy's is empty. Measured-benefit status: projected from structure + 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
42
+ "rationale": "0944 (feature D64): a deterministic probe (`spur task wrapup drift-probe`, packages/app/src/workflow/wrapup/drift-probe.ts since script-absorption PR-5) runs only when the caller leaves wrapup mode empty and projects mode=fast when no changed path matches a doc-owned surface (AGENTS.md doc map + docs/99_PROJECT_CONSTITUTION.md ownership table) and every task's Solution change map parsed — clean wraps then skip doc-sync via the existing fast edge (fast:drift-probe-clean), any doubt stays on the safety path. Projected basis: doc-sync costs exactly 1 agent.run per wrapup (wrapup-pipeline declares one model query; 0938 baseline docs/reports/2026-09-workflow-cost-baseline.json has 0 recorded wrapup runs — agentRunCountMedian null — so the 1 is structural, never a measured median). Measurement gap honestly named: skipping doc-sync also skips learnings capture (0607 R2 merge), so clean wraps lose per-task learnings rows; measured post-promotion by comparing .spur/memory/wrapup-routes.log fast:drift-probe-clean counts against captured <runId>-wrapup-learnings.md files. For 0946 (measurement-only confirmation): the 0938 snapshot carries per-state rows in states[] but history-anatomy has zero of them (0 recorded runs — only task-pipeline/record exists), and cache hit/miss disposition lives in the history-anatomy provenance stamp (0659/0660, `spur history anatomy-*`, formerly history-anatomy-cache.ts), not in real-run-cost.ts; terminalReasonMix exists per workflow but history-anatomy's is empty. Measured-benefit status: projected from structure + 0938, NOT shadow-run-confirmed; `promotion evaluate` runs post-merge. If it does not beat the baseline, it is reverted (ADR-076).",
43
43
  "measurement": {
44
44
  "workflow": "wrapup-pipeline"
45
45
  },
package/config/workflows/history-anatomy.yaml CHANGED
@@ -4,7 +4,7 @@
4
4
  # Orchestration is configuration (ADR-022): a state machine over the existing dual-workflow
5
5
  # engine. The YAML owns ONLY the cache branch, deterministic stage ordering, executor dispatch,
6
6
  # bounded correction, and atomic publication sequencing. The deterministic cache/digest/
7
- # structure/publish work is `spur history anatomy <op>` (0659's helper, absorbed by script-absorption PR-6); the judgment (mode validity,
7
+ # structure/publish work is `spur history anatomy-<op>` (0659's helper, absorbed by script-absorption PR-6); the judgment (mode validity,
8
8
  # what counts as evidence, the report contract, enrich/validate rubrics) is 0658's skill. Per
9
9
  # ADR-069 R1, cache-decide / digest / structure-check / publish must NOT be inline shell — every
10
10
  # shell action here is glue length (a single helper invocation), because each of those programs
@@ -108,11 +108,11 @@ states:
108
108
  onEnter:
109
109
  - kind: shell
110
110
  options:
111
- # Path arithmetic lives in `spur history anatomy paths` (ADR-069 R1; script-absorption
111
+ # Path arithmetic lives in `spur history anatomy-paths` (ADR-069 R1; script-absorption
112
112
  # PR-6 — HA_HELPER is the running spur, HA_SKILL the resolved skill dir). Avoid
113
113
  # `${...}` here — that syntax collides with the engine's own template interpolation.
114
114
  command: >-
115
- $spurBin history anatomy paths --report-dir "$reportDir" --date "$date"
115
+ $spurBin history anatomy-paths --report-dir "$reportDir" --date "$date"
116
116
  --output "$output" --mode "$mode" --since "$since" --until "$until"
117
117
  --focus "$focus" --recompute "$recompute" --run-id "$__runId"
118
118
  --out .spur/run/$__runId-paths.txt
@@ -146,7 +146,7 @@ states:
146
146
  options:
147
147
  command: >-
148
148
  . .spur/run/$__runId-paths.txt;
149
- $spurBin history anatomy probe --artifact .spur/run/$__runId-history-anatomy-current.json
149
+ $spurBin history anatomy-probe --artifact .spur/run/$__runId-history-anatomy-current.json
150
150
  --baseline .spur/run/$__runId-history-anatomy-baseline.json --target "$HA_TARGET"
151
151
  --mode "$mode" --date "$HA_DATE" --recompute "$recompute" --executor "$agent"
152
152
  --skill-dir "$HA_SKILL" --contract "$HA_SKILL/references/report-contract.md"
@@ -187,7 +187,7 @@ states:
187
187
  - kind: shell
188
188
  options:
189
189
  command: >-
190
- $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-enrich.txt --expect .spur/run/$__runId-candidate.md
190
+ $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-enrich.txt --expect .spur/run/$__runId-candidate.md
191
191
 
192
192
  - id: structure-gate
193
193
  description: >
@@ -198,7 +198,7 @@ states:
198
198
  - kind: shell
199
199
  options:
200
200
  command: >-
201
- $spurBin history anatomy check \
201
+ $spurBin history anatomy-check \
202
202
  .spur/run/$__runId-candidate.md > .spur/run/$__runId-structure-gate.txt 2>&1 || true
203
203
 
204
204
  - id: validate
@@ -264,7 +264,7 @@ states:
264
264
  - kind: shell
265
265
  options:
266
266
  command: >-
267
- $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-validate.txt --expect .spur/run/$__runId-validation.txt
267
+ $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-validate.txt --expect .spur/run/$__runId-validation.txt
268
268
 
269
269
  - id: correct
270
270
  description: >
@@ -301,7 +301,7 @@ states:
301
301
  - kind: shell
302
302
  options:
303
303
  command: >-
304
- $spurBin history anatomy assert-clean --baseline .spur/run/$__runId-baseline-correct.txt --expect .spur/run/$__runId-candidate.md
304
+ $spurBin history anatomy-assert-clean --baseline .spur/run/$__runId-baseline-correct.txt --expect .spur/run/$__runId-candidate.md
305
305
 
306
306
  - id: refresh-provenance
307
307
  description: >
@@ -314,7 +314,7 @@ states:
314
314
  options:
315
315
  command: >-
316
316
  . .spur/run/$__runId-paths.txt;
317
- $spurBin history anatomy refresh --report "$HA_TARGET"
317
+ $spurBin history anatomy-refresh --report "$HA_TARGET"
318
318
  --out .spur/run/$__runId-publishable.md --disposition hit
319
319
 
320
320
  - id: stamp
@@ -328,7 +328,7 @@ states:
328
328
  options:
329
329
  command: >-
330
330
  . .spur/run/$__runId-paths.txt;
331
- $spurBin history anatomy stamp --candidate .spur/run/$__runId-candidate.md
331
+ $spurBin history anatomy-stamp --candidate .spur/run/$__runId-candidate.md
332
332
  --provenance .spur/run/$__runId-provenance.json
333
333
  --out .spur/run/$__runId-publishable.md
334
334
 
@@ -343,7 +343,7 @@ states:
343
343
  command: >-
344
344
  . .spur/run/$__runId-paths.txt;
345
345
  mkdir -p "$(dirname "$HA_TARGET")";
346
- $spurBin history anatomy publish .spur/run/$__runId-publishable.md "$HA_TARGET"
346
+ $spurBin history anatomy-publish .spur/run/$__runId-publishable.md "$HA_TARGET"
347
347
 
348
348
  - id: published
349
349
  description: Terminal — report published atomically after a passing validation.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gobing-ai/spur",
3
- "version": "0.4.22",
3
+ "version": "0.4.24",
4
4
  "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
5
5
  "keywords": [
6
6
  "spur",
package/plugins/sp/commands/dev-runall.md CHANGED
@@ -102,7 +102,7 @@ full distinction.
102
102
  - **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — the section whose trigger has not fired is on demand.
103
103
  - **Publish the visible batch plan first (1105):** publish `A Prepare batch` (A1–A4) and `Z Batch
104
104
  report` before the first task, then one letter per task from `spur task batch-plan waves` after
105
- freeze/order and digit children from `spur task batch-plan task-children` at task start —
105
+ freeze/order and digit children from `spur task batch-plan-children` at task start —
106
106
  [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
107
107
  § 2.7 Visible batch plan.
108
108
  - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the engine loop (`spur workflow run --vars '{"executor":"host"}'` → work item → `spur workflow continue`); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.
package/plugins/sp/plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "sp",
3
- "version": "0.4.22",
3
+ "version": "0.4.24",
4
4
  "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
5
5
  }
package/plugins/sp/skills/dogfood-testing/SKILL.md CHANGED
@@ -82,11 +82,11 @@ The command forwards these via `$ARGUMENTS`:
82
82
  > <!-- pipeline-tokens:end -->
83
83
  > matched as a **distinct hyphen-word**
84
84
  > (machine-checked by
85
- > `detectPipelineDriving` (`spur agent dogfood gate`);
85
+ > `detectPipelineDriving` (`spur agent dogfood-gate`);
86
86
  > see [§Pipeline-driving word-boundary contract](#pipeline-driving-word-boundary-contract))
87
87
  > → `⚠ pipeline-driving testee detected; pass --max-retry 0 (observe-only) or --max-retry N (fix mode, tree mutation acknowledged)`.
88
88
  > - **Mutating `--fix` modes** — `--fix all` / `--fix blockers-first`, boundary-guarded via
89
- > `hasMutatingFixMode` (`spur agent dogfood gate`) (never matches
89
+ > `hasMutatingFixMode` (`spur agent dogfood-gate`) (never matches
90
90
  > `--fix none` / `--focus all` / `--prefix all`). No pipeline token required: a verify/review leg
91
91
  > with `--fix all` mutates the tree on its own (0280 dogfood P2, task 0293). Honesty note:
92
92
  > `--max-retry 0` here bounds **the driver only** — the testee still mutates the tree — so the
@@ -100,7 +100,7 @@ The command forwards these via `$ARGUMENTS`:
100
100
  in-agent):
101
101
 
102
102
  ```bash
103
- spur agent dogfood gate \
103
+ spur agent dogfood-gate \
104
104
  --testee "<raw testee string>" \
105
105
  [--max-retry-present]
106
106
  ```
@@ -121,7 +121,7 @@ The command forwards these via `$ARGUMENTS`:
121
121
  re-run the gate with the derived step labels:
122
122
 
123
123
  ```bash
124
- spur agent dogfood gate \
124
+ spur agent dogfood-gate \
125
125
  --testee "<raw testee string>" \
126
126
  --max-retry-present \
127
127
  --steps "step1 label||step2 label||..."
@@ -232,7 +232,7 @@ contract violation**.
232
232
  **before** claiming `status: complete`:
233
233
 
234
234
  ```bash
235
- spur agent dogfood validate-report --file <report-path>
235
+ spur agent dogfood-validate-report --file <report-path>
236
236
  ```
237
237
 
238
238
  Exit **0** → proceed. Exit **2** → set `status: aborted`, list every error code under §5
@@ -338,7 +338,7 @@ Do **not** use this skill for:
338
338
  Pipeline-driving detection is **word-boundary**, not leading-space substring. The live gate is:
339
339
 
340
340
  ```bash
341
- spur agent dogfood gate --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
341
+ spur agent dogfood-gate --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
342
342
  ```
343
343
 
344
344
  | Token shape | Examples | Matches | Rejects |
@@ -349,7 +349,7 @@ spur agent dogfood gate --testee "<testee>" [--max-retry-present] [--steps "…"
349
349
  `-` is a **word character** for boundaries: a token must be a distinct hyphen-word. Contract tests:
350
350
  `packages/app/tests/services/dogfood/pipeline-detect.test.ts`. Helpers:
351
351
  `detectPipelineDriving`, `isImplementHeavyStep`, `detectImplementHeavy`, `evaluateDogfoodGate` in
352
- `spur agent dogfood gate` (absorbed into the CLI; was `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts`).
352
+ `spur agent dogfood-gate` (absorbed into the CLI; was `plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts`).
353
353
 
354
354
  ## Mutating `--fix` mode contract
355
355
 
package/plugins/sp/skills/dogfood-testing/references/report-template.md CHANGED
@@ -336,7 +336,7 @@ Before the skill may stop (success, partial, fail, observe-only end, or abort),
336
336
  and mirror the footer block at the **end of the report file**. A report whose body lacks the
337
337
  footer cannot set `status: complete`.
338
338
  8. **Self-validate (task 0278 R6):** run
339
- `spur agent dogfood validate-report --file <report-path>` before
339
+ `spur agent dogfood-validate-report --file <report-path>` before
340
340
  claiming `status: complete`. Exit 2 → `status: aborted` + list error codes under
341
341
  `#### Unresolved` (never force complete on a non-@1.2 shape).
342
342
  9. **Refusal rule (@1.2):** when any check above fails, set `status: aborted` and list every
package/plugins/sp/skills/history-anatomy/references/modes.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  The skill resolves exactly two modes. Everything else fails loud. This matrix is the enforcement
4
4
  surface the workflow (0660) and the skill share; keep the vocabulary frozen. Execution note
5
- (0920): argument validation runs deterministically in `spur history anatomy paths`
5
+ (0920): argument validation runs deterministically in `spur history anatomy-paths`
6
6
  (formerly the `history-anatomy-cache` helper) (logic core: `packages/app/src/services/history-anatomy.ts`, task 1005) before the
7
7
  workflow starts; the model hop no longer performs it.
8
8
 
package/plugins/sp/skills/spur-cli/references/agent.md CHANGED
@@ -30,7 +30,8 @@ that before using `run` for fan-out dispatch.
30
30
  | `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to `queued` | `[id]` `--session-id <sid>` `--json` |
31
31
  | `status` | Agent specs with live process status and member session (requires `spur self serve`) | `--server <url>` `--json` |
32
32
  | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
33
- | `dogfood <gate\|validate-report>` | `sp:dogfood-testing` gates: pipeline-driving refusal (exit 2) and report-contract validation (exit 2) | `--testee` `--max-retry-present` `--steps` `--file` `--json` |
33
+ | `dogfood-gate` | `sp:dogfood-testing` gate: pipeline-driving refusal (exit 2) | `--testee` `--max-retry-present` `--steps` `--json` |
34
+ | `dogfood-validate-report` | `sp:dogfood-testing` report-contract validation (exit 2) | `--file` `--json` |
34
35
  | `usage` | Run-once provider usage capture (codexbar) → quota-owned availability refresh; scheduled externally | `--dry-run` `--source <name>` `--json` |
35
36
  | `start <spec-id>` | Start a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
36
37
  | `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
@@ -332,12 +333,12 @@ Posts to the supervisor API
332
333
  (`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
333
334
  `start`.
334
335
 
335
- ## `dogfood` - dogfood-testing gates
336
+ ## `dogfood-gate` / `dogfood-validate-report` - dogfood-testing gates
336
337
 
337
338
  ```bash
338
- spur agent dogfood gate --testee "/sp:dev-run 0123" --json # exit 2 = refuse (pipeline-driving, no --max-retry)
339
- spur agent dogfood gate --testee "…" --steps "plan||implement" # Phase 1 W8 re-check
340
- spur agent dogfood validate-report --file report.md --json # exit 2 = contract errors
339
+ spur agent dogfood-gate --testee "/sp:dev-run 0123" --json # exit 2 = refuse (pipeline-driving, no --max-retry)
340
+ spur agent dogfood-gate --testee "…" --steps "plan||implement" # Phase 1 W8 re-check
341
+ spur agent dogfood-validate-report --file report.md --json # exit 2 = contract errors
341
342
  ```
342
343
 
343
344
  Absorbed from `plugins/sp/scripts/dogfood-testing/` (script-absorption PR-7). `--json` here prints
package/plugins/sp/skills/spur-cli/references/builder.md CHANGED
@@ -20,8 +20,7 @@ This noun is **frozen at exactly eight verbs** (`bump-ver`, `drop-tags`, `publis
20
20
  script-absorption entries; `show-branches` and the four flat PR verbs `pr-status`, `pr-check`,
21
21
  `pr-open`, `pr-review` from the 2026-10-16 feature-L1 entries) by operator consent
22
22
  (`docs/design/harness-surface-governance.md` §3) — do not invent additional `builder` subcommands.
23
- The former `pr <op>` pass-through stays registered as a **hidden, deprecated alias** for one release
24
- (it prints one stderr deprecation line naming the replacement verb), so it is not listed here.
23
+ The former `pr <op>` pass-through was removed by task 1290 (two-level `spur <noun> <verb>` rule).
25
24
 
26
25
  ## Verb map
27
26
 
@@ -96,12 +95,6 @@ PR); `pr-check` → `{ ok, verdict, preflight, hygiene }`; `pr-open` → `{ ok,
96
95
  and returns `PENDING` when a marked request is still in flight; `--force` requests a fresh review
97
96
  of the current HEAD regardless. Never force-pushes.
98
97
 
99
- ```bash
100
- # deprecated alias, one release: maps the old op names to the verbs above
101
- spur builder pr preflight --json # -> spur builder pr-check
102
- spur builder pr status --json # -> spur builder pr-status
103
- ```
104
-
105
98
  ## `show-branches` - read-only branch topology report
106
99
 
107
100
  ```bash
package/plugins/sp/skills/spur-cli/references/history.md CHANGED
@@ -9,7 +9,7 @@ see_also:
9
9
 
10
10
  `spur history` is the local history data plane: import transcripts into SQLite, aggregate a
11
11
  versioned artifact, render that artifact, or run the daily composition. Command registration and
12
- CLI guards live in `apps/cli/src/commands/history.ts` (`registerHistoryCommand`); payload contracts
12
+ CLI guards live in `apps/cli/src/commands/history/` (`registerHistoryCommand` in `index.ts`, one file per verb); payload contracts
13
13
  live in `packages/app/src/services/history-service.ts` (`FanOutResult`, `DailyResult`,
14
14
  `HistoryService`, `runHistoryReport`) and `packages/domain/src/analytics/artifact.ts`
15
15
  (`HistoryArtifact`).
@@ -23,7 +23,14 @@ live in `packages/app/src/services/history-service.ts` (`FanOutResult`, `DailyRe
23
23
  | `report [path]` | Purely render an existing artifact; default to `latest.json` | `--mode <name>` `--task <wbs>` `--top <n>` `--json` |
24
24
  | `daily` | Run import-all → analyze → artifact → 90-day report pruning once | `--since <iso>` `--until <iso>` `--root <path>` `--source-timeout <ms>` `--mode <name>` `--json` |
25
25
  | `reset` | Destructively wipe every `history_*` table for a clean re-import; refuses without `--yes` | `--yes` `--json` |
26
- | `anatomy <op>` | history-anatomy cache ops behind the `history-anatomy` workflow (`digest`, `check`, `paths`, `assert-clean`, `probe`, `stamp`, `refresh`, `publish`) | op argv (see `spur history anatomy --help`) |
26
+ | `anatomy-digest` | history-anatomy cache op `digest` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-digest --help`) |
27
+ | `anatomy-check` | history-anatomy cache op `check` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-check --help`) |
28
+ | `anatomy-paths` | history-anatomy cache op `paths` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-paths --help`) |
29
+ | `anatomy-assert-clean` | history-anatomy cache op `assert-clean` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-assert-clean --help`) |
30
+ | `anatomy-probe` | history-anatomy cache op `probe` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-probe --help`) |
31
+ | `anatomy-stamp` | history-anatomy cache op `stamp` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-stamp --help`) |
32
+ | `anatomy-refresh` | history-anatomy cache op `refresh` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-refresh --help`) |
33
+ | `anatomy-publish` | history-anatomy cache op `publish` behind the `history-anatomy` workflow | op argv (see `spur history anatomy-publish --help`) |
27
34
  | `timeline` | Per-prompt work/wait time and tokens from the host transcript (JSON), for `sp:session-review` | `--transcript <path>` `--group <spec>` |
28
35
  | `summary` | Daily summary report for `sp:daily-summary` (tokens, git, history health, annotations) | `--date <d>` `--dry-run` `--output <path>` `--no-git` `--no-ccusage` |
29
36
 
package/plugins/sp/skills/spur-cli/references/tasks.md CHANGED
@@ -49,7 +49,8 @@ re-reading or re-tokenizing the task.
49
49
  | `migrate-anchors` | Qualify in-repo evidence anchors to repo-relative paths (0583 R1–R3); `--wbs` scopes to one task file (1109 R1); retargets scratch `done_reason` verdict pointers (1140) | `--wbs` `--dry-run` `--json` |
50
50
  | `refresh-roster <wbs>` | Regenerate a parent task's sub-task roster block in `## Plan` | `--folder` `--json` |
51
51
  | `batch-create` | Create many tasks from a validated JSON array | `--file <path>` `--skip-ready` `--agent <selector>` `--folder` `--json` |
52
- | `batch-plan <mode>` | Batch plan projection: `waves` / `order` / `task-children` (JSON on stdout; the batch driver's visible plan) | `--tasks <file>` `--concurrency <n>` `--letter <A-Z>` `--plan <file>` |
52
+ | `batch-plan <mode>` | Batch plan projection: `waves` / `order` (JSON on stdout; the batch driver's visible plan) | `--tasks <file>` `--concurrency <n>` |
53
+ | `batch-plan-children` | One task row's phase digits from the visible plan (JSON on stdout) | `--letter <A-Z>` `--plan <file>` |
53
54
  | `preflight [wbs]` | Read-only batch admission: TABLE A STOP check, quick readiness (`--operation`), one-shot recovery hop; status/deps read from the corpus unless given | `--status <s>` `--deps <list>` `--dep-status <map>` `--operation <op>` `--filtered-count <n>` `--required-sections <list>` `--present-sections <list>` `--force` `--recovery` `--classify-feature <json>` `--folder` `--json` |
54
55
  | `wrapup <op>` | One deterministic `wrapup-pipeline` step (`resolve`, `route-reason`, `metrics`, `doc-sync-snapshot`, `doc-sync-scope`, `doc-supersession`, `drift-probe`) — workflow-internal | `--run-id <id>` `--tasks <json>` `--mode <m>` `--spur-bin <cmd>` |
55
56
  | `record <wbs>` | Write `Testing` from a verify verdict (deterministic); bare-`## Review` fallback only; optional Solution + transition | `--verdict-file <path>` `--solution-from-diff` `--transition <status>` `--folder` `--json` |
package/plugins/sp/skills/spur-cli/references/workflows.md CHANGED
@@ -121,7 +121,9 @@ The skill's logic divides by **whether the LLM adds value**:
121
121
  | `cost` | `spur workflow cost` (CLI) | `[--workflow <name>]… [--by-state] [--include-bookkeeping] [--since <date>] [--budget <file>] [--measured-file <json>] [--json]` | Real terminal non-dry run measurements, or a budget result; unknown measurements stay null. Budget failures exit 1 |
122
122
  | `persist-out` | `spur workflow persist-out` (CLI) | `--from <worktree> [--task-file <path>]…` | WT-4 landing: copy a worktree's run rows, two-file records and cited/owned evidence into the invoking tree before teardown; exit 1 fail closed (retain the worktree) |
123
123
  | `persist-check` | `spur workflow persist-check` (CLI) | `--from <worktree> [--task-file <path>]… [--run-id <id>]… [--root <tree>] [--success-json <path>]` | WT-4 pre-removal assertion that the worktree owns no unpersisted durable evidence; exit 0 ok / 1 blocked or divergent / 2 usage |
124
- | `commit-guard` | `spur workflow commit-guard <op>` (CLI) | `start\|stage\|check --run <id> [--base <sha>] [-- <paths…>]` | Stages only paths this run wrote; exit 2 when a listed path is refused, 3 on unmerged/conflict-marked targets |
124
+ | `commit-guard-start` | `spur workflow commit-guard-start` (CLI) | `--run <id>` | Fingerprint HEAD and the dirty working files into `.spur/run/<run>-tree-start.json` |
125
+ | `commit-guard-stage` | `spur workflow commit-guard-stage` (CLI) | `--run <id> [--base <sha>] [-- <paths…>]` | Stages only paths this run wrote; exit 2 when a listed path is refused, 3 on unmerged/conflict-marked targets |
126
+ | `commit-guard-check` | `spur workflow commit-guard-check` (CLI) | `--run <id> [--base <sha>]` | Report working-tree changes this run did not write; stage nothing. The nested `commit-guard <op>` spelling was removed (task 1290) |
125
127
  | `add` | agent procedure | `"<nl-description>" [--kind <state-machine\|transition-flow>] [--file <path>]` | **Mode chosen (confirmed)** → first reconciled against existing workflows (extend an existing flow rather than duplicate) → YAML authored in real schema shape → **validated AND dry-run** (reaches the expected terminal state) → [add](workflows/operations.md#add) |
126
128
  | `refine` | agent procedure | `<workflow-file> [--intent "<goal>"] [--dry-run]` | Smallest change meeting the intent, re-validated and re-dry-run; `--dry-run` emits a diff only → [refine](workflows/operations.md#refine) |
127
129
 
@@ -277,7 +279,9 @@ spur workflow profile <workflow> [--last <n>] [--window <sec>] [--spur-bin <cmd
277
279
  spur workflow cost [--workflow <name>]... [--by-state] [--include-bookkeeping] [--since <YYYY-MM-DD>] [--budget <file>] [--measured-file <json>] [--json]
278
280
  spur workflow persist-out --from <worktree> [--task-file <path>]...
279
281
  spur workflow persist-check --from <worktree> [--task-file <path>]... [--run-id <id>]... [--root <tree>]
280
- spur workflow commit-guard <op> [options]
282
+ spur workflow commit-guard-start --run <id>
283
+ spur workflow commit-guard-stage --run <id> [--base <sha>] [-- <paths>...]
284
+ spur workflow commit-guard-check --run <id> [--base <sha>]
281
285
  ```
282
286
 
283
287
  ### `cost` — real-run measurements and budgets
package/plugins/sp/skills/spur-dev/references/execution-batch-report.md CHANGED
@@ -185,11 +185,11 @@ batch tip — the step that makes the close-out the report's own contradiction).
185
185
  is never a point on the base ref.
186
186
  Stage them through the guard — never a free-form `git add` — so a concurrent writer's file cannot
187
187
  ride into the close-out commit (incident `36f274590`). `$RUN_ID` is the id Step 3 fixed before
188
- `spur workflow commit-guard start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:
188
+ `spur workflow commit-guard-start` (execution-batch.md § Step 3); an unset id makes the guard exit 1 — fail closed:
189
189
 
190
190
  ```bash
191
- spur workflow commit-guard check --run "$RUN_ID" # 1129 R3: a non-empty foreign list goes in the batch report
192
- spur workflow commit-guard stage --run "$RUN_ID" -- <files the wrap wrote> \
191
+ spur workflow commit-guard-check --run "$RUN_ID" # 1129 R3: a non-empty foreign list goes in the batch report
192
+ spur workflow commit-guard-stage --run "$RUN_ID" -- <files the wrap wrote> \
193
193
  || { echo "close-out halt: commit-guard refused a path (foreign, unmerged or conflict-marked); nothing committed" >&2; exit 1; }
194
194
  git commit -m "chore(wrap): <command> <selector> close-out writes"
195
195
  ```
package/plugins/sp/skills/spur-dev/references/execution-batch.md CHANGED
@@ -311,7 +311,7 @@ per-task letter is ever hand-assigned.
311
311
  `spur workflow show task-pipeline.yaml --no-logo --format todo --json` payload:
312
312
 
313
313
  ```bash
314
- spur task batch-plan task-children --letter <task-letter> --plan <plan.json>
314
+ spur task batch-plan-children --letter <task-letter> --plan <plan.json>
315
315
  ```
316
316
 
317
317
  4. **When a task ends:** mark the task's letter (and its published digits) with the task's terminal
@@ -327,7 +327,7 @@ plan = resolve(--tasks) → freeze → order(deps) # may abort (cycle) or
327
327
  report = []
328
328
  publish visible plan §2.7: A/Z rows now; one letter per task after this freeze (task batch-plan waves)
329
329
  RUN_ID = WT-3 marker id under --worktree, else "batch-$(date -u +%Y%m%dT%H%M%SZ)" # fixed ONCE here; the close-out reuses it
330
- spur workflow commit-guard start --run "$RUN_ID" # 1129 R1: fingerprint before the first task writes; the close-out commit stages through it
330
+ spur workflow commit-guard-start --run "$RUN_ID" # 1129 R1: fingerprint before the first task writes; the close-out commit stages through it
331
331
  for wbs in plan: # default sequential mode
332
332
  if any dependency of wbs failed earlier in THIS batch:
333
333
  report += skipped(wbs, reason); continue # only relevant under --keep-going
@@ -338,7 +338,7 @@ for wbs in plan: # default sequential mode
338
338
  preflight = spur task preflight <wbs> # Step 2.6 — TABLE A STOP
339
339
  if preflight.action == skip:
340
340
  report += preflight-skip(wbs, preflight); continue
341
- visible plan (§2.7): letter in_progress + task-children digits at start; letter ← outcome at end
341
+ visible plan (§2.7): letter in_progress + batch-plan-children digits at start; letter ← outcome at end
342
342
  run: if interactive sequential omit/inline:
343
343
  spur workflow run task-pipeline.yaml --vars <vars with executor=host> --json
344
344
  perform the returned work item; spur workflow continue <run-id> --answer-text <receipt>
package/plugins/sp/skills/spur-dev/references/execution-worktree-landing.md CHANGED
@@ -453,14 +453,14 @@ git checkout <base-ref> && git merge --no-ff -m "<prepared message>" <branch>
453
453
  # the batch's run id, the same one WT-3b's worktree fingerprint used — the two trees keep two
454
454
  # artifacts under the same id):
455
455
  # RUN_ID="<marker-id>" # the WT-3 marker's id
456
- # spur workflow commit-guard start --run "$RUN_ID"
456
+ # spur workflow commit-guard-start --run "$RUN_ID"
457
457
  # git checkout <base-ref> && git merge --no-commit <branch>
458
458
  # 2. resolve source conflicts by hand; generated files are then regenerated with the project's
459
459
  # generator, never hand-merged
460
460
  # (this repo: bun run --filter @gobing-ai/spur build:bundle)
461
461
  # 3. stage every resolved path and regenerated bundle through the guard — an unmerged or
462
462
  # unstaged path makes step 5 abort, and a conflict-marked path exits 3 (resolve, then retry):
463
- # spur workflow commit-guard stage --run "$RUN_ID" -- <resolved paths and regenerated bundles>
463
+ # spur workflow commit-guard-stage --run "$RUN_ID" -- <resolved paths and regenerated bundles>
464
464
  # Forbidden here as in every driver commit step: `git add -A` and `git add .`.
465
465
  # 4. run qualityGateCmd once, after ALL conflicts are resolved
466
466
  # 5. commit the merge with the prepared message file — CHECK THE PARENTS FIRST (step 5a)
package/plugins/sp/skills/spur-dev/references/execution-worktree-setup.md CHANGED
@@ -352,7 +352,7 @@ fingerprints the invoking tree for the same reason (its own step 1b).
352
352
  [ "$(git branch --show-current)" = "$BRANCH" ] \
353
353
  || { echo "branch mismatch: expected $BRANCH, got $(git branch --show-current)" >&2; exit 1; }
354
354
  RUN_ID="<marker-id>" # the WT-3 marker's id — the same id WT-3b's stage call uses
355
- spur workflow commit-guard start --run "$RUN_ID" # <worktree>/.spur/run/$RUN_ID-tree-start.json = { head, dirty[] }
355
+ spur workflow commit-guard-start --run "$RUN_ID" # <worktree>/.spur/run/$RUN_ID-tree-start.json = { head, dirty[] }
356
356
  )
357
357
  ```
358
358
 
@@ -368,8 +368,8 @@ same call, verifies the WT-3 identity, and never relies on a persistent `cd` or
368
368
  cd -- "../<worktree-dir>" || { echo "tree missing: expected ../<worktree-dir>" >&2; exit 1; }
369
369
  [ "$(git branch --show-current)" = "$BRANCH" ] \
370
370
  || { echo "branch mismatch: expected $BRANCH, got $(git branch --show-current)" >&2; exit 1; }
371
- spur workflow commit-guard check --run "$RUN_ID" # 1129 R3: concurrent foreign writers; a non-empty list goes in the batch report
372
- spur workflow commit-guard stage --run "$RUN_ID" -- <files-the-batch-wrote> \
371
+ spur workflow commit-guard-check --run "$RUN_ID" # 1129 R3: concurrent foreign writers; a non-empty list goes in the batch report
372
+ spur workflow commit-guard-stage --run "$RUN_ID" -- <files-the-batch-wrote> \
373
373
  || { echo "WT-3b halt: commit-guard refused a path (foreign, unmerged or conflict-marked); nothing committed" >&2; exit 1; }
374
374
  git commit -m "<type>(<scope>): <command> <selector> batch writes"
375
375
  )
@@ -377,7 +377,7 @@ same call, verifies the WT-3 identity, and never relies on a persistent `cd` or
377
377
 
378
378
  > **Forbidden in every driver commit step:** `git add -A` and `git add .`. They stage whatever a
379
379
  > concurrent writer happened to leave in the tree — the two incidents this guard exists for are
380
- > `a94f9f431` and `36f274590` — so a driver stages only through `spur workflow commit-guard stage`.
380
+ > `a94f9f431` and `36f274590` — so a driver stages only through `spur workflow commit-guard-stage`.
381
381
 
382
382
  > **`stage` takes files, never directories.** A directory argument is refused as `(unchanged since
383
383
  > base)` and stages *nothing*, so a task whose diff lives in a moved tree must expand the changed