@gobing-ai/spur 0.3.99 → 0.4.1

package/config/workflows/wrapup-pipeline.yaml

@@ -23,6 +23,18 @@
 #          -> done
 #        doc-sync routes a contract violation to `repair` (cheap, no
 #        re-dispatch — ADR-118 pilot) and an executor failure to `failed`;
+#        1147 adds two deterministic post-doc-sync checks that fail the step
+#        BEFORE the tripwire backstop and name doc-sync. Those edges are
+#        declared before the contract-violation edge, so a doc-sync that both
+#        misses its learnings post-condition and trips a deterministic check
+#        fails the step instead of taking repair. The checks are: the write-scope check
+#        (the entry snapshot diffed against the working listing; allowed paths
+#        are docs/** minus docs/tasks*/docs/features* plus the declared learnings
+#        capture — a violation writes scope-violation: <paths> and is reported,
+#        never auto-reverted) and the supersession-pin re-run
+#        (repo-wide-tests/adr-supersession.test.ts), so a resurrected delinked
+#        index row is attributable to doc-sync; doc-tripwire stays the full
+#        backstop and is never weakened;
 #        learnings-validate (0986) rejects a nonempty narration-only capture to
 #        the same `repair` edge with a distinct invalid-learnings-shape status —
 #        expectFile proves existence, never shape — while empty/missing captures
@@ -86,7 +98,7 @@
 "$schema": "@gobing-ai/spur/schemas/state-machine-workflow.schema.json"
 kind: state-machine
 name: wrapup-pipeline
-version: "7"
+version: "9"
 description: "Post-execution wrap-up: doc-sync (doc drift + learning capture), metrics, feature-transition, branch-cleanup"
 iterationBound: 10
 initialState: start
@@ -232,8 +244,26 @@ states:
       (a clean exit that missed its declared answerFile/expectFile post-condition)
       routes to the cheap `repair` edge instead of a full re-dispatch (ADR-118
       pilot, 0871) — `onError: continue` lets the transition guards read the
-      agent's result instead of halting the run.
+      agent's result instead of halting the run. 1147 R1/R2 wrap it with a
+      deterministic write-scope guard (entry snapshot before the query, diff after
+      it; a violation writes scope-violation: <paths> and routes to `failed`, the
+      edits are reported and never auto-reverted) and a supersession-pin re-run, so
+      an out-of-scope or delinked-row write is attributed here instead of surfacing
+      late at doc-tripwire.
     onEnter:
+      # (1147 R1) entry snapshot: the working listing is recorded BEFORE the model
+      # query so the post-doc-sync check can attribute only this step's writes. Never
+      # aborts; a git failure or a missing script leaves the snapshot absent and the
+      # check fails closed rather than guessing.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" doc-sync-snapshot;
+            else
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
+            fi
       # (warn) free-form prompt: no /sp:doc-evolve command surface yet (ADR-043
       # residual, 0607 R2 one-query merge); capture is bounded by expectFile.
       - kind: agent.run
