@gobing-ai/spur 0.3.86 → 0.3.87

package/plugins/sp/skills/code-refactoring/references/fix-ladder.md

@@ -0,0 +1,52 @@
+# Fix ladder and eligibility
+
+Authority: `docs/design/dev-refactor-command.md` §6. The ladder ranks what may be applied
+mechanically versus what needs an operator answer. It reuses the repository severity meaning
+(P1 blocker / P2 major — see [finding-schema.md](./finding-schema.md)) so `--fix blockers-first`
+keeps the glossary sense.
+
+## Rungs
+
+| Rung | Example | `preservation` | `fix_eligibility` |
+| --- | --- | --- | --- |
+| Rename / move / dedupe / inline with identical behavior | A3 consolidate, T3 fixture cleanup, ui token normalization | preserving | `auto` |
+| Add missing test, contract field, a11y attribute | T4, api additive, ui P3 | preserving | `auto` |
+| Remove dead code with zero references | A1 direct removal proven dead | preserving | `auto` only when a reference search finds no caller; else `confirm` |
+| Remove a test, endpoint, control, or code path with callers | T1, A1/A2 live, api removal, ui control removal | cutting | `confirm` |
+| Change a contract or observable behavior | api breaking, A5–A7 seam moves | breaking | `confirm` (or `suggest` when multi-task) |
+| Architectural migration plan | A6–A7, ADR candidates | — | `suggest` |
+
+Hard rules:
+
+- An `auto` fix **never deletes or weakens a test** (no skipped assertions, no loosened
+  expectations, no deleted cases).
+- `cutting` and `breaking` findings are **never `auto`** and **never below P2**.
+
+## Apply policies (`--fix`)
+
+| Policy | Meaning |
+| --- | --- |
+| `none` (default) | Write both artifacts, perform no edit. |
+| `blockers-first` | Apply P1/P2 findings with `fix_eligibility: auto`. |
+| `all` | Apply every `auto` finding, then queue every `confirm` finding for the taste gate. |
+
+## Apply loop (mirrors `sp:code-simplification` / `dev-simplify`: test-after-each, revert on regression)
+
+1. **Green baseline first.** Run the `--check` command before any edit. A red baseline is a hard
+   stop: write the report, apply nothing.
+2. **One finding at a time.** Apply a single finding (highest severity first: P1 → P4), limited to
+   the finding's evidence files.
+3. **Re-run `--check`.**
+   - Passes → mark the finding `status: applied`, continue with the next.
+   - Fails → revert **only that finding's own edits**: reverse-apply the exact hunks the finding
+     introduced (keep the finding's diff; `git apply -R`, or re-edit the specific lines). Never
+     `git checkout -- <file>` a whole evidence file — a later finding may share that file with an
+     earlier **applied** finding, and a file-level checkout would revert that applied work too.
+     Mark the finding `status: reverted`, continue with the next. Never revert another finding's
+     work.
+4. After the last finding: re-run the structural check on the findings artifact, then write the
+   report (see `SKILL.md` phase 5).
+
+`confirm` findings in the `all` policy follow the taste gate: applied only after an explicit
+operator `yes` (see the gate matrix in `SKILL.md`). A declined finding is marked `status: rejected`
+or `status: deferred` (headless) per the operator answer — never silently dropped.

package/plugins/sp/skills/code-refactoring/references/focus-detection.md

@@ -0,0 +1,44 @@
+# Focus auto-detection
+
+Authority: `docs/design/dev-refactor-command.md` §8. Lens selection is **deterministic globs, not
+model judgment**, so a misroute is auditable: re-running detection on the same tree yields the same
+set.
+
+## Classification
+
+First matching table row per file; the lens set is the **union** across all files in `--scope`.
+
+| Order | Glob | Lens |
+| --- | --- | --- |
+| 1 | `**/tests/**`, `**/*.test.*`, `**/*.spec.*`, `**/__tests__/**` | tests |
+| 2 | `apps/web/**`, `**/*.astro`, `**/*.tsx`, `**/*.jsx`, `**/*.css`, `**/*.vue` | ui |
+| 3 | `packages/contracts/**`, `**/routes/**`, `**/openapi*`, `**/*.proto`, `**/*.graphql`, `apps/cli/src/commands/**`, `apps/server/src/**` | api |
+| 4 | anything else (fallback) | architect |
+
+Rules:
+
+- Evaluate rows in order; a file matching an earlier row is never classified by a later one
+  (a `*.test.tsx` file is a **tests** file, not ui).
+- Every file in scope resolves to exactly one lens; the scope set is the union of resolved lenses.
+- An empty scope set (no files matched anything) collapses to the `architect` fallback for the
+  whole scope only when scope itself is non-empty; an empty scope is a resolve-phase error.
+
+## `--focus` flag
+
+| Value | Behavior |
+| --- | --- |
+| `auto` (default) | Run detection above and use its lens set. |
+| single lens (`api` \| `architect` \| `tests` \| `ui`) | Run only that lens. |
+| comma list (`api,tests`) | Run exactly the listed lenses, in the operator's order. |
+
+## Report before run
+
+The resolved lens set **must be reported before any lens runs** — one line naming the chosen
+lenses and, for `auto`, the per-file counts that selected them, e.g.:
+
+```text
+focus=auto → lenses: tests (14 files), api (3 files)
+```
+
+Under `--auto` this line is still written (to the report and the session output); what `--auto`
+skips is only the *interactive* confirmation of scope and lens set, never the report.

package/plugins/sp/skills/code-refactoring/references/refactor-finding.schema.json

@@ -0,0 +1,95 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://spur.gobing.ai/schemas/refactor-finding.schema.json",
+    "title": "Refactor findings artifact (bare array of findings, design H13 §4)",
+    "description": "One JSON object per refactoring finding; the artifact written to .spur/run/<run-id>-refactor-findings.json is a bare array of these objects.",
+    "type": "array",
+    "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+            "id",
+            "focus",
+            "severity",
+            "rung",
+            "title",
+            "evidence",
+            "preservation",
+            "fix_eligibility",
+            "proposal",
+            "verify",
+            "status"
+        ],
+        "properties": {
+            "id": {
+                "type": "string",
+                "pattern": "^RF-(api|architect|tests|ui)-[0-9]{3}$",
+                "description": "RF-<focus>-<nnn>, e.g. RF-api-001."
+            },
+            "focus": {
+                "type": "string",
+                "enum": ["api", "architect", "tests", "ui"],
+                "description": "The lens that produced the finding."
+            },
+            "severity": {
+                "type": "string",
+                "enum": ["P1", "P2", "P3", "P4"],
+                "description": "Repository-authority severity after the lens-native → P1–P4 map (finding-schema.md §5). P0 is outside the map."
+            },
+            "rung": {
+                "type": "string",
+                "description": "Lens-native rung kept verbatim: architect A0–A7, tests T0–T7, api compatibility class, ui pass name."
+            },
+            "title": {
+                "type": "string",
+                "minLength": 1,
+                "description": "One line."
+            },
+            "evidence": {
+                "type": "array",
+                "minItems": 1,
+                "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": ["file", "line"],
+                    "properties": {
+                        "file": {
+                            "type": "string",
+                            "minLength": 1
+                        },
+                        "line": {
+                            "type": "integer",
+                            "minimum": 1
+                        }
+                    }
+                },
+                "description": "At least one file:line inside --scope."
+            },
+            "preservation": {
+                "type": "string",
+                "enum": ["preserving", "cutting", "breaking"],
+                "description": "preserving: behavior identical; cutting: a user-visible feature/test/endpoint/control is removed; breaking: contract or behavior changes for a consumer."
+            },
+            "fix_eligibility": {
+                "type": "string",
+                "enum": ["auto", "confirm", "suggest"],
+                "description": "auto: mechanical, behavior-preserving, checkable; confirm: needs an operator answer; suggest: report only."
+            },
+            "proposal": {
+                "type": "string",
+                "minLength": 1,
+                "description": "What to change, imperative."
+            },
+            "verify": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Command or check that proves the fix; defaults to the --check command."
+            },
+            "status": {
+                "type": "string",
+                "enum": ["open", "applied", "reverted", "deferred", "rejected"],
+                "description": "Lifecycle of the finding through the gate/apply loop."
+            }
+        }
+    }
+}

