@gobing-ai/spur 0.3.47 → 0.3.49

package/config/workflows/pr-review.yaml

@@ -0,0 +1,338 @@
+# PR-review workflow: deterministic spine for /sp:dev-pr-review (skill sp:pr-reviewing).
+# Authored for the @gobing-ai/ts-dual-workflow-engine state-machine schema
+# (initialState / states[].id / onEnter / top-level transitions), same family as
+# basic.yaml / task-pipeline.yaml. Seeded into projects by `spur init` (scaffold manifest).
+#
+# Shape: preflight → hygiene → precheck → push → ensure-pr → request → wait → collect → done
+#        (soft probes everywhere: red gates route to `failed`/`pending` via transitions,
+#         never a raw lifecycle abort — same reliability contract as basic.yaml)
+#
+# This YAML is the SSOT for the review spine's state order and guards. Every state shells
+# out to the staged pr-reviewing.ts entrypoint (the tested deterministic core); no gh/git
+# logic lives in this file. All model-bearing work — finding triage, `fix` mode, `rules`
+# mode — stays in the sp:pr-reviewing skill and never enters this machine.
+#
+# Non-negotiable: the external review goes through the GitHub PR + an `@codex review`
+# comment. Never substitute a local Codex review mechanism.
+#
+# Vars (override per run: --vars '{"mode":"submit","focus":"migration safety"}'):
+#   mode             — full (default) | submit | rerun
+#                        full:   dedupe an up-to-date Codex review, else request + wait + collect
+#                        submit: request and stop at `pending` (no wait)
+#                        rerun:  request with --force even when HEAD is already reviewed
+#   baseBranch       — base for a newly created PR (default: existing PR base, else repo default)
+#   focus            — extra review focus appended to the @codex request
+#   noWait           — "true" returns pending right after the request instead of polling
+#   waitTimeoutSec   — poll budget for Codex output (default 600)
+#   waitIntervalSec  — poll interval (default 30; do not poll aggressively)
+#   preReviewCmd     — project fast check run before requesting (empty = skipped).
+#                      TRUSTED CONFIG ONLY — executed via `sh -c` (task 0436 SECUA residual).
+#                      Never interpolate untrusted operator/LLM input into it.
+#   __runId          — injected by WorkflowAppService.run(); scopes .spur/run artifacts.
+
+"$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
+name: pr-review
+kind: state-machine
+description: GitHub Codex PR-review spine — preflight → hygiene → precheck → push → ensure-pr → request → wait → collect
+iterationBound: 16
+initialState: preflight
+terminalStates:
+  - done
+  - pending
+  - failed
+failureStates:
+  - failed
+vars:
+  mode: 'full'
+  baseBranch: ''
+  focus: ''
+  noWait: 'false'
+  waitTimeoutSec: '600'
+  waitIntervalSec: '30'
+  preReviewCmd: ''
+  __runId: ''
+
+states:
+  - id: preflight
+    description: >
+      Soft probe: git/gh/repo checks (detached HEAD, dirty tree, gh auth, GitHub remote).
+      Writes PASS|FAIL to .spur/run/${vars.__runId}-pr-preflight.status; always exit 0.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-preflight.status" &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" preflight --json > ".spur/run/$__runId-pr-context.json";
+            rc=$?; set -e &&
+            if [ "$rc" -eq 0 ]; then printf 'PASS\n' > "$STATUS_FILE"; else printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: hygiene
+    description: >
+      Submission sanity scan of base...HEAD: secrets/.env/conflict markers BLOCK the run;
+      debug residue only WARNs. Not a replacement for the independent Codex review.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-hygiene.status" &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" hygiene --base "$baseBranch" --json
+            --status-file "$STATUS_FILE" > ".spur/run/$__runId-pr-hygiene.json";
+            rc=$?; set -e &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: precheck
+    description: >
+      Optional project fast check (vars.preReviewCmd) before spending a review request.
+      Empty command records SKIP; a red check stops the run before request (fail loud).
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-precheck.status" &&
+            if [ -z "$preReviewCmd" ]; then
+              printf 'SKIP\n' > "$STATUS_FILE";
+            else
+              set +e; sh -c "$preReviewCmd"; rc=$?; set -e;
+              if [ "$rc" -eq 0 ]; then printf 'PASS\n' > "$STATUS_FILE"; else printf 'FAIL\n' > "$STATUS_FILE"; fi;
+            fi &&
+            exit 0
+
+  - id: push
+    description: >
+      Publish the branch (normal push only, never force; sets upstream when missing).
+      A PR reviews pushed commits only.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-push.status" &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" push --json --status-file "$STATUS_FILE"
+            > ".spur/run/$__runId-pr-push.json";
+            rc=$?; set -e &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: ensure-pr
+    description: Find or create the GitHub PR for the current branch — never a duplicate.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-ensure.status" &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" ensure-pr --base "$baseBranch" --json
+            --status-file "$STATUS_FILE" > ".spur/run/$__runId-pr.json";
+            rc=$?; set -e &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: request
+    description: >
+      Post the `@codex review` request (per-HEAD dedupe unless mode=rerun forces).
+      Records the request under .spur/run/${vars.__runId}-pr-request.json.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-request.status" &&
+            FORCE_FLAG="" &&
+            if [ "$mode" = "rerun" ]; then FORCE_FLAG="--force"; fi &&
+            set +e &&
+            bun "$(superskill script path sp pr-reviewing.ts)" request --focus "$focus" $FORCE_FLAG --json
+            --status-file "$STATUS_FILE" > ".spur/run/$__runId-pr-request.json";
+            rc=$?; set -e &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: wait
+    description: >
+      Bounded poll for Codex output on the current pushed HEAD. Timeout records TIMEOUT
+      and routes to `pending` — never a failure (collect later with /sp:dev-pr-review collect).
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-wait.status" &&
+            set +e &&
+            SINCE="$(bun -e 'const fs=require("node:fs");const value=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).requestedAt;process.stdout.write(value ?? "")' ".spur/run/$__runId-pr-request.json")" &&
+            REQUEST_HEAD="$(bun -e 'const fs=require("node:fs");const value=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).head;process.stdout.write(value ?? "")' ".spur/run/$__runId-pr-request.json")" &&
+            bun "$(superskill script path sp pr-reviewing.ts)" wait --since "$SINCE" --head "$REQUEST_HEAD" --timeout "$waitTimeoutSec" --interval "$waitIntervalSec"
+            --json --status-file "$STATUS_FILE" > ".spur/run/$__runId-pr-wait.json";
+            rc=$?; set -e &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            exit 0
+
+  - id: collect
+    description: Normalize the latest current-HEAD Codex result and record composite PR/CI status.
+    onEnter:
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            STATUS_FILE=".spur/run/$__runId-pr-collect.status" &&
+            set +e &&
+            SINCE="$(bun -e 'const fs=require("node:fs");const value=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).requestedAt;process.stdout.write(value ?? "")' ".spur/run/$__runId-pr-request.json")" &&
+            REQUEST_HEAD="$(bun -e 'const fs=require("node:fs");const value=JSON.parse(fs.readFileSync(process.argv[1],"utf8")).head;process.stdout.write(value ?? "")' ".spur/run/$__runId-pr-request.json")" &&
+            bun "$(superskill script path sp pr-reviewing.ts)" collect --since "$SINCE" --head "$REQUEST_HEAD" --json
+            --status-file "$STATUS_FILE" > ".spur/run/$__runId-pr-findings.json";
+            collect_rc=$?;
+            bun "$(superskill script path sp pr-reviewing.ts)" status --since "$SINCE" --head "$REQUEST_HEAD" --json > ".spur/run/$__runId-pr-status.json";
+            status_rc=$?; set -e &&
+            if [ "$collect_rc" -ne 0 ] || [ "$status_rc" -ne 0 ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            if [ ! -f "$STATUS_FILE" ]; then printf 'FAIL\n' > "$STATUS_FILE"; fi &&
+            { cat ".spur/run/$__runId-pr-findings.json" 2>/dev/null || true; } &&
+            exit 0
+
+  - id: done
+    description: Terminal — review collected; findings artifact at .spur/run/${vars.__runId}-pr-findings.json
+  - id: pending
+    description: Terminal — review requested (or timed out) but not yet collected; run /sp:dev-pr-review collect later
+  - id: failed
+    description: Terminal — a gate went red; the stage .status/.json artifacts under .spur/run name the blocker
+
+transitions:
+  - from: preflight
+    to: hygiene
+    description: Repo, gh auth, and clean tree verified
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-preflight.status 2>/dev/null)" = PASS'
+  - from: preflight
+    to: failed
+    description: Preflight red (detached HEAD, dirty tree, gh auth, no GitHub remote) — stop before any publishing
+    guard:
+      kind: always
+
+  - from: hygiene
+    to: precheck
+    description: Clean or warn-only — warnings ride along to the report
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(PASS|WARN)$" .spur/run/$__runId-pr-hygiene.status 2>/dev/null'
+  - from: hygiene
+    to: failed
+    description: BLOCK (secrets/.env/conflict markers) or probe failure — never submit a tainted diff
+    guard:
+      kind: always
+
+  - from: precheck
+    to: push
+    description: Project fast check passed or was skipped
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(PASS|SKIP)$" .spur/run/$__runId-pr-precheck.status 2>/dev/null'
+  - from: precheck
+    to: failed
+    description: Project checks red — do not spend a review request on code that fails its own gate
+    guard:
+      kind: always
+
+  - from: push
+    to: ensure-pr
+    description: Branch published (or already up to date)
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(PUSHED|UP_TO_DATE)$" .spur/run/$__runId-pr-push.status 2>/dev/null'
+  - from: push
+    to: failed
+    description: Push rejected (e.g. non-fast-forward) — report; never force-push as a workaround
+    guard:
+      kind: always
+
+  - from: ensure-pr
+    to: request
+    description: PR found or created
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(FOUND|CREATED)$" .spur/run/$__runId-pr-ensure.status 2>/dev/null'
+  - from: ensure-pr
+    to: failed
+    description: No reviewable delta or PR creation failed — report the actual git/GitHub state
+    guard:
+      kind: always
+
+  # Declaration order matters: ALREADY_REVIEWED routes straight to collect (full mode dedupe);
+  # submit/noWait stop at pending; everything else waits.
+  - from: request
+    to: collect
+    description: Current HEAD already carries a Codex review — collect instead of duplicating
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-request.status 2>/dev/null)" = ALREADY_REVIEWED'
+  - from: request
+    to: pending
+    description: Request already in flight, or mode=submit/--no-wait after posting — return pending
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-request.status 2>/dev/null)" = ALREADY_REQUESTED || { test "$(cat .spur/run/$__runId-pr-request.status 2>/dev/null)" = REQUESTED && { test "$mode" = "submit" || test "$noWait" = "true"; }; }'
+  - from: request
+    to: wait
+    description: Request posted — poll for the result
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-request.status 2>/dev/null)" = REQUESTED'
+  - from: request
+    to: failed
+    description: Request failed (no PR, gh error) — report the preserved error
+    guard:
+      kind: always
+
+  - from: wait
+    to: collect
+    description: Codex findings or an explicit clean result on the current HEAD found
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(FOUND|CLEAN)$" .spur/run/$__runId-pr-wait.status 2>/dev/null'
+  - from: wait
+    to: pending
+    description: Poll budget exhausted — pending, not failed
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-wait.status 2>/dev/null)" = TIMEOUT'
+  - from: wait
+    to: failed
+    description: Poll probe itself failed
+    guard:
+      kind: always
+
+  - from: collect
+    to: done
+    description: Current-HEAD review collected (CLEAN/FINDINGS)
+    guard:
+      kind: shell
+      options:
+        command: 'grep -qE "^(FINDINGS|CLEAN)$" .spur/run/$__runId-pr-collect.status 2>/dev/null'
+  - from: collect
+    to: pending
+    description: No current-HEAD result yet — pending, never clean
+    guard:
+      kind: shell
+      options:
+        command: 'test "$(cat .spur/run/$__runId-pr-collect.status 2>/dev/null)" = PENDING'
+  - from: collect
+    to: failed
+    description: Collect probe failed
+    guard:
+      kind: always

