@gobing-ai/spur 0.3.85 → 0.3.87

package/plugins/sp/skills/spur-dev/references/ac-style-guide.md

@@ -27,6 +27,14 @@ Rules:
 - **One R-number = one scenario.** Never split a requirement across multiple scenarios
   under the same R-number; never merge two requirements into one scenario.
 
+## Task-side numbering (`AC<n>`)
+
+`R<n>` is the **feature** scenario key and the **task Requirements** key. Task `### Acceptance
+Criteria` items therefore use their own namespace: `- [ ] AC1 — <title>` or `Scenario: AC1 — <title>`,
+numbered task-locally. Carry a feature scenario by copying its title after the prefix (`normalizeTitle`
+strips both `AC<n>` and `R<n>`, so DD-09 matching is unaffected); bind a task requirement with
+`(req: R<n>)`. Legacy tasks that wrote `- [ ] R<n> —` / `Scenario: R<n> —` keep working unchanged.
+
 ## Two AC tiers (authoring convention)
 
 A planning convention (DD-06 "permissive start"), not a `spur feature check` feature today —
@@ -73,6 +81,10 @@ scenario, it matches by title. Rules:
   Registered user can log in with email and password" is traceable.
 - **No synonyms in cross-references.** The title in the feature file and the title in the
   task's AC reference must be byte-identical.
+- **Avoid gate vocabulary in titles.** `spur task check` (L4.gate-language) rejects task sections
+  containing `HITL`, `approval`/`approved`, `merged`/`merge event`, `content-gate`, `GATED`, or
+  `capstone` as standalone words; task AC bullets copy scenario titles verbatim, so a title using
+  them fails every child task. Write "pause for an operator answer" instead of "HITL approval".
 
 ## Verdict AC ↔ feature scenario linkage
 
@@ -199,6 +211,18 @@ Use the canonical BDD template at `templates/bdd/gherkin.md`. Key rules:
 - **When** describes the single action under test.
 - **Then** asserts the observable outcome.
 - **And** chains additional preconditions, actions, or assertions.
+- **Trace the scenario to its requirements (0887 R4).** Directly under each `Scenario:`
+  heading add a comment line listing the requirement-inventory ids the scenario covers;
+  the BDD parser skips `#` comment lines, so the form is checker-inert:
+
+  ```gherkin
+  Scenario: Registered user can log in with email and password
+    # covers: I1, I3
+    Given ...
+  ```
+
+  Every inventory item without a `[deferred: ...]` marker must be covered by at least one
+  scenario — `idea-coverage-check` measures this at the idea-pipeline's ac-generate boundary.
 
 Avoid:
 

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

@@ -573,8 +573,6 @@ invariants that keep the pipeline set coherent as new ones are added.
 | `idea-pipeline.yaml` | Ideation + planning (vague idea or known slug → feature + AC + task batch) | `/sp:dev-idea`, `/sp:dev-plan` | `handoff`, `cancelled` |
 | `task-pipeline.yaml` | Execution (one task → done) | `/sp:dev-run` | `done`, `failed` |
 | `wrapup-pipeline.yaml` | Wrap-up (completed tasks → learning + metrics + doc-sync) | `/sp:dev-wrap`, `/sp:dev-wrapall` | `done`, `skipped` |
-| `feature-dev.yaml` | Umbrella (brainstorm → plan → execute → feature-verify) | `/sp:dev-runall --feature <id>` (or `--tasks feature:<id>`) | `done`, `failed` |
-| `basic.yaml` | Simple (generic implement/check/fix loop) | direct `spur workflow run` | `done`, `failed` |
 | `feature-lifecycle.yaml` | Feature status FSM (entity lifecycle, not a phase pipeline) | `spur feature update` | `done`, `cancelled` |
 | `task-lifecycle.yaml` | Task status FSM (entity lifecycle, not a phase pipeline) | `spur task update` | `done`, `cancelled` |
 
@@ -587,8 +585,9 @@ not replace them.
 A pipeline may invoke another workflow through a command wrapper or `spur workflow run` **only at a
 phase boundary** — it must NOT inline another pipeline's state graph. Concretely:
 
-- `feature-dev.yaml`'s `execute-tasks` state may invoke `task-pipeline.yaml` per task via
-  `spur workflow run` (phase boundary: design → execution).
+- The feature-level batch entry (`/sp:dev-runall --feature <id>`) dispatches `task-pipeline.yaml`
+  per task through the CLI command wrapper, not by inlining the task graph (feature roster →
+  execution boundary).
 - `idea-pipeline.yaml`'s `handoff` state may output a command for the operator to run
   `task-pipeline.yaml` (phase boundary: ideation → execution).
 - `task-pipeline.yaml`'s `implement` state must NOT contain a nested state machine for
