@gobing-ai/spur 0.3.85 → 0.3.87

package/plugins/sp/README.md

@@ -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)
 
@@ -620,14 +623,11 @@ pipeline owns one lifecycle phase:
 
 | Workflow                    | Phase                             | Entry command                     |
 | --------------------------- | --------------------------------- | --------------------------------- |
-| `basic.yaml`                | Generic implement/check/fix       | direct `spur workflow run`        |
 | `feature-lifecycle.yaml`    | Feature status FSM                | `spur feature update`             |
 | `task-lifecycle.yaml`       | Task status FSM                   | `spur task update`                |
 | `task-pipeline.yaml`        | Single-task execution             | `/sp:dev-run`                     |
 | `idea-pipeline.yaml`        | Idea/planning → feature + tasks   | `/sp:dev-idea`, `/sp:dev-plan`    |
-| `feature-dev.yaml`          | Feature umbrella execution        | `/sp:dev-runall --feature`        |
 | `wrapup-pipeline.yaml`      | Post-execution wrap-up            | `/sp:dev-wrap`, `/sp:dev-wrapall` |
-| `docs-pipeline.yaml`        | Docs-only task execution          | `/sp:dev-run --mode implement`    |
 | `wayfinder-resolution.yaml` | Wayfinder ticket resolution loop  | `spur workflow run` (free-form)   |
 
 ### Lifecycle operations

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/hooks/agent-hint.ts