package/config/workflows/task-pipeline.yaml

@@ -262,6 +262,8 @@ states:
         options:
           agent: ${vars.implementAgent}
           # Pure slash command only (ADR-043). Anti-recursion / implement discipline
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           # lives in /sp:dev-run --mode implement → sp:code-implementation, not YAML prose.
           input: /sp:dev-run --mode implement ${vars.wbs} --auto
           timeoutMs: ${vars.implementTimeoutMs}
@@ -374,6 +376,8 @@ states:
         options:
           agent: ${vars.agent}
           # R3 (0482): `--findings` names the failing anchors inline; `--gate-log` remains
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           # the full-context escape hatch when the digest is not enough.
           input: /sp:dev-fixall "${vars.qualityGateCmd}" --gate-log .spur/run/${vars.wbs}-test-gate.log --findings "${vars.gateFindings}"
           timeoutMs: ${vars.stepTimeoutMs}
@@ -422,6 +426,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-review ${vars.wbs} --auto
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: approve
@@ -452,6 +458,8 @@ states:
         options:
           agent: ${vars.agent}
           input: /sp:dev-verify ${vars.wbs} --auto --fix all --focus all
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           timeoutMs: ${vars.stepTimeoutMs}
           answerFile: .spur/run/${vars.wbs}-verify-answer.txt
       - kind: shell

