@popoverai/dotrequirements 0.24.3 → 0.26.0

package/dist/commands/push.js

@@ -100,16 +100,50 @@ export async function pushCommand(file, options) {
             console.log(`  ✓ Updated: ${fileName}`);
         }
     }
-    console.log(`\n✓ Push complete!`);
+    // IMPORT-3: marker failures are loud but never fatal
+    if (result.importWarnings.length > 0) {
+        console.log();
+        for (const { fileName, status } of result.importWarnings) {
+            if (status === "already_used") {
+                console.log(`⚠ ${fileName}: this file's import marker was already used, so its requirements were saved as natively authored (they count toward your plan's requirement limit). Re-running codebase-to-spec produces a fresh marker.`);
+            }
+            else {
+                console.log(`⚠ ${fileName}: this file's import marker was not recognized — your CLI may need updating. Its requirements were saved as natively authored (they count toward your plan's requirement limit).`);
+            }
+        }
+    }
+    // SYNC-FAIL-1: a failed push must not masquerade as success — agents and
+    // scripts drive this command and rely on the exit code to tell the truth
+    const failed = result.errors.length;
+    const syncedCount = result.created + result.updated;
+    if (failed > 0) {
+        process.exitCode = 1;
+        if (syncedCount === 0) {
+            console.log(`\n✗ Push failed: ${failed} document(s) could not be saved.`);
+        }
+        else {
+            console.log(`\n⚠ Push incomplete: ${syncedCount} document(s) synced, ${failed} failed.`);
+        }
+    }
+    else {
+        console.log(`\n✓ Push complete!`);
+    }
     if (result.created > 0) {
         console.log(`  Created: ${result.created} document(s)`);
     }
     if (result.updated > 0) {
         console.log(`  Updated: ${result.updated} document(s)`);
     }
-    if (result.created === 0 && result.updated === 0) {
+    if (failed === 0 && syncedCount === 0) {
         console.log("  No documents were pushed.");
     }
+    // SYNC-LAND-1: land the user on their spec, not at a dead end
+    if (result.synced.length > 0) {
+        console.log("\nReview in dot•requirements:");
+        for (const doc of result.synced) {
+            console.log(`  ${doc.fileName} → ${doc.url}`);
+        }
+    }
 }
 /**
  * Display the dry run summary.

package/dist/convex.d.ts

@@ -34,13 +34,11 @@ export declare const api: {
         queries: {
             listByProject: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
-        mutations: {
-            bulkUpdate: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
-        };
     };
     projects: {
         mutations: {
             create: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            update: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
     teams: {
@@ -55,6 +53,9 @@ export declare const api: {
         queries: {
             getInviteInfo: import("convex/server").FunctionReference<"query", "public", any, any, string | undefined>;
         };
+        mutations: {
+            createInvite: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+        };
     };
     polar: {
         acceptTeamInvite: import("convex/server").FunctionReference<"action", "public", any, any, string | undefined>;
@@ -67,6 +68,7 @@ export declare const api: {
         mutations: {
             ensureOwnSecret: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
             revokeOwnSecret: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
+            ensureShareToken: import("convex/server").FunctionReference<"mutation", "public", any, any, string | undefined>;
         };
     };
     lib: {

package/dist/convex.js

@@ -40,13 +40,11 @@ export const api = {
         queries: {
             listByProject: query("requirements/queries:listByProject"),
         },
-        mutations: {
-            bulkUpdate: mutation("requirements/mutations:bulkUpdate"),
-        },
     },
     projects: {
         mutations: {
             create: mutation("projects/mutations:create"),
+            update: mutation("projects/mutations:update"),
         },
     },
     teams: {
@@ -61,6 +59,9 @@ export const api = {
         queries: {
             getInviteInfo: query("teamInvites/queries:getInviteInfo"),
         },
+        mutations: {
+            createInvite: mutation("teamInvites/mutations:createInvite"),
+        },
     },
     polar: {
         acceptTeamInvite: action("polar:acceptTeamInvite"),
@@ -73,6 +74,7 @@ export const api = {
         mutations: {
             ensureOwnSecret: mutation("projectSecrets/mutations:ensureOwnSecret"),
             revokeOwnSecret: mutation("projectSecrets/mutations:revokeOwnSecret"),
+            ensureShareToken: mutation("projectSecrets/mutations:ensureShareToken"),
         },
     },
     lib: {

package/dist/harness/cache.d.ts

@@ -94,20 +94,6 @@ export declare function getTestRunId(requirementsDir: string): string | null;
  * Clean up the test run ID file
  */
 export declare function cleanupTestRunId(requirementsDir: string): void;
