@gobing-ai/spur 0.3.94 → 0.3.95

package/.claude-plugin/marketplace.json

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

package/README.md

@@ -59,6 +59,21 @@ If `~/.local/bin` isn't already on your `PATH`, add it (e.g. `export PATH="$HOME
 in your shell profile). Supported targets: `darwin-arm64`, `darwin-x64`, `linux-arm64`, `linux-x64`.
 Windows: use the Bun path under WSL.
 
+**Verification.** The installer downloads to a temp file, checks it against the release's
+`SHA256SUMS`, and only then atomically replaces `spur`. A failed download, a checksum mismatch, or a
+missing `SHA256SUMS` leaves an existing install untouched and exits non-zero. `SPUR_RELEASE_URL`
+overrides the download base URL (a mirror, or a `file://` directory in tests).
+
+The checksum is a **code-execution** boundary, not just an integrity check: having verified the
+download, the installer *runs* it (`spur init`), so a release whose `SHA256SUMS` cannot be verified
+is a release you cannot safely install. `SPUR_SKIP_VERIFY=1` is the single explicit bypass and
+prints a warning — keep it for local or air-gapped installs, and pipe the script into `sh` only from
+a source you trust.
+
+**Releasing standalone binaries.** Run `bun run build:binaries` in `apps/cli`, then upload **all**
+of `dist/cli/spur-*` **and** `dist/cli/SHA256SUMS` to the GitHub Release for the tag. A release
+without `SHA256SUMS` makes the installer fail by default.
+
 ### Package layout (what ships)
 
 The published tarball is a self-contained Bun bundle plus static assets:
@@ -98,6 +113,33 @@ spur status
 
 Every command supports `--json` for machine-readable output.
 
+### Extending the Spur Board
+
+A project can add its own Board modules — a compiled React tool or an embedded URL app — without
+editing this package. An installed Board reads them from a fresh project's `.spur/config.yaml`:
+
+```yaml
+bootstrap:
+  modules:
+    - id: team-board
+      name: Team board
+      icon: "🧭"
+      type: react
+      directory: board/team-board/dist
+      entry: index.js
+      styles: [index.css]
+    - id: docs
+      name: Documentation
+      icon: "📚"
+      type: iframe
+      url: https://docs.example.test/
+```
+
+`spur init` seeds `modules: []` (built-ins only); change selection with a config edit, then restart
+`spur serve` and reload. The full authoring contract — the declaration union, the
+`@gobing-ai/spur/board` type export, the Vite library setup and the frame/trust limits — is in the
+[downstream Board modules design](https://github.com/gobing-ai/spur/blob/main/docs/design/downstream-board-modules.md).
+
 ## Documentation
 
 Full docs, architecture, and the complete command surface live in the

package/board/index.d.ts

@@ -0,0 +1,38 @@
+// Generated by scripts/commands/emit-board-types.ts from
+// apps/web/src/modules/contribution.ts — edit the authoring source, then regenerate.
+import type { ComponentType } from 'react';
+/**
+ * Public authoring contract for a native (compiled React) Board module contribution
+ * (A8 / task 0988 R1).
+ *
+ * This file is the ONE authoring source for the declaration-only `@gobing-ai/spur/board`
+ * package export: `scripts/commands/emit-board-types.ts` emits `apps/cli/board/index.d.ts`
+ * from it, so the published ABI cannot drift from the Board's own types. Keep it
+ * type-only — no React *value* import may reach the CLI or plugin artifacts (the CLI
+ * ships no React; the contributor supplies compatible React types through its own
+ * devDependencies).
+ *
+ * Module metadata (id/name/icon/route) is deliberately absent: it is project
+ * configuration (one selection authority), while this shape carries only what the
+ * renderer needs to mount a contribution.
+ */
+export interface BoardModuleContribution {
+    /** Contribution protocol version this Board accepts. */
+    readonly apiVersion: 1;
+    /**
+     * Workspace component. Rendered inside the Board's React tree with the Board's own
+     * React instance — it must not call `createRoot`, and no private Board context is
+     * exported to it.
+     */
+    readonly component: ComponentType;
+    /** Optional companion the Board's right panel renders while this module is active. */
+    readonly rightPanelComponent?: ComponentType;
+}
+/**
+ * The named export a native Board module entry must publish.
+ *
+ * Declared rather than implemented: `@gobing-ai/spur/board` is a declaration-only export,
+ * not a runtime SDK (consumers import its types; their compiled ESM entry exports this
+ * name for the renderer).
+ */
+export declare const webModule: BoardModuleContribution;

package/config/plugin-scripts.json

@@ -93,6 +93,11 @@
             "rel": "script-contract-check.ts",
             "contract": "repo-only"
         },
