roadmapsmith 0.9.24 → 0.9.26

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.24",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
+  "version": "0.9.26",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
   "author": {
     "name": "PapiScholz"
   },

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.24",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
+  "version": "0.9.26",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
   "author": {
     "name": "PapiScholz"
   },

package/README.md

@@ -120,7 +120,8 @@ roadmapsmith init [--roadmap-file <path>] [--agents-file <path>] [--dry-run]
 roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]
 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]
-roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]
+roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]
+roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]   # compatibility alias
 ```
 
 ## Claude Code native slash commands
@@ -153,7 +154,7 @@ Then restart Codex, open the plugin directory, install `roadmapsmith` from the `
 
 Codex native plugin support means install/enable discovery inside Codex. It is separate from Claude-specific `/reload-skills` behavior, and the VS Code task layer remains the fallback/manual workflow when you are not using the plugin directory.
 
-`roadmapsmith doctor --json` now reports native slash surfaces separately from the VS Code task layer:
+`roadmapsmith status --json` now reports native slash surfaces separately from the VS Code task layer (`doctor --json` remains a compatibility alias):
 
 - `claudeGui`
 - `claudeCli`
@@ -179,7 +180,8 @@ The repo does not remove user-global skills automatically. Use the `doctor` outp
   - code OR test OR artifact evidence required.
   - test evidence required for code tasks when test frameworks are detected.
 - Validation failures in sync write warning lines:
-  - `- ⚠️ attempted but validation failed: <reason>`
+  - `- ⚠️ attempted but validation failed: <reason>` when there is concrete attempt evidence
+  - `- ⚠️ no implementation evidence found yet: <reason>` when there is not
 - Preserves unmanaged markdown content by updating only the managed roadmap block.
 
 ## Defaults

package/bin/cli.js

@@ -31,7 +31,8 @@ function printHelp() {
     '  roadmapsmith generate [--project-root <path>] [--config <path>] [--roadmap-file <path>] [--dry-run] [--audit] [--full-regen]',
     '  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]',
-    '  roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]'
+    '  roadmapsmith status [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]',
+    '  roadmapsmith doctor [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--json]   # compatibility alias'
   ].join('\n'));
 }
 