-/**
- * Write the project root to cache (for cross-process persistence).
- * This allows test workers to find the lookup cache even after cwd changes.
- */
-export declare function writeProjectRoot(requirementsDir: string, projectRoot: string): void;
-/**
- * Read the project root from cache, returning null if not found.
- */
-export declare function readProjectRoot(requirementsDir: string): string | null;
-/**
- * Try to find the project root from any known .requirements cache directory.
- * Walks up from cwd looking for .requirements/.cache/project-root file.
- */
-export declare function findCachedProjectRoot(startDir?: string): string | null;
 /**
  * Clear tracking data for a new test run
  */

package/dist/harness/cache.js

@@ -14,7 +14,6 @@ const CACHE_DIR = ".cache";
 const LOOKUP_FILE = "lookup.json";
 const TRACKING_FILE = "tracking.jsonl";
 const COVERAGE_FILE = "coverage.json";
-const PROJECT_ROOT_FILE = "project-root";
 // Test run ID file (outside cache, in .requirements/)
 const TEST_RUN_ID_FILE = ".test-run-id";
 /**
@@ -70,7 +69,7 @@ export function writeLookupCache(requirementsDir, requirements) {
             label: node.label,
             content: node.content,
         };
-        // Always add the numeric path (e.g. "AUTH-LOGIN.0")
+        // Always add the numeric path (e.g. "AUTH-LOGIN-1.0")
         lookup.requirements[node.id] = entry;
         // Add label path as an alias if it differs from the numeric path
         if (labelPath && labelPath !== node.id) {
@@ -174,45 +173,6 @@ export function cleanupTestRunId(requirementsDir) {
         fs.unlinkSync(testRunIdPath);
     }
 }
-/**
- * Write the project root to cache (for cross-process persistence).
- * This allows test workers to find the lookup cache even after cwd changes.
- */
-export function writeProjectRoot(requirementsDir, projectRoot) {
-    const cacheDir = getCacheDir(requirementsDir, true);
-    const projectRootPath = path.join(cacheDir, PROJECT_ROOT_FILE);
-    fs.writeFileSync(projectRootPath, projectRoot);
-}
-/**
- * Read the project root from cache, returning null if not found.
- */
-export function readProjectRoot(requirementsDir) {
-    const cacheDir = getCacheDir(requirementsDir);
-    const projectRootPath = path.join(cacheDir, PROJECT_ROOT_FILE);
-    if (!fs.existsSync(projectRootPath)) {
-        return null;
-    }
-    return fs.readFileSync(projectRootPath, "utf-8").trim();
-}
-/**
- * Try to find the project root from any known .requirements cache directory.
- * Walks up from cwd looking for .requirements/.cache/project-root file.
- */
-export function findCachedProjectRoot(startDir = process.cwd()) {
-    let currentDir = path.resolve(startDir);
-    while (true) {
-        const requirementsDir = path.join(currentDir, ".requirements");
-        const projectRootPath = path.join(requirementsDir, CACHE_DIR, PROJECT_ROOT_FILE);
-        if (fs.existsSync(projectRootPath)) {
-            return fs.readFileSync(projectRootPath, "utf-8").trim();
-        }
-        const parentDir = path.dirname(currentDir);
-        if (parentDir === currentDir) {
-            return null;
-        }
-        currentDir = parentDir;
-    }
-}
 /**
  * Clear tracking data for a new test run
  */

package/dist/harness/finalize.js

