@gobing-ai/spur 0.3.48 → 0.3.49

package/plugins/sp/scripts/validate-commands.ts

@@ -8,7 +8,8 @@
  *
  * Gates:
  *  (a) heading whitelist — H1 title + the per-contract ordered section headings
- *  (b) frontmatter schema — description, argument-hint, allowed-tools; dev-only extras
+ *  (b) frontmatter schema — description, argument-hint, allowed-tools; dev-only extras;
+ *      real-YAML re-parse so malformed blocks cannot ship an empty description
  *  (c) target resolution — sp:<skill> refs, workflow files, procedure anchors
  *  (d) allowed-tools coherence — Skill present iff body contains Skill() call
  *  (e) dev-command argument contract — syntax-only hint, Argument Flags table columns,
@@ -19,6 +20,7 @@
 
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
+import { parse as parseYaml } from 'yaml';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -53,6 +55,8 @@ interface ParsedCommand {
     readonly description: string | undefined;
     readonly argumentHint: string | undefined;
     readonly allowedTools: string[] | undefined;
+    /** Set when the frontmatter fails a real YAML parse or yields an empty description. */
+    readonly frontmatterYamlProblem: string | undefined;
     readonly body: string;
 }
 
@@ -68,6 +72,30 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
     const argumentHint = extractYamlField(fm, 'argument-hint');
     const allowedTools = extractYamlList(fm, 'allowed-tools');
 
+    // The regex extractions above feed the per-field gates, but they cannot see
+    // malformed YAML: `description: >-` followed by unindented keys reads as a
+    // present description to the regex while a real YAML parser folds the next
+    // keys into the block scalar — the bug that shipped an empty description to
+    // superskill install for dev-feature-change. Gate (b) re-checks with a real
+    // parse so that class cannot regress.
+    let frontmatterYamlProblem: string | undefined;
+    if (fm.trim() !== '') {
+        try {
+            const parsed: unknown = parseYaml(fm);
+            if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                frontmatterYamlProblem = 'frontmatter is not a YAML mapping';
+            } else {
+                const parsedDescription = (parsed as Record<string, unknown>).description;
+                if (typeof parsedDescription !== 'string' || parsedDescription.trim() === '') {
+                    frontmatterYamlProblem = 'frontmatter description is empty after YAML parsing';
+                }
+            }
+        } catch (error) {
+            const detail = error instanceof Error ? error.message.split('\n')[0] : String(error);
+            frontmatterYamlProblem = `frontmatter is not valid YAML: ${detail}`;
+        }
+    }
+
     const lines = body.split('\n');
     const title = lines[0]?.startsWith('# ') ? lines[0].slice(2).trim() : '';
 
@@ -90,7 +118,7 @@ function parseCommand(filePath: string, name: string): ParsedCommand {
         }
     }
 
-    return { name, title, headings, description, argumentHint, allowedTools, body };
+    return { name, title, headings, description, argumentHint, allowedTools, frontmatterYamlProblem, body };
 }
 
 /** Extract a plain YAML string field (handles quoted and unquoted). */
