@popoverai/dotrequirements 0.26.0 → 0.26.2

package/dist/commands/pull.js

@@ -5,6 +5,7 @@ import { getConvexUrl } from "../config.js";
 import { api } from "../convex.js";
 import { findRequirementsFiles } from "../requirements/index.js";
 import { buildRequirementsFile } from "../schema/index.js";
+import { extractFrontmatterBlock } from "../schema/parser-core.js";
 import { brand } from "../utils/brand.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
 export async function pullCommand(options) {
@@ -94,12 +95,33 @@ export async function pullCommand(options) {
     }
     // Build index of existing files by document ID (search entire workspace)
     const existingFilesByDocId = await buildDocumentIdIndex(process.cwd());
+    // SYNC-WEB-CREATE-2.0: track paths claimed during this pull so colliding
+    // titles don't silently overwrite each other within one operation
+    const usedPaths = new Set(existingFilesByDocId.values());
     // Write each document as a Markdown file
     for (const doc of documents) {
         // Check if an existing file has this document ID
         const existingFilePath = existingFilesByDocId.get(doc.documentId);
-        const filePath = existingFilePath ??
-            path.join(requirementsDir, `${sanitizeFileName(doc.title)}.requirements.md`);
+        let filePath;
+        if (existingFilePath) {
+            filePath = existingFilePath;
+        }
+        else {
+            // SYNC-WEB-CREATE-2.1: an all-symbols title sanitizes to nothing —
+            // fall back to the document ID rather than a hidden ".requirements.md"
+            const baseName = sanitizeFileName(doc.title) || doc.documentId;
+            let candidate = path.join(requirementsDir, `${baseName}.requirements.md`);
+            // SYNC-WEB-CREATE-2.0: disambiguate later collisions with a numeric
+            // suffix; also avoid clobbering an on-disk file that belongs to a
+            // different (or no) document
+            let suffix = 2;
+            while (usedPaths.has(candidate) || fs.existsSync(candidate)) {
+                candidate = path.join(requirementsDir, `${baseName}-${suffix}.requirements.md`);
+                suffix++;
+            }
+            filePath = candidate;
+        }
+        usedPaths.add(filePath);
         const fileName = path.basename(filePath);
         // IMPORT-1: carry the CTS run marker forward from the existing local
         // file — pull rebuilds frontmatter from cloud data, and silently dropping
@@ -168,10 +190,21 @@ async function buildDocumentIdIndex(workspaceRoot) {
 /**
  * Extract document.id from a requirements file's frontmatter.
  * Returns undefined if the file can't be read or doesn't have a document ID.
+ * SYNC-DISCOVERY-3: only the leading YAML frontmatter block is consulted —
+ * a document id quoted in body prose or a fenced example must never mark
+ * the file as owning that document.
  */
 function extractDocumentIdFromFile(filePath) {
     try {
-        const content = fs.readFileSync(filePath, "utf-8");
+        const fileContent = fs.readFileSync(filePath, "utf-8");
+        // Isolate the leading ---...--- frontmatter block; no frontmatter means
+        // the file is unlinked to any cloud document (SYNC-DISCOVERY-3.2).
+        // Shared helper normalizes CRLF (SYNC-FORMAT-1) so a Windows-saved file
+        // keeps matching its document and is updated in place (SYNC-DISCOVERY-2.1).
+        const content = extractFrontmatterBlock(fileContent);
+        if (content === undefined) {
+            return undefined;
+        }
         // Match document.id in YAML frontmatter - handles both inline and nested formats
         // Inline: document: { id: "abc123", ... }
         // Nested (id: can appear at any position within the indented document block):

package/dist/commands/push.js

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import * as readline from "node:readline";
 import { getConvexUrl } from "../config.js";
-import { dryRunPush, executePush, parseFilesForPush, } from "../push/index.js";
+import { dryRunPush, executePush, parseFilesForPushIndividually, } from "../push/index.js";
 import { findRequirementsFiles } from "../requirements/index.js";
 import { brand } from "../utils/brand.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
@@ -30,20 +30,30 @@ export async function pushCommand(file, options) {
             return;
         }
     }
-    // Parse all local files
+    // Parse local files. SYNC-FAIL-4: one invalid file is skipped while the
+    // rest of the batch still pushes — same helper as the MCP push handler.
     console.log("Parsing local requirements...");
-    const { parsedFiles, totalRequirements } = parseFilesForPush(filesToPush);
+    const { parsedFiles, totalRequirements, parseFailures } = parseFilesForPushIndividually(filesToPush);
     // Log file parsing progress
     for (const file of parsedFiles) {
         const fileName = path.basename(file.filePath);
         const doc = file.metadata.document;
-        if (doc?.defaultPrefix && !file.metadata.document?.defaultPrefix) {
-            console.log(`  Reading ${fileName}...`);
+        console.log(`  Reading ${fileName}...`);
+        // DOC-HEADER-11.4: parseFilesForPush mutates the metadata when it infers
+        // the prefix, so the flag it returns is the only record of the inference
+        if (doc?.defaultPrefix && file.inferredDefaultPrefix) {
             console.log(`    Inferred defaultPrefix "${doc.defaultPrefix}" from first requirement`);
         }
-        else {
-            console.log(`  Reading ${fileName}...`);
+    }
+    // SYNC-FAIL-4.1: every file in the push failed to parse — report each
+    // skipped file, then fail honestly instead of dry-running nothing
+    if (parsedFiles.length === 0) {
+        for (const failure of parseFailures) {
+            console.log(`  ✗ Skipped ${path.basename(failure.filePath)}: ${failure.error}`);
         }
+        console.log("\nNo valid documents to push.");
+        process.exitCode = 1;
+        return;
     }
     console.log(`\nFound ${totalRequirements} requirement(s) in ${parsedFiles.length} document(s).\n`);
     // Build credentials
@@ -56,13 +66,19 @@ export async function pushCommand(file, options) {
     console.log("Validating documents...");
     const dryRunResult = await dryRunPush(parsedFiles, credentials);
     // Display unified summary
-    displayDryRunSummary(dryRunResult);
+    displayDryRunSummary(dryRunResult, parseFailures);
     // Check if there's anything to push
     const pushableCount = dryRunResult.updates.length +
         dryRunResult.creates.length +
         dryRunResult.notFound.length;
     if (pushableCount === 0) {
         console.log("No valid documents to push.");
+        // SYNC-FAIL-4.1: every file in the push was invalid — whether it failed
+        // local parse or dry-run validation — so the command must fail honestly,
+        // matching the MCP handler's merged rule
+        if (parseFailures.length > 0 || dryRunResult.invalid.length > 0) {
+            process.exitCode = 1;
+        }
         return;
     }
     // Single confirmation prompt
@@ -88,8 +104,9 @@ export async function pushCommand(file, options) {
     ]) {
         const fileName = path.basename(file.filePath);
         const isCreate = dryResult.action === "create" || dryResult.action === "not_found";
-        // Check if this file had an error
-        const error = result.errors.find((e) => e.fileName === fileName);
+        // Check if this file had an error — match by full path, since two pushed
+        // files can share a basename
+        const error = result.errors.find((e) => e.filePath === file.filePath);
         if (error) {
             console.log(`  ✗ Failed: ${fileName} - ${error.error}`);
         }
@@ -100,6 +117,16 @@ export async function pushCommand(file, options) {
             console.log(`  ✓ Updated: ${fileName}`);
         }
     }
+    // SYNC-FAIL-2.1: the cloud save succeeded but the local file couldn't be
+    // updated — name the file, say the cloud is fine, and give the recovery
+    // step that re-links the file instead of minting a duplicate on retry
+    if (result.writeBackWarnings?.length > 0) {
+        console.log();
+        for (const warning of result.writeBackWarnings) {
+            console.log(`⚠ ${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.`);
+        }
+    }
     // IMPORT-3: marker failures are loud but never fatal
     if (result.importWarnings.length > 0) {
         console.log();
@@ -148,7 +175,7 @@ export async function pushCommand(file, options) {
 /**
  * Display the dry run summary.
  */
-function displayDryRunSummary(dryRunResult) {
+function displayDryRunSummary(dryRunResult, parseFailures = []) {
     const { updates, creates, notFound, invalid, conflicts } = dryRunResult;
     console.log("\n=== Push Summary ===\n");
     if (updates.length > 0) {
@@ -179,11 +206,22 @@ function displayDryRunSummary(dryRunResult) {
         }
         console.log();
     }
-    if (invalid.length > 0) {
-        console.log(`Skipped - invalid files (${invalid.length}):`);
-        for (const { file, result } of invalid) {
-            const fileName = path.basename(file.filePath);
-            console.log(`  ✗ ${fileName}: ${result.error}`);
+    // SYNC-FAIL-4.0: local parse failures surface alongside dry-run invalids,
+    // each named by file, while the rest of the batch proceeds
+    const skipped = [
+        ...parseFailures.map((failure) => ({
+            fileName: path.basename(failure.filePath),
+            error: failure.error,
+        })),
+        ...invalid.map(({ file, result }) => ({
+            fileName: path.basename(file.filePath),
+            error: result.error,
+        })),
+    ];
+    if (skipped.length > 0) {
+        console.log(`Skipped - invalid files (${skipped.length}):`);
+        for (const { fileName, error } of skipped) {
+            console.log(`  ✗ ${fileName}: ${error}`);
         }
         console.log();
     }

package/dist/commands/report.js

@@ -36,8 +36,16 @@ export async function reportCommand(options) {
             `(${error instanceof Error ? error.message : String(error)})`);
     }
     if (options.requirement) {
-        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL);
-        console.log(printCloudRequirement(record, format));
+        // REPORT-CLOUD-1.7: --branch/--since apply to the requirement-scoped
+        // output too, not just the project-wide report
+        const record = await getRequirementCoverage(options.requirement, projectId, projectSecret, CONVEX_URL, {
+            branch: options.branch,
+            sinceTimestamp: options.since,
+        });
+        console.log(printCloudRequirement(record, format, {
+            branch: options.branch,
+            since: options.since,
+        }));
         return;
     }
     const record = await getProjectCoverage(projectId, projectSecret, CONVEX_URL, {
@@ -100,11 +108,18 @@ function formatLocalMarkdown(report) {
     }
     return out;
 }
-function printCloudRequirement(record, format) {
+function printCloudRequirement(record, format, filters) {
     if (format === "json") {
         return JSON.stringify({ source: "cloud", requirement: record }, null, 2);
     }
     if (!record.lastTestedAt) {
+        // REPORT-CLOUD-1.7: with filters in play, an empty record means nothing
+        // matched them — say so rather than implying the requirement was never
+        // tested at all
+        const filterNote = formatCloudFilters(filters);
+        if (filterNote) {
+            return `\n${record.requirementKey}: no coverage records match the requested filters (${filterNote.replace(/^Filters: /, "")}).\n`;
+        }
         return `\n${record.requirementKey}: never tested on the cloud-persisted record.\n`;
     }
     const lastTested = new Date(record.lastTestedAt).toISOString();

package/dist/commands/review-test.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { DEFAULT_API_BASE_URL, fetchReviewTestFeedback, } from "../requirements/cloud-ai.js";
+import { findRequirementsInFile } from "../requirements/grep.js";
 import { formatRequirementTree, getRequirementTree, loadAllRequirements, } from "../requirements/index.js";
 import { getProjectCredentials } from "../utils/project-settings.js";
 export async function reviewTestCommand(testFilePath) {
@@ -15,17 +16,24 @@ export async function reviewTestCommand(testFilePath) {
         throw new Error(`File must be a test file: *.{test,spec}.{js,jsx,ts,tsx} — got ${testFilePath}`);
     }
     const testFileContents = readFileSync(fullPath, "utf-8");
-    // CLI-REVIEW-1.0: collect every requirement(...) call site
-    const requirementIdMatches = testFileContents.matchAll(/requirement\s*\(\s*['"`]([^'"`]+)['"`]\s*\)/g);
-    const requirementIds = new Set();
-    for (const match of requirementIdMatches) {
-        requirementIds.add(match[1]);
-    }
-    // CLI-REVIEW-1.1: resolve references against the workspace and bundle trees
+    // CLI-REVIEW-1.0: collect every requirement(...) call site via the shared
+    // AST-based extractor (as the MCP review handler does post-#43) 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));
+    // CLI-REVIEW-1.1: resolve references against the workspace and bundle trees.
+    // 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 so label-path refs
+    // resolve instead of being dropped.
     const { flattened } = await loadAllRequirements(workspaceRoot);
     const rootToTestedIds = new Map();
     for (const reqId of requirementIds) {
-        const req = flattened.find((r) => r.id === reqId || r.rootId === reqId);
+        const dotIndex = reqId.indexOf(".");
+        const refRootId = dotIndex > 0 ? reqId.substring(0, dotIndex) : reqId;
+        const req = flattened.find((r) => r.rootId === refRootId);
         if (req) {
             if (!rootToTestedIds.has(req.rootId)) {
                 rootToTestedIds.set(req.rootId, new Set());

package/dist/commands/tests-for.js

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

package/dist/commands/validate.js

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

package/dist/harness/cache.d.ts

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

package/dist/harness/cache.js

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

package/dist/harness/finalize.js

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

package/dist/harness/index.js

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

package/dist/harness/requirementsLoader.js

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