package/config/workflows/wayfinder-resolution.yaml

@@ -82,6 +82,8 @@ states:
         options:
           agent: ${vars.agent}
           capture: true
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: planner
           mode: text
           input: >-
             Resolve task ${vars.wbs} in resolution mode ${vars.resolutionMode} using the prepared
@@ -115,6 +117,8 @@ states:
         options:
           agent: ${vars.agent}
           capture: true
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: reviewer
           mode: text
           input: >-
             Verify resolved task ${vars.wbs} using only local reads and `spur` CLI. Check its

package/config/workflows/wrapup-pipeline.yaml

@@ -80,7 +80,9 @@ states:
       - kind: agent.run
         options:
           agent: ${vars.agent}
-          input: "Skill(skill=\"sp:doc-evolve\", args=\"wrapup tasks=${vars.tasks}\"). Repair drift in docs/00_ADR.md, docs/03_ARCHITECTURE.md, docs/04_DESIGN.md, docs/design/* per constitution edit rules. Do not write task/feature corpus."
+          input: 'Skill(skill="sp:doc-evolve", args="wrapup tasks=${vars.tasks}"). Repair drift in docs/00_ADR.md, docs/03_ARCHITECTURE.md, docs/04_DESIGN.md, docs/design/* per constitution edit rules. Do not write task/feature corpus.'
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           timeoutMs: ${vars.stepTimeoutMs}
 
   - id: learning-capture
