@gobing-ai/spur 0.3.94 → 0.3.96

package/config/workflows/wrapup-pipeline.yaml

@@ -13,17 +13,28 @@
 # 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
+#          -> doc-tripwire (1037: repo-wide tripwire over the still-uncommitted wrap
+#          diff; repair also enters it; the task-resolve fast path does not)
+#          -> 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;
+#        learnings-append and repair converge on doc-tripwire (1037), which runs
+#        docTripwireCmd — the repo-wide tripwires over the still-uncommitted wrap
+#        diff — before metrics-record; the task-resolve fast path never enters it;
 #        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
-#        `failed` (0770) instead of being absorbed by an always-defensive skip.
+#        capture, a failed required sync, a failed repo-wide tripwire (1037), or
+#        a failed feature gate routes to `failed` (0770) instead of being
+#        absorbed by an always-defensive skip.
 #
 # Vars (passed as a JSON object via `--vars`):
 # tasks    — JSON array of WBS strings, passed as a JSON-encoded STRING value
@@ -75,7 +86,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: wrapup-pipeline
-version: "5"
+version: "7"
 description: "Post-execution wrap-up: doc-sync (doc drift + learning capture), metrics, feature-transition, branch-cleanup"
 iterationBound: 10
 initialState: start
@@ -100,6 +111,13 @@ vars:
   # TRUSTED CONFIG ONLY — this string is executed via `sh -c` (same surface as
   # task-pipeline's qualityGateCmd). Never interpolate untrusted input into it.
   featureGateCmd: '$spurBin feature check "$feature"'
+  # Repo-wide tripwire over the wrap diff (1037): runs `bun run test-repo-wide`
+  # only when package.json declares the script, so other projects no-op. Callers
+  # can override it with --vars; an empty string disables the check (the hop
+  # still writes PASS).
+  # TRUSTED CONFIG ONLY — this string is executed via `sh -c` (same surface as
+  # featureGateCmd). Never interpolate untrusted input into it.
+  docTripwireCmd: 'if jq -e ''.scripts["test-repo-wide"]'' package.json >/dev/null 2>&1; then bun run test-repo-wide; fi'
   __hitlAnswer: ""
 
 states:
@@ -108,6 +126,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 +167,10 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -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;
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" 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,13 +185,14 @@ 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
-              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";
             else
-              printf '{"clean":false,"reasons":["probe script not found"],"paths":[]}' > ".spur/run/$__runId-drift-probe.json";
-              printf '\n' > ".spur/run/$__runId-mode.txt";
+              eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-drift-probe.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-drift-probe.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)";
+              if [ -f "$S" ]; then
+                "$RUNNER" "$S";
+              else
+                printf '{"clean":false,"reasons":["probe script not found"],"paths":[]}' > ".spur/run/$__runId-drift-probe.json";
+                printf '\n' > ".spur/run/$__runId-mode.txt";
+              fi;
             fi
       - kind: file.read.into-var
         options:
@@ -190,12 +213,10 @@ states:
         options:
           command: >-
             mkdir -p .spur/run .spur/memory &&
