roadmapsmith 0.5.0 → 0.6.0

package/bin/cli.js

@@ -1,212 +1,216 @@
-#!/usr/bin/env node
-'use strict';
-
-const fs = require('fs');
-const path = require('path');
-const { parseArgv } = require('../src/utils');
-const { loadConfig, resolveRoadmapFile, resolveAgentsFile, loadPlugins } = require('../src/config');
-const { readTextIfExists, writeText, printDryRunDiff } = require('../src/io');
-const { renderRoadmapTemplate, renderAgentsTemplate } = require('../src/templates');
-const { generateRoadmapDocument } = require('../src/generator');
-const { parseRoadmap } = require('../src/parser');
-const { buildValidationContext, validateTasks, auditValidation } = require('../src/validator');
-const { applySync } = require('../src/sync');
-
-function printHelp() {
-  console.log([
-    'Usage:',
-    '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
-    '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]',
-    '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]',
-    '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]'
-  ].join('\n'));
-}
-
-function isEnabled(value) {
-  if (value === true) return true;
-  if (typeof value !== 'string') return false;
-  const normalized = value.toLowerCase();
-  return normalized === '1' || normalized === 'true' || normalized === 'yes';
-}
-
-function formatResultLine(task, result) {
-  const status = result.passed ? 'PASS' : 'FAIL';
-  const reason = result.reasons.length > 0 ? ` :: ${result.reasons.join('; ')}` : '';
-  return `${status} [${task.id}] ${task.text}${reason}`;
-}
-
-function maybeFilterTasks(tasks, filterValue) {
-  if (!filterValue) return tasks;
-  const normalized = String(filterValue).toLowerCase();
-  return tasks.filter((task) => {
-    return task.id.toLowerCase() === normalized || task.text.toLowerCase().includes(normalized);
-  });
-}
-
-function printAudit(audit) {
-  console.log(`Audit summary: ${audit.checkedWithoutEvidence.length} checked-without-evidence, ${audit.readyButUnchecked.length} ready-but-unchecked.`);
-  if (audit.checkedWithoutEvidence.length > 0) {
-    console.log('Checked without evidence:');
-    audit.checkedWithoutEvidence.forEach((item) => {
-      console.log(`- [${item.task.id}] ${item.task.text}`);
-    });
-  }
-  if (audit.readyButUnchecked.length > 0) {
-    console.log('Ready but unchecked:');
-    audit.readyButUnchecked.forEach((item) => {
-      console.log(`- [${item.task.id}] ${item.task.text}`);
-    });
-  }
-}
-
-async function run() {
-  const parsed = parseArgv(process.argv.slice(2));
-  const command = parsed.command;
-  const flags = parsed.flags;
-
-  if (!command || isEnabled(flags.help) || isEnabled(flags.h)) {
-    printHelp();
-    return;
-  }
-
-  if (command === 'init') {
-    const projectRoot = process.cwd();
-    const config = loadConfig({ projectRoot });
-    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
-    const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
-    const dryRun = isEnabled(flags['dry-run']);
-
-    const roadmapExists = fs.existsSync(roadmapFile);
-    const agentsExists = fs.existsSync(agentsFile);
-
-    if (!roadmapExists) {
-      const roadmap = renderRoadmapTemplate();
-      const result = writeText(roadmapFile, roadmap, { dryRun });
-      if (dryRun && result.changed) {
-        printDryRunDiff(roadmapFile, result.before, result.after);
-      }
-      console.log(`${dryRun ? 'Would create' : 'Created'} ${roadmapFile}`);
-    } else {
-      console.log(`Skipped existing ${roadmapFile}`);
-    }
-
-    if (!agentsExists) {
-      const agents = renderAgentsTemplate({ roadmapPath: path.basename(roadmapFile) });
-      const result = writeText(agentsFile, agents, { dryRun });
-      if (dryRun && result.changed) {
-        printDryRunDiff(agentsFile, result.before, result.after);
-      }
-      console.log(`${dryRun ? 'Would create' : 'Created'} ${agentsFile}`);
-    } else {
-      console.log(`Skipped existing ${agentsFile}`);
-    }
-    return;
-  }
-
-  if (command === 'generate') {
-    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
-    const config = loadConfig({ projectRoot, configPath: flags.config });
-    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
-    const plugins = loadPlugins(projectRoot, config.plugins);
-    const existingContent = readTextIfExists(roadmapFile) || '';
-    const dryRun = isEnabled(flags['dry-run']);
-
-    const document = generateRoadmapDocument({
-      projectRoot,
-      roadmapPath: roadmapFile,
-      existingContent,
-      config,
-      plugins
-    });
-
-    const writeResult = writeText(roadmapFile, document, { dryRun });
-    if (dryRun) {
-      if (writeResult.changed) {
-        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
-      } else {
-        console.log(`No changes for ${roadmapFile}`);
-      }
-    } else {
-      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
-    }
-
-    if (isEnabled(flags.audit)) {
-      const parsedRoadmap = parseRoadmap(document);
-      const validationContext = buildValidationContext(projectRoot, config, plugins);
-      const results = validateTasks(parsedRoadmap.tasks, validationContext, config, plugins);
-      const audit = auditValidation(parsedRoadmap.tasks, results);
-      printAudit(audit);
-    }
-    return;
-  }
-
-  if (command === 'sync') {
-    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
-    const config = loadConfig({ projectRoot, configPath: flags.config });
-    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
-    const content = readTextIfExists(roadmapFile);
-    if (content == null) {
-      throw new Error(`Roadmap not found: ${roadmapFile}`);
-    }
-
-    const parsedRoadmap = parseRoadmap(content);
-    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
-    const results = validateTasks(parsedRoadmap.tasks, validationContext, config, validationContext.plugins);
-    const next = applySync(content, parsedRoadmap.tasks, results);
-    const dryRun = isEnabled(flags['dry-run']);
-    const writeResult = writeText(roadmapFile, next, { dryRun });
-
-    if (dryRun) {
-      if (writeResult.changed) {
-        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
-      } else {
-        console.log(`No changes for ${roadmapFile}`);
-      }
-    } else {
-      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
-    }
-
-    if (isEnabled(flags.audit)) {
-      const audit = auditValidation(parsedRoadmap.tasks, results);
-      printAudit(audit);
-    }
-    return;
-  }
-
-  if (command === 'validate') {
-    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
-    const config = loadConfig({ projectRoot, configPath: flags.config });
-    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
-    const content = readTextIfExists(roadmapFile);
-    if (content == null) {
-      throw new Error(`Roadmap not found: ${roadmapFile}`);
-    }
-
-    const parsedRoadmap = parseRoadmap(content);
-    const tasks = maybeFilterTasks(parsedRoadmap.tasks, flags.task);
-    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
-    const results = validateTasks(tasks, validationContext, config, validationContext.plugins);
-
-    if (isEnabled(flags.json)) {
-      const payload = tasks.map((task) => ({ task, result: results[task.id] }));
-      console.log(JSON.stringify(payload, null, 2));
-    } else {
-      tasks.forEach((task) => {
-        console.log(formatResultLine(task, results[task.id]));
-      });
-    }
-
-    const failed = tasks.some((task) => !results[task.id].passed);
-    if (failed) {
-      process.exitCode = 1;
-    }
-    return;
-  }
-
-  throw new Error(`Unknown command: ${command}`);
-}
-
-run().catch((error) => {
-  console.error(error.message);
-  process.exitCode = 1;
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseArgv } = require('../src/utils');
+const { loadConfig, resolveRoadmapFile, resolveAgentsFile, loadPlugins } = require('../src/config');
+const { readTextIfExists, writeText, printDryRunDiff } = require('../src/io');
+const { renderRoadmapTemplate, renderAgentsTemplate } = require('../src/templates');
+const { generateRoadmapDocument } = require('../src/generator');
+const { parseRoadmap } = require('../src/parser');
+const { buildValidationContext, validateTasks, auditValidation } = require('../src/validator');
+const { applySync } = require('../src/sync');
+
+function printHelp() {
+  console.log([
+    'Usage:',
+    '  roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]',
+    '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit]',
+    '  roadmapsmith sync [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run] [--audit]',
+    '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--json]'
+  ].join('\n'));
+}
+
+function isEnabled(value) {
+  if (value === true) return true;
+  if (typeof value !== 'string') return false;
+  const normalized = value.toLowerCase();
+  return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+
+function formatResultLine(task, result) {
+  const status = result.passed ? 'PASS' : 'FAIL';
+  const reason = result.reasons.length > 0 ? ` :: ${result.reasons.join('; ')}` : '';
+  return `${status} [${task.id}] ${task.text}${reason}`;
+}
+
+function maybeFilterTasks(tasks, filterValue) {
+  if (!filterValue) return tasks;
+  const normalized = String(filterValue).toLowerCase();
+  return tasks.filter((task) => {
+    return task.id.toLowerCase() === normalized || task.text.toLowerCase().includes(normalized);
+  });
+}
+
+function printAudit(audit) {
+  console.log(`Audit summary: ${audit.checkedWithoutEvidence.length} checked-without-evidence, ${audit.readyButUnchecked.length} ready-but-unchecked.`);
+  if (audit.checkedWithoutEvidence.length > 0) {
+    console.log('Checked without evidence:');
+    audit.checkedWithoutEvidence.forEach((item) => {
+      console.log(`- [${item.task.id}] ${item.task.text}`);
+    });
+  }
+  if (audit.readyButUnchecked.length > 0) {
+    console.log('Ready but unchecked:');
+    audit.readyButUnchecked.forEach((item) => {
+      console.log(`- [${item.task.id}] ${item.task.text}`);
+    });
+  }
+}
+
+async function run() {
+  const parsed = parseArgv(process.argv.slice(2));
+  const command = parsed.command;
+  const flags = parsed.flags;
+
+  if (!command || isEnabled(flags.help) || isEnabled(flags.h)) {
+    printHelp();
+    return;
+  }
+
+  if (command === 'init') {
+    const projectRoot = process.cwd();
+    const config = loadConfig({ projectRoot });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
+    const dryRun = isEnabled(flags['dry-run']);
+
+    const roadmapExists = fs.existsSync(roadmapFile);
+    const agentsExists = fs.existsSync(agentsFile);
+
+    if (!roadmapExists) {
+      const roadmap = renderRoadmapTemplate();
+      const result = writeText(roadmapFile, roadmap, { dryRun });
+      if (dryRun && result.changed) {
+        printDryRunDiff(roadmapFile, result.before, result.after);
+      }
+      console.log(`${dryRun ? 'Would create' : 'Created'} ${roadmapFile}`);
+    } else {
+      console.log(`Skipped existing ${roadmapFile}`);
+    }
+
+    if (!agentsExists) {
+      const agents = renderAgentsTemplate({ roadmapPath: path.basename(roadmapFile) });
+      const result = writeText(agentsFile, agents, { dryRun });
+      if (dryRun && result.changed) {
+        printDryRunDiff(agentsFile, result.before, result.after);
+      }
+      console.log(`${dryRun ? 'Would create' : 'Created'} ${agentsFile}`);
+    } else {
+      console.log(`Skipped existing ${agentsFile}`);
+    }
+    return;
+  }
+
+  if (command === 'generate') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const plugins = loadPlugins(projectRoot, config.plugins);
+    const existingContent = readTextIfExists(roadmapFile) || '';
+    const dryRun = isEnabled(flags['dry-run']);
+
+    const document = generateRoadmapDocument({
+      projectRoot,
+      roadmapPath: roadmapFile,
+      existingContent,
+      config,
+      plugins
+    });
+
+    const writeResult = writeText(roadmapFile, document, { dryRun });
+    if (dryRun) {
+      if (writeResult.changed) {
+        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
+      } else {
+        console.log(`No changes for ${roadmapFile}`);
+      }
+    } else {
+      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
+    }
+
+    if (isEnabled(flags.audit)) {
+      const parsedRoadmap = parseRoadmap(document);
+      const validationContext = buildValidationContext(projectRoot, config, plugins);
+      const results = validateTasks(parsedRoadmap.tasks, validationContext, config, plugins);
+      const audit = auditValidation(parsedRoadmap.tasks, results);
+      printAudit(audit);
+    }
+    return;
+  }
+
+  if (command === 'sync') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const content = readTextIfExists(roadmapFile);
+    if (content == null) {
+      throw new Error(`Roadmap not found: ${roadmapFile}`);
+    }
+
+    const parsedRoadmap = parseRoadmap(content);
+    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+    const results = validateTasks(parsedRoadmap.tasks, validationContext, config, validationContext.plugins);
+    const next = applySync(content, parsedRoadmap.tasks, results);
+    const dryRun = isEnabled(flags['dry-run']);
+    const writeResult = writeText(roadmapFile, next, { dryRun });
+
+    if (dryRun) {
+      if (writeResult.changed) {
+        printDryRunDiff(roadmapFile, writeResult.before, writeResult.after);
+      } else {
+        console.log(`No changes for ${roadmapFile}`);
+      }
+    } else {
+      console.log(writeResult.changed ? `Updated ${roadmapFile}` : `No changes for ${roadmapFile}`);
+    }
+
+    if (isEnabled(flags.audit)) {
+      const audit = auditValidation(parsedRoadmap.tasks, results);
+      printAudit(audit);
+    }
+    return;
+  }
+
+  if (command === 'validate') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
+    const content = readTextIfExists(roadmapFile);
+    if (content == null) {
+      throw new Error(`Roadmap not found: ${roadmapFile}`);
+    }
+
+    const parsedRoadmap = parseRoadmap(content);
+    const tasks = maybeFilterTasks(parsedRoadmap.tasks, flags.task);
+    const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+    const results = validateTasks(tasks, validationContext, config, validationContext.plugins);
+
+    const CONFIDENCE_RANK = { low: 0, medium: 1, high: 2 };
+    const minRank = CONFIDENCE_RANK[config.validation && config.validation.minimumConfidence] ?? 0;
+    const visibleTasks = tasks.filter((task) => (CONFIDENCE_RANK[results[task.id].confidence] ?? 0) >= minRank);
+
+    if (isEnabled(flags.json)) {
+      const payload = visibleTasks.map((task) => ({ task, result: results[task.id] }));
+      console.log(JSON.stringify(payload, null, 2));
+    } else {
+      visibleTasks.forEach((task) => {
+        console.log(formatResultLine(task, results[task.id]));
+      });
+    }
+
+    const failed = visibleTasks.some((task) => !results[task.id].passed);
+    if (failed) {
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+run().catch((error) => {
+  console.error(error.message);
+  process.exitCode = 1;
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Generate, sync, and validate deterministic project roadmaps for agent-driven execution.",
   "main": "src/index.js",
   "bin": {
@@ -12,10 +12,18 @@
   },
   "keywords": [
     "roadmap",
-    "skills",
+    "planning",
     "agent",
     "cli",
-    "planning"
+    "validation",
+    "sync",
+    "task-tracking",
+    "evidence-based",
+    "deterministic",
+    "monorepo",
+    "claude-code",
+    "ai-agent",
+    "project-management"
   ],
   "author": "PapiScholz",
   "license": "MIT",

package/src/config.js

@@ -24,6 +24,9 @@ const DEFAULT_CONFIG = {
     steps: [],
     phases: []
   },
+  validation: {
+    minimumConfidence: 'low'
+  },
   milestones: [
     { version: 'v0.1', goal: 'Foundation baseline complete' },
     { version: 'v0.2', goal: 'Core feature coverage stabilized' },
@@ -73,6 +76,10 @@ function mergeConfig(userConfig) {
       phases: (userConfig && userConfig.product && Array.isArray(userConfig.product.phases))
         ? userConfig.product.phases
         : DEFAULT_CONFIG.product.phases
+    },
+    validation: {
+      ...DEFAULT_CONFIG.validation,
+      ...((userConfig && userConfig.validation) || {})
     }
   };
 }

package/src/renderer/professional.js

@@ -176,8 +176,10 @@ function renderSection5Milestones(model, lines) {
       lines.push('**What Must Be Stable:**');
       lines.push('');
       for (const item of milestone.mustBeStable) {
-        const id = `prof-ms-${msSlug}-stable-${slugify(item)}`;
-        lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P1]\` ${item} <!-- rs:task=${id} -->`);
+        const text = typeof item === 'string' ? item : item.text;
+        const note = typeof item === 'object' && item.note ? ` — _${item.note}_` : '';
+        const id = `prof-ms-${msSlug}-stable-${slugify(text)}`;
+        lines.push(`- [${checkedState(model, id) ? 'x' : ' '}] \`[P1]\` ${text}${note} <!-- rs:task=${id} -->`);
       }
       lines.push('');
     }

package/src/validator/index.js

@@ -1,420 +1,425 @@
-'use strict';
-
-const path = require('path');
-const fs = require('fs');
-const { walkFiles, detectTestFrameworks } = require('../io');
-const { collectPluginContributions } = require('../config');
-const { escapeRegExp, tokenize } = require('../utils');
-
-const CODE_EXTENSIONS = new Set([
-  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb', '.php', '.cs'
-]);
-
-const DOC_HINTS = ['readme', 'changelog', 'docs', 'documentation', 'spec', 'diagram', 'runbook'];
-const CODE_HINTS = ['implement', 'add', 'create', 'build', 'refactor', 'fix', 'module', 'function', 'api', 'endpoint', 'command'];
-const GENERIC_TASK_TOKENS = new Set([
-  'implement',
-  'implementation',
-  'module',
-  'function',
-  'class',
-  'method',
-  'command',
-  'create',
-  'add',
-  'build',
-  'refactor',
-  'fix',
-  'test',
-  'tests'
-]);
-
-function readFileIndex(projectRoot, files) {
-  const index = [];
-  for (const relativePath of files) {
-    const absolutePath = path.resolve(projectRoot, relativePath);
-    const ext = path.extname(relativePath).toLowerCase();
-    let content = '';
-    try {
-      const buffer = fs.readFileSync(absolutePath);
-      if (buffer.length > 512 * 1024) {
-        continue;
-      }
-      content = buffer.toString('utf8');
-    } catch {
-      continue;
-    }
-
-    index.push({
-      relativePath,
-      absolutePath,
-      ext,
-      content,
-      isTestFile: /(^|\/)(__tests__|tests)\//.test(relativePath) || /\.test\.|\.spec\.|_test\.go$/.test(relativePath)
-    });
-  }
-  return index;
-}
-
-const KNOWN_PATH_ROOTS = [
-  'src/', 'lib/', 'bin/', 'test/', 'tests/', 'docs/', 'scripts/',
-  'packages/', 'apps/', 'tools/', '.github/', 'roadmap-skill/'
-];
-
-function hasFileExtension(token) {
-  const lastSegment = token.replace(/\\/g, '/').split('/').pop() || '';
-  return /\.[A-Za-z0-9]{1,10}$/.test(lastSegment);
-}
-
-function isLikelyPath(token) {
-  if (/^\.{1,2}\/|^\//.test(token)) return true;
-  if (hasFileExtension(token)) return true;
-  if (KNOWN_PATH_ROOTS.some((root) => token.startsWith(root))) return true;
-  if ((token.match(/\//g) || []).length >= 2) return true;
-  return false;
-}
-
-function extractExplicitPaths(text) {
-  const results = new Set();
-  const quoted = String(text).match(/`([^`]+)`/g) || [];
-  for (const token of quoted) {
-    const clean = token.slice(1, -1);
-    if (clean.includes('/') || clean.includes('\\') || clean.includes('.')) {
-      results.add(clean);
-    }
-  }
-
-  const pathTokens = String(text).match(/([A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+)/g) || [];
-  for (const raw of pathTokens) {
-    const token = raw.replace(/[.,;:!?)]+$/, '');
-    if (isLikelyPath(token)) results.add(token);
-  }
-
-  return Array.from(results).sort((left, right) => left.localeCompare(right));
-}
-
-function extractSymbolHints(text) {
-  const symbols = new Set();
-  const patterns = [
-    /(?:function|class|method|command)\s+([A-Za-z_][A-Za-z0-9_]*)/gi,
-    /(?:function|module|class|command|method)\s+`([A-Za-z_][A-Za-z0-9_-]*)`/gi,
-    /`([A-Za-z_][A-Za-z0-9_-]*)`\s+(?:function|module|class|command|method)/gi
-  ];
-
-  for (const pattern of patterns) {
-    let match = pattern.exec(text);
-    while (match) {
-      symbols.add(match[1]);
-      match = pattern.exec(text);
-    }
-  }
-
-  return Array.from(symbols).sort((left, right) => left.localeCompare(right));
-}
-
-function isCodeTask(taskText) {
-  const normalized = String(taskText).toLowerCase();
-  return CODE_HINTS.some((hint) => normalized.includes(hint));
-}
-
-function isDocTask(taskText) {
-  const normalized = String(taskText).toLowerCase();
-  return DOC_HINTS.some((hint) => normalized.includes(hint));
-}
-
-function findFilesByPathHints(pathHints, fileIndex) {
-  const matches = [];
-  for (const hint of pathHints) {
-    const normalizedHint = hint.replace(/\\/g, '/');
-    const direct = fileIndex.find((file) => file.relativePath === normalizedHint);
-    if (direct) {
-      matches.push(direct.relativePath);
-      continue;
-    }
-
-    for (const file of fileIndex) {
-      if (file.relativePath.endsWith(normalizedHint)) {
-        matches.push(file.relativePath);
-      }
-    }
-  }
-  return Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right));
-}
-
-function findFilesBySymbols(symbolHints, fileIndex) {
-  const matches = new Set();
-  for (const symbol of symbolHints) {
-    const regex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`, 'i');
-    for (const file of fileIndex) {
-      if (!CODE_EXTENSIONS.has(file.ext)) {
-        continue;
-      }
-      if (regex.test(file.content)) {
-        matches.add(file.relativePath);
-      }
-    }
-  }
-  return Array.from(matches).sort((left, right) => left.localeCompare(right));
-}
-
-function findCodeEvidence(taskText, fileIndex) {
-  const tokens = tokenize(taskText)
-    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
-    .slice(0, 8);
-  if (tokens.length === 0) {
-    return [];
-  }
-
-  const matches = [];
-  for (const file of fileIndex) {
-    if (!CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
-      continue;
-    }
-
-    let score = 0;
-    const lowered = file.content.toLowerCase();
-    for (const token of tokens) {
-      if (token.length < 3) {
-        continue;
-      }
-      if (lowered.includes(token)) {
-        score += 1;
-      }
-    }
-
-    const threshold = tokens.length === 1 ? 1 : 2;
-    if (score >= threshold) {
-      matches.push(file.relativePath);
-    }
-  }
-
-  return matches.slice(0, 20);
-}
-
-function findTestEvidence(taskText, fileIndex) {
-  const tokens = tokenize(taskText)
-    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
-    .slice(0, 8);
-  const matches = [];
-
-  for (const file of fileIndex) {
-    if (!file.isTestFile) {
-      continue;
-    }
-    const lowered = file.content.toLowerCase();
-    const hasMatch = tokens.some((token) => lowered.includes(token));
-    if (hasMatch) {
-      matches.push(file.relativePath);
-    }
-  }
-
-  return matches.slice(0, 20);
-}
-
-function findArtifactEvidence(taskText, fileIndex) {
-  const normalized = String(taskText).toLowerCase();
-  const matches = [];
-
-  if (!isDocTask(taskText) && !normalized.includes('artifact') && !normalized.includes('release')) {
-    return matches;
-  }
-
-  const artifactPatterns = [
-    /^README\.md$/i,
-    /^CHANGELOG\.md$/i,
-    /^docs\//i,
-    /^artifacts\//i,
-    /^dist\//i,
-    /^build\//i
-  ];
-
-  for (const file of fileIndex) {
-    if (artifactPatterns.some((pattern) => pattern.test(file.relativePath))) {
-      matches.push(file.relativePath);
-    }
-  }
-
-  return matches.slice(0, 20);
-}
-
-function evaluateRule(rule, task, context) {
-  if (!rule) {
-    return { passed: true, reasons: [], evidence: {} };
-  }
-
-  if (rule.when) {
-    const regexp = new RegExp(rule.when, 'i');
-    if (!regexp.test(task.text)) {
-      return { passed: true, reasons: [], evidence: {} };
-    }
-  }
-
-  if (typeof rule.check === 'function') {
-    const custom = rule.check(task, context);
-    if (!custom) {
-      return { passed: true, reasons: [], evidence: {} };
-    }
-    return {
-      passed: custom.passed !== false,
-      reasons: Array.isArray(custom.reasons) ? custom.reasons : [],
-      evidence: custom.evidence || {}
-    };
-  }
-
-  const reasons = [];
-  const evidence = {};
-
-  if (rule.type === 'file-exists' && rule.path) {
-    const hit = context.fileIndex.find((file) => file.relativePath === rule.path || file.relativePath.endsWith(rule.path));
-    if (!hit) {
-      reasons.push(rule.message || `missing file: ${rule.path}`);
-    } else {
-      evidence.file = hit.relativePath;
-    }
-  }
-
-  if (rule.type === 'symbol' && rule.pattern) {
-    const regex = new RegExp(rule.pattern, 'i');
-    const hit = context.fileIndex.find((file) => regex.test(file.content));
-    if (!hit) {
-      reasons.push(rule.message || `missing symbol pattern: ${rule.pattern}`);
-    } else {
-      evidence.symbol = hit.relativePath;
-    }
-  }
-
-  if (rule.type === 'artifact' && rule.path) {
-    const hit = context.fileIndex.find((file) => file.relativePath.startsWith(rule.path) || file.relativePath === rule.path);
-    if (!hit) {
-      reasons.push(rule.message || `missing artifact: ${rule.path}`);
-    } else {
-      evidence.artifact = hit.relativePath;
-    }
-  }
-
-  if (rule.type === 'test' && context.testFrameworks.length === 0) {
-    reasons.push(rule.message || 'test framework not detected');
-  }
-
-  return {
-    passed: reasons.length === 0,
-    reasons,
-    evidence
-  };
-}
-
-function buildValidationContext(projectRoot, config, plugins) {
-  const files = walkFiles(projectRoot);
-  const fileIndex = readFileIndex(projectRoot, files);
-  const testFrameworks = detectTestFrameworks(projectRoot, files);
-
-  return {
-    projectRoot,
-    config,
-    plugins,
-    files,
-    fileIndex,
-    testFrameworks
-  };
-}
-
-function validateTask(task, context, config, plugins) {
-  const pathHints = extractExplicitPaths(task.text);
-  const symbolHints = extractSymbolHints(task.text);
-
-  const filesFromPaths = findFilesByPathHints(pathHints, context.fileIndex);
-  const filesFromSymbols = findFilesBySymbols(symbolHints, context.fileIndex);
-  const filesFromCode = findCodeEvidence(task.text, context.fileIndex);
-  const filesFromTests = findTestEvidence(task.text, context.fileIndex);
-  const filesFromArtifacts = findArtifactEvidence(task.text, context.fileIndex);
-
-  const evidence = {
-    code: filesFromCode.length > 0 || filesFromSymbols.length > 0,
-    test: filesFromTests.length > 0,
-    artifact: filesFromArtifacts.length > 0,
-    files: filesFromPaths,
-    symbols: filesFromSymbols,
-    codeFiles: filesFromCode,
-    testFiles: filesFromTests,
-    artifactFiles: filesFromArtifacts
-  };
-
-  const reasons = [];
-  if (pathHints.length > 0 && filesFromPaths.length === 0) {
-    reasons.push(`missing referenced file(s): ${pathHints.join(', ')}`);
-  }
-  if (symbolHints.length > 0 && filesFromSymbols.length === 0) {
-    reasons.push(`missing symbol(s): ${symbolHints.join(', ')}`);
-  }
-
-  const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
-  if (!hasEvidence) {
-    reasons.push('no code, test, or artifact evidence found');
-  }
-
-  const requiresTest = context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
-  if (requiresTest && !evidence.test) {
-    reasons.push('missing test evidence');
-  }
-
-  const configuredRules = Array.isArray(config.validators) ? config.validators : [];
-  const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
-  for (const rule of [...configuredRules, ...pluginRules]) {
-    const ruleResult = evaluateRule(rule, task, context);
-    if (!ruleResult.passed) {
-      reasons.push(...ruleResult.reasons);
-    }
-  }
-
-  const uniqueReasons = Array.from(new Set(reasons));
-
-  return {
-    taskId: task.id,
-    passed: uniqueReasons.length === 0,
-    reasons: uniqueReasons,
-    evidence,
-    requiresTest,
-    hasEvidence,
-    attempted: hasEvidence || pathHints.length > 0 || symbolHints.length > 0
-  };
-}
-
-function validateTasks(tasks, context, config, plugins) {
-  const result = {};
-  for (const task of tasks) {
-    result[task.id] = validateTask(task, context, config, plugins);
-  }
-  return result;
-}
-
-function auditValidation(tasks, results) {
-  const checkedWithoutEvidence = [];
-  const readyButUnchecked = [];
-
-  for (const task of tasks) {
-    const result = results[task.id];
-    if (!result) {
-      continue;
-    }
-
-    if (task.checked && !result.passed) {
-      checkedWithoutEvidence.push({ task, result });
-    }
-
-    if (!task.checked && result.passed) {
-      readyButUnchecked.push({ task, result });
-    }
-  }
-
-  return {
-    checkedWithoutEvidence,
-    readyButUnchecked
-  };
-}
-
-module.exports = {
-  auditValidation,
-  buildValidationContext,
-  validateTask,
-  validateTasks
-};
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+const { walkFiles, detectTestFrameworks } = require('../io');
+const { collectPluginContributions } = require('../config');
+const { escapeRegExp, tokenize } = require('../utils');
+
+const CODE_EXTENSIONS = new Set([
+  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.rb', '.php', '.cs'
+]);
+
+const DOC_HINTS = ['readme', 'changelog', 'docs', 'documentation', 'spec', 'diagram', 'runbook'];
+const CODE_HINTS = ['implement', 'add', 'create', 'build', 'refactor', 'fix', 'module', 'function', 'api', 'endpoint', 'command'];
+const GENERIC_TASK_TOKENS = new Set([
+  'implement',
+  'implementation',
+  'module',
+  'function',
+  'class',
+  'method',
+  'command',
+  'create',
+  'add',
+  'build',
+  'refactor',
+  'fix',
+  'test',
+  'tests'
+]);
+
+function readFileIndex(projectRoot, files) {
+  const index = [];
+  for (const relativePath of files) {
+    const absolutePath = path.resolve(projectRoot, relativePath);
+    const ext = path.extname(relativePath).toLowerCase();
+    let content = '';
+    try {
+      const buffer = fs.readFileSync(absolutePath);
+      if (buffer.length > 512 * 1024) {
+        continue;
+      }
+      content = buffer.toString('utf8');
+    } catch {
+      continue;
+    }
+
+    index.push({
+      relativePath,
+      absolutePath,
+      ext,
+      content,
+      isTestFile: /(^|\/)(__tests__|tests)\//.test(relativePath) || /\.test\.|\.spec\.|_test\.go$/.test(relativePath)
+    });
+  }
+  return index;
+}
+
+const KNOWN_PATH_ROOTS = [
+  'src/', 'lib/', 'bin/', 'test/', 'tests/', 'docs/', 'scripts/',
+  'packages/', 'apps/', 'tools/', '.github/', 'roadmap-skill/'
+];
+
+function hasFileExtension(token) {
+  const lastSegment = token.replace(/\\/g, '/').split('/').pop() || '';
+  return /\.[A-Za-z0-9]{1,10}$/.test(lastSegment);
+}
+
+function isLikelyPath(token) {
+  if (/^\.{1,2}\/|^\//.test(token)) return true;
+  if (hasFileExtension(token)) return true;
+  if (KNOWN_PATH_ROOTS.some((root) => token.startsWith(root))) return true;
+  if ((token.match(/\//g) || []).length >= 2) return true;
+  return false;
+}
+
+function extractExplicitPaths(text) {
+  const results = new Set();
+  const quoted = String(text).match(/`([^`]+)`/g) || [];
+  for (const token of quoted) {
+    const clean = token.slice(1, -1);
+    if (clean.includes('/') || clean.includes('\\') || clean.includes('.')) {
+      results.add(clean);
+    }
+  }
+
+  const pathTokens = String(text).match(/([A-Za-z0-9_.-]+\/[A-Za-z0-9_./-]+)/g) || [];
+  for (const raw of pathTokens) {
+    const token = raw.replace(/[.,;:!?)]+$/, '');
+    if (isLikelyPath(token)) results.add(token);
+  }
+
+  return Array.from(results).sort((left, right) => left.localeCompare(right));
+}
+
+function extractSymbolHints(text) {
+  const symbols = new Set();
+  const patterns = [
+    /(?:function|class|method|command)\s+([A-Za-z_][A-Za-z0-9_]*)/gi,
+    /(?:function|module|class|command|method)\s+`([A-Za-z_][A-Za-z0-9_-]*)`/gi,
+    /`([A-Za-z_][A-Za-z0-9_-]*)`\s+(?:function|module|class|command|method)/gi
+  ];
+
+  for (const pattern of patterns) {
+    let match = pattern.exec(text);
+    while (match) {
+      symbols.add(match[1]);
+      match = pattern.exec(text);
+    }
+  }
+
+  return Array.from(symbols).sort((left, right) => left.localeCompare(right));
+}
+
+function isCodeTask(taskText) {
+  const normalized = String(taskText).toLowerCase();
+  return CODE_HINTS.some((hint) => normalized.includes(hint));
+}
+
+function isDocTask(taskText) {
+  const normalized = String(taskText).toLowerCase();
+  return DOC_HINTS.some((hint) => normalized.includes(hint));
+}
+
+function findFilesByPathHints(pathHints, fileIndex) {
+  const matches = [];
+  for (const hint of pathHints) {
+    const normalizedHint = hint.replace(/\\/g, '/');
+    const direct = fileIndex.find((file) => file.relativePath === normalizedHint);
+    if (direct) {
+      matches.push(direct.relativePath);
+      continue;
+    }
+
+    for (const file of fileIndex) {
+      if (file.relativePath.endsWith(normalizedHint)) {
+        matches.push(file.relativePath);
+      }
+    }
+  }
+  return Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right));
+}
+
+function findFilesBySymbols(symbolHints, fileIndex) {
+  const matches = new Set();
+  for (const symbol of symbolHints) {
+    const regex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`, 'i');
+    for (const file of fileIndex) {
+      if (!CODE_EXTENSIONS.has(file.ext)) {
+        continue;
+      }
+      if (regex.test(file.content)) {
+        matches.add(file.relativePath);
+      }
+    }
+  }
+  return Array.from(matches).sort((left, right) => left.localeCompare(right));
+}
+
+function findCodeEvidence(taskText, fileIndex) {
+  const tokens = tokenize(taskText)
+    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
+    .slice(0, 8);
+  if (tokens.length === 0) {
+    return [];
+  }
+
+  const matches = [];
+  for (const file of fileIndex) {
+    if (!CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
+      continue;
+    }
+
+    let score = 0;
+    const lowered = file.content.toLowerCase();
+    for (const token of tokens) {
+      if (token.length < 3) {
+        continue;
+      }
+      if (lowered.includes(token)) {
+        score += 1;
+      }
+    }
+
+    const threshold = tokens.length === 1 ? 1 : 2;
+    if (score >= threshold) {
+      matches.push(file.relativePath);
+    }
+  }
+
+  return matches.slice(0, 20);
+}
+
+function findTestEvidence(taskText, fileIndex) {
+  const tokens = tokenize(taskText)
+    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
+    .slice(0, 8);
+  const matches = [];
+
+  for (const file of fileIndex) {
+    if (!file.isTestFile) {
+      continue;
+    }
+    const lowered = file.content.toLowerCase();
+    const hasMatch = tokens.some((token) => lowered.includes(token));
+    if (hasMatch) {
+      matches.push(file.relativePath);
+    }
+  }
+
+  return matches.slice(0, 20);
+}
+
+function findArtifactEvidence(taskText, fileIndex) {
+  const normalized = String(taskText).toLowerCase();
+  const matches = [];
+
+  if (!isDocTask(taskText) && !normalized.includes('artifact') && !normalized.includes('release')) {
+    return matches;
+  }
+
+  const artifactPatterns = [
+    /^README\.md$/i,
+    /^CHANGELOG\.md$/i,
+    /^docs\//i,
+    /^artifacts\//i,
+    /^dist\//i,
+    /^build\//i
+  ];
+
+  for (const file of fileIndex) {
+    if (artifactPatterns.some((pattern) => pattern.test(file.relativePath))) {
+      matches.push(file.relativePath);
+    }
+  }
+
+  return matches.slice(0, 20);
+}
+
+function evaluateRule(rule, task, context) {
+  if (!rule) {
+    return { passed: true, reasons: [], evidence: {} };
+  }
+
+  if (rule.when) {
+    const regexp = new RegExp(rule.when, 'i');
+    if (!regexp.test(task.text)) {
+      return { passed: true, reasons: [], evidence: {} };
+    }
+  }
+
+  if (typeof rule.check === 'function') {
+    const custom = rule.check(task, context);
+    if (!custom) {
+      return { passed: true, reasons: [], evidence: {} };
+    }
+    return {
+      passed: custom.passed !== false,
+      reasons: Array.isArray(custom.reasons) ? custom.reasons : [],
+      evidence: custom.evidence || {}
+    };
+  }
+
+  const reasons = [];
+  const evidence = {};
+
+  if (rule.type === 'file-exists' && rule.path) {
+    const hit = context.fileIndex.find((file) => file.relativePath === rule.path || file.relativePath.endsWith(rule.path));
+    if (!hit) {
+      reasons.push(rule.message || `missing file: ${rule.path}`);
+    } else {
+      evidence.file = hit.relativePath;
+    }
+  }
+
+  if (rule.type === 'symbol' && rule.pattern) {
+    const regex = new RegExp(rule.pattern, 'i');
+    const hit = context.fileIndex.find((file) => regex.test(file.content));
+    if (!hit) {
+      reasons.push(rule.message || `missing symbol pattern: ${rule.pattern}`);
+    } else {
+      evidence.symbol = hit.relativePath;
+    }
+  }
+
+  if (rule.type === 'artifact' && rule.path) {
+    const hit = context.fileIndex.find((file) => file.relativePath.startsWith(rule.path) || file.relativePath === rule.path);
+    if (!hit) {
+      reasons.push(rule.message || `missing artifact: ${rule.path}`);
+    } else {
+      evidence.artifact = hit.relativePath;
+    }
+  }
+
+  if (rule.type === 'test' && context.testFrameworks.length === 0) {
+    reasons.push(rule.message || 'test framework not detected');
+  }
+
+  return {
+    passed: reasons.length === 0,
+    reasons,
+    evidence
+  };
+}
+
+function buildValidationContext(projectRoot, config, plugins) {
+  const files = walkFiles(projectRoot);
+  const fileIndex = readFileIndex(projectRoot, files);
+  const testFrameworks = detectTestFrameworks(projectRoot, files);
+
+  return {
+    projectRoot,
+    config,
+    plugins,
+    files,
+    fileIndex,
+    testFrameworks
+  };
+}
+
+function validateTask(task, context, config, plugins) {
+  const pathHints = extractExplicitPaths(task.text);
+  const symbolHints = extractSymbolHints(task.text);
+
+  const filesFromPaths = findFilesByPathHints(pathHints, context.fileIndex);
+  const filesFromSymbols = findFilesBySymbols(symbolHints, context.fileIndex);
+  const filesFromCode = findCodeEvidence(task.text, context.fileIndex);
+  const filesFromTests = findTestEvidence(task.text, context.fileIndex);
+  const filesFromArtifacts = findArtifactEvidence(task.text, context.fileIndex);
+
+  const evidence = {
+    code: filesFromCode.length > 0 || filesFromSymbols.length > 0,
+    test: filesFromTests.length > 0,
+    artifact: filesFromArtifacts.length > 0,
+    files: filesFromPaths,
+    symbols: filesFromSymbols,
+    codeFiles: filesFromCode,
+    testFiles: filesFromTests,
+    artifactFiles: filesFromArtifacts
+  };
+
+  const reasons = [];
+  if (pathHints.length > 0 && filesFromPaths.length === 0) {
+    reasons.push(`missing referenced file(s): ${pathHints.join(', ')}`);
+  }
+  if (symbolHints.length > 0 && filesFromSymbols.length === 0) {
+    reasons.push(`missing symbol(s): ${symbolHints.join(', ')}`);
+  }
+
+  const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
+  if (!hasEvidence) {
+    reasons.push('no code, test, or artifact evidence found');
+  }
+
+  const requiresTest = context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
+  if (requiresTest && !evidence.test) {
+    reasons.push('missing test evidence');
+  }
+
+  const configuredRules = Array.isArray(config.validators) ? config.validators : [];
+  const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
+  for (const rule of [...configuredRules, ...pluginRules]) {
+    const ruleResult = evaluateRule(rule, task, context);
+    if (!ruleResult.passed) {
+      reasons.push(...ruleResult.reasons);
+    }
+  }
+
+  const uniqueReasons = Array.from(new Set(reasons));
+  const attempted = hasEvidence || pathHints.length > 0 || symbolHints.length > 0;
+
+  const evidenceCount = [evidence.code, evidence.test, evidence.artifact].filter(Boolean).length;
+  const confidence = evidenceCount >= 2 ? 'high' : evidenceCount === 1 ? 'medium' : attempted ? 'medium' : 'low';
+
+  return {
+    taskId: task.id,
+    passed: uniqueReasons.length === 0,
+    confidence,
+    reasons: uniqueReasons,
+    evidence,
+    requiresTest,
+    hasEvidence,
+    attempted
+  };
+}
+
+function validateTasks(tasks, context, config, plugins) {
+  const result = {};
+  for (const task of tasks) {
+    result[task.id] = validateTask(task, context, config, plugins);
+  }
+  return result;
+}
+
+function auditValidation(tasks, results) {
+  const checkedWithoutEvidence = [];
+  const readyButUnchecked = [];
+
+  for (const task of tasks) {
+    const result = results[task.id];
+    if (!result) {
+      continue;
+    }
+
+    if (task.checked && !result.passed) {
+      checkedWithoutEvidence.push({ task, result });
+    }
+
+    if (!task.checked && result.passed) {
+      readyButUnchecked.push({ task, result });
+    }
+  }
+
+  return {
+    checkedWithoutEvidence,
+    readyButUnchecked
+  };
+}
+
+module.exports = {
+  auditValidation,
+  buildValidationContext,
+  validateTask,
+  validateTasks
+};