@gobing-ai/spur 0.4.30 → 0.4.31

package/.claude-plugin/marketplace.json

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

package/config/workflows/history-anatomy.yaml

@@ -144,11 +144,13 @@ states:
     onEnter:
       - kind: shell
         options:
+          # 1326: the selector is NOT provenance. `--executor "$agent"` used to stamp the literal
+          # `auto`; the resolved executor/model now come from the run's own action receipts at stamp.
           command: >-
             . .spur/run/$__runId-paths.txt;
             $spurBin history anatomy-probe --artifact .spur/run/$__runId-history-anatomy-current.json
             --baseline .spur/run/$__runId-history-anatomy-baseline.json --target "$HA_TARGET"
-            --mode "$mode" --date "$HA_DATE" --recompute "$recompute" --executor "$agent"
+            --mode "$mode" --date "$HA_DATE" --recompute "$recompute"
             --skill-dir "$HA_SKILL" --contract "$HA_SKILL/references/report-contract.md"
             --workflow "$workflowFile" --helper "$HA_HELPER" --contract-version "$contractVersion" --run-id "$__runId"
             --out .spur/run/$__runId-provenance.json
@@ -322,14 +324,23 @@ states:
       Cache-miss path. Attaches the full R7 frontmatter provenance block (identity tuple, window
       state, generated/validated timestamps, artifact paths + digests, contract/skill/workflow
       digests, per-source coverage + last_imported_at, spur/schema version, executor, run id,
-      cache disposition) and the freshness banner to the validated candidate.
+      cache disposition) and the freshness banner to the validated candidate. 1326 R5/R6: the
+      validated timestamp and the per-action executor/model rows come from the run's OWN receipts
+      (the validation artifact and the run trace), never from probe time or the selector.
     onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run;
+            $spurBin workflow trace "$__runId" --json > .spur/run/$__runId-trace.json
       - kind: shell
         options:
           command: >-
             . .spur/run/$__runId-paths.txt;
             $spurBin history anatomy-stamp --candidate .spur/run/$__runId-candidate.md
             --provenance .spur/run/$__runId-provenance.json
+            --validation .spur/run/$__runId-validation.txt
+            --trace .spur/run/$__runId-trace.json
             --out .spur/run/$__runId-publishable.md
 
   - id: publish

package/config/workflows/task-pipeline.yaml

@@ -539,6 +539,11 @@ states:
                 executable: "${vars.spurBin}"
                 args: ["task", "gate", "${vars.wbs}", "${vars.gateMode}", "--no-logo"]
                 resultFile: .spur/run/${vars.__runId}-gate.status
+                # 1322 R1/R4: the step's own output persists at the gate log (`.spur/run/<wbs>-gate.log`),
+                # so the driver's single bounded wait reads evidence from a known path instead of
+                # sleep-polling, and a failing gate carries the resolved path in its step result
+                # (`data.logFile`) — remediation reads evidence without re-running anything.
+                logFile: .spur/run/${vars.wbs}-gate.log
                 softFail: true
                 # 1319 R2(c): group-owned backstop. The gate's own per-spawn bound (R1) bounds
                 # each command; this bounds the action and reaps any surviving descendant.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.4.30",
+    "version": "0.4.31",
     "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",

package/plugins/sp/plugin.json

@@ -1,5 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.30",
+    "version": "0.4.31",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
 }

package/plugins/sp/skills/history-anatomy/references/operations.md

@@ -35,6 +35,14 @@ Given the current and baseline artifacts, author the model half of the report. A
    ownerSurface). Categories from the closed vocabulary; stable keys of the form
    `<category>:<owner-surface>:<signal>`. Severity is the closed P1/P2/P3 vocabulary; reproCommand reproduces the observation verbatim; ownerSurface names
    the concrete owning surface (file/package/command), consistent with the key's middle segment.
