roadmapsmith 0.9.28 → 0.9.30

package/src/validator/index.js

@@ -13,6 +13,8 @@ const CODE_EXTENSIONS = new Set([
 ]);
 const TRANSLATION_DIR_SEGMENTS = ['locale', 'locales', 'i18n', 'translations'];
 const DEFAULT_EXCLUDED_PATH_PREFIXES = ['.claude/', '.agent/', 'roadmap-skill/'];
+const GENERATED_OUTPUT_PREFIXES = ['dist-electron/', 'dist/', 'build/', 'out/', '.next/', 'coverage/'];
+const AUXILIARY_HEURISTIC_PATH_SEGMENTS = new Set(['scripts', 'tools', 'tooling', 'demo', 'demos']);
 
 // "docs" omitted from DOC_HINTS — it is a path prefix in scan tasks, not a doc-authoring keyword.
 const DOC_HINTS = ['readme', 'changelog', 'documentation', 'spec', 'diagram', 'runbook'];
@@ -151,6 +153,93 @@ function isMostlyUiStrings(content) {
   return stringLikeLines / lines.length > 0.8;
 }
 
+function isGeneratedOutputPath(relativePath) {
+  const normalized = normalizePathForMatch(relativePath);
+  return GENERATED_OUTPUT_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
+function splitNormalizedPathSegments(relativePath) {
+  return normalizePathForMatch(relativePath).split('/').filter(Boolean);
+}
+
+function isAuxiliaryHeuristicPath(relativePath) {
+  return splitNormalizedPathSegments(relativePath).some((segment) => AUXILIARY_HEURISTIC_PATH_SEGMENTS.has(segment));
+}
+
+function relativePathExplicitlyReferenced(relativePath, options = {}) {
+  const normalized = normalizeReferencedPath(relativePath);
+  const explicitPaths = Array.isArray(options.explicitPaths) ? options.explicitPaths : [];
+  const explicitFilenames = Array.isArray(options.explicitFilenames) ? options.explicitFilenames : [];
+  if (explicitPaths.some((entry) => referencedPathMatches(normalized, entry))) {
+    return true;
+  }
+
+  const baseName = path.basename(normalized);
+  return explicitFilenames.some((entry) => normalizeReferencedPath(entry) === baseName);
+}
+
+function shouldSkipHeuristicFile(relativePath, options = {}) {
+  return isAuxiliaryHeuristicPath(relativePath) && !relativePathExplicitlyReferenced(relativePath, options);
+}
+
+function authoredSiblingGroupKey(relativePath) {
+  const normalized = normalizePathForMatch(relativePath);
+  const ext = path.extname(normalized);
+  return ext ? normalized.slice(0, -ext.length) : normalized;
+}
+
+function authoredSiblingExtensionRank(relativePath) {
+  const ext = path.extname(String(relativePath || '')).toLowerCase();
+  switch (ext) {
+    case '.ts':
+      return 0;
+    case '.tsx':
+      return 1;
+    case '.jsx':
+      return 2;
+    case '.js':
+      return 3;
+    case '.mjs':
+      return 4;
+    case '.cjs':
+      return 5;
+    case '.py':
+      return 6;
+    default:
+      return 10;
+  }
+}
+
+function dedupeAuthoredCompiledSiblings(relativePaths, fileIndex) {
+  const indexedPaths = new Set(fileIndex.map((file) => file.relativePath));
+  const groups = new Map();
+  for (const relativePath of Array.from(new Set(relativePaths)).filter(Boolean)) {
+    if (!indexedPaths.has(relativePath)) {
+      continue;
+    }
+    const key = authoredSiblingGroupKey(relativePath);
+    const group = groups.get(key) || [];
+    group.push(relativePath);
+    groups.set(key, group);
+  }
+
+  const selected = [];
+  for (const group of groups.values()) {
+    group.sort((left, right) => {
+      const rankDelta = authoredSiblingExtensionRank(left) - authoredSiblingExtensionRank(right);
+      if (rankDelta !== 0) return rankDelta;
+      return left.localeCompare(right);
+    });
+    selected.push(group[0]);
+  }
+
+  return selected.sort((left, right) => left.localeCompare(right));
+}
+
+function finalizeHeuristicMatches(relativePaths, fileIndex, limit = 20) {
+  return dedupeAuthoredCompiledSiblings(relativePaths, fileIndex).slice(0, limit);
+}
+
 function readFileIndex(projectRoot, files, config) {
   const index = [];
   for (const relativePath of files) {
@@ -180,6 +269,7 @@ function readFileIndex(projectRoot, files, config) {
       absolutePath,
       ext,
       content,
+      generatedOutput: isGeneratedOutputPath(relativePath),
       isTestFile: /(^|\/)(__tests__|tests)\//.test(relativePath) || /\.test\.|\.spec\.|_test\.go$/.test(relativePath)
     });
   }
@@ -626,23 +716,27 @@ function findFilesByPathHints(pathHints, pathHintResolver) {
   return Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right));
 }
 
