@gobing-ai/spur 0.3.85 → 0.3.87

package/plugins/sp/plugin.json

@@ -1,6 +1,6 @@
 {
     "name": "sp",
-    "version": "0.3.85",
+    "version": "0.3.87",
     "description": "Spur — a local-first harness engineering toolkit that wraps mainstream coding agents with constraint checking, workflow orchestration, and history analytics.",
     "extensions": {
         "pi": ["./hooks/pi/guard-extension.ts"]

package/plugins/sp/references/roles.md

@@ -58,7 +58,7 @@ roles:
     stages: [implement, test, wrap]
   - id: reviewer
     tier: capable-1
-    commands: [dev-verify, dev-verifyall, dev-review, dev-review-session, dev-pr-review, dev-dogfood, rule-scan, dev-find-conflict, dev-find-issue]
+    commands: [dev-verify, dev-verifyall, dev-review, dev-review-session, dev-pr-review, dev-dogfood, dev-refactor, rule-scan, dev-find-conflict, dev-find-issue]
     stages: [verify, review, dogfood]
   - id: planner
     tier: capable-2

package/plugins/sp/scripts/daily-summary/daily-summary.mjs

@@ -8,6 +8,15 @@ import { spawn, spawnSync } from "child_process";
 import { existsSync, mkdirSync, readlinkSync, writeFileSync } from "fs";
 import { dirname, isAbsolute, join, resolve } from "path";
 
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+function getEnvVars() {
+  return process.env;
+}
+
 // plugins/sp/scripts/daily-summary/logger.ts
 var state = { console: true, file: false };
 function emit(stream, message) {
@@ -103,7 +112,7 @@ var defaultProcessSpawner = (cmd, args, env) => {
     try {
       const proc = spawn(cmd, args, {
         stdio: ["ignore", "pipe", "pipe"],
-        env: env ?? process.env
+        env: env ?? getEnvVars()
       });
       const stdoutChunks = [];
       const stderrChunks = [];
@@ -130,7 +139,7 @@ function setProcessSpawner(next) {
 }
 async function getCcusageData(date) {
   try {
-    const env = { ...process.env };
+    const env = { ...getEnvVars() };
     const ccusageCheck = await processSpawner("ccusage", ["--version"], env);
     if (ccusageCheck.exitCode !== 0) {
       return null;
@@ -279,10 +288,10 @@ async function getGitCommits(date) {
   }
 }
 async function promptUser() {
-  if (process.env.SP_DAILY_SUMMARY_NO_PROMPT === "1") {
+  if (getEnvVar("SP_DAILY_SUMMARY_NO_PROMPT") === "1") {
     return { learnings: "", issuesFixed: "", pending: "" };
   }
-  if (process.env.RD3_DAILY_SUMMARY_NO_PROMPT === "1") {
+  if (getEnvVar("RD3_DAILY_SUMMARY_NO_PROMPT") === "1") {
     logger.warn("[deprecate] RD3_DAILY_SUMMARY_NO_PROMPT is deprecated; use SP_DAILY_SUMMARY_NO_PROMPT");
     return { learnings: "", issuesFixed: "", pending: "" };
   }

package/plugins/sp/scripts/daily-summary/daily-summary.ts

@@ -11,6 +11,8 @@
 import { spawn, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readlinkSync, writeFileSync } from 'node:fs';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { getEnvVar, getEnvVars } from '@gobing-ai/ts-utils';
+
 import { logger } from './logger';
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -225,7 +227,7 @@ export const defaultProcessSpawner: ProcessSpawner = (cmd, args, env) => {
         try {
             const proc = spawn(cmd, args, {
                 stdio: ['ignore', 'pipe', 'pipe'],
-                env: env ?? process.env,
+                env: env ?? getEnvVars(),
             });
             const stdoutChunks: Buffer[] = [];
             const stderrChunks: Buffer[] = [];
@@ -258,7 +260,7 @@ export function setProcessSpawner(next?: ProcessSpawner): void {
 export async function getCcusageData(date: string): Promise<CcusageData | null> {
     try {
         // Check if ccusage is available
-        const env = { ...process.env };
+        const env = { ...getEnvVars() };
         const ccusageCheck = await processSpawner('ccusage', ['--version'], env);
         if (ccusageCheck.exitCode !== 0) {
             return null;
@@ -473,10 +475,10 @@ export async function getGitCommits(date: string): Promise<GitCommit[]> {
 // ─── User Input ─────────────────────────────────────────────────────────────
 
 export async function promptUser(): Promise<UserAnnotations> {
-    if (process.env.SP_DAILY_SUMMARY_NO_PROMPT === '1') {
+    if (getEnvVar('SP_DAILY_SUMMARY_NO_PROMPT') === '1') {
         return { learnings: '', issuesFixed: '', pending: '' };
     }
-    if (process.env.RD3_DAILY_SUMMARY_NO_PROMPT === '1') {
+    if (getEnvVar('RD3_DAILY_SUMMARY_NO_PROMPT') === '1') {
         logger.warn('[deprecate] RD3_DAILY_SUMMARY_NO_PROMPT is deprecated; use SP_DAILY_SUMMARY_NO_PROMPT');
         return { learnings: '', issuesFixed: '', pending: '' };
     }

package/plugins/sp/scripts/feature-sync-bounded.mjs

@@ -8,6 +8,14 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVar(name, fallback) {
+  const raw = process.env[name];
+  return raw === undefined ? fallback : raw;
+}
+
+// plugins/sp/scripts/feature-sync-bounded.ts
 function classifySyncResult(result) {
   if (result.proposal.gateBlocked === true)
     return "blocked";
@@ -95,8 +103,8 @@ through unchanged.
 
 Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
 function defaultSpurBin() {
-  if (process.env.SPUR_BIN)
-    return process.env.SPUR_BIN;
+  if (getEnvVar("SPUR_BIN"))
+    return getEnvVar("SPUR_BIN");
   const local = fileURLToPath(new URL("../../../apps/cli/src/index.ts", import.meta.url));
   if (existsSync(local))
     return `bun ${local}`;

package/plugins/sp/scripts/feature-sync-bounded.ts

@@ -24,6 +24,7 @@ import { createHash } from 'node:crypto';
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ── Local types (match packages/app FeatureService shapes; no package import) ───────────
 
@@ -250,7 +251,7 @@ Exit: 0 = sync handled (applied / no-op / suppressed-blocked / live-blocked).`;
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 export function defaultSpurBin(): string {
-    if (process.env.SPUR_BIN) return process.env.SPUR_BIN;
+    if (getEnvVar('SPUR_BIN')) return getEnvVar('SPUR_BIN');
     // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw pathname breaks
     // on %-encoded paths, e.g. spaces in the checkout directory)
     const local = fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url));

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

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

package/plugins/sp/scripts/idea-handoff.mjs

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 // @bun
 
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
 // plugins/sp/scripts/idea-handoff.ts
 var libUrl = new URL("../lib/idea-handoff.generated.mjs", import.meta.url).href;
 async function loadHandoffLib() {
   return await import(libUrl);
 }
 var IDEA_HANDOFF_USAGE = "usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) \u2014 no subcommands";
-async function main(argv, env = process.env) {
+async function main(argv, env = getEnvVars()) {
   if (argv.length > 0) {
     process.stderr.write(`${IDEA_HANDOFF_USAGE}
 `);

package/plugins/sp/scripts/idea-handoff.ts

@@ -1,4 +1,7 @@
 #!/usr/bin/env bun
+
+import { getEnvVars } from '@gobing-ai/ts-utils';
+
 /**
  * idea-handoff — portable entrypoint for the idea-pipeline finalization (task 0824, feature I21).
  *
@@ -29,7 +32,7 @@ export async function loadHandoffLib(): Promise<typeof import('../lib/idea-hando
 export const IDEA_HANDOFF_USAGE =
     'usage: idea-handoff.ts  (env: __runId, featureId, optional spurBin) — no subcommands';
 
-export async function main(argv: string[], env: NodeJS.ProcessEnv = process.env): Promise<number> {
+export async function main(argv: string[], env: NodeJS.ProcessEnv = getEnvVars()): Promise<number> {
     if (argv.length > 0) {
         process.stderr.write(`${IDEA_HANDOFF_USAGE}\n`);
         return 2;

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

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