@popoverai/dotrequirements 0.23.0 → 0.24.1

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

@@ -0,0 +1,100 @@
+/**
+ * System prompt for the specifier worker.
+ *
+ * Each specifier handles one behavioral area. It writes its partial to a
+ * known path, runs the local style-check on its own draft, applies feedback,
+ * and confirms completion.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-1, CTS-SPEC-2, CTS-SPEC-3, CTS-SPEC-4
+ */
+export const SPECIFIER_PROMPT = `You are reading a slice of a software codebase — 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.
+
+A 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.
+
+## What to capture
+
+A behavioral specification describes what the system does from the outside — what someone using it can observe, not how the implementation works. Scoped to your assigned area, capture:
+
+- **User-facing behaviors** — what the customer can do, what happens when they do it, what they see in response
+- **Integration behaviors** — how this area interacts with external services, what it sends/receives, how it handles failures
+- **Domain rules** — validation, business logic, state transitions, decision logic specific to this area
+- **Error and edge cases** — what happens when things go wrong, what the system tolerates, what it rejects
+- **Documented warnings, hazards, and limitations** — things the README or docstrings warn customers about
+
+## 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 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.
+
+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.
+
+## Style principles
+
+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.
+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.
+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.
+11. **Decompose large requirements.** If it can't be validated with a single test, break it down.
+
+## Read the documentation in your slice
+
+If 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.
+
+## Workflow (REQUIRED)
+
+### Phase A: Draft
+
+1. Read your slice. Read documentation in the slice. If needed, Read/Grep the full pack to discover behaviors documented in tests or recipes.
+2. Use the **Write** tool to write your draft to the partial path provided in the user message. Output in this format:
+   - 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 — 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.
+   - Blank line.
+   - Series of fenced \`dotrequirements\` blocks.
+
+   Do NOT include YAML frontmatter, H1 title, summary paragraph, or area H2. The composer adds those.
+
+### Phase B: Validate (schema/syntax — REQUIRED FIRST)
+
+1. 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 — it checks that every requirement block parses, every criterion has a \`→\` arrow, position paths match indentation, and IDs are unique.
+2. If validate prints \`Schema validation: PASS\`, proceed to Phase C.
+3. 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 — schema errors will cause the downstream pipeline to reject your spec.
+
+### Phase C: Style-check and revise (clarity — REQUIRED SECOND)
+
+1. 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>\`).
+2. Read the feedback carefully.
+3. For every MUST FIX and SHOULD FIX finding, edit your partial in place using the **Edit** tool to apply the suggested change.
+4. Act on COULD IMPROVE findings unless doing so would make the spec worse.
+5. 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.
+6. Style-check runs at most twice per invocation. Feedback from any subsequent run is noted in your final stdout but not acted upon.
+7. When done revising, output a short confirmation: "Done. Partial saved to <path>." That's it.
+
+## Format rules
+
+\`\`\`dotrequirements
+PREFIX-AREA-1: Short imperative title
+  0. → A precondition or context
+  1. → An action or trigger
+  2. → An observable outcome
+    2.0. → Additional outcome detail
+\`\`\`
+
+- **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.
+- **Indentation**: 2 spaces per nesting level. Position paths must match indentation.
+
+## Output discipline
+
+- The PARTIAL FILE is your primary deliverable, written/edited via Write and Edit tools.
+- Your stdout response is brief — just confirmation when done.
+- No chain-of-thought narration in the partial file or your stdout.`;
+//# sourceMappingURL=specifier.js.map

package/dist/codebase-to-spec/prompts/style-check.d.ts

