dev-loops 0.5.0 → 0.6.0

package/scripts/github/list-issues.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+import { buildParseError, formatCliError, isDirectCliRun, parseJsonText } from "../_core-helpers.mjs";
+import { requireTokenValue, runChild } from "../_cli-primitives.mjs";
+import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+
+const STATES = new Set(["open", "closed", "all"]);
+
+const USAGE = `Usage: list-issues.mjs --repo <owner/name> [--state <open|closed|all>] [--label <l>] [--limit <n>]
+List/filter repository issues. Thin wrapper over \`gh issue list\` — use this instead
+of an agent-level raw \`gh issue list\` so the loop's internal-tooling record stays
+clean (#993). The queue tool lists the project board, not arbitrary issue queries;
+this fills that gap (siblings: comment-issue.mjs, fetch-ci-logs.mjs).
+Required:
+  --repo <owner/name>           Repository slug (e.g. owner/repo)
+Optional:
+  --state <open|closed|all>     Issue state filter (default open)
+  --label <l>                   Filter by label (repeatable; AND-combined by gh)
+  --limit <n>                   Return at most <n> issues (default 30)
+Output (stdout, JSON):
+  { "ok": true, "issues": [{ "number": 17, "title": "...", "state": "open", "labels": ["bug"] }, ...] }
+Error output (stderr, JSON):
+  { "ok": false, "error": "...", "usage"?: "..." }
+${JQ_OUTPUT_USAGE}
+Exit codes:
+  0  Success
+  1  Argument error or gh failure
+  2  Invalid --jq filter`.trim();
+const parseError = buildParseError(USAGE);
+
+export function parseListIssuesCliArgs(argv) {
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      help: { type: "boolean", short: "h" },
+      repo: { type: "string" },
+      state: { type: "string" },
+      label: { type: "string", multiple: true },
+      limit: { type: "string" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+  const options = {
+    help: false,
+    repo: undefined,
+    state: "open",
+    labels: [],
+    limit: 30,
+    jq: undefined,
+    silent: false,
+  };
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    if (token.name === "help") {
+      options.help = true;
+      return options;
+    }
+    if (token.name === "repo") {
+      options.repo = requireTokenValue(token, parseError).trim();
+      continue;
+    }
+    if (token.name === "state") {
+      const state = requireTokenValue(token, parseError).trim().toLowerCase();
+      if (!STATES.has(state)) {
+        throw parseError("--state must be one of: open, closed, all");
+      }
+      options.state = state;
+      continue;
+    }
+    if (token.name === "label") {
+      const label = requireTokenValue(token, parseError).trim();
+      if (label.length === 0) {
+        throw parseError("--label must be a non-empty string");
+      }
+      options.labels.push(label);
+      continue;
+    }
+    if (token.name === "limit") {
+      const raw = requireTokenValue(token, parseError);
+      const value = Number(raw);
+      if (!Number.isInteger(value) || value < 1) {
+        throw parseError(`--limit must be a positive integer, got "${raw}"`);
+      }
+      options.limit = value;
+      continue;
+    }
+    if (token.name === "jq") {
+      options.jq = requireTokenValue(token, parseError);
+      continue;
+    }
+    if (token.name === "silent") {
+      options.silent = true;
+      continue;
+    }
+    throw parseError(`Unknown argument: ${token.rawName}`);
+  }
+  if (options.repo === undefined) {
+    throw parseError("Listing issues requires --repo <owner/name>");
+  }
+  try {
+    parseRepoSlug(options.repo);
+  } catch (error) {
+    throw parseError(error instanceof Error ? error.message : String(error));
+  }
+  return options;
+}
+
+// Returns a well-typed issue, or null if the gh entry is missing/invalid in any
+// required field. Callers filter the nulls so the emitted shape stays
+// well-typed (documented output) and --jq filters never hit null number/title/state.
+function normalizeIssue(raw) {
+  if (!Number.isInteger(raw?.number) || typeof raw?.title !== "string" || typeof raw?.state !== "string") {
+    return null;
+  }
+  return {
+    number: raw.number,
+    title: raw.title,
+    // gh reports issue state UPPERCASE (OPEN/CLOSED); normalize to lowercase to
+    // match the --state flag vocabulary.
+    state: raw.state.toLowerCase(),
+    labels: Array.isArray(raw?.labels)
+      ? raw.labels.map((l) => (typeof l?.name === "string" ? l.name : null)).filter((n) => n !== null)
+      : [],
+  };
+}
+
+export async function listIssues(options, { env = process.env, ghCommand = "gh", run = runChild } = {}) {
+  const args = [
+    "issue",
+    "list",
+    "--repo",
+    options.repo,
+    "--state",
+    options.state,
+    "--limit",
+    String(options.limit),
+    "--json",
+    "number,title,state,labels",
+  ];
+  for (const label of options.labels) {
+    args.push("--label", label);
+  }
+  const result = await run(ghCommand, args, env);
+  if (result.code !== 0) {
+    const detail = result.stderr.trim() || `exit code ${result.code}`;
+    throw new Error(`gh issue list failed: ${detail}`);
+  }
+  const payload = parseJsonText(result.stdout, { label: "gh issue list" });
+  if (!Array.isArray(payload)) {
+    throw new Error("gh issue list did not return a JSON array");
+  }
+  return { ok: true, issues: payload.map(normalizeIssue).filter((issue) => issue !== null) };
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  { stdout = process.stdout, stderr = process.stderr, env = process.env, ghCommand = "gh", run = runChild } = {},
+) {
+  let options;
+  try {
+    options = parseListIssuesCliArgs(argv);
+  } catch (error) {
+    stderr.write(`${formatCliError(error)}\n`);
+    return 1;
+  }
+  if (options.help) {
+    stdout.write(`${USAGE}\n`);
+    return 0;
+  }
+  let result;
+  try {
+    result = await listIssues(options, { env, ghCommand, run });
+  } catch (error) {
+    stderr.write(`${JSON.stringify({ ok: false, error: error instanceof Error ? error.message : String(error) })}\n`);
+    return 1;
+  }
+  return emitResult(result, { jq: options.jq, silent: options.silent, stdout, stderr });
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli().then((code) => { process.exitCode = code; });
+}

