@popoverai/dotrequirements 0.24.2 → 0.25.0

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

@@ -0,0 +1,850 @@
+/**
+ * Dispatch-context composition for the codebase-to-spec workflow.
+ *
+ * A cts-worker runs `dotrequirements cts dispatch-context <dispatch-id>` to
+ * fetch the full composed prompt for its role (self-composition — there is no
+ * PreToolUse hook). Each returned prompt is self-contained: persona body +
+ * paths + any prior-round context the worker needs.
+ *
+ * Recognized dispatch IDs:
+ * - `planner-initial` — initial planner; writes outline.yaml
+ * - `planner-revise-<turn>` — revising planner; reads the prior outline.yaml
+ *   (with its review.thread), applies the latest thread entry's revisions, and
+ *   writes a new outline.yaml. `<turn>` is the round being PRODUCED (2 = first
+ *   revision).
+ * - `outline-reviewer` — independent reviewer of the area decomposition; appends
+ *   its verdict to the document-level review.thread.
+ * - `specifier-<area>` — drafts one area's partial.
+ * - `reviewer-<area>` — independent per-area reviewer; appends its verdict to
+ *   that area's review.thread.
+ * - `editor-<area>` — applies the per-area reviewer's revisions to the partial.
+ * - `cross-area-reviewer` — document-level reviewer of the composed spec
+ *   (cross-area issues + coverage); returns its verdict for the reconcile loop.
+ * - `compose-editor` — applies cross-area revisions to the composed spec.
+ * - `phase1-test` — mechanical plumbing self-test.
+ *
+ * Requirements covered:
+ * - CTSO-CONV-2: the outline converges via an independent reviewer loop
+ * - CTSO-CONV-5: cross-area review reconciles the composed spec
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { findProjectRoot } from "../utils/project-settings.js";
+import { cachePaths } from "./cache.js";
+import { sanitizeAreaName } from "./fan-out.js";
+import { EDITOR_PROMPT } from "./prompts/editor.js";
+import { PLANNER_INITIAL_PROMPT } from "./prompts/planner-initial.js";
+import { PLANNER_REVISE_PROMPT } from "./prompts/planner-revise.js";
+import { SPEC_REVIEWER_PROMPT } from "./prompts/spec-reviewer.js";
+import { SPECIFIER_PROMPT } from "./prompts/specifier.js";
+import { parseConversationalOutline, } from "./schemas.js";
+/** Phase 1 dispatch-id used to validate the mechanical plumbing end-to-end. */
+export const PHASE1_TEST_DISPATCH_ID = "phase1-test";
+/** Phase 1 token the test worker echoes back. */
+export const PHASE1_TEST_TOKEN = "PHASE1-WORKER-OK token=CTS9X";
+/** Phase 2 dispatch-id for the initial planner pass. */
+export const PLANNER_INITIAL_DISPATCH_ID = "planner-initial";
+/**
+ * Phase 2b dispatch-id prefix for planner revise dispatches. Suffix is the
+ * turn number being PRODUCED (e.g., `planner-revise-2` produces the
+ * second turn's outline, reading the prior outline + its latest review
+ * thread entry as inputs).
+ */
+export const PLANNER_REVISE_DISPATCH_ID_PREFIX = "planner-revise-";
+/**
+ * Phase 3 dispatch-id prefix for specifier dispatches. Suffix is the area's
+ * prefix from the approved outline (e.g., `specifier-PLAN` runs the
+ * specifier for the PLAN area).
+ */
+export const SPECIFIER_DISPATCH_ID_PREFIX = "specifier-";
+/**
+ * Phase 4 dispatch-id prefix for editor dispatches. Suffix is the area's
+ * prefix (e.g., `editor-PLAN` revises the PLAN area's partial based on
+ * the latest area.review.thread entry's revisions).
+ */
+export const EDITOR_DISPATCH_ID_PREFIX = "editor-";
+/**
+ * Dispatch-id prefix for per-area reviewer dispatches. Suffix is the area's
+ * prefix (e.g., `reviewer-PLAN` reviews the PLAN area's partial). The reviewer
+ * is a distinct worker from the specifier/editor that produced the partial
+ * (independent second pair of eyes — CTSO-CONV-3.1). It appends its verdict to
+ * that area's `review.thread` in outline.yaml (read by the editor dispatch) and
+ * also returns the verdict so the workflow's convergence loop can branch on it.
+ */
+export const REVIEWER_DISPATCH_ID_PREFIX = "reviewer-";
+/**
+ * Dispatch-id for the outline reviewer — the independent reviewer for the
+ * planner's area decomposition (project level, one per run). Distinct from the
+ * planner that produced the outline (CTSO-CONV-2.1). It appends its verdict to
+ * the project-level `outline.review.thread` and returns the verdict so the
+ * workflow's outline loop can branch on it. The outline loop is sequential, so
+ * unlike the per-area reviewers this writer never contends on the file.
+ */
+export const OUTLINE_REVIEWER_DISPATCH_ID = "outline-reviewer";
+/**
+ * Dispatch-id for the cross-area reviewer — the document-level reviewer that
+ * runs AFTER per-area work converges and the partials are composed into a single
+ * spec. It reviews the composed spec for cross-area issues (duplication,
+ * terminology/persona drift, awkward cross-cutting splits, depth imbalance) plus
+ * document-level coverage and framing. It appends its verdict to the outline's
+ * top-level `crossAreaReview.thread` (auditable, like the per-area reviewers)
+ * and also returns it so the workflow's reconcile loop can branch on it
+ * (CTSO-CONV-5). Reuses the legacy SPEC_REVIEWER_PROMPT persona. One per round,
+ * sequential — no file contention.
+ */
+export const CROSS_AREA_REVIEWER_DISPATCH_ID = "cross-area-reviewer";
+/**
+ * Dispatch-id for the compose-level editor — applies the cross-area reviewer's
+ * revisions to the whole composed spec (not one area). Reuses the legacy
+ * EDITOR_PROMPT persona at its native document scope, reading the revisions to
+ * apply from the outline's top-level `crossAreaReview.thread` — the same
+ * auditable channel the per-area editor uses for `area.review.thread`.
+ */
+export const COMPOSE_EDITOR_DISPATCH_ID = "compose-editor";
+/**
+ * Compose the dispatch context for a given dispatch-id.
+ *
+ * @returns the composed dispatch context, or `null` if the id is unknown
+ *          or required inputs (cache files) are missing.
+ */
+export function composeDispatchContext(dispatchId, options = {}) {
+    if (dispatchId === PHASE1_TEST_DISPATCH_ID) {
+        return composePhase1Test();
+    }
+    if (dispatchId === PLANNER_INITIAL_DISPATCH_ID) {
+        return composePlannerInitial(options);
+    }
+    if (dispatchId.startsWith(PLANNER_REVISE_DISPATCH_ID_PREFIX)) {
+        const turnText = dispatchId.slice(PLANNER_REVISE_DISPATCH_ID_PREFIX.length);
+        const turn = Number.parseInt(turnText, 10);
+        if (!Number.isFinite(turn) || turn < 2 || String(turn) !== turnText) {
+            return null;
+        }
+        return composePlannerRevise(turn, options);
+    }
+    if (dispatchId.startsWith(SPECIFIER_DISPATCH_ID_PREFIX)) {
+        const areaPrefix = dispatchId.slice(SPECIFIER_DISPATCH_ID_PREFIX.length);
+        if (!areaPrefix)
+            return null;
+        return composeSpecifier(areaPrefix, options);
+    }
+    if (dispatchId === OUTLINE_REVIEWER_DISPATCH_ID) {
+        return composeOutlineReviewer(options);
+    }
+    if (dispatchId === CROSS_AREA_REVIEWER_DISPATCH_ID) {
+        return composeCrossAreaReviewer(options);
+    }
+    if (dispatchId === COMPOSE_EDITOR_DISPATCH_ID) {
+        return composeComposeEditor(options);
+    }
+    if (dispatchId.startsWith(REVIEWER_DISPATCH_ID_PREFIX)) {
+        const areaPrefix = dispatchId.slice(REVIEWER_DISPATCH_ID_PREFIX.length);
+        if (!areaPrefix)
+            return null;
+        return composeReviewer(areaPrefix, options);
+    }
+    // NOTE: the editor branch must come after the reviewer branch only if their
+    // prefixes could collide; they don't ("editor-" vs "reviewer-"), so order is
+    // irrelevant here.
+    if (dispatchId.startsWith(EDITOR_DISPATCH_ID_PREFIX)) {
+        const areaPrefix = dispatchId.slice(EDITOR_DISPATCH_ID_PREFIX.length);
+        if (!areaPrefix)
+            return null;
+        return composeEditor(areaPrefix, options);
+    }
+    return null;
+}
+function composePhase1Test() {
+    return {
+        prompt: [
+            "You are the Phase 1 mechanical-plumbing test worker for the",
+            "codebase-to-spec conversational orchestrator.",
+            "",
+            "Reply with exactly the following text and nothing else:",
+            "",
+            PHASE1_TEST_TOKEN,
+        ].join("\n"),
+    };
+}
+/**
+ * YAML overlay applied on top of both planner prompts. Overrides their
+ * "output JSON" instructions and adds per-area customer guidance.
+ *
+ * Designed as a single shared block since the schema, customer guidance,
+ * and format override apply identically to initial + revise dispatches.
+ */
+const PLANNER_YAML_OVERLAY = `---
+
+## Output format — read carefully, this OVERRIDES the system prompt above
+
+The system prompt above instructs you to output a JSON object. **This dispatch overrides that.** Your output format is YAML, not JSON. Follow the YAML schema below.
+
+The schema also includes per-area \`customers\` and renames \`files\` to \`source_files\`. Both are new fields not present in the system prompt's schema description.
+
+## YAML output schema
+
+Your output is a YAML document with this structure (every field below is required unless marked optional):
+
+\`\`\`yaml
+title: <string>
+defaultPrefix: <uppercase identifier, distinct from any area prefix>
+summary: |
+  <multi-line prose summarizing the system: what it is, who it's for>
+review: # OPTIONAL — present only when revising; preserve from input verbatim
+  result: approved | needs-revision
+  thread:
+    - result: approved | needs-revision
+      revisions: # only when result is needs-revision; ≥1 entries
+        - <string>
+areas:
+  - name: <string — read in customer vocabulary>
+    prefix: <uppercase identifier, unique within document>
+    description: |
+      <multi-line prose grounding this area in customer behavior>
+    source_files: [<file paths from the pack>]
+    customers:
+      - description: |
+          <multi-line prose: SPECIFIC, area-scoped customer description>
+\`\`\`
+
+## Per-area customer guidance (NEW field — read carefully)
+
+For EACH area, identify the customer(s) who care about that area's behaviors. Write each customer description fresh, specific to who interacts with THAT area:
+
+- Not "developer" but "a CTS operator at the planning checkpoint, deciding whether CTS understood their codebase well enough to fan-out specifiers"
+- Not "user" but the concrete role and the specific situation they're in when this area's behaviors matter
+- The same role appearing in multiple areas may have DIFFERENT needs at different moments; describe each occurrence freshly
+- If you find yourself writing the same generic description across areas, that's a smell — either your customers aren't specific enough OR your areas aren't customer-distinct
+
+There is no project-level customer list. Each area's customers are defined inline, area-scoped.
+
+## Schema validation reminders
+
+- \`defaultPrefix\` and each area's \`prefix\` must be uppercase alphanumeric/underscore (regex: \`/^[A-Z][A-Z0-9_]*$/\`).
+- Area prefixes must be unique within the document AND distinct from \`defaultPrefix\`.
+- \`source_files\` paths must match the \`File: <path>\` headers in the pack exactly.
+- Each area must have ≥1 customer with a non-empty \`description\`.
+`;
+function composePlannerInitial(options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.overview)) {
+        return null;
+    }
+    const prompt = [
+        PLANNER_INITIAL_PROMPT,
+        "",
+        PLANNER_YAML_OVERLAY,
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        `Read the compressed packed codebase at: ${paths.overview}`,
+        "",
+        `Produce the outline YAML conforming to the schema above and write it to: ${paths.outline}`,
+        "",
+        "Do NOT include a `review` field — that section is added by the conversational orchestrator after you finish. Only emit the content fields.",
+        "",
+        "Do not output YAML in your reply — only write it to the file. When the file is written, end your response with a brief one-line confirmation noting the file path.",
+    ].join("\n");
+    return { prompt };
+}
+/**
+ * Resolve the CLI invocation prefix worker subagents should use when running
+ * `cts validate` and `cts style-check` on their partials. Resolved at module
+ * load so every dispatch composed in this run uses the same prefix:
+ *
+ * 1. `DOTREQUIREMENTS_CLI` env var if set (same override the cts-worker
+ *    hook script uses — keeps the two resolution paths consistent).
+ * 2. `node <process.argv[1]>` — points the worker at the exact CLI binary
+ *    the user just invoked. The worker subagent runs Bash on the same
+ *    machine in the same project, so reproducing the user's CLI is more
+ *    reliable than hoping `dotrequirements` on PATH resolves to the same
+ *    version.
+ */
+function resolveCliInvocation() {
+    if (process.env.DOTREQUIREMENTS_CLI)
+        return process.env.DOTREQUIREMENTS_CLI;
+    return `node ${process.argv[1]}`;
+}
+const LOCAL_CLI_INVOCATION = resolveCliInvocation();
+/**
+ * Overlay for the specifier dispatch. Inserted between the legacy
+ * SPECIFIER_PROMPT and the per-dispatch task instructions. Reinforces:
+ * - Customer-grounding discipline (per-area customers from outline.yaml)
+ * - source.txt as the read source for area files
+ * - Validate + style-check workflow
+ */
+const SPECIFIER_OVERLAY = `---
+
+## Updated context — read carefully
+
+The system prompt above gives you the discipline for producing a behavioral spec. This dispatch supplies the specific area you're working on, the customer-grounding for that area (from the approved outline), and the validate/style-check commands you must run on your own draft.
+
+## Customer-grounding (the area's customers from the approved outline)
+
+The customers below are area-scoped — each describes who interacts with THIS area's behaviors and what they're trying to do at this point in the system. Ground your requirements in these specific customer needs. Use the personas the outline names; don't substitute generic "user" / "developer" framings.
+
+## Output format
+
+The PARTIAL FILE is your primary deliverable. Markdown with fenced \`dotrequirements\` blocks per the format rules in the system prompt above. Do NOT include YAML frontmatter, H1 title, summary paragraph, or area H2 — the composer adds those downstream.
+
+## Workflow (legacy CTS-SPEC-3 — REQUIRED)
+
+After writing your initial draft, you MUST run validate then style-check on your own partial via Bash. Apply MUST FIX and SHOULD FIX findings via Edit. Style-check runs at most twice. Specific Bash commands appear in the task section below.
+`;
+function composeSpecifier(areaPrefix, options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline) || !existsSync(paths.source)) {
+        return null;
+    }
+    // Parse and validate the outline. The outline must be approved (or we
+    // wouldn't be fanning out specifiers).
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (!outline.review || outline.review.result !== "approved") {
+        return null;
+    }
+    const area = outline.areas.find((a) => a.prefix === areaPrefix);
+    if (!area)
+        return null;
+    const partialPath = paths.partial(sanitizeAreaName(area.name));
+    const outlineYaml = readFileSync(paths.outline, "utf-8");
+    const customersBlock = area.customers
+        .map((c, i) => `${i + 1}. ${c.description.trim()}`)
+        .join("\n\n");
+    const prompt = [
+        SPECIFIER_PROMPT,
+        "",
+        SPECIFIER_OVERLAY,
+        "",
+        "---",
+        "",
+        "## Your area",
+        "",
+        `Name: ${area.name}`,
+        `Prefix: ${area.prefix}`,
+        `Document defaultPrefix: ${outline.defaultPrefix}`,
+        `Requirement ID form: ${outline.defaultPrefix}-${area.prefix}-<N> (sequential, 1-indexed, no zero-padding)`,
+        "",
+        "### Description (from the approved outline)",
+        "",
+        area.description.trim(),
+        "",
+        "### Customers (area-scoped — ground your requirements in these)",
+        "",
+        customersBlock,
+        "",
+        "### Source files in this area",
+        "",
+        ...area.source_files.map((f) => `- ${f}`),
+        "",
+        `Read these files from the uncompressed pack at ${paths.source} (grep for \`File: <name>\` headers to find each one's content). You can also read them directly from the worktree if you know the paths. You may consult other files in the pack (e.g., tests, READMEs) for behaviors documented outside this area's primary files.`,
+        "",
+        "---",
+        "",
+        "## Full outline (for cross-area awareness — what is in scope vs. not)",
+        "",
+        "```yaml",
+        outlineYaml.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        `Write your partial to: ${partialPath}`,
+        "",
+        "Then run validate (REQUIRED) and style-check (REQUIRED) on your own partial via Bash:",
+        "",
+        `- Validate: \`${LOCAL_CLI_INVOCATION} cts validate ${partialPath}\``,
+        `- Style-check: \`${LOCAL_CLI_INVOCATION} cts style-check ${partialPath}\``,
+        "",
+        "Follow the three-phase workflow (Draft → Validate → Style-check) from the system prompt. Apply MUST FIX and SHOULD FIX findings via Edit. Cap style-check at two runs.",
+        "",
+        'End with a short confirmation: "Done. Partial saved to <path>."',
+    ].join("\n");
+    return { prompt };
+}
+const EDITOR_OVERLAY = `---
+
+## Updated context — read carefully
+
+The system prompt above describes editing a composed spec **document**. **This dispatch scopes you to ONE partial spec for ONE behavioral area**, not the composed document. The partial is the work-in-progress for one area; CA reviewed it and flagged revisions you must apply.
+
+## Critique shape (different from the legacy reviewer's shape)
+
+Our orchestrator uses a simpler critique shape. You receive a list of \`revisions\` — concrete directives to apply. There are NO categorized findings (no coverage_gaps / framing_errors / cross_area_issues / internal_mechanics_drift). Just revisions.
+
+You are in **apply-mode-equivalent**: apply each revision in the list as written. Do not introduce changes beyond the listed revisions. Do not restructure unflagged content. If a revision is ambiguous, apply your best literal interpretation and note the ambiguity in your final stdout confirmation.
+
+## Customer-grounding (the area's customers from outline)
+
+The customers below are area-scoped. Maintain the customer-grounded framing of existing requirements; any new requirements you add must name the same personas the existing requirements use.
+
+## Workflow (REQUIRED — same as specifier)
+
+After applying revisions via Edit, you MUST run validate + style-check on the revised partial via Bash. Apply MUST FIX and SHOULD FIX findings via Edit. Style-check runs at most twice. Specific Bash commands appear in the task section below.
+`;
+function composeEditor(areaPrefix, options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        return null;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const area = outline.areas.find((a) => a.prefix === areaPrefix);
+    if (!area)
+        return null;
+    // Editor only runs when the area has been reviewed and the latest review
+    // thread entry (written by the reviewer into outline.yaml) asks for revisions.
+    if (!area.review || area.review.result !== "needs-revision") {
+        return null;
+    }
+    const latestEntry = area.review.thread[area.review.thread.length - 1];
+    if (!latestEntry || latestEntry.result !== "needs-revision") {
+        return null;
+    }
+    const partialPath = paths.partial(sanitizeAreaName(area.name));
+    if (!existsSync(partialPath)) {
+        // Can't edit a partial that doesn't exist yet.
+        return null;
+    }
+    const currentPartial = readFileSync(partialPath, "utf-8");
+    const customersBlock = area.customers
+        .map((c, i) => `${i + 1}. ${c.description.trim()}`)
+        .join("\n\n");
+    const revisionsBlock = latestEntry.revisions
+        .map((r, i) => `${i + 1}. ${r.trim()}`)
+        .join("\n\n");
+    const prompt = [
+        EDITOR_PROMPT,
+        "",
+        EDITOR_OVERLAY,
+        "",
+        "---",
+        "",
+        "## Your area",
+        "",
+        `Name: ${area.name}`,
+        `Prefix: ${area.prefix}`,
+        `Document defaultPrefix: ${outline.defaultPrefix}`,
+        `Requirement ID form: ${outline.defaultPrefix}-${area.prefix}-<N>`,
+        "",
+        "### Description (from the approved outline)",
+        "",
+        area.description.trim(),
+        "",
+        "### Customers (area-scoped — preserve their grounding in your edits)",
+        "",
+        customersBlock,
+        "",
+        "---",
+        "",
+        "## Current partial (read via Read tool to load it into your view; the content is also embedded here for reference)",
+        "",
+        `Path: ${partialPath}`,
+        "",
+        "```markdown",
+        currentPartial.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        "## Reviewer's revisions (apply each as written)",
+        "",
+        revisionsBlock,
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        `Use the Edit tool to apply each revision to the partial at ${partialPath}. Do not introduce changes beyond the listed revisions.`,
+        "",
+        "Then run validate (REQUIRED) and style-check (REQUIRED) on the revised partial via Bash:",
+        "",
+        `- Validate: \`${LOCAL_CLI_INVOCATION} cts validate ${partialPath}\``,
+        `- Style-check: \`${LOCAL_CLI_INVOCATION} cts style-check ${partialPath}\``,
+        "",
+        "Apply MUST FIX and SHOULD FIX findings from style-check via Edit. Cap style-check at two runs.",
+        "",
+        'End with a brief stdout confirmation summarizing the kinds of changes you made (e.g., "Applied 3 revisions: added 2 requirements about edge cases, rephrased 1 framing-error finding.").',
+    ].join("\n");
+    return { prompt };
+}
+const REVIEWER_PROMPT = `You are a codebase-to-spec **reviewer**. A specifier (or editor) worker has drafted the behavioral spec for ONE area; you are a fresh, independent pair of eyes reviewing that draft before it is accepted. You did not write it — judge it on its merits.
+
+## What you are reviewing
+
+A "partial" — a Markdown file of fenced \`dotrequirements\` blocks capturing the behavior of one area, grounded in that area's customers. The schema has already been validated by the author; judge substance, not syntax.
+
+## Review criteria (priority order)
+
+1. **Customer-grounding** — Each requirement is framed around the area's named customers (the personas below), describing what that customer observes. Generic "the user" / "the developer" framing, or framing around the code's internals instead of the customer, is a problem.
+2. **Behavioral framing** — Requirements describe observable behavior, not API signatures, function names, data shapes, or implementation mechanics.
+3. **Independent testability** — Each requirement reads on its own. Cross-references between requirements ("as in REQ-X"), or criteria bundling several independent actions, hurt testability.
+4. **Coverage** — Behaviors visible in the area's source files are captured; flag notable missing behaviors.
+5. **No internal-mechanics leakage** — Internal vocabulary, private helpers, or pipeline jargon a customer would never observe should not appear.
+
+## Your verdict
+
+- **approved** — the draft meets the criteria well enough to accept. No revisions.
+- **needs-revision** — one or more criteria are not met. Provide **concrete, actionable** revision directives — each says *what to change*, specific enough that an editor can apply it mechanically. Not "this feels off" but "Reframe CTSPROMPT-STYLE-2 around what Riley observes from the checker, not the checker's internal categories."
+
+Be a real reviewer: approve genuinely good drafts (don't invent problems), but don't rubber-stamp drafts with real customer-grounding, framing, or testability issues.`;
+function composeReviewer(areaPrefix, options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        return null;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    // Same gate as composeSpecifier: area reviews only run against areas of an
+    // approved outline, so an unapproved decomposition never gets rubber-stamped
+    // area by area.
+    if (!outline.review || outline.review.result !== "approved") {
+        return null;
+    }
+    const area = outline.areas.find((a) => a.prefix === areaPrefix);
+    if (!area)
+        return null;
+    const partialPath = paths.partial(sanitizeAreaName(area.name));
+    if (!existsSync(partialPath)) {
+        // Nothing to review until the specifier has produced a partial.
+        return null;
+    }
+    const currentPartial = readFileSync(partialPath, "utf-8");
+    const customersBlock = area.customers
+        .map((c, i) => `${i + 1}. ${c.description.trim()}`)
+        .join("\n\n");
+    const prompt = [
+        REVIEWER_PROMPT,
+        "",
+        "---",
+        "",
+        "## Your area",
+        "",
+        `Name: ${area.name}`,
+        `Prefix: ${area.prefix}`,
+        "",
+        "### Description (from the approved outline)",
+        "",
+        area.description.trim(),
+        "",
+        "### Customers (area-scoped — requirements must be grounded in these)",
+        "",
+        customersBlock,
+        "",
+        "---",
+        "",
+        "## The draft partial to review",
+        "",
+        `Path: ${partialPath}`,
+        "",
+        "```markdown",
+        currentPartial.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        "1. Review the draft against the criteria above and decide your verdict.",
+        `2. Record your verdict in the outline at: ${paths.outline}`,
+        `   Find the area whose \`prefix:\` is \`${areaPrefix}\` and append one entry to its`,
+        "   `review.thread` (create the area's `review:` block with a single-entry thread if it",
+        "   has none yet), and set that area's `review.result` to match. Entry shapes:",
+        "     - `{ result: approved }`",
+        '     - `{ result: needs-revision, revisions: ["<directive>", "..."] }`',
+        "   Use the **Edit** tool and preserve every other part of the file exactly. Do NOT",
+        "   rewrite the whole file. If the Edit fails because the file changed since you read it",
+        "   (another area's reviewer wrote concurrently), re-read the outline and re-apply your",
+        "   edit to the current content.",
+        "3. Return the same verdict as your structured output:",
+        '   `{ "result": "approved" | "needs-revision", "revisions": [...] }`.',
+        "",
+        "Your outline edit and your structured return MUST carry the same verdict.",
+    ].join("\n");
+    return { prompt };
+}
+const OUTLINE_REVIEWER_PROMPT = `You are a codebase-to-spec **outline reviewer**. A planner produced an outline that carves a packed codebase into behavioral areas, each with its own area-scoped customers. You are an independent reviewer (not the planner) judging whether this decomposition is good enough to fan out specifiers against.
+
+## Criteria
+
+1. **Area granularity** — each area is a coherent behavioral surface: not so broad it smears several distinct behaviors together, not so fine it is a trivial sliver.
+2. **Area boundaries** — areas do not overlap; a given behavior belongs to exactly one area.
+3. **Coverage** — the substantive behavioral files in the pack are each assigned to some area. Non-behavioral files (build config, pure test scaffolding) may be omitted.
+4. **Customer-vocabulary names** — area names read in the customer's language (what the software does for someone), not architectural or file-layout labels. Each area declares at least one area-scoped customer with a concrete description.
+5. **Prefixes** — each area has a distinct uppercase prefix.
+
+## Verdict
+
+- **approved** — the decomposition is good enough to fan out.
+- **needs-revision** — give concrete, actionable directives the planner can apply (e.g. "split the FOO area into producer and reviewer behaviors, each its own area"; "rename BAR to customer vocabulary"; "assign baz.ts to an area"). Not "this feels off."
+
+Be a real reviewer: approve good decompositions, but flag real granularity / boundary / coverage / naming problems.`;
+function composeOutlineReviewer(options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        return null;
+    }
+    // Parse to confirm it is a well-formed outline before reviewing.
+    try {
+        parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    const outlineYaml = readFileSync(paths.outline, "utf-8");
+    const prompt = [
+        OUTLINE_REVIEWER_PROMPT,
+        "",
+        "---",
+        "",
+        "## The outline to review",
+        "",
+        `Path: ${paths.outline}`,
+        "",
+        "```yaml",
+        outlineYaml.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        "1. Review the outline against the criteria above and decide your verdict.",
+        `2. Record your verdict in the outline at: ${paths.outline}`,
+        "   Append one entry to the document-level (top-level) `review.thread` — a sibling of",
+        "   `title` / `areas`, NOT an area's `review` — creating the top-level `review:` block",
+        "   with a single-entry thread if it has none yet, and set the top-level `review.result`",
+        "   to match. Entry shapes:",
+        "     - `{ result: approved }`",
+        '     - `{ result: needs-revision, revisions: ["<directive>", "..."] }`',
+        "   Use the **Edit** tool and preserve every other part of the file exactly. If the Edit",
+        "   fails because the file changed since you read it, re-read and re-apply.",
+        "3. Return the same verdict as your structured output:",
+        '   `{ "result": "approved" | "needs-revision", "revisions": [...] }`.',
+        "",
+        "Your outline edit and your structured return MUST carry the same verdict.",
+    ].join("\n");
+    return { prompt };
+}
+const CROSS_AREA_REVIEWER_OVERLAY = `---
+
+## Orchestrator adaptations — read carefully
+
+You are reviewing the **composed spec** after per-area specifiers converged and their partials were assembled into one document. Focus on the document-level / cross-area pass — what only a whole-document view can catch: duplication across areas, inconsistent terminology or personas, awkward cross-cutting splits, depth imbalance, and document-level coverage gaps or framing errors that span areas. Per-area requirement quality has already been reviewed; do not re-litigate within-area style.
+
+Run the **persona roster check** (cheap to fix here, impossible to see per-area): each distinct customer carries exactly ONE name across the whole document, and one name never denotes different customers in different areas. Flag confusably similar names.
+
+## Verdict shape (simpler than the legacy reviewer's)
+
+Ignore the legacy categorized-findings object and three-state verdict described above. Return ONLY this shape:
+
+- \`{ "result": "approved", "revisions": [] }\` — the composed spec is coherent and ready as-is. Reserve for genuinely good specs.
+- \`{ "result": "needs-revision", "revisions": ["<directive>", "..."] }\` — fold every change you want (whether you'd have called it approved-with-revisions or requires-another-review) into a flat list of concrete, actionable directives an editor can apply mechanically. Cite requirement IDs and area names. Not "this feels off."`;
+function composeCrossAreaReviewer(options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline) || !existsSync(paths.composedSpec)) {
+        // Need both the outline (to record the verdict) and the composed spec (to
+        // review). The latter only exists once the partials have been composed.
+        return null;
+    }
+    const composed = readFileSync(paths.composedSpec, "utf-8");
+    const prompt = [
+        SPEC_REVIEWER_PROMPT,
+        "",
+        CROSS_AREA_REVIEWER_OVERLAY,
+        "",
+        "---",
+        "",
+        "## The composed spec to review",
+        "",
+        `Path: ${paths.composedSpec}`,
+        "",
+        "```markdown",
+        composed.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        `For codebase grounding, the uncompressed pack is at ${paths.source} (grep for \`File: <name>\` headers). Consult it to spot-check coverage and framing against the actual code; you do not need to read all of it.`,
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        "1. Review the composed spec against the criteria above and decide your verdict.",
+        `2. Record your verdict in the outline at: ${paths.outline}`,
+        "   Append one entry to the document-level (top-level) `crossAreaReview.thread` — a",
+        "   sibling of `title` / `summary` / `areas` / `review`. This is SEPARATE from the",
+        "   top-level `review` (which records outline approval); do NOT touch `review`. Create",
+        "   the top-level `crossAreaReview:` block with a single-entry thread if it has none",
+        "   yet, and set its `crossAreaReview.result` to match. Entry shapes:",
+        "     - `{ result: approved }`",
+        '     - `{ result: needs-revision, revisions: ["<directive>", "..."] }`',
+        "   Use the **Edit** tool and preserve every other part of the file exactly. If the Edit",
+        "   fails because the file changed since you read it, re-read and re-apply.",
+        "3. Return the same verdict as your structured output:",
+        '   `{ "result": "approved" | "needs-revision", "revisions": [...] }`.',
+        "",
+        "Your outline edit and your structured return MUST carry the same verdict.",
+    ].join("\n");
+    return { prompt };
+}
+const COMPOSE_EDITOR_OVERLAY = `---
+
+## Critique shape (different from the legacy reviewer's shape)
+
+You receive a flat list of \`revisions\` — concrete directives to apply to the composed spec. There are NO categorized findings (no coverage_gaps / framing_errors / cross_area_issues / internal_mechanics_drift). Just the revisions listed below.
+
+Apply each revision as written; do not introduce changes beyond the listed revisions, and do not restructure unflagged content. If a revision is ambiguous, apply your best literal interpretation and note it in your final stdout confirmation. Keep the document coherent — this IS the composed document (not a single area's partial).`;
+function composeComposeEditor(options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline) || !existsSync(paths.composedSpec)) {
+        // Need the outline (for the cross-area revisions) and the composed spec
+        // (to edit). Either missing → nothing to do.
+        return null;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    // Editor only runs when the cross-area reviewer recorded a needs-revision
+    // verdict in the top-level crossAreaReview thread (mirrors the per-area
+    // editor's gate on area.review).
+    if (!outline.crossAreaReview ||
+        outline.crossAreaReview.result !== "needs-revision") {
+        return null;
+    }
+    const latestEntry = outline.crossAreaReview.thread[outline.crossAreaReview.thread.length - 1];
+    if (!latestEntry || latestEntry.result !== "needs-revision") {
+        return null;
+    }
+    const composed = readFileSync(paths.composedSpec, "utf-8");
+    const revisionsBlock = latestEntry.revisions
+        .map((r, i) => `${i + 1}. ${r.trim()}`)
+        .join("\n\n");
+    const prompt = [
+        EDITOR_PROMPT,
+        "",
+        COMPOSE_EDITOR_OVERLAY,
+        "",
+        "---",
+        "",
+        "## The composed spec to edit",
+        "",
+        `Path: ${paths.composedSpec}`,
+        "",
+        "```markdown",
+        composed.trim(),
+        "```",
+        "",
+        "---",
+        "",
+        "## Cross-area revisions (apply each as written)",
+        "",
+        revisionsBlock,
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        `Use the Edit tool to apply each revision above to the composed spec at ${paths.composedSpec}. Do not introduce changes beyond the listed revisions.`,
+        "",
+        `Then run validate (REQUIRED) on the composed spec via Bash: \`${LOCAL_CLI_INVOCATION} cts validate ${paths.composedSpec}\``,
+        "",
+        "Fix any schema errors validate reports. Do NOT run style-check here: the per-area partials were already style-checked before composition, and cross-area edits are structural (dedup, terminology, persona consistency), so re-style-checking the whole assembled document is unnecessary.",
+        "",
+        "End with a brief stdout confirmation summarizing the kinds of changes you made.",
+    ].join("\n");
+    return { prompt };
+}
+function composePlannerRevise(turn, options) {
+    const projectRoot = options.projectRoot ?? findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.overview) || !existsSync(paths.outline)) {
+        return null;
+    }
+    // Read and validate the current outline. The latest thread entry must
+    // be `needs-revision` for a revise dispatch to make sense.
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch {
+        return null;
+    }
+    if (!outline.review || outline.review.result !== "needs-revision") {
+        return null;
+    }
+    const latestEntry = outline.review.thread[outline.review.thread.length - 1];
+    if (!latestEntry || latestEntry.result !== "needs-revision") {
+        return null;
+    }
+    const priorOutlineYaml = readFileSync(paths.outline, "utf-8");
+    const revisionsYaml = latestEntry.revisions
+        .map((r, i) => `- # revision ${i + 1}\n  ${r.split("\n").join("\n    ")}`)
+        .join("\n");
+    const prompt = [
+        PLANNER_REVISE_PROMPT,
+        "",
+        PLANNER_YAML_OVERLAY,
+        "",
+        "---",
+        "",
+        "## Inputs for this revision",
+        "",
+        `### Compressed packed codebase`,
+        `Path: ${paths.overview}`,
+        "",
+        `### Current outline.yaml (turn ${turn - 1})`,
+        "```yaml",
+        priorOutlineYaml.trim(),
+        "```",
+        "",
+        `### Reviewer's revisions (the latest \`review.thread\` entry's revisions, extracted)`,
+        "```yaml",
+        revisionsYaml,
+        "```",
+        "",
+        "---",
+        "",
+        "## Your task for this dispatch",
+        "",
+        "Apply each revision in the list as written. Preserve areas that the revisions don't touch.",
+        "",
+        "**IMPORTANT: Preserve the `review` section from the current outline verbatim.** Copy `review.result` and the entire `review.thread` array into your output exactly as they appear in the current outline. The orchestrator manages the review section; you must not modify it. After you write the file, the orchestrator will append a new review entry.",
+        "",
+        `Write the revised outline YAML to: ${paths.outline}`,
+        "",
+        "Do not output YAML in your reply — only write it to the file. End with a brief one-line confirmation noting the file path.",
+    ].join("\n");
+    return { prompt };
+}
+//# sourceMappingURL=dispatch.js.map