@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/commands/codebase-to-spec/edit-loop.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `dotrequirements codebase-to-spec edit-loop` subcommand.
+ *
+ * Runs the spec review + editor loop over the composed spec.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular `edit-loop` subcommand
+ * - CTS-EDIT-1..6: end-to-end loop behavior
+ */
+export interface EditLoopCmdOptions {
+    maxTurns?: number;
+    model?: string;
+    projectRoot?: string;
+}
+export declare function editLoopCommand(rawOptions?: EditLoopCmdOptions): Promise<void>;
+//# sourceMappingURL=edit-loop.d.ts.map

package/dist/commands/codebase-to-spec/edit-loop.js

@@ -0,0 +1,83 @@
+/**
+ * `dotrequirements codebase-to-spec edit-loop` subcommand.
+ *
+ * Runs the spec review + editor loop over the composed spec.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular `edit-loop` subcommand
+ * - CTS-EDIT-1..6: end-to-end loop behavior
+ */
+import { copyFileSync, existsSync, writeFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { DEFAULT_EDIT_LOOP_MAX_TURNS, runEditLoop, } from "../../codebase-to-spec/edit-loop.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { StdoutProgress } from "../../codebase-to-spec/progress.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function editLoopCommand(rawOptions = {}) {
+    const progress = new StdoutProgress();
+    const projectRoot = rawOptions.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    const maxTurns = rawOptions.maxTurns ?? DEFAULT_EDIT_LOOP_MAX_TURNS;
+    if (!existsSync(paths.composedSpec)) {
+        process.stderr.write(`Missing composed spec at ${paths.composedSpec}. Run \`dotrequirements cts compose\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!existsSync(paths.source)) {
+        process.stderr.write(`Missing uncompressed pack at ${paths.source}. Run \`dotrequirements cts pack\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    progress.emit({
+        stage: "spec-review",
+        step: "start",
+        message: `Starting spec review + edit loop (max-turns=${maxTurns})`,
+    });
+    let result;
+    try {
+        result = await runEditLoop({
+            composedSpecPath: paths.composedSpec,
+            specVersionFor: (turn) => paths.specVersion(turn),
+            fullPackPath: paths.source,
+            addDirs: [paths.root],
+            maxTurns,
+            model: rawOptions.model,
+            progress,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`\nEdit loop failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.StageFailed;
+        return;
+    }
+    // Persist per-turn reviewer output (JSON).
+    result.reviewsByTurn.forEach((review, idx) => {
+        writeFileSync(paths.specReviewTurn(idx + 1), `${JSON.stringify(review, null, 2)}\n`, "utf-8");
+    });
+    if (result.hitMaxTurns) {
+        progress.emit({
+            stage: "spec-review",
+            step: "max-turns-hit",
+            message: `Loop hit max-turns (${maxTurns}) without converging. Using latest spec anyway.`,
+            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
+        });
+        process.exitCode = ExitCode.MaxTurnsHit;
+    }
+    else {
+        progress.emit({
+            stage: "spec-review",
+            step: "done",
+            message: `Edit loop converged at turn ${result.turnsUsed} with verdict: ${result.finalVerdict}`,
+            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
+        });
+    }
+    // Copy the final post-edit spec to a stable path so downstream stages
+    // (present) and external tooling have a predictable location.
+    copyFileSync(result.finalSpecPath, paths.specFinal);
+    progress.emit({
+        stage: "spec-review",
+        step: "final-spec",
+        message: `Final spec → ${paths.specFinal}`,
+    });
+}
+//# sourceMappingURL=edit-loop.js.map

package/dist/commands/codebase-to-spec/fan-out.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `dotrequirements codebase-to-spec fan-out` subcommand.
+ *
+ * Runs the specifier for every area in the cached outline, in parallel up to
+ * a bounded concurrency limit, with retry-once on failure.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular `fan-out` subcommand
+ * - CTS-SPEC-1.2: bounded concurrent execution
+ * - CTS-SPEC-5: failure detection + retry + non-blocking continuation
+ */
+export interface FanOutCmdOptions {
+    concurrency?: number;
+    model?: string;
+    cliBinary?: string;
+    projectRoot?: string;
+}
+export declare function fanOutCommand(options?: FanOutCmdOptions): Promise<void>;
+//# sourceMappingURL=fan-out.d.ts.map

package/dist/commands/codebase-to-spec/fan-out.js

@@ -0,0 +1,77 @@
+/**
+ * `dotrequirements codebase-to-spec fan-out` subcommand.
+ *
+ * Runs the specifier for every area in the cached outline, in parallel up to
+ * a bounded concurrency limit, with retry-once on failure.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular `fan-out` subcommand
+ * - CTS-SPEC-1.2: bounded concurrent execution
+ * - CTS-SPEC-5: failure detection + retry + non-blocking continuation
+ */
+import { existsSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { DEFAULT_FAN_OUT_CONCURRENCY, runFanOut, } from "../../codebase-to-spec/fan-out.js";
+import { StdoutProgress } from "../../codebase-to-spec/progress.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+import { readFinalOutline } from "./plan-loop.js";
+export async function fanOutCommand(options = {}) {
+    const progress = new StdoutProgress();
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    const cliBinary = options.cliBinary ?? "dotrequirements";
+    if (!existsSync(paths.outlineFinal)) {
+        process.stderr.write(`Missing outline at ${paths.outlineFinal}. Run \`dotrequirements cts plan-loop\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!existsSync(paths.source)) {
+        process.stderr.write(`Missing uncompressed pack at ${paths.source}. Run \`dotrequirements cts pack\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const outline = readFinalOutline(projectRoot);
+    const concurrency = options.concurrency ?? DEFAULT_FAN_OUT_CONCURRENCY;
+    progress.emit({
+        stage: "specify",
+        step: "start",
+        message: `Fan-out: ${outline.areas.length} areas (concurrency=${concurrency})`,
+    });
+    const result = await runFanOut({
+        outline,
+        fullPackPath: paths.source,
+        partialPathFor: (sanitized) => paths.partial(sanitized),
+        slicePathFor: (sanitized) => `${paths.partialsDir}/slice-${sanitized}.txt`,
+        validateCommand: `${cliBinary} cts validate`,
+        styleCheckCommand: `${cliBinary} cts style-check`,
+        addDirs: [paths.root],
+        concurrency,
+        model: options.model,
+        progress,
+    });
+    // Summary
+    const failed = result.outcomes.filter((o) => o.status === "failed");
+    const completed = result.outcomes.filter((o) => o.status === "completed");
+    const skipped = result.outcomes.filter((o) => o.status === "skipped-resume");
+    progress.emit({
+        stage: "specify",
+        step: "summary",
+        message: `Completed: ${completed.length} / Skipped (resume): ${skipped.length} / Failed: ${failed.length}`,
+        data: {
+            completed: completed.length,
+            skipped: skipped.length,
+            failed: failed.length,
+        },
+    });
+    if (failed.length > 0) {
+        for (const o of failed) {
+            process.stderr.write(`  failed: ${o.area.name} (${o.area.prefix}) — ${o.failureCause ?? "unknown"}\n`);
+        }
+        // Per CTS-SPEC-5, a failed specifier does not block the rest of the
+        // pipeline; we still let the caller decide. Surface non-zero so wrappers
+        // can react if they care.
+        process.exitCode = ExitCode.StageFailed;
+    }
+}
+//# sourceMappingURL=fan-out.js.map

package/dist/commands/codebase-to-spec/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Command registrar for `dotrequirements codebase-to-spec` (alias: `cts`).
+ *
+ * Subcommands route to focused handlers in this directory. Each subcommand can
+ * be invoked granularly (e.g., `dotrequirements cts pack`) per CTS-CLI-2.
+ */
+import type { Command } from "commander";
+export declare function registerCodebaseToSpec(program: Command): void;
+//# sourceMappingURL=index.d.ts.map

package/dist/commands/codebase-to-spec/index.js

@@ -0,0 +1,135 @@
+/**
+ * Command registrar for `dotrequirements codebase-to-spec` (alias: `cts`).
+ *
+ * Subcommands route to focused handlers in this directory. Each subcommand can
+ * be invoked granularly (e.g., `dotrequirements cts pack`) per CTS-CLI-2.
+ */
+import { composeCommand } from "./compose.js";
+import { editLoopCommand } from "./edit-loop.js";
+import { fanOutCommand } from "./fan-out.js";
+import { packCommand } from "./pack.js";
+import { planLoopCommand } from "./plan-loop.js";
+import { presentCommand } from "./present.js";
+import { runCommand } from "./run.js";
+import { skillInstallCommand } from "./skill-install.js";
+import { specifyAreaCommand } from "./specify-area.js";
+import { styleCheckCommand } from "./style-check.js";
+import { validateCommand } from "./validate.js";
+export function registerCodebaseToSpec(program) {
+    const cts = program
+        .command("codebase-to-spec")
+        .alias("cts")
+        .description("Generate dotrequirements behavioral specifications from a codebase");
+    cts
+        .command("pack")
+        .description("Pack the codebase (compressed and uncompressed views) into the cache")
+        .option("-s, --scope <path>", "Limit to files under this path (subdir of project root)")
+        .option("--fresh", "Clear the cache before running")
+        .option("--budget <tokens>", "Override the working-context budget (in tokens)", (v) => parseInt(v, 10))
+        .action((opts) => packCommand({ ...opts, budgetTokens: opts.budget }));
+    cts
+        .command("plan-loop")
+        .description("Run the planner + outline review loop on the cached pack")
+        .option("--max-turns <n>", "Hard cap on review turns", (v) => parseInt(v, 10))
+        .option("--model <name>", "Override the model used by the planner and reviewer")
+        .action((opts) => planLoopCommand({
+        maxTurns: opts.maxTurns,
+        model: opts.model,
+    }));
+    cts
+        .command("specify-area <name>")
+        .description("Run the specifier for one named area from the cached outline")
+        .option("--model <name>", "Override the model used by the specifier")
+        .action((name, opts) => specifyAreaCommand(name, {
+        model: opts.model,
+    }));
+    cts
+        .command("fan-out")
+        .description("Run all specifiers in parallel for areas in the cached outline")
+        .option("-c, --concurrency <n>", "Max concurrent specifiers", (v) => parseInt(v, 10))
+        .option("--model <name>", "Override the model used by specifiers")
+        .action((opts) => fanOutCommand({
+        concurrency: opts.concurrency,
+        model: opts.model,
+    }));
+    cts
+        .command("validate <partial-path>")
+        .description("Validate the schema/syntax of a partial-spec file (deterministic, offline)")
+        .action((partialPath) => validateCommand(partialPath));
+    cts
+        .command("style-check <partial-path>")
+        .description("Run a local style-check on a partial-spec file (severity-categorized feedback)")
+        .option("--model <name>", "Override the model used for the check")
+        .action((partialPath, opts) => styleCheckCommand(partialPath, { model: opts.model }));
+    cts
+        .command("compose")
+        .description("Assemble per-area partials into a single composed spec")
+        .action(() => composeCommand());
+    cts
+        .command("edit-loop")
+        .description("Run the spec reviewer + editor loop on the composed spec")
+        .option("--max-turns <n>", "Hard cap on edit-loop turns", (v) => parseInt(v, 10))
+        .option("--model <name>", "Override the model used by the reviewer and editor")
+        .action((opts) => editLoopCommand({
+        maxTurns: opts.maxTurns,
+        model: opts.model,
+    }));
+    cts
+        .command("present")
+        .description("Write the final spec to .requirements/ and emit a pipeline summary")
+        .option("--interactive", "Force interactive mode (override TTY detection)")
+        .option("--non-interactive", "Force non-interactive mode (override TTY detection)")
+        .option("--overwrite", "Replace existing .requirements/ files without prompting")
+        .option("--skip-existing", "Leave existing .requirements/ files untouched")
+        .action((opts) => {
+        const forceMode = opts.interactive
+            ? "interactive"
+            : opts.nonInteractive
+                ? "non-interactive"
+                : undefined;
+        return presentCommand({
+            forceMode,
+            overwrite: opts.overwrite,
+            skipExisting: opts.skipExisting,
+        });
+    });
+    cts
+        .command("run")
+        .description("Run the full pipeline (pack → plan → specify → compose → edit → present)")
+        .option("-s, --scope <path>", "Limit to files under this path (subdir of project root)")
+        .option("--fresh", "Clear the cache before running")
+        .option("--budget <tokens>", "Override the working-context budget (in tokens)", (v) => parseInt(v, 10))
+        .option("--max-turns <n>", "Hard cap on outline review turns", (v) => parseInt(v, 10))
+        .option("--model <name>", "Override the model used by agent calls")
+        .option("--interactive", "Force interactive mode for the present stage")
+        .option("--non-interactive", "Force non-interactive mode for the present stage")
+        .option("--overwrite", "Replace existing .requirements/ files without prompting")
+        .option("--skip-existing", "Leave existing .requirements/ files untouched")
+        .action((opts) => {
+        const forceMode = opts.interactive
+            ? "interactive"
+            : opts.nonInteractive
+                ? "non-interactive"
+                : undefined;
+        return runCommand({
+            ...opts,
+            budgetTokens: opts.budget,
+            maxTurns: opts.maxTurns,
+            forceMode,
+            overwrite: opts.overwrite,
+            skipExisting: opts.skipExisting,
+        });
+    });
+    cts
+        .command("skill-install")
+        .description("Install the codebase-to-spec skill (SKILL.md) into the host's skills directory")
+        .option("--global", "Install to ~/.claude/skills/ instead of the project")
+        .option("--target-dir <path>", "Install into a custom skills directory (for non-Claude-Code hosts)")
+        .option("--overwrite", "Replace an existing SKILL.md if one is already present")
+        .action((opts) => skillInstallCommand({
+        global: opts.global,
+        targetDir: opts.targetDir,
+        overwrite: opts.overwrite,
+    }));
+}
+//# sourceMappingURL=index.js.map

package/dist/commands/codebase-to-spec/pack.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `dotrequirements codebase-to-spec pack` subcommand.
+ *
+ * Packs the codebase into the cache directory and runs the budget check.
+ *
+ * Requirements covered:
+ * - CTS-CLI-3: Pipeline refuses to spec a codebase that exceeds the working context budget
+ * - CTS-PACK-1: Pack stage produces compressed and uncompressed views of the codebase
+ * - CTS-PACK-2: Engineer can extend the ignore list per project
+ * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
+ */
+export interface PackOptions {
+    scope?: string;
+    fresh?: boolean;
+    budgetTokens?: number;
+    /** Override progress emitter, mainly for tests. */
+    progress?: import("../../codebase-to-spec/progress.js").ProgressEmitter;
+    /** Override the project root, mainly for tests. */
+    projectRoot?: string;
+}
+export declare function packCommand(rawOptions?: PackOptions): Promise<void>;
+//# sourceMappingURL=pack.d.ts.map

package/dist/commands/codebase-to-spec/pack.js

@@ -0,0 +1,76 @@
+/**
+ * `dotrequirements codebase-to-spec pack` subcommand.
+ *
+ * Packs the codebase into the cache directory and runs the budget check.
+ *
+ * Requirements covered:
+ * - CTS-CLI-3: Pipeline refuses to spec a codebase that exceeds the working context budget
+ * - CTS-PACK-1: Pack stage produces compressed and uncompressed views of the codebase
+ * - CTS-PACK-2: Engineer can extend the ignore list per project
+ * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
+ */
+import { resolve } from "node:path";
+import { checkBudget, countTokensInFileExact, DEFAULT_BUDGET_TOKENS, formatBudgetExceededMessage, } from "../../codebase-to-spec/budget.js";
+import { clearCache, ensureCacheDir } from "../../codebase-to-spec/cache.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { runPack } from "../../codebase-to-spec/pack.js";
+import { StdoutProgress } from "../../codebase-to-spec/progress.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function packCommand(rawOptions = {}) {
+    const progress = rawOptions.progress ?? new StdoutProgress();
+    const projectRoot = rawOptions.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const budgetTokens = rawOptions.budgetTokens ?? DEFAULT_BUDGET_TOKENS;
+    if (rawOptions.fresh) {
+        progress.emit({
+            stage: "pack",
+            step: "clear-cache",
+            message: "Clearing existing cache (--fresh)",
+        });
+        clearCache(projectRoot);
+    }
+    const paths = ensureCacheDir(projectRoot);
+    const scope = rawOptions.scope
+        ? resolve(projectRoot, rawOptions.scope)
+        : undefined;
+    progress.emit({
+        stage: "pack",
+        step: "start",
+        message: scope
+            ? `Packing codebase at ${scope}`
+            : `Packing codebase at ${projectRoot}`,
+    });
+    const packResult = await runPack({
+        projectRoot,
+        paths,
+        scope: rawOptions.scope,
+    });
+    progress.emit({
+        stage: "pack",
+        step: "done",
+        message: `Packed ${packResult.fileCount} files → ${paths.overview} (compressed), ${paths.source} (uncompressed)`,
+        data: { fileCount: packResult.fileCount },
+    });
+    // Budget check (CTS-CLI-3)
+    const measured = countTokensInFileExact(paths.overview);
+    const budget = checkBudget(measured, budgetTokens);
+    progress.emit({
+        stage: "pack",
+        step: "budget-check",
+        message: `Compressed pack is ${budget.measuredTokens.toLocaleString()} tokens (budget: ${budget.budgetTokens.toLocaleString()})`,
+        data: {
+            measuredTokens: budget.measuredTokens,
+            budgetTokens: budget.budgetTokens,
+        },
+    });
+    if (!budget.withinBudget) {
+        process.stderr.write(`${formatBudgetExceededMessage(budget)}\n`);
+        process.exitCode = ExitCode.BudgetExceeded;
+        return;
+    }
+    progress.emit({
+        stage: "pack",
+        step: "budget-ok",
+        message: `Budget OK. Ready for the plan stage.`,
+    });
+}
+//# sourceMappingURL=pack.js.map

package/dist/commands/codebase-to-spec/plan-loop.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `dotrequirements codebase-to-spec plan-loop` subcommand.
+ *
+ * Reads the compressed pack from the cache and runs the outline review loop
+ * (planner → reviewer → revise → ... → approved). Writes per-turn artifacts
+ * and the final outline.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: `dotrequirements cts plan-loop` runs only the outline review loop and exits
+ * - CTS-PLAN-1..6: end-to-end loop behavior
+ * - CTS-RESUME-1.1: skip loop if outline-final.json exists
+ * - CTS-OBSERVE-1, CTS-OBSERVE-2: progress + failure observability
+ */
+import type { Outline } from "../../codebase-to-spec/schemas.js";
+export interface PlanLoopOptions {
+    maxTurns?: number;
+    model?: string;
+    progress?: import("../../codebase-to-spec/progress.js").ProgressEmitter;
+    projectRoot?: string;
+}
+export declare function planLoopCommand(rawOptions?: PlanLoopOptions): Promise<void>;
+/**
+ * Helper used by `cts run` and tests to consume the outline that plan-loop wrote.
+ */
+export declare function readFinalOutline(projectRoot: string): Outline;
+//# sourceMappingURL=plan-loop.d.ts.map

package/dist/commands/codebase-to-spec/plan-loop.js

@@ -0,0 +1,105 @@
+/**
+ * `dotrequirements codebase-to-spec plan-loop` subcommand.
+ *
+ * Reads the compressed pack from the cache and runs the outline review loop
+ * (planner → reviewer → revise → ... → approved). Writes per-turn artifacts
+ * and the final outline.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: `dotrequirements cts plan-loop` runs only the outline review loop and exits
+ * - CTS-PLAN-1..6: end-to-end loop behavior
+ * - CTS-RESUME-1.1: skip loop if outline-final.json exists
+ * - CTS-OBSERVE-1, CTS-OBSERVE-2: progress + failure observability
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { DEFAULT_OUTLINE_LOOP_MAX_TURNS, runOutlineReviewLoop, } from "../../codebase-to-spec/outline-review-loop.js";
+import { StdoutProgress } from "../../codebase-to-spec/progress.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+export async function planLoopCommand(rawOptions = {}) {
+    const progress = rawOptions.progress ?? new StdoutProgress();
+    const projectRoot = rawOptions.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    const maxTurns = rawOptions.maxTurns ?? DEFAULT_OUTLINE_LOOP_MAX_TURNS;
+    // Resume — if outline-final.json already exists, skip the loop entirely.
+    if (existsSync(paths.outlineFinal)) {
+        progress.emit({
+            stage: "plan",
+            step: "resume-skip",
+            message: `outline-final.json exists at ${paths.outlineFinal}; skipping plan loop`,
+        });
+        return;
+    }
+    // Require the compressed pack from the prior stage.
+    if (!existsSync(paths.overview)) {
+        process.stderr.write(`Missing compressed pack at ${paths.overview}. Run \`dotrequirements cts pack\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    progress.emit({
+        stage: "plan",
+        step: "start",
+        message: `Starting plan + outline review loop (max-turns=${maxTurns})`,
+    });
+    let result;
+    try {
+        result = await runOutlineReviewLoop({
+            overviewPath: paths.overview,
+            addDirs: [paths.root],
+            maxTurns,
+            model: rawOptions.model,
+            progress,
+        });
+    }
+    catch (err) {
+        process.stderr.write(`\nPlan loop failed: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.StageFailed;
+        return;
+    }
+    // Persist per-turn artifacts (one outline per turn, one review per turn) so
+    // we have full evidence and resumability.
+    result.outlinesByTurn.forEach((outline, idx) => {
+        const path = paths.outlineTurn(idx + 1);
+        writeFileSync(path, `${JSON.stringify(outline, null, 2)}\n`, "utf-8");
+    });
+    result.reviewsByTurn.forEach((review, idx) => {
+        const path = paths.outlineReviewTurn(idx + 1);
+        writeFileSync(path, `${JSON.stringify(review, null, 2)}\n`, "utf-8");
+    });
+    // Write the final outline.
+    writeFileSync(paths.outlineFinal, `${JSON.stringify(result.outline, null, 2)}\n`, "utf-8");
+    if (result.hitMaxTurns) {
+        progress.emit({
+            stage: "plan",
+            step: "max-turns-hit",
+            message: `Loop hit max-turns (${maxTurns}) without converging. Using latest outline anyway.`,
+            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
+        });
+        process.exitCode = ExitCode.MaxTurnsHit;
+    }
+    else {
+        progress.emit({
+            stage: "plan",
+            step: "done",
+            message: `Plan loop converged at turn ${result.turnsUsed} with verdict: ${result.finalVerdict}`,
+            data: { turnsUsed: result.turnsUsed, finalVerdict: result.finalVerdict },
+        });
+    }
+    progress.emit({
+        stage: "plan",
+        step: "outline-written",
+        message: `Final outline → ${paths.outlineFinal} (${result.outline.areas.length} areas)`,
+    });
+}
+/**
+ * Helper used by `cts run` and tests to consume the outline that plan-loop wrote.
+ */
+export function readFinalOutline(projectRoot) {
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outlineFinal)) {
+        throw new Error(`Missing ${paths.outlineFinal}. Run \`cts plan-loop\` first.`);
+    }
+    return JSON.parse(readFileSync(paths.outlineFinal, "utf-8"));
+}
+//# sourceMappingURL=plan-loop.js.map

package/dist/commands/codebase-to-spec/present.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `dotrequirements codebase-to-spec present` subcommand.
+ *
+ * Writes the final spec to `.requirements/` and emits a pipeline summary.
+ *
+ * Requirements covered:
+ * - CTS-CLI-2: granular `present` subcommand
+ * - CTS-CLI-4: TTY-driven interactive/non-interactive selection
+ * - CTS-PRESENT-1..4
+ */
+export interface PresentCmdOptions {
+    /** Force --interactive or --non-interactive (overrides TTY detection). */
+    forceMode?: "interactive" | "non-interactive";
+    /** Replace existing .requirements/ files without prompting (non-interactive). */
+    overwrite?: boolean;
+    /** Skip writing files that would conflict (non-interactive). */
+    skipExisting?: boolean;
+    projectRoot?: string;
+}
+export declare function presentCommand(rawOptions?: PresentCmdOptions): Promise<void>;
+//# sourceMappingURL=present.d.ts.map