@popoverai/dotrequirements 0.25.0 → 0.26.1

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.

package/dist/push/core.js

@@ -14,6 +14,8 @@ import * as path from "node:path";
 import { ConvexHttpClient } from "convex/browser";
 import { api } from "../convex.js";
 import { buildRequirementsFile, getAllRequirements, parseRequirementKey, parseRequirementsFromFile, } from "../schema/index.js";
+/** Base URL of the web app, where synced documents are reviewed. */
+export const WEB_APP_URL = "https://app.dotrequirements.io";
 // ============================================================================
 // Parsing
 // ============================================================================
@@ -170,13 +172,15 @@ export async function executePush(dryRunResult, credentials) {
     let created = 0;
     let updated = 0;
     const errors = [];
+    const importWarnings = [];
+    const synced = [];
     for (const { file, result } of pushableFiles) {
         const doc = file.metadata.document;
         const fileName = path.basename(file.filePath);
         // For not_found, clear the ID so we create a new document
         const effectiveDocId = result.action === "not_found" ? undefined : doc.id;
         try {
-            const pushResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+            const rawResult = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
                 projectAuth: {
                     projectSlug: credentials.projectId,
                     projectSecret: credentials.projectSecret,
@@ -186,8 +190,21 @@ export async function executePush(dryRunResult, credentials) {
                 title: doc.title,
                 markdownContent: file.markdownContent,
                 defaultPrefix: doc.defaultPrefix,
+                // IMPORT-2: forward the CTS run marker when the file is stamped
+                runMarker: file.metadata.ctsRun,
                 dryRun: false,
             }));
+            // The server returns a structured result iff we sent a runMarker
+            const pushResult = typeof rawResult === "string" ? rawResult : rawResult.documentId;
+            if (typeof rawResult !== "string") {
+                const status = rawResult.importStatus;
+                if (status === "invalid_marker" ||
+                    status === "unsupported_version" ||
+                    status === "already_used") {
+                    // IMPORT-3.2/3.3: loud, never fatal
+                    importWarnings.push({ fileName, status });
+                }
+            }
             const isCreate = result.action === "create" || result.action === "not_found";
             if (isCreate) {
                 // New document - write ID back to file
@@ -206,11 +223,61 @@ export async function executePush(dryRunResult, credentials) {
                 fs.writeFileSync(file.filePath, updatedContent, "utf-8");
                 updated++;
             }
+            // SYNC-LAND-1: every synced document gets its web URL in the result
+            synced.push({
+                fileName,
+                documentId: pushResult,
+                url: `${WEB_APP_URL}/documents/${pushResult}`,
+            });
         }
         catch (err) {
-            errors.push({ fileName, error: err.message });
+            errors.push({ fileName, error: errorDisplayMessage(err) });
+        }
+    }
+    return { created, updated, errors, importWarnings, synced };
+}
+/**
+ * Servers throw ConvexError({kind, message}) for expected failures (e.g.
+ * LIMITS-4.2's limit error); the client-side Error message embeds that data
+ * as JSON. Surface the human-readable message it carries instead of the blob.
+ */
+function errorDisplayMessage(err) {
+    const data = err.data;
+    const fromData = humanMessage(data);
+    if (fromData)
+        return fromData;
+    const message = err instanceof Error ? err.message : String(err);
+    // ConvexError messages may embed the data JSON directly or after a
+    // "ConvexError:" prefix — try the trailing {...} chunk
+    const jsonStart = message.indexOf("{");
+    if (jsonStart !== -1) {
+        try {
+            const parsed = JSON.parse(message.slice(jsonStart));
+            const fromMessage = humanMessage(parsed);
+            if (fromMessage)
+                return fromMessage;
+        }
+        catch {
+            // fall through to the raw message
+        }
+    }
+    return message;
+}
+function humanMessage(data) {
+    if (typeof data === "string") {
+        try {
+            return humanMessage(JSON.parse(data));
         }
+        catch {
+            return undefined;
+        }
+    }
+    if (data &&
+        typeof data === "object" &&
+        "message" in data &&
+        typeof data.message === "string") {
+        return data.message;
     }
-    return { created, updated, errors };
+    return undefined;
 }
 //# sourceMappingURL=core.js.map

package/dist/push/index.d.ts

@@ -4,5 +4,5 @@
  * Shared push logic for syncing local requirements files to the cloud.
  * Used by both CLI push command and MCP push_requirements tool.
  */
-export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, } from "./core.js";
+export { type CloudDocumentMetadata, type ConflictInfo, type DryRunResult, type DryRunResultItem, dryRunPush, executePush, extractMarkdownContent, type FileWithDryRun, type ParsedFile, type PushCredentials, type PushResult, parseFilesForPush, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/push/index.js

@@ -6,5 +6,5 @@
  */
 export { dryRunPush, executePush, 
 // Functions
-extractMarkdownContent, parseFilesForPush, } from "./core.js";
+extractMarkdownContent, parseFilesForPush, WEB_APP_URL, } from "./core.js";
 //# sourceMappingURL=index.js.map

package/dist/schema/parser-core.js

@@ -4,7 +4,7 @@
  * This module contains pure parsing functions with no Node.js dependencies,
  * making it safe to import in Convex runtime or browser environments.
  */
-import { ValidationError, } from "./schemas.js";
+import { ValidationError, validateKey, } from "./schemas.js";
 /**
  * Default delimiter for requirements.
  * Can be overridden for organization-specific preferences.
@@ -186,6 +186,10 @@ export function extractRequirementBlocks(body) {
             throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
         }
         const key = firstLineMatch[1];
+        // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
+        // locally instead of erroring server-side. Validation only — the original
+        // key is preserved (normalization happens downstream).
+        validateKey(key);
         blocks.push({ key, blockContent: blockContent.trim() });
         match = blockRegex.exec(body);
     }

package/dist/schema/parser.js

@@ -3,7 +3,7 @@
  */
 import * as fs from "node:fs";
 import YAML from "yaml";
-import { ValidationError, validateMetadata, } from "./schemas.js";
+import { ValidationError, validateKey, validateMetadata, } from "./schemas.js";
 const DELIMITER_PATTERN = "(?:→|->)"; // Non-capturing group for both Unicode and ASCII
 /**
  * Parse a criterion line in "position. Label → content" format.
@@ -198,6 +198,10 @@ function extractRequirementBlocks(body) {
             throw new ValidationError(`Invalid requirement block format - first line must be "KEY: content"`, blockContent.substring(0, 50));
         }
         const key = firstLineMatch[1];
+        // SYNC-KEY-1: reject malformed keys at parse time so push/validate fail
+        // locally instead of erroring server-side. Validation only — the original
+        // key is preserved (normalization happens downstream).
+        validateKey(key);
         // Try to find a heading immediately before this block for the title
         // Look backwards from the match position to find the nearest heading
         const textBeforeBlock = body.substring(0, match.index);