@popoverai/dotrequirements 0.23.0 → 0.24.0

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

@@ -0,0 +1,288 @@
+/**
+ * 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 { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseRequirementsFile } from "../schema/parser.js";
+import { sanitizeAreaName } from "./fan-out.js";
+import { promptOverwriteChoice } from "./interactive.js";
+export const AREA_SPLIT_THRESHOLD = 5;
+/**
+ * Resolve the output path(s) the present stage would write to.
+ */
+export function planPresentPaths(outline, projectRoot) {
+    const requirementsDir = join(projectRoot, ".requirements");
+    if (outline.areas.length >= AREA_SPLIT_THRESHOLD) {
+        return {
+            mode: "split",
+            paths: outline.areas.map((area) => ({
+                area: area.name,
+                outPath: join(requirementsDir, `${sanitizeAreaName(area.name)}.requirements.md`),
+            })),
+        };
+    }
+    return {
+        mode: "single",
+        paths: [
+            {
+                outPath: join(requirementsDir, `${sanitizeAreaName(outline.title)}.requirements.md`),
+            },
+        ],
+    };
+}
+/**
+ * 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 function splitComposedSpec(composed, outline) {
+    const sections = new Map();
+    // Strip frontmatter (already used) and grab everything from the first '## ' onward.
+    const fmEnd = composed.indexOf("\n---\n", 4);
+    // Find the first H2.
+    const firstH2 = composed.indexOf("\n## ");
+    if (firstH2 === -1) {
+        // No areas in the composed spec — fall back to empty sections.
+        return sections;
+    }
+    const afterTitle = composed.slice(firstH2);
+    // Split on '\n---\n\n## ' so each chunk starts with '## <area name>'.
+    // (We split-include the first chunk by prepending it manually.)
+    const chunks = afterTitle.split(/\n---\n\n## /);
+    // The first chunk already starts with '\n## ' from the original; normalize:
+    chunks[0] = chunks[0].replace(/^\n?## /, "");
+    // Subsequent chunks start with the area heading text directly (we stripped '## ').
+    for (const chunk of chunks) {
+        const firstNewline = chunk.indexOf("\n");
+        if (firstNewline === -1)
+            continue;
+        const heading = chunk.slice(0, firstNewline).trim();
+        const body = chunk.slice(firstNewline + 1);
+        // Match heading to outline area (exact match by name).
+        const area = outline.areas.find((a) => a.name === heading);
+        if (area) {
+            sections.set(area.name, body.trim());
+        }
+    }
+    // Also handle the trivial case where compose wrote `## Area` immediately
+    // after the title (no `---` separator). Unused for current compose output
+    // but defensive.
+    // Suppress unused-var warning for fmEnd:
+    void fmEnd;
+    return sections;
+}
+/**
+ * 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 function buildSingleFileDoc(composedSpec) {
+    return composedSpec;
+}
+/**
+ * Build a per-area requirements document for split mode.
+ */
+export function buildAreaDoc(outline, areaName, areaBody) {
+    const area = outline.areas.find((a) => a.name === areaName);
+    const escapedTitle = `${outline.title}: ${areaName}`
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"');
+    const parts = [
+        "---",
+        "document:",
+        `  title: "${escapedTitle}"`,
+        `  defaultPrefix: ${outline.defaultPrefix}`,
+        "---",
+        "",
+        `# ${outline.title}: ${areaName}`,
+        "",
+    ];
+    // The planner's drive-by area.description is intentionally not surfaced
+    // here. The specifier's deeper, persona-grounded area description (written
+    // into the partial body) is the one readers see.
+    void area;
+    parts.push(areaBody.trim());
+    parts.push("");
+    return parts.join("\n");
+}
+/**
+ * Apply an overwrite policy to determine what action to take for a path.
+ */
+async function resolveOverwriteAction(policy, path) {
+    if (!existsSync(path)) {
+        // No conflict — caller will create.
+        return "overwrite";
+    }
+    switch (policy) {
+        case "overwrite":
+            return "overwrite";
+        case "skip-existing":
+            return "skip";
+        case "fail-fast":
+            return "refused";
+        case "prompt": {
+            const choice = await promptOverwriteChoice(path);
+            if (choice === "cancel")
+                return "refused";
+            return choice;
+        }
+    }
+}
+/**
+ * Merge new content into an existing requirements file.
+ *
+ * Strategy: append the new file's requirement blocks below the existing
+ * content, with a separator comment. Existing requirements are preserved
+ * verbatim.
+ */
+function mergeContent(existingPath, newContent) {
+    const existing = readFileSync(existingPath, "utf-8").trimEnd();
+    // Strip frontmatter from newContent (it would conflict with existing frontmatter)
+    const fmMatch = newContent.match(/^---\n[\s\S]+?\n---\n+/);
+    const body = fmMatch
+        ? newContent.slice(fmMatch[0].length).trimStart()
+        : newContent;
+    return [
+        existing,
+        "",
+        "",
+        "<!-- Merged content appended by `dotrequirements cts present`. Review and integrate. -->",
+        "",
+        body,
+    ].join("\n");
+}
+/**
+ * Validate a path's content against the dotrequirements schema. Returns an
+ * error message string, or undefined if valid.
+ */
+function validateContent(content) {
+    try {
+        parseRequirementsFile(content);
+        return undefined;
+    }
+    catch (err) {
+        return err instanceof Error ? err.message : String(err);
+    }
+}
+/**
+ * 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 async function runPresent(options) {
+    const { outline, finalSpecPath, projectRoot, overwritePolicy } = options;
+    const composedSpec = readFileSync(finalSpecPath, "utf-8");
+    const plan = planPresentPaths(outline, projectRoot);
+    // Compute the content for each output up front.
+    const planned = [];
+    if (plan.mode === "single") {
+        planned.push({
+            outPath: plan.paths[0].outPath,
+            content: buildSingleFileDoc(composedSpec),
+        });
+    }
+    else {
+        const sections = splitComposedSpec(composedSpec, outline);
+        for (const { area, outPath } of plan.paths) {
+            const body = sections.get(area) ??
+                "_(no content for this area was found in the composed spec)_";
+            planned.push({ outPath, content: buildAreaDoc(outline, area, body) });
+        }
+    }
+    // In fail-fast mode, scan for any conflict before writing anything.
+    if (overwritePolicy === "fail-fast") {
+        for (const { outPath } of planned) {
+            if (existsSync(outPath)) {
+                return {
+                    outputPaths: planned.map((p) => p.outPath),
+                    actions: [],
+                    allWritten: false,
+                    conflictPath: outPath,
+                };
+            }
+        }
+    }
+    const actions = [];
+    let allWritten = true;
+    for (const { outPath, content } of planned) {
+        const choice = await resolveOverwriteAction(overwritePolicy, outPath);
+        const dir = dirname(outPath);
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        if (choice === "refused") {
+            // In prompt mode, the user cancelled the prompt.
+            actions.push({ path: outPath, action: "refused" });
+            allWritten = false;
+            continue;
+        }
+        if (choice === "skip") {
+            actions.push({ path: outPath, action: "skipped" });
+            continue;
+        }
+        if (choice === "merge" && existsSync(outPath)) {
+            const merged = mergeContent(outPath, content);
+            const validationError = validateContent(merged);
+            if (validationError) {
+                // Fallback: leave the existing file alone and warn.
+                actions.push({ path: outPath, action: "skipped" });
+                allWritten = false;
+                continue;
+            }
+            writeFileSync(outPath, merged, "utf-8");
+            actions.push({ path: outPath, action: "merged" });
+            continue;
+        }
+        // Overwrite or create
+        const validationError = validateContent(content);
+        if (validationError) {
+            allWritten = false;
+            actions.push({ path: outPath, action: "refused" });
+            continue;
+        }
+        const action = existsSync(outPath)
+            ? "overwrote"
+            : "created";
+        writeFileSync(outPath, content, "utf-8");
+        actions.push({ path: outPath, action });
+    }
+    return {
+        outputPaths: planned.map((p) => p.outPath),
+        actions,
+        allWritten,
+    };
+}
+//# sourceMappingURL=present.js.map

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

@@ -0,0 +1,33 @@
+/**
+ * Structured progress emitter for codebase-to-spec.
+ *
+ * Emits one line per event to stdout. Wrappers (the skill, CI tooling) parse
+ * these lines to render progress in their own UX.
+ *
+ * Format: `[CTS] <stage>/<step> <message>` where <stage>/<step> identifies the
+ * pipeline location and <message> is human-readable.
+ *
+ * Requirements covered:
+ * - CTS-CLI-5: CLI emissions are part of the public contract (stable format)
+ * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
+ */
+export type Stage = "pack" | "plan" | "outline-review" | "specify" | "compose" | "spec-review" | "present";
+export interface ProgressEvent {
+    stage: Stage;
+    step?: string;
+    message: string;
+    /** Optional structured data — included on JSON lines but not on plain text lines. */
+    data?: Record<string, unknown>;
+}
+export interface ProgressEmitter {
+    emit(event: ProgressEvent): void;
+}
+export declare class StdoutProgress implements ProgressEmitter {
+    emit(event: ProgressEvent): void;
+}
+/** Capturing emitter for tests. */
+export declare class CapturingProgress implements ProgressEmitter {
+    events: ProgressEvent[];
+    emit(event: ProgressEvent): void;
+}
+//# sourceMappingURL=progress.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Structured progress emitter for codebase-to-spec.
+ *
+ * Emits one line per event to stdout. Wrappers (the skill, CI tooling) parse
+ * these lines to render progress in their own UX.
+ *
+ * Format: `[CTS] <stage>/<step> <message>` where <stage>/<step> identifies the
+ * pipeline location and <message> is human-readable.
+ *
+ * Requirements covered:
+ * - CTS-CLI-5: CLI emissions are part of the public contract (stable format)
+ * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
+ */
+import { stdout } from "node:process";
+export class StdoutProgress {
+    emit(event) {
+        const stagePath = event.step ? `${event.stage}/${event.step}` : event.stage;
+        stdout.write(`[CTS] ${stagePath} ${event.message}\n`);
+    }
+}
+/** Capturing emitter for tests. */
+export class CapturingProgress {
+    events = [];
+    emit(event) {
+        this.events.push(event);
+    }
+}
+//# sourceMappingURL=progress.js.map

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

