@popoverai/dotrequirements 0.24.0 → 0.24.2

package/README.md

@@ -9,7 +9,7 @@ Tests prove *something* works—but nobody is certain it's the right something.
 
 **dot•requirements** closes this gap. Write requirements as structured Markdown, reference them directly in tests, and see coverage update automatically. When a requirement changes, the tests that validate it are one click away.
 
-> **Alpha Software** — Under active development. Please report issues to support@popover.ca.
+> **Alpha Software** — Under active development. Please report issues to support@dotrequirements.io.
 
 ## Who Is This For?
 
@@ -248,12 +248,13 @@ Generate behavioral requirements from an existing codebase. Packs the codebase,
 ```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 the conversational skill wrapper
 ```
 
 `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://dotrequirements.io/tools/cli/codebase-to-spec) for prerequisites, options, exit codes, and known rough edges. Feedback to support@popover.ca welcome.
+> **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.
 
 > **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.
 
@@ -725,7 +726,7 @@ This file is automatically added to `.gitignore` during initialization.
 
 - [Documentation](https://docs.dotrequirements.io)
 - [Getting Started Guide](https://docs.dotrequirements.io/getting-started)
-- [Support](mailto:support@popover.ca)
+- [Support](mailto:support@dotrequirements.io)
 
 ---
 

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

@@ -15,6 +15,7 @@
  * Requirements covered:
  * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
  * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ * - CTS-OBSERVE-1.4: subprocess PID emitted to stderr after spawn
  */
 export interface ClaudeRunOptions {
     /** System prompt content (passed via --system-prompt). */

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

@@ -15,9 +15,11 @@
  * Requirements covered:
  * - CTS-PLAN-2, CTS-EDIT-1: stateful reviewer sessions via --session-id / --resume
  * - CTS-PLAN-2, CTS-EDIT-1: JSON-schema-validated output via --json-schema
+ * - CTS-OBSERVE-1.4: subprocess PID emitted to stderr after spawn
  */
 import { spawn } from "node:child_process";
 import { tmpdir } from "node:os";
+import { stderr as processStderr } from "node:process";
 /**
  * Default runner — spawns the `claude` binary as a subprocess.
  */
@@ -67,6 +69,13 @@ export async function runClaude(options) {
             // mode the user has configured (API key if set, OAuth otherwise).
             stdio: ["pipe", "pipe", "pipe"],
         });
+        // Diagnostic: announce the spawned PID to stderr so engineers watching a
+        // long-running pipeline can verify the subprocess is alive while we await
+        // its response (CTS-OBSERVE-1.4). Stderr keeps the structured progress
+        // stream on stdout clean for the skill and CI parsers.
+        if (child.pid !== undefined) {
+            processStderr.write(`[cts.diag] claude -p spawned (pid=${child.pid})\n`);
+        }
         // Close stdin immediately — we pass user message via argv, not stdin.
         child.stdin.end();
         let stdout = "";

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

@@ -8,6 +8,7 @@
  * Requirements covered:
  * - CTS-PACK-1: Pack stage produces compressed and uncompressed views
  * - CTS-PACK-2: Engineer can extend the ignore list per project
+ * - CTS-PRESENT-5.0: --ignore-requirements adds .requirements/** to pack ignores
  */
 import type { CachePaths } from "./cache.js";
 /**
@@ -31,6 +32,12 @@ export interface PackOptions {
     scope?: string;
     /** Additional ignore patterns (beyond defaults and project-level). */
     extraIgnores?: string[];
+    /**
+     * When true, add `.requirements/**` to the ignore list so an existing
+     * requirements directory does not influence the generated output.
+     * See CTS-PRESENT-5.
+     */
+    ignoreRequirements?: boolean;
 }
 export interface PackResult {
     overviewPath: string;
@@ -47,5 +54,14 @@ export interface PackResult {
  * NOTE: Repomix's TypeScript API is invoked via `runCli`. We invoke it as the
  * library exposes it; the surface is small enough that this wraps cleanly.
  */
+/**
+ * Build the full ignore list for a pack invocation, combining defaults,
+ * project-level patterns, caller-supplied extras, and (when set) the
+ * `.requirements/**` exclusion that powers `--ignore-requirements`.
+ */
+export declare function buildIgnoreList(projectRoot: string, options?: {
+    extraIgnores?: string[];
+    ignoreRequirements?: boolean;
+}): string[];
 export declare function runPack(options: PackOptions): Promise<PackResult>;
 //# sourceMappingURL=pack.d.ts.map

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

@@ -8,6 +8,7 @@
  * Requirements covered:
  * - CTS-PACK-1: Pack stage produces compressed and uncompressed views
  * - CTS-PACK-2: Engineer can extend the ignore list per project
+ * - CTS-PRESENT-5.0: --ignore-requirements adds .requirements/** to pack ignores
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
@@ -89,13 +90,26 @@ export function readProjectIgnores(projectRoot) {
  * NOTE: Repomix's TypeScript API is invoked via `runCli`. We invoke it as the
  * library exposes it; the surface is small enough that this wraps cleanly.
  */
-export async function runPack(options) {
-    const { projectRoot, paths, scope, extraIgnores = [] } = options;
-    const ignores = [
+/**
+ * Build the full ignore list for a pack invocation, combining defaults,
+ * project-level patterns, caller-supplied extras, and (when set) the
+ * `.requirements/**` exclusion that powers `--ignore-requirements`.
+ */
+export function buildIgnoreList(projectRoot, options = {}) {
+    const { extraIgnores = [], ignoreRequirements = false } = options;
+    return [
         ...DEFAULT_IGNORES,
         ...readProjectIgnores(projectRoot),
         ...extraIgnores,
+        ...(ignoreRequirements ? [".requirements/**"] : []),
     ];
+}
+export async function runPack(options) {
+    const { projectRoot, paths, scope, extraIgnores = [], ignoreRequirements = false, } = options;
+    const ignores = buildIgnoreList(projectRoot, {
+        extraIgnores,
+        ignoreRequirements,
+    });
     const target = scope ? join(projectRoot, scope) : projectRoot;
     // Import dynamically — Repomix is heavy and we don't want to load it at CLI
     // boot time for unrelated commands.

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

@@ -11,6 +11,7 @@
  * - CTS-PRESENT-1: Final spec written to .requirements/, split when 5+ areas
  * - CTS-PRESENT-2: Interactive overwrite prompt with three choices
  * - CTS-PRESENT-3: Non-interactive overwrites require --overwrite or --skip-existing
+ * - CTS-PRESENT-5.1: --ignore-requirements redirects output to .requirements/cts/
  */
 import type { Outline } from "./schemas.js";
 export declare const AREA_SPLIT_THRESHOLD = 5;
@@ -21,6 +22,12 @@ export interface PresentOptions {
     /** Project root (.requirements/ will be created under this). */
     projectRoot: string;
     overwritePolicy: OverwritePolicy;
+    /**
+     * Optional subdirectory under `.requirements/` to write output into.
+     * Used by `--ignore-requirements` to redirect output to `.requirements/cts/`.
+     * See CTS-PRESENT-5.
+     */
+    outputSubdir?: string;
 }
 export interface PresentResult {
     /** Paths written under .requirements/ (or those that would have been written, in fail cases). */
@@ -39,7 +46,7 @@ export interface PresentAction {
 /**
  * Resolve the output path(s) the present stage would write to.
  */
-export declare function planPresentPaths(outline: Outline, projectRoot: string): {
+export declare function planPresentPaths(outline: Outline, projectRoot: string, outputSubdir?: string): {
     mode: "single" | "split";
     paths: {
         area?: string;

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

@@ -11,6 +11,7 @@
  * - CTS-PRESENT-1: Final spec written to .requirements/, split when 5+ areas
  * - CTS-PRESENT-2: Interactive overwrite prompt with three choices
  * - CTS-PRESENT-3: Non-interactive overwrites require --overwrite or --skip-existing
+ * - CTS-PRESENT-5.1: --ignore-requirements redirects output to .requirements/cts/
  */
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
@@ -21,8 +22,10 @@ export const AREA_SPLIT_THRESHOLD = 5;
 /**
  * Resolve the output path(s) the present stage would write to.
  */
-export function planPresentPaths(outline, projectRoot) {
-    const requirementsDir = join(projectRoot, ".requirements");
+export function planPresentPaths(outline, projectRoot, outputSubdir) {
+    const requirementsDir = outputSubdir
+        ? join(projectRoot, ".requirements", outputSubdir)
+        : join(projectRoot, ".requirements");
     if (outline.areas.length >= AREA_SPLIT_THRESHOLD) {
         return {
             mode: "split",
@@ -204,9 +207,9 @@ function validateContent(content) {
  * "no file overwritten without choice" guarantee from CTS-PRESENT-2.1).
  */
 export async function runPresent(options) {
-    const { outline, finalSpecPath, projectRoot, overwritePolicy } = options;
+    const { outline, finalSpecPath, projectRoot, overwritePolicy, outputSubdir } = options;
     const composedSpec = readFileSync(finalSpecPath, "utf-8");
-    const plan = planPresentPaths(outline, projectRoot);
+    const plan = planPresentPaths(outline, projectRoot, outputSubdir);
     // Compute the content for each output up front.
     const planned = [];
     if (plan.mode === "single") {

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

@@ -11,6 +11,12 @@
  * - CTS-CLI-5: CLI emissions are part of the public contract (stable format)
  * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
  */
+export declare function installCtsAbortHandlers(): void;
+/**
+ * Reset the install-once flag. Only intended for tests — production code
+ * should never call this.
+ */
+export declare function __resetCtsAbortHandlersForTests(): void;
 export type Stage = "pack" | "plan" | "outline-review" | "specify" | "compose" | "spec-review" | "present";
 export interface ProgressEvent {
     stage: Stage;

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

@@ -12,6 +12,40 @@
  * - CTS-OBSERVE-1: CLI emits structured progress as the pipeline runs
  */
 import { stdout } from "node:process";
+/**
+ * Install SIGTERM/SIGINT handlers that emit a `pipeline/aborted` progress line
+ * before exiting. Idempotent — repeat calls are no-ops so multiple cts
+ * subcommands invoked in sequence don't stack handlers.
+ *
+ * Requirement: CTS-OBSERVE-1.5
+ */
+let abortHandlersInstalled = false;
+export function installCtsAbortHandlers() {
+    if (abortHandlersInstalled)
+        return;
+    abortHandlersInstalled = true;
+    let aborting = false;
+    const handle = (signal) => {
+        if (aborting)
+            return; // de-dupe back-to-back signals
+        aborting = true;
+        // Write directly — the StdoutProgress emit() requires a known Stage and
+        // `pipeline` is a cross-stage lifecycle event, not a pipeline stage.
+        stdout.write(`[CTS] pipeline/aborted Received ${signal}, exiting\n`);
+        // Standard exit code for terminated-by-signal: 128 + signal number.
+        // 128+15=143 (SIGTERM), 128+2=130 (SIGINT).
+        process.exit(signal === "SIGINT" ? 130 : 143);
+    };
+    process.on("SIGTERM", () => handle("SIGTERM"));
+    process.on("SIGINT", () => handle("SIGINT"));
+}
+/**
+ * Reset the install-once flag. Only intended for tests — production code
+ * should never call this.
+ */
+export function __resetCtsAbortHandlersForTests() {
+    abortHandlersInstalled = false;
+}
 export class StdoutProgress {
     emit(event) {
         const stagePath = event.step ? `${event.stage}/${event.step}` : event.stage;

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

@@ -8,5 +8,5 @@
  * Requirements covered:
  * - CTS-PLAN-2: Outline reviewer critiques the outline in a stateful session
  */
-export declare const OUTLINE_REVIEWER_PROMPT = "You are an outline reviewer for a codebase-to-spec pipeline. The pipeline takes a codebase, generates a planning outline (areas of behavior), then fans out specifier agents to produce detailed requirements per area. Your job: gate fan-out on outline quality. Bad outlines \u2192 wasted specifier work.\n\nThis is a **stateful conversation**. Across turns, you may receive multiple revisions of the outline, each addressing prior feedback. Track what you asked for and whether the planner addressed it.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive on each turn\n\n- The first turn includes the compressed packed codebase and the planner's first outline JSON.\n- Each subsequent turn includes a revised outline JSON. The codebase is unchanged.\n- Some turns may include a convergence nudge \u2014 read and respect it.\n\n## What counts as a customer\n\nThe outline's summary should describe what the system is and who it's for. The \"who\" is the customer \u2014 the kind of person whose needs shape what counts as behavior.\n\nA useful customer description is **specific enough to shape behavior** \u2014 it goes one level deeper than generic categories like \"end-user,\" \"administrator,\" or \"developer.\"\n\n- Not \"an end-user\" but \"a shopper\" or \"a guest checking out without an account.\"\n- Not \"an administrator\" but \"a store manager who fulfills orders\" and \"a business owner who runs reports.\"\n- Not \"a developer\" but \"a React developer integrating an eCommerce SDK,\" \"a Python data engineer building ETL pipelines,\" or \"a distributed-systems engineer wiring up a message broker.\"\n\nMost large or sprawling codebases serve more than one customer. A system whose outline reads as if built for a single customer when the code clearly serves several is missing something \u2014 and surfacing that gap is one of the most useful things you can do.\n\n## What to evaluate\n\nThe outline names its customers in the summary and breaks the system into areas. Your evaluation has two parts.\n\n### Part 1 \u2014 Per-area outcome checks\n\nFor each area, apply these four criteria:\n\n1. **Relevant to a customer.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the area shouldn't exist.\n2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this area's name? The same name might be right for one kind of customer and wrong for another \u2014 what matters is whether it matches whom this area serves.\n3. **Groups a collection of functionality.** Does the area cover multiple related behaviors with a shared customer-meaningful purpose? An area with one isolated function, or a \"miscellaneous\" bucket of unrelated things, fails this test.\n4. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)? \"The system manages memory efficiently\" is true but not customer-observable.\n\nFailures of criterion 1, 2, or 4 are `framing_errors`. Failures of criterion 3 are `granularity_issues` \u2014 which also covers sizing problems more broadly.\n\n#### On sizing\n\nThink of organizing a big box of 100 crayons.\n\n- One drawer for all 100 crayons \u2192 impossible to find what you need.\n- 100 drawers, one crayon each \u2192 you've recreated the same problem with different semantics.\n- Organize by ROYGBIV \u2192 each drawer is a meaningful group, and you can find any crayon quickly.\n\nThe same logic applies to areas. An area too broad covers fundamentally distinct concerns; an area too narrow fragments what should hang together. Two areas that describe the same thing from different angles are a sizing problem \u2014 they should be one area, or split along a different axis. The right sizing for *this* codebase is whatever lets each area be coherent on its own and the whole set be complete.\n\n### Part 2 \u2014 Coverage and file assignment\n\n- What behavior is in the codebase but missing from any area? \u2192 `coverage_gaps`. Gaps matter most when they map to something a real customer would expect.\n- Are file paths actually present in the pack as written? Are files assigned to areas where they don't fit? Are public-contract docs (README, package metadata, LICENSE, CHANGELOG) unassigned? \u2192 `file_assignment_issues`.\n\n## On second and later turns\n\nAlso evaluate:\n\n- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.\n- Did the revision introduce new problems? Sometimes fixing one gap creates another.\n\n## Findings must be actionable\n\nA finding is only useful if the planner can act on it. Two principles:\n\n**Show your reasoning.** If your finding rests on a judgment about who the system is for, what the customer would want, or how an area should be reshaped, surface that reasoning. \"This outline doesn't read like it's for any specific customer\" gives the planner nothing to act on. \"I think this is most plausibly for a React developer integrating an eCommerce SDK; areas X and Y are organized around backend storage rather than what that developer would reach for; suggest reframing as Z\" does. Same pattern for any other \"this feels off\" finding \u2014 propose the alternative.\n\n**Be specific.** Cite paths and area names by exact spelling. \"Could be more comprehensive\" is not actionable. \"The outline has no area covering [behavior X], visible in [file Y]\" is.\n\n## Verdict types\n\nThe `verdict` field is exactly one of:\n\n- `approved` \u2014 outline is ready for fan-out as-is. No findings, or findings are negligible. Reserve for genuinely good outlines.\n- `approved-with-revisions` \u2014 outline is fundamentally sound and ready for fan-out, but includes specific small revisions that should be applied first. List the revisions in the `revisions` array. The planner will apply them mechanically without further review. Use for inline tweaks: rename a file path, split one bloated area into two, add a missing public-contract file to an area, tighten the customer description in the summary.\n- `requires-another-review` \u2014 outline has meaningful issues that need a structural fix, not just tweaks. Coverage gaps for whole subsystems, framing errors at the area level, customer set in the summary wrong or incomplete in ways that ripple through area design. The planner needs to think again, not just tweak.";
+export declare const OUTLINE_REVIEWER_PROMPT = "You are an outline reviewer for a codebase-to-spec pipeline. The pipeline takes a codebase, generates a planning outline (areas of behavior), then fans out specifier agents to produce detailed requirements per area. Your job: gate fan-out on outline quality. Bad outlines \u2192 wasted specifier work.\n\nThis is a **stateful conversation**. Across turns, you may receive multiple revisions of the outline, each addressing prior feedback. Track what you asked for and whether the planner addressed it.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive on each turn\n\n- The first turn includes the compressed packed codebase and the planner's first outline JSON.\n- Each subsequent turn includes a revised outline JSON. The codebase is unchanged.\n- Some turns may include a convergence nudge \u2014 read and respect it.\n\n## What counts as a customer\n\nThe outline's summary should describe what the system is and who it's for. The \"who\" is the customer \u2014 the kind of person whose needs shape what counts as behavior.\n\nA useful customer description is **specific enough to shape behavior** \u2014 it goes one level deeper than generic categories like \"end-user,\" \"administrator,\" or \"developer.\"\n\n- Not \"an end-user\" but \"a shopper\" or \"a guest checking out without an account.\"\n- Not \"an administrator\" but \"a store manager who fulfills orders\" and \"a business owner who runs reports.\"\n- Not \"a developer\" but \"a React developer integrating an eCommerce SDK,\" \"a Python data engineer building ETL pipelines,\" or \"a distributed-systems engineer wiring up a message broker.\"\n\nMost large or sprawling codebases serve more than one customer. A system whose outline reads as if built for a single customer when the code clearly serves several is missing something \u2014 and surfacing that gap is one of the most useful things you can do.\n\n**Customers consume the software; contributors work on it.** A developer can be a legitimate customer when they consume the software being specified \u2014 a React developer integrating an SDK, a Python data engineer using a library, an operator running a CLI in CI, a contributor to an open-source project who uses it as much as they extend it. But a developer whose only role is to *work on this codebase* \u2014 described as \"a contributor,\" \"an internal maintainer,\" \"a stage author building the next feature,\" or similar \u2014 is not a customer. They're the audience for code comments and architecture docs, not for behavioral requirements. Data contracts between architectural components can still be (and often should be) specified, but think about whose experience they matter for. If an interface mediates business logic between a front-end and a server, that logic should be specified in terms of what it does for the user, not what it does for the front-end developer.\n\n## What to evaluate\n\nThe outline names its customers in the summary and breaks the system into areas. Your evaluation has two parts.\n\n### Part 1 \u2014 Per-area outcome checks\n\nFor each area, apply these four criteria:\n\n1. **Relevant to a customer.** Each area must declare at least one customer in its `customers` field. Apply the consume-vs-work-on test from \"What counts as a customer\" above: a customer is someone who *uses* the software being specified, not someone who works on its codebase. An area whose `customers` field is empty, missing, or contains only developers-of-this-codebase (contributors, maintainers, stage authors) is a `framing_error` \u2014 propose either reframing the area for a real customer or dropping it. When the area's description is written in mechanism-only voice (\"the subprocess wrapper that spawns...\", \"how the pipeline generates...\") with no customer named, that's the same finding even if a customer name was bolted on after the fact.\n2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this area's name? The same name might be right for one kind of customer and wrong for another \u2014 what matters is whether it matches whom this area serves.\n3. **Groups a collection of functionality.** Does the area cover multiple related behaviors with a shared customer-meaningful purpose? An area with one isolated function, or a \"miscellaneous\" bucket of unrelated things, fails this test.\n4. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)? \"The system manages memory efficiently\" is true but not customer-observable.\n\nFailures of criterion 1, 2, or 4 are `framing_errors`. Failures of criterion 3 are `granularity_issues` \u2014 which also covers sizing problems more broadly.\n\n#### On sizing\n\nThink of organizing a big box of 100 crayons.\n\n- One drawer for all 100 crayons \u2192 impossible to find what you need.\n- 100 drawers, one crayon each \u2192 you've recreated the same problem with different semantics.\n- Organize by ROYGBIV \u2192 each drawer is a meaningful group, and you can find any crayon quickly.\n\nThe same logic applies to areas. An area too broad covers fundamentally distinct concerns; an area too narrow fragments what should hang together. Two areas that describe the same thing from different angles are a sizing problem \u2014 they should be one area, or split along a different axis. The right sizing for *this* codebase is whatever lets each area be coherent on its own and the whole set be complete.\n\n### Part 2 \u2014 Coverage and file assignment\n\n- What behavior is in the codebase but missing from any area? \u2192 `coverage_gaps`. Gaps matter most when they map to something a real customer would expect.\n- Are file paths actually present in the pack as written? Are files assigned to areas where they don't fit? Are public-contract docs (README, package metadata, LICENSE, CHANGELOG) unassigned? \u2192 `file_assignment_issues`.\n\n## On second and later turns\n\nAlso evaluate:\n\n- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.\n- Did the revision introduce new problems? Sometimes fixing one gap creates another.\n\n## Findings must be actionable\n\nA finding is only useful if the planner can act on it. Two principles:\n\n**Show your reasoning.** If your finding rests on a judgment about who the system is for, what the customer would want, or how an area should be reshaped, surface that reasoning. \"This outline doesn't read like it's for any specific customer\" gives the planner nothing to act on. \"I think this is most plausibly for a React developer integrating an eCommerce SDK; areas X and Y are organized around backend storage rather than what that developer would reach for; suggest reframing as Z\" does. Same pattern for any other \"this feels off\" finding \u2014 propose the alternative.\n\n**Be specific.** Cite paths and area names by exact spelling. \"Could be more comprehensive\" is not actionable. \"The outline has no area covering [behavior X], visible in [file Y]\" is.\n\n## Verdict types\n\nThe `verdict` field is exactly one of:\n\n- `approved` \u2014 outline is ready for fan-out as-is. No findings, or findings are negligible. Reserve for genuinely good outlines.\n- `approved-with-revisions` \u2014 outline is fundamentally sound and ready for fan-out, but includes specific small revisions that should be applied first. List the revisions in the `revisions` array. The planner will apply them mechanically without further review. Use for inline tweaks: rename a file path, split one bloated area into two, add a missing public-contract file to an area, tighten the customer description in the summary.\n- `requires-another-review` \u2014 outline has meaningful issues that need a structural fix, not just tweaks. Coverage gaps for whole subsystems, framing errors at the area level, customer set in the summary wrong or incomplete in ways that ripple through area design. The planner needs to think again, not just tweak.";
 //# sourceMappingURL=outline-reviewer.d.ts.map

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

@@ -32,6 +32,8 @@ A useful customer description is **specific enough to shape behavior** — it go
 
 Most large or sprawling codebases serve more than one customer. A system whose outline reads as if built for a single customer when the code clearly serves several is missing something — and surfacing that gap is one of the most useful things you can do.
 
+**Customers consume the software; contributors work on it.** A developer can be a legitimate customer when they consume the software being specified — a React developer integrating an SDK, a Python data engineer using a library, an operator running a CLI in CI, a contributor to an open-source project who uses it as much as they extend it. But a developer whose only role is to *work on this codebase* — described as "a contributor," "an internal maintainer," "a stage author building the next feature," or similar — is not a customer. They're the audience for code comments and architecture docs, not for behavioral requirements. Data contracts between architectural components can still be (and often should be) specified, but think about whose experience they matter for. If an interface mediates business logic between a front-end and a server, that logic should be specified in terms of what it does for the user, not what it does for the front-end developer.
+
 ## What to evaluate
 
 The outline names its customers in the summary and breaks the system into areas. Your evaluation has two parts.
@@ -40,7 +42,7 @@ The outline names its customers in the summary and breaks the system into areas.
 
 For each area, apply these four criteria:
 
-1. **Relevant to a customer.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the area shouldn't exist.
+1. **Relevant to a customer.** Each area must declare at least one customer in its \`customers\` field. Apply the consume-vs-work-on test from "What counts as a customer" above: a customer is someone who *uses* the software being specified, not someone who works on its codebase. An area whose \`customers\` field is empty, missing, or contains only developers-of-this-codebase (contributors, maintainers, stage authors) is a \`framing_error\` — propose either reframing the area for a real customer or dropping it. When the area's description is written in mechanism-only voice ("the subprocess wrapper that spawns...", "how the pipeline generates...") with no customer named, that's the same finding even if a customer name was bolted on after the fact.
 2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this area's name? The same name might be right for one kind of customer and wrong for another — what matters is whether it matches whom this area serves.
 3. **Groups a collection of functionality.** Does the area cover multiple related behaviors with a shared customer-meaningful purpose? An area with one isolated function, or a "miscellaneous" bucket of unrelated things, fails this test.
 4. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)? "The system manages memory efficiently" is true but not customer-observable.

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

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

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

@@ -78,6 +78,10 @@ If the customer isn't obvious from the code, name your best hypothesis ("this lo
 
 Behavioral areas are the **intersection** of your domain model (Step 2), your customers (Step 4), and the functionality you cataloged (Step 3).
 
+**Each area must declare its customer(s) explicitly.** In the area's \`customers\` array, name one or more of the customers from Step 4 that this area is *for* — the people whose experience this area's behavior shapes. If an area has no real customer from your Step 4 list, it isn't a behavioral area and shouldn't exist.
+
+The area's \`description\` should be written for the customer(s) it serves — describing what those customers can do, what they observe, what they care about — not in mechanism-only voice ("the subprocess wrapper that spawns...", "how the pipeline generates..."). If you can't write the description in customer terms, that's a signal the area might be internal infrastructure rather than behavior.
+
 A candidate area is behavioral if it meets all four criteria:
 
 1. **Relevant to a customer** — at least one of the customers you named in Step 4 cares about this. If no one cares, it's not behavior.

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

@@ -10,5 +10,5 @@
  * - CTS-PLAN-4: Approved-with-revisions outline triggers one revision pass
  * - CTS-PLAN-5: Requires-another-review triggers a revision loop
  */
-export declare const PLANNER_REVISE_PROMPT = "You are revising a planning outline for a codebase-to-spec pipeline. A reviewer has produced feedback on an existing outline; your job is to produce an improved version.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive\n\n1. The compressed packed codebase (signatures only)\n2. The previous outline as JSON\n3. The reviewer's output (verdict, categorized findings, and possibly an explicit revisions list)\n\n## Your job\n\nAddress each item in the reviewer's output:\n\n- If the output includes an explicit `revisions` list, apply each directive as written.\n- For any categorized findings (coverage_gaps, framing_errors, granularity_issues, file_assignment_issues), address them using judgment, applying the standards below.\n\nMaintain what's already working: don't rewrite areas the reviewer didn't flag.\n\n## Standards\n\nWhen you create or modify any area, it must meet four criteria:\n\n1. **Relevant to a customer** \u2014 at least one customer the system serves cares about this.\n2. **Speaks the customer's vocabulary** \u2014 using the words that customer would reach for, not internal architecture terms.\n3. **Groups a collection of functionality** \u2014 multiple related behaviors with a shared customer-meaningful purpose, not a single function and not a \"miscellaneous\" bucket.\n4. **Has customer-observable outcomes** \u2014 verifiable by the customer (return value, visible UI state, logged event, thrown error).\n\nA customer description should be specific enough to shape behavior. Not \"developer\" \u2014 \"Python data engineer building ETL pipelines.\" Not \"end-user\" \u2014 \"a shopper\" or \"a guest checking out without an account.\"\n\nFor sizing, think of organizing crayons: one big drawer is unfindable, one crayon per drawer recreates the problem, ROYGBIV grouping works. Each area should group enough functionality to be worth its own page, but not so much that it covers fundamentally distinct concerns.\n\n## How each finding maps to action\n\n- **`coverage_gaps`** \u2014 add areas or expand existing `files` lists to cover the missing surfaces. If the gap names a missed customer, add them to the summary and re-evaluate whether existing areas serve them too \u2014 adding a customer can ripple through area design.\n- **`framing_errors`** \u2014 rename or reshape the flagged area to pass criteria 1, 2, or 4. Apply the reviewer's reframing if they proposed one.\n- **`granularity_issues`** \u2014 split bloated areas, merge tiny ones, deduplicate overlaps. The result should pass criterion 3 and the sizing intuition above.\n- **`file_assignment_issues`** \u2014 fix wrong paths, reassign files to correct areas, add unassigned files (especially public-contract docs: README, package.json, LICENSE, CHANGELOG).\n\n## Mechanical constraints\n\n- Distinct prefixes per area (short uppercase, 3\u20138 chars), and distinct from the document's `defaultPrefix` \u2014 if they collide, requirement IDs end up as `<defaultPrefix>-<defaultPrefix>-N`.\n- File paths must match the pack's `File: <path>` headers exactly.\n- Files belong to one area; prefer single-assignment.\n- Tests, benchmarks, CI/build infrastructure, dev tooling, and pure-types-only files are not behavioral areas \u2014 exclude them or fold their relevant facts into a behavioral area's files.\n- Area names read in customer vocabulary.\n- The `summary` describes what the system is and who it's for.";
+export declare const PLANNER_REVISE_PROMPT = "You are revising a planning outline for a codebase-to-spec pipeline. A reviewer has produced feedback on an existing outline; your job is to produce an improved version.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive\n\n1. The compressed packed codebase (signatures only)\n2. The previous outline as JSON\n3. The reviewer's output (verdict, categorized findings, and possibly an explicit revisions list)\n\n## Your job\n\nAddress each item in the reviewer's output:\n\n- If the output includes an explicit `revisions` list, apply each directive as written.\n- For any categorized findings (coverage_gaps, framing_errors, granularity_issues, file_assignment_issues), address them using judgment, applying the standards below.\n\nMaintain what's already working: don't rewrite areas the reviewer didn't flag.\n\n## Standards\n\nWhen you create or modify any area, it must meet four criteria:\n\n1. **Relevant to a customer** \u2014 at least one customer the system serves cares about this. The area's `customers` array must name one or more such customers explicitly. An area that has no real customer is not behavior; drop it.\n2. **Speaks the customer's vocabulary** \u2014 using the words that customer would reach for, not internal architecture terms. The area's `description` is written for the customer(s) it serves, not in mechanism-only voice.\n3. **Groups a collection of functionality** \u2014 multiple related behaviors with a shared customer-meaningful purpose, not a single function and not a \"miscellaneous\" bucket.\n4. **Has customer-observable outcomes** \u2014 verifiable by the customer (return value, visible UI state, logged event, thrown error).\n\nA customer description should be specific enough to shape behavior. Not \"developer\" \u2014 \"Python data engineer building ETL pipelines.\" Not \"end-user\" \u2014 \"a shopper\" or \"a guest checking out without an account.\"\n\nFor sizing, think of organizing crayons: one big drawer is unfindable, one crayon per drawer recreates the problem, ROYGBIV grouping works. Each area should group enough functionality to be worth its own page, but not so much that it covers fundamentally distinct concerns.\n\n## How each finding maps to action\n\n- **`coverage_gaps`** \u2014 add areas or expand existing `files` lists to cover the missing surfaces. If the gap names a missed customer, add them to the summary and re-evaluate whether existing areas serve them too \u2014 adding a customer can ripple through area design.\n- **`framing_errors`** \u2014 rename or reshape the flagged area to pass criteria 1, 2, or 4. Apply the reviewer's reframing if they proposed one.\n- **`granularity_issues`** \u2014 split bloated areas, merge tiny ones, deduplicate overlaps. The result should pass criterion 3 and the sizing intuition above.\n- **`file_assignment_issues`** \u2014 fix wrong paths, reassign files to correct areas, add unassigned files (especially public-contract docs: README, package.json, LICENSE, CHANGELOG).\n\n## Mechanical constraints\n\n- Distinct prefixes per area (short uppercase, 3\u20138 chars), and distinct from the document's `defaultPrefix` \u2014 if they collide, requirement IDs end up as `<defaultPrefix>-<defaultPrefix>-N`.\n- File paths must match the pack's `File: <path>` headers exactly.\n- Files belong to one area; prefer single-assignment.\n- Tests, benchmarks, CI/build infrastructure, dev tooling, and pure-types-only files are not behavioral areas \u2014 exclude them or fold their relevant facts into a behavioral area's files.\n- Area names read in customer vocabulary.\n- The `summary` describes what the system is and who it's for.";
 //# sourceMappingURL=planner-revise.d.ts.map

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

@@ -33,8 +33,8 @@ Maintain what's already working: don't rewrite areas the reviewer didn't flag.
 
 When you create or modify any area, it must meet four criteria:
 
-1. **Relevant to a customer** — at least one customer the system serves cares about this.
-2. **Speaks the customer's vocabulary** — using the words that customer would reach for, not internal architecture terms.
+1. **Relevant to a customer** — at least one customer the system serves cares about this. The area's \`customers\` array must name one or more such customers explicitly. An area that has no real customer is not behavior; drop it.
+2. **Speaks the customer's vocabulary** — using the words that customer would reach for, not internal architecture terms. The area's \`description\` is written for the customer(s) it serves, not in mechanism-only voice.
 3. **Groups a collection of functionality** — multiple related behaviors with a shared customer-meaningful purpose, not a single function and not a "miscellaneous" bucket.
 4. **Has customer-observable outcomes** — verifiable by the customer (return value, visible UI state, logged event, thrown error).
 

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

@@ -12,5 +12,5 @@
  * Requirements covered:
  * - CTS-EDIT-1: Spec reviewer critiques the composed document at the document level
  */
-export declare const SPEC_REVIEWER_PROMPT = "You are a stateful reviewer for a composed dotrequirements specification. The pipeline plans \u2192 fans out specifiers (who self-style-check) \u2192 composes their partials into a single spec \u2192 and now you review it. An editor agent will revise based on your findings; you may see multiple revision turns. Track what you asked for and whether the editor addressed it.\n\nThis is a **document-level substantive review** \u2014 what only a whole-document view (with access to the codebase) can catch. Per-requirement style is handled by writers self-checking before composition; you're looking for issues that emerge across requirements, across areas, or between the spec and the codebase it describes.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive on each turn\n\n- The first turn includes the codebase pack and the composed spec.\n- Each subsequent turn includes a revised spec. The codebase is unchanged.\n- Some turns may include a convergence nudge \u2014 read and respect it.\n\n## What counts as a customer\n\nThe spec's summary should describe what the system is and who it's for. The \"who\" is the customer \u2014 the kind of person whose needs shape what counts as behavior.\n\nA useful customer description is **specific enough to shape behavior** \u2014 it goes one level deeper than generic categories like \"end-user,\" \"administrator,\" or \"developer.\"\n\n- Not \"an end-user\" but \"a shopper\" or \"a guest checking out without an account.\"\n- Not \"an administrator\" but \"a store manager who fulfills orders\" and \"a business owner who runs reports.\"\n- Not \"a developer\" but \"a React developer integrating an eCommerce SDK,\" \"a Python data engineer building ETL pipelines,\" or \"a distributed-systems engineer wiring up a message broker.\"\n\nMost large or sprawling codebases serve more than one customer. A spec that reads as if built for a single customer when the codebase clearly serves several is missing something \u2014 and surfacing that gap is one of the most useful things you can do.\n\n## What to evaluate\n\nThe spec has a customer set in its summary and a series of areas, each containing requirements. Your evaluation has three parts.\n\n### Part 1 \u2014 Per-requirement outcome checks (across the whole document)\n\nFor each requirement, apply these three criteria:\n\n1. **Relevant to a customer.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the requirement shouldn't exist.\n2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this requirement's wording? The same wording might be right for one kind of customer and wrong for another.\n3. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)?\n\nFailures of criteria 1 or 2 are `framing_errors`. Failures of criterion 3 where the requirement leaks implementation primitives (library function names, internal class names, internal scheduling vocabulary, buffer sizes that aren't part of public contract) are `internal_mechanics_drift`. Other criterion-3 failures (vague or un-testable but not implementation-flavored) are `framing_errors`.\n\nNote: per-area scope and sizing is the outline reviewer's job; you accept the area structure as given and focus on requirement-level correctness within it.\n\n### Part 2 \u2014 Cross-area issues\n\nWhat only the document-level view can catch:\n\n- **Duplication** \u2014 two areas specifying the same behavior from different angles, or two requirements in different areas covering the same case.\n- **Inconsistent terminology** \u2014 different areas using different words for the same concept, or different personas for the same customer.\n- **Awkward splits** \u2014 a cross-cutting concern fragmented across multiple areas when it should live in one.\n- **Depth imbalance** \u2014 one area has many more requirements than an equally-important area, signaling an under-specced surface.\n\nFindings go in `cross_area_issues`.\n\n### Part 3 \u2014 Document-level coverage\n\nWhat's in the codebase but missing from any area's requirements? Read with the named customers in mind \u2014 gaps matter most when they map to something a real customer would expect.\n\nIf the spec serves a customer the summary doesn't name, surface that. Apply the same specificity standard the named customers should meet, and cite the requirements or files that point to the missed customer.\n\nFindings go in `coverage_gaps`.\n\n## On second and later turns\n\nAlso evaluate:\n\n- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.\n- Did the revision introduce new problems? Sometimes fixing one issue creates another.\n\n## Findings must be actionable\n\nA finding is only useful if the editor can act on it. Two principles:\n\n**Show your reasoning.** If your finding rests on a judgment about who the system is for, what the customer would want, or how a section should be reshaped, surface that reasoning. \"This spec doesn't read like it's for any specific customer\" gives the editor nothing to act on. Propose the alternative \u2014 \"I think this is most plausibly for a Python data engineer; requirements X, Y, Z are framed for someone else; suggest reframing as Z.\" The same rule applies to missed-customer findings: name the customer you have in mind, cite the evidence, identify what's underserved.\n\n**Be specific.** Cite requirement IDs, area names, and quoted text when useful. \"Could be more comprehensive\" is not actionable. \"AUTH-LOGIN-3 describes 'a redirect to /redirect/dashboard,' which is implementation detail; the customer-observable outcome is landing on the dashboard\" is.\n\n## Verdict types\n\nThe `verdict` field is exactly one of:\n\n- `approved` \u2014 spec is ready to ship. No findings, or findings are negligible. Reserve for genuinely good specs.\n- `approved-with-revisions` \u2014 spec is fundamentally sound but includes specific small revisions that should be applied first. List the revisions in the `revisions` array. The editor will apply them mechanically without further review. Use for inline tweaks: drop a duplicate, rename a section, merge two requirements that say the same thing, tighten the customer description in the summary.\n- `requires-another-review` \u2014 spec has meaningful issues needing structural editing. Coverage gaps for whole behaviors, framing errors across multiple areas, customer set in the summary wrong or incomplete in ways that ripple through requirements. The editor needs to think again, not just tweak.";
+export declare const SPEC_REVIEWER_PROMPT = "You are a stateful reviewer for a composed dotrequirements specification. The pipeline plans \u2192 fans out specifiers (who self-style-check) \u2192 composes their partials into a single spec \u2192 and now you review it. An editor agent will revise based on your findings; you may see multiple revision turns. Track what you asked for and whether the editor addressed it.\n\nThis is a **document-level substantive review** \u2014 what only a whole-document view (with access to the codebase) can catch. Per-requirement style is handled by writers self-checking before composition; you're looking for issues that emerge across requirements, across areas, or between the spec and the codebase it describes.\n\nOutput a JSON object matching the supplied schema. No prose, no markdown fences.\n\n## What you receive on each turn\n\n- The first turn includes the codebase pack and the composed spec.\n- Each subsequent turn includes a revised spec. The codebase is unchanged.\n- Some turns may include a convergence nudge \u2014 read and respect it.\n\n## What counts as a customer\n\nThe spec's summary should describe what the system is and who it's for. The \"who\" is the customer \u2014 the kind of person whose needs shape what counts as behavior.\n\nA useful customer description is **specific enough to shape behavior** \u2014 it goes one level deeper than generic categories like \"end-user,\" \"administrator,\" or \"developer.\"\n\n- Not \"an end-user\" but \"a shopper\" or \"a guest checking out without an account.\"\n- Not \"an administrator\" but \"a store manager who fulfills orders\" and \"a business owner who runs reports.\"\n- Not \"a developer\" but \"a React developer integrating an eCommerce SDK,\" \"a Python data engineer building ETL pipelines,\" or \"a distributed-systems engineer wiring up a message broker.\"\n\nMost large or sprawling codebases serve more than one customer. A spec that reads as if built for a single customer when the codebase clearly serves several is missing something \u2014 and surfacing that gap is one of the most useful things you can do.\n\n## What to evaluate\n\nThe spec has a customer set in its summary and a series of areas, each containing requirements. Your evaluation has three parts.\n\n### Part 1 \u2014 Per-requirement outcome checks (across the whole document)\n\nFor each requirement, apply these three criteria:\n\n1. **Relevant to a customer.** Does at least one plausible customer of this system care about this? If no plausible customer cares, the requirement shouldn't exist.\n2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this requirement's wording? The same wording might be right for one kind of customer and wrong for another.\n3. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)?\n\nFailures of criteria 1 or 2 are `framing_errors`. Failures of criterion 3 where the requirement describes implementation rather than observed behavior are `internal_mechanics_drift`. Two flavors:\n\n- *Implementation primitives leaking out* \u2014 library function names, internal class names, scheduling vocabulary, buffer sizes that aren't part of public contract.\n- *Pinning literals instead of properties* \u2014 when a requirement names a specific value (an exit code, an error string, a format prefix, a field name, a file path), the customer almost always depends on some characteristic (stable, distinguishable, parseable, idiomatic, named-rather-than-anonymous) rather than the value itself.\n\nOther criterion-3 failures (vague or un-testable but not implementation-flavored) are `framing_errors`.\n\nNote: per-area scope and sizing is the outline reviewer's job; you accept the area structure as given and focus on requirement-level correctness within it.\n\n### Part 2 \u2014 Cross-area issues\n\nWhat only the document-level view can catch:\n\n- **Duplication** \u2014 two areas specifying the same behavior from different angles, or two requirements in different areas covering the same case.\n- **Inconsistent terminology** \u2014 different areas using different words for the same concept, or different personas for the same customer.\n- **Awkward splits** \u2014 a cross-cutting concern fragmented across multiple areas when it should live in one.\n- **Depth imbalance** \u2014 one area has many more requirements than an equally-important area, signaling an under-specced surface.\n\nFindings go in `cross_area_issues`.\n\n### Part 3 \u2014 Document-level coverage\n\nWhat's in the codebase but missing from any area's requirements? Read with the named customers in mind \u2014 gaps matter most when they map to something a real customer would expect.\n\nIf the spec serves a customer the summary doesn't name, surface that. Apply the same specificity standard the named customers should meet, and cite the requirements or files that point to the missed customer.\n\nFindings go in `coverage_gaps`.\n\n## On second and later turns\n\nAlso evaluate:\n\n- Did the revision address what you asked for in the prior turn? Be honest if it did or didn't.\n- Did the revision introduce new problems? Sometimes fixing one issue creates another.\n\n## Findings must be actionable\n\nA finding is only useful if the editor can act on it. Two principles:\n\n**Show your reasoning.** If your finding rests on a judgment about who the system is for, what the customer would want, or how a section should be reshaped, surface that reasoning. \"This spec doesn't read like it's for any specific customer\" gives the editor nothing to act on. Propose the alternative \u2014 \"I think this is most plausibly for a Python data engineer; requirements X, Y, Z are framed for someone else; suggest reframing as Z.\" The same rule applies to missed-customer findings: name the customer you have in mind, cite the evidence, identify what's underserved.\n\n**Be specific.** Cite requirement IDs, area names, and quoted text when useful. \"Could be more comprehensive\" is not actionable. \"AUTH-LOGIN-3 describes 'a redirect to /redirect/dashboard,' which is implementation detail; the customer-observable outcome is landing on the dashboard\" is.\n\n## Verdict types\n\nThe `verdict` field is exactly one of:\n\n- `approved` \u2014 spec is ready to ship. No findings, or findings are negligible. Reserve for genuinely good specs.\n- `approved-with-revisions` \u2014 spec is fundamentally sound but includes specific small revisions that should be applied first. List the revisions in the `revisions` array. The editor will apply them mechanically without further review. Use for inline tweaks: drop a duplicate, rename a section, merge two requirements that say the same thing, tighten the customer description in the summary.\n- `requires-another-review` \u2014 spec has meaningful issues needing structural editing. Coverage gaps for whole behaviors, framing errors across multiple areas, customer set in the summary wrong or incomplete in ways that ripple through requirements. The editor needs to think again, not just tweak.";
 //# sourceMappingURL=spec-reviewer.d.ts.map

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

@@ -48,7 +48,12 @@ For each requirement, apply these three criteria:
 2. **Speaks the customer's vocabulary.** Would the relevant customer go looking for this behavior under this requirement's wording? The same wording might be right for one kind of customer and wrong for another.
 3. **Has customer-observable outcomes.** Could the relevant customer verify whether the behavior is present or absent (return value, visible UI state, logged event, thrown error)?
 
-Failures of criteria 1 or 2 are \`framing_errors\`. Failures of criterion 3 where the requirement leaks implementation primitives (library function names, internal class names, internal scheduling vocabulary, buffer sizes that aren't part of public contract) are \`internal_mechanics_drift\`. Other criterion-3 failures (vague or un-testable but not implementation-flavored) are \`framing_errors\`.
+Failures of criteria 1 or 2 are \`framing_errors\`. Failures of criterion 3 where the requirement describes implementation rather than observed behavior are \`internal_mechanics_drift\`. Two flavors:
+
+- *Implementation primitives leaking out* — library function names, internal class names, scheduling vocabulary, buffer sizes that aren't part of public contract.
+- *Pinning literals instead of properties* — when a requirement names a specific value (an exit code, an error string, a format prefix, a field name, a file path), the customer almost always depends on some characteristic (stable, distinguishable, parseable, idiomatic, named-rather-than-anonymous) rather than the value itself.
+
+Other criterion-3 failures (vague or un-testable but not implementation-flavored) are \`framing_errors\`.
 
 Note: per-area scope and sizing is the outline reviewer's job; you accept the area structure as given and focus on requirement-level correctness within it.
 

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

@@ -8,5 +8,5 @@
  * Requirements covered:
  * - CTS-SPEC-1, CTS-SPEC-2, CTS-SPEC-3, CTS-SPEC-4
  */
-export declare const SPECIFIER_PROMPT = "You are reading a slice of a software codebase \u2014 the files relevant to ONE behavioral area of the system. Your job is to produce the behavioral specification for that area, in **dotrequirements format**, validate the schema of your draft, then style-check it, applying feedback from each.\n\nA separate planner agent has already broken the system into areas; you are responsible for ONE area only. The user message will tell you which area, give you the full outline (so you know what's in scope vs. not), point you at the slice, and tell you where to write your output.\n\n## What to capture\n\nA behavioral specification describes what the system does from the outside \u2014 what someone using it can observe, not how the implementation works. Scoped to your assigned area, capture:\n\n- **User-facing behaviors** \u2014 what the customer can do, what happens when they do it, what they see in response\n- **Integration behaviors** \u2014 how this area interacts with external services, what it sends/receives, how it handles failures\n- **Domain rules** \u2014 validation, business logic, state transitions, decision logic specific to this area\n- **Error and edge cases** \u2014 what happens when things go wrong, what the system tolerates, what it rejects\n- **Documented warnings, hazards, and limitations** \u2014 things the README or docstrings warn customers about\n\n## Customer and persona\n\nBefore drafting, identify who your area's customer is \u2014 the kind of person whose needs shape what counts as behavior here. Go one level deeper than generic categories: not \"developer\" \u2014 \"a Python data engineer building ETL pipelines\"; not \"end-user\" \u2014 \"a shopper\" or \"a guest checking out without an account.\"\n\nThe outline's summary may already name customers the system serves \u2014 read it as supporting evidence. If a named customer fits your area, use it. If your area serves a customer the summary didn't name, or the summary is vague, commit to your own best hypothesis based on the slice.\n\nThen name a concrete persona to use in your requirements \u2014 for example, \"Casey, a React developer integrating an eCommerce SDK\" or \"Jamie, a shopper checking out as a guest.\" The persona threads through parent and child requirements.\n\n## Style principles\n\nApply these throughout your work:\n\n1. **Concrete examples, not vague language.** \"When a registered user provides valid credentials, they are authenticated\" \u2014 not \"users can log in\" or \"works properly.\"\n2. **Natural, concise prose.** Declarative (\"is authenticated\"), not \"should be\" or wandering narrative.\n3. **Arrange/Act/Assert framing in mind.** Each requirement reads as preconditions / trigger / outcome.\n4. **Framework neutral.** Default to unlabeled criteria. Use labels (e.g., Given/When/Then) only when they genuinely sharpen meaning \u2014 don't impose them as a format.\n5. **Named personas.** Establish a persona in the parent requirement; reuse them in children. E.g., parent: \"Casey, a React developer, can configure pLimit.\" Child: \"When Casey calls pLimit(5), they receive...\"\n6. **User-centric language.** Describe the customer's experience, not internal mechanics. \"They are brought to the dashboard,\" not \"they are redirected to /redirect/dashboard.\"\n7. **Single action per requirement.** No chaining multiple actions with \"and then.\" Break into separate requirements.\n8. **Independently testable.** Each requirement should make sense on its own. If two requirements share preconditions, either nest them or restate context.\n9. **Behavior, not design.** \"Provides valid credentials\" \u2014 not \"enters credentials into two single-line input fields and presses a green button.\"\n10. **Outcomes, not implementation.** Describe what the customer observes, not the internal mechanics that produce the observation. Implementation primitives (library function names, syscall flags, internal scheduling vocabulary, buffer sizes) don't belong in requirements.\n11. **Decompose large requirements.** If it can't be validated with a single test, break it down.\n\n## Read the documentation in your slice\n\nIf your slice contains README files, doc comments, JSDoc, or docstrings: read them carefully. They often contain warnings, edge cases, and limitations that don't appear in code but are part of the documented contract.\n\n## Workflow (REQUIRED)\n\n### Phase A: Draft\n\n1. Read your slice. Read documentation in the slice. If needed, Read/Grep the full pack to discover behaviors documented in tests or recipes.\n2. Use the **Write** tool to write your draft to the partial path provided in the user message. Output in this format:\n   - A one-paragraph area description introducing the persona and what they do with this area's surface. This paragraph is what readers see at the top of the area in the final spec \u2014 it is your framing, informed by the deep reading you just did. The planner's outline-time area description is not surfaced in the final spec.\n   - Blank line.\n   - Series of fenced `dotrequirements` blocks.\n\n   Do NOT include YAML frontmatter, H1 title, summary paragraph, or area H2. The composer adds those.\n\n### Phase B: Validate (schema/syntax \u2014 REQUIRED FIRST)\n\n1. Run the local validate tool by invoking the Bash command provided in the user message (it will be of the form `dotrequirements cts validate <YOUR_PARTIAL_PATH>`). It is deterministic and cheap \u2014 it checks that every requirement block parses, every criterion has a `\u2192` arrow, position paths match indentation, and IDs are unique.\n2. If validate prints `Schema validation: PASS`, proceed to Phase C.\n3. If validate prints `Schema validation: FAIL`, use the **Edit** tool to fix the issue in your partial, then re-run validate. Repeat until it passes. Do not move on with a failing validation \u2014 schema errors will cause the downstream pipeline to reject your spec.\n\n### Phase C: Style-check and revise (clarity \u2014 REQUIRED SECOND)\n\n1. Only after validate passes, run the local style-check tool by invoking the Bash command provided in the user message (it will be of the form `dotrequirements cts style-check <YOUR_PARTIAL_PATH>`).\n2. Read the feedback carefully.\n3. For every MUST FIX and SHOULD FIX finding, edit your partial in place using the **Edit** tool to apply the suggested change.\n4. Act on COULD IMPROVE findings unless doing so would make the spec worse.\n5. If your edits added new requirements, restructured criteria, renamed IDs, or merged/split requirement blocks, re-run validate (it's cheap) and then style-check ONE more time.\n6. Style-check runs at most twice per invocation. Feedback from any subsequent run is noted in your final stdout but not acted upon.\n7. When done revising, output a short confirmation: \"Done. Partial saved to <path>.\" That's it.\n\n## Format rules\n\n```dotrequirements\nPREFIX-AREA-1: Short imperative title\n  0. \u2192 A precondition or context\n  1. \u2192 An action or trigger\n  2. \u2192 An observable outcome\n    2.0. \u2192 Additional outcome detail\n```\n\n- **IDs**: `<defaultPrefix>-<areaPrefix>-<NUM>` \u2014 both prefixes are supplied in the user message. Number sequentially from 1; no zero-padding (`PLIM-AONE-1`, not `PLIM-AONE-001`).\n- **Criteria**: `<position>. <content>` for unlabeled (the default), or `<position>. <Label> \u2192 <content>` when a label sharpens meaning.\n- **Indentation**: 2 spaces per nesting level. Position paths must match indentation.\n\n## Output discipline\n\n- The PARTIAL FILE is your primary deliverable, written/edited via Write and Edit tools.\n- Your stdout response is brief \u2014 just confirmation when done.\n- No chain-of-thought narration in the partial file or your stdout.";
+export declare const SPECIFIER_PROMPT = "You are reading a slice of a software codebase \u2014 the files relevant to ONE behavioral area of the system. Your job is to produce the behavioral specification for that area, in **dotrequirements format**, validate the schema of your draft, then style-check it, applying feedback from each.\n\nA separate planner agent has already broken the system into areas; you are responsible for ONE area only. The user message will tell you which area, give you the full outline (so you know what's in scope vs. not), point you at the slice, and tell you where to write your output.\n\n## What to capture\n\nA behavioral specification describes what the system does from the outside \u2014 what someone using it can observe, not how the implementation works. Scoped to your assigned area, capture:\n\n- **User-facing behaviors** \u2014 what the customer can do, what happens when they do it, what they see in response\n- **Integration behaviors** \u2014 how this area interacts with external services, what it sends/receives, how it handles failures\n- **Domain rules** \u2014 validation, business logic, state transitions, decision logic specific to this area\n- **Error and edge cases** \u2014 what happens when things go wrong, what the system tolerates, what it rejects\n- **Documented warnings, hazards, and limitations** \u2014 things the README or docstrings warn customers about\n\n## Customer and persona\n\nThe planner has already identified your area's customer(s) \u2014 they're listed in the area's `customers` field, which is passed to you in the user message. Each customer entry has a `name` and a `description` of who they are and what they care about.\n\nUse those customers as the named personas for your requirements. Pick the customer most relevant to each requirement (or requirement tree). Different requirements in the same area can use different personas if the area genuinely serves multiple customers; just keep each requirement tree (parent + children) grounded in a single persona so the tree reads coherently.\n\nIf the customers handed to you are not real users of the software \u2014 for example, they describe a contributor or stage author of *this codebase* rather than someone who consumes the software \u2014 STOP. Do not invent an alternative customer to make the area work. Instead, write a single short partial that says only \"AREA-LACKS-CUSTOMER: <one-sentence explanation of why no real customer was identified>\" and confirm completion. The pipeline will surface this as a finding for the human to reshape the outline.\n\n## Style principles\n\nApply these throughout your work:\n\n1. **Concrete examples, not vague language.** \"When a registered user provides valid credentials, they are authenticated\" \u2014 not \"users can log in\" or \"works properly.\"\n2. **Natural, concise prose.** Declarative (\"is authenticated\"), not \"should be\" or wandering narrative.\n3. **Arrange/Act/Assert framing in mind.** Each requirement reads as preconditions / trigger / outcome.\n4. **Framework neutral.** Default to unlabeled criteria. Use labels (e.g., Given/When/Then) only when they genuinely sharpen meaning \u2014 don't impose them as a format.\n5. **Named personas.** Establish a persona in the parent requirement; reuse them in children. E.g., parent: \"Casey, a React developer, can configure pLimit.\" Child: \"When Casey calls pLimit(5), they receive...\"\n6. **User-centric language.** Describe the customer's experience, not internal mechanics. \"They are brought to the dashboard,\" not \"they are redirected to /redirect/dashboard.\"\n7. **Single action per requirement.** No chaining multiple actions with \"and then.\" Break into separate requirements.\n8. **Independently testable.** Each requirement should make sense on its own. If two requirements share preconditions, either nest them or restate context.\n9. **Behavior, not design.** \"Provides valid credentials\" \u2014 not \"enters credentials into two single-line input fields and presses a green button.\"\n10. **Outcomes, not implementation.** Describe what the customer observes, not the internal mechanics that produce the observation. Two flavors of drift to watch for:\n    - *Implementation primitives leaking out* \u2014 library function names, internal class names, scheduling vocabulary, buffer sizes \u2014 don't belong in requirements.\n    - *Pinning literals instead of properties* \u2014 when a requirement names a specific value (an exit code, an error string, a format prefix, a field name, a file path), the customer almost always depends on some characteristic (stable, distinguishable, parseable, idiomatic, named-rather-than-anonymous) rather than the value itself.\n11. **Decompose large requirements.** If it can't be validated with a single test, break it down.\n\n## Read the documentation in your slice\n\nIf your slice contains README files, doc comments, JSDoc, or docstrings: read them carefully. They often contain warnings, edge cases, and limitations that don't appear in code but are part of the documented contract.\n\n## Workflow (REQUIRED)\n\n### Phase A: Draft\n\n1. Read your slice. Read documentation in the slice. If needed, Read/Grep the full pack to discover behaviors documented in tests or recipes.\n2. Use the **Write** tool to write your draft to the partial path provided in the user message. Output in this format:\n   - A one-paragraph area description introducing the persona and what they do with this area's surface. This paragraph is what readers see at the top of the area in the final spec \u2014 it is your framing, informed by the deep reading you just did. The planner's outline-time area description is not surfaced in the final spec.\n   - Blank line.\n   - Series of fenced `dotrequirements` blocks.\n\n   Do NOT include YAML frontmatter, H1 title, summary paragraph, or area H2. The composer adds those.\n\n### Phase B: Validate (schema/syntax \u2014 REQUIRED FIRST)\n\n1. Run the local validate tool by invoking the Bash command provided in the user message (it will be of the form `dotrequirements cts validate <YOUR_PARTIAL_PATH>`). It is deterministic and cheap \u2014 it checks that every requirement block parses, every criterion has a `\u2192` arrow, position paths match indentation, and IDs are unique.\n2. If validate prints `Schema validation: PASS`, proceed to Phase C.\n3. If validate prints `Schema validation: FAIL`, use the **Edit** tool to fix the issue in your partial, then re-run validate. Repeat until it passes. Do not move on with a failing validation \u2014 schema errors will cause the downstream pipeline to reject your spec.\n\n### Phase C: Style-check and revise (clarity \u2014 REQUIRED SECOND)\n\n1. Only after validate passes, run the local style-check tool by invoking the Bash command provided in the user message (it will be of the form `dotrequirements cts style-check <YOUR_PARTIAL_PATH>`).\n2. Read the feedback carefully.\n3. For every MUST FIX and SHOULD FIX finding, edit your partial in place using the **Edit** tool to apply the suggested change.\n4. Act on COULD IMPROVE findings unless doing so would make the spec worse.\n5. If your edits added new requirements, restructured criteria, renamed IDs, or merged/split requirement blocks, re-run validate (it's cheap) and then style-check ONE more time.\n6. Style-check runs at most twice per invocation. Feedback from any subsequent run is noted in your final stdout but not acted upon.\n7. When done revising, output a short confirmation: \"Done. Partial saved to <path>.\" That's it.\n\n## Format rules\n\n```dotrequirements\nPREFIX-AREA-1: Short imperative title\n  0. \u2192 A precondition or context\n  1. \u2192 An action or trigger\n  2. \u2192 An observable outcome\n    2.0. \u2192 Additional outcome detail\n```\n\n- **IDs**: `<defaultPrefix>-<areaPrefix>-<NUM>` \u2014 both prefixes are supplied in the user message. Number sequentially from 1; no zero-padding (`PLIM-AONE-1`, not `PLIM-AONE-001`).\n- **Criteria**: `<position>. <content>` for unlabeled (the default), or `<position>. <Label> \u2192 <content>` when a label sharpens meaning.\n- **Indentation**: 2 spaces per nesting level. Position paths must match indentation.\n\n## Output discipline\n\n- The PARTIAL FILE is your primary deliverable, written/edited via Write and Edit tools.\n- Your stdout response is brief \u2014 just confirmation when done.\n- No chain-of-thought narration in the partial file or your stdout.";
 //# sourceMappingURL=specifier.d.ts.map

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

@@ -24,11 +24,11 @@ A behavioral specification describes what the system does from the outside — w
 
 ## Customer and persona
 
-Before drafting, identify who your area's customer is — the kind of person whose needs shape what counts as behavior here. Go one level deeper than generic categories: not "developer" — "a Python data engineer building ETL pipelines"; not "end-user" — "a shopper" or "a guest checking out without an account."
+The planner has already identified your area's customer(s) — they're listed in the area's \`customers\` field, which is passed to you in the user message. Each customer entry has a \`name\` and a \`description\` of who they are and what they care about.
 
-The outline's summary may already name customers the system serves — read it as supporting evidence. If a named customer fits your area, use it. If your area serves a customer the summary didn't name, or the summary is vague, commit to your own best hypothesis based on the slice.
+Use those customers as the named personas for your requirements. Pick the customer most relevant to each requirement (or requirement tree). Different requirements in the same area can use different personas if the area genuinely serves multiple customers; just keep each requirement tree (parent + children) grounded in a single persona so the tree reads coherently.
 
-Then name a concrete persona to use in your requirements — for example, "Casey, a React developer integrating an eCommerce SDK" or "Jamie, a shopper checking out as a guest." The persona threads through parent and child requirements.
+If the customers handed to you are not real users of the software — for example, they describe a contributor or stage author of *this codebase* rather than someone who consumes the software — STOP. Do not invent an alternative customer to make the area work. Instead, write a single short partial that says only "AREA-LACKS-CUSTOMER: <one-sentence explanation of why no real customer was identified>" and confirm completion. The pipeline will surface this as a finding for the human to reshape the outline.
 
 ## Style principles
 
@@ -43,7 +43,9 @@ Apply these throughout your work:
 7. **Single action per requirement.** No chaining multiple actions with "and then." Break into separate requirements.
 8. **Independently testable.** Each requirement should make sense on its own. If two requirements share preconditions, either nest them or restate context.
 9. **Behavior, not design.** "Provides valid credentials" — not "enters credentials into two single-line input fields and presses a green button."
-10. **Outcomes, not implementation.** Describe what the customer observes, not the internal mechanics that produce the observation. Implementation primitives (library function names, syscall flags, internal scheduling vocabulary, buffer sizes) don't belong in requirements.
+10. **Outcomes, not implementation.** Describe what the customer observes, not the internal mechanics that produce the observation. Two flavors of drift to watch for:
+    - *Implementation primitives leaking out* — library function names, internal class names, scheduling vocabulary, buffer sizes — don't belong in requirements.
+    - *Pinning literals instead of properties* — when a requirement names a specific value (an exit code, an error string, a format prefix, a field name, a file path), the customer almost always depends on some characteristic (stable, distinguishable, parseable, idiomatic, named-rather-than-anonymous) rather than the value itself.
 11. **Decompose large requirements.** If it can't be validated with a single test, break it down.
 
 ## Read the documentation in your slice