@gobing-ai/spur 0.3.99 → 0.4.0

package/plugins/sp/skills/spur-cli/references/agent.md

@@ -23,14 +23,18 @@ that before using `run` for fan-out dispatch.
 | ---- | ------- | --------- |
 | `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
 | `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
+| `trace <runId>` | Print one execution record's lineage — the run, its dispatch parents, agent session ids and streams (1076 R4, ADR-132) | `--follow` `--timeout <ms>` `--json` |
 | `list` | List detected coding agents, or agent specs with `--specs` (live run status + member session merged from `spur self serve`) | `--specs` `--server <url>` `--json` |
+| `report` | Report a fleet member lifecycle state (`working`/`idle`/`blocked`) from a host hook (G73 R1/R2, task 1080) | `--state <state>` `--seq <ns>` `--spec <id>` `--json` |
+| `join` | Join the fleet as a guest occupant — a live session that pulls its own work (G73 R2, task 1081) | `--role <name>` `--id <id>` `--session-id <sid>` `--pid <n>` `--executor <name>` `--json` |
+| `leave` | Leave the fleet: release the guest lease, retire the occupant, return claimed messages to pending | `[id]` `--session-id <sid>` `--json` |
 | `status` | Agent specs with live process status and member session (requires `spur self serve`) | `--server <url>` `--json` |
 | `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
 | `usage` | Run-once provider usage capture (codexbar) → quota-owned availability refresh; scheduled externally | `--dry-run` `--source <name>` `--json` |
 | `start <spec-id>` | Start a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 | `stop <spec-id>` | Stop a supervised agent process (requires `spur self serve`) | `--server <url>` `--json` |
 
-`list`, `status`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
+`list`, `status`, `doctor`, `run`, `wait`, `trace`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
 `loop` is a supervisor-internal process surface. **Exit codes:** `0` success, `1` failure, and `2`
 invalid usage; `run` can also propagate the invoked agent's non-zero result.
 
@@ -91,7 +95,9 @@ It waits for a wake on the `system_events` ledger — a human request (`message.
 change (`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
 (`agent.invoke.exit`) — then drains the inbox into an `agent run` invocation. An idle wake records
 the hold reason instead of dispatching; with no wake event it still drains every `--poll` ms
-(default `2000`). It runs until `SIGINT` / `SIGTERM`.
+(default `2000`). It runs until `SIGINT` / `SIGTERM`, or until its parent `spur serve` disappears —
+the parent is re-read each poll and a change aborts the loop, so a `SIGKILL`ed serve leaves no
+orphan loop (1088 R2).
 
 ## `wait` - identity-pinned occupant wait (G4 wave 2)
 
@@ -146,8 +152,9 @@ supervisor**: each row carries a trailing status column
 (`running` / `stopped` / `errored` / `unknown`), `pid=<n>` where a process exists, and the member
 session (0897): the session mode plus a shortened resume id (`resume id=3f9c2a1d`), or `-` when the
 member has no recorded session. When `spur self serve` is unreachable, the listing falls back to all
-`stopped` with a stderr warning. `--server <url>`
-(default `http://localhost:3000/api`) targets the supervisor API.
+`stopped` with a stderr warning. `--server <url>` targets the supervisor API; without it the URL is
+this project's serve — the port in the cwd's project-registry entry (`http://localhost:<port>/api`),
+falling back to `http://localhost:3000/api` only when the project has no live entry (1088 R1).
 
 ```bash
 spur agent list --specs
@@ -164,9 +171,77 @@ spur agent status --json     # full objects, session carried whole ({ mode, id }
 
 Reads the same supervisor feed as `list --specs` (liveness **and** session come from
 `GET /api/processes`; the served project's ledger is the source of the session state). An
-unreachable server reports every spec `stopped` with no session. See
+unreachable server reports every spec `stopped` with no session. `--server <url>`
+(default: this project's registry serve port, `http://localhost:<port>/api`; else
+`http://localhost:3000/api` — 1088 R1) targets it. See
 [Member sessions](#member-sessions-g66) for what the modes mean.
 
+## `report` - fleet lifecycle state from a host hook (G73, task 1080)
+
+```bash
+spur agent report --state working --seq 1759665600000000000
+spur agent report --state blocked --seq 1759665600000000000 --spec proj-worker-1 --json
+```
+
+| Flag | Description |
+| --- | --- |
+| `--state <state>` | Lifecycle state: `working` \| `idle` \| `blocked` (required) |
+| `--seq <ns>` | Monotonic report sequence in nanoseconds (required); not greater than the last accepted one → ignored |
+| `--spec <id>` | Member spec id; defaults to `SPUR_SPEC_ID` |
+| `--json` | Machine-readable result (`accepted`, `observation`) |
+| `--json-envelope` | Wrap the JSON in the standard output envelope |
+
+An accepted report writes the cataloged `agent.lifecycle.changed` ledger row — the newest
+accepted row for the member is its current state, so there is no separate state store. The
+dispatch strategy treats `blocked` as unavailable (hold reason `member-blocked`), and the Board
+shows `needs human` on that member.
+
+Exit `2` when `--state`/`--seq` is missing or malformed, or when no member id resolves
+(`SPUR_SPEC_ID` unset and no `--spec`). The `sp` plugin's `agent-lifecycle` host hook calls this
+in the background on `SessionStart` (idle), `UserPromptSubmit` (working), `Notification`
+(`permission_prompt` → blocked) and `Stop` (idle); outside a fleet it makes no call at all.
+
+## `join` / `leave` - guest occupancy (G73 R2/R5, task 1081)
+
+```bash
+spur agent join --role reviewer --json          # id defaults to <role>-g<n>
+spur agent join --role coder --id my-session --json
+spur agent leave --json                          # the guest joined by this session
+```
+
+A guest is a live session that **pulls** work: never supervised, never restarted, addressable by
+concrete id only (role/executor selectors count declared members, so a guest is invisible to them).
+`join` writes an occupant row in `coordination_runs`, claims a `guest:<id>` lease on the shared
+claim table (same TTL/heartbeat semantics as the write slot — R5) and writes
+`.spur/run/guests/<id>.json` so a host Stop hook can recognize its own session without a CLI call.
+`leave`, or lease expiry in the reconciler pass, releases the lease, marks the occupant exited,
+returns its claimed messages to `pending` and removes the record.
+
+| Flag | Description |
+| --- | --- |
+| `--role <name>` | Layer-1 role (`scribe` \| `coder` \| `reviewer` \| `planner`); required for `join` |
+| `--id <id>` | Guest id (defaults to `<role>-g<n>`); colliding with a declared member or a joined guest exits 2 |
+| `--session-id <sid>` | Host session id (defaults to `CLAUDE_CODE_SESSION_ID`) |
+| `--pid <n>` | Process id to record |
+| `--executor <name>` | Executor name to record (informational — a guest is never dispatched to) |
+| `--json` | Machine-readable result |
+
+A guest carrying no executor attestation is never a stage target: `spur agent run --spec <guest-id>`
+is refused (R3), and `requiresCapabilities` stages therefore can never reach one.
+
+## `wait --inbox <id>` - the guest pull primitive (G73 R4)
+
+```bash
+spur agent wait --inbox reviewer-g1 --timeout 540000 --json
+```
+
+Returns `0` as soon as queued inbox work exists for the guest and `1` on timeout or when the id is
+not a joined guest — never a silent hang. Every call heartbeats the guest's lease, so a session that
+keeps looping stays joined; the timeout stays under the Bash tool's ~10-minute limit. The
+`fleet-join` skill loops it (wait → `spur message inbox --agent <id>` → work → `spur message reply`),
+and the `fleet-guest-stop` plugin hook delivers the same messages at a turn boundary on hosts that
+support a blocking Stop hook.
+
 ## `doctor` - readiness check
 
 ```bash
@@ -193,6 +268,31 @@ stderr-clean and carries `capabilities`, `capabilityStale: {verifiedAgainst, det
 normalized `availability` object, and a top-level `usage` per agent row instead. Exit `1` if any
 checked agent is not ready.
 
+## `trace` - one execution record's lineage (1076 R4, ADR-132)
+
+```bash
+spur agent trace <runId>              # the run, its parents, its children
+spur agent trace <rootId> --follow    # poll until every run in the lineage is terminal
+spur agent trace <runId> --json
+```
+
+`trace` reports ADR-132's execution record as one lineage. A node is a run: a workflow run comes from
+the `runs` table, an agent run from `coordination_runs`, and the dispatch edge is
+`coordination_runs.parent_run_id` — set from a workflow dispatch key (`<runId>/<state>`) or the
+inherited `SPUR_RUN_ID`. `trace <runId>` first walks that edge UP to the root and then DOWN to the
+leaves, so any id in the chain yields the whole picture. Each node carries its status, the agent
+session ids recorded for it (`history_run_session`, exact rows only) and its durable stream under
+`.spur/memory/runs/<runId>.md` when one was written. The stream is the record; the supervisor's ring
+buffer is only a live view.
+
+### Flags
+
+| Flag | Purpose |
+| ------ | --------- |
+| `--follow` | Poll until every run in the lineage reaches a terminal status. |
+| `--timeout <ms>` | `--follow` budget (default 600000). On expiry one checkpoint line is printed and the command exits 1; the runs continue. |
+| `--json` | `{ rootRunId, nodes: [{ runId, kind, status, parentRunId, sessionIds, logPath }] }` — root first, depth-first. |
+
 ## `start` - start a supervised process
 
 ```bash
@@ -202,7 +302,9 @@ spur agent start worker-1 --json
 
 Posts to the `spur self serve` supervisor API
 (`POST /api/agents/:id/start`) and prints `started <id> (pid=<n>, status=<s>)`. Requires a
-reachable `spur self serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
+reachable `spur self serve`; `--server <url>` targets it, defaulting to this project's registry
+serve port (`http://localhost:<port>/api`, else `http://localhost:3000/api` when the project has no
+live entry — 1088 R1). Exit `1`
 when the server is unreachable or the start fails.
 
 ## `stop` - stop a supervised process

package/plugins/sp/skills/spur-cli/references/decision.md

@@ -0,0 +1,97 @@
+---
+name: spur-cli-decision
+description: "spur-cli noun reference: operate `spur decision` as the read/serve surface over the decision catalog - list registered decisions, show one served contract (parameters, criteria vocabulary, effective maker), run a decision to a served outcome (never writes a workflow resultFile), and status the catalog layers. Backed by @gobing-ai/ts-ai-decision 0.5.16 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093."
+see_also:
+  - spur-cli
+---
+
+# spur decision - decision catalog surface
+
+`spur decision` exposes the **decision catalog** (ADR-117 trace discipline, task 1092) to agents
+and scripts: discover which decisions exist, inspect one's contract, serve one outcome, and audit
+catalog health. It is a thin transport over `DecisionService` (`packages/app`); the decision hub
+lives in `@gobing-ai/ts-ai-decision`.
+
+**Frozen at exactly four verbs** (`list`, `show`, `run`, `status`) by task 1093's design
+(`docs/design/decision-catalog.md` §3.4) — do not invent additional subcommands.
+
+## Catalog layers
+
+Decisions resolve first-wins across three layers:
+
+| Layer | Root | Notes |
+| ----- | ---- | ----- |
+| `project` | `<cwd>/.spur/decisions/*.yaml` | Highest precedence |
+| `registered` | programmatic catalog registrations | Agents register in-process |
+| `shared` | `decisions/` under the bundled config root | Shipped catalogs (`config/decisions/` in-repo) |
+
+The bundled shared catalog ships `task-triage`, `failure-class`, and `review-failure-class` (all
+`choice` type, param `wbs`). Duplicate ids across layers keep the higher layer; duplicates inside
+one file are a load error.
+
+**Config keys** (under `decisions:` in `config.global.yaml` or project config):
+`paths` (extra catalog folders joined to the registered layer), `maker` (default DecisionMaker
+for every decision point), `makers` (per-decision-id overrides). An unregistered maker name is a
+config error, never a silent fallback (design §3.6).
+
+## Verb map
+
+| Verb | Purpose | Key flags |
+| ---- | ------- | --------- |
+| `list` | Every visible decision: id, type, layer, catalog file, description | `--layer <layer>`, `--json` |
+| `show <id>` | One served contract: type, parameters, criteria, fallback, minConfidence, effective maker + source | `--json` |
+| `run <id>` | Serve one outcome (closed vocabulary; **never writes a resultFile**) | `--param <pairs...>`, `--evidence <files...>`, `--maker <name>`, `--json` |
+| `status` | Layer counts, registered makers, per-decision maker resolution, load errors | `--json` |
+
+All verbs support `--json` (bare payload) and `--json-envelope` (`{ok, data|error}` envelope,
+ADR-091). Failure output for `--json` commands uses the canonical error envelope only under
+`--json-envelope`; plain `--json` keeps the human message on stderr.
+
+**Exit codes:** `status` exits 1 on catalog load errors; `show` exits 1 on unknown id; `list` always
+exits 0 (design §3.4 — load errors surface via `status`).
+
+**Exit contract for `run` (design §3.4):** any backend-observed outcome — low confidence, model
+error surfaced as fallback, declined — is still a **successful serve** (exit 0, envelope carries
+`source`/`confidence` so callers can see why). Exit 1 is reserved for caller mistakes caught
+**before** the backend: unknown id, unknown parameter, missing required parameter, type-invalid
+parameter, unregistered `--maker`, unreadable evidence file.
+
+## Parameters and evidence
+
+`--param k=v` is repeatable and validated against the decision's declared parameters: values for
+`number`/`boolean`/`json` params are parsed accordingly (`json` accepts inline JSON objects);
+string/enum params pass through verbatim. A parameter with no `default` is **required** (hub
+loader derives `required: !hasDefault`). Undeclared keys exit 1.
+
+`--evidence <file>` is repeatable; each file is read, **redacted and bounded to
+`DECIDE_EVIDENCE_MAX_CHARS` (2000 chars)** via the same `redactAndBound` used by workflow
+agent execution. Evidence rides the hub's implicit `instructions` input parameter — it reaches the
+maker through the rendered question, never as a raw input key (the hub rejects undeclared input
+keys). An unreadable evidence file exits 1 before any backend call.
+
+## Effective maker resolution
+
+Makers resolve `flag → config-decision → config-default → catalog-decision → catalog-default`;
+`decision show` reports the effective maker as `{name, source}` with that source precedence
+(operator config outranks the shipped catalog because only the machine owner knows which backends
+exist there). The final `catalog-default` maker is the hub built-in `typesafe` — decisions served
+without a configured backend still produce deterministic closed-vocabulary outcomes, which is why
+`run` is usable in tests and scripts with no model access.
+
+## Examples
+
+```bash
+spur decision list --json | jq -r '.[].id'
+spur decision show task-triage                      # inspect contract before serving
+spur decision run task-triage --param wbs=1093 --json
+spur decision run failure-class --param wbs=1093 \
+    --evidence .spur/run/<runId>-test-output.txt    # redacted evidence -> instructions
+spur decision status --json | jq '.data.errors'     # audit catalog health
+```
+
+## References
+
+- Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface)
+- Hub: `@gobing-ai/ts-ai-decision` 0.5.16 (`DecisionService`, catalog schema, maker registry)
+- App service: `packages/app/src/decision/decision-service.ts`
+- Shipped catalogs: `config/decisions/*.yaml`

package/plugins/sp/skills/spur-cli/references/tasks/verbs.md

@@ -448,3 +448,25 @@ spur task path     <wbs> [--folder] [--json]
 spur task run-link <wbs> [--source <src>] [--run-id <id>] [--json]
 spur task scaffold-tests <wbs> [--file <path>] [--folder] [--json]
 ```
+
+**No `delete` verb — and that is the surface's shape, not an oversight.** The corpus is
+append-only history: a task that is no longer wanted is a *decision*, and the lifecycle already owns
+it. Use
+
+```
+spur task update <wbs> cancelled [--json]      # the in-band terminal; the file stays as the record
+```
+
+Removing the file entirely is reserved for a task that should never have existed (a duplicate WBS, a
+mis-scaffolded capture) — a **corpus repair**, not a lifecycle move. Do it as a tracked deletion so
+the removal itself is auditable:
+
+```
+git rm docs/tasks<N>/<wbs>_<slug>.md
+git commit -m "chore(corpus): drop <wbs> — <why it never existed>"
+```
+
+Check for inbound references before deleting (`grep -rn "<wbs>" docs/ config/ plugins/`, plus any
+`dependencies[]` edge via `spur task list --json`). The `deps remove` verb clears an edge. A deleted
+WBS must not stay referenced: a dangling `dependencies[]` entry is a broken traceability edge, not a
+harmless leftover.

package/plugins/sp/skills/spur-composer/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spur-composer
-description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows and agent specs. Owns workflow catalog selection, the ephemeral→project→shared ladder, the ADR-115 budgets, trace-driven rule tuning, and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, apply doctor proposals."
+description: "Select, compose and tune spur artifacts — tasks, features, rules, workflows, agent specs and project Board modules. Owns workflow catalog selection, the ephemeral→project→shared ladder, ADR-115 budgets, trace-driven rule tuning and applying accepted sp:spur-doctor proposals. Triggers: compose a workflow, tune a rule, add a Board module."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -50,6 +50,7 @@ its own output and never runs a recurring loop — evaluation is the doctor's jo
 | rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
 | workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
 | agent spec | Read through `spur agent list --specs`; specs are materialized from the fleet declaration at serve start | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
+| board module | Declare under `bootstrap.modules`, gated by the serve preflight (§ Board module composition) | [../spur-cli/references/serve.md](../spur-cli/references/serve.md) |
 
 Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.
 
@@ -106,6 +107,31 @@ budgets:
 A new model step in a shared workflow raises its `pipeline-budgets` `modelQueries`; that needs a
 recorded decision before the shared step.
 
+## Board module composition
+
+A project adds its own Spur Board modules (ADR-128) by declaration, never by editing the installed
+package. The contract — the `react`/`iframe` union, the `@gobing-ai/spur/board` type, the Vite
+externals and the frame/trust limits — is owned by
+[downstream Board modules §6](../../../../docs/design/downstream-board-modules.md#6-authoring-guide);
+the user walkthrough is
+[docs/help/how_to_customize_project_modules.md](../../../../docs/help/how_to_customize_project_modules.md).
+Link them, never restate them.
+
+| Step | Action |
+| --- | --- |
+| select | A built-in module or an existing declaration already covers the need → no new module. An app that already runs and permits framing → `type: iframe`. Otherwise → `type: react`. |
+| compose | Add one declaration to the project `.spur/config.yaml` `bootstrap.modules` list. Stage it with `enabled: false` first: it is fully validated (id shape, duplicates, host/retired collisions) but loads no assets. |
+| build | `react` only: the downstream project builds its own ESM entry plus CSS into the declared `directory`, externalizing exactly the `imports` keys of the installed `web/board-runtime.json`. Building the module is the project's code work, not composer's. |
+| gate | Restart `spur self serve`; the preflight fails startup on any declaration, asset or runtime-version error. Confirm the module in `GET /api/board/modules` and open `/board/modules/<id>`. `spur self serve --json` is a dry port probe and does **not** run this preflight. |
+| enable | Flip to `enabled: true`, restart and reload. There is no hot reload. |
+
+- The module is project-owned: it never climbs a shared layer, and it needs no `build:bundle`.
+- Declare only trusted code — importing a `react` entry evaluates it. Spur never starts or proxies an
+  `iframe` app, and a frame the child refuses stays blank by design.
+- Changing a built-in module is internal Board work in the spur repository
+  ([docs/help/how_to_add_a_new_ui_module.md](../../../../docs/help/how_to_add_a_new_ui_module.md)),
+  not a downstream declaration.
+
 ## Rule tuning loop
 
 Start from trace evidence, never from a guess:

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -40,8 +40,9 @@ each would be scope creep for one-liner procedures.
 
 > **`dev-review-session`** is not in this table. It is a thin `Skill()` wrapper over
 > **`sp:session-review`** for an immediate, inline review of the active conversation. Report-only
-> is the default; `--triage` applies pure-doc / one-to-two-line fixes and files remaining actionable
-> findings as implement-ready tasks through the task CLI. It launches no workflow or agent and
+> is the default; `--fix auto` (alias `--triage`) applies pure-doc / one-to-two-line fixes and files
+> remaining actionable findings as implement-ready tasks through the task CLI; `--fix all` fixes
+> every actionable finding inline and files none. It launches no workflow or agent and
 > imports no history. Use it before the active session ends; use history-anatomy for ended sessions,
 > cross-agent windows, trends, or quantitative forensics.
 
@@ -72,19 +73,19 @@ each would be scope creep for one-liner procedures.
 | 2   | review     | `dev-review`        | `Skill()`         | `sp:code-verification` (`review`) + `sp:functional-review` + `sp:code-improvement` | `[--tasks <selector> \| --feature <id>[,<id>] \| --scope <path>[,<path>]] [--agent <inline\|auto\|name>] [--focus <dims>] [--triage] [--worktree [<name>]] [--auto]`                                                                                              |
 | 3   | verify     | `dev-verify`        | `Skill()`         | `sp:code-verification` (`verify`)                                                  | `<wbs> [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--skip-shippable]`                                                     |
 | 3a  | verifyall  | `dev-verifyall`     | `Skill()` → agent | `sp:spur-dev` (`verifyall`)                                                        | `--tasks <selector> [--feature <id>] [--agent <inline\|auto\|name>] [--fix <none\|blockers-first\|all>] [--focus <lens>] [--bdd] [--auto] [--force] [--next] [--json] [--skip-shippable] [--worktree [<name>]]` |
-| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]]`                                                                                              |
+| 4   | run        | `dev-run`           | `Skill()`         | `sp:spur-dev` (`run` / `implement`)                                                | `<wbs> [--mode <full\|implement>] [--agent <inline\|auto\|name>] [--auto] [--next] [--wrap] [--continue] [--worktree [<name>]] [--no-summary]`                                                                                              |
 | 5   | refine     | `dev-refine`        | `Skill()`         | `sp:spur-dev` (`refine`)                                                           | `<wbs> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--next]`                                                                           |
 | 5a  | refineall  | `dev-refineall`     | `Skill()`         | `sp:spur-dev` (`refineall`)                                                        | `--feature <id> \| --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard\|ready>] [--agent <inline\|auto\|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]` |
 | 6   | plan       | `dev-plan`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<description>" [--feature <id>] [--parent <feature-id>] [--skip-design] [--agent <inline\|auto\|name>] [--auto]`                                                                   |
 | 7   | docs       | _(no thin wrapper)_ | `Skill()`         | `sp:doc-evolve`                                                                    | `"<change description>"`                                                                                                                                                                               |
-| 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                                    |
+| 8   | changelog  | `dev-changelog`     | `inline`          | git log + conventional-commit grouping                                             | `[<file>] [--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                            |
 | 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>]`                                                                                                                            |
 | 10  | fixall     | `dev-fixall`        | `inline`          | lint + test fix loop                                                               | `[<validation-command>] [--max-retry <n>] [--scope <path>] [--gate-log <path>] [--findings <anchors>]`                                                                                                 |
 | 11  | handover   | `dev-handover`      | `inline`          | structured doc generation                                                          | `"<blocker description>"`                                                                                                                                                                              |
 | 11a | job-dump   | `dev-job-dump`      | `Skill()`         | `sp:spur-dev` (`job-dump`) | `--file <path>` |
 | 11b | job-resume | `dev-job-resume`    | `Skill()`         | `sp:spur-dev` (`job-resume`) | `--file <path>` |
 | 12  | brainstorm | `dev-brainstorm`    | `Skill()`         | `sp:brainstorm` (`dev-brainstorm`)                                                 | `<topic> [--depth <basic\|detailed\|comprehensive>] [--options <n>] [--agent <inline\|auto\|name>] [--skip-discovery] [--wayfind] [--task [<feature-id>]] [--feature [<parent-id>]] [--next]`          |
-| 13  | runall     | `dev-runall`        | `Skill()` → agent | `sp:spur-dev` (`runall`) → `sp:super-planner`                                      | `--tasks <selector> [--feature <id>] [--mode <sequential\|parallel>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]]`                      |
+| 13  | runall     | `dev-runall`        | `Skill()` → agent | `sp:spur-dev` (`runall`) → `sp:super-planner`                                      | `--tasks <selector> [--feature <id>] [--mode <sequential\|parallel>] [--keep-going] [--auto] [--agent <inline\|auto\|name>] [--json] [--wrap] [--next] [--continue] [--worktree [<name>]] [--no-summary]`                      |
 | 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json]`                                                                          |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
@@ -155,13 +156,28 @@ must not be changed without updating the backing skill.
 ### 4. run
 
 - **Purpose:** Run a task through the execution pipeline (full) or execute a single pipeline step (implement).
-- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
+- **Inputs:** `<wbs>` (required). `--mode <full|implement>` selects the execution mode. `implement` invokes `sp:code-implementation` inline by default. Interactive `full` resolves the selector uniformly (task 0687): omit ≡ explicit `--agent inline`; full mode reads `task-pipeline.yaml` and drives its actions/guards in the host session — host-controlled and non-subprocess, with 0508 eligibility applying to the resolved-inline selector (eligible `agent.run` stages dispatch once to a native subagent, host fallback)). `--agent auto`, a name, or headless invocation launches the workflow subprocess. `--agent <inline|auto|name>` selects the execution surface (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips the HITL approve gate / confirmations and propagates down the `--next` chain. `--next` controls chaining only and never changes the mode; a pipeline implement stage must invoke `/sp:dev-run <wbs> --mode implement`. On implement success with `--next`, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`. On a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` section must state that explicitly and the verify verdict will record the scope. `--worktree [<name>]` runs the full pipeline inside an isolated git worktree (create or reuse; FF-merge on success, retain on failure) — the batch lifecycle in [execution-batch.md § Worktree isolation](execution-batch.md#worktree-isolation---worktree-name) applied to a batch of one; rejected with `--mode implement`. `--no-summary` skips the [execution summary](#execution-summary) printed after a full-mode run. `--wrap` hands off to `/sp:dev-wrap <wbs>` after the main step; the `--agent` selector is preserved into that handoff when supplied (omission remains omission), and the wrap hop reports its own trigger-3 subprocess override per the wrap contract.
 - **Backing:** `sp:spur-dev` skill — `run` operation for the full pipeline (the spine drives it); `sp:code-implementation` competency skill for the implement step (the spine dispatches to it).
 - **Modes:**
   - **`full`** (default): Drive the full pipeline — precheck → implement → test → review → approve(HITL) → verify → record → done. Interactive omit/inline uses [inline-pipeline-driver.md](inline-pipeline-driver.md) (host-controlled; eligible stages may use a native subagent); explicit/headless executor selection invokes `spur workflow run task-pipeline.yaml --vars '{"wbs":"<wbs>"}'` (with `profile: auto` when `--auto`). Both monitor/surface HITL and preserve the YAML gates. `--next` never changes this mode.
   - **`implement`** (explicit `--mode implement` only): Execute only the implement step. Read the task's `## Requirements` / `## Design` / `## Plan`, write the code that satisfies them, author the `## Solution` change-map section (file:line + what/why per changed file) via `spur task update <wbs> --section Solution --from-file`. This is the implement step the pipeline calls — it is NOT the pipeline driver. With `--next`: on success, transition `todo → wip → testing` through the FSM (guards honored — no `--no-lifecycle`) + chain to `/sp:dev-verify <wbs> --auto --next`; on a guard failure, stop as review-pending. **Partial-deliverable rule:** if the task ships only part of its requirements (e.g. an R1/R2 split with the rest in a follow-up task), the `## Solution` and `## Review` sections MUST carry a `⚠️ PARTIAL` marker naming the deferred part and the follow-up WBS — see `plugins/sp/commands/dev-run.md` → "Section ownership".
 - **Delegation:** `Skill(skill="sp:spur-dev", args="run-inline $ARGUMENTS")` for interactive full omit/inline (resolved-inline semantics, task 0687); `Skill(skill="sp:spur-dev", args="run $ARGUMENTS")` for explicit/headless full mode; `Skill(skill="sp:code-implementation", args="$ARGUMENTS")` for implement mode.
 