+   **Every derived numeric comparison, delta, ratio, or sum in `observation`/`inference` carries an
+   adjacent `calc:` assertion** (grammar in `report-contract.md`). Write the arithmetic, do not
+   assert the conclusion: a claim that one figure is larger needs `calc: <a> > <b>`, a gap needs
+   `calc: <a> - <b> = <gap>`. The deterministic structure gate fails a false assertion
+   (`arithmetic-contradiction`), a missing one on a derived field (`arithmetic-evidence-missing`),
+   and an unparsable one (`arithmetic-invalid-assertion`) before validation runs — the observed
+   2026-11-08 inversion (`719,838,772` called larger than `725,707,709`) burned a full correction
+   pass precisely because no gate could see it.
 4. **Recurrence ledger** — classify every finding against the baseline on the **stable key**.
 5. **Telemetry gaps** — every dimension the artifact cannot support, rendered `not available`.
 6. **Remediation options** — proposals only (owner surface, expected impact, verification method,
@@ -74,6 +82,9 @@ Given a candidate report and the artifacts, independently verify:
 - **Positive patterns** — held to the same standard; an anchor-less entry FAILs.
 - **Remediation** — proposals only; any applied change, diff, or command the report claims to have
   run FAILs.
+- **Arithmetic** — every `calc:` assertion recomputes; a claim whose assertion does not hold, or a
+  derived claim with no assertion, is a finding against the report. Independent validation still
+  owns whether the operands belong to the cited artifact; the deterministic gate owns the math.
 
 Emit `PASS` only when every rule holds. On FAIL, name the section, the finding key, and the rule
 violated. Never launch a workflow.

package/plugins/sp/skills/history-anatomy/references/report-contract.md

@@ -68,6 +68,34 @@ Every finding — problem and positive alike — carries the full field set:
 | `reproCommand` | The invocation that reproduces the observation — one command a reader can run verbatim (0680 R2). Gate-enforced. |
 | `ownerSurface` | The concrete surface that owns the fix (a file path, package, or command), consistent with the key's `<owner-surface>` segment but named as a target rather than a slug (0680 R3). Gate-enforced. |
 
+## Arithmetic assertions (`calc:`) — task 1326
+
+A field that makes a **derived numeric claim** must carry its arithmetic next to it, in the same
+field, as a machine-checkable line. The deterministic structure gate (`checkReportStructure`)
+rejects a false assertion and a derived claim that has none — before independent validation, so the
+model validator is never the only arithmetic check.
+
+Grammar (frozen; no `eval`, no parentheses, no unit suffixes, no arbitrary JavaScript):
+
+```text
+calc: <number> <+|-> [number ...] = <number>      # left-associative sums and deltas
+calc: <number> * <number> = <number>              # product
+calc: <number> / <number> = <number>              # ratio
+calc: <number> <|<=|>|>= <number>                 # ordering claim
+```
+
+- Integers are exact; a non-integer result uses a relative tolerance of `1e-9`.
+- The label may be written bare (`calc: …`) or as inline code (`` `calc`: … ``) — the gate accepts
+  both, and both must parse.
+- **Detection is deterministic and vocabulary-based.** An `observation` or `inference` field counts
+  as derived when it contains `%` or one of `larger|smaller|higher|lower|more than|less than|above|
+  below|exceeds|dominates|gap|delta|difference|sum|sums|sum of|share|ratio|mean|average`
+  (case-insensitive). Naming a raw artifact field alone (`totals.inputTokens`) is not a derived
+  claim. A grammar failure is `arithmetic-invalid-assertion`; a false assertion is
+  `arithmetic-contradiction`; a derived field with no assertion is `arithmetic-evidence-missing`.
+- The assertion names the arithmetic; the operands still have to belong to the cited artifact, and
+  that ownership check stays with independent validation. The gate never silently corrects a report.
+
 ## Evidence rules
 
 Enforcement rail for every claim:

package/plugins/sp/skills/spur-cli/references/tasks.md

@@ -28,18 +28,56 @@ spur task get  <wbs> --json  # alias of `show` — same output, no separate code
 spur task path <wbs> --json  # absolute path only
 ```
 
+Sectioned and summary reads (task 1325) stay on the same resolution path — see
+[Sectioned and summary reads](#sectioned-and-summary-reads-task-1325).
+
 Do not search `docs/tasks*` or guess `--folder` to locate a known WBS. `show` is the default when an
 agent needs to read a task; use `path` only when another filesystem command needs the absolute path.
 Both commands resolve across configured task folders. Add `--folder` only when deliberately limiting
 the lookup to one non-default corpus. Capture `show` once per run and reuse its response instead of
 re-reading or re-tokenizing the task.
 
+## Sectioned and summary reads (task 1325)
+
+`show` can return part of a task instead of the whole body — useful when an agent only needs one
+section or an index:
+
+- **`--section <name>`** (repeatable) and **`--sections "A,B"`** (CSV) return only the named
+  sections. Each entry carries `name`, `headingLine`, `byteCount` (Buffer bytes, multi-byte aware),
+  and `content` — the section byte-exact as it sits in the file (heading line through the line
+  before the next heading), suitable for exact `--from-file`-style reuse. Frontmatter metadata and
+  `filePath` ride along; `totalBytes` is the whole file's byte size. Sections return in **file
+  order**, duplicates collapse. Unknown names exit `3` (same channel as `sections list`) and name
+  the valid sections.
+- **`--summary`** returns the full section index (`name`/`headingLine`/`byteCount` per section plus
+  `totalBytes`) with **no** `content` fields — the cheap table-of-contents probe. `--summary` cannot
+  be combined with `--section`/`--sections` (exit `2`).
+
+```bash
+spur task show 1325 --section Plan --json           # one section, byte-exact
+spur task show 1325 --section Plan --section Q&A    # repeatable, file order
+spur task show 1325 --sections "Plan,History" --json
+spur task show 1325 --summary --json                # index only, no bodies
+```
+
+## Write-time size advisory (task 1325)
+
+`create` and `batch-create` (and the service-level `updateBody` write path) report the written
+file's size against the precheck budget at write time: a task at or over the R-item /
+prose-paragraph threshold gets a `Task has N R-items (max 10)`-style advisory in the write
+result's `warnings[]`. The advisory **never blocks the write** — it is the authoring-time early
+warning that `task check --precheck` enforces as a gate later. Rendering: single `create`
+surfaces top-level `warnings` in `--json` and prints each advisory bare to stderr in human
+mode; `batch-create` surfaces per-child `warnings` rows (`[{"wbs", "warnings"}]`, present only
+when non-empty) in `--json` and prints `<wbs>: <warning>` lines to stderr in human mode;
+`update --section` section writes carried this advisory already.
+
 ## Verb map
 
 | Verb | Purpose | Key flags |
 | ---- | ------- | --------- |
 | `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--no-reopen` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--skip-ready` `--agent <selector>` `--folder` `--json` |
-| `show <wbs>` | Print one task's frontmatter + body | `--folder` `--json` |
+| `show <wbs>` | Print one task's frontmatter + body; section-filtered or summary mode (1325) | `--section <name>` `--sections <csv>` `--summary` `--folder` `--json` |
 | `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (exclusive with `--section`) `--feature <id>` `--no-reopen` `--priority <p>` `--ac-numbering task-local` `--ac-altitude <a>` `--estimate-hours <n>` `--no-lifecycle` `--force-done` `--reason <text>` `--provenance-bypass` `--verdict-dir <path>` `--folder` `--json` |
 | `deps <wbs> <op> [values...]` | Mutate `dependencies[]` frontmatter array (ops: `set`, `add`, `remove`, `clear`) | `--folder` `--json` |
 | `sections <wbs> <op> [name]` | Initialize, add, or list canonical task sections (ops: `init`, `add`, `list`) | `--folder` `--json` |

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -470,6 +470,32 @@ implement stage then conflated. The pipeline precheck prints a WARNING with the
 tree has uncommitted non-corpus changes; treat it as a stop-and-commit, not noise. It warns rather
 than blocks because a legitimately in-progress tree is the operator's call.
 
+## Long-running commands: launch detached, wait bounded
+
+Applies whenever a step runs a command that takes minutes — full gates, coverage passes, e2e
+rehearsals, engine runs. KK's post-0.4.30 history analysis (2026-11-10) shows the failure mode:
+implement sessions spent **88 minutes in literal `sleep` calls plus 28 poll loops** babysitting
+~18-minute gates, and one rehearsal session emitted **3,455 near-identical poll messages over 14.5
+hours** while hand-dispatching LLM stages as background tasks.
+
+- **Start it detached, then wait once, bounded.** Background the process with a log file
+  (`cmd > .spur/run/<name>.log 2>&1 &`), then use a single bounded wait — one tail after the
+  expected duration, or `spur workflow trace <run> --follow --timeout 600000` for engine runs.
+  Never loop `sleep 30` turns or re-report the same wait in a fresh message.
+- **Multi-dispatch flows run as a workflow DAG.** A rehearsal driving several LLM stages
+  (curate → write → judge → revise) belongs in `spur workflow run` so the engine owns dispatch,
+  timeout, and retry — the session orchestrates, it does not babysit.
+- **Cheap tiers between phases, full gate at the boundary.** A full-repo gate costs 15–19 minutes
+  in a mid-size monorepo; interleave the light tier and reserve the full pass for the quality
+  boundary (see [`../../spur-check/SKILL.md`](../../spur-check/SKILL.md)). The task pipeline does this
+  deterministically (1322): recheck visits triage through the affected-scope light tier first —
+  a red tier fails the visit without paying the full chain, and a selection that touches a shared
+  package or an unmapped path falls back to the full suite rather than trusting the tier.
+- **Gate output persists at a known path.** The pipeline's gate step tees its output to
+  `.spur/run/<wbs>-gate.log` (1322 R1); wait once, bounded, then read the log — never sleep-poll
+  a running gate. A failing gate carries that resolved path in its step result (`data.logFile`),
+  so remediation reads evidence without re-running anything (1322 R4).
+
 ## Iron Laws
 
 Seven non-negotiable invariants for the spur-dev lifecycle. These are laws, not guidelines — a

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -155,6 +155,11 @@ background and let its exit report the terminal verdict. Use `spur workflow trac
 Synchronous invocation (`--json` without `--async`) is acceptable **only** for short pipelines
 (< 2 min, e.g. precheck-only or a dry-run). Do not use it for the full task pipeline.
 
+Gate steps are the >5-minute case (1322): the gate's output persists at
+`.spur/run/<wbs>-gate.log`, and a failing gate's step result carries that resolved path
+(`logFile`), so the wait is one `--follow` call and the evidence read is one file read — never a
+`sleep`/`trace` poll loop (0421).
+
 On the subprocess path, when `--agent <value>` is set (passed through from the thin wrapper), merge it into the vars as
 **both** `agent` and `implementAgent` (task 0483 R2):
 `--vars '{"wbs":"<wbs>","agent":"<value>","implementAgent":"<value>"}'`. The pipeline YAML reads