@popoverai/dotrequirements 0.26.0 → 0.26.2

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

@@ -1,215 +0,0 @@
-/**
- * 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/outline-review-loop.d.ts

@@ -1,51 +0,0 @@
-/**
- * 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

package/dist/codebase-to-spec/outline-review-loop.js

@@ -1,187 +0,0 @@
-/**
- * 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 { randomUUID } from "node:crypto";
-import { runClaude } from "./claude.js";
-import { runInitialPlanner, runRevisingPlanner, } from "./planner.js";
-import { OUTLINE_REVIEWER_PROMPT } from "./prompts/outline-reviewer.js";
-import { OUTLINE_REVIEW_JSON_SCHEMA, parseOutlineReview, } from "./schemas.js";
-export const DEFAULT_OUTLINE_LOOP_MAX_TURNS = 3;
-function reviewerUserMessageInitial(overviewPath, outline) {
-    return [
-        `Initial outline review.`,
-        ``,
-        `The compressed packed codebase is at: ${overviewPath}`,
-        ``,
-        `## Outline`,
-        `\`\`\`json`,
-        JSON.stringify(outline, null, 2),
-        `\`\`\``,
-        ``,
-        `Read the codebase if you need to verify file paths or coverage gaps, then produce your critique JSON.`,
-    ].join("\n");
-}
-function reviewerUserMessageRevised(turn, overviewPath, outline, nudge) {
-    const parts = [
-        `Review turn ${turn}. The planner has revised the outline based on your prior feedback.`,
-        ``,
-    ];
-    if (nudge) {
-        parts.push(nudge, ``);
-    }
-    parts.push(`The codebase pack at ${overviewPath} is unchanged.`, ``, `## Revised outline`, `\`\`\`json`, JSON.stringify(outline, null, 2), `\`\`\``, ``, `Compare this outline to the prior one. Report on what was fixed, what is still open, and what (if anything) was introduced as a new issue. Then produce your critique JSON.`);
-    return parts.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 outline, but if it is close, lean toward \`approved-with-revisions\` over \`requires-another-review\`. Reserve \`requires-another-review\` for genuine structural problems that the planner has not addressed despite prior feedback.`;
-}
-async function callReviewer(args) {
-    const result = await args.runner({
-        systemPrompt: OUTLINE_REVIEWER_PROMPT,
-        userMessage: args.userMessage,
-        model: args.model,
-        tools: ["Read", "Grep"],
-        addDirs: args.addDirs,
-        jsonSchema: OUTLINE_REVIEW_JSON_SCHEMA,
-        session: {
-            kind: args.isFirstTurn ? "fresh" : "resume",
-            sessionId: args.sessionId,
-        },
-    });
-    if (result.exitCode !== 0) {
-        throw new Error(`Outline reviewer failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
-    }
-    // On parse failure, retry the same turn once before failing.
-    // CTS-PLAN-2 requirement: "on validation failure the CLI logs the parse error
-    // and retries the same turn once before failing the loop"
-    try {
-        return parseOutlineReview(result.stdout);
-    }
-    catch (err) {
-        // Retry once
-        const retry = await args.runner({
-            systemPrompt: OUTLINE_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"],
-            addDirs: args.addDirs,
-            jsonSchema: OUTLINE_REVIEW_JSON_SCHEMA,
-            session: { kind: "resume", sessionId: args.sessionId },
-        });
-        if (retry.exitCode !== 0) {
-            throw new Error(`Outline reviewer retry failed (exit ${retry.exitCode}): ${retry.stderr || retry.stdout}`);
-        }
-        return parseOutlineReview(retry.stdout);
-    }
-}
-/**
- * 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 async function runOutlineReviewLoop(options) {
-    const { overviewPath, addDirs, maxTurns = DEFAULT_OUTLINE_LOOP_MAX_TURNS, runner = runClaude, model, progress, sessionId = randomUUID(), } = options;
-    const plannerCtx = { overviewPath, addDirs, runner, model };
-    // Turn 1 — initial planner + initial reviewer
-    progress?.emit({
-        stage: "plan",
-        step: "planner-initial",
-        message: "Generating initial outline",
-    });
-    const outline1 = await runInitialPlanner(plannerCtx);
-    const outlinesByTurn = [outline1];
-    const reviewsByTurn = [];
-    progress?.emit({
-        stage: "outline-review",
-        step: "turn-1",
-        message: `Reviewing initial outline (${outline1.areas.length} areas)`,
-    });
-    let currentOutline = outline1;
-    let review = await callReviewer({
-        runner,
-        sessionId,
-        isFirstTurn: true,
-        userMessage: reviewerUserMessageInitial(overviewPath, outline1),
-        addDirs,
-        model,
-    });
-    reviewsByTurn.push(review);
-    progress?.emit({
-        stage: "outline-review",
-        step: "turn-1",
-        message: `Verdict: ${review.verdict}`,
-        data: { verdict: review.verdict },
-    });
-    let turn = 1;
-    while (review.verdict === "requires-another-review" && turn < maxTurns) {
-        turn++;
-        progress?.emit({
-            stage: "plan",
-            step: `revise-turn-${turn}`,
-            message: "Revising outline based on critique",
-        });
-        currentOutline = await runRevisingPlanner(plannerCtx, currentOutline, review);
-        outlinesByTurn.push(currentOutline);
-        const nudge = turn >= maxTurns - 1 && turn !== maxTurns
-            ? convergenceNudge(turn, maxTurns)
-            : undefined;
-        progress?.emit({
-            stage: "outline-review",
-            step: `turn-${turn}`,
-            message: `Reviewing revised outline (turn ${turn}/${maxTurns})`,
-            data: { turn, maxTurns, nudge: !!nudge },
-        });
-        review = await callReviewer({
-            runner,
-            sessionId,
-            isFirstTurn: false,
-            userMessage: reviewerUserMessageRevised(turn, overviewPath, currentOutline, nudge),
-            addDirs,
-            model,
-        });
-        reviewsByTurn.push(review);
-        progress?.emit({
-            stage: "outline-review",
-            step: `turn-${turn}`,
-            message: `Verdict: ${review.verdict}`,
-            data: { verdict: review.verdict },
-        });
-    }
-    const hitMaxTurns = review.verdict === "requires-another-review" && turn >= maxTurns;
-    // If the verdict ended on approved-with-revisions, run the planner once
-    // more to apply the listed revisions. Same agent as the revise loop; the
-    // difference is that we proceed to fan-out instead of looping back to
-    // review.
-    if (review.verdict === "approved-with-revisions" &&
-        review.revisions.length > 0) {
-        progress?.emit({
-            stage: "plan",
-            step: "apply-revisions",
-            message: `Applying ${review.revisions.length} revision(s)`,
-        });
-        currentOutline = await runRevisingPlanner(plannerCtx, currentOutline, review);
-        outlinesByTurn.push(currentOutline);
-    }
-    return {
-        outline: currentOutline,
-        outlinesByTurn,
-        reviewsByTurn,
-        finalVerdict: review.verdict,
-        turnsUsed: turn,
-        hitMaxTurns,
-    };
-}
-//# sourceMappingURL=outline-review-loop.js.map

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

@@ -1,41 +0,0 @@
-/**
- * Planner functions (initial and revise).
- *
- * Two modes correspond to two places the planner is invoked:
- * - initial: first outline from the compressed pack (CTS-PLAN-1)
- * - revise:  address reviewer feedback — works for both
- *            `requires-another-review` (CTS-PLAN-5) and
- *            `approved-with-revisions` (CTS-PLAN-4). The orchestration
- *            decides whether to loop back to the reviewer or proceed to
- *            fan-out.
- *
- * Each mode is stateless — a fresh claude -p session per call.
- */
-import { type ClaudeRunner } from "./claude.js";
-import { type Outline, type OutlineReview } from "./schemas.js";
-export interface PlannerContext {
-    /** Path to the compressed pack file (readable by the spawned agent). */
-    overviewPath: string;
-    /** Directories the agent should have read access to (e.g., the cache dir). */
-    addDirs: string[];
-    /** Optional claude runner override (for tests). */
-    runner?: ClaudeRunner;
-    /** Optional model override. */
-    model?: string;
-}
-/**
- * Run the planner in initial mode and return a parsed outline.
- * Requirement: CTS-PLAN-1
- */
-export declare function runInitialPlanner(ctx: PlannerContext): Promise<Outline>;
-/**
- * Run the planner in revise mode — produce a new outline that addresses the
- * reviewer's output. Handles both verdicts that trigger another planner pass:
- * `requires-another-review` (categorized findings, judgment-based) and
- * `approved-with-revisions` (explicit revisions list). The same prompt handles
- * both shapes; the prompt switches behavior based on what's in the review.
- *
- * Requirements: CTS-PLAN-4, CTS-PLAN-5
- */
-export declare function runRevisingPlanner(ctx: PlannerContext, priorOutline: Outline, review: OutlineReview): Promise<Outline>;
-//# sourceMappingURL=planner.d.ts.map

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

