@popoverai/dotrequirements 0.24.3 → 0.25.0

package/dist/templates/skills/codebase-to-spec/SKILL.md

@@ -1,209 +1,85 @@
 ---
 name: codebase-to-spec
-description: Generate dotrequirements behavioral specifications from a codebase via the conversational orchestrator. The user's CC session drives the pipeline directly — dispatching workers as subagents, reviewing per-area drafts, and iterating with editor passes. Use this when the user wants to capture what an existing codebase does as a set of testable behavioral requirements (legacy systems, third-party libraries, before refactoring).
+description: Generate dotrequirements behavioral specifications from a codebase. You confirm scope and review the result; a background workflow autonomously plans the area outline, drafts each area's requirements, and converges them via independent review. Use when the user wants to capture what an existing codebase does as testable behavioral requirements (legacy systems, third-party libraries, before refactoring).
+allowed-tools: Bash, Read, Workflow, AskUserQuestion
 ---
 
-# Codebase to Spec — Conversational Orchestrator
+# Codebase to Spec
 
-You are the conversational orchestrator for codebase-to-spec. Unlike a thin CLI wrapper, **you drive the pipeline directly** — dispatching workers as `cts-worker` subagents (via the Task tool), reading their outputs, writing per-stage reviews into `.dotrequirements-cache/outline.yaml`, and looping until each stage converges.
-
-The CLI provides dispatch-instruction commands (`cts dispatch-*`) that you call to scaffold each step; you then dispatch the worker subagent yourself. The substrate is the single evolving `outline.yaml` file — it carries both the spec content (areas, customers, source files) and the review thread for each stage.
+You turn an existing codebase into a dotrequirements behavioral spec. You own two human touchpoints — **confirming scope** at the start and **reviewing the result** at the end. Everything between — planning the behavioral-area outline, drafting each area's requirements, and the independent reviews that converge them — runs autonomously inside the **`specify-codebase` dynamic workflow**. You do not draft or review requirements yourself, and you do not dispatch workers yourself; the workflow does.
 
 ## When this skill is right
 
-Use when the user wants behavioral requirements *from* code that already exists. Typical phrasings:
-- "Generate requirements from this codebase"
-- "Capture the behavior of this library"
-- "I want a behavioral spec for the auth module"
-- "Document what this service does"
-
-Do **not** use for new feature design (use the `dotreq-requirements` skill instead), bug investigation, or code review.
-
-## Workflow
-
-### Step 1 — Confirm scope
-
-If the user passed a scope argument (path), use it. Otherwise ask one concise question:
+Use when the user wants behavioral requirements *from* code that already exists:
+- "Generate requirements from this codebase" / "capture what this library does" / "spec the auth module before I refactor it"
 
-> "Which part of the codebase should I spec? Give me a path (e.g. `src/auth`) or say 'the whole thing'."
-
-For larger codebases, encourage scoping to a single area. The CLI will surface a `BudgetExceeded` exit code if the compressed pack is too large.
-
-### Step 2 — Pack
+Do **not** use for new-feature design (use the `dotreq-requirements` skill), bug investigation, or code review.
 
-Run `dotrequirements cts pack --scope <PATH>` via Bash. This is deterministic — no LLM work. The CLI emits `[CTS] pack/done` and `[CTS] pack/budget-ok` lines.
+## Prerequisite: dynamic workflows
 
-### Step 3 — Plan: dispatch the planner, review, iterate to approval
+This skill runs its pipeline as a dynamic Workflow. If the `Workflow` tool is not available in this environment, **stop** and tell the user:
 
-**3a. Initial planner dispatch.** Run `dotrequirements cts dispatch-planner` via Bash. The output is JSON like `{ "dispatch_id": "planner-initial", "output_path": "..." }`. Dispatch the worker:
-
-```
-Task(subagent_type="cts-worker", prompt="dispatch-id=planner-initial")
-```
+> "codebase-to-spec runs as a dynamic workflow, which this Claude Code version/configuration doesn't support. For CI or headless use, run `dotrequirements cts run --scope <path>` instead."
 
