android2harmony 0.1.6 → 0.1.8

package/skills/a2h-app-req-gen/scripts/reqgen/src/agent-render/cli.js

@@ -0,0 +1,811 @@
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { buildNameTraceEntries } from "../analysis/names/index.js";
+import {
+  ensureOutputDirectoryEmpty,
+  OutputDirectoryNotEmptyError,
+} from "../core/output-guard.js";
+import { renderReqDraft } from "../generation/index.js";
+import {
+  GenerationError,
+  filterRenderableAreas,
+  loadStage2AreaGraph,
+  loadStage2GapAudit,
+  loadStage2InputWithReport,
+  sortAreasReachableFirst,
+} from "../stage2-input.js";
+import { loadStage2NameTraceabilityInput } from "../stage2-name-trace-input.js";
+import {
+  createClaudeBackend,
+  createCommandBackend,
+  createOpencodeBackend,
+} from "./backend.js";
+import { linkGapAuditToReqModel } from "./gap-audit-link.js";
+import {
+  mergeAreaReqMarkdown,
+  mergeAreaReqTxt,
+  mergeReqMarkdown,
+  mergeReqTxt,
+} from "./merge.js";
+import { buildNameTraceLookup } from "./name-trace.js";
+import {
+  defaultCheckScriptPath,
+  expandAreaRenderItems,
+  expandRenderItems,
+  prepareAreaInputs,
+  prepareFeatureInputs,
+  renderAllAreas,
+  renderAllAreasUnified,
+  renderAllFeatures,
+  renderAllFeaturesUnified,
+  writeRenderList,
+} from "./orchestrate.js";
+// overviewQuoteCheck is kept in overview.ts for programmatic use by other modules
+import { runPostMergeAudit } from "./post-merge-fix.js";
+import { exportSpecHandoff } from "../spec-handoff.js";
+import {
+  snapshotAreaReq,
+  snapshotAreaReqTxt,
+  snapshotReq,
+  snapshotReqTxt,
+  writeReqTxtFiles,
+} from "./snapshot.js";
+class AgentUsageError extends Error {}
+function parseMode(value) {
+  if (value === undefined) return "subagent";
+  if (value === "subagent" || value === "shell" || value === "shell-legacy")
+    return value;
+  throw new AgentUsageError(
+    `--mode must be "subagent", "shell", or "shell-legacy", got ${value}`,
+  );
+}
+const agentValueOptions = new Set([
+  "input",
+  "output",
+  "resume",
+  "mode",
+  "project-root",
+  "backend",
+  "agent-name",
+  "ai-command",
+  "spec-output",
+  "concurrency",
+  "max-retries",
+  "backoff-ms",
+]);
+function takeValue(args, index, name, inline) {
+  const value = inline ?? args[index + 1];
+  if (
+    value === undefined ||
+    value.trim().length === 0 ||
+    (inline === undefined && value.startsWith("--"))
+  ) {
+    throw new AgentUsageError(`Option requires a value: --${name}`);
+  }
+  return value;
+}
+function positiveInteger(value, name) {
+  const result = Number(value);
+  if (!Number.isSafeInteger(result) || result <= 0) {
+    throw new AgentUsageError(
+      `--${name} must be a positive integer, got ${value}`,
+    );
+  }
+  return result;
+}
+export function parseAgentArguments(args) {
+  const normalized = args[0] === "--" ? args.slice(1) : args;
+  const values = new Map();
+  let snapshot = false;
+  let perFeature = false;
+  let withUnreachableArea = false;
+  let noAuditFix = false;
+  for (let index = 0; index < normalized.length; index += 1) {
+    const token = normalized[index];
+    if (token === "--snapshot") {
+      if (snapshot)
+        throw new AgentUsageError("--snapshot may be provided once");
+      snapshot = true;
+      continue;
+    }
+    if (token === "--per-feature") {
+      if (perFeature)
+        throw new AgentUsageError("--per-feature may be provided once");
+      perFeature = true;
+      continue;
+    }
+    if (token === "--with-unreachable-area") {
+      if (withUnreachableArea) {
+        throw new AgentUsageError(
+          "--with-unreachable-area may be provided once",
+        );
+      }
+      withUnreachableArea = true;
+      continue;
+    }
+    if (token === "--no-audit-fix") {
+      if (noAuditFix)
+        throw new AgentUsageError("--no-audit-fix may be provided once");
+      noAuditFix = true;
+      continue;
+    }
+    if (!token.startsWith("--")) {
+      throw new AgentUsageError(`Unexpected argument: ${token}`);
+    }
+    const separator = token.indexOf("=");
+    const name = token.slice(2, separator === -1 ? undefined : separator);
+    if (!agentValueOptions.has(name)) {
+      throw new AgentUsageError(`Unknown option: --${name}`);
+    }
+    if (values.has(name)) {
+      throw new AgentUsageError(`Option may be provided once: --${name}`);
+    }
+    const inline = separator === -1 ? undefined : token.slice(separator + 1);
+    values.set(name, takeValue(normalized, index, name, inline));
+    if (inline === undefined) index += 1;
+  }
+  const input = values.get("input");
+  if (input === undefined) {
+    throw new AgentUsageError("Missing required option: --input");
+  }
+  const inputDirectory = resolve(input);
+  const mode = parseMode(values.get("mode"));
+  const resume = values.has("resume");
+  if (resume && values.has("output")) {
+    throw new AgentUsageError("--resume cannot be combined with --output");
+  }
+  if (resume && mode !== "shell") {
+    throw new AgentUsageError("--resume requires --mode shell");
+  }
+  if (resume && snapshot) {
+    throw new AgentUsageError("--resume cannot be combined with --snapshot");
+  }
+  const outputExplicit = values.has("output");
+  return {
+    inputDirectory,
+    outputDirectory: resume
+      ? resolve(values.get("resume"))
+      : outputExplicit
+        ? resolve(values.get("output"))
+        : join(inputDirectory, "generation"),
+    projectRoot: values.has("project-root")
+      ? resolve(values.get("project-root"))
+      : undefined,
+    mode,
+    backendName: values.get("backend") ?? "claude",
+    agentName: values.get("agent-name") ?? "reqgen-renderer",
+    aiCommand: values.get("ai-command"),
+    specOutputDirectory: values.has("spec-output")
+      ? resolve(values.get("spec-output"))
+      : undefined,
+    concurrency: values.has("concurrency")
+      ? positiveInteger(values.get("concurrency"), "concurrency")
+      : 8,
+    maxRetries: values.has("max-retries")
+      ? positiveInteger(values.get("max-retries"), "max-retries")
+      : 5,
+    backoffMs: values.has("backoff-ms")
+      ? positiveInteger(values.get("backoff-ms"), "backoff-ms")
+      : 5000,
+    snapshot,
+    perFeature,
+    withUnreachableArea,
+    noAuditFix,
+    outputExplicit,
+    resume,
+  };
+}
+function buildBackend(options) {
+  if (options.aiCommand !== undefined) {
+    return createCommandBackend(options.aiCommand);
+  }
+  if (options.backendName === "claude") {
+    return createClaudeBackend({ legacy: options.mode === "shell-legacy" });
+  }
+  if (options.backendName === "opencode") {
+    return createOpencodeBackend();
+  }
+  throw new AgentUsageError(
+    `Unknown backend: ${options.backendName} (use --ai-command for custom backends)`,
+  );
+}
+function summary(status, options, totalAreas, totalFeatures, aiRendered) {
+  return JSON.stringify(
+    {
+      status,
+      output: options.outputDirectory,
+      renderDir: join(options.outputDirectory, "rendering"),
+      totalAreas,
+      totalFeatures,
+      aiRendered,
+      fallback: totalFeatures - aiRendered,
+    },
+    null,
+    2,
+  );
+}
+function aiRenderedCountArea(results) {
+  let aiRendered = 0;
+  for (const areaResult of results.values()) {
+    if (areaResult.status !== "ok") continue;
+    for (const featureResult of areaResult.features.values()) {
+      if (featureResult.status === "ok" && featureResult.body !== undefined) {
+        aiRendered += 1;
+      }
+    }
+  }
+  return aiRendered;
+}
+function aiRenderedCountFeature(results) {
+  let aiRendered = 0;
+  for (const result of results.values()) {
+    if (result.status === "ok" && result.body !== undefined) aiRendered += 1;
+  }
+  return aiRendered;
+}
+/** Recomputed via renderReqDraft (Stage 1's deterministic layer, unchanged)
+ * rather than reading generation/req.md off disk — the merge template
+ * is then always hash-verified against this run's req-model/area-graph
+ * instead of trusting a plain text file that could be stale or hand-edited.
+ * The Agent-rendered output still overwrites req.md in the end. */
+async function loadTemplate(inputDirectory, report, fullReqModel) {
+  const graph = await loadStage2AreaGraph(inputDirectory, report, fullReqModel);
+  return renderReqDraft(fullReqModel, graph);
+}
+// runPostMergeAudit is in post-merge-fix.ts
+async function runSnapshot(options, io) {
+  const { reqModel: loadedReqModel, report } = await loadStage2InputWithReport(
+    options.inputDirectory,
+  );
+  const sortedReqModel = sortAreasReachableFirst(loadedReqModel);
+  const reqModel = filterRenderableAreas(sortedReqModel);
+  const renderDir = join(options.outputDirectory, "rendering");
+  // Always produce both formats: req.md (markdown) + req-{idx}.txt (plain text).
+  const templateText = await loadTemplate(
+    options.inputDirectory,
+    report,
+    reqModel,
+  );
+  const graph = await loadStage2AreaGraph(
+    options.inputDirectory,
+    report,
+    reqModel,
+  );
+  if (options.perFeature) {
+    const mergeOptions = {
+      includeUnreachableAreas: options.withUnreachableArea,
+    };
+    const mdResult = await snapshotReq(
+      reqModel,
+      reqModel,
+      renderDir,
+      options.outputDirectory,
+      templateText,
+      mergeOptions,
+    );
+    const txtResult = await snapshotReqTxt(
+      reqModel,
+      reqModel,
+      graph,
+      renderDir,
+      options.outputDirectory,
+      mergeOptions,
+    );
+    io.stdout(
+      JSON.stringify(
+        {
+          status: "ok",
+          md: mdResult,
+          txt: txtResult,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  } else {
+    const mergeOptions = {
+      includeUnreachableAreas: options.withUnreachableArea,
+    };
+    const mdResult = await snapshotAreaReq(
+      reqModel,
+      reqModel,
+      renderDir,
+      options.outputDirectory,
+      templateText,
+      mergeOptions,
+    );
+    const txtResult = await snapshotAreaReqTxt(
+      reqModel,
+      reqModel,
+      graph,
+      renderDir,
+      options.outputDirectory,
+      mergeOptions,
+    );
+    io.stdout(
+      JSON.stringify(
+        {
+          status: "ok",
+          md: mdResult,
+          txt: txtResult,
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+  }
+  await runRequestedSpecHandoff(options, io);
+  return 0;
+}
+/** Export only when the caller explicitly asks for it.  Keeping this opt-in
+ * preserves the existing Stage 2 output layout while allowing a single
+ * Stage 2 invocation to hand its result directly to `$a2h-spec-generate`. */
+async function runRequestedSpecHandoff(options, io) {
+  if (options.specOutputDirectory === undefined) return;
+  const result = await exportSpecHandoff({
+    inputDirectory: options.inputDirectory,
+    stage2Directory: options.outputDirectory,
+    outputDirectory: options.specOutputDirectory,
+    mode: options.perFeature ? "feature" : "area",
+    includeUnreachableAreas: options.withUnreachableArea,
+    // The Stage 2 output directory is an explicitly selected generated path;
+    // refreshing its handoff is safe and avoids stale page batches on resume.
+    replace: true,
+  });
+  io.stdout(
+    `${JSON.stringify(
+      {
+        status: "spec-handoff",
+        outputDirectory: result.outputDirectory,
+        manifestPath: result.manifestPath,
+        batches: result.manifest.batches.length,
+        requirements: result.manifest.batches.reduce(
+          (sum, batch) => sum + batch.requirementCount,
+          0,
+        ),
+        warnings: result.manifest.warnings,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+}
+async function loadGapAuditLinks(inputDirectory, report, fullReqModel) {
+  const gapAudit = await loadStage2GapAudit(
+    inputDirectory,
+    report,
+    fullReqModel,
+  );
+  return linkGapAuditToReqModel(fullReqModel, gapAudit);
+}
+/** Absent when the Stage 1 run predates source-facts.json/area-graph.json;
+ * the Agent then degrades to blind exploration for everyone. */
+async function loadNameTrace(inputDirectory, reqModel) {
+  const input = await loadStage2NameTraceabilityInput(inputDirectory, reqModel);
+  if (input === undefined) return undefined;
+  return buildNameTraceLookup(buildNameTraceEntries({ ...input, reqModel }));
+}
+/** `reqModel` (post-filterRenderableAreas) decides what gets sent to the
+ * Agent; `fullReqModel` must be the same, unfiltered req-model templateText
+ * was rendered from, so the merge walk's Area/Feature positions line up with
+ * the template text — filtering some Areas out of rendering must not desync
+ * it from the template it is walking. */
+async function runRenderPerFeature(
+  reqModel,
+  fullReqModel,
+  options,
+  io,
+  templateText,
+  graph,
+  nameTrace,
+  gapAuditLinks,
+  backend,
+  renderDir,
+  analysisMode,
+  unified,
+) {
+  const items = expandRenderItems(reqModel);
+  const totalAreas = reqModel.areas.length;
+  const totalFeatures = items.length;
+  const results = new Map();
+  let interrupted = false;
+  process.once("SIGINT", () => {
+    interrupted = true;
+    io.stdout(
+      summary(
+        "interrupted",
+        options,
+        totalAreas,
+        totalFeatures,
+        aiRenderedCountFeature(results),
+      ) + "\n",
+    );
+    process.exit(0);
+  });
+  const agentOpts = {
+    backend,
+    projectRoot: options.projectRoot,
+    inputDirectory: options.inputDirectory,
+    outputDirectory: options.outputDirectory,
+    analysisMode,
+    launchMode: options.mode,
+    renderDir,
+    agentName: options.agentName,
+    concurrency: options.concurrency,
+    maxRetries: options.maxRetries,
+    backoffMs: options.backoffMs,
+    nameTrace,
+    gapAuditLinks,
+    noAuditFix: options.noAuditFix,
+    resume: options.resume,
+  };
+  const rendered = unified
+    ? await renderAllFeaturesUnified(items, reqModel, agentOpts)
+    : await renderAllFeatures(items, reqModel, agentOpts);
+  for (const [id, result] of rendered) results.set(id, result);
+  if (!interrupted) {
+    // Always write both formats: req.md (markdown) + req-{idx}.txt (plain text).
+    const mergeOptions = {
+      includeUnreachableAreas: options.withUnreachableArea,
+    };
+    const mdText = mergeReqMarkdown(
+      fullReqModel,
+      reqModel,
+      results,
+      templateText,
+      mergeOptions,
+    );
+    const txtAreas = mergeReqTxt(
+      fullReqModel,
+      reqModel,
+      results,
+      graph,
+      mergeOptions,
+    );
+    await writeFile(join(options.outputDirectory, "req.md"), mdText, "utf8");
+    await writeReqTxtFiles(options.outputDirectory, txtAreas);
+    // Post-merge audit + optional fix agent (shell / shell-legacy modes)
+    if (!options.noAuditFix) {
+      await runPostMergeAudit(
+        join(options.outputDirectory, "req.md"),
+        options.inputDirectory,
+        options.outputDirectory,
+        options.mode,
+        io,
+      );
+    }
+    await runRequestedSpecHandoff(options, io);
+    io.stdout(
+      summary(
+        "ok",
+        options,
+        totalAreas,
+        totalFeatures,
+        aiRenderedCountFeature(results),
+      ) + "\n",
+    );
+  }
+}
+/** See runRenderPerFeature for why both a renderable and a full req-model
+ * are needed. */
+async function runRenderPerArea(
+  reqModel,
+  fullReqModel,
+  options,
+  io,
+  templateText,
+  graph,
+  nameTrace,
+  gapAuditLinks,
+  backend,
+  renderDir,
+  analysisMode,
+  unified,
+) {
+  const items = expandAreaRenderItems(reqModel);
+  const totalAreas = reqModel.areas.length;
+  const totalFeatures = items.reduce(
+    (sum, item) => sum + item.area.features.length,
+    0,
+  );
+  const results = new Map();
+  let interrupted = false;
+  process.once("SIGINT", () => {
+    interrupted = true;
+    io.stdout(
+      summary(
+        "interrupted",
+        options,
+        totalAreas,
+        totalFeatures,
+        aiRenderedCountArea(results),
+      ) + "\n",
+    );
+    process.exit(0);
+  });
+  const agentOpts = {
+    backend,
+    projectRoot: options.projectRoot,
+    inputDirectory: options.inputDirectory,
+    outputDirectory: options.outputDirectory,
+    analysisMode,
+    launchMode: options.mode,
+    renderDir,
+    agentName: options.agentName,
+    concurrency: options.concurrency,
+    maxRetries: options.maxRetries,
+    backoffMs: options.backoffMs,
+    nameTrace,
+    gapAuditLinks,
+    noAuditFix: options.noAuditFix,
+    resume: options.resume,
+  };
+  const rendered = unified
+    ? await renderAllAreasUnified(items, reqModel, agentOpts)
+    : await renderAllAreas(items, reqModel, agentOpts);
+  for (const [id, result] of rendered) results.set(id, result);
+  if (!interrupted) {
+    // Always write both formats: req.md (markdown) + req-{idx}.txt (plain text).
+    const mergeOptions = {
+      includeUnreachableAreas: options.withUnreachableArea,
+    };
+    await writeFile(
+      join(options.outputDirectory, "req.md"),
+      mergeAreaReqMarkdown(
+        fullReqModel,
+        reqModel,
+        results,
+        templateText,
+        mergeOptions,
+      ),
+      "utf8",
+    );
+    const txtAreas = mergeAreaReqTxt(
+      fullReqModel,
+      reqModel,
+      results,
+      graph,
+      mergeOptions,
+    );
+    await writeReqTxtFiles(options.outputDirectory, txtAreas);
+    // Post-merge audit + optional fix agent (shell / shell-legacy modes)
+    if (!options.noAuditFix) {
+      await runPostMergeAudit(
+        join(options.outputDirectory, "req.md"),
+        options.inputDirectory,
+        options.outputDirectory,
+        options.mode,
+        io,
+      );
+    }
+    await runRequestedSpecHandoff(options, io);
+    io.stdout(
+      summary(
+        "ok",
+        options,
+        totalAreas,
+        totalFeatures,
+        aiRenderedCountArea(results),
+      ) + "\n",
+    );
+  }
+}
+function prepareSummary(
+  options,
+  checkScriptPath,
+  totalAreas,
+  entries,
+  renderList,
+) {
+  return JSON.stringify(
+    {
+      status: "ok",
+      mode: "subagent",
+      output: options.outputDirectory,
+      renderDir: join(options.outputDirectory, "rendering"),
+      checkScript: checkScriptPath,
+      renderList: renderList.listPath,
+      renderManifest: renderList.manifestPath,
+      totalAreas,
+      total: entries.length,
+      done: renderList.done,
+      pending: renderList.pending,
+      entries,
+    },
+    null,
+    2,
+  );
+}
+/** ADR-0005: writes task.md + expected.json for every renderable unit, plus
+ * render-list.md/render-manifest.json (see writeRenderList) — never spawns a
+ * backend. Turning each manifest entry into an output.json is the job of a
+ * subagent, dispatched by the main Agent running a2h-app-req-gen (see
+ * references/subagent-render.md), not this CLI process. Idempotent and safe
+ * to rerun anytime, including to resume an interrupted batch: it never
+ * touches draft.json/output.json, and always recomputes render-list.md from
+ * whichever output.json files already exist on disk. */
+async function runPrepare(options, io) {
+  if (options.specOutputDirectory !== undefined) {
+    throw new AgentUsageError(
+      "--spec-output requires finalized Stage 2 output; omit it during subagent preparation " +
+        "and pass it to the later --snapshot invocation",
+    );
+  }
+  if (options.projectRoot === undefined) {
+    throw new AgentUsageError(
+      "--mode subagent requires --project-root <android-project> " +
+        "(the subagent's read-only exploration boundary)",
+    );
+  }
+  const { reqModel: loadedReqModel, report } = await loadStage2InputWithReport(
+    options.inputDirectory,
+  );
+  const sortedReqModel = sortAreasReachableFirst(loadedReqModel);
+  const reqModel = filterRenderableAreas(sortedReqModel);
+  const nameTrace = await loadNameTrace(options.inputDirectory, reqModel);
+  const gapAuditLinks = await loadGapAuditLinks(
+    options.inputDirectory,
+    report,
+    sortedReqModel,
+  );
+  const renderDir = join(options.outputDirectory, "rendering");
+  const analysisMode = report.semanticCompleteness ?? "unknown";
+  const prepareOpts = {
+    projectRoot: options.projectRoot,
+    analysisMode,
+    renderDir,
+    gapAuditLinks,
+    nameTrace,
+  };
+  const entries = options.perFeature
+    ? await prepareFeatureInputs(
+        expandRenderItems(reqModel),
+        reqModel,
+        prepareOpts,
+      )
+    : await prepareAreaInputs(
+        expandAreaRenderItems(reqModel),
+        reqModel,
+        prepareOpts,
+      );
+  const checkScriptPath = defaultCheckScriptPath();
+  const renderList = await writeRenderList(
+    options.outputDirectory,
+    checkScriptPath,
+    entries,
+  );
+  io.stdout(
+    prepareSummary(
+      options,
+      checkScriptPath,
+      reqModel.areas.length,
+      entries,
+      renderList,
+    ) + "\n",
+  );
+  return 0;
+}
+async function runRender(options, io) {
+  if (options.projectRoot === undefined) {
+    throw new AgentUsageError(
+      "--mode shell requires --project-root <android-project> " +
+        "(the Agent read-only exploration boundary)",
+    );
+  }
+  const { reqModel: loadedReqModel, report } = await loadStage2InputWithReport(
+    options.inputDirectory,
+  );
+  const sortedReqModel = sortAreasReachableFirst(loadedReqModel);
+  const reqModel = filterRenderableAreas(sortedReqModel);
+  const nameTrace = await loadNameTrace(options.inputDirectory, reqModel);
+  const gapAuditLinks = await loadGapAuditLinks(
+    options.inputDirectory,
+    report,
+    sortedReqModel,
+  );
+  const templateText = await loadTemplate(
+    options.inputDirectory,
+    report,
+    sortedReqModel,
+  );
+  // Load graph for both md-out (via loadTemplate above) and txt modes.
+  const graph = await loadStage2AreaGraph(
+    options.inputDirectory,
+    report,
+    sortedReqModel,
+  );
+  const backend = buildBackend(options);
+  const renderDir = join(options.outputDirectory, "rendering");
+  await mkdir(renderDir, { recursive: true });
+  const analysisMode = report.semanticCompleteness ?? "unknown";
+  // The unified task-file protocol is implemented by the Claude backend in
+  // ordinary shell mode.  Custom commands and opencode still receive the
+  // inline prompt; passing them a task path silently produced invalid JSON in
+  // the old routing rule.
+  const unified =
+    options.mode === "shell" &&
+    options.aiCommand === undefined &&
+    options.backendName === "claude";
+  if (options.perFeature) {
+    await runRenderPerFeature(
+      reqModel,
+      sortedReqModel,
+      options,
+      io,
+      templateText,
+      graph,
+      nameTrace,
+      gapAuditLinks,
+      backend,
+      renderDir,
+      analysisMode,
+      unified,
+    );
+  } else {
+    await runRenderPerArea(
+      reqModel,
+      sortedReqModel,
+      options,
+      io,
+      templateText,
+      graph,
+      nameTrace,
+      gapAuditLinks,
+      backend,
+      renderDir,
+      analysisMode,
+      unified,
+    );
+  }
+  return 0;
+}
+export async function runAgentStage2(argv, io) {
+  let options;
+  try {
+    options = parseAgentArguments(argv);
+  } catch (error) {
+    io.stderr(`${error instanceof Error ? error.message : String(error)}\n`);
+    return 2;
+  }
+  try {
+    if (options.resume) {
+      let isDirectory = false;
+      try {
+        isDirectory = (await stat(options.outputDirectory)).isDirectory();
+      } catch {
+        // Report a usage error below rather than silently starting a new run.
+      }
+      if (!isDirectory) {
+        io.stderr(
+          `--resume directory does not exist: ${options.outputDirectory}\n`,
+        );
+        return 2;
+      }
+    }
+    // Guard: refuse to overwrite an existing output directory when the user
+    // explicitly set --output.  Auto-generated default paths and --snapshot
+    // mode (which must read existing output.json) are exempt.
+    if (options.outputExplicit && !options.snapshot) {
+      try {
+        await ensureOutputDirectoryEmpty(options.outputDirectory);
+      } catch (error) {
+        if (error instanceof OutputDirectoryNotEmptyError) {
+          io.stderr(error.message + "\n");
+          return 2;
+        }
+        throw error;
+      }
+    }
+    if (options.snapshot) return await runSnapshot(options, io);
+    return options.mode === "shell" || options.mode === "shell-legacy"
+      ? await runRender(options, io)
+      : await runPrepare(options, io);
+  } catch (error) {
+    const details =
+      error instanceof GenerationError ? (error.details ?? []) : [];
+    io.stderr(
+      `Stage 2 (agent) failed: ${error instanceof Error ? error.message : String(error)}\n${details.map((detail) => `${detail}\n`).join("")}`,
+    );
+    return 1;
+  }
+}