@gobing-ai/spur 0.3.86 → 0.3.88

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
 
@@ -152,10 +153,23 @@ must not be changed without updating the backing skill.
 
 ### 5. refine
 
-- **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design.
-- **Inputs:** `<wbs>` (required). `--focus <mode>` narrows the gap analysis. `--depth <standard|ready>` (default **`standard`**) sets the depth bar — see [flag-glossary.md](flag-glossary.md#flag-depth). Execution defaults to inline (in-session); `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips interactive Q&A (synthesis only) and propagates down the `--next` chain. `--next`: advance to the next step — transition `backlog → todo` through the FSM **idempotently** (only when `status == backlog`; a task already at `todo` or past it skips the transition and chains anyway — `status >= todo` ⇒ already advanced) and invoke `/sp:dev-run <wbs> --mode implement --auto --next`. On a guard/refine failure, stop as review-pending.
+- **Purpose:** Refine a task's requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria before execution. Optional **implement-ready** depth freezes Design/Requirements/Plan so another agent can implement without inventing design, and is also the path for **evaluating and correcting an existing task** — a review-triage filing, a stale backlog capture, or any task whose claims and proposed fixes may no longer hold.
+- **Inputs:** `<wbs>` (required). `--focus <mode>` narrows the gap analysis (values below). `--description <text>` injects operator framing into the Q&A/synthesis. `--depth <standard|ready>` (default **`standard`**) sets the depth bar — see [flag-glossary.md](flag-glossary.md#flag-depth). Execution defaults to inline (in-session); `--agent <inline|auto|name>` selector accepted (see [SSOT](cross-cutting.md#inline-default-execution-surface)). `--auto` skips interactive Q&A (synthesis only) and propagates down the `--next` chain. `--next`: advance to the next step — transition `backlog → todo` through the FSM **idempotently** (only when `status == backlog`; a task already at `todo` or past it skips the transition and chains anyway — `status >= todo` ⇒ already advanced) and invoke `/sp:dev-run <wbs> --mode implement --auto --next`. On a guard/refine failure, stop as review-pending.
+- **Status scope:** refine targets `backlog`/`todo` tasks (the same rule `batch-preflight` applies to refineall). A task at `wip` or later has an implementation built on its current spec. Refine it only on an explicit operator request, never under `--auto` alone, and never move its status backwards.
+- **`--focus` values** (hint bundles for the gap analysis/Q&A; default `all`):
+
+  | Value | Domain hints | When |
+  | --- | --- | --- |
+  | `all` | purpose, scope, constraints, dependencies, acceptance criteria, users, timeline | Complete refinement |
+  | `requirements` | purpose, scope, acceptance criteria | Standard refinement |
+  | `background` | purpose, scope | Thin tasks needing context |
+  | `constraints` | constraints, dependencies, timeline | Technical depth |
+  | `acceptance` | acceptance criteria, users | Verification focus |
+  | `quick` | scope, acceptance criteria | Fast pass |
+
+  Focus narrows what `--depth standard` looks at. Under `--depth ready` the full checklist still runs, and focus only orders the work.
 - **Backing:** `sp:spur-dev` skill, `refine` operation. Q&A clarifications are presented as decision briefs per [decision-brief.md](decision-brief.md).
-- **Behavior:** Read the task → elicit missing AC/Design/Plan through targeted Q&A (or auto-synthesis) → write each via `spur task update <wbs> --section <name> --from-file`. Done just-in-time, per task, immediately before execution. With `--next`: on success, transition status (idempotently — see Inputs) + chain to dev-run; on failure, stop and surface error.
+- **Behavior:** Read the task → (ready depth) audit the existing content against the current tree → elicit missing or wrong Background/Requirements/AC/Design/Plan through targeted Q&A (or auto-synthesis) → write each via `spur task update <wbs> --section <name> --from-file`. Done just-in-time, per task, immediately before execution. With `--next`: on success, transition status (idempotently — see Inputs) + chain to dev-run; on failure, stop and surface error.
 - **Pre-synthesis skip gate (under `--auto` + `--depth standard` only):** Before invoking synthesis, run `spur task check <wbs> --json`. Filter the findings to the **refine target sections** only:
   `{Background, Requirements, Acceptance Criteria, Design, Plan}`.
   These are the anti-drift surfaces: constraints + planning that cheaper implementers must follow.
@@ -205,28 +219,72 @@ must not be changed without updating the backing skill.
   SKIP — sections already meet implement-ready checklist: depth=ready, sections-considered=[…]
   ```
 
-  **Implement-ready checklist (all must hold for allowed target sections):**
-  1. **Requirements** — R-items are observable outcomes; explicit out-of-scope / non-goals; no
+  **Implement-ready checklist (all must hold for allowed target sections).** Each item's `id` is
+  the `READY_CHECKLIST_IDS` value (`packages/app/src/services/task-readiness.ts`) that the
+  create-time ready preparation and the idea-pipeline ready-prepare stage also use:
+  1. **`requirements`** — R-items are observable outcomes; explicit out-of-scope / non-goals; no
      ambiguous “wire it up” without a named seam or file area.
-  2. **Design** — WHAT / WHY / WHERE; **frozen names** (types, flags, vars, paths) **or** explicit
+  2. **`design`** — WHAT / WHY / WHERE; **frozen names** (types, flags, vars, paths) **or** explicit
      “no new API”; precedence / algorithm when behavior is non-obvious; **anti-patterns** (what not
      to implement); primary file/package targets; handoff to dependent tasks (WBS) if any.
-  3. **Plan** — ordered checklist mappable to R-items; test/verification intent called out.
-  4. **Acceptance Criteria** — scenarios still match feature R-titles when `feature_id` is set;
-     Given/When/Then still executable as a verify lens.
-  5. **Q&A / References** — open decisions closed or explicitly deferred with owner; links to ADR /
+  3. **`plan`** — ordered checklist mappable to R-items; test/verification intent called out.
+  4. **`ac`** — every scenario uses an [ac-style-guide.md](ac-style-guide.md) task-side form
+     (`- [ ] AC<n> — <title>` or `Scenario: AC<n> — <title>`, with `(req: R<n>)`). `spur task check`
+     parses only checkbox and `Scenario:` lines, so any other shape (a plain `- AC1 —` bullet, a bold
+     heading) silently escapes its AC checks. When `feature_id` is set, each AC
+     title matches a feature scenario title, unless the task is deliberately `ac_altitude:
+     task-local`. Given/When/Then stays executable as a verify lens.
+  5. **`decisions`** — Q&A open decisions closed or explicitly deferred with owner; links to ADR /
      feature / upstream tasks present when the design depends on them.
-  6. **Cross-task** — if `dependencies[]` exist, Design states what this task assumes from deps and
-     what it must leave for dependents (no silent re-ownership of upstream contracts).
-  7. **Premise verification** — every factual claim in Background and Requirements that the Design
-     depends on (a status, a file/table/location, an already-landed fix, a count) is checked against
-     the **current tree** — read the file, run the query, grep the corpus. 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 available outcome.
-
-  Ready depth is for multi-package work, multi-agent implement handoffs, and costly pipeline
-  failures — not for every small task. Default remains `standard`.
+  6. **`dependencies`** — if `dependencies[]` exist, Design states what this task assumes from deps
+     and what it must leave for dependents (no silent re-ownership of upstream contracts). A
+     dependency the Design relies on but `dependencies[]` lacks is added with `spur task deps`.
+  7. **`premises`** — every factual claim in Background, Requirements, Design and Plan is checked
+     against the **current tree** (read the file, run the query, grep the corpus), not only the gaps.
+     This is the **audit pass**; it matters most for a task written earlier or by another agent
+     (review-triage filings, stale backlog). Lenses:
+     - **Facts** — statuses, `file:line` references, type/field/flag names, counts, "already fixed"
+       or "not yet implemented" claims.
+     - **Sources** — a cited run, artifact, session or doc exists and says what the task claims. If
+       it is gone, say so and restate the claim from code.
+     - **Fix soundness** — each proposed fix holds for every caller and mode of the seam it touches,
+       does not break a currently valid path, and reuses an existing mechanism before adding one.
+     - **Test observability** — each AC names a test layer (and file) that can actually observe the
+       behavior. A test that mocks the collaborator carrying the behavior cannot.
+     - **Environment** — installed dependency versions match the lockfile and generated artifacts
+       are current. If not, the Plan gets a step-0 precondition.
+     - **Concurrency** — active worktrees or `wip` tasks touching the same files (`git worktree
+       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.
+
+     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
+     available outcome.
+
+  **Correction record.** When the audit changes a claim, append a dated block to Background —
+  `**Refine corrections (<YYYY-MM-DD>)**`, one line per correction: claim → verified reality →
+  resolution. Never delete an earlier block, so the next reader sees what changed and why. Scope
+  decisions made along the way also go into Q&A as closed decisions.
+
+  **Ready finalization.** Once every item holds:
+  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.
+  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`,
+     refine does not chain into run.
+  4. Report the checklist as rows `{id, pass, evidence}`, one per id, in the markdown result and in
+     the `--json` object, alongside the corrections count and status before → after.
+
+  A decision refine cannot close under `--auto` makes the outcome `failed`. Report the concrete
+  question, and leave the task at `backlog`.
+
+  Ready depth is the canonical path for three jobs: the ready competency behind `spur task create`
+  (its recovery command), evaluating and correcting an existing task, and freezing multi-package or
+  multi-agent handoffs. It is not for every small task. Default remains `standard`.
 
 - **SKIP short-circuits synthesis, not `--next`.** A SKIP means no synthesis was needed — it does **not** cancel the `--next` chain. Under `--auto --next`, a SKIP still flows into the (idempotent) status transition and the chained `/sp:dev-run --mode implement`. "`refine --auto --next` on a well-specified task" is therefore effectively "run the implement→verify chain"; an operator who wanted refinement only should drop `--next`.
 - **Delegation:** `Skill(skill="sp:spur-dev", args="refine $ARGUMENTS")`
@@ -243,13 +301,13 @@ must not be changed without updating the backing skill.
   1. Resolve + **freeze** the set at kickoff (never re-query membership mid-batch).
   2. Apply `--status` filter (default `backlog` + `todo`; applied in-agent against the frozen set; `spur task list --status` takes exactly one canonical status per call — see `execution-batch.md` Step 1). Tasks already `done`/`cancelled`/`testing` are excluded unless the operator widens `--status`. Report each exclusion with reason.
   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).
+  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.
+  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).
 - **`--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: `/sp:dev-refineall --feature <id> --auto --depth ready`.
+- **`--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).
 
 ### 6. plan
@@ -335,11 +393,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 +421,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,22 @@ 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` (`all|requirements|background|constraints|acceptance|quick` —
+[dev-operations.md](dev-operations.md) § refine), or a reconstruction lens on `dev-reverse`.
 Narrowing reduces token cost; omitting runs
 all dimensions.
 
@@ -175,7 +184,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 +262,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 +304,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`.
@@ -353,10 +373,12 @@ 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 — run the ready checklist; rewrite sections until the bar is met |
+| `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` |
 
 Default for refine stays `standard` so ordinary `refineall --auto` remains cheap. Use `ready` for
-multi-package / multi-agent handoffs and flaky-pipeline features where a wrong implement is costly.
+multi-package / multi-agent handoffs, flaky-pipeline features where a wrong implement is costly, and
+evaluating/correcting an existing task (review-triage filing, stale backlog) whose claims may no
+longer hold.
 Full checklist: [dev-operations.md](dev-operations.md) § refine (depth ready).
 
 ### `--bdd` — use BDD scenarios as the verification lens

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

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

@@ -301,10 +301,12 @@ the handoff degrades to refineall.
 (and preferably Plan/AC) so tasks land **content-ready**. **`--skip-design`:** leave `design`
 empty — headings only.
 
-**Refine is the fallback**, not the primary Design author:
+**Refine is the fallback** Design author, not the primary one. It is also the audit path for
+tasks that already have content:
 
 ```text
 /sp:dev-refine <wbs>          # single task — fills blank Design/AC/Plan if L3 gaps
+/sp:dev-refine <wbs> --depth ready    # evaluate + correct an existing/filed task, then promote to todo
 /sp:dev-refineall --feature X --auto
 /sp:dev-refineall --feature X --auto --depth ready   # implement-ready freeze (no L3-only SKIP)
 ```
@@ -314,7 +316,9 @@ Under `--auto` + **`--depth standard`** (default), refine **SKIP**s when target
 placeholder, synthesis runs (standard tier by default; escalates only on gate-fail). Under
 **`--depth ready`**, do not SKIP on L3-clean alone — run the implement-ready checklist in
 [dev-operations.md](dev-operations.md) § refine (frozen APIs, anti-patterns, file targets, handoffs)
-so another agent can implement without inventing design.
+so another agent can implement without inventing design. Ready depth also audits every existing
+claim against the current tree, records corrections in Background, and promotes a passing task
+`backlog → todo`.
 
 **Check the variant before you write.** Which sections a task carries is decided by its `template:`
 frontmatter against `.spur/tasks/section-matrix.yaml` — NOT a fixed list. Before authoring any
@@ -344,16 +348,16 @@ feature filled before a runall, use `/sp:dev-refineall --feature <id> --auto` (b
 of `/sp:dev-refine`). It reuses the same per-task refine operation, freezes the set, topo-sorts by
 `dependencies[]`, and emits a batch report — see [dev-operations.md](dev-operations.md) § refineall.
 This does **not** replace just-in-time refine before each implement; it is a bulk pre-pass when the
-feature's tasks are still `backlog`/`todo` placeholders. Prefer `--auto` for batch scale; avoid
-`--next` on large features (that chains each task into run).
+feature's tasks are still `backlog`/`todo` placeholders. Prefer `--auto` for batch scale.
+`/sp:dev-refineall` takes no `--next`; chain with `/sp:dev-runall --feature <id>` afterwards.
 
 **Refine arguments** (defined on the `/sp:dev-refine` entry point, passed through verbatim; also
 shared flags on `/sp:dev-refineall`):
 
 | Argument | Effect |
 |----------|--------|
-| `--focus <mode>` | Narrows the gap analysis to a subset of domain hints. See the `sp:dev-refine` skill for the full value table (`all`, `requirements`, `background`, `constraints`, `acceptance`, `quick`). Default `all`. |
-| `--depth <standard\|ready>` | Spec depth bar. `standard` (default) = L3 structural completeness + L3 SKIP under `--auto`. `ready` = implement-ready freeze (never L3-only SKIP). See [flag-glossary.md](flag-glossary.md#flag-depth). |
+| `--focus <mode>` | Narrows the gap analysis to a subset of domain hints. Values `all`, `requirements`, `background`, `constraints`, `acceptance`, `quick` — hint table in [dev-operations.md](dev-operations.md) § refine. Default `all`. Under `--depth ready` it only orders the work. |
+| `--depth <standard\|ready>` | Spec depth bar. `standard` (default) = L3 structural completeness + L3 SKIP under `--auto`. `ready` = audit + implement-ready freeze + promote to `todo` (never L3-only SKIP). See [flag-glossary.md](flag-glossary.md#flag-depth). |
 | `--auto` | Skip interactive Q&A — synthesize improvements from the task content alone. Use for well-scoped tasks where the agent can fill gaps without operator input. **Required for practical batch use** via `dev-refineall`. |
 
 **Pre-synthesis skip gate (under `--auto` + `--depth standard`).** Before synthesizing, run `spur task check <wbs> --json`. When the **refine target sections** show no L3 findings, emit a structured SKIP instead of calling the synthesis agent. **Not applied when `--depth ready`.**

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.