@@ -692,7 +691,7 @@ Field semantics (enforced by `parseCheckpointMetadata` / `checkpointStaleness`):
 **Writer cadence (0784 R4).** There is exactly one canonical writer: the `task-pipeline` done
 state's terminal checkpoint (`status: done`, real HEAD, run id from `$__runId`, and `$wbs`-expanded
 artifact paths). It is a plain `shell` step — checkpoints are working memory, not CLI-gated corpus.
-The `feature-dev`, `wrapup-pipeline`, and `idea-pipeline` pipelines used to echo pseudo-checkpoints
+The `wrapup-pipeline`, and `idea-pipeline` pipelines (plus the since-retired `feature-dev`) used to echo pseudo-checkpoints
 ("checkpoint: <workflow> done ...") that violated the canonical schema; those writers were removed
 in 0784 — the persisted run row is the authoritative terminal record, and a non-canonical echo
 cannot be resumed, routed, or reclaimed safely.

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

@@ -85,7 +85,8 @@ each would be scope creep for one-liner procedures.
 | 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json]`                                                                          |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
-| 16  | idea       | `dev-idea`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<idea>" [--auto] [--skip-design] [--approve-taste] [--agent <inline\|auto\|name>]`                                                                                                                                                  |
+| 16  | idea       | `dev-idea`          | `Skill()`         | inline driver (`idea-pipeline`) or async workflow                                  | `"<idea>" [--from-file <path>] [--auto] [--skip-design] [--approve-taste] [--agent <inline\|auto\|name>]`                                                                                                                              |
+| 17  | refactor   | `dev-refactor`      | `Skill()`         | `sp:code-refactoring` skill (thin wrapper, ADR-032)                                | `[<description>] [--scope <path>] [--focus <api\|architect\|tests\|ui\|auto>] [--fix <none\|blockers-first\|all>] [--check <cmd>] [--agent <inline\|auto\|name>] [--auto]`                                                                                          |
 
 ## Skill-backed operations
 
@@ -335,11 +336,18 @@ must not be changed without updating the backing skill.
 ### 16. idea
 
 - **Purpose:** Turn a vague idea into a feature with AC and a decomposed task batch — the unified entry point for the planning half.
-- **Inputs:** `"<idea>"` (required, positional, quoted). Three everyday axes:
+- **Inputs:** `"<idea>"` (quoted) or `--from-file <path>` — exactly one; the two are mutually
+  exclusive (0887 R7). Three everyday axes:
   - `--auto` — skip **objective** HITL (feature-check, batch-create); taste gates still pause.
   - `--skip-design` — design package off (system-design + task Design).
   - `--approve-taste` — with `--auto`, skip **all** remaining taste pauses this run (idea-eval + design-approval). Sets `idea_approved=true` and `design_approved=true`.
     Aliases (prefer `--approve-taste`): `--idea-approved` → `idea_approved`; `--design-approved` → `design_approved`. There is **no** `--design` force flag.
+  - `--from-file <path>` — read the idea text from a file instead of the positional argument
+    (verbatim; long/multiline asks). Mutually exclusive with `"<idea>"`.
+- **Verbatim idea artifact:** before `start` executes, the driver persists the idea argument (or
+  `--from-file` contents) unmodified to `.spur/run/<run-id>-idea-input.md` (0887 R1); the precheck
+  fails the run when that file is empty or missing, and every model-bearing stage prompt treats
+  it as the authoritative ask (R2).
 - **Backing:** `idea-pipeline.yaml` through the inline driver for omitted/`inline`, or `spur workflow run idea-pipeline.yaml --async` for `auto`/name.
 - **Behavior:** Builds vars from the table above and drives the idea pipeline. Flow: discovery → **idea-eval** (taste; reject → cancelled) → feature-create → ac-generate → feature-check → system-design (conditional) → design-approval (taste) → decompose → batch-create (`--skip-ready`) → ready-prepare (ready checklist per created task + ready-evidence sidecar, 0788) → handoff. STOPS at handoff — no task execution, no pipeline nesting. Headless runs use one `trace --follow`; cancellation is reported stopped only when `workflow cancel --json` returns `killed: true`.
 - **Delegation:** Host-session inline driver by default; explicit executor selection uses the async workflow worker.
