@popoverai/dotrequirements 0.24.2 → 0.24.3

package/dist/commands/codebase-to-spec/present-orchestrator.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `dotrequirements codebase-to-spec present-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `present`. Reads outline.yaml +
+ * composedSpec (produced by compose-orchestrator), writes the final spec
+ * to `.requirements/`. The orchestrator doesn't have a separate
+ * document-level edit-loop, so this reads from composedSpec directly
+ * rather than specFinal.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-1..4 (reuses the legacy present logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+export interface PresentOrchestratorOptions {
+    forceMode?: "interactive" | "non-interactive";
+    overwrite?: boolean;
+    skipExisting?: boolean;
+}
+export declare function presentOrchestratorCommand(options?: PresentOrchestratorOptions): Promise<void>;
+//# sourceMappingURL=present-orchestrator.d.ts.map

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

@@ -0,0 +1,81 @@
+/**
+ * `dotrequirements codebase-to-spec present-orchestrator` subcommand.
+ *
+ * Conversational-orchestrator variant of `present`. Reads outline.yaml +
+ * composedSpec (produced by compose-orchestrator), writes the final spec
+ * to `.requirements/`. The orchestrator doesn't have a separate
+ * document-level edit-loop, so this reads from composedSpec directly
+ * rather than specFinal.
+ *
+ * Requirements covered:
+ * - CTS-PRESENT-1..4 (reuses the legacy present logic)
+ * - CTSO-INTEG-1: orchestrator uses existing deterministic stages unchanged
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { cachePaths } from "../../codebase-to-spec/cache.js";
+import { ExitCode } from "../../codebase-to-spec/exit-codes.js";
+import { detectMode } from "../../codebase-to-spec/interactive.js";
+import { runPresent, } from "../../codebase-to-spec/present.js";
+import { conversationalOutlineToLegacy, parseConversationalOutline, } from "../../codebase-to-spec/schemas.js";
+import { findProjectRoot } from "../../utils/project-settings.js";
+function resolvePolicy(isInteractive, options) {
+    if (options.overwrite && options.skipExisting) {
+        return { error: "--overwrite and --skip-existing are mutually exclusive." };
+    }
+    if (options.overwrite)
+        return "overwrite";
+    if (options.skipExisting)
+        return "skip-existing";
+    if (isInteractive)
+        return "prompt";
+    return "fail-fast";
+}
+export async function presentOrchestratorCommand(options = {}) {
+    const projectRoot = findProjectRoot(process.cwd()) ?? process.cwd();
+    const paths = cachePaths(projectRoot);
+    if (!existsSync(paths.outline)) {
+        process.stderr.write(`No outline.yaml found at ${paths.outline}. Run the orchestrator's planner first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    if (!existsSync(paths.composedSpec)) {
+        process.stderr.write(`No composed spec at ${paths.composedSpec}. Run \`cts compose-orchestrator\` first.\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    let outline;
+    try {
+        outline = parseConversationalOutline(readFileSync(paths.outline, "utf-8"));
+    }
+    catch (err) {
+        process.stderr.write(`Outline at ${paths.outline} is invalid: ${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = ExitCode.MissingInput;
+        return;
+    }
+    const { isInteractive } = detectMode(options.forceMode);
+    const policy = resolvePolicy(isInteractive, options);
+    if (typeof policy === "object") {
+        process.stderr.write(`${policy.error}\n`);
+        process.exitCode = ExitCode.InvalidFlags;
+        return;
+    }
+    const legacyOutline = conversationalOutlineToLegacy(outline);
+    const result = await runPresent({
+        outline: legacyOutline,
+        finalSpecPath: paths.composedSpec,
+        projectRoot,
+        overwritePolicy: policy,
+    });
+    if (!result.allWritten) {
+        if (result.conflictPath) {
+            process.stderr.write(`Refusing to overwrite ${result.conflictPath}. Pass --overwrite or --skip-existing.\n`);
+        }
+        process.exitCode = ExitCode.OverwriteRefused;
+        return;
+    }
+    for (const action of result.actions) {
+        process.stdout.write(`  ${action.action}: ${action.path}\n`);
+    }
+    process.stdout.write(`Wrote ${result.actions.filter((a) => a.action === "created" || a.action === "overwrote").length} file(s) to .requirements/\n`);
+}
+//# sourceMappingURL=present-orchestrator.js.map

package/dist/commands/codebase-to-spec/skill-install.js

