@gobing-ai/spur 0.3.85 → 0.3.87

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

@@ -30,16 +30,29 @@
  * Usage:
  *   bun plugins/sp/scripts/inline-run-setup.ts --run-id <id> --file <definition> [--spur-bin <path>]
  *   bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> \
+ *       --status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]
+ *   bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]
  *
  * The `--fingerprint` mode prints the engine's proof-input digest for the given spec files and
  * creates nothing (task 0862 R5).
  *
+ * The `--action` / `--close` modes are the inline driver's ADR-117 emission boundary (task
+ * 0868): `--action` records one completed action boundary as an `action_runs` row through the
+ * shared `WorkflowActionTraceWriter`, `--close` marks the run row terminal through the same
+ * writer. `--action` is best-effort: a persistence failure is appended to
+ * `.spur/run/<run-id>.log` and the script still exits 0 with `{"ok":false}` on stdout, so
+ * observation never wedges the run. `--close` is NOT best-effort: the run-row closure is
+ * bookkeeping, so a missing run row or a persistence failure exits 1 with a named error.
+ * Exit 2 is reserved for usage errors.
+ *
  * Env: SPUR_BIN
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Outcome document written to `.spur/run/<run-id>-inline-setup.json`. */
 interface SetupOutcome {
@@ -63,6 +76,13 @@ function usage(): never {
     console.error(
         '       bun plugins/sp/scripts/inline-run-setup.ts --fingerprint --task-file <path> [--feature-file <path>] [--spur-bin <path>]',
     );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --action --run-id <id> --node <state> --kind <kind> ' +
+            '--status <done|failed> --ok <true|false> --duration-ms <n> [--spur-bin <path>]',
+    );
+    console.error(
+        '       bun plugins/sp/scripts/inline-run-setup.ts --close --run-id <id> --status <done|failed|paused> [--spur-bin <path>]',
+    );
     process.exit(2);
 }
 
@@ -177,13 +197,143 @@ async function printFingerprint(taskFile: string, featureFile: string, spurBin:
     return 0;
 }
 
