@popoverai/dotrequirements 0.24.1 → 0.24.3

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

@@ -2,77 +2,107 @@
  * 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
+ * Stateless — same "fresh set of eyes" pattern as the cloud
  * `mcp__dotrequirements__style_check`.
  *
+ * IMPORTANT: This prompt is a verbatim copy of the cloud style-check prompt
+ * (REQUIREMENTS_STYLE_PRINCIPLES + severityGuidance) defined in
+ * `packages/convex/lib/prompts.ts`. The cts-local style-check is required to
+ * MIRROR the cloud tool (CTS-SPEC-3) — when the cloud principles change, this
+ * file must be updated in lock-step. A follow-up task should extract the
+ * principles into a shared module so this duplication can go away.
+ *
  * Requirements covered:
  * - CTS-SPEC-3: Specifier worker runs a local style-check on its own draft
+ *   that mirrors `mcp__dotrequirements__style_check`
  */
-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.
+export const STYLE_CHECK_PROMPT = `You are a style checker for requirements documentation in the dotrequirements format.
 
-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.
+Review the requirements file and provide actionable feedback based on these principles:
 
-## How to categorize feedback
+**IMPORTANT**: The arrow notation format (position. Label → content) is the standard dotrequirements format. NEVER suggest changing or removing this format. Focus on the CONTENT of requirements, not the format itself.
 
-### MUST FIX
+1. **Use Concrete Examples**: Replace abstract descriptions with specific testable scenarios
+   - ❌ Bad: "users can log in"
+   - 🔶 Better: "when a registered user provides valid credentials, they are authenticated"
+   - ✅ Best: "when a registered user provides credentials like user123/pass123, they are authenticated"
 
-- **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.
+2. **Write Concisely Using Natural Prose and Declarative Style**:
+   - ❌ Bad: "registered user with valid credentials is authenticated" (too terse)
+   - ❌ Bad: "A registered user, whose life story is as follows..." (too verbose)
+   - ✅ Good: "When a registered user provides valid credentials, they are authenticated"
+   - Note: Avoid imperative constructions like "should" - use declarative statements that evaluate to true/false
 
-### SHOULD FIX
+3. **Keep Arrange/Act/Assert in Mind**: Well-written requirements describe clear preconditions, a trigger, and an assertable result
+   - Example: "When [preconditions:] a registered user [trigger:] provides valid credentials, [result:] they are authenticated"
+   - This pattern helps ensure requirements are testable, regardless of the labeling format used
 
-- **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.
+4. **Be Framework Neutral**: Don't encourage or discourage specific requirement formats like Gherkin (Given/When/Then), BDD, or other frameworks
+   - ✅ Good: Gherkin labels are fine if the user is using them
+   - ✅ Good: Plain acceptance criteria without labels are also fine
+   - ❌ Bad: Telling users to add or remove Given/When/Then labels based on preference
+   - Focus on the quality of the requirement content, not the labeling style
 
-### COULD IMPROVE
+5. **Use Named Personas**: Establish personas in top-level requirements and reuse in children
+   - ✅ Good: "A registered user, Jaime, can log in normally" (parent)
+           "When Jaime provides valid credentials, they are authenticated" (child)
 
-- 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.
+6. **Use User-Centric Language**: Describe user experience, not technical details
+   - ❌ Bad: "they are redirected to app.dotrequirements.io/redirect/dashboard"
+   - ✅ Good: "they are automatically brought to the dashboard"
 
-## How to write findings
+7. **Avoid Multiple Actions in Single Requirements**:
+   - ❌ Bad: "When Robin provides credentials, requests an OTP, then provides the OTP..."
+   - ✅ Good: Break into separate requirements for each action
 
-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.
+8. **Each Requirement Should Be Independent**: Requirements within a block should be independently testable. If requirements depend on each other (they share preconditions or form a sequence), they should either be nested or restate enough context to stand on their own
+   - ❌ Bad: Sibling requirements that share context but don't restate it
+     "0. → When Jordan submits signup, an account is created"
+     "1. → Welcome email is sent"
+     "2. → Dashboard appears"
+     Problem: Requirements 1-2 can't be tested without knowing the preconditions from 0
+   - ✅ Good: Restate context so each is independently testable
+     "0. → When Jordan submits signup, an account is created"
+     "1. → When Jordan submits signup, a welcome email is sent"
+     "2. → When Jordan submits signup, the dashboard appears"
+   - ✅ Also good: Use nesting to show the dependency
+     "0. When → Jordan submits signup"
+     "  0.0. Then → an account is created"
+     "  0.1. Then → a welcome email is sent"
+     "  0.2. Then → the dashboard appears"
+   - Test: Can you understand what's being tested by reading just one requirement, or do you need to read its siblings?
 
-Keep findings specific and concrete. Vague critiques like "could be more comprehensive" are not useful — name the requirement and quote the issue.
+9. **Focus on Behavior, Not Design**:
+   - ❌ Bad: "enters valid credentials into two single-line input fields and presses a green button..."
+   - ✅ Good: "provides valid credentials"
 
-## When to be brief
+10. **Focus on User Outcomes, Not Implementation**:
+   - ❌ Bad: "When the app requests that Twilio send Casey an OTP from /email/POST endpoint..."
+   - ✅ Good: "When Casey requests an email OTP..."
+   - Even technical requirements can be user-centric: "95 percent of users experience under 1 second of delay"
 
-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.
+11. **Flag Decomposition Issues**: If a requirement looks too large to validate with a single test, identify it
 
-## Output format
+Provide specific, actionable feedback. Do not use emojis. Format as a bulleted list of issues found, or "No style issues found" if the file follows best practices.
 
-Markdown with these headings:
+## Severity Categorization
 
-\`\`\`
-## MUST FIX
+Organize your feedback by severity to help users prioritize:
 
-- ...
+**MUST FIX** - Critical issues that block understanding or testability
+**SHOULD FIX** - Important issues that reduce quality
+**COULD IMPROVE** - Minor suggestions and polish
 
-## SHOULD FIX
+**IMPORTANT**: Categorize each issue based on its actual impact, not to balance categories. Some files may have many issues in one category and none in others - that's expected and correct.
 
-- ...
-
-## COULD IMPROVE
+Do not use emojis. Format your response as:
 
-- ...
-\`\`\`
-
-Omit any heading with no findings. End with a one-line summary like \`OVERALL: <terse assessment>\`.
+## MUST FIX
+[List critical issues, or "None"]
 
-## Output discipline
+## SHOULD FIX
+[List important issues, or "None"]
 
-- 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.`;
+## COULD IMPROVE
+[List minor suggestions, or "None"]`;
 //# sourceMappingURL=style-check.js.map

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

@@ -9,21 +9,56 @@
  * - CTS-PLAN-2: outline reviewer output structure (categorized findings + verdict)
  */
 import { z } from "zod";
+export declare const CustomerSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+}, {
+    name: string;
+    description: string;
+}>;
+export type Customer = z.infer<typeof CustomerSchema>;
 export declare const AreaSchema: z.ZodObject<{
     name: z.ZodString;
     description: z.ZodString;
     prefix: z.ZodString;
     files: z.ZodArray<z.ZodString, "many">;
+    /**
+     * Customers this area serves — at least one. Each customer is a *user* of
+     * the software (not a contributor to its codebase). The specifier will use
+     * one of these as the persona it grounds the area's requirements in.
+     * See CTS-PLAN-1 (customer threading).
+     */
+    customers: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        description: string;
+    }, {
+        name: string;
+        description: string;
+    }>, "many">;
 }, "strip", z.ZodTypeAny, {
     prefix: string;
     files: string[];
     name: string;
     description: string;
+    customers: {
+        name: string;
+        description: string;
+    }[];
 }, {
     prefix: string;
     files: string[];
     name: string;
     description: string;
+    customers: {
+        name: string;
+        description: string;
+    }[];
 }>;
 export type Area = z.infer<typeof AreaSchema>;
 export declare const OutlineSchema: z.ZodObject<{
@@ -35,16 +70,40 @@ export declare const OutlineSchema: z.ZodObject<{
         description: z.ZodString;
         prefix: z.ZodString;
         files: z.ZodArray<z.ZodString, "many">;
+        /**
+         * Customers this area serves — at least one. Each customer is a *user* of
+         * the software (not a contributor to its codebase). The specifier will use
+         * one of these as the persona it grounds the area's requirements in.
+         * See CTS-PLAN-1 (customer threading).
+         */
+        customers: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            name: string;
+            description: string;
+        }, {
+            name: string;
+            description: string;
+        }>, "many">;
     }, "strip", z.ZodTypeAny, {
         prefix: string;
         files: string[];
         name: string;
         description: string;
+        customers: {
+            name: string;
+            description: string;
+        }[];
     }, {
         prefix: string;
         files: string[];
         name: string;
         description: string;
+        customers: {
+            name: string;
+            description: string;
+        }[];
     }>, "many">;
 }, "strip", z.ZodTypeAny, {
     title: string;
@@ -55,6 +114,10 @@ export declare const OutlineSchema: z.ZodObject<{
         files: string[];
         name: string;
         description: string;
+        customers: {
+            name: string;
+            description: string;
+        }[];
     }[];
 }, {
     title: string;
@@ -65,6 +128,10 @@ export declare const OutlineSchema: z.ZodObject<{
         files: string[];
         name: string;
         description: string;
+        customers: {
+            name: string;
+            description: string;
+        }[];
     }[];
 }>;
 export type Outline = z.infer<typeof OutlineSchema>;
@@ -104,8 +171,25 @@ export declare const OUTLINE_JSON_SCHEMA: {
                             readonly type: "string";
                         };
                     };
+                    readonly customers: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly type: "object";
+                            readonly properties: {
+                                readonly name: {
+                                    readonly type: "string";
+                                };
+                                readonly description: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly required: readonly ["name", "description"];
+                            readonly additionalProperties: false;
+                        };
+                    };
                 };
-                readonly required: readonly ["name", "description", "prefix", "files"];
+                readonly required: readonly ["name", "description", "prefix", "files", "customers"];
                 readonly additionalProperties: false;
             };
         };
@@ -253,5 +337,380 @@ export declare const SPEC_REVIEW_JSON_SCHEMA: {
     readonly required: readonly ["coverage_gaps", "framing_errors", "cross_area_issues", "internal_mechanics_drift", "revisions", "verdict"];
     readonly additionalProperties: false;
 };
+export declare const ConversationalCustomerSchema: z.ZodObject<{
+    description: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+}, {
+    description: string;
+}>;
+export type ConversationalCustomer = z.infer<typeof ConversationalCustomerSchema>;
+/**
+ * One entry in the review thread (project-level or per-area). Discriminated
+ * on `result`:
+ *
+ * - `approved`: no revisions required.
+ * - `needs-revision`: must include a non-empty `revisions` list — each
+ *   entry is a clear, actionable instruction for the next planner pass.
+ */
+export declare const ConversationalReviewEntrySchema: 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";
+}>]>;
+export type ConversationalReviewEntry = z.infer<typeof ConversationalReviewEntrySchema>;
+/**
+ * Review state. Used both at the project level (outline.review) and per
+ * area (area.review). `result` mirrors the latest thread entry's result
+ * so callers can query state without walking the thread.
+ */
+export declare const ConversationalReviewSchema: 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";
+    })[];
+}>;
+export type ConversationalReview = z.infer<typeof ConversationalReviewSchema>;
+export declare const ConversationalAreaSchema: z.ZodObject<{
+    name: z.ZodString;
+    prefix: z.ZodString;
+    description: z.ZodString;
+    source_files: z.ZodArray<z.ZodString, "many">;
+    customers: z.ZodArray<z.ZodObject<{
+        description: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        description: string;
+    }, {
+        description: string;
+    }>, "many">;
+    /**
+     * Per-area review state — same shape as the project-level review.
+     * Optional: planner output doesn't include it; CA adds it after reviewing
+     * a partial. Tracks the per-area iteration loop (specify → review →
+     * editor → re-review → approved) the same way `outline.review` tracks
+     * the outline iteration loop.
+     */
+    review: 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";
+        })[];
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    prefix: string;
+    name: string;
+    description: string;
+    customers: {
+        description: string;
+    }[];
+    source_files: string[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}, {
+    prefix: string;
+    name: string;
+    description: string;
+    customers: {
+        description: string;
+    }[];
+    source_files: string[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}>;
+export type ConversationalArea = z.infer<typeof ConversationalAreaSchema>;
+export declare const ConversationalOutlineSchema: z.ZodObject<{
+    title: z.ZodString;
+    defaultPrefix: z.ZodString;
+    summary: z.ZodString;
+    review: 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;
+        description: z.ZodString;
+        source_files: z.ZodArray<z.ZodString, "many">;
+        customers: z.ZodArray<z.ZodObject<{
+            description: z.ZodString;
+        }, "strip", z.ZodTypeAny, {
+            description: string;
+        }, {
+            description: string;
+        }>, "many">;
+        /**
+         * Per-area review state — same shape as the project-level review.
+         * Optional: planner output doesn't include it; CA adds it after reviewing
+         * a partial. Tracks the per-area iteration loop (specify → review →
+         * editor → re-review → approved) the same way `outline.review` tracks
+         * the outline iteration loop.
+         */
+        review: 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";
+            })[];
+        }>>;
+    }, "strip", z.ZodTypeAny, {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }, {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}, {
+    title: string;
+    defaultPrefix: string;
+    summary: string;
+    areas: {
+        prefix: string;
+        name: string;
+        description: string;
+        customers: {
+            description: string;
+        }[];
+        source_files: string[];
+        review?: {
+            result: "approved" | "needs-revision";
+            thread: ({
+                result: "approved";
+            } | {
+                revisions: string[];
+                result: "needs-revision";
+            })[];
+        } | undefined;
+    }[];
+    review?: {
+        result: "approved" | "needs-revision";
+        thread: ({
+            result: "approved";
+        } | {
+            revisions: string[];
+            result: "needs-revision";
+        })[];
+    } | undefined;
+}>;
+export type ConversationalOutline = z.infer<typeof ConversationalOutlineSchema>;
+/**
+ * Parse YAML text against the conversational outline schema. Throws with
+ * a descriptive message on parse or validation failure.
+ */
+export declare function parseConversationalOutline(text: string): ConversationalOutline;
+/**
+ * Adapt a conversational orchestrator outline to the legacy Outline shape
+ * for use with stages that still take the legacy schema (compose, present).
+ *
+ * Discards orchestrator-only fields (review); maps `source_files` → `files`;
+ * bridges the customer-shape difference by synthesizing a `name` from each
+ * conversational customer's description.
+ */
+export declare function conversationalOutlineToLegacy(outline: ConversationalOutline): Outline;
+/**
+ * Serialize a conversational outline back to YAML text. Uses literal-block
+ * multi-line strings (`|`) where possible for readability.
+ */
+export declare function stringifyConversationalOutline(outline: ConversationalOutline): string;
 export declare function parseSpecReview(text: string): SpecReview;
 //# sourceMappingURL=schemas.d.ts.map