@gobing-ai/spur 0.3.94 → 0.3.96

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

@@ -0,0 +1,83 @@
+---
+description: Find and fix failing GitHub Actions runs — gh fetch → diagnose → root-cause fix → commit → push → re-verify until green
+role: coder
+argument-hint: "[<context>] [--max-retry <n>] [--no-push]"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Grep", "Glob"]
+---
+
+# Dev Fixgha
+
+Self-contained all-in-one GitHub Actions repair loop (no backing skill): fetch failing runs with
+`gh`, diagnose each from its failed-step log, fix the root cause locally, commit, push, and watch the
+new runs — repeating until every in-scope workflow is green. Invoking this command is the operator's
+explicit request to edit `.github/workflows/` when the root cause lives there.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<context>` | Free-text context and/or search filter: a workflow name or file, run ID/URL, PR number, branch, job/step name, or a hint about the failure. Narrows which runs are in scope and seeds the diagnosis. | latest failing run per workflow on the current branch |
+| `--max-retry <n>` | Max fix → push → verify iterations before stopping with the remaining failures. | 3 |
+| `--no-push` | Fix and commit locally but do not push or re-verify on GitHub. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-fixgha [<context>] [--max-retry <n>] [--no-push]
+
+## Implementation
+
+Execute the stages below in order. Parse `gh` output with `--json` / `--jq`; never scrape tables.
+A stage that cannot succeed after `--max-retry` iterations stops the run with the specific failing
+output — do not silently skip a real failure.
+
+**1 — Preflight.** `gh auth status` must pass (otherwise stop and tell the operator to run
+`! gh auth login`). Resolve the repo (`gh repo view --json nameWithOwner`), the current branch, and
+`HEAD`. The working tree must be clean of unrelated changes (one writer per tree) — if it is not,
+stop and report instead of mixing them into CI-fix commits.
+
+**2 — Collect failing runs.** Build the in-scope set from `<context>`:
+
+- run ID / URL → that run (`gh run view <id> --json databaseId,workflowName,headBranch,headSha,conclusion,jobs,url`);
+- PR number → `gh pr checks <n> --json name,state,link,workflow` (failed checks only);
+- workflow name/file → `gh run list --workflow <wf> --branch <branch> --limit 10 --json databaseId,workflowName,headSha,status,conclusion,event,url`;
+- otherwise → `gh run list --branch <branch> --limit 30 --json …` and keep the **latest** run per
+  workflow whose `conclusion` is `failure`, `startup_failure`, or `timed_out`. An older failure
+  already superseded by a green run of the same workflow is out of scope.
+
+Free text that is not an identifier narrows by workflow/job/step name and is carried into diagnosis.
+If `actionlint` is on `PATH`, also run it over `.github/workflows/` and add its findings as
+static issues. Nothing failing and no static findings → report "all GitHub Actions green" and stop.
+
+**3 — Diagnose each failure.** Pull only the failing output: `gh run view <id> --log-failed`
+(bounded — keep the tail around the first error per failed step, not the whole log). Classify:
+
+| Class | Signal | Action |
+| --- | --- | --- |
+| Code | test / lint / typecheck / build error | Reproduce locally with the failing step's command, then fix the source. |
+| Workflow | YAML / expression error, bad action ref or deprecated version, missing `permissions`, wrong runner/tool version, cache/path mismatch | Fix the workflow file minimally. |
+| Environment | CI-only behavior (OS, root vs non-root, missing binary, timezone, case-sensitive FS) | Fix the code or workflow so both environments are correct — never weaken a correct test. |
+| Transient | network/registry timeout, runner outage, rate limit, no code/workflow cause | `gh run rerun <id> --failed` once; if it fails again, reclassify. |
+| External | missing/expired secret, repo setting, billing, third-party outage | Cannot be fixed from the tree — record and report for the operator. |
+
+**4 — Fix.** Root cause only, surgical diff. Forbidden shortcuts: `continue-on-error`, `if: false`,
+deleting or skipping jobs/steps/tests, loosening thresholds, `--no-verify`, force-push, and any edit
+to secrets. After fixing, run the local quality gate (`bun run check`, or the project's equivalent);
+if red, run `/sp:dev-fixall "<gate-command>"` before continuing.
+
+**5 — Commit.** Follow the gitmsg procedure in
+[dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg) to produce one
+conventional commit per iteration (typically `fix(ci): …` for workflow changes, or the owning
+`fix(<scope>): …` for code), whose body names the run IDs it addresses. Commit with the
+repository's hooks enabled.
+
+**6 — Push and re-verify.** Skip when `--no-push` (report the commits and stop). Otherwise
+`git push` (set upstream if missing; on rejection, pull `--rebase` then retry — never force). Find
+the runs for the pushed SHA (`gh run list --commit <sha> --json databaseId,workflowName,status,conclusion`;
+poll briefly — runs can take a few seconds to appear), then `gh run watch <id> --exit-status` for
+each in-scope workflow. Any new failure feeds back into stage 3. Stop when all in-scope workflows
+are green or `--max-retry` iterations are spent.
+
+**7 — Report.** One table: workflow · run ID · class · root cause · fix (`path:line`) · commit ·
+final status. List External/unfixed items separately with the exact operator action required.

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

@@ -1,5 +1,5 @@
 ---
-description: Generate conventional commit message(s) from the current change set via one bounded diff capture, optionally commit
+description: Generate conventional commit message(s) from the current change set via one bounded gather call, optionally commit
 role: scribe
 argument-hint: "[--commit] [--squash] [--all] [--scope <path>]"
 allowed-tools: ["Bash", "Read"]
@@ -28,8 +28,10 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg) (gitmsg).
 
-One diff capture per run — `-U0`, lockfiles excluded, 60 KB cap — is the token contract; never re-read
-the diff wider. Neither `--commit` nor `--squash` → messages only. `--commit` → one commit per concern, split automatically,
-so the operator is never asked to re-stage and re-run. `--squash` → one commit for everything.
-An empty index widens to the whole tree only on a message-only run, and says so; a committing run
-stops there and prints the exact `--all` re-run line instead of guessing.
+One gather call per run (per-file-capped `-U0` diff including untracked content, recent subjects for
+scope vocabulary, secret and partial-staging guards — git + shell only), then at most one commit call.
+Never re-read the diff wider. Neither `--commit` nor `--squash` → messages only. `--commit` → one
+commit per concern, split automatically, so the operator is never asked to re-stage and re-run.
+`--squash` → one commit for everything. An empty index widens to the whole tree only on a
+message-only run, and says so; a committing run stops there and prints the exact `--all` re-run line
+instead of guessing.

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

@@ -63,8 +63,8 @@ Then stop the run (this stage failed). The operator can proceed by re-running wi
 
 **3 — Generate a conventional commit message.** Follow the gitmsg procedure (the same one
 `/sp:dev-gitmsg` runs) — see
-[dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg): one bounded diff
-capture, concern grouping, conventional `<type>(<scope>): <summary>` formatting. Two deviations
+[dev-operations.md](../skills/spur-dev/references/dev-operations.md#9-gitmsg): one bounded gather
+call, concern grouping, conventional `<type>(<scope>): <summary>` formatting. Two deviations
 belong to this flow: read the change set with `--all` semantics (this stage commits everything the
 gate just proved green, not only what happens to be staged), and resolve multiple concerns to a
 **single combined message** (dominant type/scope, one body bullet per concern) so the push is

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

@@ -1,7 +1,7 @@
 ---
 description: Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create (Design by default), handoff
 role: planner
-argument-hint: "\"<idea>\" [--from-file <path>] [--auto] [--skip-design] [--approve-taste] [--agent <inline|auto|name>]"
+argument-hint: "\"<idea>\" | --from-file <path> [--skip-design] [--agent <inline|auto|name>] [--auto]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
@@ -16,29 +16,39 @@ contract below maps to that workflow's transitions.
 | --- | --- | --- |
 | `"<idea>"` | Vague idea to turn into a feature with AC and tasks. | required (or `--from-file`) |
 | `--from-file` `<path>` | Read the idea from a file instead of the positional argument. Mutually exclusive with `"<idea>"` — exactly one must be present. The file's contents become the verbatim idea text (trimmed of surrounding whitespace only). Useful for long or multiline asks that are awkward to quote. | off |
-| `--auto` | Skip objective HITL gates only (taste gates still pause). | off |
-| `--skip-design` | Omit system-design and per-task Design. | off |
-| `--approve-taste` | With `--auto`: set idea_approved + design_approved so idea-eval / design-approval do not pause. | off |
-| `--idea-approved` | Compatibility alias for idea_approved=true (subset of --approve-taste). | off |
-| `--design-approved` | Compatibility alias for design_approved=true (subset of --approve-taste). | off |
+| `--skip-design` | Omit system-design (and its approval gate) and per-task Design. | off |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. Omission and `inline` drive `idea-pipeline.yaml` in this session with zero external agent/workflow processes; `auto` tier-resolves an executor and a name pins one, both through the async workflow worker. | inline |
+| `--auto` | Accept the pipeline's recommendation at every operator gate (see below). | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
 ```
