@gobing-ai/spur 0.3.76 → 0.3.78

package/plugins/sp/scripts/batch-preflight.ts

@@ -25,6 +25,182 @@ export type PreflightResult =
     | { action: 'run'; code?: string; reason?: string }
     | { action: 'skip'; code: string; reason: string; unmetDeps?: string[] };
 
+// ── Command-aware quick readiness (task 0814 R2) ──────────────────────────────
+// Read-only admission decision for the requested dev operation. Distinguishes
+// runnable / needs-refinement / blocked / skipped / invalid outcomes without
+// LLM dispatch, full tests/lint, live-data probes, feature mutation, or
+// corpus-wide relational checking. Refinement gaps are work to do, not errors.
+
+export type ReadinessOperation = 'run' | 'refine' | 'verify';
+
+export interface QuickReadinessInput {
+    wbs: string;
+    status: TaskStatus;
+    operation: ReadinessOperation;
+    /** Frontmatter dependencies[] WBS list (run only). */
+    dependencies?: string[];
+    /** Status of each dependency WBS; missing → treated as unmet (run only). */
+    depStatuses?: Record<string, string>;
+    /** Size of the status-filtered candidate set after the selector resolved; 0 = empty set. */
+    filteredCount?: number;
+    /** Required planning sections for this variant+status; empty = not applicable. */
+    requiredSections?: string[];
+    /** Sections that are actually present (non-placeholder) in the task. */
+    presentSections?: string[];
+    /** L1/L2/L3 content-policy findings keyed by section; empty = clean. */
+    sectionFindings?: Record<string, string>;
+    /** Verify only: re-verification semantics (--force) — never a dirty-tree bypass. */
+    force?: boolean;
+}
+
+export type QuickReadinessResult =
+    | { action: 'runnable'; code: string; reason: string }
+    | { action: 'needs-refinement'; code: string; reason: string; gaps: string[] }
+    | { action: 'blocked'; code: string; reason: string; unmetDeps?: string[] }
+    | { action: 'skipped'; code: string; reason: string }
+    | { action: 'invalid'; code: string; reason: string };
+
+/**
+ * Evaluate quick readiness for a requested dev operation (0814 R2). Read-only:
+ * no model, no full tests/lint, no live-data probe, no feature mutation, no
+ * corpus-wide relational check. An empty status-filtered set is `skipped`
+ * (mirrors the zero-task rule), never an error. Refinement gaps under `refine`
+ * are work to do, so they do not block; under `run` they are `needs-refinement`.
+ */
+export function quickReadiness(input: QuickReadinessInput): QuickReadinessResult {
+    const status = (input.status ?? '').toLowerCase();
+    const operation = input.operation;
+
+    if (operation !== 'run' && operation !== 'refine' && operation !== 'verify') {
+        return {
+            action: 'invalid',
+            code: 'IV',
+            reason: `quick-readiness: unknown operation '${operation}' (${input.wbs})`,
+        };
+    }
+
+    if (input.filteredCount !== undefined) {
+        if (input.filteredCount < 0) {
+            return {
+                action: 'invalid',
+                code: 'IV',
+                reason: `quick-readiness: invalid negative filtered count '${input.filteredCount}' (${input.wbs})`,
+            };
+        }
+        if (input.filteredCount === 0) {
+            return {
+                action: 'skipped',
+                code: 'EMPTY',
+                reason: `quick-readiness: empty status-filtered set — nothing to ${operation} (${input.wbs})`,
+            };
+        }
+    }
+
+    if (status === 'cancelled' || status === 'done') {
+        // verify --force re-verification (R2 AC): an already-verified terminal task
+        // is re-checked, not skipped — but force never bypasses a dirty tree or the
+        // owning gates; it only re-admits a terminal task for re-verification.
+        if (operation === 'verify' && input.force === true) {
+            return {
+                action: 'runnable',
+                code: 'FORCE',
+                reason: `quick-readiness: verify --force re-verification of ${status} task ${input.wbs}`,
+            };
+        }
+        return {
+            action: 'skipped',
+            code: status === 'done' ? 'DONE' : 'CANCELLED',
+            reason: `quick-readiness: already ${status} — no ${operation} hop (${input.wbs})`,
+        };
+    }
+
+    if (status === 'blocked') {
+        return {
+            action: 'blocked',
+            code: 'BLK',
+            reason: `quick-readiness: blocked — human/handover first (${input.wbs})`,
+        };
+    }
+
+    // Unmet out-of-set dependency is a block for the operation that needs it.
+    if (operation === 'run' && input.dependencies && input.dependencies.length > 0) {
+        const unmet = input.dependencies.filter((d) => (input.depStatuses?.[d] ?? 'missing').toLowerCase() !== 'done');
+        if (unmet.length > 0) {
+            return {
+                action: 'blocked',
+                code: 'DEP',
+                reason: `quick-readiness: unmet deps — ${unmet.join(', ')} (${input.wbs})`,
+                unmetDeps: unmet,
+            };
+        }
+    }
+
+    const required = input.requiredSections ?? [];
+    const present = input.presentSections ?? [];
+    // A required section is a gap when it is absent from the present-set OR carries a
+    // content-policy finding (the caller-supplied `sectionFindings` from the matrix /
+    // `TaskCheckService.checkContentPolicy`). This lets the function detect a gap itself
+    // rather than depending on the caller to pre-enumerate every missing section.
+    const gaps = required.filter((s) => {
+        const finding = input.sectionFindings?.[s];
+        return !present.includes(s) || (finding !== undefined && finding !== '');
+    });
+
+    // refine: missing/incomplete planning sections are the work, not a failure.
+    if (operation === 'refine') {
+        if (status !== 'backlog' && status !== 'todo') {
+            return {
+                action: 'skipped',
+                code: 'NONPLAN',
+                reason: `quick-readiness: refine targets backlog/todo only, not '${status}' (${input.wbs})`,
+            };
+        }
+        return {
+            action: 'runnable',
+            code: 'OK',
+            reason: `quick-readiness: refine ready for ${input.wbs} (${gaps.length} planning gap(s) to fill)`,
+        };
+    }
+
+    if (operation === 'verify') {
+        if (status !== 'testing' && status !== 'wip') {
+            return {
+                action: 'invalid',
+                code: 'NOVERIFY',
+                reason: `quick-readiness: verify needs testing/wip, not '${status}' (${input.wbs})`,
+            };
+        }
+        return {
+            action: 'runnable',
+            code: 'OK',
+            reason: `quick-readiness: verify ready for ${input.wbs}`,
+        };
+    }
+
+    // run: implementation admission. Eligible statuses are todo/wip/testing;
+    // a backlog task needs the chain's auto-promotion first (step 0).
+    if (status !== 'todo' && status !== 'wip' && status !== 'testing') {
+        return {
+            action: 'invalid',
+            code: 'NORUN',
+            reason: `quick-readiness: run needs todo/wip/testing, not '${status}' (${input.wbs})`,
+        };
+    }
+    if (gaps.length > 0) {
+        return {
+            action: 'needs-refinement',
+            code: 'REFINE',
+            reason: `quick-readiness: implementation sections incomplete (${input.wbs})`,
+            gaps,
+        };
+    }
+    return {
+        action: 'runnable',
+        code: 'OK',
+        reason: `quick-readiness: run ready for ${input.wbs}`,
+    };
+}
+
 /**
  * Evaluate whether the batch should launch task-pipeline.yaml for this WBS.
  * STOP codes align with routing-table TABLE A row ids (A2, A7, A8, A9).
@@ -113,6 +289,16 @@ export interface PreflightCliArgs {
     recovery: boolean;
     help: boolean;
     json: boolean;
+    /** Quick-readiness operation (run|refine|verify); when set, run quickReadiness. */
+    operation: ReadinessOperation | null;
+    /** Verify-only re-verification (R2 AC). */
+    force: boolean;
+    /** Status-filtered candidate set size; 0 = empty set. */
+    filteredCount: number | null;
+    /** Required planning sections (matrix-selected). */
+    requiredSections: string[];
+    /** Sections actually present in the task. */
+    presentSections: string[];
 }
 
 export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