-            if [ -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;
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" 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 +255,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,17 +308,45 @@ 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
+      through the doc-tripwire hop (1037) 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: doc-tripwire
+    description: >
+      Repo-wide tripwire over the wrap diff (1037): the doc-sync edits are still
+      uncommitted when wrap-up reaches a terminal success, and the repo-wide
+      tripwires (repo-wide-tests/) execute only inside spur-check-feature — once
+      a wrap edit is committed on a clean tree, the working-diff tests (e.g.
+      adr-supersession (e)) can no longer see it. Entered from learnings-append
+      and repair, before metrics or feature state mutate, it runs the trusted
+      `docTripwireCmd` and records PASS or FAIL to a run-scoped status file; the
+      action always exits 0 so status truth lives in the file (0783 R4). Only a
+      verified run writes PASS; an empty docTripwireCmd disables the check and
+      still writes PASS. The no-doc-sync fast path (task-resolve →
+      metrics-record) never enters this state.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            sh -c "$docTripwireCmd" &&
+            printf 'PASS\n' > ".spur/run/$__runId-wrapup-doc-tripwire.status" ||
+            printf 'FAIL\n' > ".spur/run/$__runId-wrapup-doc-tripwire.status"
+
   - id: metrics-record
     description: >
       Append one JSONL row per task to .spur/memory/wrapup-metrics.jsonl deterministically.
@@ -288,18 +365,17 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -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;
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" 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
 
   - id: feature-transition
     description: >
-      If vars.feature is set, sync feature status via bounded feature-sync-bounded
+      If vars.feature is set, sync feature status via `spur feature sync` (repeated-BLOCKED
+      suppression is built into the sync service, so no wrapper script is needed)
       (0411). The shell terminates `exit 0` so artifacts already landed are never
       discarded, but the outcome is truthful (0770 + 0783 R4): sync succeeds only
       with a valid proposal matching vars.feature, no gateBlocked/requiresConfirm
@@ -322,12 +398,10 @@ states:
         options:
           command: >-
             mkdir -p .spur/run &&
-            if [ -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;
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" 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
 
@@ -387,9 +461,10 @@ states:
   - id: failed
     description: >
       Terminal — wrap-up failed (0770): invalid wrap input, an unresolved or
-      non-completed task, a failed metrics capture, a failed required sync, or
-      a failed feature gate. Already-written artifacts (learnings, metrics
-      rows, route reason) are preserved; nothing is rolled back.
+      non-completed task, a failed metrics capture, a failed required sync, a
+      failed repo-wide tripwire (1037), or a failed feature gate.
+      Already-written artifacts (learnings, metrics rows, route reason) are
+      preserved; nothing is rolled back.
 
 transitions:
   # ── start -> task-resolve ──
@@ -460,8 +535,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,20 +550,72 @@ transitions:
     guard:
       kind: always
 
-  # ── linear body: learnings-append -> metrics-record ──
+  # ── 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
+
+  # ── doc-sync exits converge on the doc-tripwire hop (1037) before metrics ──
   - from: learnings-append
-    to: metrics-record
-    description: Learning capture appended (or soft-skipped) — record metrics.
+    to: doc-tripwire
+    description: Learning capture appended (or soft-skipped) — run the repo-wide tripwire over the wrap diff.
     guard:
       kind: always
 
-  # ── repair: cheap path, no re-dispatch -> metrics-record ──
   - from: repair
-    to: metrics-record
-    description: Contract-violation repair recorded — proceed to metrics without re-dispatch.
+    to: doc-tripwire
+    description: Contract-violation repair recorded — run the tripwire before metrics without re-dispatch.
     guard:
       kind: always
 
+  # ── doc-tripwire: repo-wide tripwire gate (1037) ──
+  # Declaration order matters: the FAIL edge is tried first so a failed tripwire
+  # can never be absorbed by the PASS edge; a missing status matches neither
+  # edge and follows the engine's no-match behavior for status-file states.
+  - from: doc-tripwire
+    to: failed
+    terminalReason: failed-check
+    description: >
+      Repo-wide tripwire FAILED on the still-uncommitted wrap diff (1037): an
+      edit the doc-sync stage made (e.g. an in-place historical ADR change)
+      violates a working-diff test. Learnings and docs already on disk stay
+      put; nothing is rolled back.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-wrapup-doc-tripwire.status 2>/dev/null)" = FAIL'
+  - from: doc-tripwire
+    to: metrics-record
+    description: Repo-wide tripwire PASS (or the check disabled by an empty docTripwireCmd) — record metrics.
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-wrapup-doc-tripwire.status 2>/dev/null)" = PASS'
+
   # ── metrics-record: fail edge, then conditional routing (feature → merge → done) ──
   # Declaration order matters: the FAIL edge is tried first (0770), then
   # feature-transition (if feature is set), then branch-cleanup (if merge=true

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.94",
+    "version": "0.3.96",
     "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.9",