-/sp:dev-idea "<idea>"
-  [--auto]              # skip objective HITL only (feature-check, batch-create)
-  [--skip-design]       # design package off (system-design + task Design)
-  [--approve-taste]     # with --auto: skip idea-eval + design-approval pauses
+/sp:dev-idea "<idea>" | --from-file <path>
+  [--skip-design]                # design package off (system-design + task Design)
   [--agent <inline|auto|name>]   # inline is the current session; auto/name are async workers
+  [--auto]                       # no operator pauses; follow each gate's recommendation
 ```
 
 There is **no** `--design` force flag. Design is default-on; only `--skip-design` opts out.
 
-**Aliases (one-release / scripts):** `--idea-approved` and `--design-approved` still map into the same
-vars as subsets of `--approve-taste` (`idea_approved` / `design_approved`). Prefer `--approve-taste`.
+**Removed flags:** `--approve-taste`, `--idea-approved`, and `--design-approved` are folded into
+`--auto`. If passed, ignore them with a one-line notice; do not treat them as `--auto`.
+
+**Operator gates.** Every gate is asked as one `AskUserQuestion` [decision brief](../skills/spur-dev/references/decision-brief.md):
+the recommended option first, then options with their reasoning. The operator picks; they never
+type a yes/no. `--auto` takes the recommended option at each gate without asking.
+
+| Gate | Pauses when | Recommendation comes from | `--auto` takes |
+| --- | --- | --- | --- |
+| idea-eval | after discovery | eval report `## Recommendation` (`proceed` / `reshape` / `drop`) | `proceed`/`reshape` → continue; `drop` → cancel; missing → still asks |
+| feature-check | after AC | recorded AC check + requirement coverage | PASS → continue; FAIL → revise AC (cap 3) |
+| design-approval | after system-design (skipped by `--skip-design`) | recorded design check | PASS → approve; FAIL → still asks |
+| batch-create | after decompose | batch schema + task-order sidecar validation | create the batch |
+
+Flag → vars: `--auto` sets `profile=auto`, `idea_approved=true`, `design_approved=true`;
+`--skip-design` sets `design=skip`.
 
 ## Implementation
 

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