@@ -1,76 +0,0 @@
-/**
- * Planner functions (initial and revise).
- *
- * Two modes correspond to two places the planner is invoked:
- * - initial: first outline from the compressed pack (CTS-PLAN-1)
- * - revise:  address reviewer feedback — works for both
- *            `requires-another-review` (CTS-PLAN-5) and
- *            `approved-with-revisions` (CTS-PLAN-4). The orchestration
- *            decides whether to loop back to the reviewer or proceed to
- *            fan-out.
- *
- * Each mode is stateless — a fresh claude -p session per call.
- */
-import { runClaude } from "./claude.js";
-import { PLANNER_INITIAL_PROMPT } from "./prompts/planner-initial.js";
-import { PLANNER_REVISE_PROMPT } from "./prompts/planner-revise.js";
-import { OUTLINE_JSON_SCHEMA, parseOutline, } from "./schemas.js";
-/**
- * Run the planner in initial mode and return a parsed outline.
- * Requirement: CTS-PLAN-1
- */
-export async function runInitialPlanner(ctx) {
-    const runner = ctx.runner ?? runClaude;
-    const result = await runner({
-        systemPrompt: PLANNER_INITIAL_PROMPT,
-        userMessage: `The compressed packed codebase is at: ${ctx.overviewPath}\n\nRead it and produce the outline JSON described in your system prompt.`,
-        model: ctx.model,
-        tools: ["Read"],
-        addDirs: ctx.addDirs,
-        jsonSchema: OUTLINE_JSON_SCHEMA,
-    });
-    if (result.exitCode !== 0) {
-        throw new Error(`Planner failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
-    }
-    return parseOutline(result.stdout);
-}
-/**
- * Run the planner in revise mode — produce a new outline that addresses the
- * reviewer's output. Handles both verdicts that trigger another planner pass:
- * `requires-another-review` (categorized findings, judgment-based) and
- * `approved-with-revisions` (explicit revisions list). The same prompt handles
- * both shapes; the prompt switches behavior based on what's in the review.
- *
- * Requirements: CTS-PLAN-4, CTS-PLAN-5
- */
-export async function runRevisingPlanner(ctx, priorOutline, review) {
-    const runner = ctx.runner ?? runClaude;
-    const userMessage = [
-        `The compressed packed codebase is at: ${ctx.overviewPath}`,
-        ``,
-        `## Prior outline`,
-        `\`\`\`json`,
-        JSON.stringify(priorOutline, null, 2),
-        `\`\`\``,
-        ``,
-        `## Reviewer output`,
-        `\`\`\`json`,
-        JSON.stringify(review, null, 2),
-        `\`\`\``,
-        ``,
-        `Produce a revised outline JSON that addresses the reviewer's output. Output JSON only.`,
-    ].join("\n");
-    const result = await runner({
-        systemPrompt: PLANNER_REVISE_PROMPT,
-        userMessage,
-        model: ctx.model,
-        tools: ["Read"],
-        addDirs: ctx.addDirs,
-        jsonSchema: OUTLINE_JSON_SCHEMA,
-    });
-    if (result.exitCode !== 0) {
-        throw new Error(`Revising planner failed (exit ${result.exitCode}): ${result.stderr || result.stdout}`);
-    }
-    return parseOutline(result.stdout);
-}
-//# sourceMappingURL=planner.js.map

package/dist/codebase-to-spec/prompts/outline-reviewer.d.ts

@@ -1,12 +0,0 @@
-/**
- * System prompt for the outline reviewer.
- *
- * Stateful across review turns (same conversation, same session-id). Reads
- * the outline and the compressed pack, produces a JSON object with
- * categorized findings and a verdict.
- *
- * Requirements covered:
- * - CTS-PLAN-2: Outline reviewer critiques the outline in a stateful session
- */
-export declare const OUTLINE_REVIEWER_PROMPT = "You are an outline reviewer for a codebase-to-spec pipeline. The pipeline takes a codebase, generates a planning outline (areas of behavior), then fans out specifier agents to produce detailed requirements per area. Your job: gate fan-out on outline quality. Bad outlines \u2192 wasted specifier work.\n\nThis is a **stateful conversation**. Across turns, you may receive multiple revisions of the outline, each addressing prior feedback. Track what you asked for and whether the planner addressed it.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive on each turn\n\n- The first turn includes the compressed packed codebase and the planner's first outline JSON.\n- Each subsequent turn includes a revised outline JSON. The codebase is unchanged.\n- Some turns may include a convergence nudge \u2014 read and respect it.\n\n## What counts as a customer\n\nThe outline's summary should describe what the system is and who it's for. The \"who\" is the customer \u2014 the kind of person whose needs shape what counts as behavior.\n\nA useful customer description is **specific enough to shape behavior** \u2014 it goes one level deeper than generic categories like \"end-user,\" \"administrator,\" or \"developer.\"\n\n- Not \"an end-user\" but \"a shopper\" or \"a guest checking out without an account.\"\n- Not \"an administrator\" but \"a store manager who fulfills orders\" and \"a business owner who runs reports.\"\n- Not \"a developer\" but \"a React developer integrating an eCommerce SDK,\" \"a Python data engineer building ETL pipelines,\" or \"a distributed-systems engineer wiring up a message broker.\"\n\nMost large or sprawling codebases serve more than one customer. A system whose outline reads as if built for a single customer when the code clearly serves several is missing something \u2014 and surfacing that gap is one of the most useful things you can do.\n\n**Customers consume the software; contributors work on it.** A developer can be a legitimate customer when they consume the software being specified \u2014 a React developer integrating an SDK, a Python data engineer using a library, an operator running a CLI in CI, a contributor to an open-source project who uses it as much as they extend it. But a developer whose only role is to *work on this codebase* \u2014 described as \"a contributor,\" \"an internal maintainer,\" \"a stage author building the next feature,\" or similar \u2014 is not a customer. They're the audience for code comments and architecture docs, not for behavioral requirements. Data contracts between architectural components can still be (and often should be) specified, but think about whose experience they matter for. If an interface mediates business logic between a front-end and a server, that logic should be specified in terms of what it does for the user, not what it does for the front-end developer.\n\n## What to evaluate\n\nThe outline names its customers in the summary and breaks the system into areas. Your evaluation has two parts.\n\n### Part 1 \u2014 Per-area outcome checks\n\nFor each area, apply these four criteria:\n\n1. **Relevant to a customer.** Each area must declare at least one customer in its `customers` field. Apply the consume-vs-work-on test from \"What counts as a customer\" above: a customer is someone who *uses* the software being specified, not someone who works on its codebase. An area whose `customers` field is empty, missing, or contains only developers-of-this-codebase (contributors, maintainers, stage authors) is a `framing_error` \u2014 propose either reframing the area for a real customer or dropping it. When the area's description is written in mechanism-only voice (\"the subprocess wrapper that spawns...\", \"how the pipeline generates...\") with no customer named, that's the same finding even if a customer name was bolted on after the fact.\n2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this area's name? The same name might be right for one kind of customer and wrong for another \u2014 what matters is whether it matches whom this area serves.\n3. **Groups a collection of functionality.** Does the area cover multiple related behaviors with a shared customer-meaningful purpose? An area with one isolated function, or a \"miscellaneous\" bucket of unrelated things, fails this test.\n4. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)? \"The system manages memory efficiently\" is true but not customer-observable.\n\nFailures of criterion 1, 2, or 4 are `framing_errors`. Failures of criterion 3 are `granularity_issues` \u2014 which also covers sizing problems more broadly.\n\n#### On sizing\n\nThink of organizing a big box of 100 crayons.\n\n- One drawer for all 100 crayons \u2192 impossible to find what you need.\n- 100 drawers, one crayon each \u2192 you've recreated the same problem with different semantics.\n- Organize by ROYGBIV \u2192 each drawer is a meaningful group, and you can find any crayon quickly.\n\nThe same logic applies to areas. An area too broad covers fundamentally distinct concerns; an area too narrow fragments what should hang together. Two areas that describe the same thing from different angles are a sizing problem \u2014 they should be one area, or split along a different axis. The right sizing for *this* codebase is whatever lets each area be coherent on its own and the whole set be complete.\n\n### Part 2 \u2014 Coverage and file assignment\n\n- What behavior is in the codebase but missing from any area? \u2192 `coverage_gaps`. Gaps matter most when they map to something a real customer would expect.\n- Are file paths actually present in the pack as written? Are files assigned to areas where they don't fit? Are public-contract docs (README, package metadata, LICENSE, CHANGELOG) unassigned? \u2192 `file_assignment_issues`.\n\n## On second and later turns\n\nAlso evaluate:\n\n- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.\n- Did the revision introduce new problems? Sometimes fixing one gap creates another.\n\n## Findings must be actionable\n\nA finding is only useful if the planner can act on it. Two principles:\n\n**Show your reasoning.** If your finding rests on a judgment about who the system is for, what the customer would want, or how an area should be reshaped, surface that reasoning. \"This outline doesn't read like it's for any specific customer\" gives the planner nothing to act on. \"I think this is most plausibly for a React developer integrating an eCommerce SDK; areas X and Y are organized around backend storage rather than what that developer would reach for; suggest reframing as Z\" does. Same pattern for any other \"this feels off\" finding \u2014 propose the alternative.\n\n**Be specific.** Cite paths and area names by exact spelling. \"Could be more comprehensive\" is not actionable. \"The outline has no area covering [behavior X], visible in [file Y]\" is.\n\n## Verdict types\n\nThe `verdict` field is exactly one of:\n\n- `approved` \u2014 outline is ready for fan-out as-is. No findings, or findings are negligible. Reserve for genuinely good outlines.\n- `approved-with-revisions` \u2014 outline is fundamentally sound and ready for fan-out, but includes specific small revisions that should be applied first. List the revisions in the `revisions` array. The planner will apply them mechanically without further review. Use for inline tweaks: rename a file path, split one bloated area into two, add a missing public-contract file to an area, tighten the customer description in the summary.\n- `requires-another-review` \u2014 outline has meaningful issues that need a structural fix, not just tweaks. Coverage gaps for whole subsystems, framing errors at the area level, customer set in the summary wrong or incomplete in ways that ripple through area design. The planner needs to think again, not just tweak.";
-//# sourceMappingURL=outline-reviewer.d.ts.map