@popoverai/dotrequirements 0.23.0 → 0.24.0

package/dist/codebase-to-spec/editor.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Editor worker: revise the composed spec in place based on a reviewer's
+ * critique.
+ *
+ * Two modes:
+ * - apply: apply mechanical revisions verbatim (when verdict is `approved-with-revisions`)
+ * - revise: address the critique using the editor's own judgment (when verdict is `requires-another-review`)
+ *
+ * Requirements covered:
+ * - CTS-EDIT-3: approved-with-revisions triggers apply mode
+ * - CTS-EDIT-4: requires-another-review triggers revise mode
+ * - CTS-EDIT-5: editor operates on the cohesive document, reads codebase only on demand
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { SpecReview } from "./schemas.js";
+export type EditorMode = "apply" | "revise";
+export interface EditorContext {
+    /**
+     * Input spec path. The editor reads from here.
+     * If `outputSpecPath` differs, the input is copied to the output path first
+     * (so the editor's in-place edits land on the output).
+     */
+    inputSpecPath: string;
+    /** Output spec path (may equal inputSpecPath for true in-place editing). */
+    outputSpecPath: string;
+    /** Path to the codebase pack the editor may consult on demand. */
+    fullPackPath: string;
+    /** Directories to grant filesystem access to. */
+    addDirs: string[];
+    /** Reviewer's critique. */
+    critique: SpecReview;
+    /** Apply or revise. */
+    mode: EditorMode;
+    runner?: ClaudeRunner;
+    model?: string;
+}
+export interface EditorResult {
+    /** True if the output file exists and is non-empty after the editor ran. */
+    wroteSpec: boolean;
+    /** Size of the output in bytes (0 if missing). */
+    outputBytes: number;
+    /** Process exit code. */
+    exitCode: number;
+    /** Captured stdout (one-line confirmation). */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+}
+/**
+ * Run the editor. If outputSpecPath differs from inputSpecPath, copy first
+ * so the in-place edits land on the output.
+ */
+export declare function runEditor(ctx: EditorContext): Promise<EditorResult>;
+//# sourceMappingURL=editor.d.ts.map

package/dist/codebase-to-spec/editor.js

