@popoverai/dotrequirements 0.26.2 → 0.27.0

package/dist/commands/review-test.js

@@ -4,14 +4,32 @@ import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/
 import { findRequirementsInFile } from "../requirements/grep.js";
 import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
-export async function reviewTestCommand(testFilePath) {
+/**
+ * Judgment instructions for local-mode test review. Mirrors the hosted
+ * review's semantic framing: test anatomy (setup, actions, assertions)
+ * checked against requirement anatomy (preconditions, triggers, outcomes).
+ */
+const REVIEW_INSTRUCTIONS = `You are the reviewer. Judge whether the test file below validates what its referenced requirements specify, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (semantic gaps are MUST FIX; categorize other findings by their own severity). Focus on gaps and give actionable suggestions.
+
+For each requirement reference, check:
+- **Setup vs preconditions** — does the test establish the state the requirement describes (e.g. "a registered user" backed by actual data, not mocked away)?
+- **Actions vs triggers** — does the test exercise the specified behavior with the specified inputs?
+- **Assertions vs outcomes** — does the test verify the specified outcomes (no tautologies), and does it cover every distinct outcome the requirement lists?
+- Note over-testing (validating behavior the requirement doesn't specify) without treating it as an error.
+- When a test's level doesn't fit its requirement (e.g. a unit test referencing an end-to-end requirement), suggest scoping the reference or a different test level — with specific guidance.`;
+export async function reviewTestCommand(testFilePath, options = {}) {
     const workspaceRoot = process.cwd();
     const fullPath = resolve(workspaceRoot, testFilePath);
-    // CLI-REVIEW-1.5: missing file → error + non-zero exit
+    // CLI-REVIEW-1.5: --source accepts only local|cloud
+    const source = options.source ?? "local";
+    if (source !== "local" && source !== "cloud") {
+        throw new Error(`Invalid --source value: ${options.source}. Expected "local" or "cloud".`);
+    }
+    // CLI-REVIEW-1.3: missing file → error + non-zero exit
     if (!existsSync(fullPath)) {
         throw new Error(`File not found: ${testFilePath}`);
     }
-    // CLI-REVIEW-1.6: must be a test file
+    // CLI-REVIEW-1.4: must be a test file
     if (!/\.(test|spec)\.(js|jsx|ts|tsx)$/.test(testFilePath)) {
         throw new Error(`File must be a test file: *.{test,spec}.{js,jsx,ts,tsx} — got ${testFilePath}`);
     }
@@ -30,6 +48,9 @@ export async function reviewTestCommand(testFilePath) {
     // resolve instead of being dropped.
     const { flattened } = await loadAllRequirements(workspaceRoot);
     const rootToTestedIds = new Map();
+    // CLI-REVIEW-1.2: references whose root resolves to no workspace
+    // requirement are reported as missing (in every mode)
+    const missingIds = [];
     for (const reqId of requirementIds) {
         const dotIndex = reqId.indexOf(".");
         const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
@@ -40,7 +61,11 @@ export async function reviewTestCommand(testFilePath) {
             }
             rootToTestedIds.get(req.rootId).add(reqId);
         }
+        else {
+            missingIds.push(reqId);
+        }
     }
+    missingIds.sort();
     const requirements = [];
     for (const [rootId, testedIds] of rootToTestedIds) {
         const tree = getRequirementTree(flattened, rootId);
@@ -50,7 +75,64 @@ export async function reviewTestCommand(testFilePath) {
             testedIds: Array.from(testedIds).sort(),
         });
     }
-    // CLI-REVIEW-1.6: cloud credentials required
+    if (source === "cloud") {
+        await runCloudReview({
+            workspaceRoot,
+            testFilePath,
+            testFileContents,
+            requirements,
+            missingIds,
+        });
+        return;
+    }
+    emitReviewMaterials({
+        testFilePath,
+        testFileContents,
+        requirements,
+        missingIds,
+    });
+}
+/**
+ * CLI-REVIEW-2: local (default) mode — emit judgment-ready review materials
+ * for the calling agent (typically a dispatched review subagent). No cloud
+ * credentials required.
+ */
+function emitReviewMaterials(params) {
+    const { testFilePath, testFileContents, requirements, missingIds } = params;
+    console.log(`# Test Review Materials for ${testFilePath}\n`);
+    console.log(`## Judgment instructions\n`);
+    console.log(REVIEW_INSTRUCTIONS);
+    // CLI-REVIEW-2.0: resolved requirement trees bundled with the test contents
+    console.log(`\n## Referenced requirements\n`);
+    if (requirements.length === 0) {
+        console.log("(none resolved — the test file references no workspace requirements)");
+    }
+    else {
+        for (const req of requirements) {
+            console.log(`### ${req.id} (tested: ${req.testedIds.join(", ")})\n`);
+            console.log(req.content);
+            console.log("");
+        }
+    }
+    // CLI-REVIEW-1.2: missing references reported in the output
+    if (missingIds.length > 0) {
+        console.log(`## Missing requirement references\n`);
+        console.log(`These references resolve to no requirement in this workspace — flag them in your findings:`);
+        for (const id of missingIds) {
+            console.log(`- ${id}`);
+        }
+        console.log("");
+    }
+    console.log(`## Test file under review (${testFilePath})\n`);
+    console.log(testFileContents);
+}
+/**
+ * CLI-REVIEW-3: --source cloud — send the bundle to the hosted review
+ * endpoint and print the returned feedback. Requires cloud credentials.
+ */
+async function runCloudReview(params) {
+    const { workspaceRoot, testFilePath, testFileContents, requirements, missingIds, } = params;
+    // CLI-REVIEW-3.2: cloud credentials required
     let projectId;
     let projectSecret;
     try {
@@ -62,22 +144,34 @@ export async function reviewTestCommand(testFilePath) {
         throw new Error(`Test review requires cloud credentials. Run \`dotrequirements link\` to connect this project to the cloud.\n` +
             `(${error instanceof Error ? error.message : String(error)})`);
     }
-    // CLI-REVIEW-1.2 / .3 / .4 / .7 / .8: dispatch to the hosted endpoint
+    // CLI-REVIEW-3.0 / .1 / .3: dispatch to the hosted endpoint
     const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
     let feedback;
+    let quotaWarning;
     try {
-        feedback = await fetchReviewTestFeedback({
+        ({ feedback, quotaWarning } = await fetchReviewTestFeedback({
             apiBaseUrl,
             projectId,
             projectSecret,
             testFileContents,
             requirements,
-        });
+        }));
     }
     catch (error) {
         throw new Error(`Test review failed: ${error instanceof Error ? error.message : String(error)}`);
     }
     console.log(`Test Review Results for ${testFilePath}\n`);
     console.log(feedback);
+    // LIMITS-5.2 / 5.2.0: the 80–99% quota warning prints with the result
+    if (quotaWarning) {
+        console.log(`\n⚠ ${quotaWarning}`);
+    }
+    // CLI-REVIEW-1.2: missing references reported in every mode
+    if (missingIds.length > 0) {
+        console.log(`\nMissing requirement references (not in this workspace):`);
+        for (const id of missingIds) {
+            console.log(`- ${id}`);
+        }
+    }
 }
 //# sourceMappingURL=review-test.js.map

package/dist/commands/style-check.d.ts

@@ -1,6 +1,7 @@
 interface StyleCheckOptions {
     keys?: string[];
     model?: string;
+    source?: string;
 }
 export declare function styleCheckCommand(filePath: string, options: StyleCheckOptions): Promise<void>;
 export {};

package/dist/commands/style-check.js

@@ -1,16 +1,44 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, } from "../requirements/cloud-ai.js";
-import { filterRequirementsByKeys } from "../requirements/index.js";
-import { getProjectCredentials } from "../utils/project-settings.js";
+import { DEFAULT_API_BASE_URL, fetchStyleCheckFeedback, getProjectContext, } from "../requirements/cloud-ai.js";
+import { filterRequirementsByKeys, loadAllRequirements, } from "../requirements/index.js";
+import { generateStyleGuideBody, readLocalStyleGuide, } from "../requirements/style-guide.js";
+import { findProjectRoot, getProjectCredentials, } from "../utils/project-settings.js";
+const CONVEX_URL = "https://data.dotrequirements.io";
+/**
+ * Judgment instructions for test-file style review in local mode. Mirrors the
+ * hosted test-style rubric (PROMPT-STYLE-TESTS-*): requirement() usage,
+ * comment discipline, structure, coverage-comment red flags, and semantic
+ * alignment between test anatomy and requirement anatomy.
+ */
+const TEST_STYLE_INSTRUCTIONS = `You are the reviewer. Judge the test file below against these test-style conventions, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (categorize each finding by its own severity; semantic gaps are MUST FIX). Focus on gaps and give actionable suggestions.
+
+- \`requirement()\` is used AS the description parameter of \`test()\`, \`describe()\`, or \`it()\` — flag requirement() calls placed in test bodies, and plain-string descriptions that should reference a requirement.
+- Comments describe what the test implementation does — flag comments that copy requirement text verbatim (the requirement() reference already carries that meaning). Tests need no comments at all.
+- Structured requirements (Given/When/Then trees) are tested with nested describe/it blocks; simple requirements need no extra nesting.
+- Flag comments that document requirement coverage (e.g. "Requirements coverage: AUTH-9.0 ✓") — coverage lives in the harness, not comments; a second source of truth drifts.
+- Test setup should establish the preconditions the referenced requirement describes; actions should exercise the specified behavior with the specified inputs; assertions should verify the specified outcomes (not tautologies like expect(true).toBe(true)). Flag requirements whose distinct outcomes are only partially validated; note over-testing without treating it as an error.
+- When a test's level doesn't fit its requirement (e.g. a unit test referencing an end-to-end requirement), suggest scoping the reference or a different test level — with specific guidance, not generic observations.
+
+The referenced requirement trees are not bundled here; if you need one, read it from \`.requirements/\` or run \`dotreq get <KEY>\`. For a full semantic review of tests against their requirements, \`dotreq review-test <file>\` is the dedicated verb.`;
+const REQUIREMENTS_STYLE_INSTRUCTIONS = `You are the reviewer. Judge the requirements below against the style guide above, then report findings under the headings MUST FIX / SHOULD FIX / COULD IMPROVE (categorize each finding by its own severity). Focus on gaps and give actionable suggestions rather than just listing problems.`;
 export async function styleCheckCommand(filePath, options) {
     const workspaceRoot = process.cwd();
     const fullPath = resolve(workspaceRoot, filePath);
-    // CLI-STYLE-1.5: missing file → error + non-zero exit
+    // CLI-STYLE-1.6: --source accepts only local|cloud
+    const source = options.source ?? "local";
+    if (source !== "local" && source !== "cloud") {
+        throw new Error(`Invalid --source value: ${options.source}. Expected "local" or "cloud".`);
+    }
+    // CLI-STYLE-1.7: --model configures the hosted review only
+    if (options.model && source !== "cloud") {
+        throw new Error(`--model applies to cloud review only. Add --source cloud to choose a review model.`);
+    }
+    // CLI-STYLE-1.4: missing file → error + non-zero exit
     if (!existsSync(fullPath)) {
         throw new Error(`File not found: ${filePath}`);
     }
-    // CLI-STYLE-1.0 / .1 / .6: file-type detection
+    // CLI-STYLE-1.0 / .1 / .5: file-type detection
     const isRequirementsFile = filePath.endsWith(".requirements.md");
     const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(filePath);
     if (!isRequirementsFile && !isTestFile) {
@@ -35,7 +63,100 @@ export async function styleCheckCommand(filePath, options) {
             scopeNote = `\nNote: Some specified keys were not found in the file: ${missingKeys.join(", ")}`;
         }
     }
-    // CLI-STYLE-1.7: credentials are required
+    const scopeLabel = options.keys && options.keys.length > 0
+        ? ` (${options.keys.join(", ")})`
+        : "";
+    if (source === "cloud") {
+        await runCloudStyleCheck({
+            workspaceRoot,
+            filePath,
+            fileContentsToCheck,
+            fileType,
+            model: options.model,
+            scopeLabel,
+            scopeNote,
+        });
+        return;
+    }
+    await emitStyleMaterials({
+        workspaceRoot,
+        filePath,
+        fileContentsToCheck,
+        fileType,
+        scopeLabel,
+        scopeNote,
+    });
+}
+/**
+ * CLI-STYLE-2: local (default) mode — emit judgment-ready review materials
+ * for the calling agent (typically a dispatched review subagent). No cloud
+ * credentials required.
+ */
+async function emitStyleMaterials(params) {
+    const { workspaceRoot, filePath, fileContentsToCheck, fileType, scopeLabel, scopeNote, } = params;
+    console.log(`# Style Review Materials for ${filePath}${scopeLabel}\n`);
+    if (fileType === "requirements") {
+        // CLI-STYLE-2.0: compose the style guide the same way
+        // create-requirement-document does.
+        // CLI-STYLE-2.0.0: a project STYLE.md, when present, IS the guide.
+        const localStyleGuide = readLocalStyleGuide(workspaceRoot);
+        let guide;
+        if (localStyleGuide?.trim()) {
+            guide = localStyleGuide;
+        }
+        else {
+            // CLI-STYLE-2.0.1: otherwise generate from bundled defaults, workspace
+            // patterns, and cloud custom guidance when linked.
+            let requirements = [];
+            try {
+                const result = await loadAllRequirements(workspaceRoot);
+                requirements = result.flattened;
+            }
+            catch {
+                // No requirements in the workspace yet — defaults still apply
+            }
+            // CLI-STYLE-2.3 / .4: credentials are optional; cloud custom guidance is
+            // silently omitted when unlinked or unreachable.
+            let customStyleGuidance = null;
+            const projectRoot = findProjectRoot(workspaceRoot);
+            if (projectRoot) {
+                try {
+                    const { projectId, projectSecret } = getProjectCredentials(workspaceRoot);
+                    const contextData = await getProjectContext(projectId, projectSecret, CONVEX_URL);
+                    customStyleGuidance = contextData?.requirementsStyleContext ?? null;
+                }
+                catch {
+                    // Unlinked or cloud unavailable — fall through with defaults
+                }
+            }
+            guide = generateStyleGuideBody({ requirements, customStyleGuidance });
+        }
+        console.log(`## Style guide\n`);
+        console.log(guide);
+        console.log(`\n## Judgment instructions\n`);
+        console.log(REQUIREMENTS_STYLE_INSTRUCTIONS);
+    }
+    else {
+        console.log(`## Judgment instructions\n`);
+        console.log(TEST_STYLE_INSTRUCTIONS);
+    }
+    // CLI-STYLE-2.1: the content under review (keys-filtered when --keys given)
+    const heading = fileType === "requirements"
+        ? "Requirements under review"
+        : "Test file under review";
+    console.log(`\n## ${heading} (${filePath})\n`);
+    console.log(fileContentsToCheck);
+    if (scopeNote) {
+        console.log(scopeNote);
+    }
+}
+/**
+ * CLI-STYLE-3: --source cloud — send the file to the hosted review endpoint
+ * and print the returned feedback. Requires cloud credentials.
+ */
+async function runCloudStyleCheck(params) {
+    const { workspaceRoot, filePath, fileContentsToCheck, fileType, model, scopeLabel, scopeNote, } = params;
+    // CLI-STYLE-3.2: credentials are required
     let projectId;
     let projectSecret;
     try {
@@ -47,29 +168,32 @@ export async function styleCheckCommand(filePath, options) {
         throw new Error(`Style check requires cloud credentials. Run \`dotrequirements link\` to connect this project to the cloud.\n` +
             `(${error instanceof Error ? error.message : String(error)})`);
     }
-    // CLI-STYLE-1.4 / .8 / .9: dispatch to the hosted endpoint
+    // CLI-STYLE-3.0 / .1 / .3: dispatch to the hosted endpoint
     const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL ?? DEFAULT_API_BASE_URL;
     let feedback;
+    let quotaWarning;
     try {
-        feedback = await fetchStyleCheckFeedback({
+        ({ feedback, quotaWarning } = await fetchStyleCheckFeedback({
             apiBaseUrl,
             projectId,
             projectSecret,
             fileContents: fileContentsToCheck,
             fileType,
-            model: options.model,
-        });
+            model,
+        }));
     }
     catch (error) {
         throw new Error(`Style check failed: ${error instanceof Error ? error.message : String(error)}`);
     }
-    const scopeLabel = options.keys && options.keys.length > 0
-        ? ` (${options.keys.join(", ")})`
-        : "";
+    // CLI-STYLE-3.4: hosted feedback arrives severity-categorized
     console.log(`Style Check Results for ${filePath}${scopeLabel}\n`);
     console.log(feedback);
     if (scopeNote) {
         console.log(scopeNote);
     }
+    // LIMITS-5.2 / 5.2.0: the 80–99% quota warning prints with the result
+    if (quotaWarning) {
+        console.log(`\n⚠ ${quotaWarning}`);
+    }
 }
 //# sourceMappingURL=style-check.js.map

package/dist/convex.d.ts

@@ -55,11 +55,9 @@ export declare const api: {
         };
         mutations: {
             createInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            acceptInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
-    polar: {
-        acceptTeamInvite: import("convex/server").FunctionReference<"action", "public", any, any, string | undefined>;
-    };
     projectSecrets: {
         queries: {
             getOwnSecret: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;

package/dist/convex.js

@@ -61,11 +61,11 @@ export const api = {
         },
         mutations: {
             createInvite: mutation("teamInvites/mutations:createInvite"),
+            // Joins the team and reconciles paid-team seats via a scheduled sync
+            // (POLAR-SEATS-3). Replaced the deleted polar:acceptTeamInvite action.
+            acceptInvite: mutation("teamInvites/mutations:acceptInvite"),
         },
     },
-    polar: {
-        acceptTeamInvite: action("polar:acceptTeamInvite"),
-    },
     projectSecrets: {
         queries: {
             getOwnSecret: query("projectSecrets/queries:getOwnSecret"),

package/dist/requirements/cloud-ai.d.ts

@@ -22,11 +22,23 @@ export interface StyleCheckParams {
     model?: string;
 }
 /**
- * POST to `/api/style-check`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * Feedback plus the optional LIMITS-5.2 quota warning ("You've used X% of
+ * your AI quota this billing cycle."). The warning is present when the
+ * team is at 80–99% of its AI allowance; callers print it alongside the
+ * feedback so the eventual quota wall never arrives unannounced. Older
+ * servers simply omit the field.
  */
-export declare function fetchStyleCheckFeedback(params: StyleCheckParams): Promise<string>;
+export interface CloudAIFeedback {
+    feedback: string;
+    quotaWarning: string | null;
+}
+/**
+ * POST to `/api/style-check`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
+ */
+export declare function fetchStyleCheckFeedback(params: StyleCheckParams): Promise<CloudAIFeedback>;
 export interface ReviewTestParams {
     apiBaseUrl: string;
     projectId: string;
@@ -39,11 +51,12 @@ export interface ReviewTestParams {
     }>;
 }
 /**
- * POST to `/api/review-test`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/review-test`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
-export declare function fetchReviewTestFeedback(params: ReviewTestParams): Promise<string>;
+export declare function fetchReviewTestFeedback(params: ReviewTestParams): Promise<CloudAIFeedback>;
 export interface ProjectContext {
     projectContext: string | null;
     requirementsStyleContext: string | null;

package/dist/requirements/cloud-ai.js

@@ -14,9 +14,10 @@
  */
 export const DEFAULT_API_BASE_URL = "https://app.dotrequirements.io";
 /**
- * POST to `/api/style-check`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/style-check`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
 export async function fetchStyleCheckFeedback(params) {
     const response = await fetch(`${params.apiBaseUrl}/api/style-check`, {
@@ -35,12 +36,13 @@ export async function fetchStyleCheckFeedback(params) {
         throw new Error(errorData.error || response.statusText);
     }
     const data = (await response.json());
-    return data.feedback;
+    return { feedback: data.feedback, quotaWarning: data.quotaWarning ?? null };
 }
 /**
- * POST to `/api/review-test`. Returns the feedback text on success;
- * throws an Error with the underlying failure reason on a non-OK
- * response or a network error.
+ * POST to `/api/review-test`. Returns the feedback (and any quota warning)
+ * on success; throws an Error with the underlying failure reason on a
+ * non-OK response or a network error — including the LIMITS-5.1
+ * quota-exceeded error, whose message carries the billing-page upgrade link.
  */
 export async function fetchReviewTestFeedback(params) {
     const response = await fetch(`${params.apiBaseUrl}/api/review-test`, {
@@ -58,7 +60,7 @@ export async function fetchReviewTestFeedback(params) {
         throw new Error(errorData.error || response.statusText);
     }
     const data = (await response.json());
-    return data.feedback;
+    return { feedback: data.feedback, quotaWarning: data.quotaWarning ?? null };
 }
 /**
  * Query Convex for project-level AI context (project description and

package/dist/schema/parser-core.d.ts

@@ -15,6 +15,19 @@ export declare const DELIMITER_PATTERN = "(?:\u2192|->)";
  * Parse a criterion line in "position. Label → content" format.
  * Example: "0. Given → user has valid credentials"
  * Also supports optional label: "0. → user has valid credentials"
+ *
+ * This is the canonical criterion grammar (SYNC-KEY-1.4). The web editor's
+ * markdown-conversion parser mirrors this exact behavior; keep them in sync.
+ *
+ * Two behaviors are load-bearing:
+ *  - Split on the FIRST delimiter only, so an arrow inside the content
+ *    ("maps A -> B") is preserved verbatim rather than being re-consumed as a
+ *    label boundary. Everything before the first delimiter is the (optional,
+ *    freeform — custom labels are supported, see MARKDOWN_SCHEMA) label;
+ *    everything after is content.
+ *  - An empty criterion ("0. → ") is a valid criterion with content "", not a
+ *    parse failure. Returning null here would make parseRequirementBlocksFromMarkdown
+ *    reject the whole block, and would drop the criterion (and its subtree) on load.
  */
 export declare function parseCriterionLine(line: string, delimiter?: string): ParsedCriterion | null;
 /**

package/dist/schema/parser-core.js

@@ -11,24 +11,48 @@ import { ValidationError, validateKey, } from "./schemas.js";
  */
 export const DEFAULT_DELIMITER = "→";
 export const DELIMITER_PATTERN = "(?:→|->)"; // Non-capturing group for both Unicode and ASCII
+// Compiled once for the common (default-delimiter) path so parseCriterionLine
+// doesn't rebuild the same RegExp on every line.
+const DEFAULT_DELIMITER_REGEX = new RegExp(DELIMITER_PATTERN);
 /**
  * Parse a criterion line in "position. Label → content" format.
  * Example: "0. Given → user has valid credentials"
  * Also supports optional label: "0. → user has valid credentials"
+ *
+ * This is the canonical criterion grammar (SYNC-KEY-1.4). The web editor's
+ * markdown-conversion parser mirrors this exact behavior; keep them in sync.
+ *
+ * Two behaviors are load-bearing:
+ *  - Split on the FIRST delimiter only, so an arrow inside the content
+ *    ("maps A -> B") is preserved verbatim rather than being re-consumed as a
+ *    label boundary. Everything before the first delimiter is the (optional,
+ *    freeform — custom labels are supported, see MARKDOWN_SCHEMA) label;
+ *    everything after is content.
+ *  - An empty criterion ("0. → ") is a valid criterion with content "", not a
+ *    parse failure. Returning null here would make parseRequirementBlocksFromMarkdown
+ *    reject the whole block, and would drop the criterion (and its subtree) on load.
  */
 export function parseCriterionLine(line, delimiter = DELIMITER_PATTERN) {
-    // Match: position + period + space + optional(label + space) + delimiter + space + content
-    // Position can be: 0, 1.0, 2.3.1, etc.
-    // Label can contain any characters except the delimiter
-    const pattern = new RegExp(`^\\s*(\\d+(?:\\.\\d+)*)\\.\\s*(?:(.+?)\\s+)?${delimiter}\\s*(.+)$`);
-    const match = line.match(pattern);
-    if (!match) {
+    // Position prefix: "0.", "1.0.", "2.3.1." — required for a criterion line.
+    const positionMatch = line.match(/^\s*(\d+(?:\.\d+)*)\.\s*/);
+    if (!positionMatch) {
+        return null;
+    }
+    const rest = line.slice(positionMatch[0].length);
+    const delimiterMatch = rest.match(delimiter === DELIMITER_PATTERN
+        ? DEFAULT_DELIMITER_REGEX
+        : new RegExp(delimiter));
+    if (!delimiterMatch || delimiterMatch.index === undefined) {
         return null;
     }
+    const label = rest.slice(0, delimiterMatch.index).trim();
+    const content = rest
+        .slice(delimiterMatch.index + delimiterMatch[0].length)
+        .trim();
     return {
-        position: match[1],
-        label: match[2] ? match[2].trim() : "", // Preserve original case, empty if no label
-        content: match[3].trim(),
+        position: positionMatch[1],
+        label, // Preserve original case; freeform (empty when no label)
+        content, // May be "" for an empty criterion
     };
 }
 /**

package/dist/templates/context-file-section.md

@@ -10,13 +10,14 @@ requirements, so your plan should too.
 
 **ALWAYS follow this workflow when changing system behavior** (new features, bug fixes, any behavioral change). Only pure refactoring (same behavior, different code) may skip requirements.
 
-1. **Find or write requirements** - Check `.requirements/` for existing specs; write new ones if needed
-2. **Style-check** - Run `mcp__dotrequirements__style_check` on the file
-3. **Get approval** - Present requirements, wait for go-ahead
-4. **Implement** - Build the feature
-5. **Write tests** - Reference requirements with `requirement()`
-6. **Run tests** - Verify everything passes
-7. **Review tests** - Run `mcp__dotrequirements__review_test` to validate coverage
+1. **Find or write requirements** - Check `.requirements/` for existing specs (`dotreq search`, `dotreq get`, `dotreq list`); write new ones if needed (`dotreq create-requirement-document` prints the template and style guide)
+2. **Style-review** - Dispatch a subagent to run `dotreq style-check <file>` and judge the requirements against the style guide it emits. If this platform cannot dispatch subagents, run the command and perform the review in this conversation.
+3. **Validate** - Run `dotreq validate` to check syntax
+4. **Get approval** - Present requirements, wait for go-ahead
+5. **Implement** - Build the feature
+6. **Write tests** - Reference requirements with `requirement()`
+7. **Run tests** - Verify everything passes
+8. **Test-review** - Dispatch a subagent to run `dotreq review-test <test-file>` and judge the tests against the materials it emits. Same fallback: no subagent support, review in this conversation.
 
 ### Requirements Syntax
 
@@ -31,7 +32,7 @@ DOMAIN-1: Short description of expected behavior
 - Criteria: `position. -> content` (optional label before the arrow)
 - Nesting: Indent with 2 spaces, use `x.y` position paths
 - Delimiter: `->` or `→`
-- **Key style**: Use sequential keys with a short domain prefix (`ORCHESTRATOR-1`, `ORCHESTRATOR-2`, ...) rather than semantic keys (`AUTONOMOUS-ADVANCE`). Sequential keys stay stable when a requirement gets reworded, so test references don't break. Call `create_requirement_document` for full key-naming guidance.
+- **Key style**: Use sequential keys with a short domain prefix (`ORCHESTRATOR-1`, `ORCHESTRATOR-2`, ...) rather than semantic keys (`AUTONOMOUS-ADVANCE`). Sequential keys stay stable when a requirement gets reworded, so test references don't break. Run `dotreq create-requirement-document` for full key-naming guidance.
 
 ### Test Usage
 
@@ -44,21 +45,23 @@ test(requirement('REQ-ID'), () => { /* test the requirement */ });
 test(requirement('REQ-ID.0'), () => { /* test specific criterion */ });
 ```
 
-### MCP Tools
+### CLI Verbs
 
 **Exploration:**
-- `list_requirements` - Overview of all requirements (set `untested: true` to filter to coverage gaps)
-- `get_requirement` - Requirement tree with test coverage
-- `search_requirements` - Search by text/regex
+- `dotreq list [--untested]` - Overview of all requirements (`--untested` filters to coverage gaps)
+- `dotreq get <id>` - Requirement tree with test coverage
+- `dotreq search <query> [--regex]` - Search by text/regex
+- `dotreq requirements-for <test-file>` - See requirements a test file covers
+- `dotreq tests-for <req-file>` - See test coverage for a requirements file
 
 **Authoring:**
-- `create_requirement_document` - Get template with format guidance
-- `validate_requirements` - Check syntax (works offline)
-- `style_check` - AI feedback on clarity
-- `push_requirements` - Sync to cloud
-
-**Testing:**
-- `get_requirements_by_test` - See requirements a test file covers
-- `list_requirements` (with `untested: true`) - Find requirements without tests
-- `report_coverage` - Get test coverage from local cache or cloud
-- `review_test` - Validate tests match requirement intent
+- `dotreq create-requirement-document [path]` - Print the template and style guide
+- `dotreq validate [glob]` - Check syntax (works offline)
+- `dotreq push [file]` - Sync to cloud (shows diff preview, then confirms)
+
+**Review (judgment runs in the dispatched subagent):**
+- `dotreq style-check <file>` - Emits the style guide + content for the reviewer to judge (`--source cloud` for hosted review)
+- `dotreq review-test <test-file>` - Emits referenced requirement trees + test content for the reviewer to judge (`--source cloud` for hosted review)
+
+**Coverage:**
+- `dotreq report [--source local|cloud]` - Test coverage report

package/dist/utils/context-file.d.ts

@@ -3,7 +3,11 @@
  */
 export declare function getContextFileName(platform: string): string | null;
 /**
- * Find the git root directory
+ * Find the git root directory.
+ *
+ * CONTEXT-FILE-6: in a worktree, .git is a FILE pointing at the main
+ * checkout — matching directories only would walk past it and resolve to
+ * the main checkout's root, landing the context file in the wrong tree.
  */
 export declare function findGitRoot(): Promise<string | null>;
 /**
@@ -39,8 +43,8 @@ export declare function getContextFilePath(platform: string): Promise<string | n
  * Build a user-facing message explaining that context file installation
  * was skipped because the current directory is not inside a git repository.
  *
- * The MCP server itself is configured separately, so this message is only
- * about the second step (writing the platform's context file).
+ * Writing the platform's context file is the whole of setup now, so a missing
+ * git root means nothing was installed.
  */
 export declare function buildNoGitRepoMessage(fileName: string): string;
 //# sourceMappingURL=context-file.d.ts.map