@@ -41,7 +41,18 @@ export async function skillInstallCommand(options = {}) {
         else {
             process.stdout.write(`SKILL.md already up to date at ${result.installedPath}\n`);
         }
-        process.stdout.write("Skill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language).\n");
+        if (result.companions) {
+            process.stdout.write(`Installed cts-worker agent at ${result.companions.agentPath}\n`);
+            process.stdout.write(`Installed persona-injection hook at ${result.companions.hookScriptPath}\n`);
+            if (result.companions.hookRegistered) {
+                process.stdout.write(`Registered PreToolUse hook in ${result.companions.settingsPath}\n`);
+            }
+            else {
+                process.stdout.write(`PreToolUse hook already registered in ${result.companions.settingsPath}\n`);
+            }
+            process.stdout.write("\n⚠️  The hook script uses `dotrequirements` from PATH. If you're working in a local dev clone, set DOTREQUIREMENTS_CLI to override (see the hook script for details).\n");
+        }
+        process.stdout.write("\nSkill ready. In Claude Code, invoke it with `/codebase-to-spec` (or via natural language).\n");
     }
     catch (err) {
         process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);

package/dist/templates/agents/cts-worker.md

@@ -0,0 +1,9 @@
+---
+name: cts-worker
+description: Generic worker subagent for the codebase-to-spec conversational orchestrator. Used for planner, specifier, editor, and reviewer dispatches. The per-dispatch persona is injected by the cts-worker-persona PreToolUse hook at dispatch time.
+tools: Bash, Read, Edit, Write, Glob, Grep
+---
+
+You are a codebase-to-spec worker. Your dispatched prompt is composed externally and supplied to you at dispatch time. It will specify your role for this dispatch (planner, specifier, editor, or reviewer), the artifacts you're working with, and the output convention you must follow.
+
+Follow the dispatched prompt exactly. Do not improvise behavior beyond what it asks. When your work is done, submit via the convention specified in the dispatch (typically a `dotrequirements cts submit` call).

package/dist/templates/hooks/cts-worker-persona.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# PreToolUse hook for Task(subagent_type=cts-worker) dispatches.
+# Composes the worker's first-turn prompt by calling
+# `dotrequirements cts dispatch-context <dispatch-id>` and emits the
+# result via `updatedInput.prompt`.
+#
+# The orchestrator's convention: the original Task prompt MUST include
+# the verbatim token `dispatch-id=<id>` so the hook can extract it.
+#
+# Bundled with the codebase-to-spec skill (CTSO-CLI-1).
+#
+# CLI resolution order:
+#   1. DOTREQUIREMENTS_CLI env var (explicit override)
+#   2. If running inside the dotrequirements monorepo itself
+#      ($CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js exists), use that
+#      local build. Lets dotrequirements developers use the orchestrator
+#      against any worktree without a global install.
+#   3. `dotrequirements` from PATH (the canonical end-user setup).
+
+INPUT=$(cat)
+SUBAGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // ""')
+
+# Self-filter: only act on cts-worker dispatches.
+if [[ "$SUBAGENT_TYPE" != "cts-worker" ]]; then
+  exit 0
+fi
+
+ORIGINAL_PROMPT=$(echo "$INPUT" | jq -r '.tool_input.prompt // ""')
+
+# Extract dispatch-id token from the original prompt.
+DISPATCH_ID=$(echo "$ORIGINAL_PROMPT" | grep -oE 'dispatch-id=[a-zA-Z0-9_-]+' | head -1 | sed 's/dispatch-id=//')
+
+if [[ -z "$DISPATCH_ID" ]]; then
+  # No dispatch-id in the prompt — let it through unmodified.
+  exit 0
+fi
+
+# Resolve the CLI invocation (see header for order).
+if [[ -n "${DOTREQUIREMENTS_CLI:-}" ]]; then
+  CLI="$DOTREQUIREMENTS_CLI"
+elif [[ -n "${CLAUDE_PROJECT_DIR:-}" && -f "$CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js" ]]; then
+  CLI="node $CLAUDE_PROJECT_DIR/packages/cli/dist/cli.js"
+else
+  CLI="dotrequirements"
+fi
+
+# Compose the dispatch context. CLI returns JSON like {"prompt": "..."}.
+COMPOSED=$($CLI cts dispatch-context "$DISPATCH_ID" 2>/dev/null)
+COMPOSE_STATUS=$?
+
+if [[ $COMPOSE_STATUS -ne 0 || -z "$COMPOSED" ]]; then
+  # CLI call failed — let the dispatch through unmodified so the
+  # worker's failure is legible.
+  exit 0
+fi
+
+PROMPT=$(echo "$COMPOSED" | jq -r '.prompt // ""')
+
+if [[ -z "$PROMPT" ]]; then
+  exit 0
+fi
+
+# Emit updatedInput so the worker subagent sees the composed prompt
+# as its first-turn input. (Field name is `updatedInput`, not
+# `modifiedInput` — verified by spike work; see working doc.)
+jq -nc --arg p "$PROMPT" '{
+  hookSpecificOutput: {
+    hookEventName: "PreToolUse",
+    permissionDecision: "allow",
+    updatedInput: {
+      prompt: $p
+    }
+  }
+}'
+
+exit 0

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