@@ -123,13 +309,43 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
     let recovery = false;
     let help = false;
     let json = false;
+    let operation: ReadinessOperation | null = null;
+    let force = false;
+    let filteredCount: number | null = null;
+    let requiredSections: string[] = [];
+    let presentSections: string[] = [];
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--help' || a === '-h') help = true;
         else if (a === '--json') json = true;
         else if (a === '--recovery') recovery = true;
-        else if (a === '--wbs') wbs = argv[++i] ?? wbs;
+        else if (a === '--force') force = true;
+        else if (a === '--operation') {
+            const v = argv[++i] ?? '';
+            operation = v === 'run' || v === 'refine' || v === 'verify' ? v : null;
+        } else if (a === '--filtered-count') {
+            const v = Number(argv[++i]);
+            filteredCount = Number.isFinite(v) ? v : null;
+        } else if (a === '--required-sections') {
+            const raw = argv[++i] ?? '';
+            requiredSections =
+                raw.length === 0
+                    ? []
+                    : raw
+                          .split(',')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        } else if (a === '--present-sections') {
+            const raw = argv[++i] ?? '';
+            presentSections =
+                raw.length === 0
+                    ? []
+                    : raw
+                          .split(',')
+                          .map((s) => s.trim())
+                          .filter(Boolean);
+        } else if (a === '--wbs') wbs = argv[++i] ?? wbs;
         else if (a === '--status') status = argv[++i] ?? null;
         else if (a === '--deps') {
             const raw = argv[++i] ?? '';
@@ -149,12 +365,27 @@ export function parsePreflightCliArgs(argv: string[]): PreflightCliArgs {
             }
         }
     }
