@gobing-ai/spur 0.3.93 → 0.3.95

package/config/workflows/wrapup-pipeline.yaml

@@ -13,13 +13,18 @@
 # pauses,
 # even under --auto (Iron Law #6: irreversible action -> surface to human).
 #
-# Shape: start -> task-resolve -> doc-sync -> learnings-append -> metrics-record
+# Shape: start -> task-resolve -> doc-sync -> learnings-validate -> learnings-append
+#          -> metrics-record
 #          -> feature-transition (conditional: if vars.feature set)
 #          -> feature-verify (post-transition feature check gate, 0915 F1)
 #          -> branch-cleanup (conditional: if vars.merge=true)
 #          -> done
 #        doc-sync routes a contract violation to `repair` (cheap, no
 #        re-dispatch — ADR-118 pilot) and an executor failure to `failed`;
+#        learnings-validate (0986) rejects a nonempty narration-only capture to
+#        the same `repair` edge with a distinct invalid-learnings-shape status —
+#        expectFile proves existence, never shape — while empty/missing captures
+#        keep the soft skip by passing through to learnings-append;
 #        task-resolve with a VALIDATED empty list short-circuits to `skipped`;
 #        invalid wrap input, an unresolved/non-completed task, a failed metrics
 #        capture, a failed required sync, or a failed feature gate routes to
@@ -75,7 +80,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: wrapup-pipeline
-version: "5"
+version: "6"
 description: "Post-execution wrap-up: doc-sync (doc drift + learning capture), metrics, feature-transition, branch-cleanup"
 iterationBound: 10
 initialState: start
@@ -108,6 +113,12 @@ states:
       Pipeline start. Task statuses are NOT mutated by wrap-up — wrap-up consumes
       completed tasks and produces learning/metrics/doc artifacts only.
     onEnter:
+      # 0960 R2: run-start script-resolution identity — record which tree this run
+      # resolved (source-repo vs installed) before any step executes. Never aborts.
+      - kind: shell
+        options:
+          command: >-
+            S=plugins/sp/scripts/script-root.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp script-root.mjs 2>/dev/null)"; RUNNER=bun; case "$S" in *.mjs) RUNNER=node ;; esac; [ -f "$S" ] && "$RUNNER" "$S" --run-id "$__runId" --spur-bin "$spurBin" || echo "script-root failed closed — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; exit 0
       - kind: note
         options:
           message: "Wrap-up pipeline start for tasks: ${vars.tasks}. Task statuses are NOT mutated."
@@ -143,12 +154,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -f plugins/sp/scripts/wrapup-steps.ts ]; then
+            if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/wrapup-steps.ts ]; then
               bun plugins/sp/scripts/wrapup-steps.ts resolve;
             elif W="$(superskill script path sp wrapup-steps.mjs 2>/dev/null)" && [ -f "$W" ]; then
               node "$W" resolve;
             else
-              echo "wrapup-steps failed closed — script not found — run 'superskill install sp'" >&2;
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-wrapup-resolve.status";
             fi
       # (0944 R1-R3) deterministic drift probe — runs ONLY when the caller left mode
@@ -163,7 +174,7 @@ states:
           command: >-
             if [ -n "$mode" ]; then
               printf '%s\n' "$mode" > ".spur/run/$__runId-mode.txt";
-            elif [ -f plugins/sp/scripts/wrapup-drift-probe.ts ]; then
+            elif [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/wrapup-drift-probe.ts ]; then
               bun plugins/sp/scripts/wrapup-drift-probe.ts;
             elif W="$(superskill script path sp wrapup-drift-probe.mjs 2>/dev/null)" && [ -f "$W" ]; then
               node "$W";
@@ -190,12 +201,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run .spur/memory &&
-            if [ -f plugins/sp/scripts/wrapup-steps.ts ]; then
+            if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/wrapup-steps.ts ]; then
               bun plugins/sp/scripts/wrapup-steps.ts route-reason;
             elif W="$(superskill script path sp wrapup-steps.mjs 2>/dev/null)" && [ -f "$W" ]; then
               node "$W" route-reason;
             else
-              echo "wrapup-steps failed closed — script not found — run 'superskill install sp'" >&2;
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-wrapup-resolve.status";
             fi
 
@@ -234,6 +245,34 @@ states:
           expectFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
 