@@ -0,0 +1,74 @@
+/**
+ * Editor worker: revise the composed spec in place based on a reviewer's
+ * critique.
+ *
+ * Two modes:
+ * - apply: apply mechanical revisions verbatim (when verdict is `approved-with-revisions`)
+ * - revise: address the critique using the editor's own judgment (when verdict is `requires-another-review`)
+ *
+ * Requirements covered:
+ * - CTS-EDIT-3: approved-with-revisions triggers apply mode
+ * - CTS-EDIT-4: requires-another-review triggers revise mode
+ * - CTS-EDIT-5: editor operates on the cohesive document, reads codebase only on demand
+ */
+import { copyFileSync, existsSync, statSync } from "node:fs";
+import { runClaude } from "./claude.js";
+import { EDITOR_PROMPT } from "./prompts/editor.js";
+function userMessage(ctx) {
+    const mode = ctx.mode === "apply" ? "APPLY" : "REVISE";
+    const lines = [
+        `Mode: ${mode}`,
+        ``,
+        `Spec to edit (in place via Edit tool): ${ctx.outputSpecPath}`,
+        `Codebase pack (consult only on demand): ${ctx.fullPackPath}`,
+        ``,
+        `## Reviewer critique`,
+        `\`\`\`json`,
+        JSON.stringify(ctx.critique, null, 2),
+        `\`\`\``,
+        ``,
+    ];
+    if (ctx.mode === "apply") {
+        lines.push(`You are in APPLY mode. The reviewer's verdict is \`approved-with-revisions\`. Apply each revision in the \`revisions\` array verbatim. Do not restructure. When done, output a one-line confirmation.`);
+    }
+    else {
+        lines.push(`You are in REVISE mode. The reviewer's verdict is \`requires-another-review\`. Address each finding using your judgment. Use the Edit tool for targeted changes. Consult the codebase only to verify specific findings before adding requirements.`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Run the editor. If outputSpecPath differs from inputSpecPath, copy first
+ * so the in-place edits land on the output.
+ */
+export async function runEditor(ctx) {
+    if (ctx.inputSpecPath !== ctx.outputSpecPath) {
+        copyFileSync(ctx.inputSpecPath, ctx.outputSpecPath);
+    }
+    const runner = ctx.runner ?? runClaude;
+    const result = await runner({
+        systemPrompt: EDITOR_PROMPT,
+        userMessage: userMessage(ctx),
+        model: ctx.model,
+        tools: ["Read", "Edit", "Grep", "Glob"],
+        addDirs: ctx.addDirs,
+    });
+    let wroteSpec = false;
+    let outputBytes = 0;
+    if (existsSync(ctx.outputSpecPath)) {
+        try {
+            outputBytes = statSync(ctx.outputSpecPath).size;
+            wroteSpec = outputBytes > 0;
+        }
+        catch {
+            // Treat as not written.
+        }
+    }
+    return {
+        wroteSpec,
+        outputBytes,
+        exitCode: result.exitCode,
+        stdout: result.stdout,
+        stderr: result.stderr,
+    };
+}
+//# sourceMappingURL=editor.js.map

package/dist/codebase-to-spec/exit-codes.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Stable exit codes for the codebase-to-spec CLI.
+ *
+ * Wrappers (the skill, CI tooling, scripts) rely on these to branch on outcome.
+ * Breaking changes are part of the CLI's public contract — see CTS-CLI-5.
+ *
+ * Requirements covered:
+ * - CTS-CLI-5: CLI exit codes and progress format are part of the public contract
+ */
+export declare const ExitCode: {
+    /** Success — pipeline completed normally. */
+    readonly Success: 0;
+    /** Generic failure — unspecified error. */
+    readonly GenericFailure: 1;
+    /** A required input was missing (e.g., a stage was invoked without its prerequisite cache artifacts). */
+    readonly MissingInput: 2;
+    /** A pipeline stage failed (specifier, reviewer, editor, etc.). */
+    readonly StageFailed: 3;
+    /**
+     * The codebase exceeds the working-context budget after compression.
+     * The CLI exits with this code when CTS-CLI-3 fires.
+     */
+    readonly BudgetExceeded: 10;
+    /**
+     * A review loop hit its max-turns cap without converging on `approved` or
+     * `approved-with-revisions`. The latest artifact is still usable; this code
+     * signals to callers that the residual review should be surfaced.
+     */
+    readonly MaxTurnsHit: 11;
+    /** Output would overwrite an existing `.requirements/` file in non-interactive mode without an explicit flag. */
+    readonly OverwriteRefused: 12;
+    /** Invalid combination of CLI flags (e.g., --overwrite and --skip-existing both supplied). */
+    readonly InvalidFlags: 13;
+};
+export type ExitCodeValue = (typeof ExitCode)[keyof typeof ExitCode];
+/**
+ * Human-readable name for an exit code, suitable for logging and error messages.
+ */
+export declare function exitCodeName(code: ExitCodeValue): string;
+//# sourceMappingURL=exit-codes.d.ts.map

package/dist/codebase-to-spec/exit-codes.js

@@ -0,0 +1,58 @@
+/**
+ * Stable exit codes for the codebase-to-spec CLI.
+ *
+ * Wrappers (the skill, CI tooling, scripts) rely on these to branch on outcome.
+ * Breaking changes are part of the CLI's public contract — see CTS-CLI-5.
+ *
+ * Requirements covered:
+ * - CTS-CLI-5: CLI exit codes and progress format are part of the public contract
+ */
+export const ExitCode = {
+    /** Success — pipeline completed normally. */
+    Success: 0,
+    /** Generic failure — unspecified error. */
+    GenericFailure: 1,
+    /** A required input was missing (e.g., a stage was invoked without its prerequisite cache artifacts). */
+    MissingInput: 2,
+    /** A pipeline stage failed (specifier, reviewer, editor, etc.). */
+    StageFailed: 3,
+    /**
+     * The codebase exceeds the working-context budget after compression.
+     * The CLI exits with this code when CTS-CLI-3 fires.
+     */
+    BudgetExceeded: 10,
+    /**
+     * A review loop hit its max-turns cap without converging on `approved` or
+     * `approved-with-revisions`. The latest artifact is still usable; this code
+     * signals to callers that the residual review should be surfaced.
+     */
+    MaxTurnsHit: 11,
+    /** Output would overwrite an existing `.requirements/` file in non-interactive mode without an explicit flag. */
+    OverwriteRefused: 12,
+    /** Invalid combination of CLI flags (e.g., --overwrite and --skip-existing both supplied). */
+    InvalidFlags: 13,
+};
+/**
+ * Human-readable name for an exit code, suitable for logging and error messages.
+ */
+export function exitCodeName(code) {
+    switch (code) {
+        case ExitCode.Success:
+            return "Success";
+        case ExitCode.GenericFailure:
+            return "GenericFailure";
+        case ExitCode.MissingInput:
+            return "MissingInput";
+        case ExitCode.StageFailed:
+            return "StageFailed";
+        case ExitCode.BudgetExceeded:
+            return "BudgetExceeded";
+        case ExitCode.MaxTurnsHit:
+            return "MaxTurnsHit";
+        case ExitCode.OverwriteRefused:
+            return "OverwriteRefused";
+        case ExitCode.InvalidFlags:
+            return "InvalidFlags";
+    }
+}
+//# sourceMappingURL=exit-codes.js.map

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

@@ -0,0 +1,63 @@
+/**
+ * Specifier fan-out orchestrator.
+ *
+ * For each area in the outline, extract a slice, spawn a specifier worker,
+ * and write the resulting partial to the cache. Workers run in parallel up
+ * to a bounded concurrency limit. On per-area failure (no partial written,
+ * empty partial), the worker is retried once; on second failure, the area
+ * is recorded as failed for surfacing to the user.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1.2: bounded concurrent execution
+ * - CTS-SPEC-5: failed/empty specifier output is detected and retried
+ * - CTS-OBSERVE-2.0: failure details are logged with area name + cause
+ * - CTS-RESUME-1.2: existing non-empty partial means the specifier is skipped
+ */
+import type { ClaudeRunner } from "./claude.js";
+import type { ProgressEmitter } from "./progress.js";
+import type { Area, Outline } from "./schemas.js";
+export declare const DEFAULT_FAN_OUT_CONCURRENCY = 8;
+export interface FanOutOptions {
+    outline: Outline;
+    /** Path to the uncompressed pack (slices come from here). */
+    fullPackPath: string;
+    /** Path resolver: given a sanitized area name, return the partial path. */
+    partialPathFor: (sanitizedAreaName: string) => string;
+    /** Path resolver: given a sanitized area name, return the slice path. */
+    slicePathFor: (sanitizedAreaName: string) => string;
+    /** Command (path + args) the specifier should run to invoke schema validation. Run before style-check. */
+    validateCommand: string;
+    /** Command (path + args) the specifier should run to invoke style-check. */
+    styleCheckCommand: string;
+    /** Directories the specifier needs filesystem access to. */
+    addDirs: string[];
+    concurrency?: number;
+    runner?: ClaudeRunner;
+    model?: string;
+    progress?: ProgressEmitter;
+}
+export interface AreaOutcome {
+    area: Area;
+    status: "completed" | "skipped-resume" | "failed";
+    /** Number of attempts made (1 = first attempt succeeded; 2 = retry succeeded; 2 with failed = retried and still failed). */
+    attempts: number;
+    /** Reason the area failed, if applicable. */
+    failureCause?: string;
+    /** Path to the partial (whether or not it was written successfully). */
+    partialPath: string;
+}
+export interface FanOutResult {
+    outcomes: AreaOutcome[];
+    /** True if every area produced a non-empty partial (either now or from cache). */
+    allSucceeded: boolean;
+}
+/**
+ * Convert an area name to a stable filesystem-safe identifier.
+ * E.g., "Reading & Editing Files" → "reading-editing-files"
+ */
+export declare function sanitizeAreaName(name: string): string;
+/**
+ * Run the fan-out: extract slices, invoke specifiers, retry on failure.
+ */
+export declare function runFanOut(options: FanOutOptions): Promise<FanOutResult>;
+//# sourceMappingURL=fan-out.d.ts.map

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

@@ -0,0 +1,215 @@
+/**
+ * Specifier fan-out orchestrator.
+ *
+ * For each area in the outline, extract a slice, spawn a specifier worker,
+ * and write the resulting partial to the cache. Workers run in parallel up
+ * to a bounded concurrency limit. On per-area failure (no partial written,
+ * empty partial), the worker is retried once; on second failure, the area
+ * is recorded as failed for surfacing to the user.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1.2: bounded concurrent execution
+ * - CTS-SPEC-5: failed/empty specifier output is detected and retried
+ * - CTS-OBSERVE-2.0: failure details are logged with area name + cause
+ * - CTS-RESUME-1.2: existing non-empty partial means the specifier is skipped
+ */
+import { existsSync, mkdirSync, statSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { extractSlice } from "./slice.js";
+import { runSpecifier } from "./specifier.js";
+export const DEFAULT_FAN_OUT_CONCURRENCY = 8;
+/**
+ * Convert an area name to a stable filesystem-safe identifier.
+ * E.g., "Reading & Editing Files" → "reading-editing-files"
+ */
+export function sanitizeAreaName(name) {
+    return (name
+        .replace(/[^A-Za-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .toLowerCase() || "area");
+}
+/**
+ * Run a bounded-concurrency loop over items. Workers pull items off a shared
+ * counter; at most `limit` workers run at a time.
+ */
+async function withLimit(items, limit, fn) {
+    let next = 0;
+    async function worker() {
+        while (true) {
+            const i = next++;
+            if (i >= items.length)
+                return;
+            await fn(items[i], i);
+        }
+    }
+    const workerCount = Math.min(Math.max(1, limit), items.length);
+    const workers = Array.from({ length: workerCount }, () => worker());
+    await Promise.all(workers);
+}
+function partialIsUsable(path) {
+    if (!existsSync(path))
+        return false;
+    try {
+        return statSync(path).size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Run the fan-out: extract slices, invoke specifiers, retry on failure.
+ */
+export async function runFanOut(options) {
+    const { outline, fullPackPath, partialPathFor, slicePathFor, validateCommand, styleCheckCommand, addDirs, concurrency = DEFAULT_FAN_OUT_CONCURRENCY, runner, model, progress, } = options;
+    if (!existsSync(fullPackPath)) {
+        throw new Error(`Missing full pack at ${fullPackPath}`);
+    }
+    // Sanitization is lossy ("Read & Write" and "read/write" both become
+    // "read-write"). If two areas collide, they'd share a partial file path and
+    // silently overwrite each other downstream. Catch this up front.
+    const sanitizedNames = new Map();
+    for (const area of outline.areas) {
+        const key = sanitizeAreaName(area.name);
+        const bucket = sanitizedNames.get(key) ?? [];
+        bucket.push(area.name);
+        sanitizedNames.set(key, bucket);
+    }
+    const collisions = [...sanitizedNames.entries()].filter(([, names]) => names.length > 1);
+    if (collisions.length > 0) {
+        const detail = collisions
+            .map(([key, names]) => `  "${key}" ← ${names.map((n) => `"${n}"`).join(", ")}`)
+            .join("\n");
+        throw new Error(`Outline contains area names that collide after sanitization. Rename them so each produces a unique partial file path:\n${detail}`);
+    }
+    const outcomes = outline.areas.map((area) => ({
+        area,
+        status: "failed",
+        attempts: 0,
+        partialPath: partialPathFor(sanitizeAreaName(area.name)),
+    }));
+    // Ensure partials directory exists for each area.
+    for (const outcome of outcomes) {
+        mkdirSync(dirname(outcome.partialPath), { recursive: true });
+    }
+    await withLimit(outcomes, concurrency, async (outcome) => {
+        const sanitized = sanitizeAreaName(outcome.area.name);
+        const slicePath = slicePathFor(sanitized);
+        // CTS-RESUME-1.2: skip if a non-empty partial exists from a prior run.
+        if (partialIsUsable(outcome.partialPath)) {
+            outcome.status = "skipped-resume";
+            outcome.attempts = 0;
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `(resume) skipping ${outcome.area.name} — partial exists`,
+            });
+            return;
+        }
+        // Extract this area's slice from the full pack.
+        if (outcome.area.files.length === 0) {
+            // No files assigned — write a stub partial so compose has something.
+            writeFileSync(outcome.partialPath, "_(no files assigned to this area)_\n", "utf-8");
+            outcome.status = "failed";
+            outcome.attempts = 0;
+            outcome.failureCause = "no files assigned in outline";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `!! ${outcome.area.name} has no files; marking as failed`,
+            });
+            return;
+        }
+        let sliceMatched = 0;
+        try {
+            const sliceResult = extractSlice(fullPackPath, slicePath, outcome.area.files);
+            sliceMatched = sliceResult.matched;
+        }
+        catch (err) {
+            outcome.failureCause = `slice extraction failed: ${err instanceof Error ? err.message : String(err)}`;
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `!! ${outcome.failureCause}`,
+            });
+            return;
+        }
+        if (sliceMatched === 0) {
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `(warning) slice for ${outcome.area.name} matched 0 files; specifier will need to fall back to full-pack reads`,
+            });
+        }
+        // Attempt 1
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `Running specifier for ${outcome.area.name} (attempt 1/2)`,
+        });
+        outcome.attempts = 1;
+        const r1 = await runSpecifier({
+            outline,
+            area: outcome.area,
+            slicePath,
+            fullPackPath,
+            partialPath: outcome.partialPath,
+            validateCommand,
+            styleCheckCommand,
+            addDirs,
+            runner,
+            model,
+        });
+        if (r1.wrotePartial) {
+            outcome.status = "completed";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `${outcome.area.name} done (${r1.partialBytes} bytes)`,
+            });
+            return;
+        }
+        // Attempt 2 (retry once on no/empty partial)
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `!! ${outcome.area.name} produced no partial; retrying (attempt 2/2)`,
+        });
+        outcome.attempts = 2;
+        const r2 = await runSpecifier({
+            outline,
+            area: outcome.area,
+            slicePath,
+            fullPackPath,
+            partialPath: outcome.partialPath,
+            validateCommand,
+            styleCheckCommand,
+            addDirs,
+            runner,
+            model,
+        });
+        if (r2.wrotePartial) {
+            outcome.status = "completed";
+            progress?.emit({
+                stage: "specify",
+                step: outcome.area.prefix,
+                message: `${outcome.area.name} done on retry (${r2.partialBytes} bytes)`,
+            });
+            return;
+        }
+        // Two failures — record and continue. CTS-SPEC-5 says other areas still proceed.
+        outcome.status = "failed";
+        outcome.failureCause =
+            r2.exitCode !== 0
+                ? `specifier exited with code ${r2.exitCode}: ${r2.stderr.slice(0, 200)}`
+                : "specifier wrote no partial (or empty partial) on both attempts";
+        writeFileSync(outcome.partialPath, `_(missing partial — specifier failed after retry: ${outcome.failureCause})_\n`, "utf-8");
+        progress?.emit({
+            stage: "specify",
+            step: outcome.area.prefix,
+            message: `!! ${outcome.area.name} failed: ${outcome.failureCause}`,
+        });
+    });
+    const allSucceeded = outcomes.every((o) => o.status === "completed" || o.status === "skipped-resume");
+    return { outcomes, allSucceeded };
+}
+//# sourceMappingURL=fan-out.js.map