@@ -333,8 +333,8 @@ export async function finalize(options = {}) {
     // Read lookup cache for report
     const lookup = readLookupCache(requirementsDir);
     // Normalize alias keys to canonical numeric keys.
-    // Non-JS consumers may write label paths (e.g. "AUTH-LOGIN.given") to tracking.jsonl.
-    // We resolve those to their canonical numeric key (e.g. "AUTH-LOGIN.0") so that
+    // Non-JS consumers may write label paths (e.g. "AUTH-LOGIN-1.given") to tracking.jsonl.
+    // We resolve those to their canonical numeric key (e.g. "AUTH-LOGIN-1.0") so that
     // coverage counting, display, and cloud reporting all use consistent keys.
     if (lookup) {
         for (const [key, trackingEntries] of Array.from(aggregated.entries())) {

package/dist/harness/prepare.js

@@ -11,7 +11,7 @@
 import { findRequirementsFilesSync } from "../requirements/index.js";
 import { parseRequirementsFromFile, } from "../schema/index.js";
 import { findProjectRoot } from "../utils/project-settings.js";
-import { clearTrackingFile, findRequirementsDir, initTestRunId, writeLookupCache, writeProjectRoot, } from "./cache.js";
+import { clearTrackingFile, findRequirementsDir, initTestRunId, writeLookupCache, } from "./cache.js";
 /**
  * Prepare the test harness for a test run.
  *
@@ -54,8 +54,6 @@ export function prepare(options = {}) {
     }
     // HARNESS-PREPARE-1: Write lookup cache for fast resolution
     writeLookupCache(requirementsDir, allRequirements);
-    // Write project root to cache (for cross-process persistence in test workers)
-    writeProjectRoot(requirementsDir, projectRoot);
     // HARNESS-PREPARE-3.0: Initialize cache directory (done by writeLookupCache)
     // HARNESS-PREPARE-3.1: Clear any previous tracking data
     clearTrackingFile(requirementsDir);

package/dist/harness/requirementsLoader.d.ts

@@ -4,14 +4,14 @@
  *
  * Project root discovery (in priority order):
  * 1. Explicit projectRoot option passed to loadRequirements()
- * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable
- * 3. Cached project root file (.requirements/.cache/project-root) written by prepare()
+ * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable (set by prepare())
+ * 3. Walk up from the working directory to the nearest .requirements/ folder
  */
 import { type RequirementNode } from "../schema/index.js";
 import type { Requirement } from "./types.js";
 export declare const loadedRequirements: Map<string, RequirementNode>;
 export interface LoadOptions {
-    /** Explicit project root path. Takes precedence over env var and cached file. */
+    /** Explicit project root path. Takes precedence over env var and walk-up discovery. */
     projectRoot?: string;
 }
 /**

package/dist/harness/requirementsLoader.js

@@ -4,14 +4,14 @@
  *
  * Project root discovery (in priority order):
  * 1. Explicit projectRoot option passed to loadRequirements()
- * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable
- * 3. Cached project root file (.requirements/.cache/project-root) written by prepare()
+ * 2. DOTREQUIREMENTS_PROJECT_ROOT environment variable (set by prepare())
+ * 3. Walk up from the working directory to the nearest .requirements/ folder
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { findRequirementsFilesSync } from "../requirements/index.js";
 import { parseRequirementsFromFile, resolveRequirementPath, } from "../schema/index.js";
-import { findCachedProjectRoot, readLookupCache } from "./cache.js";
+import { findProjectRoot as findProjectRootByWalkUp, readLookupCache, } from "./cache.js";
 // Cache: Maps full requirement IDs (e.g., "REQ-123.0.1") to RequirementNode
 export const loadedRequirements = new Map();
 // Cache: Maps root requirement IDs (e.g., "REQ-123") to their tree
@@ -22,7 +22,12 @@ let warnedAboutFallback = false;
  * Find the project root using the priority order:
  * 1. Explicit projectRoot option
  * 2. DOTREQUIREMENTS_PROJECT_ROOT env var
- * 3. Cached project root file
+ * 3. Walk up from cwd to the nearest .requirements/ folder
+ *
+ * The walk-up means the nearest enclosing project wins: tests running in a
+ * worktree nested inside another checkout load that worktree's requirements,
+ * not the outer checkout's (HARNESS-REQUIREMENT-4.3). It also matches how
+ * tracking.ts discovers the requirements directory.
  */
 function findProjectRoot(options = {}) {
     // Priority 1: Explicit option
@@ -33,8 +38,8 @@ function findProjectRoot(options = {}) {
     if (process.env.DOTREQUIREMENTS_PROJECT_ROOT) {
         return process.env.DOTREQUIREMENTS_PROJECT_ROOT;
     }
-    // Priority 3: Cached file (written by prepare())
-    return findCachedProjectRoot(process.cwd());
+    // Priority 3: Nearest .requirements/ folder (HARNESS-REQUIREMENT-4.2)
+    return findProjectRootByWalkUp(process.cwd());
 }
 /**
  * Try to load requirements from lookup cache (fast path).
@@ -97,8 +102,8 @@ export function loadRequirements(options = {}) {
     // Find project root
     const projectRoot = findProjectRoot(options);
     if (!projectRoot) {
-        throw new Error("Could not find project root. " +
-            "Set DOTREQUIREMENTS_PROJECT_ROOT environment variable or run prepare() in globalSetup.");
+        throw new Error(`Could not find project root: no .requirements/ directory in ${process.cwd()} or any parent directory. ` +
+            "Create one with `dotrequirements init`, or set the DOTREQUIREMENTS_PROJECT_ROOT environment variable.");
     }
     // Try cache first (fast path)
     if (tryLoadFromCache(projectRoot)) {

package/dist/mcp/handlers/authoring.d.ts

@@ -23,7 +23,7 @@ export interface ValidateRequirementsArgs {
  *
  * Requirements covered:
  * - MCP-AUTHOR-1.0: The template includes format guidance with code block examples
- * - MCP-AUTHOR-1.1: The template includes guidance on concrete examples, concise prose, and testable conditions
+ * - MCP-AUTHOR-1.1: The template includes style guidance (concrete examples, concise prose, testable conditions)
  * - MCP-AUTHOR-1.2: When the project has requirementsStyleContext configured, it is included in the template
  * - MCP-AUTHOR-1.3: When cloud credentials are unavailable, the template works without the custom context
  */
@@ -32,10 +32,10 @@ export declare function handleCreateRequirementDocument(args: CreateRequirementD
  * Handler for validate_requirements tool
  *
  * Requirements covered:
- * - MCP-AUTHOR-2.0: When the file has valid syntax, the response confirms validation passed
- * - MCP-AUTHOR-2.1: When the file has syntax errors, the response lists each error with location
- * - MCP-AUTHOR-2.2: Validation does not require network access or cloud credentials
- * - MCP-AUTHOR-2.3: When the file does not exist, an error is returned
+ * - MCP-AUTHOR-2.1: When the file has valid syntax, the response confirms validation passed
+ * - MCP-AUTHOR-2.2: When the file has syntax errors, the response lists each error with location
+ * - MCP-AUTHOR-2.3: Validation does not require network access or cloud credentials
+ * - MCP-AUTHOR-2.4: When the file does not exist, an error is returned
  */
 export declare function handleValidateRequirements(args: ValidateRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
 //# sourceMappingURL=authoring.d.ts.map

package/dist/mcp/handlers/authoring.js

@@ -17,7 +17,7 @@ import { errorResponse, textResponse } from "./types.js";
  *
  * Requirements covered:
  * - MCP-AUTHOR-1.0: The template includes format guidance with code block examples
- * - MCP-AUTHOR-1.1: The template includes guidance on concrete examples, concise prose, and testable conditions
+ * - MCP-AUTHOR-1.1: The template includes style guidance (concrete examples, concise prose, testable conditions)
  * - MCP-AUTHOR-1.2: When the project has requirementsStyleContext configured, it is included in the template
  * - MCP-AUTHOR-1.3: When cloud credentials are unavailable, the template works without the custom context
  */
@@ -53,21 +53,21 @@ export async function handleCreateRequirementDocument(args, context) {
  * Handler for validate_requirements tool
  *
  * Requirements covered:
- * - MCP-AUTHOR-2.0: When the file has valid syntax, the response confirms validation passed
- * - MCP-AUTHOR-2.1: When the file has syntax errors, the response lists each error with location
- * - MCP-AUTHOR-2.2: Validation does not require network access or cloud credentials
- * - MCP-AUTHOR-2.3: When the file does not exist, an error is returned
+ * - MCP-AUTHOR-2.1: When the file has valid syntax, the response confirms validation passed
+ * - MCP-AUTHOR-2.2: When the file has syntax errors, the response lists each error with location
+ * - MCP-AUTHOR-2.3: Validation does not require network access or cloud credentials
+ * - MCP-AUTHOR-2.4: When the file does not exist, an error is returned
  */
 export async function handleValidateRequirements(args, context) {
     const { filePath } = args;
-    // MCP-AUTHOR-2.2: Validation works offline - just use workspaceRoot
+    // MCP-AUTHOR-2.3: Validation works offline - just use workspaceRoot
     const fullPath = resolve(context.workspaceRoot, filePath);
-    // MCP-AUTHOR-2.3: Check if file exists
+    // MCP-AUTHOR-2.4: Check if file exists
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${filePath}`);
     }
     try {
-        // MCP-AUTHOR-2.0 & MCP-AUTHOR-2.1: Parse and validate
+        // MCP-AUTHOR-2.1 & MCP-AUTHOR-2.2: Parse and validate
         const parsed = parseRequirementsFromFile(fullPath);
         const reqCount = Object.keys(parsed.requirements).length;
         // Check push readiness
@@ -89,7 +89,7 @@ export async function handleValidateRequirements(args, context) {
         return textResponse(`${headline}${pushDetails}\n\n**Metadata:**\n- Version: ${parsed.metadata.version ?? "(none)"}\n- Document: ${parsed.metadata.document?.title || "(none)"}\n- Document ID: ${parsed.metadata.document?.id || "(none)"}\n\n**Requirements:** ${reqCount} root requirement(s) found`);
     }
     catch (error) {
-        // MCP-AUTHOR-2.1: Syntax errors are returned with details
+        // MCP-AUTHOR-2.2: Syntax errors are returned with details
         return {
             content: [
                 {

package/dist/mcp/handlers/push.d.ts

@@ -17,10 +17,10 @@ export interface PushRequirementsArgs {
  * Handler for push_requirements tool
  *
  * Requirements covered:
- * - MCP-PUSH-1.0: When a push is requested without confirmed flag, a diff preview is returned
+ * - MCP-PUSH-1.0: When not confirmed, no changes are made and a preview of creates/updates is returned
  * - MCP-PUSH-1.1: When confirmed is true, the push executes and returns success message
  * - MCP-PUSH-1.2: When credentials are missing or invalid, an error explains how to authenticate
- * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed
+ * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed (MCP-PUSH-1.3.0: missing file is an error)
  */
 export declare function handlePushRequirements(args: PushRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;
 //# sourceMappingURL=push.d.ts.map

package/dist/mcp/handlers/push.js

@@ -14,10 +14,10 @@ import { errorResponse, textResponse } from "./types.js";
  * Handler for push_requirements tool
  *
  * Requirements covered:
- * - MCP-PUSH-1.0: When a push is requested without confirmed flag, a diff preview is returned
+ * - MCP-PUSH-1.0: When not confirmed, no changes are made and a preview of creates/updates is returned
  * - MCP-PUSH-1.1: When confirmed is true, the push executes and returns success message
  * - MCP-PUSH-1.2: When credentials are missing or invalid, an error explains how to authenticate
- * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed
+ * - MCP-PUSH-1.3: When filePath is provided, only that file is pushed (MCP-PUSH-1.3.0: missing file is an error)
  */
 export async function handlePushRequirements(args, context) {
     const { filePath, confirmed = false, projectId } = args;
@@ -123,19 +123,52 @@ export async function handlePushRequirements(args, context) {
     // MCP-PUSH-1.1: When confirmed, execute push
     try {
         const result = await executePush(dryRunResult, credentials);
-        let output = "✓ Push complete!\n\n";
+        // SYNC-FAIL-1: a failed push must not masquerade as success
+        const failed = result.errors.length;
+        const syncedCount = result.created + result.updated;
+        let output;
+        if (failed > 0 && syncedCount === 0) {
+            output = `✗ Push failed: ${failed} document(s) could not be saved.\n\n`;
+        }
+        else if (failed > 0) {
+            output = `⚠ Push incomplete: ${syncedCount} document(s) synced, ${failed} failed.\n\n`;
+        }
+        else {
+            output = "✓ Push complete!\n\n";
+        }
         if (result.created > 0) {
             output += `**Created:** ${result.created} document(s)\n`;
         }
         if (result.updated > 0) {
             output += `**Updated:** ${result.updated} document(s)\n`;
         }
+        // IMPORT-3: marker failures are loud but never fatal
+        if (result.importWarnings.length > 0) {
+            output += `\n**Import marker warnings:**\n`;
+            for (const { fileName, status } of result.importWarnings) {
+                output +=
+                    status === "already_used"
+                        ? `- ⚠ ${fileName}: import marker already used — requirements were saved as natively authored (they count toward the plan's requirement limit). Re-running codebase-to-spec produces a fresh marker.\n`
+                        : `- ⚠ ${fileName}: import marker not recognized — the CLI may need updating. Requirements were saved as natively authored (they count toward the plan's requirement limit).\n`;
+            }
+        }
         if (result.errors.length > 0) {
             output += `\n**Errors:**\n`;
             for (const { fileName, error } of result.errors) {
                 output += `- ${fileName}: ${error}\n`;
             }
         }
+        // SYNC-LAND-1: where each synced document lives in the web app
+        if (result.synced.length > 0) {
+            output += `\n**Review in dot•requirements:**\n`;
+            for (const doc of result.synced) {
+                output += `- ${doc.fileName}: ${doc.url}\n`;
+            }
+        }
+        // SYNC-FAIL-1.2: total failure is an error result, not a success story
+        if (failed > 0 && syncedCount === 0) {
+            return { content: [{ type: "text", text: output }], isError: true };
+        }
         return textResponse(output);
     }
     catch (error) {

package/dist/mcp/handlers/review.d.ts

@@ -25,7 +25,7 @@ export interface ReviewTestArgs {
  * Handler for style_check tool
  *
  * Requirements covered:
- * - MCP-REVIEW-1.0: For requirements files, feedback identifies vague language, missing preconditions, and style violations
+ * - MCP-REVIEW-1.0: For requirements files, feedback identifies clarity issues such as vague language and missing preconditions
  * - MCP-REVIEW-1.1: For test files, feedback identifies incorrect requirement() usage and missing test coverage
  * - MCP-REVIEW-1.2: Feedback is categorized by severity: must fix, should fix, could improve
  * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
@@ -38,9 +38,9 @@ export declare function handleStyleCheck(args: StyleCheckArgs, context: HandlerC
  * Handler for review_test tool
  *
  * Requirements covered:
- * - MCP-REVIEW-2.0: The review validates that test setup matches requirement preconditions
- * - MCP-REVIEW-2.1: The review validates that test actions match requirement triggers
- * - MCP-REVIEW-2.2: The review validates that test assertions match requirement outcomes
+ * - MCP-REVIEW-2.0: Feedback identifies test setup that does not match requirement preconditions
+ * - MCP-REVIEW-2.1: Feedback identifies test actions that do not match requirement triggers
+ * - MCP-REVIEW-2.2: Feedback identifies test assertions that do not match requirement outcomes
  * - MCP-REVIEW-2.3: Feedback identifies requirements without test coverage
  * - MCP-REVIEW-2.4: Feedback identifies tests that reference non-existent requirements
  * - MCP-REVIEW-2.5: When cloud credentials are unavailable, an error explains how to authenticate

package/dist/mcp/handlers/review.js

@@ -26,7 +26,7 @@ const STYLE_CHECK_GUIDANCE = `
  * Handler for style_check tool
  *
  * Requirements covered:
- * - MCP-REVIEW-1.0: For requirements files, feedback identifies vague language, missing preconditions, and style violations
+ * - MCP-REVIEW-1.0: For requirements files, feedback identifies clarity issues such as vague language and missing preconditions
  * - MCP-REVIEW-1.1: For test files, feedback identifies incorrect requirement() usage and missing test coverage
  * - MCP-REVIEW-1.2: Feedback is categorized by severity: must fix, should fix, could improve
  * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
@@ -120,9 +120,9 @@ export async function handleStyleCheck(args, context, options) {
  * Handler for review_test tool
  *
  * Requirements covered:
- * - MCP-REVIEW-2.0: The review validates that test setup matches requirement preconditions
- * - MCP-REVIEW-2.1: The review validates that test actions match requirement triggers
- * - MCP-REVIEW-2.2: The review validates that test assertions match requirement outcomes
+ * - MCP-REVIEW-2.0: Feedback identifies test setup that does not match requirement preconditions
+ * - MCP-REVIEW-2.1: Feedback identifies test actions that do not match requirement triggers
+ * - MCP-REVIEW-2.2: Feedback identifies test assertions that do not match requirement outcomes
  * - MCP-REVIEW-2.3: Feedback identifies requirements without test coverage
  * - MCP-REVIEW-2.4: Feedback identifies tests that reference non-existent requirements
  * - MCP-REVIEW-2.5: When cloud credentials are unavailable, an error explains how to authenticate

package/dist/mcp/handlers/search.d.ts

@@ -23,7 +23,7 @@ export interface SearchRequirementsArgs {
  * - MCP-SEARCH-1.3: useRegex interprets query as case-insensitive regex
  * - MCP-SEARCH-1.4: Invalid regex returns error
  * - MCP-SEARCH-1.5: No matches returns informative message
- * - MCP-SEARCH-1.6: Nested match returns root requirement
+ * - MCP-SEARCH-1.6: Nested match returns the full root requirement tree
  * - MCP-SEARCH-1.7: Results include full tree as code block
  */
 export declare function handleSearchRequirements(args: SearchRequirementsArgs, context: HandlerContext): Promise<ToolResponse>;

package/dist/mcp/handlers/search.js

@@ -16,7 +16,7 @@ import { errorResponse, textResponse } from "./types.js";
  * - MCP-SEARCH-1.3: useRegex interprets query as case-insensitive regex
  * - MCP-SEARCH-1.4: Invalid regex returns error
  * - MCP-SEARCH-1.5: No matches returns informative message
- * - MCP-SEARCH-1.6: Nested match returns root requirement
+ * - MCP-SEARCH-1.6: Nested match returns the full root requirement tree
  * - MCP-SEARCH-1.7: Results include full tree as code block
  */
 export async function handleSearchRequirements(args, context) {

package/dist/mcp/index.js

@@ -523,11 +523,40 @@ After writing tests:
     }
     throw new Error(`Unknown prompt: ${name}`);
 });
+/**
+ * MCP-ARGS-1: find required arguments (per the tool's inputSchema) that are
+ * missing from a call, so we can fail with a self-explaining error before the
+ * handler runs — a missing argument must never surface as an internal crash.
+ */
+function findMissingRequiredArgs(toolName, args) {
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool)
+        return undefined; // unknown tools get their own error downstream
+    const schema = tool.inputSchema;
+    const required = schema.required ?? [];
+    const missing = required.filter((key) => args?.[key] === undefined || args?.[key] === null);
+    if (missing.length === 0)
+        return undefined;
+    return { missing, accepted: Object.keys(schema.properties ?? {}) };
+}
 // Handle tool calls
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
     // Refresh cache for each request to pick up changes
     invalidateCache();
+    // MCP-ARGS-1.2: reject calls missing required arguments before dispatch
+    const argCheck = findMissingRequiredArgs(name, args);
+    if (argCheck) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Missing required argument(s) for ${name}: ${argCheck.missing.join(", ")}. Accepted arguments: ${argCheck.accepted.join(", ")}.`,
+                },
+            ],
+            isError: true,
+        };
+    }
     // Create handler context for extracted handlers
     const handlerContext = {
         getRequirements,

package/dist/push/core.d.ts

@@ -72,6 +72,13 @@ export interface DryRunResult {
     conflicts: ConflictInfo[];
     totalRequirements: number;
 }
+/**
+ * Outcome of run-marker handling for one pushed file (IMPORT-2/3).
+ * Mirrors the server's ImportStatus.
+ */
+export type ImportStatus = "imported" | "invalid_marker" | "unsupported_version" | "already_used" | "ignored_update" | "none";
+/** Base URL of the web app, where synced documents are reviewed. */
+export declare const WEB_APP_URL = "https://app.dotrequirements.io";
 /**
  * Result of the execute phase.
  */
@@ -82,6 +89,17 @@ export interface PushResult {
         fileName: string;
         error: string;
     }>;
+    /** IMPORT-3: marker failures that must be surfaced to the user, per file */
+    importWarnings: Array<{
+        fileName: string;
+        status: Extract<ImportStatus, "invalid_marker" | "unsupported_version" | "already_used">;
+    }>;
+    /** SYNC-LAND-1: each successfully synced document, with its web URL */
+    synced: Array<{
+        fileName: string;
+        documentId: string;
+        url: string;
+    }>;
 }
 /**
  * Extract markdown content from a file, stripping YAML frontmatter.