@xenonbyte/da-vinci-workflow 0.2.3 → 0.2.5

package/lib/verify.js

@@ -2,7 +2,6 @@ const fs = require("fs");
 const path = require("path");
 const { STATUS } = require("./workflow-contract");
 const {
-  normalizeText,
   unique,
   resolveImplementationLanding,
   resolveChangeDir,
@@ -13,8 +12,23 @@ const {
   readChangeArtifacts,
   readArtifactTexts
 } = require("./planning-parsers");
+const { readExecutionSignals, summarizeSignalsBySurface } = require("./execution-signals");
+const { normalizeRelativePath, pathWithinRoot } = require("./utils");
 
-const CODE_FILE_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx", ".html", ".css", ".scss"]);
+const CODE_FILE_EXTENSIONS = new Set([
+  ".js",
+  ".jsx",
+  ".ts",
+  ".tsx",
+  ".html",
+  ".css",
+  ".scss",
+  ".vue",
+  ".svelte"
+]);
+const SYNTAX_AWARE_SCRIPT_EXTENSIONS = new Set([".js", ".jsx", ".ts", ".tsx"]);
+const IMPLEMENTATION_MARKUP_EXTENSIONS = new Set([".html", ".vue", ".svelte"]);
+const STRUCTURE_MARKUP_EXTENSIONS = new Set([".html", ".tsx", ".jsx", ".js", ".vue", ".svelte"]);
 const NON_IMPLEMENTATION_DIR_NAMES = new Set([
   ".git",
   ".da-vinci",
@@ -47,6 +61,7 @@ const MAX_SCANNED_FILES = 2000;
 const MAX_SCANNED_BYTES_PER_FILE = 512 * 1024;
 const MAX_SCANNED_DIRECTORIES = 10000;
 const MAX_SCAN_DEPTH = 32;
+const DEFAULT_EVIDENCE_MAX_AGE_MS = 24 * 60 * 60 * 1000;
 
 function buildEnvelope(name, projectRoot, strict) {
   return {
@@ -90,6 +105,58 @@ function isNonImplementationFileName(name) {
   return NON_IMPLEMENTATION_FILE_PATTERNS.some((pattern) => pattern.test(normalized));
 }
 
+function normalizeCoverageText(value) {
+  return String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function tokenizeCoverage(value, minLength = 1) {
+  return normalizeCoverageText(value)
+    .split(" ")
+    .map((token) => token.trim())
+    .filter((token) => token.length >= minLength);
+}
+
+function safeRealpathSync(candidatePath) {
+  try {
+    if (typeof fs.realpathSync.native === "function") {
+      return fs.realpathSync.native(candidatePath);
+    }
+    return fs.realpathSync(candidatePath);
+  } catch (_error) {
+    return null;
+  }
+}
+
+function canonicalizePath(candidatePath) {
+  const resolved = path.resolve(candidatePath);
+  return safeRealpathSync(resolved) || resolved;
+}
+
+function listSummary(items, max = 5) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return "";
+  }
+  const head = items.slice(0, max).join(", ");
+  if (items.length <= max) {
+    return head;
+  }
+  return `${head} ... (+${items.length - max} more)`;
+}
+
+function hasExcludedDirectory(relativePath) {
+  const normalized = normalizeRelativePath(relativePath);
+  if (!normalized) {
+    return false;
+  }
+  const segments = normalized.split("/");
+  const directorySegments = segments.slice(0, -1);
+  return directorySegments.some((segment) => isNonImplementationDirName(segment));
+}
+
 function collectCodeFiles(projectRoot) {
   const files = [];
   const scan = {
@@ -217,13 +284,136 @@ function readCodeFileForScan(filePath) {
   }
 }
 
-function allCovered(checks) {
-  for (const check of checks) {
-    if (!check.covered) {
-      return false;
+function safeMtimeMs(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return Number(stat.mtimeMs) || 0;
+  } catch (_error) {
+    return 0;
+  }
+}
+
+function collectFreshnessBaseline(projectRoot, resolved, artifactPaths) {
+  const baselineCandidates = [];
+  if (artifactPaths) {
+    baselineCandidates.push(
+      artifactPaths.proposalPath,
+      artifactPaths.tasksPath,
+      artifactPaths.bindingsPath,
+      artifactPaths.pencilDesignPath,
+      artifactPaths.verificationPath
+    );
+  }
+  if (resolved && resolved.changeDir) {
+    const specsRoot = path.join(resolved.changeDir, "specs");
+    if (fs.existsSync(specsRoot)) {
+      const stack = [specsRoot];
+      while (stack.length > 0) {
+        const current = stack.pop();
+        let entries = [];
+        try {
+          entries = fs.readdirSync(current, { withFileTypes: true });
+        } catch (_error) {
+          continue;
+        }
+        for (const entry of entries) {
+          const absolutePath = path.join(current, entry.name);
+          if (entry.isDirectory() && !entry.isSymbolicLink()) {
+            stack.push(absolutePath);
+            continue;
+          }
+          if (entry.isFile() && entry.name === "spec.md") {
+            baselineCandidates.push(absolutePath);
+          }
+        }
+      }
+    }
+  }
+  const baselineMs = baselineCandidates.reduce((latest, candidate) => Math.max(latest, safeMtimeMs(candidate)), 0);
+  return {
+    baselineMs,
+    baselineIso: baselineMs > 0 ? new Date(baselineMs).toISOString() : ""
+  };
+}
+
+function collectVerificationFreshness(projectPathInput, options = {}) {
+  const projectRoot = path.resolve(projectPathInput || process.cwd());
+  const changeId = options.changeId ? String(options.changeId).trim() : "";
+  if (!changeId) {
+    return {
+      fresh: false,
+      changeId: null,
+      requiredSurfaces: [],
+      surfaces: {},
+      staleReasons: ["Missing change id for verification freshness checks."],
+      baselineIso: ""
+    };
+  }
+
+  const requiredSurfaces =
+    Array.isArray(options.requiredSurfaces) && options.requiredSurfaces.length > 0
+      ? options.requiredSurfaces
+      : ["verify-bindings", "verify-implementation", "verify-structure", "verify-coverage"];
+  const maxAgeMs =
+    Number.isFinite(Number(options.maxAgeMs)) && Number(options.maxAgeMs) > 0
+      ? Number(options.maxAgeMs)
+      : DEFAULT_EVIDENCE_MAX_AGE_MS;
+  const nowMs = Date.now();
+  const signals = readExecutionSignals(projectRoot, { changeId });
+  const summary = summarizeSignalsBySurface(signals);
+  const baseline = collectFreshnessBaseline(projectRoot, options.resolved, options.artifactPaths);
+  const staleReasons = [];
+  const surfaces = {};
+
+  for (const surface of requiredSurfaces) {
+    const key = String(surface || "").toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    const signal = summary[key];
+    if (!signal) {
+      staleReasons.push(`Missing evidence signal: ${surface}.`);
+      surfaces[surface] = {
+        present: false,
+        stale: true
+      };
+      continue;
+    }
+    const timestampMs = Date.parse(String(signal.timestamp || ""));
+    if (!Number.isFinite(timestampMs)) {
+      staleReasons.push(`Invalid evidence timestamp for ${surface}.`);
+      surfaces[surface] = {
+        present: true,
+        stale: true,
+        timestamp: signal.timestamp || ""
+      };
+      continue;
+    }
+    const olderThanBaseline = baseline.baselineMs > 0 && timestampMs < baseline.baselineMs;
+    const olderThanMaxAge = nowMs - timestampMs > maxAgeMs;
+    if (olderThanBaseline) {
+      staleReasons.push(
+        `${surface} evidence is older than current artifact baseline (${new Date(timestampMs).toISOString()} < ${baseline.baselineIso}).`
+      );
+    }
+    if (olderThanMaxAge) {
+      staleReasons.push(
+        `${surface} evidence is older than freshness window (${Math.round((nowMs - timestampMs) / 1000)}s).`
+      );
     }
+    surfaces[surface] = {
+      present: true,
+      stale: olderThanBaseline || olderThanMaxAge,
+      status: signal.status,
+      timestamp: signal.timestamp
+    };
   }
-  return true;
+
+  return {
+    fresh: staleReasons.length === 0,
+    changeId,
+    requiredSurfaces,
+    surfaces,
+    staleReasons: unique(staleReasons),
+    baselineIso: baseline.baselineIso
+  };
 }
 
 function createSharedSetup(projectPathInput, options = {}) {
@@ -280,6 +470,547 @@ function commonSetup(surface, projectPathInput, options) {
   };
 }
 
+function collectChangedFileEntries(projectRoot, options = {}) {
+  const requested = options.changedFilesProvided === true || Array.isArray(options.changedFiles);
+  const rawEntries = Array.isArray(options.changedFiles)
+    ? options.changedFiles
+    : options.changedFiles === undefined
+      ? []
+      : [options.changedFiles];
+  const resolvedRoot = path.resolve(projectRoot);
+  const canonicalRoot = safeRealpathSync(resolvedRoot) || resolvedRoot;
+
+  const response = {
+    requested,
+    rawEntries: rawEntries.map((value) => String(value || "").trim()).filter(Boolean),
+    entries: [],
+    invalidEntries: [],
+    duplicateEntries: [],
+    missingEntries: [],
+    directoryEntries: [],
+    unreadableEntries: []
+  };
+
+  if (!requested) {
+    return response;
+  }
+
+  const seenInputs = new Set();
+  const seenCanonical = new Set();
+  for (const rawEntry of response.rawEntries) {
+    const absolutePath = path.isAbsolute(rawEntry)
+      ? path.resolve(rawEntry)
+      : path.resolve(projectRoot, rawEntry);
+
+    if (!pathWithinRoot(resolvedRoot, absolutePath)) {
+      response.invalidEntries.push({
+        input: rawEntry,
+        reason: "path escapes project root"
+      });
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(path.relative(projectRoot, absolutePath));
+    const dedupeInputKey = relativePath.toLowerCase();
+    if (seenInputs.has(dedupeInputKey)) {
+      response.duplicateEntries.push(relativePath || rawEntry);
+      continue;
+    }
+    seenInputs.add(dedupeInputKey);
+
+    if (!fs.existsSync(absolutePath)) {
+      response.missingEntries.push(relativePath || rawEntry);
+      continue;
+    }
+
+    let stat;
+    try {
+      stat = fs.lstatSync(absolutePath);
+    } catch (_error) {
+      response.unreadableEntries.push(relativePath || rawEntry);
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      response.directoryEntries.push(relativePath || rawEntry);
+      continue;
+    }
+
+    const canonicalAbsolutePath = safeRealpathSync(absolutePath);
+    if (!canonicalAbsolutePath) {
+      response.unreadableEntries.push(relativePath || rawEntry);
+      continue;
+    }
+    if (!pathWithinRoot(canonicalRoot, canonicalAbsolutePath)) {
+      response.invalidEntries.push({
+        input: rawEntry,
+        reason: "path escapes project root via symlink"
+      });
+      continue;
+    }
+
+    const canonicalRelativePath = normalizeRelativePath(path.relative(canonicalRoot, canonicalAbsolutePath));
+    const effectiveRelativePath = canonicalRelativePath || relativePath;
+    const dedupeCanonicalKey = effectiveRelativePath.toLowerCase();
+    if (seenCanonical.has(dedupeCanonicalKey)) {
+      response.duplicateEntries.push(effectiveRelativePath || rawEntry);
+      continue;
+    }
+    seenCanonical.add(dedupeCanonicalKey);
+
+    response.entries.push({
+      input: rawEntry,
+      absolutePath,
+      canonicalPath: canonicalAbsolutePath,
+      relativePath: effectiveRelativePath,
+      extension: path.extname(effectiveRelativePath || relativePath).toLowerCase(),
+      isSymlink: stat.isSymbolicLink()
+    });
+  }
+
+  return response;
+}
+
+function buildImplementationChecks(specRecords, tasksArtifact) {
+  const stateChecks = [];
+  let stateCounter = 0;
+  for (const record of specRecords) {
+    const states = record.parsed.sections.states.items || [];
+    for (const stateItem of states) {
+      const stateLabel = String(stateItem || "").split(":")[0];
+      const tokens = unique(tokenizeCoverage(stateLabel, 3));
+      if (tokens.length === 0) {
+        continue;
+      }
+      stateCounter += 1;
+      stateChecks.push(createImplementationCheck({
+        id: `state-${stateCounter}`,
+        type: "state",
+        label: String(stateItem || "").trim(),
+        recordPath: record.path,
+        tokens
+      }));
+    }
+  }
+
+  const taskGroupChecks = [];
+  for (const group of tasksArtifact.taskGroups) {
+    const tokens = unique(tokenizeCoverage(group.title, 4));
+    if (tokens.length === 0) {
+      continue;
+    }
+    taskGroupChecks.push(createImplementationCheck({
+      id: `task-group-${group.id}`,
+      type: "task-group",
+      label: `${group.id}. ${group.title}`,
+      groupId: group.id,
+      tokens
+    }));
+  }
+
+  return {
+    stateChecks,
+    taskGroupChecks,
+    allChecks: [...stateChecks, ...taskGroupChecks]
+  };
+}
+
+function createImplementationCheck(data) {
+  const tokens = Array.isArray(data.tokens) ? data.tokens.filter(Boolean) : [];
+  return {
+    id: data.id,
+    type: data.type,
+    label: data.label,
+    recordPath: data.recordPath || null,
+    groupId: data.groupId || null,
+    tokens,
+    requiredMatches: computeRequiredMatches(data.type, tokens),
+    covered: false,
+    evidence: null,
+    boundaries: []
+  };
+}
+
+function computeRequiredMatches(type, tokens) {
+  if (!Array.isArray(tokens) || tokens.length === 0) {
+    return 0;
+  }
+  if (tokens.length === 1) {
+    return 1;
+  }
+  if (type === "task-group") {
+    return Math.min(2, tokens.length);
+  }
+  return Math.min(2, tokens.length);
+}
+
+function evaluateCheckAgainstTokenSet(check, tokenSet) {
+  const matchedTokens = [];
+  for (const token of check.tokens) {
+    if (tokenSet.has(token)) {
+      matchedTokens.push(token);
+    }
+  }
+  return {
+    matchedTokens,
+    covered: matchedTokens.length >= check.requiredMatches
+  };
+}
+
+function addBoundary(check, boundary) {
+  if (!check || !boundary || !boundary.type) {
+    return;
+  }
+  const key = `${boundary.type}|${boundary.file || ""}|${boundary.reason || ""}`;
+  if (!Array.isArray(check.boundaries)) {
+    check.boundaries = [];
+  }
+  if (check.boundaries.some((item) => `${item.type}|${item.file || ""}|${item.reason || ""}` === key)) {
+    return;
+  }
+  check.boundaries.push({
+    type: boundary.type,
+    file: boundary.file || null,
+    reason: boundary.reason || ""
+  });
+}
+
+function evidenceScore(evidence) {
+  if (!evidence) {
+    return 0;
+  }
+  const confidenceScore =
+    evidence.confidence === "high"
+      ? 30
+      : evidence.confidence === "medium"
+        ? 20
+        : evidence.confidence === "low"
+          ? 10
+          : 0;
+  const modeScore =
+    evidence.mode === "syntax-aware"
+      ? 4
+      : evidence.mode === "markup"
+        ? 3
+        : evidence.mode === "heuristic"
+          ? 2
+          : 1;
+  return confidenceScore + modeScore;
+}
+
+function applyEvidence(check, evidence) {
+  if (!check || !evidence) {
+    return;
+  }
+  if (!check.evidence || evidenceScore(evidence) > evidenceScore(check.evidence)) {
+    check.evidence = evidence;
+    check.covered = true;
+  }
+}
+
+const REGEX_PREFIX_CHARS = new Set([
+  "(",
+  "[",
+  "{",
+  ",",
+  ";",
+  ":",
+  "=",
+  "!",
+  "&",
+  "|",
+  "?",
+  "+",
+  "-",
+  "*",
+  "%",
+  "^",
+  "~",
+  "<",
+  ">",
+  "/"
+]);
+const REGEX_PREFIX_KEYWORD_PATTERN =
+  /(?:^|[^\w$])(return|throw|case|delete|void|typeof|instanceof|in|of|new|await|yield)\s*$/;
+
+function previousNonWhitespaceChar(text, startIndex) {
+  for (let index = startIndex; index >= 0; index -= 1) {
+    const char = text[index];
+    if (char === " " || char === "\t" || char === "\n" || char === "\r" || char === "\f") {
+      continue;
+    }
+    return char;
+  }
+  return "";
+}
+
+function canStartRegexLiteral(text, index) {
+  const previousChar = previousNonWhitespaceChar(text, index - 1);
+  if (!previousChar) {
+    return true;
+  }
+  if (REGEX_PREFIX_CHARS.has(previousChar)) {
+    return true;
+  }
+  return REGEX_PREFIX_KEYWORD_PATTERN.test(text.slice(0, index));
+}
+
+function collectScriptEvidenceText(source) {
+  const text = String(source || "");
+  const out = [];
+  let state = "normal";
+  let regexInClass = false;
+
+  for (let index = 0; index < text.length; index += 1) {
+    const char = text[index];
+    const next = text[index + 1];
+
+    if (state === "normal") {
+      if (char === "/" && next === "/") {
+        out.push(" ", " ");
+        state = "line-comment";
+        index += 1;
+        continue;
+      }
+      if (char === "/" && next === "*") {
+        out.push(" ", " ");
+        state = "block-comment";
+        index += 1;
+        continue;
+      }
+      if (char === "/" && canStartRegexLiteral(text, index)) {
+        out.push(" ");
+        state = "regex";
+        regexInClass = false;
+        continue;
+      }
+      if (char === "'") {
+        out.push(" ");
+        state = "single-quote";
+        continue;
+      }
+      if (char === '"') {
+        out.push(" ");
+        state = "double-quote";
+        continue;
+      }
+      if (char === "`") {
+        out.push(" ");
+        state = "template";
+        continue;
+      }
+      out.push(char);
+      continue;
+    }
+
+    if (state === "line-comment") {
+      if (char === "\n") {
+        out.push("\n");
+        state = "normal";
+      } else {
+        out.push(" ");
+      }
+      continue;
+    }
+
+    if (state === "block-comment") {
+      if (char === "*" && next === "/") {
+        out.push(" ", " ");
+        state = "normal";
+        index += 1;
+        continue;
+      }
+      out.push(char === "\n" ? "\n" : " ");
+      continue;
+    }
+
+    if (state === "regex") {
+      if (char === "\n") {
+        out.push("\n");
+        state = "normal";
+        continue;
+      }
+      if (char === "\\") {
+        out.push(" ");
+        if (index + 1 < text.length) {
+          out.push(" ");
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "[" && !regexInClass) {
+        out.push(" ");
+        regexInClass = true;
+        continue;
+      }
+      if (char === "]" && regexInClass) {
+        out.push(" ");
+        regexInClass = false;
+        continue;
+      }
+      if (char === "/" && !regexInClass) {
+        out.push(" ");
+        state = "regex-flags";
+        continue;
+      }
+      out.push(" ");
+      continue;
+    }
+
+    if (state === "regex-flags") {
+      if (/[a-z]/i.test(char)) {
+        out.push(" ");
+        continue;
+      }
+      state = "normal";
+      index -= 1;
+      continue;
+    }
+
+    if (state === "single-quote") {
+      if (char === "\\") {
+        out.push(" ");
+        if (index + 1 < text.length) {
+          out.push(" ");
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "'") {
+        out.push(" ");
+        state = "normal";
+        continue;
+      }
+      if (char === "\n") {
+        return {
+          ok: false,
+          text: "",
+          reason: "unterminated-string-literal"
+        };
+      }
+      out.push(" ");
+      continue;
+    }
+
+    if (state === "double-quote") {
+      if (char === "\\") {
+        out.push(" ");
+        if (index + 1 < text.length) {
+          out.push(" ");
+          index += 1;
+        }
+        continue;
+      }
+      if (char === '"') {
+        out.push(" ");
+        state = "normal";
+        continue;
+      }
+      if (char === "\n") {
+        return {
+          ok: false,
+          text: "",
+          reason: "unterminated-string-literal"
+        };
+      }
+      out.push(" ");
+      continue;
+    }
+
+    if (state === "template") {
+      if (char === "\\") {
+        out.push(" ");
+        if (index + 1 < text.length) {
+          out.push(" ");
+          index += 1;
+        }
+        continue;
+      }
+      if (char === "`") {
+        out.push(" ");
+        state = "normal";
+        continue;
+      }
+      out.push(char === "\n" ? "\n" : " ");
+      continue;
+    }
+  }
+
+  if (state === "single-quote" || state === "double-quote" || state === "template" || state === "block-comment") {
+    return {
+      ok: false,
+      text: "",
+      reason: "unterminated-comment-or-string"
+    };
+  }
+
+  return {
+    ok: true,
+    text: out.join(""),
+    reason: ""
+  };
+}
+
+function stripMarkupComments(source) {
+  return String(source || "").replace(/<!--[\s\S]*?-->/g, (comment) => comment.replace(/[^\n]/g, " "));
+}
+
+function collectStructureEvidenceText(source, extension) {
+  const markupFiltered = stripMarkupComments(source);
+  if (SYNTAX_AWARE_SCRIPT_EXTENSIONS.has(extension)) {
+    const scriptEvidence = collectScriptEvidenceText(markupFiltered);
+    if (scriptEvidence.ok) {
+      return {
+        text: scriptEvidence.text,
+        syntaxAvailable: true,
+        reason: ""
+      };
+    }
+    return {
+      text: "",
+      syntaxAvailable: false,
+      reason: scriptEvidence.reason || "syntax-unavailable"
+    };
+  }
+
+  return {
+    text: markupFiltered,
+    syntaxAvailable: true,
+    reason: ""
+  };
+}
+
+function serializeCheck(check, noRelevantFiles = false) {
+  const evidence = check.evidence
+    ? {
+        mode: check.evidence.mode,
+        confidence: check.evidence.confidence,
+        file: check.evidence.file || null,
+        reason: check.evidence.reason || "",
+        matchedTokens: check.evidence.matchedTokens || [],
+        degraded: check.evidence.degraded === true
+      }
+    : {
+        mode: noRelevantFiles ? "not-scanned" : "none",
+        confidence: "none",
+        file: null,
+        reason: noRelevantFiles ? "no-relevant-files-scanned" : "no-qualifying-evidence",
+        matchedTokens: [],
+        degraded: false
+      };
+
+  return {
+    id: check.id,
+    type: check.type,
+    label: check.label,
+    covered: check.covered,
+    tokens: check.tokens,
+    requiredMatches: check.requiredMatches,
+    evidence,
+    boundaries: Array.isArray(check.boundaries) ? check.boundaries : []
+  };
+}
+
 function verifyBindings(projectPathInput, options = {}) {
   const setup = commonSetup("verify-bindings", projectPathInput, options);
   const { result, artifacts } = setup;
@@ -323,13 +1054,6 @@ function verifyImplementation(projectPathInput, options = {}) {
     return result;
   }
 
-  const codeScan = collectCodeFiles(result.projectRoot);
-  const codeFiles = codeScan.files;
-  if (codeFiles.length === 0) {
-    result.failures.push("No implementation files were found for verify-implementation.");
-    return finalize(result);
-  }
-
   const specRecords = parseRuntimeSpecs(resolved.changeDir, result.projectRoot);
   const tasksArtifact = parseTasksArtifact(artifacts.tasks || "");
 
@@ -338,46 +1062,158 @@ function verifyImplementation(projectPathInput, options = {}) {
     return finalize(result);
   }
 
-  const stateChecks = [];
-  for (const record of specRecords) {
-    const states = record.parsed.sections.states.items || [];
-    for (const stateItem of states) {
-      const state = normalizeText(String(stateItem || "").split(":")[0]);
-      if (!state) {
+  const checks = buildImplementationChecks(specRecords, tasksArtifact);
+  const allChecks = checks.allChecks;
+
+  const changedFiles = collectChangedFileEntries(result.projectRoot, options);
+  if (changedFiles.requested && changedFiles.invalidEntries.length > 0) {
+    for (const invalidEntry of changedFiles.invalidEntries) {
+      result.failures.push(
+        `Invalid --changed-files entry "${invalidEntry.input}": ${invalidEntry.reason}.`
+      );
+    }
+    return finalize(result);
+  }
+
+  let codeFiles = [];
+  let scan = {
+    truncatedByFileLimit: false,
+    truncatedByDirectoryLimit: false,
+    depthLimitHits: 0,
+    skippedSymlinks: 0,
+    readErrors: 0,
+    scannedDirectories: 0
+  };
+  const filteredChanged = {
+    duplicates: changedFiles.duplicateEntries.length,
+    missing: changedFiles.missingEntries.length,
+    directories: changedFiles.directoryEntries.length,
+    unreadable: changedFiles.unreadableEntries.length,
+    unsupported: 0,
+    excluded: 0,
+    symlinks: 0
+  };
+
+  if (changedFiles.requested) {
+    for (const entry of changedFiles.entries) {
+      if (entry.isSymlink) {
+        filteredChanged.symlinks += 1;
         continue;
       }
-      const stateTokens = state.split(" ").filter((token) => token.length >= 3);
-      if (stateTokens.length === 0) {
+      if (!CODE_FILE_EXTENSIONS.has(entry.extension)) {
+        filteredChanged.unsupported += 1;
         continue;
       }
-      stateChecks.push({
-        recordPath: record.path,
-        stateItem,
-        tokens: stateTokens,
-        covered: false
-      });
+      if (isNonImplementationFileName(path.basename(entry.relativePath)) || hasExcludedDirectory(entry.relativePath)) {
+        filteredChanged.excluded += 1;
+        continue;
+      }
+      codeFiles.push(entry.absolutePath);
     }
+    codeFiles = unique(codeFiles).sort();
+  } else {
+    const codeScan = collectCodeFiles(result.projectRoot);
+    codeFiles = codeScan.files;
+    scan = codeScan.scan;
   }
 
-  const taskGroupChecks = [];
-  for (const group of tasksArtifact.taskGroups) {
-    const titleTokens = normalizeText(group.title)
-      .split(" ")
-      .filter((token) => token.length >= 4);
-    if (titleTokens.length === 0) {
-      continue;
+  let scannedBytes = 0;
+  let skippedLargeFiles = 0;
+  let readErrors = 0;
+  let scannedFiles = 0;
+  const degradedFallbackFiles = new Set();
+  const markupHeuristicFiles = new Set();
+  const unsupportedHeuristicFiles = new Set();
+
+  result.scan = {
+    scanMode: changedFiles.requested ? "incremental" : "full",
+    requestedChangedFiles: changedFiles.rawEntries.length,
+    selectedFileCount: changedFiles.requested ? changedFiles.entries.length : codeFiles.length,
+    relevantFileCount: codeFiles.length,
+    scannedFileCount: 0,
+    filtered: {
+      ...filteredChanged,
+      total:
+        filteredChanged.duplicates +
+        filteredChanged.missing +
+        filteredChanged.directories +
+        filteredChanged.unreadable +
+        filteredChanged.unsupported +
+        filteredChanged.excluded +
+        filteredChanged.symlinks
+    },
+    noRelevantFiles: false
+  };
+
+  if (changedFiles.requested) {
+    if (changedFiles.missingEntries.length > 0) {
+      result.notes.push(
+        `Incremental input ignored missing files: ${listSummary(changedFiles.missingEntries)}.`
+      );
+    }
+    if (changedFiles.directoryEntries.length > 0) {
+      result.notes.push(
+        `Incremental input ignored directory paths: ${listSummary(changedFiles.directoryEntries)}.`
+      );
+    }
+    if (changedFiles.duplicateEntries.length > 0) {
+      result.notes.push(
+        `Incremental input deduplicated repeated paths: ${listSummary(changedFiles.duplicateEntries)}.`
+      );
     }
+    if (filteredChanged.unsupported > 0) {
+      result.notes.push(
+        `Incremental input ignored ${filteredChanged.unsupported} unsupported implementation file(s).`
+      );
+    }
+    if (filteredChanged.excluded > 0) {
+      result.notes.push(
+        `Incremental input ignored ${filteredChanged.excluded} excluded test/fixture/spec file(s).`
+      );
+    }
+    if (filteredChanged.symlinks > 0) {
+      result.notes.push(
+        `Incremental input ignored ${filteredChanged.symlinks} symlink path(s).`
+      );
+    }
+    if (changedFiles.unreadableEntries.length > 0) {
+      result.notes.push(
+        `Incremental input ignored unreadable files: ${listSummary(changedFiles.unreadableEntries)}.`
+      );
+    }
+  }
 
-    taskGroupChecks.push({
-      group,
-      tokens: titleTokens,
-      covered: false
-    });
+  if (codeFiles.length === 0) {
+    if (changedFiles.requested) {
+      result.scan.noRelevantFiles = true;
+      result.warnings.push(
+        "Incremental verify-implementation scanned zero relevant implementation files; result is partial."
+      );
+      result.summary = {
+        codeFiles: 0,
+        specFiles: specRecords.length,
+        taskGroups: tasksArtifact.taskGroups.length,
+        scannedBytes: 0,
+        scanMode: "incremental"
+      };
+      result.implementation = {
+        stateChecks: checks.stateChecks.length,
+        taskGroupChecks: checks.taskGroupChecks.length,
+        degradedChecks: 0,
+        checks: allChecks.map((check) => serializeCheck(check, true)),
+        evidenceModeCounts: {
+          "syntax-aware": 0,
+          markup: 0,
+          heuristic: 0,
+          none: allChecks.length
+        }
+      };
+      return finalize(result);
+    }
+    result.failures.push("No implementation files were found for verify-implementation.");
+    return finalize(result);
   }
 
-  let scannedBytes = 0;
-  let skippedLargeFiles = 0;
-  let readErrors = 0;
   for (const codeFile of codeFiles) {
     const read = readCodeFileForScan(codeFile);
     scannedBytes += read.bytesRead;
@@ -390,67 +1226,201 @@ function verifyImplementation(projectPathInput, options = {}) {
       continue;
     }
 
-    const lower = String(read.text || "").toLowerCase();
-    if (!lower) {
+    scannedFiles += 1;
+    const relativeFile = normalizeRelativePath(path.relative(result.projectRoot, codeFile));
+    const extension = path.extname(codeFile).toLowerCase();
+    const source = String(read.text || "");
+    if (!source) {
       continue;
     }
 
-    for (const check of stateChecks) {
-      if (check.covered) {
+    const rawTokenSet = new Set(tokenizeCoverage(source, 1));
+
+    if (SYNTAX_AWARE_SCRIPT_EXTENSIONS.has(extension)) {
+      const scriptEvidence = collectScriptEvidenceText(source);
+      if (scriptEvidence.ok) {
+        const syntaxTokenSet = new Set(tokenizeCoverage(scriptEvidence.text, 1));
+        for (const check of allChecks) {
+          if (!check.tokens.length) {
+            continue;
+          }
+          const syntaxMatch = evaluateCheckAgainstTokenSet(check, syntaxTokenSet);
+          if (syntaxMatch.covered) {
+            applyEvidence(check, {
+              mode: "syntax-aware",
+              confidence: "high",
+              file: relativeFile,
+              reason: "syntax-structure-match",
+              matchedTokens: syntaxMatch.matchedTokens,
+              degraded: false
+            });
+            continue;
+          }
+
+          const rawMatch = evaluateCheckAgainstTokenSet(check, rawTokenSet);
+          if (rawMatch.covered) {
+            addBoundary(check, {
+              type: "comment-or-string-only",
+              file: relativeFile,
+              reason: "raw token appeared only outside executable syntax"
+            });
+            continue;
+          }
+
+          if (rawMatch.matchedTokens.length > 0 || syntaxMatch.matchedTokens.length > 0) {
+            addBoundary(check, {
+              type: "accidental-token-overlap",
+              file: relativeFile,
+              reason: "token overlap below required threshold"
+            });
+          }
+        }
         continue;
       }
-      check.covered = check.tokens.some((token) => lower.includes(token));
+
+      degradedFallbackFiles.add(relativeFile);
+      for (const check of allChecks) {
+        if (!check.tokens.length) {
+          continue;
+        }
+        const rawMatch = evaluateCheckAgainstTokenSet(check, rawTokenSet);
+        if (rawMatch.covered) {
+          applyEvidence(check, {
+            mode: "heuristic",
+            confidence: "low",
+            file: relativeFile,
+            reason: `syntax-unavailable:${scriptEvidence.reason}`,
+            matchedTokens: rawMatch.matchedTokens,
+            degraded: true
+          });
+        } else if (rawMatch.matchedTokens.length > 0) {
+          addBoundary(check, {
+            type: "accidental-token-overlap",
+            file: relativeFile,
+            reason: "token overlap below required threshold"
+          });
+        }
+      }
+      continue;
+    }
+
+    const mode = IMPLEMENTATION_MARKUP_EXTENSIONS.has(extension) ? "markup" : "heuristic";
+    const confidence = mode === "markup" ? "medium" : "low";
+    if (mode === "markup") {
+      markupHeuristicFiles.add(relativeFile);
+    } else {
+      unsupportedHeuristicFiles.add(relativeFile);
     }
-    for (const check of taskGroupChecks) {
-      if (check.covered) {
+    for (const check of allChecks) {
+      if (!check.tokens.length) {
         continue;
       }
-      check.covered = check.tokens.some((token) => lower.includes(token));
+      const rawMatch = evaluateCheckAgainstTokenSet(check, rawTokenSet);
+      if (rawMatch.covered) {
+        applyEvidence(check, {
+          mode,
+          confidence,
+          file: relativeFile,
+          reason: mode === "markup" ? "markup-heuristic-match" : `unsupported-language:${extension || "(none)"}`,
+          matchedTokens: rawMatch.matchedTokens,
+          degraded: mode !== "markup"
+        });
+      } else if (rawMatch.matchedTokens.length > 0) {
+        addBoundary(check, {
+          type: "accidental-token-overlap",
+          file: relativeFile,
+          reason: "token overlap below required threshold"
+        });
+      }
     }
+  }
 
-    if (allCovered(stateChecks) && allCovered(taskGroupChecks)) {
-      break;
+  result.scan.scannedFileCount = scannedFiles;
+
+  const degradedChecks = [];
+  const evidenceModeCounts = {
+    "syntax-aware": 0,
+    markup: 0,
+    heuristic: 0,
+    none: 0
+  };
+
+  for (const check of allChecks) {
+    if (!check.evidence) {
+      evidenceModeCounts.none += 1;
+      continue;
+    }
+    const mode = check.evidence.mode;
+    if (Object.prototype.hasOwnProperty.call(evidenceModeCounts, mode)) {
+      evidenceModeCounts[mode] += 1;
+    }
+    if (check.evidence.degraded) {
+      degradedChecks.push(check);
     }
   }
 
-  for (const check of stateChecks) {
+  for (const check of checks.stateChecks) {
     if (!check.covered) {
       result.warnings.push(
-        `State coverage may be missing in implementation: "${check.stateItem}" (${check.recordPath}).`
+        `State coverage may be missing in implementation: "${check.label}" (${check.recordPath}).`
       );
     }
   }
-  for (const check of taskGroupChecks) {
+  for (const check of checks.taskGroupChecks) {
     if (!check.covered) {
       result.warnings.push(
-        `Task-group intent may be missing in implementation: "${check.group.id}. ${check.group.title}".`
+        `Task-group intent may be missing in implementation: "${check.label}".`
       );
     }
   }
 
-  if (codeScan.scan.truncatedByFileLimit) {
+  if (degradedFallbackFiles.size > 0) {
+    result.warnings.push(
+      `verify-implementation fell back to heuristic mode for unparseable script files: ${listSummary(Array.from(degradedFallbackFiles).sort())}.`
+    );
+  }
+  if (markupHeuristicFiles.size > 0) {
+    result.notes.push(
+      `verify-implementation used markup heuristic evidence for: ${listSummary(Array.from(markupHeuristicFiles).sort())}.`
+    );
+  }
+  if (unsupportedHeuristicFiles.size > 0) {
+    result.notes.push(
+      `verify-implementation used unsupported-language heuristic evidence for: ${listSummary(
+        Array.from(unsupportedHeuristicFiles).sort()
+      )}.`
+    );
+  }
+
+  if (result.strict && degradedChecks.length > 0) {
+    result.warnings.push(
+      "Strict mode does not promote degraded heuristic evidence to full-confidence coverage."
+    );
+  }
+
+  if (scan.truncatedByFileLimit) {
     result.warnings.push(
       `verify-implementation hit file scan limit (${MAX_SCANNED_FILES}); deep coverage may be incomplete.`
     );
   }
-  if (codeScan.scan.truncatedByDirectoryLimit) {
+  if (scan.truncatedByDirectoryLimit) {
     result.warnings.push(
       `verify-implementation hit directory scan limit (${MAX_SCANNED_DIRECTORIES}); coverage may be incomplete.`
     );
   }
-  if (codeScan.scan.readErrors + readErrors > 0) {
+  if (scan.readErrors + readErrors > 0) {
     result.warnings.push(
-      `verify-implementation skipped unreadable files/directories (${codeScan.scan.readErrors + readErrors}).`
+      `verify-implementation skipped unreadable files/directories (${scan.readErrors + readErrors}).`
     );
   }
-  if (codeScan.scan.depthLimitHits > 0) {
+  if (scan.depthLimitHits > 0) {
     result.notes.push(
-      `verify-implementation enforced max scan depth (${MAX_SCAN_DEPTH}); skipped deeper paths: ${codeScan.scan.depthLimitHits}.`
+      `verify-implementation enforced max scan depth (${MAX_SCAN_DEPTH}); skipped deeper paths: ${scan.depthLimitHits}.`
     );
   }
-  if (codeScan.scan.skippedSymlinks > 0) {
+  if (scan.skippedSymlinks > 0) {
     result.notes.push(
-      `verify-implementation skipped symlink entries during scan: ${codeScan.scan.skippedSymlinks}.`
+      `verify-implementation skipped symlink entries during scan: ${scan.skippedSymlinks}.`
     );
   }
   if (skippedLargeFiles > 0) {
@@ -463,8 +1433,17 @@ function verifyImplementation(projectPathInput, options = {}) {
     codeFiles: codeFiles.length,
     specFiles: specRecords.length,
     taskGroups: tasksArtifact.taskGroups.length,
-    scannedBytes
+    scannedBytes,
+    scanMode: result.scan.scanMode
+  };
+  result.implementation = {
+    stateChecks: checks.stateChecks.length,
+    taskGroupChecks: checks.taskGroupChecks.length,
+    degradedChecks: degradedChecks.length,
+    checks: allChecks.map((check) => serializeCheck(check, false)),
+    evidenceModeCounts
   };
+
   return finalize(result);
 }
 
@@ -488,6 +1467,32 @@ function verifyStructure(projectPathInput, options = {}) {
     return finalize(result);
   }
 
+  const changedFiles = collectChangedFileEntries(result.projectRoot, options);
+  if (changedFiles.requested && changedFiles.invalidEntries.length > 0) {
+    for (const invalidEntry of changedFiles.invalidEntries) {
+      result.failures.push(
+        `Invalid --changed-files entry "${invalidEntry.input}": ${invalidEntry.reason}.`
+      );
+    }
+    return finalize(result);
+  }
+
+  const changedFileSet = new Set(
+    changedFiles.entries
+      .filter((entry) => !entry.isSymlink)
+      .map((entry) => canonicalizePath(entry.absolutePath))
+  );
+
+  const scannedMappingFiles = new Set();
+  let scannedMappings = 0;
+  let skippedByIncremental = 0;
+  let ignoredSymlinkEntries = 0;
+  for (const entry of changedFiles.entries) {
+    if (entry.isSymlink) {
+      ignoredSymlinkEntries += 1;
+    }
+  }
+
   for (const mapping of bindings.mappings) {
     const landing = resolveImplementationLanding(result.projectRoot, mapping.implementation);
     if (!landing) {
@@ -495,33 +1500,69 @@ function verifyStructure(projectPathInput, options = {}) {
       continue;
     }
 
+    const normalizedLanding = canonicalizePath(landing);
+    if (changedFiles.requested && !changedFileSet.has(normalizedLanding)) {
+      skippedByIncremental += 1;
+      continue;
+    }
+
+    scannedMappingFiles.add(normalizedLanding);
+    scannedMappings += 1;
+
     const ext = path.extname(landing).toLowerCase();
     const source = safeReadFile(landing);
-    const normalizedSource = normalizeText(source);
-    const pageTokens = normalizeText(mapping.designPage)
-      .split(" ")
-      .filter((token) => token.length >= 3);
-
-    if (ext === ".html" || ext === ".tsx" || ext === ".jsx" || ext === ".js") {
-      const hasMarkupIndicators = /<section|<main|<header|<footer|<div/.test(source);
-      if (hasMarkupIndicators) {
-        confidence.push({ mapping: mapping.implementation, mode: "markup", confidence: "high" });
+    const structureEvidence = collectStructureEvidenceText(source, ext);
+    const normalizedSource = normalizeCoverageText(structureEvidence.text);
+    const pageTokens = unique(tokenizeCoverage(mapping.designPage, 3));
+
+    if (STRUCTURE_MARKUP_EXTENSIONS.has(ext)) {
+      const hasMarkupIndicators = /<section|<main|<header|<footer|<div|<template|<article/.test(
+        structureEvidence.text
+      );
+      if (!structureEvidence.syntaxAvailable) {
+        confidence.push({
+          mapping: mapping.implementation,
+          mode: "heuristic",
+          confidence: "medium",
+          file: normalizeRelativePath(path.relative(result.projectRoot, landing))
+        });
+        result.warnings.push(
+          `verify-structure used heuristic mode for "${mapping.implementation}" because syntax parsing was unavailable (${structureEvidence.reason}).`
+        );
+      } else if (hasMarkupIndicators) {
+        confidence.push({
+          mapping: mapping.implementation,
+          mode: "markup",
+          confidence: "high",
+          file: normalizeRelativePath(path.relative(result.projectRoot, landing))
+        });
       } else {
-        confidence.push({ mapping: mapping.implementation, mode: "heuristic", confidence: "medium" });
+        confidence.push({
+          mapping: mapping.implementation,
+          mode: "heuristic",
+          confidence: "medium",
+          file: normalizeRelativePath(path.relative(result.projectRoot, landing))
+        });
         result.warnings.push(
           `verify-structure used heuristic mode for "${mapping.implementation}" because markup structure was limited.`
         );
       }
     } else {
-      confidence.push({ mapping: mapping.implementation, mode: "heuristic", confidence: "low" });
+      confidence.push({
+        mapping: mapping.implementation,
+        mode: "heuristic",
+        confidence: "low",
+        file: normalizeRelativePath(path.relative(result.projectRoot, landing))
+      });
       result.warnings.push(
         `verify-structure used heuristic mode for "${mapping.implementation}" due to unsupported file type ${ext || "(none)"}.`
       );
     }
 
     if (pageTokens.length > 0) {
-      const covered = pageTokens.some((token) => normalizedSource.includes(token));
-      if (!covered) {
+      const tokenSet = new Set(tokenizeCoverage(normalizedSource, 1));
+      const matchedCount = pageTokens.filter((token) => tokenSet.has(token)).length;
+      if (matchedCount === 0) {
         result.warnings.push(
           `Structural drift suspected: design page "${mapping.designPage}" tokens not found in "${mapping.implementation}".`
         );
@@ -529,8 +1570,72 @@ function verifyStructure(projectPathInput, options = {}) {
     }
   }
 
+  const unmatchedChangedFiles = changedFiles.entries
+    .filter((entry) => !entry.isSymlink)
+    .map((entry) => canonicalizePath(entry.absolutePath))
+    .filter((absolutePath) => !scannedMappingFiles.has(absolutePath));
+
+  result.scan = {
+    scanMode: changedFiles.requested ? "incremental" : "full",
+    requestedChangedFiles: changedFiles.rawEntries.length,
+    selectedFileCount: changedFiles.requested ? changedFiles.entries.length : bindings.mappings.length,
+    scannedMappingCount: scannedMappings,
+    skippedMappings: skippedByIncremental,
+    filtered: {
+      duplicates: changedFiles.duplicateEntries.length,
+      missing: changedFiles.missingEntries.length,
+      directories: changedFiles.directoryEntries.length,
+      unreadable: changedFiles.unreadableEntries.length,
+      symlinks: ignoredSymlinkEntries,
+      noBindingMatch: unmatchedChangedFiles.length,
+      total:
+        changedFiles.duplicateEntries.length +
+        changedFiles.missingEntries.length +
+        changedFiles.directoryEntries.length +
+        changedFiles.unreadableEntries.length +
+        ignoredSymlinkEntries +
+        unmatchedChangedFiles.length
+    },
+    noRelevantFiles: changedFiles.requested && scannedMappings === 0
+  };
+
+  if (changedFiles.requested) {
+    if (changedFiles.missingEntries.length > 0) {
+      result.notes.push(
+        `Incremental input ignored missing files: ${listSummary(changedFiles.missingEntries)}.`
+      );
+    }
+    if (changedFiles.directoryEntries.length > 0) {
+      result.notes.push(
+        `Incremental input ignored directory paths: ${listSummary(changedFiles.directoryEntries)}.`
+      );
+    }
+    if (changedFiles.duplicateEntries.length > 0) {
+      result.notes.push(
+        `Incremental input deduplicated repeated paths: ${listSummary(changedFiles.duplicateEntries)}.`
+      );
+    }
+    if (unmatchedChangedFiles.length > 0) {
+      const unmatchedRelative = unmatchedChangedFiles
+        .map((absolutePath) => normalizeRelativePath(path.relative(result.projectRoot, absolutePath)))
+        .sort();
+      result.notes.push(
+        `Incremental input included files without binding coverage: ${listSummary(unmatchedRelative)}.`
+      );
+    }
+    if (ignoredSymlinkEntries > 0) {
+      result.notes.push(`Incremental input ignored ${ignoredSymlinkEntries} symlink path(s).`);
+    }
+    if (scannedMappings === 0) {
+      result.warnings.push(
+        "Incremental verify-structure scanned zero relevant implementation mappings; result is partial."
+      );
+    }
+  }
+
   result.structure = {
-    confidence
+    confidence,
+    scan: result.scan
   };
   return finalize(result);
 }
@@ -539,8 +1644,17 @@ function verifyCoverage(projectPathInput, options = {}) {
   const projectRoot = path.resolve(projectPathInput || process.cwd());
   const strict = options.strict === true;
   const changeId = options.changeId ? String(options.changeId).trim() : "";
+  const changedFilesRequested = options.changedFilesProvided === true || Array.isArray(options.changedFiles);
+  const changedFiles = Array.isArray(options.changedFiles) ? options.changedFiles : undefined;
+
   const sharedSetup = createSharedSetup(projectRoot, { changeId, strict });
-  const sharedOptions = { changeId, strict, sharedSetup };
+  const sharedOptions = {
+    changeId,
+    strict,
+    sharedSetup,
+    changedFiles,
+    changedFilesProvided: changedFilesRequested
+  };
   const bindingsResult = verifyBindings(projectRoot, sharedOptions);
   const implementationResult = verifyImplementation(projectRoot, sharedOptions);
   const structureResult = verifyStructure(projectRoot, sharedOptions);
@@ -581,6 +1695,30 @@ function verifyCoverage(projectPathInput, options = {}) {
     result.warnings.push("Missing `verification.md`; coverage evidence is incomplete.");
   }
 
+  const incrementalSurfaces = [];
+  const partialSurfaces = [];
+  if (implementationResult.scan && implementationResult.scan.scanMode === "incremental") {
+    incrementalSurfaces.push("verify-implementation");
+    if (implementationResult.scan.noRelevantFiles) {
+      partialSurfaces.push("verify-implementation:no-relevant-files");
+    }
+  }
+  if (structureResult.scan && structureResult.scan.scanMode === "incremental") {
+    incrementalSurfaces.push("verify-structure");
+    if (structureResult.scan.noRelevantFiles) {
+      partialSurfaces.push("verify-structure:no-relevant-files");
+    }
+  }
+
+  if (incrementalSurfaces.length > 0) {
+    result.warnings.push(
+      `verify-coverage aggregated incremental upstream verification (${incrementalSurfaces.join(", ")}); treat as partial freshness.`
+    );
+    result.notes.push(
+      "Incremental verification scopes are useful for changed-file checks but do not replace full-project freshness."
+    );
+  }
+
   result.components = {
     bindings: {
       status: bindingsResult.status,
@@ -590,19 +1728,85 @@ function verifyCoverage(projectPathInput, options = {}) {
     implementation: {
       status: implementationResult.status,
       failures: implementationResult.failures,
-      warnings: implementationResult.warnings
+      warnings: implementationResult.warnings,
+      scan: implementationResult.scan || null,
+      evidenceModeCounts:
+        implementationResult.implementation && implementationResult.implementation.evidenceModeCounts
+          ? implementationResult.implementation.evidenceModeCounts
+          : {}
     },
     structure: {
       status: structureResult.status,
       failures: structureResult.failures,
       warnings: structureResult.warnings,
-      confidence: structureResult.structure ? structureResult.structure.confidence : []
+      confidence: structureResult.structure ? structureResult.structure.confidence : [],
+      scan: structureResult.scan || null
     }
   };
 
+  result.scan = {
+    scanMode: incrementalSurfaces.length > 0 ? "incremental" : "full",
+    incrementalSurfaces,
+    partialSurfaces,
+    changedFilesRequested: changedFilesRequested
+  };
+
+  const freshness = collectVerificationFreshness(projectRoot, {
+    changeId: result.changeId,
+    resolved: sharedSetup.resolved,
+    artifactPaths: sharedSetup.artifactPaths,
+    requiredSurfaces: ["verify-bindings", "verify-implementation", "verify-structure"]
+  });
+  result.freshness = freshness;
+  if (!freshness.fresh) {
+    result.warnings.push(
+      "Verification freshness is stale for completion-facing claims; re-run verify surfaces before completion wording."
+    );
+    for (const reason of freshness.staleReasons) {
+      result.warnings.push(reason);
+    }
+  }
+
   return finalize(result);
 }
 
+function formatBoundarySummary(boundaries) {
+  if (!Array.isArray(boundaries) || boundaries.length === 0) {
+    return "";
+  }
+  const compact = boundaries.map((item) => item.type).filter(Boolean);
+  if (compact.length === 0) {
+    return "";
+  }
+  return ` [boundaries: ${unique(compact).join(", ")}]`;
+}
+
+function appendScanLines(lines, scan) {
+  if (!scan) {
+    return;
+  }
+  lines.push("", "Scan:");
+  lines.push(`- mode: ${scan.scanMode || "full"}`);
+  if (Number.isFinite(scan.selectedFileCount)) {
+    lines.push(`- selected files: ${scan.selectedFileCount}`);
+  }
+  if (Number.isFinite(scan.relevantFileCount)) {
+    lines.push(`- relevant files: ${scan.relevantFileCount}`);
+  }
+  if (Number.isFinite(scan.scannedFileCount)) {
+    lines.push(`- scanned files: ${scan.scannedFileCount}`);
+  }
+  if (Number.isFinite(scan.scannedMappingCount)) {
+    lines.push(`- scanned mappings: ${scan.scannedMappingCount}`);
+  }
+  if (scan.filtered && Number.isFinite(scan.filtered.total)) {
+    lines.push(`- filtered entries: ${scan.filtered.total}`);
+  }
+  if (scan.noRelevantFiles) {
+    lines.push("- no relevant files: yes");
+  }
+}
+
 function formatVerifyReport(result, title = "Da Vinci verify") {
   const lines = [
     title,
@@ -616,6 +1820,9 @@ function formatVerifyReport(result, title = "Da Vinci verify") {
       lines.push(`${key}: ${value}`);
     }
   }
+
+  appendScanLines(lines, result.scan);
+
   if (result.failures.length > 0) {
     lines.push("", "Failures:");
     for (const failure of result.failures) {
@@ -634,12 +1841,27 @@ function formatVerifyReport(result, title = "Da Vinci verify") {
       lines.push(`- ${note}`);
     }
   }
+
+  if (result.implementation && Array.isArray(result.implementation.checks) && result.implementation.checks.length > 0) {
+    lines.push("", "Implementation evidence:");
+    for (const check of result.implementation.checks) {
+      const evidence = check.evidence || {};
+      const state = check.covered ? "covered" : "missing";
+      const location = evidence.file ? ` @ ${evidence.file}` : "";
+      lines.push(
+        `- ${check.type} "${check.label}": ${state} via ${evidence.mode || "none"} (${evidence.confidence || "none"})${location}${formatBoundarySummary(check.boundaries)}`
+      );
+    }
+  }
+
   if (result.structure && Array.isArray(result.structure.confidence) && result.structure.confidence.length > 0) {
     lines.push("", "Structure confidence:");
     for (const item of result.structure.confidence) {
-      lines.push(`- ${item.mapping}: ${item.mode} (${item.confidence})`);
+      const location = item.file ? ` @ ${item.file}` : "";
+      lines.push(`- ${item.mapping}: ${item.mode} (${item.confidence})${location}`);
     }
   }
+
   return lines.join("\n");
 }
 
@@ -648,5 +1870,6 @@ module.exports = {
   verifyImplementation,
   verifyStructure,
   verifyCoverage,
-  formatVerifyReport
+  formatVerifyReport,
+  collectVerificationFreshness
 };