+        {
+            "rel": "script-root.ts",
+            "contract": "standard",
+            "twin": "script-root.mjs"
+        },
         {
             "rel": "stage-registry-adapter.ts",
             "contract": "repo-only"

package/config/workflows/feature-verification.yaml

@@ -50,13 +50,16 @@ states:
       digest, run identity) and the coarse status file, always exit 0 so the
       transition guard routes missing/corrupt/FAIL to `failed`.
     onEnter:
+      # 0960 R2: run-start script-resolution identity — record which tree this run
+      # resolved (source-repo vs installed) before the verification step runs. Never aborts.
       - kind: shell
         options:
           command: >-
-            bun plugins/sp/scripts/feature-verification-steps.ts verify
-            --feature-id "$featureId"
-            --run-id "$__runId"
-            --spur-bin "$spurBin"
+            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: shell
+        options:
+          command: >-
+            mkdir -p .spur/run; S=plugins/sp/scripts/feature-verification-steps.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp feature-verification-steps.mjs 2>/dev/null)"; RUNNER=bun; case "$S" in *.mjs) RUNNER=node ;; esac; [ -f "$S" ] && "$RUNNER" "$S" verify --feature-id "$featureId" --run-id "$__runId" --spur-bin "$spurBin" || printf 'FAIL feature-verification failed closed — script not found — run superskill install sp --marketplace gobing-ai/spur\n' > ".spur/run/$__runId-feature-verification.status"; exit 0
 
   - id: done
     description: Terminal — repo-wide checks passed and the receipt is bound.

package/config/workflows/idea-pipeline.yaml

@@ -84,6 +84,12 @@ states:
       handoff — no task execution. Soft agent doctor (status file) so doctor red
       routes to `failed` via transitions instead of a raw lifecycle abort.
     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: "Idea pipeline start for idea: ${vars.idea}"
@@ -254,12 +260,12 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            S=plugins/sp/scripts/idea-coverage-check.ts &&
-            if [ ! -f "$S" ]; then S="$(superskill script path sp idea-coverage-check.ts 2>/dev/null)"; fi &&
+            S=plugins/sp/scripts/idea-coverage-check.ts;
+            [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp idea-coverage-check.ts 2>/dev/null)";
             if [ -n "$S" ] && [ -f "$S" ]; then
               bun "$S" --run-id "$__runId" --report ".spur/run/$__runId-idea-eval-report.md" --ac ".spur/run/$__runId-idea-ac-content.md" || printf 'FAIL run=%s checker exited nonzero (bun missing or checker crash)\n' "$__runId" > ".spur/run/$__runId-idea-coverage.reason";
             else
-              printf 'FAIL run=%s checker not found — run superskill install sp\n' "$__runId" | tee ".spur/run/$__runId-idea-coverage.reason" >&2;
+              printf 'FAIL run=%s checker not found — run superskill install sp --marketplace gobing-ai/spur\n' "$__runId" | tee ".spur/run/$__runId-idea-coverage.reason" >&2;
               printf 'FAIL\n' > ".spur/run/$__runId-idea-coverage.status";
             fi
       # 0945 R2: derive the route facts ONCE at this boundary (0769 pattern) — guards read these
@@ -558,7 +564,7 @@ states:
             elif H="$(superskill script path sp idea-handoff.mjs 2>/dev/null)" && [ -f "$H" ]; then
               node "$H";
             else