@@ -212,6 +240,9 @@ function checkHeadingWhitelist(cmd: ParsedCommand): readonly Violation[] {
 
 function checkFrontmatterSchema(cmd: ParsedCommand): readonly Violation[] {
     const violations: Violation[] = [];
+    if (cmd.frontmatterYamlProblem) {
+        violations.push({ command: cmd.name, gate: 'b', message: cmd.frontmatterYamlProblem });
+    }
     if (!cmd.description) {
         violations.push({ command: cmd.name, gate: 'b', message: 'missing frontmatter description' });
     }

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

@@ -89,6 +89,14 @@ only burns wall clock and context budget.
   `bun test <file> --test-name-pattern "<test>"`, or `bunx tsc --noEmit` on a single package.
 - **NEVER run** `bun run test`, `bun run spur-check`, `bun run check`, or any other full-suite /
   project-gate command from inside implement. These belong to the pipeline's `test` hop.
+- **Full-suite budget: at most 2 per task** (task 0436 R2) — counted across the whole task run
+  (implement probes + the pipeline `test` hop + verify/recheck), not per step. When a check fails,
+  run the narrow target (`bun test <file> --test-name-pattern <test>`) to green before any full
+  suite; reach for the second full run only when the narrow target cannot reproduce the failure.
+- **Consolidate dogfood runs**: one combined real-data execution that exercises all scenarios,
+  not N near-identical `--dry-run`/real invocations of the same script. If you find yourself
+  rerunning the same dogfood command with one flag changed, stop and fold the variants into a
+  single run — repeated identical commands are loop-detector findings and pure cost.
 - If a targeted probe reveals a failure you cannot fix within implement scope, note it in
   `## Solution` and let the `test` hop's fixall handle it — do not pre-empt the gate.
 
@@ -146,7 +154,7 @@ reproduce → isolate → minimal fix → regression guard.
 ## Common Rationalizations
 
 | Rationalization | Reality |
-|---|---|
+| --- | --- |
 | "The spec is clear — I don't need to read the callers." | Code that looks orthogonal is how regressions ship (R5). Read the exports you touch and their immediate callers before writing. |
 | "I'll add the tests in a follow-up." | Untested production code is unverified code. The task's test step is not optional; behavior ships with its test. |
 | "This abstraction will be useful later." | Speculative abstraction is complexity without a caller (R2). Build for the requirement in front of you; add the seam when the second use arrives. |

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

@@ -239,6 +239,11 @@ printf '...' > /tmp/<wbs>-testing.md
 spur task update <wbs> --section Testing --from-file /tmp/<wbs>-testing.md
 ```
 
+> **Corrections: the answer file is the source of truth.** `spur task record` re-transcribes
+> `## Testing` from the verdict artifact, overwriting `--section Testing` writes — direct section
+> fixes are futile. Fix `.spur/run/<wbs>-verify-answer.txt` → `spur task verdict <wbs>
+> --from-answer <file>` → re-record. `--section` is initial authorship only.
+
 > **Do not write `## Review` directly in verify mode.** The `## Review` section is owned by the
 > `review` step (`/sp:dev-review`), which dispatches `functional-review` + `code-verification`
 > review mode + `code-improvement`. The `record` step backfills `## Review` from the verdict
@@ -283,9 +288,7 @@ Verdict: PASS
 | P4 | — | — | No P1–P3 findings; verify verdict PASS |
 ```
 
-The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant, and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
-
-**MUST NOT:** use `| R# | ... |` as the sole id header without `Status` in column 2.
+The per-requirement traceability table MUST use `| Req | Status | Evidence |` (exactly this header, no `R#`/`R`/`Requirement` variant — `Status` in column 2 — and no extra columns between Req and Status). The Acceptance Criteria table MUST use `| AC | Status | Evidence Type | Evidence |`.
 **MUST NOT:** place a `Severity` column between `Req` and `Status` in the authoring contract.
 The parser is tolerant of these variants (defense-in-depth), but the authoring contract is
 canonical.
@@ -348,8 +351,7 @@ mutation is discoverable from the tracked task file alone, without diffing untra
 ### Step 13 — Shippable readiness gate (feature-level)
 
 Per-task PASS is **not** the same as “this feature is ready to ship.” After Steps 11–12, when the
-gate is **active**, evaluate feature AC satisfaction via the existing CLI (do not invent a second
-framework).
+gate is **active**, evaluate feature AC satisfaction via the existing CLI.
 
 **When active**
 
@@ -371,16 +373,17 @@ framework).
    `docs/.spur/run` or other nested `.spur` trees). Ephemeral scratch may use `/tmp` or
    `/private/tmp`. Requirement / AC row `id`s in the verdict MUST match feature scenario titles
    (or `AC-N` aliases) so satisfaction can mark MET.
-2. Run:
+2. Run (0568 R6 monorepo-safe: SPUR_BIN env > local CLI > PATH):
 
    ```bash
-   spur feature check <featureId> --json
-   spur task list --feature <featureId> --json
+   SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+   $SPUR_BIN feature check <featureId> --json
+   $SPUR_BIN task list --feature <featureId> --json
    ```
 
 3. Classify **Shippable: PASS** only if **all** of:
    - No finding whose code/message indicates **linked but unverified** scenarios
-     (`L4_SCENARIO_UNVERIFIED` / “linked but unverified”).
+     (`L4_SCENARIO_UNVERIFIED`).
    - No **orphan / uncovered** feature scenarios (`L4_ORPHAN_SCENARIOS`,
      `L4_UNCOVERED_FEATURE_SCENARIO` / no covering task).
    - No **incomplete** linked tasks: every task with this `feature_id` is `done` or `cancelled`