@@ -1,7 +1,7 @@
 ---
 description: Plan a feature from a description — intake → feature create → AC generation → feature check gate → decomposition → batch-create (Design by default)
 role: planner
-argument-hint: "\"<description>\" [--feature <id>] [--parent <feature-id>] [--agent <inline|auto|name>] [--skip-design] [--auto] [--approve-taste]"
+argument-hint: "\"<description>\" [--feature <id>] [--parent <feature-id>] [--skip-design] [--agent <inline|auto|name>] [--auto]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
@@ -18,8 +18,7 @@ Wraps the **sp:spur-dev** skill.
 | `--parent` `<feature-id>` | Create under a parent feature. | omitted |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing planning. Omission and `inline` drive `idea-pipeline.yaml` in this session with zero external agent/workflow processes; `auto` tier-resolves an executor and a name pins one, both through the async workflow worker. | inline |
 | `--skip-design` | Omit the system-design hop. | off |
-| `--auto` | Skip objective HITL gates. | off |
-| `--approve-taste` | With --auto: skip design-approval pause. | off |
+| `--auto` | Accept the pipeline's recommendation at every operator gate (same gate table as `/sp:dev-idea`). | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
@@ -27,18 +26,18 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ```
 /sp:dev-plan "<description>"
-  [--feature <id>] [--parent <feature-id>] [--agent <inline|auto|name>]
-  [--auto]              # skip objective HITL where the plan path supports it
-  [--skip-design]       # design package off (satellite + task Design)
-  [--approve-taste]     # with --auto: skip design-approval taste pause when applicable
+  [--feature <id>] [--parent <feature-id>]
+  [--skip-design]                # design package off (satellite + task Design)
+  [--agent <inline|auto|name>]
+  [--auto]                       # no operator pauses; follow each gate's recommendation
 ```
 
 **Design package (unified with `/sp:dev-idea`):** Design is **on by default**. Default fills
 per-task `### Design` in the batch and the feature satellite when the seam heuristic fires
 (ties lean **design**). There is **no** `--design` force flag — only **`--skip-design`** opts out.
 
