@gobing-ai/spur 0.3.53 → 0.3.55

package/plugins/sp/scripts/script-contract-check.ts

@@ -0,0 +1,319 @@
+#!/usr/bin/env bun
+/**
+ * script-contract-check — two-sided gate over plugins/sp script entrypoint contracts
+ * (task 0600, feature I, ADR-065).
+ *
+ * Enforces superskill's standard plugin script contract across plugins/sp:
+ * 1. A 'standard' entry must have a valid .mjs twin not older than its .ts source.
+ * 2. A .mjs twin on disk must be registered under a 'standard' entry (never 'repo-only' or unlisted).
+ * 3. Every script file under plugins/sp/scripts/ must have a manifest entry (two-sided).
+ * 4. No shipped surface (commands/, skills/, agents/, README.md) may reference 'bun plugins/sp/scripts/'.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/script-contract-check.ts
+ *     [--manifest <path>]     default: config/plugin-scripts.json
+ *     [--scripts-dir <path>]  default: plugins/sp/scripts
+ *     [--plugin-dir <path>]   default: plugins/sp
+ *
+ * Exit code: 0 on success, 1 on any violation.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export type ScriptContractType = 'standard' | 'repo-only';
+
+export interface ScriptManifestEntry {
+    rel: string;
+    contract: ScriptContractType;
+    twin?: string;
+}
+
+export interface ScriptManifest {
+    schema_version?: number;
+    description?: string;
+    entries: ScriptManifestEntry[];
+}
+
+export interface Violation {
+    kind:
+        | 'missing_twin'
+        | 'stale_twin'
+        | 'unexpected_twin'
+        | 'unregistered_script'
+        | 'forbidden_invocation'
+        | 'incomplete';
+    target: string;
+    message: string;
+}
+
+export function parseArgs(argv: string[]): {
+    manifest: string;
+    scriptsDir: string;
+    pluginDir: string;
+    cwd: string;
+} {
+    let manifest = 'config/plugin-scripts.json';
+    let scriptsDir = 'plugins/sp/scripts';
+    let pluginDir = 'plugins/sp';
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--manifest') manifest = argv[++i] ?? manifest;
+        else if (argv[i] === '--scripts-dir') scriptsDir = argv[++i] ?? scriptsDir;
+        else if (argv[i] === '--plugin-dir') pluginDir = argv[++i] ?? pluginDir;
+    }
+    return { manifest, scriptsDir, pluginDir, cwd: process.cwd() };
+}
+
+export function loadManifest(path: string): { manifest: ScriptManifest | null; error: string | null } {
+    if (!existsSync(path)) return { manifest: null, error: `manifest not found at ${path}` };
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw) as ScriptManifest;
+        if (!Array.isArray(parsed.entries)) {
+            return { manifest: null, error: `${path}: missing "entries" array` };
+        }
+        return { manifest: parsed, error: null };
+    } catch (err) {
+        return { manifest: null, error: `malformed JSON at ${path}: ${String(err)}` };
+    }
+}
+
+export function listDiskScripts(scriptsDir: string): { tsFiles: string[]; mjsFiles: string[] } {
+    const tsFiles: string[] = [];
+    const mjsFiles: string[] = [];
+
+    function walk(dir: string, base: string): void {
+        let entries: string[];
+        try {
+            entries = readdirSync(dir);
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            let st: ReturnType<typeof statSync>;
+            try {
+                st = statSync(fullPath);
+            } catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(fullPath, base ? `${base}/${entry}` : entry);
+            } else if (st.isFile()) {
+                const rel = base ? `${base}/${entry}` : entry;
+                if (entry.endsWith('.ts')) {
+                    tsFiles.push(rel);
+                } else if (entry.endsWith('.mjs')) {
+                    mjsFiles.push(rel);
+                }
+            }
+        }
+    }
+
+    walk(scriptsDir, '');
+    return { tsFiles: tsFiles.sort(), mjsFiles: mjsFiles.sort() };
+}
+
+export function scanShippedSurfaces(pluginDir: string): Array<{ file: string; line: number; content: string }> {
+    const matches: Array<{ file: string; line: number; content: string }> = [];
+    const forbiddenPattern = 'bun plugins/sp/scripts/';
+
+    const searchDirs = ['commands', 'skills', 'agents'];
+    const singleFiles = ['README.md'];
+
+    function scanFile(filePath: string): void {
+        if (!existsSync(filePath)) return;
+        let text: string;
+        try {
+            text = readFileSync(filePath, 'utf8');
+        } catch {
+            return;
+        }
+        const lines = text.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? '';
+            if (line.includes(forbiddenPattern)) {
+                matches.push({
+                    file: filePath,
+                    line: i + 1,
+                    content: line.trim(),
+                });
+            }
+        }
+    }
+
+    function walk(dir: string): void {
+        let entries: string[];
+        try {
+            entries = readdirSync(dir);
+        } catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            let st: ReturnType<typeof statSync>;
+            try {
+                st = statSync(fullPath);
+            } catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(fullPath);
+            } else if (
+                st.isFile() &&
+                (entry.endsWith('.md') || entry.endsWith('.json') || entry.endsWith('.yaml') || entry.endsWith('.yml'))
+            ) {
+                scanFile(fullPath);
+            }
+        }
+    }
+
+    for (const d of searchDirs) {
+        walk(join(pluginDir, d));
+    }
+    for (const f of singleFiles) {
+        scanFile(join(pluginDir, f));
+    }
+
+    return matches;
+}
+
+export function validateContract(manifest: ScriptManifest, scriptsDir: string, pluginDir: string): Violation[] {
+    const violations: Violation[] = [];
+    const { tsFiles, mjsFiles } = listDiskScripts(scriptsDir);
+
+    const manifestMap = new Map<string, ScriptManifestEntry>();
+    for (const entry of manifest.entries) {
+        if (!entry.rel || !entry.contract) {
+            violations.push({
+                kind: 'incomplete',
+                target: entry.rel ?? '<missing>',
+                message: `manifest entry missing required fields (rel, contract)`,
+            });
+            continue;
+        }
+        manifestMap.set(entry.rel, entry);
+    }
+
+    // Rule 1: standard entries must have valid .mjs twins not older than the .ts source.
+    // mtime is only meaningful when a build genuinely ran: a `git worktree add` stamps
+    // every checked-out file within the same millisecond, and the lexicographic write
+    // order (`tool.mjs` < `tool.ts`) makes the twin spuriously "older" by <1ms. Tolerate
+    // sub-second deltas so a fresh checkout is never flagged; real build staleness is
+    // seconds-to-minutes, far beyond this window (task 0606 R1 eval-worktree blocker).
+    const STALE_TWIN_TOLERANCE_MS = 1000;
+    for (const entry of manifest.entries) {
+        if (entry.rel && entry.contract === 'standard') {
+            const expectedTwinRel = entry.twin ?? entry.rel.replace(/\.ts$/, '.mjs');
+            const twinPath = join(scriptsDir, expectedTwinRel);
+            const tsPath = join(scriptsDir, entry.rel);
+
+            if (!existsSync(twinPath)) {
+                violations.push({
+                    kind: 'missing_twin',
+                    target: entry.rel,
+                    message: `standard script ${entry.rel} is missing its .mjs twin (${expectedTwinRel})`,
+                });
+            } else if (existsSync(tsPath)) {
+                const tsStat = statSync(tsPath);
+                const twinStat = statSync(twinPath);
+                if (twinStat.mtimeMs < tsStat.mtimeMs - STALE_TWIN_TOLERANCE_MS) {
+                    violations.push({
+                        kind: 'stale_twin',
+                        target: entry.rel,
+                        message: `standard script .mjs twin ${expectedTwinRel} is older than source ${entry.rel}`,
+                    });
+                }
+            }
+        }
+    }
+
+    // Rule 2: committed .mjs files must belong to a 'standard' entry
+    for (const mjsRel of mjsFiles) {
+        const correspondingTsRel = mjsRel.replace(/\.mjs$/, '.ts');
+        const entry = manifestMap.get(correspondingTsRel);
+        if (!entry) {
+            violations.push({
+                kind: 'unexpected_twin',
+                target: mjsRel,
+                message: `.mjs twin ${mjsRel} exists on disk but has no manifest entry for ${correspondingTsRel}`,
+            });
+        } else if (entry.contract === 'repo-only') {
+            violations.push({
+                kind: 'unexpected_twin',
+                target: mjsRel,
+                message: `repo-only script ${correspondingTsRel} must not have a .mjs twin (${mjsRel})`,
+            });
+        }
+    }
+
+    // Rule 3: all .ts files on disk must have a manifest entry
+    const diskTsSet = new Set(tsFiles);
+    for (const tsRel of tsFiles) {
+        if (!manifestMap.has(tsRel)) {
+            violations.push({
+                kind: 'unregistered_script',
+                target: tsRel,
+                message: `script ${tsRel} exists in scripts dir but is not registered in manifest`,
+            });
+        }
+    }
+
+    // Also verify manifest entries exist on disk
+    for (const [rel] of manifestMap) {
+        if (!diskTsSet.has(rel)) {
+            violations.push({
+                kind: 'unregistered_script',
+                target: rel,
+                message: `manifest entry ${rel} does not exist on disk in ${scriptsDir}`,
+            });
+        }
+    }
+
+    // Rule 4: scan shipped surfaces for forbidden invocation
+    const forbiddenHits = scanShippedSurfaces(pluginDir);
+    for (const hit of forbiddenHits) {
+        violations.push({
+            kind: 'forbidden_invocation',
+            target: `${hit.file}:${hit.line}`,
+            message: `shipped surface ${hit.file}:${hit.line} contains forbidden invocation 'bun plugins/sp/scripts/': ${hit.content}`,
+        });
+    }
+
+    return violations;
+}
+
+export function run(argv: string[] = process.argv.slice(2)): number {
+    const { manifest, scriptsDir, pluginDir, cwd } = parseArgs(argv);
+    const manifestPath = resolve(cwd, manifest);
+    const absScriptsDir = resolve(cwd, scriptsDir);
+    const absPluginDir = resolve(cwd, pluginDir);
+
+    const { manifest: parsed, error } = loadManifest(manifestPath);
+    if (error || !parsed) {
+        console.error(`script-contract-check: FAIL - ${error}`);
+        return 1;
+    }
+
+    const violations = validateContract(parsed, absScriptsDir, absPluginDir);
+    const ok = violations.length === 0;
+
+    const standardCount = parsed.entries.filter((e) => e.contract === 'standard').length;
+    const repoOnlyCount = parsed.entries.filter((e) => e.contract === 'repo-only').length;
+
+    console.log(
+        `script-contract-check: ${parsed.entries.length} script(s) baselined (${standardCount} standard, ${repoOnlyCount} repo-only), ` +
+            `${violations.length} violation(s) — ${ok ? 'PASS' : 'FAIL'}`,
+    );
+
+    if (ok) return 0;
+
+    for (const v of violations) {
+        console.error(`script-contract-check: FAIL (${v.kind}) - ${v.message}`);
+    }
+    return 1;
+}
+
+if (import.meta.main) {
+    process.exit(run());
+}

package/plugins/sp/skills/daily-summary/SKILL.md

@@ -52,13 +52,13 @@ The daily-summary skill:
 
 ```bash
 # Generate summary for today
-bun plugins/sp/scripts/daily-summary/daily-summary.ts
+node "$(superskill script path sp daily-summary/daily-summary.mjs)"
 
 # Generate summary for a specific date
-bun plugins/sp/scripts/daily-summary/daily-summary.ts --date 2026-04-17
+node "$(superskill script path sp daily-summary/daily-summary.mjs)" --date 2026-04-17
 
 # Show summary without writing file
-bun plugins/sp/scripts/daily-summary/daily-summary.ts --dry-run
+node "$(superskill script path sp daily-summary/daily-summary.mjs)" --dry-run
 ```
 
 ## Workflows

package/plugins/sp/skills/dogfood-testing/SKILL.md

@@ -96,9 +96,9 @@ The command forwards these via `$ARGUMENTS`:
    in-agent):
 
    ```bash
-   bun plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts \
+   node "$(superskill script path sp dogfood-testing/detect-pipeline-driving.mjs)" \
      --testee "<raw testee string>" \
-     [--max-retry-present]   # pass this flag only when the dogfood invocation included --max-retry
+     [--max-retry-present]
    ```
 
    - Exit **2** → print the stdout refuse line and **stop** (do not plan). The CLI refuses on either
@@ -118,7 +118,7 @@ The command forwards these via `$ARGUMENTS`:
     re-run the gate with the derived step labels:
 
     ```bash
-    bun plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts \
+    node "$(superskill script path sp dogfood-testing/detect-pipeline-driving.mjs)" \
       --testee "<raw testee string>" \
       --max-retry-present \
       --steps "step1 label||step2 label||..."
@@ -226,7 +226,7 @@ contract violation**.
    **before** claiming `status: complete`:
 
    ```bash
-   bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report-path>
+   node "$(superskill script path sp dogfood-testing/validate-report.mjs)" --file <report-path>
    ```
 
    Exit **0** → proceed. Exit **2** → set `status: aborted`, list every error code under §5
@@ -328,7 +328,7 @@ Do **not** use this skill for:
 Pipeline-driving detection is **word-boundary**, not leading-space substring. The live gate is:
 
 ```bash
-bun plugins/sp/scripts/dogfood-testing/detect-pipeline-driving.ts --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
+node "$(superskill script path sp dogfood-testing/detect-pipeline-driving.mjs)" --testee "<testee>" [--max-retry-present] [--steps "…"] [--json]
 ```
 
 | Token shape | Examples | Matches | Rejects |

package/plugins/sp/skills/dogfood-testing/references/report-template.md

@@ -278,7 +278,7 @@ Before the skill may stop (success, partial, fail, observe-only end, or abort),
    and mirror the footer block at the **end of the report file**. A report whose body lacks the
    footer cannot set `status: complete`.
 8. **Self-validate (task 0278 R6):** run
-   `bun plugins/sp/scripts/dogfood-testing/validate-report.ts --file <report-path>` before
+   `node "$(superskill script path sp dogfood-testing/validate-report.mjs)" --file <report-path>` before
    claiming `status: complete`. Exit 2 → `status: aborted` + list error codes under
    `#### Unresolved` (never force complete on a non-@1.2 shape).
 9. **Refusal rule (@1.2):** when any check above fails, set `status: aborted` and list every

package/plugins/sp/skills/pr-reviewing/SKILL.md

@@ -129,11 +129,11 @@ staged entrypoint below, supports `--json`, and must be parsed. Stop at the firs
 report its artifact. The canonical installed invocation is:
 
 ```sh
-bun "$(superskill script path sp pr-reviewing.ts)" <subcommand> [flags]
+node "$(superskill script path sp pr-reviewing.mjs)" <subcommand> [flags]
 ```
 
-Installed targets resolve the staged TypeScript source and execute it with Bun, matching the rest
-of `plugins/sp/scripts`.
+Installed targets resolve the staged `.mjs` twin and execute it with Node, matching the standard
+superskill script contract.
 
 1. **Preflight** — `<script> preflight --base "$base" --json`. Hard-fails on a
    detached HEAD, missing `gh` auth, no GitHub remote, a dirty tree, or the current branch

package/plugins/sp/skills/spur-dev/SKILL.md

@@ -219,7 +219,8 @@ for "what's actually in file Y" or for resources that sit outside the step seque
 - `plugins/sp/references/roles.md` — the Layer-1 role→tier table (`scribe` / `coder` / `reviewer` /
   `planner`, one per tier); the role vocabulary this spine's operations route under.
 - `.spur/workflows/task-pipeline.yaml` — the execution pipeline definition.
-- `.spur/workflows/planning-pipeline.yaml` — the front-half state machine.
+- `.spur/workflows/idea-pipeline.yaml` — the front-half state machine (absorbed the retired
+  planning-pipeline in D5-K; `/sp:dev-plan` routes here, ADR-072).
 - `.spur/templates/bdd/gherkin.md` — the BDD scenario template.
 
 ## Platform Notes

package/plugins/sp/skills/spur-dev/references/cross-cutting.md

@@ -538,8 +538,7 @@ invariants that keep the pipeline set coherent as new ones are added.
 
 | Pipeline | Lifecycle phase | Entry point | Terminal states |
 | --- | --- | --- | --- |
-| `idea-pipeline.yaml` | Ideation (vague idea → feature + AC + task batch) | `/sp:dev-idea` | `handoff`, `cancelled` |
-| `planning-pipeline.yaml` | Design (known slug/task → design handoff) | `/sp:dev-plan` | `handoff`, `cancelled` |
+| `idea-pipeline.yaml` | Ideation + planning (vague idea or known slug → feature + AC + task batch) | `/sp:dev-idea`, `/sp:dev-plan` | `handoff`, `cancelled` |
 | `task-pipeline.yaml` | Execution (one task → done) | `/sp:dev-run` | `done`, `failed` |
 | `wrapup-pipeline.yaml` | Wrap-up (completed tasks → learning + metrics + doc-sync) | `/sp:dev-wrap`, `/sp:dev-wrapall` | `done`, `skipped` |
 | `feature-dev.yaml` | Umbrella (brainstorm → plan → execute → feature-verify) | `/sp:dev-runall --feature <id>` (or `--tasks feature:<id>`) | `done`, `failed` |
@@ -644,8 +643,8 @@ next_action: "run verification"
 **Write checkpoints after:**
 
 - Every HITL gate decision (approved/rejected/deferred).
-- Every phase transition in `planning-pipeline`, `task-pipeline`, `feature-dev`, `idea-pipeline`,
-  and `wrapup-pipeline`.
+- Every phase transition in `task-pipeline`, `feature-dev`, `idea-pipeline`, and
+  `wrapup-pipeline`.
 - Every terminal state (`done`, `failed`, `cancelled`, `skipped`).
 
 **Read checkpoints when:**

package/plugins/sp/skills/spur-dev/references/dev-operations.md

@@ -82,7 +82,7 @@ each would be scope creep for one-liner procedures.
 | 13a | parallel   | `dev-parallel`      | `Skill()`         | `sp:parallel-execution`                                                            | `--tasks <selector> [--feature <id>] [--mode <fan-out\|review-panel\|investigation>] [--agent <inline\|auto\|name>] [--json]`                                                                          |
 | 14  | wrap       | `dev-wrap`          | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `<wbs> [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                                                                 |
 | 15  | wrapall    | `dev-wrapall`       | `Skill()`         | `spur workflow run` (wrapup-pipeline)                                              | `[--since <iso>] [--feature <id>] [--status <s>] [--agent <inline\|auto\|name>] [--auto] [--merge] [--dry-run]`                                                                                        |
-| 16  | idea       | `dev-idea`          | `Skill()`         | `spur workflow run` (idea-pipeline)                                                | `"<idea>" [--auto] [--skip-design] [--approve-taste]`                                                                                                                                                  |
+| 16  | idea       | `dev-idea`          | `Skill()`         | `spur workflow run` (idea-pipeline)                                                | `"<idea>" [--auto] [--skip-design] [--approve-taste] [--agent <inline\|auto\|name>]`                                                                                                                                                  |
 
 ## Skill-backed operations
 

package/plugins/sp/skills/spur-dev/references/execution-batch.md

@@ -179,7 +179,7 @@ The ordered execution plan: a WBS-ascending-topological list of tasks to run, pl
 helper (preferred) or `sp:next-router` dry-run:
 
 ```bash
-bun plugins/sp/scripts/batch-preflight.ts \
+node "$(superskill script path sp batch-preflight.mjs)" \
   --wbs <wbs> --status <status> \
   --deps <comma-deps> --dep-status <wbs:status,...> --json
 ```
@@ -278,7 +278,7 @@ After a non-PASS terminal state (or when the task status is stuck at `wip`/`test
 verdict), consult **one** recovery hop:
 
 ```bash
-bun plugins/sp/scripts/batch-preflight.ts --wbs <wbs> --status <status> --recovery
+node "$(superskill script path sp batch-preflight.mjs)" --wbs <wbs> --status <status> --recovery
 # → e.g. /sp:dev-verify 0042 --auto --next
 ```
 
@@ -306,7 +306,7 @@ Both `task-pipeline.yaml` (`record` step) and `wrapup-pipeline.yaml` (`feature-t
 invoke the bounded wrapper instead of raw `feature sync`:
 
 ```bash
-bun plugins/sp/scripts/feature-sync-bounded.ts <feature-id> --spur-bin "<spurBin>" --json
+node "$(superskill script path sp feature-sync-bounded.mjs)" <feature-id> --spur-bin "<spurBin>" --json
 ```
 
 The wrapper:

package/plugins/sp/skills/spur-dev/references/gate-checklists.md

@@ -36,8 +36,8 @@ SSOT: `.spur/workflows/task-lifecycle.yaml`.
 
 ## feature-check gate
 
-Entered before `spur feature check <id> --strict` (idea-pipeline `feature-check` state;
-planning-pipeline AC validation).
+Entered before `spur feature check <id> --strict` (idea-pipeline `feature-check` state — the
+AC-validation gate `/sp:dev-plan` also routes through since D5-K).
 
 - [ ] Feature file has a non-placeholder `## Goal` and `## Scope` section.
 - [ ] Acceptance criteria are R-numbered scenarios in Gherkin `Feature/Scenario` form (see `ac-style-guide.md`).
@@ -48,8 +48,8 @@ planning-pipeline AC validation).
 
 ## batch-create gate
 
-Entered before `spur task batch-create --file <json>` (idea-pipeline `batch-create` state;
-planning-pipeline decomposition gate).
+Entered before `spur task batch-create --file <json>` (idea-pipeline `batch-create` state — the
+decomposition gate `/sp:dev-plan` also routes through since D5-K).
 
 - [ ] The batch JSON is a bare array (not an object with a `tasks` key).
 - [ ] Each entry validates locally against `apps/cli/schemas/task-batch.schema.json` (`additionalProperties: false` — no unknown keys).