package/plugins/sp/skills/spec-decomposition/references/decomposition.md

@@ -134,14 +134,13 @@ single run-on paragraph on render, even though they look like separate items in
 "requirements": "- [ ] R1. <text>\n- [ ] R2. <text>\n- [ ] R3. <text>"
 ```
 
-`R1. <text>\nR2. <text>` (no marker) is the trap. `spur task check` **accepts** it — the L3
-R-numbering rule matches the bare `Rn.` token — so nothing fails, and the defect only surfaces later
-as an unreadable paragraph in Board preview. Do not rely on `check` to catch this. Keep the `Rn.`
+`R1. <text>\nR2. <text>` and `- R1 — <text>` are the traps: `spur task check` reports
+`L3.requirements-checkbox` and a bare run renders as one paragraph in Board preview. Keep the `Rn.`
 (period) token inside the marker so R-numbering still resolves; see the canonical rule in
 `sp:spur-dev` → `references/planning-workflow.md`.
 
 Applies to the other body fields too: `plan` as an ordered list (`1. …\n2. …`), `acceptance_criteria`
-as a fenced ```` ```gherkin ```` block, and any enumeration inside `background` or `design` as a
+as `- [ ] AC1 — <feature scenario title without its R-number>` bullets (see § Idea-pipeline emission), and any enumeration inside `background` or `design` as a
 `- ` list.
 
 ### Design at create (default) vs `--skip-design`
