@popoverai/dotrequirements 0.26.1 → 0.26.2

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

@@ -16,6 +16,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { parseRequirementsFile } from "../schema/parser.js";
+import { stripFrontmatterBlock } from "../schema/parser-core.js";
 import { generateRunMarker } from "../schema/run-marker.js";
 import { sanitizeAreaName } from "./area-name.js";
 import { promptOverwriteChoice } from "./interactive.js";
@@ -187,11 +188,9 @@ async function resolveOverwriteAction(policy, path) {
  */
 function mergeContent(existingPath, newContent) {
     const existing = readFileSync(existingPath, "utf-8").trimEnd();
-    // Strip frontmatter from newContent (it would conflict with existing frontmatter)
-    const fmMatch = newContent.match(/^---\n[\s\S]+?\n---\n+/);
-    const body = fmMatch
-        ? newContent.slice(fmMatch[0].length).trimStart()
-        : newContent;
+    // Strip frontmatter from newContent (it would conflict with existing
+    // frontmatter) via the shared CRLF-normalizing helper.
+    const body = stripFrontmatterBlock(newContent).trimStart();
     return [
         existing,
         "",

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

@@ -87,8 +87,9 @@ function describeValidationError(err) {
         const parts = [err.message];
         let cursor = err.cause;
         while (cursor instanceof Error) {
-            // Don't repeat the same message twice if the wrapper just rethrew.
-            if (cursor.message && cursor.message !== parts[parts.length - 1]) {
+            // Don't repeat the same message twice if the wrapper just rethrew
+            // (or already embedded the inner message in its own).
+            if (cursor.message && !parts[parts.length - 1].includes(cursor.message)) {
                 parts.push(cursor.message);
             }
             cursor = cursor.cause;

package/dist/commands/acceptance-test.js

@@ -127,8 +127,10 @@ export async function acceptanceTestCommand(requirementKey, url, options) {
         else {
             displayResults(requirementTree, results);
         }
-        // 11. Exit with appropriate code
-        const failedCount = results.filter((r) => r.status !== "passed").length;
+        // 11. Exit with appropriate code — computed over the requirement tree so
+        // a requirement with a missing result counts as not passing, agreeing
+        // with the displayed counts (ACCEPTANCE-1.0/.1/.2)
+        const failedCount = requirementTree.filter((_, i) => results[i]?.status !== "passed").length;
         if (failedCount > 0) {
             process.exit(1);
         }

package/dist/commands/ai-setup.js

@@ -1,10 +1,11 @@
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import prompts from "prompts";
 import { brand } from "../utils/brand.js";
 import { appendOrUpdateSection, buildNoGitRepoMessage, findDotrequirementsSection, findGitRoot, getContextFileName, } from "../utils/context-file.js";
+import { findProjectRoot, readProjectSettings, } from "../utils/project-settings.js";
 import { loadTemplate } from "../utils/templates.js";
 /**
  * Load the context file section template
@@ -12,6 +13,56 @@ import { loadTemplate } from "../utils/templates.js";
 function loadContextFileSection() {
     return loadTemplate("context-file-section.md");
 }
+/**
+ * Read an assistant's existing MCP config file (AISETUP-2).
+ * Returns {} when the file is absent or empty. Returns null when the file
+ * exists but is unusable — unreadable (AISETUP-2.2), invalid JSON
+ * (AISETUP-2.1), or a non-object root (AISETUP-2.3). In every null case the
+ * path has already been shown to the user and the caller must stop without
+ * writing; rewriting would destroy every other configured server.
+ */
+function readExistingMcpConfig(configPath) {
+    const stopWithoutWriting = (reason) => {
+        console.error(`❌ ${reason}`);
+        console.log("   Nothing was changed. Fix (or remove) the file, then re-run ai-setup:");
+        console.log(`   ${configPath}\n`);
+        return null;
+    };
+    if (!existsSync(configPath)) {
+        return {};
+    }
+    let existingContent;
+    try {
+        existingContent = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return stopWithoutWriting("Existing config file could not be read.");
+    }
+    if (!existingContent.trim()) {
+        return {};
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(existingContent);
+    }
+    catch {
+        return stopWithoutWriting("Existing config file contains invalid JSON.");
+    }
+    // AISETUP-2.3: a non-object root (e.g. a top-level array) would swallow the
+    // mcpServers assignment and serialize back without it — success would be
+    // reported while nothing was configured
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return stopWithoutWriting("Existing config file is not a JSON object.");
+    }
+    // AISETUP-2.3: same trap one level down — an array-valued mcpServers takes
+    // the server entry as an expando property that JSON.stringify drops
+    const mcpServers = parsed.mcpServers;
+    if (mcpServers != null &&
+        (typeof mcpServers !== "object" || Array.isArray(mcpServers))) {
+        return stopWithoutWriting('Existing config file has an "mcpServers" field that is not a JSON object.');
+    }
+    return parsed;
+}
 /**
  * Install workflow guidance to the appropriate context file for a platform.
  * With `yes` (the non-interactive --assistant path, AISETUP-1.0), both
@@ -166,10 +217,18 @@ async function dispatchSetup(client, yes = false) {
 }
 async function setupClaudeCode(yes = false) {
     console.log("\n📦 Configuring MCP for Claude Code...\n");
-    const command = `claude mcp add-json dotrequirements '{"type":"stdio","command":"npx","args":["-y","@popoverai/dotrequirements","mcp"]}'`;
+    // Register via an args array so no shell quoting is involved: cmd.exe does
+    // not honor single quotes, so a shell-quoted JSON string breaks on Windows.
+    const mcpServerJson = JSON.stringify({
+        type: "stdio",
+        command: "npx",
+        args: ["-y", "@popoverai/dotrequirements", "mcp"],
+    });
+    // Shell-safe on every platform (no quoting needed anywhere)
+    const manualCommand = "claude mcp add dotrequirements -- npx -y @popoverai/dotrequirements mcp";
     let mcpConfigured = false;
     try {
-        execSync(command, { stdio: "pipe" });
+        execFileSync("claude", ["mcp", "add-json", "dotrequirements", mcpServerJson], { stdio: "pipe" });
         console.log("✅ MCP configured successfully for Claude Code!");
         mcpConfigured = true;
     }
@@ -185,7 +244,7 @@ async function setupClaudeCode(yes = false) {
         else {
             console.error("❌ Failed to configure MCP automatically.");
             console.log("\nYou can manually run:");
-            console.log(`  ${command}`);
+            console.log(`  ${manualCommand}`);
             if (stderr) {
                 console.log(`\nError: ${stderr}`);
             }
@@ -224,24 +283,17 @@ async function setupClaudeDesktop() {
             REQUIREMENTS_DIR: process.cwd(),
         },
     };
+    // AISETUP-2.1–2.3: bail out before touching anything if the config is unusable
+    const config = readExistingMcpConfig(configPath);
+    if (config === null) {
+        return;
+    }
     try {
         if (!existsSync(configDir)) {
             console.log("Creating Claude Desktop config directory...");
             mkdirSync(configDir, { recursive: true });
         }
-        let config = {};
-        if (existsSync(configPath)) {
-            try {
-                const existingContent = readFileSync(configPath, "utf-8");
-                if (existingContent.trim()) {
-                    config = JSON.parse(existingContent);
-                }
-            }
-            catch {
-                console.log("⚠️  Existing config file is invalid, creating fresh config...");
-                config = {};
-            }
-        }
+        // AISETUP-2.0: other configured servers survive; only ours is (re)set
         if (!config.mcpServers) {
             config.mcpServers = {};
         }
@@ -271,30 +323,26 @@ async function setupClaudeDesktop() {
 }
 async function setupCursor(yes = false) {
     console.log("\n📦 Configuring MCP for Cursor (project-specific)...\n");
-    const configPath = join(process.cwd(), ".cursor", "mcp.json");
-    const configDir = join(process.cwd(), ".cursor");
+    // Cursor loads .cursor/mcp.json from the project (git) root — match the
+    // context-file placement, falling back to cwd outside a repository
+    const projectDir = (await findGitRoot()) ?? process.cwd();
+    const configDir = join(projectDir, ".cursor");
+    const configPath = join(configDir, "mcp.json");
     const mcpServerConfig = {
         command: "npx",
         args: ["-y", "@popoverai/dotrequirements", "mcp"],
     };
+    // AISETUP-2.1–2.3: bail out before touching anything if the config is unusable
+    const config = readExistingMcpConfig(configPath);
+    if (config === null) {
+        return;
+    }
     try {
         if (!existsSync(configDir)) {
             console.log("Creating Cursor config directory...");
             mkdirSync(configDir, { recursive: true });
         }
-        let config = {};
-        if (existsSync(configPath)) {
-            try {
-                const existingContent = readFileSync(configPath, "utf-8");
-                if (existingContent.trim()) {
-                    config = JSON.parse(existingContent);
-                }
-            }
-            catch {
-                console.log("⚠️  Existing config file is invalid, creating fresh config...");
-                config = {};
-            }
-        }
+        // AISETUP-2.0: other configured servers survive; only ours is (re)set
         if (!config.mcpServers) {
             config.mcpServers = {};
         }
@@ -324,45 +372,33 @@ async function setupAntigravity(yes = false) {
     console.log("\n📦 Configuring MCP for Google Antigravity...\n");
     const configPath = join(homedir(), ".gemini", "antigravity", "mcp_config.json");
     const configDir = join(homedir(), ".gemini", "antigravity");
-    // Check if we're in a dotrequirements project directory
-    const envLocalPath = join(process.cwd(), ".env.local");
+    // AISETUP-3.0: detect the project the way the CLI defines projects —
+    // .requirements/project-settings.json at the project root
     let projectId = null;
     let projectPath = null;
-    if (existsSync(envLocalPath)) {
+    const projectRoot = findProjectRoot();
+    if (projectRoot) {
         try {
-            const envContent = readFileSync(envLocalPath, "utf-8");
-            const lines = envContent.split("\n");
-            for (const line of lines) {
-                const trimmed = line.trim();
-                if (trimmed.startsWith("DOTREQUIREMENTS_PROJECT_ID=")) {
-                    projectId = trimmed.split("=")[1]?.trim().replace(/['"]/g, "");
-                    projectPath = process.cwd();
-                    break;
-                }
+            const settings = readProjectSettings(projectRoot);
+            if (settings) {
+                projectId = settings.projectId;
+                projectPath = projectRoot;
             }
         }
         catch {
-            // .env.local exists but couldn't read it - continue with global setup
+            // Settings file unreadable/invalid — continue with global setup
         }
     }
+    // AISETUP-2.1–2.3: bail out before touching anything if the config is unusable
+    const config = readExistingMcpConfig(configPath);
+    if (config === null) {
+        return;
+    }
     try {
         if (!existsSync(configDir)) {
             console.log("Creating Antigravity config directory...");
             mkdirSync(configDir, { recursive: true });
         }
-        let config = {};
-        if (existsSync(configPath)) {
-            try {
-                const existingContent = readFileSync(configPath, "utf-8");
-                if (existingContent.trim()) {
-                    config = JSON.parse(existingContent);
-                }
-            }
-            catch {
-                console.log("⚠️  Existing config file is invalid, creating fresh config...");
-                config = {};
-            }
-        }
         if (!config.mcpServers) {
             config.mcpServers = {};
         }
@@ -385,7 +421,9 @@ async function setupAntigravity(yes = false) {
             console.log(`   Path: ${projectPath}\n`);
         }
         else {
-            console.log(`ℹ️  Not in a ${brand} project directory (no .env.local with DOTREQUIREMENTS_PROJECT_ID found)`);
+            // AISETUP-3.1: outside any initialized project — skip the per-project
+            // step and say so
+            console.log("ℹ️  No project found (no .requirements/project-settings.json in this directory or its parents)");
             console.log("   Setting up global MCP server only.\n");
         }
         writeFileSync(configPath, JSON.stringify(config, null, 2), "utf-8");

package/dist/commands/get.js

@@ -1,10 +1,14 @@
 import { glob } from "glob";
-import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
+import { formatRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { findFilesWithRequirement, findTestCodeForRequirement, } from "../requirements/testCodeExtractor.js";
 export async function getCommand(id) {
     const workspaceRoot = process.cwd();
     const { flattened } = await loadAllRequirements(workspaceRoot);
-    const tree = getRequirementTree(flattened, id);
+    // Match the node itself plus all of its descendants by id prefix (mirrors
+    // the #46 MCP get fix). The shared getRequirementTree only matches on
+    // rootId/id equality, which drops grandchildren (e.g. REQ-123.0.0) when a
+    // child id (REQ-123.0) is requested.
+    const tree = flattened.filter((r) => r.id === id || r.id.startsWith(`${id}.`));
     // CLI-FIND-GET-1.2: missing ID → error + non-zero exit
     if (tree.length === 0) {
         throw new Error(`Requirement "${id}" not found`);

package/dist/commands/init.js

@@ -147,11 +147,10 @@ async function authenticatedFlow(cwd, options) {
     }
     if (projectChoice === "create") {
         await createNewProjectFlow(cwd, client, selectedTeam, options);
+        return true;
     }
-    else {
-        await connectExistingProjectFlow(cwd, client, selectedTeam);
-    }
-    return true;
+    // INIT-12: a cancelled project selection means init did not complete
+    return await connectExistingProjectFlow(cwd, client, selectedTeam);
 }
 /**
  * INIT-18: Prompt user to select a team after OAuth
@@ -268,13 +267,15 @@ async function createNewProjectFlow(cwd, client, team, options) {
 }
 /**
  * INIT-6, INIT-16: Connect to an existing project
+ * Returns true if connected successfully, false if the user cancelled
+ * (INIT-12: cancellation must not read as a successful init)
  */
 async function connectExistingProjectFlow(cwd, client, team) {
     // INIT-6.0, INIT-16.0: Select project from team
     const selectedProject = await selectProject(client, team.teamId);
     if (!selectedProject) {
         console.log("Initialization cancelled.");
-        return;
+        return false;
     }
     // AUTHZ-3: Prompt for secret expiry (paid tier only, if creating new secret)
     const expiryDays = await promptExpiryDays(team.tier);
@@ -306,6 +307,7 @@ async function connectExistingProjectFlow(cwd, client, team) {
     console.log("\nNext steps:");
     console.log("  1. Review the requirements in .requirements/");
     console.log("  2. Add the test harness to your test setup (see README)");
+    return true;
 }
 /**
  * MEMBERSHIP-18: Invite flow - join a team using an invite token

package/dist/commands/link-resolution.d.ts

@@ -29,7 +29,9 @@ export interface LinkFlags {
     json?: boolean;
 }
 /**
- * LINK-12.3: any deviation flag implies non-interactive mode.
+ * LINK-12.3: any deviation flag implies non-interactive mode. The JSON
+ * output flag does too — machine-readable output only exists on the
+ * non-interactive path, so `link --json` alone must not run interactively.
  */
 export declare function isNonInteractive(flags: LinkFlags): boolean;
 export declare function hasCapacity(team: TeamOption): boolean;

package/dist/commands/link-resolution.js

@@ -6,10 +6,12 @@
  * assistant needs to ask the user and retry with a deviation flag.
  */
 /**
- * LINK-12.3: any deviation flag implies non-interactive mode.
+ * LINK-12.3: any deviation flag implies non-interactive mode. The JSON
+ * output flag does too — machine-readable output only exists on the
+ * non-interactive path, so `link --json` alone must not run interactively.
  */
 export function isNonInteractive(flags) {
-    return Boolean(flags.yes || flags.team || flags.connect || flags.create);
+    return Boolean(flags.yes || flags.team || flags.connect || flags.create || flags.json);
 }
 export function hasCapacity(team) {
     return team.projectLimit === -1 || team.projectCount < team.projectLimit;

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();