@@ -243,7 +273,10 @@ states:
           input: >-
             First run Skill(skill="sp:doc-evolve", args="wrapup") to repair drift in
             docs/00_ADR.md, docs/03_ARCHITECTURE.md, docs/04_DESIGN.md, docs/design/* per constitution edit
-            rules; do not write task/feature corpus. The batch task list is the normalized, validated
+            rules; do not write task/feature corpus. Write ONLY inside docs/ (never docs/tasks* or
+            docs/features*) — any other changed path fails the wrap step with a scope violation. A row
+            absent from docs/04_DESIGN.md for a superseded satellite is intentional: do NOT re-add it.
+            The batch task list is the normalized, validated
             capture at .spur/run/${vars.__runId}-wrapup-tasks.json — read it for the WBS ids; never
             re-parse raw input. THEN extract working learnings from those tasks —
             conventions, errors fixed, patterns, gotchas, grouped by date and task WBS — as raw markdown
@@ -255,6 +288,34 @@ states:
           answerFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           expectFile: .spur/run/${vars.__runId}-wrapup-learnings.md
           timeoutMs: ${vars.stepTimeoutMs}
+      # (1147 R1) post-doc-sync write-scope guard: the script diffs the working listing
+      # against the entry snapshot and writes PASS or `scope-violation: <paths>` — the
+      # action always exits 0 so status truth lives in the file (0783 R4) and the
+      # declared guard routes. Violating edits are reported, never reverted.
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" doc-sync-scope;
+            else
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
+              printf 'scope-violation: wrapup-steps script not found\n' > ".spur/run/$__runId-wrapup-doc-sync-scope.status";
+            fi
+      # (1147 R2) supersession pins re-run: a doc-sync that resurrects a deliberately
+      # delinked index row (`repo-wide-tests/adr-supersession.test.ts`, g2) fails HERE,
+      # named with the pin, instead of being attributed to the later doc-tripwire
+      # backstop. Skips in a project without the pin; always exits 0 (0783 R4).
+      - kind: shell
+        options:
+          command: >-
+            mkdir -p .spur/run &&
+            eval "$(jq -r 'if .mode=="source-repo" then "S="+@sh"\(.dir)/wrapup-steps.ts"+" RUNNER=bun" elif .mode=="installed" then "S="+@sh"\(.dir)/wrapup-steps.mjs"+" RUNNER=node" else empty end' ".spur/run/$__runId-script-root.json" 2>/dev/null)"; if [ -f "$S" ]; then
+              "$RUNNER" "$S" doc-supersession;
+            else
+              echo "wrapup-steps failed closed — script not found — run 'superskill install sp --marketplace gobing-ai/spur'" >&2;
+              printf 'supersession-pin-failed: wrapup-steps script not found\n' > ".spur/run/$__runId-wrapup-doc-supersession.status";
+            fi
 
   - id: learnings-validate
     description: >
@@ -463,7 +524,8 @@ states:
     description: >
       Terminal — wrap-up failed (0770): invalid wrap input, an unresolved or
       non-completed task, a failed metrics capture, a failed required sync, a
-      failed repo-wide tripwire (1037), or a failed feature gate.
+      failed repo-wide tripwire (1037), a failed feature gate, or one of the
+      deterministic post-doc-sync checks (1147: write scope, supersession pins).
       Already-written artifacts (learnings, metrics rows, route reason) are
       preserved; nothing is rolled back.
 
@@ -521,17 +583,47 @@ transitions:
     guard:
       kind: always
 
-  # ── doc-sync: contract-first routing (ADR-118 pilot, 0871) ──
-  # Declaration order matters: the contract-violation edge is tried first, then
-  # success (action-ok), then the executor-failure defense (always) — a failed
-  # agent.run reaches these guards because doc-sync's agent.run declares
-  # onError: continue.
+  # ── doc-sync: deterministic checks, then contract repair (ADR-118; 1147 R1/R2) ──
+  # Declaration order matters. The engine takes the first passing guard. The two
+  # deterministic post-doc-sync checks (write scope, supersession pins) are tried
+  # first, so a doc-sync that both misses its learnings post-condition and writes
+  # out of scope (or resurrects a delinked row) fails the step. A violation they
+  # recorded can never be absorbed by repair or by the success edge. Contract
+  # violation is next (repair only when neither deterministic check fired), then
+  # success (action-ok), then the executor-failure defense (always). A failed
+  # agent.run reaches these guards because doc-sync's agent.run declares onError: continue.
+  - from: doc-sync
+    to: failed
+    terminalReason: failed-check
+    description: >
+      Write-scope violation (1147 R1): the post-doc-sync check found a changed path
+      outside docs/** minus the task/feature corpus (and the declared learnings
+      capture) — the status file names the paths and the failing step is doc-sync
+      itself. The edits are reported, never auto-reverted; already-written artifacts
+      stay on disk. Declared before contract-violation so a compound miss fails here.
+    guard:
+      kind: shell
+      options:
+        command: 'grep -q "^scope-violation:" .spur/run/$__runId-wrapup-doc-sync-scope.status 2>/dev/null'
+  - from: doc-sync
+    to: failed
+    terminalReason: failed-check
+    description: >
+      Supersession drift (1147 R2): the post-doc-sync re-run of
+      repo-wide-tests/adr-supersession.test.ts failed — doc-sync re-added a
+      deliberately delinked index row. Attributed here (named with the pin) rather
+      than at the later doc-tripwire backstop, which stays unchanged. Declared
+      before contract-violation so a compound miss fails here.
+    guard:
+      kind: shell
+      options:
+        command: 'grep -q "^supersession-pin-failed:" .spur/run/$__runId-wrapup-doc-supersession.status 2>/dev/null'
   - from: doc-sync
     to: repair
     description: >
       Contract violation (ADR-118): the agent exited 0 but missed its declared
-      post-condition. Route to the cheap repair edge — never re-dispatch the
-      full agent.run on this attempt.
+      post-condition, and neither deterministic check fired. Route to the cheap
+      repair edge — never re-dispatch the full agent.run on this attempt.
     trigger: contract-violation
     guard:
       kind: contract-violation
@@ -545,8 +637,9 @@ transitions:
     terminalReason: failed-check
     description: >
       Executor failure (non-zero exit, signal, or dispatch error) — keep the
-      existing fail semantics; a contract violation never falls through here
-      because the contract-violation edge is declared first.
+      existing fail semantics. A scope or supersession violation is declared
+      earlier and fails the step; a contract violation never falls through here
+      because its edge is declared before this defense.
     trigger: executor-failure
     guard:
       kind: always

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.99",
+    "version": "0.4.1",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -57,14 +57,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.5.12",
-        "@gobing-ai/ts-ai-runner": "^0.5.12",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.12",
-        "@gobing-ai/ts-infra": "^0.5.12",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.12",
-        "@gobing-ai/ts-rule-engine": "^0.5.12",
-        "@gobing-ai/ts-runtime": "^0.5.12",
-        "@gobing-ai/ts-utils": "^0.5.12",
+        "@gobing-ai/ts-db": "^0.5.21",
+        "@gobing-ai/ts-ai-runner": "^0.5.21",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.5.21",
+        "@gobing-ai/ts-infra": "^0.5.21",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.21",
+        "@gobing-ai/ts-rule-engine": "^0.5.21",
+        "@gobing-ai/ts-runtime": "^0.5.21",
+        "@gobing-ai/ts-utils": "^0.5.21",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -98,6 +98,7 @@ list this README is checked against.
 | `dev-idea`       | 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, handoff |
 | `dev-plan`       | Plan a feature from a written description — intake → feature create → AC generation → feature check gate → decomposition → batch-create                                         |
 | `dev-brainstorm` | Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring                                              |
+| `dev-find-way`   | Wayfinder — chart a multi-session investigation map, or resolve one map ticket; always in an isolated git worktree + branch (`--worktree`, `--wrap`)                             |
 | `dev-refine`     | Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; `--depth ready` audits and corrects existing claims, freezes the spec, promotes to todo |
 
 #### Lifecycle — execution
@@ -273,6 +274,7 @@ plugins/sp/
 ├── 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)
@@ -342,6 +344,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `reverse-engineering`       | 1.1   | Codebase analysis / HLD generation / audit — depth-driven reverse engineering with orthogonal mode, focus, and format controls; backs `/sp:dev-reverse`                                                                                    |
 | `issue-finding`             | 2.0   | Session-log forensics — multi-source discovery, bottleneck ranking, optional topic focus, CLI-gated fix task generation; **legacy path** — superseded by `history-anatomy` for indexed reporting; backs no current command; directly invocable as sp:issue-finding |
 | `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`     |
 | `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                                                                        |
@@ -391,7 +394,7 @@ index above lists the live inventory, organized by the surface they wrap:
 
 | Prefix       | Count | Delegates to                                                                                                                                                                                                                                                                                                        | Purpose                                                                                |
 | ------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `dev-*`      | 33    | `sp:spur-dev`, `sp:spur-cli`, `sp:next-router`, `sp:next-feature`, `sp:brainstorm`, `sp:wayfinder`, `sp:sys-architecture`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:functional-review`, `sp:code-improvement`, `sp:code-simplification`, `sp:sys-debugging`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:history-anatomy`, `sp:session-review`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
+| `dev-*`      | 38    | `sp:spur-dev`, `sp:spur-cli`, `sp:next-router`, `sp:next-feature`, `sp:brainstorm`, `sp:wayfinder`, `sp:sys-architecture`, `sp:code-implementation`, `sp:code-testing`, `sp:code-verification`, `sp:functional-review`, `sp:code-improvement`, `sp:code-simplification`, `sp:sys-debugging`, `sp:dogfood-testing`, `sp:parallel-execution`, `sp:history-anatomy`, `sp:session-review`, `sp:conflict-finding`, `sp:reverse-engineering`, `sp:pr-reviewing`, inline | The dev-workflow surface — planning, execution, batch, wrap-up, review/verify, hygiene |
 | `rule-*`     | 3     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The rule surface — `rule-add`, `rule-refine`, `rule-scan`                              |
 | `workflow-*` | 2     | `sp:spur-cli`                                                                                                                                                                                                                                                                                                       | The workflow surface — `workflow-add`, `workflow-refine`                               |
 | `spur-init`  | 1     | `sp:doc-evolve`                                                                                                                                                                                                                                                                                                     | Project bootstrap (`spur init`) with doc-evolve integration                            |
@@ -406,6 +409,15 @@ 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`.
+
 **Thin-wrapper contract** is enforced by `scripts/commands/validate-commands.ts`:
 
 ```bash
@@ -473,13 +485,16 @@ the agent provides an isolated context window.
 #### 4. Hooks (`hooks/`)
 
 Event-driven enforcement that runs automatically without user invocation. `hooks.json` registers
-four handlers:
+six handlers across seven events:
 
 | Event          | Matcher                               | Handler                                        | Timeout |
 | -------------- | ------------------------------------- | ---------------------------------------------- | ------- |
 | `PreToolUse`   | `Write\|Edit`                         | `superskill hook run sp task-write-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      |
+| `Notification` | `permission_prompt`                   | `superskill hook run sp agent-lifecycle`       | 5s      |
+| `Stop`         | —                                     | `superskill hook run sp fleet-guest-stop`      | 10s     |
 | `SessionEnd`   | —                                     | `superskill hook run sp context-session-stop`  | 15s     |
 
 **Write guard.** The `PreToolUse` hook fires on every `Write`/`Edit` tool call and checks whether
@@ -493,6 +508,11 @@ estimates the token cost of each matched tool call and appends it to `.spur/cont
 (with redaction of sensitive argument fields), `context-session-start` seeds the indexed-context
 hint on first launch, and `context-session-stop` closes out the session record.
 
+**Fleet hooks (1080/1081).** `agent-lifecycle` reports member state in the background via
+`spur agent report --state working|idle|blocked` (a permission prompt is `blocked`) — only when
+`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`,
 `git push --force`, …) — it is **not** registered in `hooks.json`. Fail-open by contract; escape
@@ -511,6 +531,7 @@ hold `SKILL.md` and prompt-side companions only.
 | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `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/{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)                                                                                                                                                                                                                                      |
 | `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 |
@@ -518,6 +539,8 @@ hold `SKILL.md` and prompt-side companions only.
 | `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/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                                                                                                                                                                                                                     |
 

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

@@ -285,6 +285,17 @@ With `--json`, emit the same shape as a JSON object for machine consumption.
   `spur workflow continue --answer-text` and the run resumes implement with the Q/A transcript
   (bounded by `maxEscalations`). See [execution-batch.md Step 3](../skills/spur-dev/references/execution-batch.md#step-3--the-driver-loop-r3-r4).
 
+## Parent-host ownership of the visible plan (1105 R4)
+
+The parent host owns the visible plan: apply the § 2.7 Visible batch plan updates in the parent
+session's native todo list (`execution-batch.md` § 2.7; the frozen status mapping lives in
+[inline-pipeline-driver.md](../skills/spur-dev/references/inline-pipeline-driver.md) § Host todo
+update styles). Subagents own code and evidence — subagents never render the visible list and todo
+tools are not available to them; at each **stage boundary** (implement, test, review, verify) a
+subagent returns `{wbs, state, outcome}` (+ optional `next`), and the parent marks the matching rows
+with the reported outcome. Keep letters/digits from the projection identical across both layers so
+row identity stays stable.
+
 ## Platform Notes
 
 - **Claude Code:** native - `Bash` runs `spur` CLI for deterministic verbs; `Skill()` is available

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

@@ -123,6 +123,12 @@ HITL gate unless `--auto` was passed.
 - [ ] Dispatch each requested dimension to its owning skill — do not inline the review logic.
 - [ ] Merge findings into a single ranked report, emitting native priority cells
       (`P1 (blocker)` > `P2 (major)` > `P3 (minor)` > `P4 (advisory)` — see Output Format).
+- [ ] Sweep a finding's **class** in the same round. When a defect is one instance of a repeated
+      pattern (the same rule misapplied on two surfaces, a signature stale in both a generator and
+      its output), grep for the siblings and report every instance now. A half-found class costs a
+      full gate + review cycle when the next round finds the other half — H1 batch 2026-10-08:
+      review round 1 of task 1129 named one runbook's fingerprint/commit mismatch, round 2 found
+      the same mismatch on the sibling runbook.
 - [ ] With a WBS target (standalone or pipeline), write the merged report to that task's
       `## Review` section via `spur task update <wbs> --section Review --from-file` — per task
       under a task set, then the combined summary table; with a path target, emit as advisory
@@ -165,6 +171,24 @@ fails it. One explicit mapping, no transcription step anywhere downstream:
 Severity words stay visible in the same cell — the mapping adds the machine-readable label, it does
 not replace the semantics.
 
+**Disposition column (1089, E71).** The findings table carries a `Disposition` cell. It is not
+cosmetic: the record stage's residual sweep reads these rows (`parseReviewFindings` in
+`packages/app/src/services/residual-scan.ts`), and a `P1`–`P3` row with no disposition classifies as
+**blocking**, which downgrades a PASS verdict to PARTIAL and closes the `done` gate. A finding you
+resolved inside the same task therefore says so in that cell — `RESOLVED`/`FIXED`/`DONE` (optionally
+with the commit) drops the row from the sweep; `DEFER(<reason>)` reclassifies a P3 as deferrable
+(never P1/P2). Prose such as "Closed." inside the *Finding* cell does not count — the sweep reads
+the cell, not the sentence. `OPEN` states "still live", and `ACCEPTED` marks a non-blocking P4
+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
+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
+its cell now, while you hold the context, instead of leaving the cost to be rediscovered after a
+full cycle.
+
 **Section-relative headings.** In WBS mode (standalone or pipeline) the report body is written
 *into* the task's `### Review` section, so every heading inside it MUST be `####` or deeper. A
 `##`/`###` heading in the body becomes a new top-level task section and corrupts the document. With
@@ -173,19 +197,17 @@ shallower.
 
 ```markdown
 #### Review Report — <wbs|path>
-
 **Scope:** <wbs diff | path glob>
 **Dimensions:** functional, security, efficiency, correctness, usability, architecture
 **Verdict:** PASS | PARTIAL | FAIL
-
 ##### Findings (ranked)
 
-| # | Priority | Dimension | Finding | Location |
-|---|----------|-----------|---------|----------|
-| 1 | P1 (blocker) | security | SQL injection in query builder | `src/api/users.ts:42` |
-| 2 | P2 (major) | architecture | Shallow pass-through UserService | `src/services/users.ts:15` |
-| 3 | P3 (minor) | correctness | Missing error branch in createUser | `src/api/users.ts:48` |
-| 4 | P4 (advisory) | usability | `createUser` error text omits the field name | `src/api/users.ts:51` |
+| # | Priority | Dimension | Finding | Location | Disposition |
+|---|----------|-----------|---------|----------|-------------|
+| 1 | P1 (blocker) | security | SQL injection in query builder | `src/api/users.ts:42` | OPEN |
+| 2 | P2 (major) | architecture | Shallow pass-through UserService | `src/services/users.ts:15` | OPEN |
+| 3 | P3 (minor) | correctness | Missing error branch in createUser | `src/api/users.ts:48` | RESOLVED (fixed in <sha>) |
+| 4 | P4 (advisory) | usability | `createUser` error text omits the field name | `src/api/users.ts:51` | ACCEPTED |
 
 ##### Functional Traceability
 
@@ -197,14 +219,20 @@ shallower.
 **Next:** <one-line action>
 ```
 
+The **Verdict line is machine-read** by the task pipeline (session finding after 1088): `review →
+verify|approve` requires a line matching `Verdict: PASS` (plain or bold), and ANYTHING ELSE —
+FAIL, PARTIAL, a missing line, a line split across two lines — routes the run into
+`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.
+
 **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:
 
 ```markdown
-| # | Priority | Dimension | Finding | Location |
-|---|----------|-----------|---------|----------|
-| 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` |
+| # | Priority | Dimension | Finding | Location | Disposition |
+|---|----------|-----------|---------|----------|-------------|
+| 1 | P4 (advisory) | — | No P1–P3 findings: 6 changed files reviewed across all six dimensions; R1–R3 traceable to tests | `packages/app/src/workflow/proof-input-fingerprint.ts:102-160` | ACCEPTED |
 ```
 
 ## Out of scope

package/plugins/sp/bunfig.toml

@@ -0,0 +1,8 @@
+# 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).
+[test]
+preload = ["../../tests/setup.ts"]

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

@@ -1,41 +1,54 @@
 ---
 description: Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring
 role: planner
-argument-hint: "<topic> [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]"
+argument-hint: "<topic> [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
 # Dev Brainstorm
 
-Wraps the **sp:brainstorm** and **sp:wayfinder** skills.
+Wraps the **sp:brainstorm** skill.
 
 ## Argument Flags
 
 | Flag | Description | Default |
 | --- | --- | --- |
 | `<topic>` | Topic or problem statement to explore. | required |
-| `--depth` `<basic\|detailed\|comprehensive>` | Breadth vs. depth of the exploration. | detailed |
-| `--options` `<n>` | Number of solution options to generate. | 3 |
+| `--depth` `<basic\|detailed\|comprehensive>` | How deep the discovery interview walks the decision tree. | detailed |
+| `--options` `<n>` | Number of solution approaches to generate. | 3 |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing ideation. | omit |
 | `--skip-discovery` | Skip the discovery interview; ideate immediately. | off |
-| `--wayfind` | Spawn a wayfinder feature for multi-session routing. | off |
-| `--task` `[<feature-id>]` | Create a tracking task under a feature. | omitted |
-| `--feature` `[<parent-id>]` | Attach the result to a parent feature. | omitted |
-| `--next` | Hand off to the next-router on success. | off |
+| `--task` `[<feature-id>]` | Artifact exit: create one `todo` task from the chosen approach, optionally under `<feature-id>`. | omitted |
+| `--feature` `[<parent-id>]` | Artifact exit: create a validated feature (Goal/Scope/BDD AC) from the chosen approach, optionally under `<parent-id>`. | omitted |
+| `--next` | With `--feature` only: on a clean `feature check`, chain into `/sp:dev-plan --feature <ID>`. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-brainstorm <topic> [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]
+```
+/sp:dev-brainstorm "<topic>" [--depth <basic|detailed|comprehensive>] [--options <n>] [--agent <inline|auto|name>] [--skip-discovery] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]
+```
+
+Two phases:
+
+1. **Discovery** — a grilling interview, one question at a time, each with a recommended answer;
+   the codebase is explored before the operator is asked. Produces a resolved decision tree.
+   `--skip-discovery` replaces it with the skill's lightweight clarification step.
+2. **Ideation** — `--options` approaches, each with trade-offs, implementation notes, confidence
+   and the decisions it depends on; one is marked recommended.
+
+Without an exit flag the brainstorm output is the result. `--task` and `--feature` are mutually
+exclusive (passing both is an error); the operator confirms the chosen approach before either
+writes to the corpus. `--next` is ignored without `--feature`.
+
+If discovery shows the destination itself is too foggy to spec in one session, stop and recommend
+`/sp:dev-find-way "<topic>"` with the resolved decision tree as its starting notes. Never chart a
+multi-session map from this command.
 
 ## Implementation
 
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
-- Default: `Skill(skill="sp:brainstorm", args="dev-brainstorm --context <decision-tree> --options <n>")`
-- `--wayfind`: `Skill(skill="sp:wayfinder", args="chart --destination <destination> --context <decision-tree>")`
-
-`--next`: chain-to-completion with
-propagation. Only meaningful with `--feature` (the front-half artifact exit): on a clean
-`feature check`, chain into `/sp:dev-plan --feature <ID>` so the planning half runs end-to-end.
-Ignored without `--feature` (there is no task in a lifecycle to advance). **was: `--next` declared but never defined.**
+- Discovery protocol: [grilling-interview.md](../skills/brainstorm/references/grilling-interview.md).
+- Ideation: `Skill(skill="sp:brainstorm", args="dev-brainstorm --context <decision-tree> --options <n>")`
+- Artifact exits and `--next`: [dev-operations.md § 12. brainstorm](../skills/spur-dev/references/dev-operations.md#12-brainstorm).

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

@@ -1,8 +1,8 @@
 ---
 description: Generate changelog from git commits
 role: scribe
-argument-hint: "[--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
-allowed-tools: ["Bash", "Read"]
+argument-hint: "[<file>] [--since <tag|commit>] [--until <tag|commit>] [--version <version>]"
+allowed-tools: ["Bash", "Read", "Edit"]
 ---
 
 # Dev Changelog
@@ -13,6 +13,7 @@ Implements an inline procedure — see [dev-operations.md](../skills/spur-dev/re
 
 | Flag | Description | Default |
 | --- | --- | --- |
+| `<file>` | Optional positional target (e.g. `CHANGELOG.md`); the new section is inserted above its newest release. | stdout |
 | `--since` `<tag\|commit>` | Start of the commit range. | latest tag |
 | `--until` `<tag\|commit>` | End of the commit range. | HEAD |
 | `--version` `<version>` | Override the detected release version. | detected |
@@ -21,9 +22,9 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Usage
 
-/sp:dev-changelog [--since <tag|commit>] [--until <tag|commit>] [--version <version>]
+/sp:dev-changelog [<file>] [--since <tag|commit>] [--until <tag|commit>] [--version <version>]
 
 ## Implementation
 
-Follow the inline procedure in [dev-operations.md](../skills/spur-dev/references/dev-operations.md#8-changelog) (changelog).
+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).
 

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

@@ -0,0 +1,80 @@
+---
+description: Wayfinder — chart a multi-session investigation map for a foggy destination, or resolve one map ticket, always inside an isolated git worktree + branch
+role: planner
+argument-hint: "<idea> | <feature-id> [<wbs>] [--agent <inline|auto|name>] [--auto] [--worktree [<name>]] [--wrap]"
+allowed-tools: ["Bash", "Read", "Write", "Edit", "Skill", "AskUserQuestion"]
+---
+
+# Dev Find Way
+
+Wraps the **sp:wayfinder** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `<idea>` | Loose idea whose destination is too foggy to spec in one session. Enters **chart** mode. | required (one of `<idea>` / `<feature-id>`) |
+| `<feature-id>` | Existing wayfinder map (feature tagged `wayfinder-map`). Enters **work** mode. | required (one of `<idea>` / `<feature-id>`) |
+| `<wbs>` | Work mode only: the ticket to resolve. Omit to take the first unclaimed frontier ticket. | first frontier ticket |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing charting/resolution. | omit |
+| `--auto` | Skip objective HITL confirmations. Never skips the map's open-question decisions. | off |
+| `--worktree` `[<name>]` | Isolation mode. Bare (or omitted) creates a fresh worktree + branch; `--worktree <name>` adopts an existing worktree by name/path/branch. FF-merge on success, retain on failure. There is no in-place mode. | create |
+| `--wrap` | Work mode only: after the ticket reaches `done`, run `/sp:dev-wrap <wbs>` inside the worktree before the merge. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+```
+/sp:dev-find-way "<idea>" [--agent <inline|auto|name>] [--auto] [--worktree [<name>]]
+/sp:dev-find-way <feature-id> [<wbs>] [--agent <inline|auto|name>] [--auto] [--worktree [<name>]] [--wrap]
+```
+
+A first argument that resolves as a feature id (`spur feature show <id> --json`) is work mode;
+anything else is a chart-mode idea. Chart mode charts the map and stops; work mode resolves
+**exactly one** ticket (one ticket per session).
+
+**Always a worktree + branch.** Every invocation runs in an isolated git worktree on its own branch —
+never in the invoking tree, and never as a branch switch (`git checkout -b`) in the invoking tree.
+A branch-only session mutates the operator's checkout under every other agent sharing it, and its
+`wayfind/*` branches pile up on the main tree. Omitting `--worktree` behaves exactly like bare
+`--worktree`.
+
+**Lifecycle.** `execution-batch.md` § Worktree isolation applied to a run of one (WT-1…WT-5):
+
+- WT-1 dirty-tree precheck on the invoking tree (abort on dirty — name the files).
+- WT-2 create (sibling dir, `bun install --frozen-lockfile --ignore-scripts`) or adopt by name.
+- WT-3 marker in the invoking tree's `.spur/run/`: `command` = `dev-find-way`, `selector` =
+  `chart:<destination-slug>` or `<feature-id>:<wbs>`.
+- Derived branch: `sp/wayfind-<destination-slug>-<short-id>` (chart) or
+  `sp/wayfind-<wbs>-<short-id>` (work).
+- WT-3b commit the session's corpus writes on the branch, then WT-4 FF-merge onto the base ref
+  (create mode removes the tree and deletes the branch; reuse mode retains both).
+- WT-5 retain intact on any failure, HITL pause, unresolved open question that ends the session,
+  or non-FF base — report path, branch and the resume command (`--worktree <name>`).
+
+Success is: **chart** — map feature created, tagged `wayfinder-map`, `spur feature check <id>`
+clean, child tickets wired; **work** — the ticket reached `done`, its line is in
+**## Decisions so far**, and graduated fog became tickets.
+
+**Ticket selection across parallel sessions (work mode).** Corpus writes — including the `wip`
+claim — land in the worktree copy until the merge, so a claim is invisible to sibling worktrees.
+Before choosing a frontier ticket, read every `.spur/run/worktree-*.json` marker in the invoking
+tree with `command: dev-find-way` and `status: active`/`retained`, and exclude their `<wbs>`. A named
+`<wbs>` held by such a marker aborts before any tree is created; resume it with
+`--worktree <name>` instead.
+
+**`--wrap`.** Runs after the ticket reaches `done` and before WT-3b, so the wrap's writes merge with
+the resolution. `--agent` is preserved into the `/sp:dev-wrap <wbs>` handoff when supplied. In chart
+mode nothing is resolved: `--wrap` is skipped with the reason `wrap skipped: chart mode resolves no
+ticket`.
+
+**Corpus visibility.** Until the FF-merge, the map and ticket writes exist only in the worktree; the
+invoking tree shows the pre-session state. Expected, not a bug.
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- Worktree lifecycle: [execution-batch.md § Worktree isolation](../skills/spur-dev/references/execution-batch.md#worktree-isolation---worktree-name) — every host call pins the execution tree per its per-call tree-pin rule.
+- Inside the worktree: `Skill(skill="sp:wayfinder", args="$ARGUMENTS")` — the skill owns charting, ticket resolution, fog graduation and the one-ticket-per-session rule.
+- `--wrap` (work mode): `/sp:dev-wrap <wbs> [--agent <value>]` inside the worktree before WT-3b.