@popoverai/dotrequirements 0.24.3 → 0.26.0

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

@@ -105,29 +105,50 @@ export function buildIgnoreList(projectRoot, options = {}) {
     ];
 }
 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;
+    const { projectRoot, paths, scope, remote, extraIgnores = [], ignoreRequirements = false, } = options;
+    // Local project ignore files (.dotrequirements-ignore) describe the local
+    // project and don't apply to a remote repo — repomix uses the cloned repo's
+    // own .gitignore. For remote packs, use defaults + caller-supplied extras;
+    // `--ignore-requirements` still applies (the remote repo's `.requirements/`
+    // is exactly the contamination CTS-PRESENT-5.0 exists to keep out).
+    const ignores = remote
+        ? [
+            ...DEFAULT_IGNORES,
+            ...extraIgnores,
+            ...(ignoreRequirements ? [".requirements/**"] : []),
+        ]
+        : buildIgnoreList(projectRoot, { extraIgnores, ignoreRequirements });
+    // Local: pack the scoped directory directly. Remote: repomix clones the repo;
+    // a `scope` becomes an `include` glob over the clone (the positional dir is
+    // ignored in remote mode, so pass ".").
+    const directories = remote
+        ? ["."]
+        : [scope ? join(projectRoot, scope) : projectRoot];
+    const remoteOptions = remote
+        ? {
+            remote,
+            ...(scope ? { include: `${scope.replace(/\/+$/, "")}/**` } : {}),
+        }
+        : {};
     // Import dynamically — Repomix is heavy and we don't want to load it at CLI
     // boot time for unrelated commands.
     const repomix = await import("repomix");
     const { runCli } = repomix;
     // Run compressed (overview)
