@gobing-ai/spur 0.3.47 → 0.3.48

package/plugins/sp/scripts/task-size-precheck.ts

@@ -26,6 +26,8 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { STAGE_FLOOR_TIER, TIER_ORDER } from './stage-registry-adapter';
 
 // ─── Regex (sync with packages/app/src/services/task-size-precheck.ts) ───────
 
@@ -44,8 +46,17 @@ const CHECKLIST_ITEM_RE = /^\s*-\s*\[[ xX]\]/m;
 const LARGE_TASK_REQS = 5;
 const LARGE_TASK_PLAN_ITEMS = 8;
 
-/** Capability tiers strong enough for a large task. Anything else blocks. */
-const CAPABLE_TIERS = new Set(['capable-1', 'capable-2', 'capable-3']);
+/**
+ * Capability tiers strong enough for a large task (R3, task 0487). The floor is
+ * the `review` stage's Layer-1 tier — `reviewer` per `references/roles.md`,
+ * read via the stage-registry adapter (0538 R4: no tier literal here; roles.md
+ * is the pointer). Tiers at or above the floor pass. An unreachable roles.md
+ * degrades to the pre-reconcile band — fail-closed for a safety gate.
+ */
+const CAPABLE_TIERS: ReadonlySet<string> = (() => {
+    const floor = STAGE_FLOOR_TIER.get('review') ?? 'capable-1';
+    return new Set(TIER_ORDER.slice(Math.max(0, TIER_ORDER.indexOf(floor))));
+})();
 
 // ─── CLI ─────────────────────────────────────────────────────────────────────
 
@@ -56,6 +67,21 @@ function usage(): never {
     process.exit(1);
 }
 
