@gobing-ai/spur 0.4.0 → 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.4.0",
+    "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.16",
-        "@gobing-ai/ts-ai-runner": "^0.5.16",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.5.16",
-        "@gobing-ai/ts-infra": "^0.5.16",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.5.16",
-        "@gobing-ai/ts-rule-engine": "^0.5.16",
-        "@gobing-ai/ts-runtime": "^0.5.16",
-        "@gobing-ai/ts-utils": "^0.5.16",
+        "@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
@@ -393,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                            |
@@ -408,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

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
@@ -175,6 +181,14 @@ with the commit) drops the row from the sweep; `DEFER(<reason>)` reclassifies a
 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

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

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

@@ -52,6 +52,12 @@ Flag → vars: `--auto` sets `profile=auto`, `idea_approved=true`, `design_appro
 
 ## Implementation
 
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill or
+  reading any reference — is `spur workflow show idea-pipeline.yaml --no-logo --format todo --json`
+  (the CLI resolves the project→registered→shared layer); then publish every `.plan` row's `text`
+  verbatim as the host todo list (the `steps[]` inventory when `.plan` is `null`) before the
+  pipeline's first stage — [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md)
+  run setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
 - `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.

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

@@ -1,7 +1,7 @@
 ---
 description: Fan out independent tasks or investigations in parallel via subagents — choose the right pattern and synthesize results
 role: planner
-argument-hint: "--tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json]"
+argument-hint: "--tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json] [--defer-gate]"
 allowed-tools: ["Bash", "Read", "Skill"]
 ---
 
@@ -18,14 +18,20 @@ Wraps the **sp:parallel-execution** skill.
 | `--mode` `<fan-out\|review-panel\|investigation>` | Fan-out pattern. | fan-out |
 | `--agent` `<inline\|auto\|name>` | Who runs each dispatched slice. Parallel fan-out is dispatch, so explicit `--agent inline` runs the batch **sequentially in the host session** with a printed notice (zero dispatch); omit keeps the default fan-out semantics; `auto` tier-resolves an executor; a name pins that executor. | omit |
 | `--json` | Emit structured JSON. | off |
+| `--defer-gate` | Opt-in parallel-batch gate policy (task 1111): each task's `test` hop runs the light tier and writes `DEFERRED`; the batch runs one integrated full gate on the base ref before the feature sync. Requires `--mode parallel`; default off. | off |
 
 For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
 
 ## Usage
 
-/sp:dev-parallel --tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json]
+/sp:dev-parallel --tasks <selector> [--feature <id>] [--mode <fan-out|review-panel|investigation>] [--agent <inline|auto|name>] [--json] [--defer-gate]
 
 ## Implementation
 
+- **Publish the visible batch plan first (1105):** as the batch orchestrator, 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 — [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) before choosing native subagents or `spur agent run`.
 - `Skill(skill="sp:parallel-execution", args="$ARGUMENTS")`

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

@@ -41,6 +41,12 @@ contract as `/sp:dev-idea`). If passed, ignore them with a one-line notice.
 
 ## Implementation
 
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill or
+  reading any reference — is `spur workflow show idea-pipeline.yaml --no-logo --format todo --json`
+  (the CLI resolves the project→registered→shared layer); then publish every `.plan` row's `text`
+  verbatim as the host todo list (the `steps[]` inventory when `.plan` is `null`) before the
+  pipeline's first stage — [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md)
+  run setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
 - Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
 - `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.

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

@@ -16,7 +16,9 @@ implement-ready tasks for further fixing; `--triage` is an alias of `--fix auto`
 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
-measurement is unavailable.
+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
+skill-injected `<skill name="…">` body counts as activity in `injectedPrompts`, never as a segment.
 
 ## Argument Flags
 

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

@@ -31,8 +31,17 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 
 ## Implementation
 
+- **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 — everything else under `references/` is on demand.
+- **Publish the generated plan first (1105):** your first tool call — before invoking the skill,
+  reading any reference, or showing the task — is `spur workflow show task-pipeline.yaml --no-logo
+  --format todo --json` (the CLI resolves the project→registered→shared layer); then publish every
+  `.plan` row's `text` verbatim as the host todo list (the `steps[]` inventory when `.plan` is
+  `null`) before readiness, Git, or isolation work —
+  [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8)
+  step 1 / [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) run
+  setup step 5.
 - Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
-- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — bootstrap checklist, quick readiness before isolation, workflow inventory before YAML, comprehensive checks at their owning boundaries (task 0814 R1/R3/R4/R7/R8).
+- Apply the [shared startup contract](../skills/spur-dev/references/cross-cutting.md#shared-startup-contract-task-0814-r1r3r4r6r7r8) — publish the generated plan first, quick readiness before isolation, digest binding, comprehensive checks at their owning boundaries (task 0814 R1/R3/R4/R7/R8; 1105 R1).
 - Full pipeline (default `--mode full`): interactive omit/`--agent inline` uses the
   [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md) via
   `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")`; `--agent auto` or a named executor
@@ -55,7 +64,8 @@ For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag
 base ref on full success, retain intact on any failure/halt/non-FF; bare form creates a fresh tree,
 `<name>` form adopts an existing worktree by name/path/branch). The lifecycle — dirty-tree precheck,
 creation or adoption, crash-safe `.spur/run/` marker, merge-or-retain, `--continue` re-entry — is
-`execution-batch.md` § Worktree isolation applied to a batch of one: marker `command` is `dev-run`
+`execution-worktree-setup.md` (creation/adoption, WT-1…WT-3b) + `execution-worktree-landing.md`
+(WT-4/WT-5) applied to a batch of one: marker `command` is `dev-run`
 and `selector` is the `<wbs>`, the derived branch is `sp/run-<wbs>-<short-id>`, and the success
 condition is the task reaching terminal `done` with no failed stage. A failing gate, a non-PASS
 verify verdict, or a HITL pause that ends the run all take the retention path.