-    return { status, deps, depStatuses, wbs, recovery, help, json };
+    return {
+        status,
+        deps,
+        depStatuses,
+        wbs,
+        recovery,
+        help,
+        json,
+        operation,
+        force,
+        filteredCount,
+        requiredSections,
+        presentSections,
+    };
 }
 
 export const PREFLIGHT_CLI_USAGE = `Usage:
   bun plugins/sp/scripts/batch-preflight.ts --wbs <wbs> --status <status> \\
     [--deps 0275,0276] [--dep-status 0275:done,0276:todo] [--recovery] [--json]
+  bun plugins/sp/scripts/batch-preflight.ts --operation <run|refine|verify> --wbs <wbs> --status <status> \
+    [--filtered-count <n>] [--required-sections A,B] [--present-sections A,B] [--force] [--json]
 
 Exit: 0 = run (or recovery hint printed); 2 = skip; 1 = usage.`;
 
@@ -173,6 +404,30 @@ export function runPreflightCli(argv: string[]): { exitCode: number; stdout: str
         return { exitCode: 0, stdout: body, stderr: '' };
     }
 
+    // Quick command-aware readiness (0814 R2) — read-only admission decision.
+    if (args.operation !== null) {
+        const result = quickReadiness({
+            wbs: args.wbs,
+            status: args.status,
+            operation: args.operation,
+            dependencies: args.deps,
+            depStatuses: args.depStatuses,
+            ...(args.filteredCount !== null ? { filteredCount: args.filteredCount } : {}),
+            ...(args.requiredSections.length > 0 ? { requiredSections: args.requiredSections } : {}),
+            ...(args.presentSections.length > 0 ? { presentSections: args.presentSections } : {}),
+            ...(args.force ? { force: true } : {}),
+        });
+        const runnable = result.action === 'runnable' || result.action === 'needs-refinement';
+        if (args.json) {
+            return { exitCode: runnable ? 0 : 2, stdout: `${JSON.stringify(result, null, 2)}\n`, stderr: '' };
+        }
+        return {
+            exitCode: runnable ? 0 : 2,
+            stdout: `${result.action}${result.code ? ` ${result.code}` : ''}: ${result.reason}\n`,
+            stderr: '',
+        };
+    }
+
     const result = preflightTask({
         wbs: args.wbs,
         status: args.status,

package/plugins/sp/scripts/inline-run-setup.ts

@@ -0,0 +1,198 @@
+#!/usr/bin/env bun
+/**
+ * inline-run-setup — authoritative inline full-pipeline run identity (task 0804 R1).
+ *
+ * Unlike the subprocess path (`spur workflow run`), the interactive inline driver
+ * allocated a run id but never persisted an authoritative `runs` row, so bound
+ * `run.artifact` registration (0785 R3) correctly refused every inline record. This
+ * script is the thin delegate the driver now runs at Run setup: it resolves the spur
+ * repo checkout from the SPUR_BIN chain, imports the real app service
+ * (`createOrAttachInlineRun` / `openInlineRunProjectDb` from packages/app), and lets it
+ * resolve the SAME project-or-bundled definition the engine would launch, compute the
+ * canonical definition digest with the exported hash machinery, and create-or-attach the
+ * run row through the existing engine persistence adapter.
+ *
+ * The script itself contains NO direct SQL, NO second hasher and NO persistence policy —
+ * every rule lives in packages/app (0804 D1). On a bundle-only install there is no repo
+ * checkout to import the app service from, so the setup fails closed with actionable
+ * remediation guidance (point SPUR_BIN at a repo checkout); it never falls back to an
+ * unbound run (0804 R1 failure policy).
+ *
+ * Outcome JSON is written to `.spur/run/<run-id>-inline-setup.json` so the driver can
+ * seed the inline var overlay (`__runId`, `__definitionDigest`) that proof capture and
+ * bound registration verify against. Exit 0 = authoritative identity ready (created or
+ * idempotently attached); exit 1 = fail closed, the driver must stop.
+ *
+ * Repo-only script (ADR-065): it imports the app workspace source, so it runs under bun
+ * against a monorepo checkout only — the same posture as task-size-precheck.ts and
+ * task-evidence-precheck.ts.
+ *
+ * Usage:
+ *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
+ *
+ * Env: SPUR_BIN
+ */
+
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** Outcome document written to `.spur/run/<run-id>-inline-setup.json`. */
+interface SetupOutcome {
+    readonly ok: boolean;
+    readonly runId: string;
+    readonly attached?: boolean;
+    readonly definitionDigest?: string;
+    readonly workflowName?: string;
+    readonly workflowVersion?: string | null;
+    readonly resolvedPath?: string;
+    readonly layer?: string;
+    readonly workdir?: string;
+    readonly status?: string;
+    readonly error?: string;
+}
+
+function usage(): never {
+    console.error(
+        'Usage: bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]',
+    );
+    process.exit(1);
+}
+
+/**
+ * The run id becomes a filename under `.spur/run/` (`<run-id>-inline-setup.json`), so it must be a
+ * single safe filename component before anything is written — the same guard class the
+ * task-pipeline.yaml route-reason action applies to `$__runId` (task 0804 R8). The allowlist
+ * refuses path separators, dot traversal (leading `.`), unresolved interpolation (`$`/`{`/`}`) and
+ * every other shell/unspecified metachar; valid UUID/timestamp-slug ids pass.
+ */
+const SAFE_RUN_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+function refuseUnsafeRunId(runId: string): never {
+    // Refuse BEFORE any outcome write: an unsafe id must never reach
+    // `.spur/run/<run-id>-inline-setup.json` (no traversal, no unintended file).
+    console.error(`inline-run-setup: refusing unsafe run id: ${runId}`);
+    console.error(
+        '  The run id must be a single safe filename component (alphanumeric/._-, no leading dot, ' +
+            'no path separators, interpolation or traversal; same class as the task-pipeline ' +
+            'route-reason guard, task 0804 R8). Allocate a fresh run id (uuid or timestamp slug) and retry.',
+    );
+    process.exit(1);
+}
+
+/**
+ * Resolve the spur repo checkout the same way the other prechecks resolve the CLI
+ * (--spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`), then derive the repo
+ * root from the resolved main module. `bun <repo>/apps/cli/src/index.ts` → repo root is
+ * three levels up. A bundle-only install (`spur` on PATH, a bundled `spur.js`, or a spur
+ * binary without the app workspace) has no app entry to import — the caller fails that
+ * closed with remediation guidance.
+ */
+function resolveAppEntry(
+    spurBin: string,
+): { entry: string; repoRoot: string } | { entry: null; repoRoot: null; chain: string } {
+    let candidates: string[] = [];
+    if (spurBin !== '') {
+        candidates = [spurBin];
+    } else {
+        // scripts/ -> plugins/sp/ -> <repo>/apps/cli/src/index.ts (fileURLToPath — raw
+        // pathname breaks on %-encoded paths, e.g. spaces in the checkout directory).
+        candidates = [fileURLToPath(new URL('../../../apps/cli/src/index.ts', import.meta.url))];
+    }
+    for (const candidate of candidates) {
+        const tokens = candidate.split(/\s+/).filter(Boolean);
+        // The main module is the last path-like token (tolerates `bun <path>` /
+        // `bun run <path>` lead tokens). Only a TypeScript source entry proves a repo
+        // checkout; a bundled `spur.js` or a bare `spur` binary does not.
+        const mainModule = [...tokens].reverse().find((t) => t.endsWith('.ts'));
+        if (mainModule === undefined || !existsSync(mainModule)) continue;
+        // <repo>/apps/cli/src/index.ts → repo root; then require the app package source.
+        const srcDir = dirname(mainModule);
+        const repoRoot = resolve(srcDir, '..', '..', '..');
+        const appEntry = join(repoRoot, 'packages', 'app', 'src', 'index.ts');
+        if (existsSync(appEntry)) return { entry: appEntry, repoRoot };
+        return { entry: null, repoRoot: null, chain: `${candidate} (no ${appEntry})` };
+    }
+    return { entry: null, repoRoot: null, chain: spurBin === '' ? 'PATH spur (bundle-only install)' : spurBin };
+}
+
+function writeOutcome(runId: string, outcome: SetupOutcome): void {
+    const runDir = join(process.cwd(), '.spur', 'run');
+    if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+    writeFileSync(join(runDir, `${runId}-inline-setup.json`), `${JSON.stringify(outcome, null, 4)}\n`);
+}
+
+async function main(): Promise<void> {
+    let runId = '';
+    let file = '';
+    let spurBin = process.env.SPUR_BIN ?? '';
+    const argv = process.argv.slice(2);
+    for (let i = 0; i < argv.length; i++) {
+        if (argv[i] === '--run-id') runId = argv[++i] ?? '';
+        else if (argv[i] === '--file') file = argv[++i] ?? '';
+        else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
+    }
+    if (runId.trim() === '' || file.trim() === '') usage();
+    if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
+
+    const { entry, repoRoot, chain } = resolveAppEntry(spurBin);
+    if (entry === null || repoRoot === null) {
+        const outcome: SetupOutcome = {
+            ok: false,
+            runId,
+            error:
+                `inline run setup failed closed: no monorepo checkout of spur is reachable via ${chain}. ` +
+                'The authoritative run identity must be persisted by the app service ' +
+                '(packages/app/src/services/inline-run-setup.ts); a bundle-only install cannot do this. ' +
+                'Remediation: point SPUR_BIN at a repo checkout, e.g. ' +
+                'SPUR_BIN="bun /path/to/spur/apps/cli/src/index.ts". The pipeline must not run unbound.',
+        };
+        writeOutcome(runId, outcome);
+        console.error(`inline-run-setup: FAIL for run ${runId}`);
+        console.error(`  ${outcome.error}`);
+        process.exit(1);
+    }
+
+    // Dynamic import by absolute path: the app source graph resolves its own workspace
+    // dependencies from the repo checkout, never from this plugin script's location.
+    const app = (await import(entry)) as {
+        createOrAttachInlineRun: (input: {
+            workdir: string;
+            getDb: () => Promise<unknown>;
+            file: string;
+            runId: string;
+        }) => Promise<SetupOutcome & { ok: boolean }>;
+        openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+    };
+
+    const workdir = process.cwd();
+    const projectDb = await app.openInlineRunProjectDb(workdir);
+    let exitCode = 0;
+    try {
+        const result = await app.createOrAttachInlineRun({
+            workdir,
+            getDb: async () => projectDb.adapter,
+            file,
+            runId,
+        });
+        writeOutcome(runId, result);
+        if (!result.ok) {
+            console.error(`inline-run-setup: FAIL for run ${runId}`);
+            console.error(`  ${result.error}`);
+            exitCode = 1;
+        } else {
+            console.error(
+                `inline-run-setup: ${result.attached ? 'attached' : 'created'} run ${runId} ` +
+                    `(${result.workflowName}, layer ${result.layer}, digest ${result.definitionDigest}, status ${result.status})`,
+            );
+        }
+    } finally {
+        projectDb.close();
+    }
+    process.exit(exitCode);
+}
+
+main().catch((e: unknown) => {
+    console.error(`inline-run-setup: FAIL — ${e instanceof Error ? e.message : String(e)}`);
+    process.exit(1);
+});