@@ -207,20 +206,22 @@ scenarios are numbered in the **feature's** namespace. Both appear in a task's
 
 The rule:
 
-- **Scenarios covering the task's own requirements carry the task-local R-prefix** —
-  `Scenario: R3 — <observable outcome>`. Tasks declaring `ac_numbering: task-local` in frontmatter
-  get these cross-checked by `spur task check` (`L3.ac-requirement-coverage`): a requirement with no
-  scenario, or a scenario citing a requirement that does not exist, is reported.
-- **Scenarios carried verbatim from the feature (for DD-09 traceability) carry NO R-prefix** — copy
-  the title text only. `normalizeTitle` (`packages/domain/src/bdd/coverage.ts:58`) strips `R\d+`
-  before matching, so the prefix is invisible to feature coverage anyway; dropping it keeps the
-  feature's number from being read as a task requirement id. Verified empirically: removing the
-  prefix from a carried scenario left the feature's orphan count unchanged.
+- **Task AC items are numbered `AC1, AC2, …` (task-local), never `R<n>`** — `R<n>` is the
+  Requirements namespace, and two R-numberings in one file is how they get confused.
+- **Bind a scenario to the task requirement it covers with `(req: R<n>)`** —
+  `Scenario: AC1 — <observable outcome> (req: R3)` (semicolons for several: `R1; R2`). Tasks
+  declaring `ac_numbering: task-local` get these cross-checked by `spur task check`
+  (`L3.ac-requirement-coverage`): a requirement with no scenario, or a scenario citing a requirement
+  that does not exist, is reported.
+- **Scenarios carried from the feature (for DD-09 traceability) copy the title text after the
+  feature's `R<n> —`** — `- [ ] AC2 — <title>`. `normalizeTitle`
+  (`packages/domain/src/bdd/coverage.ts`) strips both `AC\d+` and `R\d+` before matching, so the
+  prefix is invisible to feature coverage; the feature's number is never read as a task id.
 
 **Legacy tasks are exempt.** Most existing tasks predate this and copied feature AC wholesale,
 carrying the feature's numbers. The coverage check is opt-in precisely so they emit nothing —
-absent `ac_numbering`, only DD-09 applies. Opting an old task in is a pure prefix renumber; it cannot
-break traceability. New tasks get `ac_numbering: task-local` from the templates automatically;
+absent `ac_numbering`, only DD-09 applies. Legacy `Scenario: R<n> —` titles still bind by prefix, so
+opting an old task in cannot break traceability. New tasks get `ac_numbering: task-local` from the templates automatically;
 `spur task update <wbs> --ac-numbering task-local` opts in an existing one.
 
 Edge-case scenarios may map to tasks, merge into a sibling, or be deferred. Record deferrals
@@ -523,7 +524,7 @@ The payload is a top-level JSON **array** (no `tasks` wrapper):
     "requirements": "- [ ] R1. Accept a title and an optional description on POST /tasks.\n- [ ] R2. Reject an empty title with a 400 and a reason.\n- [ ] R3. Allocate the task file through the CLI-gated write path.",
     "design": "Approach: POST /tasks via existing TaskService.create.\nRejected: ad-hoc SQL in handler.\nInvariants: CLI-gated corpus writes only.",
     "plan": "1. Contract\n2. Handler\n3. Tests",