package/dist/codebase-to-spec/interactive.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interactive / non-interactive mode detection and overwrite prompting.
+ *
+ * Requirements covered:
+ * - CTS-CLI-4: CLI distinguishes interactive and non-interactive invocation modes
+ * - CTS-PRESENT-2: Overwrites in interactive mode prompt the Engineer
+ * - CTS-PRESENT-3: Overwrites in non-interactive mode require an explicit flag
+ */
+export type OverwriteChoice = "overwrite" | "skip" | "merge";
+export interface InteractiveMode {
+    /** True when running in interactive mode (TTY on stdin, or --interactive forced). */
+    isInteractive: boolean;
+    /** What the engineer chose for a given path (only used in interactive mode). */
+    prompt: (path: string) => Promise<OverwriteChoice | "cancel">;
+}
+/**
+ * Detect interactive mode. Defaults to TTY detection on stdin; can be forced
+ * by the caller via the `force` argument.
+ *
+ * @param force 'interactive' or 'non-interactive' to override TTY detection.
+ */
+export declare function detectMode(force?: "interactive" | "non-interactive"): {
+    isInteractive: boolean;
+};
+/**
+ * Prompt the engineer for an overwrite decision in interactive mode.
+ * Returns the chosen action, or `'cancel'` if the engineer dismissed the prompt.
+ */
+export declare function promptOverwriteChoice(path: string): Promise<OverwriteChoice | "cancel">;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/codebase-to-spec/interactive.js