@@ -1,3 +1,4 @@
+import { getEnvVars } from '@gobing-ai/ts-utils';
 /**
  * Shared host-agent identification helpers — the **only** host-agent detection path
  * in the sp plugin hooks.
@@ -22,11 +23,11 @@
  * 3. `TERM_PROGRAM` — terminal identifier (e.g. `claude`, `ghostty`)
  * 4. `SPUR_DEFAULT_AGENT` — configured default agent
  *
- * @param env - environment record (defaults to `process.env`)
+ * @param env - environment record (defaults to `getEnvVars()`)
  * @param fallback - value returned when no candidate matches (defaults to `undefined`)
  */
 export function resolveAgentHint(
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     fallback: string | undefined = undefined,
 ): string | undefined {
     const candidates = [env.SPUR_AGENT, env.CLAUDE_CODE_ENTRYPOINT, env.TERM_PROGRAM, env.SPUR_DEFAULT_AGENT];
@@ -45,11 +46,11 @@ export function resolveAgentHint(
  * 3. `OPENAI_MODEL` — OpenAI API model
  * 4. `CLAUDE_MODEL` — Claude Code model setting
  *
- * @param env - environment record (defaults to `process.env`)
+ * @param env - environment record (defaults to `getEnvVars()`)
  * @param fallback - value returned when no candidate matches (defaults to `undefined`)
  */
 export function resolveModelHint(
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     fallback: string | undefined = undefined,
 ): string | undefined {
     const candidates = [env.SPUR_MODEL, env.ANTHROPIC_MODEL, env.OPENAI_MODEL, env.CLAUDE_MODEL];

package/plugins/sp/hooks/careful-guard.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env bun
+
 /**
  * careful-guard — PreToolUse guard for destructive shell commands (task 0215, R3).
  *
@@ -21,6 +22,7 @@
  * adapter. This file owns the Claude Code payload/decision shape only.
  */
 
+import { getEnvVar } from '@gobing-ai/ts-utils';
 import { classifyCommand } from './destructive-policy';
 
 interface ToolPayload {
@@ -43,7 +45,7 @@ function preToolUseDecision(decision: Decision, reason?: string): never {
 }
 
 async function main(): Promise<void> {
-    if (process.env.SPUR_CAREFUL === 'off') preToolUseDecision('allow');
+    if (getEnvVar('SPUR_CAREFUL') === 'off') preToolUseDecision('allow');
 
     const stdinText = await Bun.stdin.text();
     let payload: ToolPayload;

package/plugins/sp/hooks/context-post-tool.ts

@@ -23,6 +23,7 @@
 import { execSync } from 'node:child_process';
 import { appendFileSync, existsSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Tools recorded by this hook (must match hooks.json PostToolUse matcher). */
 export const ALLOWED_TOOLS = new Set(['Bash', 'Grep', 'Glob', 'Read', 'Write', 'Edit']);
@@ -411,7 +412,7 @@ export function readContextFreshness(contextDir: string): string | null {
 // Entrypoint — thin wrapper; logic lives in {@link recordToolUseEvent} for unit coverage.
 if (import.meta.main) {
     void (async () => {
-        const dir = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context');
+        const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
         try {
             const stdinText = await Bun.stdin.text();
             const payload = JSON.parse(stdinText) as ToolPayload;

package/plugins/sp/hooks/context-session-start.ts

@@ -15,6 +15,7 @@
 import { execSync } from 'node:child_process';
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
 import { resolveAgentHint, resolveModelHint } from './agent-hint';
 import { checkContextFreshness } from './context-post-tool';
 
@@ -82,7 +83,7 @@ interface SessionFileBody {
  * a stale file is only reachable from inside a live agent run, where reusing it is the correct
  * answer anyway.
  */
-export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = process.env): string | null {
+export function resolveActiveSession(dir: string, now: Date, env: NodeJS.ProcessEnv = getEnvVars()): string | null {
     let raw: string;
     try {
         raw = readFileSync(join(dir, '.session.json'), 'utf-8');
@@ -123,7 +124,7 @@ export function resolveActiveSession(dir: string, now: Date, env: NodeJS.Process
  */
 export function recordSessionStart(
     dir: string,
-    env: NodeJS.ProcessEnv = process.env,
+    env: NodeJS.ProcessEnv = getEnvVars(),
     now: () => Date = () => new Date(),
 ): string | null {
     try {
@@ -195,7 +196,7 @@ export function recordSessionStart(
 // Entrypoint — kept minimal so unit coverage focuses on pure helpers above.
 if (import.meta.main) {
     try {
-        recordSessionStart(join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context'));
+        recordSessionStart(join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context'));
     } catch {
         /* fail-open */
     }

package/plugins/sp/hooks/context-session-stop.ts

@@ -17,6 +17,7 @@
 
 import { appendFileSync, existsSync, readFileSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 interface LedgerEvent {
     session: string;
@@ -53,7 +54,7 @@ function exitOk(): never {
 }
 
 async function main(): Promise<void> {
-    const dir = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), '.spur', 'context');
+    const dir = join(getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd(), '.spur', 'context');
 
     const sessionFile = join(dir, '.session.json');
     if (!existsSync(sessionFile)) exitOk();

package/plugins/sp/hooks/pi/guard-extension.ts

@@ -23,6 +23,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync, realpathSync, rmSy
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
 import { resolveAgentHint as resolveAgentHintShared, resolveModelHint as resolveModelHintShared } from '../agent-hint';
 import { classifyCommand } from '../destructive-policy';
 import { couldBeTaskFile } from '../task-file-policy';
@@ -81,7 +82,7 @@ function resolveSpurTaskOwnership(filePath: string): TaskOwnership {
         spawnSync(cmd, args, { cwd: process.cwd(), encoding: 'utf-8', timeout: 8000 });
 
     // 1. SPUR_BIN env override (may include args) or `spur` on PATH
-    const envBin = process.env.SPUR_BIN || 'spur';
+    const envBin = getEnvVar('SPUR_BIN') || 'spur';
     const envParts = envBin.split(' ');
     let res = run(envParts[0] ?? 'spur', [...envParts.slice(1), 'task', 'resolve', filePath, '--strict', '--json']);
     // Only 0 (owned) / 1 (unowned) are valid spur exit codes; 127 (interpreter
@@ -203,8 +204,8 @@ function initSession(): void {
         const sessionId = generateSessionId();
         const session = {
             session_id: sessionId,
-            agent: resolveAgentHintShared(process.env, 'pi'),
-            model: resolveModelHintShared(process.env),
+            agent: resolveAgentHintShared(getEnvVars(), 'pi'),
+            model: resolveModelHintShared(getEnvVars()),
             started_at: new Date().toISOString(),
         };
         writeFileSync(sessionFilePath(), `${JSON.stringify(session, null, 2)}\n`);

package/plugins/sp/hooks/task-write-guard.ts

@@ -20,6 +20,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 import { couldBeTaskFile } from './task-file-policy';
 
 interface ToolPayload {
@@ -40,7 +41,7 @@ function preToolUseDecision(decision: 'allow' | 'deny', reason?: string): never
 
 /** Resolve whether a path is owned by a Spur task via `spur task resolve --strict --json`. */
 function resolveSpurTaskOwnership(filePath: string, cwd: string): TaskOwnership {
-    const spurBin = process.env.SPUR_BIN || 'spur';
+    const spurBin = getEnvVar('SPUR_BIN') || 'spur';
     const parts = spurBin.split(' ');
     const cmd = parts[0] ?? 'spur';
     const args = [...parts.slice(1), 'task', 'resolve', filePath, '--strict', '--json'];
@@ -54,7 +55,7 @@ function resolveSpurTaskOwnership(filePath: string, cwd: string): TaskOwnership
 }
 
 async function main(): Promise<void> {
-    if (process.env.SPUR_WRITE_GUARD === 'off') preToolUseDecision('allow');
+    if (getEnvVar('SPUR_WRITE_GUARD') === 'off') preToolUseDecision('allow');
 
     const stdinText = await Bun.stdin.text();
     let payload: ToolPayload;
@@ -73,7 +74,7 @@ async function main(): Promise<void> {
     // cannot name a task file — that is every ordinary source edit.
     if (!couldBeTaskFile(filePath)) preToolUseDecision('allow');
 
-    const ownership = resolveSpurTaskOwnership(filePath, process.env.CLAUDE_PROJECT_DIR ?? process.cwd());
+    const ownership = resolveSpurTaskOwnership(filePath, getEnvVar('CLAUDE_PROJECT_DIR') ?? process.cwd());
     if (ownership === 'owned') {
         preToolUseDecision(
             'deny',