@gobing-ai/spur 0.4.8 → 0.4.9

package/plugins/sp/README.md

@@ -272,16 +272,16 @@ plugins/sp/
 │   └── wayfinder/                   # Multi-session investigation maps (SKILL.md only)
 ├── commands/                        # Slash-command wrappers — the SSOT (hand-editable thin wrappers; see Commands below)
 ├── agents/                          # 4 specialist subagents (expert-spur, super-coder, super-planner, super-reviewer)
-├── hooks/                           # hooks.json + one thin entry per registered identity
-│                                    # + task-write-guard.ts (compat shim) + careful-guard.ts (opt-in, unwired)
-│                                    # + pi/guard-extension.ts (plugin.json `extensions.pi` entry point)
-│                                    # entries delegate to lib cores (task 1174); hook suites live in tests/hooks/
+├── hooks/                           # hooks.json (the registry) only — Pi runs it through superskill's native Pi adapter
+│                                    # — no hook entries here; see scripts/hooks/ (superskill ADR-039)
 ├── lib/                             # Handwritten plugin cores — context-{post-tool,session-start,session-stop}.ts,
 │                                    # agent-hint.ts, context-owner.ts, destructive-policy.ts, task-file-policy.ts,
-│                                    # env.ts, plus generated *.generated.mjs|.d.mts bundles over packages/app
-├── scripts/                         # Executable helpers, split from prompts (ADR-031) — batch-preflight.ts + scripts/<skill>/
-│                                    # (daily-summary: daily-summary.ts; dogfood-testing: {detect-pipeline-driving, validate-report}.ts)
-├── tests/                           # Plugin tests — skill-structure.test.ts + hooks/ (guard, context, Pi suites)
+│                                    # env.ts (no generated bundles: script absorption retired them)
+├── scripts/                         # Hook entries only (script absorption complete, task 1213 —
+│                                    # no script-root, no .mjs twins, no manifest)
+│   └── hooks/                       # One entry per hook identity, run by `superskill hook run sp <id>`;
+│                                    # entries delegate to lib cores; suites live in tests/hooks/
+├── tests/                           # Plugin tests — skill-structure.test.ts + hooks/ (guard, context, lifecycle suites)
 │                                    # + evals/ (behavioral eval corpus + judge; see tests/evals/README.md,
 │                                    # runner at scripts/commands/skill-eval.ts) + per-skill suites
 ├── plugin.json                      # Marketplace entry
@@ -348,7 +348,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `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`             |
 | `fleet-join`                | 1.0   | Guest fleet occupancy — join as a live guest occupant, loop `spur agent wait --inbox` to pull work, reply through `spur message reply`, then leave; G73 (task 1081)                                                                          |
 | `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`     |
+| `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` + `spur builder pr`; 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                                                                        |
 | `history-anatomy`           | 1.0   | Diagnostic interpretation owner over already-imported history — daily/ad-hoc mode contract, closed finding taxonomy, twelve-section report contract, `enrich`/`validate` rubrics; no workflow launch, no JSONL fallback, no corpus mutation                                                                   |
 | `session-review`            | 1.1   | Inline review of the active coding-agent session — compact outcomes, evidence-backed resolved/open issue classification, proposal-only improvements, and next actions; no workflow, import, delegation, or mutation                                                                                           |
@@ -411,14 +411,10 @@ hand-editable source for the operator command surface. Per-platform adapters are
 output** owned by `superskill` (`superskill install sp`) and never committed here. Plugin `sp` ships
 no per-platform artifacts — only the platform-independent thin wrappers.
 
-**Install-time `lib/` ownership (1120).** Staging and refreshing the plugin's sibling
-`lib/inline-run.generated.mjs` app bundle into the shared scripts root is `superskill`'s install
-contract (superskill commit `b42961b`, first release after 0.3.35): spur ships the bundle, superskill
-places it. The inline scripts carry a skew guard for the window where the installed bundle is older
-than its scripts (e.g. superskill ≤ 0.3.35): they fail with a named version-skew error — bundle
-path, missing exports, and both remedies — instead of an `is not a function` TypeError. Until a
-superskill release containing `b42961b` is installed and `sp` reinstalled, pass
-`--spur-bin <spur checkout>/apps/cli/src/index.ts`.
+**No install-time app bundle.** The plugin used to ship a `lib/inline-run.generated.mjs` app bundle
+that `superskill` staged beside the scripts (1120). Script absorption (PR-4..PR-6) moved every
+consumer onto `spur <noun> <verb>`, so the bundle and its skew guard are gone: the skills call the
+installed `spur` CLI directly.
 
 **Thin-wrapper contract** is enforced by `scripts/commands/validate-commands.ts`:
 
