@gobing-ai/spur 0.4.2 → 0.4.4

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

@@ -1,6 +1,6 @@
 ---
 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.22 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093."
+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 with per-maker readiness marks (registered, configured, recorded, probed). Backed by @gobing-ai/ts-ai-decision 0.5.22 hub; offline by default via the built-in `typesafe` maker. Introduced by task 1093; readiness marks and `--probe` by feature P11."
 see_also:
   - spur-cli
 ---
@@ -25,9 +25,10 @@ Decisions resolve first-wins across three layers:
 | `registered` | folders listed in config `decisions.paths` | Operator-added catalogs |
 | `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.
+The bundled shared catalog ships `task-triage`, `failure-class`, `review-failure-class`,
+`gate-evidence`, `idea-recommendation`, `needs-design`, `anatomy-validation-verdict` and
+`maker-liveness` (the last served only by `spur decision status --probe`; no workflow references
+it). Duplicate ids across layers keep the higher layer; duplicates inside one file are a load error.
 
 **Config keys** (under `decisions:` in the global `~/.config/spur/config.yaml` or project `.spur/config.yaml`):
 `paths` (extra catalog folders forming the `registered` layer), `maker` (default DecisionMaker
@@ -41,7 +42,7 @@ config error, never a silent fallback (design §3.6).
 | `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` |
+| `status` | Sectioned readiness report: one status line, errors, aligned `Makers` and `Decisions` tables (registration, configuration source, recorded evidence), `Catalog` block | `--probe`, `--reliability [--since <iso>]`, `--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
@@ -51,6 +52,25 @@ ADR-091). Failure output for `--json` commands uses the canonical error envelope
 (design §3.4 — load errors surface via `status`) except for an invalid `--layer` value (exit 1).
 Error envelopes use `NOT_FOUND` for an unknown id and `VALIDATION_FAILED` for every other caller mistake.
 
+## Readiness marks (`status`, feature P11)
+
+The default `status` output separates four marks per maker and per decision
+(`docs/design/decision-observability-and-adoption.md` §3.4.1):
+
+| Mark | Column | Source |
+| ---- | ------ | ------ |
+| registered | `ST` glyph on the maker row | the maker registry holds the name |
+| configured | `CONFIGURED BY` | `decisions.maker` / `decisions.makers.<id>` |
+| recorded | `RECORDED` / `ACCEPTED` / `LAST SEEN` | the recorded `decision.end` ledger, matched on `(decisionId, maker)` |
+| proven | `PROBE` (only with `--probe`) | one live liveness decision per maker |
+
+`RECORDED` with `ACCEPTED 0` is the state that reads as healthy everywhere else: the maker is
+registered and configured but has never once succeeded. `--probe` is the only path that calls a
+maker, is bounded per driver, writes no decision log row and emits no event (`--probe` with
+`--reliability` is refused). Parse the marks with `--json`: `makers[]`
+(`registered`, `configuredBy`, `serves`, `evidence`), `perDecision[].evidence`, and `probes[]`
+under `--probe`.
+
 **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
