roadmapsmith 0.9.27 → 0.9.28

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "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,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "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

@@ -28,7 +28,7 @@ npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code
 ```
 
 This is the recommended Claude Code install path for native GUI slash commands such as `/roadmap`, `/roadmap-zero`, `/roadmap-maintain`, `/roadmap-status`, `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`.
-If you install only `--skill roadmap-sync`, Claude GUI will expose only `/roadmap-sync`.
+`roadmap-sync` is deprecated compatibility only; install the full bundle for new workflows and use `/roadmap-maintain` or `/roadmap-update`.
 The skill bundle does not install the CLI and it does not create visible VS Code actions by itself.
 The published `roadmapsmith` package/plugin surface now also ships the shared bundle files for both hosts (`skills.json`, `skills/*`, `.codex-plugin/plugin.json`, `.claude-plugin/plugin.json`) for downstream host installers, but consuming the CLI alone still does not auto-register native Codex or Claude GUI commands.
 
@@ -101,7 +101,11 @@ Use the lower-level commands only when you want manual control over generation,
 | CI | Use disposable checkouts if you run `sync --audit`, because it still mutates the roadmap today. |
 | Other hosts | Use the skill plus manual CLI commands. |
 
-If Node is installed outside PATH, set `ROADMAPSMITH_NODE` to a working `node` executable before using the generated VS Code tasks.
+If Node is installed outside PATH, set `ROADMAPSMITH_NODE` to a working `node` executable before using the generated VS Code tasks. If the globally installed `roadmapsmith` shim itself cannot resolve Node, bypass it in PowerShell with:
+
+```powershell
+& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" <command>
+```
 
 ---
 
@@ -119,6 +123,7 @@ roadmapsmith maintain [--project-root <path>] [--config <path>] [--roadmap-file
 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 update --task <stable-id> --evidence <text> [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]
 roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--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
@@ -183,6 +188,8 @@ The repo does not remove user-global skills automatically. Use the `doctor` outp
   - `- ⚠️ 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.
+- `validate` emits structured diagnostics in human and JSON output (`FAIL:NOT_IMPLEMENTED`, `FAIL:NO_TEST`, `FAIL:MISSING_REFERENCE`, and `WARN:STALE_EVIDENCE`).
+- `update --task <id> --evidence <text>` writes only when the evidence validates at high confidence; otherwise the roadmap is unchanged.
 
 ## Defaults
 

package/bin/cli.js

@@ -4,7 +4,7 @@
 const fs = require('fs');
 const path = require('path');
 const readline = require('node:readline/promises');
-const { parseArgv } = require('../src/utils');
+const { ensureTrailingNewline, parseArgv } = require('../src/utils');
 const { loadConfig, resolveRoadmapFile, resolveAgentsFile, loadPlugins, readUserConfig, resolveConfigPath } = require('../src/config');
 const { readTextIfExists, writeText, printDryRunDiff } = require('../src/io');
 const { buildSetupFiles, applySetupFiles, inspectHostSetup, parseHosts, assertSupportedEditor } = require('../src/host');
@@ -30,6 +30,7 @@ function printHelp() {
     '  roadmapsmith setup [--project-root <path>] [--config <path>] [--editor vscode] [--hosts <codex,claude>] [--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 update --task <stable-id> --evidence <text> [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--dry-run]',
     '  roadmapsmith validate [--roadmap-file <path>] [--project-root <path>] [--config <path>] [--task <id|text>] [--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'
@@ -44,8 +45,13 @@ function isEnabled(value) {
 }
 
 function formatResultLine(task, result) {
-  const status = result.passed ? 'PASS' : 'FAIL';
-  const reason = result.reasons.length > 0 ? ` :: ${result.reasons.join('; ')}` : '';
+  const diagnostics = Array.isArray(result.diagnostics) ? result.diagnostics : [];
+  const primaryError = diagnostics.find((item) => item.severity === 'error');
+  const warnings = diagnostics.filter((item) => item.severity === 'warning');
+  const status = primaryError ? `FAIL:${primaryError.code}` : (result.passed ? 'PASS' : 'FAIL');
+  const parts = [...result.reasons];
+  warnings.forEach((item) => parts.push(`WARN:${item.code} ${item.message}`));
+  const reason = parts.length > 0 ? ` :: ${parts.join('; ')}` : '';
   return `${status} [${task.id}] ${task.text}${reason}`;
 }
 
@@ -215,6 +221,77 @@ function runSyncCommand(projectRoot, config, flags, options = {}) {
   }
 }
 
+function addEvidenceToTask(content, task, evidenceText) {
+  const lines = String(content || '').split(/\r?\n/);
+  const evidenceLine = `${task.indent || ''}  - Evidence: ${evidenceText}`;
+  if (Array.isArray(task.evidenceLines) && task.evidenceLines.length > 0) {
+    lines[task.evidenceLines[0].lineIndex] = evidenceLine;
+    return ensureTrailingNewline(lines.join('\n'));
+  }
+
+  const insertionIndex = task.warningLineIndex != null
+    ? task.warningLineIndex
+    : task.lastChildLineIndex + 1;
+  lines.splice(insertionIndex, 0, evidenceLine);
+  return ensureTrailingNewline(lines.join('\n'));
+}
+
+function runUpdateCommand(projectRoot, config, flags) {
+  const hasTask = flags.task != null;
+  const hasEvidence = flags.evidence != null;
+  if (!hasTask && !hasEvidence) {
+    runSyncCommand(projectRoot, config, flags);
+    return;
+  }
+  if (!hasTask || !hasEvidence || Array.isArray(flags.task) || Array.isArray(flags.evidence)) {
+    throw new Error('update requires exactly one --task <stable-id> and one --evidence <text> value');
+  }
+
+  const taskId = String(flags.task).trim();
+  const evidenceText = String(flags.evidence).trim();
+  if (!taskId || !evidenceText || /[\r\n]/.test(evidenceText)) {
+    throw new Error('update requires a non-empty single-line --task and --evidence value');
+  }
+
+  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 matches = tasksInManagedBlock(parsedRoadmap).filter((task) => task.id === taskId);
+  if (matches.length !== 1) {
+    throw new Error(matches.length === 0
+      ? `Roadmap task not found: ${taskId}`
+      : `Roadmap task ID is ambiguous: ${taskId}`);
+  }
+
+  const draft = addEvidenceToTask(content, matches[0], evidenceText);
+  const draftTask = tasksInManagedBlock(parseRoadmap(draft)).find((task) => task.id === taskId);
+  const validationContext = buildValidationContext(projectRoot, config, loadPlugins(projectRoot, config.plugins));
+  const result = validateTasks([draftTask], validationContext, config, validationContext.plugins)[taskId];
+  const errors = (result.diagnostics || []).filter((item) => item.severity === 'error');
+  const suppliedEvidenceResolved = result.evidence.authoritative && result.evidence.authoritativeFiles.length > 0;
+  if (!suppliedEvidenceResolved || !result.passed || result.confidence !== 'high' || errors.length > 0) {
+    const reasons = result.reasons.length > 0 ? `: ${result.reasons.join('; ')}` : '';
+    throw new Error(`Task ${taskId} was not updated; supplied evidence must resolve in the repository and validate at high confidence${reasons}`);
+  }
+
+  const next = applySync(draft, [draftTask], { [taskId]: result });
+  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}`);
+  }
+}
+
 function printHumanStatus(payload) {
   console.log('RoadmapSmith status\n');
   console.log(`Project root: ${payload.projectRoot}`);
@@ -343,6 +420,8 @@ async function run() {
     if (slashAction.id === 'audit') {
       flags.audit = true;
       effectiveCommand = 'sync';
+    } else if (slashAction.id === 'sync' && String(command).trim().toLowerCase() === '/roadmap-update') {
+      effectiveCommand = 'update';
     } else {
       effectiveCommand = slashAction.id;
     }
@@ -411,6 +490,13 @@ async function run() {
     return;
   }
 
+  if (effectiveCommand === 'update') {
+    const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
+    const config = loadConfig({ projectRoot, configPath: flags.config });
+    runUpdateCommand(projectRoot, config, flags);
+    return;
+  }
+
   if (effectiveCommand === 'validate') {
     const projectRoot = path.resolve(String(flags['project-root'] || process.cwd()));
     const config = loadConfig({ projectRoot, configPath: flags.config });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.27",
+  "version": "0.9.28",
   "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": {

package/skills/roadmap/SKILL.md

@@ -13,7 +13,7 @@ Use this command as the native discovery entrypoint for the shared RoadmapSmith
 2. When working inside the RoadmapSmith repository itself and `roadmap-skill/bin/cli.js` exists, prefer the local engine:
    - `node roadmap-skill/bin/cli.js /roadmap`
    - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js /roadmap` if `node` is not in PATH
-3. Otherwise, if the `roadmapsmith` CLI is available, you may run `roadmapsmith /roadmap` from the project root and use that output directly.
+3. Otherwise, if the `roadmapsmith` CLI is available, you may run `roadmapsmith /roadmap` from the project root and use that output directly. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" /roadmap`.
 4. If the CLI is missing, provide the palette manually and explain the install path:
    - `npm install -g roadmapsmith`
    - `npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code`

package/skills/roadmap-maintain/SKILL.md

@@ -12,7 +12,8 @@ Use this command when the repository already has code, tests, docs, or an existi
 1. Prefer the local engine inside this repository:
    - `node roadmap-skill/bin/cli.js maintain --project-root .`
    - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js maintain --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith maintain --project-root .`.
+2. Otherwise prefer `roadmapsmith maintain --project-root .`. If that global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" maintain --project-root .`.
 3. Treat this command as CLI-backed. Do not silently replace it with manual reasoning when the CLI is unavailable.
 4. Mention that maintain runs preserve-first generate, sync, and audit in one invocation.
-5. Mention that `roadmapsmith maintain --full-regen` or `roadmapsmith generate --full-regen` is the explicit destructive rebuild path when the user truly wants a full managed-block replacement.
+5. After a successful maintain cycle, do not propose generate, sync, or audit separately unless the user needs manual control or inspection.
+6. Mention that `roadmapsmith maintain --full-regen` or `roadmapsmith generate --full-regen` is the explicit destructive rebuild path when the user truly wants a full managed-block replacement.

package/skills/roadmap-status/SKILL.md

@@ -12,6 +12,6 @@ Use this command to inspect whether the shared bundle, native host surfaces, CLI
 1. Prefer the local engine inside this repository:
    - `node roadmap-skill/bin/cli.js doctor --json --project-root .`
    - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js doctor --json --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith doctor --json --project-root .`.
+2. Otherwise prefer `roadmapsmith doctor --json --project-root .`. If its global shim cannot resolve `node`, use `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" doctor --json --project-root .`.
 3. Parse and summarize the JSON output in plain language.
 4. Explicitly call out missing commands or duplicate `/roadmap-sync` registration when doctor reports them.

package/skills/roadmap-sync/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: roadmap-sync
-description: Legacy namespaced root and policy guidance for RoadmapSmith slash workflows.
+description: DEPRECATED legacy root for RoadmapSmith slash workflows; use roadmap-maintain or roadmap-update.
 ---
 
-# RoadmapSmith Legacy Root
+# RoadmapSmith Legacy Root (Deprecated)
 
-Use this skill when the host exposes or the user invokes `/roadmap-sync`, or when the agent needs the RoadmapSmith operating rules for roadmap maintenance.
+Use this skill only when the host exposes or the user explicitly invokes `/roadmap-sync`. For new work, use `/roadmap-maintain` for the daily flow or `/roadmap-update` for evidence-backed completion.
 
 ## Required behavior
 

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

@@ -1,7 +1,7 @@
 {
   "interface": {
-    "display_name": "Roadmap Sync",
-    "short_description": "Legacy root plus policy for evidence-backed ROADMAP.md slash workflows.",
+    "display_name": "Roadmap Sync (Deprecated)",
+    "short_description": "DEPRECATED legacy root; use /roadmap-maintain or /roadmap-update.",
     "default_prompt": "Prefer /roadmap, /roadmap-status, /roadmap-maintain, and /roadmap-update."
   }
 }

package/skills/roadmap-update/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: roadmap-update
-description: Apply evidence-backed checklist sync through the RoadmapSmith CLI.
+description: Apply evidence-backed checklist sync or complete one task with verified evidence through the RoadmapSmith CLI.
 ---
 
 # RoadmapSmith Update
@@ -10,8 +10,9 @@ Use this command when the user wants the direct sync surface without routing thr
 ## Required behavior
 
 1. Prefer the local engine inside this repository:
-   - `node roadmap-skill/bin/cli.js sync --project-root .`
-   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js sync --project-root .` if `node` is not in PATH
-2. Otherwise prefer `roadmapsmith sync --project-root .`.
+   - `node roadmap-skill/bin/cli.js update --project-root .`
+   - on this Windows machine, prefer `C:\Program Files\nodejs\node.exe roadmap-skill/bin/cli.js update --project-root .` if `node` is not in PATH
+2. Otherwise prefer `roadmapsmith update --project-root .`. If that global shim fails because `node` is not in PATH, run `& "C:\Program Files\nodejs\node.exe" "$env:APPDATA\npm\node_modules\roadmapsmith\bin\cli.js" update --project-root .`.
 3. Explain that `/roadmap-update` is the visible namespaced sync command, while `/roadmap-sync <action>` remains legacy compatibility.
-4. Keep the evidence-backed sync semantics unchanged: sync updates checklist state from repository evidence; it is not a full regeneration path.
+4. Keep the evidence-backed sync semantics unchanged: no-argument update syncs the roadmap from repository evidence; it is not a full regeneration path.
+5. To complete one task, run `roadmapsmith update --task <stable-id> --evidence "<single-line evidence>"`. It writes only after the supplied evidence validates at high confidence; use `--dry-run` to preview it.

package/skills.json

@@ -10,86 +10,85 @@
   ],
   "usageExamples": [
     "npx skills add PapiScholz/roadmapsmith --skill '*' -a claude-code",
-    "npx skills add PapiScholz/roadmapsmith --skill roadmap-sync",
     "roadmapsmith setup",
     "roadmapsmith zero",
     "roadmapsmith maintain",
     "roadmapsmith /roadmap",
-    "roadmapsmith /roadmap-update",
+    "roadmapsmith update --task p2-customer-history --evidence \"src/app/api/customers/route.ts, test/customers.test.js\"",
     "roadmapsmith validate --json"
   ],
   "install": {
     "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; 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."
+    "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. DEPRECATED: /roadmap-sync remains only as a compatibility root for existing automation; use /roadmap-maintain or /roadmap-update for new workflows. 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.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-zero",
       "path": "skills/roadmap-zero",
       "description": "Native slash entrypoint for the one-command Zero Mode CLI workflow.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-maintain",
       "path": "skills/roadmap-maintain",
       "description": "Native slash entrypoint for the preserve-first generate + sync + audit flow.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-init",
       "path": "skills/roadmap-init",
       "description": "Native slash entrypoint for creating ROADMAP.md and AGENTS.md.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "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.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-update",
       "path": "skills/roadmap-update",
-      "description": "Native slash entrypoint for applying evidence-backed checklist sync.",
-      "version": "0.9.27"
+      "description": "Native slash entrypoint for evidence-backed sync and verified single-task completion.",
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-sync",
       "path": "skills/roadmap-sync",
-      "description": "Legacy namespaced root plus policy guidance for RoadmapSmith slash workflows.",
-      "version": "0.9.27"
+      "description": "DEPRECATED legacy compatibility root; use roadmap-maintain or roadmap-update.",
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-audit",
       "path": "skills/roadmap-audit",
       "description": "Native slash entrypoint for the current sync-plus-audit workflow.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.27"
+      "version": "0.9.28"
     }
   ]
 }

package/src/sync/index.js

@@ -142,6 +142,18 @@ function applySync(content, parsedTasks, results) {
         lines.splice(warningIndex, 1);
         offset -= 1;
       }
+      if (
+        result.staleEvidenceResolved &&
+        (!Array.isArray(task.evidenceLines) || task.evidenceLines.length === 0) &&
+        result.discoveredEvidence
+      ) {
+        const insertionIndex = Math.max(
+          lineIndex + 1,
+          (task.lastChildLineIndex + offset) + 1
+        );
+        lines.splice(insertionIndex, 0, `${task.indent || ''}  - Evidence: ${result.discoveredEvidence}`);
+        offset += 1;
+      }
       continue;
     }
 

package/src/validator/index.js

@@ -1290,6 +1290,52 @@ function buildValidationContext(projectRoot, config, plugins) {
   };
 }
 
+function diagnosticCodeForReason(reason) {
+  const normalized = String(reason || '').toLowerCase();
+  if (normalized.includes('missing referenced file') || normalized.includes('evidence file(s) not found')) {
+    return 'MISSING_REFERENCE';
+  }
+  if (normalized.includes('missing test evidence')) {
+    return 'NO_TEST';
+  }
+  if (
+    normalized.includes('no code, test, or artifact evidence found') ||
+    normalized.includes('implementation task requires evidence line') ||
+    normalized.includes('weak path') ||
+    normalized.includes('file reference shows implementation location')
+  ) {
+    return 'NOT_IMPLEMENTED';
+  }
+  return null;
+}
+
+function buildDiagnostics(reasons, options = {}) {
+  const diagnostics = [];
+  const seen = new Set();
+  for (const reason of Array.isArray(reasons) ? reasons : []) {
+    const code = diagnosticCodeForReason(reason);
+    if (!code || seen.has(code)) {
+      continue;
+    }
+    seen.add(code);
+    diagnostics.push({ code, severity: 'error', message: reason });
+  }
+  if (options.staleEvidence) {
+    diagnostics.push({
+      code: 'STALE_EVIDENCE',
+      severity: 'warning',
+      message: 'historical validation warning conflicts with fresh repository evidence'
+    });
+  }
+  return diagnostics;
+}
+
+function buildDiscoveredEvidenceLine(evidence) {
+  const files = unionArrays(evidence.codeFiles, evidence.testFiles)
+    .sort((left, right) => left.localeCompare(right));
+  return files.length > 0 ? files.join(', ') : null;
+}
+
 function validateTask(task, context, config, plugins) {
   const {
     paths: pathHints,
@@ -1467,8 +1513,15 @@ function validateTask(task, context, config, plugins) {
   // evidence, artifact evidence, or strong code+test threshold to pass.
   // Already-checked tasks with found path hints are preserved via shouldPreserveCheckedTask.
   const hasHighConfidenceImplementationEvidence = meetsStrongThreshold && evidence.code && evidence.test;
+  const hasFreshRepositoryEvidence = hasStrongEvidence || hasWeakEvidence;
+  let staleEvidenceDetected = false;
+  let staleEvidenceResolved = false;
   let passed = authoritativeEvidence.passed || hasArtifactTaskPass || hasTrustedRuleEvidencePass || meetsStrongThreshold;
 
+  if (task.warningText && !task.checked && hasFreshRepositoryEvidence && !authoritativeEvidence.passed) {
+    staleEvidenceDetected = true;
+  }
+
   if (!passed && !task.checked && hasDirectReferencePass) {
     const locationReason = 'file reference shows implementation location, not confirmed completion';
     if (!uniqueReasons.includes(locationReason)) {
@@ -1476,13 +1529,15 @@ function validateTask(task, context, config, plugins) {
     }
   }
 
-  // Unchecked tasks with an existing ⚠️ warning are preserved as failing unless an Evidence line
-  // explicitly confirms implementation. meetsStrongThreshold (token match) cannot override a
-  // human/agent judgment that the feature is incomplete.
+  // Historical warnings are only cleared by independent, high-confidence repository evidence.
   if (task.warningText && !task.checked && passed && !authoritativeEvidence.passed) {
-    passed = false;
-    if (uniqueReasons.length === 0) {
-      uniqueReasons.push('validation failed');
+    if (hasHighConfidenceImplementationEvidence && negativeSignalMatches.length === 0 && uniqueReasons.length === 0) {
+      staleEvidenceResolved = true;
+    } else {
+      passed = false;
+      if (uniqueReasons.length === 0) {
+        uniqueReasons.push('validation failed');
+      }
     }
   }
   if (negativeSignalMatches.length > 0) {
@@ -1533,17 +1588,21 @@ function validateTask(task, context, config, plugins) {
   // Used by auditValidation to flag implementation tasks that pass solely via documentation.
   const evidenceIsDocOnly = !evidence.code && !evidence.test && evidence.artifact && !isDocTask(task.text);
 
+  const finalPassed = overrideResult ? overrideResult.passed !== false : (passed && uniqueReasons.length === 0);
   return {
     taskId: task.id,
-    passed: overrideResult ? overrideResult.passed !== false : (passed && uniqueReasons.length === 0),
+    passed: finalPassed,
     confidence,
     reasons: uniqueReasons,
+    diagnostics: buildDiagnostics(uniqueReasons, { staleEvidence: staleEvidenceDetected }),
     evidence,
     evidenceIsDocOnly,
     requiresTest,
     hasEvidence: hasStrongEvidence || hasWeakEvidence,
     attempted,
-    preservedCheckedState
+    preservedCheckedState,
+    staleEvidenceResolved,
+    discoveredEvidence: staleEvidenceResolved ? buildDiscoveredEvidenceLine(evidence) : null
   };
 }