@popoverai/dotrequirements 0.23.0 → 0.24.0

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

@@ -0,0 +1,187 @@
+/**
+ * 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/pack.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Pack stage: produce compressed and uncompressed views of a codebase.
+ *
+ * Wraps Repomix's programmatic API to write:
+ * - `.dotrequirements-cache/overview.txt` — compressed (tree-sitter signatures)
+ * - `.dotrequirements-cache/source.txt` — uncompressed (full source for slices)
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: Pack stage produces compressed and uncompressed views
+ * - CTS-PACK-2: Engineer can extend the ignore list per project
+ */
+import type { CachePaths } from "./cache.js";
+/**
+ * The curated default ignore list. These patterns are applied in addition to
+ * `.gitignore` and any project-level `.dotrequirements-ignore`.
+ *
+ * Sized to remove obvious non-behavioral noise: generated code, package
+ * manifests/lockfiles, vendored libraries, build artifacts, large binaries.
+ */
+export declare const DEFAULT_IGNORES: readonly string[];
+/**
+ * Read project-level ignore patterns from `.dotrequirements-ignore` (and
+ * `.dotreqignore` as a shorthand), if either exists. Returns an empty array if
+ * no file is present.
+ */
+export declare function readProjectIgnores(projectRoot: string): string[];
+export interface PackOptions {
+    projectRoot: string;
+    paths: CachePaths;
+    /** Optional scope path (subdir of projectRoot) to limit which files are packed. */
+    scope?: string;
+    /** Additional ignore patterns (beyond defaults and project-level). */
+    extraIgnores?: string[];
+}
+export interface PackResult {
+    overviewPath: string;
+    sourcePath: string;
+    /** Number of files included after ignores. */
+    fileCount: number;
+}
+/**
+ * Run Repomix twice over the same scope: once compressed, once uncompressed.
+ *
+ * We use Repomix's programmatic API rather than `npx repomix` so the CLI does
+ * not require a separate install and so we can control config precisely.
+ *
+ * NOTE: Repomix's TypeScript API is invoked via `runCli`. We invoke it as the
+ * library exposes it; the surface is small enough that this wraps cleanly.
+ */
+export declare function runPack(options: PackOptions): Promise<PackResult>;
+//# sourceMappingURL=pack.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * Pack stage: produce compressed and uncompressed views of a codebase.
+ *
+ * Wraps Repomix's programmatic API to write:
+ * - `.dotrequirements-cache/overview.txt` — compressed (tree-sitter signatures)
+ * - `.dotrequirements-cache/source.txt` — uncompressed (full source for slices)
+ *
+ * Requirements covered:
+ * - CTS-PACK-1: Pack stage produces compressed and uncompressed views
+ * - CTS-PACK-2: Engineer can extend the ignore list per project
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * The curated default ignore list. These patterns are applied in addition to
+ * `.gitignore` and any project-level `.dotrequirements-ignore`.
+ *
+ * Sized to remove obvious non-behavioral noise: generated code, package
+ * manifests/lockfiles, vendored libraries, build artifacts, large binaries.
+ */
+export const DEFAULT_IGNORES = [
+    // Vendored dependencies
+    "node_modules/**",
+    "vendor/**",
+    ".pnp.*",
+    // Build outputs
+    "dist/**",
+    "build/**",
+    "out/**",
+    ".next/**",
+    ".nuxt/**",
+    ".svelte-kit/**",
+    ".turbo/**",
+    ".parcel-cache/**",
+    // Generated code
+    "**/*.generated.*",
+    "**/_generated/**",
+    "**/__generated__/**",
+    "**/*.pb.ts",
+    "**/*.pb.go",
+    // Lockfiles
+    "package-lock.json",
+    "pnpm-lock.yaml",
+    "yarn.lock",
+    "bun.lockb",
+    "composer.lock",
+    "Gemfile.lock",
+    "poetry.lock",
+    "uv.lock",
+    "Cargo.lock",
+    // Coverage and test artifacts
+    "coverage/**",
+    ".nyc_output/**",
+    ".next-cache/**",
+    // IDE / editor
+    ".idea/**",
+    ".vscode/**",
+    // OS files
+    ".DS_Store",
+    "Thumbs.db",
+    // Project caches we own
+    ".dotrequirements-cache/**",
+];
+/**
+ * Read project-level ignore patterns from `.dotrequirements-ignore` (and
+ * `.dotreqignore` as a shorthand), if either exists. Returns an empty array if
+ * no file is present.
+ */
+export function readProjectIgnores(projectRoot) {
+    const candidates = [".dotrequirements-ignore", ".dotreqignore"];
+    for (const name of candidates) {
+        const p = join(projectRoot, name);
+        if (existsSync(p)) {
+            const content = readFileSync(p, "utf-8");
+            return content
+                .split(/\r?\n/)
+                .map((line) => line.trim())
+                .filter((line) => line.length > 0 && !line.startsWith("#"));
+        }
+    }
+    return [];
+}
+/**
+ * Run Repomix twice over the same scope: once compressed, once uncompressed.
+ *
+ * We use Repomix's programmatic API rather than `npx repomix` so the CLI does
+ * not require a separate install and so we can control config precisely.
+ *
+ * NOTE: Repomix's TypeScript API is invoked via `runCli`. We invoke it as the
+ * library exposes it; the surface is small enough that this wraps cleanly.
+ */
+export async function runPack(options) {
+    const { projectRoot, paths, scope, extraIgnores = [] } = options;
+    const ignores = [
+        ...DEFAULT_IGNORES,
+        ...readProjectIgnores(projectRoot),
+        ...extraIgnores,
+    ];
+    const target = scope ? join(projectRoot, scope) : projectRoot;
+    // Import dynamically — Repomix is heavy and we don't want to load it at CLI
+    // boot time for unrelated commands.
+    const repomix = await import("repomix");
+    const { runCli } = repomix;
+    // Run compressed (overview)
+    await runCli([target], projectRoot, {
+        output: paths.overview,
+        style: "plain",
+        compress: true,
+        ignore: ignores.join(","),
+    });
+    // Run uncompressed (source)
+    await runCli([target], projectRoot, {
+        output: paths.source,
+        style: "plain",
+        compress: false,
+        ignore: ignores.join(","),
+    });
+    // Count "File:" headers in the uncompressed pack to report file count
+    const sourceContent = readFileSync(paths.source, "utf-8");
+    const fileCount = (sourceContent.match(/^File: /gm) ?? []).length;
+    return {
+        overviewPath: paths.overview,
+        sourcePath: paths.source,
+        fileCount,
+    };
+}
+//# sourceMappingURL=pack.js.map

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

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