package/scripts/loop/_handoff-contract.mjs

@@ -28,6 +28,7 @@ const SUBAGENT_ACTIONS = new Set([
   "request_review",
   "rerequest_review",
   "run_pre_approval",
+  "run_ui_e2e",
 ]);
 function normalizeContractValue(value) {
   return typeof value === "string" ? value.trim().toLowerCase() : null;

package/scripts/loop/detect-pr-gate-coordination-state.mjs

@@ -17,6 +17,7 @@ import { parseRepoSlug } from "@dev-loops/core/github/repo-slug";
 import { buildSnapshotFromPrFacts, interpretLoopState, summarizeLoopInterpretation } from "@dev-loops/core/loop/copilot-loop-state";
 import { evaluatePrGateCoordination, PR_CHECKPOINT, PR_CHECKPOINT_ACTION } from "@dev-loops/core/loop/pr-gate-coordination";
 import { shouldGuardCopilotReviewRequest } from "@dev-loops/core/loop/pr-gate-coordination";
+import { UI_E2E_CHECK_NAMES } from "@dev-loops/core/loop/ui-e2e-scoping";
 import { fetchGithubReviewThreadsPayload } from "../github/capture-review-threads.mjs";
 import { detectCheckpointEvidence } from "../github/detect-checkpoint-evidence.mjs";
 import { parseArgs } from "node:util";
@@ -163,7 +164,7 @@ async function fetchRequestedReviewers({ repo, pr }, { env = process.env, ghComm
 async function fetchPrFacts({ repo, pr }, { env = process.env, ghCommand = "gh" } = {}) {
   const result = await runChild(
     ghCommand,
-    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup"],
+    ["pr", "view", String(pr), "--repo", repo, "--json", "number,state,isDraft,headRefOid,mergeable,mergeStateStatus,body,title,closingIssuesReferences,reviews,statusCheckRollup,files"],
     env,
   );
   if (result.code !== 0) {
@@ -198,6 +199,32 @@ export async function fetchPrFactsWithSettledMergeable(
   }
   return prData;
 }
+// Changed-file paths from `gh pr view --json files` (issue #976). Feeds the
+// path-triggered UI e2e scoping precondition in the evaluator.
+export function extractChangedFiles(prData) {
+  const files = Array.isArray(prData?.files) ? prData.files : [];
+  return files
+    .map((entry) => (typeof entry?.path === "string" ? entry.path : null))
+    .filter((p) => typeof p === "string" && p.length > 0);
+}
+
+// Whether the shared UI e2e suite passed for this head, read deterministically
+// from the statusCheckRollup: every UI e2e check that is present must be
+// SUCCESS. Returns null when no UI e2e check is present in the rollup (unknown
+// → the evaluator fails closed), false if any present UI e2e check is not a
+// success, true if all present ones succeeded.
+export function deriveUiE2ePassed(prData, checkNames = UI_E2E_CHECK_NAMES) {
+  const rollup = Array.isArray(prData?.statusCheckRollup) ? prData.statusCheckRollup : [];
+  const wanted = new Set(checkNames);
+  const present = rollup.filter((entry) => wanted.has(entry?.name) || wanted.has(entry?.context));
+  if (present.length === 0) return null;
+  return present.every((entry) => {
+    const conclusion = String(entry?.conclusion ?? "").toUpperCase();
+    const state = String(entry?.state ?? "").toUpperCase();
+    return conclusion === "SUCCESS" || state === "SUCCESS";
+  });
+}
+
 export function resolveLinkedIssueFromPr(prData) {
   if (!prData || typeof prData !== "object") return null;
   const closing = Array.isArray(prData.closingIssuesReferences) ? prData.closingIssuesReferences : [];
@@ -439,6 +466,9 @@ export async function detectPrGateCoordinationState(options, runtime = {}) {
     mergeStateStatus: context.mergeStateStatus,
     mergeable: context.mergeable,
     conflictFiles: context.conflictFiles,
+    // UI e2e auto-scoping (#976): path-triggered + fail-closed precondition.
+    changedFiles: extractChangedFiles(context.prData),
+    uiE2ePassed: deriveUiE2ePassed(context.prData),
     lifecycleState: context.interpretation.state,
     loopDisposition: context.disposition.loopDisposition,
     ciStatus: context.snapshot?.ciStatus ?? null,

package/scripts/loop/run-conductor-cycle.mjs

@@ -32,11 +32,16 @@ export const CHECKPOINT_ACTION_TO_CONDUCTOR_ACTION = Object.freeze({
   [PR_CHECKPOINT_ACTION.DECLARE_MERGE_READY]: "merge",
   [PR_CHECKPOINT_ACTION.AWAIT_FINAL_HUMAN_APPROVAL]: "await_approval",
   [PR_CHECKPOINT_ACTION.RESOLVE_MERGE_CONFLICTS]: "resolve_conflicts",
+  [PR_CHECKPOINT_ACTION.RUN_UI_E2E_SUITE]: "run_ui_e2e",
   [PR_CHECKPOINT_ACTION.REPORT_BLOCKED]: "blocked",
   [PR_CHECKPOINT_ACTION.REPORT_DONE]: "done",
 });
 export const ACTION_PRIORITY = Object.freeze({
   merge: 100,
+  // UI e2e auto-scoping fix work (#976): a path-triggered, fail-closed
+  // precondition — surface it ahead of feedback/draft work so the rendered
+  // artifact gets registered + covered before the gate proceeds.
+  run_ui_e2e: 95,
   fix_threads: 90,
   run_pre_approval: 80,
   draft_gate: 70,

package/scripts/projects/resolve-active-board-item.mjs

@@ -0,0 +1,193 @@
+#!/usr/bin/env node
+// Collapse the board's "In Progress" column to a SINGLE continue target (#988 P1).
+//
+// Pure list->single-target collapse with NO routing opinions: it lists the
+// In-Progress items via list-queue-items.mjs and either returns the lone target
+// or FAILS CLOSED. It never guesses among multiple active items.
+//
+//   exactly one  -> { ok: true, target: { kind: "issue"|"pr", number } }
+//   zero         -> { ok: false, reason: "..." }  (no in-progress item)
+//   multiple     -> { ok: false, reason: "..." }  (names the items)
+//
+// Downstream (the dev-loop skill) resolves authoritative state from this number;
+// this helper deliberately makes no further decisions.
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { parseArgs } from "node:util";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { main as listQueueItems } from "./list-queue-items.mjs";
+
+const IN_PROGRESS_COLUMN = "In Progress";
+
+const USAGE = `Usage: dev-loops queue resolve-active --repo <owner/name> --project <number|id>
+
+Collapse the board's "${IN_PROGRESS_COLUMN}" column to a single continue target.
+Used by bare \`/continue\` to pick up the one in-progress item. Fails closed
+(no guessing) when the board has zero or more than one in-progress item.
+
+Options:
+  --repo <owner/name>     Required. Repository to scope the project search.
+  --project <number|id>   Required. Project number (integer) or node ID.
+  --help, -h              Show this help.
+
+Output (stdout):
+  JSON, exactly one in-progress item:
+    { ok: true, target: { kind: "issue"|"pr", number } }
+  JSON, zero or multiple (fail closed):
+    { ok: false, reason: "..." }
+
+${JQ_OUTPUT_USAGE}
+
+Exit codes (default / unfiltered output):
+  0 — exactly one in-progress item resolved
+  1 — usage or argument error
+  2 — GitHub API error / invalid --jq filter
+  3 — fail closed (pass an explicit issue/PR): zero or multiple in-progress
+      items, or the board/project could not be resolved (project, status
+      field, or "${IN_PROGRESS_COLUMN}" column not found)
+
+With --jq/--silent the result is filtered to a value/predicate, so the exit code
+follows the shared jq-output contract (0 = truthy/ok, 1 = falsy/non-ok, 2 =
+invalid filter) — fail closed surfaces as a falsy \`.ok\`, i.e. exit 1, not 3.
+`.trim();
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      repo: { type: "string" },
+      project: { type: "string" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        if (token.value !== undefined) {
+          throw parseError(`Unknown flag: ${token.rawName}=${token.value}`);
+        }
+        args.help = true;
+        break;
+      case "repo":
+        args.repo = requireValue(token, "--repo requires a value (owner/name)");
+        break;
+      case "project":
+        args.project = requireValue(token, "--project requires a value (number or node ID)");
+        break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
+    }
+  }
+  return args;
+}
+
+function describeItem(item) {
+  const ref = item.prNumber != null ? `PR #${item.prNumber}` : `issue #${item.issueNumber}`;
+  return item.title ? `${ref} (${item.title})` : ref;
+}
+
+// Collapse a list of board items to a single continue target. Prefer the linked
+// PR number when present (the canonical artifact once work is in flight), else
+// the issue. No routing opinion beyond that single pick.
+function collapseToTarget(items) {
+  if (items.length === 0) {
+    return {
+      ok: false,
+      reason: `No in-progress board item to continue. Pass an explicit issue/PR, e.g. \`/continue #N\`.`,
+    };
+  }
+  if (items.length > 1) {
+    const listed = items.map(describeItem).join(", ");
+    return {
+      ok: false,
+      reason: `${items.length} in-progress board items: ${listed}. Pass an explicit issue/PR to disambiguate, e.g. \`/continue #N\`.`,
+    };
+  }
+  const item = items[0];
+  const target = item.prNumber != null
+    ? { kind: "pr", number: item.prNumber }
+    : { kind: "issue", number: item.issueNumber };
+  return { ok: true, target };
+}
+
+async function main(args, { env = process.env, runChild } = {}) {
+  const listed = await listQueueItems(
+    { repo: args.repo, project: args.project, column: IN_PROGRESS_COLUMN },
+    { env, runChild },
+  );
+  return collapseToTarget(listed.items ?? []);
+}
+
+function classifyExitCode(err) {
+  if (err.code === "INVALID_ARGS" || err.code === "INVALID_REPO" || err.code === "INVALID_PROJECT") return 1;
+  if (err.code === "PROJECT_NOT_FOUND" || err.code === "FIELD_NOT_FOUND" || err.code === "COLUMN_NOT_FOUND") return 3;
+  return 2;
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr, env = process.env, runChild } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(USAGE);
+    return;
+  }
+  try {
+    const result = await main(args, { env, runChild });
+    // Fail closed (zero/multiple) is a clean, expected outcome — distinct exit code 3,
+    // not a crash; --jq/--silent still apply so callers can probe `.ok`.
+    process.exitCode = emitResult(result, {
+      jq: args.jq,
+      silent: args.silent,
+      stdout,
+      stderr,
+      ok: result.ok,
+    });
+    if (result.ok !== true && args.jq === undefined && !args.silent) {
+      process.exitCode = 3;
+    }
+  } catch (err) {
+    stderr.write(JSON.stringify({ ok: false, error: err.message, code: err.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = classifyExitCode(err);
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(JSON.stringify({ ok: false, error: error.message, code: error.code ?? "UNKNOWN" }) + "\n");
+    process.exitCode = 2;
+  });
+}
+
+export { main, collapseToTarget, runCli };

package/scripts/refine/scaffold-spike-file.mjs

@@ -0,0 +1,183 @@
+#!/usr/bin/env node
+// Scaffold a STARTABLE spike findings artifact from an inline question (#988 P2).
+//
+// `/start-spike <question>` needs a findings artifact that passes
+// `validateSpikeExplorationSections` (non-empty Question/Approach/Findings) so
+// `resolve-dev-loop-startup --spike <path>` accepts it. This is the only new
+// piece behind /start-spike: a pure section builder + a thin file writer. The
+// Recommendation is left for the spike to fill in (the exit marker), matching
+// the spike-mode contract — so this scaffolds an in-progress spike, not a
+// ready-for-exit one. No new spike behavior; the intake/gate/exit machinery is
+// the shipped #964/#965/#966 surface.
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseArgs } from "node:util";
+
+import { formatCliError, isDirectCliRun } from "../_core-helpers.mjs";
+import { JQ_OUTPUT_PARSE_OPTIONS, JQ_OUTPUT_USAGE, emitResult } from "../lib/jq-output.mjs";
+import { SPIKE_FILE_EXPLORATION_SECTIONS } from "./validate-spike-file.mjs";
+
+// Placeholder bodies the operator fills in during the spike. Non-empty so the
+// exploration scaffold validates; explicitly marked TBD so they are obviously
+// stubs, not findings. (`Recommendation` is intentionally omitted — it is the
+// exit marker, written when the spike concludes.)
+const PLACEHOLDER = "TBD — filled in during the spike.";
+
+const USAGE = `Usage:
+  scaffold-spike-file.mjs --question <text> --out <path>
+
+Scaffold a startable spike findings artifact from an inline question. Writes a
+file carrying the exploration scaffold (## Question filled from --question,
+## Approach/## Findings stubbed) so \`resolve-dev-loop-startup --spike <path>\`
+accepts it. The ## Recommendation is left for the spike to fill in.
+
+Options:
+  --question <text>   Required. The question the spike investigates.
+  --out <path>        Required. Where to write the findings artifact.
+  --help, -h          Show this help.
+
+Output (stdout):
+  JSON: { ok: true, path: "<abs>", question: "<text>" }
+
+${JQ_OUTPUT_USAGE}
+`.trim();
+
+// Pure builder: question text -> a findings-artifact markdown body carrying the
+// exploration scaffold. Question gets the operator's text; Approach/Findings get
+// non-empty placeholder bodies so the exploration scaffold validates.
+export function buildSpikeScaffold(question) {
+  const trimmed = String(question ?? "").trim();
+  if (trimmed.length === 0) {
+    throw Object.assign(new Error("--question must be non-empty"), { code: "INVALID_ARGS" });
+  }
+  const bodies = { Question: trimmed, Approach: PLACEHOLDER, Findings: PLACEHOLDER };
+  const sections = SPIKE_FILE_EXPLORATION_SECTIONS.map(
+    (heading) => `## ${heading}\n\n${bodies[heading]}\n`,
+  );
+  return `# Spike\n\n${sections.join("\n")}`;
+}
+
+function parseCliArgs(argv) {
+  const parseError = (message) => Object.assign(new Error(message), { usage: USAGE, code: "INVALID_ARGS" });
+  const requireValue = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("-")) {
+      throw parseError(message);
+    }
+    return v;
+  };
+  // The question is free text embedded in the artifact body, never forwarded as
+  // a CLI option — so unlike --out/--jq it may legitimately begin with `-`
+  // (e.g. "- should we ...?"). Only require a non-empty value, matching the
+  // core free-text parser; leave the leading-`-` guard to the path/filter flags.
+  const requireQuestion = (token, message) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0) {
+      throw parseError(message);
+    }
+    return v;
+  };
+
+  const args = {};
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      question: { type: "string" },
+      out: { type: "string" },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      ...JQ_OUTPUT_PARSE_OPTIONS,
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw parseError(`Unexpected argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "help":
+        args.help = true;
+        break;
+      case "json":
+        // Output is JSON by default; accepted as a no-op for callers that pass it.
+        break;
+      case "question":
+        args.question = requireQuestion(token, "--question requires a value");
+        break;
+      case "out":
+        args.out = requireValue(token, "--out requires a value (path)");
+        break;
+      case "jq":
+        args.jq = requireValue(token, "--jq requires a filter");
+        break;
+      case "silent":
+        args.silent = true;
+        break;
+      default:
+        throw parseError(`Unknown flag: ${token.rawName}`);
+    }
+  }
+  return args;
+}
+
+export async function main(args, { writeFileImpl = writeFile, mkdirImpl = mkdir } = {}) {
+  if (!args.question) {
+    throw Object.assign(new Error("--question is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  if (!args.out) {
+    throw Object.assign(new Error("--out is required"), { usage: USAGE, code: "INVALID_ARGS" });
+  }
+  const body = buildSpikeScaffold(args.question);
+  const outPath = path.resolve(args.out);
+  await mkdirImpl(path.dirname(outPath), { recursive: true });
+  // Fail closed on an existing file: the slash-command picks a fresh path and
+  // must never clobber a spike already in progress. `wx` makes write+exclusive
+  // atomic, so a concurrent create still loses (no overwrite).
+  try {
+    await writeFileImpl(outPath, body, { encoding: "utf8", flag: "wx" });
+  } catch (err) {
+    if (err?.code === "EEXIST") {
+      throw Object.assign(new Error(`--out already exists, refusing to overwrite: ${outPath}`), {
+        usage: USAGE,
+        code: "INVALID_ARGS",
+      });
+    }
+    throw err;
+  }
+  return { ok: true, path: outPath, question: String(args.question).trim() };
+}
+
+async function runCli(argv, { stdout = process.stdout, stderr = process.stderr } = {}) {
+  let args;
+  try {
+    args = parseCliArgs(argv);
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (args.help) {
+    stdout.write(`${USAGE}\n`);
+    return;
+  }
+  try {
+    const result = await main(args);
+    process.exitCode = emitResult(result, { jq: args.jq, silent: args.silent, stdout, stderr });
+  } catch (err) {
+    stderr.write(`${formatCliError(err)}\n`);
+    process.exitCode = err.code === "INVALID_ARGS" ? 1 : 2;
+  }
+}
+
+if (isDirectCliRun(import.meta.url)) {
+  runCli(process.argv.slice(2)).catch((error) => {
+    process.stderr.write(`${formatCliError(error)}\n`);
+    process.exitCode = 2;
+  });
+}