+  - id: learnings-validate
+    description: >
+      Structural shape gate between doc-sync and the append (0986): expectFile
+      asserts the capture EXISTS and nothing about its shape, so a
+      stream-of-thought capture could be appended verbatim to the tracked
+      memory file. This state classifies a NONEMPTY capture — a date, a
+      four-digit task WBS, and at least one markdown bullet — and writes PASS
+      or invalid-learnings-shape to a run-scoped status. An empty or missing
+      capture keeps the existing soft skip (PASS) so learnings-append still
+      performs its no-op; an unclassifiable status fails loud instead of
+      appending it. Structural check only — the doc-sync prompt owns prose
+      quality; no new engine-level content contract.
+    onEnter:
+      # (warn) structural check only; the doc-sync prompt owns prose quality (0986 Design).
+      # The WBS predicate excludes digit/dash neighbours so a date's year cannot satisfy it.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            S=".spur/run/$__runId-wrapup-learnings.status" &&
+            F=".spur/run/$__runId-wrapup-learnings.md" &&
+            if [ ! -s "$F" ] || awk '/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/{d=1} /(^|[^0-9-])[0-9][0-9][0-9][0-9]([^0-9-]|$)/{w=1} /^[[:space:]]*[-*] /{b=1} END{exit !(d+w+b==3)}' "$F"; then
+              printf 'PASS\n' > "$S";
+            else
+              printf 'invalid-learnings-shape\n' > "$S";
+            fi &&
+            exit 0
+
   - id: learnings-append
     description: >
       Best-effort soft append of the captured learnings to .spur/memory/learnings.md
@@ -259,15 +298,22 @@ states:
     description: >
       Contract-violation repair (ADR-118 pilot, 0871): doc-sync's agent.run missed
       its declared post-condition after a clean exit, so wrap-up does NOT re-dispatch
-      the expensive agent on this attempt. The miss is recorded to a run-scoped
-      repair status and wrap-up proceeds to metrics-record — the run log and action
-      trace already name the violated contract and the observed value.
+      the expensive agent on this attempt. Also the destination for a nonempty
+      capture that fails learnings-validate's shape gate (0986). The miss is
+      recorded to a run-scoped repair status — text distinguishing a narration-only
+      shape failure from the missing-file contract violation — and wrap-up proceeds
+      to metrics-record; the run log and action trace already name the violated
+      contract and the observed value.
     onEnter:
       - kind: shell
         options:
           command: >-
             mkdir -p .spur/run &&
-            printf 'contract-violation: doc-sync learnings capture missed its declared contract — repair skipped re-dispatch (ADR-118 pilot)\n' > ".spur/run/$__runId-wrapup-repair.status" &&
+            R=".spur/run/$__runId-wrapup-repair.status" &&
+            V="$(cat .spur/run/$__runId-wrapup-learnings.status 2>/dev/null)" &&
+            if [ "$V" = invalid-learnings-shape ]; then printf 'invalid-learnings-shape: narration-only learnings capture — append skipped, repair recorded (0986)\n' > "$R";
+            else printf 'contract-violation: doc-sync learnings capture missed its declared contract — repair skipped re-dispatch (ADR-118 pilot)\n' > "$R";
+            fi &&
             exit 0
 
   - id: metrics-record
@@ -288,12 +334,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -f plugins/sp/scripts/wrapup-steps.ts ]; then
+            if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/wrapup-steps.ts ]; then
               bun plugins/sp/scripts/wrapup-steps.ts metrics;
             elif W="$(superskill script path sp wrapup-steps.mjs 2>/dev/null)" && [ -f "$W" ]; then
               node "$W" metrics;
             else
-              echo "wrapup-steps failed closed — script not found — run 'superskill install sp'" >&2;
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-wrapup-metrics.status";
             fi
 
@@ -322,12 +368,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -f plugins/sp/scripts/wrapup-steps.ts ]; then
+            if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/wrapup-steps.ts ]; then
               bun plugins/sp/scripts/wrapup-steps.ts feature-transition;
             elif W="$(superskill script path sp wrapup-steps.mjs 2>/dev/null)" && [ -f "$W" ]; then
               node "$W" feature-transition;
             else
-              echo "wrapup-steps failed closed — script not found — run 'superskill install sp'" >&2;
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-wrapup-sync.status";
             fi
 
@@ -460,8 +506,8 @@ transitions:
     guard:
       kind: contract-violation
   - from: doc-sync