@@ -0,0 +1,12 @@
+/**
+ * System prompt for the local style-check tool.
+ *
+ * Reads a partial-spec file and produces severity-categorized feedback.
+ * Stateless — same "fresh set of eyes" pattern as the existing cloud
+ * `mcp__dotrequirements__style_check`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+export declare const STYLE_CHECK_PROMPT = "You are a stateless style reviewer for a single dotrequirements partial spec \u2014 one or more `dotrequirements` fenced blocks plus an optional one-line description above them. Your job is to give the author actionable feedback on per-requirement writing quality.\n\nThis check is a \"fresh set of eyes\" \u2014 you have no memory of prior feedback rounds. You are looking only at this file as it currently stands.\n\n## How to categorize feedback\n\n### MUST FIX\n\n- **The requirement does not describe an observable outcome.** \"The system manages memory efficiently\" gives a tester nothing to verify. The requirement needs to be rephrased around what the customer can observe.\n\n### SHOULD FIX\n\n- **Vague language** where concrete behavior is needed.\n- **Missing preconditions** that anchor the test \u2014 a When/Then with no Given-equivalent context.\n- **Internal-mechanics drift** \u2014 describing how the implementation works (library function names, syscall flags, internal scheduling vocabulary, buffer sizes) instead of what the customer observes.\n- **Documentation prose dressed as a requirement** \u2014 \"the documentation directs users to...\" style commentary that isn't testable behavior.\n- **Persona inconsistency** \u2014 the spec doesn't name a persona, or child requirements drop the persona established by their parent.\n- **Chained actions** \u2014 a single requirement covering multiple discrete actions that should be separate requirements.\n- **Hidden sibling dependencies** \u2014 a requirement that only makes sense if read alongside its siblings.\n- **Imposed format labels** \u2014 Given/When/Then or other framework labels applied uniformly without sharpening meaning. The dotrequirements default is unlabeled criteria; labels are used only when they help.\n\n### COULD IMPROVE\n\n- Over-long titles that read like full sentences.\n- Inconsistent terminology with the rest of the area.\n- Redundant sub-criteria that re-state the parent.\n- UI or design specifics where behavior alone would suffice.\n\n## How to write findings\n\nFor each finding:\n- Cite the specific requirement ID (e.g., `AUTH-LOGIN-1`).\n- Quote the offending text.\n- Explain why it's an issue.\n- Suggest a rephrasing, or recommend dropping the requirement.\n\nKeep findings specific and concrete. Vague critiques like \"could be more comprehensive\" are not useful \u2014 name the requirement and quote the issue.\n\n## When to be brief\n\nIf the partial is genuinely good, say so. Don't manufacture findings to fill space. A clean style check is the right outcome more often than not.\n\n## Output format\n\nMarkdown with these headings:\n\n```\n## MUST FIX\n\n- ...\n\n## SHOULD FIX\n\n- ...\n\n## COULD IMPROVE\n\n- ...\n```\n\nOmit any heading with no findings. End with a one-line summary like `OVERALL: <terse assessment>`.\n\n## Output discipline\n\n- Output ONLY the categorized feedback, beginning with the first heading.\n- No preamble, no chain-of-thought, no explanation of your process.\n- Be honest. Accurate signal helps the author iterate.";
+//# sourceMappingURL=style-check.d.ts.map

package/dist/codebase-to-spec/prompts/style-check.js

@@ -0,0 +1,78 @@
+/**
+ * System prompt for the local style-check tool.
+ *
+ * Reads a partial-spec file and produces severity-categorized feedback.
+ * Stateless — same "fresh set of eyes" pattern as the existing cloud
+ * `mcp__dotrequirements__style_check`.
+ *
+ * Requirements covered:
+ * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ */
+export const STYLE_CHECK_PROMPT = `You are a stateless style reviewer for a single dotrequirements partial spec — one or more \`dotrequirements\` fenced blocks plus an optional one-line description above them. Your job is to give the author actionable feedback on per-requirement writing quality.
+
+This check is a "fresh set of eyes" — you have no memory of prior feedback rounds. You are looking only at this file as it currently stands.
+
+## How to categorize feedback
+
+### MUST FIX
+
+- **The requirement does not describe an observable outcome.** "The system manages memory efficiently" gives a tester nothing to verify. The requirement needs to be rephrased around what the customer can observe.
+
+### SHOULD FIX
+
+- **Vague language** where concrete behavior is needed.
+- **Missing preconditions** that anchor the test — a When/Then with no Given-equivalent context.
+- **Internal-mechanics drift** — describing how the implementation works (library function names, syscall flags, internal scheduling vocabulary, buffer sizes) instead of what the customer observes.
+- **Documentation prose dressed as a requirement** — "the documentation directs users to..." style commentary that isn't testable behavior.
+- **Persona inconsistency** — the spec doesn't name a persona, or child requirements drop the persona established by their parent.
+- **Chained actions** — a single requirement covering multiple discrete actions that should be separate requirements.
+- **Hidden sibling dependencies** — a requirement that only makes sense if read alongside its siblings.
+- **Imposed format labels** — Given/When/Then or other framework labels applied uniformly without sharpening meaning. The dotrequirements default is unlabeled criteria; labels are used only when they help.
+
+### COULD IMPROVE
+
+- Over-long titles that read like full sentences.
+- Inconsistent terminology with the rest of the area.
+- Redundant sub-criteria that re-state the parent.
+- UI or design specifics where behavior alone would suffice.
+
+## How to write findings
+
+For each finding:
+- Cite the specific requirement ID (e.g., \`AUTH-LOGIN-1\`).
+- Quote the offending text.
+- Explain why it's an issue.
+- Suggest a rephrasing, or recommend dropping the requirement.
+
+Keep findings specific and concrete. Vague critiques like "could be more comprehensive" are not useful — name the requirement and quote the issue.
+
+## When to be brief
+
+If the partial is genuinely good, say so. Don't manufacture findings to fill space. A clean style check is the right outcome more often than not.
+
+## Output format
+
+Markdown with these headings:
+
+\`\`\`
+## MUST FIX
+
+- ...
+
+## SHOULD FIX
+
+- ...
+
+## COULD IMPROVE
+
+- ...
+\`\`\`
+
+Omit any heading with no findings. End with a one-line summary like \`OVERALL: <terse assessment>\`.
+
+## Output discipline
+
+- Output ONLY the categorized feedback, beginning with the first heading.
+- No preamble, no chain-of-thought, no explanation of your process.
+- Be honest. Accurate signal helps the author iterate.`;
+//# sourceMappingURL=style-check.js.map

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