+#### Execution summary
+
+Default on for full-mode `dev-run` and `dev-runall`; `--no-summary` skips it. At command start record
+`SINCE=$(date -u +%Y-%m-%dT%H:%M:%SZ)`. When the run settles (done, failed or paused), write each run's
+`spur workflow progress <run-id> --json` to `$TMPDIR/<run-id>-progress.json` and print, verbatim under an
+`### Execution summary` heading:
+`node "$(superskill script path sp run-summary.mjs)" --since "$SINCE" --progress <file> --markdown`
+(`dev-runall`: one `--progress <wbs>=<file>` per attempted run). One file renders one row per state visit;
+several render one row per run; a `driver overhead` row carries host work outside every stage window so rows
+sum to `Total` (omitted when parallel runs overlap). Columns: Stage | Status | Time | Wait | Tool calls |
+Token (total / non-cached) — total counts every input class plus output; non-cached drops cache reads.
+Stage windows with no host transcript record (subprocess executors) render `n/a`, never 0. The summary is
+reporting only: a failure prints `Execution summary: n/a (<reason>)` and never changes the run's outcome.
+Not printed for `--mode implement` (no workflow run).
+
 ### 5. refine
 
 - **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design, and is also the path for **evaluating and correcting an existing task** — a review-triage filing, a stale backlog capture, or any task whose claims and proposed fixes may no longer hold.