-**Taste re-entry:** `--approve-taste` is the same flag as on `dev-idea` (sets prior design approval
-for taste gates). Alias: `--design-approved` (prefer `--approve-taste`).
+**Removed flags:** `--approve-taste` and `--design-approved` are folded into `--auto` (same
+contract as `/sp:dev-idea`). If passed, ignore them with a one-line notice.
 
 ## Implementation
 

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

@@ -1,8 +1,8 @@
 ---
-description: "Review code for a task or path — multi-dimensional review across functional traceability, SECUA quality, and architectural depth. With --triage: fix small findings directly, then file the rest as implement-ready tasks. Triggers: \"review this\", \"check the code\", \"SECUA review\", \"dev review\", \"audit this\", \"triage review findings\"."
+description: "Review code for a task set or paths — multi-dimensional review across functional traceability, SECUA quality, and architectural depth. With --triage: fix small findings directly, then file the rest as implement-ready tasks. Triggers: \"review this\", \"check the code\", \"SECUA review\", \"dev review\", \"audit this\", \"triage review findings\"."
 role: reviewer
-argument-hint: "[<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]]"
-allowed-tools: ["Bash", "Read", "Skill"]
+argument-hint: "[--tasks <selector> | --feature <id>[,<id>] | --scope <path>[,<path>]] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]] [--auto]"
+allowed-tools: ["Bash", "Read", "Skill", "Edit", "Write"]
 ---
 
 # Dev Review
@@ -13,19 +13,24 @@ Wraps the **sp:functional-review**, **sp:code-verification**, and **sp:code-impr
 
 | Flag | Description | Default |
 | --- | --- | --- |
