@gobing-ai/spur 0.3.86 → 0.3.87

package/plugins/sp/scripts/idea-coverage-check.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env bun
+/**
+ * idea-coverage-check — requirement-inventory ↔ AC coverage gate for the idea pipeline
+ * (task 0887 R4).
+ *
+ * Cross-checks the `## Requirement inventory` section of the idea-evaluation report
+ * (R3) against the `# covers: I<n>, ...` comment lines of the generated acceptance
+ * criteria (R4): every inventory item that is not explicitly `[deferred: ...]` must be
+ * covered by at least one scenario. An `[unclear: ...]` marker does not exempt an item —
+ * it still demands coverage or an explicit deferral.
+ *
+ * Writes PASS/FAIL to `.spur/run/<run-id>-idea-coverage.status` and always exits 0
+ * (soft action, task 0769 pattern): the ac-generate guards in idea-pipeline.yaml read
+ * the status file, so a missing or failing checker fails closed through the guard, not
+ * through the exit code.
+ *
+ * Ships with the plugin to arbitrary projects, so it stays node-builtin-only —
+ * no workspace imports.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/idea-coverage-check.ts --run-id <id> --report <path>
+ *     --ac <path> [--out <path>]
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+
+interface ParsedArgs {
+    runId: string;
+    reportPath: string;
+    acPath: string;
+    outPath: string;
+}
+
+/** `- **I3** — ask text` / `- I3. ask text` — the R3 inventory item form. */
+const INVENTORY_ITEM_RE = /^\s*[-*]\s+\**I(\d+)\**\s*[.:—-]?\s+(.*)$/;
+
+/** `# covers: I1, I3` — the R4 scenario coverage comment. */
+const COVERS_RE = /^\s*#\s*covers:\s*(.+)$/i;
+
+/** Scenario header — the anchor a covers-comment attaches to. */
+const SCENARIO_RE = /^\s*Scenario(?:\s+Outline)?:/;
+
+function parseArgs(argv: string[]): ParsedArgs {
+    let runId = '';
+    let reportPath = '';
+    let acPath = '';
+    let outPath = '';
+    for (let i = 0; i < argv.length; i++) {
+        const value = argv[i + 1];
+        switch (argv[i]) {
+            case '--run-id':
+                runId = value ?? '';
+                i++;
+                break;
+            case '--report':
+                reportPath = value ?? '';
+                i++;
+                break;
+            case '--ac':
+                acPath = value ?? '';
+                i++;
+                break;
+            case '--out':
+                outPath = value ?? '';
+                i++;
+                break;
+        }
+    }
+    if (runId === '' || reportPath === '' || acPath === '') {
+        process.stderr.write(
+            'usage: idea-coverage-check.ts --run-id <id> --report <path> --ac <path> [--out <path>]\n',
+        );
+        process.exit(2);
+    }
+    return {
+        runId,
+        reportPath,
+        acPath,
+        outPath: outPath !== '' ? outPath : join('.spur', 'run', `${runId}-idea-coverage.status`),
+    };
+}
+
+/**
+ * Inventory ids from the report's `## Requirement inventory` section, split into
+ * covered-owing (no `[deferred:` marker) and exempt (deferred) ids. An `[unclear:`
+ * marker is informational — the item still owes coverage.
+ */
+function parseInventory(report: string): { owing: Set<string>; deferred: Set<string>; hasSection: boolean } {
+    const lines = report.split('\n');
+    const start = lines.findIndex((line) => /^#{1,6}\s*Requirement inventory\s*$/i.test(line));
+    if (start === -1) return { owing: new Set(), deferred: new Set(), hasSection: false };
+    const owing = new Set<string>();
+    const deferred = new Set<string>();
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^#{1,6}\s/.test(lines[i] ?? '')) break;
+        const match = INVENTORY_ITEM_RE.exec(lines[i] ?? '');
+        if (match === null) continue;
+        const id = `I${match[1]}`;
+        if (/\[\s*deferred\s*:/i.test(match[2] ?? '')) deferred.add(id);
+        else owing.add(id);
+    }
+    return { owing, deferred, hasSection: true };
+}
+
+/** Coverage map from the AC content: scenario-count per `I<n>` id. */
+function parseCoverage(ac: string): Map<string, number> {
+    const covered = new Map<string, number>();
+    let inScenario = false;
+    for (const line of ac.split('\n')) {
+        if (SCENARIO_RE.test(line)) {
+            inScenario = true;
+            continue;
+        }
+        if (!inScenario) continue;
+        const match = COVERS_RE.exec(line);
+        if (match === null) continue;
+        for (const raw of (match[1] ?? '').split(',')) {
+            const id = raw.trim().toUpperCase();
+            if (/^I\d+$/.test(id)) covered.set(id, (covered.get(id) ?? 0) + 1);
+        }
+    }
+    return covered;
+}
+
+function writeStatus(outPath: string, verdict: 'PASS' | 'FAIL', runId: string, detail: string): void {
+    mkdirSync(dirname(outPath), { recursive: true });
+    writeFileSync(outPath, `${verdict}\n`);
+    // Sibling reason file: the feature-check HITL prompt surfaces WHY next to the bare
+    // status letter, without guards having to parse a multi-line status file.
+    writeFileSync(`${outPath}.reason`, `${verdict} run=${runId} ${detail}\n`);
+}
+
+function main(): void {
+    const args = parseArgs(process.argv.slice(2));
+
+    if (!existsSync(args.reportPath) || !existsSync(args.acPath)) {
+        const detail = `missing input (report=${existsSync(args.reportPath) ? 'ok' : 'absent'}, ac=${existsSync(args.acPath) ? 'ok' : 'absent'})`;
+        writeStatus(args.outPath, 'FAIL', args.runId, detail);
+        process.stdout.write(`idea-coverage-check FAIL run=${args.runId} ${detail}\n`);
+        return;
+    }
+
+    const inventory = parseInventory(readFileSync(args.reportPath, 'utf8'));
+    const covered = parseCoverage(readFileSync(args.acPath, 'utf8'));
+
+    if (!inventory.hasSection || inventory.owing.size + inventory.deferred.size === 0) {
+        const detail = `no Requirement inventory items in ${args.reportPath}`;
+        writeStatus(args.outPath, 'FAIL', args.runId, detail);
+        process.stdout.write(`idea-coverage-check FAIL run=${args.runId} ${detail}\n`);
+        return;
+    }
+
+    const uncovered = [...inventory.owing].filter((id) => (covered.get(id) ?? 0) === 0).sort();
+    const shape = `inventory=${inventory.owing.size + inventory.deferred.size} (deferred=${inventory.deferred.size})`;
+    if (uncovered.length > 0) {
+        const detail = `${shape} covered=${inventory.owing.size - uncovered.length} uncovered=${uncovered.join(',')}`;
+        writeStatus(args.outPath, 'FAIL', args.runId, detail);
+        process.stdout.write(`idea-coverage-check FAIL run=${args.runId} ${detail}\n`);
+        return;
+    }
+
+    const detail = `${shape} all covered`;
+    writeStatus(args.outPath, 'PASS', args.runId, detail);
+    process.stdout.write(`idea-coverage-check PASS run=${args.runId} ${detail}\n`);
+}
+
+main();

package/plugins/sp/scripts/inline-pipeline-parity-check.ts

@@ -11,8 +11,14 @@
  * check is a symmetric set diff: an element present in one and absent in the
  * other fails the check and names the element.
  *
- * The set is defined in {@link DOCUMENTED} below; the driver's markdown list is
- * the human mirror. Update both when the driver adds or drops a kind.
+ * The set is defined in {@link DOCUMENTED} below. Task 0881 (0877 R7): the harness
+ * enumerates state from BOTH reference sets — this constant and the driver
+ * markdown's mirror list — plus the YAML union, as a three-way symmetric diff, so
+ * removing a kind from either reference cannot escape parity. It also scans task
+ * frontmatter `dependencies[]` for spurious edges: a referenced wbs with no task
+ * file (post-0875, dependency edges no longer move the planning digest —
+ * `packages/app/src/services/task-readiness.ts` — so over-declared edges would
+ * otherwise be silently unbound).
  *
  * Usage:
  *   bun plugins/sp/scripts/inline-pipeline-parity-check.ts
@@ -49,6 +55,91 @@ const DOCUMENTED = {
 /** Directory of workflow definitions the driver is responsible for. */
 const WORKFLOW_DIR = join('config', 'workflows');
 
+/** The driver reference doc — the second reference set (0881). */
+const DRIVER_REF = join('plugins', 'sp', 'skills', 'spur-dev', 'references', 'inline-pipeline-driver.md');
+
+/** Task corpus dirs scanned for spurious `dependencies[]` edges (0881). */
+const TASK_DIRS = ['docs/tasks', 'docs/tasks5'];
+
+/**
+ * Parse the driver reference's mirrored kind lists (`**Actions:** … · `kind` …`) into
+ * reference sets. Returns null when the doc is absent (fixture roots).
+ */
+function collectMarkdownReferenceKinds(root: string): { actions: Set<string>; guards: Set<string> } | null {
+    let md: string;
+    try {
+        md = readFileSync(join(root, DRIVER_REF), 'utf8');
+    } catch {
+        return null;
+    }
+    const read = (label: RegExp): Set<string> => {
+        const line = md.split('\n').find((l) => label.test(l));
+        const out = new Set<string>();
+        if (!line) return out;
+        for (const m of line.matchAll(/`([^`]+)`/g)) out.add(m[1] ?? '');
+        out.delete('');
+        return out;
+    };
+    return { actions: read(/^\*\*Actions:/), guards: read(/^\*\*Guards/) };
+}
+
+/**
+ * Scan task frontmatter `dependencies[]` for spurious edges: a referenced wbs that
+ * resolves to no task file in the corpus (0881 — post-0875 these edges no longer
+ * move the planning digest, so over-declared ones are otherwise silently unbound).
+ */
+function checkTaskDependencyEdges(root: string, errors: string[]): number {
+    const wbss = new Set<string>();
+    const depFiles: { path: string; deps: string[] }[] = [];
+    for (const dir of TASK_DIRS) {
+        const abs = join(root, dir);
+        let entries: string[] = [];
+        try {
+            entries = readdirSync(abs);
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            const m = /^(\d+)_.*\.md$/.exec(e);
+            if (!m?.[1]) continue;
+            wbss.add(m[1]);
+            const raw = readFileSync(join(abs, e), 'utf8');
+            const fm = /^---\n([\s\S]*?)\n---/.exec(raw);
+            if (!fm?.[1]) continue;
+            const deps: string[] = [];
+            const inline = /^dependencies:\s*\[(.*)\]/m.exec(fm[1]);
+            if (inline?.[1]) {
+                for (const part of inline[1].split(',')) {
+                    const w = part.trim().replace(/["']/g, '');
+                    if (w !== '') deps.push(w);
+                }
+            } else {
+                const block = /^dependencies:\s*$/m.exec(fm[1]);
+                if (block) {
+                    for (const line of fm[1].split('\n')) {
+                        const item = /^\s*-\s*["']?(\d+)["']?\s*$/.exec(line);
+                        if (item?.[1]) deps.push(item[1]);
+                    }
+                }
+            }
+            if (deps.length > 0) depFiles.push({ path: join(dir, e), deps });
+        }
+    }
+    let count = 0;
+    for (const { path, deps } of depFiles) {
+        for (const dep of deps) {
+            // Only wbs-shaped values are machine dependency edges; prose refs in the
+            // legacy corpus are descriptive text, never consumed as edges.
+            if (!/^\d{3,4}$/.test(dep)) continue;
+            if (!wbss.has(dep)) {
+                errors.push(`spurious dependency edge: ${path} depends on ${dep} but no task with wbs ${dep} exists`);
+                count += 1;
+            }
+        }
+    }
+    return count;
+}
+
 /** Walk a state list and yield every `kind:` value found in `onEnter` action
  *  lists. Skips the top-level workflow `kind:` (e.g. `state-machine`). */
 function collectActionKinds(states: unknown): Set<string> {
@@ -170,6 +261,26 @@ async function main(): Promise<number> {
         errors.push(`guard kind "${x}" documented in inline-pipeline-driver.md but never used in any workflow`);
     }
 
+    // Three-way parity with the markdown mirror (0881): a kind dropped from either
+    // reference set — constant or doc — is caught, not just YAML drift.
+    const ref = collectMarkdownReferenceKinds(root);
+    if (ref !== null) {
+        for (const x of diff(ref.actions, DOCUMENTED.actions).onlyInA)
+            errors.push(`action kind "${x}" in the driver markdown but absent from the DOCUMENTED set`);
+        for (const x of diff(ref.actions, DOCUMENTED.actions).onlyInB)
+            errors.push(`action kind "${x}" in DOCUMENTED but deleted from the driver markdown reference`);
+        for (const x of diff(ref.guards, DOCUMENTED.guards).onlyInA)
+            errors.push(`guard kind "${x}" in the driver markdown but absent from the DOCUMENTED set`);
+        for (const x of diff(ref.guards, DOCUMENTED.guards).onlyInB)
+            errors.push(`guard kind "${x}" in DOCUMENTED but deleted from the driver markdown reference`);
+        for (const x of diff(ref.actions, unionActions).onlyInB)
+            errors.push(`action kind "${x}" in the references but never used in any workflow`);
+        for (const x of diff(ref.guards, unionGuards).onlyInB)
+            errors.push(`guard kind "${x}" in the references but never used in any workflow`);
+    }
+
+    const spuriousEdges = checkTaskDependencyEdges(root, errors);
+
     if (errors.length > 0) {
         process.stderr.write(`inline-pipeline-parity-check: ${errors.length} divergence(s)\n`);
         for (const e of errors) process.stderr.write(`  - ${e}\n`);
@@ -177,7 +288,7 @@ async function main(): Promise<number> {
     }
 
     process.stdout.write(
-        `inline-pipeline-parity-check: ok (${unionActions.size} actions, ${unionGuards.size} guards agree across ${files.length} workflows)\n`,
+        `inline-pipeline-parity-check: ok (${unionActions.size} actions, ${unionGuards.size} guards agree across ${files.length} workflows and both reference sets; ${spuriousEdges} spurious dependency edges)\n`,
     );
     return 0;
 }

package/plugins/sp/scripts/inline-run-setup.ts

@@ -31,7 +31,7 @@
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> \
- *       --status <done|failed|running|paused> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
+ *       --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]
  *
  * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
@@ -78,7 +78,7 @@ function usage(): never {
     );
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> ' +
-            '--status <done|failed|running|paused> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
+            '--status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
     );
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]',
@@ -200,10 +200,12 @@ async function printFingerprint(taskFile: string, featureFile: string, spurBin:
 /** Terminal statuses the inline driver may declare when closing its run row. */
 const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
 
-/** Action-row statuses the engine's `action_runs.status` column accepts. */
-const ACTION_STATUSES = new Set(['running', 'done', 'failed', 'paused']);
+/** Finalize statuses — a finish emission is terminal, so only done|failed are valid (0868 #4). */
+const ACTION_STATUSES = new Set(['done', 'failed']);
 
 /** Input for the ADR-117 emission modes (`--action` / `--close`). */
+import type { WorkflowActionTraceWriter } from '@gobing-ai/app';
+
 interface TraceModeInput {
     readonly runId: string;
     readonly close: boolean;
@@ -260,15 +262,15 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
         );
     }
 
+    // Compile-time link (0868 finding #5): the writer half is typed by the real packages/app
+    // export (type-only import, erased at runtime) so a signature drift breaks THIS file's
+    // typecheck instead of hiding behind the hand-declared cast.
     const app = (await import(entry)) as {
         openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
         createWorkflowActionTraceWriter: (
             db: unknown,
             recordFailure?: (failure: unknown) => void,
-        ) => {
-            recordAction: (boundary: Record<string, unknown>) => Promise<{ ok: boolean; actionId?: string }>;
-            closeRun: (runId: string, status: string) => Promise<{ ok: boolean }>;
-        };
+        ) => WorkflowActionTraceWriter;
     };
 
     let projectDb: { adapter: unknown; close: () => void } | undefined;
@@ -281,16 +283,24 @@ async function runTraceMode(input: TraceModeInput): Promise<number> {
                 `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? 'unknown error'}`,
             );
         });
-        const result = input.close
-            ? await writer.closeRun(input.runId, input.status)
-            : await writer.recordAction({
-                  runId: input.runId,
-                  node: input.node,
-                  kind: input.kind,
-                  status: input.status,
-                  ok: input.ok,
-                  durationMs: input.durationMs,
-              });
+        const result = (
+            input.close
+                ? await writer.closeRun(input.runId, input.status)
+                : await writer.recordAction({
+                      runId: input.runId,
+                      node: input.node,
+                      kind: input.kind,
+                      status: input.status,
+                      ok: input.ok,
+                      durationMs: input.durationMs,
+                  })
+        ) as Record<string, unknown>;
+        if (result.ok !== true && result.failure !== undefined) {
+            // One stdout shape for emission failures (0868 finding #1): flatten the guard's
+            // nested failure object to the same `{ok, runId, error}` the direct paths emit.
+            const failure = result.failure as { error?: string };
+            return fail(failure.error ?? 'unknown trace emission failure');
+        }
         process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}\n`);
         return 0;
     } catch (error) {

package/plugins/sp/skills/brainstorm/SKILL.md

@@ -197,6 +197,10 @@ When brainstorm runs under `idea-pipeline` discovery, it MUST also emit a filled
 [`spur-dev/references/idea-evaluation.md`](../spur-dev/references/idea-evaluation.md):
 
 - Enhanced idea statement (sidecar — does **not** overwrite the operator's original idea text)
+- **Requirement inventory** — mandatory `## Requirement inventory` section: numbered `I<n>` items
+  quoting or paraphrasing the source lines from the run's verbatim idea artifact
+  (`.spur/run/<run-id>-idea-input.md`, 0887 R1/R3), with `[unclear: ...]` markers where the ask is
+  ambiguous and `[deferred: <reason>]` markers for explicit out-of-scope items
 - Urgency and necessity scores (0–5) with one-line rationales
 - Premises, pros, cons, better alternatives (if any)
 - Recommendation (`proceed` | `reshape` | `drop`) + stakes

package/plugins/sp/skills/code-refactoring/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: code-refactoring
+description: "Refactoring coordinator with a preservation contract: routes the four taste lenses (api, architect, tests, ui), normalizes findings to a shared schema and P1–P4 severities, gates applies, runs a fix ladder with revert-on-regression. Use for 'dev-refactor', 'safe refactor', 'refactor while keeping every feature'."
+license: Apache-2.0
+metadata:
+  author: spur
+  version: "1.0"
+  platforms: "claude-code,codex,openclaw,opencode,antigravity"
+  category: execution
+  interactions:
+    - technique
+  operations:
+    - refactor
+  openclaw:
+    emoji: "♻️"
+see_also:
+  - sp:taste-refactoring-api
+  - sp:taste-refactoring-architect
+  - sp:taste-refactoring-tests
+  - sp:taste-refactoring-ui
+  - sp:code-simplification
+  - sp:code-review
+---
+
+# code-refactoring — the lens-routed refactoring coordinator
+
+Own everything a cheaper executor must get right **mechanically**: routing, finding schema,
+severity normalization, preservation classification, gate policy, apply loop, artifacts. The four
+taste lenses keep their principles and judgments; this skill turns their prose into gated,
+checkable, reversible work.
+
+The product is **analysis first, edits second**: with the default `--fix none` the run writes two
+artifacts and performs no edit at all.
+
+Backs `/sp:dev-refactor`. Authority: `docs/design/dev-refactor-command.md` (§2 phases, §4–§8
+contracts, §11 invariants).
+
+## Inputs
+
+| Input | Meaning | Default |
+| --- | --- | --- |
+| `--scope <path>` | Path bound; no edit may land outside it. | working tree (recent changes) |
+| `--focus <api\|architect\|tests\|ui\|auto>` | Lens set; comma list allowed. | `auto` |
+| `--fix <none\|blockers-first\|all>` | Apply policy. | `none` |
+| `--check <cmd>` | Baseline and per-fix verification command. | project gate (`bun run spur-check` when present) |
+| `--auto` | Skips **objective** gates only. | off |
+| free-text description | Steering for the lenses (e.g. "pagination consistency"). | — |
+
+## Stop rules (design §11 — verbatim, non-negotiable)
+
+1. **No edit outside `--scope`; no edit before a green baseline.**
+2. **`cutting` / `breaking` findings are applied only after an explicit operator `yes`.**
+3. **Tests are never removed or weakened by an `auto` fix.**
+4. **Every finding carries `file:line` evidence inside scope.**
+5. **The command file contains no orchestration logic** — this skill owns the orchestration, the
+   command stays a thin wrapper.
+
+Violating any stop rule ends the run as a failure; do not "finish" a partial apply.
+
+## Phase 0 — Resolve
+
+1. Resolve `--scope` to a concrete path; list the in-scope files.
+2. Resolve the lens set: if `--focus auto`, classify per
+   [focus-detection.md](./references/focus-detection.md) (ordered globs, first match per file,
+   union across files); otherwise use the given lens list.
+3. **Report the lens set before any lens runs** (one line, per focus-detection.md).
+4. Run the `--check` command for a **green baseline**. Red baseline = hard stop: write the report,
+   apply nothing, end the run.
+
+## Phase 1 — Analyze (dispatch lenses)
+
+For each lens in the resolved set, dispatch the taste skill and collect native findings:
+
+```text
+Skill(sp:taste-refactoring-tests)      # if tests in lens set
+Skill(sp:taste-refactoring-ui)         # if ui in lens set
+Skill(sp:taste-refactoring-api)        # if api in lens set
+Skill(sp:taste-refactoring-architect)  # if architect in lens set
+```
+
+Pass each lens the scope path and the free-text description. Read the lens's `## Spur contract`
+section, then map its native findings into the shared schema
+([finding-schema.md](./references/finding-schema.md)): lens-native rung is kept in `rung`,
+severity is translated through the §5 map, and every finding carries a **preserved-behavior
+inventory** input from the lens (endpoints / modules / test-protected behaviors / UI controls in
+scope) before any proposal.
+
+Classification rules when mapping (enforced by the structural check):
+
+- `preservation`: does the proposal remove a user-visible feature/test/endpoint/control
+  (`cutting`), change a contract or observable behavior for a consumer (`breaking`), or keep
+  behavior identical (`preserving`)?
+- `fix_eligibility`: `auto` only for mechanical, behavior-preserving, checkable changes;
+  `confirm` when an operator answer is needed; `suggest` for report-only plans.
+- A `cutting`/`breaking` finding is never below P2 and never `auto`.
+
+## Phase 2 — Merge
+
+1. Dedupe by `(evidence file, line span, rung)`: identical span + rung from two lenses is one
+   finding — keep the higher severity, keep the first lens's `id` (renumber gaps afterward).
+2. Rank P1 → P4 (then focus order tests, ui, api, architect).
+3. Re-assert scope: every `evidence[].file` is inside `--scope`; drop or fail findings that are
+   not (stop rule 4).
+
+## Phase 3 — Gate
+
+| Gate | Class | `--auto` | Headless (`--agent auto\|name`) |
+| --- | --- | --- | --- |
+| Confirm resolved scope + lens set | objective | skipped | skipped |
+| Confirm apply batch of `auto` findings | objective | skipped | skipped |
+| Each `cutting` / `breaking` finding | **taste** | **pauses** | no pause: `status: deferred`, listed as SUGGEST in the report |
+| Baseline check red | hard stop | stop, report | stop, report |
+
+- **Objective gates** ask yes/no about facts (scope, lens set, batch contents); `--auto` answers
+  them from the resolved state.
+- **Taste gates** — every `cutting` or `breaking` finding — **always pause for an explicit
+  operator answer** in an interactive session, regardless of `--auto`. Under a headless executor
+  there is no operator to ask: set `status: deferred` and list the finding as SUGGEST in the
+  report. A headless run never applies a cutting/breaking finding.
+- A declined taste gate marks the finding `status: rejected` (operator "no") — never silently
+  dropped.
+
+## Phase 4 — Apply (fix ladder)
+
+Execute `--fix` per [fix-ladder.md](./references/fix-ladder.md): green baseline first, one finding
+at a time, re-run `--check` after each, revert only the failed finding's own edits (reverse-apply
+its hunks — never a file-level checkout; see fix-ladder.md) and mark
+`reverted`. `none` skips this phase entirely (both artifacts still written).
+
+## Phase 5 — Report
+
+Run the structural check from [finding-schema.md](./references/finding-schema.md), then write both
+artifacts:
+
+1. `.spur/run/<run-id>-refactor-findings.json` — the bare findings array (validated schema).
+2. `.spur/run/<run-id>-refactor-report.md` — containing:
+   - the resolved **lens set** (and per-file counts for `auto`),
+   - a **P1–P4 findings table** with `file:line`,
+   - a **preservation summary** (preserving / cutting / breaking counts),
+   - **applied / reverted / deferred** lists (plus rejected when taste gates declined findings).
+
+`<run-id>` is the enclosing pipeline run id when invoked inside one, otherwise
+`refactor-<yyyymmdd>-<hhmmss>`. `--fix none` still writes both artifacts.
+
+## Cheaper executor — minimum reading
+
+A reduced-context executor may run this skill with exactly these files:
+
+1. this `SKILL.md` (phases, gates, stop rules),
+2. `references/finding-schema.md` (fields, severity map, structural check),
+3. `references/fix-ladder.md` (apply loop, revert rule),
+4. `references/focus-detection.md` (globs, report-before-run),
+5. each selected lens's `## Spur contract` section only.
+
+Do not skip the structural check or the stop rules; everything else is compressible.

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

@@ -0,0 +1,74 @@
+# Refactor finding schema
+
+Every finding produced by a taste lens is normalized into one shared object before the coordinator
+merges, gates, or applies anything. The findings artifact is a **bare JSON array** of these objects
+at `.spur/run/<run-id>-refactor-findings.json`, machine-checked by
+[`refactor-finding.schema.json`](./refactor-finding.schema.json) (JSON Schema draft-07).
+
+Authority: `docs/design/dev-refactor-command.md` §4 (fields) and §5 (severity map).
+
+## Fields
+
+| Field | Type | Values / notes |
+| --- | --- | --- |
+| `id` | string | `RF-<focus>-<nnn>` (e.g. `RF-api-001`) |
+| `focus` | enum | `api` `architect` `tests` `ui` — the lens that produced the finding |
+| `severity` | enum | `P1` `P2` `P3` `P4` (see the map below; `P0` does not exist in this schema) |
+| `rung` | string | lens-native rung kept verbatim (`A0–A7`, `T0–T7`, api compatibility class, ui pass name) |
+| `title` | string | one line |
+| `evidence` | `{file, line}[]` | at least one `file:line` inside `--scope` |
+| `preservation` | enum | `preserving` (behavior identical) · `cutting` (a user-visible feature/test/endpoint/control is removed) · `breaking` (contract or behavior changes for a consumer) |
+| `fix_eligibility` | enum | `auto` (mechanical, behavior-preserving, checkable) · `confirm` (needs an operator answer) · `suggest` (report only) |
+| `proposal` | string | what to change, imperative |
+| `verify` | string | command or check that proves the fix (defaults to the `--check` command) |
+| `status` | enum | `open` `applied` `reverted` `deferred` `rejected` |
+
+Severity authority: `plugins/sp/agents/super-reviewer.md` (P1 blocker · P2 major · P3 minor ·
+P4 advisory). The map below is the only place lens-native severities are translated.
+
+## Lens-native → P1–P4 severity map
+
+| Lens | Native scale | → P1 (blocker) | → P2 (major) | → P3 (minor) | → P4 (advisory) |
+| --- | --- | --- | --- | --- | --- |
+| tests | P0–P3 | P0 | P1 | P2 | P3 |
+| ui | P0–P3 | P0 | P1 | P2 | P3 |
+| architect | A-ladder + 7-axis scores | any axis ≤1 with a correctness/safety consequence | axis ≤2 or A5–A7 seam problems | A3–A4 | A0–A2, ADR candidates, deferred questions |
+| api | compatibility class | `breaking` change already shipped or contract ambiguity that corrupts data | `risky` inconsistency across ≥2 endpoints | `additive` cleanups | naming/docs |
+
+Rule (structural, enforced by the check below): a `cutting` or `breaking` finding is **never below
+P2** and **never `fix_eligibility: auto`**.
+
+## Structural check (no new dependency)
+
+Run this documented `bun -e` snippet before writing the report — it asserts required keys and enum
+membership and fails loudly on the two hard rules above (it must reject `severity: P0` and any
+`cutting`/`breaking` finding marked `fix_eligibility: auto`):
+
+```bash
+bun -e '
+const f = require("fs");
+const FINDINGS = JSON.parse(f.readFileSync(process.argv[process.argv.length - 1], "utf8"));
+const REQ = ["id", "focus", "severity", "rung", "title", "evidence", "preservation", "fix_eligibility", "proposal", "verify", "status"];
+const ENUM = {
+  focus: ["api", "architect", "tests", "ui"],
+  severity: ["P1", "P2", "P3", "P4"],
+  preservation: ["preserving", "cutting", "breaking"],
+  fix_eligibility: ["auto", "confirm", "suggest"],
+  status: ["open", "applied", "reverted", "deferred", "rejected"],
+};
+if (!Array.isArray(FINDINGS)) throw new Error("findings artifact must be a bare JSON array");
+for (const x of FINDINGS) {
+  const id = x.id ?? "(no id)";
+  for (const k of REQ) if (!(k in x)) throw new Error(`${id}: missing required key ${k}`);
+  for (const [k, vals] of Object.entries(ENUM)) if (!vals.includes(x[k])) throw new Error(`${id}: ${k}=${JSON.stringify(x[k])} not in ${vals.join("|")}`);
+  if (!Array.isArray(x.evidence) || x.evidence.length < 1 || !x.evidence.every((e) => e && typeof e.file === "string" && e.file.length > 0 && Number.isInteger(e.line) && e.line >= 1)) throw new Error(`${id}: evidence must be a non-empty [{file, line}] array`);
+  if ((x.preservation === "cutting" || x.preservation === "breaking") && x.severity !== "P1" && x.severity !== "P2") throw new Error(`${id}: cutting/breaking is never below P2`);
+  if ((x.preservation === "cutting" || x.preservation === "breaking") && x.fix_eligibility === "auto") throw new Error(`${id}: cutting/breaking is never fix_eligibility auto`);
+}
+console.log(`refactor-findings: ${FINDINGS.length} finding(s) structurally valid`);
+' .spur/run/<run-id>-refactor-findings.json
+```
+
+The coordinator runs this check after mapping and again after every status change, before the
+report is written. A failed check is a hard stop — the artifact is not written and the run reports
+the failure instead of applying anything.