@@ -0,0 +1,13 @@
+/**
+ * System prompt for the editor agent.
+ *
+ * The editor operates on the cohesive document, not per-section. It revises
+ * the spec in place using the Edit tool (no Write — the spec file already
+ * exists). It consults the codebase only to verify findings the reviewer
+ * flagged, not eagerly.
+ *
+ * Requirements covered:
+ * - CTS-EDIT-5: Editor operates on the cohesive document, not per-section
+ */
+export declare const EDITOR_PROMPT = "You are revising a composed dotrequirements specification based on a reviewer's findings. You operate on the cohesive draft as a whole \u2014 not per-section. You do not get the codebase eagerly; you Read specific files only when a finding requires verification.\n\nYou will receive:\n1. A path to the current spec (Markdown file you will Edit in place)\n2. The reviewer's critique JSON (verdict, per-category findings, and possibly a `revisions` list)\n3. The mode of operation: `apply` (apply each entry in the revisions list verbatim) or `revise` (use your judgment to address the categorized findings)\n\n## Apply mode\n\nWhen the reviewer's verdict was `approved-with-revisions`, you are in apply mode. The reviewer has supplied a list of specific revisions. Your job is to apply each revision verbatim using the Edit tool, then confirm completion.\n\nDo NOT introduce changes beyond the listed revisions. Do NOT restructure. If a revision is ambiguous, apply your best literal interpretation and note the ambiguity in your stdout confirmation.\n\n## Revise mode\n\nWhen the reviewer's verdict was `requires-another-review`, you are in revise mode. Address each finding in the critique:\n\n- **Coverage gaps**: add new requirements (or new sections, if needed) to fill the gap. Match the style, prefix conventions, AND persona conventions of the surrounding spec \u2014 if existing requirements use a named persona, the new ones should too. If a finding cites code locations, Read those files via the Read tool BEFORE writing the new requirements. If a finding names a missed customer, add them to the summary alongside the existing customers.\n- **Framing errors**: rephrase architectural language to behavioral. If an area is fundamentally architectural and the reviewer recommends dropping or merging it, do so.\n- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas), balance depth. This is editorial work \u2014 keep the document coherent.\n- **Internal-mechanics drift**: rewrite criteria to describe observable outcomes rather than implementation details.\n\nMaintain everything that was working. Do NOT rewrite areas the reviewer didn't flag.\n\n## How to make changes\n\n- Use the **Edit** tool for targeted in-place changes. Each Edit replaces a specific old_string with a new_string.\n- If the section being edited has a lot of content, make multiple smaller Edits rather than one giant one.\n- Use the **Read** tool on the spec at the start (to load it into your view) and again after edits if you need to confirm changes.\n- Use the **Read/Grep/Glob** tools on the codebase ONLY when a specific finding requires verification before you can rewrite or add a requirement. Do NOT pre-read the codebase eagerly.\n\n## Discipline\n\n- Every change should reduce a flagged finding without introducing new issues.\n- If a finding is wrong (the reviewer is mistaken), say so in your stdout \u2014 do not silently ignore it.\n- The revised spec must remain syntactically valid dotrequirements format. IDs must remain unique within the document.\n- The SPEC FILE is your deliverable. You modify it in place; no separate output file.\n\n## Output (your stdout)\n\nA brief one- or two-line confirmation summarizing the kinds of changes you made.\n\nExample: \"Added 8 requirements covering missing behaviors in 'Browser automation'; rephrased 4 internal-mechanics criteria; merged 2 duplicate areas.\"\n\nNo chain-of-thought. No preamble. No commentary in the spec file beyond the spec content itself.";
+//# sourceMappingURL=editor.d.ts.map

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