@@ -245,7 +246,7 @@ function printHumanStatus(payload) {
 function runStatusCommand(projectRoot, config, flags, options = {}) {
   const roadmapFile = resolveRoadmapFile(projectRoot, config, flags['roadmap-file']);
   const agentsFile = resolveAgentsFile(projectRoot, config, flags['agents-file']);
-  const payload = inspectHostSetup(projectRoot, { roadmapFile, agentsFile });
+  const payload = inspectHostSetup(projectRoot, { roadmapFile, agentsFile, currentCliPath: __filename });
 
   if (options.json) {
     process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
@@ -443,7 +444,7 @@ async function run() {
     return;
   }
 
-  if (effectiveCommand === 'doctor') {
+  if (effectiveCommand === 'status' || effectiveCommand === 'doctor') {
     const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
     let ok = true;
     const jsonMode = isEnabled(flags.json);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.24",
-  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude.",
+  "version": "0.9.26",
+  "description": "One-command evidence-backed ROADMAP.md generator and sync tool for AI coding agents, with shared RoadmapSmith plugin skills for Codex and Claude plus the roadmapsmith status readiness surface.",
   "main": "src/index.js",
   "bin": {
     "roadmapsmith": "bin/cli.js"

package/skills/roadmap-sync/agents/openai.yaml

@@ -2,6 +2,6 @@
   "interface": {
     "display_name": "Roadmap Sync",
     "short_description": "Legacy root plus policy for evidence-backed ROADMAP.md slash workflows.",
-    "default_prompt": "Prefer /roadmap for discovery, /roadmap-maintain for existing repos, and /roadmap-update for direct sync."
+    "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update."
   }
 }

package/skills.json

@@ -22,74 +22,74 @@
     "command": "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
     "source": "PapiScholz/roadmapsmith",
     "skill": "*",
-    "notes": "Recommended Claude Code install path for native GUI slash commands like /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, and /roadmap-setup. The legacy /roadmap-sync root remains available for compatibility, especially as /roadmap-sync <action>. Install the roadmapsmith CLI separately for actual command execution, then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
+    "notes": "Recommended Claude Code install path for native GUI slash commands like /roadmap, /roadmap-zero, /roadmap-maintain, /roadmap-status, /roadmap-init, /roadmap-generate, /roadmap-validate, /roadmap-update, /roadmap-audit, and /roadmap-setup. The legacy /roadmap-sync root remains available for compatibility, especially as /roadmap-sync <action>. Install the roadmapsmith CLI separately for actual command execution; roadmapsmith status is the visible readiness command and roadmapsmith doctor remains a compatibility alias. Then run /reload-skills and, if applicable, /reload-plugins. Codex native plugin installs use the repo/package .codex-plugin surface instead of this Claude-specific skills CLI path."
   },
   "skills": [
     {
       "name": "roadmap",
       "path": "skills/roadmap",
       "description": "Native slash palette for RoadmapSmith commands and recommended entrypoints across supported hosts.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
       "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
       "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
-      "description": "Native slash readiness check grounded in roadmapsmith doctor JSON.",
-      "version": "0.9.24"
+      "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-generate",
       "path": "skills/roadmap-generate",
       "description": "Native slash entrypoint for managed roadmap updates that require --full-regen before destructive replacement.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
       "description": "Native slash entrypoint for applying evidence-backed checklist sync.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
       "description": "Legacy namespaced root plus policy guidance for RoadmapSmith slash workflows.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the current sync-plus-audit workflow.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.24"
+      "version": "0.9.26"
     }
   ]
 }

package/src/host.js

@@ -921,7 +921,7 @@ function renderVsCodeLauncher() {
     'function explain() {',
     '  console.log(\'RoadmapSmith layers:\\n\');',
     '  console.log(\'1. The roadmap-sync skill guides the agent. It does not add VS Code buttons or install the CLI.\');',
-    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus init/generate/validate/sync/setup/doctor, with --full-regen reserved for destructive replacement.\');',
+    '  console.log(\'2. The roadmapsmith CLI executes zero/maintain plus init/generate/validate/sync/setup/status, with doctor kept as a compatibility alias and --full-regen reserved for destructive replacement.\');',
     '  console.log(\'3. roadmapsmith setup makes the CLI visible in VS Code through tasks and optional Claude hook wiring.\\n\');',
     '  console.log(\'Typical VS Code workflow:\');',
     '  console.log(\'- Run "RoadmapSmith: Status" to inspect readiness.\');',
@@ -1020,7 +1020,7 @@ function renderVsCodeLauncher() {
     '}',
     '',
     'function status() {',
-    '  const result = runCli([\'doctor\', \'--project-root\', PROJECT_ROOT, \'--json\'], { capture: true, allowMissingCli: true });',
+    '  const result = runCli([\'status\', \'--project-root\', PROJECT_ROOT, \'--json\'], { capture: true, allowMissingCli: true });',
     '  if (!result || result.missingCli) {',
     '    printMissingCliStatus();',
     '    return;',
@@ -1143,7 +1143,26 @@ function findGlobalRoadmapsmith() {
   return findCommandPath('roadmapsmith');
 }
 
-function detectCliResolution(projectRoot) {
+function isRoadmapsmithCliEntrypoint(filePath) {
+  const normalized = String(filePath || '').replace(/\\/g, '/').toLowerCase();
+  if (!normalized) {
+    return false;
+  }
+  return normalized.endsWith('/roadmap-skill/bin/cli.js')
+    || normalized.endsWith('/roadmapsmith/bin/cli.js')
+    || /(?:^|[\\/])roadmapsmith(?:\.(?:cmd|exe|bat|ps1))?$/.test(normalized);
+}
+
+function detectCliResolution(projectRoot, options = {}) {
+  const currentCliPath = options.currentCliPath || process.argv[1] || null;
+  if (currentCliPath && isRoadmapsmithCliEntrypoint(currentCliPath)) {
+    return {
+      ready: true,
+      kind: 'current-process',
+      path: currentCliPath
+    };
+  }
+
   const workspaceDevCli = path.join(projectRoot, 'roadmap-skill', 'bin', 'cli.js');
   if (fs.existsSync(workspaceDevCli)) {
     return {
@@ -1244,7 +1263,7 @@ function inspectHostSetup(projectRoot, options = {}) {
   const roadmapFile = options.roadmapFile;
   const agentsFile = options.agentsFile;
   const runtime = detectNodeRuntime(options.env || process.env);
-  const cli = detectCliResolution(projectRoot);
+  const cli = detectCliResolution(projectRoot, { currentCliPath: options.currentCliPath });
   const vscode = inspectVsCodeTasks(projectRoot);
   const claude = inspectClaudeSetup(projectRoot);
   const bundle = inspectSharedBundleSurface();

package/src/parser/index.js

@@ -4,7 +4,12 @@ const { slugify } = require('../utils');
 
 const MANAGED_START = '<!-- rs:managed:start -->';
 const MANAGED_END = '<!-- rs:managed:end -->';
-const WARNING_PREFIX = '⚠️ attempted but validation failed:';
+const WARNING_PREFIX = '⚠️';
+const WARNING_REASON_PREFIXES = [
+  'attempted but validation failed:',
+  'no implementation evidence found yet:',
+  'validation failed:'
+];
 
 function getIndentWidth(text) {
   return String(text || '').replace(/\t/g, '    ').length;
@@ -86,7 +91,14 @@ function parseEvidenceLine(content) {
 
 function parseWarningLine(content) {
   if (!content.startsWith(WARNING_PREFIX)) return null;
-  return content.slice(WARNING_PREFIX.length).trim();
+  let normalized = content.slice(WARNING_PREFIX.length).trim();
+  for (const prefix of WARNING_REASON_PREFIXES) {
+    if (normalized.startsWith(prefix)) {
+      normalized = normalized.slice(prefix.length).trim();
+      break;
+    }
+  }
+  return normalized;
 }
 
 function parseBlockedByLine(content) {
@@ -98,6 +110,7 @@ function parseRoadmap(content) {
   const lines = String(content || '').split(/\r?\n/);
   const managedRange = findManagedRange(lines);
   const tasks = [];
+  const implicitIdCounts = new Map();
   let section = '';
 
   for (let index = 0; index < lines.length; index += 1) {
@@ -162,7 +175,12 @@ function parseRoadmap(content) {
       }
     }
 
-    const id = markerId || slugify(text);
+    const baseId = markerId || slugify(text);
+    const nextImplicitCount = markerId ? 1 : (implicitIdCounts.get(baseId) || 0) + 1;
+    if (!markerId) {
+      implicitIdCounts.set(baseId, nextImplicitCount);
+    }
+    const id = markerId || (nextImplicitCount === 1 ? baseId : `${baseId}-${nextImplicitCount}`);
     tasks.push({
       id,
       text,

package/src/slash.js

@@ -16,7 +16,7 @@ const SLASH_ACTIONS = [
   {
     id: 'status',
     description: 'Inspect CLI, roadmap, VS Code task, Codex, and Claude readiness.',
-    classicCliExample: 'roadmapsmith doctor --json',
+    classicCliExample: 'roadmapsmith status --json',
     taskLabel: 'RoadmapSmith: Status'
   },
   {

package/src/sync/index.js

@@ -3,14 +3,21 @@
 const { parseRoadmap } = require('../parser');
 const { ensureTrailingNewline } = require('../utils');
 
-const WARNING_REASON_PREFIX = 'attempted but validation failed:';
+const ATTEMPTED_WARNING_REASON_PREFIX = 'attempted but validation failed:';
+const NO_EVIDENCE_WARNING_REASON_PREFIX = 'no implementation evidence found yet:';
+const WARNING_REASON_PREFIXES = [
+  ATTEMPTED_WARNING_REASON_PREFIX,
+  NO_EVIDENCE_WARNING_REASON_PREFIX,
+  'validation failed:'
+];
 
 function setChecklistState(line, checked) {
   return line.replace(/- \[( |x|X)\]/, `- [${checked ? 'x' : ' '}]`);
 }
 
-function formatWarning(indent, reason) {
-  return `${indent}  - ⚠️ attempted but validation failed: ${reason}`;
+function formatWarning(indent, reason, attempted) {
+  const prefix = attempted ? ATTEMPTED_WARNING_REASON_PREFIX : NO_EVIDENCE_WARNING_REASON_PREFIX;
+  return `${indent}  - ⚠️ ${prefix} ${reason}`;
 }
 
 function isWhitespaceCharacter(char) {
@@ -72,9 +79,12 @@ function normalizeWarningReason(reason) {
   }
 
   normalized = stripLeadingWarningMarker(normalized).trim();
-  const prefixIndex = normalized.indexOf(WARNING_REASON_PREFIX);
-  if (prefixIndex >= 0) {
-    normalized = normalized.slice(prefixIndex + WARNING_REASON_PREFIX.length).trim();
+  for (const prefix of WARNING_REASON_PREFIXES) {
+    const prefixIndex = normalized.indexOf(prefix);
+    if (prefixIndex >= 0) {
+      normalized = normalized.slice(prefixIndex + prefix.length).trim();
+      break;
+    }
   }
 
   return normalized;
@@ -122,12 +132,12 @@ function applySync(content, parsedTasks, results) {
     lines[lineIndex] = setChecklistState(lines[lineIndex], result.passed);
 
     const reason = normalizeWarningReasons(result.reasons).join('; ');
-    const warningText = formatWarning(task.indent || '', reason || 'validation failed');
+    const warningText = formatWarning(task.indent || '', reason || 'validation failed', result.attempted);
     const hasWarning = task.warningLineIndex != null;
     const warningIndex = hasWarning ? task.warningLineIndex + offset : null;
     const lastChildLineIndex = (task.lastChildLineIndex != null ? task.lastChildLineIndex : task.lineIndex) + offset;
 
-    if (result.passed || !result.attempted) {
+    if (result.passed) {
       if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
         lines.splice(warningIndex, 1);
         offset -= 1;
@@ -136,7 +146,7 @@ function applySync(content, parsedTasks, results) {
     }
 
     if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
-      const existingReason = lines[warningIndex].split('validation failed:')[1];
+      const existingReason = normalizeWarningReason(lines[warningIndex]);
       const newReason = reason || 'validation failed';
       if (!shouldPreserveExistingWarning(existingReason, newReason)) {
         lines[warningIndex] = warningText;

package/src/validator/index.js

@@ -197,18 +197,9 @@ function hasFileExtension(token) {
 }
 
 function isLikelyPath(token) {
-  if (token.includes('*') || token.includes('?')) return false; // glob/wildcard
-  if (/^\/api\//i.test(token)) return false; // HTTP API route paths are not file paths
-  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
-  // 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;
+  if (isRealFilePath(token)) return true;
+  // Preserve the legacy extension-only fallback for standalone path-looking tokens.
+  return hasFileExtension(token);
 }
 
 // Matches standalone filenames without a slash — e.g. "roadmap-skill.config.json",
@@ -230,21 +221,83 @@ function hasKnownFileExtension(token) {
   return KNOWN_FILE_EXTENSIONS.has(token.slice(lastDot).toLowerCase());
 }
 
+function startsWithKnownPathRoot(token) {
+  const normalized = String(token || '').replace(/\\/g, '/').toLowerCase();
+  return KNOWN_PATH_ROOTS.some((root) => normalized.startsWith(root.toLowerCase()));
+}
+
+function isHttpRouteToken(token) {
+  const normalized = String(token || '').trim();
+  if (!normalized) return false;
+  if (/^(GET|POST|PUT|PATCH|DELETE)\s+\/\S+$/i.test(normalized)) {
+    return true;
+  }
+  return /^\/api\//i.test(normalized);
+}
+
+function isMimeTypeToken(token) {
+  return /^[A-Za-z0-9.+-]+\/[A-Za-z0-9.+-]+$/.test(String(token || '').trim());
+}
+
+function looksLikeFormulaToken(token) {
+  return /[=×÷]/.test(String(token || '').trim());
+}
+
+function isRealFilePath(token) {
+  const normalized = String(token || '').trim().replace(/\\/g, '/');
+  if (!normalized) return false;
+  if (normalized.includes('*') || normalized.includes('?')) return false;
+  if (/\s/.test(normalized)) return false;
+  if (looksLikeFormulaToken(normalized)) return false;
+  if (isHttpRouteToken(normalized)) return false;
+
+  const looksLikePath =
+    hasKnownFileExtension(normalized) ||
+    startsWithKnownPathRoot(normalized) ||
+    /^\.{1,2}\//.test(normalized) ||
+    /^\//.test(normalized);
+  if (!looksLikePath) return false;
+
+  if (!hasKnownFileExtension(normalized) && !startsWithKnownPathRoot(normalized) && isMimeTypeToken(normalized)) {
+    return false;
+  }
+
+  if (/^\.{1,2}\/|^\//.test(normalized)) {
+    return /[A-Za-z0-9_]/.test(normalized);
+  }
+
+  return true;
+}
+
 function isAsciiAlphaNumeric(char) {
   if (!char || char.length === 0) return false;
   const code = char.charCodeAt(0);
   return (code >= 48 && code <= 57) || (code >= 65 && code <= 90) || (code >= 97 && code <= 122);
 }
 
-function isPathTokenCharacter(char) {
-  return isAsciiAlphaNumeric(char) || char === '.' || char === '_' || char === '-' || char === '/' || char === '\\';
+function isPathTokenCharacter(char, current) {
+  if (char === '~') {
+    return !current;
+  }
+  return isAsciiAlphaNumeric(char) || char === '.' || char === '_' || char === '-' || char === '/' || char === '\\' || char === ':';
 }
 
 function stripTrailingPathPunctuation(token) {
   let result = String(token || '');
   while (result.length > 0) {
     const lastChar = result[result.length - 1];
-    if (lastChar !== '.' && lastChar !== ',' && lastChar !== ';' && lastChar !== ':' && lastChar !== '!' && lastChar !== '?' && lastChar !== ')') {
+    if (
+      lastChar !== '.' &&
+      lastChar !== ',' &&
+      lastChar !== ';' &&
+      lastChar !== ':' &&
+      lastChar !== '!' &&
+      lastChar !== '?' &&
+      lastChar !== ')' &&
+      lastChar !== ']' &&
+      lastChar !== '>' &&
+      lastChar !== '`'
+    ) {
       break;
     }
     result = result.slice(0, -1);
@@ -255,22 +308,41 @@ function stripTrailingPathPunctuation(token) {
 function collectPathishTokens(text) {
   const tokens = [];
   let current = '';
+  let tokenStart = -1;
   const source = String(text || '');
   for (let index = 0; index < source.length; index += 1) {
     const char = source[index];
-    if (isPathTokenCharacter(char)) {
+    if (isPathTokenCharacter(char, current)) {
+      if (!current) {
+        tokenStart = index;
+      }
       current += char;
       continue;
     }
     if (current) {
-      tokens.push(stripTrailingPathPunctuation(current));
+      const value = stripTrailingPathPunctuation(current);
+      if (value) {
+        tokens.push({
+          value,
+          start: tokenStart,
+          end: tokenStart + value.length
+        });
+      }
       current = '';
+      tokenStart = -1;
     }
   }
   if (current) {
-    tokens.push(stripTrailingPathPunctuation(current));
+    const value = stripTrailingPathPunctuation(current);
+    if (value) {
+      tokens.push({
+        value,
+        start: tokenStart,
+        end: tokenStart + value.length
+      });
+    }
   }
-  return tokens.filter(Boolean);
+  return tokens;
 }
 
 // LINE_REF_RE matches "path/file.ext:NN" or "path/file.ext:NN-MM" — indicates WHERE
@@ -278,46 +350,142 @@ function collectPathishTokens(text) {
 // to lineReferenceHints and excluded from hasDirectReferencePass scoring.
 const LINE_REF_RE = /^(.+?):(\d+)(?:-\d+)?$/;
 
+function normalizePathCandidateToken(rawToken) {
+  const stripped = stripTrailingPathPunctuation(String(rawToken || '').trim());
+  if (!stripped) {
+    return '';
+  }
+  const normalized = stripped.replace(/\\/g, '/');
+  if (/^~\//.test(normalized)) {
+    return normalized;
+  }
+  return normalized.replace(/^~(?=\/)/, '~');
+}
+
+function isExternalPathToken(token) {
+  return /^~\//.test(String(token || '').trim().replace(/\\/g, '/'));
+}
+
+function classifyExplicitPathCandidate(rawToken) {
+  const clean = normalizePathCandidateToken(rawToken);
+  if (!clean || clean.includes('*') || clean.includes('?')) {
+    return null;
+  }
+
+  const lineMatch = LINE_REF_RE.exec(clean);
+  if (lineMatch) {
+    const linePath = normalizePathCandidateToken(lineMatch[1]);
+    if (isExternalPathToken(linePath)) {
+      return { path: linePath, kind: 'external', isLineReference: true };
+    }
+    if (isRealFilePath(linePath)) {
+      return { path: linePath, kind: 'repo', isLineReference: true };
+    }
+    return null;
+  }
+
+  if (isExternalPathToken(clean)) {
+    return { path: clean, kind: 'external', isLineReference: false };
+  }
+
+  if (!isRealFilePath(clean)) {
+    return null;
+  }
+
+  return { path: clean, kind: 'repo', isLineReference: false };
+}
+
+function addClassifiedPath(classified, results, externalPaths, lineReferenceHints) {
+  if (!classified) return;
+  if (classified.kind === 'external') {
+    externalPaths.add(classified.path);
+  } else {
+    results.add(classified.path);
+    if (classified.isLineReference) {
+      lineReferenceHints.add(classified.path);
+    }
+  }
+}
+
+function findHttpRequestRouteRanges(text) {
+  const ranges = [];
+  const pattern = /\b(?:GET|POST|PUT|PATCH|DELETE)\s+(\/[^\s`]+)/gi;
+  let match = pattern.exec(String(text || ''));
+  while (match) {
+    const routeToken = match[1];
+    const routeStart = match.index + match[0].length - routeToken.length;
+    ranges.push({ start: routeStart, end: routeStart + routeToken.length });
+    match = pattern.exec(String(text || ''));
+  }
+  return ranges;
+}
+
+function isTokenInsideRanges(token, ranges) {
+  return ranges.some((range) => token.start >= range.start && token.end <= range.end);
+}
+
+function addPathTokensFromPlainText(text, results, externalPaths, lineReferenceHints) {
+  const ignoredRanges = findHttpRequestRouteRanges(text);
+  for (const token of collectPathishTokens(text)) {
+    if (!token.value.includes('/') && !isExternalPathToken(token.value)) {
+      continue;
+    }
+    if (isTokenInsideRanges(token, ignoredRanges)) {
+      continue;
+    }
+    addClassifiedPath(classifyExplicitPathCandidate(token.value), results, externalPaths, lineReferenceHints);
+  }
+}
+
+function addPathTokensFromBacktickSpan(text, results, externalPaths, lineReferenceHints) {
+  const wholeSpan = classifyExplicitPathCandidate(text);
+  if (wholeSpan) {
+    addClassifiedPath(wholeSpan, results, externalPaths, lineReferenceHints);
+    return;
+  }
+
+  if (!/[;,]/.test(text)) {
+    return;
+  }
+
+  for (const part of text.split(/[;,]/)) {
+    addClassifiedPath(classifyExplicitPathCandidate(part), results, externalPaths, lineReferenceHints);
+  }
+}
+
 function extractExplicitPaths(text) {
   const results = new Set();
+  const externalPaths = new Set();
   const lineReferenceHints = new Set();
+  const source = String(text || '');
+  let cursor = 0;
 
-  const quoted = String(text).match(/`([^`]+)`/g) || [];
-  for (const token of quoted) {
-    const clean = token.slice(1, -1);
-    if (clean.includes('*') || clean.includes('?')) continue; // glob
-    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);
+  while (cursor < source.length) {
+    const openTick = source.indexOf('`', cursor);
+    if (openTick < 0) {
+      addPathTokensFromPlainText(source.slice(cursor), results, externalPaths, lineReferenceHints);
+      break;
     }
-  }
 
-  for (const word of String(text).split(/\s+/)) {
-    if (!word.includes('/')) continue;
-    const token = stripTrailingPathPunctuation(word);
-    if (token.includes('*') || token.includes('?')) continue; // glob
-    const lineMatch = LINE_REF_RE.exec(token);
-    if (lineMatch && hasKnownFileExtension(lineMatch[1])) {
-      if (isLikelyPath(lineMatch[1])) {
-        lineReferenceHints.add(lineMatch[1]);
-        results.add(lineMatch[1]);
-      }
-    } else if (isLikelyPath(token)) {
-      results.add(token);
+    addPathTokensFromPlainText(source.slice(cursor, openTick), results, externalPaths, lineReferenceHints);
+    const closeTick = source.indexOf('`', openTick + 1);
+    if (closeTick < 0) {
+      addPathTokensFromPlainText(source.slice(openTick), results, externalPaths, lineReferenceHints);
+      break;
     }
+
+    addPathTokensFromBacktickSpan(source.slice(openTick + 1, closeTick), results, externalPaths, lineReferenceHints);
+    cursor = closeTick + 1;
   }
 
   const paths = Array.from(results)
     .filter((p) => !p.includes('*') && !p.includes('?'))
     .sort((left, right) => left.localeCompare(right));
-  return { paths, lineReferenceHints };
+  return {
+    paths,
+    externalPaths: Array.from(externalPaths).sort((left, right) => left.localeCompare(right)),
+    lineReferenceHints
+  };
 }
 
 // Standalone filenames (no slash) mentioned in task prose — e.g. "roadmap-skill.config.json",
@@ -363,6 +531,14 @@ function isCodeTask(taskText) {
   return CODE_HINTS.some((hint) => normalized.includes(hint));
 }
 
+function isHttpExpectationTask(taskText) {
+  const text = String(taskText || '');
+  if (!/(?:->|→)/.test(text) || !/\bHTTP\s+\d{3}\b/i.test(text)) {
+    return false;
+  }
+  return /\b(?:GET|POST|PUT|PATCH|DELETE)\b/i.test(text) || /\/api\//i.test(text);
+}
+
 function isDocTask(taskText) {
   const normalized = String(taskText).toLowerCase();
   // Use word-boundary matching to avoid substring false positives (e.g. "specific" ≠ "spec").
@@ -377,10 +553,59 @@ function isImplementationTask(taskText) {
   return !isDocTask(taskText) && (isCodeTask(taskText) || taskDescribesChange(taskText));
 }
 
-function findFilesByPathHints(pathHints, fileIndex) {
+function deriveNextAppRouteAlias(relativePath) {
+  const normalized = normalizePathForMatch(relativePath);
+  const match = normalized.match(/^(?:src\/)?app(?:\/(.*))?\/(page|route)\.(?:js|jsx|ts|tsx)$/);
+  if (!match) {
+    return null;
+  }
+
+  const routePath = match[1] || '';
+  const segments = routePath ? routePath.split('/').filter(Boolean) : [];
+  const visibleSegments = [];
+  for (const segment of segments) {
+    if (/^\([^)]*\)$/.test(segment)) {
+      continue;
+    }
+    if (segment.includes('(') || segment.includes(')') || segment.includes('[') || segment.includes(']') || segment.startsWith('@')) {
+      return null;
+    }
+    visibleSegments.push(segment);
+  }
+
+  return visibleSegments.length > 0 ? `/${visibleSegments.join('/')}` : '/';
+}
+
+function buildPathHintResolver(fileIndex) {
+  const routeAliasIndex = new Map();
+  for (const file of fileIndex) {
+    const alias = deriveNextAppRouteAlias(file.relativePath);
+    if (!alias) {
+      continue;
+    }
+    const existing = routeAliasIndex.get(alias) || [];
+    existing.push(file.relativePath);
+    routeAliasIndex.set(alias, existing);
+  }
+
+  for (const [alias, matches] of routeAliasIndex.entries()) {
+    routeAliasIndex.set(alias, Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right)));
+  }
+
+  return {
+    fileIndex,
+    routeAliasIndex
+  };
+}
+
+function findFilesByPathHints(pathHints, pathHintResolver) {
+  const resolver = Array.isArray(pathHintResolver)
+    ? buildPathHintResolver(pathHintResolver)
+    : pathHintResolver;
+  const fileIndex = resolver.fileIndex;
   const matches = [];
   for (const hint of pathHints) {
-    const normalizedHint = hint.replace(/\\/g, '/');
+    const normalizedHint = normalizePathCandidateToken(hint);
     const direct = fileIndex.find((file) => file.relativePath === normalizedHint);
     if (direct) {
       matches.push(direct.relativePath);
@@ -392,6 +617,11 @@ function findFilesByPathHints(pathHints, fileIndex) {
         matches.push(file.relativePath);
       }
     }
+
+    const routeMatches = resolver.routeAliasIndex.get(normalizedHint);
+    if (routeMatches && routeMatches.length > 0) {
+      matches.push(...routeMatches);
+    }
   }
   return Array.from(new Set(matches)).sort((left, right) => left.localeCompare(right));
 }
@@ -683,19 +913,12 @@ function isTestPath(relativePath) {
   return /(^|\/)(__tests__|tests)\//.test(relativePath) || /\.test\.|\.spec\.|_test\.go$/.test(relativePath);
 }
 
-function extractEvidencePaths(evidenceText) {
-  const paths = new Set();
-  for (const rawCandidate of collectPathishTokens(evidenceText)) {
-    const candidate = rawCandidate.split('\\').join('/');
-    if (!candidate.includes('/') || candidate.includes('*') || candidate.includes('?')) {
-      continue;
-    }
-    if (!hasKnownFileExtension(candidate)) {
-      continue;
-    }
-    paths.add(candidate.replace(/^\.\//, ''));
-  }
-  return Array.from(paths).sort((left, right) => left.localeCompare(right));
+function extractReferencedPaths(text) {
+  const extracted = extractExplicitPaths(text);
+  return {
+    repoPaths: extracted.paths,
+    externalPaths: extracted.externalPaths
+  };
 }
 
 function evidenceLineHasPassingSummary(evidenceText) {
@@ -714,7 +937,7 @@ function evidenceSummaryImpliesTests(evidenceText) {
     /\b(?:vitest|jest|npm test|pnpm test|yarn test|bun test)\b/i.test(String(evidenceText || ''));
 }
 
-function evaluateAuthoritativeEvidence(task, fileIndex) {
+function evaluateAuthoritativeEvidence(task, pathHintResolver) {
   const evidenceLines = Array.isArray(task.evidenceLines) ? task.evidenceLines : [];
   if (evidenceLines.length === 0) {
     return {
@@ -729,8 +952,9 @@ function evaluateAuthoritativeEvidence(task, fileIndex) {
     };
   }
 
-  const referencedPaths = unionArrays(...evidenceLines.map((line) => extractEvidencePaths(line.text)));
-  const matchedPaths = referencedPaths.length > 0 ? findFilesByPathHints(referencedPaths, fileIndex) : [];
+  const extractedReferences = evidenceLines.map((line) => extractReferencedPaths(line.text));
+  const referencedPaths = unionArrays(...extractedReferences.map((entry) => entry.repoPaths));
+  const matchedPaths = referencedPaths.length > 0 ? findFilesByPathHints(referencedPaths, pathHintResolver) : [];
   const summaryMatches = evidenceLines
     .filter((line) => evidenceLineHasPassingSummary(line.text))
     .map((line) => line.text);
@@ -1053,6 +1277,7 @@ function buildValidationContext(projectRoot, config, plugins) {
   const files = walkFiles(projectRoot);
   const fileIndex = readFileIndex(projectRoot, files, config);
   const testFrameworks = detectTestFrameworks(projectRoot, files);
+  const pathHintResolver = buildPathHintResolver(fileIndex);
 
   return {
     projectRoot,
@@ -1060,26 +1285,31 @@ function buildValidationContext(projectRoot, config, plugins) {
     plugins,
     files,
     fileIndex,
+    pathHintResolver,
     testFrameworks
   };
 }
 
 function validateTask(task, context, config, plugins) {
-  const { paths: pathHints, lineReferenceHints } = extractExplicitPaths(task.text);
+  const {
+    paths: pathHints,
+    externalPaths,
+    lineReferenceHints
+  } = extractExplicitPaths(task.text);
   // Paths that are line-reference hints (file.ts:NN) indicate WHERE to implement,
   // not that implementation exists. They are excluded from hasDirectReferencePass.
   const purePathHints = pathHints.filter((p) => !lineReferenceHints.has(p));
   const standaloneFilenames = extractStandaloneFilenames(task.text);
   const symbolHints = extractSymbolHints(task.text);
-  const authoritativeEvidence = evaluateAuthoritativeEvidence(task, context.fileIndex);
+  const authoritativeEvidence = evaluateAuthoritativeEvidence(task, context.pathHintResolver);
 
-  const filesFromPaths = findFilesByPathHints(pathHints, context.fileIndex);
-  const filesFromPurePathHints = findFilesByPathHints(purePathHints, context.fileIndex);
+  const filesFromPaths = findFilesByPathHints(pathHints, context.pathHintResolver);
+  const filesFromPurePathHints = findFilesByPathHints(purePathHints, context.pathHintResolver);
   const filesFromSymbols = findFilesBySymbols(symbolHints, 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 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);
@@ -1143,7 +1373,12 @@ function validateTask(task, context, config, plugins) {
     }
   }
 
-  const requiresTest = !task.noTest && context.testFrameworks.length > 0 && isCodeTask(task.text) && !isDocTask(task.text);
+  const requiresTest =
+    !task.noTest &&
+    context.testFrameworks.length > 0 &&
+    isCodeTask(task.text) &&
+    !isDocTask(task.text) &&
+    !isHttpExpectationTask(task.text);
   const configuredRules = Array.isArray(config.validators) ? config.validators : [];
   const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
   let overrideResult = null;
@@ -1181,13 +1416,14 @@ function validateTask(task, context, config, plugins) {
     uniqueReasons = Array.isArray(overrideResult.reasons) ? Array.from(new Set(overrideResult.reasons)) : [];
   }
 
-  const hasConcreteReferenceEvidence = filesFromPurePathHints.length > 0 || filesFromSymbols.length > 0;
-  const attempted = authoritativeEvidence.active
-    || hasRuleGrantedEvidence
-    || evidence.code
-    || evidence.test
-    || evidence.artifact
-    || hasConcreteReferenceEvidence;
+  const hasConcreteReferenceEvidence = filesFromPaths.length > 0 || filesFromSymbols.length > 0;
+  const hasConcreteAttemptEvidence =
+    authoritativeEvidence.active ||
+    hasRuleGrantedEvidence ||
+    filesFromTests.length > 0 ||
+    hasConcreteReferenceEvidence ||
+    (isDocTask(task.text) && filesFromArtifacts.length > 0);
+  const attempted = hasConcreteAttemptEvidence;
   const { categories: strongEvidenceCategories } = countStrongEvidenceCategories(task.text, evidence);
   const strongEvidenceCount = strongEvidenceCategories.length;
   // Only pure path hints (not line-reference hints like file.ts:169) count as direct evidence.