@@ -0,0 +1,257 @@
+/**
+ * JSON schemas for outline + reviewer output.
+ *
+ * The CLI passes these to `claude -p --json-schema` to constrain agent output,
+ * then validates the parsed result before driving the loop.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-1: outline structure
+ * - CTS-PLAN-2: outline reviewer output structure (categorized findings + verdict)
+ */
+import { z } from "zod";
+export declare const AreaSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    prefix: z.ZodString;
+    files: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    prefix: string;
+    files: string[];
+    name: string;
+    description: string;
+}, {
+    prefix: string;
+    files: string[];
+    name: string;
+    description: string;
+}>;
+export type Area = z.infer<typeof AreaSchema>;
+export declare const OutlineSchema: z.ZodObject<{
+    title: z.ZodString;
+    defaultPrefix: z.ZodString;
+    summary: z.ZodString;
+    areas: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        prefix: z.ZodString;
+        files: z.ZodArray<z.ZodString, "many">;
+    }, "strip", z.ZodTypeAny, {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }, {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }[];
+}, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        files: string[];
+        name: string;
+        description: string;
+    }[];
+}>;
+export type Outline = z.infer<typeof OutlineSchema>;
+/**
+ * JSON Schema for the outline, passed to `claude -p --json-schema`.
+ * Mirrors OutlineSchema in JSON Schema form (which `claude -p` accepts).
+ */
+export declare const OUTLINE_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly title: {
+            readonly type: "string";
+        };
+        readonly defaultPrefix: {
+            readonly type: "string";
+        };
+        readonly summary: {
+            readonly type: "string";
+        };
+        readonly areas: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                    };
+                    readonly prefix: {
+                        readonly type: "string";
+                    };
+                    readonly files: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+                readonly required: readonly ["name", "description", "prefix", "files"];
+                readonly additionalProperties: false;
+            };
+        };
+    };
+    readonly required: readonly ["title", "defaultPrefix", "summary", "areas"];
+    readonly additionalProperties: false;
+};
+export declare const VerdictValues: readonly ["approved", "approved-with-revisions", "requires-another-review"];
+export type Verdict = (typeof VerdictValues)[number];
+export declare const OutlineReviewSchema: z.ZodObject<{
+    coverage_gaps: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    framing_errors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    granularity_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    file_assignment_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    revisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    verdict: z.ZodEnum<["approved", "approved-with-revisions", "requires-another-review"]>;
+}, "strip", z.ZodTypeAny, {
+    coverage_gaps: string[];
+    framing_errors: string[];
+    granularity_issues: string[];
+    file_assignment_issues: string[];
+    revisions: string[];
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+}, {
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    coverage_gaps?: string[] | undefined;
+    framing_errors?: string[] | undefined;
+    granularity_issues?: string[] | undefined;
+    file_assignment_issues?: string[] | undefined;
+    revisions?: string[] | undefined;
+}>;
+export type OutlineReview = z.infer<typeof OutlineReviewSchema>;
+export declare const OUTLINE_REVIEW_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly coverage_gaps: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly framing_errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly granularity_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly file_assignment_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly revisions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly string[];
+        };
+    };
+    readonly required: readonly ["coverage_gaps", "framing_errors", "granularity_issues", "file_assignment_issues", "revisions", "verdict"];
+    readonly additionalProperties: false;
+};
+/**
+ * Try to parse a string as JSON and validate against the outline schema.
+ * Throws with a descriptive message on failure (caller catches and either
+ * retries or fails the loop).
+ */
+export declare function parseOutline(text: string): Outline;
+/**
+ * Parse a reviewer's JSON output and validate against the outline-review schema.
+ */
+export declare function parseOutlineReview(text: string): OutlineReview;
+export declare const SpecReviewSchema: z.ZodObject<{
+    coverage_gaps: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    framing_errors: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    cross_area_issues: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    internal_mechanics_drift: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    revisions: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    verdict: z.ZodEnum<["approved", "approved-with-revisions", "requires-another-review"]>;
+}, "strip", z.ZodTypeAny, {
+    coverage_gaps: string[];
+    framing_errors: string[];
+    revisions: string[];
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    cross_area_issues: string[];
+    internal_mechanics_drift: string[];
+}, {
+    verdict: "approved" | "approved-with-revisions" | "requires-another-review";
+    coverage_gaps?: string[] | undefined;
+    framing_errors?: string[] | undefined;
+    revisions?: string[] | undefined;
+    cross_area_issues?: string[] | undefined;
+    internal_mechanics_drift?: string[] | undefined;
+}>;
+export type SpecReview = z.infer<typeof SpecReviewSchema>;
+export declare const SPEC_REVIEW_JSON_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly coverage_gaps: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly framing_errors: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly cross_area_issues: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly internal_mechanics_drift: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly revisions: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+            };
+        };
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly string[];
+        };
+    };
+    readonly required: readonly ["coverage_gaps", "framing_errors", "cross_area_issues", "internal_mechanics_drift", "revisions", "verdict"];
+    readonly additionalProperties: false;
+};
+export declare function parseSpecReview(text: string): SpecReview;
+//# sourceMappingURL=schemas.d.ts.map

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