-    to: learnings-append
-    description: Doc drift repair + learning capture succeeded — append learnings.
+    to: learnings-validate
+    description: Doc drift repair + learning capture succeeded — validate the capture's shape before appending.
     guard:
       kind: action-ok
   - from: doc-sync
@@ -475,6 +521,35 @@ transitions:
     guard:
       kind: always
 
+  # ── learnings-validate: shape gate (0986) — invalid-shape to repair, PASS to append ──
+  # Declaration order matters: the discriminating invalid-shape edge is tried
+  # first, then PASS; an unreadable status fails loud rather than appending an
+  # unclassified capture.
+  - from: learnings-validate
+    to: repair
+    description: >
+      Nonempty capture failed the structural shape gate (no date/WBS/bullet) —
+      route to the cheap repair edge and never append narration (0986 R2).
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-wrapup-learnings.status 2>/dev/null)" = invalid-learnings-shape'
+  - from: learnings-validate
+    to: learnings-append
+    description: Capture is shape-valid (or empty/missing, keeping the soft skip) — append.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-wrapup-learnings.status 2>/dev/null)" = PASS'
+  - from: learnings-validate
+    to: failed
+    terminalReason: failed-check
+    description: >
+      Validation status missing or unreadable — fail loud instead of appending
+      a capture whose shape was never classified.
+    guard:
+      kind: always
+
   # ── linear body: learnings-append -> metrics-record ──
   - from: learnings-append
     to: metrics-record

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.93",
+    "version": "0.3.95",
     "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",