@@ -429,7 +445,7 @@ gate commands, pending questions and approval requirements.>
 ### 13. runall
 
 - **Purpose:** Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via `task-pipeline.yaml`, inspect verdicts, apply the failure policy, emit a batch report.
-- **Inputs:** `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`, or `ready`). `--mode <sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset per `execution-batch.md` § Parallel Execution). `--keep-going` skips a failed task's in-batch dependents and continues independents (default halts on first failure). `--auto` sets `profile=auto` on each per-task run (skips the HITL approve gate). `--feature <id>` is sugar for `--tasks feature:<id>`; when the effective selector is feature-derived, the batch runs `spur feature check <id> --strict --json` **once** before task resolution — a non-zero strict check aborts with verdict `aborted`, zero attempted tasks, and the structured findings (task 0510 R2); scoped: `L4.scenario-unverified` (expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort — any other strict error aborts. Explicit WBS/status/`ready` selectors add no feature check. The orchestrator loop itself continues in this session; interactive sequential omit/`inline` uses the host driver — host-controlled with eligible `agent.run` stages dispatching once to a native subagent and host fallback (task 0508) — while `--agent auto`/a name, parallel mode, and headless invocation keep the isolated per-task workflow subprocess boundary. `--agent <inline|auto|name>` pins the executor for the per-task stages (see [SSOT](cross-cutting.md#inline-default-execution-surface)); the value crosses into per-task `vars.agent`, not the orchestrator. `--json` emits the report as JSON. `--wrap` triggers `wrapup-pipeline.yaml` **once for the batch** over the `done` subset only (execution-batch.md Step 6: `vars.feature` only when every frozen task is `done`/`cancelled`; empty done subset skips with a reason), `--next` chains each task to terminal status then runs the same batch-once wrap, `--continue` resumes from checkpoint.
+- **Inputs:** `--tasks <selector>` (required — explicit WBS list, status pseudo-list, `feature:<id>`, or `ready`). `--mode <sequential|parallel>` (default `sequential`; `parallel` fans out a proven-independent subset per `execution-batch.md` § Parallel Execution). `--keep-going` skips a failed task's in-batch dependents and continues independents (default halts on first failure). `--auto` sets `profile=auto` on each per-task run (skips the HITL approve gate). `--feature <id>` is sugar for `--tasks feature:<id>`; when the effective selector is feature-derived, the batch runs `spur feature check <id> --strict --json` **once** before task resolution — a non-zero strict check aborts with verdict `aborted`, zero attempted tasks, and the structured findings (task 0510 R2); scoped: `L4.scenario-unverified` (expected pre-run state of any not-yet-run feature) is reported verbatim but does not abort — any other strict error aborts. Explicit WBS/status/`ready` selectors add no feature check. The orchestrator loop itself continues in this session; interactive sequential omit/`inline` uses the host driver — host-controlled with eligible `agent.run` stages dispatching once to a native subagent and host fallback (task 0508) — while `--agent auto`/a name, parallel mode, and headless invocation keep the isolated per-task workflow subprocess boundary. `--agent <inline|auto|name>` pins the executor for the per-task stages (see [SSOT](cross-cutting.md#inline-default-execution-surface)); the value crosses into per-task `vars.agent`, not the orchestrator. `--json` emits the report as JSON. `--wrap` triggers `wrapup-pipeline.yaml` **once for the batch** over the `done` subset only (execution-batch.md Step 6: `vars.feature` only when every frozen task is `done`/`cancelled`; empty done subset skips with a reason), `--next` chains each task to terminal status then runs the same batch-once wrap, `--continue` resumes from checkpoint. `--no-summary` skips the [execution summary](#execution-summary) printed after the batch report (one row per attempted run).
 - **Three orthogonal axes (do not confuse):** `--keep-going` = batch failure policy (halt vs skip dependents); `--continue` = resume from checkpoint against the batch's original frozen identity (execution-batch.md § Batch continuation, task 0919); `--next` = per-task lifecycle chaining (advance status on a verdict — `dev-verify`/`dev-verifyall` only). `routing-table.md` offers `--continue` and `--next` as competing options for the same situation only when the batch was interrupted mid-run; otherwise they address different problems.
 - **Backing:** `sp:spur-dev` skill, `runall` operation → delegates the driver loop to the **`sp:super-planner`** agent (the batch orchestrator).
 - **Behavior:** The orchestrator reads [execution-batch.md](execution-batch.md) and drives: resolve selector → freeze set → topo-sort by `dependencies[]` (Kahn, WBS-ascending tie-break; cycle aborts) → resolve out-of-set deps by status (done → allow, else → block subtree) → run each task via `spur workflow run task-pipeline.yaml --async` + `spur workflow trace` polling → inspect terminal state + `.spur/run/<wbs>-verdict.json` → stop-the-batch default or `--keep-going` subtree skip → emit batch report. Per-task pipeline is invoked **verbatim** — no new FSM, no step edits. `--auto`/`--agent` are the only flags that cross the orchestrator→pipeline boundary (both into per-task `--vars`).
@@ -519,7 +535,7 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 ### 8. changelog
 
 - **Purpose:** Generate a structured changelog from git commits between two refs.
-- **Inputs:** `--since <ref>` (default: last tag), `--until <ref>` (default: `HEAD`), `--version <ver>` (default: auto-detect from latest tag).
+- **Inputs:** `<file>` (optional positional, e.g. `CHANGELOG.md`; default: stdout), `--since <ref>` (default: last tag), `--until <ref>` (default: `HEAD`), `--version <ver>` (default: auto-detect from latest tag).
 - **Backing:** `inline` — git log + conventional-commit grouping.
 - **Behavior:**
   1. Resolve `--since`: if not given, use the most recent tag (`git describe --tags --abbrev=0`). If no tags exist, use the repo root commit.
@@ -529,14 +545,10 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
   5. Format as markdown:
      - `keepachangelog` (default): `## [<version>] - <date>` header, then category headings per the keepachangelog convention — `### Added` / `### Fixed` / `### Changed` / `### Removed` / `### Other` — mapped from conventional-commit types.
      - `simple`: flat bulleted list grouped by type heading (`### feat`, `### fix`, …).
