roadmapsmith 0.9.9 → 0.9.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.9",
+  "version": "0.9.11",
   "description": "Evidence-backed ROADMAP.md generator and sync tool for AI coding agents.",
   "main": "src/index.js",
   "bin": {

package/src/parser/index.js

@@ -86,6 +86,11 @@ function parseWarningLine(content) {
   return content.slice(WARNING_PREFIX.length).trim();
 }
 
+function parseBlockedByLine(content) {
+  if (!/^blocked\s+by:/i.test(content)) return null;
+  return content.replace(/^blocked\s+by:\s*/i, '').trim();
+}
+
 function parseRoadmap(content) {
   const lines = String(content || '').split(/\r?\n/);
   const managedRange = findManagedRange(lines);
@@ -111,6 +116,7 @@ function parseRoadmap(content) {
     let warningLineIndex = null;
     let warningText = null;
     const evidenceLines = [];
+    const blockedByIds = [];
     let lastChildLineIndex = index;
     for (let childIndex = index + 1; childIndex < lines.length; childIndex += 1) {
       const childLine = lines[childIndex];
@@ -145,6 +151,12 @@ function parseRoadmap(content) {
         warningLineIndex = childIndex;
         warningText = warningTextValue;
       }
+
+      const blockedByText = parseBlockedByLine(childBullet.content);
+      if (blockedByText !== null) {
+        const ids = blockedByText.split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
+        blockedByIds.push(...ids);
+      }
     }
 
     const id = markerId || slugify(text);
@@ -157,6 +169,7 @@ function parseRoadmap(content) {
       warningLineIndex,
       warningText,
       evidenceLines,
+      blockedByIds,
       markerId,
       noTest,
       indent,

package/src/validator/index.js

@@ -50,6 +50,28 @@ const GENERIC_TASK_TOKENS = new Set([
   'phrases', 'conceptual',
 ]);
 
+// Verbs that indicate the task describes work still to be done, not completed work.
+// When a task starts with one of these verbs, code token overlap alone cannot pass it —
+// either an Evidence line (authoritativeEvidence.passed) or test evidence is required.
+const ACTION_VERBS = new Set([
+  'agregar', 'mostrar', 'implementar', 'configurar', 'reemplazar', 'cambiar',
+  'corregir', 'manejar', 'proteger', 'sanitizar', 'validar', 'deshabilitar',
+  'generar', 'expandir', 'reducir', 'completar', 'crear', 'eliminar',
+  'add', 'show', 'implement', 'configure', 'replace', 'change', 'fix',
+  'handle', 'protect', 'sanitize', 'validate', 'disable', 'generate',
+  'expand', 'reduce', 'complete', 'create', 'remove'
+]);
+
+function taskStartsWithActionVerb(taskText) {
+  const normalized = String(taskText)
+    .replace(/\*\*([^*]+)\*\*/g, '$1')
+    .replace(/\[([^\]]+)\]/g, '$1')
+    .trim()
+    .toLowerCase();
+  const firstWord = normalized.split(/[\s,;:()[\]]+/)[0] || '';
+  return ACTION_VERBS.has(firstWord);
+}
+
 const CANONICAL_FILES = {
   security: 'SECURITY.md',
   readme: 'README.md',
@@ -178,7 +200,11 @@ function hasFileExtension(token) {
 }
 
 function isLikelyPath(token) {
-  if (/^\.{1,2}\/|^\//.test(token)) return true;
+  if (token.includes('*') || token.includes('?')) return false; // glob/wildcard
+  if (/^\.{1,2}\/|^\//.test(token)) {
+    // Bare "/" or "./" with nothing after is not a real path (e.g. "API / ESC-POS" → "/")
+    return /[A-Za-z0-9_]/.test(token);
+  }
   if (hasFileExtension(token)) return true;
   if (KNOWN_PATH_ROOTS.some((root) => token.startsWith(root))) return true;
   // The ">= 2 slashes" rule was intentionally removed: it caused conceptual slash phrases
@@ -262,14 +288,16 @@ function extractExplicitPaths(text) {
   for (const token of quoted) {
     const clean = token.slice(1, -1);
     if (clean.includes('*') || clean.includes('?')) continue; // glob
-    if (clean.includes('/') || clean.includes('\\') || clean.includes('.')) {
-      const lineMatch = LINE_REF_RE.exec(clean);
-      if (lineMatch && hasKnownFileExtension(lineMatch[1])) {
-        lineReferenceHints.add(lineMatch[1]);
-        results.add(lineMatch[1]);
-      } else {
-        results.add(clean);
-      }
+    const hasSlash = clean.includes('/') || clean.includes('\\');
+    // Require a slash or a known file extension — rejects property access like err.message,
+    // fs.readFileSync, error.stack (whose extensions are not in KNOWN_FILE_EXTENSIONS).
+    if (!hasSlash && !hasKnownFileExtension(clean)) continue;
+    const lineMatch = LINE_REF_RE.exec(clean);
+    if (lineMatch && hasKnownFileExtension(lineMatch[1])) {
+      lineReferenceHints.add(lineMatch[1]);
+      results.add(lineMatch[1]);
+    } else {
+      results.add(clean);
     }
   }
 
@@ -288,7 +316,9 @@ function extractExplicitPaths(text) {
     }
   }
 
-  const paths = Array.from(results).sort((left, right) => left.localeCompare(right));
+  const paths = Array.from(results)
+    .filter((p) => !p.includes('*') && !p.includes('?'))
+    .sort((left, right) => left.localeCompare(right));
   return { paths, lineReferenceHints };
 }
 
@@ -1060,7 +1090,9 @@ function validateTask(task, context, config, plugins) {
     code: filesFromCode.length > 0 || filesFromSymbols.length > 0,
     test: filesFromTests.length > 0,
     artifact: filesFromArtifacts.length > 0,
-    files: filesFromPaths,
+    // Use only pure path hints (not line-reference hints) so that "file.ts:169" style hints
+    // — which indicate WHERE to implement — do not contribute to feature-surface scoring.
+    files: filesFromPurePathHints,
     symbols: filesFromSymbols,
     codeFiles: filesFromCode,
     weakPathFiles: filesFromWeakPathTokens,
@@ -1077,7 +1109,9 @@ function validateTask(task, context, config, plugins) {
   applyAuthoritativeEvidence(evidence, authoritativeEvidence, context.fileIndex);
 
   const reasons = [];
-  if (pathHints.length > 0 && filesFromPaths.length === 0) {
+  // Suppress path hint failures when authoritative evidence already confirms the task —
+  // a bad path hint (typo, moved file) should not override a passing Evidence line.
+  if (pathHints.length > 0 && filesFromPaths.length === 0 && !authoritativeEvidence.passed) {
     reasons.push(`missing referenced file(s): ${pathHints.join(', ')}`);
   }
   if (Array.isArray(authoritativeEvidence.reasons) && authoritativeEvidence.reasons.length > 0) {
@@ -1182,8 +1216,23 @@ function validateTask(task, context, config, plugins) {
     uniqueReasons = Array.from(new Set(uniqueReasons));
   }
 
-  let passed = authoritativeEvidence.passed || hasDirectReferencePass || hasArtifactTaskPass || hasTrustedRuleEvidencePass || meetsStrongThreshold;
-  if (task.warningText && passed && !authoritativeEvidence.passed && !meetsStrongThreshold) {
+  // hasDirectReferencePass is intentionally excluded: a path hint in task text indicates
+  // WHERE to implement, not that implementation is done. Unchecked tasks need authoritative
+  // evidence, artifact evidence, or strong code+test threshold to pass.
+  // Already-checked tasks with found path hints are preserved via shouldPreserveCheckedTask.
+  let passed = authoritativeEvidence.passed || hasArtifactTaskPass || hasTrustedRuleEvidencePass || meetsStrongThreshold;
+
+  if (!passed && !task.checked && hasDirectReferencePass) {
+    const locationReason = 'file reference shows implementation location, not confirmed completion';
+    if (!uniqueReasons.includes(locationReason)) {
+      uniqueReasons.push(locationReason);
+    }
+  }
+
+  // Unchecked tasks with an existing ⚠️ warning are preserved as failing unless an Evidence line
+  // explicitly confirms implementation. meetsStrongThreshold (token match) cannot override a
+  // human/agent judgment that the feature is incomplete.
+  if (task.warningText && !task.checked && passed && !authoritativeEvidence.passed) {
     passed = false;
     uniqueReasons.push(task.warningText);
     uniqueReasons = Array.from(new Set(uniqueReasons));
@@ -1192,15 +1241,43 @@ function validateTask(task, context, config, plugins) {
     passed = false;
   }
 
+  // Action-verb gate (Causa 3): unchecked tasks whose text starts with a pending-work verb
+  // (Agregar, Configurar, Add, Fix, …) cannot pass on code token overlap alone.
+  // The verb signals "this is work to do", so the validator requires either:
+  //   a) an Evidence line confirming the work is done (authoritativeEvidence.passed), or
+  //   b) test evidence proving the feature is exercised, or
+  //   c) grant-evidence from a config rule (hasTrustedRuleEvidencePass), or
+  //   d) canonical artifact evidence (hasArtifactTaskPass — e.g. "Add SECURITY.md").
+  if (
+    !task.checked &&
+    passed &&
+    taskStartsWithActionVerb(task.text) &&
+    !authoritativeEvidence.passed &&
+    !hasTrustedRuleEvidencePass &&
+    !hasArtifactTaskPass &&
+    !evidence.test
+  ) {
+    passed = false;
+    const actionVerbReason = 'action-verb task requires high-confidence evidence or Evidence line';
+    if (!uniqueReasons.includes(actionVerbReason)) {
+      uniqueReasons.push(actionVerbReason);
+    }
+  }
+
+  // Preserve already-checked tasks when the validator can't confirm implementation but also
+  // can't find strong evidence against it. Two cases:
+  //   1. No path/symbol hints at all — no machine-readable claims to evaluate.
+  //   2. Path hints resolve to existing files but code/test evidence is absent —
+  //      file presence is not implementation; don't uncheck on that alone.
+  // Symbol hints are NOT preserved: a missing symbol is a concrete falsifiable claim.
   const shouldPreserveCheckedTask =
     task.checked &&
     !passed &&
     !authoritativeEvidence.active &&
-    purePathHints.length === 0 &&
     symbolHints.length === 0 &&
-    !hasDirectReferencePass &&
+    negativeSignalMatches.length === 0 &&
     evidence.structuralEvidence !== false &&
-    negativeSignalMatches.length === 0;
+    (hasDirectReferencePass || purePathHints.length === 0);
   let preservedCheckedState = false;
   if (shouldPreserveCheckedTask) {
     passed = true;
@@ -1235,13 +1312,21 @@ function validateTasks(tasks, context, config, plugins) {
     result[task.id] = validateTask(task, context, config, plugins);
   }
 
-  // Post-pass: milestone tasks with "Blocked by: id-a, id-b" cannot pass
-  // while any listed dependency is still failing.
+  // Post-pass: tasks with "Blocked by: id-a, id-b" cannot pass while any listed dependency
+  // is still failing. The IDs may appear inline in task.text OR as child bullet lines
+  // (parsed by parser into task.blockedByIds).
   for (const task of tasks) {
+    const blockedIds = [];
     const m = BLOCKED_BY_RE.exec(task.text);
-    if (!m) continue;
-    const blockedIds = m[1].split(/[\s,]+/).map((s) => s.trim()).filter(Boolean);
-    const failingDeps = blockedIds.filter((id) => result[id] && !result[id].passed);
+    if (m) {
+      blockedIds.push(...m[1].split(/[\s,]+/).map((s) => s.trim()).filter(Boolean));
+    }
+    if (Array.isArray(task.blockedByIds) && task.blockedByIds.length > 0) {
+      blockedIds.push(...task.blockedByIds);
+    }
+    if (blockedIds.length === 0) continue;
+    const uniqueBlockedIds = Array.from(new Set(blockedIds));
+    const failingDeps = uniqueBlockedIds.filter((id) => result[id] && !result[id].passed);
     if (failingDeps.length > 0 && result[task.id] && result[task.id].passed) {
       result[task.id].passed = false;
       result[task.id].reasons = [`blocked by incomplete tasks: ${failingDeps.join(', ')}`];