@@ -93,6 +95,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "Extract working learnings from tasks ${vars.tasks}. Output raw markdown (no fences) grouped by date and task WBS: conventions, errors fixed, patterns, gotchas. Captured to .spur/run/wrapup-learnings.md."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: coder
           answerFile: .spur/run/wrapup-learnings.md
           expectFile: .spur/run/wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
@@ -103,6 +107,8 @@ states:
             if test -s .spur/run/wrapup-learnings.md; then
               cat .spur/run/wrapup-learnings.md >> .spur/memory/learnings.md &&
               printf '\n' >> .spur/memory/learnings.md;
+            else
+              echo "wrapup: learning capture missing or empty at $PWD/.spur/run/wrapup-learnings.md - append skipped" >&2;
             fi &&
             exit 0
 
@@ -115,6 +121,8 @@ states:
         options:
           agent: ${vars.agent}
           input: "For each task in ${vars.tasks}, output one JSONL line (no fences) with fields: wbs, feature_id, status, verdict, timestamp. Captured to .spur/run/wrapup-metrics.jsonl."
+          # Declared Layer-1 role (0538 R2): routing reason beside the agent: pin.
+          role: scribe
           answerFile: .spur/run/wrapup-metrics.jsonl
           expectFile: .spur/run/wrapup-metrics.jsonl
           timeoutMs: ${vars.stepTimeoutMs}