@@ -356,6 +364,14 @@ must not be changed without updating the backing skill.
 
 - **Taste pre-clear (`--approve-taste`):** owned with design-approval var semantics in [cross-cutting.md](cross-cutting.md) § "Design Approval Gate"; idea-eval uses the parallel `idea_approved` var. One CLI flag sets both.
 
+### 17. refactor
+
+- **Purpose:** Lens-routed refactoring with a preservation contract — route a scope through taste lenses (api / architect / tests / ui, auto-detected by path), classify findings on the shared `refactor-finding` schema, and apply via the fix ladder without breaking preserved behavior.
+- **Inputs:** `[<description>]` free-text steering, `--scope <path>` (default: working tree), `--focus <lens>` (default: auto), `--fix <policy>` (default: none), `--check <cmd>` (default: project gate), `--agent <selector>` (default: inline), `--auto` (default: off).
+- **Backing:** `sp:code-refactoring` skill — the command carries zero orchestration logic (ADR-032); the skill owns focus auto-detection, lens dispatch, the P1–P4 severity map, objective/taste gates, and the fix ladder with revert-on-regression.
+- **Behavior:** Green `--check` baseline → focus detection → lens dispatch → findings to `.spur/run/<run-id>-refactor-findings.json` + human report `.spur/run/<run-id>-refactor-report.md` (lens set, P1–P4 table, preservation summary, applied/reverted/deferred). `--fix blockers-first` auto-applies P1/P2 `auto`-eligible findings; `--fix all` extends to `operator`-eligible P3/P4; every fix re-runs `--check` and reverts on regression. Tests are never removed or weakened by an `auto` fix.
+- **Operator taste gates:** every `cutting` or `breaking` finding pauses for an explicit operator answer in every mode — even `--auto` skips only objective gates. `--fix none` (the default) writes both artifacts with no edits.
+
 ---
 
 ## Inline operations

package/plugins/sp/skills/spur-dev/references/done-housekeeping.md

@@ -105,7 +105,7 @@ gate will reject the task without it). Use the normal `--section --from-file` co
 **4. Force-done with an honest reason.**
 
 ```bash
-SPUR_PROVENANCE_OVERRIDE=1 spur task update <wbs> done --force-done \
+spur task update <wbs> done --force-done --provenance-bypass \
   --reason "<step> agent.run timed out at <N>s; recovered manually: lint clean, <suite> pass, sections authored by hand"
 ```
 

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

@@ -160,13 +160,21 @@ Scope the operation to all tasks under a feature id (`^[A-Z][1-9]*$`). On featur
 commands (`dev-wrapall`) it also advances the feature through legal lifecycle edges with guards
 honored.
 
+### `--check <cmd>` — validation command for iterate-and-check loops
+
+**Anchor:** `#flag-check`.
+
+Verification command a command iterates against (`dev-simplify`, `dev-refactor`). The command
+establishes a baseline with it before the first change and re-runs it after each change.
+
 ### `--focus <dims>` — constrain the operation to specific dimensions
 
 **Anchor:** `#flag-focus`.
 
 Constrain the operation to a named subset of dimensions — review dimensions on `dev-review`/
 `dev-verify`/`dev-verifyall` (`all|stack|dependencies|data|flows|api|security|quality|performance`),
-a refine focus mode on `dev-refine`/`dev-refineall`, or a reconstruction lens on `dev-reverse`.
+a refactor lens set on `dev-refactor` (`api|architect|tests|ui|auto`), a refine focus mode on
+`dev-refine`/`dev-refineall`, or a reconstruction lens on `dev-reverse`.
 Narrowing reduces token cost; omitting runs
 all dimensions.
 
@@ -175,7 +183,7 @@ all dimensions.
 **Anchor:** `#flag-scope`.
 
 Limit the operation to a file or directory path (`dev-arch`, `dev-debug`, `dev-fixall`,
-`dev-gitmsg`, `dev-gtd`, `dev-simplify`) to bound the working set.
+`dev-gitmsg`, `dev-gtd`, `dev-refactor`, `dev-simplify`) to bound the working set.
 
 ### `--all` — widen the operation to everything in its domain
 
@@ -253,7 +261,8 @@ tasks by `updated_at >= date`).
 
 **Anchor:** `#flag-fix`.
 
-Remediation policy on verify-family commands (`dev-verify`, `dev-verifyall`):
+Remediation policy on verify-family commands (`dev-verify`, `dev-verifyall`) and the refactor
+coordinator (`dev-refactor`):
 `none|blockers-first|all`. `none` reports findings without fixing; `blockers-first` fixes only P1/P2;
 `all` fixes everything found. Deprecated on `dev-review` (routes to `dev-verify --fix`).
 
