@gobing-ai/spur 0.3.85 → 0.3.87

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.

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-cli/references/workflows.md

@@ -62,7 +62,7 @@ ordered guards, and may loop back on itself (e.g. implement → check → fix
 | Node typing | none (states are untyped) | `type: action\|gate\|parallel\|decision` |
 | Required keys | `name, initialState, states, transitions` | `kind, name, initialNode, nodes, edges` |
 | `kind` field | optional (defaults to state-machine) | **required** — `kind: transition-flow` |
-| Canonical example | implement→check→fix loop (`basic.yaml` — soft status-file probe + bounded fixall) | read→validate→transform→write pipeline |
+| Canonical example | implement→check→fix loop (`task-pipeline.yaml` — quality-gate hop with bounded fixall) | read→validate→transform→write pipeline |
 
 **Heuristic:** loops / retries / one-active-state → **state-machine**; pipeline / fan-out / action-per-node → **transition-flow**.
 
@@ -95,7 +95,7 @@ Use this skill to:
 
 The skill's logic divides by **whether the LLM adds value**:
 
-- **Direct CLI** (`validate`, `run`, `list`, `trace`, `continue`, `cancel`, `clean`) — deterministic,
+- **Direct CLI** (`validate`, `run`, `list`, `trace`, `progress`, `continue`, `cancel`, `clean`) — deterministic,
   single-verb commands. Run them straight. A slash-command wrapper would only forward flags and add
   drift; **there is no command for these — use the CLI**. The skill still drives them in natural
   language (interpreting a failed validate, reading a run trace).
@@ -113,6 +113,7 @@ The skill's logic divides by **whether the LLM adds value**:
 | `clean` | `spur workflow clean` (CLI) | `[--older-than <min>] [--force] [--logs] [--dry-run]` | Bulk-finalize stale `running`/`pending` runs as failed **and** reclaim retained run logs older than `workflow.logRetentionDays` (30d default) |
 | `list` | `spur workflow list` (CLI) | — | Available workflow **YAML definition files** (not run records) |
 | `trace` | `spur workflow trace` (CLI) | `[run-id] [--workflow <n>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output]` | Run history list or per-run timeline |
+| `progress` | `spur workflow progress` (CLI) | `<run-id>` | The `projectWorkflowProgress` projection for that run — current state, per-action attempts, candidate next transitions, diagnostics. Read-only; the verb renders, `packages/app` derives. Unknown run id exits 1 with `Run <id> not found.` |
 | `add` | agent procedure | `"<nl-description>" [--kind <state-machine\|transition-flow>] [--file <path>]` | **Mode chosen (confirmed)** → first reconciled against existing workflows (extend an existing flow rather than duplicate) → YAML authored in real schema shape → **validated AND dry-run** (reaches the expected terminal state) → [add](workflows/operations.md#add) |
 | `refine` | agent procedure | `<workflow-file> [--intent "<goal>"] [--dry-run]` | Smallest change meeting the intent, re-validated and re-dry-run; `--dry-run` emits a diff only → [refine](workflows/operations.md#refine) |
 
@@ -262,6 +263,7 @@ spur workflow cancel   <run-id> [--json]
 spur workflow clean    [--older-than <minutes>] [--force] [--logs] [--dry-run] [--json]
 spur workflow list     [--json]
 spur workflow trace    [run-id] [--workflow <name>] [--status <s>] [--since <iso>] [--last <n>] [--follow] [--poll <ms>] [--output] [--json]
+spur workflow progress <run-id> [--json]
 ```
 
 ### `show` - project a definition
@@ -359,7 +361,7 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
    (transition-flow) wins. Order the specific case before the fallback. Simple shell checks can use
    `action-ok` before an unconditional retry edge; multi-condition gates prefer a **soft status-file
    probe** (always exit 0) with ordered shell guards for PASS / FAIL / exhausted (see
-   `basic.yaml` and `task-pipeline.yaml` quality-gate hop).
+   `task-pipeline.yaml`'s quality-gate hop).
 4. **`env.allow` is an allowlist.** `${env.X}` resolves only if `X` is listed under `env.allow`;
    otherwise it resolves empty. A workflow that "loses" an environment value usually forgot to allow it.
 5. **Extensions are fail-closed.** The CLI loads YAML-declared extension modules itself
@@ -400,10 +402,9 @@ the workflow's actions (`shell`, custom runners) do that; this skill builds and
   custom action/guard runners, the trust-gated extension loader, and CLI-vs-library capability gaps.
 - `@gobing-ai/ts-dual-workflow-engine` README — authoritative library reference (both drivers,
   RunLifecycle, persistence, the full event map, every built-in capability).
-- `basic.yaml` — the canonical state-machine implement→soft-check→fixall loop
-  (status-file branching + `qualityGateMaxFixAttempts`); copy real shapes from here.
-- `task-pipeline.yaml` — full production pipeline (precheck, quality gate, HITL,
-  verify, record) when you need the complete reliability pattern set.
+- `task-pipeline.yaml` — the canonical state-machine implement→soft-check→fixall loop and
+  full production pipeline (status-file branching, `qualityGateMaxFixAttempts`, quality gate,
+  HITL, verify, record); copy real shapes from here.
 
 ## Platform Notes