@@ -0,0 +1,48 @@
+/**
+ * Interactive / non-interactive mode detection and overwrite prompting.
+ *
+ * Requirements covered:
+ * - CTS-CLI-4: CLI distinguishes interactive and non-interactive invocation modes
+ * - CTS-PRESENT-2: Overwrites in interactive mode prompt the Engineer
+ * - CTS-PRESENT-3: Overwrites in non-interactive mode require an explicit flag
+ */
+import prompts from "prompts";
+/**
+ * Detect interactive mode. Defaults to TTY detection on stdin; can be forced
+ * by the caller via the `force` argument.
+ *
+ * @param force 'interactive' or 'non-interactive' to override TTY detection.
+ */
+export function detectMode(force) {
+    if (force === "interactive")
+        return { isInteractive: true };
+    if (force === "non-interactive")
+        return { isInteractive: false };
+    // TTY detection
+    return { isInteractive: !!process.stdin.isTTY };
+}
+/**
+ * Prompt the engineer for an overwrite decision in interactive mode.
+ * Returns the chosen action, or `'cancel'` if the engineer dismissed the prompt.
+ */
+export async function promptOverwriteChoice(path) {
+    const response = await prompts({
+        type: "select",
+        name: "choice",
+        message: `Overwrite ${path}?`,
+        choices: [
+            { title: "Overwrite (replace the existing file)", value: "overwrite" },
+            { title: "Skip (leave the existing file untouched)", value: "skip" },
+            {
+                title: "Merge (keep both — append new requirements to existing)",
+                value: "merge",
+            },
+        ],
+        initial: 0,
+    });
+    if (response.choice === undefined) {
+        return "cancel";
+    }
+    return response.choice;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/codebase-to-spec/outline-review-loop.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Outline review loop: planner → reviewer → revise → reviewer → ... → approved.
+ *
+ * The reviewer runs in a SINGLE stateful claude session across turns (so it
+ * can compare prior outlines to the latest one). The planner is stateless —
+ * each invocation is fresh.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2: stateful reviewer session
+ * - CTS-PLAN-3: approved → proceed
+ * - CTS-PLAN-4: approved-with-revisions → one revision pass, then proceed
+ * - CTS-PLAN-5: requires-another-review → revision loop
+ * - CTS-PLAN-6: max-turns + convergence nudge
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { ProgressEmitter } from "./progress.js";
+import { type Outline, type OutlineReview } from "./schemas.js";
+export declare const DEFAULT_OUTLINE_LOOP_MAX_TURNS = 3;
+export interface OutlineReviewLoopOptions {
+    overviewPath: string;
+    addDirs: string[];
+    maxTurns?: number;
+    runner?: ClaudeRunner;
+    model?: string;
+    progress?: ProgressEmitter;
+    /** Override session id (for tests and reproducibility). Otherwise random. */
+    sessionId?: string;
+}
+export interface OutlineReviewLoopResult {
+    /** The final outline after the loop converges (or hits max-turns). */
+    outline: Outline;
+    /** Per-turn outline snapshots (turn 1 is the initial, then each revision). */
+    outlinesByTurn: Outline[];
+    /** Per-turn reviewer results. */
+    reviewsByTurn: OutlineReview[];
+    /** The final reviewer verdict. */
+    finalVerdict: OutlineReview["verdict"];
+    /** Number of review turns used (= length of reviewsByTurn). */
+    turnsUsed: number;
+    /** True if the loop hit max-turns without converging. */
+    hitMaxTurns: boolean;
+}
+/**
+ * Run the outline review loop end-to-end.
+ *
+ * Returns the final outline (after applying mechanical revisions if the
+ * verdict was `approved-with-revisions`), the per-turn trace, and the final
+ * verdict.
+ */
+export declare function runOutlineReviewLoop(options: OutlineReviewLoopOptions): Promise<OutlineReviewLoopResult>;
+//# sourceMappingURL=outline-review-loop.d.ts.map