@@ -294,6 +303,16 @@ verifying a task whose artifact is intentionally not yet shippable (e.g. a doc-o
 Omit the design package (system-design satellite + task `### Design`) on planning commands
 (`dev-plan`, `dev-idea`). The task is created without the design section; refine supplies it later.
 
+### `--from-file <path>` — read the idea from a file (dev-idea)
+
+**Anchor:** `#flag-from-file`.
+
+`dev-idea` reads the idea text from `<path>` instead of the positional argument. Mutually
+exclusive with `"<idea>"` — exactly one must be present. The file's contents become the verbatim
+idea text, persisted unmodified to `.spur/run/<run-id>-idea-input.md` (0887 R1) and treated as
+the authoritative ask by every model-bearing stage prompt. Useful for long or multiline asks
+that are awkward to quote (0887 R7).
+
 ### `--output <path>` — write the result to a path
 
 **Anchor:** `#flag-output`.

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -149,11 +149,11 @@ passed, so provenance denied first and Review L3 denied on the retry.
 
 | # | Gate layer | Triggers denial when | Remediation |
 |---|------------|----------------------|-------------|
-| 1 | **Strict-core + verdict artifact** (`spur task check <wbs> --strict-core` + `done-transition-guard.ts`) | The strict-core check fails, or `.spur/run/<wbs>-verdict.json` is **missing** or has a non-PASS aggregate. **Missing artifact is a deny** (not a silent allow — closes the 0349 "done without verdict" class). The aggregate is recomputed from requirement/AC rows; the harsher of stored and computed wins. | Re-run `/sp:dev-verify <wbs>` until PASS (writes the artifact), or explicitly override with `spur task update <wbs> done --force-done --reason "<why>"`. Docs-only pipelines (`docs-pipeline.yaml`) meet the same layer: read-only measured verification
+| 1 | **Strict-core + verdict artifact** (`spur task check <wbs> --strict-core` + `done-transition-guard.ts`) | The strict-core check fails, or `.spur/run/<wbs>-verdict.json` is **missing** or has a non-PASS aggregate. **Missing artifact is a deny** (not a silent allow — closes the 0349 "done without verdict" class). The aggregate is recomputed from requirement/AC rows; the harsher of stored and computed wins. | Re-run `/sp:dev-verify <wbs>` until PASS (writes the artifact), or explicitly override with `spur task update <wbs> done --force-done --reason "<why>"`. Docs-only procedures meet the same layer: read-only measured verification
 (answer file + `spur task verdict`) writes the standard `.spur/run/<wbs>-verdict.json` artifact
 under proof-input digest bracketing; missing or non-PASS evidence is a refusal, never a synthetic
 PASS stub. |
-| 2 | **Provenance guard** (`lifecycle-adapter.ts`) | No pipeline-kind run link exists for `<wbs>`. | Run `/sp:dev-run <wbs>` through the full pipeline, use `/sp:dev-run <wbs> --mode implement --auto --next` for the explicit step chain, or record the audited bypass with `SPUR_PROVENANCE_OVERRIDE=1`. |
+| 2 | **Provenance guard** (`lifecycle-adapter.ts`) | No pipeline-kind run link exists for `<wbs>`. | Run `/sp:dev-run <wbs>` through the full pipeline, use `/sp:dev-run <wbs> --mode implement --auto --next` for the explicit step chain, or record the audited bypass with `--provenance-bypass` on `spur task update`. |
 | 3 | **Review L3** (`task-check.ts`) | `### Review` is empty, placeholder-only, or lacks a populated P1–P4 findings table. | Run `/sp:dev-review <wbs>`; verify cannot write Review because of the Step 10 prohibition above. |
 
 When the verdict is **PARTIAL/FAIL**, or any gate layer fails: stop as review-pending — surface

package/plugins/sp/skills/spur-dev/references/idea-evaluation.md

@@ -20,7 +20,9 @@ recommendation is mandatory, stakes in plain English, and approve/reject is the
 re-author the report.
 
 **Sidecar rule:** The enhanced idea does **not** overwrite `vars.idea`. Feature-create reads both
-the original idea and this report.
+the original idea and this report. The operator's verbatim ask of record is the run's
+`.spur/run/<run-id>-idea-input.md` (persisted by the pipeline `start` state / the inline driver
+before any processing); the `## Requirement inventory` items trace back to it.
 
 ## Template
 
@@ -30,6 +32,13 @@ the original idea and this report.
 ## Enhanced Idea
 <one-paragraph refined statement of what the idea actually requires — the "real requirement" after discovery sharpens the vague input>
 
+## Requirement inventory
+<mandatory — the coverage gate (idea-coverage-check) parses this section, so keep the exact `- I<n> — ` item form>
+- I1 — <requirement stated as an ask, quoting or paraphrasing the source line from the run's idea-input artifact> (source: "<quoted fragment from the operator's idea>")
+- I2 — <next requirement>
+- I<n> — <optional: a requirement explicitly out of scope> [deferred: <reason>]
+- I<n> — <optional: an ambiguous ask> [unclear: <why it is ambiguous>] — an unclear marker does not exempt the item; it still needs coverage or an explicit deferral
+
 ## Scores
 
 | Dimension | Score (0–5) | Rationale |
@@ -74,6 +83,7 @@ Stakes: <plain-English cost of proceeding vs not; reversibility; blast radius>
 |------|--------|
 | Filled instance path | `.spur/run/idea-eval-report.md` |
 | Template home | this file |
+| Requirement inventory | mandatory `## Requirement inventory` section (0887 R3); consumed by `idea-coverage-check` (R4) |
 | HITL state | `idea-eval` in `idea-pipeline.yaml` |
 | Approve | continue → `feature-create` |
 | Reject / cancel | → `cancelled` (no feature) |

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

@@ -25,7 +25,11 @@ implements it; remove the entry when the corresponding kind is dropped from the
 
 **Actions:** `shell` · `note` · `doctor.probe` · `file.read.into-var` · `hitl.confirm` · `agent.run` · `proof.fingerprint` · `run.artifact` · `command.gate`
 
-**Guards (transitions):** `always` · `shell`
+**Guards (transitions):** `always` · `shell` · `action-ok` · `contract-violation`
+
+- `action-ok` — pass iff the prior action on this state/node succeeded (engine builtin).
+- `contract-violation` — pass iff the prior `agent.run` result is a named contract violation
+  (`data.outcome === 'contract-violation'`, ADR-118); the report carries `contract` and `observed`.
 
 ## What this driver is
 
@@ -156,6 +160,35 @@ the human/native presentation layer — labels are display addresses only, never
    This is required for the normal `testing → done` provenance guard. Planning pipelines have no
    task lifecycle link and skip this task-specific action.
 
+### Idea-pipeline quick start (0887 R1/R2)
+
+Minimum files to read for `/sp:dev-idea` inline runs — then drive `idea-pipeline.yaml`:
+
+- `.spur/workflows/idea-pipeline.yaml` (the machine) and this driver.
+- `plugins/sp/skills/spur-dev/references/idea-evaluation.md` (report template incl. the mandatory
+  `## Requirement inventory`) and `references/ac-style-guide.md` (scenario `# covers:` form).
+- `references/dev-operations.md` § idea for the stage-by-stage surface.
+
+**Persist the verbatim idea FIRST.** Before executing the `start` state, write the operator's
+idea argument (or `--from-file` contents) **unmodified** to
+`.spur/run/<run-id>-idea-input.md`; the run precheck fails when that file is empty or missing,
+and every model-bearing stage prompt treats it as the authoritative ask. `--from-file` and the
+positional idea are mutually exclusive — exactly one must be present.
+
+Expected artifacts per stage (all run-scoped under `.spur/run/<run-id>-*`):
+
+| Stage | Artifacts |
+| ----- | --------- |
+| start | `-idea-input.md` (verbatim idea), `-idea-precheck-doctor.status` |
+| discovery | `-idea-eval-report.md` (with `## Requirement inventory`), `-idea-needs-design.json` |
+| feature-create | `-idea-feature-id.txt`, `-idea-goal.md`, `-idea-scope.md` |
+| ac-generate | `-idea-ac-content.md`, `-idea-ac-check.status`, `-idea-coverage.status` |
+| system-design | `-idea-design-review.md`, `-idea-design-check.status` |
+| decompose | `-idea-task-batch.json`, `-idea-task-order.json` |
+| batch-create-run | `-idea-batch-create-result.json`, `-idea-batch-create.done`/`.failed` |
+| ready-prepare | `-idea-ready.json` |
+| handoff-finalize | `-idea-handoff.md` |
+
 ## Comprehensive-check retention and evidence (R7/R8)
 
 **R7 — comprehensive checks stay at their owning boundaries.** Quick readiness and plan projection are
@@ -398,6 +431,63 @@ keep their exact content after the stamp prefix. This normalization is contractu
 **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).
 
