@gobing-ai/spur 0.3.48 → 0.3.50

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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.48",
+    "version": "0.3.50",
     "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.32",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.31",
-        "@gobing-ai/ts-infra": "^0.4.31",
-        "@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-db": "^0.4.38",
+        "@gobing-ai/ts-ai-runner": "^0.4.38",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.38",
+        "@gobing-ai/ts-infra": "^0.4.38",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.38",
+        "@gobing-ai/ts-rule-engine": "^0.4.38",
+        "@gobing-ai/ts-runtime": "^0.4.38",
+        "@gobing-ai/ts-utils": "^0.4.38",
         "@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/commands/{dev-featurechange.md → dev-feature-change.md}

@@ -1,14 +1,11 @@
 ---
-description: >-
+description: "Restructure the feature tree from a mapping file — dry-run then apply via spur feature move / task feature_id edges / root docs/*.md reference rewrites (CLI-gated; no raw Write on docs/features or docs/tasks). Triggers: feature restructure, feature tree move, reparent features, apply mapping file"
 role: planner
-  Restructure the feature tree from a mapping file — dry-run then apply via
-  spur feature move / task feature_id edges / root docs/*.md reference rewrites
-  (CLI-gated; no raw Write on docs/features or docs/tasks)
 argument-hint: "[--map <path>] [--dry-run] [--apply] [--limit <old-id>] [--wave <1|2|3|all>] [--yes]"
 allowed-tools: ["Bash", "Read", "AskUserQuestion", "Skill"]
 ---
 
-# Dev Featurechange
+# Dev Feature Change
 
 CLI-gated feature-tree restructure orchestrator. Executes dispositions from a mapping file; does not invent hierarchy.
 
@@ -28,7 +25,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ## Usage
 
 ```
-/sp:dev-featurechange [--map <path>] [--dry-run] [--apply] [--limit <old-id>] [--wave <1|2|3|all>] [--yes]
+/sp:dev-feature-change [--map <path>] [--dry-run] [--apply] [--limit <old-id>] [--wave <1|2|3|all>] [--yes]
 ```
 
 ## Implementation
@@ -43,7 +40,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 - Read `--map`. Collect rows where disposition is not `keep` (typically `reparent-under:<parent>`).
 - Filter by `--limit` / `--wave` if set.
-- Wave defaults from map: **1** = K→J, L→J · **2** = N→H, O→H · **3** = P→D, Q→F, R→F8.
+- Wave membership comes from the map itself (its wave column/section is the SSOT). Never hard-code letter sets here — the tree moves under the command and literals go stale.
 
 **Free-digit preflight (mandatory before dry-run report)**
 
@@ -53,7 +50,7 @@ Group selected reparent rows by `new_parent`. For each parent:
 spur feature list --json
 ```
 
-Count current children (ids where `id` starts with parent and length = parent.length+1, digit 1–9).  
+Count current children (ids where `id` starts with parent and length = parent.length+1, digit 1–9).
 `free = 9 - childCount`. If `rowsUnderParent.length > free`, **abort the plan** with a clear error naming the parent, free slots, and competing old_ids. Do not apply a partial wave.
 
 **Dry-run plan (always) — sequential prediction**
@@ -102,10 +99,10 @@ spur feature refresh --json
 spur feature check --json
 ```
 
-Task edges: `feature move` rewrites `feature_id` across **all** configured task folders (via `foldersConfig`). Safety check:
+Task edges: `feature move` rewrites `feature_id` across **all** configured task folders (via `foldersConfig`). Safety check (the glob covers every tasks folder, present and future):
 
 ```bash
-rg -n '^feature_id: <old_id>$' docs/tasks docs/tasks2 docs/tasks3
+rg -n '^feature_id: <old_id>$' docs/tasks*/
 ```
 
 If any stale edges remain, fix with:

package/plugins/sp/commands/dev-find-issue.md

@@ -1,7 +1,7 @@
 ---
 description: "Render the session-forensics report from imported history data (8 CLI-derivable sections plus 6 model-authored), identify bottlenecks and behavioral anti-patterns, and optionally create a structured fix task behind --create-task. Triggers: post-mortem, performance analysis, session review, find issues, identify bottlenecks"
 role: reviewer
-argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|omp|claude|codex|gemini|opencode|antigravity|openclaw|pi>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--create-task] [--agent <inline|auto|name>] [--json]"
+argument-hint: "[<topic>] [--sessions <glob>] [--source <auto|pi|claude|codex|gemini|opencode|antigravity|openclaw|omp|grok|agy|all>] [--feature <id>] [--template <meta|issue|standard>] [--priority <P0|P1|P2|P3>] [--severity <S0|S1|S2>] [--category <list>] [--since <iso>] [--until <iso>] [--top <n>] [--min-cost <duration>] [--strict-topic] [--create-task] [--agent <inline|auto|name>] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
 ---
 
@@ -14,24 +14,24 @@ task file via `spur task create`.
 
 ## Argument Flags
 
-| Flag                                                                                 | Description                          | Default    |
-| ------------------------------------------------------------------------------------ | ------------------------------------ | ---------- |
-| `[<topic>]`                                                                          | Narrow the analysis to a topic.      | omitted    |
-| `--sessions` `<glob>`                                                                | Session log glob (fallback input).   | recent     |
-| `--source` `<auto\|omp\|claude\|codex\|gemini\|opencode\|antigravity\|openclaw\|pi>` | Agent source to scan.                | auto       |
-| `--feature` `<id>`                                                                   | Attach the generated task to a feature. | omitted |
-| `--template` `<meta\|issue\|standard>`                                               | Task template shape (`--create-task` only). | standard |
-| `--priority` `<P0\|P1\|P2\|P3>`                                                      | Filter / assign task priority.       | P2         |
-| `--severity` `<S0\|S1\|S2>`                                                          | Filter / assign severity.            | all        |
-| `--category` `<list>`                                                                | Comma list of categories to keep.    | all        |
-| `--since` `<iso>`                                                                    | Start of the scan window.            | configured |
-| `--until` `<iso>`                                                                    | End of the scan window.              | now        |
-| `--top` `<n>`                                                                        | Limit to top N findings.             | omitted    |
-| `--min-cost` `<duration>`                                                            | Minimum wasted duration to report.   | omitted    |
-| `--strict-topic`                                                                     | Drop findings off-topic.             | off        |
-| `--create-task`                                                                      | Generate a fix task for findings.    | off        |
-| `--agent` `<inline\|auto\|name>`                                                     | Who runs the model-bearing analysis. | omit       |
-| `--json`                                                                             | Emit structured JSON.                | off        |
+| Flag                                                                                                 | Description                                                                                                                   | Default    |
+| ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| `[<topic>]`                                                                                          | Narrow the analysis to a topic.                                                                                               | omitted    |
+| `--sessions` `<glob>`                                                                                | Session log glob (fallback input).                                                                                            | recent     |
+| `--source` `<auto\|pi\|claude\|codex\|gemini\|opencode\|antigravity\|openclaw\|omp\|grok\|agy\|all>` | Agent source to scan (CLI vocabulary; `all` fans out, `auto` resolves at runtime).                                            | auto       |
+| `--feature` `<id>`                                                                                   | Attach the generated task to a feature.                                                                                       | omitted    |
+| `--template` `<meta\|issue\|standard>`                                                               | Task template shape (`--create-task` only); `issue` is the explicit single-finding override, `standard` the generic override. | meta       |
+| `--priority` `<P0\|P1\|P2\|P3>`                                                                      | Filter / assign task priority.                                                                                                | P2         |
+| `--severity` `<S0\|S1\|S2>`                                                                          | Filter / assign severity.                                                                                                     | all        |
+| `--category` `<list>`                                                                                | Comma list of categories to keep.                                                                                             | all        |
+| `--since` `<iso>`                                                                                    | Start of the scan window.                                                                                                     | configured |
+| `--until` `<iso>`                                                                                    | End of the scan window.                                                                                                       | now        |
+| `--top` `<n>`                                                                                        | Limit to top N findings.                                                                                                      | omitted    |
+| `--min-cost` `<duration>`                                                                            | Minimum wasted duration to report.                                                                                            | omitted    |
+| `--strict-topic`                                                                                     | Drop findings off-topic.                                                                                                      | off        |
+| `--create-task`                                                                                      | Generate a fix task for findings.                                                                                             | off        |
+| `--agent` `<inline\|auto\|name>`                                                                     | Who runs the model-bearing analysis.                                                                                          | omit       |
+| `--json`                                                                                             | Emit structured JSON.                                                                                                         | off        |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -52,6 +52,11 @@ the history data plane is now the primary source (no flag needed), and the old r
 is the new default. Raw JSONL remains a fallback under the three conditions documented in
 `sp:issue-finding`.
 
+**Data-plane preflight.** Forensics read the imported history plane as-is. If findings come back
+empty or stale, run `/sp:dev-history-load` (on-demand cumulative `spur history import` + analyze,
+checkpoint resume — task 0567) before re-running forensics; it owns the interactive preflight, while
+`spur history daily` owns the periodic cadence.
+
 **See also:** skill `sp:issue-finding` (SSOT), `/sp:dev-runall`, `/sp:dev-dogfood`,
 `sp:daily-summary`, `sp:reverse-engineering`.
 

package/plugins/sp/commands/dev-find-next.md

@@ -1,5 +1,5 @@
 ---
-description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' with a ranked, evidence-carrying frontier, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' with a ranked, evidence-carrying frontier, and emits rank-distorting tree defects as proposals /sp:dev-feature-change consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
 role: planner
 argument-hint: "[--task [<feature-id>]] [--agent <inline|auto|name>] [--auto] [--json]"
 allowed-tools: ["Bash", "Read", "Write", "Grep", "Glob", "Skill"]
@@ -13,7 +13,7 @@ instead of ranking them, and emits tree structure defects as proposals only.
 
 Answers *"which X"* — the question `/sp:dev-next` deliberately does not (next-router routing-table
 §0 step 1c). Advancing a chosen target remains `/sp:dev-next`'s job; applying tree changes remains
-`/sp:dev-featurechange`'s job.
+`/sp:dev-feature-change`'s job.
 
 ## Argument Flags
 
@@ -55,7 +55,7 @@ Without `--task` the command is read-only with respect to the corpus and docs. U
 only mutation is the one the dispatched commands perform on `docs/tasks*/` after confirm (or
 auto-accept) — the command still performs no `spur feature move`, no sync apply, and no write under
 `docs/features/**`. Defect proposals conform to the `docs/plans/feature-tree-restructure-map.md`
-schema and are applied only through `/sp:dev-featurechange` (dry-run → confirm → apply).
+schema and are applied only through `/sp:dev-feature-change` (dry-run → confirm → apply).
 
 **See also:** skill `sp:next-feature` (SSOT), `sp:next-router` (`/sp:dev-next`),
 `sp:conflict-finding` (the prompt-first template), `sp:spur-cli`.