-        "@gobing-ai/ts-ai-runner": "^0.5.9",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.9",
-        "@gobing-ai/ts-infra": "^0.5.9",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.9",
-        "@gobing-ai/ts-rule-engine": "^0.5.9",
-        "@gobing-ai/ts-runtime": "^0.5.9",
-        "@gobing-ai/ts-utils": "^0.5.9",
+        "@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

@@ -133,11 +133,12 @@ list this README is checked against.
 | `dev-find-conflict` | Authority-aware semantic audit across source, task, feature, and project authority files — detect conflicts, resolve claim-specific authority, and route confirmed repairs through owner surfaces |
 | `dev-find-next`     | Prompt-first feature frontier prioritizer — ranks the open feature frontier by derived importance/urgency with per-candidate evidence; gates unactionable features; emits tree defects as proposals only     |
 | `dev-fixall`        | Fix all lint, type, and test errors systematically across the working tree                                                                                                                        |
+| `dev-fixgha`        | Find and fix failing GitHub Actions runs — gh fetch → diagnose → root-cause fix → commit → push → re-verify until green; optional context/filter argument                                        |
 | `dev-simplify`      | Simplify recently-changed code for clarity without changing behavior — incremental, test-after-each, revert on regression                                                                         |
 | `dev-refactor`      | Lens-routed refactoring with a preservation contract — taste lenses (api/architect/tests/ui) classify findings on the shared schema; cutting/breaking changes pause for operator approval; forwards to sp:code-refactoring |
 | `dev-arch`          | Survey a codebase (or module tree) for shallow modules and deepening opportunities — emit a ranked MARKDOWN candidate report that feeds the planning half; never auto-refactors                   |
 | `dev-reverse`       | Reverse-engineer a codebase — analyze unfamiliar repos, generate HLD/architecture docs, audit quality/security, and produce onboarding documentation                                              |
-| `dev-gitmsg`        | Generate conventional commit message(s) from the current change set via one bounded diff capture, optionally commit                                                                                         |
+| `dev-gitmsg`        | Generate conventional commit message(s) from the current change set via one bounded gather call, optionally commit                                                                                         |
 | `dev-gtd`           | Get things done — quality gate (auto-fix) → conventional commit → push → gh verify in one flow; optional act CI simulation via `--act`                                                          |
 | `dev-changelog`     | Generate changelog from git commits                                                                                                                                                               |
 
@@ -269,9 +270,9 @@ plugins/sp/
 │                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
 │                                    # + shared policy modules: agent-hint.ts, destructive-policy.{ts,test.ts}, task-file-policy.{ts,test.ts}
 │                                    # + pi/guard-extension.{ts,test.ts} (plugin.json `extensions.pi` entry point)
-├── scripts/                         # Executable helpers, split from prompts (ADR-031) — validate-commands.ts (thin-wrapper validator), batch-preflight.ts + scripts/<skill>/
+├── scripts/                         # Executable helpers, split from prompts (ADR-031) — batch-preflight.ts + scripts/<skill>/
 │                                    # (daily-summary: {daily-summary, logger}.ts; dogfood-testing: {detect-pipeline-driving, validate-report}.ts)
-├── tests/                           # Plugin tests — command-contract.test.ts + skill-structure.test.ts + batch-preflight.test.ts + per-skill suites
+├── tests/                           # Plugin tests — skill-structure.test.ts + batch-preflight.test.ts + per-skill suites (command-contract moved to scripts/commands/)
 ├── evals/                           # Skill behavioral eval harness (scenarios + judge + run-eval runner)
 ├── plugin.json                      # Marketplace entry
 └── README.md                        # This file