-function findFilesBySymbols(symbolHints, fileIndex) {
+function findFilesBySymbols(symbolHints, fileIndex, heuristicOptions = {}) {
   const matches = new Set();
   for (const symbol of symbolHints) {
     const regex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`, 'i');
     for (const file of fileIndex) {
+      if (file.generatedOutput) continue;
       if (!CODE_EXTENSIONS.has(file.ext)) {
         continue;
       }
+      if (shouldSkipHeuristicFile(file.relativePath, heuristicOptions)) {
+        continue;
+      }
       if (regex.test(file.content)) {
         matches.add(file.relativePath);
       }
     }
   }
-  return Array.from(matches).sort((left, right) => left.localeCompare(right));
+  return finalizeHeuristicMatches(Array.from(matches), fileIndex);
 }
 
-function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new Set()) {
+function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new Set(), heuristicOptions = {}) {
   const tokens = tokenize(taskText)
     .filter((token) => token.length >= 6 && !GENERIC_TASK_TOKENS.has(token) && !pathDerivedTokens.has(token))
     .slice(0, 10);
@@ -650,6 +744,10 @@ function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new
 
   const matches = new Set();
   for (const file of fileIndex) {
+    if (file.generatedOutput) continue;
+    if (shouldSkipHeuristicFile(file.relativePath, heuristicOptions)) {
+      continue;
+    }
     const pathSegments = normalizePathForMatch(file.relativePath).split('/').filter(Boolean);
     for (const token of tokens) {
       if (pathSegments.some((segment) => segment === token || segment.includes(token))) {
@@ -659,16 +757,16 @@ function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new
     }
     if (matches.size >= 20) break;
   }
-  return Array.from(matches).sort((left, right) => left.localeCompare(right));
+  return finalizeHeuristicMatches(Array.from(matches), fileIndex);
 }
 
-function extractTaskEvidenceTokens(taskText, pathDerivedTokens = new Set()) {
+function extractTaskEvidenceTokens(taskText, pathDerivedTokens = new Set(), minimumLength = 3) {
   return tokenize(taskText)
-    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/') && !pathDerivedTokens.has(token))
+    .filter((token) => token.length >= minimumLength && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/') && !pathDerivedTokens.has(token))
     .slice(0, 8);
 }
 
-function findWeakPathContentSpecificTokens(taskText, fileIndex, weakPathFiles, pathDerivedTokens = new Set()) {
+function findWeakPathContentSpecificTokens(taskText, fileIndex, weakPathFiles, pathDerivedTokens = new Set(), heuristicOptions = {}) {
   const tokens = extractTaskEvidenceTokens(taskText, pathDerivedTokens);
   if (tokens.length === 0 || weakPathFiles.length === 0) return [];
 
@@ -678,6 +776,9 @@ function findWeakPathContentSpecificTokens(taskText, fileIndex, weakPathFiles, p
     if (!weakFiles.has(file.relativePath) || !CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
       continue;
     }
+    if (shouldSkipHeuristicFile(file.relativePath, heuristicOptions)) {
+      continue;
+    }
 
     const normalizedPath = normalizePathForMatch(file.relativePath);
     const lowered = file.content.toLowerCase();
@@ -736,7 +837,7 @@ function extractPathDerivedTokens(pathHints) {
   return tokens;
 }
 
-function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
+function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set(), heuristicOptions = {}) {
   const tokens = extractTaskEvidenceTokens(taskText, pathDerivedTokens);
   if (tokens.length === 0) {
     return [];
@@ -744,7 +845,10 @@ function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
 
   const matches = [];
   for (const file of fileIndex) {
-    if (!CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
+    if (file.generatedOutput || !CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
+      continue;
+    }
+    if (shouldSkipHeuristicFile(file.relativePath, heuristicOptions)) {
       continue;
     }
 
@@ -767,7 +871,7 @@ function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
     }
   }
 
-  return matches.slice(0, 20);
+  return finalizeHeuristicMatches(matches, fileIndex);
 }
 
 function normalizeReferencedPath(rawPath) {
@@ -802,7 +906,7 @@ function extractTestReadReferences(content) {
   return refs;
 }
 
-function findTestEvidence(taskText, fileIndex, referencedPaths = []) {
+function findTestEvidence(taskText, fileIndex, referencedPaths = [], heuristicOptions = {}) {
   const tokens = tokenize(taskText)
     .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/'))
     .slice(0, 8);
@@ -819,7 +923,10 @@ function findTestEvidence(taskText, fileIndex, referencedPaths = []) {
   const matches = [];
 
   for (const file of fileIndex) {
-    if (!file.isTestFile) continue;
+    if (file.generatedOutput || !file.isTestFile) continue;
+    if (shouldSkipHeuristicFile(file.relativePath, heuristicOptions)) {
+      continue;
+    }
 
     // A test file counts as evidence only when it imports a module whose path contains
     // one of the task's meaningful tokens. Content-keyword matching is intentionally absent:
@@ -856,7 +963,7 @@ function findTestEvidence(taskText, fileIndex, referencedPaths = []) {
     }
   }
 
-  return matches.slice(0, 20);
+  return finalizeHeuristicMatches(matches, fileIndex);
 }
 
 function findArtifactEvidence(taskText, fileIndex) {
@@ -897,6 +1004,7 @@ function findArtifactEvidence(taskText, fileIndex) {
   ];
 
   for (const file of fileIndex) {
+    if (file.generatedOutput) continue;
     if (artifactPatterns.some((pattern) => pattern.test(file.relativePath)) && !files.includes(file.relativePath)) {
       files.push(file.relativePath);
     }
@@ -1273,7 +1381,399 @@ function evaluateRule(rule, task, context) {
   };
 }
 
-function buildValidationContext(projectRoot, config, plugins) {
+function parseVerificationFields(text) {
+  const fields = {};
+  for (const part of String(text || '').split(';')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim().toLowerCase();
+    let value = part.slice(separator + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key && value) fields[key] = value;
+  }
+  return fields;
+}
+
+function stripCodeComments(content) {
+  const source = String(content || '');
+  let result = '';
+  let quote = null;
+  let escaped = false;
+  let lineHasContent = false;
+
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (quote) {
+      result += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      if (char === '\n') lineHasContent = false;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      result += char;
+      lineHasContent = true;
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      const closeIndex = source.indexOf('*/', index + 2);
+      index = closeIndex < 0 ? source.length : closeIndex + 1;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      const newlineIndex = source.indexOf('\n', index + 2);
+      if (newlineIndex < 0) break;
+      result += '\n';
+      lineHasContent = false;
+      index = newlineIndex;
+      continue;
+    }
+
+    if (char === '#' && !lineHasContent) {
+      const newlineIndex = source.indexOf('\n', index + 1);
+      if (newlineIndex < 0) break;
+      result += '\n';
+      lineHasContent = false;
+      index = newlineIndex;
+      continue;
+    }
+
+    result += char;
+    if (char === '\n') {
+      lineHasContent = false;
+    } else if (!/\s/.test(char)) {
+      lineHasContent = true;
+    }
+  }
+
+  return result;
+}
+
+function findIndexedFile(relativePath, context) {
+  const normalized = normalizeReferencedPath(relativePath);
+  return context.fileIndex.find((file) => !file.generatedOutput && (
+    normalizeReferencedPath(file.relativePath) === normalized ||
+    normalizeReferencedPath(file.relativePath).endsWith('/' + normalized)
+  ));
+}
+
+function readTestReportRecords(projectRoot, validationConfig) {
+  const reports = Array.isArray(validationConfig && validationConfig.testReports)
+    ? validationConfig.testReports
+    : [];
+  const records = [];
+
+  function visit(value, reportPath, mtimeMs) {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      value.forEach((entry) => visit(entry, reportPath, mtimeMs));
+      return;
+    }
+    const status = String(value.status || value.state || value.result || '').toLowerCase();
+    const file = value.file || value.filepath || value.testFile || value.nameFile;
+    const name = value.fullName || value.fullname || value.name || value.title;
+    if (file && name && /^(pass|passed|success)$/.test(status)) {
+      records.push({ file: String(file), name: String(name), reportPath, mtimeMs });
+    }
+    Object.values(value).forEach((entry) => visit(entry, reportPath, mtimeMs));
+  }
+
+  for (const report of reports) {
+    if (!report || report.format !== 'vitest-json' || !report.path) continue;
+    const reportPath = path.resolve(projectRoot, report.path);
+    try {
+      const payload = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+      const mtimeMs = fs.statSync(reportPath).mtimeMs;
+      visit(payload, reportPath, mtimeMs);
+    } catch {
+      // A missing or malformed optional report is simply unavailable evidence.
+    }
+  }
+  return records;
+}
+
+function timestampIsFresh(timestamp, files) {
+  const verifiedAt = Date.parse(timestamp || '');
+  if (!Number.isFinite(verifiedAt)) return false;
+  return files.every((file) => {
+    try {
+      return verifiedAt >= fs.statSync(file.absolutePath).mtimeMs;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function findFreshTestProof(task, fields, context) {
+  const testFile = findIndexedFile(fields.test || fields.file, context);
+  const sourceFile = fields.source ? findIndexedFile(fields.source, context) : null;
+  const caseName = fields.case;
+  if (!testFile || !caseName) return { passed: false, available: false };
+  const freshnessFiles = [testFile, ...(sourceFile ? [sourceFile] : [])];
+  const evidenceLines = Array.isArray(task.testEvidenceLines) ? task.testEvidenceLines : [];
+  for (const line of evidenceLines) {
+    const evidence = parseVerificationFields(line.text);
+    if (String(evidence.status || '').toUpperCase() !== 'PASS') continue;
+    if (normalizeReferencedPath(evidence.file) !== normalizeReferencedPath(testFile.relativePath)) continue;
+    if (evidence.case !== caseName) continue;
+    if (timestampIsFresh(evidence.verifiedat, freshnessFiles)) {
+      return { passed: true, available: true };
+    }
+    return { passed: false, available: true, stale: true };
+  }
+  for (const record of context.testReportRecords || []) {
+    if (!referencedPathMatches(record.file, testFile.relativePath) || !record.name.includes(caseName)) continue;
+    if (record.mtimeMs >= Math.max(...freshnessFiles.map((file) => fs.statSync(file.absolutePath).mtimeMs))) {
+      return {
+        passed: true,
+        available: true,
+        generatedEvidence: `file=${testFile.relativePath}; case=${caseName}; status=PASS; verifiedAt=${new Date(record.mtimeMs).toISOString()}`
+      };
+    }
+    return { passed: false, available: true, stale: true };
+  }
+  return { passed: false, available: false };
+}
+
+function testCoversEndpoint(testFile, route, context) {
+  const normalizedRoute = String(route).replace(/\[([^\]]+)\]/g, '$1').toLowerCase();
+  const normalizedContent = testFile.content.replace(/\[([^\]]+)\]/g, '$1').toLowerCase();
+  if (normalizedContent.includes(normalizedRoute)) return true;
+  const source = findIndexedFile(`src/app${route}/route.ts`, context);
+  if (source && normalizedContent.includes(path.basename(source.relativePath, source.ext).toLowerCase())) return true;
+  const segments = normalizedRoute.split('/').filter((segment) => segment.length >= 3);
+  return segments.length > 0 && segments.every((segment) => normalizedContent.includes(segment));
+}
+
+function extractPathDomainTokens(relativePath) {
+  return splitNormalizedPathSegments(relativePath)
+    .flatMap((segment) => tokenize(segment))
+    .filter((token) => token.length >= 2 && !GENERIC_TASK_TOKENS.has(token));
+}
+
+function collectRecipeLineContext(content, index) {
+  const source = String(content || '');
+  const lineStart = source.lastIndexOf('\n', index);
+  const lineEnd = source.indexOf('\n', index);
+  const previousLineStart = lineStart > 0 ? source.lastIndexOf('\n', lineStart - 1) : -1;
+  const start = previousLineStart >= 0 ? previousLineStart + 1 : 0;
+  const end = lineEnd >= 0 ? lineEnd : source.length;
+  return source.slice(start, end);
+}
+
+function appendUniqueDiagnostic(diagnostics, diagnostic) {
+  if (!diagnostic || !diagnostic.code) {
+    return diagnostics;
+  }
+  if (diagnostics.some((item) => item.code === diagnostic.code)) {
+    return diagnostics;
+  }
+  diagnostics.push(diagnostic);
+  return diagnostics;
+}
+
+function buildTaskRecipeCandidatePool(task, context) {
+  const { paths: pathHints, externalPaths } = extractExplicitPaths(task.text);
+  const standaloneFilenames = extractStandaloneFilenames(task.text);
+  const symbolHints = extractSymbolHints(task.text);
+  const pathDerivedTokens = extractPathDerivedTokens([...pathHints, ...externalPaths, ...standaloneFilenames]);
+  const heuristicOptions = {
+    explicitPaths: [...pathHints, ...externalPaths],
+    explicitFilenames: standaloneFilenames
+  };
+  const candidatePaths = unionArrays(
+    findFilesByPathHints(pathHints, context.pathHintResolver),
+    findFilesBySymbols(symbolHints, context.fileIndex, heuristicOptions),
+    findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens, heuristicOptions),
+    findFilesByTaskPathTokens(task.text, context.fileIndex, pathDerivedTokens, heuristicOptions)
+  );
+  const indexedFiles = new Map(context.fileIndex.map((file) => [file.relativePath, file]));
+  return candidatePaths.map((relativePath) => indexedFiles.get(relativePath)).filter(Boolean);
+}
+
+function findVerificationRecipe(task, context) {
+  if ((Array.isArray(task.verifyLines) && task.verifyLines.length > 0) || (Array.isArray(task.evidenceLines) && task.evidenceLines.length > 0)) {
+    return { recipe: null, specificityFailure: false, foundStaticSignal: false };
+  }
+
+  const patterns = [
+    /disabled\s*=\s*\{[^}]+\}/i,
+    /<(?:dialog|alertdialog)\b[^>]*\bopen\s*=/i,
+    /abortcontroller|abortsignal\.timeout/i,
+    /router\.push\s*\(/i
+  ];
+  const taskTokens = extractTaskEvidenceTokens(task.text, new Set(), 2);
+  const candidateFiles = buildTaskRecipeCandidatePool(task, context);
+  const candidates = [];
+  let foundStaticSignal = false;
+
+  for (const file of candidateFiles) {
+    if (file.generatedOutput || file.isTestFile || !CODE_EXTENSIONS.has(file.ext)) continue;
+    for (const pattern of patterns) {
+      const match = pattern.exec(file.content);
+      if (!match) {
+        continue;
+      }
+      foundStaticSignal = true;
+      const pathTokens = extractPathDomainTokens(file.relativePath);
+      if (!pathTokens.some((token) => taskTokens.includes(token))) {
+        continue;
+      }
+      const lineContext = collectRecipeLineContext(file.content, match.index);
+      const contextTokens = extractTaskEvidenceTokens(`${match[0]} ${lineContext}`, new Set(), 2);
+      if (!contextTokens.some((token) => taskTokens.includes(token))) {
+        continue;
+      }
+      const line = file.content.slice(0, match.index).split(/\r?\n/).length;
+      const command = context.config.validation && context.config.validation.recipeCommand
+        ? `; run ${String(context.config.validation.recipeCommand).replace('{testFile}', '<test-file>')}`
+        : '';
+      candidates.push(`${file.relativePath}:${line} inspect ${match[0].trim()}${command}`);
+      break;
+    }
+  }
+
+  const uniqueCandidates = Array.from(new Set(candidates));
+  if (uniqueCandidates.length === 1) {
+    return { recipe: uniqueCandidates[0], specificityFailure: false, foundStaticSignal };
+  }
+
+  return {
+    recipe: null,
+    specificityFailure: foundStaticSignal || candidates.length > 0,
+    foundStaticSignal
+  };
+}
+
+function isBehavioralTask(taskText) {
+  return /\b(mostrar|deshabilitar|confirmar|notificar|redirigir|imprimir|show|disable|confirm|notify|redirect|print)\b/i.test(String(taskText || ''));
+}
+
+function evaluateDeterministicVerification(task, context) {
+  const verifyLines = Array.isArray(task.verifyLines) ? task.verifyLines : [];
+  if (verifyLines.length === 0) {
+    if (!isBehavioralTask(task.text)) {
+      return { applicable: false, passed: false, reasons: [], diagnostics: [], recipe: null };
+    }
+    const recipeResult = findVerificationRecipe(task, context);
+    const diagnostics = [];
+    if (recipeResult.specificityFailure) {
+      diagnostics.push({
+        code: 'REQUIRES_HUMAN_EVIDENCE',
+        severity: 'warning',
+        message: 'behavioral task requires explicit human or test evidence'
+      });
+      diagnostics.push({
+        code: 'NO_SPECIFIC_RECIPE',
+        severity: 'warning',
+        message: 'no task-specific verification recipe could be generated'
+      });
+    } else {
+      diagnostics.push({
+        code: recipeResult.recipe ? 'REQUIRES_HUMAN_EVIDENCE' : 'NO_STATIC_SIGNAL',
+        severity: 'warning',
+        message: recipeResult.recipe ? 'behavioral task requires explicit human or test evidence' : 'no static implementation signal was found for behavioral task'
+      });
+    }
+    return {
+      applicable: false,
+      passed: false,
+      reasons: [],
+      diagnostics,
+      recipe: recipeResult.recipe
+    };
+  }
+  const reasons = [];
+  const diagnostics = [];
+  let generatedTestEvidence = null;
+
+  for (const line of verifyLines) {
+    const fields = parseVerificationFields(line.text);
+    const kind = fields.kind;
+    if (kind === 'contains' || kind === 'property') {
+      const file = findIndexedFile(fields.file, context);
+      if (!file) {
+        reasons.push(`missing referenced file(s): ${fields.file || '<unspecified>'}`);
+        continue;
+      }
+      const content = stripCodeComments(file.content);
+      if (kind === 'contains') {
+        if (!fields.expected || !content.includes(fields.expected)) {
+          reasons.push(`no content match in ${file.relativePath}: expected ${fields.expected || '<unspecified>'}`);
+        }
+        continue;
+      }
+      const keyPattern = new RegExp(`\\b${escapeRegExp(fields.key || '')}\\s*:`);
+      const exactPattern = new RegExp(`\\b${escapeRegExp(fields.key || '')}\\s*:\\s*${escapeRegExp(fields.equals || '')}(?=\\s*[,}\\n])`);
+      if (!exactPattern.test(content)) {
+        reasons.push(keyPattern.test(content)
+          ? `wrong value for ${fields.key} in ${file.relativePath}: expected ${fields.equals}`
+          : `no content match in ${file.relativePath}: expected ${fields.key}: ${fields.equals}`);
+      }
+      continue;
+    }
+    if (kind === 'endpoints') {
+      const routes = String(fields.routes || '').split(',').map((value) => value.trim()).filter(Boolean);
+      const tests = context.fileIndex.filter((file) => !file.generatedOutput && file.isTestFile);
+      const covered = routes.filter((route) => tests.some((file) => testCoversEndpoint(file, route, context)));
+      if (covered.length !== routes.length) {
+        const missing = routes.filter((route) => !covered.includes(route));
+        reasons.push(`partial endpoint coverage ${covered.length}/${routes.length}: missing ${missing.join(', ')}`);
+      }
+      continue;
+    }
+    if (kind === 'behavior') {
+      const source = findIndexedFile(fields.source, context);
+      const testFile = findIndexedFile(fields.test, context);
+      const testContent = testFile ? testFile.content : '';
+      const sourceReference = source && testContent.includes(path.basename(source.relativePath, source.ext));
+      const exercise = fields.trigger && testContent.includes(fields.trigger);
+      const assertion = fields.assertion && testContent.includes(fields.assertion);
+      const namedCase = fields.case && testContent.includes(fields.case);
+      const proof = findFreshTestProof(task, fields, context);
+      if (!source || !testFile || !sourceReference || !exercise || !assertion || !namedCase) {
+        diagnostics.push({ code: 'REQUIRES_HUMAN_EVIDENCE', severity: 'warning', message: 'behavior verification needs a source reference, named test, trigger, and assertion' });
+        continue;
+      }
+      if (proof.stale) {
+        diagnostics.push({ code: 'STALE_TEST_REPORT', severity: 'warning', message: `test result for ${testFile.relativePath} predates the verified source` });
+        continue;
+      }
+      if (!proof.passed) {
+        diagnostics.push({ code: 'REQUIRES_HUMAN_EVIDENCE', severity: 'warning', message: `no fresh passing result for ${testFile.relativePath}` });
+        continue;
+      }
+      generatedTestEvidence = proof.generatedEvidence || generatedTestEvidence;
+      continue;
+    }
+    reasons.push(`unsupported verification kind: ${kind || '<unspecified>'}`);
+  }
+
+  const passed = reasons.length === 0 && diagnostics.length === 0;
+  return {
+    applicable: true,
+    passed,
+    reasons,
+    diagnostics,
+    generatedTestEvidence,
+    recipe: null
+  };
+}
+
+function buildValidationContext(projectRoot, config, plugins, options = {}) {
   const files = walkFiles(projectRoot);
   const fileIndex = readFileIndex(projectRoot, files, config);
   const testFrameworks = detectTestFrameworks(projectRoot, files);
@@ -1286,7 +1786,9 @@ function buildValidationContext(projectRoot, config, plugins) {
     files,
     fileIndex,
     pathHintResolver,
-    testFrameworks
+    testFrameworks,
+    testReportRecords: readTestReportRecords(projectRoot, config.validation),
+    strictValidation: options.strictValidation === true
   };
 }
 
@@ -1298,6 +1800,15 @@ function diagnosticCodeForReason(reason) {
   if (normalized.includes('missing test evidence')) {
     return 'NO_TEST';
   }
+  if (normalized.includes('wrong value')) {
+    return 'WRONG_VALUE';
+  }
+  if (normalized.includes('partial endpoint coverage')) {
+    return 'PARTIAL';
+  }
+  if (normalized.includes('no content match')) {
+    return 'NOT_IMPLEMENTED';
+  }
   if (
     normalized.includes('no code, test, or artifact evidence found') ||
     normalized.includes('implementation task requires evidence line') ||
@@ -1327,6 +1838,10 @@ function buildDiagnostics(reasons, options = {}) {
       message: 'historical validation warning conflicts with fresh repository evidence'
     });
   }
+  for (const diagnostic of options.extra || []) {
+    if (!diagnostic || !diagnostic.code || diagnostics.some((item) => item.code === diagnostic.code)) continue;
+    diagnostics.push(diagnostic);
+  }
   return diagnostics;
 }
 
@@ -1347,19 +1862,26 @@ function validateTask(task, context, config, plugins) {
   const purePathHints = pathHints.filter((p) => !lineReferenceHints.has(p));
   const standaloneFilenames = extractStandaloneFilenames(task.text);
   const symbolHints = extractSymbolHints(task.text);
+  const heuristicOptions = {
+    explicitPaths: [...pathHints, ...externalPaths],
+    explicitFilenames: standaloneFilenames
+  };
+  const strictValidation = context.strictValidation === true;
   const authoritativeEvidence = evaluateAuthoritativeEvidence(task, context.pathHintResolver);
+  const deterministicVerification = evaluateDeterministicVerification(task, context);
+  const hasExplicitPendingItems = Array.isArray(task.explicitPendingItems) && task.explicitPendingItems.length > 0;
 
   const filesFromPaths = findFilesByPathHints(pathHints, context.pathHintResolver);
   const filesFromPurePathHints = findFilesByPathHints(purePathHints, context.pathHintResolver);
-  const filesFromSymbols = findFilesBySymbols(symbolHints, context.fileIndex);
+  const filesFromSymbols = findFilesBySymbols(symbolHints, context.fileIndex, heuristicOptions);
   // Combine path hints AND standalone filenames for token exclusion so that tokens
   // derived from any referenced filename (e.g. "roadmap-skill" from
   // "roadmap-skill.config.json") are excluded from code evidence scoring.
   const pathDerivedTokens = extractPathDerivedTokens([...pathHints, ...externalPaths, ...standaloneFilenames]);
-  const filesFromCode = findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens);
-  const filesFromWeakPathTokens = findFilesByTaskPathTokens(task.text, context.fileIndex, pathDerivedTokens);
-  const weakPathContentTokens = findWeakPathContentSpecificTokens(task.text, context.fileIndex, filesFromWeakPathTokens, pathDerivedTokens);
-  const filesFromTests = findTestEvidence(task.text, context.fileIndex, [...pathHints, ...standaloneFilenames]);
+  const filesFromCode = findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens, heuristicOptions);
+  const filesFromWeakPathTokens = findFilesByTaskPathTokens(task.text, context.fileIndex, pathDerivedTokens, heuristicOptions);
+  const weakPathContentTokens = findWeakPathContentSpecificTokens(task.text, context.fileIndex, filesFromWeakPathTokens, pathDerivedTokens, heuristicOptions);
+  const filesFromTests = findTestEvidence(task.text, context.fileIndex, [...pathHints, ...standaloneFilenames], heuristicOptions);
   const { files: filesFromArtifacts, heuristicArtifacts } = findArtifactEvidence(task.text, context.fileIndex);
 
   const structuralCheck = checkNamespaceStructuralEvidence(task.id, task.text, context.fileIndex);
@@ -1424,7 +1946,8 @@ function validateTask(task, context, config, plugins) {
     context.testFrameworks.length > 0 &&
     isCodeTask(task.text) &&
     !isDocTask(task.text) &&
-    !isHttpExpectationTask(task.text);
+    !isHttpExpectationTask(task.text) &&
+    !(task.verifyLines || []).some((line) => ['contains', 'property', 'endpoints', 'behavior'].includes(parseVerificationFields(line.text).kind));
   const configuredRules = Array.isArray(config.validators) ? config.validators : [];
   const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
   let overrideResult = null;
@@ -1458,6 +1981,18 @@ function validateTask(task, context, config, plugins) {
 
   let uniqueReasons = Array.from(new Set(reasons));
 
+  if (deterministicVerification.passed) {
+    uniqueReasons = uniqueReasons.filter((reason) => (
+      reason !== 'no code, test, or artifact evidence found' &&
+      reason !== 'missing test evidence' &&
+      !reason.startsWith('weak path-')
+    ));
+  }
+
+  if (deterministicVerification.applicable && deterministicVerification.reasons.length > 0) {
+    uniqueReasons = Array.from(new Set([...uniqueReasons, ...deterministicVerification.reasons]));
+  }
+
   if (overrideResult) {
     uniqueReasons = Array.isArray(overrideResult.reasons) ? Array.from(new Set(overrideResult.reasons)) : [];
   }
@@ -1516,7 +2051,17 @@ function validateTask(task, context, config, plugins) {
   const hasFreshRepositoryEvidence = hasStrongEvidence || hasWeakEvidence;
   let staleEvidenceDetected = false;
   let staleEvidenceResolved = false;
-  let passed = authoritativeEvidence.passed || hasArtifactTaskPass || hasTrustedRuleEvidencePass || meetsStrongThreshold;
+  // Heuristic proximity remains useful to locate candidates, but is never sufficient to
+  // complete an unchecked task. Completion requires human Evidence, a trusted rule, or a
+  // typed deterministic verifier.
+  let passed = strictValidation
+    ? (authoritativeEvidence.passed || deterministicVerification.passed)
+    : (authoritativeEvidence.passed || hasTrustedRuleEvidencePass || deterministicVerification.passed);
+
+  if (!task.checked && !authoritativeEvidence.passed && !hasTrustedRuleEvidencePass && !deterministicVerification.passed && hasHighConfidenceImplementationEvidence) {
+    uniqueReasons.push('implementation task requires deterministic Verify metadata or explicit Evidence to be marked complete');
+    uniqueReasons = Array.from(new Set(uniqueReasons));
+  }
 
   if (task.warningText && !task.checked && hasFreshRepositoryEvidence && !authoritativeEvidence.passed) {
     staleEvidenceDetected = true;
@@ -1531,7 +2076,7 @@ function validateTask(task, context, config, plugins) {
 
   // Historical warnings are only cleared by independent, high-confidence repository evidence.
   if (task.warningText && !task.checked && passed && !authoritativeEvidence.passed) {
-    if (hasHighConfidenceImplementationEvidence && negativeSignalMatches.length === 0 && uniqueReasons.length === 0) {
+    if ((deterministicVerification.passed || hasHighConfidenceImplementationEvidence) && negativeSignalMatches.length === 0 && uniqueReasons.length === 0) {
       staleEvidenceResolved = true;
     } else {
       passed = false;
@@ -1544,6 +2089,16 @@ function validateTask(task, context, config, plugins) {
     passed = false;
   }
 
+  const extraDiagnostics = [...deterministicVerification.diagnostics];
+  if (hasExplicitPendingItems) {
+    passed = false;
+    extraDiagnostics.push({
+      code: 'HAS_EXPLICIT_PENDING',
+      severity: 'warning',
+      message: `task declares pending item(s): ${task.explicitPendingItems.map((item) => item.text || 'pending').join(', ')}`
+    });
+  }
+
   // Unchecked implementation tasks need explicit evidence or high-confidence implementation
   // evidence. Weak token overlap, direct file references, or code-only matches are not enough.
   if (
@@ -1552,6 +2107,7 @@ function validateTask(task, context, config, plugins) {
     isImplementationTask(task.text) &&
     !authoritativeEvidence.passed &&
     !hasTrustedRuleEvidencePass &&
+    !deterministicVerification.passed &&
     !hasArtifactTaskPass &&
     !hasHighConfidenceImplementationEvidence
   ) {
@@ -1571,6 +2127,7 @@ function validateTask(task, context, config, plugins) {
   const shouldPreserveCheckedTask =
     task.checked &&
     !passed &&
+    !strictValidation &&
     !authoritativeEvidence.active &&
     symbolHints.length === 0 &&
     negativeSignalMatches.length === 0 &&
@@ -1588,13 +2145,15 @@ function validateTask(task, context, config, plugins) {
   // Used by auditValidation to flag implementation tasks that pass solely via documentation.
   const evidenceIsDocOnly = !evidence.code && !evidence.test && evidence.artifact && !isDocTask(task.text);
 
-  const finalPassed = overrideResult ? overrideResult.passed !== false : (passed && uniqueReasons.length === 0);
+  const finalPassed = (!strictValidation && overrideResult)
+    ? (overrideResult.passed !== false && !hasExplicitPendingItems)
+    : (passed && uniqueReasons.length === 0 && !hasExplicitPendingItems);
   return {
     taskId: task.id,
     passed: finalPassed,
     confidence,
     reasons: uniqueReasons,
-    diagnostics: buildDiagnostics(uniqueReasons, { staleEvidence: staleEvidenceDetected }),
+    diagnostics: buildDiagnostics(uniqueReasons, { staleEvidence: staleEvidenceDetected, extra: extraDiagnostics }),
     evidence,
     evidenceIsDocOnly,
     requiresTest,
@@ -1602,7 +2161,9 @@ function validateTask(task, context, config, plugins) {
     attempted,
     preservedCheckedState,
     staleEvidenceResolved,
-    discoveredEvidence: staleEvidenceResolved ? buildDiscoveredEvidenceLine(evidence) : null
+    discoveredEvidence: staleEvidenceResolved ? buildDiscoveredEvidenceLine(evidence) : null,
+    verificationRecipe: deterministicVerification.recipe,
+    generatedTestEvidence: deterministicVerification.generatedTestEvidence || null
   };
 }
 
@@ -1635,6 +2196,33 @@ function validateTasks(tasks, context, config, plugins) {
     }
   }
 
+  const recipeOwners = new Map();
+  for (const [taskId, taskResult] of Object.entries(result)) {
+    if (!taskResult.verificationRecipe) {
+      continue;
+    }
+    const owners = recipeOwners.get(taskResult.verificationRecipe) || [];
+    owners.push(taskId);
+    recipeOwners.set(taskResult.verificationRecipe, owners);
+  }
+
+  for (const [recipe, owners] of recipeOwners.entries()) {
+    if (owners.length < 2) {
+      continue;
+    }
+    for (const taskId of owners) {
+      if (!result[taskId] || result[taskId].verificationRecipe !== recipe) {
+        continue;
+      }
+      result[taskId].verificationRecipe = null;
+      appendUniqueDiagnostic(result[taskId].diagnostics, {
+        code: 'NO_SPECIFIC_RECIPE',
+        severity: 'warning',
+        message: 'generated verification recipe was not unique to a single task'
+      });
+    }
+  }
+
   return result;
 }