-              echo "idea handoff failed closed — idea-handoff script not found — run 'superskill install sp'" >&2;
+              echo "idea handoff failed closed — idea-handoff script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
               exit 1;
             fi
   - id: handoff

package/config/workflows/task-pipeline.yaml

@@ -13,9 +13,10 @@
 #        `test` is the project quality gate (shell + bounded /sp:dev-fixall), not
 #        /sp:dev-unit (coverage gap-fill; router C3/C5).
 #
-# F96 residual sweep (0950): precheck captures the resume-safe base commit; verify
-# scans and folds residuals between the verdict and the proof bind (blocking leftovers
-# downgrade PASS → PARTIAL and take the existing remediation edge); done settles
+# F96 residual sweep (0950, reordered 0983): precheck captures the resume-safe base
+# commit; record scans and folds residuals AFTER `task record` flips the verdict-proven
+# boxes (a post-record blocking leftover downgrades PASS → PARTIAL, fails the record →
+# done guard closed, and re-records Testing before the failed edge); done settles
 # deferrals; failed renders the recovery report. No new state, edge, or model query.
 #
 # Vars (passed as a JSON object via `--vars`):
@@ -187,6 +188,12 @@ states:
           Fast deterministic task readiness and size checks. Failures route to the
           `failed` terminal state (not a raw lifecycle abort mid-enter).
       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
           # (e) git-status hygiene advisory; never fails the run (0487 R6 / 0511 R1).
           - kind: shell
             options:
@@ -207,12 +214,12 @@ states:
           - kind: shell
             options:
                 command: >-
-                    mkdir -p .spur/run; S=plugins/sp/scripts/task-size-precheck.ts; [ -f "$S" ] || S="$(superskill script path sp task-size-precheck.ts 2>/dev/null)"; if [ -f "$S" ]; then bun "$S" "$wbs" --spur-bin "$spurBin" --max-reqs "$maxImplementReqs" --max-plan-items "$maxImplementPlanItems"; else echo "task-size-precheck failed closed — checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'." >&2; echo "FAIL" > ".spur/run/$wbs-precheck-size.status"; fi; exit 0
+                    mkdir -p .spur/run; S=plugins/sp/scripts/task-size-precheck.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp task-size-precheck.ts 2>/dev/null)"; if [ -f "$S" ]; then bun "$S" "$wbs" --spur-bin "$spurBin" --max-reqs "$maxImplementReqs" --max-plan-items "$maxImplementPlanItems"; else echo "task-size-precheck failed closed — checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp --marketplace gobing-ai/spur'." >&2; echo "FAIL" > ".spur/run/$wbs-precheck-size.status"; fi; exit 0
           # (d) task-evidence-precheck.ts owns the check; shell only resolves it and fails closed (0726 R2).
           - kind: shell
             options:
                 command: >-
-                    mkdir -p .spur/run; S=plugins/sp/scripts/task-evidence-precheck.ts; [ -f "$S" ] || S="$(superskill script path sp task-evidence-precheck.ts 2>/dev/null)"; if [ -f "$S" ]; then bun "$S" "$wbs" --spur-bin "$spurBin"; else echo "task-evidence-precheck failed closed — checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'." >&2; echo "FAIL" > ".spur/run/$wbs-precheck-evidence.status"; fi; exit 0
+                    mkdir -p .spur/run; S=plugins/sp/scripts/task-evidence-precheck.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp task-evidence-precheck.ts 2>/dev/null)"; if [ -f "$S" ]; then bun "$S" "$wbs" --spur-bin "$spurBin"; else echo "task-evidence-precheck failed closed — checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp --marketplace gobing-ai/spur'." >&2; echo "FAIL" > ".spur/run/$wbs-precheck-evidence.status"; fi; exit 0
           # (e) F96 R1 (0950): capture the run's base commit once — a resumed or re-entered run
           # keeps its original base so residual scans stay anchored to the same diff.
           - kind: shell
@@ -432,7 +439,7 @@ states:
           - kind: shell
             options:
                 command: >-
