roadmapsmith 0.9.27 → 0.9.29

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "roadmapsmith",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "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.29",
   "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.
 
@@ -92,6 +92,19 @@ roadmapsmith maintain   # existing repo
 
 Use the lower-level commands only when you want manual control over generation, validation, or sync.
 
+## Deterministic completion
+
+For unchecked implementation tasks, related files and matching test names are candidate signals only. `maintain` completes a task only from explicit `Evidence:` or typed child verification metadata:
+
+```markdown
+- [ ] Enable ESLint builds
+  - Verify: kind=property; file=next.config.js; key=ignoreDuringBuilds; equals=false
+- [ ] Prevent double submit
+  - Verify: kind=behavior; source=src/login.tsx; test=src/__tests__/login.test.tsx; case=disables submit; trigger=fireEvent.click; assertion=toBeDisabled
+```
+
+`contains`, `property`, and `endpoints` are static checks. A behavioral check also requires a fresh `validation.testReports` entry using `format: "vitest-json"`; RoadmapSmith reads reports but never executes tests. Missing proof produces a `Verification recipe:` and a warning rather than a checked box. A fresh passing report is persisted as `Test evidence: file=<test>; case=<case>; status=PASS; verifiedAt=<ISO timestamp>` and becomes stale when it predates the referenced source or test file.
+
 ## Host Support Today
 
 | Host | Current support |
@@ -101,7 +114,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 +136,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
@@ -176,13 +194,14 @@ The repo does not remove user-global skills automatically. Use the `doctor` outp
 - Uses stable task IDs: `<!-- rs:task=<slug> -->`.
 - Sync marks `[x]` only when validation passes.
 - `sync --audit` currently runs sync and then prints a mismatch summary; it is not yet a dedicated read-only audit mode.
-- Validation evidence gate:
-  - code OR test OR artifact evidence required.
-  - test evidence required for code tasks when test frameworks are detected.
+- For unchecked implementation tasks, heuristic code/test/path matches are candidates only. Completion requires explicit `Evidence:`, a trusted validator rule, or typed deterministic `Verify:` metadata.
+- `Verify:` supports `contains`, `property`, `endpoints`, and `behavior`; behavior additionally requires a fresh configured Vitest JSON report or a fresh `Test evidence:` annotation.
 - Validation failures in sync write warning lines:
   - `- ⚠️ 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, including `FAIL:NOT_IMPLEMENTED`, `FAIL:NO_TEST`, `FAIL:MISSING_REFERENCE`, `FAIL:WRONG_VALUE`, `FAIL:PARTIAL`, `WARN:STALE_EVIDENCE`, `WARN:REQUIRES_HUMAN_EVIDENCE`, `WARN:NO_STATIC_SIGNAL`, `WARN:HAS_EXPLICIT_PENDING`, and `WARN:STALE_TEST_REPORT`.
+- `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,15 @@ 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' : (warnings[0] ? `WARN:${warnings[0].code}` : '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 +223,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 +422,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 +492,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.29",
   "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
 
@@ -17,4 +17,4 @@ Use this skill when the host exposes or the user invokes `/roadmap-sync`, or whe
    - `/roadmap-status`
    - `/roadmap-init`, `/roadmap-generate`, `/roadmap-validate`, `/roadmap-update`, `/roadmap-audit`, and `/roadmap-setup`
 3. When the user explicitly invokes `/roadmap-sync <action>`, route to the matching CLI-backed action without changing semantics and mention the migration path to `/roadmap <action>` or the direct `/roadmap-*` command.
-4. Preserve the operating rules for evidence-backed roadmap maintenance and checklist synchronization.
+4. Preserve the operating rules for evidence-backed roadmap maintenance and checklist synchronization: heuristic file/token matches may diagnose candidates, but only explicit `Evidence:` or typed `Verify:` checks may complete an unchecked implementation task. Never claim a behavioral task is complete without fresh test evidence or human verification.

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.29"
     },
     {
       "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.29"
     },
     {
       "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.29"
     },
     {
       "name": "roadmap-status",
       "path": "skills/roadmap-status",
       "description": "Native slash readiness check grounded in roadmapsmith status JSON.",
-      "version": "0.9.27"
+      "version": "0.9.29"
     },
     {
       "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.29"
     },
     {
       "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.29"
     },
     {
       "name": "roadmap-validate",
       "path": "skills/roadmap-validate",
       "description": "Native slash entrypoint for evidence-backed roadmap validation.",
-      "version": "0.9.27"
+      "version": "0.9.29"
     },
     {
       "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.29"
     },
     {
       "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.29"
     },
     {
       "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.29"
     },
     {
       "name": "roadmap-setup",
       "path": "skills/roadmap-setup",
       "description": "Native slash entrypoint for generating RoadmapSmith host integration files.",
-      "version": "0.9.27"
+      "version": "0.9.29"
     }
   ]
 }