-The PreToolUse hook composes the full planner prompt; the worker writes `outline.yaml` and signals completion.
-
-**3b. Review the outline.** Read `.dotrequirements-cache/outline.yaml`. Assess:
-- **Customer naming**: Each area must have ≥1 customers with concrete, area-scoped descriptions (not "a developer" — "a Python data engineer building ETL pipelines"). Same role across areas is OK if described freshly per area's context.
-- **Area set**: Customer-vocabulary names, not architectural labels. Coverage of substantive files; non-behavioral files (tests, build infrastructure) excluded.
-- **Mechanical correctness**: distinct prefixes per area; paths matching the pack; ≥1 customer per area.
-
-**3c. Write your review into outline.yaml.** Edit the outline to add a top-level `review:` section. Two shapes:
-
-```yaml
-# Approved
-review:
-  result: approved
-  thread:
-    - result: approved
-```
-
-```yaml
-# Needs revision (revisions list is required, ≥1 entries)
-review:
-  result: needs-revision
-  thread:
-    - result: needs-revision
-      revisions:
-        - "Split the FOO area into two areas, separating the producer behavior from the reviewer behavior. Each should have its own customer and source files."
-        - "Tighten the customer description on BAR — it currently reads as generic 'a developer'; ground it in what the customer is doing at this specific moment in the system."
-```
-
-Revisions must be specific, actionable directives the planner can apply mechanically. Avoid "this feels off" — say what to change.
-
-**3d. If needs-revision, dispatch the planner again.** Run `dotrequirements cts dispatch-planner --revise`. Dispatch:
-
-```
-Task(subagent_type="cts-worker", prompt="dispatch-id=planner-revise-<N>")
-```
+Do not attempt a non-workflow fallback.
 
