roadmapsmith 0.7.0 → 0.8.0

package/package.json

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

package/src/classifier/index.js

@@ -0,0 +1,134 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const WEB_DIRS = ['app/', 'pages/', 'components/', 'src/app/', 'src/pages/', 'src/components/'];
+const ASSET_DIRS = ['public/', 'assets/', 'static/'];
+const WEB_CONFIGS = [
+  'next.config.js', 'next.config.ts', 'next.config.mjs',
+  'vite.config.js', 'vite.config.ts',
+  'astro.config.mjs', 'astro.config.ts'
+];
+const STYLE_CONFIGS = ['tailwind.config.js', 'tailwind.config.ts', 'tailwind.config.cjs'];
+const WEB_DEPS = new Set(['next', 'react', 'vue', 'svelte', 'astro', 'vite', 'nuxt', 'gatsby', 'remix', '@remix-run/react']);
+const LANDING_ROUTE_RE = /(?:^|\/)(?:contact|services|about|pricing|hero|cta|landing)(?:\/|\.)/i;
+
+function readPackageDeps(projectRoot) {
+  if (!projectRoot) return [];
+  try {
+    const raw = fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8');
+    const pkg = JSON.parse(raw);
+    return Object.keys({ ...pkg.dependencies, ...pkg.devDependencies });
+  } catch {
+    return [];
+  }
+}
+
+function hasDir(files, prefix) {
+  return files.some((f) => f.startsWith(prefix));
+}
+
+function hasFilename(files, name) {
+  return files.some((f) => f === name || f.endsWith('/' + name));
+}
+
+function hasWorkspaces(projectRoot) {
+  if (!projectRoot) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
+    return Array.isArray(pkg.workspaces) && pkg.workspaces.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+function classifyProject({ projectRoot, files }) {
+  const signals = [];
+
+  if (hasWorkspaces(projectRoot)) {
+    signals.push('package.json workspaces field');
+    return { type: 'monorepo', confidence: 'high', signals };
+  }
+
+  const hasPy = hasFilename(files, 'pyproject.toml') || hasFilename(files, 'setup.py');
+  if (hasPy && !files.some((f) => /\.[jt]sx?$/.test(f))) {
+    signals.push('pyproject.toml / setup.py, no JS files');
+    return { type: 'python-package', confidence: 'high', signals };
+  }
+
+  let webScore = 0;
+  let landingScore = 0;
+  const deps = readPackageDeps(projectRoot);
+
+  for (const dep of deps) {
+    if (WEB_DEPS.has(dep)) {
+      webScore += 2;
+      signals.push(`dependency: ${dep}`);
+    }
+  }
+
+  for (const dir of WEB_DIRS) {
+    if (hasDir(files, dir)) {
+      webScore += 2;
+      signals.push(`directory: ${dir.replace(/\/$/, '')}`);
+    }
+  }
+
+  for (const dir of ASSET_DIRS) {
+    if (hasDir(files, dir)) {
+      webScore += 1;
+      signals.push(`directory: ${dir.replace(/\/$/, '')}`);
+    }
+  }
+
+  for (const cfg of WEB_CONFIGS) {
+    if (hasFilename(files, cfg)) {
+      webScore += 3;
+      signals.push(`config: ${cfg}`);
+    }
+  }
+
+  for (const cfg of STYLE_CONFIGS) {
+    if (hasFilename(files, cfg)) {
+      webScore += 1;
+      signals.push(`config: ${cfg}`);
+    }
+  }
+
+  if (files.some((f) => /\.css$/.test(f))) {
+    webScore += 1;
+    signals.push('CSS files present');
+  }
+
+  const landingRoutes = files.filter((f) => LANDING_ROUTE_RE.test(f));
+  if (landingRoutes.length > 0) {
+    landingScore += landingRoutes.length * 2;
+    signals.push(`landing/service routes: ${landingRoutes.length}`);
+  }
+
+  if (hasFilename(files, 'favicon.ico') || hasFilename(files, 'logo.png') || hasFilename(files, 'logo.svg')) {
+    landingScore += 1;
+    signals.push('branding asset in public/');
+  }
+
+  if (webScore === 0 && (files.some((f) => f.startsWith('bin/')) || hasFilename(files, 'cli.js'))) {
+    signals.push('bin/ directory or cli.js');
+    return { type: 'cli-tool', confidence: 'medium', signals };
+  }
+
+  if (webScore === 0 && hasFilename(files, 'package.json')) {
+    signals.push('package.json, no web signals');
+    return { type: 'npm-package', confidence: 'low', signals };
+  }
+
+  if (webScore >= 3) {
+    const type = landingScore >= 3 ? 'landing-site' : 'frontend-web';
+    const confidence = webScore >= 7 ? 'high' : 'medium';
+    return { type, confidence, signals };
+  }
+
+  return { type: 'unknown-generic', confidence: 'low', signals: [] };
+}
+
+module.exports = { classifyProject };

package/src/generator/index.js

@@ -9,6 +9,7 @@ const { parseRoadmap, upsertManagedBlock } = require('../parser');
 const { findBestTaskMatch, dedupeTasks } = require('../match');
 const { collectPluginContributions } = require('../config');
 const { renderBody } = require('../renderer');
+const { classifyProject } = require('../classifier');
 
 const IMPL_PATTERN_RE = /[/|]TODO|TODO[|/]|[/|]FIXME|FIXME[|/]/;
 const COMMENT_TODO_RE = /(?:\/\/|#|\*\s*).*\b(?:TODO|FIXME)\b/;
@@ -149,6 +150,8 @@ function scanProject(projectRoot) {
   const implementedFiles = files.filter((file) => /\.(js|ts|tsx|py|go|rs|java|kt|cs)$/.test(file));
   const testFiles = files.filter((file) => /(^|\/)(__tests__|tests)\//.test(file) || /\.test\.|\.spec\.|_test\.go$/.test(file));
 
+  const classifier = classifyProject({ projectRoot, files });
+
   return {
     projectRoot,
     files,
@@ -160,7 +163,10 @@ function scanProject(projectRoot) {
     codeTodos,
     workspaces,
     implementedCount: implementedFiles.length,
-    testCount: testFiles.length
+    testCount: testFiles.length,
+    projectType: classifier.type,
+    classifierConfidence: classifier.confidence,
+    classifierSignals: classifier.signals
   };
 }
 
@@ -175,6 +181,35 @@ function toCandidate(text, phase, priority, source = 'default') {
   };
 }
 
+const WEB_CANDIDATES_COMMON = [
+  { text: 'Add SEO metadata: title, description, and canonical URL for all pages', phase: 'P0' },
+  { text: 'Implement responsive and mobile-first layout across all breakpoints', phase: 'P0' },
+  { text: 'Establish accessibility baseline (semantic HTML, ARIA labels, keyboard navigation)', phase: 'P0' },
+  { text: 'Add OpenGraph and Twitter card metadata for social sharing', phase: 'P1' },
+  { text: 'Achieve Lighthouse performance score ≥ 90 and resolve critical findings', phase: 'P1' },
+  { text: 'Validate branding consistency: typography, color tokens, and logo usage', phase: 'P1' },
+  { text: 'Configure deployment and hosting pipeline (CI/CD to production)', phase: 'P2' },
+  { text: 'Add web security headers: Content-Security-Policy, X-Frame-Options, HSTS', phase: 'P2' }
+];
+
+const LANDING_CANDIDATES = [
+  { text: 'Complete services and content sections with clear value proposition', phase: 'P1' },
+  { text: 'Implement contact form and conversion flow with input validation', phase: 'P1' },
+  { text: 'Set up analytics and conversion event tracking', phase: 'P2' }
+];
+
+function buildWebCandidates(scan) {
+  const candidates = WEB_CANDIDATES_COMMON.map(({ text, phase }) =>
+    toCandidate(text, phase, phase, 'classifier')
+  );
+  if (scan.projectType === 'landing-site') {
+    for (const { text, phase } of LANDING_CANDIDATES) {
+      candidates.push(toCandidate(text, phase, phase, 'classifier'));
+    }
+  }
+  return candidates;
+}
+
 function buildDefaultCandidates(scan, config) {
   const languageLabel = scan.languages.length > 0 ? scan.languages.join(', ') : 'current stack';
   const candidates = [];
@@ -223,6 +258,10 @@ function buildDefaultCandidates(scan, config) {
     candidates.push(toCandidate(`Resolve backlog note in ${hint.file}`, 'P0', 'P0', 'todo-hint'));
   }
 
+  if (scan.projectType === 'frontend-web' || scan.projectType === 'landing-site') {
+    candidates.push(...buildWebCandidates(scan));
+  }
+
   return candidates;
 }
 
@@ -547,10 +586,22 @@ function generateRoadmapDocument(options) {
     items: section.items || []
   }));
 
+  const evidenceLine = scan.classifierSignals.length > 0
+    ? scan.classifierSignals.slice(0, 5).join(', ')
+    : 'general file scan';
+  const profileSection = {
+    title: 'Detected Project Profile',
+    items: [
+      `- **Type:** ${scan.projectType}`,
+      `- **Confidence:** ${scan.classifierConfidence}`,
+      `- **Evidence:** ${evidenceLine}`
+    ]
+  };
+
   const baseCandidates = buildDefaultCandidates(scan, config);
   const matcherCandidates = applyTaskMatchers(scan, config);
   const merged = mergeWithExisting([...baseCandidates, ...matcherCandidates, ...pluginTaskCandidates], existingPhaseTasks);
-  const model = createModel(scan, merged, config, [...configSections, ...pluginSections], existingCheckedById);
+  const model = createModel(scan, merged, config, [profileSection, ...configSections, ...pluginSections], existingCheckedById);
   const profile = config.roadmapProfile || 'compact';
   const managedBody = renderBody(model, profile);
 

package/src/renderer/professional.js

@@ -530,6 +530,14 @@ function renderProfessional(model) {
   renderSection12SuccessCriteria(model, lines);
   renderSection13CustomPhases(model, lines);
 
+  for (const section of (model.customSections || [])) {
+    lines.push(`## ${section.title}`);
+    for (const line of section.items) {
+      lines.push(line);
+    }
+    lines.push('');
+  }
+
   return ensureTrailingNewline(lines.join('\n')).trimEnd();
 }
 

package/src/validator/index.js

@@ -12,23 +12,40 @@ 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'];
+// "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'];
 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'
+  // Action verbs too broad to be evidence signals
+  'implement', 'implementation', 'create', 'add', 'build', 'refactor', 'fix',
+  'detect', 'detection', 'support', 'handle', 'handler', 'update', 'check', 'run',
+  'process', 'processing', 'generate', 'generation', 'format', 'report',
+  // Structural concepts shared by every codebase
+  'module', 'function', 'class', 'method', 'command', 'type', 'value', 'values',
+  'output', 'input', 'data',
+  // Test vocabulary
+  'test', 'tests',
+  // Infrastructure names present in nearly every Node/JS project
+  'config', 'configuration', 'package', 'json', 'project', 'roadmap',
+  // Domain words specific to this tool that appear in non-feature source files
+  'confidence', 'profile', 'validation', 'evidence',
+  // Package/module field names that appear naturally in any Node.js generator or config file
+  'main', 'exports', 'files', 'fields', 'without', 'field',
+  // Terminology used in architecture/detection task descriptions that overlaps with source identifiers
+  'signals', 'directory', 'directories', 'headers', 'site', 'shebang',
+  // Common directory names that appear in import paths — too generic for evidence
+  'src', 'lib',
+  // Broad task-description verbs and nouns that pollute evidence matching across every codebase
+  'task', 'tasks', 'file', 'source', 'code', 'artifact', 'artifacts',
+  'generic', 'feature', 'features', 'section', 'sections',
+  'user', 'users', 'workflow', 'workflows', 'mode', 'modes', 'replace',
+  // Tool-internal vocabulary that appears in non-feature implementation files
+  'audit', 'debug', 'signal', 'signals', 'log',
+  // English stopwords and function words that appear everywhere — not useful as evidence signals
+  'only', 'must', 'what', 'which', 'kind', 'never', 'also', 'each',
+  'detected', 'generated', 'existing', 'available',
+  // Tool-commentary vocabulary that appears in source comments but describes past/intended behavior
+  'phrases', 'conceptual',
 ]);
 
 const CANONICAL_FILES = {
@@ -38,9 +55,37 @@ const CANONICAL_FILES = {
   license: 'LICENSE'
 };
 
+// The roadmap file must never be included in the evidence pool: its task descriptions
+// contain the exact vocabulary of the tasks being validated, which would cause every
+// task to validate itself.
+const SELF_REFERENTIAL_FILES = new Set(['ROADMAP.md']);
+
+// Maps task-ID namespace prefix to a predicate on (normalized) file paths.
+// When a task ID has a known namespace, at least one evidence file must satisfy
+// the predicate — otherwise generic token overlap alone cannot pass the task.
+const NAMESPACE_STRUCTURAL_PATTERNS = {
+  cls:  (p) => /classif(?:ier|y)|archetype/.test(p),
+  dsg:  (p) => /generator[/\\](?:domain|web|landing|profiles?)|(?:domain|web|landing)[/\\](?:profile|generator)/.test(p),
+  evh2: (p) => p.includes('/validator/') || p.includes('\\validator\\'),
+  cst:  (p) => /smoke|integration[-_]test|e2e/.test(p),
+  uxf:  (p) => p.includes('/renderer/') || p.includes('\\renderer\\') || /renderer\.[jt]sx?$/.test(p),
+  cfgo: (p) => /config[/\\]|schema[/\\]|config\.[jt]s$|schema\.[jt]s$/.test(p),
+  doc3: (p) => /(?:^|[/\\])docs[/\\]|readme\.md$/i.test(p),
+};
+
+// Test fixture directories contain synthetic code created to drive test scenarios,
+// not real implementations. Including them pollutes the evidence pool with vocabulary
+// that was deliberately seeded for testing purposes (e.g. namespace-vocab fixtures).
+function isFixturePath(relativePath) {
+  return /(?:^|[/\\])fixtures[/\\]/.test(relativePath);
+}
+
 function readFileIndex(projectRoot, files) {
   const index = [];
   for (const relativePath of files) {
+    if (SELF_REFERENTIAL_FILES.has(relativePath)) continue;
+    if (isFixturePath(relativePath)) continue;
+
     const absolutePath = path.resolve(projectRoot, relativePath);
     const ext = path.extname(relativePath).toLowerCase();
     let content = '';
@@ -79,10 +124,31 @@ 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;
+  // The ">= 2 slashes" rule was intentionally removed: it caused conceptual slash phrases
+  // like "code/test/artifact" or "build/test/deploy" to be treated as file paths.
+  // Real multi-segment paths are caught by the extension or known-root rules above.
   return false;
 }
 
+// Matches standalone filenames without a slash — e.g. "roadmap-skill.config.json",
+// "package.json", "vite.config.ts". These are path references whose component tokens
+// (e.g. "roadmap", "skill") must be excluded from code evidence scoring to prevent
+// circular vocabulary: a task mentioning a filename would otherwise score hits in any
+// source file that happens to reference the same filename for unrelated reasons.
+// Numeric-only tokens like "1.0.0" or "v0.8" are excluded via the leading-digit guard.
+const STANDALONE_FILE_RE = /\b([A-Za-z][A-Za-z0-9_.+-]*\.[A-Za-z0-9]{2,10})\b/g;
+const KNOWN_FILE_EXTENSIONS = new Set([
+  '.js', '.cjs', '.mjs', '.ts', '.tsx', '.jsx', '.py', '.go', '.rs',
+  '.java', '.kt', '.swift', '.rb', '.php', '.cs', '.json', '.yaml', '.yml',
+  '.toml', '.md', '.txt', '.sh', '.bash', '.env', '.html', '.css', '.scss', '.lock'
+]);
+
+function hasKnownFileExtension(token) {
+  const lastDot = token.lastIndexOf('.');
+  if (lastDot < 0) return false;
+  return KNOWN_FILE_EXTENSIONS.has(token.slice(lastDot).toLowerCase());
+}
+
 function extractExplicitPaths(text) {
   const results = new Set();
   const quoted = String(text).match(/`([^`]+)`/g) || [];
@@ -102,6 +168,25 @@ function extractExplicitPaths(text) {
   return Array.from(results).sort((left, right) => left.localeCompare(right));
 }
 
+// Standalone filenames (no slash) mentioned in task prose — e.g. "roadmap-skill.config.json",
+// "package.json". These are filename *references*, NOT path-existence assertions: the author
+// is describing which file contains a feature, not asserting that the file must exist.
+// Used only for pathDerivedToken extraction (to prevent circular vocabulary), never for
+// findFilesByPathHints (which would pass any task whose config file already exists).
+function extractStandaloneFilenames(text) {
+  const results = new Set();
+  STANDALONE_FILE_RE.lastIndex = 0;
+  let m = STANDALONE_FILE_RE.exec(String(text));
+  while (m) {
+    const token = m[1].replace(/[.,;:!?)]+$/, '');
+    if (hasKnownFileExtension(token) && !token.startsWith('.')) {
+      results.add(token);
+    }
+    m = STANDALONE_FILE_RE.exec(String(text));
+  }
+  return Array.from(results);
+}
+
 function extractSymbolHints(text) {
   const symbols = new Set();
   const patterns = [
@@ -128,7 +213,12 @@ function isCodeTask(taskText) {
 
 function isDocTask(taskText) {
   const normalized = String(taskText).toLowerCase();
-  return DOC_HINTS.some((hint) => normalized.includes(hint));
+  // Use word-boundary matching to avoid substring false positives (e.g. "specific" ≠ "spec").
+  const hasDocKeyword = DOC_HINTS.some((hint) => new RegExp(`(?<![a-z])${hint}(?![a-z])`).test(normalized));
+  if (!hasDocKeyword) return false;
+  // Also require a creation/update verb so that policy tasks mentioning doc files
+  // ("README must not be used as evidence") don't trigger doc-artifact evidence.
+  return /\b(add|create|write|update|init|initialize|introduce|setup|document)\b/.test(normalized);
 }
 
 function findFilesByPathHints(pathHints, fileIndex) {
@@ -166,9 +256,31 @@ function findFilesBySymbols(symbolHints, fileIndex) {
   return Array.from(matches).sort((left, right) => left.localeCompare(right));
 }
 
-function findCodeEvidence(taskText, fileIndex) {
+// Tokens extracted from a referenced file path (e.g. "roadmap-skill" from
+// "roadmap-skill.config.json") must not be reused as code evidence signals.
+// Those tokens appear in any file that mentions the same path — creating circular
+// vocabulary where a task about "X in path/to/file" passes because the source
+// code references the same path for unrelated reasons.
+function extractPathDerivedTokens(pathHints) {
+  const tokens = new Set();
+  for (const hint of pathHints) {
+    // Char-split: "roadmap-skill.config.json" → ["roadmap", "skill", "config", "json"]
+    const parts = hint.replace(/[.\-_/\\]/g, ' ').toLowerCase().split(/\s+/).filter(Boolean);
+    for (const part of parts) {
+      if (part.length >= 3) tokens.add(part);
+    }
+    // Tokenizer-split: also adds compound tokens the char-split misses, e.g. "roadmap-skill"
+    // (the tokenizer preserves hyphens in identifiers; the char-split strips them).
+    for (const token of tokenize(hint)) {
+      if (token.length >= 3) tokens.add(token);
+    }
+  }
+  return tokens;
+}
+
+function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
   const tokens = tokenize(taskText)
-    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
+    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/') && !pathDerivedTokens.has(token))
     .slice(0, 8);
   if (tokens.length === 0) {
     return [];
@@ -191,7 +303,9 @@ function findCodeEvidence(taskText, fileIndex) {
       }
     }
 
-    const threshold = tokens.length === 1 ? 1 : 2;
+    // Require more matches proportional to how many specific tokens the task has.
+    // Tasks with 4+ meaningful tokens need 3 files to match to prevent vocabulary overlap.
+    const threshold = tokens.length >= 4 ? 3 : tokens.length >= 2 ? 2 : 1;
     if (score >= threshold) {
       matches.push(file.relativePath);
     }
@@ -202,18 +316,46 @@ function findCodeEvidence(taskText, fileIndex) {
 
 function findTestEvidence(taskText, fileIndex) {
   const tokens = tokenize(taskText)
-    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token))
+    .filter((token) => token.length >= 3 && !GENERIC_TASK_TOKENS.has(token) && !token.endsWith('/'))
     .slice(0, 8);
+
+  if (tokens.length === 0) return [];
+
+  // Only tokens of length >= 4 are used for import-reference matching.
+  // Very short tokens (e.g. "app", "web") are too generic: they appear as substrings in
+  // many import paths that have nothing to do with the feature being validated.
+  // The single-short-token fallback below handles the narrow case of one-word module names.
+  const importTokens = tokens.filter((token) => token.length >= 4);
+
   const matches = [];
 
   for (const file of fileIndex) {
-    if (!file.isTestFile) {
+    if (!file.isTestFile) 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:
+    // test content (descriptions, literals) can contain future-task vocabulary,
+    // producing self-referential false positives.
+    //
+    // Trailing slashes are NOT stripped: "app/" is a directory reference, not a module name.
+    // "../src/app" (a real import) does not contain the string "app/" so it won't match.
+    const importRefs = (
+      file.content.match(/require\s*\(\s*['"`]([^'"`]+)['"`]\s*\)|from\s+['"`]([^'"`]+)['"`]/g) || []
+    ).join(' ').toLowerCase();
+
+    if (importTokens.length > 0 && importTokens.some((token) => importRefs.includes(token))) {
+      matches.push(file.relativePath);
       continue;
     }
-    const lowered = file.content.toLowerCase();
-    const hasMatch = tokens.some((token) => lowered.includes(token));
-    if (hasMatch) {
-      matches.push(file.relativePath);
+
+    // Narrow fallback: single very-short token (e.g. "app", "cli").
+    // Import paths for these are too short to distinguish reliably, so fall back to a
+    // content match — but only when there is exactly one such token (no multi-token dilution).
+    if (tokens.length === 1 && tokens[0].length < 4) {
+      const lowered = file.content.toLowerCase();
+      if (lowered.includes(tokens[0])) {
+        matches.push(file.relativePath);
+      }
     }
   }
 
@@ -225,19 +367,26 @@ function findArtifactEvidence(taskText, fileIndex) {
   const files = [];
   const heuristicArtifacts = [];
 
-  for (const [keyword, filename] of Object.entries(CANONICAL_FILES)) {
-    if (normalized.includes(keyword)) {
-      const hit = fileIndex.find(
-        (f) => f.relativePath === filename || f.relativePath.endsWith('/' + filename)
-      );
-      if (hit) {
-        files.push(hit.relativePath);
-        heuristicArtifacts.push(hit.relativePath);
+  // Canonical file detection only applies to short tasks (≤8 words) that are about
+  // creating or referencing that specific file. Long sentences that merely MENTION
+  // "readme" or "security" in a policy/constraint context are excluded.
+  const wordCount = normalized.trim().split(/\s+/).length;
+  if (wordCount <= 8) {
+    for (const [keyword, filename] of Object.entries(CANONICAL_FILES)) {
+      // Use hyphen-aware word boundaries: "security-headers" must not match "security".
+      if (new RegExp(`(?<![a-z-])${keyword}(?![a-z-])`).test(normalized)) {
+        const hit = fileIndex.find(
+          (f) => f.relativePath === filename || f.relativePath.endsWith('/' + filename)
+        );
+        if (hit) {
+          files.push(hit.relativePath);
+          heuristicArtifacts.push(hit.relativePath);
+        }
       }
     }
   }
 
-  if (!isDocTask(taskText) && !normalized.includes('artifact') && !normalized.includes('release')) {
+  if (!isDocTask(taskText)) {
     return { files, heuristicArtifacts };
   }
 
@@ -259,6 +408,82 @@ function findArtifactEvidence(taskText, fileIndex) {
   return { files: files.slice(0, 20), heuristicArtifacts };
 }
 
+function extractTaskNamespace(taskId) {
+  if (!taskId) return null;
+  const match = String(taskId).match(/^([a-z][a-z0-9]*)-/);
+  return match ? match[1] : null;
+}
+
+function isAcceptanceCriteria(taskId) {
+  return /ph\d+[_-]st\d+[_-]exit/.test(String(taskId || ''));
+}
+
+// Gate: returns { applicable, passed, structuralFiles, reason }.
+// For namespaces with a defined structural pattern:
+//   1. If no files in fileIndex match the pattern → immediate fail.
+//   2. For acceptance-criteria tasks (phN-stN-exit IDs): path match alone is enough.
+//   3. For implementation tasks: feature tokens from task text must score ≥ ceil(n/2)
+//      against namespace-matched files, preventing vocabulary overlap from generic
+//      infrastructure code (io.js, generator/index.js) from serving as evidence.
+function checkNamespaceStructuralEvidence(taskId, taskText, fileIndex) {
+  const namespace = extractTaskNamespace(taskId);
+  if (!namespace || !NAMESPACE_STRUCTURAL_PATTERNS[namespace]) {
+    return { applicable: false, passed: true, structuralFiles: [], reason: null };
+  }
+
+  const predicate = NAMESPACE_STRUCTURAL_PATTERNS[namespace];
+  const namespaceFiles = fileIndex.filter((f) => predicate(f.relativePath));
+
+  if (namespaceFiles.length === 0) {
+    return {
+      applicable: true,
+      passed: false,
+      structuralFiles: [],
+      reason: `namespace "${namespace}" has no implementation files`,
+    };
+  }
+
+  const featureTokens = tokenize(taskText)
+    .filter((t) => t.length >= 4 && !GENERIC_TASK_TOKENS.has(t) && !t.endsWith('/'))
+    .slice(0, 8);
+
+  if (featureTokens.length === 0) {
+    return {
+      applicable: true,
+      passed: true,
+      structuralFiles: namespaceFiles.map((f) => f.relativePath),
+      reason: null,
+    };
+  }
+
+  let bestScore = 0;
+  for (const nsFile of namespaceFiles) {
+    const lowered = nsFile.content.toLowerCase();
+    let score = 0;
+    for (const token of featureTokens) {
+      if (lowered.includes(token)) score++;
+    }
+    if (score > bestScore) bestScore = score;
+  }
+
+  const threshold = Math.max(1, Math.ceil(featureTokens.length / 2));
+  if (bestScore >= threshold) {
+    return {
+      applicable: true,
+      passed: true,
+      structuralFiles: namespaceFiles.map((f) => f.relativePath),
+      reason: null,
+    };
+  }
+
+  return {
+    applicable: true,
+    passed: false,
+    structuralFiles: namespaceFiles.map((f) => f.relativePath),
+    reason: `structural token score ${bestScore}/${threshold} in "${namespace}" files — token overlap insufficient`,
+  };
+}
+
 function evaluateRule(rule, task, context) {
   if (!rule) {
     return { passed: true, reasons: [], evidence: {} };
@@ -342,14 +567,21 @@ function buildValidationContext(projectRoot, config, plugins) {
 
 function validateTask(task, context, config, plugins) {
   const pathHints = extractExplicitPaths(task.text);
+  const standaloneFilenames = extractStandaloneFilenames(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);
+  // 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, ...standaloneFilenames]);
+  const filesFromCode = findCodeEvidence(task.text, context.fileIndex, pathDerivedTokens);
   const filesFromTests = findTestEvidence(task.text, context.fileIndex);
   const { files: filesFromArtifacts, heuristicArtifacts } = findArtifactEvidence(task.text, context.fileIndex);
 
+  const structuralCheck = checkNamespaceStructuralEvidence(task.id, task.text, context.fileIndex);
+
   const evidence = {
     code: filesFromCode.length > 0 || filesFromSymbols.length > 0,
     test: filesFromTests.length > 0,
@@ -359,7 +591,9 @@ function validateTask(task, context, config, plugins) {
     codeFiles: filesFromCode,
     testFiles: filesFromTests,
     artifactFiles: filesFromArtifacts,
-    heuristicArtifacts
+    heuristicArtifacts,
+    structuralEvidence: structuralCheck.applicable ? structuralCheck.passed : null,
+    structuralFiles: structuralCheck.structuralFiles,
   };
 
   const reasons = [];
@@ -370,8 +604,16 @@ function validateTask(task, context, config, plugins) {
     reasons.push(`missing symbol(s): ${symbolHints.join(', ')}`);
   }
 
+  // Namespace-structural gate: for known namespaces, token overlap alone is insufficient.
+  // The task must have evidence files whose paths match the namespace pattern.
+  if (structuralCheck.applicable && !structuralCheck.passed) {
+    reasons.push(structuralCheck.reason || `no structural evidence for namespace "${extractTaskNamespace(task.id)}"`);
+  }
+
   const hasEvidence = evidence.code || evidence.test || evidence.artifact || evidence.files.length > 0;
-  if (!hasEvidence) {
+  if (!hasEvidence && !structuralCheck.applicable) {
+    reasons.push('no code, test, or artifact evidence found');
+  } else if (!hasEvidence && structuralCheck.applicable && structuralCheck.passed) {
     reasons.push('no code, test, or artifact evidence found');
   }
 
@@ -395,12 +637,17 @@ function validateTask(task, context, config, plugins) {
   const evidenceCount = [evidence.code, evidence.test, evidence.artifact].filter(Boolean).length;
   const confidence = evidenceCount >= 2 ? 'high' : evidenceCount === 1 ? 'medium' : 'low';
 
+  // True when the only passing evidence is artifact/doc files and the task is not a doc task.
+  // Used by auditValidation to flag implementation tasks that pass solely via documentation.
+  const evidenceIsDocOnly = !evidence.code && !evidence.test && evidence.artifact && !isDocTask(task.text);
+
   return {
     taskId: task.id,
     passed: uniqueReasons.length === 0,
     confidence,
     reasons: uniqueReasons,
     evidence,
+    evidenceIsDocOnly,
     requiresTest,
     hasEvidence,
     attempted
@@ -418,12 +665,13 @@ function validateTasks(tasks, context, config, plugins) {
 function auditValidation(tasks, results) {
   const checkedWithoutEvidence = [];
   const readyButUnchecked = [];
+  const checkedWithWeakEvidence = [];
+  const documentationOnlyEvidenceForImplementation = [];
+  const checkedWithNoStructuralEvidence = [];
 
   for (const task of tasks) {
     const result = results[task.id];
-    if (!result) {
-      continue;
-    }
+    if (!result) continue;
 
     if (task.checked && !result.passed) {
       checkedWithoutEvidence.push({ task, result });
@@ -432,11 +680,27 @@ function auditValidation(tasks, results) {
     if (!task.checked && result.passed) {
       readyButUnchecked.push({ task, result });
     }
+
+    if (task.checked && result.passed && result.confidence === 'low') {
+      checkedWithWeakEvidence.push({ task, result });
+    }
+
+    if (task.checked && result.passed && result.evidenceIsDocOnly) {
+      documentationOnlyEvidenceForImplementation.push({ task, result });
+    }
+
+    // Checked task that failed specifically because structural evidence is missing.
+    if (task.checked && !result.passed && result.evidence.structuralEvidence === false) {
+      checkedWithNoStructuralEvidence.push({ task, result });
+    }
   }
 
   return {
     checkedWithoutEvidence,
-    readyButUnchecked
+    readyButUnchecked,
+    checkedWithWeakEvidence,
+    documentationOnlyEvidenceForImplementation,
+    checkedWithNoStructuralEvidence,
   };
 }
 
@@ -460,5 +724,7 @@ module.exports = {
   validateTask,
   validateTasks,
   CONFIDENCE_RANK,
-  applyMinimumConfidence
+  applyMinimumConfidence,
+  extractTaskNamespace,
+  isAcceptanceCriteria,
 };