@@ -424,16 +427,14 @@ Full flag matrix and ops notes: [spur-dev/references/dev-operations.md](../spur-
 
 ### Step 14 — Report
 
-Show the per-task verdict, the per-requirement table, the gate outcome (cleared / blocked), and the
-**Shippable:** line from Step 13 when applicable. Under the pipeline the task verdict is consumed by
-the done-gate; for a direct `/sp:dev-verify` invocation the full report is the operator's summary.
+Show the per-task verdict, per-requirement table, gate outcome (cleared/blocked), and the
+**Shippable:** line from Step 13 when applicable. Under the pipeline the done-gate consumes the
+verdict; for a direct `/sp:dev-verify` invocation the full report is the operator's summary.
 
-**`--next` on an already-terminal task (no-op surfacing).** When `--next` is invoked on a task
-already at `done` or `cancelled`, the transition cannot fire. The verify report line MUST state the
-no-op itself (e.g. `--next: no-op - task already terminal (<status>)`) rather than relying solely
-on the CLI print (documented in `dev-verify.md`'s `--next` chain section). The CLI print is the
-machine signal; the report line is the operator-visible summary - both must agree so a terminal-task
-re-audit cannot be misread as a successful `testing -> done` transition.
+**`--next` on a terminal task (no-op surfacing).** The transition cannot fire; the verify report
+line MUST state the no-op itself (e.g. `--next: no-op - task already terminal (<status>)`). The CLI
+print is the machine signal, the report line the operator summary — both must agree so a terminal
+re-audit is never misread as a successful `testing -> done` (dev-verify.md `--next` chain).
 
 ---
 
@@ -513,14 +514,12 @@ Do **not** use this skill for:
 - **`sp:spur-dev`** — the execution-half umbrella that drives the pipeline this skill gates.
 - [references/code-improvement.md](references/code-improvement.md) — architecture-improvement lens
   for module depth, seam placement, locality, coupling, and testability.
-- **`sp:functional-review`** — a peer review skill for requirements traceability (R{n} → file:line
-  evidence, per-requirement MET/PARTIAL/UNMET, `FunctionalVerdict`). When the `review` dimension
-  needs functional traceability (not just SECUA), dispatch this skill; see
-  [../functional-review/SKILL.md](../functional-review/SKILL.md).
-- **`sp:code-improvement`** — a peer review skill for architectural deepening (5 signals: shallow
-  module, tight coupling, wrong seam, weak locality, poor test surface; severity
-  blocker/major/minor/advisory). When review findings expose structural friction rather than a
-  localized defect, dispatch this skill; see [../code-improvement/SKILL.md](../code-improvement/SKILL.md).
+- **`sp:functional-review`** — requirements-traceability peer review (R{n} → file:line,
+  per-requirement MET/PARTIAL/UNMET). Dispatch when the `review` dimension needs functional
+  traceability, not just SECUA: [../functional-review/SKILL.md](../functional-review/SKILL.md).
+- **`sp:code-improvement`** — architectural-deepening peer review (5 signals, severity
+  blocker/major/minor/advisory). Dispatch for structural friction rather than localized
+  defects: [../code-improvement/SKILL.md](../code-improvement/SKILL.md).
 
 ---
 
@@ -533,5 +532,5 @@ directly: `Skill(skill="sp:code-verification", args="verify <wbs> --fix all")`.
 
 ### Codex / OpenClaw / OpenCode / Antigravity
 
-Run `spur` CLI via Bash; parse `--json`. Invoke this skill directly for the verification logic — the
-skill is the SSOT; the commands are thin wrappers.
+Run `spur` CLI via Bash; parse `--json`. Invoke the skill directly — the skill is the SSOT; the
+commands are thin wrappers.

package/plugins/sp/skills/issue-finding/SKILL.md

@@ -139,11 +139,12 @@ sessions (typed ETL via `spur history` — or raw JSONL under the three fallback
 **Primary path (typed sources):** `spur history report --mode forensics` (task 0555).
 
 ```bash
-spur history import --source <source> --json   # checkpoint resume makes re-runs cheap
-spur history analyze --json                    # writes the versioned artifact; derived
-                                               # variables are computed here (task 0554)
-spur history report --mode forensics           # pure renderer of the artifact; never opens
-                                               # the database; defaults to the latest pointer
+# 0568 R4: SPUR_BIN env > local CLI > PATH — stale PATH spur fails history import.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+
+$SPUR_BIN history import --source <source> --json   # checkpoint resume
+$SPUR_BIN history analyze --json                    # writes versioned artifact (0554)
+$SPUR_BIN history report --mode forensics           # pure renderer; latest artifact pointer
 ```
 
 The forensics renderer emits **8 CLI-derivable sections**: Session Data Summary, Tool Breakdown,

package/plugins/sp/skills/issue-finding/references/session-formats.md

@@ -84,8 +84,10 @@ each file, the session key is the JSONL filename stem (importer `sessionIdFromCo
 analyze per key:
 
 ```bash
-spur history import --source omp --file <absolute-file> --mode force-file --json
-spur history analyze --session <filename-stem> --json
+# Monorepo-safe spur resolution (0568 R6): SPUR_BIN env > monorepo-local CLI > PATH.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+$SPUR_BIN history import --source omp --file <absolute-file> --mode force-file --json
+$SPUR_BIN history analyze --session <filename-stem> --json
 ```
 
 ETL owns token/cost/message/tool/loop/assistant-duration aggregates; raw JSONL stays authoritative

package/plugins/sp/skills/next-feature/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: next-feature
-description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' by deriving importance/urgency from corpus, git, and authority-doc evidence, and emits rank-distorting tree defects as proposals /sp:dev-featurechange consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
+description: "Prompt-first feature frontier prioritizer — answers 'which feature should we work on now?' by deriving importance/urgency from corpus, git, and authority-doc evidence, and emits rank-distorting tree defects as proposals /sp:dev-feature-change consumes. Triggers: find next, which feature, feature ranking, frontier priority, what should I work on."
 license: Apache-2.0
 version: 1.0.0
 metadata:
@@ -30,7 +30,7 @@ A prompt-first prioritizer that answers **"which feature should we work on now?"
 `sp:next-router` deliberately does not answer (`routing-table.md` §0 step 1c: target omitted → not
 v1). It derives importance and urgency from evidence already in the corpus, ranks the actionable
 frontier in **tiers with per-candidate evidence**, and emits rank-distorting tree defects as
-**proposals** `/sp:dev-featurechange` consumes.
+**proposals** `/sp:dev-feature-change` consumes.
 
 **Honesty contract:** prompt-first. The model applies the rubric; existing deterministic tools
 (`spur feature|task … --json`, `git`, `rg`) gather facts. No TypeScript analyzer, no numeric scores,
@@ -39,7 +39,7 @@ in this corpus it is 76% one value (0493 measurement).
 
 **Propose, never apply.** This skill performs no `spur feature move` and writes nothing under
 `docs/features/**`. The only path from a structure proposal to a changed tree is
-`/sp:dev-featurechange` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
+`/sp:dev-feature-change` (dry-run → confirm → apply). Ranking runs are read-only; the sole exception is
 `--task`, which after an **operator confirm** (interactive, or auto-accepted under `--auto`)
 dispatches `/sp:dev-plan` and `/sp:dev-refineall` — commands that write `docs/tasks*/` through their
 own gates. This skill still creates no tasks itself.
@@ -52,7 +52,7 @@ own gates. This skill still creates no tasks itself.
 **Do NOT use for:**
 
 - Advancing an already-chosen task or feature — that is `/sp:dev-next` (`sp:next-router`).
-- Applying tree changes — that is `/sp:dev-featurechange` (feature F31).
+- Applying tree changes — that is `/sp:dev-feature-change` (feature F31).
 - Task-level ordering inside a feature — next-router's TABLE A owns that.
 
 ## Protocol
@@ -106,7 +106,7 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
 - Ranking a feature whose actionability gate fails. Gate first, rank second.
 - Emitting a numeric score (WSJF/RICE arithmetic) from absent value/effort estimates.
 - Copying the B3 predicate into this skill. Cite it; read it at runtime.
-- Any `spur feature move`, or writing proposals anywhere `docs/features/**` — featurechange owns apply.
+- Any `spur feature move`, or writing proposals anywhere `docs/features/**` — feature-change owns apply.
 - Decomposing a feature here, or calling `spur task create` / `spur task batch-create` under `--task`.
   Dispatch `/sp:dev-plan`; it owns decomposition and the batch-create schema gate. Equally:
   dispatching under `--auto` without `--task` (there is no confirm to skip), auto-accepting a target
@@ -123,7 +123,7 @@ Run the steps in order. Each step's depth lives in its reference; this file is t
 | [references/signal-derivation.md](references/signal-derivation.md) | Sync precondition, B3 runtime citation, per-signal derivation commands, degenerate-spread rejection |
 | [references/ranking-rubric.md](references/ranking-rubric.md) | Tier definitions, tie-breaks, evidence-per-candidate output contract |
 | [references/proposal-contract.md](references/proposal-contract.md) | D1–D4 defect set, evidence bar, mapping-schema conformance, silence |
-| [references/handoff-routing.md](references/handoff-routing.md) | featurechange handoff, next-router seam, the `--task` tier→hop routing table and its confirm contract |
+| [references/handoff-routing.md](references/handoff-routing.md) | feature-change handoff, next-router seam, the `--task` tier→hop routing table and its confirm contract |
 
 Grounding: tickets 0493 (measured signals), 0494 (reuse ledger), 0495 (defect contract) under
 feature H12.

package/plugins/sp/skills/next-feature/references/handoff-routing.md

@@ -1,4 +1,4 @@
-# Handoff routing — featurechange handoff, next-router seam, conditional dispatch
+# Handoff routing — feature-change handoff, next-router seam, conditional dispatch
 
 ## The seam with `/sp:dev-next` (next-router)
 
@@ -8,7 +8,7 @@
 - When the operator picks a winner from the ranked report, the printed handoff line is:
   `/sp:dev-next <feature-id>`.
 
-## The handoff to `/sp:dev-featurechange` (feature F31)
+## The handoff to `/sp:dev-feature-change` (feature F31)
 
 Defect proposals follow the 0495 Artifact C boundary, traced end to end:
 
@@ -16,9 +16,9 @@ Defect proposals follow the 0495 Artifact C boundary, traced end to end:
 | --- | --- | --- |
 | 1. Detect + emit proposal rows | this skill | No |
 | 2. Handoff | printed inline in the report (report reading of OQ1) | No |
-| 3. `--dry-run` | `/sp:dev-featurechange` | No |
+| 3. `--dry-run` | `/sp:dev-feature-change` | No |
 | 4. Confirm | operator | — |
-| 5. `--apply` (`spur feature move`) | `/sp:dev-featurechange` only | **Yes — sole writer** |
+| 5. `--apply` (`spur feature move`) | `/sp:dev-feature-change` only | **Yes — sole writer** |
 
 There is no path from this skill to a mutated tree that bypasses step 4. Proposal rows are printed
 inline in the default report; writing them into `docs/plans/feature-tree-restructure-map.md` as new
@@ -83,7 +83,7 @@ inside dispatched children remain governed by their own contracts (`--approve-ta
 ### What `--task` does not change
 
 The defect half is untouched: still no `spur feature move`, still nothing written under
-`docs/features/**`, still `/sp:dev-featurechange` as the sole applier of structure proposals. `--task`
+`docs/features/**`, still `/sp:dev-feature-change` as the sole applier of structure proposals. `--task`
 adds one gated path to `docs/tasks*/`, through commands that own their own gates.
 
 ## Where outputs go

package/plugins/sp/skills/next-feature/references/signal-derivation.md

@@ -7,7 +7,10 @@ cannot be derived is reported as **unavailable**, never fabricated.
 ## §0 — Sync-first precondition (step zero)
 
 ```bash
-spur feature sync --all --dry-run --json
+# Monorepo-safe spur resolution (0568 R6): SPUR_BIN env > monorepo-local CLI > PATH.
+# Defined once here; §1+ reuse $SPUR_BIN — §0 runs first by construction.
+SPUR_BIN="${SPUR_BIN:-$([ -f apps/cli/src/index.ts ] && echo 'bun apps/cli/src/index.ts' || echo spur)}"
+$SPUR_BIN feature sync --all --dry-run --json
 ```
 
 Feature `status` is manual bookkeeping and drifts (0493: 24 of 25 rankable features would change
@@ -34,7 +37,7 @@ renamed, the fallback key is its content: "frontier = open ∧ unblocked".)
 Inputs per candidate feature:
 
 ```bash
-spur task list --feature <id> --json
+$SPUR_BIN task list --feature <id> --json
 ```
 
 `task list --feature` is **active-folder-only**: it enumerates tasks in the active task folder
@@ -52,9 +55,11 @@ is not authoritative — a frontier task may be archived outside it. Run the fal
    the feature's row as an **anomaly hint** only: it may flag the feature without naming a WBS. The
    sync reason is never treated as a WBS source — no WBS is ever inferred from sync prose.
 2. Scan the whole corpus for linked tasks:
+
    ```bash
    rg -l '^feature_id: "?<id>"?$' docs/tasks*/
    ```
+
    Corpus ids are `[A-Z][0-9]+`-shaped, so `<id>` is regex-safe as-is; escape metacharacters if a
    non-conforming id ever appears.
 3. Parse the leading WBS from each matched basename; resolve every corpus-only WBS (not present in