@popoverai/dotrequirements 0.26.1 → 0.27.0

package/dist/commands/pull.js

@@ -5,6 +5,7 @@ import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { findRequirementsFiles } from "../requirements/index.js";
 import { buildRequirementsFile } from "../schema/index.js";
+import { extractFrontmatterBlock } from "../schema/parser-core.js";
 import { brand } from "../utils/brand.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
 export async function pullCommand(options) {
@@ -94,12 +95,33 @@ export async function pullCommand(options) {
     }
     // Build index of existing files by document ID (search entire workspace)
     const existingFilesByDocId = await buildDocumentIdIndex(process.cwd());
+    // SYNC-WEB-CREATE-2.0: track paths claimed during this pull so colliding
+    // titles don't silently overwrite each other within one operation
+    const usedPaths = new Set(existingFilesByDocId.values());
     // Write each document as a Markdown file
     for (const doc of documents) {
         // Check if an existing file has this document ID
         const existingFilePath = existingFilesByDocId.get(doc.documentId);
-        const filePath = existingFilePath ??
-            path.join(requirementsDir, `${sanitizeFileName(doc.title)}.requirements.md`);
+        let filePath;
+        if (existingFilePath) {
+            filePath = existingFilePath;
+        }
+        else {
+            // SYNC-WEB-CREATE-2.1: an all-symbols title sanitizes to nothing —
+            // fall back to the document ID rather than a hidden ".requirements.md"
+            const baseName = sanitizeFileName(doc.title) || doc.documentId;
+            let candidate = path.join(requirementsDir, `${baseName}.requirements.md`);
+            // SYNC-WEB-CREATE-2.0: disambiguate later collisions with a numeric
+            // suffix; also avoid clobbering an on-disk file that belongs to a
+            // different (or no) document
+            let suffix = 2;
+            while (usedPaths.has(candidate) || fs.existsSync(candidate)) {
+                candidate = path.join(requirementsDir, `${baseName}-${suffix}.requirements.md`);
+                suffix++;
+            }
+            filePath = candidate;
+        }
+        usedPaths.add(filePath);
         const fileName = path.basename(filePath);
         // IMPORT-1: carry the CTS run marker forward from the existing local
         // file — pull rebuilds frontmatter from cloud data, and silently dropping
@@ -168,10 +190,21 @@ async function buildDocumentIdIndex(workspaceRoot) {
 /**
  * Extract document.id from a requirements file's frontmatter.
  * Returns undefined if the file can't be read or doesn't have a document ID.
+ * SYNC-DISCOVERY-3: only the leading YAML frontmatter block is consulted —
+ * a document id quoted in body prose or a fenced example must never mark
+ * the file as owning that document.
  */
 function extractDocumentIdFromFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, "utf-8");
+        const fileContent = fs.readFileSync(filePath, "utf-8");
+        // Isolate the leading ---...--- frontmatter block; no frontmatter means
+        // the file is unlinked to any cloud document (SYNC-DISCOVERY-3.2).
+        // Shared helper normalizes CRLF (SYNC-FORMAT-1) so a Windows-saved file
+        // keeps matching its document and is updated in place (SYNC-DISCOVERY-2.1).
+        const content = extractFrontmatterBlock(fileContent);
+        if (content === undefined) {
+            return undefined;
+        }
         // Match document.id in YAML frontmatter - handles both inline and nested formats
         // Inline: document: { id: "abc123", ... }
         // Nested (id: can appear at any position within the indented document block):

package/dist/commands/push.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { getConvexUrl } from "../config.js";
-import { dryRunPush, executePush, parseFilesForPush, } from "../push/index.js";
+import { dryRunPush, executePush, parseFilesForPushIndividually, } from "../push/index.js";
 import { findRequirementsFiles } from "../requirements/index.js";
 import { brand } from "../utils/brand.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
@@ -30,20 +30,30 @@ export async function pushCommand(file, options) {
             return;
         }
     }
-    // Parse all local files
+    // Parse local files. SYNC-FAIL-4: one invalid file is skipped while the
+    // rest of the batch still pushes — same helper as the MCP push handler.
     console.log("Parsing local requirements...");
-    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    const { parsedFiles, totalRequirements, parseFailures } = parseFilesForPushIndividually(filesToPush);
     // Log file parsing progress
     for (const file of parsedFiles) {
         const fileName = path.basename(file.filePath);
         const doc = file.metadata.document;
-        if (doc?.defaultPrefix && !file.metadata.document?.defaultPrefix) {
-            console.log(`  Reading ${fileName}...`);
+        console.log(`  Reading ${fileName}...`);
+        // DOC-HEADER-11.4: parseFilesForPush mutates the metadata when it infers
+        // the prefix, so the flag it returns is the only record of the inference
+        if (doc?.defaultPrefix && file.inferredDefaultPrefix) {
             console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
         }
-        else {
-            console.log(`  Reading ${fileName}...`);
+    }
+    // SYNC-FAIL-4.1: every file in the push failed to parse — report each
+    // skipped file, then fail honestly instead of dry-running nothing
+    if (parsedFiles.length === 0) {
+        for (const failure of parseFailures) {
+            console.log(`  ✗ Skipped ${path.basename(failure.filePath)}: ${failure.error}`);
         }
+        console.log("\nNo valid documents to push.");
+        process.exitCode = 1;
+        return;
     }
     console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
     // Build credentials
@@ -56,13 +66,19 @@ export async function pushCommand(file, options) {
     console.log("Validating documents...");
     const dryRunResult = await dryRunPush(parsedFiles, credentials);
     // Display unified summary
-    displayDryRunSummary(dryRunResult);
+    displayDryRunSummary(dryRunResult, parseFailures);
     // Check if there's anything to push
     const pushableCount = dryRunResult.updates.length +
         dryRunResult.creates.length +
         dryRunResult.notFound.length;
     if (pushableCount === 0) {
         console.log("No valid documents to push.");
+        // SYNC-FAIL-4.1: every file in the push was invalid — whether it failed
+        // local parse or dry-run validation — so the command must fail honestly,
+        // matching the MCP handler's merged rule
+        if (parseFailures.length > 0 || dryRunResult.invalid.length > 0) {
+            process.exitCode = 1;
+        }
         return;
     }
     // Single confirmation prompt
@@ -88,8 +104,9 @@ export async function pushCommand(file, options) {
     ]) {
         const fileName = path.basename(file.filePath);
         const isCreate = dryResult.action === "create" || dryResult.action === "not_found";
-        // Check if this file had an error
-        const error = result.errors.find((e) => e.fileName === fileName);
+        // Check if this file had an error — match by full path, since two pushed
+        // files can share a basename
+        const error = result.errors.find((e) => e.filePath === file.filePath);
         if (error) {
             console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
         }
@@ -100,6 +117,16 @@ export async function pushCommand(file, options) {
             console.log(`  ✓ Updated: ${fileName}`);
         }
     }
+    // SYNC-FAIL-2.1: the cloud save succeeded but the local file couldn't be
+    // updated — name the file, say the cloud is fine, and give the recovery
+    // step that re-links the file instead of minting a duplicate on retry
+    if (result.writeBackWarnings?.length > 0) {
+        console.log();
+        for (const warning of result.writeBackWarnings) {
+            console.log(`⚠ ${warning.fileName}: saved to the cloud, but the local file could not be updated (${warning.error}). ` +
+                `To avoid creating a duplicate, add "id: ${warning.documentId}" under "document:" in the frontmatter of ${warning.filePath}, then push again.`);
+        }
+    }
     // IMPORT-3: marker failures are loud but never fatal
     if (result.importWarnings.length > 0) {
         console.log();
@@ -148,7 +175,7 @@ export async function pushCommand(file, options) {
 /**
  * Display the dry run summary.
  */
-function displayDryRunSummary(dryRunResult) {
+function displayDryRunSummary(dryRunResult, parseFailures = []) {
     const { updates, creates, notFound, invalid, conflicts } = dryRunResult;
     console.log("\n=== Push Summary ===\n");
     if (updates.length > 0) {
@@ -179,11 +206,22 @@ function displayDryRunSummary(dryRunResult) {
         }
         console.log();
     }
-    if (invalid.length > 0) {
-        console.log(`Skipped - invalid files (${invalid.length}):`);
-        for (const { file, result } of invalid) {
-            const fileName = path.basename(file.filePath);
-            console.log(`  ✗ ${fileName}: ${result.error}`);
+    // SYNC-FAIL-4.0: local parse failures surface alongside dry-run invalids,
+    // each named by file, while the rest of the batch proceeds
+    const skipped = [
+        ...parseFailures.map((failure) => ({
+            fileName: path.basename(failure.filePath),
+            error: failure.error,
+        })),
+        ...invalid.map(({ file, result }) => ({
+            fileName: path.basename(file.filePath),
+            error: result.error,
+        })),
+    ];
+    if (skipped.length > 0) {
+        console.log(`Skipped - invalid files (${skipped.length}):`);
+        for (const { fileName, error } of skipped) {
+            console.log(`  ✗ ${fileName}: ${error}`);
         }
         console.log();
     }

package/dist/commands/report.js

@@ -36,8 +36,16 @@ export async function reportCommand(options) {
             `(${error instanceof Error ? error.message : String(error)})`);
     }
     if (options.requirement) {
-        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL);
-        console.log(printCloudRequirement(record, format));
+        // REPORT-CLOUD-1.7: --branch/--since apply to the requirement-scoped
+        // output too, not just the project-wide report
+        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL, {
+            branch: options.branch,
+            sinceTimestamp: options.since,
+        });
+        console.log(printCloudRequirement(record, format, {
+            branch: options.branch,
+            since: options.since,
+        }));
         return;
     }
     const record = await getProjectCoverage(projectId, projectSecret, CONVEX_URL, {
@@ -100,11 +108,18 @@ function formatLocalMarkdown(report) {
     }
     return out;
 }
-function printCloudRequirement(record, format) {
+function printCloudRequirement(record, format, filters) {
     if (format === "json") {
         return JSON.stringify({ source: "cloud", requirement: record }, null, 2);
     }
     if (!record.lastTestedAt) {
+        // REPORT-CLOUD-1.7: with filters in play, an empty record means nothing
+        // matched them — say so rather than implying the requirement was never
+        // tested at all
+        const filterNote = formatCloudFilters(filters);
+        if (filterNote) {
+            return `\n${record.requirementKey}: no coverage records match the requested filters (${filterNote.replace(/^Filters: /, "")}).\n`;
+        }
         return `\n${record.requirementKey}: never tested on the cloud-persisted record.\n`;
     }
     const lastTested = new Date(record.lastTestedAt).toISOString();

package/dist/commands/review-test.d.ts

@@ -1,2 +1,6 @@
-export declare function reviewTestCommand(testFilePath: string): Promise<void>;
+interface ReviewTestOptions {
+    source?: string;
+}
+export declare function reviewTestCommand(testFilePath: string, options?: ReviewTestOptions): Promise<void>;
+export {};
 //# sourceMappingURL=review-test.d.ts.map

package/dist/commands/review-test.js

@@ -1,38 +1,71 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/cloud-ai.js";
+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}`);
     }
     const testFileContents = readFileSync(fullPath, "utf-8");
-    // CLI-REVIEW-1.0: collect every requirement(...) call site
-    const requirementIdMatches = testFileContents.matchAll(/requirement\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g);
-    const requirementIds = new Set();
-    for (const match of requirementIdMatches) {
-        requirementIds.add(match[1]);
-    }
-    // CLI-REVIEW-1.1: resolve references against the workspace and bundle trees
+    // CLI-REVIEW-1.0: collect every requirement(...) call site via the shared
+    // AST-based extractor (as the MCP review handler does post-#43) so that
+    // multi-arg calls (`requirement("A", "B")`) and options-bearing calls
+    // (`requirement("A", { ... })`) are captured — the old single-string regex
+    // matched neither.
+    const references = await findRequirementsInFile(fullPath);
+    const requirementIds = new Set(references.map((ref) => ref.requirementId));
+    // CLI-REVIEW-1.1: resolve references against the workspace and bundle trees.
+    // A reference may be a bare root (`AUTH-1`), an index child (`AUTH-1.0`), or
+    // a label path (`AUTH-1.given`). Normalize each reference to its root id
+    // (the substring before the first dot) before matching so label-path refs
+    // 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 req = flattened.find((r) => r.id === reqId || r.rootId === reqId);
+        const dotIndex = reqId.indexOf(".");
+        const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
+        const req = flattened.find((r) => r.rootId === refRootId);
         if (req) {
             if (!rootToTestedIds.has(req.rootId)) {
                 rootToTestedIds.set(req.rootId, new Set());
             }
             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);
@@ -42,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 {
@@ -54,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