@@ -124,6 +132,8 @@ states:
             mkdir -p .spur/memory &&
             if test -s .spur/run/wrapup-metrics.jsonl; then
               cat .spur/run/wrapup-metrics.jsonl >> .spur/memory/wrapup-metrics.jsonl;
+            else
+              echo "wrapup: metrics capture missing or empty at $PWD/.spur/run/wrapup-metrics.jsonl - append skipped" >&2;
             fi &&
             exit 0
 
@@ -131,6 +141,9 @@ states:
     description: >
       If vars.feature is set, sync feature status via bounded feature-sync-bounded
       (0411). Soft shell — blocked/failed sync must not abort wrap-up after metrics.
+      Empty vars.feature is NOT a blocked sync but a mis-invocation (the engine only
+      enters this state when vars.feature is set) and fails loud (dogfood 2026-08-15,
+      feature I3: a silent exit 0 made the wrap look complete with no transition).
     onEnter:
       # Genuinely soft: the terminating `exit 0` must be reached on BOTH branches, so
       # the sync is chained with `;` — with `&&` a non-zero sync skipped `exit 0` and
@@ -142,6 +155,10 @@ states:
       - kind: shell
         options:
           command: >-
+            if [ -z "$feature" ]; then
+              echo "feature-transition: vars.feature is empty — refusing no-op feature sync (mis-invocation, not a blocked sync)" >&2;
+              exit 1;
+            fi;
             if [ -f plugins/sp/scripts/feature-sync-bounded.ts ]; then
               bun plugins/sp/scripts/feature-sync-bounded.ts "$feature" --spur-bin "$spurBin" --json;
             else

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.47",
+    "version": "0.3.49",
     "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",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.31",
-        "@gobing-ai/ts-ai-runner": "^0.4.31",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.31",
-        "@gobing-ai/ts-infra": "^0.4.31",
+        "@gobing-ai/ts-db": "^0.4.35",
+        "@gobing-ai/ts-ai-runner": "^0.4.35",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.35",
+        "@gobing-ai/ts-infra": "^0.4.35",
         "@gobing-ai/ts-llm-jsonl-importer": "^0.4.31",
-        "@gobing-ai/ts-rule-engine": "^0.4.31",
-        "@gobing-ai/ts-runtime": "^0.4.31",
-        "@gobing-ai/ts-utils": "^0.4.31",
+        "@gobing-ai/ts-rule-engine": "^0.4.35",
+        "@gobing-ai/ts-runtime": "^0.4.35",
+        "@gobing-ai/ts-utils": "^0.4.35",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -103,11 +103,12 @@ 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-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                                                                                           |
 | `dev-wrap`          | Wrap up a single completed task — learnings, metrics, doc-sync, optional feature transition and branch cleanup                                  |
 | `dev-refresh`       | Refresh feature status by feature ID, task WBS, or batch sweep via spur feature sync                                                            |
-| `dev-featurechange` | Restructure feature tree from a mapping file — dry-run/apply via `spur feature move`, task edges, root `docs/*.md` only                         |
+| `dev-feature-change` | Restructure feature tree from a mapping file — dry-run/apply via `spur feature move`, task edges, root `docs/*.md` only                         |
 
 #### Lifecycle — batch and parallel
 
@@ -126,6 +127,7 @@ list this README is checked against.
 | `dev-handover`      | Generate a structured handover document when blocked — captures goal, progress, blocker, rejected approaches, and next steps                                                                      |
 | `dev-debug`         | Systematic debugging protocol — reproduce, isolate, diagnose root cause, apply minimal fix, and verify with regression tests                                                                      |
 | `dev-daily`         | Generate a daily summary report from agent usage data, git history, and notes                                                                                                                     |