-                    mkdir -p .spur/run; if [ -f plugins/sp/scripts/quality-gate.ts ]; then bun plugins/sp/scripts/quality-gate.ts run; elif Q="$(superskill script path sp quality-gate.mjs 2>/dev/null)" && [ -f "$Q" ]; then node "$Q" run; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
+                    mkdir -p .spur/run; if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/quality-gate.ts ]; then bun plugins/sp/scripts/quality-gate.ts run; elif Q="$(superskill script path sp quality-gate.mjs 2>/dev/null)" && [ -f "$Q" ]; then node "$Q" run; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
 
     - id: test-fix
       description: >
@@ -515,7 +522,7 @@ states:
           - kind: shell
             options:
                 command: >-
-                    mkdir -p .spur/run; if [ -f plugins/sp/scripts/quality-gate.ts ]; then bun plugins/sp/scripts/quality-gate.ts recheck; elif Q="$(superskill script path sp quality-gate.mjs 2>/dev/null)" && [ -f "$Q" ]; then node "$Q" recheck; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
+                    mkdir -p .spur/run; if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/quality-gate.ts ]; then bun plugins/sp/scripts/quality-gate.ts recheck; elif Q="$(superskill script path sp quality-gate.mjs 2>/dev/null)" && [ -f "$Q" ]; then node "$Q" recheck; else echo "quality gate failed closed — quality-gate script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf 'FAIL\n' > ".spur/run/$wbs-test-gate.status"; fi; exit 0
 
     - id: triage
       description: >-
@@ -535,7 +542,7 @@ states:
           - kind: shell
             options:
                 command: >-
-                    mkdir -p .spur/run; if [ -f plugins/sp/scripts/task-diffstat.ts ]; then bun plugins/sp/scripts/task-diffstat.ts --spur-bin "$spurBin"; elif D="$(superskill script path sp task-diffstat.mjs 2>/dev/null)" && [ -f "$D" ]; then node "$D"; else echo "task-diffstat failed closed — task-diffstat script not found — run 'superskill install sp'" >&2; printf '{"files":0,"insertions":0,"deletions":0,"paths":[],"sensitive":true}\n' > ".spur/run/$wbs-diffstat.json"; fi; exit 0
+                    mkdir -p .spur/run; if [ -f config/plugin-scripts.json -a -f plugins/sp/scripts/task-diffstat.ts ]; then bun plugins/sp/scripts/task-diffstat.ts --spur-bin "$spurBin"; elif D="$(superskill script path sp task-diffstat.mjs 2>/dev/null)" && [ -f "$D" ]; then node "$D"; else echo "task-diffstat failed closed — task-diffstat script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; printf '{"files":0,"insertions":0,"deletions":0,"paths":[],"sensitive":true}\n' > ".spur/run/$wbs-diffstat.json"; fi; exit 0
           # (b)+(c) lane pre-guard BEFORE decide: a caller-set mode is projected verbatim (R2b);
           # a sensitive path or >400 changed lines pins safety (R2c) and the decide result below
           # is never consulted. A missing/malformed diffstat row (producer crashed or never ran,
@@ -706,10 +713,10 @@ states:
             options:
                 command: >-
                     LINT_SCRIPT="plugins/sp/scripts/verify-answer-lint.ts";
-                    [ -f "$LINT_SCRIPT" ] ||
+                    [ -f config/plugin-scripts.json -a -f "$LINT_SCRIPT" ] ||
                     LINT_SCRIPT="$(superskill script path sp verify-answer-lint.ts 2>/dev/null)";
                     if [ -z "$LINT_SCRIPT" ] || [ ! -f "$LINT_SCRIPT" ]; then
-                      echo "verify-answer-lint: checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'" >&2;
+                      echo "verify-answer-lint: checker not found in plugins/sp/scripts/ nor staged — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
                       exit 1;
                     fi;
                     bun "$LINT_SCRIPT" "$wbs"
@@ -718,16 +725,6 @@ states:
           - kind: shell
             options:
                 command: "$spurBin task verdict $wbs --from-answer .spur/run/$wbs-verify-answer.txt"