@@ -0,0 +1,76 @@
+/**
+ * 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/present.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Present stage: write the final spec to .requirements/.
+ *
+ * - When the outline has 5+ areas, split into per-area files
+ *   (`.requirements/<sanitized-area-name>.requirements.md`).
+ * - When the outline has fewer than 5 areas, write a single document at
+ *   `.requirements/<sanitized-title>.requirements.md`.
+ * - Overwrite handling depends on interactive vs non-interactive mode.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-1: Final spec written to .requirements/, split when 5+ areas
+ * - CTS-PRESENT-2: Interactive overwrite prompt with three choices
+ * - CTS-PRESENT-3: Non-interactive overwrites require --overwrite or --skip-existing
+ */
+import type { Outline } from "./schemas.js";
+export declare const AREA_SPLIT_THRESHOLD = 5;
+export type OverwritePolicy = "prompt" | "overwrite" | "skip-existing" | "fail-fast";
+export interface PresentOptions {
+    outline: Outline;
+    finalSpecPath: string;
+    /** Project root (.requirements/ will be created under this). */
+    projectRoot: string;
+    overwritePolicy: OverwritePolicy;
+}
+export interface PresentResult {
+    /** Paths written under .requirements/ (or those that would have been written, in fail cases). */
+    outputPaths: string[];
+    /** Per-file action taken. */
+    actions: PresentAction[];
+    /** True if every file landed successfully. */
+    allWritten: boolean;
+    /** Reason for failure, if `allWritten` is false in fail-fast mode. */
+    conflictPath?: string;
+}
+export interface PresentAction {
+    path: string;
+    action: "created" | "overwrote" | "skipped" | "merged" | "refused";
+}
+/**
+ * Resolve the output path(s) the present stage would write to.
+ */
+export declare function planPresentPaths(outline: Outline, projectRoot: string): {
+    mode: "single" | "split";
+    paths: {
+        area?: string;
+        outPath: string;
+    }[];
+};
+/**
+ * Split a composed spec into per-area sections.
+ *
+ * The compose stage writes:
+ *
+ *     ---
+ *     frontmatter
+ *     ---
+ *
+ *     # Title
+ *
+ *     Summary.
+ *
+ *     ---
+ *
+ *     ## Area One
+ *     ...
+ *
+ *     ---
+ *
+ *     ## Area Two
+ *     ...
+ *
+ * We split on `\n---\n\n## ` and pair each chunk with its area heading.
+ */
+export declare function splitComposedSpec(composed: string, outline: Outline): Map<string, string>;
+/**
+ * Build a single-file requirements document from the composed spec.
+ * The composed spec IS this document (with the right frontmatter and structure).
+ * We just read it and return it.
+ */
+export declare function buildSingleFileDoc(composedSpec: string): string;
+/**
+ * Build a per-area requirements document for split mode.
+ */
+export declare function buildAreaDoc(outline: Outline, areaName: string, areaBody: string): string;
+/**
+ * Run the present stage.
+ *
+ * Returns a list of actions taken per path. In fail-fast mode, if any path
+ * would conflict, the function returns early with `conflictPath` set and
+ * `allWritten = false` — no files are written in this case (preserving the
+ * "no file overwritten without choice" guarantee from CTS-PRESENT-2.1).
+ */
+export declare function runPresent(options: PresentOptions): Promise<PresentResult>;
+//# sourceMappingURL=present.d.ts.map