@gobing-ai/spur 0.3.86 → 0.3.88

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.86",
+    "version": "0.3.88",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -53,14 +53,14 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-db": "^0.4.67",
-        "@gobing-ai/ts-ai-runner": "^0.4.67",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.67",
-        "@gobing-ai/ts-infra": "^0.4.67",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.67",
-        "@gobing-ai/ts-rule-engine": "^0.4.67",
-        "@gobing-ai/ts-runtime": "^0.4.67",
-        "@gobing-ai/ts-utils": "^0.4.67",
+        "@gobing-ai/ts-db": "^0.4.69",
+        "@gobing-ai/ts-ai-runner": "^0.4.69",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.69",
+        "@gobing-ai/ts-infra": "^0.4.69",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.69",
+        "@gobing-ai/ts-rule-engine": "^0.4.69",
+        "@gobing-ai/ts-runtime": "^0.4.69",
+        "@gobing-ai/ts-utils": "^0.4.69",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/plugins/sp/README.md

@@ -94,7 +94,7 @@ list this README is checked against.
 | `dev-idea`       | Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create, handoff |
 | `dev-plan`       | Plan a feature from a written description — intake → feature create → AC generation → feature check gate → decomposition → batch-create                                         |
 | `dev-brainstorm` | Interactive solution design — heuristic discovery interview followed by structured ideation with trade-offs and confidence scoring                                              |
-| `dev-refine`     | Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; `--depth ready` for implement-ready freeze                    |
+| `dev-refine`     | Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; `--depth ready` audits and corrects existing claims, freezes the spec, promotes to todo |
 
 #### Lifecycle — execution
 
@@ -116,7 +116,7 @@ list this README is checked against.
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `dev-runall`    | Run a batch of tasks through their pipelines in dependency-correct order — resolve a set, topo-sort, run each via task-pipeline.yaml, emit a batch report              |
 | `dev-parallel`  | Fan out independent tasks or investigations in parallel via subagents — choose the right pattern and synthesize results                                                |
-| `dev-refineall` | Batch-refine tasks (feature or selector) — planning-half bulk fill of Background/Requirements/AC/Design/Plan before runall; `--depth ready` for implement-ready freeze |
+| `dev-refineall` | Batch-refine tasks (feature or selector) — planning-half bulk fill of Background/Requirements/AC/Design/Plan before runall; `--depth ready` audits, corrects, freezes and promotes each task |
 | `dev-verifyall` | Batch-verify tasks against requirements and AC — resolves a set, runs per-task verification, produces consolidated PASS/PARTIAL/FAIL summary report                    |
 | `dev-wrapall`   | Wrap up a batch of completed tasks — learnings, metrics, doc-sync, feature transition, optional branch cleanup                                                         |
 
@@ -134,6 +134,7 @@ list this README is checked against.
 | `dev-find-next`     | Prompt-first feature frontier prioritizer — ranks the open feature frontier by derived importance/urgency with per-candidate evidence; gates unactionable features; emits tree defects as proposals only     |
 | `dev-fixall`        | Fix all lint, type, and test errors systematically across the working tree                                                                                                                        |
 | `dev-simplify`      | Simplify recently-changed code for clarity without changing behavior — incremental, test-after-each, revert on regression                                                                         |
+| `dev-refactor`      | Lens-routed refactoring with a preservation contract — taste lenses (api/architect/tests/ui) classify findings on the shared schema; cutting/breaking changes pause for operator approval; forwards to sp:code-refactoring |
 | `dev-arch`          | Survey a codebase (or module tree) for shallow modules and deepening opportunities — emit a ranked MARKDOWN candidate report that feeds the planning half; never auto-refactors                   |
 | `dev-reverse`       | Reverse-engineer a codebase — analyze unfamiliar repos, generate HLD/architecture docs, audit quality/security, and produce onboarding documentation                                              |
 | `dev-gitmsg`        | Generate conventional commit message(s) from the current change set via one bounded diff capture, optionally commit                                                                                         |