@@ -24,12 +24,16 @@
         "spur": "spur.js"
     },
     "exports": {
-        "./schemas/*": "./schemas/*"
+        "./schemas/*": "./schemas/*",
+        "./board": {
+            "types": "./board/index.d.ts"
+        }
     },
     "files": [
         "spur.js",
         "config",
         "schemas",
+        "board",
         "web",
         "README.md",
         "plugins/",
@@ -45,7 +49,7 @@
         "dev": "bun run src/index.ts",
         "build": "bun run ../../scripts/spur-dev.ts build-cli",
         "build:binaries": "bun run ../../scripts/spur-dev.ts build-binaries",
-        "build:bundle": "bun run ../../scripts/spur-dev.ts bundle-web && bun build src/index.ts --target=bun --outfile spur.js && bun run ../../scripts/spur-dev.ts bundle-config config && bun run ../../scripts/spur-dev.ts bundle-plugins",
+        "build:bundle": "bun run ../../scripts/spur-dev.ts bundle-web && bun run ../../scripts/spur-dev.ts emit-board-types && bun build src/index.ts --target=bun --outfile spur.js && bun run ../../scripts/spur-dev.ts bundle-config config && bun run ../../scripts/spur-dev.ts bundle-plugins",
         "test": "bun test tests --coverage --coverage-dir=../../.coverage --pass-with-no-tests",
         "typecheck": "tsc --noEmit",
         "prepack": "bun run build:bundle",
@@ -53,14 +57,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.5.7",
-        "@gobing-ai/ts-ai-runner": "^0.5.7",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.7",
-        "@gobing-ai/ts-infra": "^0.5.7",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.7",
-        "@gobing-ai/ts-rule-engine": "^0.5.7",
-        "@gobing-ai/ts-runtime": "^0.5.7",
-        "@gobing-ai/ts-utils": "^0.5.7",
+        "@gobing-ai/ts-db": "^0.5.11",
+        "@gobing-ai/ts-ai-runner": "^0.5.11",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.5.11",
+        "@gobing-ai/ts-infra": "^0.5.11",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.11",
+        "@gobing-ai/ts-rule-engine": "^0.5.11",
+        "@gobing-ai/ts-runtime": "^0.5.11",
+        "@gobing-ai/ts-utils": "^0.5.11",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -102,7 +102,7 @@ list this README is checked against.
 | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dev-next`          | Status-aware router — inspect a task (or next frontier under a feature), dispatch the best existing `/sp:dev-*` command, chain on clean success |
 | `dev-run`           | Run a task — full pipeline (precheck→implement→test→review→approve→verify→record→done) or single-step (implement)                               |
-| `dev-review`        | Multi-dimensional review for a task or path — functional requirements traceability, SECUA framework, and architectural depth                    |
+| `dev-review`        | Multi-dimensional review for a task or path (traceability, SECUA, architecture); `--triage` fixes small findings, files the rest as tasks       |
 | `dev-pr-review`     | GitHub Codex PR review — prepare/reuse a PR, request `@codex review`, collect findings, validate/fix/re-review (fix mode); workflow-backed spine |
 | `dev-verify`        | Verify a task against its requirements and Acceptance Criteria — traceability check producing a PASS/PARTIAL/FAIL verdict with evidence         |
 | `dev-unit`          | Generate or extend tests until the unit target is met                                                                                           |

package/plugins/sp/commands/dev-review-session.md

@@ -1,5 +1,5 @@
 ---
-description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. With --triage: apply pure-doc / one-to-two-line fixes inline, then file remaining findings as one new task. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved, triage findings"
+description: "Review the active coding-agent session immediately: summarize outcomes, distinguish resolved and open issues with evidence, and propose bounded improvements. With --triage: apply pure-doc / one-to-two-line fixes inline, then file remaining findings as one or more implement-ready tasks. Triggers: review this session, session wrap-up, immediate retrospective, what happened, what was resolved, triage findings"
 role: reviewer
 argument-hint: "[<focus>] [--triage]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
@@ -11,8 +11,8 @@ Wraps the **sp:session-review** skill for a lightweight review of the active hos
 default it is report-only: current conversation plus read-only repository evidence, run inline so
 the session context is preserved — no workflow launch, history import, task creation, or
 remediation. With `--triage`, it first triages the findings, then applies direct fixes (pure
-documentation work and one-to-two-line fixes) inline and files everything remaining as exactly one
-new task for further fixing. The result includes a non-overlapping time breakdown with durations in
+documentation work and one-to-two-line fixes) inline and files everything remaining as one or more
+implement-ready tasks for further fixing. The result includes a non-overlapping time breakdown with durations in
 `M:SS` or `H:MM:SS` form and `n/a` for unavailable measurements.
 
 ## Argument Flags
@@ -20,7 +20,7 @@ new task for further fixing. The result includes a non-overlapping time breakdow
 | Flag | Description | Default |
 | --- | --- | --- |
 | `[<focus>]` | Optional question or operation to emphasize without excluding material session outcomes. | full active session |
-| `--triage` | After the report: bucket findings → apply pure-doc / 1–2-line fixes inline → create one task for the remainder. | off (report-only) |
+| `--triage` | After the report: bucket findings → apply pure-doc / 1–2-line fixes inline → file the remainder as one or more implement-ready tasks. | off (report-only) |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

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

@@ -1,7 +1,7 @@
 ---
-description: "Review code for a task or path — multi-dimensional review across functional traceability, SECUA quality, and architectural depth. Triggers: \"review this\", \"check the code\", \"SECUA review\", \"dev review\", \"audit this\"."
+description: "Review code for a task or path — multi-dimensional review across functional traceability, SECUA quality, and architectural depth. With --triage: fix small findings directly, then file the rest as implement-ready tasks. Triggers: \"review this\", \"check the code\", \"SECUA review\", \"dev review\", \"audit this\", \"triage review findings\"."
 role: reviewer
-argument-hint: "[<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--fix (deprecated)]"
+argument-hint: "[<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -16,17 +16,28 @@ Wraps the **sp:functional-review**, **sp:code-verification**, and **sp:code-impr
 | `[<wbs\|path>]` | Task WBS or source path to review. | cwd |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing review. | omit |
 | `--focus` `<dims>` | Review dimensions (functional / SECUA / architecture). | all |
-| `--fix` | Deprecated no-op + warning; route remediation to /sp:dev-verify --fix. | off |
+| `--triage` | After the review: fix small findings directly, file the rest as one or more implement-ready tasks. | off (report-only) |
+| `--worktree` `[<name>]` | Run the triage in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. Requires `--triage`. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-review [<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--fix (deprecated)]
+```
+/sp:dev-review [<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]]
+/sp:dev-review scripts --triage
+/sp:dev-review 0962 --triage --worktree
+```
+
+Put the target first: a bare token after `--worktree` is read as the worktree name.
 
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - WBS mode (`<wbs>`): `Skill(skill="sp:functional-review", args="<wbs> $ARGUMENTS")` + `Skill(skill="sp:code-verification", args="review $ARGUMENTS")` + `Skill(skill="sp:code-improvement", args="<wbs> $ARGUMENTS")` (functional traceability + SECUA framework + architectural depth; the three skills return review fragments and the coordinator (`sp:super-reviewer`) writes the combined `## Review` — F92 0593 R1)
 - Path mode (`<path>`): `Skill(skill="sp:code-verification", args="review $ARGUMENTS")` + `Skill(skill="sp:code-improvement", args="<path> $ARGUMENTS")` (advisory SECUA quality + architectural depth; performs no task mutation)
