@khoavu882/doflow 0.0.0-stage → 2.0.0-beta.3

package/src/runtime/verification/engine.ts

@@ -0,0 +1,1461 @@
+'use strict';
+
+// TypeScript migration (agent-docs/BRIEF_GOAL_DOFLOW.md): run directly by Node native type-stripping.
+
+/**
+ * Registry-driven verification layer (plan task C.2, design C7): `VerificationEngine` compiles a
+ * contract **before** implementation and a report **after**, scaling required tiers to risk,
+ * detecting commands from project manifests, and wiring the C8 recovery classifier into the
+ * failure path with its bounded retry.
+ *
+ * Built on two modules split out alongside it:
+ *   - `verification-contract-runner.js` — `VerificationContractRunner`, the deterministic
+ *     check-execution primitive this engine compiles tiers of checks down to.
+ *   - `verification-registry.js` — `loadVerificationRegistry`, which reads and validates
+ *     `core/registry/verification.json` into the shape `compileContract` reads tiers from.
+ *
+ * Three defects in the runner this engine sits on (a check with no command reporting PASS, a
+ * timed-out check losing its output, an empty contract reporting PASS over zero evidence — see
+ * `verification-contract-runner.js`) are the reason this layer looks the way it does. Their shared
+ * shape is a gate answering confidently about something it never evaluated, so the engine keeps
+ * "not evaluated" as a first-class outcome — UNRESOLVED — that can never become PASS.
+ */
+
+const path = require('node:path');
+const nodeFs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { detectCommands, applyTargetPattern, TARGET_PATTERN_TOKEN } = require('../command-detect.ts');
+const { selectChangedTests } = require('./test-selection.ts');
+const { RecoveryManager } = require('../recovery.ts');
+const { finishRuntime, usageError } = require('../cli-result.ts');
+const { REPO_ROOT } = require('../../helper/repo-root.ts');
+const {
+  resolveScopeBound, resolveIntegrationBase, resolveExplicitBaseline, parseDeclaredScope, scopeReasonText, boundSourcesText,
+} = require('./scope-bound.ts');
+const nodeCrypto = require('node:crypto');
+const { readReadinessRecord, RECORD_VERSION } = require('../readiness-record.ts');
+const { verifyReadinessCheck, featureSlugFor } = require('../implementation-gate.ts');
+const { assertSafeTaskId } = require('../evidence-ledger.ts');
+const { upkeepAfterVerify } = require('../storage/upkeep.ts');
+const {
+  VerificationContractRunner,
+  FATAL_CHECK_MARKERS,
+  TIMEOUT_EXIT_CODE,
+  MAX_STREAM_CHARS,
+} = require('./contract-runner.ts');
+const {
+  loadVerificationRegistry,
+  TIER_RESOLUTIONS,
+  TIER_STATUSES,
+  RECOVERY_OUTCOMES,
+  REGISTRY_FILENAME,
+} = require('./registry.ts');
+
+// `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.
+
+/** `PASS` and `FAIL` are the Python's vocabulary. `INCONCLUSIVE` is added for the empty-contract
+ * case only — see `evaluateContract`. */
+const VERIFICATION_STATUSES = Object.freeze(['PASS', 'FAIL', 'INCONCLUSIVE']);
+
+/** The targeted tier is subsumed by the broad one when both would run the same command (FR-001). */
+const TARGETED_TIER_ID = 'targeted-tests';
+const BROAD_TIER_ID = 'broad-tests';
+
+/**
+ * @param {*} value
+ * @returns {Array<string>}
+ */
+/** A stderr excerpt for a message. (Referenced by the observation errors below without ever being
+ * defined, so a non-zero `git status` with no spawn error threw a ReferenceError instead of reporting.) */
+function truncate(text: any, max: number = 200): string {
+  const flat = String(text || '').trim();
+  return flat.length > max ? `${flat.slice(0, max)}…` : flat;
+}
+
+function toStringArray(value: any): string[] {
+  return Array.isArray(value) ? value.filter((v) => typeof v === 'string' && v !== '') : [];
+}
+
+/**
+ * Parses `git status --porcelain` into the set of paths it touched.
+ * @param {string} stdout
+ * @returns {Array<string>}
+ */
+function parsePorcelain(stdout: any): string[] {
+  const files: string[] = [];
+  for (const line of String(stdout || '').split('\n')) {
+    if (line.trim() === '') continue;
+    const body = line.slice(3);
+    // A rename is reported as `old -> new`; the new path is the one that exists now.
+    const arrow = body.indexOf(' -> ');
+    files.push(arrow === -1 ? body.trim() : body.slice(arrow + 4).trim());
+  }
+  return files.filter(Boolean);
+}
+
+class VerificationEngine {
+  cwd: string;
+  fsImpl: any;
+  exec: any;
+  clock: any;
+  registry: any;
+  policy: any;
+  runner: any;
+  recoveryOverride: any;
+
+  /**
+   * @param {Object} [options]
+   * @param {string} [options.cwd] directory checks run in
+   * @param {string} [options.repoRoot] where `core/registry/` lives
+   * @param {Object} [options.registry] pre-parsed registry (test seam)
+   * @param {Object} [options.fsImpl] injection seam for manifest and registry reads
+   * @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
+   */
+  constructor(options: any = {}) {
+    this.cwd = options.cwd || process.cwd();
+    this.fsImpl = options.fsImpl || nodeFs;
+    this.exec = options.exec || spawnSync;
+    this.clock = options.clock || Date.now;
+    this.registry = loadVerificationRegistry({
+      repoRoot: options.repoRoot,
+      registryDir: options.registryDir,
+      registryPath: options.registryPath,
+      registry: options.registry,
+      fsImpl: this.fsImpl,
+    });
+    this.policy = this.registry.policy || {};
+    this.runner = new VerificationContractRunner({ cwd: this.cwd, exec: this.exec });
+    this.recoveryOverride = options.recovery || null;
+  }
+
+  /** @returns {string} ISO timestamp from the injected clock */
+  timestamp(): string {
+    return new Date(this.clock()).toISOString();
+  }
+
+  /**
+   * @param {string} riskLevel
+   * @returns {Object} the risk-level definition
+   */
+  riskDefinition(riskLevel: string): any {
+    const def = this.registry.riskLevels[riskLevel];
+    if (!def) {
+      // Never coerce to the default: a caller that mistyped CRITICAL would silently get MEDIUM's
+      // lighter tier set on the change that most needed the heavier one.
+      throw new Error(
+        `Unknown risk level '${riskLevel}'. Valid: ${Object.keys(this.registry.riskLevels).join(', ')}`,
+      );
+    }
+    return def;
+  }
+
+  /**
+   * Compiles the verification contract. Called **before** implementation: this is the artifact that
+   * states how success will be established (FR-009), and `runContract` later reports against it.
+   *
+   * @param {Object} input
+   * @param {string} input.taskId
+   * @param {string} [input.riskLevel] defaults to `policy.defaultRiskLevel`
+   * @param {Object} [input.detection] a `detectCommands` result; detected here when absent
+   * @param {string} [input.projectRoot] used for detection when `detection` is not supplied
+   * @param {string} [input.planPath] a feature `plan.md` whose override block wins over detection
+   * @param {string} [input.planText] override text supplied directly
+   * @param {string} [input.targetPattern] scopes the targeted-tests tier; without one, the tier is
+   *   scoped to the feature's changed test files (see test-selection.js) where the toolchain allows
+   * @param {Array<string>} [input.changedFiles] files the selection treats as changed, in place of the
+   *   change-scope observation
+   * @param {Array<{name: string, command: string, timeoutMs?: number}>} [input.structuralChecks]
+   * @param {Array<{id: string, description?: string, command?: string}>} [input.requirements]
+   * @param {{maxFiles?: number, allowedPaths?: Array<string>, source?: string, sources?: Array<Object>,
+   *   baseline?: 'integration', unresolvedReason?: string, searched?: Array<Object>}} [input.scope]
+   *   `baseline: 'integration'` measures the change from the merge base with the integration ref
+   *   (a bound derived from a plan, scope-bound.js); without it only the working tree is observed.
+   *   `sources` names where the bound came from; with no bound, `unresolvedReason` replaces the
+   *   tier's generic reason and `searched` lists the places looked.
+   * @returns {Object} the contract
+   */
+  compileContract(input: any = {}): any {
+    // A contract with no task is the readiness.ts `taskId || 'default'` defect in a new place: a
+    // confident verdict filed against the wrong subject. Refuse instead of inventing an id.
+    if (typeof input.taskId !== 'string' || input.taskId.trim() === '') {
+      throw new Error('compileContract requires a non-empty taskId');
+    }
+
+    const riskLevel = input.riskLevel || this.policy.defaultRiskLevel;
+    const risk = this.riskDefinition(riskLevel);
+    const requiredTiers = new Set(risk.requiredTiers);
+    const advisoryTiers = new Set(risk.advisoryTiers || []);
+
+    const detection = input.detection || detectCommands({
+      projectRoot: input.projectRoot || this.cwd,
+      planPath: input.planPath,
+      planText: input.planText,
+      fsImpl: this.fsImpl,
+    });
+
+    let structuralChecks = Array.isArray(input.structuralChecks) ? input.structuralChecks : [];
+    let requirements = Array.isArray(input.requirements) ? input.requirements : [];
+    const scope = input.scope && typeof input.scope === 'object' ? input.scope : {};
+    const phase = input.phase === 'postimplementation' ? 'postimplementation' : 'unknown';
+    const declaredNone = new Set<string>(detection.declaredNone || []);
+    const absent = new Set<string>(detection.absent || []);
+    let provenance = input.provenance && typeof input.provenance === 'object' ? { ...input.provenance } : null;
+
+    if (input.verificationInput !== undefined && input.verificationInput !== null) {
+      const val = validateVerificationInput({ cwd: this.cwd, verificationInput: input.verificationInput });
+      if (!val.ok) throw new Error(val.message);
+      structuralChecks = val.structuralChecks;
+      requirements = val.requirements;
+      provenance = { ...(provenance || {}), ...val.provenance };
+    }
+    if (scope.baseline === 'explicit' && scope.baselineSha) {
+      provenance = { ...(provenance || {}), baselineSha: scope.baselineSha };
+    }
+
+    const tiers = this.registry.tiers.map((tier: any) => {
+      const required = requiredTiers.has(tier.id);
+      const advisory = advisoryTiers.has(tier.id);
+      const base = {
+        id: tier.id,
+        name: tier.name,
+        kind: tier.kind,
+        order: tier.order,
+        required,
+        advisory,
+        fatal: Boolean(tier.fatal),
+        modelBased: Boolean(tier.modelBased),
+        failureClass: tier.failureClass || null,
+        checks: [],
+        resolution: 'SKIPPED',
+        reason: `Not required at risk level ${riskLevel}.`,
+      };
+      if (!required && !advisory) return base;
+
+      if (tier.source === 'detected-command') {
+        const selectorContext = { changedFiles: input.changedFiles, scope, root: detection.projectRoot || input.projectRoot || this.cwd };
+        return Object.assign(base, this.resolveCommandTier(tier, detection, declaredNone, absent, input.targetPattern, selectorContext));
+      }
+      if (tier.source === 'caller-supplied' && tier.id === 'structural-invariants') {
+        return Object.assign(base, this.resolveStructuralTier(tier, structuralChecks));
+      }
+      if (tier.source === 'caller-supplied' && tier.id === 'requirement-satisfaction') {
+        return Object.assign(base, this.resolveRequirementTier(tier, requirements));
+      }
+      if (tier.source === 'scope-observation') {
+        return Object.assign(base, this.resolveScopeTier(tier, scope));
+      }
+      if (tier.source === 'model') {
+        return Object.assign(base, {
+          resolution: 'RESOLVED',
+          reason: 'Advisory model review; supplied to runContract, never establishes PASS.',
+        });
+      }
+      // A tier whose source this engine does not implement is unevaluated, not satisfied.
+      return Object.assign(base, {
+        resolution: 'UNRESOLVED',
+        reason: `Tier source '${tier.source}' has no evaluator in this engine.`,
+      });
+    });
+
+    // Subsumption is a second pass because it depends on how a *later* tier resolved: parse is
+    // covered by build only if build actually has a command.
+    const byId = new Map<string, any>(tiers.map((t: any) => [t.id, t]));
+    for (const tier of this.registry.tiers) {
+      const resolved: any = byId.get(tier.id);
+      if (!resolved || resolved.resolution !== 'UNRESOLVED') continue;
+      const cover = toStringArray(tier.subsumedBy).find((id: string) => { const e: any = byId.get(id); return e && e.resolution === 'RESOLVED'; });
+      if (cover) {
+        resolved.resolution = 'SUBSUMED';
+        resolved.subsumedBy = cover;
+        resolved.reason = `No dedicated command; covered by the '${cover}' tier, which runs the same source through a stricter step.`;
+      }
+    }
+
+    // A targeted tier that would run the very command a required broad tier runs is that tier's
+    // duplicate, not a cheaper check: it is reported SUBSUMED and never executed (FR-001).
+    const targeted: any = byId.get(TARGETED_TIER_ID);
+    const broad: any = byId.get(BROAD_TIER_ID);
+    if (targeted && broad && targeted.resolution === 'RESOLVED' && broad.required && broad.resolution === 'RESOLVED') {
+      const broadCommands = new Set<string>(broad.checks.map((c: any) => c.command as string));
+      if (targeted.checks.length > 0 && targeted.checks.every((c: any) => broadCommands.has(c.command))) {
+        targeted.resolution = 'SUBSUMED';
+        targeted.subsumedBy = BROAD_TIER_ID;
+        targeted.checks = [];
+        targeted.reason = `Would run the same command as the required '${BROAD_TIER_ID}' tier, which runs it once.`;
+      }
+    }
+
+    const unresolvedRequiredTiers = tiers
+      .filter((t: any) => t.required && t.resolution === 'UNRESOLVED')
+      .map((t: any) => ({ tier: t.id, reason: t.reason }));
+
+    return {
+      version: this.registry.version,
+      taskId: input.taskId,
+      riskLevel,
+      compiledAt: this.timestamp(),
+      // Compilation does not know when it runs relative to implementation, so it never asserts it ran
+      // before: `unknown` is null, and only an explicit `postimplementation` phase records false (IC-022).
+      phase,
+      compiledBeforeImplementation: phase === 'postimplementation' ? false : null,
+      ...(provenance && typeof provenance === 'object' ? { provenance } : {}),
+      cwd: this.cwd,
+      maxRecoveryIterations: risk.maxRecoveryIterations,
+      detection: {
+        usable: detection.usable,
+        manifestFound: detection.manifestFound,
+        manifests: detection.manifests,
+        absent: detection.absent,
+        declaredNone: detection.declaredNone,
+        errors: detection.errors,
+      },
+      scope: {
+        maxFiles: Number.isFinite(scope.maxFiles) ? scope.maxFiles : null,
+        allowedPaths: toStringArray(scope.allowedPaths),
+        ...(scope.baseline === 'explicit' ? { baseline: { kind: 'pinned', ref: scope.baselineRef, sha: scope.baselineSha } } : {}),
+        ...(Array.isArray(scope.sources) ? { sources: scope.sources } : {}),
+        ...(Array.isArray(scope.searched) ? { searched: scope.searched } : {}),
+      },
+      tiers,
+      unresolvedRequiredTiers,
+      runnableCheckCount: tiers.reduce((n: number, t: any) => n + t.checks.length, 0),
+    };
+  }
+
+  /**
+   * Resolves a tier served by a detected command. The whole point of the three-way distinction in
+   * `command-detect` lands here.
+   * @private
+   */
+  resolveCommandTier(tier: any, detection: any, declaredNone: Set<string>, absent: Set<string>, targetPattern: any, selectorContext: any = null): any {
+    if (!detection.usable) {
+      return {
+        resolution: 'UNRESOLVED',
+        reason: `Command detection is unusable: ${detection.errors.join('; ')}`,
+      };
+    }
+
+    const roles = toStringArray(tier.commandRoles);
+    const selectAll = tier.commandRoleSelection === 'all';
+    const checks: any[] = [];
+    const notes: string[] = [];
+    let selection: any = null;
+
+    for (const role of roles) {
+      const found = detection.commands[role];
+      if (!found) continue;
+      let pattern = targetPattern;
+      if (role === 'testTargeted' && found.command.includes(TARGET_PATTERN_TOKEN)) {
+        if (typeof targetPattern === 'string' && targetPattern.trim() !== '') {
+          selection = { basis: 'explicit-pattern', selectedCount: null, totalCount: null, fallback: null };
+        } else {
+          // No caller-supplied target: scope to the files this feature changed, where the toolchain
+          // has a test-file convention. The changed files are the ones the change-scope tier reads.
+          const ctx = selectorContext || {};
+          const scope = ctx.scope || {};
+          const observation = this.observeForSelection(ctx.changedFiles, {
+            baseline: scope.baseline, baselineRef: scope.baselineRef, baselineSha: scope.baselineSha,
+          });
+          const selected = selectChangedTests({
+            found, observation, root: ctx.root || this.cwd, fsImpl: this.fsImpl,
+          });
+          if (selected) {
+            pattern = selected.pattern;
+            selection = selected.selection;
+          } else {
+            selection = { basis: 'none', selectedCount: null, totalCount: null, fallback: 'not-scopable' };
+          }
+        }
+      }
+      const { command, substituted } = applyTargetPattern(found.command, pattern);
+      if (command === null) {
+        // The command is a template and no target was supplied. Fall through to the next role —
+        // for targeted-tests that is the broad test command, which the report records.
+        notes.push(selection && selection.fallback
+          ? `role '${role}' has no selection (${selection.fallback})`
+          : `role '${role}' needs a target pattern and none was supplied`);
+        continue;
+      }
+      checks.push({
+        name: `${tier.id}:${role}`,
+        tier: tier.id,
+        role,
+        command,
+        timeoutMs: tier.timeoutMs || undefined,
+        source: found.source,
+        derivation: found.derivation,
+        targetScoped: substituted,
+      });
+      if (!selectAll) break;
+    }
+
+    if (checks.length > 0) {
+      const fellBack = !selectAll && checks[0].role !== roles[0];
+      return {
+        resolution: 'RESOLVED',
+        reason: fellBack
+          ? `Using the '${checks[0].role}' command; ${notes.join('; ')}.`
+          : null,
+        checks,
+        ...(selection ? { selection } : {}),
+      };
+    }
+
+    // Explicit human declaration outranks everything: the plan said this project has no such
+    // command, which is a statement, not a detection miss.
+    if (roles.every((role: string) => declaredNone.has(role))) {
+      return {
+        resolution: 'NOT_APPLICABLE',
+        reason: `plan.md declares this project has no ${roles.join('/')} command.`,
+      };
+    }
+
+    // A manifest was read and does not declare the role. For build or lint that is real evidence
+    // the project has no such step; for a test command it is not, and `absenceIsEvidence: false`
+    // in the registry is what keeps that case UNRESOLVED and off PASS.
+    if (tier.absenceIsEvidence && detection.manifestFound && roles.every((role: string) => absent.has(role) || declaredNone.has(role))) {
+      return {
+        resolution: 'NOT_APPLICABLE',
+        reason: `${detection.manifests.join(', ')} declares no ${roles.join('/')} step.`,
+      };
+    }
+
+    const why = detection.manifestFound
+      ? `no ${roles.join('/')} command could be detected from ${detection.manifests.join(', ')}`
+      : `no project manifest was found under ${detection.projectRoot || this.cwd}`;
+    return {
+      resolution: 'UNRESOLVED',
+      reason: `${why}. Declare it in plan.md's \`${this.policy.planOverrideBlock}\` block (use null to state the project has none).`,
+    };
+  }
+
+  /** @private */
+  resolveStructuralTier(tier: any, structuralChecks: any[]): any {
+    const checks = structuralChecks
+      .filter((c) => c && typeof c.command === 'string' && c.command.trim() !== '')
+      .map((c, i) => ({
+        name: `${tier.id}:${c.name || `invariant_${i + 1}`}`,
+        tier: tier.id,
+        role: 'structural',
+        command: c.command,
+        timeoutMs: c.timeoutMs || tier.timeoutMs || undefined,
+        source: 'caller',
+        derivation: 'declared',
+      }));
+    if (checks.length === 0) {
+      return {
+        resolution: 'UNRESOLVED',
+        reason: 'No structural invariant checks were supplied, and this risk level requires structural evidence.',
+      };
+    }
+    return { resolution: 'RESOLVED', checks, reason: null };
+  }
+
+  /** @private */
+  resolveRequirementTier(tier: any, requirements: any[]): any {
+    const checks: any[] = [];
+    const unevaluated: any[] = [];
+    for (const req of requirements) {
+      if (!req || typeof req.id !== 'string' || req.id === '') continue;
+      if (typeof req.command === 'string' && req.command.trim() !== '') {
+        checks.push({
+          name: `${tier.id}:${req.id}`,
+          tier: tier.id,
+          role: 'requirement',
+          requirementId: req.id,
+          description: req.description || null,
+          command: req.command,
+          timeoutMs: req.timeoutMs || tier.timeoutMs || undefined,
+          source: 'caller',
+          derivation: 'declared',
+        });
+      } else {
+        // An asserted requirement is not a verified one. It is listed so the report can name what
+        // is unproven, rather than counted as satisfied.
+        unevaluated.push({ id: req.id, description: req.description || null });
+      }
+    }
+    if (checks.length === 0 && unevaluated.length === 0) {
+      return {
+        resolution: 'UNRESOLVED',
+        reason: 'No requirement checks were supplied, and this risk level requires requirement evidence.',
+      };
+    }
+    return {
+      resolution: 'RESOLVED',
+      checks,
+      unevaluatedRequirements: unevaluated,
+      reason: unevaluated.length > 0
+        ? `${unevaluated.length} requirement(s) have no executable check and cannot be reported satisfied.`
+        : null,
+    };
+  }
+
+  /** @private */
+  resolveScopeTier(tier: any, scope: any): any {
+    const maxFiles = Number.isFinite(scope.maxFiles) ? scope.maxFiles : null;
+    const allowedPaths = toStringArray(scope.allowedPaths);
+    if (maxFiles === null && allowedPaths.length === 0) {
+      return {
+        resolution: 'UNRESOLVED',
+        reason: typeof scope.unresolvedReason === 'string' && scope.unresolvedReason !== ''
+          ? scope.unresolvedReason
+          : 'No change-scope bound was declared before implementation, so the actual scope has nothing to be compared against.',
+      };
+    }
+    return {
+      resolution: 'RESOLVED',
+      bound: {
+        maxFiles,
+        allowedPaths,
+        ...(typeof scope.source === 'string' ? { source: scope.source } : {}),
+        ...(Array.isArray(scope.sources) ? { sources: scope.sources } : {}),
+        ...(scope.baseline === 'integration' ? { baseline: 'integration' } : {}),
+        ...(scope.baseline === 'explicit' ? { baseline: 'explicit', baselineRef: scope.baselineRef, baselineSha: scope.baselineSha } : {}),
+      },
+      reason: null,
+    };
+  }
+
+  /**
+   * Observes which files the change actually touched.
+   * @private
+   * @param {Array<string>} [changedFiles] caller-supplied files, which win over any observation
+   * @param {Object} [bound] a bound with `baseline: 'integration'` adds the files committed since the
+   *   merge base with the integration ref to the working tree's
+   * @returns {{ files: Array<string>|null, reason: string|null, baseline?: Object }}
+   */
+  observeChangedFiles(changedFiles: any, bound: any = null): any {
+    // An explicit baseline observes git itself: a caller's file list cannot stand in for what changed.
+    if (bound && bound.baseline === 'explicit') return this.observeSince(bound.baselineSha, { kind: 'pinned', ref: bound.baselineRef, sha: bound.baselineSha });
+    if (Array.isArray(changedFiles)) return { files: changedFiles.filter((f: any) => typeof f === 'string'), reason: null };
+
+    if (bound && bound.baseline === 'integration') return this.observeFromBase();
+
+    let res: any;
+    try {
+      res = this.exec('git status --porcelain', {
+        shell: true,
+        cwd: this.cwd,
+        encoding: 'utf8',
+        timeout: 30000,
+      });
+    } catch (error: any) {
+      return { files: null, reason: `Could not observe the changed files: ${error.message}` };
+    }
+    if (!res || res.error || res.status !== 0) {
+      const detail = (res && res.error && res.error.message) || (res && truncate(res.stderr)) || 'git returned a non-zero status';
+      return { files: null, reason: `Could not observe the changed files: ${detail}` };
+    }
+    return { files: parsePorcelain(res.stdout), reason: null };
+  }
+
+  /**
+   * The changed files the test selector reads. Same sources as `observeChangedFiles`, except that
+   * with no baseline and no caller list the working tree is read NUL-separated, unquoted and with
+   * untracked directories expanded, so a non-ASCII name or a new directory of tests is not dropped.
+   * @private
+   */
+  observeForSelection(changedFiles: any, bound: any = null): any {
+    const hasBaseline = bound && (bound.baseline === 'explicit' || bound.baseline === 'integration');
+    if (!Array.isArray(changedFiles) && !hasBaseline) return this.observeSince(null, null);
+    return this.observeChangedFiles(changedFiles, bound);
+  }
+
+  /**
+   * The bounded observation (IC-004): files committed since the merge base with the integration ref,
+   * plus the working tree. Paths are read NUL-separated and unquoted, so a name with a space or
+   * non-ASCII characters is the name the plan wrote, and renames are not collapsed, so a moved file
+   * reports both where it was and where it went.
+   * @private
+   */
+  observeFromBase(): any {
+    const base = resolveIntegrationBase({ cwd: this.cwd, exec: this.exec });
+    if (base.reason) {
+      const working = this.observeSince(null, null);
+      if (working.files === null) return working;
+      return { files: working.files, reason: null, baseline: { kind: 'working-tree', note: base.note || `${base.reason}; only the working tree was compared` } };
+    }
+    return this.observeSince(base.mergeBase, { kind: 'merge-base', ref: base.ref, mergeBase: base.mergeBase });
+  }
+
+  /**
+   * Files changed since `commit` (null: the working tree alone): committed changes to HEAD, staged,
+   * unstaged and untracked paths. NUL-delimited, unquoted, with renames split so both names count; only
+   * DoFlow's own `.doflow/` state is excluded.
+   * @private
+   */
+  observeSince(commit: string | null, baseline: any): any {
+    const git = (args: string[]) => {
+      let res: any;
+      try {
+        res = this.exec('git', ['-c', 'core.quotePath=false', ...args], { cwd: this.cwd, encoding: 'utf8', timeout: 30000 });
+      } catch (error: any) {
+        return { reason: `Could not observe the changed files: ${error.message}` };
+      }
+      if (!res || res.error || res.status !== 0) {
+        const detail = (res && res.error && res.error.message) || (res && truncate(res.stderr)) || 'git returned a non-zero status';
+        return { reason: `Could not observe the changed files: ${detail}` };
+      }
+      return { out: String(res.stdout || '') };
+    };
+    const status = git(['status', '--porcelain', '-z', '--no-renames', '--untracked-files=all']);
+    if (status.reason) return { files: null, reason: status.reason };
+    // `-z` porcelain entries are `XY <path>` separated by NUL.
+    // `.doflow/` is DoFlow's own state (records, journals): writing it is not changing the project,
+    // and a repo that does not ignore it would otherwise fail its own scope after any record.
+    const counts = (f: string) => f !== '.doflow' && !f.startsWith('.doflow/');
+    const working = status.out!.split('\0').filter(Boolean).map((entry: string) => entry.slice(3)).filter(Boolean).filter(counts);
+    if (commit === null) return { files: working, reason: null };
+
+    const diff = git(['diff', '--name-only', '--no-renames', '-z', `${commit}..HEAD`]);
+    if (diff.reason) return { files: null, reason: diff.reason };
+    const committed = diff.out!.split('\0').filter(Boolean).filter(counts);
+    return { files: [...new Set([...committed, ...working])], reason: null, baseline };
+  }
+
+  /**
+   * Runs a compiled contract and produces the report. Called **after** implementation.
+   *
+   * @param {Object} contract from `compileContract`
+   * @param {Object} [runtimeInput]
+   * @param {Array<string>} [runtimeInput.changedFiles] overrides the git observation
+   * @param {{status: string, findings?: Array<string>, reviewer?: string}} [runtimeInput.modelReview]
+   * @returns {Object} the report
+   */
+  runContract(contract: any, runtimeInput: any = {}): any {
+    if (!contract || !Array.isArray(contract.tiers)) {
+      throw new Error('runContract expects a contract produced by compileContract');
+    }
+
+    const startedAt = this.timestamp();
+    const reportTiers: any[] = [];
+    const failedChecks: string[] = [];
+    let fatalTier: string | null = null;
+    let checksRun = 0;
+    let checksPassed = 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<string, any>();
+
+    for (const tier of contract.tiers) {
+      const entry: any = {
+        id: tier.id,
+        name: tier.name,
+        kind: tier.kind,
+        required: tier.required,
+        advisory: tier.advisory,
+        modelBased: tier.modelBased,
+        failureClass: tier.failureClass,
+        status: tier.resolution === 'RESOLVED' ? 'NOT_RUN' : tier.resolution,
+        reason: tier.reason,
+        checks: [],
+        ...(tier.selection ? { selection: tier.selection } : {}),
+        ...(tier.subsumedBy ? { subsumedBy: tier.subsumedBy } : {}),
+      };
+
+      if (tier.resolution !== 'RESOLVED') {
+        reportTiers.push(entry);
+        continue;
+      }
+
+      if (fatalTier) {
+        entry.status = 'NOT_RUN';
+        entry.reason = `Not run: the fatal '${fatalTier}' tier failed, so any result here would describe that failure rather than this tier.`;
+        reportTiers.push(entry);
+        continue;
+      }
+
+      if (tier.modelBased) {
+        Object.assign(entry, this.evaluateModelTier(tier, runtimeInput.modelReview));
+        reportTiers.push(entry);
+        continue;
+      }
+
+      if (tier.kind === 'scope') {
+        Object.assign(entry, this.evaluateScopeTier(tier, runtimeInput.changedFiles));
+        reportTiers.push(entry);
+        continue;
+      }
+
+      for (const check of tier.checks) {
+        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.status === 'PASS') checksPassed += 1;
+        else failedChecks.push(result.name);
+      }
+
+      const anyFailed = entry.checks.some((c: any) => c.status === 'FAIL');
+      if (anyFailed) {
+        entry.status = 'FAIL';
+        if (tier.fatal) fatalTier = tier.id;
+      } else if (Array.isArray(tier.unevaluatedRequirements) && tier.unevaluatedRequirements.length > 0) {
+        // Every executable requirement check passed, but some requirements had none. Reporting the
+        // tier as PASS would claim satisfaction for requirements nothing evaluated.
+        entry.status = 'UNRESOLVED';
+        entry.unevaluatedRequirements = tier.unevaluatedRequirements;
+      } else if (entry.checks.length === 0) {
+        entry.status = 'UNRESOLVED';
+        entry.reason = 'Tier resolved but contributed no runnable check.';
+      } else {
+        entry.status = 'PASS';
+      }
+      reportTiers.push(entry);
+    }
+
+    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');
+    const evaluated = reportTiers.filter((t) => t.status === 'PASS' || t.status === 'FAIL');
+    const modelTier = reportTiers.find((t) => t.modelBased);
+
+    let status: string;
+    let reason: string;
+    if (evaluated.length === 0) {
+      // The empty-contract defect, generalized: zero evaluated tiers is a verdict over zero
+      // evidence whether the contract was empty or every tier turned out unresolvable.
+      status = 'INCONCLUSIVE';
+      reason = contract.tiers.every((t: any) => t.resolution === 'SKIPPED')
+        ? 'Contract declared no checks; nothing was verified'
+        : 'No tier produced a result; nothing was verified';
+    } else if (requiredFailed.length > 0) {
+      status = 'FAIL';
+      reason = `Required tier(s) failed: ${requiredFailed.map((t) => t.id).join(', ')}.`;
+    } else if (modelTier && modelTier.status === 'FAIL') {
+      // A model review can lower the verdict but never raise it — checked after the deterministic
+      // tiers so it is never the thing that established correctness.
+      status = 'FAIL';
+      reason = 'Model-based review reported a failure.';
+    } else if (requiredUnverified.length > 0) {
+      status = 'INCONCLUSIVE';
+      reason = `Required tier(s) were never evaluated: ${requiredUnverified.map((t) => t.id).join(', ')}.`;
+    } else {
+      status = 'PASS';
+      reason = 'Every required tier passed.';
+    }
+
+    const requirementTier = reportTiers.find((t) => t.kind === 'requirement');
+    const scopeTier = reportTiers.find((t) => t.kind === 'scope');
+
+    return {
+      version: contract.version,
+      taskId: contract.taskId,
+      riskLevel: contract.riskLevel,
+      status,
+      reason,
+      startedAt,
+      finishedAt: this.timestamp(),
+      tiers: reportTiers,
+      failedChecks,
+      counts: {
+        checksRun,
+        checksPassed,
+        checksFailed: checksRun - checksPassed,
+        tiersRequired: requiredTiers.length,
+        tiersPassed: requiredTiers.filter((t) => t.status === 'PASS').length,
+        tiersFailed: requiredFailed.length,
+        tiersUnverified: requiredUnverified.length,
+        tiersNotApplicable: requiredTiers.filter((t) => t.status === 'NOT_APPLICABLE' || t.status === 'SUBSUMED').length,
+      },
+      requirementSatisfaction: requirementTier
+        ? {
+          status: requirementTier.status,
+          satisfied: requirementTier.checks.filter((c: any) => c.status === 'PASS').map((c: any) => c.requirementId || c.name),
+          failed: requirementTier.checks.filter((c: any) => c.status === 'FAIL').map((c: any) => c.requirementId || c.name),
+          unevaluated: (requirementTier.unevaluatedRequirements || []).map((r: any) => r.id),
+        }
+        : null,
+      scope: scopeTier ? scopeTier.scope || { status: scopeTier.status, reason: scopeTier.reason } : null,
+      modelReview: modelTier
+        ? { status: modelTier.status, primaryProof: false, findings: modelTier.findings || [] }
+        : null,
+      unresolved: reportTiers
+        .filter((t) => t.status === 'UNRESOLVED' || t.status === 'NOT_RUN')
+        .map((t) => ({ tier: t.id, required: t.required, reason: t.reason })),
+      // A PASS reached with several tiers declared inapplicable is still a PASS, but a reader who
+      // cannot see which tiers never ran will over-read it. Listed next to the verdict, not buried.
+      notApplicable: reportTiers
+        .filter((t) => t.status === 'NOT_APPLICABLE' || t.status === 'SUBSUMED')
+        .map((t) => ({ tier: t.id, status: t.status, reason: t.reason })),
+      // The contract's own chronology and provenance travel with the verdict, so a report cannot read
+      // as stronger evidence than the contract it was run against (IC-022).
+      contract: {
+        compiledAt: contract.compiledAt || null,
+        phase: contract.phase || 'unknown',
+        compiledBeforeImplementation: contract.compiledBeforeImplementation === undefined ? null : contract.compiledBeforeImplementation,
+        ...(contract.provenance ? { provenance: contract.provenance } : {}),
+      },
+      detection: contract.detection,
+    };
+  }
+
+  /** @private */
+  evaluateModelTier(tier: any, modelReview: any): any {
+    if (!modelReview || typeof modelReview.status !== 'string') {
+      return {
+        status: 'UNRESOLVED',
+        reason: 'No model review was supplied for a risk level that requires one to be recorded.',
+        findings: [],
+      };
+    }
+    const supplied = modelReview.status.toUpperCase();
+    if (supplied === 'FAIL') {
+      return { status: 'FAIL', reason: 'Model review reported findings.', findings: toStringArray(modelReview.findings) };
+    }
+    if (supplied === 'PASS') {
+      // Recorded as PASS for the tier, but the overall verdict already required every deterministic
+      // tier to pass before reaching here — this never becomes the proof of anything on its own.
+      return { status: 'PASS', reason: 'Model review recorded no findings; advisory only.', findings: [] };
+    }
+    return {
+      status: 'UNRESOLVED',
+      reason: `Model review status '${modelReview.status}' is neither PASS nor FAIL.`,
+      findings: toStringArray(modelReview.findings),
+    };
+  }
+
+  /** @private */
+  evaluateScopeTier(tier: any, changedFiles: any): any {
+    const bound = tier.bound || { maxFiles: null, allowedPaths: [] };
+    const { files, reason, baseline } = this.observeChangedFiles(changedFiles, bound);
+    if (files === null) {
+      return {
+        status: 'UNRESOLVED',
+        reason,
+        scope: { bound, actual: null, withinBound: null, reason },
+      };
+    }
+
+    const violations: string[] = [];
+    if (Number.isFinite(bound.maxFiles) && files.length > bound.maxFiles) {
+      violations.push(`${files.length} files changed, bound was ${bound.maxFiles}`);
+    }
+    if (bound.allowedPaths.length > 0) {
+      const outside = files.filter((f: string) => !bound.allowedPaths.some((p: string) => f === p || f.startsWith(p.endsWith('/') ? p : `${p}/`)));
+      if (outside.length > 0) violations.push(`outside the declared paths: ${outside.join(', ')}`);
+    }
+
+    const withinBound = violations.length === 0;
+    // A bound measured from the working tree alone (no integration ref) says so: committed work
+    // is invisible to it, which is a limit of the answer, not a clean result.
+    const note = baseline && baseline.note ? baseline.note : null;
+    const verdictReason = withinBound
+      ? note
+      : `Change exceeded its declared scope — ${violations.join('; ')}.${note ? ` (${note})` : ''}`;
+    return {
+      status: withinBound ? 'PASS' : 'FAIL',
+      reason: verdictReason,
+      scope: { bound, actual: { fileCount: files.length, files }, withinBound, violations, ...(baseline ? { baseline } : {}) },
+    };
+  }
+
+  /**
+   * Declares completion. FR-009: a task is complete only when its required checks pass, or when the
+   * user explicitly accepts what is still failing.
+   *
+   * @param {Object} report
+   * @param {Object} [acceptance]
+   * @param {boolean} [acceptance.userAccepted]
+   * @param {string} [acceptance.acceptedBy] who accepted; an unattributed acceptance is refused
+   * @param {string} [acceptance.note]
+   * @returns {{ complete: boolean, basis: string, reason: string, acceptedFailures?: Array<Object> }}
+   */
+  declareCompletion(report: any, acceptance: any = {}): any {
+    if (!report || typeof report.status !== 'string') {
+      throw new Error('declareCompletion expects a report produced by runContract');
+    }
+    if (report.status === 'PASS') {
+      return { complete: true, basis: 'required-checks-passed', reason: report.reason };
+    }
+    if (acceptance.userAccepted !== true) {
+      return {
+        complete: false,
+        basis: 'not-accepted',
+        reason: `Verification is ${report.status}: ${report.reason} Completion needs the required checks to pass or an explicit user acceptance.`,
+      };
+    }
+    const requiresAccepter = (this.policy.completion || {}).overrideRequiresAccepter !== false;
+    if (requiresAccepter && (typeof acceptance.acceptedBy !== 'string' || acceptance.acceptedBy.trim() === '')) {
+      // "The user explicitly accepts" needs a user. An anonymous flag is indistinguishable from the
+      // caller setting it for itself.
+      return {
+        complete: false,
+        basis: 'acceptance-unattributed',
+        reason: 'Accepting a failing verification requires naming who accepted it.',
+      };
+    }
+    return {
+      complete: true,
+      basis: 'user-accepted-failures',
+      reason: acceptance.note || `Accepted by ${acceptance.acceptedBy} while ${report.status}.`,
+      acceptedFailures: (report.tiers || [])
+        .filter((t: any) => t.required && t.status !== 'PASS' && t.status !== 'NOT_APPLICABLE' && t.status !== 'SUBSUMED' && t.status !== 'SKIPPED')
+        .map((t: any) => ({ tier: t.id, status: t.status, reason: t.reason })),
+    };
+  }
+
+  /**
+   * A stable fingerprint of what failed. Two identical fingerprints across attempts mean the retry
+   * changed nothing observable, which FR-010 forbids as a response.
+   * @param {Object} report
+   * @returns {string}
+   */
+  failureSignature(report: any): string {
+    const failed = [...(report.failedChecks || [])].sort().join('|');
+    const unresolved = (report.unresolved || []).map((u: any) => u.tier).sort().join('|');
+    return `${report.status}::${failed}::${unresolved}`;
+  }
+
+  /**
+   * Classifies a failing report and returns the targeted action for that class (C8), bounded by the
+   * risk level's retry limit.
+   *
+   * @param {Object} report
+   * @param {Object} [options]
+   * @param {number} [options.iteration=0] retries already spent
+   * @param {string} [options.lastAgent]
+   * @param {number} [options.maxIterations] defaults to the report's risk level
+   * @returns {Object|null} null when there is nothing to recover from
+   */
+  planRecovery(report: any, options: any = {}): any {
+    if (!report || report.status === 'PASS') return null;
+
+    const maxIterations = Number.isInteger(options.maxIterations)
+      ? options.maxIterations
+      : this.riskDefinition(report.riskLevel).maxRecoveryIterations;
+    const manager = this.recoveryOverride || new RecoveryManager({ maxIterations });
+
+    const failingTier = (report.tiers || []).find((t: any) => t.required && t.status === 'FAIL')
+      || (report.tiers || []).find((t: any) => t.status === 'FAIL');
+    const unverifiedTier = (report.tiers || []).find((t: any) => t.required && (t.status === 'UNRESOLVED' || t.status === 'NOT_RUN'));
+
+    let failureClass: string;
+    let classificationSource: string;
+    let errorMessage: string;
+    let hint: string | null = null;
+
+    if (failingTier) {
+      const firstFailure = (failingTier.checks || []).find((c: any) => c.status === 'FAIL');
+      errorMessage = [failingTier.reason, firstFailure && firstFailure.error, firstFailure && firstFailure.stderr]
+        .filter(Boolean)
+        .join(' ');
+      // A tier's declared class is structural evidence about what kind of check failed; the keyword
+      // classifier reads prose. recovery.js already prefers structure over prose between check
+      // names and error text, and this applies the same precedence one level up. The classifier
+      // still runs and is reported, so a disagreement stays visible rather than being hidden.
+      const classified = manager.classifyFailure(errorMessage, report.failedChecks);
+      failureClass = failingTier.failureClass || classified;
+      classificationSource = failingTier.failureClass ? 'tier-declaration' : 'classifier';
+      if (failingTier.failureClass && failingTier.failureClass !== classified) {
+        hint = `Keyword classifier suggested ${classified}; the '${failingTier.id}' tier declares ${failingTier.failureClass}.`;
+      }
+    } else if (unverifiedTier) {
+      errorMessage = unverifiedTier.reason || 'A required verification tier was never evaluated.';
+      failureClass = this.policy.unresolvedDetectionFailureClass || manager.classifyFailure(errorMessage, []);
+      classificationSource = 'unresolved-tier';
+      hint = `Nothing verified the '${unverifiedTier.id}' tier. Declare its command in plan.md's \`${this.policy.planOverrideBlock}\` block, or set it to null to state the project has none.`;
+    } else {
+      errorMessage = report.reason || 'Verification did not pass.';
+      failureClass = manager.classifyFailure(errorMessage, report.failedChecks);
+      classificationSource = 'classifier';
+    }
+
+    const plan = manager.planRecovery(failureClass, options.iteration || 0, options.lastAgent);
+    return {
+      ...plan,
+      classificationSource,
+      maxIterations,
+      errorMessage,
+      hint,
+      reportStatus: report.status,
+      failureSignature: this.failureSignature(report),
+    };
+  }
+
+  /**
+   * Runs a contract and, on failure, drives the bounded recovery loop.
+   *
+   * `remediate` must report that it changed something. FR-010 forbids re-running unchanged
+   * behaviour, so a remediation that returns `changed !== true` stops the loop instead of producing
+   * a second identical attempt, and an attempt whose failure fingerprint repeats stops it too — a
+   * change that altered nothing observable is the same thing wearing a different hat.
+   *
+   * @param {Object} contract
+   * @param {Object} [options]
+   * @param {Function} [options.remediate] `(plan, report, iteration) => {changed: boolean, contract?}`
+   * @param {string} [options.lastAgent]
+   * @param {Object} [options.runtimeInput] forwarded to each `runContract`
+   * @returns {{ outcome: string, report: Object, plan: Object|null, attempts: Array<Object>, reason: string }}
+   */
+  runWithRecovery(contract: any, options: any = {}): any {
+    let current = contract;
+    let lastAgent = options.lastAgent;
+    let previousSignature: string | null = null;
+    let iteration = 0;
+    const attempts: any[] = [];
+
+    for (;;) {
+      const report = this.runContract(current, options.runtimeInput || {});
+      const signature = this.failureSignature(report);
+      attempts.push({ iteration, status: report.status, signature, failedChecks: report.failedChecks });
+
+      if (report.status === 'PASS') {
+        return { outcome: 'PASS', report, plan: null, attempts, reason: report.reason };
+      }
+      if (signature === previousSignature) {
+        return {
+          outcome: 'NO_PROGRESS',
+          report,
+          plan: null,
+          attempts,
+          reason: 'The previous recovery reported a change but produced an identical failure; retrying again would repeat unchanged behaviour.',
+        };
+      }
+      previousSignature = signature;
+
+      const plan = this.planRecovery(report, { iteration, lastAgent });
+      if (!plan.canRetry) {
+        return { outcome: 'ABORTED', report, plan, attempts, reason: plan.reason };
+      }
+      if (typeof options.remediate !== 'function') {
+        return {
+          outcome: 'NO_REMEDIATION',
+          report,
+          plan,
+          attempts,
+          reason: `Recovery action ${plan.action} is available but no remediation callback was supplied.`,
+        };
+      }
+
+      const outcome = options.remediate(plan, report, iteration);
+      if (!outcome || outcome.changed !== true) {
+        return {
+          outcome: 'NO_CHANGE',
+          report,
+          plan,
+          attempts,
+          reason: `Remediation for ${plan.failureClass} reported no change; re-running unchanged behaviour is not a permitted response.`,
+        };
+      }
+      if (outcome.contract) current = outcome.contract;
+      lastAgent = plan.agent;
+      iteration += 1;
+    }
+  }
+
+  /**
+   * Convenience: compile, run, and report in one call. The two halves stay separately callable
+   * because FR-009 requires the contract to exist *before* implementation, which this shape cannot
+   * express on its own.
+   * @param {Object} input `compileContract` input
+   * @param {Object} [runtimeInput] `runContract` input
+   */
+  verify(input: any, runtimeInput: any): any {
+    const contract = this.compileContract(input);
+    return { contract, report: this.runContract(contract, runtimeInput) };
+  }
+}
+
+/**
+ * Handles `doflow verify` — compile the verification contract (FR-009) and, by default, run it and
+ * report against it.
+ *
+ * `--action contract` stops after compiling, which is the before-implementation half: it states
+ * how success will be established without establishing anything. The default runs the checks and
+ * emits the report. The contract is recompiled rather than read back from a state file, so the two
+ * halves cannot describe different contracts.
+ *
+ * @param {Object} options
+ * @param {string} options.taskId
+ * @param {'report'|'contract'|'status'} [options.action='report']
+ * @param {string} [options.risk] risk level; the registry's default when omitted
+ * @param {string} [options.planPath] a `plan.md` whose command override beats detection
+ * @param {boolean} [options.json=false]
+ * @param {string} [options.projectRoot]
+ * @param {string} [options.slug] the feature whose plan bounds the change; the branch's when omitted
+ * @param {string} [options.scope] a declared scope (`<path>[,<path>...]`), unioned with any plan bound
+ * @returns {number} exit code
+ */
+/**
+ * Validates a verification input manifest file (IC-022).
+ *
+ * @param {Object} options
+ * @param {string} options.cwd
+ * @param {string} options.verificationInput
+ * @param {Object} [options.fs]
+ * @param {Object} [options.crypto]
+ * @returns {{ ok: true, structuralChecks: Array<Object>, requirements: Array<Object>, provenance: Object } | { ok: false, message: string }}
+ */
+function validateVerificationInput({ cwd, verificationInput, fs = nodeFs, crypto = nodeCrypto }: {
+  cwd: string;
+  verificationInput: any;
+  fs?: any;
+  crypto?: any;
+}): any {
+  if (typeof verificationInput !== 'string' || verificationInput.trim() === '') {
+    return { ok: false, message: '--verification-input requires a file path.' };
+  }
+  const inputAbs = path.isAbsolute(verificationInput) ? verificationInput : path.resolve(cwd, verificationInput);
+  let rawBytes: Buffer;
+  try {
+    rawBytes = fs.readFileSync(inputAbs);
+  } catch (err: any) {
+    return { ok: false, message: `--verification-input '${verificationInput}' could not be read: ${err.message}` };
+  }
+  const manifestDigest = 'sha256:' + crypto.createHash('sha256').update(rawBytes).digest('hex');
+  let manifest: any;
+  try {
+    manifest = JSON.parse(rawBytes.toString('utf8'));
+  } catch (err: any) {
+    return { ok: false, message: `--verification-input '${verificationInput}' is not valid JSON: ${err.message}` };
+  }
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) {
+    return { ok: false, message: `--verification-input '${verificationInput}' must be a JSON object.` };
+  }
+
+  const ALLOWED_KEYS = new Set(['structuralChecks', 'requirements', 'originalContractPath', 'originalContractDigest']);
+  for (const key of Object.keys(manifest)) {
+    if (!ALLOWED_KEYS.has(key)) {
+      return { ok: false, message: `--verification-input '${verificationInput}' contains unknown field '${key}'.` };
+    }
+  }
+
+  const hasOrigPath = manifest.originalContractPath !== undefined;
+  const hasOrigDigest = manifest.originalContractDigest !== undefined;
+  if ((hasOrigPath && !hasOrigDigest) || (!hasOrigPath && hasOrigDigest)) {
+    return { ok: false, message: `--verification-input '${verificationInput}' must specify both originalContractPath and originalContractDigest together.` };
+  }
+  if (hasOrigPath && hasOrigDigest) {
+    if (typeof manifest.originalContractPath !== 'string' || manifest.originalContractPath.trim() === '') {
+      return { ok: false, message: '--verification-input originalContractPath must be a non-empty string.' };
+    }
+    if (typeof manifest.originalContractDigest !== 'string' || !/^sha256:[0-9a-f]{64}$/.test(manifest.originalContractDigest)) {
+      return { ok: false, message: '--verification-input originalContractDigest must be in format sha256:<64 hex chars>.' };
+    }
+    const origAbs = path.isAbsolute(manifest.originalContractPath) ? manifest.originalContractPath : path.resolve(cwd, manifest.originalContractPath);
+    let origBytes: Buffer;
+    try {
+      origBytes = fs.readFileSync(origAbs);
+    } catch (err: any) {
+      return { ok: false, message: `--verification-input originalContractPath '${manifest.originalContractPath}' could not be read: ${err.message}` };
+    }
+    const actualOrigDigest = 'sha256:' + crypto.createHash('sha256').update(origBytes).digest('hex');
+    if (actualOrigDigest !== manifest.originalContractDigest) {
+      return { ok: false, message: `--verification-input originalContractDigest mismatch for '${manifest.originalContractPath}': expected ${manifest.originalContractDigest}, got ${actualOrigDigest}.` };
+    }
+  }
+
+  let structuralChecks: any[] = [];
+  if (manifest.structuralChecks !== undefined) {
+    if (!Array.isArray(manifest.structuralChecks)) {
+      return { ok: false, message: '--verification-input structuralChecks must be an array.' };
+    }
+    const seenNames = new Set<string>();
+    const ALLOWED_STRUCT_KEYS = new Set(['name', 'command', 'timeoutMs']);
+    for (let i = 0; i < manifest.structuralChecks.length; i++) {
+      const entry = manifest.structuralChecks[i];
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        return { ok: false, message: `--verification-input structuralChecks[${i}] must be an object.` };
+      }
+      for (const k of Object.keys(entry)) {
+        if (!ALLOWED_STRUCT_KEYS.has(k)) {
+          return { ok: false, message: `--verification-input structuralChecks[${i}] contains unknown field '${k}'.` };
+        }
+      }
+      if (typeof entry.name !== 'string' || entry.name.trim() === '') {
+        return { ok: false, message: `--verification-input structuralChecks[${i}].name must be a non-empty string.` };
+      }
+      if (seenNames.has(entry.name)) {
+        return { ok: false, message: `--verification-input duplicate structural check name '${entry.name}'.` };
+      }
+      seenNames.add(entry.name);
+      if (typeof entry.command !== 'string' || entry.command.trim() === '') {
+        return { ok: false, message: `--verification-input structuralChecks[${i}].command must be a non-empty string.` };
+      }
+      if (entry.timeoutMs !== undefined && (!Number.isInteger(entry.timeoutMs) || entry.timeoutMs <= 0)) {
+        return { ok: false, message: `--verification-input structuralChecks[${i}].timeoutMs must be a positive integer.` };
+      }
+    }
+    structuralChecks = manifest.structuralChecks;
+  }
+
+  let requirements: any[] = [];
+  if (manifest.requirements !== undefined) {
+    if (!Array.isArray(manifest.requirements)) {
+      return { ok: false, message: '--verification-input requirements must be an array.' };
+    }
+    const seenIds = new Set<string>();
+    const ALLOWED_REQ_KEYS = new Set(['id', 'description', 'command', 'timeoutMs']);
+    for (let i = 0; i < manifest.requirements.length; i++) {
+      const entry = manifest.requirements[i];
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+        return { ok: false, message: `--verification-input requirements[${i}] must be an object.` };
+      }
+      for (const k of Object.keys(entry)) {
+        if (!ALLOWED_REQ_KEYS.has(k)) {
+          return { ok: false, message: `--verification-input requirements[${i}] contains unknown field '${k}'.` };
+        }
+      }
+      if (typeof entry.id !== 'string' || entry.id.trim() === '') {
+        return { ok: false, message: `--verification-input requirements[${i}].id must be a non-empty string.` };
+      }
+      if (seenIds.has(entry.id)) {
+        return { ok: false, message: `--verification-input duplicate requirement id '${entry.id}'.` };
+      }
+      seenIds.add(entry.id);
+      if (entry.description !== undefined && typeof entry.description !== 'string') {
+        return { ok: false, message: `--verification-input requirements[${i}].description must be a string.` };
+      }
+      if (entry.command !== undefined && (typeof entry.command !== 'string' || entry.command.trim() === '')) {
+        return { ok: false, message: `--verification-input requirements[${i}].command must be a non-empty string when provided.` };
+      }
+      if (entry.timeoutMs !== undefined && (!Number.isInteger(entry.timeoutMs) || entry.timeoutMs <= 0)) {
+        return { ok: false, message: `--verification-input requirements[${i}].timeoutMs must be a positive integer.` };
+      }
+    }
+    requirements = manifest.requirements;
+  }
+
+  const provenance = {
+    manifestPath: verificationInput,
+    manifestDigest,
+    ...(hasOrigPath ? {
+      originalContractPath: manifest.originalContractPath,
+      originalContractDigest: manifest.originalContractDigest,
+    } : {}),
+  };
+
+  return { ok: true, structuralChecks, requirements, provenance };
+}
+
+/**
+ * Handles `doflow verify` — compile the verification contract (FR-009) and, by default, run it and
+ * report against it.
+ *
+ * `--action contract` stops after compiling, which is the before-implementation half: it states
+ * how success will be established without establishing anything. The default runs the checks and
+ * emits the report. The contract is recompiled rather than read back from a state file, so the two
+ * halves cannot describe different contracts.
+ *
+ * @param {Object} options
+ * @param {string} options.taskId
+ * @param {'report'|'contract'|'status'} [options.action='report']
+ * @param {string} [options.risk] risk level; the registry's default when omitted
+ * @param {string} [options.planPath] a `plan.md` whose command override beats detection
+ * @param {boolean} [options.json=false]
+ * @param {string} [options.projectRoot]
+ * @param {string} [options.slug] the feature whose plan bounds the change; the branch's when omitted
+ * @param {string} [options.scope] a declared scope (`<path>[,<path>...]`), unioned with any plan bound
+ * @param {string} [options.verificationInput] path to input manifest with structuralChecks and requirements (IC-022)
+ * @param {string} [options.verificationPhase] explicit compilation phase (e.g. postimplementation) (IC-022)
+ * @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 }: {
+  taskId?: any;
+  action?: string;
+  risk?: any;
+  planPath?: any;
+  json?: boolean;
+  projectRoot?: any;
+  slug?: string | null;
+  scope?: any;
+  verificationInput?: string | null;
+  verificationPhase?: string | null;
+  baselineRef?: string | null;
+} = {}): number {
+  // The task id names state files here, so it obeys the rule every other task verb applies.
+  try {
+    assertSafeTaskId(taskId);
+  } catch (error: any) {
+    return usageError('verify', error.message, json);
+  }
+
+  if (verificationPhase !== null && verificationPhase !== undefined) {
+    if (verificationPhase !== 'postimplementation' && verificationPhase !== 'unknown') {
+      return usageError('verify', `unknown --verification-phase '${verificationPhase}'. Valid: postimplementation`, json);
+    }
+  }
+
+  let declared: any = null;
+  if (scope !== null && scope !== undefined) {
+    const parsed = parseDeclaredScope(typeof scope === 'string' ? scope : '');
+    if (parsed.reason) {
+      return usageError('verify', `--scope ${parsed.reason}. Write repository-relative paths separated by commas, a trailing / for a directory, for example --scope src/a.js,src/lib/. Nothing was changed.`, json);
+    }
+    declared = { paths: parsed.paths, origin: 'verify-flag' };
+  }
+  const cwd = projectRoot || process.cwd();
+
+  let structuralChecks: any[] = [];
+  let requirements: any[] = [];
+  let inputProvenance: any = null;
+  if (verificationInput !== null && verificationInput !== undefined) {
+    const val = validateVerificationInput({ cwd, verificationInput });
+    if (!val.ok) {
+      return usageError('verify', val.message, json);
+    }
+    structuralChecks = val.structuralChecks;
+    requirements = val.requirements;
+    inputProvenance = val.provenance;
+  }
+
+  // The feature the task belongs to, for the readiness record's namespace and for a run keyed by
+  // the feature slug: `--slug`, else the task id's own folder, else the branch's.
+  const featureSlug = featureSlugFor({ projectRoot: cwd, taskId, slug });
+
+  // A scope is declared in one place. The readiness record carries the one stated before the
+  // work; a flag that says something else is refused rather than silently preferred. Records in two
+  // other checkouts declare nothing: the contract says so and still answers.
+  const recorded = readReadinessRecord({ stateRoot: cwd, taskId, slug: featureSlug });
+  const recordNote = recorded.status === 'ambiguous'
+    ? `readiness record: not used; task '${taskId}' has records in more than one other checkout (${recorded.candidates.join(', ')})`
+    : null;
+  // Only a record this runtime can read declares a scope; one it cannot read is reported by the
+  // readiness check, and refusing --scope against it would send the caller to a readiness run that
+  // cannot replace it.
+  const usable = recorded.status === 'found' && recorded.record && recorded.record.version === RECORD_VERSION;
+  const recordedScope = usable && Array.isArray(recorded.record.declaredScope) && recorded.record.declaredScope.length > 0
+    ? recorded.record.declaredScope : null;
+  if (recordedScope) {
+    const recordRel = recorded.origin === 'current' ? path.relative(cwd, recorded.file) : recorded.file;
+    if (declared && !sameSet(declared.paths, recordedScope)) {
+      return usageError('verify', `--scope ${String(scope).trim()} differs from the scope declared in the readiness record ${recordRel} (${recordedScope.join(',')}). A scope is declared in one place: re-run doflow-run readiness --task-class ${recorded.record.taskClass} --task-id ${taskId} --scope ${String(scope).trim()}, or drop --scope. Nothing was changed.`, json);
+    }
+    if (!declared) declared = { paths: [...recordedScope], origin: 'readiness-record', record: recordRel };
+  }
+
+  let engine: any;
+  let contract: any;
+  try {
+    engine = new VerificationEngine({ cwd, repoRoot: REPO_ROOT });
+    // 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 });
+    if (recordNote) resolved.searched.push({ place: 'readiness record', result: recordNote.slice('readiness record: '.length) });
+    const scopeInput = resolved.bound
+      ? { ...resolved.bound, searched: resolved.searched }
+      : { unresolvedReason: resolved.unresolvedReason || scopeReasonText({ reason: resolved.reason, taskId, planSource: resolved.planSource }), searched: resolved.searched };
+    contract = engine.compileContract({
+      taskId,
+      riskLevel: risk,
+      projectRoot: cwd,
+      planPath,
+      scope: scopeInput,
+      phase: verificationPhase,
+      structuralChecks,
+      requirements,
+      provenance: inputProvenance,
+    });
+  } catch (error: any) {
+    return usageError('verify', error.message, json, error);
+  }
+  // The bound's sources print under the change-scope tier's line; no other line changes.
+  const boundLines = new Map(contract.tiers
+    .filter((t: any) => t.bound && Array.isArray(t.bound.sources) && t.bound.sources.length > 0)
+    .map((t: any) => [t.id, `      bound: ${boundSourcesText(t.bound.sources)}`]));
+  if (recordNote) {
+    const scopeTier = contract.tiers.find((t: any) => t.kind === 'scope');
+    if (scopeTier) boundLines.set(scopeTier.id, [boundLines.get(scopeTier.id), `      ${recordNote}`].filter(Boolean).join('\n'));
+  }
+
+  if (action === 'contract') {
+    if (json) console.log(JSON.stringify(contract, null, 2));
+    else {
+      console.log(`\nDoFlow Verification Contract [${contract.taskId}] — risk ${contract.riskLevel}:`);
+      console.log('═'.repeat(78));
+      for (const tier of contract.tiers) {
+        console.log(`  ${tier.id.padEnd(22)} ${tier.resolution.padEnd(12)} ${tier.required ? 'required' : 'advisory'}`);
+        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)}`);
+      }
+      console.log('═'.repeat(78) + '\n');
+    }
+    // A contract is a plan, not a verdict — compiling one always answers, even when a tier could
+    // not be resolved, because the unresolved tier is itself part of what the contract states.
+    return finishRuntime(0);
+  }
+  if (action !== 'report' && action !== 'status') {
+    return usageError('verify', `unknown --action '${action}'. Valid: report (default), contract`, json);
+  }
+
+  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.
+  try {
+    report.readiness = verifyReadinessCheck({ stateRoot: cwd, taskId, slug: featureSlug });
+  } catch (error: any) {
+    return usageError('verify', error.message, json, error);
+  }
+  const readinessHeld = report.readiness.applies && !report.readiness.ok;
+  if (readinessHeld && report.status === 'PASS') {
+    report.status = 'INCONCLUSIVE';
+    report.reason = report.readiness.message;
+  }
+  if (json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`\nDoFlow Verification Report [${report.taskId}] — ${report.status}:`);
+    console.log('═'.repeat(78));
+    console.log(report.reason);
+    if (readinessHeld) console.log(`readiness: ${report.readiness.message}`);
+    console.log('─'.repeat(78));
+    for (const tier of report.tiers) {
+      console.log(`  ${tier.id.padEnd(22)} ${tier.status.padEnd(16)} ${tier.required ? 'required' : 'advisory'}`);
+      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)}`);
+    }
+    console.log('─'.repeat(78));
+    console.log(`Checks: ${report.counts.checksPassed}/${report.counts.checksRun} passed`);
+    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}`);
+    }
+    console.log('═'.repeat(78) + '\n');
+  }
+  // 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);
+}
+
+/** One line stating what the targeted tier selected, or why it ran the broad command instead. */
+function selectionText(selection: any): string {
+  const of = selection.totalCount === null ? '' : ` of ${selection.totalCount}`;
+  if (selection.fallback) return `selection: ${selection.basis}, fell back to the broad command (${selection.fallback})`;
+  if (selection.selectedCount === null) return `selection: ${selection.basis}`;
+  return `selection: ${selection.basis}, ${selection.selectedCount}${of} test files`;
+}
+
+/** Whether two path lists name the same set. */
+function sameSet(a: string[], b: string[]): boolean {
+  const left = new Set(a);
+  const right = new Set(b);
+  return left.size === right.size && [...left].every((p) => right.has(p));
+}
+
+module.exports = {
+  VerificationContractRunner,
+  VerificationEngine,
+  loadVerificationRegistry,
+  VERIFICATION_STATUSES,
+  TIER_RESOLUTIONS,
+  TIER_STATUSES,
+  RECOVERY_OUTCOMES,
+  FATAL_CHECK_MARKERS,
+  TIMEOUT_EXIT_CODE,
+  MAX_STREAM_CHARS,
+  REGISTRY_FILENAME,
+  handleVerifyCommand,
+  validateVerificationInput,
+};