@popoverai/dotrequirements 0.23.0 → 0.24.0

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

@@ -0,0 +1,54 @@
+/**
+ * Cache directory layout and path helpers for codebase-to-spec.
+ *
+ * All pipeline artifacts live under `.dotrequirements-cache/` in the project
+ * root. Wrappers and downstream stages read cached inputs by these paths;
+ * resumability (CTS-RESUME-1..4) is driven by the presence/absence of these
+ * files.
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: pack stage paths (overview.txt, source.txt)
+ * - CTS-RESUME-1..4: per-stage cache detection
+ */
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+export const CACHE_DIR_NAME = ".dotrequirements-cache";
+export function cachePaths(projectRoot) {
+    const root = join(projectRoot, CACHE_DIR_NAME);
+    return {
+        root,
+        overview: join(root, "overview.txt"),
+        source: join(root, "source.txt"),
+        outlineFinal: join(root, "outline-final.json"),
+        outlineTurn: (n) => join(root, `outline-${n}.json`),
+        outlineReviewTurn: (n) => join(root, `outline-review-${n}.json`),
+        partialsDir: join(root, "partials"),
+        partial: (name) => join(root, "partials", `${name}.partial.md`),
+        composedSpec: join(root, "spec-composed.md"),
+        specVersion: (n) => join(root, `spec-v${n}.md`),
+        specReviewTurn: (n) => join(root, `spec-review-${n}.json`),
+        specFinal: join(root, "spec-final.md"),
+        pipelineSummary: join(root, "pipeline-summary.json"),
+    };
+}
+export function ensureCacheDir(projectRoot) {
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.root)) {
+        mkdirSync(paths.root, { recursive: true });
+    }
+    if (!existsSync(paths.partialsDir)) {
+        mkdirSync(paths.partialsDir, { recursive: true });
+    }
+    return paths;
+}
+/**
+ * Remove all cached artifacts. Used by `--fresh`.
+ * Requirement: CTS-RESUME-4
+ */
+export function clearCache(projectRoot) {
+    const root = join(projectRoot, CACHE_DIR_NAME);
+    if (existsSync(root)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=cache.js.map

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

@@ -0,0 +1,69 @@
+/**
+ * `claude -p` subprocess wrapper for codebase-to-spec.
+ *
+ * Provides a small typed surface for invoking the user's Claude Code agent in
+ * non-interactive (print) mode, with optional stateful session continuation
+ * and JSON-schema output validation.
+ *
+ * Why this lives here:
+ * - The pipeline spawns the user's claude binary, inheriting the user's
+ *   environment so whatever auth mode they've configured (API key, OAuth via
+ *   Claude Code subscription, etc.) is what gets used.
+ * - Each invocation is a separate context window. Stateful loops use
+ *   --session-id and --resume to maintain conversation state across turns.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
+ * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ */
+export interface ClaudeRunOptions {
+    /** System prompt content (passed via --system-prompt). */
+    systemPrompt: string;
+    /** User message (passed as final positional arg). */
+    userMessage: string;
+    /** Model alias (e.g., 'sonnet') or full name. Defaults to 'sonnet'. */
+    model?: string;
+    /** Tools the agent may use. Defaults to ['Read']. */
+    tools?: string[];
+    /** Directories to grant filesystem access to (via --add-dir). */
+    addDirs?: string[];
+    /** Optional JSON schema for structured output validation. */
+    jsonSchema?: object;
+    /**
+     * Stateful session control:
+     * - `{ kind: 'fresh', sessionId: '<uuid>' }` — create a new session with this id
+     * - `{ kind: 'resume', sessionId: '<uuid>' }` — continue an existing session
+     * - omitted / undefined — stateless, no persistence
+     */
+    session?: {
+        kind: "fresh";
+        sessionId: string;
+    } | {
+        kind: "resume";
+        sessionId: string;
+    };
+    /** Override the working directory. Defaults to system temp dir. */
+    cwd?: string;
+    /** Override permission mode. Defaults to 'bypassPermissions'. */
+    permissionMode?: "bypassPermissions" | "auto" | "default" | "acceptEdits";
+    /** Path to the claude binary. Defaults to 'claude' (found in PATH). */
+    claudeBinary?: string;
+}
+export interface ClaudeRunResult {
+    /** Process exit code. */
+    exitCode: number;
+    /** Captured stdout. */
+    stdout: string;
+    /** Captured stderr. */
+    stderr: string;
+}
+/**
+ * Default runner — spawns the `claude` binary as a subprocess.
+ */
+export declare function runClaude(options: ClaudeRunOptions): Promise<ClaudeRunResult>;
+/**
+ * Pluggable runner interface so tests can swap in a mock without spawning
+ * a real subprocess. Production code uses `runClaude`; tests pass a fake.
+ */
+export type ClaudeRunner = (options: ClaudeRunOptions) => Promise<ClaudeRunResult>;
+//# sourceMappingURL=claude.d.ts.map

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

@@ -0,0 +1,126 @@
+/**
+ * `claude -p` subprocess wrapper for codebase-to-spec.
+ *
+ * Provides a small typed surface for invoking the user's Claude Code agent in
+ * non-interactive (print) mode, with optional stateful session continuation
+ * and JSON-schema output validation.
+ *
+ * Why this lives here:
+ * - The pipeline spawns the user's claude binary, inheriting the user's
+ *   environment so whatever auth mode they've configured (API key, OAuth via
+ *   Claude Code subscription, etc.) is what gets used.
+ * - Each invocation is a separate context window. Stateful loops use
+ *   --session-id and --resume to maintain conversation state across turns.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
+ * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ */
+import { spawn } from "node:child_process";
+import { tmpdir } from "node:os";
+/**
+ * Default runner — spawns the `claude` binary as a subprocess.
+ */
+export async function runClaude(options) {
+    const { systemPrompt, userMessage, model = "sonnet", tools = ["Read"], addDirs = [], jsonSchema, session, cwd = tmpdir(), permissionMode = "bypassPermissions", claudeBinary = "claude", } = options;
+    const args = ["-p"];
+    args.push("--model", model);
+    args.push("--permission-mode", permissionMode);
+    // `--output-format text` does NOT enforce `--json-schema` (we verified this
+    // empirically). When we want schema-enforced JSON we need
+    // `--output-format json`, which wraps the response in a metadata envelope
+    // whose `structured_output` field contains the validated JSON.
+    args.push("--output-format", jsonSchema ? "json" : "text");
+    if (tools.length > 0) {
+        args.push("--tools", tools.join(","));
+    }
+    for (const dir of addDirs) {
+        args.push("--add-dir", dir);
+    }
+    if (jsonSchema) {
+        args.push("--json-schema", JSON.stringify(jsonSchema));
+    }
+    if (session) {
+        if (session.kind === "fresh") {
+            args.push("--session-id", session.sessionId);
+        }
+        else {
+            args.push("--resume", session.sessionId);
+            // On resume we still need to re-pass permission mode and add-dirs;
+            // resume doesn't preserve them by default.
+        }
+    }
+    else {
+        args.push("--no-session-persistence");
+    }
+    // System prompt — only on initial calls. On resume, the system prompt is
+    // already baked into the session and re-passing it can confuse the agent.
+    if (!session || session.kind === "fresh") {
+        args.push("--append-system-prompt", systemPrompt);
+    }
+    // The user message is always the final positional arg.
+    args.push(userMessage);
+    return new Promise((resolve, reject) => {
+        const child = spawn(claudeBinary, args, {
+            cwd,
+            // Inherit the parent environment so `claude -p` uses whatever auth
+            // mode the user has configured (API key if set, OAuth otherwise).
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        // Close stdin immediately — we pass user message via argv, not stdin.
+        child.stdin.end();
+        let stdout = "";
+        let stderr = "";
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            const exitCode = code ?? 0;
+            // If we asked for schema-validated JSON, claude -p returns a metadata
+            // envelope. Extract the agent's actual output from `structured_output`
+            // (preferred) or `result` (fallback). Callers expect `stdout` to
+            // contain only the agent's output, not the envelope.
+            if (jsonSchema && exitCode === 0 && stdout.trim().length > 0) {
+                try {
+                    const envelope = JSON.parse(stdout);
+                    if (envelope && typeof envelope === "object") {
+                        if (envelope.is_error) {
+                            // Surface the API error message on stderr so callers can see it.
+                            const apiErrSnippet = typeof envelope.result === "string"
+                                ? envelope.result
+                                : JSON.stringify(envelope);
+                            resolve({
+                                exitCode: exitCode || 1,
+                                stdout: "",
+                                stderr: `${stderr}\nclaude -p reported is_error: ${apiErrSnippet}`,
+                            });
+                            return;
+                        }
+                        if ("structured_output" in envelope) {
+                            resolve({
+                                exitCode,
+                                stdout: JSON.stringify(envelope.structured_output),
+                                stderr,
+                            });
+                            return;
+                        }
+                        if (typeof envelope.result === "string") {
+                            resolve({ exitCode, stdout: envelope.result, stderr });
+                            return;
+                        }
+                    }
+                }
+                catch {
+                    // Fall through to raw stdout. Caller's parser will surface the
+                    // schema-validation failure.
+                }
+            }
+            resolve({ exitCode, stdout, stderr });
+        });
+    });
+}
+//# sourceMappingURL=claude.js.map

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

@@ -0,0 +1,49 @@
+/**
+ * Compose stage: assemble per-area partials into a single composed spec.
+ *
+ * The composed document has YAML frontmatter (title, defaultPrefix), an H1
+ * title, a summary paragraph from the outline, and one H2 section per area.
+ * Each area section contains the partial's content.
+ *
+ * After assembly, schema validation runs over the document. Mechanical errors
+ * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
+ * errors surface to the caller.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
+ * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ */
+import type { Outline } from "./schemas.js";
+export interface ComposeOptions {
+    outline: Outline;
+    /** Resolves an area's sanitized name to its partial file path. */
+    partialPathFor: (sanitizedAreaName: string) => string;
+    /** Where to write the composed spec. */
+    composedPath: string;
+}
+export interface ComposeResult {
+    /** Path the composed spec was written to. */
+    composedPath: string;
+    /** Number of partials that contributed content. */
+    partialsIncluded: number;
+    /** Number of areas whose partial was missing or marked as missing. */
+    partialsMissing: number;
+    /** Validation outcome — undefined when validation passes. */
+    validationError?: string;
+}
+/**
+ * Assemble the composed Markdown document.
+ *
+ * Public so tests can call without disk side effects (composedPath isn't used
+ * here; the caller writes the returned string).
+ */
+export declare function assembleComposedDocument(outline: Outline, partialPathFor: (sanitized: string) => string): {
+    content: string;
+    partialsIncluded: number;
+    partialsMissing: number;
+};
+/**
+ * Compose the spec and write it to disk. Validates the result.
+ */
+export declare function runCompose(options: ComposeOptions): ComposeResult;
+//# sourceMappingURL=compose.d.ts.map

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

@@ -0,0 +1,124 @@
+/**
+ * Compose stage: assemble per-area partials into a single composed spec.
+ *
+ * The composed document has YAML frontmatter (title, defaultPrefix), an H1
+ * title, a summary paragraph from the outline, and one H2 section per area.
+ * Each area section contains the partial's content.
+ *
+ * After assembly, schema validation runs over the document. Mechanical errors
+ * (duplicate IDs within an area, etc.) trigger deterministic fixes; other
+ * errors surface to the caller.
+ *
+ * Requirements covered:
+ * - CTS-COMPOSE-1: Compose produces a single Markdown document from partials
+ * - CTS-COMPOSE-2: Compose validates the resulting document and corrects mechanical errors
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { parseRequirementsFile } from "../schema/parser.js";
+import { sanitizeAreaName } from "./fan-out.js";
+/**
+ * Read a partial file. If missing or marked as a missing-partial placeholder,
+ * return null (caller will emit a stub section).
+ */
+function readPartial(path) {
+    if (!existsSync(path))
+        return null;
+    const content = readFileSync(path, "utf-8");
+    const trimmed = content.trim();
+    if (!trimmed)
+        return null;
+    // Common placeholders for missing partials produced by fan-out on failure
+    // or by zero-files-assigned areas.
+    if (trimmed.startsWith("_(missing partial") ||
+        trimmed.startsWith("_(no files assigned")) {
+        return null;
+    }
+    return content;
+}
+/**
+ * Assemble the composed Markdown document.
+ *
+ * Public so tests can call without disk side effects (composedPath isn't used
+ * here; the caller writes the returned string).
+ */
+export function assembleComposedDocument(outline, partialPathFor) {
+    const parts = [];
+    parts.push("---");
+    parts.push("document:");
+    parts.push(`  title: "${escapeYamlString(outline.title)}"`);
+    parts.push(`  defaultPrefix: ${outline.defaultPrefix}`);
+    parts.push("---");
+    parts.push("");
+    parts.push(`# ${outline.title}`);
+    parts.push("");
+    parts.push(outline.summary.trim());
+    parts.push("");
+    let partialsIncluded = 0;
+    let partialsMissing = 0;
+    for (const area of outline.areas) {
+        const sanitized = sanitizeAreaName(area.name);
+        const partialPath = partialPathFor(sanitized);
+        parts.push("---");
+        parts.push("");
+        parts.push(`## ${area.name}`);
+        parts.push("");
+        const partial = readPartial(partialPath);
+        if (partial) {
+            parts.push(partial.trim());
+            partialsIncluded++;
+        }
+        else {
+            parts.push(`_(partial for ${area.name} is missing or empty — surface this to the user when presenting the spec)_`);
+            partialsMissing++;
+        }
+        parts.push("");
+    }
+    return {
+        content: parts.join("\n"),
+        partialsIncluded,
+        partialsMissing,
+    };
+}
+/** Escape a string for safe YAML scalar use. */
+function escapeYamlString(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/**
+ * Attempt to fix mechanical errors in a composed document.
+ *
+ * For v0, the simplest mechanical fix is duplicate IDs within an area —
+ * we detect and renumber them sequentially. Position-path and Gherkin syntax
+ * errors surface to the validator's caller; we don't auto-fix those because
+ * the editor loop is better suited to it.
+ */
+function fixMechanicalErrors(content) {
+    // Detect duplicate IDs (lines like "PREFIX-AREA-001: ...") within each area.
+    // For v0 we punt — the schema validator will catch them and the caller will
+    // surface to the user. Returning content unchanged keeps the contract: the
+    // function is a no-op for inputs without fixable errors.
+    return content;
+}
+/**
+ * Compose the spec and write it to disk. Validates the result.
+ */
+export function runCompose(options) {
+    const { outline, partialPathFor, composedPath } = options;
+    const { content, partialsIncluded, partialsMissing } = assembleComposedDocument(outline, partialPathFor);
+    const finalContent = fixMechanicalErrors(content);
+    writeFileSync(composedPath, finalContent, "utf-8");
+    // Validate
+    let validationError;
+    try {
+        parseRequirementsFile(finalContent);
+    }
+    catch (err) {
+        validationError = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        composedPath,
+        partialsIncluded,
+        partialsMissing,
+        validationError,
+    };
+}
+//# sourceMappingURL=compose.js.map

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

@@ -0,0 +1,54 @@
+/**
+ * Spec review + editor loop.
+ *
+ * Same structure as the outline review loop, scaled up for document-level
+ * revision: stateful spec reviewer + stateless editor. The reviewer
+ * persists across turns so it can compare prior spec versions to the latest.
+ *
+ * Requirements covered:
+ * - CTS-EDIT-1: stateful spec reviewer
+ * - CTS-EDIT-2: approved → proceed
+ * - CTS-EDIT-3: approved-with-revisions → one mechanical edit pass
+ * - CTS-EDIT-4: requires-another-review → revise & resubmit
+ * - CTS-EDIT-5: editor operates on cohesive document
+ * - CTS-EDIT-6: max-turns + convergence nudge
+ */
+import { type ClaudeRunner } from "./claude.js";
+import type { ProgressEmitter } from "./progress.js";
+import { type SpecReview } from "./schemas.js";
+export declare const DEFAULT_EDIT_LOOP_MAX_TURNS = 6;
+export interface EditLoopOptions {
+    /** Path to the composed spec (input). */
+    composedSpecPath: string;
+    /**
+     * Resolver: given a turn number (1-indexed), return the path the editor's
+     * output for that turn should land at. Loop persists each version.
+     */
+    specVersionFor: (turn: number) => string;
+    /** Path to the codebase pack. */
+    fullPackPath: string;
+    /** Directories for filesystem access. */
+    addDirs: string[];
+    maxTurns?: number;
+    runner?: ClaudeRunner;
+    model?: string;
+    progress?: ProgressEmitter;
+    /** Override session id (for tests / reproducibility). */
+    sessionId?: string;
+}
+export interface EditLoopResult {
+    /** Path to the final spec (post-edit if applicable). */
+    finalSpecPath: string;
+    /** Per-turn spec paths (turn 1 is the composed-spec copy, then each revision). */
+    specPathsByTurn: string[];
+    /** Per-turn reviewer results. */
+    reviewsByTurn: SpecReview[];
+    /** The final reviewer verdict. */
+    finalVerdict: SpecReview["verdict"];
+    /** Number of review turns used. */
+    turnsUsed: number;
+    /** True if the loop hit max-turns without converging. */
+    hitMaxTurns: boolean;
+}
+export declare function runEditLoop(options: EditLoopOptions): Promise<EditLoopResult>;
+//# sourceMappingURL=edit-loop.d.ts.map

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

@@ -0,0 +1,195 @@
+/**
+ * Spec review + editor loop.
+ *
+ * Same structure as the outline review loop, scaled up for document-level
+ * revision: stateful spec reviewer + stateless editor. The reviewer
+ * persists across turns so it can compare prior spec versions to the latest.
+ *
+ * Requirements covered:
+ * - CTS-EDIT-1: stateful spec reviewer
+ * - CTS-EDIT-2: approved → proceed
+ * - CTS-EDIT-3: approved-with-revisions → one mechanical edit pass
+ * - CTS-EDIT-4: requires-another-review → revise & resubmit
+ * - CTS-EDIT-5: editor operates on cohesive document
+ * - CTS-EDIT-6: max-turns + convergence nudge
+ */
+import { randomUUID } from "node:crypto";
+import { copyFileSync } from "node:fs";
+import { runClaude } from "./claude.js";
+import { runEditor } from "./editor.js";
+import { SPEC_REVIEWER_PROMPT } from "./prompts/spec-reviewer.js";
+import { parseSpecReview, SPEC_REVIEW_JSON_SCHEMA, } from "./schemas.js";
+export const DEFAULT_EDIT_LOOP_MAX_TURNS = 6;
+function reviewerUserMessageInitial(specPath, packPath) {
+    return [
+        `Initial spec review.`,
+        ``,
+        `Composed spec: ${specPath}`,
+        `Codebase pack: ${packPath}`,
+        ``,
+        `Read both via the Read tool, then produce your critique JSON.`,
+    ].join("\n");
+}
+function reviewerUserMessageRevised(turn, specPath, packPath, nudge) {
+    const lines = [
+        `Review turn ${turn}. The editor has revised the spec based on your prior feedback.`,
+        ``,
+    ];
+    if (nudge) {
+        lines.push(nudge, ``);
+    }
+    lines.push(`Revised spec: ${specPath}`, `Codebase pack at ${packPath} is unchanged.`, ``, `Read the revised spec, compare to the prior version, and produce your critique JSON.`);
+    return lines.join("\n");
+}
+function convergenceNudge(turn, maxTurns) {
+    return `CONVERGENCE NUDGE: This is review turn ${turn} of ${maxTurns} maximum. Please prioritize convergence. Your job is still to only approve a genuinely-ready spec, but if it is close, lean toward \`approved-with-revisions\` over \`requires-another-review\`. Reserve \`requires-another-review\` for genuine issues that the editor has not addressed despite prior feedback.`;
+}
+async function callReviewer(args) {
+    const result = await args.runner({
+        systemPrompt: SPEC_REVIEWER_PROMPT,
+        userMessage: args.userMessage,
+        model: args.model,
+        tools: ["Read", "Grep", "Glob"],
+        addDirs: args.addDirs,
+        jsonSchema: SPEC_REVIEW_JSON_SCHEMA,
+        session: {
+            kind: args.isFirstTurn ? "fresh" : "resume",
+            sessionId: args.sessionId,
+        },
+    });
+    if (result.exitCode !== 0) {
+        throw new Error(`Spec reviewer failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
+    }
+    // Retry-once on parse failure (CTS-EDIT-1 convention, same as outline loop).
+    try {
+        return parseSpecReview(result.stdout);
+    }
+    catch (err) {
+        const retry = await args.runner({
+            systemPrompt: SPEC_REVIEWER_PROMPT,
+            userMessage: `${args.userMessage}\n\n(Your prior output failed schema validation: ${err instanceof Error ? err.message : String(err)}. Please try again, emitting JSON only.)`,
+            model: args.model,
+            tools: ["Read", "Grep", "Glob"],
+            addDirs: args.addDirs,
+            jsonSchema: SPEC_REVIEW_JSON_SCHEMA,
+            session: { kind: "resume", sessionId: args.sessionId },
+        });
+        if (retry.exitCode !== 0) {
+            throw new Error(`Spec reviewer retry failed (exit ${retry.exitCode}): ${retry.stderr || retry.stdout}`);
+        }
+        return parseSpecReview(retry.stdout);
+    }
+}
+export async function runEditLoop(options) {
+    const { composedSpecPath, specVersionFor, fullPackPath, addDirs, maxTurns = DEFAULT_EDIT_LOOP_MAX_TURNS, runner = runClaude, model, progress, sessionId = randomUUID(), } = options;
+    // Turn 1: copy the composed spec to spec-v1 and review it.
+    const specV1 = specVersionFor(1);
+    copyFileSync(composedSpecPath, specV1);
+    progress?.emit({
+        stage: "spec-review",
+        step: "turn-1",
+        message: `Reviewing composed spec (${specV1})`,
+    });
+    let review = await callReviewer({
+        runner,
+        sessionId,
+        isFirstTurn: true,
+        userMessage: reviewerUserMessageInitial(specV1, fullPackPath),
+        addDirs,
+        model,
+    });
+    const specPathsByTurn = [specV1];
+    const reviewsByTurn = [review];
+    let currentSpecPath = specV1;
+    progress?.emit({
+        stage: "spec-review",
+        step: "turn-1",
+        message: `Verdict: ${review.verdict}`,
+        data: { verdict: review.verdict },
+    });
+    let turn = 1;
+    while (review.verdict === "requires-another-review" && turn < maxTurns) {
+        turn++;
+        const nextSpec = specVersionFor(turn);
+        progress?.emit({
+            stage: "spec-review",
+            step: `edit-turn-${turn}`,
+            message: `Editor revising spec (turn ${turn}/${maxTurns})`,
+        });
+        const editResult = await runEditor({
+            inputSpecPath: currentSpecPath,
+            outputSpecPath: nextSpec,
+            fullPackPath,
+            addDirs,
+            critique: review,
+            mode: "revise",
+            runner,
+            model,
+        });
+        if (!editResult.wroteSpec) {
+            throw new Error(`Editor produced no output spec at ${nextSpec} (exit ${editResult.exitCode}): ${editResult.stderr}`);
+        }
+        currentSpecPath = nextSpec;
+        specPathsByTurn.push(currentSpecPath);
+        const nudge = turn >= maxTurns - 1 && turn !== maxTurns
+            ? convergenceNudge(turn, maxTurns)
+            : undefined;
+        progress?.emit({
+            stage: "spec-review",
+            step: `turn-${turn}`,
+            message: `Reviewing revised spec (turn ${turn}/${maxTurns})`,
+            data: { turn, maxTurns, nudge: !!nudge },
+        });
+        review = await callReviewer({
+            runner,
+            sessionId,
+            isFirstTurn: false,
+            userMessage: reviewerUserMessageRevised(turn, currentSpecPath, fullPackPath, nudge),
+            addDirs,
+            model,
+        });
+        reviewsByTurn.push(review);
+        progress?.emit({
+            stage: "spec-review",
+            step: `turn-${turn}`,
+            message: `Verdict: ${review.verdict}`,
+            data: { verdict: review.verdict },
+        });
+    }
+    const hitMaxTurns = review.verdict === "requires-another-review" && turn >= maxTurns;
+    // approved-with-revisions → apply mechanical revisions to a final version.
+    if (review.verdict === "approved-with-revisions" &&
+        review.revisions.length > 0) {
+        const finalTurn = turn + 1;
+        const finalPath = specVersionFor(finalTurn);
+        progress?.emit({
+            stage: "spec-review",
+            step: "apply-revisions",
+            message: `Applying ${review.revisions.length} mechanical revision(s)`,
+        });
+        const applyResult = await runEditor({
+            inputSpecPath: currentSpecPath,
+            outputSpecPath: finalPath,
+            fullPackPath,
+            addDirs,
+            critique: review,
+            mode: "apply",
+            runner,
+            model,
+        });
+        if (!applyResult.wroteSpec) {
+            throw new Error(`Apply-mode editor produced no output spec at ${finalPath} (exit ${applyResult.exitCode}): ${applyResult.stderr}`);
+        }
+        currentSpecPath = finalPath;
+        specPathsByTurn.push(currentSpecPath);
+    }
+    return {
+        finalSpecPath: currentSpecPath,
+        specPathsByTurn,
+        reviewsByTurn,
+        finalVerdict: review.verdict,
+        turnsUsed: turn,
+        hitMaxTurns,
+    };
+}
+//# sourceMappingURL=edit-loop.js.map