@@ -399,7 +400,7 @@ hand-editable source for the operator command surface. Per-platform adapters are
 output** owned by `superskill` (`superskill install sp`) and never committed here. Plugin `sp` ships
 no per-platform artifacts — only the platform-independent thin wrappers.
 
-**Thin-wrapper contract** is enforced by `scripts/validate-commands.ts`:
+**Thin-wrapper contract** is enforced by `scripts/commands/validate-commands.ts`:
 
 ```bash
 bun run validate-commands            # validate all 39 commands
@@ -415,7 +416,7 @@ gate (a) is strengthened: the ordered three-heading set `## Argument Flags` →
 `## Implementation` is required, and gate (e) checks the `argument-hint` is syntax-only (no
 Markdown links), the `## Argument Flags` table has exactly `Flag | Description | Default` columns,
 the command carries exactly one glossary reference, and canonical hint tokens have bidirectional
-parity with table rows. The same gates are tested in `tests/command-contract.test.ts` and
+parity with table rows. The same gates are tested in `scripts/commands/command-contract.test.ts` and
 `tests/command-flag-parity.test.ts`. See
 `docs/design/dev-command-argument-contract.md` for the full contract.
 
@@ -506,15 +507,12 @@ hold `SKILL.md` and prompt-side companions only.
 | `hooks/context-*.ts`                                 | Runtime for the three registered context hooks (session-start, post-tool, session-stop) — token-cost estimation + ledger append for `sp:indexed-context`                                                                                                                                          |
 | `hooks/careful-guard.ts`                             | Opt-in destructive-command guard (unwired — see Hooks above)                                                                                                                                                                                                                                      |
 | `scripts/batch-preflight.ts`                         | Pure TABLE A STOP evaluation for `super-planner` — skip doomed pipeline launches without spawning a Skill subprocess; recovery hints map stuck statuses to a single `/sp:dev-*` hop                                                                                                               |
-| `scripts/workflow-step-profile.ts`                   | Read-only step profile from `spur workflow trace` — per node and action-kind durations, idle gaps, session mode and `cacheHit` coverage, plus the ADR-115 cache-window flags `sp:spur-doctor` turns into workflow-optimization proposals |
+| `scripts/workflow-step-profile.ts`                   | Thin glue over the generated lib bundle (`lib/step-profile.generated.mjs` from `packages/app/src/workflow/step-profile.ts`) — read-only step profile from `spur workflow trace`: per node and action-kind durations, idle gaps, session mode and `cacheHit` coverage, plus the ADR-115 cache-window flags `sp:spur-doctor` turns into workflow-optimization proposals |
 | `scripts/dogfood-testing/detect-pipeline-driving.ts` | Word-boundary detector for pipeline-driving testees (leading-space invariant)                                                                                                                                                                                                                     |
 | `scripts/dogfood-testing/validate-report.ts`         | Pure `validateReport(md)` — footer-mandatory + 7-check finalize-or-abort contract with stable error codes                                                                                                                                                                                         |
 | `scripts/daily-summary/{daily-summary,logger}.ts`    | ccusage + git-history orchestration helpers for `sp:daily-summary`                                                                                                                                                                                                                                |
-| `scripts/feature-sync-bounded.ts`                    | Bounded retry-suppression wrapper for `spur feature sync` during batch/wrap-up runs — suppresses identical L4-blocked repeats                                                                                                              |
-| `scripts/stage-registry-adapter.ts`                  | dev-next golden-path adapter over the canonical stage registry — TABLE A/B/C resolution bridge for the status-aware facade                                                                                                                |
-| `scripts/task-size-precheck.ts`                      | Pipeline size precheck guard (R2) — evaluates R-item/Plan-count limits to PASS/FAIL                                                                                                              |
 | `scripts/task-diffstat.ts`                           | 0943 triage-lane diffstat producer — numstat + untracked scan vs the run base; writes `<wbs>-diffstat.json` with the sensitive-path flag; fails safe (sensitive)                                                       |