@@ -1,118 +1,209 @@
 ---
 name: codebase-to-spec
-description: Generate dotrequirements behavioral specifications from a codebase. Use this when the user wants to capture what an existing codebase does as a set of testable behavioral requirements — e.g. for legacy systems, third-party libraries, or before refactoring.
+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).
 ---
 
-# Codebase to Spec
+# Codebase to Spec — Conversational Orchestrator
 
-You are a thin conversational wrapper around the `dotrequirements cts run` CLI. **You do not implement any pipeline logic yourself.** The CLI handles packing, planning, fan-out parallelism, retry, resumability, review loops, and presentation. Your job is to:
+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.
 
-1. Confirm the user's scope.
-2. Run the CLI via the Bash tool.
-3. Narrate progress as the CLI emits it.
-4. Surface the final summary and residual notes.
-5. Offer sensible follow-ups (push to cloud, re-run, narrow scope, etc.).
+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.
 
 ## When this skill is right
 
-Use it when the user wants behavioral requirements *from* code that already exists. Typical phrasings:
+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 it for:
-- New feature design (use `dotreq-requirements` / the capture flow instead)
-- Bug investigation
-- Code review
+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 (e.g. a path like `src/auth`), use it. Otherwise, ask one concise question:
+If the user passed a scope argument (path), use it. Otherwise ask one concise question:
 
-> "Which part of the codebase should I spec? You can give me a path (e.g. `src/auth`) or say 'the whole thing'."
+> "Which part of the codebase should I spec? Give me a path (e.g. `src/auth`) or say 'the whole thing'."
 
-Whole-codebase runs are fine for small repos. For larger ones, encourage scoping to a single area — the CLI will tell you if the working-context budget is exceeded.
+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 — Run the CLI
+### Step 2 — Pack
 
-Invoke the pipeline via Bash. The command is:
+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.
+
+### Step 3 — Plan: dispatch the planner, review, iterate to approval
+
+**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")
+```
+
+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>")
+```
+
+(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):
 
-```bash
-dotrequirements cts run --scope <PATH> --non-interactive
 ```
+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
+
+### Step 5 — Per-area review and editor loops
+
+As each specifier's task-notification arrives, review that area's partial:
+
+**5a. Read the partial.** Pull up the file the worker wrote.
 
-Flags:
-- `--scope <path>` — limit packing to a subdirectory. Omit for the whole repo.
-- `--non-interactive` — important: you're running in an agentic context, so prompts won't work.
-- `--overwrite` — replace existing `.requirements/*.requirements.md` files.
-- `--skip-existing` — leave existing files untouched.
-- `--fresh` — clear the cache before running (use only if a previous run is corrupt).
+**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
 
-Default to `--non-interactive`. Decide between `--overwrite` and `--skip-existing` based on what the user wants if there are existing `.requirements/` files; otherwise neither flag is needed (the default `fail-fast` policy will surface conflicts).
+**5c. Write your review into outline.yaml's area section.** Same shape as the project-level review, on the area:
 
-### Step 3 — Narrate progress
+```yaml
+areas:
+  - name: ...
+    prefix: PLAN
+    review:
+      result: approved
+      thread:
+        - result: approved
+    ...
+```
+
+Or needs-revision with a revisions list (≥1 entries).
 
