@popoverai/dotrequirements 0.26.0 → 0.26.2

package/dist/harness/tracking.d.ts

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

package/dist/harness/tracking.js

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

package/dist/mcp/handlers/authoring.js

@@ -6,12 +6,11 @@
  * - validate_requirements: Validate requirements file syntax offline
  */
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
 import { getProjectContext } from "../../requirements/cloud-ai.js";
 import { generateStyleGuide, readLocalStyleGuide, } from "../../requirements/style-guide.js";
 import { parseRequirementsFromFile, validateForPush, } from "../../schema/index.js";
 import { CONVEX_URL } from "../convexClient.js";
-import { errorResponse, textResponse } from "./types.js";
+import { errorResponse, resolveProjectFilePath, textResponse, } from "./types.js";
 /**
  * Handler for create_requirement_document tool
  *
@@ -60,8 +59,18 @@ export async function handleCreateRequirementDocument(args, context) {
  */
 export async function handleValidateRequirements(args, context) {
     const { filePath } = args;
-    // MCP-AUTHOR-2.3: Validation works offline - just use workspaceRoot
-    const fullPath = resolve(context.workspaceRoot, filePath);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback. MCP-AUTHOR-2.3: validation stays offline — if
+    // discovery has no credentials it simply throws and we fall back to
+    // workspaceRoot resolution.
+    let projectPath;
+    try {
+        projectPath = (await context.getProjectFromDiscovery()).path;
+    }
+    catch {
+        projectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(filePath, projectPath, context.workspaceRoot);
     // MCP-AUTHOR-2.4: Check if file exists
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${filePath}`);

package/dist/mcp/handlers/get.js

@@ -4,7 +4,7 @@
  * Retrieves a specific requirement by ID with its full tree and test coverage.
  */
 import { glob } from "glob";
-import { formatRequirementTree, getRequirementTree, } from "../../requirements/index.js";
+import { formatRequirementTree } from "../../requirements/index.js";
 import { findFilesWithRequirement, findTestCodeForRequirement, } from "../../requirements/testCodeExtractor.js";
 import { textResponse } from "./types.js";
 /**
@@ -20,10 +20,14 @@ export async function handleGetRequirement(args, context) {
     const { id, projectId } = args;
     const project = await context.getProjectFromDiscovery(projectId);
     const requirements = await context.getRequirements(projectId);
-    // Get the tree starting from this ID
+    // Get the tree starting from this ID.
     // MCP-GET-1.0: Full tree for root requirement
     // MCP-GET-1.1: Subtree for child requirement
-    const tree = getRequirementTree(requirements, id);
+    //
+    // #46: Match the node itself plus all of its descendants by id prefix. The
+    // shared getRequirementTree only matches on rootId/id equality, which drops
+    // grandchildren (e.g. REQ-123.0.0) when a child id (REQ-123.0) is requested.
+    const tree = requirements.filter((r) => r.id === id || r.id.startsWith(`${id}.`));
     // MCP-GET-1.2: Return error if not found
     if (tree.length === 0) {
         return textResponse(`Requirement "${id}" not found`);

package/dist/mcp/handlers/push.js

@@ -6,7 +6,7 @@
  */
 import { existsSync } from "node:fs";
 import { basename, resolve } from "node:path";
-import { dryRunPush, executePush, parseFilesForPush, } from "../../push/index.js";
+import { dryRunPush, executePush, parseFilesForPushIndividually, } from "../../push/index.js";
 import { findRequirementsFiles } from "../../requirements/index.js";
 import { CONVEX_URL } from "../convexClient.js";
 import { errorResponse, textResponse } from "./types.js";
@@ -46,24 +46,60 @@ export async function handlePushRequirements(args, context) {
             return textResponse("No *.requirements.md files found. Nothing to push.");
         }
     }
-    // Parse files
-    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    // Parse files. #45/SYNC-FAIL-4: one invalid file does not abort the whole
+    // push — its failure is surfaced in the preview's "Skipped - Invalid"
+    // section while valid files still push. Same helper as the CLI command.
+    const { parsedFiles, totalRequirements, parseFailures } = parseFilesForPushIndividually(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);
+    // Run dry run (always, even when confirmed - ensures fresh state).
+    // SYNC-FAIL-3: two files claiming the same document ID abort the push
+    // before any cloud write — surface that as a clean error result naming
+    // both files rather than an unhandled throw.
+    let dryRunResult;
+    try {
+        dryRunResult = await dryRunPush(parsedFiles, credentials);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.includes("claim the same document ID")) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `✗ Push aborted: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        throw error;
+    }
+    // #45: Merge dry-run invalids (missing document section, cloud validation)
+    // with local parse failures so both are surfaced together, each named by
+    // filename.
+    const allInvalid = [
+        ...dryRunResult.invalid.map(({ file, result }) => ({
+            fileName: basename(file.filePath),
+            error: result.error ?? "invalid",
+        })),
+        ...parseFailures.map(({ filePath, error }) => ({
+            fileName: basename(filePath),
+            error,
+        })),
+    ];
     // 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) {
+    if (pushableCount === 0 && allInvalid.length > 0) {
         // Only invalid files
-        const invalidList = dryRunResult.invalid
-            .map(({ file, result }) => `- ${basename(file.filePath)}: ${result.error}`)
+        const invalidList = allInvalid
+            .map(({ fileName, error }) => `- ${fileName}: ${error}`)
             .join("\n");
         return {
             content: [
@@ -106,11 +142,10 @@ export async function handlePushRequirements(args, context) {
             }
             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`;
+        if (allInvalid.length > 0) {
+            summary += `## Skipped - Invalid (${allInvalid.length})\n`;
+            for (const { fileName, error } of allInvalid) {
+                summary += `- ✗ ${fileName}: ${error}\n`;
             }
             summary += "\n";
         }
@@ -158,6 +193,17 @@ export async function handlePushRequirements(args, context) {
                 output += `- ${fileName}: ${error}\n`;
             }
         }
+        // SYNC-FAIL-2.1: cloud save succeeded but the local file couldn't be
+        // updated — name the file, say the cloud is fine, and give the recovery
+        // step so a retry doesn't mint a duplicate document.
+        if (result.writeBackWarnings?.length > 0) {
+            output += `\n**Warnings:**\n`;
+            for (const warning of result.writeBackWarnings) {
+                output +=
+                    `- ⚠ ${warning.fileName}: saved to the cloud, but the local file could not be updated (${warning.error}). ` +
+                        `To avoid creating a duplicate, add "id: ${warning.documentId}" under "document:" in the frontmatter of ${warning.filePath}, then push again.\n`;
+            }
+        }
         // SYNC-LAND-1: where each synced document lives in the web app
         if (result.synced.length > 0) {
             output += `\n**Review in dot•requirements:**\n`;

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

@@ -13,6 +13,7 @@ export interface StyleCheckArgs {
     filePath: string;
     requirementKeys?: string[];
     model?: string;
+    projectId?: string;
 }
 /**
  * Arguments for review_test tool

package/dist/mcp/handlers/review.js

@@ -6,11 +6,12 @@
  * - review_test: Comprehensively review tests for semantic correctness
  */
 import { existsSync, readFileSync } from "node:fs";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { fetchReviewTestFeedback, fetchStyleCheckFeedback, } from "../../requirements/cloud-ai.js";
+import { findRequirementsInFile } from "../../requirements/grep.js";
 import { filterRequirementsByKeys, formatRequirementTree, getRequirementTree, } from "../../requirements/index.js";
 import { discoverProjects, } from "../../utils/project-discovery.js";
-import { errorResponse, textResponse } from "./types.js";
+import { errorResponse, resolveProjectFilePath, textResponse, } from "./types.js";
 const STYLE_CHECK_GUIDANCE = `
 
 ---
@@ -32,9 +33,20 @@ const STYLE_CHECK_GUIDANCE = `
  * - MCP-REVIEW-1.3: When cloud credentials are unavailable, an error explains how to authenticate
  */
 export async function handleStyleCheck(args, context, options) {
-    const { filePath, requirementKeys, model } = args;
+    const { filePath, requirementKeys, model, projectId } = args;
     const { useEnvAuth = false, apiBaseUrl = "https://app.dotrequirements.io" } = options ?? {};
-    const fullPath = resolve(context.workspaceRoot, filePath);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path that push accepts also works
+    // here in PROJ_*-based setups. Discovery may throw without credentials — that
+    // is fine, we then fall back to workspaceRoot.
+    let styleProjectPath;
+    try {
+        styleProjectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        styleProjectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(filePath, styleProjectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${filePath}`);
     }
@@ -73,7 +85,14 @@ export async function handleStyleCheck(args, context, options) {
     const fileDir = dirname(fullPath);
     let project;
     try {
-        if (useEnvAuth) {
+        if (projectId) {
+            // #48: PROJ-CONTEXT-6 — an explicit projectId disambiguates a
+            // multi-project workspace. Thread it straight through to discovery
+            // (matching review_test/push/report) instead of the file-directory
+            // auto-detect path, which cannot choose among multiple projects.
+            project = await context.getProjectFromDiscovery(projectId);
+        }
+        else if (useEnvAuth) {
             // Using env auth - go straight to context
             project = await context.getProjectFromDiscovery();
         }
@@ -88,8 +107,14 @@ export async function handleStyleCheck(args, context, options) {
                 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");
+                // #48: Multiple projects — can't auto-detect. The remedy is to pass
+                // projectId (not `dotrequirements link`, which is already satisfied);
+                // list the available projects so the caller can choose.
+                const available = result.projects
+                    .map((p) => p.projectId)
+                    .filter(Boolean)
+                    .join(", ");
+                return errorResponse(`Multiple projects found. Specify the \`projectId\` parameter to choose one${available ? ` (available: ${available})` : ""}.`);
             }
         }
     }
@@ -130,7 +155,17 @@ export async function handleStyleCheck(args, context, options) {
 export async function handleReviewTest(args, context, options) {
     const { testFilePath, projectId } = args;
     const { apiBaseUrl = "https://app.dotrequirements.io" } = options ?? {};
-    const fullPath = resolve(context.workspaceRoot, testFilePath);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback. Discovery may throw without credentials — fall back
+    // to workspaceRoot; the credential error is reported later.
+    let reviewProjectPath;
+    try {
+        reviewProjectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        reviewProjectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(testFilePath, reviewProjectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`File not found: ${testFilePath}`);
     }
@@ -141,12 +176,12 @@ export async function handleReviewTest(args, context, options) {
     }
     // Read test file contents
     const testFileContents = 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]);
-    }
+    // #43: Extract requirement IDs via the shared AST-based extractor so that
+    // multi-arg calls (`requirement("A", "B")`) and options-bearing calls
+    // (`requirement("A", { ... })`) are captured — the old single-string regex
+    // matched neither.
+    const references = await findRequirementsInFile(fullPath);
+    const requirementIds = new Set(references.map((ref) => ref.requirementId));
     // MCP-REVIEW-2.5: Get project credentials
     let project;
     try {
@@ -159,9 +194,17 @@ export async function handleReviewTest(args, context, options) {
     const allRequirements = await context.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
+    //
+    // #42: A reference may be a bare root (`AUTH-1`), an index child (`AUTH-1.0`),
+    // or a label path (`AUTH-1.given`). Normalize each reference to its root id
+    // (the substring before the first dot) before matching — the same approach
+    // getReferencedRequirementIds uses — so label-path refs resolve instead of
+    // being reported as non-existent.
     const rootToTestedIds = new Map();
     for (const reqId of requirementIds) {
-        const req = allRequirements.find((r) => r.id === reqId || r.rootId === reqId);
+        const dotIndex = reqId.indexOf(".");
+        const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
+        const req = allRequirements.find((r) => r.rootId === refRootId);
         if (req) {
             if (!rootToTestedIds.has(req.rootId)) {
                 rootToTestedIds.set(req.rootId, new Set());

package/dist/mcp/handlers/test-mapping.js

@@ -7,7 +7,7 @@ import { existsSync } from "node:fs";
 import { relative, resolve } from "node:path";
 import { findAllTestReferences, findRequirementsInFile, } from "../../requirements/grep.js";
 import { getRequirementById } from "../../requirements/index.js";
-import { errorResponse, textResponse } from "./types.js";
+import { errorResponse, resolveProjectFilePath, textResponse, } from "./types.js";
 /**
  * Handler for get_requirements_by_test tool
  *
@@ -18,14 +18,26 @@ import { errorResponse, textResponse } from "./types.js";
  */
 export async function handleGetRequirementsByTest(args, context) {
     const { testFile, projectId } = args;
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path works in PROJ_*-based setups.
+    let projectPath;
+    try {
+        projectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        projectPath = undefined;
+    }
     // MCP-MAP-1.2: Check if file exists before processing
-    const fullPath = resolve(context.workspaceRoot, testFile);
+    const fullPath = resolveProjectFilePath(testFile, projectPath, context.workspaceRoot);
     if (!existsSync(fullPath)) {
         return errorResponse(`Test file not found: ${testFile}`);
     }
     const requirements = await context.getRequirements(projectId);
-    // MCP-MAP-1.0: Find all requirement references in the test file
-    const refs = await findRequirementsInFile(testFile);
+    // MCP-MAP-1.0: Find all requirement references in the test file.
+    // #44: Pass the already-resolved absolute path — findRequirementsInFile
+    // resolves relative paths against process.cwd(), which is not the workspace
+    // root when the MCP server runs from a different directory.
+    const refs = await findRequirementsInFile(fullPath);
     if (refs.length === 0) {
         return textResponse(`No requirement references found in "${testFile}"`);
     }
@@ -50,7 +62,18 @@ export async function handleGetRequirementsByTest(args, context) {
 export async function handleGetTestsByRequirement(args, context) {
     const { requirementsFile, projectId } = args;
     const { workspaceRoot } = context;
-    const fullPath = resolve(workspaceRoot, requirementsFile);
+    // #49: Resolve against the discovered project.path (matching push) with a
+    // workspaceRoot fallback, so a relative path works in PROJ_*-based setups.
+    // The same base root anchors sourceFile comparison, test scanning, and the
+    // relative paths in the output.
+    let projectPath;
+    try {
+        projectPath = (await context.getProjectFromDiscovery(projectId)).path;
+    }
+    catch {
+        projectPath = undefined;
+    }
+    const fullPath = resolveProjectFilePath(requirementsFile, projectPath, workspaceRoot);
     // Verify file exists
     if (!existsSync(fullPath)) {
         return errorResponse(`Requirements file not found: ${requirementsFile}`);
@@ -59,23 +82,35 @@ export async function handleGetTestsByRequirement(args, context) {
     if (!requirementsFile.endsWith(".requirements.md")) {
         return errorResponse(`File must be a requirements file: *.requirements.md`);
     }
+    // Anchor all subsequent path work to the root that actually contains the
+    // requirements file, so sourceFile comparison and test discovery agree.
+    const baseRoot = projectPath ?? workspaceRoot;
     // Load all requirements from this file
     const requirements = await context.getRequirements(projectId);
-    const fileRequirements = requirements.filter((req) => resolve(workspaceRoot, req.sourceFile) === fullPath);
+    const fileRequirements = requirements.filter((req) => resolve(baseRoot, req.sourceFile) === fullPath);
     if (fileRequirements.length === 0) {
         return textResponse(`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(workspaceRoot);
-    // Build coverage map: requirement ID -> list of test references
+    const allTestRefs = await findAllTestReferences(baseRoot);
+    // Build coverage map keyed by ROOT id. A reference may be a bare root
+    // (`AUTH-1`), an index child (`AUTH-1.0`), or a label path (`AUTH-1.given`).
+    // #47: Normalize each reference to its root id (the substring before the
+    // first dot) before keying — the same normalization as the tests-for fix —
+    // so label-path refs match numeric requirement ids instead of rendering as
+    // "(requirement not found)".
     const coverageMap = new Map();
     for (const ref of allTestRefs) {
-        if (!coverageMap.has(ref.requirementId)) {
-            coverageMap.set(ref.requirementId, []);
+        const dotIndex = ref.requirementId.indexOf(".");
+        const refRootId = dotIndex > 0
+            ? ref.requirementId.substring(0, dotIndex)
+            : ref.requirementId;
+        if (!coverageMap.has(refRootId)) {
+            coverageMap.set(refRootId, []);
         }
-        coverageMap.get(ref.requirementId).push(ref);
+        coverageMap.get(refRootId).push(ref);
     }
     // MCP-MAP-2.0: Categorize requirements as covered or not covered
     const covered = [];
@@ -114,7 +149,7 @@ export async function handleGetTestsByRequirement(args, context) {
             }
             output += `- **${id}**: ${tests.length} test${tests.length === 1 ? "" : "s"}\n`;
             for (const [file, lines] of testsByFile.entries()) {
-                const relPath = relative(workspaceRoot, file);
+                const relPath = relative(baseRoot, file);
                 const lineList = lines.sort((a, b) => a - b).join(", ");
                 output += `  - \`${relPath}\` (lines ${lineList})\n`;
             }

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

@@ -64,6 +64,20 @@ export interface HandlerContext {
  * The args parameter contains tool-specific arguments.
  */
 export type ToolHandler<TArgs = Record<string, unknown>> = (args: TArgs, context: HandlerContext) => Promise<ToolResponse>;
+/**
+ * Resolve a user-supplied relative file path to an absolute path.
+ *
+ * #49: The MCP server's workspaceRoot is its process cwd, but in PROJ_*-based
+ * (Antigravity) setups the discovered project.path is the real project root and
+ * differs from cwd. push_requirements resolves against project.path; the other
+ * file-taking handlers historically resolved against workspaceRoot, so the same
+ * relative path worked for push but not for validate/style/review/mapping.
+ *
+ * This resolves against project.path first (matching push) and falls back to
+ * workspaceRoot when the file is not present there, so both layouts work.
+ * Absolute paths are returned unchanged.
+ */
+export declare function resolveProjectFilePath(filePath: string, projectPath: string | undefined, workspaceRoot: string): string;
 /**
  * Helper to create a text response
  */

package/dist/mcp/handlers/types.js

@@ -5,6 +5,33 @@
  * and returns an MCP tool response. This enables unit testing without
  * the full MCP server infrastructure.
  */
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+/**
+ * Resolve a user-supplied relative file path to an absolute path.
+ *
+ * #49: The MCP server's workspaceRoot is its process cwd, but in PROJ_*-based
+ * (Antigravity) setups the discovered project.path is the real project root and
+ * differs from cwd. push_requirements resolves against project.path; the other
+ * file-taking handlers historically resolved against workspaceRoot, so the same
+ * relative path worked for push but not for validate/style/review/mapping.
+ *
+ * This resolves against project.path first (matching push) and falls back to
+ * workspaceRoot when the file is not present there, so both layouts work.
+ * Absolute paths are returned unchanged.
+ */
+export function resolveProjectFilePath(filePath, projectPath, workspaceRoot) {
+    if (isAbsolute(filePath)) {
+        return filePath;
+    }
+    if (projectPath) {
+        const fromProject = resolve(projectPath, filePath);
+        if (existsSync(fromProject)) {
+            return fromProject;
+        }
+    }
+    return resolve(workspaceRoot, filePath);
+}
 /**
  * Helper to create a text response
  */