-          # (d) F96 R2 (0950): residual-scan.ts owns the sweep; shell only resolves it.
-          # ONE hard action (scan+fold): a scanner crash fails verify closed — the
-          # verify→failed catch-all routes a missing/malformed verdict. Runs AFTER
-          # `task verdict` and BEFORE the jq bind so a blocking residual turns PASS
-          # into PARTIAL (fold rewrites the verdict artifact) and takes the existing
-          # verify→test-fix edge while attempts remain.
-          - kind: shell
-            options:
-                command: >-
-                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ ! -f "$S" ]; then echo "residual-scan failed closed — scanner not found in plugins/sp/scripts/ nor staged — run 'superskill install sp'" >&2; exit 1; fi; case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" scan "$wbs" --spur-bin "$spurBin" && "$RUNNER" "$S" fold "$wbs" --spur-bin "$spurBin"
           # (e) one jq mutation binds the verdict to the proof digest (0703 R3; runId 0730 §B.2 /
           # 0757 R4; definitionDigest 0759 R5; honest review stamp 0785 R4; soft action + hard guard).
           - kind: shell
@@ -745,7 +742,11 @@ states:
           evidence (0785 R4) — before any task record or status mutation. Post-record step
           conditionally syncs feature status via the bounded `feature-sync-bounded` wrapper
           (task 0411 retry-suppression) if `feature_id` is present, or appends an orphan
-          link proposal to the run report if absent (task 0328 / ADR-0322).
+          link proposal to the run report if absent (task 0328 / ADR-0322). The post-record
+          residual sweep (0983) re-scans the task file after the verdict-proven box flips and
+          folds blocking leftovers into the verdict before `record → done`; a downgrade
+          re-records Testing from the final artifact so a failed task never keeps a stale
+          PASS narrative.
       onEnter:
           # 0785 R3: BOUND verify-verdict registration — FIRST action, before any task record or
           # status mutation, replacing the redundant proof.fingerprint compare (the action itself
@@ -771,7 +772,11 @@ states:
             options:
                 id: task-record-transition
                 executable: "${vars.spurBin}"
-                args: ["task", "record", "${vars.wbs}", "--solution-from-diff", "--transition", "testing"]
+                # 0980: --no-lifecycle mirrors the wip/done hops — the pipeline run is
+                # already the lifecycle record, so a record-stage transition must not
+                # spawn a nested task-lifecycle run that outlives the pipeline as a
+                # `running` orphan. The target-aware check gate still runs (inline).
+                args: ["task", "record", "${vars.wbs}", "--solution-from-diff", "--transition", "testing", "--no-lifecycle"]
                 retry:
                     maxAttempts: 2
                     delayMs: 2000
@@ -791,7 +796,30 @@ states:
           - kind: shell
             options:
                 command: >-