+## Structured trace emission (ADR-117, task 0868)
+
+`.spur/run/<run-id>.log` is a human convenience, **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.
+
+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:
+
+- **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:
+
+  ```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>
+  ```
+
+  `<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. 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.
+
+- **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>
+  ```
+
+  `--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`.
+
+**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/run/<run-id>.log` 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.

package/plugins/sp/skills/taste-refactoring-api/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: taste-refactoring-api
 description: Design, review, and refactor REST/HTTP, RPC/gRPC, GraphQL, and event API contracts safely.
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - refactor-apis
+  openclaw:
+    emoji: "🔌"
 ---
 
 # taste-refactoring-api
@@ -174,7 +186,7 @@ The goal is to eliminate repeated low-level API decisions, not to create bureauc
 
 ## Protocol-specific review
 
-After classifying the API, read the matching REST/HTTP, RPC/gRPC, GraphQL, or event/webhook section in [references/protocol-modes.md](references/protocol-modes.md). Apply that checklist before continuing with the refactoring strategy.
+After classifying the API, read the matching REST/HTTP, RPC/gRPC, GraphQL, or event/webhook section in [references/protocol-modes.md](references/protocol-modes.md). Apply that checklist before continuing with the refactoring strategy. For command-line surface work (designing or reviewing a CLI), read the [CLI mode](references/protocol-modes.md) section instead — a CLI is a contract surface with the same compatibility duties as any wire protocol.
 
 ## Refactoring strategy
 
@@ -332,3 +344,34 @@ Specify the tests/checks needed: contract tests, schema validation, compatibilit
 ## Decision rule
 
 A “better” API is not the one with the prettiest route names. It is the one that makes common client code obvious, predictable, safe under failure, compatible over time, secure by default, and operable in production.
+
+## Spur contract
+
+Machine-facing adapter for `sp:code-refactoring` dispatch (feature H13). Everything above is the
+lens's native output and is unchanged; this section only maps it to the shared finding schema.
+
+**Inputs received:** a scope path, an optional change description, and the `api` focus. Read
+first: the classification and protocol section above (plus [references/protocol-modes.md](references/protocol-modes.md)),
+then `../code-refactoring/references/finding-schema.md` for shared field semantics.
+
+**Native finding → schema mapping:** each “Highest-impact refactor” item → `id` as
+`RF-api-<nnn>`; the item's compatibility label → `rung` verbatim (`additive` | `risky` |
+`breaking`); consumer impact → `title` and `proposal` (imperative); cited routes/lines →
+`evidence` as `{file, line}` entries inside scope; `Verification` items → `verify`; the
+“Proposed contract” snippets stay in `proposal`; new findings start at `status: open`.
+
+**Severity mapping (design §5):** a `breaking` change already shipped, or contract ambiguity that
+corrupts data → `P1`; a `risky` inconsistency across ≥2 endpoints → `P2`; `additive` cleanups →
+`P3`; naming/docs → `P4`.
+
+**Preserved-behavior inventory (required before proposals):** emit the consumer contract —
+audience (public/partner/internal/service-to-service), endpoints/operations in scope, existing
+clients that must remain compatible, and the compatibility promise — before the first finding.
+
+**Preservation class (reuses the native classification):** `additive` → `preserving`; `risky`
+and `breaking` → `breaking`; removal of an endpoint, field, or code path with callers →
+`cutting` even when the change reads additive to remaining consumers.
+
+**Stop rules:** an established style guide or public compatibility promise is a constraint, not
+suggestion; `cutting`/`breaking` is never below `P2` and never `fix_eligibility: auto`; risky and
+breaking changes carry a migration strategy; anything outside the scope path is not a finding.

package/plugins/sp/skills/taste-refactoring-api/references/protocol-modes.md

@@ -77,3 +77,34 @@ For mutation races, prefer explicit optimistic concurrency such as ETags / `If-M
 - Make consumers tolerant of additive fields.
 - Do not use events as disguised synchronous RPC responses when the caller needs an immediate result.
 