-    await runCli([target], projectRoot, {
+    await runCli(directories, projectRoot, {
         output: paths.overview,
         style: "plain",
         compress: true,
         ignore: ignores.join(","),
+        ...remoteOptions,
     });
     // Run uncompressed (source)
-    await runCli([target], projectRoot, {
+    await runCli(directories, projectRoot, {
         output: paths.source,
         style: "plain",
         compress: false,
         ignore: ignores.join(","),
+        ...remoteOptions,
     });
     // Count "File:" headers in the uncompressed pack to report file count
     const sourceContent = readFileSync(paths.source, "utf-8");

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

@@ -85,6 +85,15 @@ export declare function splitComposedSpec(composed: string, outline: Outline): M
  * We just read it and return it.
  */
 export declare function buildSingleFileDoc(composedSpec: string): string;
+/**
+ * Insert the run marker as a top-level frontmatter field (IMPORT-1.0).
+ *
+ * At push time, a valid marker on a newly-created document grants its rows
+ * `imported` authorship — exempt from the requirement limit (IMPORT-2).
+ * Returns the content unchanged when it has no frontmatter block (defensive;
+ * present output always has one).
+ */
+export declare function stampRunMarker(content: string, marker: string): string;
 /**
  * Build a per-area requirements document for split mode.
  */

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

@@ -16,6 +16,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseRequirementsFile } from "../schema/parser.js";
+import { generateRunMarker } from "../schema/run-marker.js";
 import { sanitizeAreaName } from "./fan-out.js";
 import { promptOverwriteChoice } from "./interactive.js";
 export const AREA_SPLIT_THRESHOLD = 5;
@@ -113,6 +114,20 @@ export function splitComposedSpec(composed, outline) {
 export function buildSingleFileDoc(composedSpec) {
     return composedSpec;
 }
+/**
+ * Insert the run marker as a top-level frontmatter field (IMPORT-1.0).
+ *
+ * At push time, a valid marker on a newly-created document grants its rows
+ * `imported` authorship — exempt from the requirement limit (IMPORT-2).
+ * Returns the content unchanged when it has no frontmatter block (defensive;
+ * present output always has one).
+ */
+export function stampRunMarker(content, marker) {
+    if (!content.startsWith("---\n")) {
+        return content;
+    }
+    return `---\nctsRun: ${marker}\n${content.slice(4)}`;
+}
 /**
  * Build a per-area requirements document for split mode.
  */
@@ -211,11 +226,14 @@ export async function runPresent(options) {
     const composedSpec = readFileSync(finalSpecPath, "utf-8");
     const plan = planPresentPaths(outline, projectRoot, outputSubdir);
     // Compute the content for each output up front.
+    // IMPORT-1.0/1.1: one run marker per present invocation, stamped into every
+    // document this run produces.
+    const runMarker = generateRunMarker();
     const planned = [];
     if (plan.mode === "single") {
         planned.push({
             outPath: plan.paths[0].outPath,
-            content: buildSingleFileDoc(composedSpec),
+            content: stampRunMarker(buildSingleFileDoc(composedSpec), runMarker),
         });
     }
     else {
@@ -223,7 +241,10 @@ export async function runPresent(options) {
         for (const { area, outPath } of plan.paths) {
             const body = sections.get(area) ??
                 "_(no content for this area was found in the composed spec)_";
-            planned.push({ outPath, content: buildAreaDoc(outline, area, body) });
+            planned.push({
+                outPath,
+                content: stampRunMarker(buildAreaDoc(outline, area, body), runMarker),
+            });
         }
     }
     // In fail-fast mode, scan for any conflict before writing anything.

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

@@ -9,5 +9,5 @@
  * Requirements covered:
  * - CTS-EDIT-5: Editor operates on the cohesive document, not per-section
  */
-export declare const EDITOR_PROMPT = "You are revising a composed dotrequirements specification based on a reviewer's findings. You operate on the cohesive draft as a whole \u2014 not per-section. You do not get the codebase eagerly; you Read specific files only when a finding requires verification.\n\nYou will receive:\n1. A path to the current spec (Markdown file you will Edit in place)\n2. The reviewer's critique JSON (verdict, per-category findings, and possibly a `revisions` list)\n3. The mode of operation: `apply` (apply each entry in the revisions list verbatim) or `revise` (use your judgment to address the categorized findings)\n\n## Apply mode\n\nWhen the reviewer's verdict was `approved-with-revisions`, you are in apply mode. The reviewer has supplied a list of specific revisions. Your job is to apply each revision verbatim using the Edit tool, then confirm completion.\n\nDo NOT introduce changes beyond the listed revisions. Do NOT restructure. If a revision is ambiguous, apply your best literal interpretation and note the ambiguity in your stdout confirmation.\n\n## Revise mode\n\nWhen the reviewer's verdict was `requires-another-review`, you are in revise mode. Address each finding in the critique:\n\n- **Coverage gaps**: add new requirements (or new sections, if needed) to fill the gap. Match the style, prefix conventions, AND persona conventions of the surrounding spec \u2014 if existing requirements use a named persona, the new ones should too. If a finding cites code locations, Read those files via the Read tool BEFORE writing the new requirements. If a finding names a missed customer, add them to the summary alongside the existing customers.\n- **Framing errors**: rephrase architectural language to behavioral. If an area is fundamentally architectural and the reviewer recommends dropping or merging it, do so.\n- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas), balance depth. This is editorial work \u2014 keep the document coherent.\n- **Internal-mechanics drift**: rewrite criteria to describe observable outcomes rather than implementation details.\n\nMaintain everything that was working. Do NOT rewrite areas the reviewer didn't flag.\n\n## How to make changes\n\n- Use the **Edit** tool for targeted in-place changes. Each Edit replaces a specific old_string with a new_string.\n- If the section being edited has a lot of content, make multiple smaller Edits rather than one giant one.\n- Use the **Read** tool on the spec at the start (to load it into your view) and again after edits if you need to confirm changes.\n- Use the **Read/Grep/Glob** tools on the codebase ONLY when a specific finding requires verification before you can rewrite or add a requirement. Do NOT pre-read the codebase eagerly.\n\n## Discipline\n\n- Every change should reduce a flagged finding without introducing new issues.\n- If a finding is wrong (the reviewer is mistaken), say so in your stdout \u2014 do not silently ignore it.\n- The revised spec must remain syntactically valid dotrequirements format. IDs must remain unique within the document.\n- The SPEC FILE is your deliverable. You modify it in place; no separate output file.\n\n## Output (your stdout)\n\nA brief one- or two-line confirmation summarizing the kinds of changes you made.\n\nExample: \"Added 8 requirements covering missing behaviors in 'Browser automation'; rephrased 4 internal-mechanics criteria; merged 2 duplicate areas.\"\n\nNo chain-of-thought. No preamble. No commentary in the spec file beyond the spec content itself.";
+export declare const EDITOR_PROMPT = "You are revising a composed dotrequirements specification based on a reviewer's findings. You operate on the cohesive draft as a whole \u2014 not per-section. You do not get the codebase eagerly; you Read specific files only when a finding requires verification.\n\nYou will receive:\n1. A path to the current spec (Markdown file you will Edit in place)\n2. The reviewer's critique JSON (verdict, per-category findings, and possibly a `revisions` list)\n3. The mode of operation: `apply` (apply each entry in the revisions list verbatim) or `revise` (use your judgment to address the categorized findings)\n\n## Apply mode\n\nWhen the reviewer's verdict was `approved-with-revisions`, you are in apply mode. The reviewer has supplied a list of specific revisions. Your job is to apply each revision verbatim using the Edit tool, then confirm completion.\n\nDo NOT introduce changes beyond the listed revisions. Do NOT restructure. If a revision is ambiguous, apply your best literal interpretation and note the ambiguity in your stdout confirmation.\n\n## Revise mode\n\nWhen the reviewer's verdict was `requires-another-review`, you are in revise mode. Address each finding in the critique:\n\n- **Coverage gaps**: add new requirements (or new sections, if needed) to fill the gap. Match the style, prefix conventions, AND persona conventions of the surrounding spec \u2014 if existing requirements use a named persona, the new ones should too. If a finding cites code locations, Read those files via the Read tool BEFORE writing the new requirements. If a finding names a missed customer, add them to the summary alongside the existing customers.\n- **Framing errors**: rephrase architectural language to behavioral. If an area is fundamentally architectural and the reviewer recommends dropping or merging it, do so.\n- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas \u2014 and one customer per name, never the same name for different roles), balance depth. This is editorial work \u2014 keep the document coherent.\n- **Internal-mechanics drift**: rewrite criteria to describe observable outcomes rather than implementation details.\n\nMaintain everything that was working. Do NOT rewrite areas the reviewer didn't flag.\n\n## How to make changes\n\n- Use the **Edit** tool for targeted in-place changes. Each Edit replaces a specific old_string with a new_string.\n- If the section being edited has a lot of content, make multiple smaller Edits rather than one giant one.\n- Use the **Read** tool on the spec at the start (to load it into your view) and again after edits if you need to confirm changes.\n- Use the **Read/Grep/Glob** tools on the codebase ONLY when a specific finding requires verification before you can rewrite or add a requirement. Do NOT pre-read the codebase eagerly.\n\n## Discipline\n\n- Every change should reduce a flagged finding without introducing new issues.\n- If a finding is wrong (the reviewer is mistaken), say so in your stdout \u2014 do not silently ignore it.\n- The revised spec must remain syntactically valid dotrequirements format. IDs must remain unique within the document.\n- The SPEC FILE is your deliverable. You modify it in place; no separate output file.\n\n## Output (your stdout)\n\nA brief one- or two-line confirmation summarizing the kinds of changes you made.\n\nExample: \"Added 8 requirements covering missing behaviors in 'Browser automation'; rephrased 4 internal-mechanics criteria; merged 2 duplicate areas.\"\n\nNo chain-of-thought. No preamble. No commentary in the spec file beyond the spec content itself.";
 //# sourceMappingURL=editor.d.ts.map

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

@@ -28,7 +28,7 @@ When the reviewer's verdict was \`requires-another-review\`, you are in revise m
 
 - **Coverage gaps**: add new requirements (or new sections, if needed) to fill the gap. Match the style, prefix conventions, AND persona conventions of the surrounding spec — if existing requirements use a named persona, the new ones should too. If a finding cites code locations, Read those files via the Read tool BEFORE writing the new requirements. If a finding names a missed customer, add them to the summary alongside the existing customers.
 - **Framing errors**: rephrase architectural language to behavioral. If an area is fundamentally architectural and the reviewer recommends dropping or merging it, do so.
-- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas), balance depth. This is editorial work — keep the document coherent.
+- **Cross-area issues**: deduplicate, merge, normalize terminology, normalize personas (one persona per customer across all areas — and one customer per name, never the same name for different roles), balance depth. This is editorial work — keep the document coherent.
 - **Internal-mechanics drift**: rewrite criteria to describe observable outcomes rather than implementation details.
 
 Maintain everything that was working. Do NOT rewrite areas the reviewer didn't flag.

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\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.";
+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. **Unlabeled criteria \u2014 house style.** Write every criterion as a bare `\u2192` line. Do not use Given/When/Then or other labels: the format permits them, but labeled style carries conventions this pipeline doesn't apply, and a document must not mix dialects from area to area.\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.\n    - *Architecture narrated as behavior* \u2014 when the subject of a requirement is a structure of the code (a layer, a component, an internal interface) rather than something a persona does or observes, reframe it around the observer. Litmus test: if no named customer could ever notice whether the outcome happened, it is not a requirement.\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>. \u2192 <content>` \u2014 unlabeled, always (house style; see style principle 4).\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

@@ -37,7 +37,7 @@ Apply these throughout your work:
 1. **Concrete examples, not vague language.** "When a registered user provides valid credentials, they are authenticated" — not "users can log in" or "works properly."
 2. **Natural, concise prose.** Declarative ("is authenticated"), not "should be" or wandering narrative.
 3. **Arrange/Act/Assert framing in mind.** Each requirement reads as preconditions / trigger / outcome.
-4. **Framework neutral.** Default to unlabeled criteria. Use labels (e.g., Given/When/Then) only when they genuinely sharpen meaning — don't impose them as a format.
+4. **Unlabeled criteria — house style.** Write every criterion as a bare \`→\` line. Do not use Given/When/Then or other labels: the format permits them, but labeled style carries conventions this pipeline doesn't apply, and a document must not mix dialects from area to area.
 5. **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..."
 6. **User-centric language.** Describe the customer's experience, not internal mechanics. "They are brought to the dashboard," not "they are redirected to /redirect/dashboard."
 7. **Single action per requirement.** No chaining multiple actions with "and then." Break into separate requirements.
@@ -46,6 +46,7 @@ Apply these throughout your work:
 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.
+    - *Architecture narrated as behavior* — when the subject of a requirement is a structure of the code (a layer, a component, an internal interface) rather than something a persona does or observes, reframe it around the observer. Litmus test: if no named customer could ever notice whether the outcome happened, it is not a requirement.
 11. **Decompose large requirements.** If it can't be validated with a single test, break it down.
 
 ## Read the documentation in your slice
@@ -91,7 +92,7 @@ PREFIX-AREA-1: Short imperative title
 \`\`\`
 
 - **IDs**: \`<defaultPrefix>-<areaPrefix>-<NUM>\` — both prefixes are supplied in the user message. Number sequentially from 1; no zero-padding (\`PLIM-AONE-1\`, not \`PLIM-AONE-001\`).
-- **Criteria**: \`<position>. <content>\` for unlabeled (the default), or \`<position>. <Label> → <content>\` when a label sharpens meaning.
+- **Criteria**: \`<position>. → <content>\` — unlabeled, always (house style; see style principle 4).
 - **Indentation**: 2 spaces per nesting level. Position paths must match indentation.
 
 ## Output discipline

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

@@ -505,6 +505,11 @@ export declare const ConversationalOutlineSchema: z.ZodObject<{
     title: z.ZodString;
     defaultPrefix: z.ZodString;
     summary: z.ZodString;
+    /**
+     * Outline-approval review (the outline iteration loop). `compose-orchestrator`
+     * gates composition on `review.result === "approved"`, so this field is
+     * distinct from and must never be conflated with `crossAreaReview` below.
+     */
     review: z.ZodOptional<z.ZodObject<{
         result: z.ZodEnum<["approved", "needs-revision"]>;
         thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
@@ -540,6 +545,49 @@ export declare const ConversationalOutlineSchema: z.ZodObject<{
             result: "needs-revision";
         })[];
     }>>;
+    /**
+     * Document-level cross-area review state (CTSO-CONV-5). Recorded after the
+     * per-area partials are composed: the cross-area reviewer appends verdicts
+     * here and the compose-editor reads the latest entry's revisions — the same
+     * auditable thread pattern as `area.review`, kept at the top level because the
+     * review spans the whole composed spec rather than one area. Separate from
+     * `review` so cross-area iteration never disturbs outline approval.
+     */
+    crossAreaReview: z.ZodOptional<z.ZodObject<{
+        result: z.ZodEnum<["approved", "needs-revision"]>;
+        thread: z.ZodArray<z.ZodDiscriminatedUnion<"result", [z.ZodObject<{
+            result: z.ZodLiteral<"approved">;
+        }, "strip", z.ZodTypeAny, {
+            result: "approved";
+        }, {
+            result: "approved";
+        }>, z.ZodObject<{
+            result: z.ZodLiteral<"needs-revision">;
+            revisions: z.ZodArray<z.ZodString, "many">;
+        }, "strip", z.ZodTypeAny, {
+            revisions: string[];
+            result: "needs-revision";
+        }, {
+            revisions: string[];
+            result: "needs-revision";
+        }>]>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }, {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    }>>;
     areas: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         prefix: z.ZodString;
@@ -660,6 +708,15 @@ export declare const ConversationalOutlineSchema: z.ZodObject<{
             result: "needs-revision";
         })[];
     } | undefined;
+    crossAreaReview?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
 }, {
     title: string;
     defaultPrefix: string;
@@ -691,6 +748,15 @@ export declare const ConversationalOutlineSchema: z.ZodObject<{
             result: "needs-revision";
         })[];
     } | undefined;
+    crossAreaReview?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
 }>;
 export type ConversationalOutline = z.infer<typeof ConversationalOutlineSchema>;
 /**
@@ -712,5 +778,92 @@ export declare function conversationalOutlineToLegacy(outline: ConversationalOut
  * multi-line strings (`|`) where possible for readability.
  */
 export declare function stringifyConversationalOutline(outline: ConversationalOutline): string;
+/**
+ * Result a specifier or editor worker returns to the workflow after writing
+ * (or skipping) an area's partial.
+ *
+ * - `drafted`: the worker composed and wrote the partial this run.
+ * - `skipped-resume`: a non-empty partial already existed, so the worker left
+ *   it in place (idempotent re-entry — see CTSO-INTEG-2).
+ */
+export declare const PartialResultStatusValues: readonly ["drafted", "skipped-resume"];
+export type PartialResultStatus = (typeof PartialResultStatusValues)[number];
+export declare const PartialResultSchema: z.ZodObject<{
+    area_prefix: z.ZodString;
+    partial_path: z.ZodString;
+    status: z.ZodEnum<["drafted", "skipped-resume"]>;
+    requirement_count: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    status: "drafted" | "skipped-resume";
+    area_prefix: string;
+    partial_path: string;
+    requirement_count?: number | undefined;
+}, {
+    status: "drafted" | "skipped-resume";
+    area_prefix: string;
+    partial_path: string;
+    requirement_count?: number | undefined;
+}>;
+export type PartialResult = z.infer<typeof PartialResultSchema>;
+export declare const PARTIAL_RESULT_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly area_prefix: {
+            readonly type: "string";
+        };
+        readonly partial_path: {
+            readonly type: "string";
+        };
+        readonly status: {
+            readonly type: "string";
+            readonly enum: readonly string[];
+        };
+        readonly requirement_count: {
+            readonly type: "integer";
+            readonly minimum: 0;
+        };
+    };
+    readonly required: readonly ["area_prefix", "partial_path", "status"];
+    readonly additionalProperties: false;
+};
+/**
+ * Verdict a reviewer worker returns to the workflow. Same shape as one
+ * `ConversationalReviewEntry` (discriminated on `result`): `approved` carries
+ * no revisions; `needs-revision` must carry a non-empty `revisions` list. This
+ * verdict drives the per-area convergence loop (CTSO-CONV-4).
+ *
+ * The JSON Schema form is flat (result + optional revisions) — JSON Schema
+ * can't express the discriminated-union constraint as cleanly as Zod. The
+ * runtime retries on mismatch, the prompt instructs the reviewer to include
+ * revisions exactly when the result is needs-revision, and `parseReviewVerdict`
+ * enforces the stricter Zod constraint on the CLI side.
+ */
+export declare const REVIEW_VERDICT_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly result: {
+            readonly type: "string";
+            readonly enum: readonly ["approved", "needs-revision"];
+        };
+        readonly revisions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+    };
+    readonly required: readonly ["result"];
+    readonly additionalProperties: false;
+};
+/**
+ * Parse + validate a specifier/editor worker's JSON result.
+ */
+export declare function parsePartialResult(text: string): PartialResult;
+/**
+ * Parse + validate a reviewer worker's JSON verdict. Reuses
+ * `ConversationalReviewEntrySchema`, so a `needs-revision` verdict requires a
+ * non-empty `revisions` list.
+ */
+export declare function parseReviewVerdict(text: string): ConversationalReviewEntry;
 export declare function parseSpecReview(text: string): SpecReview;
 //# sourceMappingURL=schemas.d.ts.map

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

@@ -252,7 +252,21 @@ export const ConversationalOutlineSchema = z.object({
         .string()
         .regex(/^[A-Z][A-Z0-9_]*$/, "defaultPrefix must be uppercase alphanumeric/underscore"),
     summary: z.string().min(1),
+    /**
+     * Outline-approval review (the outline iteration loop). `compose-orchestrator`
+     * gates composition on `review.result === "approved"`, so this field is
+     * distinct from and must never be conflated with `crossAreaReview` below.
+     */
     review: ConversationalReviewSchema.optional(),
+    /**
+     * Document-level cross-area review state (CTSO-CONV-5). Recorded after the
+     * per-area partials are composed: the cross-area reviewer appends verdicts
+     * here and the compose-editor reads the latest entry's revisions — the same
+     * auditable thread pattern as `area.review`, kept at the top level because the
+     * review spans the whole composed spec rather than one area. Separate from
+     * `review` so cross-area iteration never disturbs outline approval.
+     */
+    crossAreaReview: ConversationalReviewSchema.optional(),
     areas: z.array(ConversationalAreaSchema).min(1),
 });
 /**
@@ -322,6 +336,103 @@ export function stringifyConversationalOutline(outline) {
         blockQuote: "literal",
     });
 }
+// ---------- Workflow orchestrator worker I/O ----------
+//
+// The workflow orchestrator (the `specify-codebase` dynamic workflow) fans out
+// specifier / editor / reviewer subagents and receives their results back as
+// schema-validated values via the workflow runtime's `schema` option. The JSON
+// Schemas below are the contract the runtime constrains each agent to; the Zod
+// schemas validate the same shapes on the CLI/test side. Because the workflow
+// script can't import this module, the JSON Schemas are mirrored inline in the
+// workflow file; a template-sync test guards against drift.
+/**
+ * Result a specifier or editor worker returns to the workflow after writing
+ * (or skipping) an area's partial.
+ *
+ * - `drafted`: the worker composed and wrote the partial this run.
+ * - `skipped-resume`: a non-empty partial already existed, so the worker left
+ *   it in place (idempotent re-entry — see CTSO-INTEG-2).
+ */
+export const PartialResultStatusValues = ["drafted", "skipped-resume"];
+export const PartialResultSchema = z.object({
+    area_prefix: z.string().min(1),
+    partial_path: z.string().min(1),
+    status: z.enum(PartialResultStatusValues),
+    requirement_count: z.number().int().nonnegative().optional(),
+});
+export const PARTIAL_RESULT_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        area_prefix: { type: "string" },
+        partial_path: { type: "string" },
+        status: {
+            type: "string",
+            enum: PartialResultStatusValues,
+        },
+        requirement_count: { type: "integer", minimum: 0 },
+    },
+    required: ["area_prefix", "partial_path", "status"],
+    additionalProperties: false,
+};
+/**
+ * Verdict a reviewer worker returns to the workflow. Same shape as one
+ * `ConversationalReviewEntry` (discriminated on `result`): `approved` carries
+ * no revisions; `needs-revision` must carry a non-empty `revisions` list. This
+ * verdict drives the per-area convergence loop (CTSO-CONV-4).
+ *
+ * The JSON Schema form is flat (result + optional revisions) — JSON Schema
+ * can't express the discriminated-union constraint as cleanly as Zod. The
+ * runtime retries on mismatch, the prompt instructs the reviewer to include
+ * revisions exactly when the result is needs-revision, and `parseReviewVerdict`
+ * enforces the stricter Zod constraint on the CLI side.
+ */
+export const REVIEW_VERDICT_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        result: { type: "string", enum: ["approved", "needs-revision"] },
+        revisions: { type: "array", items: { type: "string" } },
+    },
+    required: ["result"],
+    additionalProperties: false,
+};
+/**
+ * Parse + validate a specifier/editor worker's JSON result.
+ */
+export function parsePartialResult(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Partial result is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return PartialResultSchema.parse(raw);
+}
+/**
+ * Parse + validate a reviewer worker's JSON verdict. Reuses
+ * `ConversationalReviewEntrySchema`, so a `needs-revision` verdict requires a
+ * non-empty `revisions` list.
+ */
+export function parseReviewVerdict(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Review verdict is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return ConversationalReviewEntrySchema.parse(raw);
+}
 export function parseSpecReview(text) {
     const trimmed = text.trim();
     let raw;