@@ -0,0 +1,57 @@
+/**
+ * System prompt for the editor agent.
+ *
+ * The editor operates on the cohesive document, not per-section. It revises
+ * the spec in place using the Edit tool (no Write — the spec file already
+ * exists). It consults the codebase only to verify findings the reviewer
+ * flagged, not eagerly.
+ *
+ * Requirements covered:
+ * - CTS-EDIT-5: Editor operates on the cohesive document, not per-section
+ */
+export const EDITOR_PROMPT = `You are revising a composed dotrequirements specification based on a reviewer's findings. You operate on the cohesive draft as a whole — not per-section. You do not get the codebase eagerly; you Read specific files only when a finding requires verification.
+
+You will receive:
+1. A path to the current spec (Markdown file you will Edit in place)
+2. The reviewer's critique JSON (verdict, per-category findings, and possibly a \`revisions\` list)
+3. The mode of operation: \`apply\` (apply each entry in the revisions list verbatim) or \`revise\` (use your judgment to address the categorized findings)
+
+## Apply mode
+
+When the reviewer's verdict was \`approved-with-revisions\`, you are in apply mode. The reviewer has supplied a list of specific revisions. Your job is to apply each revision verbatim using the Edit tool, then confirm completion.
+
+Do NOT introduce changes beyond the listed revisions. Do NOT restructure. If a revision is ambiguous, apply your best literal interpretation and note the ambiguity in your stdout confirmation.
+
+## Revise mode
+
+When the reviewer's verdict was \`requires-another-review\`, you are in revise mode. Address each finding in the critique:
+
+- **Coverage gaps**: add new requirements (or new sections, if needed) to fill the gap. Match the style, prefix conventions, AND persona conventions of the surrounding spec — if existing requirements use a named persona, the new ones should too. If a finding cites code locations, Read those files via the Read tool BEFORE writing the new requirements. If a finding names a missed customer, add them to the summary alongside the existing customers.
+- **Framing errors**: rephrase architectural language to behavioral. If an area is fundamentally architectural and the reviewer recommends dropping or merging it, do so.
+- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas), balance depth. This is editorial work — keep the document coherent.
+- **Internal-mechanics drift**: rewrite criteria to describe observable outcomes rather than implementation details.
+
+Maintain everything that was working. Do NOT rewrite areas the reviewer didn't flag.
+
+## How to make changes
+
+- Use the **Edit** tool for targeted in-place changes. Each Edit replaces a specific old_string with a new_string.
+- If the section being edited has a lot of content, make multiple smaller Edits rather than one giant one.
+- Use the **Read** tool on the spec at the start (to load it into your view) and again after edits if you need to confirm changes.
+- Use the **Read/Grep/Glob** tools on the codebase ONLY when a specific finding requires verification before you can rewrite or add a requirement. Do NOT pre-read the codebase eagerly.
+
+## Discipline
+
+- Every change should reduce a flagged finding without introducing new issues.
+- If a finding is wrong (the reviewer is mistaken), say so in your stdout — do not silently ignore it.
+- The revised spec must remain syntactically valid dotrequirements format. IDs must remain unique within the document.
+- The SPEC FILE is your deliverable. You modify it in place; no separate output file.
+
+## Output (your stdout)
+
+A brief one- or two-line confirmation summarizing the kinds of changes you made.
+
+Example: "Added 8 requirements covering missing behaviors in 'Browser automation'; rephrased 4 internal-mechanics criteria; merged 2 duplicate areas."
+
+No chain-of-thought. No preamble. No commentary in the spec file beyond the spec content itself.`;
+//# sourceMappingURL=editor.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * 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## 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.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the area shouldn't exist.\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