-- `--fix`: Deprecated (no-op + warning message; route remediation to `/sp:dev-verify --fix`). **`--next` removed** (feature H8, 2026-07-31) — it was a deprecated no-op; route progression to `/sp:dev-next`. **was: `--next` deprecated no-op.**
+- `--triage`: after the review returns, run the triage protocol in [dev-operations.md § 2. review](../skills/spur-dev/references/dev-operations.md#2-review) **inline in this session** — the review skills and `sp:super-reviewer` stay report-only.
+- Without `--worktree`, every write lands in the current working tree on the current branch: no branch creation, no checkout, no commit.
+- `--worktree [<name>]`: the [execution-batch.md § Worktree isolation](../skills/spur-dev/references/execution-batch.md#worktree-isolation---worktree-name) lifecycle as a run of one (marker `command` = `dev-review`, `selector` = the target). Rejected without `--triage`.
+  While it runs, fixes and filed tasks land in the worktree copy; the main tree shows them only after the FF-merge.
+- `--fix`: Deprecated (still accepted: no-op + warning; route remediation to `--triage` or `/sp:dev-verify --fix`). **`--next` removed** (feature H8, 2026-07-31) — it was a deprecated no-op; route progression to `/sp:dev-next`. **was: `--next` deprecated no-op.**

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

@@ -40,10 +40,13 @@ See `sp:code-verification` § Shippable readiness gate.
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - `Skill(skill="sp:code-verification", args="verify $ARGUMENTS")`
-- **Residual sweep (F96 R1):** after the verify answer is written and `task verdict` derives
-  `.spur/run/<wbs>-verdict.json`, run `residual-scan scan` + `fold` (observe-only; folds the
-  verdict's `residual-sweep` check, PASS → PARTIAL when a blocking residual exists) — under every
-  `--fix` mode — before `spur task record`. Resolve the script via `superskill script path sp
+- **Residual sweep (F96 R1, post-record since 0987):** after `task verdict` derives
+  `.spur/run/<wbs>-verdict.json` and `spur task record` has flipped the verdict-proven R/AC boxes,
+  run `residual-scan scan` + `fold` (observe-only; folds the verdict's `residual-sweep` check,
+  PASS → PARTIAL when a blocking residual exists) — under every `--fix` mode — then, only on a
+  downgrade, re-run `spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json` so Testing
+  carries the final verdict. Same order as the pipeline `record` state (0983): scanning before
+  record reads unticked-but-proven boxes and folds a clean PASS to PARTIAL. Resolve the script via `superskill script path sp
   residual-scan.mjs`; never reference `plugins/sp/scripts/` in shipped surfaces
   (script-contract-check rule 4). When the task reaches `done` through `--next`, run
   `residual-scan settle` (best-effort). On a folded PARTIAL: the bounded remediation loop has

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

@@ -72,8 +72,9 @@ Without `--fix all`, shippable is not evaluated (optional note: use `--fix all`
 - Batch orchestration: `Skill(skill="sp:spur-dev", args="verifyall $ARGUMENTS")`
 - Per-task verification (inner): `Skill(skill="sp:code-verification", args="verify <wbs> $SHARED_FLAGS")`
 - Shippable gate: once after the batch (same skill § Shippable readiness gate)
-- **Residual sweep (F96 R1, per task):** same contract as `/sp:dev-verify` — after each task's
-  verdict artifact is derived, run `residual-scan scan` + `fold` (under every `--fix` mode) before
-  `spur task record`; on reaching `done` via `--next`, run `settle`. Script resolution:
+- **Residual sweep (F96 R1, per task, post-record since 0987):** same contract as
+  `/sp:dev-verify` — after each task's verdict artifact is derived and `spur task record` has
+  flipped its verdict-proven boxes, run `residual-scan scan` + `fold` (under every `--fix` mode),
+  and re-record only on a downgrade; on reaching `done` via `--next`, run `settle`. Script resolution:
   `superskill script path sp residual-scan.mjs` (never `plugins/sp/scripts/` —
   script-contract-check rule 4).

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

@@ -17,7 +17,7 @@ Wraps the **wrapup-pipeline.yaml** workflow.
 | `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed (headless): `omit` and `--agent inline` resolve identically per task 0687 — tier substitution under objective trigger 3 (durable auditable run record required) with a warning naming the substituted executor; `auto` tier-resolves an executor; a name pins that executor into `vars.agent`. | inline |
 | `--auto` | Skip objective HITL gates. | off |
 | `--merge` | Merge the wrap branch. | off |
-| `--dry-run` | Render the wrap without writing. | off |
+| `--dry-run` | Validate and walk transitions without executing actions. Conditional states therefore resolve to their declared failure edges (their guard files are never written), so a render ending in `failed` is **not** a run failure — it reports "this state's route cannot be decided without running it". Use a real run to preview a route. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

package/plugins/sp/hooks/context-post-tool.ts

@@ -34,7 +34,7 @@ export const REDACTION_CAP_BYTES = 4096;
 /** Max command/pattern summary length before ellipsis (chars). */
 export const SUMMARY_MAX_CHARS = 200;
 
-interface ToolPayload {
+export interface ToolPayload {
     session_id?: string;
     tool_name?: string;
     tool_input?: {
@@ -115,7 +115,7 @@ export function redactText(text: string, capBytes: number = REDACTION_CAP_BYTES)
     if (bytes.length <= capBytes) return s;
     // Truncate on byte boundary then append marker
     let end = capBytes;
-    while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+    while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
     return `${new TextDecoder().decode(bytes.subarray(0, end))}…[truncated]`;
 }
 

package/plugins/sp/hooks/context-session-start.ts

@@ -126,6 +126,7 @@ export function recordSessionStart(
     dir: string,
     env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
+    agentFallback?: string,
 ): string | null {
     try {
         mkdirSync(dir, { recursive: true });
@@ -140,7 +141,7 @@ export function recordSessionStart(
     const pad = (n: number) => String(n).padStart(2, '0');
     const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}`;
     const ts = at.toISOString();
-    const agent = resolveAgentHint(env);
+    const agent = resolveAgentHint(env, agentFallback);
     const model = resolveModelHint(env);
 
     const sessionBody: Record<string, unknown> = {

package/plugins/sp/hooks/context-session-stop.ts

@@ -49,30 +49,30 @@ function computeSessionTotals(
     return { reads, writes, tokens };
 }
 
-function exitOk(): never {
-    process.exit(0);
-}
-
-async function main(): Promise<void> {
-    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
-
+/**
+ * Finalize one session (task 0969 R3): read the `.session.json` pointer, compute the session's
+ * rollup totals, append the `session_end` row, remove the pointer (best-effort) and return the
+ * event. Shared by this hook's entrypoint and Pi's `session_shutdown` so both hosts roll up
+ * identically. Returns null on every fail-open path.
+ */
+export function recordSessionEnd(dir: string, now: () => Date = () => new Date()): Record<string, unknown> | null {
     const sessionFile = join(dir, '.session.json');
-    if (!existsSync(sessionFile)) exitOk();
+    if (!existsSync(sessionFile)) return null;
 
     let sessionId = '';
     try {
         const session = JSON.parse(readFileSync(sessionFile, 'utf-8')) as { session?: string };
         sessionId = session.session ?? '';
     } catch {
-        exitOk();
+        return null;
     }
 
-    if (!sessionId) exitOk();
+    if (!sessionId) return null;
 
     const totals = computeSessionTotals(join(dir, 'token-ledger.jsonl'), sessionId);
 
     const event = {
-        ts: new Date().toISOString(),
+        ts: now().toISOString(),
         session: sessionId,
         type: 'session_end' as const,
         totals,
@@ -81,7 +81,7 @@ async function main(): Promise<void> {
     try {
         appendFileSync(join(dir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
     } catch {
-        exitOk();
+        return null;
     }
 
     try {
@@ -90,7 +90,15 @@ async function main(): Promise<void> {
         // cleanup is best-effort
     }
 
-    exitOk();
+    return event;
 }
 
-void main().catch(exitOk);
+// Entrypoint: run the shared core, then exit 0 (fail-open) as this hook always has.
+if (import.meta.main) {
+    try {
+        recordSessionEnd(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
+    } catch {
+        /* fail-open: every error path exits 0 */
+    }
+    process.exit(0);
+}