-  6. Print the changelog to stdout. If the operator wants it in `CHANGELOG.md`, they redirect or paste.
-  7. Verify the emitted section against git and close with one line: `Verification: HIGH|MEDIUM|LOW — <first failing check and deviation, or 'all checks passed'>`.
-     - **Coverage** — bullet count equals the commit count in `<since>..<until>`, and every short hash appears exactly once.
-     - **Mapping** — per-category bullet counts match the conventional-type counts (`feat`→`Added`, `fix`→`Fixed`, other recognized types→`Changed`, unrecognized→`Other`).
-     - **Header** — `[<version>] - <date>` matches the resolved `--version` (or detected tag) and the header date.
-     - **Citations** — a bullet that asserts API/library behavior or a version/dependency claim beyond its commit summary carries a source citation: an official docs URL, or a local `path:line` verified against the installed manifest/lockfile (`package.json`, lockfile, or the cited file). A commit hash is provenance for what shipped, not a citation for what the API/library does; an uncited claim is flagged inline on the bullet (`(uncited: <claim>)`) rather than silently dropped.
-     - **HIGH** — all checks pass with every API/library claim cited. **MEDIUM** — coverage intact but mapping or header deviates, or at least one API/library claim lacks a source citation. **LOW** — coverage broken (missing/duplicate hashes), the range cannot be reconciled against git, or a citation fails verification (dead URL, or a `path:line` that does not support the claim).
-- **Invariants:** Never mutates `CHANGELOG.md` directly — the command surface is stdout-only; writing it to a file (e.g. appending to `CHANGELOG.md`) is the operator's redirect choice, never the command's.
+  6. Emit: with `<file>`, insert the section into that file above its newest `## [` release heading (or after its title when none exists) and touch nothing else in the file; without `<file>`, print it to stdout.
+  7. Self-check before emitting: every short hash in `<since>..<until>` appears exactly once. Fix any miss or duplicate; do not report a verdict.
+  8. Reply in at most three lines: the range, bullet counts per category, and the output target.
+- **Invariants:** Output is derived from `git log` only. No quality gates — no lint/test/`spur-check`/rule runs, citation or manifest lookups, confidence ratings, or edits beyond the one inserted section. The file is left uncommitted.
 
 ### 9. gitmsg
 

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -424,7 +424,8 @@ one or more tasks sit on an operator question (escalate, 0933) or an approval ga
 (cycle / unknown selector) — emit a structured report. The report is the orchestrator's sole
 output; it does not mutate the corpus (the pipeline's `record` step already wrote per-task
 results). A `paused` task is non-terminal — the report marks it `paused` (never `done`) and names