-                    S=plugins/sp/scripts/record-feature-sync.ts; [ -f "$S" ] || S="$(superskill script path sp record-feature-sync.mjs 2>/dev/null)"; [ "$deferFeatureSync" = "true" ] && echo "feature sync deferred to batch integration" >> ".spur/run/$wbs-report.txt" || if [ -f "$S" ]; then bun "$S" --spur-bin "$spurBin"; else echo "feature sync skipped — record-feature-sync not found in plugins/sp/scripts/ nor staged" >> ".spur/run/$wbs-report.txt"; fi; exit 0
+                    S=plugins/sp/scripts/record-feature-sync.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp record-feature-sync.mjs 2>/dev/null)"; [ "$deferFeatureSync" = "true" ] && echo "feature sync deferred to batch integration" >> ".spur/run/$wbs-report.txt" || if [ -f "$S" ]; then bun "$S" --spur-bin "$spurBin"; else echo "feature sync skipped — record-feature-sync not found in plugins/sp/scripts/ nor staged" >> ".spur/run/$wbs-report.txt"; fi; exit 0
+          # (d) F96 (0983): residual-scan.ts owns the sweep; shell only resolves it. The
+          # scan moved here from verify: it must read the task file AFTER `task record`
+          # flipped the verdict-proven Requirement/AC boxes (0692), or a proven-but-unticked
+          # box folds every good run to PARTIAL and the done guard is unreachable (0967).
+          # Classification unchanged: any box still unchecked post-record (unproven R/AC,
+          # unfinished Plan) stays blocking and fails the record → done guard closed.
+          # ONE hard action (scan+fold): a scanner crash fails record closed.
+          - kind: shell
+            options:
+                command: >-
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ ! -f "$S" ]; then echo "residual-scan failed closed — scanner not found in plugins/sp/scripts/ nor staged — run 'superskill install sp --marketplace gobing-ai/spur'" >&2; exit 1; fi; case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" scan "$wbs" --spur-bin "$spurBin" && "$RUNNER" "$S" fold "$wbs" --spur-bin "$spurBin"
+          # (e) F96 R5 (0983): a sweep downgrade must reach the task record — re-record from
+          # the FINAL (post-fold) artifact so Testing carries the downgraded verdict; a failed
+          # task must not retain a stale PASS Testing narrative. Soft (exit 0): the downgrade
+          # itself already fails the record → done guard; a re-record failure prints its
+          # re-run command and the failed state renders the recovery report.
+          # 0980: --no-lifecycle for the same orphan reason as the main record command —
+          # inert today (the task is already at testing, so this is a same-status no-op),
+          # but it keeps the no-nested-lifecycle invariant if the flow shifts.
+          - kind: shell
+            options:
+                command: >-
+                    verdict="$(jq -r .verdict .spur/run/$wbs-verdict.json 2>/dev/null)"; if [ -n "$verdict" ] && [ "$verdict" != PASS ]; then $spurBin task record $wbs --solution-from-diff --transition testing --no-lifecycle || echo "post-downgrade re-record failed — re-run: $spurBin task record $wbs" >&2; fi; exit 0
 
     - id: done
       description: >
@@ -805,7 +833,7 @@ states:
           - kind: shell
             options:
                 command: >-
-                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" settle "$wbs" --spur-bin "$spurBin" || echo "residual-settle failed — re-run: residual-scan settle $wbs" >&2; else echo "residual-scan not staged — settle skipped — re-run: residual-scan settle $wbs" >&2; fi; exit 0
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" settle "$wbs" --spur-bin "$spurBin" || echo "residual-settle failed — re-run: residual-scan settle $wbs" >&2; else echo "residual-scan not staged — settle skipped — re-run: residual-scan settle $wbs" >&2; fi; exit 0
           # (c) command.gate owns the done transition with classified transient retry.
           - kind: command.gate
             options:
@@ -852,7 +880,7 @@ states:
           - kind: shell
             options:
                 command: >-
-                    S=plugins/sp/scripts/residual-scan.ts; [ -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" report "$wbs" --spur-bin "$spurBin" || echo "residual-report failed — re-run: residual-scan report $wbs" >&2; else echo "residual-scan not staged — report skipped — re-run: residual-scan report $wbs" >&2; fi; exit 0
+                    S=plugins/sp/scripts/residual-scan.ts; [ -f config/plugin-scripts.json -a -f "$S" ] || S="$(superskill script path sp residual-scan.mjs 2>/dev/null)"; if [ -f "$S" ]; then case "$S" in *.mjs) RUNNER=node ;; *) RUNNER=bun ;; esac; "$RUNNER" "$S" report "$wbs" --spur-bin "$spurBin" || echo "residual-report failed — re-run: residual-scan report $wbs" >&2; else echo "residual-scan not staged — report skipped — re-run: residual-scan report $wbs" >&2; fi; exit 0
 
     - id: cancelled
       description: Terminal — pipeline cancelled by operator at the approval gate (R1).
@@ -1163,6 +1191,6 @@ transitions:
     - from: record
       to: failed
       terminalReason: failed-check
-      description: Task check failed or proof evidence missing/malformed/mismatched — block before done.
+      description: Task check failed, a post-record residual downgrade, or proof evidence missing/malformed/mismatched — block before done.
       guard:
           kind: always

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