@popoverai/dotrequirements 0.15.0 → 0.16.0

package/dist/commands/push.d.ts

@@ -2,10 +2,5 @@ interface PushOptions {
     yes?: boolean;
 }
 export declare function pushCommand(file: string | undefined, options: PushOptions): Promise<void>;
-/**
- * Extract markdown content from a file, stripping YAML frontmatter.
- * Exported for testing.
- */
-export declare function extractMarkdownContent(rawContent: string): string;
 export {};
 //# sourceMappingURL=push.d.ts.map

package/dist/commands/push.js

@@ -1,13 +1,11 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { ConvexHttpClient } from 'convex/browser';
-import { getConvexUrl } from '../config.js';
-import { parseRequirementsFromFile, getAllRequirements, parseRequirementKey, buildRequirementsFile } from '../schema/index.js';
-import { api } from '../convex.js';
 import * as readline from 'readline';
 import { brand } from '../utils/brand.js';
 import { findRequirementsFiles } from '../mcp/requirements.js';
 import { getProjectCredentials } from '../utils/project-settings.js';
+import { getConvexUrl } from '../config.js';
+import { parseFilesForPush, dryRunPush, executePush, } from '../push/index.js';
 export async function pushCommand(file, options) {
     try {
         console.log(`Preparing to push requirements to ${brand} cloud...\n`);
@@ -35,164 +33,42 @@ export async function pushCommand(file, options) {
         }
         // Parse all local files
         console.log('Parsing local requirements...');
-        const parsedFiles = [];
-        let totalRequirements = 0;
-        for (const filePath of filesToPush) {
-            const fileName = path.basename(filePath);
-            console.log(`  Reading ${fileName}...`);
-            // Read raw file content
-            const rawContent = fs.readFileSync(filePath, 'utf-8');
-            // Parse to get metadata and requirements
-            const parsed = parseRequirementsFromFile(filePath);
-            const flatRequirements = getAllRequirements(parsed.requirements);
-            // Extract markdown content (everything after frontmatter)
-            const markdownContent = extractMarkdownContent(rawContent);
-            // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified
-            const doc = parsed.metadata.document;
-            if (doc && !doc.defaultPrefix && flatRequirements.length > 0) {
-                const firstReq = flatRequirements[0];
-                if (firstReq) {
-                    const parsedKey = parseRequirementKey(firstReq.id);
-                    if (parsedKey) {
-                        doc.defaultPrefix = parsedKey.prefix;
-                        console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
-                    }
-                }
-            }
-            parsedFiles.push({
-                filePath,
-                metadata: parsed.metadata,
-                markdownContent,
-                requirementCount: flatRequirements.length,
-            });
-            totalRequirements += flatRequirements.length;
-        }
-        console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
-        // Connect to Convex
-        const convexUrl = getConvexUrl();
-        const client = new ConvexHttpClient(convexUrl);
-        // Phase 1: Dry run to categorize all files
-        console.log('Validating documents...');
-        const dryRunResults = [];
+        const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+        // Log file parsing progress
         for (const file of parsedFiles) {
-            const doc = file.metadata.document;
             const fileName = path.basename(file.filePath);
-            if (!doc) {
-                // No document section - mark as invalid locally
-                dryRunResults.push({
-                    file,
-                    result: {
-                        dryRun: true,
-                        action: 'invalid',
-                        title: fileName,
-                        error: 'Missing document section in frontmatter',
-                    },
-                });
-                continue;
-            }
-            try {
-                const result = await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
-                    projectAuth: {
-                        projectSlug: projectId,
-                        projectSecret,
-                    },
-                    target: { type: 'project', slug: projectId },
-                    documentId: doc.id,
-                    title: doc.title,
-                    markdownContent: file.markdownContent,
-                    defaultPrefix: doc.defaultPrefix,
-                    dryRun: true,
-                });
-                dryRunResults.push({ file, result });
-            }
-            catch (err) {
-                dryRunResults.push({
-                    file,
-                    result: {
-                        dryRun: true,
-                        action: 'invalid',
-                        title: doc.title,
-                        error: err.message,
-                    },
-                });
+            const doc = file.metadata.document;
+            if (doc?.defaultPrefix && !file.metadata.document?.defaultPrefix) {
+                console.log(`  Reading ${fileName}...`);
+                console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
             }
-        }
-        // Categorize results
-        const updates = dryRunResults.filter(r => r.result.action === 'update');
-        const creates = dryRunResults.filter(r => r.result.action === 'create');
-        const notFound = dryRunResults.filter(r => r.result.action === 'not_found');
-        const invalid = dryRunResults.filter(r => r.result.action === 'invalid');
-        // Check for conflicts on updates (cloud changed since last pull)
-        const conflicts = [];
-        if (updates.length > 0) {
-            const docIds = updates.map(u => u.result.documentId);
-            const cloudMetadata = await client.query(api.documents.queries.getDocumentsMetadata, {
-                projectAuth: {
-                    projectSlug: projectId,
-                    projectSecret,
-                },
-                target: { type: 'project', slug: projectId },
-                documentIds: docIds,
-            });
-            const cloudMetaByDocId = new Map(cloudMetadata.map((m) => [m.documentId, m]));
-            for (const item of updates) {
-                const docId = item.result.documentId;
-                const cloudMeta = cloudMetaByDocId.get(docId);
-                if (cloudMeta && item.file.metadata.pulledAt) {
-                    const pulledAtMs = new Date(item.file.metadata.pulledAt).getTime();
-                    if (cloudMeta.updatedAt > pulledAtMs) {
-                        conflicts.push({ item, cloudMeta });
-                    }
-                }
+            else {
+                console.log(`  Reading ${fileName}...`);
             }
         }
+        console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
+        // Build credentials
+        const credentials = {
+            projectId,
+            projectSecret,
+            convexUrl: getConvexUrl(),
+        };
+        // Phase 1: Dry run
+        console.log('Validating documents...');
+        const dryRunResult = await dryRunPush(parsedFiles, credentials);
         // Display unified summary
-        console.log('\n=== Push Summary ===\n');
-        if (updates.length > 0) {
-            console.log(`Updated documents (${updates.length}):`);
-            for (const { file, result } of updates) {
-                const fileName = path.basename(file.filePath);
-                const hasConflict = conflicts.some(c => c.item.file === file);
-                const conflictNote = hasConflict ? ' ⚠️  [cloud changed since pull]' : '';
-                const warningNote = result.warning ? ` (${result.warning})` : '';
-                console.log(`  ~ ${fileName}${conflictNote}${warningNote}`);
-            }
-            console.log();
-        }
-        if (creates.length > 0) {
-            console.log(`New documents (${creates.length}):`);
-            for (const { file, result } of creates) {
-                const fileName = path.basename(file.filePath);
-                const warningNote = result.warning ? ` (${result.warning})` : '';
-                console.log(`  + ${fileName}${warningNote}`);
-            }
-            console.log();
-        }
-        if (notFound.length > 0) {
-            console.log(`Documents not found in cloud (${notFound.length}) - will create new:`);
-            for (const { file, result } of notFound) {
-                const fileName = path.basename(file.filePath);
-                console.log(`  ! ${fileName} (ID: ${result.documentId})`);
-            }
-            console.log();
-        }
-        if (invalid.length > 0) {
-            console.log(`Skipped - invalid files (${invalid.length}):`);
-            for (const { file, result } of invalid) {
-                const fileName = path.basename(file.filePath);
-                console.log(`  ✗ ${fileName}: ${result.error}`);
-            }
-            console.log();
-        }
+        displayDryRunSummary(dryRunResult);
         // Check if there's anything to push
-        const pushableFiles = [...updates, ...creates, ...notFound];
-        if (pushableFiles.length === 0) {
+        const pushableCount = dryRunResult.updates.length +
+            dryRunResult.creates.length +
+            dryRunResult.notFound.length;
+        if (pushableCount === 0) {
             console.log('No valid documents to push.');
             return;
         }
         // Single confirmation prompt
         if (!options.yes) {
-            const hasConflicts = conflicts.length > 0;
+            const hasConflicts = dryRunResult.conflicts.length > 0;
             const prompt = hasConflicts
                 ? 'Continue with push? (will overwrite cloud changes) [y/N] '
                 : 'Continue with push? [y/N] ';
@@ -204,59 +80,35 @@ export async function pushCommand(file, options) {
         }
         // Phase 2: Execute push
         console.log('\nPushing documents to cloud...');
-        let created = 0;
-        let updated = 0;
-        for (const { file, result } of pushableFiles) {
-            const doc = file.metadata.document;
+        const result = await executePush(dryRunResult, credentials);
+        // Display results
+        for (const { file, result: dryResult } of [
+            ...dryRunResult.updates,
+            ...dryRunResult.creates,
+            ...dryRunResult.notFound,
+        ]) {
             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, {
-                    projectAuth: {
-                        projectSlug: projectId,
-                        projectSecret,
-                    },
-                    target: { type: 'project', slug: projectId },
-                    documentId: effectiveDocId,
-                    title: doc.title,
-                    markdownContent: file.markdownContent,
-                    defaultPrefix: doc.defaultPrefix,
-                    dryRun: false,
-                });
-                const isCreate = result.action === 'create' || result.action === 'not_found';
-                if (isCreate) {
-                    // New document - write ID back to file
-                    doc.id = pushResult;
-                    file.metadata.pulledAt = new Date().toISOString();
-                    file.metadata.version = 1;
-                    const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                    fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
-                    console.log(`  ✓ Created: ${fileName} → ${pushResult}`);
-                    created++;
-                }
-                else {
-                    // Update pulledAt to reflect this push
-                    file.metadata.pulledAt = new Date().toISOString();
-                    file.metadata.version = (file.metadata.version || 0) + 1;
-                    const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
-                    fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
-                    console.log(`  ✓ Updated: ${fileName}`);
-                    updated++;
-                }
+            const isCreate = dryResult.action === 'create' || dryResult.action === 'not_found';
+            // Check if this file had an error
+            const error = result.errors.find((e) => e.fileName === fileName);
+            if (error) {
+                console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
             }
-            catch (err) {
-                console.error(`  ✗ Failed: ${fileName} - ${err.message}`);
+            else if (isCreate) {
+                console.log(`  ✓ Created: ${fileName} → ${file.metadata.document?.id}`);
+            }
+            else {
+                console.log(`  ✓ Updated: ${fileName}`);
             }
         }
         console.log(`\n✓ Push complete!`);
-        if (created > 0) {
-            console.log(`  Created: ${created} document(s)`);
+        if (result.created > 0) {
+            console.log(`  Created: ${result.created} document(s)`);
         }
-        if (updated > 0) {
-            console.log(`  Updated: ${updated} document(s)`);
+        if (result.updated > 0) {
+            console.log(`  Updated: ${result.updated} document(s)`);
         }
-        if (created === 0 && updated === 0) {
+        if (result.created === 0 && result.updated === 0) {
             console.log('  No documents were pushed.');
         }
     }
@@ -266,16 +118,47 @@ export async function pushCommand(file, options) {
     }
 }
 /**
- * Extract markdown content from a file, stripping YAML frontmatter.
- * Exported for testing.
+ * Display the dry run summary.
  */
-export function extractMarkdownContent(rawContent) {
-    // Match YAML frontmatter: starts with ---, ends with ---
-    const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n*/);
-    if (frontmatterMatch) {
-        return rawContent.slice(frontmatterMatch[0].length);
+function displayDryRunSummary(dryRunResult) {
+    const { updates, creates, notFound, invalid, conflicts } = dryRunResult;
+    console.log('\n=== Push Summary ===\n');
+    if (updates.length > 0) {
+        console.log(`Updated documents (${updates.length}):`);
+        for (const { file, result } of updates) {
+            const fileName = path.basename(file.filePath);
+            const hasConflict = conflicts.some((c) => c.item.file === file);
+            const conflictNote = hasConflict ? ' ⚠️  [cloud changed since pull]' : '';
+            const warningNote = result.warning ? ` (${result.warning})` : '';
+            console.log(`  ~ ${fileName}${conflictNote}${warningNote}`);
+        }
+        console.log();
+    }
+    if (creates.length > 0) {
+        console.log(`New documents (${creates.length}):`);
+        for (const { file, result } of creates) {
+            const fileName = path.basename(file.filePath);
+            const warningNote = result.warning ? ` (${result.warning})` : '';
+            console.log(`  + ${fileName}${warningNote}`);
+        }
+        console.log();
+    }
+    if (notFound.length > 0) {
+        console.log(`Documents not found in cloud (${notFound.length}) - will create new:`);
+        for (const { file, result } of notFound) {
+            const fileName = path.basename(file.filePath);
+            console.log(`  ! ${fileName} (ID: ${result.documentId})`);
+        }
+        console.log();
+    }
+    if (invalid.length > 0) {
+        console.log(`Skipped - invalid files (${invalid.length}):`);
+        for (const { file, result } of invalid) {
+            const fileName = path.basename(file.filePath);
+            console.log(`  ✗ ${fileName}: ${result.error}`);
+        }
+        console.log();
     }
-    return rawContent;
 }
 /**
  * Prompt user for confirmation

package/dist/harness/cache.d.ts

@@ -70,7 +70,8 @@ export declare function findRequirementsFiles(projectRoot: string): string[];
  */
 export declare function writeLookupCache(requirementsDir: string, requirements: RequirementNode[]): void;
 /**
- * Read the lookup cache, returning null if not found or invalid
+ * 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.
  */
 export declare function readLookupCache(requirementsDir: string): LookupCache | null;
 /**

package/dist/harness/cache.js

@@ -101,7 +101,28 @@ export function writeLookupCache(requirementsDir, requirements) {
     fs.writeFileSync(lookupPath, JSON.stringify(lookup, null, 2));
 }
 /**
- * Read the lookup cache, returning null if not found or invalid
+ * Check if any source file is newer than the cache file.
+ * Returns true if cache is stale and should be invalidated.
+ */
+function isCacheStale(requirementsDir, cacheMtime) {
+    const projectRoot = path.dirname(requirementsDir);
+    const sourceFiles = findRequirementsFiles(projectRoot);
+    for (const file of sourceFiles) {
+        try {
+            const stat = fs.statSync(file);
+            if (stat.mtimeMs > cacheMtime) {
+                return true;
+            }
+        }
+        catch {
+            // File might have been deleted, ignore
+        }
+    }
+    return false;
+}
+/**
+ * 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.
  */
 export function readLookupCache(requirementsDir) {
     const cacheDir = getCacheDir(requirementsDir);
@@ -109,6 +130,16 @@ export function readLookupCache(requirementsDir) {
     if (!fs.existsSync(lookupPath)) {
         return null;
     }
+    // Check if cache is stale (any source file newer than cache)
+    try {
+        const cacheStat = fs.statSync(lookupPath);
+        if (isCacheStale(requirementsDir, cacheStat.mtimeMs)) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
     try {
         const content = fs.readFileSync(lookupPath, 'utf-8');
         return JSON.parse(content);

package/dist/mcp/convexClient.d.ts

@@ -47,5 +47,12 @@ export declare function getProjectCoverage(projectId: string, projectSecret: str
     }>;
     untested: string[];
 }>;
+/**
+ * PROJ-CONTEXT-7: Query Convex for project context (AI style guidelines)
+ */
+export declare function getProjectContext(projectId: string, projectSecret: string, convexUrl: string): Promise<{
+    projectContext: string | null;
+    requirementsStyleContext: string | null;
+} | null>;
 export {};
 //# sourceMappingURL=convexClient.d.ts.map

package/dist/mcp/convexClient.js

@@ -47,7 +47,11 @@ export async function getRequirementCoverage(requirementKey, projectId, projectS
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
 }
 /**
  * Query Convex for project coverage summary
@@ -76,6 +80,50 @@ export async function getProjectCoverage(projectId, projectSecret, convexUrl, op
     if (!response.ok) {
         throw new Error(`Failed to query coverage: ${response.statusText}`);
     }
-    return await response.json();
+    const json = await response.json();
+    if (json.status === 'error') {
+        throw new Error(`Convex query failed: ${json.errorMessage}`);
+    }
+    return json.value;
+}
+/**
+ * PROJ-CONTEXT-7: Query Convex for project context (AI style guidelines)
+ */
+export async function getProjectContext(projectId, projectSecret, convexUrl) {
+    try {
+        const response = await fetch(`${convexUrl}/api/query`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                path: 'projects/queries:get',
+                args: {
+                    projectAuth: {
+                        projectSlug: projectId,
+                        projectSecret,
+                    },
+                    target: {
+                        type: 'project',
+                        slug: projectId,
+                    },
+                },
+                format: 'json',
+            }),
+        });
+        if (!response.ok) {
+            return null;
+        }
+        const json = await response.json();
+        if (json.status === 'error' || !json.value) {
+            return null;
+        }
+        return {
+            projectContext: json.value.projectContext ?? null,
+            requirementsStyleContext: json.value.requirementsStyleContext ?? null,
+        };
+    }
+    catch {
+        // Non-fatal: return null if query fails
+        return null;
+    }
 }
 //# sourceMappingURL=convexClient.js.map

package/dist/mcp/index.js

@@ -6,12 +6,14 @@ import { loadAllRequirements, searchRequirements, getRequirementById, getRequire
 import { findAllTestReferences, getReferencedRequirementIds, } from './grep.js';
 import { findTestCodeForRequirement, findFilesWithRequirement, } from './testCodeExtractor.js';
 import { glob } from 'glob';
-import { CONVEX_URL, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, } from './convexClient.js';
+import { CONVEX_URL, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, getProjectContext, } from './convexClient.js';
 import { discoverProjects, resolveProject, } from '../utils/project-discovery.js';
 import { getCredentialsFromEnv } from '../utils/project-settings.js';
-import { readFileSync } from 'fs';
+import { readFileSync, existsSync } from 'fs';
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { dirname, join, resolve, basename } from 'path';
+import { parseFilesForPush, dryRunPush, executePush, } from '../push/index.js';
+import { findRequirementsFiles } from './requirements.js';
 // Read version from package.json
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -1054,6 +1056,24 @@ ${projectList || '(none found)'}`,
 
 **Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
                 }
+                // PROJ-CONTEXT-7: Try to fetch user-provided style context from cloud
+                let userStyleGuidance = '';
+                try {
+                    const project = await getProjectFromDiscovery();
+                    const context = await getProjectContext(project.projectId, project.projectSecret, CONVEX_URL);
+                    if (context?.requirementsStyleContext?.trim()) {
+                        userStyleGuidance = `
+
+## User-Provided Style Guidelines
+
+The following style guidelines were provided by the project owner. When these conflict with the defaults above, prioritize the user's guidelines.
+
+${context.requirementsStyleContext.trim()}`;
+                    }
+                }
+                catch {
+                    // No credentials or cloud unavailable - continue without user context
+                }
                 const template = `---
 document:
   title: "Example Requirements"
@@ -1149,6 +1169,7 @@ ${labelGuidance}
 - Note: Even technical requirements can be user-centric: "95 percent of users experience under 1 second of delay"
 
 **11. Decompose Large Requirements**: If it can't be validated with a single test, break it down.
+${userStyleGuidance}
 
 ## Example Requirements
 
@@ -1281,21 +1302,13 @@ describe(requirement('AUTH-LOGIN-1'), () => {
             }
             case 'push_requirements': {
                 const { filePath, confirmed = false, projectId: projectIdParam } = args;
-                const fs = await import('fs');
-                const path = await import('path');
-                const { parseRequirementsFromFile, getAllRequirements } = await import('../schema/index.js');
-                const { ConvexHttpClient } = await import('convex/browser');
                 // Get project (credentials come from project object, works with both file and env auth)
                 const project = await getProjectFromDiscovery(projectIdParam);
-                const convexUrl = CONVEX_URL;
-                const projectId = project.projectId;
-                const projectSecret = project.projectSecret;
                 // Determine files to push
-                const requirementsDir = path.resolve(project.path, '.requirements');
                 let filesToPush;
                 if (filePath) {
-                    const fullPath = path.resolve(project.path, filePath);
-                    if (!fs.existsSync(fullPath)) {
+                    const fullPath = resolve(project.path, filePath);
+                    if (!existsSync(fullPath)) {
                         return {
                             content: [
                                 {
@@ -1309,78 +1322,121 @@ describe(requirement('AUTH-LOGIN-1'), () => {
                     filesToPush = [fullPath];
                 }
                 else {
-                    if (!fs.existsSync(requirementsDir)) {
-                        return {
-                            content: [
-                                {
-                                    type: 'text',
-                                    text: 'No .requirements/ directory found',
-                                },
-                            ],
-                            isError: true,
-                        };
-                    }
-                    const files = fs.readdirSync(requirementsDir);
-                    filesToPush = files
-                        .filter((f) => f.endsWith('.requirements.md'))
-                        .map((f) => path.join(requirementsDir, f));
+                    // Use same file discovery as CLI - searches entire workspace
+                    filesToPush = await findRequirementsFiles(project.path);
                     if (filesToPush.length === 0) {
                         return {
                             content: [
                                 {
                                     type: 'text',
-                                    text: 'No Markdown files (*.requirements.md) found in .requirements/',
+                                    text: 'No *.requirements.md files found. Nothing to push.',
                                 },
                             ],
-                            isError: true,
                         };
                     }
                 }
-                // Parse local requirements
-                const allLocalRequirements = [];
-                for (const file of filesToPush) {
-                    const parsed = parseRequirementsFromFile(file);
-                    const flatReqs = getAllRequirements(parsed.requirements);
-                    for (const req of flatReqs) {
-                        allLocalRequirements.push({
-                            key: req.id,
-                            label: req.label,
-                            content: req.content,
-                            rootId: req.metadata?.rootId,
-                            position: req.metadata?.position,
-                        });
-                    }
+                // Parse files
+                const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+                // Build credentials
+                const credentials = {
+                    projectId: project.projectId,
+                    projectSecret: project.projectSecret,
+                    convexUrl: CONVEX_URL,
+                };
+                // Run dry run (always, even when confirmed - ensures fresh state)
+                const dryRunResult = await dryRunPush(parsedFiles, credentials);
+                // Check if there's anything to push
+                const pushableCount = dryRunResult.updates.length +
+                    dryRunResult.creates.length +
+                    dryRunResult.notFound.length;
+                if (pushableCount === 0 && dryRunResult.invalid.length > 0) {
+                    // Only invalid files
+                    const invalidList = dryRunResult.invalid
+                        .map(({ file, result }) => `- ${basename(file.filePath)}: ${result.error}`)
+                        .join('\n');
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `✗ No valid documents to push.\n\n**Invalid files:**\n${invalidList}`,
+                            },
+                        ],
+                        isError: true,
+                    };
                 }
                 if (!confirmed) {
-                    // First call: show diff
-                    const client = new ConvexHttpClient(convexUrl);
-                    // Note: We need a public query to fetch requirements
-                    // For now, just show what would be pushed
+                    // First call: show preview with real dry run results
+                    let summary = `# Push Preview\n\n**Files:** ${parsedFiles.length}\n**Requirements:** ${totalRequirements}\n\n`;
+                    if (dryRunResult.updates.length > 0) {
+                        summary += `## Updates (${dryRunResult.updates.length})\n`;
+                        for (const { file, result } of dryRunResult.updates) {
+                            const fileName = basename(file.filePath);
+                            const hasConflict = dryRunResult.conflicts.some((c) => c.item.file === file);
+                            const conflictNote = hasConflict ? ' ⚠️ [cloud changed since pull]' : '';
+                            const warningNote = result.warning ? ` (${result.warning})` : '';
+                            summary += `- ~ ${fileName}${conflictNote}${warningNote}\n`;
+                        }
+                        summary += '\n';
+                    }
+                    if (dryRunResult.creates.length > 0) {
+                        summary += `## New Documents (${dryRunResult.creates.length})\n`;
+                        for (const { file, result } of dryRunResult.creates) {
+                            const fileName = basename(file.filePath);
+                            const warningNote = result.warning ? ` (${result.warning})` : '';
+                            summary += `- + ${fileName}${warningNote}\n`;
+                        }
+                        summary += '\n';
+                    }
+                    if (dryRunResult.notFound.length > 0) {
+                        summary += `## Not Found in Cloud (${dryRunResult.notFound.length}) - will create new\n`;
+                        for (const { file, result } of dryRunResult.notFound) {
+                            const fileName = basename(file.filePath);
+                            summary += `- ! ${fileName} (ID: ${result.documentId})\n`;
+                        }
+                        summary += '\n';
+                    }
+                    if (dryRunResult.invalid.length > 0) {
+                        summary += `## Skipped - Invalid (${dryRunResult.invalid.length})\n`;
+                        for (const { file, result } of dryRunResult.invalid) {
+                            const fileName = basename(file.filePath);
+                            summary += `- ✗ ${fileName}: ${result.error}\n`;
+                        }
+                        summary += '\n';
+                    }
+                    if (dryRunResult.conflicts.length > 0) {
+                        summary += `⚠️ **Warning:** ${dryRunResult.conflicts.length} file(s) have cloud changes since last pull. Pushing will overwrite those changes.\n\n`;
+                    }
+                    summary += `**To proceed:** Call this tool again with \`confirmed: true\``;
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `# Push Preview\n\n**Files:** ${filesToPush.length}\n**Requirements:** ${allLocalRequirements.length}\n\n**Requirements to push:**\n${allLocalRequirements.map((r) => `- ${r.key}: ${r.label} → ${r.content}`).join('\n')}\n\n⚠️ This will **replace all** requirements in the project.\n\n**To proceed:** Call this tool again with \`confirmed: true\``,
+                                text: summary,
                             },
                         ],
                     };
                 }
                 // Second call: execute push
-                const client = new ConvexHttpClient(convexUrl);
                 try {
-                    const result = await client.mutation('requirements/mutations:bulkReplace', {
-                        projectAuth: {
-                            projectSlug: projectId,
-                            projectSecret,
-                        },
-                        target: { type: 'project', slug: projectId },
-                        requirements: allLocalRequirements,
-                    });
+                    const result = await executePush(dryRunResult, credentials);
+                    let 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`;
+                    }
+                    if (result.errors.length > 0) {
+                        output += `\n**Errors:**\n`;
+                        for (const { fileName, error } of result.errors) {
+                            output += `- ${fileName}: ${error}\n`;
+                        }
+                    }
                     return {
                         content: [
                             {
                                 type: 'text',
-                                text: `✓ Push complete!\n\n**Inserted:** ${result.inserted}\n**Deleted:** ${result.deleted}`,
+                                text: output,
                             },
                         ],
                     };

package/dist/push/core.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared push logic for CLI and MCP.
+ *
+ * This module contains the core push functionality that both the CLI push command
+ * and MCP push_requirements tool use. It handles:
+ * - Parsing local files
+ * - Dry run validation with Convex
+ * - Conflict detection
+ * - Executing the push
+ * - Updating local files with document IDs and timestamps
+ */
+import type { Metadata } from '../schema/index.js';
+export interface PushCredentials {
+    projectId: string;
+    projectSecret: string;
+    convexUrl: string;
+}
+/**
+ * Parsed file ready for push.
+ * SYNC-ARCH-1: Documents are the sync unit, not individual requirements.
+ */
+export interface ParsedFile {
+    filePath: string;
+    metadata: Metadata;
+    /** Raw file content (markdown with frontmatter stripped) */
+    markdownContent: string;
+    /** Requirement count for display */
+    requirementCount: number;
+}
+/**
+ * Cloud document metadata for conflict detection.
+ * SYNC-CLI-EDIT-2: Compare pulledAt with cloud updatedAt.
+ */
+export interface CloudDocumentMetadata {
+    documentId: string;
+    version: number;
+    updatedAt: number;
+}
+/**
+ * Dry run result from saveWithRequirements.
+ */
+export interface DryRunResultItem {
+    dryRun: true;
+    action: 'create' | 'update' | 'not_found' | 'invalid';
+    documentId?: string;
+    title?: string;
+    warning?: string;
+    error?: string;
+}
+/**
+ * File with its dry run result.
+ */
+export interface FileWithDryRun {
+    file: ParsedFile;
+    result: DryRunResultItem;
+}
+/**
+ * Conflict information for a file.
+ */
+export interface ConflictInfo {
+    item: FileWithDryRun;
+    cloudMeta: CloudDocumentMetadata;
+}
+/**
+ * Result of the dry run phase.
+ */
+export interface DryRunResult {
+    updates: FileWithDryRun[];
+    creates: FileWithDryRun[];
+    notFound: FileWithDryRun[];
+    invalid: FileWithDryRun[];
+    conflicts: ConflictInfo[];
+    totalRequirements: number;
+}
+/**
+ * Result of the execute phase.
+ */
+export interface PushResult {
+    created: number;
+    updated: number;
+    errors: Array<{
+        fileName: string;
+        error: string;
+    }>;
+}
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ */
+export declare function extractMarkdownContent(rawContent: string): string;
+/**
+ * Parse files for push. Returns parsed files with metadata and content.
+ */
+export declare function parseFilesForPush(filePaths: string[]): {
+    parsedFiles: ParsedFile[];
+    totalRequirements: number;
+};
+/**
+ * Execute dry run phase: validate all files against Convex and detect conflicts.
+ */
+export declare function dryRunPush(parsedFiles: ParsedFile[], credentials: PushCredentials): Promise<DryRunResult>;
+/**
+ * Execute the push: save all pushable files to Convex and update local files.
+ */
+export declare function executePush(dryRunResult: DryRunResult, credentials: PushCredentials): Promise<PushResult>;
+//# sourceMappingURL=core.d.ts.map

package/dist/push/core.js

@@ -0,0 +1,216 @@
+/**
+ * Shared push logic for CLI and MCP.
+ *
+ * This module contains the core push functionality that both the CLI push command
+ * and MCP push_requirements tool use. It handles:
+ * - Parsing local files
+ * - Dry run validation with Convex
+ * - Conflict detection
+ * - Executing the push
+ * - Updating local files with document IDs and timestamps
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ConvexHttpClient } from 'convex/browser';
+import { parseRequirementsFromFile, getAllRequirements, parseRequirementKey, buildRequirementsFile, } from '../schema/index.js';
+import { api } from '../convex.js';
+// ============================================================================
+// Parsing
+// ============================================================================
+/**
+ * Extract markdown content from a file, stripping YAML frontmatter.
+ */
+export function extractMarkdownContent(rawContent) {
+    // Match YAML frontmatter: starts with ---, ends with ---
+    const frontmatterMatch = rawContent.match(/^---\n[\s\S]*?\n---\n*/);
+    if (frontmatterMatch) {
+        return rawContent.slice(frontmatterMatch[0].length);
+    }
+    return rawContent;
+}
+/**
+ * Parse files for push. Returns parsed files with metadata and content.
+ */
+export function parseFilesForPush(filePaths) {
+    const parsedFiles = [];
+    let totalRequirements = 0;
+    for (const filePath of filePaths) {
+        // Read raw file content
+        const rawContent = fs.readFileSync(filePath, 'utf-8');
+        // Parse to get metadata and requirements
+        const parsed = parseRequirementsFromFile(filePath);
+        const flatRequirements = getAllRequirements(parsed.requirements);
+        // Extract markdown content (everything after frontmatter)
+        const markdownContent = extractMarkdownContent(rawContent);
+        // DOC-HEADER-11.1/11.2: Infer prefix from first requirement if not specified
+        const doc = parsed.metadata.document;
+        if (doc && !doc.defaultPrefix && flatRequirements.length > 0) {
+            const firstReq = flatRequirements[0];
+            if (firstReq) {
+                const parsedKey = parseRequirementKey(firstReq.id);
+                if (parsedKey) {
+                    doc.defaultPrefix = parsedKey.prefix;
+                }
+            }
+        }
+        parsedFiles.push({
+            filePath,
+            metadata: parsed.metadata,
+            markdownContent,
+            requirementCount: flatRequirements.length,
+        });
+        totalRequirements += flatRequirements.length;
+    }
+    return { parsedFiles, totalRequirements };
+}
+// ============================================================================
+// Dry Run
+// ============================================================================
+/**
+ * Execute dry run phase: validate all files against Convex and detect conflicts.
+ */
+export async function dryRunPush(parsedFiles, credentials) {
+    const client = new ConvexHttpClient(credentials.convexUrl);
+    const dryRunResults = [];
+    // Phase 1: Dry run to categorize all files
+    for (const file of parsedFiles) {
+        const doc = file.metadata.document;
+        const fileName = path.basename(file.filePath);
+        if (!doc) {
+            // No document section - mark as invalid locally
+            dryRunResults.push({
+                file,
+                result: {
+                    dryRun: true,
+                    action: 'invalid',
+                    title: fileName,
+                    error: 'Missing document section in frontmatter',
+                },
+            });
+            continue;
+        }
+        try {
+            const result = (await client.mutation(api.documents.saveWithRequirements.saveWithRequirements, {
+                projectAuth: {
+                    projectSlug: credentials.projectId,
+                    projectSecret: credentials.projectSecret,
+                },
+                target: { type: 'project', slug: credentials.projectId },
+                documentId: doc.id,
+                title: doc.title,
+                markdownContent: file.markdownContent,
+                defaultPrefix: doc.defaultPrefix,
+                dryRun: true,
+            }));
+            dryRunResults.push({ file, result });
+        }
+        catch (err) {
+            dryRunResults.push({
+                file,
+                result: {
+                    dryRun: true,
+                    action: 'invalid',
+                    title: doc.title,
+                    error: err.message,
+                },
+            });
+        }
+    }
+    // Categorize results
+    const updates = dryRunResults.filter((r) => r.result.action === 'update');
+    const creates = dryRunResults.filter((r) => r.result.action === 'create');
+    const notFound = dryRunResults.filter((r) => r.result.action === 'not_found');
+    const invalid = dryRunResults.filter((r) => r.result.action === 'invalid');
+    // Check for conflicts on updates (cloud changed since last pull)
+    const conflicts = [];
+    if (updates.length > 0) {
+        const docIds = updates.map((u) => u.result.documentId);
+        const cloudMetadata = await client.query(api.documents.queries.getDocumentsMetadata, {
+            projectAuth: {
+                projectSlug: credentials.projectId,
+                projectSecret: credentials.projectSecret,
+            },
+            target: { type: 'project', slug: credentials.projectId },
+            documentIds: docIds,
+        });
+        const cloudMetaByDocId = new Map(cloudMetadata.map((m) => [m.documentId, m]));
+        for (const item of updates) {
+            const docId = item.result.documentId;
+            const cloudMeta = cloudMetaByDocId.get(docId);
+            if (cloudMeta && item.file.metadata.pulledAt) {
+                const pulledAtMs = new Date(item.file.metadata.pulledAt).getTime();
+                if (cloudMeta.updatedAt > pulledAtMs) {
+                    conflicts.push({ item, cloudMeta });
+                }
+            }
+        }
+    }
+    return {
+        updates,
+        creates,
+        notFound,
+        invalid,
+        conflicts,
+        totalRequirements: parsedFiles.reduce((sum, f) => sum + f.requirementCount, 0),
+    };
+}
+// ============================================================================
+// Execute Push
+// ============================================================================
+/**
+ * Execute the push: save all pushable files to Convex and update local files.
+ */
+export async function executePush(dryRunResult, credentials) {
+    const client = new ConvexHttpClient(credentials.convexUrl);
+    const pushableFiles = [
+        ...dryRunResult.updates,
+        ...dryRunResult.creates,
+        ...dryRunResult.notFound,
+    ];
+    let created = 0;
+    let updated = 0;
+    const errors = [];
+    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, {
+                projectAuth: {
+                    projectSlug: credentials.projectId,
+                    projectSecret: credentials.projectSecret,
+                },
+                target: { type: 'project', slug: credentials.projectId },
+                documentId: effectiveDocId,
+                title: doc.title,
+                markdownContent: file.markdownContent,
+                defaultPrefix: doc.defaultPrefix,
+                dryRun: false,
+            }));
+            const isCreate = result.action === 'create' || result.action === 'not_found';
+            if (isCreate) {
+                // New document - write ID back to file
+                doc.id = pushResult;
+                file.metadata.pulledAt = new Date().toISOString();
+                file.metadata.version = 1;
+                const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
+                fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                created++;
+            }
+            else {
+                // Update pulledAt to reflect this push
+                file.metadata.pulledAt = new Date().toISOString();
+                file.metadata.version = (file.metadata.version || 0) + 1;
+                const updatedContent = buildRequirementsFile(file.metadata, file.markdownContent);
+                fs.writeFileSync(file.filePath, updatedContent, 'utf-8');
+                updated++;
+            }
+        }
+        catch (err) {
+            errors.push({ fileName, error: err.message });
+        }
+    }
+    return { created, updated, errors };
+}
+//# sourceMappingURL=core.js.map

package/dist/push/index.d.ts

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

package/dist/push/index.js

@@ -0,0 +1,10 @@
+/**
+ * Push Module
+ *
+ * Shared push logic for syncing local requirements files to the cloud.
+ * Used by both CLI push command and MCP push_requirements tool.
+ */
+export { 
+// Functions
+extractMarkdownContent, parseFilesForPush, dryRunPush, executePush, } from './core.js';
+//# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@popoverai/dotrequirements",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Requirements tracking CLI, test harness, and MCP server",
   "type": "module",
   "bin": {