package/src/config.js

@@ -31,7 +31,9 @@ const DEFAULT_CONFIG = {
     doneCriteria: []
   },
   validation: {
-    minimumConfidence: 'low'
+    minimumConfidence: 'low',
+    testReports: [],
+    recipeCommand: ''
   },
   milestones: [
     { version: 'v0.1', goal: 'Foundation baseline complete' },
@@ -95,7 +97,10 @@ function mergeConfig(userConfig) {
     },
     validation: {
       ...DEFAULT_CONFIG.validation,
-      ...((userConfig && userConfig.validation) || {})
+      ...((userConfig && userConfig.validation) || {}),
+      testReports: userConfig && userConfig.validation && Array.isArray(userConfig.validation.testReports)
+        ? userConfig.validation.testReports
+        : DEFAULT_CONFIG.validation.testReports
     }
   };
 }

package/src/io.js

@@ -13,7 +13,9 @@ const DEFAULT_IGNORED_DIRS = new Set([
   '.turbo',
   '.cache',
   'dist',
+  'dist-electron',
   'build',
+  'out',
   'coverage',
   'target',
   'node_modules',

package/src/parser/index.js

@@ -89,6 +89,26 @@ function parseEvidenceLine(content) {
   return content.slice(9).trim();
 }
 
+function parsePrefixedChildLine(content, prefix) {
+  const normalizedPrefix = `${prefix}:`;
+  if (content.slice(0, normalizedPrefix.length).toLowerCase() !== normalizedPrefix.toLowerCase()) {
+    return null;
+  }
+  return content.slice(normalizedPrefix.length).trim();
+}
+
+function parseVerifyLine(content) {
+  return parsePrefixedChildLine(content, 'Verify');
+}
+
+function parseTestEvidenceLine(content) {
+  return parsePrefixedChildLine(content, 'Test evidence');
+}
+
+function parseVerificationRecipeLine(content) {
+  return parsePrefixedChildLine(content, 'Verification recipe');
+}
+
 function parseWarningLine(content) {
   if (!content.startsWith(WARNING_PREFIX)) return null;
   let normalized = content.slice(WARNING_PREFIX.length).trim();
@@ -132,6 +152,10 @@ function parseRoadmap(content) {
     let warningLineIndex = null;
     let warningText = null;
     const evidenceLines = [];
+    const verifyLines = [];
+    const testEvidenceLines = [];
+    const explicitPendingItems = [];
+    let verificationRecipeLineIndex = null;
     const blockedByIds = [];
     let lastChildLineIndex = index;
     for (let childIndex = index + 1; childIndex < lines.length; childIndex += 1) {
@@ -162,6 +186,28 @@ function parseRoadmap(content) {
         });
       }
 
+      const verifyText = parseVerifyLine(childBullet.content);
+      if (verifyText != null) {
+        verifyLines.push({ lineIndex: childIndex, text: verifyText, raw: childLine });
+      }
+
+      const testEvidenceText = parseTestEvidenceLine(childBullet.content);
+      if (testEvidenceText != null) {
+        testEvidenceLines.push({ lineIndex: childIndex, text: testEvidenceText, raw: childLine });
+      }
+
+      const verificationRecipeText = parseVerificationRecipeLine(childBullet.content);
+      if (verificationRecipeText != null) {
+        verificationRecipeLineIndex = childIndex;
+      }
+
+      if (childBullet.content.startsWith('❌')) {
+        explicitPendingItems.push({
+          lineIndex: childIndex,
+          text: childBullet.content.slice('❌'.length).trim()
+        });
+      }
+
       const warningTextValue = parseWarningLine(childBullet.content);
       if (warningTextValue != null) {
         warningLineIndex = childIndex;
@@ -190,6 +236,10 @@ function parseRoadmap(content) {
       warningLineIndex,
       warningText,
       evidenceLines,
+      verifyLines,
+      testEvidenceLines,
+      verificationRecipeLineIndex,
+      explicitPendingItems,
       blockedByIds,
       markerId,
       noTest,

package/src/sync/index.js

@@ -112,6 +112,23 @@ function shouldPreserveExistingWarning(existingReason, newReason) {
   return cleanNew === 'validation failed' && cleanExisting && cleanExisting !== cleanNew;
 }
 
+function formatVerificationRecipe(indent, recipe) {
+  return `${indent}  - Verification recipe: ${recipe}`;
+}
+
+function formatTestEvidence(indent, evidence) {
+  return `${indent}  - Test evidence: ${evidence}`;
+}
+
+function findVerificationRecipeIndex(lines, taskLineIndex) {
+  for (let index = taskLineIndex + 1; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim() || /^\s*#{2,}\s/.test(line) || /^\s*- \[[ xX]\]\s/.test(line)) break;
+    if (/^\s*- Verification recipe:/i.test(line)) return index;
+  }
+  return null;
+}
+
 function applySync(content, parsedTasks, results) {
   const parsed = parseRoadmap(content);
   const lines = [...parsed.lines];
@@ -142,10 +159,32 @@ function applySync(content, parsedTasks, results) {
         lines.splice(warningIndex, 1);
         offset -= 1;
       }
-      continue;
-    }
-
-    if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
+      const recipeIndex = findVerificationRecipeIndex(lines, lineIndex);
+      if (recipeIndex != null && recipeIndex >= 0 && recipeIndex < lines.length) {
+        lines.splice(recipeIndex, 1);
+        offset -= 1;
+      }
+      if (
+        result.generatedTestEvidence &&
+        (!Array.isArray(task.testEvidenceLines) || task.testEvidenceLines.length === 0)
+      ) {
+        const insertionIndex = Math.max(lineIndex + 1, (task.lastChildLineIndex + offset) + 1);
+        lines.splice(insertionIndex, 0, formatTestEvidence(task.indent || '', result.generatedTestEvidence));
+        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;
+      }
+    } else if (warningIndex != null && warningIndex >= 0 && warningIndex < lines.length) {
       const existingReason = normalizeWarningReason(lines[warningIndex]);
       const newReason = reason || 'validation failed';
       if (!shouldPreserveExistingWarning(existingReason, newReason)) {
@@ -155,6 +194,23 @@ function applySync(content, parsedTasks, results) {
       lines.splice(lastChildLineIndex + 1, 0, warningText);
       offset += 1;
     }
+
+    const recipeIndex = findVerificationRecipeIndex(lines, lineIndex);
+    if (result.passed) {
+      continue;
+    }
+    if (result.verificationRecipe) {
+      const recipeLine = formatVerificationRecipe(task.indent || '', result.verificationRecipe);
+      if (recipeIndex != null && recipeIndex >= 0 && recipeIndex < lines.length) {
+        lines[recipeIndex] = recipeLine;
+      } else {
+        lines.splice(lastChildLineIndex + 1, 0, recipeLine);
+        offset += 1;
+      }
+    } else if (recipeIndex != null && recipeIndex >= 0 && recipeIndex < lines.length) {
+      lines.splice(recipeIndex, 1);
+      offset -= 1;
+    }
   }
 
   return ensureTrailingNewline(lines.join('\n'));

package/src/validator/index.js

@@ -13,6 +13,7 @@ const CODE_EXTENSIONS = new Set([
 ]);
 const TRANSLATION_DIR_SEGMENTS = ['locale', 'locales', 'i18n', 'translations'];
 const DEFAULT_EXCLUDED_PATH_PREFIXES = ['.claude/', '.agent/', 'roadmap-skill/'];
+const GENERATED_OUTPUT_PREFIXES = ['dist-electron/', 'dist/', 'build/', 'out/', '.next/', 'coverage/'];
 
 // "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'];
@@ -151,6 +152,11 @@ function isMostlyUiStrings(content) {
   return stringLikeLines / lines.length > 0.8;
 }
 
+function isGeneratedOutputPath(relativePath) {
+  const normalized = normalizePathForMatch(relativePath);
+  return GENERATED_OUTPUT_PREFIXES.some((prefix) => normalized.startsWith(prefix));
+}
+
 function readFileIndex(projectRoot, files, config) {
   const index = [];
   for (const relativePath of files) {
@@ -180,6 +186,7 @@ function readFileIndex(projectRoot, files, config) {
       absolutePath,
       ext,
       content,
+      generatedOutput: isGeneratedOutputPath(relativePath),
       isTestFile: /(^|\/)(__tests__|tests)\//.test(relativePath) || /\.test\.|\.spec\.|_test\.go$/.test(relativePath)
     });
   }
@@ -631,6 +638,7 @@ function findFilesBySymbols(symbolHints, fileIndex) {
   for (const symbol of symbolHints) {
     const regex = new RegExp(`\\b${escapeRegExp(symbol)}\\b`, 'i');
     for (const file of fileIndex) {
+      if (file.generatedOutput) continue;
       if (!CODE_EXTENSIONS.has(file.ext)) {
         continue;
       }
@@ -650,6 +658,7 @@ function findFilesByTaskPathTokens(taskText, fileIndex, pathDerivedTokens = new
 
   const matches = new Set();
   for (const file of fileIndex) {
+    if (file.generatedOutput) continue;
     const pathSegments = normalizePathForMatch(file.relativePath).split('/').filter(Boolean);
     for (const token of tokens) {
       if (pathSegments.some((segment) => segment === token || segment.includes(token))) {
@@ -744,7 +753,7 @@ function findCodeEvidence(taskText, fileIndex, pathDerivedTokens = new Set()) {
 
   const matches = [];
   for (const file of fileIndex) {
-    if (!CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
+    if (file.generatedOutput || !CODE_EXTENSIONS.has(file.ext) || file.isTestFile) {
       continue;
     }
 
@@ -819,7 +828,7 @@ function findTestEvidence(taskText, fileIndex, referencedPaths = []) {
   const matches = [];
 
   for (const file of fileIndex) {
-    if (!file.isTestFile) continue;
+    if (file.generatedOutput || !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:
@@ -897,6 +906,7 @@ function findArtifactEvidence(taskText, fileIndex) {
   ];
 
   for (const file of fileIndex) {
+    if (file.generatedOutput) continue;
     if (artifactPatterns.some((pattern) => pattern.test(file.relativePath)) && !files.includes(file.relativePath)) {
       files.push(file.relativePath);
     }
@@ -1273,6 +1283,303 @@ function evaluateRule(rule, task, context) {
   };
 }
 
+function parseVerificationFields(text) {
+  const fields = {};
+  for (const part of String(text || '').split(';')) {
+    const separator = part.indexOf('=');
+    if (separator <= 0) continue;
+    const key = part.slice(0, separator).trim().toLowerCase();
+    let value = part.slice(separator + 1).trim();
+    if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+      value = value.slice(1, -1);
+    }
+    if (key && value) fields[key] = value;
+  }
+  return fields;
+}
+
+function stripCodeComments(content) {
+  const source = String(content || '');
+  let result = '';
+  let quote = null;
+  let escaped = false;
+  let lineHasContent = false;
+
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    const next = source[index + 1];
+
+    if (quote) {
+      result += char;
+      if (escaped) {
+        escaped = false;
+      } else if (char === '\\') {
+        escaped = true;
+      } else if (char === quote) {
+        quote = null;
+      }
+      if (char === '\n') lineHasContent = false;
+      continue;
+    }
+
+    if (char === '"' || char === "'" || char === '`') {
+      quote = char;
+      result += char;
+      lineHasContent = true;
+      continue;
+    }
+
+    if (char === '/' && next === '*') {
+      const closeIndex = source.indexOf('*/', index + 2);
+      index = closeIndex < 0 ? source.length : closeIndex + 1;
+      continue;
+    }
+
+    if (char === '/' && next === '/') {
+      const newlineIndex = source.indexOf('\n', index + 2);
+      if (newlineIndex < 0) break;
+      result += '\n';
+      lineHasContent = false;
+      index = newlineIndex;
+      continue;
+    }
+
+    if (char === '#' && !lineHasContent) {
+      const newlineIndex = source.indexOf('\n', index + 1);
+      if (newlineIndex < 0) break;
+      result += '\n';
+      lineHasContent = false;
+      index = newlineIndex;
+      continue;
+    }
+
+    result += char;
+    if (char === '\n') {
+      lineHasContent = false;
+    } else if (!/\s/.test(char)) {
+      lineHasContent = true;
+    }
+  }
+
+  return result;
+}
+
+function findIndexedFile(relativePath, context) {
+  const normalized = normalizeReferencedPath(relativePath);
+  return context.fileIndex.find((file) => !file.generatedOutput && (
+    normalizeReferencedPath(file.relativePath) === normalized ||
+    normalizeReferencedPath(file.relativePath).endsWith('/' + normalized)
+  ));
+}
+
+function readTestReportRecords(projectRoot, validationConfig) {
+  const reports = Array.isArray(validationConfig && validationConfig.testReports)
+    ? validationConfig.testReports
+    : [];
+  const records = [];
+
+  function visit(value, reportPath, mtimeMs) {
+    if (!value || typeof value !== 'object') return;
+    if (Array.isArray(value)) {
+      value.forEach((entry) => visit(entry, reportPath, mtimeMs));
+      return;
+    }
+    const status = String(value.status || value.state || value.result || '').toLowerCase();
+    const file = value.file || value.filepath || value.testFile || value.nameFile;
+    const name = value.fullName || value.fullname || value.name || value.title;
+    if (file && name && /^(pass|passed|success)$/.test(status)) {
+      records.push({ file: String(file), name: String(name), reportPath, mtimeMs });
+    }
+    Object.values(value).forEach((entry) => visit(entry, reportPath, mtimeMs));
+  }
+
+  for (const report of reports) {
+    if (!report || report.format !== 'vitest-json' || !report.path) continue;
+    const reportPath = path.resolve(projectRoot, report.path);
+    try {
+      const payload = JSON.parse(fs.readFileSync(reportPath, 'utf8'));
+      const mtimeMs = fs.statSync(reportPath).mtimeMs;
+      visit(payload, reportPath, mtimeMs);
+    } catch {
+      // A missing or malformed optional report is simply unavailable evidence.
+    }
+  }
+  return records;
+}
+
+function timestampIsFresh(timestamp, files) {
+  const verifiedAt = Date.parse(timestamp || '');
+  if (!Number.isFinite(verifiedAt)) return false;
+  return files.every((file) => {
+    try {
+      return verifiedAt >= fs.statSync(file.absolutePath).mtimeMs;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function findFreshTestProof(task, fields, context) {
+  const testFile = findIndexedFile(fields.test || fields.file, context);
+  const sourceFile = fields.source ? findIndexedFile(fields.source, context) : null;
+  const caseName = fields.case;
+  if (!testFile || !caseName) return { passed: false, available: false };
+  const freshnessFiles = [testFile, ...(sourceFile ? [sourceFile] : [])];
+  const evidenceLines = Array.isArray(task.testEvidenceLines) ? task.testEvidenceLines : [];
+  for (const line of evidenceLines) {
+    const evidence = parseVerificationFields(line.text);
+    if (String(evidence.status || '').toUpperCase() !== 'PASS') continue;
+    if (normalizeReferencedPath(evidence.file) !== normalizeReferencedPath(testFile.relativePath)) continue;
+    if (evidence.case !== caseName) continue;
+    if (timestampIsFresh(evidence.verifiedat, freshnessFiles)) {
+      return { passed: true, available: true };
+    }
+    return { passed: false, available: true, stale: true };
+  }
+  for (const record of context.testReportRecords || []) {
+    if (!referencedPathMatches(record.file, testFile.relativePath) || !record.name.includes(caseName)) continue;
+    if (record.mtimeMs >= Math.max(...freshnessFiles.map((file) => fs.statSync(file.absolutePath).mtimeMs))) {
+      return {
+        passed: true,
+        available: true,
+        generatedEvidence: `file=${testFile.relativePath}; case=${caseName}; status=PASS; verifiedAt=${new Date(record.mtimeMs).toISOString()}`
+      };
+    }
+    return { passed: false, available: true, stale: true };
+  }
+  return { passed: false, available: false };
+}
+
+function testCoversEndpoint(testFile, route, context) {
+  const normalizedRoute = String(route).replace(/\[([^\]]+)\]/g, '$1').toLowerCase();
+  const normalizedContent = testFile.content.replace(/\[([^\]]+)\]/g, '$1').toLowerCase();
+  if (normalizedContent.includes(normalizedRoute)) return true;
+  const source = findIndexedFile(`src/app${route}/route.ts`, context);
+  if (source && normalizedContent.includes(path.basename(source.relativePath, source.ext).toLowerCase())) return true;
+  const segments = normalizedRoute.split('/').filter((segment) => segment.length >= 3);
+  return segments.length > 0 && segments.every((segment) => normalizedContent.includes(segment));
+}
+
+function findVerificationRecipe(task, context) {
+  const patterns = [
+    /disabled\s*=\s*\{[^}]+\}/i,
+    /<(?:dialog|alertdialog)\b[^>]*\bopen\s*=/i,
+    /abortcontroller|abortsignal\.timeout/i,
+    /router\.push\s*\(/i
+  ];
+  for (const file of context.fileIndex) {
+    if (file.generatedOutput || file.isTestFile || !CODE_EXTENSIONS.has(file.ext)) continue;
+    const match = patterns.map((pattern) => pattern.exec(file.content)).find(Boolean);
+    if (!match) continue;
+    const line = file.content.slice(0, match.index).split(/\r?\n/).length;
+    const command = context.config.validation && context.config.validation.recipeCommand
+      ? `; run ${String(context.config.validation.recipeCommand).replace('{testFile}', '<test-file>')}`
+      : '';
+    return `${file.relativePath}:${line} inspect ${match[0].trim()}${command}`;
+  }
+  return null;
+}
+
+function isBehavioralTask(taskText) {
+  return /\b(mostrar|deshabilitar|confirmar|notificar|redirigir|imprimir|show|disable|confirm|notify|redirect|print)\b/i.test(String(taskText || ''));
+}
+
+function evaluateDeterministicVerification(task, context) {
+  const verifyLines = Array.isArray(task.verifyLines) ? task.verifyLines : [];
+  if (verifyLines.length === 0) {
+    if (!isBehavioralTask(task.text)) {
+      return { applicable: false, passed: false, reasons: [], diagnostics: [], recipe: null };
+    }
+    const recipe = findVerificationRecipe(task, context);
+    return {
+      applicable: false,
+      passed: false,
+      reasons: [],
+      diagnostics: [{
+        code: recipe ? 'REQUIRES_HUMAN_EVIDENCE' : 'NO_STATIC_SIGNAL',
+        severity: 'warning',
+        message: recipe ? 'behavioral task requires explicit human or test evidence' : 'no static implementation signal was found for behavioral task'
+      }],
+      recipe
+    };
+  }
+  const reasons = [];
+  const diagnostics = [];
+  let generatedTestEvidence = null;
+
+  for (const line of verifyLines) {
+    const fields = parseVerificationFields(line.text);
+    const kind = fields.kind;
+    if (kind === 'contains' || kind === 'property') {
+      const file = findIndexedFile(fields.file, context);
+      if (!file) {
+        reasons.push(`missing referenced file(s): ${fields.file || '<unspecified>'}`);
+        continue;
+      }
+      const content = stripCodeComments(file.content);
+      if (kind === 'contains') {
+        if (!fields.expected || !content.includes(fields.expected)) {
+          reasons.push(`no content match in ${file.relativePath}: expected ${fields.expected || '<unspecified>'}`);
+        }
+        continue;
+      }
+      const keyPattern = new RegExp(`\\b${escapeRegExp(fields.key || '')}\\s*:`);
+      const exactPattern = new RegExp(`\\b${escapeRegExp(fields.key || '')}\\s*:\\s*${escapeRegExp(fields.equals || '')}(?=\\s*[,}\\n])`);
+      if (!exactPattern.test(content)) {
+        reasons.push(keyPattern.test(content)
+          ? `wrong value for ${fields.key} in ${file.relativePath}: expected ${fields.equals}`
+          : `no content match in ${file.relativePath}: expected ${fields.key}: ${fields.equals}`);
+      }
+      continue;
+    }
+    if (kind === 'endpoints') {
+      const routes = String(fields.routes || '').split(',').map((value) => value.trim()).filter(Boolean);
+      const tests = context.fileIndex.filter((file) => !file.generatedOutput && file.isTestFile);
+      const covered = routes.filter((route) => tests.some((file) => testCoversEndpoint(file, route, context)));
+      if (covered.length !== routes.length) {
+        const missing = routes.filter((route) => !covered.includes(route));
+        reasons.push(`partial endpoint coverage ${covered.length}/${routes.length}: missing ${missing.join(', ')}`);
+      }
+      continue;
+    }
+    if (kind === 'behavior') {
+      const source = findIndexedFile(fields.source, context);
+      const testFile = findIndexedFile(fields.test, context);
+      const testContent = testFile ? testFile.content : '';
+      const sourceReference = source && testContent.includes(path.basename(source.relativePath, source.ext));
+      const exercise = fields.trigger && testContent.includes(fields.trigger);
+      const assertion = fields.assertion && testContent.includes(fields.assertion);
+      const namedCase = fields.case && testContent.includes(fields.case);
+      const proof = findFreshTestProof(task, fields, context);
+      if (!source || !testFile || !sourceReference || !exercise || !assertion || !namedCase) {
+        diagnostics.push({ code: 'REQUIRES_HUMAN_EVIDENCE', severity: 'warning', message: 'behavior verification needs a source reference, named test, trigger, and assertion' });
+        continue;
+      }
+      if (proof.stale) {
+        diagnostics.push({ code: 'STALE_TEST_REPORT', severity: 'warning', message: `test result for ${testFile.relativePath} predates the verified source` });
+        continue;
+      }
+      if (!proof.passed) {
+        diagnostics.push({ code: 'REQUIRES_HUMAN_EVIDENCE', severity: 'warning', message: `no fresh passing result for ${testFile.relativePath}` });
+        continue;
+      }
+      generatedTestEvidence = proof.generatedEvidence || generatedTestEvidence;
+      continue;
+    }
+    reasons.push(`unsupported verification kind: ${kind || '<unspecified>'}`);
+  }
+
+  const passed = reasons.length === 0 && diagnostics.length === 0;
+  return {
+    applicable: true,
+    passed,
+    reasons,
+    diagnostics,
+    generatedTestEvidence,
+    recipe: passed ? null : findVerificationRecipe(task, context)
+  };
+}
+
 function buildValidationContext(projectRoot, config, plugins) {
   const files = walkFiles(projectRoot);
   const fileIndex = readFileIndex(projectRoot, files, config);
@@ -1286,10 +1593,70 @@ function buildValidationContext(projectRoot, config, plugins) {
     files,
     fileIndex,
     pathHintResolver,
-    testFrameworks
+    testFrameworks,
+    testReportRecords: readTestReportRecords(projectRoot, config.validation)
   };
 }
 
+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('wrong value')) {
+    return 'WRONG_VALUE';
+  }
+  if (normalized.includes('partial endpoint coverage')) {
+    return 'PARTIAL';
+  }
+  if (normalized.includes('no content match')) {
+    return 'NOT_IMPLEMENTED';
+  }
+  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'
+    });
+  }
+  for (const diagnostic of options.extra || []) {
+    if (!diagnostic || !diagnostic.code || diagnostics.some((item) => item.code === diagnostic.code)) continue;
+    diagnostics.push(diagnostic);
+  }
+  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,
@@ -1302,6 +1669,8 @@ function validateTask(task, context, config, plugins) {
   const standaloneFilenames = extractStandaloneFilenames(task.text);
   const symbolHints = extractSymbolHints(task.text);
   const authoritativeEvidence = evaluateAuthoritativeEvidence(task, context.pathHintResolver);
+  const deterministicVerification = evaluateDeterministicVerification(task, context);
+  const hasExplicitPendingItems = Array.isArray(task.explicitPendingItems) && task.explicitPendingItems.length > 0;
 
   const filesFromPaths = findFilesByPathHints(pathHints, context.pathHintResolver);
   const filesFromPurePathHints = findFilesByPathHints(purePathHints, context.pathHintResolver);
@@ -1378,7 +1747,8 @@ function validateTask(task, context, config, plugins) {
     context.testFrameworks.length > 0 &&
     isCodeTask(task.text) &&
     !isDocTask(task.text) &&
-    !isHttpExpectationTask(task.text);
+    !isHttpExpectationTask(task.text) &&
+    !(task.verifyLines || []).some((line) => ['contains', 'property', 'endpoints', 'behavior'].includes(parseVerificationFields(line.text).kind));
   const configuredRules = Array.isArray(config.validators) ? config.validators : [];
   const pluginRules = collectPluginContributions(plugins || [], 'registerValidators', context);
   let overrideResult = null;
@@ -1412,6 +1782,18 @@ function validateTask(task, context, config, plugins) {
 
   let uniqueReasons = Array.from(new Set(reasons));
 
+  if (deterministicVerification.passed) {
+    uniqueReasons = uniqueReasons.filter((reason) => (
+      reason !== 'no code, test, or artifact evidence found' &&
+      reason !== 'missing test evidence' &&
+      !reason.startsWith('weak path-')
+    ));
+  }
+
+  if (deterministicVerification.applicable && deterministicVerification.reasons.length > 0) {
+    uniqueReasons = Array.from(new Set([...uniqueReasons, ...deterministicVerification.reasons]));
+  }
+
   if (overrideResult) {
     uniqueReasons = Array.isArray(overrideResult.reasons) ? Array.from(new Set(overrideResult.reasons)) : [];
   }
@@ -1467,7 +1849,22 @@ 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;
-  let passed = authoritativeEvidence.passed || hasArtifactTaskPass || hasTrustedRuleEvidencePass || meetsStrongThreshold;
+  const hasFreshRepositoryEvidence = hasStrongEvidence || hasWeakEvidence;
+  let staleEvidenceDetected = false;
+  let staleEvidenceResolved = false;
+  // Heuristic proximity remains useful to locate candidates, but is never sufficient to
+  // complete an unchecked task. Completion requires human Evidence, a trusted rule, or a
+  // typed deterministic verifier.
+  let passed = authoritativeEvidence.passed || hasTrustedRuleEvidencePass || deterministicVerification.passed;
+
+  if (!task.checked && !authoritativeEvidence.passed && !hasTrustedRuleEvidencePass && !deterministicVerification.passed && hasHighConfidenceImplementationEvidence) {
+    uniqueReasons.push('implementation task requires deterministic Verify metadata or explicit Evidence to be marked complete');
+    uniqueReasons = Array.from(new Set(uniqueReasons));
+  }
+
+  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';
@@ -1476,19 +1873,31 @@ 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 ((deterministicVerification.passed || hasHighConfidenceImplementationEvidence) && negativeSignalMatches.length === 0 && uniqueReasons.length === 0) {
+      staleEvidenceResolved = true;
+    } else {
+      passed = false;
+      if (uniqueReasons.length === 0) {
+        uniqueReasons.push('validation failed');
+      }
     }
   }
   if (negativeSignalMatches.length > 0) {
     passed = false;
   }
 
+  const extraDiagnostics = [...deterministicVerification.diagnostics];
+  if (hasExplicitPendingItems) {
+    passed = false;
+    extraDiagnostics.push({
+      code: 'HAS_EXPLICIT_PENDING',
+      severity: 'warning',
+      message: `task declares pending item(s): ${task.explicitPendingItems.map((item) => item.text || 'pending').join(', ')}`
+    });
+  }
+
   // Unchecked implementation tasks need explicit evidence or high-confidence implementation
   // evidence. Weak token overlap, direct file references, or code-only matches are not enough.
   if (
@@ -1497,6 +1906,7 @@ function validateTask(task, context, config, plugins) {
     isImplementationTask(task.text) &&
     !authoritativeEvidence.passed &&
     !hasTrustedRuleEvidencePass &&
+    !deterministicVerification.passed &&
     !hasArtifactTaskPass &&
     !hasHighConfidenceImplementationEvidence
   ) {
@@ -1533,17 +1943,23 @@ 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 && !hasExplicitPendingItems) : (passed && uniqueReasons.length === 0 && !hasExplicitPendingItems);
   return {
     taskId: task.id,
-    passed: overrideResult ? overrideResult.passed !== false : (passed && uniqueReasons.length === 0),
+    passed: finalPassed,
     confidence,
     reasons: uniqueReasons,
+    diagnostics: buildDiagnostics(uniqueReasons, { staleEvidence: staleEvidenceDetected, extra: extraDiagnostics }),
     evidence,
     evidenceIsDocOnly,
     requiresTest,
     hasEvidence: hasStrongEvidence || hasWeakEvidence,
     attempted,
-    preservedCheckedState
+    preservedCheckedState,
+    staleEvidenceResolved,
+    discoveredEvidence: staleEvidenceResolved ? buildDiscoveredEvidenceLine(evidence) : null,
+    verificationRecipe: deterministicVerification.recipe,
+    generatedTestEvidence: deterministicVerification.generatedTestEvidence || null
   };
 }