@gobing-ai/spur 0.3.48 → 0.3.49

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`.

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

@@ -1,15 +1,15 @@
 ---
-description: Get things done — quality gate → fix → act CI simulation → commit → push → gh verify in one flow
+description: Get things done — quality gate → fix → commit → push → gh verify in one flow (optional act CI simulation via --act)
 role: coder
-argument-hint: "[<quality-gate-command>] [--dry-run] [--skip-act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]"
+argument-hint: "[<quality-gate-command>] [--dry-run] [--act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]"
 allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob"]
 ---
 
 # Dev GTD
 
 Self-contained end-to-end delivery command: local quality gate (auto-fix via `/sp:dev-fixall`),
-local CI/CD simulation via `act`, conventional commit message generation, commit, push, and
-GitHub push-success verification via `gh`. Designed to stand alone (no backing skill); once mature
+optional local CI/CD simulation via `act` (`--act` only), conventional commit message generation,
+commit, push, and GitHub push-success verification via `gh`. Designed to stand alone (no backing skill); once mature
 it supersedes `/sp:dev-gitmsg` and is absorbed into the shared command structure.
 
 ## Argument Flags
@@ -18,7 +18,7 @@ it supersedes `/sp:dev-gitmsg` and is absorbed into the shared command structure
 | --- | --- | --- |
 | `<quality-gate-command>` | Local quality gate to run first; on failure, invoke `/sp:dev-fixall "<cmd>"` to fix all issues automatically. | `bun run check` |
 | `--dry-run` | Generate the git message and plan only — no commit, push, or gh verify. | off |
-| `--skip-act` | Skip the local `act` CI/CD simulation step. | off |
+| `--act` | Run local `act` CI/CD simulation before commit (heavy: launches Docker). Default off — stage 6 `gh` verify covers real CI post-push. Reach for it on workflow edits, dependency bumps, infra changes. Independent of `--dry-run`: `--dry-run --act` still runs the simulation. | off |
 | `--no-push` | Commit but do not git push or gh-verify. | off |
 | `--no-verify` | Push but skip the `gh` push-success verification. | off |
 | `--scope <path>` | Scope the commit-message diff analysis to a path. | all staged changes |
@@ -28,7 +28,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Usage
 
-/sp:dev-gtd [<quality-gate-command>] [--dry-run] [--skip-act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]
+/sp:dev-gtd [<quality-gate-command>] [--dry-run] [--act] [--no-push] [--no-verify] [--scope <path>] [--max-retry <n>]
 
 ## Implementation
 
@@ -41,8 +41,9 @@ default `bun run check`. Run it. If it exits non-zero, invoke `/sp:dev-fixall "<
 re-run the gate. Loop until the gate is clean or `--max-retry` is exhausted. Report what was fixed
 per file.
 
