@gobing-ai/spur 0.4.2 → 0.4.4

package/plugins/sp/README.md

@@ -272,15 +272,18 @@ 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 + task-write-guard.{ts,test.ts} + context-{session-start,post-tool,session-stop}.ts
-│                                    # + agent-lifecycle.{ts,test.ts} + fleet-guest-stop.{ts,test.ts} (fleet member/guest hooks)
-│                                    # + careful-guard.{ts,test.ts} + context-hooks.test.ts + token-estimate.test.ts
-│                                    # + shared policy modules: agent-hint.ts, destructive-policy.{ts,test.ts}, task-file-policy.{ts,test.ts}
-│                                    # + pi/guard-extension.{ts,test.ts} (plugin.json `extensions.pi` entry point)
+├── 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/
+├── 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, logger}.ts; dogfood-testing: {detect-pipeline-driving, validate-report}.ts)
-├── tests/                           # Plugin tests — skill-structure.test.ts + batch-preflight.test.ts + per-skill suites (command-contract moved to scripts/commands/)
-├── evals/                           # Skill behavioral eval harness (scenarios + judge + run-eval runner)
+│                                    # (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)
+│                                    # + evals/ (behavioral eval corpus + judge; see tests/evals/README.md,
+│                                    # runner at scripts/commands/skill-eval.ts) + per-skill suites
 ├── plugin.json                      # Marketplace entry
 └── README.md                        # This file
 ```
@@ -512,8 +515,9 @@ 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/` (with tests) as an opt-in
-`PreToolUse` guard that asks before destructive shell commands (`rm -rf`, `DROP TABLE`,
+**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`.
 
@@ -529,19 +533,21 @@ 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`                                 | Runtime for the three registered context hooks (session-start, post-tool, session-stop) — token-cost estimation + ledger append for `sp:indexed-context`                                                                                                                                          |
+| `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)                                                                                                                                                                                                                                      |
+| `hooks/careful-guard.ts`                             | Opt-in destructive-command guard (unwired — 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` | Word-boundary detector for pipeline-driving testees (leading-space invariant)                                                                                                                                                                                                                     |
-| `scripts/dogfood-testing/validate-report.ts`         | Pure `validateReport(md)` — footer-mandatory + 7-check finalize-or-abort contract with stable error codes                                                                                                                                                                                         |
-| `scripts/daily-summary/{daily-summary,logger}.ts`    | ccusage + git-history orchestration helpers for `sp:daily-summary`                                                                                                                                                                                                                                |
+| `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 — in `hooks/` for guards, in `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                                                     |
+| `*.test.ts`                                          | Unit suites — `tests/hooks/` for the hook entries and their lib cores, `tests/<skill>/` per ADR-031 pairing                                                                                                                                                                                        |
 
 **Design principle:** Scripts are **deterministic enforcement**. Unlike skills (which are advisory
 knowledge consumed by the LLM), scripts run as code and make binary allow/deny decisions. They are

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

@@ -200,6 +200,7 @@ shallower.
 **Scope:** <wbs diff | path glob>
 **Dimensions:** functional, security, efficiency, correctness, usability, architecture
 **Verdict:** PASS | PARTIAL | FAIL
+**Confidence:** HIGH | MEDIUM | LOW
 ##### Findings (ranked)
 
 | # | Priority | Dimension | Finding | Location | Disposition |
@@ -225,6 +226,51 @@ FAIL, PARTIAL, a missing line, a line split across two lines — routes the run
 `review-fail-triage` and its bounded repair hop. Keep it on one line, in that shape, in every
 review answer; never restate it as prose only.
 
+**The Confidence line is machine-read too (one confidence contract, 2026-10-12).** Every review
+report carries exactly one `Confidence: HIGH | MEDIUM | LOW` line, stated at the level the review can
+actually defend — the same enum and the same earning rule the verify answer uses
+([verdict-schema.md](../skills/code-verification/references/verdict-schema.md) § Confidence level):
+
+- `HIGH` — every requirement row is `MET`, every finding carries a disposition, and the report cites
+  its evidence. `HIGH` says the evidence needs no re-check.
+- `MEDIUM` — the verdict holds but evidence gaps remain; name them.
+- `LOW` — the verdict rests on unverified assumptions that could plausibly flip it; name them.
+
+A missing line, a level outside the enum, or a `HIGH` the rows do not earn turns an otherwise usable
+PASS into a refused one: consumer repositories gate the review answer artifact and every level it
+claims, exactly as they gate the verify answer. This is a contract change — review answers written
+before it were never asked for a level, so pre-adoption artifacts read as debt, not defects.
+
+**Machine-checked at the gate.** The pipeline's own review PASS edges enforce the line before verify:
+`residual-scan review-gate` reads the recorded `### Review` body, and a missing, duplicated or
+out-of-enum level becomes a **blocking** `review-contract` item — `review → verify` stops and the run
+enters `review-fail-triage` with the bounded repair hop, exactly as an open P1–P3 row does. The gate
+checks the recorded section's presence and vocabulary; the same scanner grades the answer passed
+by both PASS edges and refuses a `LOW` (or ungraded) PASS unless the operator sets
+`ackLowConfidence` exactly to `true` (task 1204 — the same policy the verify
+chain enforces), so whether a level is *earned* stays a judgement call (see the earning rule above):
+the report must still argue it.
+
+**Source citations for external claims (one claim contract, 2026-10-12).** A Finding cell or a
+Functional Traceability `Evidence` cell that asserts an external API/library claim carries a
+verifiable citation in the SAME cell — a repo `path:line(-end)`, the external named-origin form
+(@origin `path` line N, line number outside the backticks), or an http(s) URL. It is the verify
+answer's rule verbatim, owned by
+[verdict-schema.md](../skills/code-verification/references/verdict-schema.md) § Source citations
+for external claims — claim markers and accepted forms are defined once there and are not restated
+here. The findings table's `Location` column does not stand in for it: `Location` anchors the
+finding's subject, not the claim's source. Cell-free receipts (test counts, reviewed-log notes)
+assert no external claim and need no citation. An uncited external claim is an assumption, so it
+caps the level the report can defend (above).
+
+**Machine-checked at the gate (findings table).** `residual-scan 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 —
+that is the rule stated above, and a gate that accepted it would pass every row that has an anchor.
+Functional Traceability `Evidence` cells stay reviewer-enforced (SECUA review): they are free prose
+in a table the gate does not parse.
+
 **No findings.** Never invent a defect to populate the table. Emit one substantive `P4 (advisory)`
 row that states what was reviewed and what was found — placeholder cells (empty, `—`, `n/a`) are
 rejected by the checker, and so they should be:

package/plugins/sp/bunfig.toml

@@ -1,8 +1,11 @@
 # Workspace-local test config (task 1127 R8/AC7, mirroring apps/cli's 0699 R3 precedent): without
-# it, `cd plugins/sp && bun test` — the run AGENTS.md prescribes — skipped the root preload and
-# resolved the operator's real ~/.config/spur/run/full-gate.lock. These suites then waited silently
-# behind any live host-wide gate holder (their holder line is swallowed by `silenceStdout`), which
-# is the dispatch-budget burn this task exists to remove. Coverage stays gated by the root bunfig
-# (bun run test).
+# it, `cd plugins/sp && bun test` — the run AGENTS.md prescribes — skipped the root preload, so these
+# suites lost the shared test setup (logger muting, the util shims, and the hermeticity env that keeps
+# tests off the operator's real ~/.config/spur/ config, projects registry and slash-command catalog).
+# Coverage stays gated by the root bunfig (bun run test).
+#
+# Historical: this comment once justified the preload by a host-wide `full-gate.lock` wait. That lock
+# was deleted in `refactor(gate): remove gate-lock mechanism and simplify quality-gate`; the preload
+# is still required, for the reasons above (task 1173 R5).
 [test]
 preload = ["../../tests/setup.ts"]

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 (lint, tests, `spur-check`, rules, citation checks).
+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, citation checks) — a generic "verify before finishing" rule does not apply here.
 

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

@@ -1,7 +1,7 @@
 ---
 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>]"
+argument-hint: "[--commit] [--squash] [--all] [--scope <path>] [--check <cmd>]"
 allowed-tools: ["Bash", "Read"]
 ---
 
@@ -17,12 +17,13 @@ Implements an inline procedure — see [dev-operations.md](../skills/spur-dev/re
 | `--squash` | Collapse every concern into one message and one commit; implies `--commit`. | off |
 | `--all` | Widen the change set past the index to every change in the tree — unstaged **and untracked**. | off |
 | `--scope` `<path>` | Path filter on the change set; always wins over change-set auto-discovery. | the whole change set |
+| `--check` `<cmd>` | Run `<cmd>` (e.g. `"bun run gate"`) once before committing; non-zero → commit nothing. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-gitmsg [--commit] [--squash] [--all] [--scope <path>]
+/sp:dev-gitmsg [--commit] [--squash] [--all] [--scope <path>] [--check <cmd>]
 
 ## Implementation
 
@@ -35,3 +36,6 @@ commit per concern, split automatically, so the operator is never asked to re-st
 `--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.
+No quality gate (`bun run gate`, lint, typecheck, tests, `spur-check`) runs unless `--check <cmd>`
+names one — then it runs once, before any commit, and a failure commits nothing. Gate → auto-fix →
+commit is `/sp:dev-gtd --no-push`.

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

@@ -24,4 +24,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#11-handover) (handover).
+Run no quality gate (`bun run gate`, lint, typecheck, tests, `spur-check`); cite results already on record.
 

package/plugins/sp/commands/dev-job-dump.md

@@ -24,6 +24,7 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 ## Implementation
 
 Follow [job-dump](../skills/spur-dev/references/dev-operations.md#11a-job-dump), using the shared
-handoff template to capture the current job and its remaining work.
+handoff template to capture the current job and its remaining work. Run no quality gate
+(`bun run gate`, lint, typecheck, tests, `spur-check`); copy existing gate results or write `not run`.
 
 Skill(skill="sp:spur-dev", args="job-dump $ARGUMENTS")

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

@@ -18,6 +18,14 @@ Wraps the **sp:spur-dev** skill. Three jobs:
 `standard` checks only that target sections are structurally complete. It never re-checks what
 they say. Use `ready` whenever the existing content itself is in doubt.
 
+**Refine never writes `feature_id`.** It may *report* an orphan task in its result, but linking a
+task to a feature is an operator decision with a lifecycle blast radius: `spur task update <wbs>
+--feature <id>` reopens a `verifying` parent unless `--no-reopen` is passed. Route linking through
+the opt-in [feature-link helper](../skills/spur-dev/references/feature-link-helper.md) (never
+gate-time, never automatic, always confirmed) — observed 2026-10-13: the ready-preparation refine
+that `spur task create` dispatches by default linked a fresh task to `P1` on its own and demoted
+that feature `verifying → active`.
+
 ## Argument Flags
 
 | Flag | Description | Default |
@@ -47,9 +55,13 @@ implement without inventing design:
 1. Audit every existing claim against the current tree: facts, cited sources, fix soundness across
    all callers, test observability, environment, concurrent work, and scope.
 2. Correct what is wrong and record each change in a dated `**Refine corrections (<date>)**` block
-   in Background.
+   in Background. When the task bundles several issues, triage each one. An issue that is invalid,
+   already fixed or owned elsewhere is removed together with its R-items, Design/Solution notes,
+   Plan steps and ACs. If no issue stays valid, cancel the task (`spur task update <wbs> cancelled`)
+   and report `cancelled` instead of promoting it.
 3. Run `spur task check <wbs> --as todo --json`, fill unset priority/estimate, and promote
-   `backlog → todo`.
+   `backlog → todo`. If triage dropped issues, re-estimate and record old → new. Also record a
+   title that still names dropped scope; the CLI cannot rename a task.
 4. Report checklist rows `{id, pass, evidence}`.
 
 Refine targets `backlog`/`todo` tasks; a `wip`-or-later task needs explicit operator consent and is

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

@@ -54,7 +54,13 @@ not a bug.
 **Depth:** default `standard` keeps the cheap L3 SKIP gate under `--auto`. Use
 `--depth ready` when handing a feature to another implementer (frozen Design/Requirements/Plan),
 or when the tasks' existing content is in doubt; thread `--depth` into each per-task refine. Ready
-report rows add corrections count, status before → after, and failed checklist ids.
+report rows add corrections count, dropped issues, status before → after, and failed checklist ids.
+Each task's issues are triaged one by one: invalid ones are dropped with their fixes, and a task
+with no valid issue left is `cancelled`. The ready report also proposes merges between overlapping
+tasks, ordering or a shared step for complementary ones, and owning features for tasks without a
+`feature_id`. It executes neither unless
+`--description` names the task and action, for example
+`--description "cancel 0273 and merge its issues into 0269; link 0260 and 0274 to G11"`.
 
 > **`--next` dropped** (feature H8, 2026-07-31). Batch-level chaining was a token bomb — each refine
 > hop is an LLM call, and a large feature means N refine chains fanned out at once. For batch

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

@@ -43,6 +43,7 @@ Put the target first: a bare token after `--worktree` is read as the worktree na
 - **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.
+- **Answer contract (pipeline dispatches).** The captured review answer (`.spur/run/<runId>-review-answer.txt`) must carry exactly one `Verdict: PASS|FAIL` line and exactly one `Confidence: HIGH|MEDIUM|LOW` line stating how strongly the review stands behind its verdict — HIGH = the reviewer re-executed the checks behind the verdict, MEDIUM = partial reliance on prior/external evidence, LOW = key evidence not re-executed. The pipeline's PASS edges admit HIGH/MEDIUM unadorned; LOW or an absent line crosses only with the operator's `ackLowConfidence` (same policy as the verify confidence gate, task 1068).
 - **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.

package/plugins/sp/hooks/careful-guard.ts

@@ -22,8 +22,8 @@
  * adapter. This file owns the Claude Code payload/decision shape only.
  */
 
+import { classifyCommand } from '../lib/destructive-policy';
 import { getEnvVar } from '../lib/env';
-import { classifyCommand } from './destructive-policy';
 
 interface ToolPayload {
     tool_name?: string;