@@ -95,11 +115,16 @@ 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 '.loadErrors'      # audit catalog health
+spur decision status                                 # readiness marks: registered / configured / recorded
+spur decision status --probe                          # prove each effective maker answers now
+spur decision status --json | jq '.makers[] | {name, registered, recorded: .evidence.recorded}'
 ```
 
 ## References
 
-- Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface)
+- Design: `docs/design/decision-catalog.md` (§2 catalog authoring, §3.4 CLI surface),
+  `docs/design/decision-observability-and-adoption.md` (§3.4 reliability report, §3.4.1 readiness view)
 - Hub: `@gobing-ai/ts-ai-decision` 0.5.22 (`DecisionService`, catalog schema, maker registry)
-- App service: `packages/app/src/decision/decision-service.ts`
+- App service: `packages/app/src/decision/decision-service.ts` (makers, `probeMaker`),
+  `packages/app/src/decision/decision-status-readiness.ts` (readiness marks, probe loop)
 - Shipped catalogs: `config/decisions/*.yaml`

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

@@ -81,9 +81,45 @@ mode needs its own required args).
 spur feature update H2 active
 ```
 
-Valid statuses: `backlog → active → verifying → blocked → done → cancelled`. The lifecycle engine
-enforces legal transitions; `verifying` is the gate where AC traceability must hold (L4).
-**One active goal** at a time is enforced by `check` (a corpus invariant).
+Valid statuses: `backlog → active → verifying → blocked → done → cancelled`, plus the frozen
+`deprecated`. The lifecycle engine enforces legal transitions; `verifying` is the gate where AC
+traceability must hold (L4). **One active goal** at a time is enforced by `check` (a corpus invariant).
+
+**`deprecated` — frozen, not terminal (ADR-136).** The state means *retained and frozen*: the record
+stays readable and countable, but nothing may attach new work to it or advance it. It is entered from
+`backlog`, `active`, `verifying`, `blocked` and `done`, and left only to `active` (un-deprecate,
+mandatory History entry) or `cancelled` (removed) — every other edge out of `deprecated` is undeclared
+and refused by the graph. The freeze, as shipped:
+
+- **Task links are refused** — `task create`, `update --feature` and `batch-create` exit non-zero and
+  write nothing (no sibling hint; `--no-reopen` is irrelevant for a frozen parent):
+
+  ```
+  parent-feature-status: feature <id> is deprecated (frozen); new tasks cannot link to it. Run removal work under its own feature, or un-deprecate: spur feature update <id> active
+  ```
+
+- **`L4.feature-deprecated`** — `task check` warns (does not error) for a *live* task under a
+  deprecated feature; a terminal task is the correct end state and gets no finding; `--strict`
+  elevates the warning as usual:
+
+  ```
+  Feature "<id>" is deprecated (frozen) — re-parent this live task (`spur task update <wbs> --feature <otherId>`) or cancel it.
+  ```
+
+- **`update --section` still lands** (exit `0`), appending a warning to `warnings[]`:
+
+  ```
+  Feature <id> is deprecated (frozen); change it only as part of removal
+  ```
+
+- **`sync` / `refresh` / `check --fix` never move it** — derivation is sticky and returns the no-op
+  proposal `{ from: 'deprecated', to: 'deprecated', reason: 'Feature is deprecated (frozen)' }`.
+
+- **`advance` refuses** with exit `1`, naming the un-deprecate command:
+
+  ```
+  <id> is deprecated; un-deprecate first: spur feature update <id> active
+  ```
 
 **Scalar field set:**
 
@@ -113,7 +149,8 @@ spur feature advance H2 --to verifying
 ```
 
 Walks the legal forward path (`backlog → active → verifying → done`) hop-by-hop until `--to`
-(default `done`). No-op when already at the target.
+(default `done`). No-op when already at the target; a `deprecated` feature is refused up front (see
+the freeze block above).
 
 ## Acceptance criteria conventions
 
@@ -169,7 +206,8 @@ the AC coverage map. Habits that keep it green:
 Use feature hierarchy for user-facing capabilities and roadmap themes; keep technical-module mapping
 as prose or notes unless the product surface is developer infrastructure. Priority is a scalar field
 (`spur feature update <id> --field priority --value P1`), while status is lifecycle state
-(`backlog → active → verifying → blocked → done → cancelled`). Do not conflate the two.
+(`backlog → active → verifying → blocked → done → cancelled`, plus the frozen `deprecated`). Do not
+conflate the two.
 
 **Structure first:** [features/hierarchy-mece.md](features/hierarchy-mece.md) (MECE roots, when to
 extend vs create). **Then priority:** [features/roadmap-priority.md](features/roadmap-priority.md).
@@ -216,6 +254,9 @@ spur feature sync H2 --force                   # re-derive live: bypass replay +
 spur feature sync H2 --folder docs/custom-tasks --json   # non-default tasks folder
 ```
 
+- **`deprecated` is sticky:** derivation returns no proposal for it
+  (`reason: 'Feature is deprecated (frozen)'`), so neither `sync` nor `check --fix` moves a frozen
+  feature — see the freeze block in §Editing a feature.
 - **`[id]`** syncs one feature; **`--all`** syncs every feature with linked tasks. One of the two is
   required - exit `2` if neither is given.
 - **`--dry-run`** reports proposed transitions without applying. **`--force`** applies a *reopen*

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

@@ -126,12 +126,32 @@ mutually exclusive.
 spur task update 0040 wip
 ```
 
-Valid statuses: `backlog · todo · wip · testing · blocked · done · cancelled` (the lifecycle engine
-enforces legal transitions). Two transitions are **guarded by `check`**: `wip→testing` runs
-`spur task check <wbs> --as testing`, and `testing→done` runs `spur task check <wbs> --as done`
-(F92 R3 — target-aware guards) — a failing
+Valid statuses are the canonical `TaskStatus` vocabulary — **`TASK_STATUSES` in
+`packages/domain/src/planning/schema.ts` is the only list**, and the lifecycle engine enforces legal
+transitions against the shipped `task-lifecycle` graph (the engine's bundled workflow, resolved per
+project).
+Operator-facing semantics (the freeze, its guards, the exempt write set) live in the design
+satellite [`task-deprecated-status.md`](../../../../../docs/design/task-deprecated-status.md) — read it
+there rather than restating the vocabulary. Two transitions are **guarded by `check`**:
+`wip→testing` runs `spur task check <wbs> --as testing`, and `testing→done` runs
+`spur task check <wbs> --as done` (F92 R3 — target-aware guards) — a failing
 gate blocks the transition (§7.5).
 
+**`deprecated` — frozen but retained (ADR-137).** Non-terminal: the record stays readable and
+countable, but nothing new attaches to it and it never advances. Legal edges (from the shipped
+graph): `backlog`, `todo`, `wip`, `testing`, `blocked` and `done` may move to `deprecated`, and it leaves only to `todo`
+(un-deprecate, mandatory `History` entry) or `cancelled` (removed). Any other status write is
+refused by the graph, and the refusal names the un-deprecate command.
+
+Two guards carry the freeze past the graph: a **new** dependency edge onto a `deprecated` task is
+refused (ready-set resolver and pipeline preflight), and a live dependent is reported by the
+`L4.task-deprecated` warning. The freeze is prospective — an edge recorded before the deprecation is
+reported, never rewritten.
+
+Writes that stay **permitted** on a `deprecated` task (each edits the record rather than declaring
+the work resumable): `spur task record`, `migrate-anchors` and verdict writes, and
+`spur task update <wbs> --section <any>` — the section write lands and returns a freeze warning.
+
 **`--no-lifecycle`** suppresses lifecycle workflow *run record* creation (use during pipeline-driven
 transitions so nested lifecycle runs are not orphaned). **It is not a guard bypass** — the
 `wip→testing` / `testing→done` `check` gates still run, evaluated inline when the FSM guard does not.

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -572,7 +572,14 @@ does not earn another full-gate run:
 4. Give the test an explicit per-test timeout and a WHY comment (see
    `plugins/sp/tests/inline-run-close-reason.test.ts:100-102`) as soon as EITHER (a) the same test
    load-flakes in two separate runs, OR (b) it times out once **outside the change scope** and then
-   passes green alone on three consecutive isolated reruns. Waiting for a second gate run to license
+   passes green alone on three consecutive isolated reruns. **Prefer making the test cheap or
+   hermetic first** — a test that hashes the live checkout transitively, or writes a probe file into
+   it, should build a `mkdtemp` fixture repo instead of buying a bigger budget
+   (`packages/app/tests/workflow/actions/proof-fingerprint.test.ts` is the pattern, 2026-10-13).
+   Only then hand the remaining repeat flakers an explicit budget: the suite-wide `--timeout` is
+   not the lever, and raising it was measured NOT to help (a 60s suite default still failed 7
+   spawn-heavy tests under a host shared with two sibling agent suites, while every one passed
+   alone in 0.15-0.3s — 2026-10-13). Waiting for a second gate run to license
    the fix cost 21 minutes on 2026-10-08 (task 1128, the 1058 two-tree canary: 5145 ms then 5967 ms
    against bun's 5000 ms default, green 3/3 alone). Never raise the global timeout, skip the test,
    or loop full-gate reruns.

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

@@ -79,7 +79,7 @@ each would be scope creep for one-liner procedures.
 | 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                                             | `[<file>] [--since <ref>] [--until <ref>] [--version <ver>]`                                                                                                                                            |
-| 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>]`                                                                                                                            |
+| 9   | gitmsg     | `dev-gitmsg`        | `inline`          | bounded diff capture → concern grouping → conventional commit                      | `[--commit] [--squash] [--all] [--scope <path>] [--check <cmd>]`                                                                                                           |
 | 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>` |
@@ -250,7 +250,8 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
   checklist** against target sections (read codebases, ADRs, dependent WBS, dogfood evidence as
   needed). If any item fails, synthesize and rewrite via CLI-gated section updates until all pass
   (or surface a blocked Q&A with a concrete question). Outcome vocabulary: `refined` (wrote) |
-  `ready` (checklist already met, no write — optional alias of refined with zero writes) | `failed`.
+  `ready` (checklist already met, no write — optional alias of refined with zero writes) |
+  `cancelled` (issue triage found no valid issue — see `premises`) | `failed`.
   Prefer reporting `refined` when any section changed; if checklist already fully met, emit:
 
   ```
@@ -295,6 +296,17 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
        list`, `spur task list --status wip --json`) are recorded in References/Design.
      - **Scope** — the work is not already done, and not owned by another task.
 
+     **Issue triage.** When the task bundles several issues (findings, defects, R-items with their
+     proposed fixes), judge each one separately as `valid` (reproduced or confirmed in the current
+     tree), `already-fixed`, `owned-elsewhere` (name the WBS) or `invalid` (premise false). An issue
+     that is not `valid` is removed **with everything that exists only for it**: its Background
+     paragraph, R-items, Design/Solution notes, Plan steps and ACs. Renumber nothing that other
+     tasks or feature scenarios cite; leave a gap instead. Each removal is one correction-record
+     line. When **no** issue stays valid, do not rewrite the task. Record the triage in the
+     correction block, then `spur task update <wbs> cancelled --json`, and report outcome
+     `cancelled`. Cancelling is not demotion; it is valid only within the backlog/todo status scope
+     above.
+
      Contradictions are corrected in **this** refine (rewrite the claim, or re-point the design at
      ground truth), never deferred to the implementer. `--depth ready` exists so a downstream agent
      does not re-derive the analysis; a frozen design built on a false premise is the worst
@@ -309,7 +321,10 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
   1. Run `spur task check <wbs> --as todo --json`. Any error means the task is not ready. Fix it,
      or report `failed`.
   2. Fill metadata that is still unset: `spur task update <wbs> --priority <P0–P3>` and
-     `--estimate-hours <n>` (both `--json`). Never overwrite a value the operator set.
+     `--estimate-hours <n>` (both `--json`). Never overwrite a value the operator set. The one
+     exception is a triage that dropped issues: re-estimate the remaining scope and record
+     old → new in the correction block. The CLI cannot rename a task. When a drop leaves the title
+     naming removed scope, record that in the correction block as well.
   3. Promote `backlog → todo` idempotently with `spur task update <wbs> todo --json`, the same FSM
      transition `--next` uses. Create-time ready preparation skips its own promotion when the task
      is already `todo`, and next-router stops routing the task back to refine. Without `--next`,
@@ -341,9 +356,10 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
   3. Topo-sort by `dependencies[]` (Kahn, WBS-ascending tie-break). Cycle → abort entire batch before any refine. Out-of-set deps: `done` → allow; else → block subtree (same as runall).
   4. For each WBS in order: invoke single-task refine with shared flags **including `--depth`**. Under `--auto` + **`--depth standard`** (default), the per-task **L3 pre-synthesis SKIP gate** still applies. Under **`--depth ready`**, each task runs the implement-ready checklist (no L3-only SKIP). That includes the premises audit, the correction record and ready finalization, so a passing task leaves at `todo`.
   5. Failure policy: **stop-the-batch** (default) or `--keep-going` (skip in-batch dependents of a failed refine; continue independents).
-  6. Emit a batch report (markdown or `--json`) that records `depth` once at the header. Under `--depth ready`, each row also carries the corrections count, status before → after, and failed checklist ids.
-- **Per-task outcome vocabulary:** `refined` (synthesis wrote sections) | `SKIP` (already meets the active depth bar under `--auto`) | `failed` | `skipped` (dep failed under `--keep-going`) | `not-attempted` (halted) | `blocked` (unmet out-of-set dep).
-- **Batch verdict:** `clean` (all attempted tasks `refined` or `SKIP`) | `halted` (a failure stopped the batch) | `aborted` (cycle / unknown selector / empty set after filter).
+  6. Emit a batch report (markdown or `--json`) that records `depth` once at the header. Under `--depth ready`, each row also carries the corrections count, dropped issues, status before → after, and failed checklist ids.
+  7. **Cross-task proposals (`--depth ready` only).** After the per-task pass, list two kinds of proposals in the report: tasks whose remaining issues overlap another set member (same root cause or file set → name the merge target; tasks that only share a step, such as one upstream release, or that fix two layers of one failure → propose ordering or a shared step, not a merge), and tasks with no `feature_id` (name the candidate owning feature with evidence). These are proposals only. Refineall merges, cancels or links a task only when the operator's `--description` names that task and the action (e.g. `cancel 0273 and merge its issues into 0269; link 0260 to G11`). That explicit directive is the confirmation the [feature-link helper](feature-link-helper.md) requires. A merge moves the surviving issues with their fixes into the target through CLI section updates, records the merge in both tasks' correction blocks, then cancels the source. Run directives before the per-task pass, so each target is refined with its merged content.
+- **Per-task outcome vocabulary:** `refined` (synthesis wrote sections) | `SKIP` (already meets the active depth bar under `--auto`) | `cancelled` (no valid issue left, or merged away by directive) | `failed` | `skipped` (dep failed under `--keep-going`) | `not-attempted` (halted) | `blocked` (unmet out-of-set dep).
+- **Batch verdict:** `clean` (all attempted tasks `refined`, `SKIP` or `cancelled`) | `halted` (a failure stopped the batch) | `aborted` (cycle / unknown selector / empty set after filter).
 - **`--next` is not accepted** (dropped by feature H8, 2026-07-31 — see `plugins/sp/commands/dev-refineall.md` for the removal record). Chain execution explicitly: refineall, then `/sp:dev-runall --feature <id>`.
 - **`--auto` recommendation:** Batch refine without `--auto` requires per-task interactive Q&A and does not scale. Default operator path: `/sp:dev-refineall --feature <id> --auto`. For implement handoffs, or to re-audit a feature's filed tasks: `/sp:dev-refineall --feature <id> --auto --depth ready`.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="refineall $ARGUMENTS")` → per task `Skill(skill="sp:spur-dev", args="refine <wbs> $SHARED_FLAGS")` (shared flags include `--depth` when set).
@@ -375,7 +391,7 @@ check receipt (`receipt.runId === runId`), otherwise `n/a (<reason>)`. Any value
 - **Behavior:**
   1. Parse arguments, preserving quoted paths with spaces. Reject a missing/empty path, repeated `--file`, unknown flags, or extra positional arguments with usage. Resolve the absolute path before changing directories. Reject a directory target; create missing parent directories. Respect CLI-gated corpus writes: task/feature documents cannot be dump targets.
   2. Gather the mission, original invocation/options, approved outcome, completed and partial work, blockers, and next actions. Verify repository/worktree paths, branch, HEAD/base, dirty files and relevant commits with Git. Inspect referenced tasks/features/runs through the CLI facade with `--json` in their execution directory. Preserve frozen batch membership, dependency order, run IDs, workflow/checkpoint identity, failure policy, executor state and worktree marker when applicable. Record inspection time and provenance; label unavailable facts `unknown`.
-  3. Fill every template section for this job; use `N/A` where inapplicable. Include uncommitted work and ownership, gate commands/results, pending questions, approvals given or still required, discovery maps, evidence paths, and wrap/merge/cleanup success conditions. Keep confirmed lessons and rejected approaches with anchors. Link authoritative specifications instead of copying them; never turn task-specific bypasses into general instructions.
+  3. Fill every template section for this job; use `N/A` where inapplicable. Include uncommitted work and ownership, gate commands/results already on record (never run a gate to fill this — write `not run`), pending questions, approvals given or still required, discovery maps, evidence paths, and wrap/merge/cleanup success conditions. Keep confirmed lessons and rejected approaches with anchors. Link authoritative specifications instead of copying them; never turn task-specific bypasses into general instructions.
   4. Redact credentials, tokens and sensitive personal data. Link large logs/artifacts by path and note their durability and availability to the recipient; the Markdown file does not transfer referenced files. Include essential continuation context directly so missing optional scratch notes do not erase the plan.
   5. Construct the complete snapshot before writing or refreshing `--file`. Read it back to verify the mission, execution directory, ordered remaining work and first actions. Report the absolute path and unresolved facts. Dumping only saves context: it does not stop an active executor, execute remaining work, change lifecycle state, commit, merge, or remove a worktree; record any executor still running.
 
@@ -552,6 +568,14 @@ gate commands, pending questions and approval requirements.>
 These define their procedure directly in the command file. No `Skill()` delegation — the command
 is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent reasoning.
 
+**Gate ownership.** A project quality gate (`bun run gate`, `spur-check`, lint, typecheck, tests,
+rule runs) runs only where an operation's own contract names it: the pipeline `test` hop
+(`run`/`runall`), `fixall`, `gtd`, `fixgha`, `unit`, and the `--check <cmd>` loops. The scribe
+operations — `changelog`, `gitmsg`, `handover`, `job-dump` — produce text or a commit, not code, so
+they run **no gate by default**, and a generic "verify before you finish" rule from `AGENTS.md` or
+host instructions does not add one. An opt-in gate is explicit: `gitmsg --check <cmd>`, or
+`/sp:dev-gtd [--no-push]` for gate → auto-fix → commit. Commit hooks still run as configured.
+
 ### 8. changelog
 
 - **Purpose:** Generate a structured changelog from git commits between two refs.
@@ -568,12 +592,12 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
   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.
+- **Invariants:** Output is derived from `git log` only. No quality gates — no `bun run gate`/lint/typecheck/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
 
 - **Purpose:** Generate conventional commit message(s) for the current change set — one gather call → concern grouping → one message per concern; optionally commit. Git + POSIX shell only; no helper script.
-- **Inputs:** `--scope <path>` (default: the whole change set) — path filter; an explicit `--scope` always wins over change-set auto-discovery. `--all` (default: off) — widen the change set past the index to every change in the tree: unstaged **and untracked** files. Omitted, the change set is the index only, which keeps pre-commit semantics stable. `--commit` (default: off) — commit the change set, one commit per concern. `--squash` (default: off) — collapse every concern into one message and one commit; implies `--commit`.
+- **Inputs:** `--scope <path>` (default: the whole change set) — path filter; an explicit `--scope` always wins over change-set auto-discovery. `--check <cmd>` (default: off) — run `<cmd>` once as a pre-commit gate (step 5a). `--all` (default: off) — widen the change set past the index to every change in the tree: unstaged **and untracked** files. Omitted, the change set is the index only, which keeps pre-commit semantics stable. `--commit` (default: off) — commit the change set, one commit per concern. `--squash` (default: off) — collapse every concern into one message and one commit; implies `--commit`.
 - **Backing:** `inline` — one bounded gather call + concern grouping + conventional commit formatting.
 - **Behavior:**
 
@@ -631,6 +655,8 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 
   5. **Report.** Print: one context line (branch; `linked worktree` when `--git-dir` ≠ `--git-common-dir` and the superproject line is empty), then each message in a fenced block. No per-file summaries, no restated diff. With neither `--commit` nor `--squash`, add one copy-paste `git commit` line per message and stop.
 
+  5a. **Gate (`--check <cmd>` only) — one more Bash call.** Without `--check`, run no gate of any kind. With it, run `<cmd>` exactly once, verbatim, after the report: exit 0 → one `check PASS` line and continue; non-zero → print its last 30 lines and commit nothing. Never fix, retry, or widen the command — gate → fix → commit is `/sp:dev-gtd`.
+
   6. **Commit (`--commit` / `--squash`) — one more Bash call.** `--squash` implies `--commit`, so both together is just `--squash`. Refuse before touching the index when:
      - `## secret hits` is non-empty → print each `file: line`, commit nothing;
      - `--commit` would split (more than one group) and `## partially staged` is non-empty → splitting would widen those `git add -p` stagings to whole files; print the paths and commit nothing (`--squash` is allowed — it commits the index as staged).
@@ -649,7 +675,7 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
 
      Hooks stay enabled; a failing hook stops the run with its output — never `--no-verify`.
 
-- **Invariants:** Git and POSIX shell only — no helper script, no temp file. At most two Bash calls: gather, then (only when committing) commit. With neither `--commit` nor `--squash`, never runs `git commit` — message only. Neither flag commits across a secret hit, and `--commit` never splits across a partial staging. Without `--all` the change set is the index, so plain `/sp:dev-gitmsg` keeps pre-commit semantics; only `--all` reaches unstaged and untracked files, and only a committing run stages them. The empty-index widen is read-only and always announced — a committing run never widens its own scope. An explicit `--scope <path>` always bounds the change set, with or without `--all`. One bounded, context-free capture per run — never a second, wider read.
+- **Invariants:** Git and POSIX shell only — no helper script, no temp file. At most two Bash calls: gather, then (only when committing) commit — three with `--check`. No quality gate (`bun run gate`, lint, typecheck, tests, `spur-check`) unless `--check` names one. With neither `--commit` nor `--squash`, never runs `git commit` — message only. Neither flag commits across a secret hit, and `--commit` never splits across a partial staging. Without `--all` the change set is the index, so plain `/sp:dev-gitmsg` keeps pre-commit semantics; only `--all` reaches unstaged and untracked files, and only a committing run stages them. The empty-index widen is read-only and always announced — a committing run never widens its own scope. An explicit `--scope <path>` always bounds the change set, with or without `--all`. One bounded, context-free capture per run — never a second, wider read.
 
 ### 10. fixall
 
@@ -796,4 +822,4 @@ is the procedure. The backing is a combination of git CLI, `spur` CLI, and agent
   `## Testing`, `## Review`), verdict files (`.spur/run/<wbs>-verdict.json`), diffs, and docs — by
   **path**, not by pasting their content into the handover body. The handover is a pointer document;
   restating content it can instead link to makes it stale the moment the source changes.
-- **Invariants:** The handover is honest — rejected approaches are recorded so the next agent doesn't retry them. The blocker is specific, not "it doesn't work."
+- **Invariants:** The handover is honest — rejected approaches are recorded so the next agent doesn't retry them. The blocker is specific, not "it doesn't work." No quality gate runs — cite gate results already on record.

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

@@ -126,7 +126,7 @@ success exits 0 printing
 `{"ok":true,"persisted":<n>,"skipped":[{"id":<run-id>,"reason":"id-exists"|"external-key-conflict"|"record-conflict:<file>"|"record-missing:<file>"|"cited-directory:<name>"|"cited-symlink:<name>"|"cited-non-file:<name>"}],"evidenceSkipped":[{"name":<file>,"reason":"foreign-divergent","newer":"invoking"|"worktree"}]}`
 (`evidenceSkipped` is omitted when empty; the same object is written to `<invoking-tree>/.spur/run/persist-out.json` for `persist-out-check` to read)
 — an `external-key-conflict` skip leaves the target run unchanged **and fails the pass (1049)**: the delegate exits 1 printing `{"ok":false,"error":…}` naming the skipped source run ids, because that (workflow, external key) identity already belongs to a different receiving run — the batch was not persisted, so reconcile the source worktree by hand (it stays the provenance owner of record) before any teardown: auditable reconciliation names the original archived DB snapshot and the skipped source run identities, verifies the archive by file hash and by merged-commit ancestry of the source branch, and treats any residual deletion as explicit operator-authorized cleanup under the strict canonical evidence rules above. Task 1149 R1 grades a terminal duplicate lifecycle row (`task-lifecycle`/`feature-lifecycle`) as `external-key-conflict-bookkeeping` (non-fatal), so guarded transitions driven inside the worktree do not block teardown; the receiving lifecycle row is reconciled automatically during persist-out. An `id-exists` replay repairs missing owned artifacts and task links without duplicating them. A
-`record-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. A
+`record-conflict:<file>` never overwrites a divergent invoking-tree record and causes the delegate to exit 1, retaining the worktree. Before reconciling one by hand, check **what** the invoking record is: when the run closed `done` inside a linked worktree the owning tree holds that run's **WT-0 landing obligation** (`landing: required branch=… path=… base=…`, see [execution-worktree-landing.md § WT-0](execution-worktree-landing.md#wt-0--markerless-worktree-runs)) — a 3-line record that is *not* a stub of the worktree's stage narrative, so copying the worktree record over it destroys the very obligation a later merge must rewrite. The reconciliation is therefore: discharge the obligation in place (`landing: merged <sha>` or `landing: retained`), and preserve the worktree narrative beside it (e.g. `<runId>.worktree-provenance.md`) rather than in place of it. A
 `record-missing:<file>` skip is a known `task-lifecycle`/`feature-lifecycle` row with no record file
 at all (its inserted DB row still counts in `persisted` — 0984 R5). Any failure
 exits 1 printing `{"ok":false,"error":<message>}` (a worktree DB run id that is not a single safe

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

@@ -152,8 +152,8 @@ kickoff** — the driver never re-queries `spur task list` to recompute membersh
 | --- | --- | --- |
 | Explicit WBS list | `^[0-9, ]+$` | Split on comma; validate each token is a 4-digit WBS; collect the explicit set. (R1.1) |
 | `feature:<id>` (via `--tasks` or `--feature <id>`) | literal `feature:` prefix or `--feature` flag | `spur task list --feature <id> --json`; collect `wbs` from each row. The `--feature` flag is sugar that becomes `--tasks feature:<id>` at the command layer. (R1.3) |
-| `ready` | literal `ready` | Resolve the union of `spur task list --status todo --json` + `spur task list --status backlog --json`, drop tasks with open children (R1.5, umbrella-parent exclusion below), then keep only tasks whose every `dependencies[]` entry resolves to `status == done` (via `spur task show <dep> --json | jq '{wbs, status, dependencies, feature_id}'` — R5 metadata-only). Report each excluded task with its unmet dependency. (R1.4) |
-| Status pseudo-list | `todo` \| `backlog` \| `wip` \| `blocked` \| `testing` | `spur task list --status <value> --json`; collect `wbs` from each row. (R1.2) |
+| `ready` | literal `ready` | Resolve the union of `spur task list --status todo --json` + `spur task list --status backlog --json`, drop tasks with open children (R1.5, umbrella-parent exclusion below), then keep only tasks whose every `dependencies[]` entry resolves to `status == done` (via `spur task show <dep> --json | jq '{wbs, status, dependencies, feature_id}'` — R5 metadata-only). Report each excluded task with its unmet dependency. A `deprecated` dependency is *not* satisfied (ADR-137: a frozen task never reads as `done`), so it keeps its dependents out of the ready set. (R1.4) |
+| Status pseudo-list | `todo` \| `backlog` \| `wip` \| `blocked` \| `testing` | `spur task list --status <value> --json`; collect `wbs` from each row. (R1.2) `deprecated` is deliberately not a selector value: a frozen task has no pipeline hop to drive, so a batch is never built from that status (ADR-137; `/sp:dev-next` row A10 stops the same way). |
 | *(else)* | no match | Error: "unknown selector `<value>`" — list the valid forms and halt before running anything. |
 
 **Dedup:** an explicit list with a repeated WBS (`--tasks 0040,0040`) collapses to a single entry;
@@ -200,7 +200,9 @@ For each dependency edge to a task **outside** the frozen set, resolve its curre
 - status ≠ `done` → mark the dependent **blocked**. Transitively mark its in-set descendants blocked
   too (fixpoint propagation: any task depending on a blocked task is itself blocked). Exclude all
   blocked tasks from execution and record the unmet dependency + the blocked subtree for the report
-  (R2.4). Independent (non-blocked) tasks in the set still run.
+  (R2.4). Independent (non-blocked) tasks in the set still run. **`deprecated` is not satisfied**
+  (ADR-137): a frozen task never reads as `done`, so the dependent blocks and the report names the
+  remedy — re-point the edge, or un-deprecate (`spur task update <dep> todo`).
 
 ### 2.4 Topological sort
 
@@ -277,6 +279,7 @@ node "$(superskill script path sp batch-preflight.mjs)" \
 | `action: skip` code **A2** | Do not launch; report `preflight-skip` + unmet deps (mirrors TABLE A2) |
 | `action: skip` code **A7** | Do not launch; report blocked (handover is operator-side) |
 | `action: skip` code **A8**/**A9** | Do not launch; already done / cancelled |