+| `dev-history-load`  | On-demand cumulative history load + narrowed analyze — import (checkpoint-resume) then analyze, optionally by session/task/window, with optional forensics render                                     |
 | `dev-dogfood`       | Dogfood an agent skill/command/CLI — drive it end-to-end with bounded auto-fix, self-monitor, and emit a comprehensive report                                                                     |
 | `dev-find-issue`    | Review agent session logs, identify performance bottlenecks and behavioral anti-patterns, and generate a structured task file with proposed fixes                                                 |
 | `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 |
@@ -135,7 +137,7 @@ list this README is checked against.
 | `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 staged changes via per-file summarization, optionally commit                                                                                         |
-| `dev-gtd`           | Get things done — quality gate (auto-fix) → act CI simulation → conventional commit → push → gh verify in one flow                                                                                |
+| `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                                                                                                                                                               |
 
 #### Rule authoring
@@ -313,6 +315,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `issue-finding`             | 1.1   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; backs `/sp:dev-find-issue`                                                                                        |
 | `conflict-finding`          | 1.0   | Authority-aware semantic audit — four-pillar (source/task/feature/authority) conflict discovery, claim-specific authority resolution, reproducible evidence, confirmed owner-routed remediation; backs `/sp:dev-find-conflict`             |
 | `next-feature`              | 1.0   | Prompt-first feature frontier prioritizer — sync-first precondition, B3 actionability gate (cited, never restated), tiered rubric over measured signals, D1–D4 defect proposals conforming to the restructure map schema; backs `/sp:dev-find-next` |
+| `pr-reviewing`              | 1.0   | GitHub Codex PR review — PR prepare/reuse, `@codex review` request with per-HEAD dedupe, bounded polling, findings normalization, validated fix + re-review; spine SSOT `pr-review.yaml` + `scripts/pr-reviewing.ts`; backs `/sp:dev-pr-review`     |
 | `indexed-context`           | 1.0   | Cross-agent project context — anatomy/learnings/pitfalls/buglog/memory in `.spur/context/`; hook-tracked token-ledger; graceful degradation on agents without hooks                                                                        |
 
 Each skill directory contains:
@@ -335,11 +338,11 @@ Skills contain zero validation logic — the CLI is the gate.
 
 Thin slash-command wrappers that parse user arguments and delegate to the corresponding skill. Each
 command is a user-facing entry point that bridges natural language to skill invocation. There are
-**37 commands** (see the Command index above for the full list), organized by the surface they wrap:
+**39 commands** (see the Command index above for the full list), organized by the surface they wrap:
 
 | Prefix       | Count | Delegates to                                                                                                                                                                                                                                                                                                        | Purpose                                                                                |
 | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `dev-*`      | 31    | `sp:spur-dev`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:code-simplification`, `sp:next-router`, `sp:brainstorm`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:sys-debugging`, `sp:daily-summary`, `sp:issue-finding`, `sp:conflict-finding`, `sp:reverse-engineering`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
+| `dev-*`      | 33    | `sp:spur-dev`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:code-simplification`, `sp:next-router`, `sp:brainstorm`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:sys-debugging`, `sp:daily-summary`, `sp:issue-finding`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
 | `rule-*`     | 3     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The rule surface — `rule-add`, `rule-refine`, `rule-scan`                              |
 | `workflow-*` | 2     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The workflow surface — `workflow-add`, `workflow-refine`                               |
 | `spur-init`  | 1     | `sp:doc-evolve`                                                                                                                                                                                                                                                                                                     | Project bootstrap (`spur init`) with doc-evolve integration                            |
@@ -349,7 +352,7 @@ Each command file contains:
 - YAML frontmatter (`description`, `argument-hint`, `allowed-tools`).
 - A delegation block: `Skill(skill="sp:<skill-name>", args="<operation> $ARGUMENTS")`.
 
-**Commands as SSOT (ADR-032).** The 37 `.md` files in `commands/` are the authoritative,
+**Commands as SSOT (ADR-032).** The 39 `.md` files in `commands/` are the authoritative,
 hand-editable source for the operator command surface. Per-platform adapters are **install-time
 output** owned by `superskill` (`superskill install sp`) and never committed here. Plugin `sp` ships
 no per-platform artifacts — only the platform-independent thin wrappers.
@@ -357,7 +360,7 @@ no per-platform artifacts — only the platform-independent thin wrappers.
 **Thin-wrapper contract** is enforced by `scripts/validate-commands.ts`:
 
 ```bash