@@ -199,6 +200,7 @@ plugins/sp/
 │   ├── code-review/                 # Pre-commit self-review + SECUA review lenses
 │   │   └── references/{review-lenses, self-review-checklist}.md
 │   ├── code-simplification/         # Behavior-preserving simplification
+│   ├── code-refactoring/            # Lens-routed refactoring coordinator (shared finding schema, P1–P4 severity map, fix ladder, focus detection)
 │   ├── code-testing/                # Testing / coverage competency
 │   │   └── references/{unit-testing.md, stacks/{bun-ts, go, python}.md}
 │   ├── code-verification/           # Verify + SECUA review
@@ -316,6 +318,7 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `code-review`               | 1.0   | Pre-commit self-review checklist (6 categories, catches 60-80% of issues) + SECUA review lenses + findings processing                                                                                                                      |
 | `code-simplification`       | 1.0   | Behavior-preserving simplification — Chesterton's Fence, signal tables, incremental change + test-after-each, scope-to-changed                                                                                                             |
 | `code-improvement`          | 1.0   | Architectural deepening — surface shallow/tightly-coupled modules and propose refactors that make them deep, testable, AI-navigable; backs `/sp:dev-arch`                                                                                  |
+| `code-refactoring`          | 1.0   | Lens-routed refactoring coordinator with a preservation contract — focus auto-detection, taste-lens dispatch, shared finding schema, P1–P4 severity map, objective/taste gates, fix ladder with revert-on-regression; backs `/sp:dev-refactor`  |
 | `functional-review`         | 1.0   | Requirements-traceability assessment — per-requirement verdicts with file:line evidence that the implementation satisfies ALL task requirements; pipeline Phase 8b gate                                                                    |
 | `doubt-driven-development`  | 1.0   | In-flight adversarial review of a non-trivial decision before committing it — hand artifact + contract to a fresh-context skeptic, reconcile, stop at 3 cycles                                                                             |
 | `source-driven-development` | 1.0   | Source-first verification — verify framework/API/library facts against primary sources before generating code; separates "the API exists" from "used correctly under its contract"                                                         |