+/**
+ * Resolve the spur CLI command in a monorepo-safe way:
+ * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
+ * The plugin's own CI always passes an explicit --spur-bin; this fallback chain
+ * keeps ad-hoc invocations from silently hitting a stale PATH install.
+ */
+function defaultSpurBin(): string {
+    if (process.env.SPUR_BIN) return process.env.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));
+    if (existsSync(local)) return `bun ${local}`;
+    return 'spur';
+}
+
 function parseArgs(argv: string[]): {
     wbs: string;
     spurBin: string;
@@ -63,7 +89,7 @@ function parseArgs(argv: string[]): {
     maxPlanItems: number;
     executor: string;
 } {
-    let spurBin = process.env.SPUR_BIN ?? 'spur';
+    let spurBin = defaultSpurBin();
     let wbs = '';
     let maxReqs = Number(process.env.MAX_IMPLEMENT_REQS) || 5;
     let maxPlanItems = Number(process.env.MAX_IMPLEMENT_PLAN_ITEMS) || 8;
@@ -73,7 +99,7 @@ function parseArgs(argv: string[]): {
     while (i < argv.length) {
         const arg = argv[i];
         if (arg === '--spur-bin') {
-            spurBin = argv[i + 1] ?? 'spur';
+            spurBin = argv[i + 1] ?? defaultSpurBin();
             i += 2;
         } else if (arg === '--max-reqs') {
             maxReqs = Number(argv[i + 1]) || 5;

package/plugins/sp/scripts/transition-shim-check.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env bun
+/**
+ * transition-shim-check — two-sided gate over `config/transition-shims.json`
+ * (task 0541, feature B2).
+ *
+ * A transition shim is a compatibility path that must survive the agent-role
+ * transition. Every shim carries a source marker comment `@transition-shim(<id>)`
+ * so it is a grep target and a review signal, and a manifest entry in
+ * `config/transition-shims.json` records who owns it and when it can be removed.
+ *
+ * The gate is deliberately two-sided, matching `config/corpus-baseline.json`
+ * semantics (corpus-check.ts): a marker with no manifest entry FAILS, and a
+ * manifest entry whose marker no longer appears in source FAILS. Without the
+ * second half the manifest would rot into a permanent suppression list — the
+ * exact invisible-debt pattern this gate exists to end.
+ *
+ * Marker convention (docs/04_DESIGN.md §2.5):
+ *   // @transition-shim(<id>) — <one line on what this keeps working>
+ *   <id> matches ^[a-z0-9][a-z0-9-]*$ (lowercase kebab).
+ * Markers live in production source roots (apps, packages, plugins, config,
+ * scripts, tooling). Docs and test fixtures are not scanned — prose examples
+ * and gate-fixture marker text must not trip the gate.
+ *
+ * The manifest is the removal worklist: emptying it is the definition of the
+ * transition being complete (R4).
+ *
+ * Ships with the plugin to arbitrary projects, so it stays node-builtin-only —
+ * no workspace imports.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/transition-shim-check.ts
+ *     [--manifest <path>]           default: config/transition-shims.json
+ *     [--roots <a,b,c>]             default: apps,packages,plugins,config,scripts,tooling
+ *
+ * Exit code: 0 when every manifest entry is present in source and every source
+ * marker is registered; 1 on any violation (unregistered marker, stale entry,
+ * or incomplete entry). Violations are printed to stderr; a summary to stdout.
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+
+const MARKER_RE = /@transition-shim\(\s*([a-z0-9][a-z0-9-]*)\s*\)/g;
+const ID_RE = /^[a-z0-9][a-z0-9-]*$/;
+
+/** Directories never scanned for markers (build output, vendored, VCS internals).
+ * `tests`/`test` are excluded too: a test fixture that mentions a marker id is
+ * data exercising the gate, not a compatibility path — shims live in production
+ * source, and only there do they need tracking. */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    'dist',
+    'coverage',
+    '.spur',
+    'build',
+    '.next',
+    '.venv',
+    '__pycache__',
+    'vendors',
+    '_legacy_reference',
+    'artifacts',
+    'tests',
+    'test',
+]);
+
+const DEFAULT_ROOTS = ['apps', 'packages', 'plugins', 'config', 'scripts', 'tooling'];
+
+/** One manifest record — every field is required (R1). */
+interface ManifestEntry {
+    id: string;
+    wbs: string;
+    file: string;
+    keepsWorking: string;
+    removalCondition: string;
+}
+
+interface Violation {
+    kind: 'unregistered' | 'stale' | 'incomplete';
+    id: string;
+    message: string;
+}
+
+function parseArgs(argv: string[]): { manifest: string; roots: string[]; cwd: string } {
+    let manifest = 'config/transition-shims.json';
+    let roots = DEFAULT_ROOTS;
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--manifest') manifest = argv[++i] ?? manifest;
+        else if (argv[i] === '--roots') roots = (argv[++i] ?? '').split(',').filter(Boolean);
+    }
+    return { manifest, roots, cwd: process.cwd() };
+}
+
+/** Walk a root and return marker id -> repo-relative files. */
+function scanMarkers(cwd: string, roots: string[]): Map<string, Set<string>> {
+    const found = new Map<string, Set<string>>();
+    const walk = (dir: string): void => {
+        let entries: string[];
+        try {
+            entries = readdirSync(dir);
+        } catch {
+            return; // unreadable or missing root — skip
+        }
+        for (const name of entries) {
+            if (SKIP_DIRS.has(name)) continue;
+            const abs = join(dir, name);
+            let st: ReturnType<typeof statSync>;
+            try {
+                st = statSync(abs);
+            } catch {
+                continue;
+            }
+            if (st.isDirectory()) {
+                walk(abs);
+                continue;
+            }
+            if (!st.isFile()) continue;
+            let text: string;
+            try {
+                text = readFileSync(abs, 'utf8');
+            } catch {
+                continue; // binary or unreadable — markers are text only
+            }
+            for (const m of text.matchAll(MARKER_RE)) {
+                const id = m[1] as string;
+                const file = relative(cwd, abs);
+                const set = found.get(id) ?? new Set<string>();
+                set.add(file);
+                found.set(id, set);
+            }
+        }
+    };
+    for (const root of roots) walk(resolve(cwd, root));
+    return found;
+}
+
+/** Load the manifest; a missing file degrades to no entries (corpus-check parity). */
+function loadManifest(path: string): { entries: ManifestEntry[]; raw: string | null } {
+    if (!existsSync(path)) return { entries: [], raw: null };
+    const raw = readFileSync(path, 'utf8');
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (error) {
+        return { entries: [], raw: `malformed JSON at ${path}: ${String(error)}` };
+    }
+    const entries = (parsed as { entries?: unknown[] }).entries;
+    if (!Array.isArray(entries)) return { entries: [], raw: `${path}: missing "entries" array` };
+    return { entries: entries as ManifestEntry[], raw: null };
+}
+
+function validateEntry(e: ManifestEntry, violations: Violation[]): void {
+    const field = (key: keyof ManifestEntry, value: unknown, why: string): void => {
+        if (typeof value !== 'string' || value.trim() === '') {
+            violations.push({
+                kind: 'incomplete',
+                id: typeof e.id === 'string' ? e.id : '<missing>',
+                message: `manifest entry ${JSON.stringify(e.id ?? null)} is missing required field "${key}"${why}`,
+            });
+        }
+    };
+    field('id', e.id, '');
+    field('wbs', e.wbs, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('file', e.file, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('keepsWorking', e.keepsWorking, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    field('removalCondition', e.removalCondition, ` in entry ${JSON.stringify(e.id ?? null)}`);
+    if (typeof e.id === 'string' && e.id !== '' && !ID_RE.test(e.id)) {
+        violations.push({
+            kind: 'incomplete',
+            id: e.id,
+            message: `manifest entry id ${JSON.stringify(e.id)} is not lowercase-kebab (^[a-z0-9][a-z0-9-]*$)`,
+        });
+    }
+}
+
+function run(): number {
+    const { manifest, roots, cwd } = parseArgs(process.argv.slice(2));
+    const manifestPath = resolve(cwd, manifest);
+    const { entries, raw } = loadManifest(manifestPath);
+    const violations: Violation[] = [];
+    const incomplete = new Set<string>();
+
+    if (raw !== null) {
+        violations.push({ kind: 'incomplete', id: '<manifest>', message: raw });
+        // A manifest that cannot be parsed has no valid entries to compare against.
+        for (const v of violations) console.error(`transition-shim-check: FAIL - ${v.message}`);
+        console.error('transition-shim-check: FAIL - manifest unreadable; refusing to pass');
+        return 1;
+    }
+
+    for (const e of entries) {
+        const before = violations.length;
+        validateEntry(e, violations);
+        if (violations.length > before) incomplete.add(String(e.id));
+    }
+
+    const markers = scanMarkers(cwd, roots);
+    const observedIds = new Set(markers.keys());
+    const manifestIds = new Set(entries.filter((e) => !incomplete.has(String(e.id))).map((e) => e.id));
+
+    for (const [id, files] of markers) {
+        if (manifestIds.has(id)) continue;
+        const file = [...files].sort().join(', ');
+        violations.push({
+            kind: 'unregistered',
+            id,
+            message: `new unregistered shim @transition-shim(${id}) in ${file} — add an entry to ${manifest} or remove the marker`,
+        });
+    }
+    for (const e of entries) {
+        if (incomplete.has(e.id)) continue;
+        if (observedIds.has(e.id)) continue;
+        violations.push({
+            kind: 'stale',
+            id: e.id,
+            message: `stale manifest entry ${e.id} (wbs ${e.wbs}) — @transition-shim(${e.id}) no longer appears in source; remove the entry, its removal condition was: ${e.removalCondition}`,
+        });
+    }
+
+    const unregistered = violations.filter((v) => v.kind === 'unregistered');
+    const stale = violations.filter((v) => v.kind === 'stale');
+    const incompleteCount = violations.filter((v) => v.kind === 'incomplete').length;
+    const ok = violations.length === 0;
+
+    const noun = entries.length === 1 ? 'entry' : 'entries';
+    console.log(
+        `transition-shim-check: ${markers.size} marker(s) observed, ${entries.length} manifest ${noun} baselined, ` +
+            `${unregistered.length} new, ${stale.length} stale, ${incompleteCount} incomplete — ${ok ? 'PASS' : 'FAIL'}`,
+    );
+    if (ok) return 0;
+
+    for (const v of violations) {
+        console.error(`transition-shim-check: ${v.kind === 'incomplete' ? 'FAIL' : `FAIL (${v.kind})`} - ${v.message}`);
+    }
+    return 1;
+}
+
+process.exit(run());

package/plugins/sp/scripts/validate-flag-contracts.ts

@@ -406,10 +406,13 @@ export function extractTriggerTable(crossCuttingRaw: string): string[] | null {
 function adrAgentClaims(adrRaw: string): Map<string, SurfaceBehavior> | null {
     if (adrRaw.includes('## ADR-047')) {
         const out = new Map<string, SurfaceBehavior>();
+        // G5 amendment (feature G5 / task 0565): explicit inline is host-session-only — headless
+        // surfaces reject it with the stable special error; 0508 native-subagent eligibility
+        // applies to omitted --agent only, never explicit inline.
         out.set('inline', {
-            surfaces: new Set(['inline', 'subprocess']),
+            surfaces: new Set(['inline']),
             conditional: false,
-            defaultWhenOmitted: true,
+            defaultWhenOmitted: false,
         });
         out.set('auto', { surfaces: new Set(['subprocess']), conditional: false });
         out.set('<name>', { surfaces: new Set(['inline', 'subprocess']), conditional: true });

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

@@ -507,6 +507,8 @@ Do **not** use this skill for:
   and the per-requirement aggregation rule.
 - [references/secu-review.md](references/secu-review.md) — the SECUA dimensions and finding-severity
   rubric.
+- `plugins/sp/references/roles.md` — the Layer-1 role→tier table; this skill's verify/review modes
+  run under the `reviewer` role (0538 R4: this file points at roles.md, it does not restate tiers).
 - `.spur/workflows/task-pipeline.yaml` — the `verify → record` gate that consumes the verdict.
 - **`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