@@ -0,0 +1,183 @@
+/**
+ * JSON schemas for outline + reviewer output.
+ *
+ * The CLI passes these to `claude -p --json-schema` to constrain agent output,
+ * then validates the parsed result before driving the loop.
+ *
+ * Requirements covered:
+ * - CTS-PLAN-1: outline structure
+ * - CTS-PLAN-2: outline reviewer output structure (categorized findings + verdict)
+ */
+import { z } from "zod";
+// ---------- Outline ----------
+export const AreaSchema = z.object({
+    name: z.string().min(1),
+    description: z.string().min(1),
+    prefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "prefix must be uppercase alphanumeric/underscore"),
+    files: z.array(z.string()).min(0),
+});
+export const OutlineSchema = z.object({
+    title: z.string().min(1),
+    defaultPrefix: z
+        .string()
+        .regex(/^[A-Z][A-Z0-9_]*$/, "defaultPrefix must be uppercase alphanumeric/underscore"),
+    summary: z.string().min(1),
+    areas: z.array(AreaSchema).min(1),
+});
+/**
+ * JSON Schema for the outline, passed to `claude -p --json-schema`.
+ * Mirrors OutlineSchema in JSON Schema form (which `claude -p` accepts).
+ */
+export const OUTLINE_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        title: { type: "string" },
+        defaultPrefix: { type: "string" },
+        summary: { type: "string" },
+        areas: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    name: { type: "string" },
+                    description: { type: "string" },
+                    prefix: { type: "string" },
+                    files: { type: "array", items: { type: "string" } },
+                },
+                required: ["name", "description", "prefix", "files"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["title", "defaultPrefix", "summary", "areas"],
+    additionalProperties: false,
+};
+// ---------- Outline review verdict ----------
+export const VerdictValues = [
+    "approved",
+    "approved-with-revisions",
+    "requires-another-review",
+];
+export const OutlineReviewSchema = z.object({
+    coverage_gaps: z.array(z.string()).default([]),
+    framing_errors: z.array(z.string()).default([]),
+    granularity_issues: z.array(z.string()).default([]),
+    file_assignment_issues: z.array(z.string()).default([]),
+    revisions: z.array(z.string()).default([]),
+    verdict: z.enum(VerdictValues),
+});
+export const OUTLINE_REVIEW_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        coverage_gaps: { type: "array", items: { type: "string" } },
+        framing_errors: { type: "array", items: { type: "string" } },
+        granularity_issues: { type: "array", items: { type: "string" } },
+        file_assignment_issues: { type: "array", items: { type: "string" } },
+        revisions: { type: "array", items: { type: "string" } },
+        verdict: {
+            type: "string",
+            enum: VerdictValues,
+        },
+    },
+    required: [
+        "coverage_gaps",
+        "framing_errors",
+        "granularity_issues",
+        "file_assignment_issues",
+        "revisions",
+        "verdict",
+    ],
+    additionalProperties: false,
+};
+/**
+ * Try to parse a string as JSON and validate against the outline schema.
+ * Throws with a descriptive message on failure (caller catches and either
+ * retries or fails the loop).
+ */
+export function parseOutline(text) {
+    const trimmed = text.trim();
+    // Try direct parse first; fall back to extracting first {...} block.
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Outline output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return OutlineSchema.parse(raw);
+}
+/**
+ * Parse a reviewer's JSON output and validate against the outline-review schema.
+ */
+export function parseOutlineReview(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Reviewer output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return OutlineReviewSchema.parse(raw);
+}
+// ---------- Spec review verdict ----------
+//
+// Same three-verdict structure as the outline reviewer, with categories
+// tailored to document-level cohesion concerns.
+export const SpecReviewSchema = z.object({
+    coverage_gaps: z.array(z.string()).default([]),
+    framing_errors: z.array(z.string()).default([]),
+    cross_area_issues: z.array(z.string()).default([]),
+    internal_mechanics_drift: z.array(z.string()).default([]),
+    revisions: z.array(z.string()).default([]),
+    verdict: z.enum(VerdictValues),
+});
+export const SPEC_REVIEW_JSON_SCHEMA = {
+    type: "object",
+    properties: {
+        coverage_gaps: { type: "array", items: { type: "string" } },
+        framing_errors: { type: "array", items: { type: "string" } },
+        cross_area_issues: { type: "array", items: { type: "string" } },
+        internal_mechanics_drift: { type: "array", items: { type: "string" } },
+        revisions: { type: "array", items: { type: "string" } },
+        verdict: {
+            type: "string",
+            enum: VerdictValues,
+        },
+    },
+    required: [
+        "coverage_gaps",
+        "framing_errors",
+        "cross_area_issues",
+        "internal_mechanics_drift",
+        "revisions",
+        "verdict",
+    ],
+    additionalProperties: false,
+};
+export function parseSpecReview(text) {
+    const trimmed = text.trim();
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        const match = trimmed.match(/(\{[\s\S]*\})/);
+        if (!match) {
+            throw new Error("Spec reviewer output is not valid JSON and contains no JSON object");
+        }
+        raw = JSON.parse(match[1]);
+    }
+    return SpecReviewSchema.parse(raw);
+}
+//# sourceMappingURL=schemas.js.map