@khoavu882/doflow 2.0.0-beta.4 → 2.0.0

package/src/runtime/verification/engine.js

@@ -22,10 +22,12 @@
  */
 
 const path = require('node:path');
+const os = require('node:os');
 const nodeFs = require('node:fs');
 const { spawnSync } = require('node:child_process');
 const { detectCommands, applyTargetPattern, TARGET_PATTERN_TOKEN } = require('../command-detect.js');
-const { selectChangedTests } = require('./test-selection.js');
+const { selectChangedTests, formatSelectedTestPattern, testFilesFor, conventionFor, quotePath } = require('./test-selection.js');
+const { selectImpactedTests } = require('./impact.js');
 const { RecoveryManager } = require('../recovery.js');
 const { finishRuntime, usageError } = require('../cli-result.js');
 const { REPO_ROOT } = require('../../helper/repo-root.js');
@@ -37,6 +39,9 @@ const { readReadinessRecord, RECORD_VERSION } = require('../readiness-record.js'
 const { verifyReadinessCheck, featureSlugFor } = require('../implementation-gate.js');
 const { assertSafeTaskId } = require('../evidence-ledger.js');
 const { upkeepAfterVerify } = require('../storage/upkeep.js');
+const { emitVerifyTelemetry } = require('./telemetry-emit.js');
+const { resolveRunsLocation, outerProjectRoot } = require('../trace/ledger.js');
+const { projectRoot: lifecycleProjectRoot } = require('../lifecycle/root.js');
 const {
   VerificationContractRunner,
   FATAL_CHECK_MARKERS,
@@ -49,8 +54,30 @@ const {
   TIER_STATUSES,
   RECOVERY_OUTCOMES,
   REGISTRY_FILENAME,
+  v0Enabled,
+  v0Applies,
+  levelOf,
 } = require('./registry.js');
 
+const sha16 = (text        )         => nodeCrypto.createHash('sha256').update(String(text), 'utf8').digest('hex').slice(0, 16);
+
+/**
+ * Saves a failed-first state file atomically via temp file + rename with mode 0600.
+ * If checks is empty, any existing state file is removed (IC-016).
+ */
+function saveFailedFirstFile(stateDir        , stateFile        , state     , fsImpl      = nodeFs)       {
+  try {
+    if (!state || !state.checks || Object.keys(state.checks).length === 0) {
+      try { fsImpl.unlinkSync(stateFile); } catch {}
+      return;
+    }
+    fsImpl.mkdirSync(stateDir, { recursive: true });
+    const tmp = path.join(stateDir, `.failed-first.${nodeCrypto.randomBytes(6).toString('hex')}.tmp`);
+    fsImpl.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    fsImpl.renameSync(tmp, stateFile);
+  } catch {}
+}
+
 // `handleVerifyCommand` (moved from bin/doflow.js) used bin/doflow.js's own REPO_ROOT — that file's
 // SCRIPT_DIR is bin/, so its repo root is path.dirname(SCRIPT_DIR). This module takes the same root
 // from src/helper/repo-root.js rather than counting its own depth.
@@ -104,6 +131,11 @@ class VerificationEngine {
   policy     ;
   runner     ;
   recoveryOverride     ;
+  v0         ;
+  /** 089 IC-005: the `verify.reuse` setting, resolved once by the verb; false unless injected. */
+  reuse         ;
+  platform        ;
+  configDir        ;
 
   /**
    * @param {Object} [options]
@@ -114,12 +146,19 @@ class VerificationEngine {
    * @param {Function} [options.exec] injection seam for shell execution; `spawnSync` contract
    * @param {Function} [options.clock] injection seam returning epoch milliseconds
    * @param {RecoveryManager} [options.recovery] overrides the per-risk-level manager
+   * @param {string} [options.logDir] where failing checks' full logs go (`verifyStateRoot`)
+   * @param {string} [options.platform] platform used for command execution
+   * @param {string} [options.configDir] resolved verification state store
+   * @param {boolean} [options.v0] whether V0 behavior is enabled (IC-015)
+   * @param {boolean} [options.reuse] whether recorded PASSes are stored and reused (089 IC-005)
    */
   constructor(options      = {}) {
     this.cwd = options.cwd || process.cwd();
     this.fsImpl = options.fsImpl || nodeFs;
     this.exec = options.exec || spawnSync;
     this.clock = options.clock || Date.now;
+    this.platform = options.platform || process.platform;
+    this.configDir = options.configDir || (options.logDir ? path.resolve(options.logDir, '..', '..', '..') : path.join(this.cwd, '.doflow'));
     this.registry = loadVerificationRegistry({
       repoRoot: options.repoRoot,
       registryDir: options.registryDir,
@@ -128,8 +167,16 @@ class VerificationEngine {
       fsImpl: this.fsImpl,
     });
     this.policy = this.registry.policy || {};
-    this.runner = new VerificationContractRunner({ cwd: this.cwd, exec: this.exec });
+    this.runner = new VerificationContractRunner({
+      cwd: this.cwd,
+      exec: this.exec,
+      logDir: options.logDir,
+      platform: this.platform,
+      fsImpl: this.fsImpl,
+    });
     this.recoveryOverride = options.recovery || null;
+    this.v0 = options.v0 !== undefined ? Boolean(options.v0) : true;
+    this.reuse = options.reuse === true;
   }
 
   /** @returns {string} ISO timestamp from the injected clock */
@@ -236,7 +283,8 @@ class VerificationEngine {
       if (!required && !advisory) return base;
 
       if (tier.source === 'detected-command') {
-        const selectorContext = { changedFiles: input.changedFiles, scope, root: detection.projectRoot || input.projectRoot || this.cwd };
+        const v0Active = Boolean(this.v0 && v0Applies(this.registry, riskLevel));
+        const selectorContext = { changedFiles: input.changedFiles, scope, root: detection.projectRoot || input.projectRoot || this.cwd, v0Active, riskLevel };
         return Object.assign(base, this.resolveCommandTier(tier, detection, declaredNone, absent, input.targetPattern, selectorContext));
       }
       if (tier.source === 'caller-supplied' && tier.id === 'structural-invariants') {
@@ -293,6 +341,7 @@ class VerificationEngine {
       .filter((t     ) => t.required && t.resolution === 'UNRESOLVED')
       .map((t     ) => ({ tier: t.id, reason: t.reason }));
 
+    const v0Active = Boolean(this.v0 && v0Applies(this.registry, riskLevel));
     return {
       version: this.registry.version,
       taskId: input.taskId,
@@ -313,6 +362,7 @@ class VerificationEngine {
         declaredNone: detection.declaredNone,
         errors: detection.errors,
       },
+      ...(v0Active ? { testTargeted: detection?.commands?.testTargeted || null } : {}),
       scope: {
         maxFiles: Number.isFinite(scope.maxFiles) ? scope.maxFiles : null,
         allowedPaths: toStringArray(scope.allowedPaths),
@@ -369,6 +419,47 @@ class VerificationEngine {
           } else {
             selection = { basis: 'none', selectedCount: null, totalCount: null, fallback: 'not-scopable' };
           }
+
+          // Feature 090 (IC-003): when v0 is active and files changed, augment with static impact analysis
+          const v0Active = ctx.v0Active !== undefined ? ctx.v0Active : Boolean(this.v0);
+          if (v0Active && observation && Array.isArray(observation.files) && observation.files.length > 0) {
+            const conv = conventionFor(found);
+            if (conv) {
+              const hasNonTest = observation.files.some((f        ) => !conv.isTest(f));
+              const noChangedTests = selected && selected.pattern === null && selected.selection?.fallback === 'no-changed-tests';
+              if (hasNonTest || noChangedTests) {
+                const impact = selectImpactedTests({
+                  root: ctx.root || this.cwd,
+                  found,
+                  changedFiles: observation.files,
+                  fsImpl: this.fsImpl,
+                });
+                if (impact && impact.mode === 'selected' && impact.tests.length > 0 && impact.tests.length < impact.totalCount) {
+                  const directlyChanged = observation.files.filter((f        ) => conv.isTest(f));
+                  const combined = [...new Set([...directlyChanged, ...impact.tests])].sort();
+                  pattern = formatSelectedTestPattern({
+                    selectedTests: combined,
+                    guardDir: conv.guardDir,
+                    platform: process.platform,
+                  });
+                  selection = {
+                    basis: 'impacted-tests',
+                    selectedCount: combined.length,
+                    totalCount: impact.totalCount,
+                    fallback: null,
+                  };
+                } else if (impact && impact.mode === 'full') {
+                  pattern = null;
+                  selection = {
+                    basis: 'none',
+                    selectedCount: null,
+                    totalCount: impact.totalCount,
+                    fallback: 'unknown-files',
+                  };
+                }
+              }
+            }
+          }
         }
       }
       const { command, substituted } = applyTargetPattern(found.command, pattern);
@@ -638,11 +729,83 @@ class VerificationEngine {
     let fatalTier                = null;
     let checksRun = 0;
     let checksPassed = 0;
+    let checksReused = 0;
     // One evaluation pass, one cache: two tiers declaring the same command (targeted and broad
     // tests are often both `npm test`) run it once and share the result. A recovery retry calls
     // runContract again and gets a fresh cache, so retries always observe live behaviour.
     const dedupeCache = new Map             ();
 
+    const v0Active = Boolean(this.v0 && v0Applies(this.registry, contract.riskLevel));
+    if (v0Active || this.reuse) {
+      // 089 IC-005: the runner decides reuse eligibility per level; a recovery retry comes back here.
+      this.runner.beginContract({
+        v0: this.v0,
+        reuse: this.reuse,
+        registry: this.registry,
+        riskLevel: contract.riskLevel,
+        configDir: this.configDir,
+      });
+    } else {
+      // A reused engine must not carry L1/L2 sharing or reuse into an L3 or flag-off contract.
+      this.runner.inflightContext = undefined;
+      this.runner.reuseContext = undefined;
+      this.runner.reuseStore = undefined;
+    }
+    let taskIdValid = false;
+    if (typeof contract.taskId === 'string') {
+      try {
+        assertSafeTaskId(contract.taskId);
+        taskIdValid = true;
+      } catch {
+        taskIdValid = false;
+      }
+    }
+
+    const stateDir = path.join(this.configDir, 'state', 'verification', 'v0');
+    const stateFile = taskIdValid ? path.join(stateDir, `failed-first-${contract.taskId}.json`) : '';
+    let realRootSha = '';
+    try {
+      const real = typeof this.fsImpl.realpathSync === 'function'
+        ? this.fsImpl.realpathSync(this.cwd)
+        : path.resolve(this.cwd);
+      realRootSha = sha16(real);
+    } catch {
+      realRootSha = sha16(path.resolve(this.cwd));
+    }
+
+    let failedFirstState      = null;
+    if (v0Active && taskIdValid) {
+      try {
+        const content = this.fsImpl.readFileSync(stateFile, 'utf8');
+        const parsed = JSON.parse(content);
+        if (parsed && parsed.v === 1 && parsed.cwd === realRootSha && parsed.checks && typeof parsed.checks === 'object') {
+          failedFirstState = parsed;
+        }
+      } catch {
+        failedFirstState = null;
+      }
+    }
+    let stateDirty = false;
+
+    const hasTargeted = Object.hasOwn(contract, 'testTargeted');
+    let foundTargeted = hasTargeted ? contract.testTargeted : contract.detection?.commands?.testTargeted;
+    if (!hasTargeted && !foundTargeted && v0Active && taskIdValid) {
+      try {
+        const det = detectCommands({ projectRoot: this.cwd, fsImpl: this.fsImpl });
+        foundTargeted = det?.commands?.testTargeted;
+      } catch {}
+    }
+    const convention = (foundTargeted && typeof foundTargeted.command === 'string' && foundTargeted.command.includes(TARGET_PATTERN_TOKEN))
+      ? conventionFor(foundTargeted)
+      : null;
+
+    if (convention && this.runner) {
+      this.runner.convention = convention;
+    }
+
+    let failedFirstAttempted = false;
+    let failedFirstHalted = false;
+
     for (const tier of contract.tiers) {
       const entry      = {
         id: tier.id,
@@ -671,6 +834,23 @@ class VerificationEngine {
         continue;
       }
 
+      if (failedFirstHalted && tier.kind === 'behavioral') {
+        entry.status = 'NOT_RUN';
+        entry.reason = 'failed-first-still-failing';
+        for (const check of tier.checks) {
+          entry.checks.push({
+            name: check.name,
+            tier: tier.id,
+            role: check.role,
+            command: check.command,
+            status: 'NOT_RUN',
+            reason: 'failed-first-still-failing',
+          });
+        }
+        reportTiers.push(entry);
+        continue;
+      }
+
       if (tier.modelBased) {
         Object.assign(entry, this.evaluateModelTier(tier, runtimeInput.modelReview));
         reportTiers.push(entry);
@@ -684,14 +864,147 @@ class VerificationEngine {
       }
 
       for (const check of tier.checks) {
+        if (failedFirstHalted && tier.kind === 'behavioral') {
+          entry.checks.push({
+            name: check.name,
+            tier: tier.id,
+            role: check.role,
+            command: check.command,
+            status: 'NOT_RUN',
+            reason: 'failed-first-still-failing',
+          });
+          continue;
+        }
+
+        let runNarrowed = false;
+        let matchedFiles           = [];
+        let narrowedCommand                = null;
+        let narrowedStrikes = 0;
+
+        if (v0Active && taskIdValid && convention && !failedFirstAttempted && tier.kind === 'behavioral') {
+          try {
+            const savedCheck = failedFirstState?.checks?.[check.name]
+              || (failedFirstState?.checks ? Object.values(failedFirstState.checks).find((c     ) => c && c.cmd === sha16(check.command)) : null);
+            const cmdChanged = savedCheck ? savedCheck.cmd !== sha16(check.command) : false;
+            const effectiveStrikes = cmdChanged ? 0 : (Number.isSafeInteger(savedCheck?.strikes) && savedCheck.strikes >= 0 ? savedCheck.strikes : 0);
+            // A file can fail in isolation while the full suite passes (for example, suite setup).
+            // After two narrowed failures, recheck the full scope so saved state cannot pin FAIL.
+            if (savedCheck && effectiveStrikes < 2 && Array.isArray(savedCheck.files) && savedCheck.files.length > 0) {
+              const universeFiles = testFilesFor(foundTargeted, this.cwd, this.fsImpl);
+              matchedFiles = universeFiles.filter((f        ) => savedCheck.files.includes(sha16(f)));
+              if (matchedFiles.length > 0) {
+                const pattern = matchedFiles.map((f        ) => quotePath(f, this.platform || process.platform)).join(' ');
+                const sub = applyTargetPattern(foundTargeted.command, pattern);
+                if (sub.substituted && sub.command) {
+                  narrowedCommand = sub.command;
+                  runNarrowed = true;
+                  narrowedStrikes = effectiveStrikes;
+                }
+              }
+            }
+          } catch {
+            runNarrowed = false;
+          }
+        }
+
+        if (runNarrowed && narrowedCommand) {
+          failedFirstAttempted = true;
+          const narrowedResult = this.runner.runCheck(check.name, narrowedCommand, check.timeoutMs, null);
+          if (narrowedResult.status === 'FAIL') {
+            narrowedResult.tier = tier.id;
+            narrowedResult.role = check.role;
+            if (check.requirementId) narrowedResult.requirementId = check.requirementId;
+            narrowedResult.failedFirst = { ran: true, status: 'FAIL', files: matchedFiles.length };
+            entry.checks.push(narrowedResult);
+            checksRun += 1;
+            failedChecks.push(narrowedResult.name);
+            failedFirstHalted = true;
+
+            const metric = this.runner.metrics.get(narrowedResult);
+            if (metric) metric.failedFirst = 'fail';
+
+            if (v0Active && taskIdValid) {
+              const filesToSave = narrowedResult.failedFiles && narrowedResult.failedFiles.length > 0
+                ? narrowedResult.failedFiles
+                : matchedFiles;
+              if (filesToSave && filesToSave.length > 0) {
+                if (!failedFirstState) failedFirstState = { v: 1, cwd: realRootSha, checks: {} };
+                failedFirstState.checks[check.name] = {
+                  cmd: sha16(check.command),
+                  files: filesToSave.map(sha16),
+                  strikes: narrowedStrikes + 1,
+                };
+                stateDirty = true;
+              }
+            }
+            continue;
+          } else {
+            // Narrowed PASS: the full check runs and alone decides
+            const fullResult = this.runner.runCheck(check.name, check.command, check.timeoutMs, dedupeCache);
+            fullResult.tier = tier.id;
+            fullResult.role = check.role;
+            if (check.requirementId) fullResult.requirementId = check.requirementId;
+            fullResult.failedFirst = { ran: true, status: 'PASS', files: matchedFiles.length };
+            entry.checks.push(fullResult);
+            checksRun += 1;
+            if (fullResult.reused) checksReused += 1;
+            if (fullResult.status === 'PASS') checksPassed += 1;
+            else failedChecks.push(fullResult.name);
+
+            const metric = this.runner.metrics.get(fullResult);
+            if (metric) metric.failedFirst = 'pass';
+
+            if (v0Active && taskIdValid) {
+              if (fullResult.status === 'PASS') {
+                if (failedFirstState?.checks?.[check.name]) {
+                  delete failedFirstState.checks[check.name];
+                  stateDirty = true;
+                }
+              } else if (fullResult.status === 'FAIL') {
+                if (fullResult.failedFiles && fullResult.failedFiles.length > 0) {
+                  if (!failedFirstState) failedFirstState = { v: 1, cwd: realRootSha, checks: {} };
+                  failedFirstState.checks[check.name] = {
+                    cmd: sha16(check.command),
+                    files: fullResult.failedFiles.map(sha16),
+                  };
+                  stateDirty = true;
+                }
+              }
+            }
+            continue;
+          }
+        }
+
         const result = this.runner.runCheck(check.name, check.command, check.timeoutMs, dedupeCache);
         result.tier = tier.id;
         result.role = check.role;
         if (check.requirementId) result.requirementId = check.requirementId;
         entry.checks.push(result);
         checksRun += 1;
+        if (result.reused) checksReused += 1;
         if (result.status === 'PASS') checksPassed += 1;
         else failedChecks.push(result.name);
+
+        const metric = this.runner.metrics.get(result);
+        if (metric) metric.failedFirst = 'none';
+
+        if (v0Active && taskIdValid && tier.kind === 'behavioral') {
+          if (result.status === 'FAIL') {
+            if (result.failedFiles && result.failedFiles.length > 0) {
+              if (!failedFirstState) failedFirstState = { v: 1, cwd: realRootSha, checks: {} };
+              failedFirstState.checks[check.name] = {
+                cmd: sha16(check.command),
+                files: result.failedFiles.map(sha16),
+              };
+              stateDirty = true;
+            }
+          } else if (result.status === 'PASS') {
+            if (failedFirstState?.checks?.[check.name]) {
+              delete failedFirstState.checks[check.name];
+              stateDirty = true;
+            }
+          }
+        }
       }
 
       const anyFailed = entry.checks.some((c     ) => c.status === 'FAIL');
@@ -712,6 +1025,10 @@ class VerificationEngine {
       reportTiers.push(entry);
     }
 
+    if (stateDirty && v0Active && taskIdValid) {
+      saveFailedFirstFile(stateDir, stateFile, failedFirstState, this.fsImpl);
+    }
+
     const requiredTiers = reportTiers.filter((t) => t.required);
     const requiredFailed = requiredTiers.filter((t) => t.status === 'FAIL');
     const requiredUnverified = requiredTiers.filter((t) => t.status === 'UNRESOLVED' || t.status === 'NOT_RUN');
@@ -760,6 +1077,7 @@ class VerificationEngine {
         checksRun,
         checksPassed,
         checksFailed: checksRun - checksPassed,
+        ...(this.reuse ? { checksReused } : {}),
         tiersRequired: requiredTiers.length,
         tiersPassed: requiredTiers.filter((t) => t.status === 'PASS').length,
         tiersFailed: requiredFailed.length,
@@ -912,7 +1230,23 @@ class VerificationEngine {
   failureSignature(report     )         {
     const failed = [...(report.failedChecks || [])].sort().join('|');
     const unresolved = (report.unresolved || []).map((u     ) => u.tier).sort().join('|');
-    return `${report.status}::${failed}::${unresolved}`;
+    const failedFiles = new Set        ();
+    const failedTests = new Set        ();
+    for (const tier of (report.tiers || [])) {
+      for (const check of (tier.checks || [])) {
+        if (check.status === 'FAIL') {
+          if (Array.isArray(check.failedFiles)) {
+            for (const f of check.failedFiles) failedFiles.add(f);
+          }
+          if (Array.isArray(check.failedTests)) {
+            for (const t of check.failedTests) failedTests.add(t);
+          }
+        }
+      }
+    }
+    const filesPart = [...failedFiles].sort().join('|');
+    const testsPart = [...failedTests].sort().join('|');
+    return `${report.status}::${failed}::${unresolved}::${filesPart}::${testsPart}`;
   }
 
   /**
@@ -1260,7 +1594,136 @@ function validateVerificationInput({ cwd, verificationInput, fs = nodeFs, crypto
  * @param {string} [options.baselineRef] commit or ref to measure change against (IC-022)
  * @returns {number} exit code
  */
-function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json = false, projectRoot, slug = null, scope = null, verificationInput = null, verificationPhase = null, baselineRef = null }   
+/**
+ * Where verification keeps its own state (check logs, the verify-moment upkeep): the store the
+ * lifecycle owns — `DOFLOW_CONFIG_DIR`, else the nearest existing `.doflow` above the main checkout,
+ * else the install this runtime was copied into, else an existing `~/.doflow`. Only when none
+ * exists (a project never set up) is it the owner's `.doflow`.
+ * A `.doflow` created under the working directory of a dispatch attempt worktree captured every
+ * later record from there and was deleted with the worktree (088 G-O1 D4).
+ * @param {Object} [options]
+ * @param {string} [options.start] the verify's working directory (default: cwd)
+ * @param {Object} [options.env=process.env]
+ * @param {string} [options.homeDir]
+ * @param {string|null} [options.installRoot] this runtime's package root
+ * @param {Object} [options.fsImpl]
+ * @returns {{configDir: string, projectRoot: string|null}} `projectRoot` is the directory holding
+ *   `configDir` when it is named `.doflow` (the root the storage upkeep takes), else null
+ */
+function verifyStateRoot({ start, env = process.env, homeDir = os.homedir(), installRoot = REPO_ROOT, fsImpl = nodeFs }      = {})                                                    {
+  // Match worker/lifecycle state ownership before looking for a store. A sibling linked checkout
+  // cannot walk up to the main checkout, and a nested .doflow is never a store root (110/111).
+  const from = lifecycleProjectRoot(outerProjectRoot(path.resolve(start || process.cwd())));
+  const isDir = (dir        )          => { try { return fsImpl.statSync(dir).isDirectory(); } catch { return false; } };
+  const at = resolveRunsLocation({ start: from, env, homeDir, fsImpl });
+  let configDir = path.join(from, '.doflow');
+  if (at.origin === 'DOFLOW_CONFIG_DIR' || at.origin === 'project') configDir = at.configDir;
+  else {
+    const marker = `${path.sep}.doflow${path.sep}`;
+    const cut = installRoot ? `${path.resolve(installRoot)}${path.sep}`.indexOf(marker) : -1;
+    const install = cut >= 0 ? path.resolve(installRoot).slice(0, cut) + path.sep + '.doflow' : null;
+    if (install && isDir(install)) configDir = install;
+    else if (isDir(at.configDir)) configDir = at.configDir; // ~/.doflow
+  }
+  return { configDir, projectRoot: path.basename(configDir) === '.doflow' ? path.dirname(configDir) : null };
+}
+
+const VERIFY_GIT_TIMEOUT_MS = 2000;
+const VERIFY_GIT_ENV = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE', 'GIT_COMMON_DIR', 'GIT_OBJECT_DIRECTORY'];
+
+/** Capture the checkout head and status before verification commands run. A moving head is unbound. */
+function verificationGitState(cwd        , env = process.env)             {
+  const gitEnv = { ...env };
+  for (const key of VERIFY_GIT_ENV) delete gitEnv[key];
+  const git = (args          ) => spawnSync('git', args, {
+    cwd,
+    env: gitEnv,
+    encoding: 'utf8',
+    timeout: VERIFY_GIT_TIMEOUT_MS,
+    stdio: ['ignore', 'pipe', 'ignore'],
+  });
+  try {
+    const before = git(['rev-parse', '--verify', 'HEAD']);
+    if (before.status !== 0) return null;
+    const head = before.stdout.trim();
+    if (!/^[0-9a-f]{40}$/.test(head)) return null;
+    const status = git(['--no-optional-locks', 'status', '--porcelain=v1', '-z', '--untracked-files=all']);
+    const after = git(['rev-parse', '--verify', 'HEAD']);
+    if (after.status !== 0 || after.stdout.trim() !== head) return null;
+    return {
+      head,
+      clean: status.status === 0 && status.stdout.length === 0,
+      projectRoot: verificationRunsRoot(cwd),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** IC-007: the checkout whose state holds the run records of a verify run in `cwd` (the lifecycle root). */
+function verificationRunsRoot(cwd        )         {
+  return lifecycleProjectRoot(outerProjectRoot(path.resolve(cwd)));
+}
+
+/** IC-007: the one file the run records of `taskId` are appended to, under `verificationRunsRoot`. */
+function verificationRunRecordFile(root        , taskId        )         {
+  return path.join(root, '.doflow', 'state', 'verification', 'runs', `${taskId}.jsonl`);
+}
+
+/** 089 IC-006: how many checks of a report carry the `reused` label. */
+function reusedCount(report     )         {
+  if (typeof report?.counts?.checksReused === 'number') return report.counts.checksReused;
+  let count = 0;
+  for (const tier of Array.isArray(report?.tiers) ? report.tiers : []) {
+    for (const check of Array.isArray(tier?.checks) ? tier.checks : []) {
+      if (check && typeof check === 'object' && check.reused) count += 1;
+    }
+  }
+  return count;
+}
+
+/** Persist the already printed report as one JSONL line; state I/O never changes its answer.
+ * 089 IC-006: with reuse on for the run, `reused` (the count) precedes `reportSha256`; with reuse
+ * off the record has no `reused` key. 095b IC-004: `risk` (the report's risk level) follows `verdict`;
+ * readers default a missing one, and `verifyRecordReasons` ignores it. */
+function appendVerificationRunRecord({ taskId, report, gitState, reuse = false, fsImpl = nodeFs }     )       {
+  if (!gitState) return;
+  try {
+    const reportJson = JSON.stringify(report, null, 2);
+    const record = {
+      schema: 1,
+      taskId,
+      head: gitState.head,
+      clean: gitState.clean,
+      verdict: report.status,
+      risk: report.riskLevel,
+      at: new Date().toISOString(),
+      ...(reuse === true ? { reused: reusedCount(report) } : {}),
+      reportSha256: `sha256:${nodeCrypto.createHash('sha256').update(reportJson, 'utf8').digest('hex')}`,
+    };
+    const file = verificationRunRecordFile(gitState.projectRoot, taskId);
+    fsImpl.mkdirSync(path.dirname(file), { recursive: true });
+    fsImpl.appendFileSync(file, `${JSON.stringify(record)}\n`, { encoding: 'utf8', mode: 0o600 });
+  } catch {
+    // Reporting is authoritative. A read-only or unavailable state directory is only a lost record.
+  }
+}
+
+/**
+ * 089 IC-005: the `verify.reuse` setting, read once per verify command. Only a valid resolved `on`
+ * enables reuse; an invalid value, a load error or any fault is the key's fail-safe `off`.
+ */
+function readVerifyReuse(env      = process.env)          {
+  try {
+    const { loadSettings } = require('../settings/resolve.js');
+    const resolution = loadSettings({ global: true, env: { ...env } }).get('verify.reuse', 'global');
+    return resolution?.state === 'ok' && resolution.value === 'on';
+  } catch {
+    return false;
+  }
+}
+
+function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json = false, projectRoot, slug = null, scope = null, verificationInput = null, verificationPhase = null, baselineRef = null, env = process.env, fsImpl = nodeFs }   
                
                   
              
@@ -1272,6 +1735,8 @@ function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json =
                                     
                                     
                               
+            
+               
   = {})         {
   // The task id names state files here, so it obeys the rule every other task verb applies.
   try {
@@ -1334,10 +1799,13 @@ function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json =
     if (!declared) declared = { paths: [...recordedScope], origin: 'readiness-record', record: recordRel };
   }
 
+  const state = verifyStateRoot({ start: cwd, env, fsImpl });
+  const v0 = v0Enabled(env, state.configDir, fsImpl);
+  const reuse = readVerifyReuse(env);
   let engine     ;
   let contract     ;
   try {
-    engine = new VerificationEngine({ cwd, repoRoot: REPO_ROOT });
+    engine = new VerificationEngine({ cwd, repoRoot: REPO_ROOT, logDir: path.join(state.configDir, 'state', 'verification', 'logs'), configDir: state.configDir, v0, reuse, fsImpl });
     // The bound comes from the feature's plan, this checkout's or the main checkout's, and from a
     // declared scope; with neither the change-scope tier is UNRESOLVED and says where it looked.
     const resolved = resolveScopeBound({ projectRoot: cwd, slug, planPath, declared, baselineRef });
@@ -1389,6 +1857,7 @@ function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json =
     return usageError('verify', `unknown --action '${action}'. Valid: report (default), contract`, json);
   }
 
+  const runGitState = action === 'report' ? verificationGitState(cwd, env) : null;
   const report = engine.runContract(contract);
   // A task whose run still has its gated stage pending is not verified while no READY readiness
   // record exists: the checks passing says nothing about whether the work should have started.
@@ -1414,9 +1883,21 @@ function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json =
       if (boundLines.has(tier.id)) console.log(boundLines.get(tier.id));
       if (tier.reason) console.log(`      ${tier.reason}`);
       if (tier.selection) console.log(`      ${selectionText(tier.selection)}`);
+      if (Array.isArray(tier.checks)) {
+        for (const check of tier.checks) {
+          if (check?.reused) {
+            const atIso = typeof check.reused.recordedAt === 'number'
+              ? new Date(check.reused.recordedAt).toISOString()
+              : String(check.reused.recordedAt);
+            console.log(`      reused ${atIso} ref ${check.reused.ref}`);
+          }
+        }
+      }
     }
     console.log('─'.repeat(78));
-    console.log(`Checks: ${report.counts.checksPassed}/${report.counts.checksRun} passed`);
+    const reused = report.counts?.checksReused ?? reusedCount(report);
+    const reusedSuffix = reused > 0 ? ` (${reused} reused, not executed)` : '';
+    console.log(`Checks: ${report.counts.checksPassed}/${report.counts.checksRun} passed${reusedSuffix}`);
     if (report.unresolved.length) {
       console.log('Never evaluated (not a pass):');
       for (const u of report.unresolved) console.log(`  ${u.tier}${u.required ? ' [required]' : ''} — ${u.reason}`);
@@ -1425,8 +1906,12 @@ function handleVerifyCommand({ taskId, action = 'report', risk, planPath, json =
   }
   // PASS is the only status that answers "verified". FAIL and INCONCLUSIVE are both findings, and
   // collapsing INCONCLUSIVE into success would report a verdict over zero evidence as a pass.
-  upkeepAfterVerify({ projectRoot: cwd });
-  return finishRuntime(report.status === 'PASS' ? 0 : 1);
+  const exitCode = report.status === 'PASS' ? 0 : 1;
+  if (action === 'report') appendVerificationRunRecord({ taskId, report, gitState: runGitState, reuse, fsImpl });
+  // After the report is printed; never throws and changes nothing printed (088 C.1, IC-006).
+  emitVerifyTelemetry({ report, metrics: engine.runner.metrics, ctx: { source: 'verb', taskId, risk: report.riskLevel, exitCode, v0: v0 ? 'on' : 'off' }, start: state.projectRoot || cwd, env, fsImpl });
+  upkeepAfterVerify({ projectRoot: state.projectRoot });
+  return finishRuntime(exitCode);
 }
 
 /** One line stating what the targeted tier selected, or why it ran the broad command instead. */
@@ -1445,6 +1930,8 @@ function sameSet(a          , b          )          {
 }
 
 module.exports = {
+  verificationRunsRoot,
+  verificationRunRecordFile,
   VerificationContractRunner,
   VerificationEngine,
   loadVerificationRegistry,
@@ -1457,5 +1944,8 @@ module.exports = {
   MAX_STREAM_CHARS,
   REGISTRY_FILENAME,
   handleVerifyCommand,
+  readVerifyReuse,
+  verifyStateRoot,
   validateVerificationInput,
+  saveFailedFirstFile,
 };