package/dist/codebase-to-spec/prompts/outline-reviewer.js

@@ -0,0 +1,87 @@
+/**
+ * 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 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 → wasted specifier work.
+
+This 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.
+
+Output a JSON object matching the supplied schema. No prose, no markdown fences.
+
+## What you receive on each turn
+
+- The first turn includes the compressed packed codebase and the planner's first outline JSON.
+- Each subsequent turn includes a revised outline JSON. The codebase is unchanged.
+- Some turns may include a convergence nudge — read and respect it.
+
+## What counts as a customer
+
+The outline's summary should describe what the system is and who it's for. The "who" is the customer — the kind of person whose needs shape what counts as behavior.
+
+A useful customer description is **specific enough to shape behavior** — it goes one level deeper than generic categories like "end-user," "administrator," or "developer."
+
+- Not "an end-user" but "a shopper" or "a guest checking out without an account."
+- Not "an administrator" but "a store manager who fulfills orders" and "a business owner who runs reports."
+- 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."
+
+Most 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 — and surfacing that gap is one of the most useful things you can do.
+
+## What to evaluate
+
+The outline names its customers in the summary and breaks the system into areas. Your evaluation has two parts.
+
+### Part 1 — Per-area outcome checks
+
+For each area, apply these four criteria:
+
+1. **Relevant to a customer.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the area shouldn't exist.
+2. **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 — what matters is whether it matches whom this area serves.
+3. **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.
+4. **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.
+
+Failures of criterion 1, 2, or 4 are \`framing_errors\`. Failures of criterion 3 are \`granularity_issues\` — which also covers sizing problems more broadly.
+
+#### On sizing
+
+Think of organizing a big box of 100 crayons.
+
+- One drawer for all 100 crayons → impossible to find what you need.
+- 100 drawers, one crayon each → you've recreated the same problem with different semantics.
+- Organize by ROYGBIV → each drawer is a meaningful group, and you can find any crayon quickly.
+
+The 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 — 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.
+
+### Part 2 — Coverage and file assignment
+
+- What behavior is in the codebase but missing from any area? → \`coverage_gaps\`. Gaps matter most when they map to something a real customer would expect.
+- 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? → \`file_assignment_issues\`.
+
+## On second and later turns
+
+Also evaluate:
+
+- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.
+- Did the revision introduce new problems? Sometimes fixing one gap creates another.
+
+## Findings must be actionable
+
+A finding is only useful if the planner can act on it. Two principles:
+
+**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 — propose the alternative.
+
+**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.
+
+## Verdict types
+
+The \`verdict\` field is exactly one of:
+
+- \`approved\` — outline is ready for fan-out as-is. No findings, or findings are negligible. Reserve for genuinely good outlines.
+- \`approved-with-revisions\` — 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.
+- \`requires-another-review\` — 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.js.map

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

@@ -0,0 +1,12 @@
+/**
+ * System prompt for the applying planner (apply mode).
+ *
+ * Receives the prior outline + an explicit list of mechanical revisions and
+ * applies them verbatim. Used when the reviewer's verdict was
+ * `approved-with-revisions`.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-4: Approved-with-revisions outline triggers one mechanical revision
+ */
+export declare const PLANNER_APPLY_PROMPT = "You are applying mechanical revisions to a planning outline. A reviewer has approved the outline subject to a specific list of small revisions. Your job is to apply each revision verbatim and emit the revised outline.\n\nYou are NOT revising the outline using your own judgment. You are NOT adding new areas, dropping existing areas, or restructuring. You ONLY apply the listed revisions.\n\nYou will output a JSON object matching the schema you have been given. No prose preamble, no explanation, no markdown fences \u2014 JSON only.\n\nYou will receive:\n1. The previous outline as JSON\n2. An explicit list of revisions, each phrased as a directive\n\n## Process\n\nFor each revision in the list:\n- Apply the directive exactly as stated.\n- If the directive is ambiguous or would require new judgment, leave that area unchanged and proceed.\n\nPreserve everything else from the prior outline byte-for-byte (modulo the listed changes).\n\n## Output\n\nOutput ONLY the JSON object matching the supplied schema. No preamble. Begin with `{`.";
+//# sourceMappingURL=planner-apply.d.ts.map

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