@@ -487,11 +483,12 @@ the agent provides an isolated context window.
 #### 4. Hooks (`hooks/`)
 
 Event-driven enforcement that runs automatically without user invocation. `hooks.json` registers
-six handlers across seven events:
+seven handlers across seven events:
 
 | Event          | Matcher                               | Handler                                        | Timeout |
 | -------------- | ------------------------------------- | ---------------------------------------------- | ------- |
 | `PreToolUse`   | `Write\|Edit`                         | `superskill hook run sp task-write-guard`      | 10s     |
+| `PreToolUse`   | `Bash`                                | `superskill hook run sp careful-guard`         | 10s     |
 | `PostToolUse`  | `Bash\|Grep\|Glob\|Read\|Write\|Edit` | `superskill hook run sp context-post-tool`     | 10s     |
 | `SessionStart` | —                                     | `superskill hook run sp context-session-start` | 15s     |
 | `SessionStart`, `UserPromptSubmit`, `Stop` | —         | `superskill hook run sp agent-lifecycle`       | 5s      |
@@ -515,14 +512,58 @@ hint on first launch, and `context-session-stop` closes out the session record.
 `SPUR_SPEC_ID` is set, so outside a fleet it makes no call. `fleet-guest-stop` delivers pending
 inbox work to a session joined as a fleet guest at turn end; any other session passes through.
 