+| `action: skip` code **DEPRECATED** | Do not launch; frozen and retained (ADR-137) — the reason line names the un-deprecate command. A deprecated WBS can reach preflight through an explicit `--tasks` list or a `feature:<id>` selector (`spur task list --feature` reports every linked row, whatever its status); the `ready` and status pseudo-lists exclude it |
 
 **Invariants:** Preflight never replaces the pipeline with a loop of `/sp:dev-next`. TABLES A/B/C
 remain SSOT in `next-router/references/routing-table.md`. Step 2.3 already pre-blocks many unmet
@@ -606,15 +609,25 @@ The cheap rule gates fail fast when run first — the full-gate run is dominated
 suite, so a gate run that dies at `test-post-check` or `corpus-check` wastes most of its wall time.
 Before launching a full `spur-check-new`:
 
-1. **Run the two rule gates first** — `bun run test-pre-check` (43 rules: `no-console-output`,
+1. **Run the static checks first** — `bun run lint` (biome over the whole tree plus every workspace
+   typecheck). They fail in ~20 s and are the two defects that most often kill a full launch: a
+   formatting miss in a touched test file, or a generated declaration surface that no longer lists a
+   new export. Measured 2026-10-12: two consecutive `spur-check` launches died here and each spent
+   its whole wall time before reaching the suite.
+2. **Then the two rule gates** — `bun run test-pre-check` (43 rules: `no-console-output`,
    `no-direct-process-spawn`, `cli-*`, `require-corresponding-test`) and `bun run test-post-check`
    (`every-export-has-tsdoc`, `coverage-gate`). They catch boundary/TSDoc violations in seconds.
-2. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
+   Two `coverage-gate` facts change how you call post-check: it **fails closed when
+   `.coverage/lcov.info` is absent**, which is the normal state of a fresh worktree, so run it after
+   the suite has written coverage or expect that one error instead of reading it as a finding; and a
+   targeted `bun test <file>` **overwrites** the tracefile, so post-check judges partial data if it
+   runs after one (the `coverage-gate` rule's own header documents both facts).
+3. **Promoted code must satisfy the boundary rules `scripts/` never enforced.** A command module
    moving from `scripts/` into `apps/cli/src` must route output through the `CommandOutput` seam (no
    `console.*`), spawn processes via `NodeProcessExecutor` (no `Bun.spawnSync`), get a
    `runtime-boundaries` fs-io exemption for sync reads (mirrors `task.ts`), and a non-command helper
    must not live in `apps/cli/src/commands/` (the noun scan treats every file there as a noun).
-3. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — the per-task gate surfaces
+4. **Doc/TSDoc edits shift `file:line` anchors** cited by other tasks — the per-task gate surfaces
    them as `L4.anchor-subject-mismatch` (0775: the corpus sweep retired; run `spur task check <wbs>`
    on touched tasks). Repoint the shifted citations (via `spur task update --section`)
 

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

@@ -16,6 +16,28 @@ When the batch completes with **no failed task**, fast-forward-merge the worktre
 base ref. The terminal action after the merge differs by mode (ownership rule: *the flag removes
 only what it created*):
 
+**Duplicate-WBS sweep before the merge (observed 2026-10-12).** WBS allocation is per-tree — a
+worktree's allocator reads only its own corpus and DB — so two trees cut from the same base both
+allocate the same next number, and the collision surfaces only here (measured: the F42 batch's
+residual task shipped as `1183` while the base ref had already given `1183` to another task, so the
+file had to be re-filed before landing). Run this against the ref you are about to merge INTO:
+
+```bash
+TARGET=<base-ref>; BRANCH=sp/<branch>
+for f in $(git diff --diff-filter=A --name-only "$(git merge-base "$TARGET" "$BRANCH")..$BRANCH" -- docs \
+           | grep -E '^docs/tasks[0-9]*/'); do
+  wbs=$(basename "$f" | cut -c1-4)
+  git ls-tree -r --name-only "$TARGET" -- docs | grep -qE "/${wbs}_" && echo "COLLISION $wbs $f"
+done
+```
+
+A hit means one file must lose: keep the target's task, re-create the branch's task in the invoking
+tree through `spur task create` (the allocator picks the next free number), and drop the branch's
+file in the merge resolution — never land both, and never renumber by hand. Verified against a
+fixture (flags a duplicate, silent on a free WBS). The pathspec form is load-bearing: `-- docs` plus
+the `^docs/tasks[0-9]*/` filter, because plain `docs/tasks*` matches nothing under `ls-tree` here and
+`:(glob)` magic is rejected by `ls-tree`/`diff` (it works for `git status`).
+
 #### Create mode — merge, remove, delete
 
 ```bash

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

@@ -180,6 +180,13 @@ main-repo hooks from inside the "isolated" tree. Scripts are skipped only at thi
 a normal clone keeps `prepare`. The worktree still gets a usable dependency tree — the install
 exists so the first `bun test` resolves workspace imports.
 
+**Generated trees are still missing after the install.** A gitignored generated tree does not ride the
+worktree, so any suite comparing the canonical source against its generated copy fails until the
+generator runs. In this repo that is `apps/cli/config/` (from `bun run bundle:config`): without it
+`plugins/sp/tests/command-flag-parity.test.ts` fails on the missing generated pipeline YAML under that
+directory (observed 2026-10-12, A91 batch). Run the generator once after a create-mode install, and
+again after a rebase or merge that touches the canonical workflow sources it is built from.
+
 #### Reuse mode (`--worktree <name>`)
 
 Creation is **skipped entirely**. `$BRANCH` is the resolved worktree's already-checked-out branch; a
@@ -374,6 +381,13 @@ same call, verifies the WT-3 identity, and never relies on a persistent `cd` or
 > concurrent writer happened to leave in the tree — the two incidents this guard exists for are
 > `a94f9f431` and `36f274590` — so a driver stages only through `commit-guard stage`.
 
+> **`stage` takes files, never directories.** A directory argument is refused as `(unchanged since
+> base)` and stages *nothing*, so a task whose diff lives in a moved tree must expand the changed
+> paths (`git status --porcelain` plus the filter for the task's own files) instead of passing
+> `plugins/sp/hooks` or `packages/app/tests/hooks`. Symptom observed on 2026-10-12 (A91 batch): the
+> first commit captured only the pre-staged `git mv`/`git rm` renames and needed an amend to carry
+> the rest of the task.
+
 The FF-only git merge carries only commits — uncommitted writes in the worktree would be left
 behind by the merge and then destroyed by create mode's `git worktree remove`. WT-3b exists so
 that can never happen.

package/plugins/sp/skills/spur-dev/references/flag-glossary.md

@@ -225,8 +225,10 @@ the `feature:<id>` sets, resolved once and frozen.
 
 **Anchor:** `#flag-check`.
 
-Verification command a command iterates against (`dev-simplify`, `dev-refactor`). The command
+Verification command a command iterates against (`dev-simplify`, `dev-refactor`, `dev-gitmsg`). The command
 establishes a baseline with it before the first change and re-runs it after each change.
+`dev-gitmsg` uses it as a one-shot opt-in pre-commit gate: run once, non-zero commits nothing, no
+fix loop. A command without `--check` in its contract runs no gate.
 
 ### `--focus <dims>` — constrain the operation to specific dimensions
 
@@ -462,7 +464,7 @@ Orthogonal to `--focus` (which _narrows_ domains) and to `--mode` on other comma
 | Value (refine family)             | Bar                                                                                                                                                                                | `--auto` SKIP behavior                                                                             |
 | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
 | `standard` (default when omitted) | L3 structural completeness (not empty/placeholder; check-clean for target sections)                                                                                                | **SKIP** when no L3 findings on target sections                                                    |
-| `ready`                           | **Implement-ready** freeze: another agent can implement without inventing design (frozen names/APIs or explicit "no new API", anti-patterns, file targets, handoffs, out-of-scope) | **Do not SKIP** on L3-clean alone — audit existing claims, run the ready checklist, rewrite sections until the bar is met, then promote `backlog → todo` |
+| `ready`                           | **Implement-ready** freeze: another agent can implement without inventing design (frozen names/APIs or explicit "no new API", anti-patterns, file targets, handoffs, out-of-scope) | **Do not SKIP** on L3-clean alone — audit existing claims, drop invalid issues with their fixes (cancel when none stays valid), run the ready checklist, rewrite sections until the bar is met, then promote `backlog → todo` |
 
 Default for refine stays `standard` so ordinary `refineall --auto` remains cheap. Use `ready` for
 multi-package / multi-agent handoffs, flaky-pipeline features where a wrong implement is costly, and