+## CLI mode
+
+A command-line interface is a contract surface with consumers (scripts, other agents, CI), not a
+collection of convenience shortcuts. Review it with the same compatibility discipline as REST or
+gRPC. Spur's own `apps/cli` is the first target.
+
+**Noun/verb grammar:** keep one noun per domain and verbs per action (`spur task show`, not
+`spur showTaskForTask`). Do not introduce a second grammar for the same concept — one spelling per
+noun, one verb per operation, consistent object order.
+
+**Flag vocabulary consistency:** shared flags (`--json`, `--scope`, `--agent`, `--fix`) keep the
+same name, arity, and semantics everywhere they appear. A flag that means something new per
+command is a defect; declare a new flag instead.
+
+**Exit codes:** `0` = success, nonzero = failure, deterministic and machine-checkable. Never
+swallow failures into `0`; never return nonzero for advisory output. Validation errors and
+runtime failures should be distinguishable from output where practical.
+
+**`--json` envelope stability:** `--json` output is a public schema. Add fields additively; never
+remove or rename existing fields, never change a field's type, and emit no human decoration
+(banners, progress text) on the JSON stream. Machine consumers parse the documented envelope only.
+
+**Help-text parity:** every accepted flag appears in `--help` with its real arity and default;
+every documented example runs as printed. A flag that works but is not documented, or documented
+but rejected, is a parity break.
+
+**Additive vs breaking:** adding a noun, verb, flag, or output field is additive. Renaming or
+removing any of them, re-purposing a flag, changing a default, or altering existing output shape
+is breaking — it requires a migration path and a deprecation window, and it never rides in a
+patch release.
+