-**Available but unwired:** `careful-guard.ts` ships in `hooks/` (its suite is
-`tests/hooks/careful-guard.test.ts`) as an opt-in `PreToolUse` guard that asks before destructive
-shell commands (`rm -rf`, `DROP TABLE`,
-`git push --force`, …) — it is **not** registered in `hooks.json`. Fail-open by contract; escape
-hatch `SPUR_CAREFUL=off`.
+**Destructive-command guard.** `careful-guard` (task 0215 R3) fires on every `Bash` tool call and
+asks the operator to confirm destructive shell commands (`rm -rf`, `DROP TABLE`, `git push --force`,
+…); rebuildable caches (`rm -rf node_modules`, `dist`, …) pass. The policy is
+`lib/destructive-policy.ts`. On Pi, superskill's native adapter routes the `ask` to `ctx.ui.confirm`
+(and blocks when Pi has no UI). Hosts that cannot confirm (Codex, omp, generic) deny an
+unconfirmable `ask` with the reason. Malformed input and runner errors still fail open; escape hatch
+`SPUR_CAREFUL=off`.
+
+**Runtime contract (superskill ADR-039).** `superskill hook run sp <id>` runs the plugin's own
+`scripts/hooks/<id>.ts` under Bun with the canonical payload on stdin. An allow prints **nothing**
+(a printed Claude `permissionDecision:"allow"` would bypass the user's permission rules). A
+block/ask prints one JSON object that superskill renders per host:
+
+- `fleet-guest-stop` prints the host-neutral `{"decision":"block","reason"}`.
+- The two `PreToolUse` guards print Claude-native JSON with the reason in both
+  `permissionDecisionReason` and `systemMessage`. On Codex/omp, `hook run` turns a deny into exit 2
+  with that reason on stderr, and an unconfirmable ask becomes the same fail-closed denial. They stay Claude-native because the neutral form cannot carry
+  `systemMessage`, Claude Code's user-facing warning.
+
+**Why `scripts/hooks/` (one canonical location).** superskill resolves `hooks/<id>` first, then
+`scripts/hooks/<id>`, under every plugin root. But install delivers different trees to different
+targets:
+
+- Codex, OpenCode, Antigravity and Hermes get only `scripts/`, staged as
+  `.agents/scripts/sp/`, with `lib/` beside it as `.agents/scripts/lib/`.
+- Native targets (Claude Code, omp, Grok) get the whole plugin.
+
+So `scripts/hooks/<id>.ts`, importing `../../lib/…`, is the only path that resolves the same way on
+every target. `hooks/` keeps the registry only. `script-contract-check`
+rejects a hook entry there: on native installs it would shadow the staged one, and staged targets
+would never receive it. Hook logic stays in the plugin (Revision 2026-10-15); the files are entries
+and lib cores, not `spur` commands.
 
 **Escape hatch:** `SPUR_WRITE_GUARD=off` short-circuits the write guard before any subprocess.
 
+**Pi.** The plugin ships no Pi-specific extension any more: the former
+`hooks/pi/guard-extension.ts` (declared through `plugin.json` `extensions.pi`) is retired. Pi gets
+the same seven `hooks.json` hooks as every other host, through superskill's **native Pi hook
+adapter** (superskill PR #4, ADR-039): `superskill install` generates one Pi extension module per
+declared hook, each running `superskill hook run sp <id>` with `SUPERSKILL_HOOK_HOST=pi`, and
+applies the decision with Pi's primitives — `{block}` for deny, `ctx.ui.confirm` for `ask`, a
+follow-up message for a Stop `block`. Requirements:
+
+- **Superskill 0.3.39 or newer** for the native Pi adapter and staged-hook timeout metadata.
+  Older installs may retain the `@vahor/pi-hooks` shim or omit hook-specific timeout budgets.
+- **A reinstall to Pi and omp** after upgrading: `superskill install sp --targets pi,omp`. Reinstall
+  removes the old `sp` extension package and any shim entries, so a hook never runs twice. An
+  existing Pi install keeps the retired extension until it is reinstalled.
+
+**Spur CLI requirement:** sp requires Spur 0.5.0 or newer on PATH. The script absorption is a clean break;
+older CLI versions do not provide the absorbed commands.
+
 #### 5. Scripts (`scripts/` + `hooks/`)
 
 Executable TypeScript that implements hook enforcement logic and deterministic helpers. Scripts are
@@ -532,20 +573,12 @@ hold `SKILL.md` and prompt-side companions only.
 
 | Script                                               | Role                                                                                                                                                                                                                                                                                              |
 | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `hooks/task-write-guard.ts`                          | Compatibility shim for older installs that still execute the script path directly. Forwards stdin to the stable PATH command `superskill hook run sp task-write-guard`, mirrors parseable PreToolUse decisions, and fails open if the runtime is unavailable. Performs no source-tree CLI lookup. |
-| `hooks/context-*.ts`                                 | argv/stdin entries for the three registered context hooks; the capture, ledger and session logic is the `lib/context-*.ts` core (task 1174)                                                                                                                                                        |
-| `hooks/{agent-lifecycle,fleet-guest-stop}.ts`       | Fleet hooks (1080/1081): member lifecycle reports via `spur agent report`; turn-end inbox delivery to joined guests |
-| `hooks/careful-guard.ts`                             | Opt-in destructive-command guard (unwired — see Hooks above); policy is `lib/destructive-policy.ts`                                                                                                                                                                                                |
+| `scripts/hooks/task-write-guard.ts`                  | PreToolUse `Write\|Edit` guard: denies raw edits of task-corpus files (ownership from `spur task resolve --strict`), silent on allow, fail-open on every error path |
+| `scripts/hooks/context-*.ts`                                 | argv/stdin entries for the three registered context hooks; the capture, ledger and session logic is the `lib/context-*.ts` core (task 1174)                                                                                                                                                        |
+| `scripts/hooks/{agent-lifecycle,fleet-guest-stop}.ts` | Fleet hooks (1080/1081): member lifecycle reports via `spur agent report`; turn-end inbox delivery to joined guests |
+| `scripts/hooks/careful-guard.ts`                     | PreToolUse `Bash` destructive-command confirm (see Hooks above); policy is `lib/destructive-policy.ts`                                                                                                                                                                                                |
 | `lib/context-{post-tool,session-start,session-stop}.ts` | Redaction-capped ledger append, session open/ownership and owner-gated teardown for `sp:indexed-context`                                                                                                                                                                                       |
 | `lib/{agent-hint,context-owner,destructive-policy,task-file-policy}.ts` | Shared hook cores — agent/model hint resolution, host-native session owner derivation, destructive-command classification, task-file matching                                                                                                                              |
-| `scripts/batch-preflight.ts`                         | Pure TABLE A STOP evaluation for `super-planner` — skip doomed pipeline launches without spawning a Skill subprocess; recovery hints map stuck statuses to a single `/sp:dev-*` hop                                                                                                               |
-| `scripts/workflow-step-profile.ts`                   | Thin glue over the generated lib bundle (`lib/step-profile.generated.mjs` from `packages/app/src/workflow/step-profile.ts`) — read-only step profile from `spur workflow trace`: per node and action-kind durations, idle gaps, session mode and `cacheHit` coverage, plus the ADR-115 cache-window flags `sp:spur-doctor` turns into workflow-optimization proposals |
-| `scripts/dogfood-testing/detect-pipeline-driving.ts` | Live Phase 1.0 CLI gate over `lib/dogfood-pipeline.ts` — word-boundary detector for pipeline-driving testees (leading-space invariant)                                                                                                                                  |
-| `scripts/dogfood-testing/validate-report.ts`         | CLI entry over `lib/dogfood-report.ts` — pure `validateReport(md)`, footer-mandatory + 7-check finalize-or-abort contract with stable error codes                                                                                                                |
-| `scripts/daily-summary/daily-summary.ts`               | ccusage + git-history orchestration helpers for `sp:daily-summary`, with its own console toggle                                                                                                                                                                                                  |
-| `scripts/task-diffstat.ts`                           | 0943 triage-lane diffstat producer — numstat + untracked scan vs the run base; writes `<wbs>-diffstat.json` with the sensitive-path flag; fails safe (sensitive)                                                       |
-| `scripts/run-summary.ts`                             | Measured execution summary `/sp:dev-run` / `/sp:dev-runall` print by default (`--no-summary` skips) — windows the host transcript by `spur workflow progress` attempt timestamps; per stage/run time, wait, tool calls, total / non-cached tokens; `n/a` for subprocess windows |
-| `scripts/session-timeline.ts`                        | Measured Time/Wait/Token evidence for `sp:session-review` — reads the active Claude Code transcript read-only, one segment per operator prompt, usage deduplicated by message id, tokens split total / non-cached; `{available:false}` exit 0 when no transcript |
 | `scripts/commands/validate-flag-contracts.ts`        | Mechanical consistency gate — compares flag claims across command files, flag-glossary, cross-cutting, dev-operations, and ADR; reports disagreements                                                                                    |
 | `*.test.ts`                                          | Unit suites — `tests/hooks/` for the hook entries and their lib cores, `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                        |
 
@@ -580,7 +613,7 @@ graph TB
 
     subgraph "Execution layer"
         CLI["spur CLI<br/>task · feature · rule · workflow<br/>· agent · history · message"]
-        SCRIPT["hooks/task-write-guard.ts"]
+        SCRIPT["scripts/hooks/task-write-guard.ts"]
     end
 
     subgraph "Corpus layer"
@@ -695,7 +728,7 @@ root codex/opencode use in global mode.
 | `skills/*.md`      | `~/.claude/skills/`                      | Adapted as Skills 2.0 skill directories — all platforms receive skills uniformly                |
 | `commands/*.md`    | `~/.claude/commands/`                    | Adapted as Skills 2.0 skill entries (`disable-model-invocation: true`)                          |
 | `agents/*.md`      | `~/.claude/agents/`                      | Adapted as Skills 2.0 skill entries (model-invocable); Pi additionally gets native agent format |
-| `hooks/hooks.json` | `~/.claude/hooks/`                       | Converted to target-native format (pi-hooks shim for pi/omp, HOOK.yaml for hermes)              |
+| `hooks/hooks.json` | `~/.claude/hooks/`                       | Converted to target-native format (generated native extensions for pi, pi-hooks shim for omp, HOOK.yaml for hermes) |
 | `hooks/*.ts`       | plugin hook runtime / compatibility copy | Copied alongside platform output only for environments that still invoke script paths directly  |
 
 Each skill declares its own platform support in `metadata.platforms` frontmatter.

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

@@ -35,7 +35,7 @@ task runs and frames the work above them.
 You are the **batch driver**. You run the loop documented in
 **[references/execution-batch.md](../skills/spur-dev/references/execution-batch.md)** - resolve the
 task set from the selector, freeze it, topologically order by dependencies, **preflight** each WBS
-against TABLE A STOP rows (via `sp:next-router` / `plugins/sp/scripts/batch-preflight.ts`), run each
+against TABLE A STOP rows (via `sp:next-router` / `spur task preflight`), run each
 ready task through the standard single-task pipeline, inspect each terminal verdict, optional
 **one-shot recovery** hop, decide continue/halt, and emit a structured batch report.
 
@@ -75,13 +75,13 @@ You own the spaces **between** task runs:
 - **Topologically order** the frozen set by `dependencies[]` (Step 2). Abort on cycle; pre-block
   unmet out-of-set deps.
 - **Preflight (Step 2.5 / 3.0)** - before each pipeline launch, evaluate TABLE A STOP rows
-  (`batch-preflight.ts` or equivalent). Skip A2/A7/A8/A9; still **launch `task-pipeline.yaml`** for
+  (`spur task preflight` or equivalent). Skip A2/A7/A8/A9; still **launch `task-pipeline.yaml`** for
   ready WBS (never substitute a `dev-next` loop for the happy path).
 - **Run each ready task** through `task-pipeline.yaml` via `spur workflow run --async`
   (Step 3). The command/script layer polls `spur workflow trace` to terminal state - polling is
   transport, not planner reasoning (R3: the poll loop must not live in this agent's body; the planner
   inspects the terminal verdict, not the poll iterations). Follow the
-  `plugins/sp/scripts/batch-preflight.ts` precedent for scripted transport.
+  `spur task preflight` precedent for scripted transport.
 - **Parallelize only when requested** by applying `sp:parallel-execution` to a proven-independent
   subset (Step 3 optional path). Serialize when dependency, file-overlap, or budget checks fail.
   Preflight still runs per WBS before fan-out; recovery stays sequential.
@@ -156,14 +156,14 @@ When you fan out or dispatch a subagent, apply the four disciplines the SSOT
 - [ ] Drive the loop in execution-batch.md - resolve -> freeze -> order -> **preflight** -> run -> inspect
       -> optional recovery -> decide -> report.
 - [ ] **Preflight** each WBS before `workflow run` using
-      `node "$(superskill script path sp batch-preflight.mjs)"` (or the pure `preflightTask` helper) with
+      `spur task preflight <wbs>` (or the pure `preflightTask` helper) with
       `spur task show --json` deps. On `action: skip` (A2/A7/A8/A9), do **not** start the pipeline;
       record skip in the batch report with the reason string.
 - [ ] Launch each **ready** per-task pipeline with `--async`. The command/script layer polls
       `spur workflow trace` to terminal state - this is transport, not planner reasoning (R3). A
       pipeline with `agent.run` stages runs for many minutes; the planner inspects the terminal
       verdict + `.spur/run/<wbs>-verdict.json`, never the poll iterations. Synchronous invocation
-      risks orphaned runs; follow the `batch-preflight.ts` precedent for scripted transport.
+      risks orphaned runs; follow the `spur task preflight` precedent for scripted transport.
 - [ ] Forward `--auto` and `--agent` into each per-task `--vars` and nothing else.
 - [ ] Freeze the set at kickoff; never re-query `spur task list` to recompute membership mid-batch.
 - [ ] Abort the whole batch on a dependency cycle before running any task.

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

@@ -182,7 +182,7 @@ the cell, not the sentence. `OPEN` states "still live", and `ACCEPTED` marks a n
 observation you are deliberately not acting on; both behave as an ordinary open row.
 
 **Pipeline cost of an open finding (1122).** The review PASS edges run this same classification
-before verify (`residual-scan review-gate`): a PASS whose table still carries an open P1-P3 row
+before verify (`spur task residual <wbs> review-gate`): a PASS whose table still carries an open P1-P3 row
 routes into `review-fail-triage` → the bounded repair hop instead of verify. Open P1-P3 findings
 block `done`; fixing one invalidates the certified digest and re-runs quality → review → verify on
 a fresh digest. Only P4 rows and `DEFER`-ed P3 rows are wrap residuals — disposition the finding in
@@ -247,7 +247,7 @@ assert no external claim and need no citation. An uncited external claim is an a
 as an explicit gap in the report body (above), so a reader can re-check it.
 
 
-**Machine-checked at the gate (findings table).** `residual-scan review-gate` applies the same two
+**Machine-checked at the gate (findings table).** `spur task residual <wbs> review-gate` applies the same two
 predicates to every finding row: a Finding cell carrying one of the verify lint's claim markers with
 no citation form becomes a **blocking** `review-contract` item, so `review → verify` stops and the
 run enters `review-fail-triage`. The `Location` column is deliberately not consulted as a citation —

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

@@ -26,5 +26,5 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Implementation
 
-Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#8-changelog) (changelog). This is a docs-only generator: run no quality gates (`bun run gate`, lint, typecheck, tests, `spur-check`, rules) — a generic "verify before finishing" rule does not apply here. The generator's own claim-verification pass (dev-operations §8, step 7: API/library claims get `<!-- src: … · HIGH|MEDIUM|LOW -->` citations) is part of the procedure, not a gate.
+Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#8-changelog) (changelog). This is a docs-only generator: run no quality gates (`bun run gate`, lint, typecheck, tests, `spur-check`, rules) — a generic "verify before finishing" rule does not apply here. The generator's own claim-verification pass is part of the procedure, not a gate, and carries two required checks per claim bullet (dev-operations §8, step 7): a **source citation** — an anchor naming a URL or a repo `path:line` — and a **confidence level**, exactly one of `HIGH`, `MEDIUM`, `LOW`, both held in the bullet's `<!-- src: … · <level> -->` comment and re-verified by step 8's self-check.
 

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

@@ -27,4 +27,4 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Implementation
 
-Run the generator per [daily-summary/SKILL.md](../skills/daily-summary/SKILL.md): `node "$(superskill script path sp daily-summary/daily-summary.mjs)" $ARGUMENTS`.
+Run the generator per [daily-summary/SKILL.md](../skills/daily-summary/SKILL.md): `spur history summary $ARGUMENTS`.

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

@@ -32,7 +32,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 - 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; `pr-review.yaml` is the SSOT
-  for the review spine's state order and guards; the staged `pr-reviewing.ts` is the
+  for the review spine's state order and guards; `spur builder pr` 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

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

@@ -15,7 +15,7 @@ documentation work and one-to-two-line fixes) inline and files everything remain
 implement-ready tasks for further fixing; `--triage` is an alias of `--fix auto`. With `--fix all`,
 it defers nothing: every actionable finding is fixed inline and no task is filed. The result includes a non-overlapping time breakdown —
 work time, operator wait, tool calls and tokens (total / non-cached) per stage, measured from the host transcript by
-`session-timeline.mjs` — with durations in `M:SS` or `H:MM:SS` form and `n/a` only when that
+`spur history timeline` — with durations in `M:SS` or `H:MM:SS` form and `n/a` only when that
 measurement is unavailable. The transcript resolves from `--transcript`, else
 `CLAUDE_CODE_SESSION_ID`, else `PI_SESSION_FILE` (the pi host sets it and no Claude session id); a
 pi `<skill name="…">` wrapper row is the operator's `/skill` invocation and opens a segment

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

@@ -42,7 +42,7 @@ feature-derived, `dev-runall` runs `spur feature check <id> --fix --json` then `
 resolving tasks — a non-zero strict check aborts the batch with verdict `aborted` and the
 structured findings, before any task pipeline action, task 0510 R2; scoped: `L4.scenario-unverified` and `L4.verifying-incomplete-tasks`
 (expected pre-run states of a not-yet-run or reopened feature) are reported verbatim but do not abort (the non-aborting set is
-`NON_ABORTING_PREFLIGHT_CODES` in `plugins/sp/scripts/batch-preflight.ts`; `--fix` repairs land in the report's `autoRepairs`) —
+`NON_ABORTING_PREFLIGHT_CODES` behind `spur task preflight --classify-feature`; `--fix` repairs land in the report's `autoRepairs`) —
 any other strict error aborts), `--mode`
 `<sequential|parallel|auto>` (default `sequential`; `parallel` fans out a proven-independent subset —
 see `execution-parallel-isolation.md`; `auto` picks one per batch — see below), `--concurrency <n>`
@@ -63,7 +63,7 @@ creates a fresh tree, `<name>` form adopts an existing worktree by name/path/bra
 `execution-worktree-setup.md` + `execution-worktree-landing.md`).
 
 **`--mode auto` (smart scheduling).** Ordering is always dependency-correct — every mode
-topo-sorts the frozen set with `batch-plan.mjs order` (deterministic, never hand-sorted). `auto`
+topo-sorts the frozen set with `spur task batch-plan order` (deterministic, never hand-sorted). `auto`
 additionally reads that schedule's dependency waves (tasks declaring the same file are serialized)
 and decides once, before the first task: `parallel` when some wave holds ≥2 independent tasks and
 `--concurrency` ≥2; otherwise `sequential` in the host session. `--worktree` or explicit
@@ -101,8 +101,8 @@ full distinction.
 
 - **Bootstrap reads (1128):** before the first dispatch, read [SKILL.md § Bootstrap reads](../skills/spur-dev/SKILL.md#bootstrap-reads) and load only that mode's files — the section whose trigger has not fired is on demand.
 - **Publish the visible batch plan first (1105):** publish `A Prepare batch` (A1–A4) and `Z Batch
-  report` before the first task, then one letter per task from `batch-plan.mjs waves` after
-  freeze/order and digit children from `batch-plan.mjs task-children` at task start —
+  report` before the first task, then one letter per task from `spur task batch-plan waves` after
+  freeze/order and digit children from `spur task batch-plan task-children` at task start —
   [execution-batch.md](../skills/spur-dev/references/execution-batch.md#27-visible-batch-plan-1105-r3)
   § 2.7 Visible batch plan.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface). Interactive sequential omit/`inline` keeps the orchestrator in the host session through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md); the resolved selector applies uniformly — eligible `agent.run` stages dispatch once to a native subagent with host fallback (0508). `--agent auto`, a name, or parallel mode retains the isolated per-task workflow boundary.

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

@@ -32,7 +32,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ```
 
 **Shippable readiness** (feature-level): when `--fix all` and the task has a `feature_id`, the
-skill runs `spur feature check <id>` after the per-task verdict and emits `Shippable: PASS|FAIL|N/A`.
+skill runs `spur feature check <id> --as done --strict` after the per-task verdict and emits `Shippable: PASS|FAIL|N/A`.
 Default **on** with `--fix all`. Opt out only with **`--skip-shippable`** (alias `--skip-shipable`).
 See `sp:code-verification` § Shippable readiness gate.
 
@@ -42,14 +42,12 @@ See `sp:code-verification` § Shippable readiness gate.
 - `Skill(skill="sp:code-verification", args="verify $ARGUMENTS")`
 - **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,
+  run `spur task residual <wbs> 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
+  record reads unticked-but-proven boxes and folds a clean PASS to PARTIAL. When the task reaches
+  `done` through `--next`, run `spur task residual <wbs> settle` (best-effort). On a folded PARTIAL: the bounded remediation loop has
   already run — a residual-failed task is routed to router C6 (HITL STOP), never another
   automatic fix loop.
 

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

@@ -60,7 +60,7 @@ statuses. Do not confuse with `--keep-going`
 
 **Shippable readiness** (feature-level): when `--fix all` and a feature context exists
 (`--feature` or a unique shared `feature_id` across the set), after all per-task verifies the
-orchestrator runs **one** `spur feature check <id>` and emits `Shippable: PASS|FAIL|N/A`.
+orchestrator runs **one** `spur feature check <id> --as done --strict` and emits `Shippable: PASS|FAIL|N/A`.
 A FAIL means the batch is **not clean** (rollup at least PARTIAL) even if every task AC PASSed.
 Default **on** with `--fix all`. Opt out only with **`--skip-shippable`** (alias `--skip-shipable`).
 Without `--fix all`, shippable is not evaluated (optional note: use `--fix all` for ship gate).
@@ -74,7 +74,6 @@ Without `--fix all`, shippable is not evaluated (optional note: use `--fix all`
 - Shippable gate: once after the batch (same skill § Shippable readiness gate)
 - **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).
+  flipped its verdict-proven boxes, run `spur task residual <wbs> scan` + `fold` (under every
+  `--fix` mode), and re-record only on a downgrade; on reaching `done` via `--next`, run
+  `spur task residual <wbs> settle`.

package/plugins/sp/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-    "description": "Spur (sp) plugin hooks — task corpus write protection + indexed-context token-ledger tracking + fleet lifecycle reporting.",
+    "description": "Spur (sp) plugin hooks — task corpus write protection + destructive-command confirm + indexed-context token-ledger tracking + fleet lifecycle reporting. Each `superskill hook run sp <id>` resolves to scripts/hooks/<id>.ts (superskill ADR-039).",
     "hooks": {
         "PreToolUse": [
             {
@@ -11,6 +11,16 @@
                         "timeout": 10
                     }
                 ]
+            },
+            {
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "superskill hook run sp careful-guard",
+                        "timeout": 10
+                    }
+                ]
             }
         ],
         "PostToolUse": [

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

@@ -17,7 +17,7 @@
  * Self-contained by design (task 0232/0246/0248). Installed hook configs use
  * `superskill hook run sp context-post-tool`.
  *
- * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-post-tool.ts` keeps the argv/stdin adapter the installed entry resolves to.
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/scripts/hooks/context-post-tool.ts` keeps the argv/stdin adapter the installed entry resolves to.
  */
 
 import { execSync } from 'node:child_process';

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

@@ -11,7 +11,7 @@
  *
  * Self-contained by design (task 0232/0246).
  *
- * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-session-start.ts` keeps the argv/stdin adapter.
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/scripts/hooks/context-session-start.ts` keeps the argv/stdin adapter.
  */
 
 import { execSync } from 'node:child_process';

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

@@ -18,7 +18,7 @@
  * Self-contained by design (task 0232). Installed hook configs use the portable
  * `superskill hook run sp context-session-stop` entrypoint.
  *
- * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/hooks/context-session-stop.ts` keeps the argv/stdin adapter.
+ * Task 1174: this core lives in `plugins/sp/lib/`; `plugins/sp/scripts/hooks/context-session-stop.ts` keeps the argv/stdin adapter.
  */
 
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';

package/plugins/sp/lib/destructive-policy.ts

@@ -123,6 +123,69 @@ const DESTRUCTIVE: Array<{ label: string; re: RegExp }> = [
     { label: 'a docker prune (docker system prune)', re: /\bdocker\s+system\s+prune\b/i },
 ];
 
+/**
+ * A single shell word usable as a git global-option value. Quoted forms are kept
+ * whole — `-C "my repo"` must read as one argument — while an unquoted word stops at
+ * whitespace and the shell separators `; & |`, so the pass can never swallow a
+ * following command.
+ */
+const GIT_OPTION_VALUE = String.raw`(?:"[^"]*"|'[^']*'|[^\s;&|]+)`;
+
+/**
+ * Git global options that consume a following word in their separated form — the word
+ * after them is a value, never the subcommand. Verified against git 2.55.0: each of
+ * these takes the next word (`git --git-dir rev-parse …` → `unknown option:
+ * --is-inside-work-tree`, i.e. git had already consumed `rev-parse` as the value).
+ * The value-less long options (`--no-pager`, `--bare`, `--no-replace-objects`, …) need
+ * no list: missing one only makes the pass stop earlier, it can never misread a value
+ * as a subcommand. Do NOT add an option here unless it really consumes the next word —
+ * `--exec-path` is optional-value, so listing it would swallow the subcommand and hide
+ * a destructive verb (git 2.55.0: `git --exec-path /tmp/p reset --hard` prints the exec
+ * path and exits; the `=`-glued form does consume the value).
+ */
+const GIT_VALUE_TAKING_OPTION = '--(?:git-dir|work-tree|namespace|config-env|attr-source)';
+
+/**
+ * One `git` global option unit, including the whitespace before its value.
+ *
+ * - `--name=value` — any long option in glued form.
+ * - `KNOWN --name value` — the value-taking long options above, separated form.
+ * - `-C value` / `-c value` — the value-taking short options; git rejects glued short
+ *   forms (`git -C. status` → `unknown option: -C.`, verified on 2.55.0), so their
+ *   value is always the next word.
+ * - `--name` / `-xy` — any value-less flag (`--no-pager`, `--bare`, `-p`, …).
+ *
+ * An option run is a sequence of these units; it ends at the first token that is not an
+ * option — the subcommand. Matching the whole grammar rather than a four-form whitelist
+ * keeps sibling options of the same defect class from hiding a destructive verb without
+ * teaching every destructive pattern git's option table.
+ */
+const GIT_GLOBAL_OPTION = String.raw`(?:--[A-Za-z][A-Za-z0-9-]*=${GIT_OPTION_VALUE}|${GIT_VALUE_TAKING_OPTION}[ \t]+${GIT_OPTION_VALUE}|-(?:[A-Za-z]*[Cc])[ \t]+${GIT_OPTION_VALUE}|--[A-Za-z][A-Za-z0-9-]*|-[A-Za-z]+)`;
+
+/**
+ * `git` followed by any run of global options directly before the subcommand. Replacing
+ * the whole span with `git` lets the destructive subcommand patterns fire on
+ * option-prefixed invocations without teaching every pattern git's option grammar.
+ *
+ * The run cannot cross a command boundary: units match `[ \t]` only (never a newline)
+ * and an unquoted value stops at `; & |`.
+ */
+const GIT_WITH_GLOBAL_OPTIONS = new RegExp(String.raw`\bgit\b(?:[ \t]+${GIT_GLOBAL_OPTION})*`, 'g');
+
+/**
+ * Remove supported git global options between the `git` executable and its subcommand.
+ *
+ * `git -C . push --force`, `git --no-pager push --force` and
+ * `git -c core.hooksPath=/tmp/hooks push -f` used to classify as safe because the
+ * subcommand patterns require `git` immediately before the verb. The
+ * replacement edits only the matched option span: every other byte — newlines, command
+ * separators, quotes — is preserved, so the patterns cannot begin matching across a
+ * command boundary, and no shell expansion or `git` process is involved.
+ */
+export function stripGitGlobalOptions(command: string): string {
+    return command.replace(GIT_WITH_GLOBAL_OPTIONS, 'git');
+}
+
 /** Return a human label for the destructive command, or null when the command is safe. */
 export function classifyCommand(command: string): string | null {
     for (const rmMatch of command.matchAll(/\brm\b([^\n&|;]*)/g)) {
@@ -139,8 +202,9 @@ export function classifyCommand(command: string): string | null {
             return 'a recursive force remove (rm -rf)';
         }
     }
+    const normalized = stripGitGlobalOptions(command);
     for (const { label, re } of DESTRUCTIVE) {
-        if (re.test(command)) return label;
+        if (re.test(normalized)) return label;
     }
     return null;
 }

package/plugins/sp/plugin.json

@@ -1,8 +1,5 @@
 {
     "name": "sp",
-    "version": "0.4.8",
-    "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"]
-    }
+    "version": "0.4.9",
+    "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics."
 }

package/plugins/sp/{hooks → scripts/hooks}/agent-lifecycle.ts

@@ -26,7 +26,7 @@
  */
 
 import { spawn } from 'node:child_process';
-import { getEnvVars } from '../lib/env';
+import { getEnvVars } from '../../lib/env';
 
 /** Lifecycle states `spur agent report` accepts — mirrors MEMBER_LIFECYCLE_STATES in the domain. */
 export type MemberLifecycleState = 'working' | 'idle' | 'blocked';