-**2 — Local CI/CD simulation via `act`.** Confirm Docker is running (`docker info`). On macOS the
-repo uses OrbStack — if the default context is not ready, use
+**2 — Local CI/CD simulation via `act` (opt-in).** Skip this stage entirely unless `--act` is
+given. When `--act` is given: confirm Docker is running (`docker info`). On macOS the repo uses
+OrbStack — if the default context is not ready, use
 `DOCKER_HOST=unix://$HOME/.orbstack/run/docker.sock`. Run
 `act -W .github/workflows/ci.yml -j verify` (or the repo's `bun run verify-gha-ci`); prefer
 `--container-architecture` matching your host when the runner pulls a foreign platform. If a step
@@ -57,10 +58,8 @@ If the build failure includes `TS2307: Cannot find module` on a workspace packag
 resolve Bun workspace packages because Bun does not create `node_modules/@scope/` symlinks.
 The real GitHub CI runner passes. **Do not** modify the build infrastructure to work around this
 `act`-specific issue. Instead, emit a clear message:
-`⚠ act CI simulation failed on workspace resolution — this is a container-environment artifact. Re-run with --skip-act to skip this step.`
-Then stop the run (this stage failed). The operator can use `--skip-act` to proceed.
-
-Skip this stage entirely when `--skip-act` is given.
+`⚠ act CI simulation failed on workspace resolution — this is a container-environment artifact. Re-run without --act to skip this step (it is opt-in).`
+Then stop the run (this stage failed). The operator can proceed by re-running without `--act`.
 
 **3 — Generate a conventional commit message.** Follow the gitmsg procedure (the same one
 `/sp:dev-gitmsg` runs). Run `git diff --cached --stat` (add `-- <path>` when `--scope` is given) for

package/plugins/sp/commands/dev-history-load.md

@@ -0,0 +1,63 @@
+---
+description: "On-demand cumulative history load + narrowed analyze: run spur history import (checkpoint-resume, additive) then spur history analyze, optionally narrowed to a session/task/window, with optional forensics render. Triggers: load history, import agent conversations, analyze my history, history for this conversation"
+role: scribe
+argument-hint: "[--source <name>] [--session <id>] [--task <wbs>] [--since <iso>] [--until <iso>] [--report] [--dry-run] [--json]"
+allowed-tools: ["Bash", "Read"]
+---
+
+# Dev History Load
+
+Runs the on-demand history load+analyze sequence: `spur history import` (all sources, checkpoint
+resume — additive and self-healing) then `spur history analyze`, with narrowing flags routed to the
+verb that accepts them. Wraps the shipped CLI sequence in one discoverable surface; owns no import
+logic, no state, and no cadence.
+
+## Argument Flags
+
+| Flag                 | Description                                                    | Default  |
+| -------------------- | -------------------------------------------------------------- | -------- |
+| `--source` `<name>`  | Agent source to import and analyze (both verbs).               | all      |
+| `--session` `<id>`   | Narrow the analyze to a single session id.                     | omitted  |
+| `--task` `<wbs>`     | Narrow the analyze to a single task WBS.                       | omitted  |
+| `--since` `<iso>`    | Inclusive lower bound on the analyze window.                   | omitted  |
+| `--until` `<iso>`    | Inclusive upper bound on the analyze window.                   | omitted  |
+| `--report`           | Render `spur history report --mode forensics` after analyze.   | off      |
+| `--dry-run`          | Preview the sequence; import scans without persisting.         | off      |
+| `--json`             | Emit one JSON result object; no banner text interleaved.       | off      |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-history-load
+/sp:dev-history-load --source omp --session <session-id>
+/sp:dev-history-load --task <wbs> --since 2026-08-01 --until 2026-08-15
+/sp:dev-history-load --report
+/sp:dev-history-load --dry-run
+/sp:dev-history-load --json
+```
+
+**Cumulative by checkpoint, not by this command.** Re-running imports only newly appended
+conversation data — the shipped import checkpoint resume (task 0470 R6) makes repeat runs additive
+and never double-counts. This command never prunes reports and never re-implements the daily
+pipeline; for the periodic cadence (import-all → analyze → artifact → 90-day prune, self-healing),
+run `spur history daily` instead.
+
+**Degraded sources proceed with a warning; fully-failed imports abort (0569).** `spur history
+import` distinguishes fatal from degraded fan-outs by exit code: **exit 1** (every source
+failed) aborts the sequence before analyze and propagates the exit code; **exit 2** (mixed —
+at least one source imported, some skipped malformed rows) proceeds to analyze with a loud
+per-source warning: stderr names each degraded source with its parse/validation error counts
+(human mode), and the `--json` payload carries a `warnings` array with the source, counts, and
+the import step's warning detail. A steady-state degraded source therefore no longer blocks a
+bare run; to scope around one deliberately, use `--source <name>` per source.
+
+## Implementation
+
+Run the load-then-analyze sequence per `plugins/sp/scripts/history-load.ts` — import first, analyze
+only after import exits 0, narrowing forwarded to `analyze` only:
+
+```
+bun plugins/sp/scripts/history-load.ts $ARGUMENTS
+```

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

@@ -0,0 +1,39 @@
+---
+description: "Review GitHub PRs with Codex; collect and fix findings."
+role: reviewer
+argument-hint: "[full|submit|collect|fix|rerun|status|rules] [--base <branch>] [--no-wait] [--agent <inline|auto|name>] [<focus>]"
+allowed-tools: ["Bash", "Read", "Skill"]
+---
+
+# Dev PR Review
+
+Wraps the **sp:pr-reviewing** skill. The review itself runs on the GitHub PR through Codex
+(`@codex review`) — never through a local Codex review mechanism; the invoking agent orchestrates
+and (in `fix` mode) implements.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<mode>` | `full\|submit\|collect\|fix\|rerun\|status\|rules` — full: request (deduped) + wait + report; submit: request and stop at pending; collect: report the latest review; fix: validate findings, fix legitimate ones, re-review; rerun: force a fresh review of the pushed HEAD; status: read-only composite; rules: author the repo's `AGENTS.md` `## Code Review Rules`. | full |
+| `--base` `<branch>` | Base branch when a new PR must be created. | existing PR base, else repo default |
+| `--no-wait` | Return pending right after the review request instead of polling. | off |
+| `--agent` `<inline\|auto\|name>` | Who performs model-bearing triage/fix. Omit uses the current agent, `inline` forbids dispatch, `auto` resolves the declared role, and a name pins that executor. This does not change the deterministic workflow/direct route. | omit |
+| `<focus>` | Remaining free text — extra review focus appended to the Codex request (e.g. `security boundaries and transaction idempotency`). | none |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-pr-review [full|submit|collect|fix|rerun|status|rules] [--base <branch>] [--no-wait] [--agent <inline|auto|name>] [review focus]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Delegate everything: `Skill(skill="sp:pr-reviewing", args="$ARGUMENTS")`. The skill owns mode
+  routing, finding triage, fix, and rules authoring; `.spur/workflows/pr-review.yaml` is the SSOT
+  for the review spine's state order and guards; the staged `pr-reviewing.ts` is the
+  deterministic git/gh core every spine step shells out to.
+- The external review goes through the GitHub PR and an `@codex review` comment only — never local
+  Codex review commands. Never force-push, rewrite history, merge the PR, or discard unrelated
+  changes; outside `fix` mode, ask before creating any commit.

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.48",
+    "version": "0.3.49",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -9,10 +9,12 @@ see_also:
 
 # Roles — the Layer-1 role-to-tier table
 
-The executor-selection contract is two layers. **Layer 1 (this file)** maps *role → tier* and is
-owned by plugin `sp`; **Layer 2** maps *tier → executor* and is owned by the operator in
-`.spur/config.yaml`. This file never names an executor, a model, or a vendor — it declares only
-what tier a role's work needs, and the operator's config decides which executor serves that tier.
+The executor-selection contract is two layers. **Layer 1 (this file)** projects *role → tier*;
+its SSOT is `DEFAULT_AGENT_ROLES` in `packages/config/src/index.ts` (task 0572 / ADR-061) — this
+file is the agent/human-facing view plus the plugin-owned command→role mapping. **Layer 2** maps
+*tier → executor* and is owned by the operator in `.spur/config.yaml`. This file never names an
+executor, a model, or a vendor — it declares only what tier a role's work needs, and the
+operator's config decides which executor serves that tier.
 
 The vocabulary is four roles, one per tier:
 
@@ -36,12 +38,17 @@ collapse, named as people so they stay addressable in `--agent`.
 
 ## The table
 
+<!-- PROJECTION (task 0572 / ADR-061): the tier/stages half of the block below is a generated view
+     of DEFAULT_AGENT_ROLES in packages/config/src/index.ts — edit that constant, not this file.
+     plugins/sp/tests/roles.test.ts (R9) fails the suite on any drift between the two. The
+     `commands:` half is plugin data (command frontmatter is its SSOT). -->
+
 ```yaml
 version: 1
 roles:
   - id: scribe
     tier: cheap
-    commands: [dev-gitmsg, dev-handover, dev-daily, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
+    commands: [dev-gitmsg, dev-handover, dev-daily, dev-history-load, dev-changelog, dev-refresh, rule-add, rule-refine, workflow-add, workflow-refine, spur-init]
     stages: [changelog]
   - id: coder
     tier: standard
@@ -49,11 +56,11 @@ roles:
     stages: [implement, test, wrap]
   - id: reviewer
     tier: capable-1
-    commands: [dev-verify, dev-verifyall, dev-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
+    commands: [dev-verify, dev-verifyall, dev-review, dev-pr-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2
-    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-arch, dev-refineall, dev-find-next, dev-featurechange]
+    commands: [dev-plan, dev-refine, dev-brainstorm, dev-idea, dev-runall, dev-parallel, dev-next, dev-arch, dev-refineall, dev-find-next, dev-feature-change]
     stages: [plan, refine, brainstorm]
 ```
 
@@ -81,13 +88,19 @@ must not sit below the highest `min_tier` among its folded stages.
   `refine`, `brainstorm`.
 
 **Placement notes (directory closure, task 0535).** The decided four-row table listed 31 commands;
-the live `plugins/sp/commands/` directory has 37. The six additional commands were placed by the
+the live `plugins/sp/commands/` directory has 39. The six additional commands were placed by the
 same stage logic: `dev-refineall` folds `refine` → planner; `dev-find-next` is planning-side
-frontier work → planner; `dev-featurechange` is planning-half corpus surgery on the feature tree →
+frontier work → planner; `dev-feature-change` is planning-half corpus surgery on the feature tree →
 planner; `dev-gtd` is the execution/delivery flow → coder; `dev-find-conflict` and `dev-find-issue`
-are audits/analysis → reviewer (same reasoning as `rule-scan`).
+are audits/analysis → reviewer (same reasoning as `rule-scan`). Later additions: `dev-history-load`
+is mechanical load+analyze orchestration → scribe; `dev-pr-review` is review orchestration —
+driving the external PR review and triaging its findings folds the `review` stage → reviewer.
 
 **Consistency is a test, not a convention.** `plugins/sp/tests/roles.test.ts` parses this YAML and
 asserts the tier-distinctness, command closure, stage-floor, and boundary invariants against the
-real command directory, the real stage registry, and the real operator config. When the table and
-the registry disagree, fix the table or the registry — never the test.
+real command directory, the real stage registry, and the real operator config — plus parity with
+`DEFAULT_AGENT_ROLES` (R9, 0572): the table above must equal the code SSOT byte-for-byte on
+id/tier/stages. When the table and the registry disagree, fix the table or the registry — never the
+test. When the table and `DEFAULT_AGENT_ROLES` disagree, fix the constant (or regenerate this view).
+A project may re-tier/re-stage a role at config time via `agent.roles` (closed vocabulary) — that
+override never flows back into this file.