-bun plugins/sp/scripts/validate-commands.ts            # validate all 37 commands
+bun plugins/sp/scripts/validate-commands.ts            # validate all 39 commands
 bun plugins/sp/scripts/validate-commands.ts --json     # machine-readable output
 ```
 

package/plugins/sp/agents/expert-spur.md

@@ -66,6 +66,7 @@ Invoke `sp:spur-cli` for verb guidance and per-noun conventions:
 
 - [ ] Delegate verb guidance to `sp:spur-cli`; use the `spur` CLI for all mutations.
 - [ ] Run the noun's `check`/`validate` verb before and after editing (e.g. `spur task check <wbs> --json`).
+- [ ] Run the corpus-wide sweep after batch edits: `spur task check --corpus --json` (fails on structural errors outside `config/corpus-baseline.json`).
 - [ ] Use `spur task update --section --from-file` for all task section edits.
 - [ ] Run the noun's `refresh` after batch operations where one exists (`spur task refresh`, `spur feature refresh`).
 

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

@@ -1,5 +1,6 @@
 ---
 description: 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
+role: planner
 argument-hint: "[<module-path>] [--scope <all|path>] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Grep", "Glob", "Skill"]
 ---
@@ -14,7 +15,7 @@ Wraps the **sp:sys-architecture** skill.
 | --- | --- | --- |
 | `[<module-path>]` | Module path to scope the architecture survey. | omitted (whole repo) |
 | `--scope` `<all\|path>` | Limit the survey to a path or expand to the whole repo. | all |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing survey work. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing survey work. | omit |
 | `--json` | Emit structured JSON instead of markdown. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).

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

@@ -1,5 +1,6 @@
 ---
 description: Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring
+role: planner
 argument-hint: "<topic> [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:brainstorm** and **sp:wayfinder** skills.
 | `<topic>` | Topic or problem statement to explore. | required |
 | `--depth` `<basic\|detailed\|comprehensive>` | Breadth vs. depth of the exploration. | detailed |
 | `--options` `<n>` | Number of solution options to generate. | 3 |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. | omit |
 | `--skip-discovery` | Skip the discovery interview; ideate immediately. | off |
 | `--wayfind` | Spawn a wayfinder feature for multi-session routing. | off |
 | `--task` `[<feature-id>]` | Create a tracking task under a feature. | omitted |

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

@@ -1,5 +1,6 @@
 ---
 description: Generate changelog from git commits
+role: scribe
 argument-hint: "[--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
 allowed-tools: ["Bash", "Read"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: "Generate a daily summary report from agent usage data, git history, and notes"
+role: scribe
 argument-hint: "[--date <YYYY-MM-DD>] [--dry-run] [--output <path>] [--no-git] [--no-ccusage]"
 allowed-tools: ["Bash", "Read"]
 ---

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

@@ -1,5 +1,6 @@
 ---
 description: "Systematic debugging protocol — reproduce, isolate, diagnose root cause, apply minimal fix, and verify with regression tests"
+role: coder
 argument-hint: "\"<symptom | failing command>\" [--scope <path>] [--task [<wbs>]] [--agent <inline|auto|name>]"
 allowed-tools: ["Bash", "Read", "Write", "Skill"]
 ---
@@ -15,7 +16,7 @@ Wraps the **sp:sys-debugging** skill.
 | `"<symptom \| failing command>"` | Symptom or failing command to diagnose. | required |
 | `--scope` `<path>` | Scope the reproduction/isolation to a path. | cwd |
 | `--task` `[<wbs>]` | Attach findings to a task. | omitted |
-| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing diagnosis. | inline |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing diagnosis. | omit |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).