@@ -0,0 +1,32 @@
+/**
+ * System prompt for the applying planner (apply mode).
+ *
+ * Receives the prior outline + an explicit list of mechanical revisions and
+ * applies them verbatim. Used when the reviewer's verdict was
+ * `approved-with-revisions`.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-4: Approved-with-revisions outline triggers one mechanical revision
+ */
+export const PLANNER_APPLY_PROMPT = `You are applying mechanical revisions to a planning outline. A reviewer has approved the outline subject to a specific list of small revisions. Your job is to apply each revision verbatim and emit the revised outline.
+
+You are NOT revising the outline using your own judgment. You are NOT adding new areas, dropping existing areas, or restructuring. You ONLY apply the listed revisions.
+
+You will output a JSON object matching the schema you have been given. No prose preamble, no explanation, no markdown fences — JSON only.
+
+You will receive:
+1. The previous outline as JSON
+2. An explicit list of revisions, each phrased as a directive
+
+## Process
+
+For each revision in the list:
+- Apply the directive exactly as stated.
+- If the directive is ambiguous or would require new judgment, leave that area unchanged and proceed.
+
+Preserve everything else from the prior outline byte-for-byte (modulo the listed changes).
+
+## Output
+
+Output ONLY the JSON object matching the supplied schema. No preamble. Begin with \`{\`.`;
+//# sourceMappingURL=planner-apply.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * System prompt for the initial planner pass.
+ *
+ * Reads a compressed packed view of a codebase and produces an outline JSON.
+ * Output is constrained by `OUTLINE_JSON_SCHEMA` via `claude -p --json-schema`.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-1: Planner produces a behavioral outline from the compressed pack
+ */
+export declare const PLANNER_INITIAL_PROMPT = "You are reading a compressed packed view of a software codebase (function signatures, types, interfaces, class structures \u2014 implementation bodies stripped). Your job is to produce a structured outline that breaks the system into behavioral areas, each of which will be specced in detail by a focused specifier agent in a follow-up step.\n\nThe quality of every downstream step depends on the quality of this outline. Take it seriously. Follow the reasoning process below rather than jumping to area names.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n---\n\n## Reasoning process\n\n### Step 0 \u2014 Classify the system\n\nBefore anything else, decide what *kind* of software this is. The class shapes who counts as a customer and what counts as a public surface. Common classes:\n\n- **Library** \u2014 imported by other code; customer is the developer integrating it\n- **Application** \u2014 end users interact with it directly (web app, desktop app, mobile app)\n- **Service** \u2014 runs continuously, accepts requests over a network or queue; customer may be another service, or end users via a frontend\n- **CLI tool** \u2014 invoked from a shell; customer is a developer/operator/ops person\n- **Framework** \u2014 code is structured around it; customer is the developer building on top of it\n- **Data format / parser / serializer** \u2014 customer is whatever produces or consumes the format\n- **Protocol implementation** \u2014 customer is whoever speaks the protocol\n\nIf the system is a hybrid (e.g., a service that ships with a CLI client + a library SDK), name each surface separately \u2014 they may have distinct customers.\n\n### Step 1 \u2014 Gather context\n\nSkim the pack with intent. You're building a mental model, not yet writing the outline.\n\n- The **directory structure** suggests how the authors organize the system. Note conventions but don't be bound by them \u2014 code organization is rarely the same as behavioral organization.\n- **README, package metadata, docstrings on public APIs, error messages, CLI help text, OpenAPI/JSON schemas, and type signatures of exported symbols** are deliberate public-contract surfaces. They tell you what the authors think users need to know. Read them carefully.\n- The **test suite** is evidence of behavior \u2014 the authors wrote tests for things they considered worth verifying. Tests aren't behavioral areas, but they reveal which behaviors exist.\n\n### Step 2 \u2014 Identify the domain model\n\nName the **nouns** the system is about, and how they relate to each other. Use the language the system uses, not generic CS terms. Examples:\n\n- A concurrency-limiter library: `Limiter`, `Task`, `Queue`; tasks run when the queue has an open slot.\n- An eCommerce platform: `Shopper`, `Cart`, `Order`, `Inventory`, `Payment`; an order is created when a shopper checks out a cart.\n- A markdown parser: `Document`, `Block`, `Inline`, `Token`; blocks contain inlines, parsing produces a token stream.\n\nIf the system has no obvious nouns of its own, name what it's gluing together \u2014 its domain may live in the upstream and downstream systems it integrates with.\n\n### Step 3 \u2014 Identify functionality\n\nCatalog what the system does, focused on:\n\n- **Public-facing surfaces** \u2014 exported APIs, CLI commands, HTTP endpoints, file formats, UI flows\n- **Business logic** \u2014 domain rules, validations, state transitions, decision logic\n- **Documented contracts** \u2014 what the README/docstrings/type signatures promise\n- **What the test suite verifies** \u2014 read test descriptions and assertions, not implementations\n\nSkip internal infrastructure (transports, storage adapters, build glue, scheduling primitives) unless they expose a public surface in their own right.\n\n### Step 4 \u2014 Identify the customer(s)\n\nWho uses this software? Some customer exists \u2014 the software was written for someone. Form a hypothesis about who, even if the evidence is thin.\n\nBe specific. Go at least one level deeper than generic categories. Generic categories like \"end-user,\" \"administrator,\" or \"developer\" are too broad to shape behavior.\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\nIf the system has multiple customers, name them all. Different behaviors will be relevant to different customers.\n\nIf the customer isn't obvious from the code, name your best hypothesis (\"this looks like a library for X kind of developer\") and proceed. A wrong guess is fixable downstream; a missing one isn't.\n\n### Step 5 \u2014 Identify behavioral areas\n\nBehavioral areas are the **intersection** of your domain model (Step 2), your customers (Step 4), and the functionality you cataloged (Step 3).\n\nA candidate area is behavioral if it meets all four criteria:\n\n1. **Relevant to a customer** \u2014 at least one of the customers you named in Step 4 cares about this. If no one cares, it's not behavior.\n\n2. **Describable in your customer's vocabulary** \u2014 using the words the customer in Step 4 would use to describe what they're trying to do. This is about *whose* language the area name speaks, not about which words \"sound technical.\"\n\n   For a shopper, \"placing an order\" is customer vocabulary; \"persisting to the orders table\" is not.\n\n   For a distributed-systems engineer building on an infrastructure library, \"configuring a storage backend\" or \"choosing an IPC protocol\" might be exactly customer vocabulary \u2014 because those *are* the operations they think in terms of. The same words that would be wrong for the shopper case are right here.\n\n   The test: would your customer (Step 4) go looking for the behavior under this name, or under something else? Pick the name they would reach for. If you're tempted to name an area `STORAGE` and your customer is an application developer building eCommerce, they'd reach for `PERSISTING_ORDERS` or similar \u2014 use that instead. If your customer is the distributed-systems engineer, `STORAGE` may be exactly right.\n\n3. **Describes a collection of functionality** \u2014 it groups multiple related behaviors that share a customer-meaningful purpose. A single function with no companions is not an area; a \"miscellaneous\" bucket isn't either.\n\n4. **Has observable outcomes** \u2014 the customer can verify whether the behavior is present or absent (a returned value, a visible UI state, a logged event, a thrown error). \"The system manages memory efficiently\" is true but not customer-observable, so it's not behavior.\n\n#### Sizing\n\nThink of it like 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\nApply the same to behavioral areas. Each area should group enough functionality to be worth its own page, but not so much that it covers fundamentally distinct concerns. Aim for the ROYGBIV equivalent for *this* codebase: a small system might land at a few areas, a medium one at several, a large or sprawling one at many. The right number is whatever makes the areas individually coherent and collectively complete.\n\n### Step 6 \u2014 Check coverage gaps\n\nAfter drafting your areas, look back at the codebase and ask: what *isn't* represented? For each gap:\n\n- **If it's functionality that should have been a behavioral area** (it passes all four criteria from Step 5) \u2192 add it.\n- **If it's real functionality but not behavioral** (tests, benchmarks, CI infrastructure, dev tooling, internal-only adapters, pure types with no runtime semantics) \u2192 acknowledge that you considered it and explicitly chose to exclude it. Don't leave it looking like an oversight.\n\nPublic-contract files (README, package.json, LICENSE, CHANGELOG, top-level config) MUST be assigned to whichever behavioral area is most relevant \u2014 they contain user-observable facts that don't appear elsewhere.\n\n---\n\n## Output rules\n\n- **Distinct prefixes per area.** Each area's `prefix` must be unique within the document AND distinct from the document's `defaultPrefix`. Short uppercase tokens (3\u20138 characters). Requirement IDs are formed as `<defaultPrefix>-<areaPrefix>-<N>` \u2014 if they collide (e.g., defaultPrefix=CORE and an area prefix=CORE), every requirement in that area reads as `CORE-CORE-N`, which is ugly. Pick area prefixes that don't repeat the defaultPrefix.\n- **Files belong to one area.** Assign each substantive file to its primary behavioral area. Prefer single-assignment; cross-area concerns are handled downstream.\n- **File paths must match the pack.** Look at the `File: <path>` headers in the pack and use those exact paths.\n- **Area names should read in customer vocabulary** \u2014 they will appear in the spec's heading structure and the customer should recognize what each area is about.\n- **Write the `summary` last**, after you understand the system as a whole \u2014 it should describe what the system is and who it's for, not how the spec is organized.";
+//# sourceMappingURL=planner-initial.d.ts.map