-| `scripts/validate-flag-contracts.ts`                 | Mechanical consistency gate — compares flag claims across command files, flag-glossary, cross-cutting, dev-operations, and ADR; reports disagreements                                                                                    |
+| `scripts/commands/validate-flag-contracts.ts`        | Mechanical consistency gate — compares flag claims across command files, flag-glossary, cross-cutting, dev-operations, and ADR; reports disagreements                                                                                    |
 | `*.test.ts`                                          | Unit suites — in `hooks/` for guards, in `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                                                     |
 
 **Design principle:** Scripts are **deterministic enforcement**. Unlike skills (which are advisory

package/plugins/sp/agents/super-reviewer.md

@@ -26,7 +26,8 @@ skills: [sp:code-verification, sp:functional-review, sp:code-improvement]
 
 The **review specialist** for the sp plugin. Runs the multi-dimensional review defined by
 `/sp:dev-review` — functional traceability, SECUA quality, and architectural depth — either
-standalone (a source path or a task WBS) or as the pipeline's Phase 7 review step.
+standalone (a task, a task set, a source path, or a path list) or as the pipeline's Phase 7
+review step.
 
 ## Role
 
@@ -44,8 +45,8 @@ write `## Review`. This coordinator is the single `## Review` writer in coordina
 fallback only and never overwrites authored Review.
 
 Your job: establish scope, dispatch each requested dimension to its skill, collect findings, merge
-them into a ranked report, and write the report to the task's `## Review` section (pipeline mode) or
-emit it as advisory output (standalone mode).
+them into a ranked report, and write the report to the task's `## Review` section (per task target)
+or emit it as advisory output (path target).
 
 ## When to use
 
@@ -57,9 +58,13 @@ emit it as advisory output (standalone mode).
 
 ### Direct-Entry (standalone)
 