-(N comes from the CLI's payload — `planner-revise-2` for the 2nd round, `planner-revise-3` for the 3rd, etc.)
-
-The worker rewrites outline.yaml's content while preserving the existing `review` section. After it completes, return to step 3b and review the revised outline. Append another entry to the `review.thread` array based on what you find.
-
-**3e. Approval.** When you're satisfied, edit outline.yaml to set `review.result: approved` and append a `{ result: approved }` entry to the thread. Proceed to step 4.
-
-### Step 4 — Fan out: dispatch all specifiers in parallel
-
-Run `dotrequirements cts dispatch-spec`. The output is a JSON array of N payloads, one per area:
-
-```json
-[
-  { "dispatch_id": "specifier-PLAN", "output_path": "...", "area_name": "...", "area_prefix": "PLAN" },
-  ...
-]
-```
-
-Fire all N background Task dispatches in **one message** (parallel, not sequential):
-
-```
-Task(subagent_type="cts-worker", prompt="dispatch-id=specifier-PLAN", run_in_background=true)
-Task(subagent_type="cts-worker", prompt="dispatch-id=specifier-OREV", run_in_background=true)
-... etc
-```
-
-Each worker:
-- Reads the area's source files via Read tool (from `.dotrequirements-cache/source.txt` or directly from the worktree)
-- Drafts the partial at `.dotrequirements-cache/partials/<sanitized-area>.partial.md`
-- Runs `cts validate` + `cts style-check` on its own draft via Bash (self-style-check loop, capped at 2 runs)
-- Signals completion via task-notification
+## Workflow
 
-### Step 5 — Per-area review and editor loops
+### 1. Confirm scope
 
-As each specifier's task-notification arrives, review that area's partial:
+If the user gave a scope (a path), use it. Otherwise ask one concise question:
 
-**5a. Read the partial.** Pull up the file the worker wrote.
+> "Which part of the codebase should I spec? Give me a path (e.g. `src/auth`) or say 'the whole thing'."
 
-**5b. Review against per-area criteria.** The area's customer descriptions in outline.yaml ground your review. Look for:
-- **Customer-grounding**: requirements use named personas from the area's customers
-- **Behavioral framing**: requirements describe what the customer observes, not API contracts or implementation mechanics
-- **Independent testability**: no cross-references between requirements; each readable on its own
-- **Coverage**: behaviors visible in source files are captured; tests/recipes informed but didn't drift into the spec
-- **Schema cleanliness**: validate already ran (worker self-validated); just sanity-check
+For large codebases, encourage scoping to a single area — the pack has a context budget.
 
-**5c. Write your review into outline.yaml's area section.** Same shape as the project-level review, on the area:
+### 2. Pack (deterministic)
 
-```yaml
-areas:
-  - name: ...
-    prefix: PLAN
-    review:
-      result: approved
-      thread:
-        - result: approved
-    ...
-```
+Run `dotrequirements cts pack --scope <PATH>` via Bash. Deterministic, no LLM. It emits `[CTS] pack/done` then `pack/budget-ok`, or exits **10 (BudgetExceeded)** if the compressed pack is too large. On BudgetExceeded, surface the limit and offer a narrower scope (back to step 1).
 
-Or needs-revision with a revisions list (≥1 entries).
+### 3. Run the workflow
 
-**5d. If needs-revision, dispatch the editor.** Run `dotrequirements cts dispatch-editor <area-prefix>`. Then:
+Launch the bundled workflow:
 
 ```
-Task(subagent_type="cts-worker", prompt="dispatch-id=editor-<prefix>")
+Workflow({ name: "specify-codebase" })
 ```
 
-The worker reads the current partial + the revisions list inline (in the composed prompt), applies each revision via Edit, runs validate + style-check, signals completion. Return to 5a and re-review.
-
-**5e. Convergence.** Continue per-area loops until every area's `review.result` is `approved`. Each area can converge independently; don't block on one area to start reviewing another.
-
-### Step 6 — Cross-area review
-
-Once all per-area reviews are approved, run `cts compose-orchestrator` to assemble the composed spec. Then read it and check:
-
-- **Persona consistency**: same role mentioned across areas should use consistent naming
-- **Duplicated behaviors**: same behavior captured in two areas (one should own it)
-- **Cross-area gaps**: behaviors that fell between areas
-- **Framing drift**: areas in different voices
-
-If cross-area concerns surface, edit the affected areas' `review` to needs-revision with appropriate revisions, dispatch editors per 5d, then re-compose. Otherwise proceed to step 7.
-
-### Step 7 — Present
-
-Run `dotrequirements cts present-orchestrator [--overwrite] [--skip-existing]` via Bash. Writes the final files under `.requirements/`. Per CTS-PRESENT-1, splits into per-area files when the outline has ≥5 areas; single file otherwise.
-
-In non-interactive mode without `--overwrite` / `--skip-existing`, the CLI errors on conflicts. Ask the user which they want when a conflict is detected.
+You normally pass no `args` — `cli` defaults to `dotrequirements` on PATH, and the iteration caps default to `roundsCap: 5` / `outlineRoundsCap: 4`. Override only if needed, passing `args` as a real object (not a JSON string). *(Only in the dotrequirements dev repo, pass `args: { cli: "node <repo>/packages/cli/dist/cli.js" }`.)*
 
-### Step 8 — Summarize and offer follow-ups
+The workflow plans the outline (planner + an independent reviewer, looping to convergence), enumerates the areas, fans out one specifier per area, converges each area (specify → review → edit), then composes the partials into one spec and runs a document-level cross-area review/edit pass (dedup, terminology, seam gaps). It runs in the background — watch progress in `/workflows`. Do not narrate every step; only surface the gates below.
 
-Present the final summary in conversational form:
-- How many areas, how many requirements
-- Any unconverged areas (latest thread entry was max-turns-hit)
-- File paths written
+### 4. Read the result
 
-Offer useful follow-ups:
-- **Push to cloud** — `dotrequirements push` syncs to dotrequirements cloud. Only suggest if the user has cloud configured (check `.dotrequirements/config.json` or ask).
-- **Refine an area** — re-review one area; mark needs-revision; re-dispatch editor.
-- **Re-run on different scope** — start over with a different `--scope` path.
+The workflow returns one of:
+- **`status: "done"`** — with `areas` (per-area `{ area_prefix, area_name, partial_path, status, rounds }`), `converged_count`, `unconverged` (prefixes that hit the round cap), `failed` (prefixes whose specifier failed outright — no draft was produced), `total`, and the cross-area pass result `cross_area_rounds` / `cross_area_converged`. The workflow has already composed and reconciled the spec. Proceed to step 5.
+- **`status: "outline-unconverged"`** — the outline reviewer didn't approve the decomposition within `outlineRoundsCap`. The latest outline is at `.dotrequirements-cache/outline.yaml`. Surface this; offer to re-run, narrow scope, or hand-edit the outline. Do **not** present.
+- **`status: "enumerate-failed"`** — the approved outline's areas couldn't be enumerated (the agent died). Nothing was drafted. Surface this and offer to re-run. Do **not** present.
 
-## Pausing for user input
+### 5. Present (deterministic)
 
-These moments naturally invite user judgment — surface them in conversation rather than auto-deciding:
-- **Scope confirmation** at the start
-- **Outline approval** before fan-out (the area decomposition is high-leverage)
-- **Cross-area concerns** that look like the user's call (e.g., "should X and Y be one area or two?")
-- **Residual concerns** at the end (anything the loop didn't fully address)
+On `status: "done"`, the workflow has already composed the spec and run the cross-area pass. Write the final file(s):
+- `dotrequirements cts present-orchestrator` — writes the composed spec to file(s) under `.requirements/`.
 
-Routine progress narration ("dispatching planner...", "fan-out complete...") should NOT interrupt the user. Only judgment-requiring moments surface as questions.
+`present-orchestrator` errors on existing-file conflicts unless given `--overwrite` or `--skip-existing`. When a conflict is reported, ask the user which they want, then re-run with that flag.
 
-## Failure handling
+When `cross_area_converged` is `false`, the cross-area pass hit `crossAreaRoundsCap` without a clean approval — present the spec, but surface that in the summary so the user gives the composed spec an extra look.
 
-The CLI uses stable exit codes:
+### 6. Summarize and offer follow-ups
 
-- **Exit 10 (BudgetExceeded)** — codebase too large after compression. Surface, offer narrower `--scope`.
-- **Exit 11 (MaxTurnsHit)** — review loop hit its cap. Latest artifact is on disk; surface residual notes and ask user whether to ship, re-iterate, or hand-edit.
-- **Exit 12 (OverwriteRefused)** — present found existing files. Offer `--overwrite` or `--skip-existing`.
-- **Exit 2 (MissingInput)** — usually means a prior step wasn't run. Surface CLI message verbatim.
-- **Exit 3 (StageFailed)** — a stage errored. Read stderr; offer resume (re-run same command — the cache means earlier stages are skipped), restart fresh (`--fresh`), or investigate.
+Present a readable summary: how many areas and requirements, the file path(s) written, and — importantly — any `unconverged` areas (they hit the round cap; their latest draft was kept and is worth a look) and any `failed` areas (no draft was produced; they are absent from the spec). Then offer, **without auto-running any of them**:
+- **Push to cloud** — `dotrequirements push` (only if cloud is configured; it's a destructive sync).
+- **Refine an area** — re-run on a narrower scope.
+- **Re-run on a different scope.**
 
 ## What you must NOT do
 
-- Don't try to generate requirements yourself; always dispatch workers.
-- Don't paraphrase the CLI's progress lines in misleading ways. If the CLI emits "specifier failed", don't say "specifier completed."
-- Don't claim convergence when an area's thread ends with `needs-revision`. The loop hasn't closed.
-- Don't push to cloud without asking — `dotrequirements push` is a destructive sync.
-- Don't edit files inside `.dotrequirements-cache/` other than `outline.yaml` (which you DO edit, to write reviews). Other cache files are managed by the CLI and workers.
-- Don't dispatch a worker without the corresponding `cts dispatch-*` call first — the dispatch-id must match what the CLI scaffolded.
+- Don't draft, review, or edit requirements yourself — the workflow's workers do that.
+- Don't dispatch workers via the Task tool — the workflow owns all agent work.
+- Don't claim convergence when `unconverged` or `failed` is non-empty — surface those areas honestly.
+- Don't present when `status` is `outline-unconverged` or `enumerate-failed`.
+- Don't push to cloud without asking.
 
 ## Host portability
 
-This skill relies on Claude Code's Task tool, PreToolUse hook, and Bash. It does not work on hosts without subagent dispatch (Cursor, Codex) — those should use the legacy `cts run` CLI directly. The skill is bundled with `dotrequirements ai-setup` for Claude Code; the `cts-worker` agent definition and persona-injection hook are installed at the same time.
+This skill requires Claude Code with dynamic-workflow support (it launches the `specify-codebase` workflow). On hosts without it, or for CI/headless use, the legacy `dotrequirements cts run` CLI runs the same pipeline non-interactively.

package/dist/templates/workflows/specify-codebase.js

@@ -0,0 +1,372 @@
+export const meta = {
+  name: 'specify-codebase',
+  description:
+    'Codebase-to-spec: autonomously plan a behavioral outline, fan out specifiers across its areas, and converge each area via independent review + editor passes — no mid-run human input',
+  whenToUse:
+    'Invoked by the codebase-to-spec skill after `cts pack`. Not run directly.',
+  phases: [
+    { title: 'Outline' },
+    { title: 'Specify' },
+    { title: 'Converge' },
+    { title: 'Reconcile' },
+  ],
+}
+
+// Injected globals: agent, pipeline, parallel, phase, log, args.
+//
+// args:
+//   cli              — resolved dotrequirements CLI invocation workers shell out to
+//                      (e.g. "dotrequirements" or "node /abs/path/packages/cli/dist/cli.js")
+//   roundsCap        — max review→edit rounds per area before giving up (default 5)
+//   outlineRoundsCap — max plan→review→revise rounds for the outline (default 4)
+//   crossAreaRoundsCap — max cross-area review→edit rounds on the composed spec (default 5)
+//
+// The caps are a runaway backstop, not a target: an area stops the moment its
+// reviewer approves, and reports `unconverged` if it can't converge in N rounds.
+// Defaults are set high enough to give careful review room on messy codebases.
+//
+// args may arrive as a JSON string depending on how the caller passes it; normalize.
+const input = typeof args === 'string' ? JSON.parse(args) : args || {}
+// `cli` defaults to the PATH binary for installed users; the dev repo passes a
+// `node <repo>/dist/cli.js` invocation explicitly.
+const {
+  cli = 'dotrequirements',
+  roundsCap = 5,
+  outlineRoundsCap = 4,
+  crossAreaRoundsCap = 5,
+} = input
+
+// --- Schemas (mirrors of the JSON Schemas in schemas.ts; a sync test guards drift) ---
+
+const PARTIAL_RESULT_SCHEMA = {
+  type: 'object',
+  properties: {
+    area_prefix: { type: 'string' },
+    partial_path: { type: 'string' },
+    status: { type: 'string', enum: ['drafted', 'skipped-resume'] },
+    requirement_count: { type: 'integer', minimum: 0 },
+  },
+  required: ['area_prefix', 'partial_path', 'status'],
+  additionalProperties: false,
+}
+
+const REVIEW_VERDICT_SCHEMA = {
+  type: 'object',
+  properties: {
+    result: { type: 'string', enum: ['approved', 'needs-revision'] },
+    revisions: { type: 'array', items: { type: 'string' } },
+  },
+  required: ['result'],
+  additionalProperties: false,
+}
+
+// Shape `cts dispatch-spec` emits (one entry per approved-outline area).
+const AREAS_SCHEMA = {
+  type: 'object',
+  properties: {
+    areas: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          dispatch_id: { type: 'string' },
+          area_prefix: { type: 'string' },
+          area_name: { type: 'string' },
+          output_path: { type: 'string' },
+        },
+        required: ['dispatch_id', 'area_prefix', 'area_name', 'output_path'],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ['areas'],
+  additionalProperties: false,
+}
+
+// Thin self-compose wrapper: a worker fetches its full instructions from the CLI.
+function follow(line) {
+  return [
+    `Run exactly this command: ${line}`,
+    `It prints JSON of the form {"prompt": "..."}. Read the "prompt" field and follow it EXACTLY.`,
+  ]
+}
+
+// ============================ Stage 0: outline ============================
+// plan → review → revise → re-review, until the outline reviewer approves the
+// area decomposition or the cap is hit. Sequential (one outline), so the
+// reviewer's writes to the document-level review.thread never contend.
+phase('Outline')
+
+await agent(
+  [
+    `You are a codebase-to-spec planner. Produce the behavioral-area outline for the packed codebase.`,
+    ...follow(`${cli} cts dispatch-context planner-initial`),
+    `End with a one-line confirmation of the outline path you wrote.`,
+  ].join('\n'),
+  { agentType: 'cts-worker', label: 'plan outline', phase: 'Outline' },
+)
+
+let outlineApproved = false
+for (let round = 1; round <= outlineRoundsCap; round++) {
+  const verdict = await agent(
+    [
+      `You are a codebase-to-spec outline reviewer (independent of the planner).`,
+      ...follow(`${cli} cts dispatch-context outline-reviewer`),
+      `It tells you to record your verdict in the outline's top-level review thread and return it.`,
+      `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+    ].join('\n'),
+    {
+      schema: REVIEW_VERDICT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `review outline r${round}`,
+      phase: 'Outline',
+    },
+  )
+
+  // Fail-closed: only an explicit "approved" verdict advances. A null verdict
+  // (reviewer subagent died after retries) is treated as non-approval — fall
+  // through to revise/re-review so we never fan out an unreviewed outline.
+  if (verdict?.result === 'approved') {
+    outlineApproved = true
+    break
+  }
+  if (round === outlineRoundsCap) break
+
+  await agent(
+    [
+      `You are a codebase-to-spec planner applying the reviewer's outline revisions.`,
+      ...follow(`${cli} cts dispatch-context planner-revise-${round + 1}`),
+      `End with a one-line confirmation.`,
+    ].join('\n'),
+    { agentType: 'cts-worker', label: `revise outline r${round}`, phase: 'Outline' },
+  )
+}
+
+if (!outlineApproved) {
+  // No mid-run HITL: don't fan out a decomposition the reviewer wouldn't pass.
+  log(`outline did not converge within ${outlineRoundsCap} rounds`)
+  return {
+    status: 'outline-unconverged',
+    outline_rounds: outlineRoundsCap,
+    areas: [],
+    converged_count: 0,
+    unconverged: [],
+    failed: [],
+    total: 0,
+  }
+}
+
+// ===================== Stage 1+2: fan out + converge =====================
+// Enumerate the approved outline's areas (an agent runs the CLI; the script
+// can't), then run each area through specify → review/edit independently.
+phase('Specify')
+
+const enumerated = await agent(
+  [
+    `Run exactly this command: ${cli} cts dispatch-spec`,
+    `It prints a JSON array, one entry per area of the approved outline.`,
+    `Return { "areas": <that array, verbatim> }.`,
+  ].join('\n'),
+  { schema: AREAS_SCHEMA, agentType: 'cts-worker', label: 'enumerate areas', phase: 'Specify' },
+)
+
+// Fail-closed: a dead enumerate agent (null return) must surface as a failure,
+// not read as an empty-but-successful decomposition that sails through fan-out
+// and reconcile to a hollow `done`.
+if (!enumerated) {
+  log('area enumeration failed — cannot fan out')
+  return {
+    status: 'enumerate-failed',
+    areas: [],
+    converged_count: 0,
+    unconverged: [],
+    failed: [],
+    total: 0,
+  }
+}
+const areas = enumerated.areas
+
+async function specify(area) {
+  return agent(
+    [
+      `You are a codebase-to-spec specifier worker for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+      ``,
+      `Step 1 — Resume check. If a non-empty partial already exists at:`,
+      `    ${area.output_path}`,
+      `  then do NOT regenerate it. Return`,
+      `  { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}", "status": "skipped-resume" }.`,
+      ``,
+      `Step 2 — Otherwise, run exactly this command:`,
+      `    ${cli} cts dispatch-context specifier-${area.area_prefix}`,
+      `  Read the "prompt" field of its JSON output and follow it EXACTLY — which source files to`,
+      `  read, how to ground requirements in this area's customers, where to write the partial,`,
+      `  and how to validate + style-check it.`,
+      ``,
+      `Step 3 — Return`,
+      `  { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}",`,
+      `    "status": "drafted", "requirement_count": <number of requirements you wrote> }.`,
+    ].join('\n'),
+    {
+      schema: PARTIAL_RESULT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `specify ${area.area_name}`,
+      phase: 'Specify',
+    },
+  )
+}
+
+async function reviewEditLoop(specifyResult, area) {
+  // Fail-closed (CTSO-INTEG-3.2): a dead specifier (null return) means there may
+  // be no partial to review — record the failure and continue with the other
+  // areas, instead of burning review/edit rounds on a draft that may not exist.
+  if (!specifyResult) {
+    log(`area ${area.area_prefix}: specifier failed — recording and moving on`)
+    return {
+      area_prefix: area.area_prefix,
+      area_name: area.area_name,
+      partial_path: area.output_path,
+      status: 'failed',
+      rounds: 0,
+    }
+  }
+
+  for (let round = 1; round <= roundsCap; round++) {
+    const verdict = await agent(
+      [
+        `You are a codebase-to-spec reviewer for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+        ...follow(`${cli} cts dispatch-context reviewer-${area.area_prefix}`),
+        `It tells you to review the partial, record your verdict in the outline, and return it.`,
+        `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+      ].join('\n'),
+      {
+        schema: REVIEW_VERDICT_SCHEMA,
+        agentType: 'cts-worker',
+        label: `review ${area.area_name} r${round}`,
+        phase: 'Converge',
+      },
+    )
+
+    if (verdict?.result === 'approved') {
+      return {
+        area_prefix: area.area_prefix,
+        area_name: area.area_name,
+        partial_path: area.output_path,
+        status: 'converged',
+        rounds: round - 1,
+      }
+    }
+
+    // Fail-closed: a null verdict (dead reviewer) is NOT approval — but it also
+    // recorded no fresh revisions in the outline, so dispatching an editor here
+    // would only re-apply the previous round's already-applied list (or have
+    // nothing to act on in round 1). Skip straight to the next review round.
+    if (!verdict) continue
+
+    // Mirror the outline and cross-area loops: the final round's verdict is
+    // final. Without this guard a last editor pass would run whose output is
+    // never re-reviewed before composition.
+    if (round === roundsCap) break
+
+    await agent(
+      [
+        `You are a codebase-to-spec editor for the area "${area.area_name}" (prefix ${area.area_prefix}).`,
+        ...follow(`${cli} cts dispatch-context editor-${area.area_prefix}`),
+        `It embeds the reviewer's revisions and tells you to apply them, then validate + style-check.`,
+        `Return { "area_prefix": "${area.area_prefix}", "partial_path": "${area.output_path}",`,
+        `  "status": "drafted", "requirement_count": <number of requirements now in the partial> }.`,
+      ].join('\n'),
+      {
+        schema: PARTIAL_RESULT_SCHEMA,
+        agentType: 'cts-worker',
+        label: `edit ${area.area_name} r${round}`,
+        phase: 'Converge',
+      },
+    )
+  }
+
+  log(`area ${area.area_prefix} hit roundsCap=${roundsCap} without approval`)
+  return {
+    area_prefix: area.area_prefix,
+    area_name: area.area_name,
+    partial_path: area.output_path,
+    status: 'unconverged',
+    rounds: roundsCap,
+  }
+}
+
+log(`Outline approved — fanning out ${areas.length} area(s)`)
+
+const results = (await pipeline(areas, specify, reviewEditLoop)).filter(Boolean)
+
+// ===================== Stage 3: compose + cross-area reconcile =====================
+// The per-area partials have converged. Assemble them into one composed spec
+// (deterministic), then run the document-level cross-area review/edit loop
+// (CTSO-CONV-5) — duplication, terminology drift, and seam gaps that only a
+// whole-document view catches — before the skill presents the result.
+phase('Reconcile')
+
+await agent(
+  [
+    `Run exactly this command: ${cli} cts compose-orchestrator`,
+    `It deterministically assembles the converged area partials into a single composed spec.`,
+    `End with a one-line confirmation of the composed-spec path it reports.`,
+  ].join('\n'),
+  { agentType: 'cts-worker', label: 'compose spec', phase: 'Reconcile' },
+)
+
+let crossAreaRounds = 0
+let crossAreaConverged = false
+for (let round = 1; round <= crossAreaRoundsCap; round++) {
+  crossAreaRounds = round
+  const verdict = await agent(
+    [
+      `You are a codebase-to-spec cross-area reviewer (document-level, independent).`,
+      ...follow(`${cli} cts dispatch-context cross-area-reviewer`),
+      `It tells you to review the composed spec for cross-area + document-level issues, record your verdict in the outline, and return it.`,
+      `Return { "result": "approved" | "needs-revision", "revisions": [...] }.`,
+    ].join('\n'),
+    {
+      schema: REVIEW_VERDICT_SCHEMA,
+      agentType: 'cts-worker',
+      label: `cross-area review r${round}`,
+      phase: 'Reconcile',
+    },
+  )
+
+  // Fail-closed: only an explicit "approved" verdict ends the loop. A null
+  // verdict (dead reviewer) is non-approval — fall through to edit/re-review.
+  if (verdict?.result === 'approved') {
+    crossAreaConverged = true
+    break
+  }
+  if (round === crossAreaRoundsCap) break
+
+  // The reviewer recorded its revisions in the outline's crossAreaReview thread;
+  // the compose editor self-composes from there and edits the composed spec.
+  await agent(
+    [
+      `You are a codebase-to-spec compose editor applying cross-area revisions to the composed spec.`,
+      ...follow(`${cli} cts dispatch-context compose-editor`),
+      `It embeds the cross-area reviewer's revisions and tells you to apply them, then validate.`,
+      `End with a one-line confirmation.`,
+    ].join('\n'),
+    { agentType: 'cts-worker', label: `compose edit r${round}`, phase: 'Reconcile' },
+  )
+}
+
+if (!crossAreaConverged) {
+  log(`cross-area review did not converge within ${crossAreaRoundsCap} rounds`)
+}
+
+return {
+  status: 'done',
+  areas: results,
+  converged_count: results.filter((r) => r.status === 'converged').length,
+  unconverged: results
+    .filter((r) => r.status === 'unconverged')
+    .map((r) => r.area_prefix),
+  failed: results.filter((r) => r.status === 'failed').map((r) => r.area_prefix),
+  total: areas.length,
+  cross_area_rounds: crossAreaRounds,
+  cross_area_converged: crossAreaConverged,
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.24.3",
+  "version": "0.25.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {
@@ -71,7 +71,7 @@
     "@types/node": "^20",
     "@types/uuid": "^11.0.0",
     "typescript": "^5",
-    "vitest": "^4.0.0"
+    "vitest": "^4.1.8"
   },
   "files": [
     "dist",