@popoverai/dotrequirements 0.23.0 → 0.24.1

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

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