-Invoked by the operator or `/sp:dev-review <wbs|path>`. You run the full multi-dimensional review
-and emit the ranked findings. Advisory by default — the operator decides what to act on. Only
-when invoked under the pipeline (or with `--next`) do blocker/major findings block a gate.
+Invoked by the operator or `/sp:dev-review` — usually as the coordinator definition the
+invoking session acts under (`/sp:dev-review` runs its review inline; it does not dispatch this
+agent). The target kind decides the output contract: **WBS target → the merged report is written
+to the task's `## Review` section** (via `spur task update <wbs> --section Review --from-file`);
+**path target → advisory output only** (no task mutation). With multiple targets the contract
+applies per target — see [Multi-target coordination](#multi-target-coordination-task-1023) below.
+Only when invoked under the pipeline do blocker/major findings block a gate.
 
 ### Pipeline Phase 7
 
@@ -68,12 +73,29 @@ Invoked by `task-pipeline.yaml`'s `review` step. The pipeline hands you the task
 return a PASS/PARTIAL/FAIL verdict to the pipeline's `approve(HITL)` gate. `blocker`/`major`
 findings block the gate; `minor`/`advisory` are recorded but do not block.
 
+### Multi-target coordination (task 1023)
+
+- **Task targets (`--tasks <selector>` / `--feature <id>[,<id>]`).** The set resolves once through
+  the batch selector grammar ([execution-batch.md § Step 1](../skills/spur-dev/references/execution-batch.md#step-1--selector-resolution-r1))
+  and freezes. Fan out one WBS-mode review per task and write each task's **own** merged
+  `## Review` — never merge two tasks into one Review. Tasks in `backlog`/`todo`/`blocked` are
+  reported **NOT-STARTED** and skipped (§ 3a outcome vocabulary); a per-task failure does not stop
+  the remaining tasks. End the run with a combined summary table (WBS, verdict, P1/P2 counts).
+- **Path targets (`--scope <path>[,<path>]`).** Paths must exist, are normalized, and
+  nested/duplicate paths are merged. Run one path-scope sub-review (Step 3p) per surviving path —
+  each eligible for native-subagent dispatch per
+  [dispatch-surface.md](../skills/parallel-execution/references/dispatch-surface.md) — then merge
+  the fragments, run **one** cross-path architecture pass (`sp:code-improvement` over the
+  inter-path imports), and emit **one** advisory report. No task mutation.
+- **`--triage` with multiple targets** buckets findings across all targets once; identical
+  `file:line` findings are deduped before bucketing.
+
 ## Skill invocation
 
 | Platform | Invocation |
 | ---------- | ----------- |
-| Claude Code | Spawned by `/sp:dev-review` → `Skill(skill="sp:code-verification"/"sp:functional-review"/"sp:code-improvement", args="...")` dispatch |
-| Other platforms | Invoke the three skills' review modes directly; this agent is the dispatcher |
+| Claude Code | The review coordinator dispatches `Skill(skill="sp:code-verification"/"sp:functional-review"/"sp:code-improvement", args="...")` — under `/sp:dev-review` the coordinator is the invoking session (this agent is not dispatched); when this agent is dispatched directly, it dispatches the same skills |
+| Other platforms | The coordinator invokes the three skills' review modes directly — this agent when dispatched, the invoking session under `/sp:dev-review` |
 
 ## Dispatch surface
 
@@ -94,13 +116,17 @@ HITL gate unless `--auto` was passed.
 
 ### Always
 
-- [ ] Establish scope first: WBS mode (task diff) or path mode (source glob). Derive the diff
-      scope the same way `sp:code-verification` Step 3 does.
+- [ ] Establish scope first per target kind: task targets (task diff → `sp:code-verification`
+      Step 3, one review per task) or path targets (tracked files under the path →
+      `sp:code-verification` Step 3p, one sub-review per path). Defer to that recipe — no
+      restated copy.
 - [ ] Dispatch each requested dimension to its owning skill — do not inline the review logic.
 - [ ] Merge findings into a single ranked report, emitting native priority cells
       (`P1 (blocker)` > `P2 (major)` > `P3 (minor)` > `P4 (advisory)` — see Output Format).
-- [ ] In pipeline mode, write the merged report to the task's `## Review` section via
-      `spur task update <wbs> --section Review --from-file`; in standalone mode, emit as output.
+- [ ] With a WBS target (standalone or pipeline), write the merged report to that task's
+      `## Review` section via `spur task update <wbs> --section Review --from-file` — per task
+      under a task set, then the combined summary table; with a path target, emit as advisory
+      output (one merged report for a path list, including the cross-path architecture pass).
 - [ ] Cite `file:line` evidence for every finding — no vague "implemented correctly."
 - [ ] Apply the honesty gate: no PASS verdict without fresh, pasted verification evidence.
 
@@ -139,10 +165,11 @@ fails it. One explicit mapping, no transcription step anywhere downstream:
 Severity words stay visible in the same cell — the mapping adds the machine-readable label, it does
 not replace the semantics.
 
-**Section-relative headings.** In pipeline mode the report body is written *into* the task's
-`### Review` section, so every heading inside it MUST be `####` or deeper. A `##`/`###` heading in
-the body becomes a new top-level task section and corrupts the document. In standalone mode
-(emitted as output, not written to a task) the same body may be rendered one level shallower.
+**Section-relative headings.** In WBS mode (standalone or pipeline) the report body is written
+*into* the task's `### Review` section, so every heading inside it MUST be `####` or deeper. A
+`##`/`###` heading in the body becomes a new top-level task section and corrupts the document. With
+a path target (emitted as output, not written to a task) the same body may be rendered one level
+shallower.
 
 ```markdown
 #### Review Report — <wbs|path>
@@ -180,8 +207,6 @@ rejected by the checker, and so they should be:
 | 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` |
 ```
 
-With `--json`, emit the same shape as a JSON object for machine consumption.
-
 ## Out of scope
 
 - Implementing fixes (that's `sp:code-implementation` / `sp:super-coder`).