-    "acceptance_criteria": "Scenario: create succeeds\n  Given a valid title\n  When POST /tasks\n  Then a task file is allocated"
+    "acceptance_criteria": "- [ ] AC1 — User can create a task with required fields"
   },
   {
     "name": "Implement task listing endpoint",
@@ -559,6 +560,12 @@ fields and normal default planning fills them from your analysis; the per-task r
 batch-create still deepens them when a task needs more detail. Validate locally against the
 schema before emitting.
 
+**Pass the deterministic task check.** Each `acceptance_criteria` bullet must be an exact feature
+scenario title (L4.uncovered-task-scenario); add task-local checks as prose after the bullets, not
+as extra bullets. No section body may use `HITL`, `approval`/`approved`, `merged`/`merge event`,
+`content-gate`, `GATED`, or `capstone` as standalone words (L4.gate-language) — say "operator
+answer" / "accepted" instead, and keep enum values out of that list too.
+
 **The order sidecar.** Also emit the private task-order sidecar at
 `.spur/run/<runId>-idea-task-order.json`: a JSON array (one entry per batch item) of
 `{ name: <exact batch item name>, depends_on_names: [<batch item names>] }` declaring

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

@@ -47,8 +47,10 @@ Every scenario/item carries an `R1, R2, …` prefix:
 
 - **Sequential within a feature**, starting at R1.
 - **Stable forever.** Never renumber once tasks exist — tasks match AC by **normalized scenario
-  title** (the `R<n> —` prefix is stripped on comparison), so renumbering around a title is safe
-  but *rewording* a title breaks the coverage edge.
+  title** (the `R<n> —` prefix is stripped on comparison, as is the task side's `AC<n> —`), so
+  renumbering around a title is safe but *rewording* a title breaks the coverage edge.
+- **`R<n>` is the feature's namespace.** Task AC items are numbered `AC<n>` (task-local) and copy
+  the feature title after their own prefix; task Requirements own `R<n>.` inside the task.
 - **One R-number = one scenario.** Don't split one requirement across scenarios under a single
   R-number; don't merge two requirements into one scenario.
 

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

@@ -58,6 +58,9 @@ spur feature create "Planning layer" --parent H      # → H<n>
 spur feature create "Task CLI" --parent H1            # → H1<n>
 ```
 
+`create --json` returns `{ ref: { kind, id, filePath, folder }, content }` — read the id from
+`.ref.id`, not a top-level `.id`.
+
 To restructure, use `move` — never hand-edit an ID. `move <id> --parent <new>` re-parents the
 subtree and **cascade-renames** every descendant; omit `--parent` to lift it to a top-level group.
 
@@ -184,7 +187,9 @@ spur feature check --strict --json  # warnings → failures
 ```
 
 The 4-layer validator (frontmatter, AC syntax, children-limit/structure, L4 traceability) emits its
-verdict and findings as JSON. **Query this, don't re-derive it** — the rules live in the CLI, never
+verdict and findings as a JSON **array**, one entry per feature (`jq '.[0].pass'`, `.[0].findings[].code`),
+like `spur task check --json`. Gherkin AC must keep its `Feature:` line (`L3.ac-bdd-error`) and
+every `Scenario:` title is the identity key tasks reference verbatim. **Query this, don't re-derive it** — the rules live in the CLI, never
 restated as prose here. This is what `sp:spur-dev`'s feature-check gate loop runs.
 
 ## Status sync - `sync`

package/plugins/sp/skills/spur-cli/references/workflows/authoring-workflows.md

@@ -137,8 +137,8 @@ runner (see [validation-and-extension.md](validation-and-extension.md)).
 Order matters for both guards and conditions: **the first that passes wins.** Put the discriminating
 guard before the unconditional fallback (`always` / no-guard edge). For multi-condition gates (doctor
 + task check, quality gate + attempt cap), prefer a **soft probe** shell that writes PASS|FAIL and
-always exits 0, then branch with ordered status-file guards — see shipped `basic.yaml` /
-`task-pipeline.yaml` (more reliable than `action-ok` alone when more than one condition decides the edge).
+always exits 0, then branch with ordered status-file guards — see shipped
+`task-pipeline.yaml` / `wrapup-pipeline.yaml` (more reliable than `action-ok` alone when more than one condition decides the edge).
 
 ## Template variables
 

package/plugins/sp/skills/spur-cli/references/workflows/operations.md

@@ -28,9 +28,9 @@ Authored workflows default to a project-local directory, grouped by purpose:
 ```
 
 A `--file <path>` argument overrides the default. Keep one workflow per file, named for what it does
-(`approval.yaml`, `import-file.yaml`), not for its mode. The canonical example
-(`basic.yaml`) lives here; copy real schema shapes from it rather than from a
-half-remembered snippet.
+(`approval.yaml`, `import-file.yaml`), not for its mode. Copy real schema shapes from a
+retained definition such as `task-pipeline.yaml` rather than from a half-remembered
+snippet.
 
 ## Sub-procedure: mode-selection gate
 

package/plugins/sp/skills/spur-cli/references/workflows/workflow-fit-and-tuning.md

@@ -95,7 +95,7 @@ and orders capabilities, it does not contain them** (ADR-069).
       between them are one judgment step.
 - [ ] **Soft status-file probe over repeated probing.** Run the expensive check once in an action
       that always exits 0 and writes its verdict to a run-scoped file; branch with ordered cheap
-      guards that read that file. One subprocess instead of one per branch — the `basic.yaml` and
+      guards that read that file. One subprocess instead of one per branch — the
       `task-pipeline.yaml` quality-gate idiom.
 - [ ] **Order guards cheapest-discriminating-first.** The first passing guard wins, so a `test -f`
       ahead of a `spur … --json` parse skips the expensive call on the common path.

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

@@ -160,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
@@ -428,7 +457,10 @@ The driver reaches it through the existing run delegate (`$SETUP_SCRIPT`,
   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.
+  (`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