package/plugins/sp/skills/taste-refactoring-architect/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: taste-refactoring-architect
 description: Review, simplify, and refactor system architecture toward minimum sufficient architecture while preserving required capabilities, quality attributes, delivery safety, and data invariants. Backs architectural refactoring and boundary reviews.
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - refactor-architecture
+  openclaw:
+    emoji: "🏛️"
 ---
 
 # taste-refactoring-architect
@@ -469,3 +481,34 @@ Do not block on perfect documentation. Produce:
 - decisions that can safely proceed now.
 
 Use A7 DEFER/OBSERVE when evidence is too weak for a structural change.
+
+## Spur contract
+
+Machine-facing adapter for `sp:code-refactoring` dispatch (feature H13). Everything above is the
+lens's native output and is unchanged; this section only maps it to the shared finding schema.
+
+**Inputs received:** a scope path, an optional change description, and the `architect` focus.
+Read first: the intervention ladder and workflow above, then
+`../code-refactoring/references/finding-schema.md` for shared field semantics.
+
+**Native finding → schema mapping:** `ID` → `id` as `RF-architect-<nnn>`; `Action` (A0–A7) →
+`rung` verbatim; `Observation`/`Why it matters` → `title` plus `proposal` (imperative); `Evidence`
+→ `evidence` as `{file, line}` entries inside scope; `Fitness functions` → `verify`; new findings
+start at `status: open`. ADR candidates and migration plans stay prose findings with
+`fix_eligibility: suggest`.
+
+**Severity mapping (design §5):** any axis ≤1 with a correctness/safety consequence → `P1`; axis
+≤2 or A5–A7 seam problems → `P2`; A3–A4 → `P3`; A0–A2, ADR candidates, deferred questions → `P4`.
+
+**Preserved-behavior inventory (required before proposals):** emit the Preservation Contract
+table — capabilities, quality attributes, data invariants, and their thresholds — for everything
+in scope before the first finding.
+
+**Preservation class:** A0/A3/A4 mechanical consolidations with identical behavior →
+`preserving`; A1/A2 removal of a live service, endpoint, queue, or code path with callers →
+`cutting`; A5–A7 seam or behavior changes → `breaking`; migration plans and ADR candidates →
+`preserving` prose with `fix_eligibility: suggest`.
+
+**Stop rules:** no removal without dependency/traffic/contract evidence; `cutting`/`breaking` is
+never below `P2` and never `fix_eligibility: auto`; multi-task migrations are `suggest`, applied
+only after an explicit operator answer; anything outside the scope path is not a finding.

package/plugins/sp/skills/taste-refactoring-tests/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: taste-refactoring-tests
 description: Refactor unit tests for failure sensitivity, deterministic confidence, and regression protection without mock-heavy brittle tests or vanity coverage. Backs test suite quality audits.
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - refactor-tests
+  openclaw:
+    emoji: "🧪"
 ---
 
 # taste-refactoring-tests
@@ -480,3 +492,33 @@ A test refactor is complete only when:
 - delivery speed is not degraded without a justified risk trade-off.
 
 The goal is **earned confidence**: green means something because the suite has demonstrated that it can turn red when the product is wrong.
