@popoverai/dotrequirements 0.26.1 → 0.27.0

package/dist/commands/tests-for.js

@@ -20,27 +20,27 @@ export async function testsForCommand(requirementsFile) {
     }
     const rootIds = new Set(fileRequirements.map((req) => req.rootId));
     const allTestRefs = await findAllTestReferences(workspaceRoot);
-    // Build coverage map: requirement ID → test refs
+    // Build coverage map keyed by ROOT id. A reference may be a bare root
+    // (`AUTH-1`), an index child (`AUTH-1.0`), or a label path (`AUTH-1.given`) —
+    // and every string arg of a multi-arg `requirement("A", "B")` call is its own
+    // ref. Normalizing each ref to its root id (the first dotted segment) lets a
+    // covered descendant count toward its root requirement.
     const coverageMap = new Map();
     for (const ref of allTestRefs) {
-        if (!coverageMap.has(ref.requirementId)) {
-            coverageMap.set(ref.requirementId, []);
+        const dotIndex = ref.requirementId.indexOf(".");
+        const refRootId = dotIndex > 0
+            ? ref.requirementId.substring(0, dotIndex)
+            : ref.requirementId;
+        if (!coverageMap.has(refRootId)) {
+            coverageMap.set(refRootId, []);
         }
-        coverageMap.get(ref.requirementId).push(ref);
+        coverageMap.get(refRootId).push(ref);
     }
     // CLI-FIND-MAP-2.0: group by coverage status
     const covered = [];
     const notCovered = [];
     for (const rootId of rootIds) {
-        const reqAndChildren = fileRequirements.filter((r) => r.rootId === rootId);
-        const allIds = reqAndChildren.map((r) => r.id);
-        const testsForThisReq = [];
-        for (const id of allIds) {
-            const refs = coverageMap.get(id);
-            if (refs) {
-                testsForThisReq.push(...refs);
-            }
-        }
+        const testsForThisReq = coverageMap.get(rootId) ?? [];
         if (testsForThisReq.length > 0) {
             covered.push({ id: rootId, tests: testsForThisReq });
         }

package/dist/commands/validate.js

@@ -1,24 +1,18 @@
-import * as fs from "node:fs";
 import * as path from "node:path";
+import { findRequirementsFiles } from "../requirements/index.js";
 import { parseRequirementsFromFile, } from "../schema/index.js";
 export async function validateCommand(options) {
     console.log("Parsing and validating requirements...");
-    const requirementsDir = path.join(process.cwd(), ".requirements");
-    if (!fs.existsSync(requirementsDir)) {
-        console.error("Error: .requirements/ directory not found.");
-        console.log('Run "dotrequirements pull" first to sync requirements.');
-        process.exit(1);
-    }
-    // Get files to test
+    // Validation parses the file in front of it — it never requires a
+    // .requirements/ directory (VALIDATE-1.0/.1). The no-flag path uses the
+    // shared recursive discovery so colocated files at any level and files in
+    // subdirectories of .requirements/ are all found (VALIDATE-2.0).
     let files;
     if (options.file) {
         files = [options.file];
     }
     else {
-        files = fs
-            .readdirSync(requirementsDir)
-            .filter((f) => f.endsWith(".requirements.md"))
-            .map((f) => path.join(requirementsDir, f));
+        files = await findRequirementsFiles(process.cwd());
     }
     if (files.length === 0) {
         console.log("No Markdown requirements files found to test.");
@@ -40,8 +34,14 @@ export async function validateCommand(options) {
             }
             totalRequirements += count;
             console.log(`  ✓ Valid structure (${count} requirement(s))`);
-            console.log(`  ✓ Version: ${metadata.version}`);
-            console.log(`  ✓ Last sync: ${metadata.pulledAt}`);
+            // Version/sync metadata is optional (hand-authored files have neither);
+            // only report fields that are present (VALIDATE-3.0/.1)
+            if (metadata.version !== undefined) {
+                console.log(`  ✓ Version: ${metadata.version}`);
+            }
+            if (metadata.pulledAt !== undefined) {
+                console.log(`  ✓ Last sync: ${metadata.pulledAt}`);
+            }
             passCount++;
         }
         catch (error) {

package/dist/convex.d.ts

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

package/dist/convex.js

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

package/dist/harness/cache.d.ts

@@ -36,6 +36,18 @@ export interface LookupCache {
         isAlias?: boolean;
     }>;
 }
+/**
+ * Staleness metadata for the lookup cache, stored in a sibling file.
+ *
+ * lookup.json's shape is a cross-language contract: the shipped Python/Java
+ * helpers parse it with minimal JSON parsers (MLANG-6/7), so new fields —
+ * especially arrays — must not be added to it. Deletion detection
+ * (HARNESS-REQUIREMENT-4) needs the source-file set, so that lives here.
+ */
+export interface LookupCacheMeta {
+    /** Project-relative paths of the source files the cache was built from. */
+    sourceFiles: string[];
+}
 /**
  * Structure of the coverage.json cache (for cloud deduplication)
  */
@@ -73,10 +85,14 @@ export declare function getCacheDir(requirementsDir: string, create?: boolean):
  */
 export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
 /**
- * Check if any source file is newer than the cache file.
- * Returns true if cache is stale and should be invalidated.
+ * Check if the lookup cache is stale and should be invalidated.
+ *
+ * A cache is stale when any source file is newer than the cache file, or —
+ * when the cache's recorded source-file set is provided — when the current
+ * set of source files differs from the recorded one (HARNESS-REQUIREMENT-4:
+ * deletions don't touch surviving files' mtimes, so the set must be compared).
  */
-export declare function isCacheStale(requirementsDir: string, cacheMtime: number): boolean;
+export declare function isCacheStale(requirementsDir: string, cacheMtime: number, cachedSourceFiles?: string[]): boolean;
 /**
  * Read the lookup cache, returning null if not found, invalid, or stale.
  * Cache is considered stale if any .requirements.md file is newer than the cache.

package/dist/harness/cache.js

@@ -12,6 +12,7 @@ import { findRequirementsFilesSync } from "../requirements/index.js";
 // Cache directory structure
 const CACHE_DIR = ".cache";
 const LOOKUP_FILE = "lookup.json";
+const LOOKUP_META_FILE = "lookup-meta.json";
 const TRACKING_FILE = "tracking.jsonl";
 const COVERAGE_FILE = "coverage.json";
 // Test run ID file (outside cache, in .requirements/)
@@ -58,6 +59,10 @@ export function getCacheDir(requirementsDir, create = false) {
 export function writeLookupCache(requirementsDir, requirements) {
     const cacheDir = getCacheDir(requirementsDir, true);
     const lookupPath = path.join(cacheDir, LOOKUP_FILE);
+    const projectRoot = path.dirname(requirementsDir);
+    const sourceFiles = findRequirementsFilesSync(projectRoot)
+        .map((file) => path.relative(projectRoot, file))
+        .sort();
     const lookup = {
         generatedAt: new Date().toISOString(),
         requirements: {},
@@ -96,14 +101,30 @@ export function writeLookupCache(requirementsDir, requirements) {
         flatten(req, null);
     }
     fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
+    const meta = { sourceFiles };
+    fs.writeFileSync(path.join(cacheDir, LOOKUP_META_FILE), JSON.stringify(meta, null, 2));
 }
 /**
- * Check if any source file is newer than the cache file.
- * Returns true if cache is stale and should be invalidated.
+ * Check if the lookup cache is stale and should be invalidated.
+ *
+ * A cache is stale when any source file is newer than the cache file, or —
+ * when the cache's recorded source-file set is provided — when the current
+ * set of source files differs from the recorded one (HARNESS-REQUIREMENT-4:
+ * deletions don't touch surviving files' mtimes, so the set must be compared).
  */
-export function isCacheStale(requirementsDir, cacheMtime) {
+export function isCacheStale(requirementsDir, cacheMtime, cachedSourceFiles) {
     const projectRoot = path.dirname(requirementsDir);
     const sourceFiles = findRequirementsFilesSync(projectRoot);
+    if (cachedSourceFiles) {
+        const current = sourceFiles
+            .map((file) => path.relative(projectRoot, file))
+            .sort();
+        const cached = [...cachedSourceFiles].sort();
+        if (current.length !== cached.length ||
+            current.some((file, i) => file !== cached[i])) {
+            return true;
+        }
+    }
     for (const file of sourceFiles) {
         try {
             const stat = fs.statSync(file);
@@ -127,23 +148,28 @@ export function readLookupCache(requirementsDir) {
     if (!fs.existsSync(lookupPath)) {
         return null;
     }
-    // Check if cache is stale (any source file newer than cache)
+    let cache;
+    let meta;
+    let cacheMtime;
     try {
-        const cacheStat = fs.statSync(lookupPath);
-        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
-            return null;
-        }
+        cacheMtime = fs.statSync(lookupPath).mtimeMs;
+        cache = JSON.parse(fs.readFileSync(lookupPath, "utf-8"));
+        meta = JSON.parse(fs.readFileSync(path.join(cacheDir, LOOKUP_META_FILE), "utf-8"));
     }
     catch {
+        // A cache without its meta file (legacy layout) can't detect deletions —
+        // treat it as stale and let prepare() rebuild both files.
         return null;
     }
-    try {
-        const content = fs.readFileSync(lookupPath, "utf-8");
-        return JSON.parse(content);
+    if (!Array.isArray(meta.sourceFiles)) {
+        return null;
     }
-    catch {
+    // Stale if the source-file set changed (deletions included) or any source
+    // file is newer than the cache
+    if (isCacheStale(requirementsDir, cacheMtime, meta.sourceFiles)) {
         return null;
     }
+    return cache;
 }
 /**
  * Generate and store a unique test run ID

package/dist/harness/finalize.js

@@ -13,6 +13,7 @@ import { execSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { getProjectInfo } from "../utils/project-settings.js";
 import { cleanupTestRunId, deleteTrackingFile, findProjectRoot, findRequirementsDir, getTestRunId, needsReporting, readCoverageCache, readLookupCache, readTrackingEntries, updateCoverageCache, } from "./cache.js";
+import { toProjectRelativePath } from "./tracking.js";
 /**
  * Aggregate tracking entries by requirement key
  */
@@ -181,7 +182,7 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
             // Use the first access location
             const firstEntry = entries[0];
             const location = firstEntry.callerLocation;
-            // Parse "filename.ts:42" format
+            // Parse "path/to/file.ts:42" format
             let testFile;
             let testLine;
             if (location !== "unknown") {
@@ -193,6 +194,12 @@ async function reportToConvex(projectRoot, testRunId, aggregated, showCloudStatu
                 else {
                     testFile = location;
                 }
+                // COVERAGE-CONTEXT-2: locations inside the project are recorded
+                // project-relative; normalize any absolute path that falls inside
+                // the project so records and git blame use a stable relative path.
+                if (testFile) {
+                    testFile = toProjectRelativePath(testFile, projectRoot);
+                }
             }
             // COVERAGE-CONTEXT-2: git blame on the requirement() call line
             let user;
@@ -337,6 +344,23 @@ export async function finalize(options = {}) {
     // 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) {
+        // HARNESS-RESOLVE-2.1: label paths resolve case-insensitively, but
+        // tracking preserves the test's original casing while the cache stores
+        // alias keys lowercased. Fold unmatched keys onto their lowercased-label
+        // alias first, so a ref like "REQ-1.Given" isn't dropped as foreign below.
+        for (const [key, trackingEntries] of Array.from(aggregated.entries())) {
+            if (lookup.requirements[key])
+                continue;
+            const m = /^([A-Z][A-Z0-9_-]*-\d+)(\..+)$/.exec(key);
+            if (!m)
+                continue;
+            const folded = m[1] + m[2].toLowerCase();
+            if (folded !== key && lookup.requirements[folded]) {
+                const existing = aggregated.get(folded) || [];
+                aggregated.set(folded, [...existing, ...trackingEntries]);
+                aggregated.delete(key);
+            }
+        }
         for (const [key, trackingEntries] of Array.from(aggregated.entries())) {
             const entry = lookup.requirements[key];
             if (entry?.isAlias) {
@@ -347,6 +371,14 @@ export async function finalize(options = {}) {
                 aggregated.delete(key);
             }
         }
+        // HARNESS-REQUIREMENT-6.1: a project's coverage report contains only
+        // requirement keys that belong to that project. Tracking entries for
+        // foreign keys (e.g. resolved against another project) are dropped.
+        for (const key of Array.from(aggregated.keys())) {
+            if (!lookup.requirements[key]) {
+                aggregated.delete(key);
+            }
+        }
     }
     const testedKeys = Array.from(aggregated.keys());
     const totalRequirements = lookup

package/dist/harness/index.js

@@ -70,21 +70,28 @@ export function requirement(...args) {
     if (options.projectRoot) {
         loadRequirements({ projectRoot: options.projectRoot });
     }
-    // Ensure test run is initialized
-    ensureTestRun();
+    // HARNESS-REQUIREMENT-2: Invalid requirement paths fail the individual test.
+    // Every ref is validated — a typo in any ref throws, naming the missing path.
+    // Validation happens BEFORE tracking so that refs that fail lookup are never
+    // recorded as covered (HARNESS-REQUIREMENT-3).
+    const resolved = requirementRefs.map((ref) => {
+        const found = getRequirement(ref);
+        if (!found) {
+            throw new Error(`Requirement ${ref} not found`);
+        }
+        return found;
+    });
+    // Ensure test run is initialized against the resolving project
+    // (HARNESS-REQUIREMENT-6: explicit projectRoot wins over the enclosing one)
+    ensureTestRun(options.projectRoot);
     // Track all requirements for coverage at the full path level
     // e.g., 'REQ-123.given' is tracked as 'REQ-123.given', not just 'REQ-123'
     for (const ref of requirementRefs) {
-        trackRequirement(ref);
+        trackRequirement(ref, options.projectRoot);
     }
     // Save after tracking all requirements (no-op in new JSONL approach)
     saveTrackingData();
-    // HARNESS-REQUIREMENT-2: Invalid requirement paths fail the individual test
-    const firstRef = requirementRefs[0];
-    const req = getRequirement(firstRef);
-    if (!req) {
-        throw new Error(`Requirement ${firstRef} not found`);
-    }
+    const req = resolved[0];
     // HARNESS-REQUIREMENT-1: Format output as human-readable string
     // Root requirements use 'requirementHeader' label which should not be shown in output
     if (!req.label || req.label === "requirementHeader") {

package/dist/harness/requirementsLoader.js

@@ -151,6 +151,18 @@ export function getRequirement(reqId) {
     if (direct) {
         return direct;
     }
+    // HARNESS-RESOLVE-2.1: label matching is case-insensitive. The lookup
+    // cache stores label-path aliases lowercased (e.g. "REQ-123.given"), and
+    // in cache mode nodes carry no children for the fallback resolver to walk,
+    // so retry with the label segments lowercased (root key stays as written).
+    const firstDot = reqId.indexOf(".");
+    if (firstDot !== -1) {
+        const normalized = reqId.slice(0, firstDot) + reqId.slice(firstDot).toLowerCase();
+        const aliased = loadedRequirements.get(normalized);
+        if (aliased) {
+            return aliased;
+        }
+    }
     // If not found, try resolving label-based paths
     // resolveRequirementPath expects an array of root requirements and the full path
     const allTrees = Array.from(requirementTrees.values());

package/dist/harness/tracking.d.ts

@@ -11,8 +11,21 @@ export interface TrackedRequirement {
     fieldsAccessed: string[];
     accessedAt: string[];
 }
-export declare function ensureTestRun(): string;
+/**
+ * Initialize (or reuse) a test run.
+ *
+ * HARNESS-REQUIREMENT-6.0: when an explicit projectRoot is provided, the run
+ * is keyed to that project's .requirements/ so tracking writes land in the
+ * resolving project's cache, not the enclosing project's.
+ */
+export declare function ensureTestRun(projectRoot?: string): string;
 export declare function getCallerLocation(): string;
+/**
+ * Normalize an absolute path inside the project to a project-relative one
+ * (COVERAGE-CONTEXT-2: stable, blame-able from the project root). Paths that
+ * are already relative or fall outside the project are returned unchanged.
+ */
+export declare function toProjectRelativePath(filePath: string, projectRoot: string): string;
 /**
  * Track a requirement access.
  *
@@ -21,8 +34,10 @@ export declare function getCallerLocation(): string;
  * HARNESS-REQUIREMENT-3.2: Works correctly when tests run in parallel processes
  *
  * @param reqId - Full requirement path (e.g., 'REQ-123.given' or 'REQ-123.0.1')
+ * @param projectRoot - Explicit project root; tracking is written to this
+ *   project's cache when provided (HARNESS-REQUIREMENT-6.0)
  */
-export declare function trackRequirement(reqId: string): void;
+export declare function trackRequirement(reqId: string, projectRoot?: string): void;
 /**
  * Save current tracking data.
  *

package/dist/harness/tracking.js

@@ -7,13 +7,33 @@
  * HARNESS-REQUIREMENT-3: Each requirement() call is recorded for coverage reporting
  */
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 import { appendTrackingEntry, clearTrackingFile, findProjectRoot, findRequirementsDir, getCacheDir, getTestRunId, initTestRunId, } from "./cache.js";
 const trackedRequirements = new Map();
 // Test run tracking
 let testRunId = null;
 let requirementsDirCached = null;
-// Initialize test run
-export function ensureTestRun() {
+// Per-project run ids for explicit projectRoot tracking (HARNESS-REQUIREMENT-6)
+const runIdsByRequirementsDir = new Map();
+/**
+ * Initialize (or reuse) a test run.
+ *
+ * HARNESS-REQUIREMENT-6.0: when an explicit projectRoot is provided, the run
+ * is keyed to that project's .requirements/ so tracking writes land in the
+ * resolving project's cache, not the enclosing project's.
+ */
+export function ensureTestRun(projectRoot) {
+    if (projectRoot) {
+        const requirementsDir = path.join(projectRoot, ".requirements");
+        let runId = runIdsByRequirementsDir.get(requirementsDir);
+        if (!runId) {
+            // Reuse a run id written by prepare() in that project, else mint one
+            runId = getTestRunId(requirementsDir) ?? `${Date.now()}-${process.pid}`;
+            runIdsByRequirementsDir.set(requirementsDir, runId);
+            getCacheDir(requirementsDir, true);
+        }
+        return runId;
+    }
     if (!testRunId) {
         // Priority 1: Use environment variable (cross-process persistence from globalSetup)
         if (process.env.DOTREQUIREMENTS_PROJECT_ROOT) {
@@ -61,14 +81,62 @@ export function getCallerLocation() {
             const regex2 = /at (.+):(\d+):(\d+)/;
             const match = regex1.exec(frame) || regex2.exec(frame);
             if (match) {
-                const filePath = match[1];
+                let filePath = match[1];
                 const lineNumber = match[2];
-                return `${path.basename(filePath)}:${lineNumber}`;
+                // ESM stack frames use file:// URLs
+                if (filePath.startsWith("file://")) {
+                    try {
+                        filePath = fileURLToPath(filePath);
+                    }
+                    catch {
+                        // Keep the raw frame path if the URL can't be converted
+                    }
+                }
+                // COVERAGE-CONTEXT-2: keep the full path (not just the basename) so
+                // finalize() can git-blame the call site for nested test files.
+                return `${filePath}:${lineNumber}`;
             }
         }
     }
     return "unknown";
 }
+/**
+ * Convert an absolute caller location to a project-relative one when the
+ * caller file lives inside the project. Keeps locations stable and blame-able
+ * from the project root (COVERAGE-CONTEXT-2); callers outside the project
+ * stay absolute.
+ */
+function toProjectRelativeLocation(location, requirementsDir) {
+    if (!requirementsDir) {
+        return location;
+    }
+    const match = /^(.+):(\d+)$/.exec(location);
+    if (!match) {
+        return location;
+    }
+    const [, filePath, lineNumber] = match;
+    const projectRoot = path.dirname(requirementsDir);
+    const relative = toProjectRelativePath(filePath, projectRoot);
+    if (relative === filePath) {
+        return location;
+    }
+    return `${relative}:${lineNumber}`;
+}
+/**
+ * Normalize an absolute path inside the project to a project-relative one
+ * (COVERAGE-CONTEXT-2: stable, blame-able from the project root). Paths that
+ * are already relative or fall outside the project are returned unchanged.
+ */
+export function toProjectRelativePath(filePath, projectRoot) {
+    if (!path.isAbsolute(filePath)) {
+        return filePath;
+    }
+    const relative = path.relative(projectRoot, filePath);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        return filePath;
+    }
+    return relative;
+}
 // Get caller's directory (full path) for finding .requirements
 function getCallerDirectory() {
     const error = new Error();
@@ -100,10 +168,15 @@ function getCallerDirectory() {
  * HARNESS-REQUIREMENT-3.2: Works correctly when tests run in parallel processes
  *
  * @param reqId - Full requirement path (e.g., 'REQ-123.given' or 'REQ-123.0.1')
+ * @param projectRoot - Explicit project root; tracking is written to this
+ *   project's cache when provided (HARNESS-REQUIREMENT-6.0)
  */
-export function trackRequirement(reqId) {
-    const callerLocation = getCallerLocation();
-    const runId = ensureTestRun();
+export function trackRequirement(reqId, projectRoot) {
+    const runId = ensureTestRun(projectRoot);
+    const targetRequirementsDir = projectRoot
+        ? path.join(projectRoot, ".requirements")
+        : requirementsDirCached;
+    const callerLocation = toProjectRelativeLocation(getCallerLocation(), targetRequirementsDir);
     // Track in memory for backward compatibility
     if (!trackedRequirements.has(reqId)) {
         trackedRequirements.set(reqId, {
@@ -116,14 +189,14 @@ export function trackRequirement(reqId) {
     tracked.accessedAt.push(callerLocation);
     // Append to JSONL file for cross-process tracking
     // HARNESS-REQUIREMENT-3.2: JSONL is append-only, safe for parallel workers
-    if (requirementsDirCached) {
+    if (targetRequirementsDir) {
         const entry = {
             requirementKey: reqId,
             callerLocation,
             timestamp: Date.now(),
             testRunId: runId,
         };
-        appendTrackingEntry(requirementsDirCached, entry);
+        appendTrackingEntry(targetRequirementsDir, entry);
     }
 }
 /**
@@ -144,6 +217,7 @@ export function clearTracking() {
     trackedRequirements.clear();
     testRunId = null;
     requirementsDirCached = null;
+    runIdsByRequirementsDir.clear();
 }
 /**
  * Initialize a test run (called by globalSetup).

package/dist/push/core.d.ts

@@ -26,6 +26,14 @@ export interface ParsedFile {
     markdownContent: string;
     /** Requirement count for display */
     requirementCount: number;
+    /**
+     * DOC-HEADER-14: the frontmatter exactly as the user wrote it, including
+     * keys the schema doesn't recognize — merged back on the post-push rewrite
+     * so those keys survive.
+     */
+    rawFrontmatter?: Record<string, unknown>;
+    /** DOC-HEADER-11.4: true when defaultPrefix was inferred from the first requirement rather than read from frontmatter */
+    inferredDefaultPrefix?: boolean;
 }
 /**
  * Cloud document metadata for conflict detection.
@@ -85,8 +93,10 @@ export declare const WEB_APP_URL = "https://app.dotrequirements.io";
 export interface PushResult {
     created: number;
     updated: number;
+    /** filePath disambiguates when two pushed files share a basename */
     errors: Array<{
         fileName: string;
+        filePath: string;
         error: string;
     }>;
     /** IMPORT-3: marker failures that must be surfaced to the user, per file */
@@ -100,6 +110,18 @@ export interface PushResult {
         documentId: string;
         url: string;
     }>;
+    /**
+     * SYNC-FAIL-2: cloud save succeeded but the local file write-back failed.
+     * These documents are synced (counted in created/updated and listed in
+     * `synced`) — the warning carries what the user needs to re-link the file
+     * without creating a duplicate.
+     */
+    writeBackWarnings: Array<{
+        fileName: string;
+        filePath: string;
+        documentId: string;
+        error: string;
+    }>;
 }
 /**
  * Extract markdown content from a file, stripping YAML frontmatter.
@@ -107,11 +129,39 @@ export interface PushResult {
 export declare function extractMarkdownContent(rawContent: string): string;
 /**
  * Parse files for push. Returns parsed files with metadata and content.
+ *
+ * Throws (via `parseRequirementsFromFile`) if any file is syntactically
+ * invalid. Callers that need one bad file not to abort the batch should parse
+ * files individually and collect failures (see the MCP push handler, #45).
  */
 export declare function parseFilesForPush(filePaths: string[]): {
     parsedFiles: ParsedFile[];
     totalRequirements: number;
 };
+export interface ParseFailure {
+    filePath: string;
+    error: string;
+}
+/**
+ * SYNC-FAIL-4.0: parse files one at a time so a single invalid file cannot
+ * abort the batch — its failure is collected per file while the valid files
+ * still parse. Shared by the CLI push command and the MCP push handler (#45)
+ * so their isolation semantics cannot drift.
+ *
+ * Note: cross-file checks that need the whole batch (e.g. SYNC-FAIL-3
+ * duplicate document IDs) are enforced downstream in dryRunPush, not here.
+ */
+export declare function parseFilesForPushIndividually(filePaths: string[]): {
+    parsedFiles: ParsedFile[];
+    totalRequirements: number;
+    parseFailures: ParseFailure[];
+};
+/**
+ * SYNC-FAIL-3: two ParsedFiles carrying the same document.id would both push
+ * as updates to one cloud document — last writer wins and the first spec is
+ * silently destroyed. Abort instead, naming both files and the shared id.
+ */
+export declare function assertNoDuplicateDocumentIds(parsedFiles: ParsedFile[]): void;
 /**
  * Execute dry run phase: validate all files against Convex and detect conflicts.
  */