@wkronmiller/lisa 0.1.0

package/src/spec/workflows/check.ts

@@ -0,0 +1,1534 @@
+import { createHash } from "crypto";
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename, dirname, join, relative } from "path";
+
+import { resolveHarnessCommandOverride } from "../../harness/command";
+import { getHarnessAdapterById } from "../../harness/registry";
+import { runHarnessStage } from "../../harness/runner";
+import type { HarnessInspection, HarnessRequest, HarnessResult } from "../../harness/types";
+import { DEFAULT_SPEC_DIFF_BASE_REF, EXTERNAL_SPEC_DIFF_BASE_REF, collectSpecDiff, readExternalSnapshotCodePaths, readExternalSnapshotRepoRevision, readExternalSpecSnapshot, writeExternalSpecSnapshot } from "../diff";
+import { resolveStageProfile } from "../config";
+import { resolveLocalOverrides } from "../local-config";
+import { getExtensionSidecarsForSpec, verifySpecExtensions } from "../extensions/registry";
+import { loadSpecWorkspace, loadSpecWorkspaceAtRef } from "../loader";
+import { parseSpecEnvironmentConfig } from "../parser";
+import { renderCheckPrompt } from "../prompt-renderer";
+import type {
+  LoadedSpecWorkspace,
+  ParsedSpecDocument,
+  ResolvedStageProfile,
+  SpecCheckEvidence,
+  SpecCheckMode,
+  SpecCheckReport,
+  SpecCheckResult,
+  SpecCheckStatus,
+  SpecDriftWarning,
+  ValidationIssue,
+} from "../types";
+import { assertSafeLisaStorageWritePath, listEffectiveWorkspaceFiles, resolveEffectiveProjectSpecPath, resolveWorkspaceLayout, toLogicalPath } from "../workspace";
+import { escapeRegExp, globToRegExp, hasGlobMagic, normalizeRelativePath } from "../path-utils";
+
+const SPEC_CHECK_EVIDENCE_TYPES = new Set<SpecCheckEvidence["type"]>(["test", "benchmark", "code-audit", "config"]);
+
+interface CheckCommandOptions {
+  mode?: SpecCheckMode;
+  base?: string;
+  head?: string;
+  profile?: string;
+  harness?: string;
+  model?: string;
+  help: boolean;
+}
+
+interface CommandExecutionResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+interface DeterministicCheckResult {
+  specId: string;
+  path: string;
+  codePaths: string[];
+  testPaths: string[];
+  testCommands: string[];
+  matchedCodeFiles: string[];
+  matchedTestFiles: string[];
+  evidence: SpecCheckEvidence[];
+  issues: string[];
+  status?: SpecCheckStatus;
+  summary: string;
+}
+
+interface ParsedVerifierAudit {
+  status: Exclude<SpecCheckStatus, "SKIPPED">;
+  summary: string;
+  evidence: SpecCheckEvidence[];
+  issues: string[];
+}
+
+interface CheckTarget {
+  specId: string;
+  path: string;
+  document?: ParsedSpecDocument;
+  validationIssues: ValidationIssue[];
+  driftWarning?: SpecDriftWarning;
+  benchmarkSidecars: ParsedSpecDocument[];
+}
+
+export interface CheckCommandIO {
+  print(message: string): void;
+  error(message: string): void;
+}
+
+export interface CheckCommandDeps {
+  io?: CheckCommandIO;
+  runHarness?: (harnessId: string, request: HarnessRequest, cwd: string) => Promise<HarnessResult>;
+  inspectHarness?: (harnessId: string, cwd: string, commandOverride?: string) => Promise<HarnessInspection>;
+  runCommand?: (command: string, cwd: string) => CommandExecutionResult;
+}
+
+function createConsoleIO(): CheckCommandIO {
+  return {
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+  };
+}
+
+function printCheckHelp(io: CheckCommandIO): void {
+  io.print(`Lisa spec check
+
+Usage:
+  lisa spec check --changed [options]
+  lisa spec check --all [options]
+
+Options:
+  --changed                   Verify only changed or drift-impacted specs
+  --all                       Verify every base spec in the workspace
+  --base <rev>                Diff base revision for --changed (default: HEAD)
+  --head <rev>                Diff head revision for --changed (default: worktree)
+  --profile <name>            Override the check stage profile
+  --harness <id>              Override the configured harness adapter
+  --model <name>              Override the configured model
+  --help, -h                  Show this help
+`);
+}
+
+function parseCheckArgs(args: string[]): CheckCommandOptions {
+  const options: CheckCommandOptions = { help: false };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (!arg) {
+      continue;
+    }
+
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === "--changed") {
+      if (options.mode && options.mode !== "changed") {
+        throw new Error("Choose exactly one of `--changed` or `--all`.");
+      }
+      options.mode = "changed";
+      continue;
+    }
+
+    if (arg === "--all") {
+      if (options.mode && options.mode !== "all") {
+        throw new Error("Choose exactly one of `--changed` or `--all`.");
+      }
+      options.mode = "all";
+      continue;
+    }
+
+    if (arg === "--base" || arg === "--head" || arg === "--profile" || arg === "--harness" || arg === "--model") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(`${arg} requires a value.`);
+      }
+
+      index += 1;
+      if (arg === "--base") {
+        options.base = value;
+      } else if (arg === "--head") {
+        options.head = value.toLowerCase() === "worktree" ? undefined : value;
+      } else if (arg === "--profile") {
+        options.profile = value;
+      } else if (arg === "--harness") {
+        options.harness = value;
+      } else {
+        options.model = value;
+      }
+      continue;
+    }
+
+    throw new Error(`Unknown lisa spec check option: ${arg}`);
+  }
+
+  if (!options.help && !options.mode) {
+    throw new Error("Choose exactly one of `--changed` or `--all`.");
+  }
+
+  if (options.mode === "all" && (options.base || args.includes("--base") || args.includes("--head"))) {
+    throw new Error("`lisa spec check --all` does not accept `--base` or `--head`. Use `--changed` for diff-scoped checks.");
+  }
+
+  return options;
+}
+
+function resolveProfile(workspace: LoadedSpecWorkspace, options: CheckCommandOptions): ResolvedStageProfile {
+  const local = resolveLocalOverrides(workspace.localConfigRoot);
+  if (workspace.config) {
+    const resolved = resolveStageProfile(workspace.config, "check", {
+      profile: options.profile,
+      harness: options.harness,
+      model: options.model,
+    }, local);
+    if (!resolved) {
+      throw new Error("Unable to resolve a check stage profile from `.specs/config.yaml`.");
+    }
+    return resolved;
+  }
+
+  return {
+    stage: "check",
+    profileName: options.profile ?? "default-check",
+    harness: options.harness ?? local.harness ?? "opencode",
+    model: options.model,
+    allowEdits: false,
+    args: [],
+  };
+}
+
+function decodeOutput(bytes: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function runGitCommand(workspaceRoot: string, args: string[], allowFailure = false): CommandExecutionResult {
+  const proc = Bun.spawnSync({
+    cmd: ["git", ...args],
+    cwd: workspaceRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const result = {
+    exitCode: proc.exitCode,
+    stdout: decodeOutput(proc.stdout),
+    stderr: decodeOutput(proc.stderr),
+  };
+
+  if (result.exitCode !== 0 && !allowFailure) {
+    throw new Error(result.stderr.trim() || `git ${args.join(" ")} failed with exit code ${result.exitCode}.`);
+  }
+
+  return result;
+}
+
+function resolveGitRevision(workspaceRoot: string, revision: string): string {
+  return runGitCommand(workspaceRoot, ["rev-parse", revision]).stdout.trim();
+}
+
+function hasRepoWorktreeDrift(workspaceRoot: string, revision: string): boolean {
+  return runGitCommand(workspaceRoot, ["diff", "--quiet", revision, "--", "."], true).exitCode !== 0;
+}
+
+function hasUntrackedFiles(workspaceRoot: string): boolean {
+  return runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard"], true).stdout.trim().length > 0;
+}
+
+function defaultRunCommand(command: string, cwd: string): CommandExecutionResult {
+  const proc = Bun.spawnSync({
+    cmd: ["sh", "-lc", command],
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: process.env,
+  });
+
+  return {
+    exitCode: proc.exitCode,
+    stdout: decodeOutput(proc.stdout),
+    stderr: decodeOutput(proc.stderr),
+  };
+}
+
+function formatCapability(value: boolean): string {
+  return value ? "yes" : "no";
+}
+
+async function defaultInspectHarness(harnessId: string, cwd: string, commandOverride?: string): Promise<HarnessInspection> {
+  const adapter = getHarnessAdapterById(harnessId, cwd);
+  if (!adapter) {
+    throw new Error(`No harness adapter is registered for \`${harnessId}\`.`);
+  }
+
+  return {
+    adapter,
+    availability: commandOverride
+      ? {
+        available: true,
+        command: commandOverride,
+        reason: "Configured command override supplied by the selected stage profile.",
+      }
+      : await adapter.detect(),
+    capabilities: await adapter.capabilities(),
+  };
+}
+
+function ensureHarnessSupportsCheck(inspection: HarnessInspection, profile: ResolvedStageProfile, options: CheckCommandOptions): void {
+  if (!inspection.adapter.supportedStages.includes("check")) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` does not support the check stage.`);
+  }
+
+  if (profile.allowEdits) {
+    throw new Error(`Check stage profile \`${profile.profileName}\` must declare \`allow_edits: false\`.`);
+  }
+
+  if (options.model && !inspection.capabilities.supportsModelSelection) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` does not support model overrides.`);
+  }
+
+  if (!inspection.availability.available) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` is unavailable: ${inspection.availability.reason}`);
+  }
+}
+
+function printHarnessReport(io: CheckCommandIO, inspection: HarnessInspection, profile: ResolvedStageProfile): void {
+  io.print("Harness");
+  io.print(`- adapter: ${inspection.adapter.id} (${inspection.adapter.displayName})`);
+  io.print(`- profile: ${profile.profileName}`);
+  io.print(`- command: ${inspection.availability.command ?? "(auto-detect)"}`);
+  io.print(`- availability: ${inspection.availability.reason}`);
+  io.print(`- can edit files: ${formatCapability(inspection.capabilities.canEditFiles)}`);
+  io.print(`- supports model selection: ${formatCapability(inspection.capabilities.supportsModelSelection)}`);
+  io.print(`- supports read-only mode: ${formatCapability(inspection.capabilities.supportsReadOnlyMode)}`);
+  io.print(`- workspace isolation: yes (per-spec temporary snapshots)`);
+  io.print("");
+}
+
+function listWorkspaceFiles(workspaceRoot: string): string[] {
+  const ignoredDirectories = new Set([".git", "node_modules", ".lisa"]);
+  const files: string[] = [];
+
+  const walk = (currentPath: string): void => {
+    for (const entry of readdirSync(currentPath, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        if (ignoredDirectories.has(entry.name)) {
+          continue;
+        }
+        walk(join(currentPath, entry.name));
+        continue;
+      }
+
+      if (!entry.isFile()) {
+        continue;
+      }
+
+      files.push(normalizeRelativePath(relative(workspaceRoot, join(currentPath, entry.name))));
+    }
+  };
+
+  walk(workspaceRoot);
+  return files.sort();
+}
+
+function resolvePatternMatches(workspaceRoot: string, pattern: string, workspaceFiles: string[]): string[] {
+  const normalized = normalizeRelativePath(pattern);
+
+  if (!hasGlobMagic(normalized)) {
+    return existsSync(join(workspaceRoot, normalized)) ? [normalized] : [];
+  }
+
+  const matcher = globToRegExp(normalized);
+  return workspaceFiles.filter((file) => matcher.test(file));
+}
+
+function expandPatterns(
+  workspaceRoot: string,
+  patterns: string[],
+  workspaceFiles: string[],
+): { matches: string[]; missingPatterns: string[] } {
+  const matches = new Set<string>();
+  const missingPatterns: string[] = [];
+
+  for (const pattern of patterns) {
+    const resolved = resolvePatternMatches(workspaceRoot, pattern, workspaceFiles);
+    if (resolved.length === 0) {
+      missingPatterns.push(pattern);
+      continue;
+    }
+
+    for (const match of resolved) {
+      matches.add(match);
+    }
+  }
+
+  return {
+    matches: Array.from(matches).sort(),
+    missingPatterns,
+  };
+}
+
+function extractStringArray(frontmatter: Record<string, unknown>, key: string): string[] {
+  const value = frontmatter[key];
+  return Array.isArray(value)
+    ? value.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+}
+
+function truncateOutput(output: string): string {
+  const trimmed = output.trim();
+  if (trimmed.length <= 240) {
+    return trimmed;
+  }
+
+  return `${trimmed.slice(0, 237)}...`;
+}
+
+function formatSpecContent(document: ParsedSpecDocument): string {
+  const frontmatter = Bun.YAML.stringify(document.frontmatter).trim();
+  if (frontmatter.length === 0) {
+    return document.body.trim();
+  }
+
+  return `---\n${frontmatter}\n---\n\n${document.body}`.trim();
+}
+
+function deriveSpecIdFromPath(path: string): string {
+  const normalized = normalizeRelativePath(path);
+  const areaMatch = normalized.match(/\.specs\/(backend|frontend)\//);
+  const filename = basename(normalized).replace(/\.md$/i, "");
+  return areaMatch ? `${areaMatch[1]}.${filename}` : filename;
+}
+
+function isBaseSpecPath(path: string): boolean {
+  const normalized = normalizeRelativePath(path);
+  return (normalized.startsWith(".specs/backend/") || normalized.startsWith(".specs/frontend/"))
+    && normalized.endsWith(".md")
+    && !normalized.includes(".bench.");
+}
+
+function getWorkspaceIssuesByPath(workspaceRoot: string, issues: ValidationIssue[]): Map<string, ValidationIssue[]> {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const map = new Map<string, ValidationIssue[]>();
+
+  for (const issue of issues) {
+    const key = normalizeRelativePath(toLogicalPath(layout, issue.path));
+    map.set(key, [...(map.get(key) ?? []), issue]);
+  }
+
+  return map;
+}
+
+function getValidationIssuesForTarget(
+  workspace: LoadedSpecWorkspace,
+  issuesByPath: Map<string, ValidationIssue[]>,
+  basePath: string,
+  specId: string,
+): ValidationIssue[] {
+  const collected = [...(issuesByPath.get(basePath) ?? [])];
+
+  for (const sidecar of workspace.documents.filter((document) => document.kind !== "base" && document.frontmatter.extends === specId)) {
+    const sidecarPath = normalizeRelativePath(toLogicalPath(resolveWorkspaceLayout(workspace.workspacePath), sidecar.path));
+    collected.push(...(issuesByPath.get(sidecarPath) ?? []));
+
+    if (sidecar.extensionKind === "benchmark" && sidecar.frontmatter.required === true && sidecar.status !== "active") {
+      collected.push({
+        severity: "error",
+        path: sidecar.path,
+        message: "A required benchmark sidecar must declare `status: active`.",
+      });
+    }
+  }
+
+  return collected;
+}
+
+function buildAllTargets(workspace: LoadedSpecWorkspace): CheckTarget[] {
+  const issuesByPath = getWorkspaceIssuesByPath(workspace.workspacePath, workspace.issues);
+  const targets = new Map<string, CheckTarget>();
+
+  for (const document of workspace.documents) {
+    if (document.kind !== "base") {
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(toLogicalPath(resolveWorkspaceLayout(workspace.workspacePath), document.path));
+    const specId = document.id ?? deriveSpecIdFromPath(relativePath);
+    targets.set(relativePath, {
+      specId,
+      path: document.path,
+      document,
+      validationIssues: getValidationIssuesForTarget(workspace, issuesByPath, relativePath, specId),
+      benchmarkSidecars: getExtensionSidecarsForSpec(workspace, specId),
+    });
+  }
+
+  for (const [relativePath, issues] of issuesByPath.entries()) {
+    if (!isBaseSpecPath(relativePath) || targets.has(relativePath)) {
+      continue;
+    }
+
+    targets.set(relativePath, {
+      specId: deriveSpecIdFromPath(relativePath),
+      path: join(workspace.workspacePath, relativePath),
+      validationIssues: issues,
+      benchmarkSidecars: [],
+    });
+  }
+
+  return Array.from(targets.values()).sort((left, right) => left.specId.localeCompare(right.specId));
+}
+
+function listChangedCodePaths(workspaceRoot: string, baseRef: string, headRef?: string): string[] {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const externalSnapshotCodePaths = layout.storageMode === "external" && baseRef === EXTERNAL_SPEC_DIFF_BASE_REF
+    ? readExternalSnapshotCodePaths(workspaceRoot)
+    : {};
+  const effectiveBaseRef = layout.storageMode === "external" && baseRef === EXTERNAL_SPEC_DIFF_BASE_REF
+    ? readExternalSnapshotRepoRevision(workspaceRoot) ?? DEFAULT_SPEC_DIFF_BASE_REF
+    : baseRef;
+  const diffArgs = ["diff", "--name-only", ...(headRef ? [effectiveBaseRef, headRef] : [effectiveBaseRef]), "--", "."];
+  const diffOutput = runGitCommand(workspaceRoot, diffArgs, true).stdout;
+  const untrackedOutput = headRef ? "" : runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard"], true).stdout;
+  const changedPaths = new Set<string>();
+
+  for (const source of [diffOutput, untrackedOutput]) {
+    for (const line of source.split("\n")) {
+      const path = normalizeRelativePath(line.trim());
+      if (!path || path.startsWith(".specs/") || path.startsWith(".git/") || path.startsWith(".lisa/")) {
+        continue;
+      }
+      const currentHash = existsSync(join(workspaceRoot, path))
+        ? createHash("sha1").update(readFileSync(join(workspaceRoot, path))).digest("hex")
+        : "__missing__";
+      const snapshotEntry = externalSnapshotCodePaths[path];
+      if (snapshotEntry && (snapshotEntry.verifiedHash === currentHash || snapshotEntry.baselineHash === currentHash)) {
+        continue;
+      }
+      changedPaths.add(path);
+    }
+  }
+
+  for (const [path, snapshotEntry] of Object.entries(externalSnapshotCodePaths)) {
+    if (changedPaths.has(path)) {
+      continue;
+    }
+
+    const currentHash = existsSync(join(workspaceRoot, path))
+      ? createHash("sha1").update(readFileSync(join(workspaceRoot, path))).digest("hex")
+      : "__missing__";
+    if (currentHash !== snapshotEntry.verifiedHash && currentHash !== snapshotEntry.baselineHash) {
+      changedPaths.add(path);
+    }
+  }
+
+  return Array.from(changedPaths).sort();
+}
+
+function listChangedEnvironmentNames(workspaceRoot: string, baseRef: string, headRef?: string): string[] {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  if (layout.storageMode === "external") {
+    const previousFiles = readExternalSpecSnapshot(workspaceRoot).files;
+    const nextFiles = new Map<string, string>();
+    const effective = listEffectiveWorkspaceFiles(layout);
+    for (const path of effective.environmentPaths) {
+      nextFiles.set(toLogicalPath(layout, path), readFileSync(path, "utf8"));
+    }
+
+    const names = new Set<string>();
+    const keys = new Set<string>([
+      ...Object.keys(previousFiles).filter((key) => key.startsWith(".specs/environments/")),
+      ...Array.from(nextFiles.keys()),
+    ]);
+
+    for (const key of keys) {
+      const previous = previousFiles[key];
+      const next = nextFiles.get(key);
+      if (previous === next) {
+        continue;
+      }
+
+      const match = key.match(/^\.specs\/environments\/([^/]+)\.(yaml|yml)$/);
+      if (match?.[1]) {
+        names.add(match[1]);
+      }
+
+      for (const content of [previous, next]) {
+        if (!content) {
+          continue;
+        }
+
+        try {
+          const environment = parseSpecEnvironmentConfig(join(workspaceRoot, key), content);
+          if (environment.name) {
+            names.add(environment.name);
+          }
+        } catch {
+          // Ignore malformed environment files here; workspace validation handles the concrete issue.
+        }
+      }
+    }
+
+    return Array.from(names).sort();
+  }
+
+  const diffOutput = runGitCommand(
+    workspaceRoot,
+    ["diff", "--name-only", ...(headRef ? [baseRef, headRef] : [baseRef]), "--", ".specs/environments"],
+    true,
+  ).stdout;
+  const untrackedOutput = headRef
+    ? ""
+    : runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard", "--", ".specs/environments"], true).stdout;
+  const names = new Set<string>();
+  const readEnvironmentAtRef = (ref: string, path: string): string | undefined => {
+    const result = runGitCommand(workspaceRoot, ["show", `${ref}:${path}`], true);
+    return result.exitCode === 0 ? result.stdout : undefined;
+  };
+
+  for (const source of [diffOutput, untrackedOutput]) {
+    for (const line of source.split("\n")) {
+      const path = normalizeRelativePath(line.trim());
+      if (!path) {
+        continue;
+      }
+
+      const match = path.match(/^\.specs\/environments\/([^/]+)\.(yaml|yml)$/);
+      if (match?.[1]) {
+        names.add(match[1]);
+      }
+
+      const contents = [
+        readEnvironmentAtRef(baseRef, path),
+        headRef
+          ? readEnvironmentAtRef(headRef, path)
+          : existsSync(join(workspaceRoot, path))
+            ? readFileSync(join(workspaceRoot, path), "utf8")
+            : undefined,
+      ];
+
+      for (const content of contents) {
+        if (!content) {
+          continue;
+        }
+
+        try {
+          const environment = parseSpecEnvironmentConfig(join(workspaceRoot, path), content);
+          if (environment.name) {
+            names.add(environment.name);
+          }
+        } catch {
+          // Ignore malformed environment files here; workspace validation handles the concrete issue.
+        }
+      }
+    }
+  }
+
+  return Array.from(names).sort();
+}
+
+function collectDriftWarnings(
+  workspace: LoadedSpecWorkspace,
+  changedPaths: string[],
+  changedSpecIds: Set<string>,
+): SpecDriftWarning[] {
+  const warnings: SpecDriftWarning[] = [];
+
+  for (const document of workspace.documents) {
+    if (document.kind !== "base") {
+      continue;
+    }
+
+    const specId = document.id ?? deriveSpecIdFromPath(toLogicalPath(resolveWorkspaceLayout(workspace.workspacePath), document.path));
+    if (changedSpecIds.has(specId)) {
+      continue;
+    }
+
+    const codePaths = extractStringArray(document.frontmatter, "code_paths");
+    const overlaps = changedPaths.filter((changedPath) => codePaths.some((pattern) => globToRegExp(pattern).test(changedPath)));
+    if (overlaps.length === 0) {
+      continue;
+    }
+
+    warnings.push({
+      specId,
+      path: document.path,
+      changedPaths: overlaps,
+      message: `Changed code overlaps ${specId} without a corresponding spec edit.`,
+    });
+  }
+
+  return warnings.sort((left, right) => left.specId.localeCompare(right.specId));
+}
+
+function getChangedExtensionIssues(specId: string, diff: ReturnType<typeof collectSpecDiff>): ValidationIssue[] {
+  const issues: ValidationIssue[] = [];
+
+  for (const delta of diff.deltas) {
+    if (delta.kind === "base" || delta.extendsSpecId !== specId) {
+      const previousExtends = typeof delta.previousDocument?.frontmatter.extends === "string"
+        ? delta.previousDocument.frontmatter.extends
+        : undefined;
+      if (previousExtends !== specId) {
+        continue;
+      }
+    }
+
+    const previousDocument = delta.previousDocument;
+    const nextDocument = delta.nextDocument;
+    const wasRequired = previousDocument?.frontmatter.required === true;
+    const stillRequired = nextDocument?.frontmatter.required === true;
+    const stillActive = nextDocument?.status === "active";
+    const previousExtends = typeof previousDocument?.frontmatter.extends === "string" ? previousDocument.frontmatter.extends : undefined;
+    const nextExtends = typeof nextDocument?.frontmatter.extends === "string" ? nextDocument.frontmatter.extends : undefined;
+
+    if (wasRequired && previousExtends === specId && (delta.fileChange === "deleted" || !stillActive || !stillRequired || nextExtends !== previousExtends)) {
+      issues.push({
+        severity: "error",
+        path: delta.path,
+        message: `Required sidecar \`${delta.specId}\` no longer protects \`${specId}\` as an active required sidecar.`,
+      });
+    }
+  }
+
+  return issues;
+}
+
+function buildChangedTargets(
+  workspace: LoadedSpecWorkspace,
+  baseRef: string,
+  headRef?: string,
+): { targets: CheckTarget[]; driftWarnings: SpecDriftWarning[]; changedSpecCount: number; effectiveHeadRef: string } {
+  const diff = collectSpecDiff(workspace.workspacePath, { baseRef, headRef });
+  const issuesByPath = getWorkspaceIssuesByPath(workspace.workspacePath, workspace.issues);
+  const changedSpecIds = new Set<string>();
+  const changedBasePaths = new Set<string>();
+
+  for (const delta of diff.deltas) {
+    if (delta.kind === "base") {
+      changedSpecIds.add(delta.specId);
+      changedBasePaths.add(normalizeRelativePath(toLogicalPath(resolveWorkspaceLayout(workspace.workspacePath), delta.path)));
+    } else {
+      const previousExtends = typeof delta.previousDocument?.frontmatter.extends === "string"
+        ? delta.previousDocument.frontmatter.extends
+        : undefined;
+      const nextExtends = typeof delta.nextDocument?.frontmatter.extends === "string"
+        ? delta.nextDocument.frontmatter.extends
+        : undefined;
+      if (previousExtends) {
+        changedSpecIds.add(previousExtends);
+      }
+      if (nextExtends) {
+        changedSpecIds.add(nextExtends);
+      }
+    }
+  }
+
+  const driftWarnings = collectDriftWarnings(
+    workspace,
+    listChangedCodePaths(workspace.workspacePath, baseRef, headRef),
+    changedSpecIds,
+  );
+  const changedEnvironmentNames = new Set(listChangedEnvironmentNames(workspace.workspacePath, baseRef, headRef));
+  const targets = new Map<string, CheckTarget>();
+
+  for (const document of workspace.documents) {
+    if (document.kind !== "base") {
+      continue;
+    }
+
+    const relativePath = normalizeRelativePath(toLogicalPath(resolveWorkspaceLayout(workspace.workspacePath), document.path));
+    const specId = document.id ?? deriveSpecIdFromPath(relativePath);
+    const sidecars = getExtensionSidecarsForSpec(workspace, specId);
+    const changedExtensionIssues = getChangedExtensionIssues(specId, diff);
+    const environmentImpacted = sidecars.some((sidecar) => {
+      const environmentName = typeof sidecar.frontmatter.environment === "string" ? sidecar.frontmatter.environment : undefined;
+      return environmentName !== undefined && changedEnvironmentNames.has(environmentName);
+    });
+    if (!changedSpecIds.has(specId) && !driftWarnings.some((warning) => warning.specId === specId) && !environmentImpacted) {
+      continue;
+    }
+
+    targets.set(relativePath, {
+      specId,
+      path: document.path,
+      document,
+      validationIssues: [...getValidationIssuesForTarget(workspace, issuesByPath, relativePath, specId), ...changedExtensionIssues],
+      driftWarning: driftWarnings.find((warning) => warning.specId === specId),
+      benchmarkSidecars: sidecars,
+    });
+  }
+
+  for (const relativePath of changedBasePaths) {
+    if (targets.has(relativePath)) {
+      continue;
+    }
+
+    targets.set(relativePath, {
+      specId: deriveSpecIdFromPath(relativePath),
+      path: join(workspace.workspacePath, relativePath),
+      validationIssues: issuesByPath.get(relativePath) ?? [],
+      benchmarkSidecars: [],
+    });
+  }
+
+  return {
+    targets: Array.from(targets.values()).sort((left, right) => left.specId.localeCompare(right.specId)),
+    driftWarnings,
+    changedSpecCount: diff.deltas.length,
+    effectiveHeadRef: diff.headRef,
+  };
+}
+
+async function runDeterministicChecks(
+  target: CheckTarget,
+  workspace: LoadedSpecWorkspace,
+  workspaceRoot: string,
+  workspaceFiles: string[],
+  testCommandResults: Map<string, CommandExecutionResult>,
+  runCommand: (command: string, cwd: string) => CommandExecutionResult,
+): Promise<DeterministicCheckResult> {
+  const codePaths = target.document ? extractStringArray(target.document.frontmatter, "code_paths") : [];
+  const testPaths = target.document ? extractStringArray(target.document.frontmatter, "test_paths") : [];
+  const testCommands = target.document ? extractStringArray(target.document.frontmatter, "test_commands") : [];
+  const evidence: SpecCheckEvidence[] = [];
+  const issues: string[] = [];
+
+  for (const issue of target.validationIssues) {
+    if (issue.severity === "warning") {
+      evidence.push({ type: "config", detail: `Validation warning: ${issue.message}` });
+    } else {
+      issues.push(issue.message);
+    }
+  }
+
+  if (!target.document) {
+    issues.push("Spec file could not be loaded for verification.");
+    return {
+      specId: target.specId,
+      path: target.path,
+      codePaths,
+      testPaths,
+      testCommands,
+      matchedCodeFiles: [],
+      matchedTestFiles: [],
+      evidence,
+      issues,
+      status: "FAIL",
+      summary: "Spec could not be parsed or loaded, so conformance could not be checked.",
+    };
+  }
+
+  if (target.document.status !== "active") {
+    evidence.push({ type: "config", detail: `Skipped ${target.document.status ?? "unknown"} spec.` });
+    return {
+      specId: target.specId,
+      path: target.path,
+      codePaths,
+      testPaths,
+      testCommands,
+      matchedCodeFiles: [],
+      matchedTestFiles: [],
+      evidence,
+      issues,
+      status: "SKIPPED",
+      summary: `Skipped non-active spec with status \`${target.document.status ?? "unknown"}\`.`,
+    };
+  }
+
+  const codeMatches = expandPatterns(workspaceRoot, codePaths, workspaceFiles);
+  const testMatches = expandPatterns(workspaceRoot, testPaths, workspaceFiles);
+
+  if (codeMatches.matches.length > 0) {
+    evidence.push({ type: "config", detail: `Matched ${codeMatches.matches.length} code path entries.` });
+  }
+  if (testMatches.matches.length > 0) {
+    evidence.push({ type: "test", detail: `Matched ${testMatches.matches.length} test path entries.` });
+  }
+
+  if (codeMatches.missingPatterns.length > 0) {
+    issues.push(`Missing declared code paths: ${codeMatches.missingPatterns.join(", ")}`);
+  }
+
+  if (testPaths.length > 0 && testMatches.missingPatterns.length > 0) {
+    issues.push(`Missing declared test paths: ${testMatches.missingPatterns.join(", ")}`);
+  }
+
+  if (target.driftWarning) {
+    evidence.push({ type: "config", detail: target.driftWarning.message });
+  }
+
+  for (const command of testCommands) {
+    const result = testCommandResults.get(command);
+    if (!result) {
+      issues.push(`Mapped test command was not executed: ${command}`);
+      continue;
+    }
+
+    if (result.exitCode === 0) {
+      evidence.push({ type: "test", detail: `Passed: ${command}` });
+      continue;
+    }
+
+    const output = truncateOutput(result.stderr || result.stdout);
+    issues.push(`Failed test command: ${command}${output ? ` (${output})` : ""}`);
+  }
+
+  if (testCommands.length === 0 && testMatches.matches.length === 0) {
+    issues.push("No mapped tests were found for this active spec.");
+  }
+
+  if (issues.length > 0) {
+    return {
+      specId: target.specId,
+      path: target.path,
+      codePaths,
+      testPaths,
+      testCommands,
+      matchedCodeFiles: codeMatches.matches,
+      matchedTestFiles: testMatches.matches,
+      evidence,
+      issues,
+      status: "FAIL",
+      summary: "Deterministic checks failed.",
+    };
+  }
+
+  if (target.document) {
+    const extensionResults = await verifySpecExtensions(
+      {
+        specId: target.specId,
+        path: target.path,
+        document: target.document,
+        sidecars: target.benchmarkSidecars,
+      },
+      {
+        workspaceRoot,
+        workspace,
+        runCommand,
+      },
+    );
+
+    for (const extensionResult of extensionResults) {
+      evidence.push(...extensionResult.evidence);
+      issues.push(...extensionResult.issues);
+
+      if (extensionResult.status === "FAIL" || extensionResult.status === "UNSURE") {
+        return {
+          specId: target.specId,
+          path: target.path,
+          codePaths,
+          testPaths,
+          testCommands,
+          matchedCodeFiles: codeMatches.matches,
+          matchedTestFiles: testMatches.matches,
+          evidence,
+          issues,
+          status: extensionResult.status,
+          summary: extensionResult.summary ?? "Extension verification did not produce a conclusive result.",
+        };
+      }
+    }
+  }
+
+  return {
+    specId: target.specId,
+    path: target.path,
+    codePaths,
+    testPaths,
+    testCommands,
+    matchedCodeFiles: codeMatches.matches,
+    matchedTestFiles: testMatches.matches,
+    evidence,
+    issues,
+    summary: "Deterministic checks passed; awaiting verifier audit.",
+  };
+}
+
+function extractJsonPayload(text: string): string | undefined {
+  const markerMatch = text.match(/LISA_CHECK_JSON_START\s*([\s\S]*?)\s*LISA_CHECK_JSON_END/);
+  if (markerMatch?.[1]) {
+    return markerMatch[1].trim();
+  }
+
+  const fencedMatch = text.match(/```json\s*([\s\S]*?)```/i);
+  if (fencedMatch?.[1]) {
+    return fencedMatch[1].trim();
+  }
+
+  const firstBrace = text.indexOf("{");
+  const lastBrace = text.lastIndexOf("}");
+  if (firstBrace >= 0 && lastBrace > firstBrace) {
+    return text.slice(firstBrace, lastBrace + 1).trim();
+  }
+
+  return undefined;
+}
+
+function parseVerifierAudit(result: HarnessResult): ParsedVerifierAudit {
+  const raw = typeof result.structuredOutput === "object" && result.structuredOutput !== null
+    ? result.structuredOutput
+    : result.finalText
+      ? JSON.parse(extractJsonPayload(result.finalText) ?? "null")
+      : null;
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Verifier did not return a valid JSON audit payload.");
+  }
+
+  const statusValue = typeof (raw as { status?: unknown }).status === "string"
+    ? (raw as { status: string }).status.toUpperCase()
+    : undefined;
+  if (statusValue !== "PASS" && statusValue !== "FAIL" && statusValue !== "UNSURE") {
+    throw new Error("Verifier audit payload must declare status as PASS, FAIL, or UNSURE.");
+  }
+
+  const evidence = Array.isArray((raw as { evidence?: unknown[] }).evidence)
+    ? (raw as { evidence: unknown[] }).evidence
+      .filter(
+        (entry): entry is { type: SpecCheckEvidence["type"]; detail: string } =>
+          typeof entry === "object"
+          && entry !== null
+          && typeof (entry as { type?: unknown }).type === "string"
+          && SPEC_CHECK_EVIDENCE_TYPES.has((entry as { type: SpecCheckEvidence["type"] }).type)
+          && typeof (entry as { detail?: unknown }).detail === "string",
+      )
+      .map((entry) => ({ type: entry.type, detail: entry.detail.trim() }))
+      .filter((entry) => entry.detail.length > 0)
+    : [];
+  const issues = Array.isArray((raw as { issues?: unknown[] }).issues)
+    ? (raw as { issues: unknown[] }).issues.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+
+  return {
+    status: statusValue,
+    summary: typeof (raw as { summary?: unknown }).summary === "string"
+      ? (raw as { summary: string }).summary.trim()
+      : "Verifier completed without a summary.",
+    evidence,
+    issues,
+  };
+}
+
+function ensureParentDirectory(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function copyPathIntoSnapshot(sourcePath: string, snapshotRoot: string, snapshotRelativePath: string): void {
+  if (!existsSync(sourcePath)) {
+    return;
+  }
+
+  const destinationPath = join(snapshotRoot, snapshotRelativePath);
+  ensureParentDirectory(destinationPath);
+  const stats = statSync(sourcePath);
+  if (stats.isDirectory()) {
+    cpSync(sourcePath, destinationPath, { recursive: true });
+    return;
+  }
+
+  cpSync(sourcePath, destinationPath);
+}
+
+function copyIntoSnapshot(workspaceRoot: string, snapshotRoot: string, relativePath: string): void {
+  copyPathIntoSnapshot(join(workspaceRoot, relativePath), snapshotRoot, relativePath);
+}
+
+function listCommonSnapshotFiles(workspaceRoot: string): string[] {
+  const candidates = ["package.json", "README.md", "bunfig.toml", "bun.lock", "bun.lockb", ".specs/config.yaml"];
+  const commonFiles = candidates.filter((candidate) => existsSync(join(workspaceRoot, candidate)));
+
+  for (const entry of readdirSync(workspaceRoot)) {
+    if (/^tsconfig.*\.json$/i.test(entry)) {
+      commonFiles.push(entry);
+    }
+  }
+
+  return Array.from(new Set(commonFiles.map((path) => normalizeRelativePath(path)))).sort();
+}
+
+function buildVerifierSnapshot(
+  workspaceRoot: string,
+  deterministic: DeterministicCheckResult,
+  commonFiles: string[],
+  extraContextPaths: string[] = [],
+): { snapshotRoot: string; contextFiles: string[] } {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const snapshotRoot = mkdtempSync(join(tmpdir(), "lisa-check-"));
+  const contextFiles = new Set<string>();
+  const paths = new Set<string>([
+    ...commonFiles,
+    ...deterministic.matchedCodeFiles,
+    ...deterministic.matchedTestFiles,
+    ...extraContextPaths.map((p) => normalizeRelativePath(p)),
+  ]);
+
+  const specLogicalPath = normalizeRelativePath(toLogicalPath(layout, deterministic.path));
+  copyPathIntoSnapshot(deterministic.path, snapshotRoot, specLogicalPath);
+  contextFiles.add(join(snapshotRoot, specLogicalPath));
+
+  if (layout.storageMode === "external" && existsSync(layout.configPath)) {
+    copyPathIntoSnapshot(layout.configPath, snapshotRoot, ".specs/config.yaml");
+    contextFiles.add(join(snapshotRoot, ".specs/config.yaml"));
+  }
+  const projectSpecPath = resolveEffectiveProjectSpecPath(layout);
+  if (projectSpecPath && existsSync(projectSpecPath)) {
+    copyPathIntoSnapshot(projectSpecPath, snapshotRoot, ".specs/project.md");
+    contextFiles.add(join(snapshotRoot, ".specs/project.md"));
+  }
+
+  for (const path of paths) {
+    copyIntoSnapshot(workspaceRoot, snapshotRoot, path);
+    const snapshotPath = join(snapshotRoot, path);
+    if (existsSync(snapshotPath)) {
+      contextFiles.add(snapshotPath);
+    }
+  }
+
+  return {
+    snapshotRoot,
+    contextFiles: Array.from(contextFiles).sort(),
+  };
+}
+
+async function mapWithConcurrency<T, U>(
+  items: T[],
+  concurrency: number,
+  mapper: (item: T) => Promise<U>,
+): Promise<U[]> {
+  const results = new Array<U>(items.length);
+  let cursor = 0;
+
+  const worker = async (): Promise<void> => {
+    while (cursor < items.length) {
+      const index = cursor;
+      cursor += 1;
+      results[index] = await mapper(items[index] as T);
+    }
+  };
+
+  const workers = Array.from({ length: Math.max(1, Math.min(concurrency, items.length)) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}
+
+async function runVerifierAudit(
+  target: CheckTarget,
+  deterministic: DeterministicCheckResult,
+  workspaceRoot: string,
+  profile: ResolvedStageProfile,
+  runHarness: (harnessId: string, request: HarnessRequest, cwd: string) => Promise<HarnessResult>,
+  commonSnapshotFiles: string[],
+): Promise<ParsedVerifierAudit> {
+  const specContextPaths = Array.isArray(target.document?.frontmatter.context_paths)
+    ? target.document.frontmatter.context_paths.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const { snapshotRoot, contextFiles } = buildVerifierSnapshot(workspaceRoot, deterministic, commonSnapshotFiles, specContextPaths);
+
+  try {
+    const specContent = existsSync(target.path)
+      ? readFileSync(target.path, "utf8")
+      : target.document
+        ? formatSpecContent(target.document)
+        : "";
+    const prompt = renderCheckPrompt({
+      workspacePath: workspaceRoot,
+      spec: target.document as ParsedSpecDocument,
+      specContent,
+      codePaths: deterministic.codePaths,
+      testPaths: deterministic.testPaths,
+      testCommands: deterministic.testCommands,
+      matchedCodeFiles: deterministic.matchedCodeFiles,
+      matchedTestFiles: deterministic.matchedTestFiles,
+      deterministicEvidence: deterministic.evidence,
+      deterministicIssues: deterministic.issues,
+      driftWarning: target.driftWarning?.message,
+    });
+
+    const result = await runHarness(
+      profile.harness,
+      {
+        stage: "check",
+        prompt,
+        cwd: snapshotRoot,
+        allowEdits: false,
+        contextFiles,
+        env: profile.command ? { LISA_HARNESS_COMMAND: resolveHarnessCommandOverride(profile.command, dirname(resolveWorkspaceLayout(workspaceRoot).configPath)) } : undefined,
+        model: profile.model,
+        profile: profile.profileName,
+        extraArgs: profile.args,
+        limits: { maxTurns: 4 },
+      },
+      snapshotRoot,
+    );
+
+    if (result.status === "blocked") {
+      return {
+        status: "UNSURE",
+        summary: "Verifier harness reported a blocked run.",
+        evidence: [],
+        issues: [result.abortReason?.trim() || result.finalText?.trim() || "Verifier harness blocked without a diagnostic."],
+      };
+    }
+
+    if (result.status !== "success") {
+      return {
+        status: "UNSURE",
+        summary: "Verifier harness did not complete successfully.",
+        evidence: [],
+        issues: [result.finalText?.trim() || "Verifier harness failed without a diagnostic."],
+      };
+    }
+
+    try {
+      return parseVerifierAudit(result);
+    } catch (error) {
+      return {
+        status: "UNSURE",
+        summary: "Verifier output could not be parsed.",
+        evidence: [],
+        issues: [error instanceof Error ? error.message : String(error)],
+      };
+    }
+  } finally {
+    rmSync(snapshotRoot, { recursive: true, force: true });
+  }
+}
+
+function mergeVerificationResult(
+  deterministic: DeterministicCheckResult,
+  audit?: ParsedVerifierAudit,
+): SpecCheckResult {
+  if (deterministic.status === "SKIPPED") {
+    return {
+      specId: deterministic.specId,
+      path: deterministic.path,
+      status: "SKIPPED",
+      summary: deterministic.summary,
+      evidence: deterministic.evidence,
+      issues: deterministic.issues,
+    };
+  }
+
+  if (deterministic.status === "FAIL") {
+    return {
+      specId: deterministic.specId,
+      path: deterministic.path,
+      status: "FAIL",
+      summary: deterministic.summary,
+      evidence: deterministic.evidence,
+      issues: deterministic.issues,
+    };
+  }
+
+  if (deterministic.status === "UNSURE") {
+    return {
+      specId: deterministic.specId,
+      path: deterministic.path,
+      status: "UNSURE",
+      summary: deterministic.summary,
+      evidence: deterministic.evidence,
+      issues: deterministic.issues,
+    };
+  }
+
+  if (!audit) {
+    return {
+      specId: deterministic.specId,
+      path: deterministic.path,
+      status: "UNSURE",
+      summary: "Deterministic checks passed, but no verifier audit result was produced.",
+      evidence: deterministic.evidence,
+      issues: [...deterministic.issues, "Missing verifier audit result."],
+    };
+  }
+
+  return {
+    specId: deterministic.specId,
+    path: deterministic.path,
+    status: audit.status,
+    summary: audit.summary,
+    evidence: [...deterministic.evidence, ...audit.evidence],
+    issues: [...deterministic.issues, ...audit.issues],
+  };
+}
+
+function summarizeResults(results: SpecCheckResult[]): SpecCheckReport["summary"] {
+  return results.reduce(
+    (summary, result) => {
+      if (result.status === "PASS") {
+        summary.pass += 1;
+      } else if (result.status === "FAIL") {
+        summary.fail += 1;
+      } else if (result.status === "UNSURE") {
+        summary.unsure += 1;
+      } else {
+        summary.skipped += 1;
+      }
+      return summary;
+    },
+    { pass: 0, fail: 0, unsure: 0, skipped: 0 },
+  );
+}
+
+function renderMarkdownReport(report: SpecCheckReport): string {
+  const lines = [
+    "# Lisa Spec Report",
+    "",
+    `- Generated: ${report.generatedAt}`,
+    `- Mode: ${report.mode}`,
+    report.baseRef ? `- Range: ${report.baseRef} -> ${report.headRef ?? "WORKTREE"}` : undefined,
+    `- Profile: ${report.profile}`,
+    `- Harness: ${report.harness}`,
+    "",
+    "## Summary",
+    `- PASS: ${report.summary.pass}`,
+    `- FAIL: ${report.summary.fail}`,
+    `- UNSURE: ${report.summary.unsure}`,
+    `- SKIPPED: ${report.summary.skipped}`,
+    "",
+  ].filter((line): line is string => line !== undefined);
+
+  if (report.driftWarnings.length > 0) {
+    lines.push("## Drift Warnings", "");
+    for (const warning of report.driftWarnings) {
+      lines.push(`- ${warning.specId}: ${warning.message}`);
+      lines.push(`  Changed paths: ${warning.changedPaths.join(", ")}`);
+    }
+    lines.push("");
+  }
+
+  lines.push("## Results", "");
+  for (const result of report.results) {
+    lines.push(`### ${result.specId} - ${result.status}`);
+    lines.push("");
+      lines.push(`- Path: ${normalizeRelativePath(toLogicalPath(resolveWorkspaceLayout(report.workspacePath), result.path))}`);
+    lines.push(`- Summary: ${result.summary}`);
+    if (result.evidence.length > 0) {
+      for (const entry of result.evidence) {
+        lines.push(`- Evidence (${entry.type}): ${entry.detail}`);
+      }
+    }
+    if (result.issues.length > 0) {
+      for (const issue of result.issues) {
+        lines.push(`- Issue: ${issue}`);
+      }
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd() + "\n";
+}
+
+function writeArtifacts(workspaceRoot: string, report: SpecCheckReport): { jsonPath: string; markdownPath: string; checkDir: string } {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const runtimeDir = layout.runtimeRoot;
+  const checkDir = join(runtimeDir, "check");
+  if (layout.storageMode === "external") {
+    assertSafeLisaStorageWritePath(runtimeDir, checkDir, "Lisa check artifacts");
+  }
+  mkdirSync(checkDir, { recursive: true });
+
+  const jsonPath = join(runtimeDir, "spec-report.json");
+  const markdownPath = join(runtimeDir, "spec-report.md");
+  if (layout.storageMode === "external") {
+    assertSafeLisaStorageWritePath(runtimeDir, jsonPath, "Lisa check artifacts");
+    assertSafeLisaStorageWritePath(runtimeDir, markdownPath, "Lisa check artifacts");
+  }
+
+  writeFileSync(jsonPath, JSON.stringify(report, null, 2) + "\n");
+  writeFileSync(markdownPath, renderMarkdownReport(report));
+
+  for (const result of report.results) {
+    const fileName = `${result.specId.replace(/[^a-zA-Z0-9._-]+/g, "_")}.json`;
+    writeFileSync(join(checkDir, fileName), JSON.stringify(result, null, 2) + "\n");
+  }
+
+  return { jsonPath, markdownPath, checkDir };
+}
+
+function printResults(io: CheckCommandIO, results: SpecCheckResult[]): void {
+  io.print("Results");
+  if (results.length === 0) {
+    io.print("- no specs selected");
+    io.print("");
+    return;
+  }
+
+  for (const result of results) {
+    io.print(`- ${result.specId}: ${result.status} - ${result.summary}`);
+  }
+  io.print("");
+}
+
+export async function runSpecCheckCommand(
+  args: string[],
+  cwd = process.cwd(),
+  deps: CheckCommandDeps = {},
+): Promise<number> {
+  const io = deps.io ?? createConsoleIO();
+
+  try {
+    const options = parseCheckArgs(args);
+    if (options.help) {
+      printCheckHelp(io);
+      return 0;
+    }
+
+    const layout = resolveWorkspaceLayout(cwd);
+    const workspaceRoot = layout.workspacePath;
+    if (layout.storageMode === "external" && (args.includes("--base") || args.includes("--head"))) {
+      io.error("External Lisa workspaces do not support `--base` or `--head` for spec history yet.");
+      return 1;
+    }
+    if (options.head) {
+      const requestedHead = resolveGitRevision(workspaceRoot, options.head);
+      const currentHead = resolveGitRevision(workspaceRoot, "HEAD");
+      if (requestedHead !== currentHead) {
+        io.error("`spec check --head <rev>` can only target the currently checked out commit. Check out that revision first or omit `--head`.");
+        return 1;
+      }
+
+      if (hasRepoWorktreeDrift(workspaceRoot, options.head) || hasUntrackedFiles(workspaceRoot)) {
+        io.error("`spec check --head <rev>` requires the full workspace to match that revision. Commit or stash local changes first.");
+        return 1;
+      }
+    }
+
+    const workspace = options.head ? loadSpecWorkspaceAtRef(options.head, workspaceRoot) : loadSpecWorkspace(workspaceRoot);
+    const profile = resolveProfile(workspace, options);
+    const inspectHarness = deps.inspectHarness ?? defaultInspectHarness;
+    const inspection = await inspectHarness(profile.harness, workspaceRoot, profile.command);
+    ensureHarnessSupportsCheck(inspection, profile, options);
+    printHarnessReport(io, inspection, profile);
+
+    if (workspace.issues.length > 0) {
+      io.print("Workspace Validation");
+      for (const issue of workspace.issues) {
+        io.print(`- ${issue.severity}: ${normalizeRelativePath(toLogicalPath(layout, issue.path))} - ${issue.message}`);
+      }
+      io.print("");
+    }
+
+    let targets: CheckTarget[];
+    let driftWarnings: SpecDriftWarning[] = [];
+    let baseRef: string | undefined;
+    let headRef: string | undefined;
+
+    if (options.mode === "changed") {
+      baseRef = options.base ?? (layout.storageMode === "external" ? EXTERNAL_SPEC_DIFF_BASE_REF : DEFAULT_SPEC_DIFF_BASE_REF);
+      const changedSelection = buildChangedTargets(workspace, baseRef, options.head);
+      targets = changedSelection.targets;
+      driftWarnings = changedSelection.driftWarnings;
+      headRef = changedSelection.effectiveHeadRef;
+
+      io.print("Selection");
+      io.print(`- mode: changed`);
+      io.print(`- base: ${baseRef}`);
+      io.print(`- head: ${headRef}`);
+      io.print(`- selected specs: ${targets.length}`);
+      io.print(`- changed spec deltas: ${changedSelection.changedSpecCount}`);
+      io.print("");
+    } else {
+      targets = buildAllTargets(workspace);
+      io.print("Selection");
+      io.print(`- mode: all`);
+      io.print(`- selected specs: ${targets.length}`);
+      io.print("");
+    }
+
+    if (driftWarnings.length > 0) {
+      io.print("Drift Warnings");
+      for (const warning of driftWarnings) {
+        io.print(`- ${warning.specId}: ${warning.changedPaths.join(", ")}`);
+      }
+      io.print("");
+    }
+
+    const workspaceFiles = listWorkspaceFiles(workspaceRoot);
+    const activeTargets = targets.filter((target) => target.document?.status === "active");
+    const testCommands = Array.from(
+      new Set(activeTargets.flatMap((target) => extractStringArray(target.document?.frontmatter ?? {}, "test_commands"))),
+    ).sort();
+    const runCommand = deps.runCommand ?? defaultRunCommand;
+    const testCommandResults = new Map<string, CommandExecutionResult>(
+      testCommands.map((command) => [command, runCommand(command, workspaceRoot)]),
+    );
+
+    if (testCommands.length > 0) {
+      io.print("Deterministic Tests");
+      for (const command of testCommandResults.keys()) {
+        const result = testCommandResults.get(command) as CommandExecutionResult;
+        io.print(`- ${command} (${result.exitCode === 0 ? "pass" : "fail"})`);
+      }
+      io.print("");
+    }
+
+    const deterministicResults = await Promise.all(
+      targets.map((target) => runDeterministicChecks(target, workspace, workspaceRoot, workspaceFiles, testCommandResults, runCommand)),
+    );
+    const commonSnapshotFiles = listCommonSnapshotFiles(workspaceRoot);
+    const runHarness = deps.runHarness ?? runHarnessStage;
+    const auditable = deterministicResults.filter((result) => result.status === undefined);
+    const targetBySpecId = new Map(targets.map((target) => [target.specId, target]));
+    const audits = new Map<string, ParsedVerifierAudit>();
+
+    for (const audit of await mapWithConcurrency(auditable, 4, async (deterministic) => {
+      const target = targetBySpecId.get(deterministic.specId) as CheckTarget;
+      return {
+        specId: deterministic.specId,
+        audit: await runVerifierAudit(target, deterministic, workspaceRoot, profile, runHarness, commonSnapshotFiles),
+      };
+    })) {
+      audits.set(audit.specId, audit.audit);
+    }
+
+    const results = deterministicResults.map((deterministic) => mergeVerificationResult(deterministic, audits.get(deterministic.specId)));
+    const report: SpecCheckReport = {
+      workspacePath: workspaceRoot,
+      mode: options.mode as SpecCheckMode,
+      baseRef,
+      headRef,
+      generatedAt: new Date().toISOString(),
+      profile: profile.profileName,
+      harness: profile.harness,
+      results,
+      driftWarnings,
+      summary: summarizeResults(results),
+    };
+    const artifacts = writeArtifacts(workspaceRoot, report);
+    if (
+      layout.storageMode === "external"
+      && report.summary.fail === 0
+      && report.summary.unsure === 0
+      && results.some((result) => result.status === "PASS")
+      && (
+        options.mode === "all"
+        || (options.mode === "changed" && driftWarnings.length === 0)
+      )
+    ) {
+      writeExternalSpecSnapshot(workspaceRoot);
+    }
+
+    printResults(io, results);
+    io.print("Artifacts");
+    io.print(`- json: ${layout.storageMode === "external" ? artifacts.jsonPath : normalizeRelativePath(relative(workspaceRoot, artifacts.jsonPath))}`);
+    io.print(`- markdown: ${layout.storageMode === "external" ? artifacts.markdownPath : normalizeRelativePath(relative(workspaceRoot, artifacts.markdownPath))}`);
+    io.print(`- per-spec: ${layout.storageMode === "external" ? artifacts.checkDir : normalizeRelativePath(relative(workspaceRoot, artifacts.checkDir))}`);
+
+    return report.summary.fail > 0 || report.summary.unsure > 0 ? 1 : 0;
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}