@popoverai/dotrequirements 0.24.3 → 0.26.0

package/README.md

@@ -243,19 +243,18 @@ Optional settings: `vercelBypassSecret`, `browserbaseApiKey`, `browserbaseProjec
 
 ### `dotreq cts` *(Alpha)*
 
-Generate behavioral requirements from an existing codebase. Packs the codebase, plans a behavioral outline, fans out per-area specifier agents to draft per-area requirements, runs a dual review loop, and writes the result to `.requirements/`.
+Generate behavioral requirements from an existing codebase — it plans a behavioral outline, drafts the requirements for each area, converges each through independent review, then reconciles the whole spec in a final cross-area pass, and writes the result to `.requirements/`.
+
+It runs as a Claude Code skill backed by a dynamic workflow. Install it, then invoke it from Claude Code:
 
 ```bash
-dotreq cts run --scope src                 # full pipeline end-to-end
-dotreq cts run --scope src --fresh         # discard cache and start over
-dotreq cts run --scope src --ignore-requirements   # run against a codebase that already has its own .requirements/
+dotreq cts skill-install            # install into this project's .claude/
+dotreq cts skill-install --global   # …or into ~/.claude/ for every project
 ```
 
-`cts` shells out to `claude -p` and uses whatever auth mode you've configured for Claude Code. Each pipeline stage is also runnable on its own (`dotreq cts pack`, `plan-loop`, `fan-out`, `compose`, `edit-loop`, `present`) for partial re-runs and debugging.
-
-> **Alpha:** output quality is prompt-sensitive and varies by codebase. See the [Codebase to Spec docs](https://docs.dotrequirements.io/tools/cli/codebase-to-spec) for prerequisites, options, exit codes, and known rough edges. Feedback to support@dotrequirements.io welcome.
+Then, in Claude Code, run `/codebase-to-spec` (or just ask — e.g. "spec the auth module"). You confirm the scope; the workflow autonomously plans the areas, drafts and reviews each one, reconciles them in a cross-area pass, and writes the result to `.requirements/`. Requires a Claude Code version with dynamic-workflow support.
 
-> **Heads up:** as of June 15, 2026, `claude -p` bills against your Claude subscription's API credit instead of the subscription seat (per Anthropic's May 13, 2026 announcement). `cts` runs will draw from that credit.
+> **Alpha:** output quality is prompt-sensitive and varies by codebase. See the [Codebase to Spec docs](https://docs.dotrequirements.io/tools/cli/codebase-to-spec) for prerequisites, scoping, and known rough edges. Feedback to support@dotrequirements.io welcome.
 
 ### `dotreq ai-setup`
 

package/dist/cli.js

@@ -64,7 +64,13 @@ program
     .action(wrapCommand(initCommand));
 program
     .command("link")
-    .description("Link local environment to an existing project")
+    .description("Link local environment to a cloud project (creating one when needed)")
+    .option("-y, --yes", "Non-interactive: resolve every decision from defaults or flags; never prompt")
+    .option("--json", "Machine-readable output (one JSON object on stdout)")
+    .option("--team <nameOrId>", "Use this team (implies --yes)")
+    .option("--connect <slug>", "Connect to this existing project (implies --yes)")
+    .option("--create", "Create a new project (implies --yes)")
+    .option("-n, --name <name>", "Project name for --create or rename")
     .action(wrapCommand(linkCommand));
 program
     .command("pull")
@@ -125,6 +131,7 @@ program
 program
     .command("ai-setup")
     .description("Configure MCP server for your AI assistant (Claude Code, Claude Desktop, etc.)")
+    .option("-a, --assistant <id>", "Configure for this assistant without prompting (e.g. claude-code)")
     .action(wrapCommand(aiSetupCommand));
 program
     .command("search <query>")

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

@@ -1,23 +1,31 @@
 /**
- * Dispatch-context composition for the conversational orchestrator.
+ * Dispatch-context composition for the codebase-to-spec workflow.
  *
- * The orchestrator's PreToolUse hook calls `dotrequirements cts dispatch-context
- * <dispatch-id>` to fetch the composed prompt that should be injected into a
- * cts-worker subagent's first turn (per CTSO-CLI-1).
+ * 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:
- * - `phase1-test` — mechanical plumbing test (Phase 1)
- * - `planner-initial` — initial planner dispatch; writes outline.yaml
- * - `planner-revise-<turn>` — revising planner dispatch; reads the prior
- *   outline.yaml (with its review.thread), applies the latest thread
- *   entry's revisions, writes a new outline.yaml. `<turn>` is the round
- *   number being PRODUCED (turn 2 = first revision).
- *
- * Future phases will add `specifier-<area>`, `editor-<area>`, etc.
+ * - `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-CLI-1: CLI exposes commands that return dispatch instructions
- * - CTSO-CONV-2: orchestrator iterates on the planner's outline until approved
+ * - CTSO-CONV-2: the outline converges via an independent reviewer loop
+ * - CTSO-CONV-5: cross-area review reconciles the composed spec
  */
 export interface DispatchContext {
     /**
@@ -52,6 +60,44 @@ export declare const SPECIFIER_DISPATCH_ID_PREFIX = "specifier-";
  * the latest area.review.thread entry's revisions).
  */
 export declare 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 declare 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 declare 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 declare 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 declare const COMPOSE_EDITOR_DISPATCH_ID = "compose-editor";
 export interface ComposeDispatchOptions {
     /**
      * Project root used to resolve cache paths. Defaults to `findProjectRoot()`

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

@@ -1,23 +1,31 @@
 /**
- * Dispatch-context composition for the conversational orchestrator.
+ * Dispatch-context composition for the codebase-to-spec workflow.
  *
- * The orchestrator's PreToolUse hook calls `dotrequirements cts dispatch-context
- * <dispatch-id>` to fetch the composed prompt that should be injected into a
- * cts-worker subagent's first turn (per CTSO-CLI-1).
+ * 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:
- * - `phase1-test` — mechanical plumbing test (Phase 1)
- * - `planner-initial` — initial planner dispatch; writes outline.yaml
- * - `planner-revise-<turn>` — revising planner dispatch; reads the prior
- *   outline.yaml (with its review.thread), applies the latest thread
- *   entry's revisions, writes a new outline.yaml. `<turn>` is the round
- *   number being PRODUCED (turn 2 = first revision).
- *
- * Future phases will add `specifier-<area>`, `editor-<area>`, etc.
+ * - `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-CLI-1: CLI exposes commands that return dispatch instructions
- * - CTSO-CONV-2: orchestrator iterates on the planner's outline until approved
+ * - 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";
@@ -26,6 +34,7 @@ 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. */
@@ -53,6 +62,44 @@ export const SPECIFIER_DISPATCH_ID_PREFIX = "specifier-";
  * 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.
  *
@@ -80,6 +127,24 @@ export function composeDispatchContext(dispatchId, options = {}) {
             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)
@@ -344,7 +409,7 @@ function composeEditor(areaPrefix, options) {
     if (!area)
         return null;
     // Editor only runs when the area has been reviewed and the latest review
-    // entry asks for revisions.
+    // thread entry (written by the reviewer into outline.yaml) asks for revisions.
     if (!area.review || area.review.result !== "needs-revision") {
         return null;
     }
@@ -419,6 +484,307 @@ function composeEditor(areaPrefix, options) {
     ].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);

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

@@ -30,6 +30,13 @@ export interface PackOptions {
     paths: CachePaths;
     /** Optional scope path (subdir of projectRoot) to limit which files are packed. */
     scope?: string;
+    /**
+     * When set, pack a remote repository (a GitHub URL or `owner/repo` shorthand)
+     * instead of a local path. Repomix clones it to a temp dir, packs, and cleans
+     * up. With `remote`, `scope` is interpreted as a repo-relative subdirectory and
+     * mapped to a repomix `include` glob (`<scope>/**`).
+     */
+    remote?: string;
     /** Additional ignore patterns (beyond defaults and project-level). */
     extraIgnores?: string[];
     /**