+/** Terminal statuses the inline driver may declare when closing its run row. */
+const CLOSE_STATUSES = new Set(['done', 'failed', 'paused']);
+
+/** Finalize statuses — a finish emission is terminal, so only done|failed are valid (0868 #4). */
+const ACTION_STATUSES = new Set(['done', 'failed']);
+
+/** Input for the ADR-117 emission modes (`--action` / `--close`). */
+import type { WorkflowActionTraceWriter } from '@gobing-ai/app';
+
+interface TraceModeInput {
+    readonly runId: string;
+    readonly close: boolean;
+    readonly node: string;
+    readonly kind: string;
+    readonly status: string;
+    readonly ok: boolean;
+    readonly durationMs: number;
+    readonly spurBin: string;
+}
+
+/**
+ * Append one emission-failure line to `.spur/run/<run-id>.log` — the run log the inline
+ * driver already owns. Best-effort and synchronous (the process may exit immediately
+ * after), and never throws: an unwritable log must not wedge the run (ADR-117 R3).
+ */
+function appendTraceFailureLine(runId: string, detail: string): void {
+    try {
+        const runDir = join(process.cwd(), '.spur', 'run');
+        if (!existsSync(runDir)) mkdirSync(runDir, { recursive: true });
+        const safeRunId = runId.replace(/[^A-Za-z0-9._-]/g, '_');
+        const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+        appendFileSync(join(runDir, `${safeRunId}.log`), `[${stamp}] ${detail}\n`);
+    } catch {
+        // Best-effort (R3): the run continues even when the failure cannot be recorded.
+    }
+}
+
+/**
+ * Emit one trace write through the SHARED `WorkflowActionTraceWriter` (task 0868 R5/R7).
+ * `--action` is best-effort: an emission failure is recorded to the run log and reported
+ * on stdout as `{"ok":false}`, and the script exits 0 so the run still reaches its declared
+ * terminal state (R3/R12). `--close` is bookkeeping, so a missing run row or a persistence
+ * failure fails loudly with exit 1 (review findings #1/#4).
+ */
+async function runTraceMode(input: TraceModeInput): Promise<number> {
+    const operation = input.close ? 'run.close' : 'action.finish';
+    const fail = (error: string): number => {
+        appendTraceFailureLine(
+            input.runId,
+            `trace-emission-failed operation=${operation} run=${input.runId}` +
+                `${input.node === '' ? '' : ` node=${input.node}`}${input.kind === '' ? '' : ` kind=${input.kind}`}: ${error}`,
+        );
+        process.stdout.write(`${JSON.stringify({ ok: false, runId: input.runId, error })}\n`);
+        // The action boundary is best-effort (exit 0); the run-row closure fails loudly (exit 1).
+        return input.close ? 1 : 0;
+    };
+
+    const { entry, repoRoot, chain } = resolveAppEntry(input.spurBin);
+    if (entry === null || repoRoot === null) {
+        return fail(
+            `no monorepo checkout of spur is reachable via ${chain} — the shared trace writer ` +
+                'lives in packages/app (point SPUR_BIN at a repo checkout)',
+        );
+    }
+
+    // Compile-time link (0868 finding #5): the writer half is typed by the real packages/app
+    // export (type-only import, erased at runtime) so a signature drift breaks THIS file's
+    // typecheck instead of hiding behind the hand-declared cast.
+    const app = (await import(entry)) as {
+        openInlineRunProjectDb: (workdir: string) => Promise<{ adapter: unknown; close: () => void }>;
+        createWorkflowActionTraceWriter: (
+            db: unknown,
+            recordFailure?: (failure: unknown) => void,
+        ) => WorkflowActionTraceWriter;
+    };
+
+    let projectDb: { adapter: unknown; close: () => void } | undefined;
+    try {
+        projectDb = await app.openInlineRunProjectDb(process.cwd());
+        const writer = app.createWorkflowActionTraceWriter(projectDb.adapter, (failure: unknown) => {
+            const detail = failure as { operation?: string; error?: string };
+            appendTraceFailureLine(
+                input.runId,
+                `trace-emission-failed operation=${detail.operation ?? operation} run=${input.runId}: ${detail.error ?? 'unknown error'}`,
+            );
+        });
+        const result = (
+            input.close
+                ? await writer.closeRun(input.runId, input.status)
+                : await writer.recordAction({
+                      runId: input.runId,
+                      node: input.node,
+                      kind: input.kind,
+                      status: input.status,
+                      ok: input.ok,
+                      durationMs: input.durationMs,
+                  })
+        ) as Record<string, unknown>;
+        if (result.ok !== true && result.failure !== undefined) {
+            // One stdout shape for emission failures (0868 finding #1): flatten the guard's
+            // nested failure object to the same `{ok, runId, error}` the direct paths emit.
+            const failure = result.failure as { error?: string };
+            return fail(failure.error ?? 'unknown trace emission failure');
+        }
+        process.stdout.write(`${JSON.stringify({ ...result, runId: input.runId })}\n`);
+        return 0;
+    } catch (error) {
+        if (input.close && (error as { name?: string }).name === 'RunRowNotFoundError') {
+            // The run row must exist before --close can mark it terminal (R6); a missing row
+            // is a loud correctness failure, not a best-effort emission failure (finding #4).
+            const message = error instanceof Error ? error.message : String(error);
+            appendTraceFailureLine(input.runId, `trace-close-failed run=${input.runId}: ${message}`);
+            process.stdout.write(
+                `${JSON.stringify({ ok: false, runId: input.runId, error: message, code: 'RUN_NOT_FOUND' })}\n`,
+            );
+            return 1;
+        }
+        return fail(error instanceof Error ? error.message : String(error));
+    } finally {
+        projectDb?.close();
+    }
+}
+
 async function main(): Promise<void> {
     let runId = '';
     let file = '';
     let fingerprint = false;
     let taskFile = '';
     let featureFile = '';
-    let spurBin = process.env.SPUR_BIN ?? '';
+    let action = false;
+    let close = false;
+    let node = '';
+    let kind = '';
+    let status = '';
+    let okRaw = '';
+    let durationRaw = '';
+    let spurBin = getEnvVar('SPUR_BIN') ?? '';
     const argv = process.argv.slice(2);
     for (let i = 0; i < argv.length; i++) {
         if (argv[i] === '--run-id') runId = argv[++i] ?? '';
@@ -191,6 +341,13 @@ async function main(): Promise<void> {
         else if (argv[i] === '--fingerprint') fingerprint = true;
         else if (argv[i] === '--task-file') taskFile = argv[++i] ?? '';
         else if (argv[i] === '--feature-file') featureFile = argv[++i] ?? '';
+        else if (argv[i] === '--action') action = true;
+        else if (argv[i] === '--close') close = true;
+        else if (argv[i] === '--node') node = argv[++i] ?? '';
+        else if (argv[i] === '--kind') kind = argv[++i] ?? '';
+        else if (argv[i] === '--status') status = argv[++i] ?? '';
+        else if (argv[i] === '--ok') okRaw = argv[++i] ?? '';
+        else if (argv[i] === '--duration-ms') durationRaw = argv[++i] ?? '';
         else if (argv[i] === '--spur-bin') spurBin = argv[++i] ?? spurBin;
     }
 
@@ -200,6 +357,42 @@ async function main(): Promise<void> {
         if (runId !== '' || file !== '' || taskFile.trim() === '') usage();
         process.exit(await printFingerprint(taskFile, featureFile, spurBin));
     }
+
+    // ADR-117 emission modes (task 0868): the inline driver reports one completed action
+    // boundary, or closes its run row at the declared terminal state. Both share the run-id
+    // filename guard, the app-entry resolution chain and the best-effort failure contract.
+    if (action || close) {
+        if (action && close) usage();
+        if (runId.trim() === '' || status.trim() === '') usage();
+        if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
+        if (close) {
+            if (!CLOSE_STATUSES.has(status)) usage();
+            process.exit(
+                await runTraceMode({
+                    runId,
+                    close: true,
+                    node: '',
+                    kind: '',
+                    status,
+                    ok: true,
+                    durationMs: 0,
+                    spurBin,
+                }),
+            );
+        }
+        if (node.trim() === '' || kind.trim() === '') usage();
+        if (!ACTION_STATUSES.has(status)) usage();
+        // `--ok` and `--duration-ms` are required and exact for the action mode
+        // (review finding #2): a miscased `--ok True` or an omitted `--duration-ms`
+        // must be a loud usage error, never a silently-defaulted `ok=0` /
+        // `duration_ms=0` row.
+        if (okRaw !== 'true' && okRaw !== 'false') usage();
+        const ok = okRaw === 'true';
+        const durationMs = Number(durationRaw);
+        if (durationRaw.trim() === '' || !Number.isFinite(durationMs) || durationMs < 0) usage();
+        process.exit(await runTraceMode({ runId, close: false, node, kind, status, ok, durationMs, spurBin }));
+    }
+
     if (runId.trim() === '' || file.trim() === '') usage();
     if (!SAFE_RUN_ID_RE.test(runId)) refuseUnsafeRunId(runId);
 

package/plugins/sp/scripts/pr-reviewing.mjs

@@ -5,8 +5,15 @@
 import { spawnSync } from "child_process";
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/pr-reviewing.ts
 var spawnRunner = (cmd) => {
-  const proc = spawnSync(cmd[0] ?? "", [...cmd.slice(1)], { encoding: "utf8", env: process.env });
+  const proc = spawnSync(cmd[0] ?? "", [...cmd.slice(1)], { encoding: "utf8", env: getEnvVars() });
   return {
     code: proc.status ?? 1,
     stdout: proc.stdout ?? "",

package/plugins/sp/scripts/pr-reviewing.ts

@@ -22,6 +22,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -118,7 +119,7 @@ export type CommandRunner = (cmd: readonly string[]) => CmdResult;
 /** Real execution: resolve the binary from PATH and capture its output. The default runner. */
 export const spawnRunner: CommandRunner = (cmd) => {
     // Pass env explicitly so both Node and Bun resolve git/gh against the caller's PATH.
-    const proc = spawnSync(cmd[0] ?? '', [...cmd.slice(1)], { encoding: 'utf8', env: process.env });
+    const proc = spawnSync(cmd[0] ?? '', [...cmd.slice(1)], { encoding: 'utf8', env: getEnvVars() });
     return {
         code: proc.status ?? 1,
         stdout: proc.stdout ?? '',

package/plugins/sp/scripts/quality-gate.mjs

@@ -17,6 +17,13 @@ import {
 } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/quality-gate.ts
 var MAX_GATE_ATTEMPTS = 5;
 var MAX_FINDINGS = 20;
 var RETRY_DELAY_MS_DEFAULT = 1e4;
@@ -178,7 +185,7 @@ function runQualityGate(mode, env, options = {}) {
   return { status, attempts: gateAttempt, logFile, findingsFile, statusFile, attemptFile };
 }
 var QUALITY_GATE_USAGE = "usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)";
-function main(argv, env = process.env) {
+function main(argv, env = getEnvVars()) {
   const mode = argv[0];
   if (mode !== "run" && mode !== "recheck") {
     process.stderr.write(`${QUALITY_GATE_USAGE}

package/plugins/sp/scripts/quality-gate.ts

@@ -41,6 +41,7 @@ import {
 } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 export const MAX_GATE_ATTEMPTS = 5;
 export const MAX_FINDINGS = 20;
@@ -268,7 +269,7 @@ export function runQualityGate(
 export const QUALITY_GATE_USAGE =
     'usage: quality-gate.ts <run|recheck>  (env: wbs, qualityGateCmd, gateProbeCmd, proofDigest)';
 
-export function main(argv: string[], env: QualityGateEnv = process.env): number {
+export function main(argv: string[], env: QualityGateEnv = getEnvVars()): number {
     const mode = argv[0];
     if (mode !== 'run' && mode !== 'recheck') {
         process.stderr.write(`${QUALITY_GATE_USAGE}\n`);

package/plugins/sp/scripts/surface-drift-inventory.ts

@@ -179,9 +179,6 @@ export function parseInvocation(spanRaw: string): Parsed | null {
         }
     }
     if (nouns.length === 0 && verbs.length === 0 && flags.length === 0) return null;
-    if (process.env.DEBUG_SPANS === '1') {
-        process.stderr.write(`SPAN ${JSON.stringify({ spanRaw, nouns, verbs, flags })}\n`);
-    }
     return { nouns, verbs, flags };
 }
 
@@ -638,7 +635,7 @@ const JSON_PROBES: string[][] = [
     ['agent', 'list', '--json'],
     ['agent', 'doctor', 'pi', '--json'],
     ['workflow', 'list', '--json'],
-    ['workflow', 'validate', 'basic.yaml', '--json'],
+    ['workflow', 'validate', 'task-pipeline.yaml', '--json'],
     ['status', '--json'],
     ['projects', 'list', '--json'],
 ];

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

@@ -37,6 +37,7 @@ import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 /** Exact task-content declaration that activates the live-evidence gate (0726 R2). */
 const DECLARATION_PREFIX = 'evidence-channel:';
@@ -58,7 +59,7 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    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}`;
     return 'spur';

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

@@ -19,13 +19,14 @@
  *   bun plugins/sp/scripts/task-size-precheck.ts <wbs> [--spur-bin <path>]
  *     [--max-reqs <n>] [--max-plan-items <n>]
  *
- * Env: SPUR_BIN, MAX_IMPLEMENT_REQS, MAX_IMPLEMENT_PLAN_ITEMS
+ * Env: SPUR_BIN (flags own the size ceilings — env overrides removed, task 0902)
  */
 
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ─── Counting (sync with packages/app/src/services/task-size-precheck.ts) ────
 
@@ -88,7 +89,7 @@ function usage(): never {
  * keeps ad-hoc invocations from silently hitting a stale PATH install.
  */
 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));
@@ -107,8 +108,9 @@ function parseArgs(argv: string[]): {
     // Doubled deterministic ceiling (0723 operator decision): 10 R-items / 16
     // Plan items — keep in sync with DEFAULT_TASK_SIZE_LIMITS in
     // packages/app/src/services/task-size-precheck.ts (asserted by test).
-    let maxReqs = Number(process.env.MAX_IMPLEMENT_REQS) || 10;
-    let maxPlanItems = Number(process.env.MAX_IMPLEMENT_PLAN_ITEMS) || 16;
+    // Overridable per invocation via --max-reqs / --max-plan-items (no env fallback).
+    let maxReqs = 10;
+    let maxPlanItems = 16;
 
     let i = 0;
     while (i < argv.length) {

package/plugins/sp/scripts/verify-answer-lint.ts

@@ -32,6 +32,7 @@
 import { execFileSync } from 'node:child_process';
 import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ─── CLI (same spur-bin chain as task-evidence-precheck.ts) ─────────────────
 
@@ -41,7 +42,7 @@ function usage(): never {
 }
 
 function defaultSpurBin(): string {
-    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}`;
     return 'spur';

package/plugins/sp/scripts/workflow-step-profile.mjs

@@ -5,6 +5,14 @@
 import { spawnSync } from "child_process";
 import { existsSync } from "fs";
 import { fileURLToPath } from "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/workflow-step-profile.ts
 var DEFAULT_LAST = 20;
 var DEFAULT_WINDOW_SEC = 300;
 function nearestRankP50(values) {
@@ -168,8 +176,8 @@ function formatStepProfileHuman(profile) {
 `;
 }
 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/workflow-step-profile.ts

@@ -25,6 +25,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
+import { getEnvVar } from '@gobing-ai/ts-utils';
 
 // ── Input shapes (a subset of the live `spur workflow trace --json` payload) ─────────────
 
@@ -321,7 +322,7 @@ export interface StepProfileCliArgs {
  * --spur-bin > SPUR_BIN > monorepo-local CLI entry > PATH `spur`.
  */
 export function defaultSpurBin(): string {
-    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}`;
     return 'spur';

package/plugins/sp/scripts/wrapup-steps.mjs

@@ -5,6 +5,13 @@
 import { spawnSync } from "child_process";
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+
+// ../ts-libs/packages/utils/dist/env.js
+function getEnvVars() {
+  return process.env;
+}
+
+// plugins/sp/scripts/wrapup-steps.ts
 function jqPick(...values) {
   for (const value of values) {
     if (value !== null && value !== undefined && value !== false)
@@ -319,7 +326,7 @@ function runFeatureTransition(env, options = {}) {
   return { status: syncStatus, statusFile: relStatusFile, exitCode: 0 };
 }
 var WRAPUP_STEPS_USAGE = "usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)";
-function main(argv, env = process.env, options = {}) {
+function main(argv, env = getEnvVars(), options = {}) {
   const sub = argv[0];
   if (sub === "resolve")
     return resolveTasks(env, options).exitCode;

package/plugins/sp/scripts/wrapup-steps.ts

@@ -31,6 +31,7 @@
 import { spawnSync } from 'node:child_process';
 import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { getEnvVars } from '@gobing-ai/ts-utils';
 
 export interface WrapupStepsEnv {
     __runId?: string;
@@ -449,7 +450,7 @@ export function runFeatureTransition(env: WrapupStepsEnv, options: WrapupStepsOp
 export const WRAPUP_STEPS_USAGE =
     'usage: wrapup-steps.ts <resolve|metrics|feature-transition>  (env: __runId, tasks, feature, featureGateCmd, spurBin)';
 
-export function main(argv: string[], env: WrapupStepsEnv = process.env, options: WrapupStepsOptions = {}): number {
+export function main(argv: string[], env: WrapupStepsEnv = getEnvVars(), options: WrapupStepsOptions = {}): number {
     const sub = argv[0];
     if (sub === 'resolve') return resolveTasks(env, options).exitCode;
     if (sub === 'metrics') {

package/plugins/sp/skills/brainstorm/SKILL.md

@@ -197,6 +197,10 @@ When brainstorm runs under `idea-pipeline` discovery, it MUST also emit a filled
 [`spur-dev/references/idea-evaluation.md`](../spur-dev/references/idea-evaluation.md):
 
 - Enhanced idea statement (sidecar — does **not** overwrite the operator's original idea text)
+- **Requirement inventory** — mandatory `## Requirement inventory` section: numbered `I<n>` items
+  quoting or paraphrasing the source lines from the run's verbatim idea artifact
+  (`.spur/run/<run-id>-idea-input.md`, 0887 R1/R3), with `[unclear: ...]` markers where the ask is
+  ambiguous and `[deferred: <reason>]` markers for explicit out-of-scope items
 - Urgency and necessity scores (0–5) with one-line rationales
 - Premises, pros, cons, better alternatives (if any)
 - Recommendation (`proceed` | `reshape` | `drop`) + stakes