-the resume command.
+the resume command. Unless `--no-summary`, follow it with the measured
+[execution summary](dev-operations.md#execution-summary), one `--progress <wbs>=<file>` per attempted run.
 
 ```
 ## Batch Report — <selector>
@@ -744,6 +745,34 @@ existing batch loop (Steps 1–5) with the worktree as process cwd. `spur workfl
 from the process (`apps/cli/src/commands/workflow.ts:124`), so no CLI change is needed — `cd` into
 the worktree directory before launching the loop.
 
+#### Evidence staging before the first task (create and reuse mode)
+
+`.spur/memory/evidence/` and `.spur/run/` are **untracked per-tree** planes, so a fresh worktree
+starts with neither while the invoking tree holds every earlier task's verdict. Both
+`preflightFeature` (`plugins/sp/scripts/wrapup-steps.ts` → `spur feature check --strict --as done`
+with cwd = the worktree) and `runMetrics` resolve verdict artifacts relative to the tree they run
+in, so without this step an already-`done` linked task reads as missing evidence
+(`L4.evidence-not-recoverable`, `L4.scenario-unverified`) and its metrics row degrades to
+`UNKNOWN`.
+
+Stage the invoking tree's verdict artifacts into the worktree **before the first task runs** —
+from the invoking tree (cwd), with `$WT` the resolved absolute worktree path. `cp -n` is
+load-bearing: reuse mode may be re-entering a tree that already owns divergence-checked evidence,
+and this step must never clobber it. Only `*-verdict.json` travels in each direction; receipts and
+other scratch artifacts are not staged, so WT-4a's identity classification is unaffected.
+
+```bash
+# Run from the INVOKING tree; $WT is the worktree (create- or reuse-mode) absolute path.
+for d in .spur/memory/evidence .spur/run; do
+  mkdir -p "$WT/$d"
+  for f in "$d"/*-verdict.json; do [ -f "$f" ] && cp -n "$f" "$WT/$d/"; done
+done
+```
+
+The position relative to the dependency install is immaterial (this is a plain copy into an
+untracked plane); the position relative to the **first task** is not — a preflight or metrics read
+that runs before this step sees an empty evidence plane.
+
 #### Name resolution (`--worktree <name>`)
 
 <a id="name-resolution---worktree-name"></a>
@@ -988,8 +1017,10 @@ if [ -n "$FINAL" ]; then
 fi                                           #   NO prune/remove/branch delete
 # Pre-removal evidence assertion (task 1067 R1, E71 enforcement): refuse to remove the
 # worktree while it still owns evidence absent from (or divergent from) the invoking tree —
-# the D63 landing skipped persist-out and silently lost verdicts + receipts. Task-file
-# WBSes / run ids ride the same TASK_FILE_ARGS resolved for WT-4a (run ids: --run-id <id>).
+# the D63 landing skipped persist-out and silently lost verdicts + receipts. WBSes ride the
+# same TASK_FILE_ARGS resolved for WT-4a; run ids are a separate `--run-id <id>` per run and
+# belong to THIS check only — `inline-run-setup.ts --persist-out` accepts `--from` and
+# `--task-file` alone and exits 2 on `--run-id` (1089 driver note).
 CHECK_SCRIPT=plugins/sp/scripts/persist-out-check.ts; [ -f config/plugin-scripts.json -a -f "$CHECK_SCRIPT" ] || CHECK_SCRIPT="$(superskill script path sp persist-out-check.mjs 2>/dev/null)"
 bun "$CHECK_SCRIPT" --from "$WT_PATH" "${TASK_FILE_ARGS[@]}" \
   || { echo "WT-4 halt: worktree evidence would be abandoned - persist-out missing or stale (WT-5)" >&2; write_marker retained; exit 1; }
@@ -1179,16 +1210,42 @@ ordered divergence recipe, run by the operator — the driver never merges, reba
 conflicts itself. Other halt causes (task failure, HITL pause) keep the hint as printed:
 
 ```
-# 1. integrate as a merge commit — never a rebase; task evidence cites the branch's commit SHAs
-git checkout <base-ref> && git merge --no-ff --no-commit <branch>
+# 1. decide whether conflicts need resolving FIRST, because that decides the merge form:
+#      git merge-tree $(git merge-base <base-ref> <branch>) <base-ref> <branch> | grep -q '^<<<<<<<' \
+#        && echo "conflicts — use the two-phase form below" || echo "clean — use the atomic form"
+#
+# 1a. CLEAN (the common case): integrate as ONE atomic merge commit. Never a rebase — task
+#     evidence cites the branch's commit SHAs. This is the file's sanctioned merge commit.
+#     Do NOT split this into a two-phase merge + commit when nothing needs resolving: that spans
+#     the whole gate run, and anything in that window that touches the repository's git state
+#     (a test, a hook, a tool invocation) discards MERGE_HEAD silently. The failure is invisible
+#     until the history is read — it produced a single-parent commit in run ada5a36c (task 1090),
+#     which then needed an extra empty ancestry merge to repair. A cheap probe could not
+#     reproduce it (MERGE_HEAD survived `bun run lint`, the rule preset and a test-file subset),
+#     so the cross-command dependency is removed rather than diagnosed.
+git checkout <base-ref> && git merge --no-ff -m "<prepared message>" <branch>
+
+# 1b. CONFLICTING: the two-phase form is correct here, because the resolution work must land
+#     between the merge and the commit. Everything in steps 2–4 belongs to this branch only.
+#     A divergent branch cannot fast-forward, so the merge flag from 1a is not needed here.
+#     git checkout <base-ref> && git merge --no-commit <branch>
 # 2. resolve source conflicts by hand; generated files are then regenerated with the project's
 #    generator, never hand-merged
 #    (this repo: bun run build:plugin-lib && bun run --filter @gobing-ai/spur build:bundle)
 # 3. stage every resolved path and regenerated bundle (git add …) — an unmerged or
 #    unstaged path makes step 5 abort
 # 4. run qualityGateCmd once, after ALL conflicts are resolved
-# 5. commit the merge with the prepared message file
-git commit -F <message-file>
+# 5. commit the merge with the prepared message file — CHECK THE PARENTS FIRST (step 5a)
+#    git commit -F <message-file>
+#
+# 5a. ALWAYS verify the merge really is a merge before treating it as landed:
+#       git log -1 --format='%h parents=%p'   # must print TWO parents
+#     One parent means MERGE_HEAD was lost somewhere between steps 1 and 5 — the content is on
+#     the base ref but the branch is not an ancestor, so `git branch -d` would refuse and the
+#     retained worktree's provenance would not be readable from the base ref. Recover by
+#     re-running step 1a against the already-landed tree (a content-free merge commit restores
+#     ancestry).
+
 # 6. persist evidence out (WT-4a), then WT-4b/4c cleanup, and set the marker to merged
 inline-run-setup --persist-out --from <worktree> --task-file …
 ```

package/plugins/sp/skills/spur-dev/references/execution-workflow.md

@@ -163,6 +163,20 @@ The pipeline (`kind: state-machine`) runs the work loop:
 precheck → implement → test [→ test-fix → test-recheck] → review → approve(HITL) → verify → record → done
 ```
 
+Two branches reach the bounded repair hop, not one (session finding after 1088):
+
+- `test`/`test-recheck` FAIL → `test-fail-triage` (0943's failure-class router) → `test-fix`;
+- `review` without a `Verdict: PASS` in its answer → `review-fail-triage` (the review-side twin) →
+  `test-fix`, bounded by the SAME `qualityGateMaxFixAttempts` counter. A FAIL review therefore has
+  an on-graph, bounded path to remediation instead of dead-ending the run, and the fix re-enters
+  quality → review → verify on a freshly captured proof digest.
+
+The completion gate also reads the verifier's confidence (session finding after 1088): the verify
+answer's `Confidence: HIGH|MEDIUM|LOW` line reaches the verdict artifact, and both `verify → record`
+and `record → done` refuse a `LOW` (or absent) level unless the run was launched with
+`--vars '{"ackLowConfidence":"true"}'`. A PASS the verifier would not stand behind is an operator
+risk decision, so it takes an operator acknowledgement — not a silent certification.
+
 Agentic steps use the pure slash inputs declared by each YAML `agent.run` action (ADR-043). The
 workflow engine dispatches them; the interactive driver invokes their backing skills in-session.
 The `test` hop is primarily