@gobing-ai/spur 0.4.0 → 0.4.1

package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md

@@ -19,6 +19,17 @@ the interpreter and trace instructions must match. Never hand-edit the installed
 
 **Retirement criterion (0755 R5, D8 decision D7):** the per-task interpreter retires once the engine covers per-task execution for `/sp:dev-runall` with real terminal runs **and** the parity check (this doc's documented action/guard set ≡ the resolved action/guard set of every `.spur/workflows/*.yaml`) is green. Recording the criterion is part of this task; acting on it is not — that is a separate A3-gate decision.
 
+## Driver state checklist (re-read this after a compaction)
+
+- **Run id** — the run row `inline-run-setup` persisted (`.spur/run/<run-id>-inline-setup.json`
+  sidecar, `.spur/memory/runs/<run-id>.md` + `.state.json`); never re-derive it from the transcript.
+- **Markers under `.spur/run/`** — `<run-id>-inline-setup.json` (frozen invocation identity),
+  `<run-id>-tree-start.json` (commit-guard fingerprint), `<wbs>-verdict.json` (per-stage verdict),
+  `<wbs>-question.md` / `<wbs>-escalation.md` (operator pause), `<run-id>-event-trace.md`.
+- **Re-read per state** — this file (Run setup → YAML interpreter → Record & done),
+  [structured-trace-emission.md](structured-trace-emission.md) at the first trace event.
+- **Authoritative state** — the run record and verdict artifacts, never the host todo list.
+
 ## Supported action and guard set (0755 R2 parity contract)
 
 The action and guard kinds this driver implements. The parity check
@@ -51,7 +62,7 @@ command, skill, script, or second workflow.
 
 **Inline HITL defer semantics (0911):** bundled pipeline human gates ship `decision: {mode:
 never}`, so the inline driver always prompts the operator for those gates regardless of
-`workflow.hitlDecisionMaker` — the decision policy never answers inline pipeline gates. A local
+`workflows.hitlDecisionMaker` — the decision policy never answers inline pipeline gates. A local
 workflow override (`.spur/workflows/*.yaml`) may declare `mode: evidence`, but the driver does
 not claim full inline parity for the DecisionMaker path: evidence-mode auto-answering inside the
 inline driver is an explicit non-goal (subprocess runs own that behavior). No hot reload: config
@@ -59,16 +70,18 @@ and YAML changes require restarting the invoking process.
 
 ## Run setup
 
-**Shared startup contract (task 0814 R1/R3/R4/R6/R7).** The order is load-bearing: publish a compact
-**bootstrap checklist** immediately (host-preparation rows, never copied workflow states); run quick
-deterministic readiness (admission, not an implementation certificate) before any isolation; when
-`--worktree` is valid, create/adopt and switch to the execution tree; then publish the **workflow
-inventory** (the CLI todo projection) — and only then read the full YAML for comprehensive/model work.
-Comprehensive checks stay at their owning boundaries and run after the plan is visible and after
-isolation when requested (R7); quick readiness and plan projection dispatch zero models and execute
-zero workflow actions (R8). Use the stable label helpers
-(`columnLabel` / `buildStepLabels` / `labelChild` in `packages/app/src/workflow/step-reporter.ts`) for
-the human/native presentation layer — labels are display addresses only, never an execution key.
+**Shared startup contract (task 0814 R1/R3/R4/R6/R7; publish-first 1105 R1).** The order is
+load-bearing: publish the **generated plan** first — resolve the selected workflow through the same
+project/bundled resolver as execution, run `spur workflow show <resolved-file> --no-logo --format
+todo --json`, and publish the `.plan` rows verbatim (the projection reads the definition and executes
+nothing, so it is safe before readiness and isolation); run quick deterministic readiness (admission,
+not an implementation certificate) next; when `--worktree` is valid, create/adopt and switch to the
+execution tree; then bind the published plan to the run's persisted `__definitionDigest` — and only
+then read the full YAML for comprehensive/model work. Comprehensive checks stay at their owning
+boundaries and run after the plan is visible and after isolation when requested (R7); quick readiness
+and plan projection dispatch zero models and execute zero workflow actions (R8). Labels come from the
+projection (or `columnLabel` in `packages/app/src/workflow/step-reporter.ts` for the `steps[]`
+fallback) — labels are display addresses only, never an execution key.
 
 1. Resolve the command inputs, `--auto`, and any explicit `--vars` — **without reading the selected
    YAML yet**. An explicit non-inline executor selection chooses the subprocess workflow path.
@@ -93,6 +106,20 @@ the human/native presentation layer — labels are display addresses only, never
      || { echo "inline run setup failed closed — checker not found; run 'superskill install sp --marketplace gobing-ai/spur'" >&2; exit 1; }
    ```
 
+   **Commit fingerprint (1129 R1).** Fingerprint the tree the task commit will land in — before the
+   first task write — because Record & done stages through this snapshot, so a concurrent writer's
+   file cannot ride into the task commit. The artifact is cwd-relative under `.spur/run/` (gitignored
+   per tree), so the snapshot and the commit it guards must name the SAME tree: without `--worktree`
+   take it here in the setup window; with `--worktree` take it immediately **after step 7's
+   isolation, from the worktree root** (still before the first task write) — a snapshot taken here
+   would land in the invoking tree, and the worktree's commit would find none (1129 review N1).
+
+   ```bash
+   RUN_ID="<marker-id>"   # the WT-3 marker's id (execution-batch.md), or the run id allocated at setup
+   GUARD=plugins/sp/scripts/commit-guard.ts; [ -f config/plugin-scripts.json -a -f "$GUARD" ] || GUARD="$(superskill script path sp commit-guard.mjs 2>/dev/null)";
+   bun "$GUARD" start --run "$RUN_ID"     # <this tree>/.spur/run/$RUN_ID-tree-start.json = { head, dirty[] }
+   ```
+
    The delegate uses the source app service when the SPUR_BIN chain identifies a checkout;
    otherwise it loads the generated application bundle shipped with the plugin. Both setup paths
    obtains the selected definition from the existing CLI `workflow show --format todo --json`
@@ -128,10 +155,21 @@ the human/native presentation layer — labels are display addresses only, never
    `session` and the Codex key `session_id` (in that order). If neither is available, allocate
    `host-session-<run-id>` and record that fallback in the log; provenance must never be blank or
    guessed from an executor subprocess.
-5. **Publish the bootstrap checklist (R1).** Render host-preparation rows into the host todo list
-   before any expensive check: `A, Quick readiness`, `B, Prepare Git`, `C, Publish workflow plan`,
-   `D, Comprehensive checking`. These are host preparation, never copied workflow states; they are
-   not silently reassigned to unrelated workflow states when the workflow view later appears.
+5. **Publish the generated plan (R1, 1105) — the run's first action.** Run `spur workflow show
+   <resolved-file> --no-logo --format todo --json` and publish the projection into the host todo list
+   before any expensive check:
+   - **Annotated workflow (the normal case):** publish every `.plan` row's `text` **verbatim** —
+     `A Prepare`, `A1 Quick readiness`, `A2 Prepare Git`, `A3 Publish plan`, `B Implement`, … — in
+     plan order. Never hand-write rows, never copy the YAML state table into prose, and never
+     renumber: the labels carry identity.
+   - **Unannotated workflow (`.plan` is `null`):** publish the flat `steps[]` inventory in
+     declaration order with `columnLabel` labels and their `initial` / `terminal` / `failure` /
+     `pause` / `loopBack` / `conditional` markers. Never re-derive this list from the YAML.
+   - **No workflow plan at all** (skill-only refine/verify batches): keep the existing host
+     preparation rows; do not fabricate a workflow YAML.
+
+   Publishing executes nothing, so it safely precedes readiness and isolation, which keep their
+   existing order below.
 6. **Quick deterministic readiness (R2), before isolation.** Evaluate `quickReadiness` from
    `plugins/sp/scripts/batch-preflight.ts` with the operation, status, filtered-set size, the
    matrix-selected required/present sections, and content-policy findings. Record the outcome
@@ -146,15 +184,12 @@ the human/native presentation layer — labels are display addresses only, never
    inherited**: a host shell call starts in an arbitrary directory and carries no cwd from the
    previous call, so every later call runs inside the **Per-call execution-tree pin** protocol
    below (task 1058), which consumes the identity confirmed here.
-8. **Publish the workflow inventory (R4), BEFORE reading the YAML.** Resolve the selected workflow
-   through the same project/bundled resolver as execution and run
-   `spur workflow show <resolved-file> --no-logo --format todo --json`. Validate the projection with
-   `parseWorkflowInventory` and bind it to the run's persisted `__definitionDigest` with
+8. **Bind the published plan to the run digest (R4) — plan row A3.** Validate the step-5 projection
+   with `parseWorkflowInventory` and bind it to the run's persisted `__definitionDigest` with
    `assertInventoryIdentity` — a drift or projection failure stops the run before any
-   comprehensive/model work, never executing with a misleading plan.
-   - **Layer 1** = that projection's `steps[]`: the declared state inventory in declaration order
-     with `initial` / `terminal` / `failure` / `pause` / `loopBack` / `conditional` markers. Mark
-     the active state. Never re-derive this list from the YAML.
+   comprehensive/model work, never executing with a misleading plan. The A rows published at step 5
+   track this setup order: A1 = quick readiness (step 6), A2 = Git/isolation (step 7), A3 = this
+   binding; mark each row completed as its step settles.
 9. **Read the selected YAML and overlay its `vars` defaults** with the invocation values. Compare the
    resolved definition identity against the bound `__definitionDigest`; a mismatch is identity drift
    and fails closed (step 8 already caught projection-side drift; this re-checks the same definition
@@ -176,15 +211,25 @@ the human/native presentation layer — labels are display addresses only, never
      ended 0/11 with precheck and implement still open).
    - **Source of truth** = the CLI projection for layer 1; the YAML read here for layer 2.
      Never hand-copy or hand-derive the state list into the driver, a command, a skill, or a script.
-   - **Stable labels (task 0814 R5).** Top-level declaration indexes map to A, B, … Z, AA, AB …;
-     visible children restart numbering under their parent (A1, A2, B1 …). Labels never replace the
-     canonical step id, and are re-derived identically on retry/resume against the same definition.
-   - **Truthful progress (task 0814 R6).** Publish pending/active state before the visible item
-     starts, then update it immediately after the observed item completes and before the next item
-     starts. Keep completed, skipped, failed, blocked, paused, and unattempted outcomes distinct;
-     never mark skipped/conditional work completed merely to clear the UI. If the host has no
-     suitable native todo tool, or it fails, use an explicit Markdown fallback with the same labels
-     and truth — never a fabricated successful tool invocation.
+   - **Stable labels (task 0814 R5; A–Z / 1–9 rule, 1105 R1).** Labels come from the published
+     `.plan`: single letters A–Z for top-level rows, digits 1–9 for children under one letter. The
+     projection enforces that cap instead of rolling to two-letter labels (`planLetter` throws past
+     Z — split into waves or stop; never render `AA`-style addresses). An `on-entry` state is
+     inserted as the next digit the moment the host enters it (`insertOnEntry` in
+     `packages/app/src/workflow/plan-projection.ts`), appended after its letter's existing children;
+     re-entering an already-published loop state keeps its label and appends the re-entry note
+     ` — attempt N`. Labels never replace the canonical step id, and are re-derived identically on
+     retry/resume against the same definition.
+   - **Truthful progress (task 0814 R6; frozen status mapping, 1105 R1).** Publish pending/active
+     state before the visible item starts, then update it immediately after the observed item
+     completes and before the next item starts. Frozen status mapping: `pending → pending`,
+     `active → in_progress`, `completed → completed`,
+     `skipped|failed|unattempted|blocked → pending` + ` [<outcome>]` — the four engine-decided
+     outcomes stay visible on a pending row, never cleared. Keep completed, skipped, failed, blocked,
+     paused, and unattempted outcomes distinct; never mark skipped/conditional work completed merely
+     to clear the UI. Re-entry appends ` — attempt N`. If the host has no suitable native todo tool,
+     or it fails, use the `renderProgressMarkdown` fallback with the same labels and truth — never a
+     fabricated successful tool invocation.
 10. For task execution only, record lifecycle provenance before entering the FSM:
 
    ```bash
@@ -200,6 +245,25 @@ the human/native presentation layer — labels are display addresses only, never
    worktree first and run this command (and every lifecycle-touching command: `task record`,
    `task update <wbs> testing|done`) from the worktree root.
 
+### Host todo update styles (1105 R2)
+
+The same published plan is updated differently per host family. Both styles keep plan order and are
+bookkeeping for the one projection — never a second source of truth:
+
+| Host | Tool(s) | Update style |
+| --- | --- | --- |
+| Claude Code | `TaskCreate` / `TaskUpdate` | per-item — create each item once, then update by id; append inserted (`on-entry`) steps at the end (the label carries identity, so list position is display only) |
+| pi | `todo` | per-item — same create-once/update-by-id discipline |
+| Codex | `update_plan` | full-list — rewrite the whole list in plan order on every update |
+| Gemini | `write_todos` | full-list — rewrite the whole list in plan order |
+| OpenCode | `todowrite` | full-list — rewrite the whole list in plan order |
+| Grok | `todo_write` | full-list — rewrite the whole list in plan order |
+| omp | host todo tool | maps plan letters to `phase` |
+| any host without a native tool | `renderProgressMarkdown` | Markdown fallback with the same labels and truth |
+
+Per-item hosts update the one row whose outcome changed; full-list hosts re-render every row from the
+current plan state. Both render the frozen status mapping above identically.
+
 ### Idea-pipeline quick start (0887 R1/R2)
 
 Minimum files to read for `/sp:dev-idea` inline runs — then drive `idea-pipeline.yaml`:
@@ -276,6 +340,10 @@ Rules (R1):
   first, then verify the physical path and repository identity.
 - **Native tool cwd options are additive.** A tool-level cwd/`cd` pin may additionally set the
   call's directory, but never replaces the identity checks above.
+- **Dispatch cwd is mandatory when the tool accepts one.** A subagent dispatch whose tool exposes a
+  `cwd` (pi `subagent`) passes the execution-tree cwd. Omitted, the child starts in the host tree:
+  it can edit main, and the timeout watchdog diffs the wrong tree (H15 2026-10-07: "changed
+  tracked files: none" on a worker that changed 5 worktree files).
 - **Host-only scope.** Engine `shell` actions already bind `context.workdir`
   (`packages/app/src/workflow/actions/shell.ts:98`) — leave them alone. No service-wide
   `process.chdir`, no new public flag, no helper framework.
@@ -314,8 +382,6 @@ entry and `.spur/memory/runs/runall-D63-2ebbd97c.md`.
 
 ## Comprehensive-check retention and evidence (R7/R8)
 
-## Comprehensive-check retention and evidence (R7/R8)
-
 **R7 — comprehensive checks stay at their owning boundaries.** Quick readiness and plan projection are
 admission and visibility, not a substitute for the owning gates. After the plan is visible and after
 isolation when requested, retain the full task/feature integrity, size, evidence-channel,
@@ -363,6 +429,19 @@ Action semantics come from the YAML and the workflow action contract:
 
 - `shell` — run the expanded command in the project working tree with resolved vars exported as
   environment variables. A non-zero result follows the action's existing failure policy.
+  **Long commands must not hold the host call (session finding 2026-10-09).** A `shell` action whose
+  command can outlive the host's per-call limit — the full quality gate, a repo-wide suite, any
+  `bun run spur-check`-class gate — is started **detached and polled**, never held in one foreground
+  call: redirect to a run-scoped file and disown it
+  (`nohup <cmd> > .spur/run/<wbs>-gate.out 2>&1 < /dev/null & disown`), then observe it in bounded
+  calls (`pgrep`, the declared `.status` file, the log tail). A call killed at the cap leaves the
+  substrate's own FAIL receipt — for the quality gate, `.spur/run/<wbs>-check-receipt.json` — and the
+  recheck's `no-progress` guard honours it, so a cap-kill reads as a red gate the next time. Preserve
+  the signal-induced receipt under a distinct name (`<wbs>-check-receipt.false-fail-<signal>.json`)
+  and say so in the run log before re-running: never delete it silently, and never report a
+  cap-killed attempt as a genuine gate failure. Measured this session: one foreground gate call
+  (25.6 min host-wide lock wait + 7.4 min runtime) was SIGTERM-killed at the host cap and produced
+  exactly that false FAIL receipt.
 - `note` — append the expanded message to the inline run log.
 - `doctor.probe` — run the declared Spur doctor once, persist its status file, and apply any
   `setVars` result (including a resolved executor) before the next action or state.
@@ -398,8 +477,10 @@ Action semantics come from the YAML and the workflow action contract:
   `answerFile`; assert `expectFile`; honor `escalationFile` (a non-empty file after exit 0 means
   the agent paused on an operator question — treat the attempt as succeeded-with-escalation and
   skip `requireDiff` for that attempt only); enforce `requireDiff` against a pre-action git snapshot,
-  including the task-scope guard; honor declared error policy. `timeoutMs` is recorded as not
-  applicable because the host session has no independent kill boundary.
+  including the task-scope guard; honor declared error policy. A host-inline action records
+  `timeoutMs` as not applicable because the host session has no independent kill boundary; a
+  dispatched subagent passes it to the host when the dispatch tool accepts a timeout (see
+  § Timeout boundary).
 - `run.artifact` — the engine's ledger registration has **no inline execution surface** (0808 R4).
   The inline equivalent is a documented **registration-equivalent convention**: before the record
   state mutates the task, the host validates the same refusal conditions inline — the declared
@@ -470,6 +551,49 @@ reformulate the prose into a command, spawn a subagent for it, or silently promo
 Beyond the deterministic `estimate_hours` floor in condition 5, no token estimate, model heuristic,
 or configuration switch is added.
 
+**Contingent fallback (task 1134 R1/R2) — capacity is not capability.** That fallback is correct for
+capability-shaped failures and **wrong when the exhausted resource is the host session's own
+provider quota**: re-selecting the same exhausted provider cannot succeed by construction, and the
+run collapses into one serial host worker with no executor diversity. So classify the pre-dispatch
+failure before falling back:
+
+```bash
+DISPATCH_SCRIPT=plugins/sp/scripts/inline-run-dispatch.ts; [ -f config/plugin-scripts.json -a -f "$DISPATCH_SCRIPT" ] || DISPATCH_SCRIPT="$(superskill script path sp inline-run-dispatch.mjs 2>/dev/null)"
+bun "$DISPATCH_SCRIPT" --dispatch-failure --run-id "$RUN_ID" --stage <state-id> --decision <escalate|stop> \
+  --text-file <bounded failure record> [--executor <name>] [--agent <a>] [--model <m>]
+```
+
+The helper wraps the upstream `@gobing-ai/ts-ai-runner` classifier (Spur matches **no** provider
+code or quota vocabulary of its own) and writes `.spur/run/<run-id>-dispatch-fallback.json` as
+`{stage, class, reason?, resetAt?, decision, executor, attribution, observedAt}`. Read `.class` from
+that file — never judge the prose yourself.
+
+- **`class: capability`** (generic 429, rate limit, overload, auth failure, timeout, missing
+  permission, missing capability, non-dispatch-eligible prose, below the size floor) → today's
+  fallback, unchanged: execute the stage once in the host session and log
+  `stage <id> executed inline in session <session-id>`.
+- **`class: capacity`** (a confirmed exhausted usage allowance or credit balance) → the stage is
+  **never** re-executed in the orchestrating host session. Hand it to the subprocess dispatch path
+  (`--agent auto|name` resolves an executor through the registry and can pick another rung); when
+  that path is unavailable, terminate the run at `failed` with `terminalReason: failed-agent`,
+  naming the executor and the record's `resetAt` when it carries one. Record
+  `stage <id> capacity exhaustion: <executor> <reason> reset <resetAt|unknown> — escalate|stop`.
+
+**Attribution before dispatch (task 1134 R3).** Immediately before each inline `agent.run` stage,
+record the executor identity the stage will use, so a later classified exhaustion can be attributed
+to a rung configuration can disable:
+
+```bash
+bun "$DISPATCH_SCRIPT" --attribution --run-id "$RUN_ID" --stage <state-id> \
+  [--executor <name>] [--agent <name>] [--model <m>]     # omit --executor for the no-attribution marker
+```
+
+This appends one line to `.spur/run/<run-id>-attribution.jsonl` and one run-log line
+(`stage <id> attribution: <executor|none>`). When no named executor resolves, pass no `--executor`:
+the ledger records the explicit `executor: null` marker — never a silent drop. An unattributed stage
+is observable but cannot write configuration (executor-availability §4), and `spur agent doctor
+--json` counts those stages as `inlineFailFast.unattributedStages`.
+
 **Pre-dispatch permission check (2026-09-15 subagent-dispatch evaluation).** Claude Code exposes no
 dry-run permission API, so the contract is **name-capabilities + fail-fast blocker** — never a
 permission-probing subsystem. Before dispatching a stage, the driver names the stage's required
@@ -515,13 +639,30 @@ boundary, and a delegate left to re-derive them re-derives them against its own
    **owning stage's artifact contract** — for a verify stage, the compact contract below.
 6. **The implement-stage acceptance-evidence requirement** — for the implement stage and any stage
    whose YAML action declares `requireDiff`. A `requireDiff` stage is the one whose delegate writes
-   the deliverable, so its handoff carries three components:
+   the deliverable, so its handoff carries four components:
    (a) **the task's AC identities verbatim** — the exact `Scenario:` titles / checklist text read by
    the driver from the task file, never paraphrased;
    (b) **required evidence** — the pasted output of the narrow targeted tests the delegate ran, and
    a `file:line` change map written into the task's `## Solution` section;
    (c) the reminder that **a delegate success message is not evidence** — post-join validation reads
-   the artifacts and the diff, not the delegate's claims.
+   the artifacts and the diff, not the delegate's claims;
+   (d) **the public-surface probe requirement (task 1135 R1/R2/R6).** Before the stage reports done
+   it runs at least one end-to-end probe of each new or changed **public surface** — a CLI
+   verb/flag, an HTTP route, or a plugin script entry — against a throwaway project root (never the
+   repo corpus, never the execution tree's tracked files), and reports the exact command plus its
+   observed output as acceptance evidence. A service-layer test suite is **not** a substitute. The
+   probe is bounded: 120 s per invocation, output capped at 8 KiB, no network beyond the CLI under
+   test, and a probe failure is evidence, never a corpus mutation.
+   A stage that changed no public surface returns instead the single line
+   `probe: not-applicable (no public surface changed)`.
+   The stage's own changed-path static self-check (task 1135 R8) also runs here: `spur rule run`
+   with the configured pre-check preset over the changed paths, `bun run script-contract-check`
+   when a plugin script was touched, and the paired-script parity test when `package.json` changed —
+   so an env-var-hygiene violation, a stale generated twin, or a half-updated paired chain is
+   named by the stage rather than discovered by the pipeline `test` hop.
+   **A stage that returns neither probe evidence nor the not-applicable line is not silently
+   complete (task 1135 R2): the driver records the stage `done` with a `probe-missing` marker in
+   the run log and carries the same marker into that task's batch-report row.**
    Component (a) is read from the task by the driver; this extends the payload contract and is NOT a
    new YAML key.
 
@@ -533,6 +674,26 @@ execution tree, and an ad-hoc git worktree created for a comparison is removed b
 reports. The G65 batch's implement dispatches left an 867 MB worktree plus a trail of `/tmp` scratch
 files that outlived the run (2026-09-15).
 
+**Delegate search discipline.** A delegate searches with bounded scope: `rg -g '!node_modules' …`
+(or an explicit narrow path), never `grep -r .` / `grep -rn --include=*` from a repository root —
+those walk `node_modules` and `.git` and can burn many minutes at full CPU in the wrong tree
+(measured 2026-10-09: a delegate's `grep -rn --include=* .` from the invoking tree root ran 4+ min
+before the orchestrator killed it). The dispatch payload's execution-tree cwd is the only tree a
+delegate searches or edits; a search it cannot bound is a search it should not run.
+
+**Driver scratch lives with the run (task 1136 R6).** Every driver scratch file — action-batch
+JSON, captured stage output, temporary status/answer files — lives under `.spur/run/<run-id>/`,
+never `/tmp` or `$TMPDIR`: the OS may reap a temp directory mid-run, and a reaped scratch file
+surfaces as an unrelated downstream failure. Run-scoped files directly under `.spur/run/` keep
+their existing `<run-id>-*` naming (the `no-env-files` rule still bans `.env` names).
+
+**Declared vars are checked before a shell action runs (task 1136 R6).** Before executing a `shell`
+action whose command references a declared workflow var (for example `$qualityGateCmd`), the driver
+confirms the var is exported and non-empty; when it is not, the action fails by name —
+`shell action requires $qualityGateCmd but it is empty/unset` — and the command never runs. The
+check is scoped to vars the workflow declares with a value: legitimately empty optional vars
+(`$featureSpecPath` for an orphan task, `$gateFindings` on a green gate) pass unchanged. This turnsa silently empty `$qualityGateCmd` into a named failure instead of a shell that runs nothing.
+
 **Verify-stage artifact contract.** A verify handoff names
 [`code-verification/references/verdict-schema.md`](../../code-verification/references/verdict-schema.md)
 as the canonical answer schema and carries this compact form verbatim:
@@ -546,6 +707,9 @@ Evidence Type = test | command | static-ref | manual-review | llm-judge | n/a
 AC rows use the task's exact AC identities (verbatim `Scenario:` titles / checklist text).
 A behavioral AC marked MET requires executable evidence (test | command);
 static-ref or llm-judge alone cannot carry it.
+Evidence anchors are repo-root-relative (`packages/app/src/foo.ts:42`); a basename
+(`foo.ts:42`) is an unresolved anchor and blocks the done projection (`L4.anchor-unresolved`) —
+see `code-verification/references/verdict-schema.md` § Basename-only anchors are unresolved anchors.
 ```
 
 **AC table shape (0948 R9).** The AC table must be exactly **4 columns** and **cell 3 must hold a
@@ -597,11 +761,41 @@ grading its own work defeats the stage. A continuation stage also dispatches fre
 same-task subagent exists (the earlier stage ran host-inline or below the dispatch floor), when a
 host-owned gate sat between the stages, or when the platform cannot address completed subagents.
 
-**Timeout boundary (task 0727):** a dispatched subagent is governed by
-**the host platform's subagent limit, not the YAML timeoutMs** — `timeoutMs` stays not-applicable
-for host execution only — and before dispatch the driver must
-**record the governing timeout boundary and its source before dispatch** in the run log
-(e.g. `host timeout <ms> (<platform subagent limit|yaml timeoutMs>)`). If the dispatch reaches that
+**Implement and test-fix workers never run the full gate (task 1127 R8 / task 1142 R3).** Since 1127 the full gate
+takes a host-wide lock (`SPUR_GATE_LOCK_DIR`, default `~/.config/spur/run/full-gate.lock`):
+concurrent full-gate runs serialize, and a manual `spur-check` (wrapped via
+`scripts/commands/gate-lock.ts`) holds the same lock. A dispatched **implement** or `test-fix` child
+that re-ran the full gate would queue behind every other gate on the host and burn its dispatch
+timeout waiting instead of working. Workers use the light tier as their iteration check (task 1142 R3) in exact order:
+1. the **changed-path matrix** (`code-implementation/SKILL.md` § Changed-path targeted checks) over the paths they touched;
+2. the resolved `quality-gate` script in `light` mode (source-repo probe, else the installed twin) (biome, per-workspace typecheck, rule presets, related tests).
+Neither step takes the full-gate lock. The pipeline's `test` and `test-recheck` hops remain the only full gate. Carry
+`--gate-log <path>` through to the child **verbatim**: never paraphrase it into "re-run the named
+gate command". That paraphrase is not cosmetic — it dropped this rule in the H15 run (task
+Background, seq 232) and sent a worker into the locked gate. The pipeline's next `test` (recheck)
+stage re-acquires the lock and delivers the deciding verdict; that deciding run may wait for a live
+holder, so a queued worker's effective budget is dispatch timeout minus observed lock queue wait,
+not the timeout alone.
+
+**Null or timed-out dispatch (task 1134 R9).** The dispatch bound stays the existing YAML
+`timeoutMs` (`implementTimeoutMs` / `stepTimeoutMs`), passed to the host dispatch as today — R9 adds
+no new bound. A dispatch that returns **no result**, or that hits that bound, is a **recorded stage
+failure**, not a fallback trigger: record the stage failed with `dispatch: null-result|timeout`,
+follow the stage's normal failure edge (implement's default `fail` policy routes the run to
+`failed`), and start **no** host-inline attempt of that stage. R1–R4 cover a *pre-dispatch* capacity
+refusal (the executor must shift); R9 covers the *dispatched-but-unproductive* case.
+
+**Timeout boundary (task 0727, amended by task 1108):** when the host's dispatch tool accepts a
+per-dispatch timeout (pi: subagent `timeoutMs`, default 30 min — pi-subagents `docs/tool-reference.md`
+line 97), the driver passes the stage's resolved YAML
+`timeoutMs` (implement → `implementTimeoutMs`) and records `host timeout <ms> (yaml timeoutMs)`.
+When it does not, a dispatched subagent is governed by
+**the host platform's subagent limit, not the YAML timeoutMs**, and the driver records
+`host timeout <ms> (platform subagent limit)`. `timeoutMs` stays not-applicable for host-inline
+execution only. Either way the driver must
+**record the governing timeout boundary and its source before dispatch** in the run log. Rationale:
+the operator sets one budget in one place; a host silently imposing its own 30 min default is what
+killed the P1 implement dispatches (1096, 1099). If the dispatch reaches that
 boundary, **a dispatch timeout is a started-subagent failure**: the no-replay rule above and the
 stage's declared YAML error policy govern (implement's default `fail` policy routes the run to
 `failed`); it is never a host re-execution. Recovery follows the
@@ -624,139 +818,48 @@ Run-log stamps (task 0727): every appended line is prefixed with an **ISO-8601 U
 (`YYYY-MM-DDTHH:MM:SSZ`, e.g. `2026-08-31T17:51:11Z`); the exact-template provenance lines above
 keep their exact content after the stamp prefix. This normalization is contractual:
 **bare local-clock stamps are prohibited** — a hand-appended `[stage 12:31]` form mixes timezones
-in one file and makes the run unauditable (task 0726 mixed both forms).
+in one file and makes the run unauditable (task 0726).
 
 ## Structured trace emission (ADR-117, task 0868)
 
-`.spur/memory/runs/<run-id>.md` is the human half of the two-file run record — evidence, **not the record
-of truth**. A run's
-observability is a property of the run, so the inline driver owes the same structured trace the
-engine subprocess writes — and it owes it through the **same writer**, never a parallel
-implementation. The shared writer is `WorkflowActionTraceWriter`
-(`packages/app/src/workflow/action-trace.ts`): the same decorator the engine composition installs
-around `DbWorkflowPersistenceAdapter`, so the two surfaces call one emission path and one run-row
-closure path and cannot drift.
+Read [structured-trace-emission.md](structured-trace-emission.md) when the first trace event is
+emitted — the action vocabulary, the emit shape and the parse/close contract.
 
-The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
-`plugins/sp/scripts/inline-run-setup.ts`) — no new entry point, no second resolution chain:
+## Post-gate tree freeze (task 1135 R3/R4/R5)
 
-- **Every executed action** — after the action settles, whether it ran host-inline or via a native
-  subagent — append its provenance line as before, then record the boundary:
+The quality gate's `proofDigest` certifies a specific tree. Two rules protect it, and both are
+**ordering plus early detection** — a host session cannot intercept a file write, so the contract is:
 
-  ```bash
-  bun "$SETUP_SCRIPT" --action --run-id "$RUN_ID" --node <state-id> --kind <action-kind> \
-    --status <done|failed> --ok <true|false> --duration-ms <measured-ms> [--estimated]
-  ```
-
-  `<state-id>` is the current YAML state id (the `node`), `<action-kind>` the YAML action kind
-  (`agent.run`, `shell`, `note`, `doctor.probe`, …). `--status` is `done` when the action settled
-  under its declared error policy and `failed` otherwise; `--duration-ms` is the wall clock the
-  driver measured around the action, and `--estimated` marks a duration the driver did **not**
-  time (a value reconstructed after the action returned). The row's provenance stamp rides
-  `action_runs.result_json` as `{provenance:'host-reported', estimated}`, and the projection
-  exposes it per attempt — `provenance` is `host-reported` for every inline row and `unknown`
-  for an engine-written or pre-stamp row, so the Board can label a host-reported duration
-  instead of presenting it as measured. This writes the `action_runs` row (node, kind, status,
-  `ok`, `duration_ms`, `run_id`) the engine would have written, so the run's rows are queryable
-  by run id (`spur workflow progress <run-id>`, `ActionRunDao`) without reading the text log.
-  The writer
-  back-dates the row's `started_at` from its own `completed_at` minus the measured duration
-  (0887 R8), so `completed_at − started_at == duration_ms` exactly; a back-date failure is
-  recorded (`action.backdate`) and never affects the run.
-
-- **A state with several actions (1007 R5)** — emit the whole state's boundaries in one call
-  instead of one `--action` invocation per action. Write a JSON array
-  (`[{node,kind,status,ok,durationMs,estimated?}, …]` — the `--action` fields, `estimated`
-  optional and `false` when absent) to a temp file and pass it with `--actions-file`:
-
-  ```bash
-  bun "$SETUP_SCRIPT" --actions-file <actions.json> --run-id "$RUN_ID"
-  ```
+1. **Every tree edit belongs to `implement`, or to the bounded `test-fix` remediation hop** — stray-file
+   cleanup, anchor qualification, contract pins, doc edits, and task-section writes other than the
+   pipeline-owned `## Testing`/`## Review`/`## Solution`. After `test` captures `proofDigest`, no
+   other state edits the tree. A genuine later correction goes through `test-fix → test-recheck`,
+   which re-captures the digest and re-snapshots the tree state.
+2. **Review joins the proof bracket.** The pipeline now compares `proofDigestNow` against
+   `proofDigest` at **review** entry as well as verify and record, so a drifted tree stops the run
+   before a review dispatch is spent. The mismatch routes through the existing tripwire to `failed`;
+   there is no new re-certify path.
 
-  Every row is recorded through the same writer as `--action` (one `action_runs` row per entry);
-  the batch is validated in full before the first write, so an invalid row or unreadable file
-  exits `1` with `{"ok":false}` and leaves **no** partial rows — fix the batch and re-emit. On
-  success it prints `{"ok":true,"runId":…,"recorded":<n>}` and exits `0`. Row emission stays
-  best-effort exactly like `--action`: if a row's write fails mid-batch, the failure is recorded
-  to the run record and the call reports `{"ok":false,…,"error":…}` but still exits `0` — the run
-  continues; never retry the batch or backfill by hand. `--actions-file` is exclusive with the
-  other mode flags (`--action`, `--decide`, `--close`, …): mixing them is a usage error (exit 2),
-  and a mixed call must be corrected, not silently split.
-
-- **A `decide` action (0941)** — the driver never executes the DecisionMaker itself; it delegates
-  to the same app runner the engine registers, which writes the resultFile row (schemaVersion 1)
-  and returns the decision, then the delegate records the `action_runs` row (`kind=decide`)
-  through the same writer as every other action:
+**A mismatch names the drifted paths (R5).** At gate entry the pipeline snapshots the non-corpus tree
+state (`git status --porcelain=v1 -uall` plus `git diff --name-only HEAD`, excluding
+`docs/tasks*` / `docs/features*`) into `.spur/run/<run-id>-gate-paths.txt`. On a mismatch the
+`proof.fingerprint` action diffs the current state against that file and reports the changed paths in
+both the tripwire event and the run log (`proof-compare-failed … drifted paths: …`), so the operator
+reads *which file* moved, not only the `D1`/`D2` pair. An **untracked** file outside those exclusions
+is part of the certified set: the digest's git-tree half stages everything outside the excluded
+globs, so a stray file added after the gate is real drift and must be named (the behaviour is
+documented beside `DEFAULT_EXCLUDE_GLOBS` in `proof-input-fingerprint.ts`).
 
-  ```bash
-  bun "$SETUP_SCRIPT" --decide --run-id "$RUN_ID" --node <state-id> --options-json <options-file>
-  ```
-
-  The options JSON mirrors the YAML `decide` options (`id`, `method: choice|noul`, `question`,
-  `choices`/`default`, optional `evidence`, optional `minConfidence`, `resultFile`); paths resolve
-  against the project workdir. The decision never pauses and never fails the run for model
-  problems: a degraded outcome (feature switch off, no backend, error, timeout, low confidence)
-  prints `ok:true` with `degraded:true`, the declared `reason`, and `value = default`, and exits
-  `0` — route on the resultFile's `.value` with the declared file guards. Every row carries
-  `source: model|default` (0976 R2), and the delegate appends
-  `decide node=<id> value=<v> source=<s> reason=<r>` to the run log, so a declared-default
-  fallback is never read as a model decision. Only an invalid options
-  schema exits `1` (fail closed), and usage errors exit `2`. The `action_runs` trace row is
-  best-effort exactly like `--action`.
-
-- **At the run's declared terminal state** — before the driver reports the run complete, close the
-  row so a successful inline run is never left non-terminal for `spur workflow clean` to reap as
-  stale:
-
-  ```bash
-  bun "$SETUP_SCRIPT" --close --run-id "$RUN_ID" --status <done|failed|paused>
-  ```
+## Record & done sequencing
 
-  `--status` is the declared terminal state's verdict, not a guess: a run that reached a terminal
-  state is `done`; a run halted by a failing action under its error policy is `failed`. On success
-  the close reports the recorded evidence: `{"ok":true,"runId":…,"actionRows":<n>}`.
-  After the close, the invoking command prints the measured
-  [execution summary](dev-operations.md#execution-summary) for `$RUN_ID` unless `--no-summary`.
-
-  **Zero-row done closes are a named failure (task 0975 R2).** A run closed `done` with **zero**
-  `action_runs` rows (`actionRows:0`) finalizes the row but exits `1` with
-  `{"ok":false,"code":"NO_ACTION_ROWS","actionRows":0}` — a run that claims success without a
-  single recorded action is exactly the untraced-runs gap ADR-117 closes, so the driver must
-  surface the code in its final report instead of reporting a clean close. The failure must NOT
-  be repaired by backfilling rows: the run row is already terminal, and hand-written rows are
-  forbidden (ADR-117) — record the finding and let the task's evidence show the gap. A `failed`
-  close with zero rows stays a clean `0` (a halt before the first boundary legitimately records
-  nothing), and any `done` close with `actionRows ≥ 1` exits `0`.
-
-**Best-effort at the action boundary only (ADR-117).** An `--action` persistence failure is
-recorded — the delegate appends a `trace-emission-failed` line to `.spur/memory/runs/<run-id>.md` and
-prints `{"ok":false}` on stdout — and the run continues to its declared terminal state; the
-delegate exits `0` for that outcome and the driver must never treat an emission failure as a run
-failure, retry it in a loop, or substitute a hand-written row. The run-row closure (`--close`) is
-bookkeeping, not trace emission, and is **not** best-effort: a missing run row or a persistence
-failure exits `1` with `{"ok":false}` and a named error (a missing row also carries
-`code:"RUN_NOT_FOUND"`), because a silently `running` row is exactly the stale state
-`spur workflow clean` reaps as `failed`. Exit `2` means the invocation itself was malformed
-(missing `--node`/`--kind`/`--status`/`--ok`, a miscased `--ok`, a missing or malformed
-`--duration-ms`, or an unsafe run id) and must be corrected, not ignored.
-
-Emission is not optional and not deferred: an inline run that skips it reintroduces the
-1,011-untraced-runs gap ADR-117 exists to close.
-
-Transition guards are not advisory. Execute the declared guard exactly, in order, with the same
-resolved variables and artifacts. `--no-lifecycle` remains bookkeeping only; the YAML's task checks,
-verdict gate, record step, and done guard all remain authoritative.
-
-## Record & done sequencing (dogfood 2026-08-21, feature A3)
-
-Order matters for the `testing → done` hop. The A3 batch hit the same clobbering spiral on two
-tasks (0617, 0619) because the sections were hand-written **before** the verdict artifact existed:
+Order matters for the `testing → done` hop: the sections must not be hand-written **before** the
+verdict artifact exists (tasks 0617, 0619 — the clobbering spiral).
 
 1. **Write the verdict artifact first.** `spur task record --solution-from-diff --transition testing`
    reads `.spur/run/<wbs>-verdict.json` (default attempt output) on every invocation and atomically retains the recorded verdict under `.spur/memory/evidence/`. A missing or malformed artifact
    yields **UNKNOWN**: bare Testing receives a "No requirements recorded" stub, while already-authored
-   Testing is preserved. `--solution-from-diff` backfills only a bare Solution. The A3 clobbering above
-   describes the historical behavior, corrected by the authored-Testing safeguard. Creating the
+   Testing is preserved. `--solution-from-diff` backfills only a bare Solution. The clobbering above is
+   the historical behavior, corrected by the authored-Testing safeguard (tasks 0617, 0619). Creating the
    artifact first (PASS, with requirement rows keyed by scenario title) remains the standard order;
    re-running record after a real verdict arrives refreshes Testing from that verdict.
 
@@ -775,6 +878,12 @@ tasks (0617, 0619) because the sections were hand-written **before** the verdict
 2. **Done-probe before done.** Run the check projected to `done` (`spur task check <wbs> --as done`
    via the `TaskCheckService` probe pattern) — it surfaces `L3.unchecked-checklist` (flip `- [ ]` → `- [x]`)
    and `L3.required-section-placeholder` before the transition, not after.
+   **Anchor repair is the YAML implement stage's job, not the driver's** (task 1109 R4):
+   `task-pipeline.yaml` runs `$spurBin task migrate-anchors --wbs $wbs --json ; exit 0` after the
+   format step and before `test` captures the proof digest, so unique basename anchors are already
+   repo-relative by the time this probe runs. The driver does not hand-patch anchors: anything the
+   scoped pass leaves (ambiguous basenames, line drift, `L4.anchor-subject-mismatch`) is reported by
+   this probe and belongs to the implementer to re-anchor.
 3. **Solution change-map anchor rule (L4.anchor-subject-mismatch).** A Solution change-map table must
    list **one `file:line` per row**. A ·-joined paragraph makes every anchor's "subject" the other
    anchors and trips the L4 subject check. Since 0804 R9, subject extraction ignores complete parsed
@@ -782,6 +891,77 @@ tasks (0617, 0619) because the sections were hand-written **before** the verdict
    (`docs/help/cmd_example.md:12`) is checked exactly like any other row — cite an **existing file**
    with a **valid line or line range** whose content names the requirement's subject. A real absent
    symbol, nonexistent file or invalid range still reports; never replace a citable row with prose.
+4. **Stage through the commit guard (1129 R2/R3/R5).** The per-task commit that follows the record
+   hop stages only the files THIS run wrote — `git add -A` and `git add .` are **forbidden** in
+   every driver commit step (they staged a concurrent session's files in `a94f9f431` and
+   `36f274590`). `check` first and record a non-empty `foreign` list in the run report; `stage`
+   exits 2 when it refuses a listed path (foreign) and 3 when a target is unmerged or still carries
+   conflict markers — both mean "resolve it, do not commit":
+
+   ```bash
+   GUARD=plugins/sp/scripts/commit-guard.ts; [ -f config/plugin-scripts.json -a -f "$GUARD" ] || GUARD="$(superskill script path sp commit-guard.mjs 2>/dev/null)";
+   bun "$GUARD" check --run "$RUN_ID"
+   bun "$GUARD" stage --run "$RUN_ID" -- <files this run wrote> \
+     || { echo "record halt: commit-guard refused a path (foreign, unmerged or conflict-marked); nothing committed" >&2; exit 1; }
+   git commit -m "<type>(<scope>): <wbs> <summary>"
+   ```
+
+5. **Print the run's execution summary (1146).** The terminal `--close` returns `summaryFile`; print
+   that file's contents verbatim under an `### Execution summary` heading, and pass `--no-summary`
+   through to `--close` when the operator asked for it. The window is the run row's `started_at` →
+   close time — the driver records no `SINCE` and assembles no measurement of its own
+   (structured-trace-emission.md § the close step owns the contract).
+
+## Running the full gate (task 0872 / 1127 R7)
+
+The full gate serializes behind a host-wide lock and legitimately runs 10-25 minutes. Two rules keep
+it from becoming a hazard (both violated once on 2026-10-10, blocking every other session for ~11
+minutes and aborting the run's own verification):
+
+- **Never wrap it in an external `timeout`, and never treat its runtime as a hang.** An outer bound
+  that fires mid-suite leaves the holder alive holding the lock while the caller believes it is gone.
+- **Run it detached and poll the log**, so losing the foreground call cannot lose the holder:
+
+  ```bash
+  nohup bash -c 'bun run spur-check > /tmp/gate.log 2>&1; echo "EXIT=$?" >> /tmp/gate.log' &
+  ```
+
+- **Never kill a gate holder whose pid is alive.** The waiter line `waiting for holder (… held Nms)`
+  is printed only after `isProcessAlive(held.claim.pid)` succeeded, so a printed holder is a live one
+  by construction; only the lock's own dead-pid reclaim is authorised to clear a claim.
+
+## Runtime interface contracts (from run evidence)
+
+Each item below cost a driver cycle to discover. They are contracts, not tips.
+
+- **`--decide --options-json <file>` takes one option object, never an array.** Shape:
+  `{id, decision, params?, evidence? | instructions?, resultFile}`; `evidence` and `instructions` are
+  mutually exclusive (`CatalogDecideOptionsSchema`). A JSON array parses as neither dialect and
+  surfaces as `decide: invalid options — Invalid input` with no field detail. `resultFile` resolves
+  against the confirmed tree's cwd, so pass a worktree-relative path such as
+  `.spur/run/<wbs>-triage.decision`.
+- **`task-diffstat.ts` reads `wbs` from the environment and writes an artifact.** Invoke it as
+  `wbs=<wbs> node "$(superskill script path sp task-diffstat.mjs)"`; stdout stays empty, so assert success on
+  `.spur/run/<wbs>-diffstat.json` and never on command output. Never the bare unguarded
+  source-repo path form — the script-contract check forbids it on a shipped surface because it
+  shadows the installed twin in a consumer.
+- **The verify answer grammar is exact.** One `Verdict:` line, one `Confidence:` line, then
+  `### Per-Requirement Traceability` (`| Req | Status | Evidence |`) and
+  `### Acceptance Criteria Verification` (`| AC | Status | Evidence Type | Evidence |`). Requirement
+  statuses are `MET | PARTIAL | UNMET`; AC statuses add `N/A`; every AC row id must match a declared
+  scenario title verbatim, including its `(req: ...)` suffix. A `MET` row whose evidence hedges
+  (`likely`, `probably`, `seems`, `appears`, `possibly`, `presumably`) is rejected as
+  `evidence-hedged`, and a level the rows do not earn is rejected as `confidence-unwarranted` or
+  `confidence-understated`. `spur task verdict` lints before writing, so a rejected answer leaves no
+  artifact and exits non-zero.
+- **Harness tooling refuses direct task-file writes.** Resolve a merge conflict in a task file by
+  choosing a git side, then applying the corpus delta through `spur task update` (for example
+  `--feature <id>`), never by editing the file.
+- **A skill body has a byte budget** (20,000 B for `SKILL.md`); procedure detail belongs in
+  `references/`. Adding a clause to a SKILL.md can fail `R44 — skill BODY budgets`.
+- **`.spur/run/` is volatile** (ADR-131, as amended): its contents are execution scratch. Anything
+  that outlives the run cites the durable owner (`.spur/memory/evidence/`, `.spur/memory/runs/`) or
+  the tracked Testing section.
 
 ## Failure contract