@@ -340,10 +343,10 @@ surface or run one workflow. All skills target the same five core platforms: `cl
 | `spur-composer`             | 1.0   | Cross-noun composition — workflow catalog selection, the ephemeral→project→shared ladder, ADR-115 budgets, trace-driven rule tuning; applies accepted `spur-doctor` proposals through `spur` verbs; never judges its own output and never runs a recurring loop                                              |
 | `spur-doctor`               | 1.0   | Cross-noun evaluation — read-only CLI evidence per noun (task/feature/rule/workflow/agent spec), reflection over `history-anatomy` findings through a closed action-class map, and a proposal table; writes nothing; diagnoses artifacts, not runtime environments (`spur agent doctor`'s job)                |
 | `redesign-web-ui`           | 1.0   | Existing-UI visual upgrade — audit generic AI fingerprints, apply in-stack polish against `DESIGN.md` / live tokens, verify behavior and viewports; does not migrate frameworks                                                                                                                            |
-| `taste-refactoring-api`     | —     | API design and refactoring for REST/HTTP, RPC/gRPC, GraphQL, and event contracts; compatibility, security, and migration review |
-| `taste-refactoring-ui`      | —     | UI design and refactoring with visual hierarchy, typography, spacing, color, and interaction review |
-| `taste-refactoring-architect` | —   | Architecture review, simplification, and refactoring; boundary modeling, dependency reduction, and migration planning |
-| `taste-refactoring-tests`   | —     | Test suite refactoring for failure sensitivity, regression detection, and assertion strength; eliminates brittle mocks |
+| `taste-refactoring-api`     | 1.0   | API design and refactoring for REST/HTTP, RPC/gRPC, GraphQL, event contracts, and CLI surfaces; compatibility, security, and migration review |
+| `taste-refactoring-ui`      | 1.0   | UI design and refactoring with visual hierarchy, typography, spacing, color, and interaction review |
+| `taste-refactoring-architect` | 1.0 | Architecture review, simplification, and refactoring; boundary modeling, dependency reduction, and migration planning |
+| `taste-refactoring-tests`   | 1.0   | Test suite refactoring for failure sensitivity, regression detection, and assertion strength; eliminates brittle mocks |
 
 #### Bounded coexistence and retirement gate — `sp:issue-finding` (HA-S1 0661)
 

package/plugins/sp/commands/dev-idea.md

@@ -1,7 +1,7 @@
 ---
 description: Turn a vague idea into a feature with AC and a decomposed task batch — discovery, idea-eval, feature-create, AC, feature-check, system-design, decompose, batch-create (Design by default), handoff
 role: planner
-argument-hint: "\"<idea>\" [--auto] [--skip-design] [--approve-taste] [--agent <inline|auto|name>]"
+argument-hint: "\"<idea>\" [--from-file <path>] [--auto] [--skip-design] [--approve-taste] [--agent <inline|auto|name>]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 ---
 
@@ -14,7 +14,8 @@ contract below maps to that workflow's transitions.
 
 | Flag | Description | Default |
 | --- | --- | --- |
-| `"<idea>"` | Vague idea to turn into a feature with AC and tasks. | required |
+| `"<idea>"` | Vague idea to turn into a feature with AC and tasks. | required (or `--from-file`) |
+| `--from-file` `<path>` | Read the idea from a file instead of the positional argument. Mutually exclusive with `"<idea>"` — exactly one must be present. The file's contents become the verbatim idea text (trimmed of surrounding whitespace only). Useful for long or multiline asks that are awkward to quote. | off |
 | `--auto` | Skip objective HITL gates only (taste gates still pause). | off |
 | `--skip-design` | Omit system-design and per-task Design. | off |
 | `--approve-taste` | With `--auto`: set idea_approved + design_approved so idea-eval / design-approval do not pause. | off |
@@ -45,5 +46,11 @@ vars as subsets of `--approve-taste` (`idea_approved` / `design_approved`). Pref
 - Omitted/`inline`: drive `idea-pipeline.yaml` through the [inline pipeline driver](../skills/spur-dev/references/inline-pipeline-driver.md). Do not launch `spur workflow run`, `spur agent run`, or a native subagent unless the operator explicitly requests delegation.
 - `auto`/name: launch `spur workflow run idea-pipeline.yaml --async`, observe with one `workflow trace --follow`, and only report cancellation as stopped when `workflow cancel --json` returns `killed: true`.
 - `Skill(skill="sp:spur-dev", args="idea $ARGUMENTS")`
+- Pass the idea text through every hop **verbatim** — never paraphrase or shorten it in the nested
+  `Skill` call or stage prompts; long ideas lose their trailing asks when summarized at the hop.
+- Before executing the pipeline's `start` state, persist the operator's idea argument (or the
+  `--from-file` contents) **unmodified** to `.spur/run/<run-id>-idea-input.md` (0887 R1); every
+  model-bearing stage prompt treats that file as the authoritative ask, and the precheck fails
+  the run when it is empty or missing.
 - Stage contract (discovery → idea-eval → feature-create → AC → feature-check → system-design →
   decompose → batch-create → ready-prepare → handoff): `plugins/sp/skills/spur-dev/references/dev-operations.md` § idea.

package/plugins/sp/commands/dev-refactor.md

@@ -0,0 +1,33 @@
+---
+description: Lens-routed refactoring with a preservation contract — taste lenses classify findings against the shared schema; cutting/breaking changes pause for operator approval
+role: reviewer
+argument-hint: "[<description>] [--scope <path>] [--focus <api|architect|tests|ui|auto>] [--fix <none|blockers-first|all>] [--check <cmd>] [--agent <inline|auto|name>] [--auto]"
+allowed-tools: ["Bash", "Read", "Edit", "Skill"]
+---
+
+# Dev Refactor
+
+Wraps the **sp:code-refactoring** skill.
+
+## Argument Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `[<description>]` | Free-text steering for the lenses (e.g. "pagination consistency"). | — |
+| `--scope` `<path>` | Path bound; no edit may land outside it. | working tree |
+| `--focus` `<api\|architect\|tests\|ui\|auto>` | Lens set; comma list allowed (`api,tests`). | auto |
+| `--fix` `<none\|blockers-first\|all>` | Apply policy; `blockers-first` = P1/P2. | none |
+| `--check` `<cmd>` | Verification command for baseline and per-fix checks. | project gate |
+| `--agent` `<inline\|auto\|name>` | Who runs the model-bearing analysis. | inline |
+| `--auto` | Skip objective gates only; cutting/breaking taste gates still pause. | off |
+
+For shared semantics, see the [flag glossary](../skills/spur-dev/references/flag-glossary.md).
+
+## Usage
+
+/sp:dev-refactor [<description>] [--scope <path>] [--focus <api|architect|tests|ui|auto>] [--fix <none|blockers-first|all>] [--check <cmd>] [--agent <inline|auto|name>] [--auto]
+
+## Implementation
+
+- Apply the [inline-default execution-surface contract](../skills/spur-dev/references/cross-cutting.md#inline-default-execution-surface).
+- `Skill(skill="sp:code-refactoring", args="$ARGUMENTS")`

package/plugins/sp/commands/dev-refine.md

@@ -1,5 +1,5 @@
 ---
-description: Refine task requirements via structured Q&A — clarify scope, elicit missing details, tighten acceptance criteria; optional implement-ready depth
+description: Refine or re-audit a task — fill missing sections via Q&A, or with --depth ready verify existing claims and fixes against the tree, correct them, and promote to todo
 role: planner
 argument-hint: "<wbs> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--next]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
@@ -7,17 +7,24 @@ allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 
 # Dev Refine
 
-Wraps the **sp:spur-dev** skill. Prefer Design at plan/create (default); refine is the **fallback**
-for blank Design/AC/Plan after `--skip-design` or incomplete create. Use `--depth ready` when another
-agent will implement and L3-clean is not enough (frozen APIs, anti-patterns, file targets, handoffs).
+Wraps the **sp:spur-dev** skill. Three jobs:
+
+| Job | Invocation |
+| --- | --- |
+| Fill blank Design/AC/Plan after `--skip-design` or an incomplete create (fallback; Design normally comes from plan/create) | `/sp:dev-refine <wbs> --auto` |
+| Evaluate and correct an existing task: a review-triage filing, a stale backlog item, anything whose claims or proposed fixes may no longer hold | `/sp:dev-refine <wbs> --depth ready` (add `--auto` to skip Q&A) |
+| Freeze a spec for another implementer; also the recovery command when `spur task create` ready preparation fails | `/sp:dev-refine <wbs> --auto --depth ready` |
+
+`standard` checks only that target sections are structurally complete. It never re-checks what
+they say. Use `ready` whenever the existing content itself is in doubt.
 
 ## Argument Flags
 
 | Flag | Description | Default |
 | --- | --- | --- |
 | `<wbs>` | Task WBS to refine. | required |
-| `--focus` `<mode>` | Refinement focus mode. | omitted |
-| `--description` `<text>` | Override the task description. | omitted |
+| `--focus` `<mode>` | Gap-analysis focus: `all\|requirements\|background\|constraints\|acceptance\|quick`. | `all` |
+| `--description` `<text>` | Operator framing injected into Q&A/synthesis. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
@@ -35,7 +42,18 @@ Under `--auto` with **`--depth standard`** (default), SKIP only when target sect
 findings: Background, Requirements, Acceptance Criteria, Design, Plan. Solution is not a refine
 target. Under **`--depth ready`**, do **not** SKIP on L3-clean alone — run the implement-ready
 checklist (dev-operations § refine) and rewrite Design/Requirements/Plan until another agent can
-implement without inventing design. Stage floor: the `planner` role per
+implement without inventing design:
+
+1. Audit every existing claim against the current tree: facts, cited sources, fix soundness across
+   all callers, test observability, environment, concurrent work, and scope.
+2. Correct what is wrong and record each change in a dated `**Refine corrections (<date>)**` block
+   in Background.
+3. Run `spur task check <wbs> --as todo --json`, fill unset priority/estimate, and promote
+   `backlog → todo`.
+4. Report checklist rows `{id, pass, evidence}`.
+
+Refine targets `backlog`/`todo` tasks; a `wip`-or-later task needs explicit operator consent and is
+never demoted. Stage floor: the `planner` role per
 [`roles.md`](../references/roles.md) — this command names roles, never tiers (0538 R4);
 ready synthesis may use a higher tier when the task spans packages/seams.
 

package/plugins/sp/commands/dev-refineall.md

@@ -1,5 +1,5 @@
 ---
-description: Refine a batch of tasks via structured Q&A — resolve a set (feature or selector), refine each in dependency-correct order, emit a batch report; optional implement-ready depth
+description: Refine a batch of tasks via structured Q&A — resolve a set (feature or selector), refine each in dependency-correct order, emit a batch report; --depth ready audits, corrects and promotes each task
 role: planner
 argument-hint: "--feature <id> | --tasks <selector> [--focus <mode>] [--description <text>] [--depth <standard|ready>] [--agent <inline|auto|name>] [--auto] [--keep-going] [--status <s>] [--json] [--worktree [<name>]]"
 allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
@@ -9,7 +9,9 @@ allowed-tools: ["Bash", "Read", "Skill", "AskUserQuestion"]
 
 Wraps the **sp:spur-dev** skill. Batch counterpart of `/sp:dev-refine` — same per-task refine
 operation, applied to a resolved set (typically every task under a feature). Pass
-`--depth ready` to force an implement-ready freeze on every task (does not L3-SKIP).
+`--depth ready` to force an implement-ready freeze on every task (does not L3-SKIP). Each task's
+existing claims are audited against the current tree and corrected, and passing tasks are promoted
+`backlog → todo`. Use it to re-audit a feature's filed or stale tasks as well as before handoff.
 
 ## Argument Flags
 
@@ -17,8 +19,8 @@ operation, applied to a resolved set (typically every task under a feature). Pas
 | --- | --- | --- |
 | `--feature` `<id>` | Refine all tasks in a feature. | required (one of `--feature` / `--tasks`) |
 | `--tasks` `<selector>` | Task selector to refine (alternative to `--feature`). | required (one of `--feature` / `--tasks`) |
-| `--focus` `<mode>` | Refinement focus mode. | omitted |
-| `--description` `<text>` | Override description for each task. | omitted |
+| `--focus` `<mode>` | Gap-analysis focus: `all\|requirements\|background\|constraints\|acceptance\|quick`. | `all` |
+| `--description` `<text>` | Operator framing injected into each task's Q&A/synthesis. | omitted |
 | `--depth` `<standard\|ready>` | Spec depth bar (see flag glossary). | `standard` |
 | `--agent` `<inline\|auto\|name>` | Who runs the model-bearing refinement. | omit |
 | `--auto` | Skip objective HITL gates. | off |
@@ -50,8 +52,9 @@ worktree copy; your main tree still shows pre-run statuses until the FF-merge on
 not a bug.
 
 **Depth:** default `standard` keeps the cheap L3 SKIP gate under `--auto`. Use
-`--depth ready` when handing a feature to another implementer (frozen Design/Requirements/Plan);
-thread `--depth` into each per-task refine.
+`--depth ready` when handing a feature to another implementer (frozen Design/Requirements/Plan),
+or when the tasks' existing content is in doubt; thread `--depth` into each per-task refine. Ready
+report rows add corrections count, status before → after, and failed checklist ids.
 
 > **`--next` dropped** (feature H8, 2026-07-31). Batch-level chaining was a token bomb — each refine
 > hop is an LLM call, and a large feature means N refine chains fanned out at once. For batch