-| `[<wbs\|path>]` | Task WBS or source path to review. | cwd |
+| `--tasks <selector>` | Review a task set — batch selector grammar ([execution-batch.md § Step 1](../skills/spur-dev/references/execution-batch.md#step-1--selector-resolution-r1)): comma WBS list or `feature:<id>`; status pseudo-lists and `ready` are rejected for review (they select work to do, not work to review). Resolved once, frozen; one WBS-mode review per task, each writing its own merged `## Review`; the run ends with a combined summary table (WBS, verdict, P1/P2 counts). | — |
+| `--feature <id>[,<id>]` | Sugar for the union of the `feature:<id>` sets — resolved once, frozen, then reviewed as `--tasks`. | — |
+| `--scope <path>[,<path>]` | Advisory review of the tracked files under one or more paths: paths must exist (exit 2 otherwise), are normalized, duplicates dropped and nested paths collapse to the ancestor (`--scope apps,apps/cli` → `apps`); one sub-review per path, one merged report with a cross-path architecture pass; no task mutation. | — |
+| `[<wbs\|path>]` | **Deprecated positional alias** (one release): a `^\d{4}$` token with a resolvable task → `--tasks <wbs>`; an existing path → `--scope <path>`; otherwise exit 2. Prints a deprecation warning naming the replacement. | — |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing review. | omit |
-| `--focus` `<dims>` | Review dimensions (functional / SECUA / architecture). | all |
-| `--triage` | After the review: fix small findings directly, file the rest as one or more implement-ready tasks. | off (report-only) |
-| `--worktree` `[<name>]` | Run the triage in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. Requires `--triage`. | off |
+| `--focus` `<dims>` | Review dimensions — vocabulary and skill routing: [code-verification/SKILL.md](../skills/code-verification/SKILL.md) review mode (SSOT). | all |
+| `--triage` | After the review: bucket findings across all targets once (identical `file:line` findings deduped), fix small findings directly, file the rest as one or more implement-ready tasks. | off (report-only) |
+| `--worktree` `[<name>]` | Run the triage in an isolated git worktree; FF-merge on success, retain on failure. Bare `--worktree` creates a fresh tree; `--worktree <name>` adopts an existing worktree by name/path/branch. Multi-target aware (below). Requires `--triage`. | off |
+| `--auto` | Skip objective HITL confirmations. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
 ```
-/sp:dev-review [<wbs|path>] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]]
-/sp:dev-review scripts --triage
+/sp:dev-review [--tasks <selector> | --feature <id>[,<id>] | --scope <path>[,<path>]] [--agent <inline|auto|name>] [--focus <dims>] [--triage] [--worktree [<name>]] [--auto]
+/sp:dev-review --tasks 0962,0963 --triage
+/sp:dev-review --scope apps,packages,plugins,scripts
 /sp:dev-review 0962 --triage --worktree
 ```
 
@@ -34,10 +39,14 @@ Put the target first: a bare token after `--worktree` is read as the worktree na
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
-- WBS mode (`<wbs>`): `Skill(skill="sp:functional-review", args="<wbs> $ARGUMENTS")` + `Skill(skill="sp:code-verification", args="review $ARGUMENTS")` + `Skill(skill="sp:code-improvement", args="<wbs> $ARGUMENTS")` (functional traceability + SECUA framework + architectural depth; the three skills return review fragments and the coordinator (`sp:super-reviewer`) writes the combined `## Review` — F92 0593 R1)
-- Path mode (`<path>`): `Skill(skill="sp:code-verification", args="review $ARGUMENTS")` + `Skill(skill="sp:code-improvement", args="<path> $ARGUMENTS")` (advisory SECUA quality + architectural depth; performs no task mutation)
-- `--triage`: after the review returns, run the triage protocol in [dev-operations.md § 2. review](../skills/spur-dev/references/dev-operations.md#2-review) **inline in this session** — the review skills and `sp:super-reviewer` stay report-only.
+- **Selector validation (before any review runs).** Exactly one target kind per invocation: `--tasks`, `--feature`, or `--scope`. More than one → exit 2 naming the conflicting selectors (a positional beside an explicit selector is a second target kind → exit 2); none (and no positional) → exit 2 with usage — there is no implicit `cwd` target. The set is resolved once and frozen through the [execution-batch.md § Step 1](../skills/spur-dev/references/execution-batch.md#step-1--selector-resolution-r1) batch resolver — no review-specific parser; `--feature <id>[,<id>]` is sugar for the union of the `feature:<id>` sets.
+- **WBS mode (per task target):** `Skill(skill="sp:functional-review", args="<wbs> $FLAGS")` + `Skill(skill="sp:code-verification", args="review <wbs> $FLAGS")` + `Skill(skill="sp:code-improvement", args="<wbs> $FLAGS")` (functional traceability + SECUA framework + architectural depth — each skill receives its one resolved WBS exactly once plus `$FLAGS` = `$ARGUMENTS` minus the selector (`--tasks`/`--feature`/`--scope` or positional) and its value, never the raw selector, and returns a review fragment only — F92 0593 R1)
+- **Task fan-out (`--tasks` / `--feature`).** One WBS-mode review per task in the frozen set. Tasks in `backlog`/`todo`/`blocked` are reported NOT-STARTED and skipped (§ 3a outcome vocabulary); a per-task failure does not stop the remaining tasks. Each implemented task gets its own merged `## Review`; the run ends with a combined summary table (WBS, verdict, P1/P2 counts).
+- Coordinator = this session. No `sp:super-reviewer` subagent is dispatched: act as the review coordinator defined in [agents/super-reviewer.md](../agents/super-reviewer.md) — merge the fragments per its Output Format (native `P1`–`P4` priority cells, section-relative headings) and, for every task target (standalone or pipeline), write that task's combined `## Review` via `spur task update <wbs> --section Review --from-file`. Path mode emits advisory output only.
+- **Path mode (per path target):** `Skill(skill="sp:code-verification", args="review <path> $FLAGS")` + `Skill(skill="sp:code-improvement", args="<path> $FLAGS")` (advisory SECUA quality + architectural depth — one normalized path forwarded once plus `$FLAGS`; performs no task mutation). Under `--scope <path>[,<path>]`: paths must exist (exit 2 otherwise), are normalized, duplicates dropped and nested paths collapse to the ancestor (`--scope apps,apps/cli` → `apps`); each surviving path gets a sub-review (Step 3p path scope), eligible for native-subagent dispatch per [dispatch-surface.md](../skills/parallel-execution/references/dispatch-surface.md); the coordinator merges the sub-reviews, runs **one** cross-path architecture pass (`sp:code-improvement` over the inter-path imports), and emits **one** advisory report. No task mutation.
+- **Positional alias (deprecated).** A positional `<wbs|path>` is accepted for one release: a `^\d{4}$` token with a resolvable task behaves as `--tasks <wbs>`; an existing path as `--scope <path>`; otherwise exit 2. Print a deprecation warning naming the replacement selector; removal is a follow-up.
+- `--triage`: after the review returns, run the triage protocol in [dev-operations.md § 2. review](../skills/spur-dev/references/dev-operations.md#2-review) **inline in this session** — the review skills and `sp:super-reviewer` stay report-only. With multiple targets, bucket the findings across all targets once (identical `file:line` findings deduped before bucketing). `Edit`/`Write` in `allowed-tools` exist only for these direct fixes.
 - Without `--worktree`, every write lands in the current working tree on the current branch: no branch creation, no checkout, no commit.
-- `--worktree [<name>]`: the [execution-batch.md § Worktree isolation](../skills/spur-dev/references/execution-batch.md#worktree-isolation---worktree-name) lifecycle as a run of one (marker `command` = `dev-review`, `selector` = the target). Rejected without `--triage`.
+- `--worktree [<name>]`: the [execution-batch.md § Worktree isolation](../skills/spur-dev/references/execution-batch.md#worktree-isolation---worktree-name) lifecycle as a run of one (marker `command` = `dev-review`, `selector` = the full normalized target list). Admission requires every target to resolve before the tree is cut. Branch slug: `sp/review-<first>-and-<N>-<short-id>` for a multi-target run (N = target count), `sp/review-<slug>-<short-id>` for a single target (the WBS or the path's basename). Rejected without `--triage`.
   While it runs, fixes and filed tasks land in the worktree copy; the main tree shows them only after the FF-merge.
 - `--fix`: Deprecated (still accepted: no-op + warning; route remediation to `--triage` or `/sp:dev-verify --fix`). **`--next` removed** (feature H8, 2026-07-31) — it was a deprecated no-op; route progression to `/sp:dev-next`. **was: `--next` deprecated no-op.**

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

@@ -40,10 +40,13 @@ See `sp:code-verification` § Shippable readiness gate.
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - `Skill(skill="sp:code-verification", args="verify $ARGUMENTS")`
-- **Residual sweep (F96 R1):** after the verify answer is written and `task verdict` derives
-  `.spur/run/<wbs>-verdict.json`, run `residual-scan scan` + `fold` (observe-only; folds the
-  verdict's `residual-sweep` check, PASS → PARTIAL when a blocking residual exists) — under every
-  `--fix` mode — before `spur task record`. Resolve the script via `superskill script path sp
+- **Residual sweep (F96 R1, post-record since 0987):** after `task verdict` derives
+  `.spur/run/<wbs>-verdict.json` and `spur task record` has flipped the verdict-proven R/AC boxes,
+  run `residual-scan scan` + `fold` (observe-only; folds the verdict's `residual-sweep` check,
+  PASS → PARTIAL when a blocking residual exists) — under every `--fix` mode — then, only on a
+  downgrade, re-run `spur task record <wbs> --verdict-file .spur/run/<wbs>-verdict.json` so Testing
+  carries the final verdict. Same order as the pipeline `record` state (0983): scanning before
+  record reads unticked-but-proven boxes and folds a clean PASS to PARTIAL. Resolve the script via `superskill script path sp
   residual-scan.mjs`; never reference `plugins/sp/scripts/` in shipped surfaces
   (script-contract-check rule 4). When the task reaches `done` through `--next`, run
   `residual-scan settle` (best-effort). On a folded PARTIAL: the bounded remediation loop has

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

@@ -49,7 +49,7 @@ the FF-merge on success. Expected, not a bug.
 
 **`--next` (per-task lifecycle chaining):** `--next`
 is chain-to-completion with propagation. For each task whose verdict is **PASS**, the chain's first
-hop transitions `testing → done` through the FSM with the `--strict-core` Review L3 guard honored;
+hop transitions `testing → done` through the FSM with the `--as done` Review L3 guard honored;
 a task whose verdict is **PARTIAL** or **FAIL** does **not** transition (it stays `testing` as
 review-pending) — that task's chain halts, reporting the verdict. One task's non-PASS never blocks
 another task's transition — each task's verdict is its own, and each task's chain is independent.
@@ -72,8 +72,9 @@ Without `--fix all`, shippable is not evaluated (optional note: use `--fix all`
 - Batch orchestration: `Skill(skill="sp:spur-dev", args="verifyall $ARGUMENTS")`
 - Per-task verification (inner): `Skill(skill="sp:code-verification", args="verify <wbs> $SHARED_FLAGS")`
 - Shippable gate: once after the batch (same skill § Shippable readiness gate)
-- **Residual sweep (F96 R1, per task):** same contract as `/sp:dev-verify` — after each task's
-  verdict artifact is derived, run `residual-scan scan` + `fold` (under every `--fix` mode) before
-  `spur task record`; on reaching `done` via `--next`, run `settle`. Script resolution:
+- **Residual sweep (F96 R1, per task, post-record since 0987):** same contract as
+  `/sp:dev-verify` — after each task's verdict artifact is derived and `spur task record` has
+  flipped its verdict-proven boxes, run `residual-scan scan` + `fold` (under every `--fix` mode),
+  and re-record only on a downgrade; on reaching `done` via `--next`, run `settle`. Script resolution:
   `superskill script path sp residual-scan.mjs` (never `plugins/sp/scripts/` —
   script-contract-check rule 4).

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

@@ -17,7 +17,7 @@ Wraps the **wrapup-pipeline.yaml** workflow.
 | `--agent` `<inline\|auto\|name>` | Who runs the wrap's model-bearing steps. Wrap is workflow-backed (headless): `omit` and `--agent inline` resolve identically per task 0687 — tier substitution under objective trigger 3 (durable auditable run record required) with a warning naming the substituted executor; `auto` tier-resolves an executor; a name pins that executor into `vars.agent`. | inline |
 | `--auto` | Skip objective HITL gates. | off |
 | `--merge` | Merge the wrap branch. | off |
-| `--dry-run` | Render the wrap without writing. | off |
+| `--dry-run` | Validate and walk transitions without executing actions. Conditional states therefore resolve to their declared failure edges (their guard files are never written), so a render ending in `failed` is **not** a run failure — it reports "this state's route cannot be decided without running it". Use a real run to preview a route. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 

package/plugins/sp/commands/spur-init.md

@@ -7,7 +7,7 @@ allowed-tools: ["Bash", "Read", "Write", "Skill"]
 
 # Spur Init
 
-Wraps **spur init** (deterministic scaffold) + **sp:doc-evolve** (project customization).
+Wraps **spur self init** (deterministic scaffold) + **sp:doc-evolve** (project customization).
 
 ## Usage
 
@@ -16,7 +16,7 @@ Wraps **spur init** (deterministic scaffold) + **sp:doc-evolve** (project custom
 ## Implementation
 
 ```bash
-spur init --json $ARGUMENTS
+spur self init --json $ARGUMENTS
 ```
 - Parse the JSON envelope once and retain it as `scaffoldResult`; summarize its created/skipped files in one block.
 - Customize (Phase 2): `Skill(skill="sp:doc-evolve", args="customize --project <scaffoldResult.project>")`.

package/plugins/sp/hooks/context-post-tool.ts

@@ -34,7 +34,7 @@ export const REDACTION_CAP_BYTES = 4096;
 /** Max command/pattern summary length before ellipsis (chars). */
 export const SUMMARY_MAX_CHARS = 200;
 
-interface ToolPayload {
+export interface ToolPayload {
     session_id?: string;
     tool_name?: string;
     tool_input?: {
@@ -115,7 +115,7 @@ export function redactText(text: string, capBytes: number = REDACTION_CAP_BYTES)
     if (bytes.length <= capBytes) return s;
     // Truncate on byte boundary then append marker
     let end = capBytes;
-    while (end > 0 && (bytes[end] & 0xc0) === 0x80) end--;
+    while (end > 0 && ((bytes[end] ?? 0) & 0xc0) === 0x80) end--;
     return `${new TextDecoder().decode(bytes.subarray(0, end))}…[truncated]`;
 }
 

package/plugins/sp/hooks/context-session-start.ts

@@ -126,6 +126,7 @@ export function recordSessionStart(
     dir: string,
     env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
+    agentFallback?: string,
 ): string | null {
     try {
         mkdirSync(dir, { recursive: true });
@@ -140,7 +141,7 @@ export function recordSessionStart(
     const pad = (n: number) => String(n).padStart(2, '0');
     const sessionId = `session-${at.toISOString().slice(0, 10)}-${pad(at.getHours())}${pad(at.getMinutes())}`;
     const ts = at.toISOString();
-    const agent = resolveAgentHint(env);
+    const agent = resolveAgentHint(env, agentFallback);
     const model = resolveModelHint(env);
 
     const sessionBody: Record<string, unknown> = {

package/plugins/sp/hooks/context-session-stop.ts

@@ -49,30 +49,30 @@ function computeSessionTotals(
     return { reads, writes, tokens };
 }
 
-function exitOk(): never {
-    process.exit(0);
-}
-
-async function main(): Promise<void> {
-    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
-
+/**
+ * Finalize one session (task 0969 R3): read the `.session.json` pointer, compute the session's
+ * rollup totals, append the `session_end` row, remove the pointer (best-effort) and return the
+ * event. Shared by this hook's entrypoint and Pi's `session_shutdown` so both hosts roll up
+ * identically. Returns null on every fail-open path.
+ */
+export function recordSessionEnd(dir: string, now: () => Date = () => new Date()): Record<string, unknown> | null {
     const sessionFile = join(dir, '.session.json');
-    if (!existsSync(sessionFile)) exitOk();
+    if (!existsSync(sessionFile)) return null;
 
     let sessionId = '';
     try {
         const session = JSON.parse(readFileSync(sessionFile, 'utf-8')) as { session?: string };
         sessionId = session.session ?? '';
     } catch {
-        exitOk();
+        return null;
     }
 
-    if (!sessionId) exitOk();
+    if (!sessionId) return null;
 
     const totals = computeSessionTotals(join(dir, 'token-ledger.jsonl'), sessionId);
 
     const event = {
-        ts: new Date().toISOString(),
+        ts: now().toISOString(),
         session: sessionId,
         type: 'session_end' as const,
         totals,
@@ -81,7 +81,7 @@ async function main(): Promise<void> {
     try {
         appendFileSync(join(dir, 'token-ledger.jsonl'), `${JSON.stringify(event)}\n`);
     } catch {
-        exitOk();
+        return null;
     }
 
     try {
@@ -90,7 +90,15 @@ async function main(): Promise<void> {
         // cleanup is best-effort
     }
 
-    exitOk();
+    return event;
 }
 
-void main().catch(exitOk);
+// Entrypoint: run the shared core, then exit 0 (fail-open) as this hook always has.
+if (import.meta.main) {
+    try {
+        recordSessionEnd(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
+    } catch {
+        /* fail-open: every error path exits 0 */
+    }
+    process.exit(0);
+}