@popoverai/dotrequirements 0.11.0

package/dist/mcp/index.js

@@ -0,0 +1,1758 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListPromptsRequestSchema, GetPromptRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { loadAllRequirements, searchRequirements, getRequirementById, getRequirementTree, formatRequirementTree, } from './requirements.js';
+import { findAllTestReferences, getReferencedRequirementIds, } from './grep.js';
+import { findTestCodeForRequirement, findFilesWithRequirement, } from './testCodeExtractor.js';
+import { glob } from 'glob';
+import { loadConvexConfig, getRequirementCoverage as queryRequirementCoverage, getProjectCoverage as queryProjectCoverage, } from './convexClient.js';
+import { discoverProjects, resolveProject, } from '../utils/project-discovery.js';
+import { isLocalOnlyProject, CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE } from '../utils/local-project.js';
+// Get project paths from environment variables
+// Supports both PROJ_* pattern (Antigravity) and REQUIREMENTS_DIR fallback
+function getProjectPathsFromEnv() {
+    const projects = new Map();
+    // Check for PROJ_* env vars (project ID -> path mapping)
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith('PROJ_') && value) {
+            const projectId = key.substring(5); // Remove 'PROJ_' prefix
+            projects.set(projectId, value);
+        }
+    }
+    return projects;
+}
+// Get workspace root from environment or default to cwd
+const WORKSPACE_ROOT = process.env.REQUIREMENTS_DIR || process.cwd();
+const PROJECT_PATHS = getProjectPathsFromEnv();
+// Cache for loaded requirements (refreshed on each tool call for now)
+let cachedRequirements = new Map();
+let cachedDiscoveryResult = null;
+async function getRequirements(projectId) {
+    const project = await getProjectFromDiscovery(projectId);
+    const cacheKey = project.projectId;
+    if (!cachedRequirements.has(cacheKey)) {
+        const { flattened } = await loadAllRequirements(project.path);
+        cachedRequirements.set(cacheKey, flattened);
+    }
+    return cachedRequirements.get(cacheKey);
+}
+async function getProjectFromDiscovery(projectId) {
+    const { isConfiguredProject } = await import('../utils/project-discovery.js');
+    // If we have PROJ_* env vars, use those instead of filesystem discovery
+    if (PROJECT_PATHS.size > 0) {
+        const projects = [];
+        // Validate all env var projects
+        for (const [id, path] of PROJECT_PATHS.entries()) {
+            const project = isConfiguredProject(path);
+            if (project) {
+                projects.push(project);
+            }
+        }
+        // Build discovery result from env var projects
+        if (projects.length === 0) {
+            cachedDiscoveryResult = {
+                type: 'none',
+                message: 'No valid dotrequirements projects found in PROJ_* environment variables',
+            };
+        }
+        else if (projects.length === 1) {
+            cachedDiscoveryResult = { type: 'single', project: projects[0] };
+        }
+        else {
+            cachedDiscoveryResult = { type: 'multiple', projects };
+        }
+        return resolveProject(cachedDiscoveryResult, projectId);
+    }
+    // Fall back to filesystem discovery if no PROJ_* env vars
+    if (!cachedDiscoveryResult) {
+        cachedDiscoveryResult = await discoverProjects(WORKSPACE_ROOT);
+    }
+    return resolveProject(cachedDiscoveryResult, projectId);
+}
+// Invalidate cache (call before operations that should see fresh data)
+function invalidateCache() {
+    cachedRequirements.clear();
+    cachedDiscoveryResult = null;
+}
+// Tool definitions
+const tools = [
+    {
+        name: 'debug_mcp_environment',
+        description: 'DEBUG TOOL: Returns diagnostic information about the MCP server environment (working directory, env vars, etc.)',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+    },
+    {
+        name: 'search_requirements',
+        description: 'Search requirements by text or regex query. Searches requirement IDs, content, and labels. Returns matching requirements with their full context.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'Text or regex pattern to search for in requirement IDs, content, or labels',
+                },
+                useRegex: {
+                    type: 'boolean',
+                    description: 'If true, treat query as a regular expression (default: false)',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: ['query'],
+        },
+    },
+    {
+        name: 'get_requirement',
+        description: 'Get a requirement and all its children, including test coverage information. Accepts any requirement path (e.g., "REQ-123" returns the root and all children, "REQ-123.0" returns that node and its children). Shows which tests reference this requirement and includes the test code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'string',
+                    description: 'The requirement ID or path (e.g., "REQ-123" for root, "REQ-123.0" for child)',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: ['id'],
+        },
+    },
+    {
+        name: 'list_untested_requirements',
+        description: 'List all requirements that have no test references. Compares requirements in .requirements/ files against requirement() calls in the codebase.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'list_all_requirements',
+        description: 'List all requirements in the workspace. Returns a summary of all requirements with their IDs, labels, and content.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'get_requirements_by_test',
+        description: 'Get the semantic meaning of requirement() references in a test file. Returns requirement content with line numbers where they are referenced.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                testFile: {
+                    type: 'string',
+                    description: 'Path to the test file to analyze',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: ['testFile'],
+        },
+    },
+    {
+        name: 'get_tests_by_requirement',
+        description: 'Show which requirements from a requirements file have test coverage. Returns a coverage report showing which requirements are tested and where the tests are located. This is the inverse of get_requirements_by_test.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                requirementsFile: {
+                    type: 'string',
+                    description: 'Path to the requirements file (e.g., ".requirements/auth.requirements.md")',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to search (required when multiple projects exist)',
+                },
+            },
+            required: ['requirementsFile'],
+        },
+    },
+    {
+        name: 'get_requirement_coverage',
+        description: 'Get test coverage information for a specific requirement from dot•requirements cloud. Shows when the requirement was last tested, on which branch, and in which test file. Requires DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                requirementKey: {
+                    type: 'string',
+                    description: 'The requirement key (e.g., "REQ-123", "AUTH-LOGIN")',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to use (required when multiple projects exist)',
+                },
+            },
+            required: ['requirementKey'],
+        },
+    },
+    {
+        name: 'get_project_coverage_summary',
+        description: 'Get a summary of test coverage for all requirements in the project from dot•requirements cloud. Shows which requirements have been tested and which haven\'t. Optionally filter by branch or time range. Requires DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                branch: {
+                    type: 'string',
+                    description: 'Optional: Filter coverage to a specific git branch (e.g., "main")',
+                },
+                sinceTimestamp: {
+                    type: 'number',
+                    description: 'Optional: Only show coverage since this timestamp (milliseconds since epoch)',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to use (required when multiple projects exist)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'create_requirement_document',
+        description: 'Returns a well-formatted Markdown template that demonstrates the requirements file format. Use this to understand the format before creating requirements files. AI should use this template as a reference, then use filesystem tools (Read/Write) to create actual files.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Optional: Suggested file path for documentation purposes (e.g., ".requirements/auth.requirements.md")',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'validate_requirements',
+        description: 'Validate a requirements Markdown file without pushing to cloud. Checks schema validity and returns detailed error messages. Works offline (no network/auth required). Use this to verify files before pushing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Path to the Markdown file to validate (e.g., ".requirements/auth.requirements.md")',
+                },
+            },
+            required: ['filePath'],
+        },
+    },
+    {
+        name: 'push_requirements',
+        description: 'Push local requirements from .requirements/ directory to dot•requirements cloud. First call returns diff summary for user review. Second call with confirmed=true executes the push. Requires DOTREQUIREMENTS_PROJECT_SECRET environment variable.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Optional: Push specific file only (e.g., ".requirements/auth.requirements.md"). If omitted, pushes all files.',
+                },
+                confirmed: {
+                    type: 'boolean',
+                    description: 'Set to true to execute the push after reviewing the diff. First call should omit this.',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to use (required when multiple projects exist)',
+                },
+            },
+            required: [],
+        },
+    },
+    {
+        name: 'style_check',
+        description: 'Check requirements files or test files for style issues and best practices. Uses AI to provide actionable feedback on writing style, clarity, and conventions. Supports requirements files (*.requirements.md) and test files (*.test.*, *.spec.*). Requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                filePath: {
+                    type: 'string',
+                    description: 'Path to the file to check (e.g., ".requirements/auth.requirements.md" or "src/auth.test.ts")',
+                },
+                model: {
+                    type: 'string',
+                    description: 'Optional: AI model to use for style checking (default: "anthropic/claude-haiku-4.5"). Supported models: "anthropic/claude-haiku-4.5", "google/gemini-3-flash"',
+                },
+            },
+            required: ['filePath'],
+        },
+    },
+    {
+        name: 'review_test',
+        description: 'Comprehensively review a test file for both style and semantic correctness. Checks if tests actually validate what the requirements specify (not just style). Loads referenced requirements and validates that test setup, actions, and assertions match requirement preconditions, triggers, and outcomes. Requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                testFilePath: {
+                    type: 'string',
+                    description: 'Path to the test file to review (e.g., "src/auth.test.ts")',
+                },
+                projectId: {
+                    type: 'string',
+                    description: 'Optional: Specify which project to use (required when multiple projects exist)',
+                },
+            },
+            required: ['testFilePath'],
+        },
+    },
+];
+// Prompt definitions
+const prompts = [
+    {
+        name: 'capture-requirements',
+        description: 'Guide the user through capturing requirements for a new feature before implementation',
+    },
+    {
+        name: 'write-tests',
+        description: 'Guide writing tests that reference and validate requirements',
+    },
+];
+// Create server
+const server = new Server({
+    name: 'dotrequirements',
+    version: '0.1.0',
+}, {
+    capabilities: {
+        tools: {},
+        prompts: {},
+    },
+});
+// Handle list tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools };
+});
+// Handle list prompts
+server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    return { prompts };
+});
+// Handle get prompt
+server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    const { name } = request.params;
+    if (name === 'capture-requirements') {
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `# Capture Requirements for New Feature
+
+Let's document what this feature should do before building it.
+
+## Questions to Ask
+
+1. What problem does this solve for users?
+2. What are the key behaviors we need to support?
+3. Are there edge cases or error conditions to handle?
+4. How will we know it works correctly?
+
+## Workflow
+
+### Step 1: Create Requirements Document
+
+Use \`create_requirement_document\` to get a template with:
+- Format guidance (discovers existing patterns in your codebase)
+- Style principles for writing clear, testable requirements
+- Examples of well-written requirements
+
+Fill in:
+- Project ID (from .env.local)
+- Document title
+- Requirement IDs, descriptions, and expected behaviors
+
+### Step 2: Validate & Refine (Optional)
+
+- \`validate_requirements\` - Check syntax is correct (works offline)
+- \`style_check\` - Get AI-powered feedback on writing quality and clarity
+
+### Step 3: Push to Cloud
+
+- \`push_requirements\` - Sync to dot•requirements cloud
+  - First call shows a diff preview
+  - Second call with \`confirmed: true\` executes the push
+
+### Step 4: Implement & Test
+
+After capturing requirements:
+1. Implement the feature
+2. Write tests that reference requirements using \`requirement('REQ-ID')\`
+3. Use the test writing skill/prompt for guidance on test structure`,
+                    },
+                },
+            ],
+        };
+    }
+    if (name === 'write-tests') {
+        return {
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: `# Write Tests for Requirements
+
+Let's write tests that validate the requirements.
+
+## Core Principles
+
+### 1. Use requirement() AS the test description
+
+\`\`\`typescript
+// ✅ Good - requirement() is the description
+test(requirement('AUTH-1'), () => { /* test code */ });
+describe(requirement('LOGIN-1.given'), () => { /* setup */ });
+it(requirement('LOGIN-1.then'), () => { /* assert */ });
+
+// ❌ Bad - requirement() in body or comments
+test("user can log in", () => { requirement('AUTH-1'); /* test code */ });
+// LOGIN-1: User can log in
+\`\`\`
+
+### 2. Structure tests to match requirement hierarchy
+
+For structured requirements, nest describe/it blocks:
+
+\`\`\`typescript
+describe(requirement('LOGIN-1'), () => {
+  describe(requirement('LOGIN-1.given'), () => {
+    // Arrange: Set up preconditions
+  });
+
+  describe(requirement('LOGIN-1.when'), () => {
+    // Act: Trigger the behavior
+
+    it(requirement('LOGIN-1.then'), () => {
+      // Assert: Verify outcome
+    });
+  });
+});
+\`\`\`
+
+For simple requirements, one test block is fine:
+
+\`\`\`typescript
+test(requirement('AUTH-1'), () => {
+  // arrange, act, assert all in one
+});
+\`\`\`
+
+### 3. Comments describe the TEST, not the requirement
+
+\`\`\`typescript
+// ✅ Good - comment explains test implementation
+describe(requirement('REQ-1.0'), () => {
+  // Mock user with valid credentials
+});
+
+// ❌ Bad - verbatim copy of requirement text
+describe(requirement('REQ-1.0'), () => {
+  // 0. When a registered user provides valid credentials, they are authenticated
+});
+\`\`\`
+
+### 4. NEVER document coverage in comments
+
+Our MCP tools track coverage automatically. Don't create a second source of truth.
+
+\`\`\`typescript
+// ❌ Bad - creates second source of truth
+/**
+ * Requirements coverage:
+ * - AUTH-9.0: Backend creates project ✓
+ * - AUTH-9.1: CLI writes to .env.local ✓
+ */
+
+// ✅ Good - use MCP tools to check coverage
+// Use get_requirement, get_requirements_by_test
+\`\`\`
+
+## Requirement Path Formats
+
+- \`requirement('AUTH-1')\` - root requirement
+- \`requirement('AUTH-1.0')\` - by numeric position
+- \`requirement('AUTH-1.given')\` - by label (case-insensitive)
+- \`requirement('AUTH-1.given#1')\` - disambiguate duplicate labels
+- \`requirement('AUTH-1.then.and')\` - nested label path
+
+## Workflow
+
+After writing tests:
+
+1. Run tests to ensure they don't throw errors
+2. **ALWAYS run \`review_test\`** on the test file to validate tests actually check what requirements specify
+3. Fix any issues identified by the review
+
+## MCP Tools for Test Writing
+
+- \`get_requirement\` - Get requirement tree with existing coverage
+- \`get_requirements_by_test\` - See requirements referenced in a test file
+- \`list_untested_requirements\` - Find requirements without tests
+- \`review_test\` - Validate test actually checks what requirement specifies (run after writing tests)`,
+                    },
+                },
+            ],
+        };
+    }
+    throw new Error(`Unknown prompt: ${name}`);
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    // Refresh cache for each request to pick up changes
+    invalidateCache();
+    try {
+        switch (name) {
+            case 'debug_mcp_environment': {
+                // Check for Antigravity-specific env vars
+                const antigravityVars = Object.entries(process.env)
+                    .filter(([key]) => key.startsWith('GEMINI_') || key.startsWith('ANTIGRAVITY_'))
+                    .map(([key, value]) => `  ${key}: ${value}`)
+                    .join('\n');
+                // Show discovered projects from env vars
+                const projectList = Array.from(PROJECT_PATHS.entries())
+                    .map(([id, path]) => `  ${id}: ${path}`)
+                    .join('\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# MCP Server Environment Debug Info
+
+**process.cwd():** ${process.cwd()}
+**WORKSPACE_ROOT:** ${WORKSPACE_ROOT}
+**REQUIREMENTS_DIR env:** ${process.env.REQUIREMENTS_DIR || '(not set)'}
+**HOME:** ${process.env.HOME || '(not set)'}
+**PWD:** ${process.env.PWD || '(not set)'}
+**OLDPWD:** ${process.env.OLDPWD || '(not set)'}
+
+**Antigravity/Gemini env vars:**
+${antigravityVars || '(none found)'}
+
+**Projects from PROJ_* env vars:**
+${projectList || '(none found)'}`,
+                        },
+                    ],
+                };
+            }
+            case 'search_requirements': {
+                const { query, useRegex = false, projectId } = args;
+                const requirements = await getRequirements(projectId);
+                let results;
+                if (useRegex) {
+                    try {
+                        const regex = new RegExp(query, 'i');
+                        results = requirements.filter((r) => regex.test(r.id) ||
+                            regex.test(r.content) ||
+                            regex.test(r.label));
+                    }
+                    catch (error) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Invalid regular expression: ${error instanceof Error ? error.message : String(error)}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                }
+                else {
+                    results = searchRequirements(requirements, query);
+                }
+                // Filter to root requirements only (path.length === 0)
+                const rootResults = results.filter((r) => r.path.length === 0);
+                if (rootResults.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No requirements found matching "${query}"${useRegex ? ' (regex)' : ''}`,
+                            },
+                        ],
+                    };
+                }
+                // For each root result, get the full tree
+                const formatted = rootResults
+                    .map((r) => {
+                    const tree = getRequirementTree(requirements, r.id);
+                    const treeFormatted = formatRequirementTree(tree);
+                    return `**${r.id}** (${r.label})\n${r.content}\n_Source: ${r.documentTitle}_\n\n\`\`\`\n${treeFormatted}\n\`\`\``;
+                })
+                    .join('\n\n---\n\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${rootResults.length} requirement(s) matching "${query}"${useRegex ? ' (regex)' : ''}:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_requirement': {
+                const { id, projectId } = args;
+                const project = await getProjectFromDiscovery(projectId);
+                const requirements = await getRequirements(projectId);
+                // Get the tree starting from this ID
+                const tree = getRequirementTree(requirements, id);
+                if (tree.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Requirement "${id}" not found`,
+                            },
+                        ],
+                    };
+                }
+                const root = tree[0];
+                const formatted = formatRequirementTree(tree);
+                // Find test files that reference this requirement
+                const testFiles = await glob('**/*.{test,spec}.{js,jsx,ts,tsx}', {
+                    cwd: project.path,
+                    absolute: true,
+                    ignore: ['**/node_modules/**', '**/dist/**', '**/build/**'],
+                });
+                const matchingFiles = findFilesWithRequirement(testFiles, id);
+                let testCodeSections = [];
+                for (const file of matchingFiles) {
+                    const testRefs = findTestCodeForRequirement(file, id);
+                    // Deduplicate by removing nested blocks - keep only outermost blocks
+                    const deduplicated = testRefs.filter((ref, i) => {
+                        // Check if this ref is contained within any other ref
+                        const isNested = testRefs.some((other, j) => {
+                            if (i === j)
+                                return false;
+                            // other contains ref if it starts before or at the same line and ends after or at the same line
+                            return other.startLine <= ref.startLine && other.endLine >= ref.endLine &&
+                                (other.startLine < ref.startLine || other.endLine > ref.endLine);
+                        });
+                        return !isNested;
+                    });
+                    for (const ref of deduplicated) {
+                        testCodeSections.push(`**${ref.requirementId}** tested in \`${ref.file}:${ref.startLine}-${ref.endLine}\`:\n\n\`\`\`typescript\n${ref.code}\n\`\`\``);
+                    }
+                }
+                const testSection = testCodeSections.length > 0
+                    ? `\n\n## Test Coverage (${testCodeSections.length} reference(s)):\n\n${testCodeSections.join('\n\n---\n\n')}`
+                    : '\n\n## Test Coverage\n\nNo tests found referencing this requirement.';
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# ${id}\n\n**Document:** ${root.documentTitle}\n**Source:** ${root.sourceFile}\n\n## Requirement Tree (${tree.length} node(s)):\n\n\`\`\`\n${formatted}\n\`\`\`${testSection}`,
+                        },
+                    ],
+                };
+            }
+            case 'list_untested_requirements': {
+                const { projectId } = args;
+                const project = await getProjectFromDiscovery(projectId);
+                const requirements = await getRequirements(projectId);
+                const referencedIds = await getReferencedRequirementIds(project.path);
+                // Get root requirements only for this comparison
+                const rootRequirements = requirements.filter((r) => r.path.length === 0);
+                const untested = rootRequirements.filter((r) => !referencedIds.has(r.id));
+                if (untested.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `All ${rootRequirements.length} requirements have test references!`,
+                            },
+                        ],
+                    };
+                }
+                const formatted = untested
+                    .map((r) => `- **${r.id}**: ${r.content}`)
+                    .join('\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${untested.length} untested requirement(s) out of ${rootRequirements.length} total:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'list_all_requirements': {
+                const { projectId } = args;
+                const project = await getProjectFromDiscovery(projectId);
+                const requirements = await getRequirements(projectId);
+                if (requirements.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No requirements found in project: ${project.path}\n\nMake sure .requirements/ directory exists with Markdown files (*.requirements.md).`,
+                            },
+                        ],
+                    };
+                }
+                // Group by root ID
+                const grouped = new Map();
+                for (const req of requirements) {
+                    const existing = grouped.get(req.rootId) || [];
+                    existing.push(req);
+                    grouped.set(req.rootId, existing);
+                }
+                const formatted = Array.from(grouped.entries())
+                    .map(([rootId, reqs]) => {
+                    const root = reqs.find((r) => r.path.length === 0);
+                    const childCount = reqs.length - 1;
+                    return `- **${rootId}**: ${root?.content || '(no content)'} (${childCount} children)`;
+                })
+                    .join('\n');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Found ${grouped.size} requirement(s) with ${requirements.length} total nodes:\n\n${formatted}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_requirements_by_test': {
+                const { testFile, projectId } = args;
+                const requirements = await getRequirements(projectId);
+                // Find all requirement references in the test file
+                const { findRequirementsInFile } = await import('./grep.js');
+                const refs = await findRequirementsInFile(testFile);
+                if (refs.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No requirement references found in "${testFile}"`,
+                            },
+                        ],
+                    };
+                }
+                // For each reference, get the requirement content
+                const entries = refs.map((ref) => {
+                    const req = getRequirementById(requirements, ref.requirementId);
+                    const reqContent = req
+                        ? `**${req.label}:** ${req.content}`
+                        : `(requirement not found)`;
+                    return `**Line ${ref.line}:** \`${ref.requirementId}\` - ${reqContent}`;
+                });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Requirements referenced in "${testFile}":\n\n${entries.join('\n\n')}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_tests_by_requirement': {
+                const { requirementsFile, projectId } = args;
+                const fs = await import('fs');
+                const path = await import('path');
+                const fullPath = path.resolve(WORKSPACE_ROOT, requirementsFile);
+                // Verify file exists
+                if (!fs.existsSync(fullPath)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Requirements file not found: ${requirementsFile}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Verify it's a requirements file
+                if (!requirementsFile.endsWith('.requirements.md')) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File must be a requirements file: *.requirements.md`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Load all requirements from this file
+                const requirements = await getRequirements(projectId);
+                const fileRequirements = requirements.filter(req => path.resolve(WORKSPACE_ROOT, req.sourceFile) === fullPath);
+                if (fileRequirements.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No requirements found in "${requirementsFile}"`,
+                            },
+                        ],
+                    };
+                }
+                // Get unique root requirement IDs from this file
+                const rootIds = new Set(fileRequirements.map(req => req.rootId));
+                // Find all test references in the workspace
+                const allTestRefs = await findAllTestReferences(WORKSPACE_ROOT);
+                // Build coverage map: requirement ID -> list of test references
+                const coverageMap = new Map();
+                for (const ref of allTestRefs) {
+                    if (!coverageMap.has(ref.requirementId)) {
+                        coverageMap.set(ref.requirementId, []);
+                    }
+                    coverageMap.get(ref.requirementId).push(ref);
+                }
+                // Categorize requirements as covered or not covered
+                const covered = [];
+                const notCovered = [];
+                for (const rootId of rootIds) {
+                    // Check if this requirement ID or any of its children are referenced
+                    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);
+                        }
+                    }
+                    if (testsForThisReq.length > 0) {
+                        covered.push({ id: rootId, tests: testsForThisReq });
+                    }
+                    else {
+                        notCovered.push(rootId);
+                    }
+                }
+                // Format output
+                let output = `# Test Coverage for \`${requirementsFile}\`\n\n`;
+                if (covered.length > 0) {
+                    output += `## Covered (${covered.length})\n\n`;
+                    for (const { id, tests } of covered) {
+                        // Group tests by file
+                        const testsByFile = new Map();
+                        for (const test of tests) {
+                            if (!testsByFile.has(test.file)) {
+                                testsByFile.set(test.file, []);
+                            }
+                            testsByFile.get(test.file).push(test.line);
+                        }
+                        output += `- **${id}**: ${tests.length} test${tests.length === 1 ? '' : 's'}\n`;
+                        for (const [file, lines] of testsByFile.entries()) {
+                            const relPath = path.relative(WORKSPACE_ROOT, file);
+                            const lineList = lines.sort((a, b) => a - b).join(', ');
+                            output += `  - \`${relPath}\` (lines ${lineList})\n`;
+                        }
+                    }
+                    output += '\n';
+                }
+                if (notCovered.length > 0) {
+                    output += `## Not Covered (${notCovered.length})\n\n`;
+                    for (const id of notCovered) {
+                        output += `- **${id}**: No tests found\n`;
+                    }
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            case 'get_requirement_coverage': {
+                const { requirementKey, projectId } = args;
+                const project = await getProjectFromDiscovery(projectId);
+                const config = loadConvexConfig(project.path);
+                if (!config) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Coverage queries require DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env file.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // AUTHZ-2.1: Check if project is local-only
+                if (isLocalOnlyProject(config.projectId)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const coverage = await queryRequirementCoverage(requirementKey, config.projectId, config.projectSecret, config.convexUrl);
+                if (!coverage.lastTestedAt) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `**${requirementKey}** has not been tested yet.`,
+                            },
+                        ],
+                    };
+                }
+                const lastTested = new Date(coverage.lastTestedAt);
+                const testLocation = coverage.testFile
+                    ? `\n**Test Location:** \`${coverage.testFile}${coverage.testLine ? `:${coverage.testLine}` : ''}\``
+                    : '';
+                let branchInfo = `\n**Branch:** ${coverage.branch}`;
+                if (coverage.allBranches.length > 1) {
+                    const otherBranches = coverage.allBranches
+                        .filter((b) => b.branch !== coverage.branch)
+                        .map((b) => `- ${b.branch}: ${new Date(b.lastTestedAt).toISOString()}`)
+                        .join('\n');
+                    branchInfo += `\n\n**Also tested on:**\n${otherBranches}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Coverage for ${requirementKey}\n\n**Last Tested:** ${lastTested.toISOString()}${branchInfo}${testLocation}`,
+                        },
+                    ],
+                };
+            }
+            case 'get_project_coverage_summary': {
+                const { branch, sinceTimestamp, projectId } = args;
+                const project = await getProjectFromDiscovery(projectId);
+                const config = loadConvexConfig(project.path);
+                if (!config) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Coverage queries require DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env file.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // AUTHZ-2.1: Check if project is local-only
+                if (isLocalOnlyProject(config.projectId)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const coverage = await queryProjectCoverage(config.projectId, config.projectSecret, config.convexUrl, { branch, sinceTimestamp });
+                const total = coverage.tested.length + coverage.untested.length;
+                const percentage = total > 0 ? ((coverage.tested.length / total) * 100).toFixed(1) : '0.0';
+                let filterInfo = '';
+                if (branch) {
+                    filterInfo += `\n**Branch:** ${branch}`;
+                }
+                if (sinceTimestamp) {
+                    filterInfo += `\n**Since:** ${new Date(sinceTimestamp).toISOString()}`;
+                }
+                let testedSection = '';
+                if (coverage.tested.length > 0) {
+                    const testedList = coverage.tested
+                        .map((t) => {
+                        const date = new Date(t.lastTestedAt).toISOString();
+                        const location = t.testFile
+                            ? ` (\`${t.testFile}${t.testLine ? `:${t.testLine}` : ''}\`)`
+                            : '';
+                        return `- **${t.requirementKey}** [${t.branch}]: ${date}${location}`;
+                    })
+                        .join('\n');
+                    testedSection = `\n\n## Tested Requirements (${coverage.tested.length})\n\n${testedList}`;
+                }
+                let untestedSection = '';
+                if (coverage.untested.length > 0) {
+                    const untestedList = coverage.untested
+                        .map((key) => `- ${key}`)
+                        .join('\n');
+                    untestedSection = `\n\n## Untested Requirements (${coverage.untested.length})\n\n${untestedList}`;
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Project Coverage Summary\n\n**Total Requirements:** ${total}\n**Coverage:** ${percentage}%${filterInfo}${testedSection}${untestedSection}`,
+                        },
+                    ],
+                };
+            }
+            case 'create_requirement_document': {
+                const { filePath = '.requirements/example.requirements.md' } = args;
+                // Discover existing label and key patterns in the codebase
+                // Try to get requirements, but don't fail if no project is configured
+                let requirements = [];
+                try {
+                    requirements = await getRequirements();
+                }
+                catch {
+                    // No project configured - that's okay, we'll just not have discovered patterns
+                }
+                const labels = new Set();
+                const keyPrefixes = new Set();
+                for (const req of requirements) {
+                    // findRequirementsFiles now excludes example/fixture files automatically
+                    // Collect labels (empty string means unlabeled, so skip those)
+                    if (req.label && req.label.trim()) {
+                        labels.add(req.label);
+                    }
+                    // Collect requirement key prefixes (root IDs only)
+                    // Extract prefix from keys like "AUTH-1" -> "AUTH", "LOGIN-FLOW-2" -> "LOGIN-FLOW"
+                    if (req.path.length === 0 && req.id) {
+                        const lastDashIndex = req.id.lastIndexOf('-');
+                        if (lastDashIndex > 0) {
+                            const prefix = req.id.substring(0, lastDashIndex);
+                            keyPrefixes.add(prefix);
+                        }
+                    }
+                }
+                const discoveredLabels = Array.from(labels).sort();
+                const discoveredPrefixes = Array.from(keyPrefixes).sort();
+                let labelGuidance = '';
+                let keyGuidance = '';
+                // Generate label guidance
+                if (discoveredLabels.length > 0) {
+                    const labelList = discoveredLabels.slice(0, 10).map(l => `"${l}"`).join(', ');
+                    const more = discoveredLabels.length > 10 ? ` (and ${discoveredLabels.length - 10} more)` : '';
+                    labelGuidance = `**Existing labels in this codebase:** ${labelList}${more}
+
+**Use these existing labels** to maintain consistency. If you're unsure which labels to use for a new requirement, ask the user.`;
+                }
+                else {
+                    labelGuidance = `**No existing requirements found in this codebase.**
+
+**Default to unlabeled requirements** (\`0. → content\`). If the user wants labels, ask them which format they prefer. Do not choose an opinionated framework like Given/When/Then without explicit user consent.`;
+                }
+                // Generate key guidance
+                if (discoveredPrefixes.length > 0) {
+                    const prefixList = discoveredPrefixes.map(p => `"${p}"`).join(', ');
+                    keyGuidance = `**Existing requirement key prefixes in this codebase:** ${prefixList}
+
+**Match the existing pattern** when creating new requirement keys. Use the same domain prefixes and sequential numbering style.`;
+                }
+                else {
+                    keyGuidance = `**No existing requirements found in this codebase.**
+
+**Use concise domain prefixes** like \`AUTH-1\`, \`LOGIN-1\`, etc. Start numbering at 1 and increment sequentially.`;
+                }
+                const template = `---
+projectId: "your-project-id"
+pulledAt: "${new Date().toISOString()}"
+version: 1
+document:
+  title: "Example Requirements"
+---
+
+# Example Requirements
+
+This template demonstrates the dotrequirements Markdown format and style guidelines.
+
+## Syntax Overview
+
+**File naming:** Use \`*.requirements.md\` pattern (colocated: \`auth.requirements.md\` or centralized: \`.requirements/auth.requirements.md\`)
+
+**Block format:**
+\`\`\`dotrequirements
+KEY: Root requirement content
+  0. → First criterion (unlabeled)
+  1. Label → Second criterion (with label)
+    1.0. → Nested criterion (unlabeled)
+\`\`\`
+
+- First line: \`KEY: content\` (requirement key and description)
+- Criteria: \`position. Label → content\` or \`position. → content\` (unlabeled)
+- Position: \`0\`, \`1\`, \`2\` (top-level) or \`0.0\`, \`1.0\` (nested) - defines hierarchy
+- Delimiter: \`→\` or \`->\` separates optional label from content
+
+## Requirement Keys: Concise and Sequential
+
+${keyGuidance}
+
+**Key format:** \`DOMAIN-FEATURE-N\` where N is sequential (1, 2, 3...)
+
+**Best practices:**
+1. **Concise domains** - Use short, clear prefixes
+   - ✅ \`AUTHZ-1\` (authorization)
+   - ✅ \`AUTH-1\` (authentication)
+   - ❌ \`AUTHORIZATION-1\` (too verbose)
+   - ❌ \`REQ-IDENTITY-ACCESS-AUTHZ-1\` (too nested)
+
+2. **Sequential, 1-indexed numbering** - Start at 1, no padding
+   - ✅ \`LOGIN-1\`, \`LOGIN-2\`, \`LOGIN-3\`
+   - ❌ \`LOGIN-0\` (don't use 0-indexing for requirement IDs)
+   - ❌ \`LOGIN-001\` (no zero-padding)
+
+3. **Unique across project** - Each key must be unique in the entire project
+
+4. **Match existing patterns** - Check existing requirements first and follow their convention
+
+## Labels: Match Your Codebase or Ask the User
+
+${labelGuidance}
+
+## Style Principles for Requirements
+
+**1. Use Concrete Examples**: Replace vague language with specific, testable conditions.
+- ❌ "users can log in" or "works properly"
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**2. Write Natural, Concise Prose**: Avoid terseness and verbosity. Use declarative style (not "should").
+- ❌ "registered user with valid credentials is authenticated" (too terse)
+- ❌ "A registered user, whose account was created on Tuesday and whose life story is as follows..." (too verbose)
+- ✅ "When a registered user provides valid credentials, they are authenticated"
+
+**3. Keep Arrange/Act/Assert in Mind**: Well-written requirements describe preconditions, trigger, and result.
+- ✅ "When [preconditions:] a registered user [trigger:] provides valid credentials, [result:] they are authenticated"
+
+**4. Be Framework Neutral**: Don't prescribe Given/When/Then vs AC vs other formats - focus on content quality.
+
+**5. Use Named Personas**: Establish personas in parent requirements, reuse in children.
+- ✅ Parent: "A registered user, Jamie, can log in normally" → Child: "When Jamie provides valid credentials, they are authenticated"
+
+**6. Use User-Centric Language**: Describe user experience, not technical internals.
+- ❌ "they are redirected to app.dotrequirements.io/redirect/dashboard"
+- ✅ "they are automatically brought to the dashboard"
+
+**7. Single Action Per Requirement**: Don't chain multiple actions with "and then".
+- ❌ "When Robin provides credentials, requests an OTP, then provides the OTP..."
+- ✅ Break into separate requirements for each action
+
+**8. Each Requirement Should Be Independent**: Requirements within a block should be independently testable. If they share preconditions or form a sequence, either nest them or restate context.
+- ❌ "0. → When Jordan submits signup, an account is created" / "1. → Welcome email is sent" / "2. → Dashboard appears"
+- ✅ Option A: Restate context - "1. → When Jordan submits signup, a welcome email is sent"
+- ✅ Option B: Use nesting - "0. When → Jordan submits signup" / "  0.0. Then → an account is created"
+- Test: Can you understand what's being tested by reading just one requirement, or do you need to read its siblings?
+
+**9. Focus on Behavior, Not Design**: Describe what happens, not UI specifics.
+- ❌ "enters valid credentials into two single-line input fields and presses a green button"
+- ✅ "provides valid credentials"
+
+**10. Focus on Outcomes, Not Implementation**: User perspective, even for technical requirements.
+- ❌ "When the app requests that Twilio send Casey an OTP from /email/POST endpoint..."
+- ✅ "When Casey requests an email OTP..."
+- 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.
+
+## Example Requirements
+
+**Unlabeled (recommended default):**
+\`\`\`dotrequirements
+AUTH-LOGIN-1: A registered user, Jamie, can log in to their account
+  0. → When Jamie provides their registered email and correct password, they are authenticated and brought to their dashboard
+  1. → When Jamie provides an incorrect password, they see an error message and remain on the login page
+  2. → When Jamie's account has been deactivated, they see a message explaining their account status
+\`\`\`
+
+**With labels (example only - DO NOT use opinionated formats like Given/When/Then without asking the user first):**
+\`\`\`dotrequirements
+PAYMENT-REFUND-1: A customer, Alex, receives a refund after returning an item
+  0. Given → Alex purchased a laptop from the store 10 days ago
+  1. Given → Alex initiates a return through their order history
+  2. When → Alex's returned laptop is received and inspected at the warehouse
+  3. Then → Alex receives a refund to their original payment method within 5 business days
+  4. Then → Alex receives an email confirmation with the refund amount and expected timeline
+\`\`\`
+
+## Referencing Requirements in Tests
+
+**Use \`requirement()\` as the test description** - it returns a string:
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+import { requirement } from '@popoverai/dotrequirements/test';
+
+describe(requirement('AUTH-LOGIN-1'), () => {
+  describe(requirement('AUTH-LOGIN-1.given'), () => {
+    // Arrange: Create Jamie's account
+  });
+
+  describe(requirement('AUTH-LOGIN-1.when'), () => {
+    // Act: Submit login with valid credentials
+
+    it(requirement('AUTH-LOGIN-1.then'), () => {
+      // Assert: Jamie is authenticated
+    });
+  });
+});
+\`\`\`
+
+**Test Style Principles:**
+
+**1. Use requirement() AS the description**: Don't put requirement() inside test body or in comments.
+- ✅ \`test(requirement('AUTH-LOGIN-1'), () => { /* test code */ })\`
+- ✅ \`it(requirement('LOGIN-1.then'), () => { /* assert */ })\`
+- ❌ \`test("user can log in", () => { requirement('AUTH-LOGIN-1'); /* test code */ })\`
+- ❌ \`// LOGIN-1: User can log in\` (comment instead of using requirement() as description)
+
+**2. Comments describe the TEST, not the requirement**: Don't copy requirement text verbatim.
+- ✅ \`describe(requirement('REQ-1.0'), () => { // registered user, valid credentials\`
+- ❌ \`describe(requirement('REQ-1.0'), () => { // 0. When a registered user provides valid credentials, they are authenticated\` (verbatim copy is a red flag)
+- Note: Comments should reflect what the test actually does, not just repeat what the requirement says
+
+**3. Structure tests to match requirements**: Nest describe/it blocks for structured requirements.
+- ✅ For structured requirements: \`describe(requirement('LOGIN-1.given'))\` nested with \`describe(requirement('LOGIN-1.when'))\` and \`it(requirement('LOGIN-1.then'))\`
+- ✅ For simple requirements: \`test(requirement('AUTH-LOGIN-1'), () => { /* arrange, act, assert all in one */ })\`
+
+**Path formats:**
+- \`requirement('AUTH-LOGIN-1')\` - root requirement
+- \`requirement('AUTH-LOGIN-1.0')\` - by numeric position
+- \`requirement('AUTH-LOGIN-1.given')\` - by label (case-insensitive)
+- \`requirement('AUTH-LOGIN-1.given#1')\` - disambiguate duplicate labels`;
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `# Requirements File Template\n\nHere's a comprehensive template for \`${filePath}\` with format and style guidance:\n\n\`\`\`markdown\n${template}\`\`\`\n\n## Next Steps\n\n1. **Create file**: Use Write tool to create \`${filePath}\` based on this template\n2. **Refine style** (optional): Call \`style_check\` for AI feedback on style and best practices\n3. **Validate syntax**: Call \`validate_requirements\` to verify format is correct\n4. **Push to Convex**: Call \`push_requirements\` to sync requirements to data layer\n\n**Note**: Requirements files can be colocated with code (\`src/auth.requirements.md\`) or centralized in \`.requirements/\` directory.`,
+                        },
+                    ],
+                };
+            }
+            case 'validate_requirements': {
+                const { filePath } = args;
+                const { parseRequirementsFromFile, validateForPush } = await import('../schema/index.js');
+                const fs = await import('fs');
+                const path = await import('path');
+                const fullPath = path.resolve(WORKSPACE_ROOT, filePath);
+                if (!fs.existsSync(fullPath)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File not found: ${filePath}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                try {
+                    const parsed = parseRequirementsFromFile(fullPath);
+                    const reqCount = Object.keys(parsed.requirements).length;
+                    // Check push readiness
+                    const pushValidation = validateForPush(parsed.metadata);
+                    let headline;
+                    let pushDetails = '';
+                    if (!pushValidation.valid) {
+                        headline = `❌ \`${filePath}\` - Not push-ready\n- ${pushValidation.reason}`;
+                    }
+                    else {
+                        const actionLabel = pushValidation.action === 'create' ? 'Will create new document' : 'Will update existing document';
+                        headline = `✓ \`${filePath}\` - ${actionLabel}`;
+                        if (pushValidation.warning) {
+                            pushDetails = `\n- ⚠️ ${pushValidation.warning}`;
+                        }
+                    }
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `${headline}${pushDetails}\n\n**Metadata:**\n- Project ID: ${parsed.metadata.projectId}\n- Version: ${parsed.metadata.version}\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) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `✗ Validation failed for \`${filePath}\`:\n\n${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            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
+                const project = await getProjectFromDiscovery(projectIdParam);
+                const config = loadConvexConfig(project.path);
+                if (!config) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Push requires environment variables:\n- DOTREQUIREMENTS_PROJECT_ID\n- DOTREQUIREMENTS_PROJECT_SECRET',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const convexUrl = config.convexUrl;
+                const projectId = config.projectId;
+                const projectSecret = config.projectSecret;
+                // AUTHZ-2.1: Check if project is local-only
+                if (isLocalOnlyProject(projectId)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // 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)) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `File not found: ${filePath}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    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));
+                    if (filesToPush.length === 0) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: 'No Markdown files (*.requirements.md) found in .requirements/',
+                                },
+                            ],
+                            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,
+                        });
+                    }
+                }
+                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
+                    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\``,
+                            },
+                        ],
+                    };
+                }
+                // 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,
+                    });
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `✓ Push complete!\n\n**Inserted:** ${result.inserted}\n**Deleted:** ${result.deleted}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `✗ Push failed:\n\n${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case 'style_check': {
+                const { filePath, model } = args;
+                const fs = await import('fs');
+                const path = await import('path');
+                const fullPath = path.resolve(WORKSPACE_ROOT, filePath);
+                if (!fs.existsSync(fullPath)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File not found: ${filePath}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Read file contents
+                const fileContents = fs.readFileSync(fullPath, 'utf-8');
+                // Detect file type
+                const isRequirementsFile = filePath.endsWith('.requirements.md');
+                const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(filePath);
+                if (!isRequirementsFile && !isTestFile) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Unsupported file type. File must be:\n- Requirements file: *.requirements.md\n- Test file: *.test.{js,jsx,ts,tsx} or *.spec.{js,jsx,ts,tsx}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const fileType = isRequirementsFile ? 'requirements' : 'test';
+                // Get Convex config for credentials - walk up from file's directory to find project
+                const fileDir = path.dirname(fullPath);
+                let project;
+                try {
+                    // Try to find a project starting from the file's directory
+                    const result = await discoverProjects(fileDir);
+                    if (result.type === 'none') {
+                        // If no project found from file dir, try from WORKSPACE_ROOT
+                        project = await getProjectFromDiscovery();
+                    }
+                    else if (result.type === 'single') {
+                        project = result.project;
+                    }
+                    else {
+                        // Multiple projects - can't auto-detect which one to use
+                        throw new Error('Multiple projects found - cannot auto-detect for this file');
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Style check requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.\n\nError: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const config = loadConvexConfig(project.path);
+                if (!config) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Style check requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // AUTHZ-2.1: Check if project is local-only
+                if (isLocalOnlyProject(config.projectId)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Call Vercel API endpoint for style checking
+                // Default to production, allow override via env var for local dev
+                const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL || 'https://app.dotrequirements.io';
+                try {
+                    const response = await fetch(`${apiBaseUrl}/api/style-check`, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify({
+                            projectId: config.projectId,
+                            projectSecret: config.projectSecret,
+                            fileContents,
+                            fileType,
+                            model,
+                        }),
+                    });
+                    if (!response.ok) {
+                        const errorData = await response.json();
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Style check failed: ${errorData.error || response.statusText}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const data = await response.json();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `# Style Check Results for \`${filePath}\`\n\n${data.feedback}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Style check error: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            case 'review_test': {
+                const { testFilePath, projectId } = args;
+                const fs = await import('fs');
+                const path = await import('path');
+                const fullPath = path.resolve(WORKSPACE_ROOT, testFilePath);
+                if (!fs.existsSync(fullPath)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File not found: ${testFilePath}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Verify it's a test file
+                const isTestFile = /\.(test|spec)\.(js|jsx|ts|tsx)$/.test(testFilePath);
+                if (!isTestFile) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `File must be a test file: *.test.{js,jsx,ts,tsx} or *.spec.{js,jsx,ts,tsx}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Read test file contents
+                const testFileContents = fs.readFileSync(fullPath, 'utf-8');
+                // Extract requirement IDs from the test file using regex
+                const requirementIdMatches = testFileContents.matchAll(/requirement\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g);
+                const requirementIds = new Set();
+                for (const match of requirementIdMatches) {
+                    requirementIds.add(match[1]);
+                }
+                // Get project
+                let project;
+                try {
+                    project = await getProjectFromDiscovery(projectId);
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Test review requires a configured dotrequirements project.\n\nError: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Load all requirements for this project
+                const allRequirements = await getRequirements(projectId);
+                // Group requirement IDs by their root to avoid sending duplicate trees
+                // e.g., NAV-3.0, NAV-3.1, NAV-3.2 all belong to root NAV-3
+                const rootToTestedIds = new Map();
+                for (const reqId of requirementIds) {
+                    const req = allRequirements.find(r => r.id === reqId || r.rootId === reqId);
+                    if (req) {
+                        if (!rootToTestedIds.has(req.rootId)) {
+                            rootToTestedIds.set(req.rootId, new Set());
+                        }
+                        rootToTestedIds.get(req.rootId).add(reqId);
+                    }
+                }
+                // Build requirements array with one entry per unique root tree
+                const requirements = [];
+                for (const [rootId, testedIds] of rootToTestedIds) {
+                    const tree = getRequirementTree(allRequirements, rootId);
+                    const formattedTree = formatRequirementTree(tree);
+                    requirements.push({
+                        id: rootId,
+                        content: formattedTree,
+                        testedIds: Array.from(testedIds).sort(),
+                    });
+                }
+                // Get Convex config
+                const config = loadConvexConfig(project.path);
+                if (!config) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Test review requires DOTREQUIREMENTS_PROJECT_ID and DOTREQUIREMENTS_PROJECT_SECRET to be configured in your .env or .env.local file.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // AUTHZ-2.1: Check if project is local-only
+                if (isLocalOnlyProject(config.projectId)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: CLOUD_FEATURES_REQUIRE_AUTH_MESSAGE,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Call Vercel API endpoint for test review
+                // Default to production, allow override via env var for local dev
+                const apiBaseUrl = process.env.DOTREQUIREMENTS_API_URL || 'https://app.dotrequirements.io';
+                try {
+                    const response = await fetch(`${apiBaseUrl}/api/review-test`, {
+                        method: 'POST',
+                        headers: {
+                            'Content-Type': 'application/json',
+                        },
+                        body: JSON.stringify({
+                            projectId: config.projectId,
+                            projectSecret: config.projectSecret,
+                            testFileContents,
+                            requirements,
+                        }),
+                    });
+                    if (!response.ok) {
+                        const errorData = await response.json();
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Test review failed: ${errorData.error || response.statusText}`,
+                                },
+                            ],
+                            isError: true,
+                        };
+                    }
+                    const data = await response.json();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `# Test Review Results for \`${testFilePath}\`\n\n${data.feedback}`,
+                            },
+                        ],
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Test review error: ${error instanceof Error ? error.message : String(error)}`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            default:
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Unknown tool: ${name}`,
+                        },
+                    ],
+                    isError: true,
+                };
+        }
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('dot•requirements MCP server running');
+    console.error('WORKSPACE_ROOT:', WORKSPACE_ROOT);
+    console.error('process.cwd():', process.cwd());
+    console.error('REQUIREMENTS_DIR env:', process.env.REQUIREMENTS_DIR);
+}
+main().catch(console.error);
+//# sourceMappingURL=index.js.map