+
+## Spur contract
+
+Machine-facing adapter for `sp:code-refactoring` dispatch (feature H13). Everything above is the
+lens's native output and is unchanged; this section only maps it to the shared finding schema.
+
+**Inputs received:** a scope path, an optional change description, and the `tests` focus. Read
+first: the intervention ladder, Confidence Contract, and review severity above, then
+`../code-refactoring/references/finding-schema.md` for shared field semantics.
+
+**Native finding → schema mapping:** `ID` → `id` as `RF-tests-<nnn>`; `Action` (T0–T7) → `rung`
+verbatim; `Severity` → `severity` via the map below; `Evidence` → `evidence` as `{file, line}`
+entries inside scope; `Why it matters` → `title`; `Proposed change` → `proposal` (imperative);
+`Expected regression-detection improvement` → folded into `proposal`; new findings start at
+`status: open`.
+
+**Severity mapping (design §5):** native P0 → `P1`; P1 → `P2`; P2 → `P3`; P3 → `P4`.
+
+**Preserved-behavior inventory (required before proposals):** emit the Confidence Contract —
+critical business rules, compatibility contracts, authorization/security decisions, data
+integrity invariants, error semantics, and incident regressions the suite must keep protecting —
+before the first finding.
+
+**Preservation class:** T0 and rungs that keep or add protection (fixture cleanup, adding a
+missing test) → `preserving`; removing a test or test file (T1) → `cutting`; weakening or
+semantically changing existing assertions → `breaking`.
+
+**Stop rules:** unknown protection is a risk, never permission to delete; a `cutting`/`breaking`
+finding is never `fix_eligibility: auto` and never below `P2`; tests are never removed or
+weakened by an `auto` fix; anything outside the scope path is not a finding.

package/plugins/sp/skills/taste-refactoring-ui/SKILL.md

@@ -1,6 +1,18 @@
 ---
 name: taste-refactoring-ui
 description: Design, review, and refactor UI hierarchy, layout, typography, spacing, color, and interactions.
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - refactor-ui
+  openclaw:
+    emoji: "🎨"
 ---
 
 # taste-refactoring-ui
@@ -288,3 +300,34 @@ For deeper reasoning and daily use, read:
 - `references/refactoring-ui-playbook.md` — chapter-by-chapter distilled guidance.
 - `checklists/daily-ui-review.md` — fast audit and ship checklist.
 - `examples/review-template.md` — reusable UI critique response structure.
+
+## Spur contract
+
+Machine-facing adapter for `sp:code-refactoring` dispatch (feature H13). Everything above is the
+lens's native output and is unchanged; this section only maps it to the shared finding schema.
+
+**Inputs received:** a scope path, an optional change description, and the `ui` focus. Read
+first: the refactoring protocol and output contract above, then
+`../code-refactoring/references/finding-schema.md` for shared field semantics.
+
+**Native finding → schema mapping:** each issue → `id` as `RF-ui-<nnn>`; the pass that owns it
+(hierarchy, spacing, typography, color, states) → `rung`; `Observation` + `Refactor` → `title`
+and `proposal` (imperative); the cited component/file and line → `evidence` as `{file, line}`
+entries inside scope; the `System rule` → folded into `proposal`; new findings start at
+`status: open`.
+
+**Severity mapping (design §5):** native P0 (task failure) → `P1`; P1 (hierarchy/structure) →
+`P2`; P2 (system inconsistency) → `P3`; P3 (polish) → `P4`.
+
+**Preserved-behavior inventory (required before proposals):** emit the controls and interactions
+in scope — primary/secondary actions, navigation, form semantics, accessible names, states —
+before the first finding.
+
+**Preservation class:** token normalization and layout/typography consolidation with identical
+function → `preserving`; adding a missing state or a11y attribute → `preserving`; removing or
+merging a control or interaction → `cutting`; changes to user-visible flows or behavior →
+`breaking`.
+
+**Stop rules:** meaning is never carried by color alone; preserve component semantics and
+accessibility; a `cutting`/`breaking` finding is never `fix_eligibility: auto` and never below
+`P2`; anything outside the scope path is not a finding.

package/schemas/state-machine-workflow.schema.json

@@ -161,6 +161,11 @@
                 "options": {
                     "type": "object",
                     "additionalProperties": true
+                },
+                "onError": {
+                    "type": "string",
+                    "enum": ["fail", "continue"],
+                    "description": "Per-action error handling policy: 'fail' halts the run; 'continue' logs the failure and proceeds so transition guards can route the outcome."
                 }
             }
         },