-The CLI emits lines like:
+**5d. If needs-revision, dispatch the editor.** Run `dotrequirements cts dispatch-editor <area-prefix>`. Then:
 
 ```
-[CTS] pack/done Packed 16 files → ... (compressed), ... (uncompressed)
-[CTS] plan/done Plan loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] specify/summary Completed: 7 / Skipped (resume): 0 / Failed: 0
-[CTS] spec-review/done Edit loop converged at turn 1 with verdict: approved-with-revisions
-[CTS] present/created created: .../sample.requirements.md
+Task(subagent_type="cts-worker", prompt="dispatch-id=editor-<prefix>")
 ```
 
-Surface these to the user in conversational form as they appear. **Do not invent progress claims** — narrate only what the CLI has actually emitted. If the CLI is silent for a long stretch (specifier fan-out can take minutes), a single reassuring note ("still working — the specifier fan-out runs in parallel and takes a few minutes for larger areas") is fine. Don't repeat it.
+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.
 
-### Step 4 — Surface the final summary
+### Step 8 — Summarize and offer follow-ups
 
-When the CLI finishes successfully, it prints a "Pipeline summary:" block with:
-- total areas
-- total top-level requirements
-- outline review turns and verdict
-- specifier completion count
-- spec review turns and verdict
-- the list of output files written
-- residual notes (issues the reviewer flagged in `approved-with-revisions` outcomes)
+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
 
-Present that summary back to the user. **Highlight the residual notes** prominently — these are concerns the reviewer wanted the human to verify. Common categories:
-- `outline.coverage_gap` — files the planner didn't assign to any area
-- `spec.coverage_gap` — behaviors the spec missed
-- `spec.framing_error` — requirements written as guidance/explanation rather than observable behavior
-- `spec.cross_area` — duplication across areas
-- `spec.internal_mechanics` — internal vocabulary that leaked into a user-facing spec
+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.
 
-### Step 5 — Offer follow-ups
+## Pausing for user input
 
-After surfacing the summary, ask the user what they want next. Useful options:
+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)
 
-- **Push to cloud** — `dotrequirements push` syncs the generated `.requirements/*.requirements.md` files to dotrequirements cloud. Only suggest this if the user has a cloud account (you can check by reading `.dotrequirements/config.json` or asking).
-- **Refine a specific area** — re-run `dotrequirements cts specify-area "<name>"` for one area, optionally with `--model <name>` for a stronger model.
-- **Refine the whole spec** — re-run `dotrequirements cts edit-loop` to iterate on the composed spec.
-- **Narrow the scope** — re-run with a smaller `--scope`.
-- **Hand-edit** — the output files are plain Markdown; the user can edit them directly.
+Routine progress narration ("dispatching planner...", "fan-out complete...") should NOT interrupt the user. Only judgment-requiring moments surface as questions.
 
 ## Failure handling
 
-The CLI uses stable exit codes (see `dotrequirements cts run --help`). Common cases:
+The CLI uses stable exit codes:
 
-- **Exit code 10 (BudgetExceeded)** — the codebase is too large for a single agent's context window after compression. Explain this in plain language and offer to retry with a narrower `--scope`.
-- **Exit code 11 (MaxTurnsHit)** — a review loop hit its cap without converging. The CLI still writes the latest artifact; surface the residual review and ask the user whether to ship it, re-run the stage (`dotrequirements cts edit-loop`), or hand-edit.
-- **Exit code 12 (OverwriteRefused)** — existing `.requirements/` files would be overwritten in non-interactive mode. Offer `--overwrite` or `--skip-existing`.
-- **Exit code 3 (StageFailed)** — a stage errored. Read stderr for details. Offer: resume (re-run the same command — the cache means earlier stages are skipped), restart fresh (`--fresh`), or investigate (read files in `.dotrequirements-cache/`).
-- **Any other non-zero exit** — surface stderr verbatim, then offer the same three options.
+- **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.
 
 ## What you must NOT do
 
-- Don't try to generate requirements yourself; always use the CLI.
-- Don't paraphrase or summarize the CLI's progress lines in ways that change their meaning.
-- Don't claim the pipeline did something it didn't (e.g. don't say "the reviewer approved this" if the verdict was `approved-with-revisions`).
+- 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 suggest editing files inside `.dotrequirements-cache/`; that's internal CLI state.
+- 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.
 
 ## Host portability
 
-This skill makes no assumptions about subagent mechanisms, Task tools, or framework-specific features. Its only host requirements are: Agent Skills format support, a Bash tool (or equivalent shell-out), and `dotrequirements` installed on the user's machine.
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.24.2",
+  "version": "0.24.3",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {