@wkronmiller/lisa 0.1.0

package/src/spec/workflows/implement.ts

@@ -0,0 +1,797 @@
+import { createHash } from "crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "fs";
+import { 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 { updateAgentGuidanceSafely } from "../agent-guidance";
+import { DEFAULT_SPEC_DIFF_BASE_REF, collectSpecDiff, getSpecDiffRelativePath } from "../diff";
+import { resolveStageProfile } from "../config";
+import { resolveLocalOverrides } from "../local-config";
+import { loadSpecWorkspace, loadSpecWorkspaceAtRef } from "../loader";
+import { planSpecImplementation } from "../planner";
+import { renderImplementPrompt } from "../prompt-renderer";
+import type { LoadedSpecWorkspace, ResolvedStageProfile, SpecDiffReport, SpecImplementationPlan, ValidationIssue } from "../types";
+import { resolveEffectiveProjectSpecPath, resolveWorkspaceLayout } from "../workspace";
+import {
+  escapeRegExp,
+  globToRegExp,
+  hasGlobMagic,
+  isSafeContextPattern,
+  normalizeRelativePath,
+} from "../path-utils";
+
+const MAX_CONTEXT_CODE_FILES_PER_SPEC = 8;
+const MAX_CONTEXT_TEST_FILES_PER_SPEC = 8;
+const MAX_CONTEXT_MATCHES_PER_PATTERN = 4;
+
+interface ImplementCommandOptions {
+  base?: string;
+  head?: string;
+  profile?: string;
+  harness?: string;
+  model?: string;
+  allowSpecDeletions: boolean;
+  help: boolean;
+}
+
+interface CommandExecutionResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+}
+
+interface DirtySnapshot {
+  files: Map<string, string>;
+}
+
+interface WriterLock {
+  path: string;
+  release(): void;
+}
+
+export interface ImplementCommandIO {
+  print(message: string): void;
+  error(message: string): void;
+}
+
+export interface ImplementCommandDeps {
+  io?: ImplementCommandIO;
+  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(): ImplementCommandIO {
+  return {
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+  };
+}
+
+function printImplementHelp(io: ImplementCommandIO): void {
+  io.print(`Lisa spec implement
+
+Usage:
+  lisa spec implement [options]
+
+Options:
+  --base <rev>                Diff base revision (default: HEAD)
+  --head <rev>                Diff head revision (default: worktree)
+  --profile <name>            Override the implement stage profile
+  --harness <id>              Override the configured harness adapter
+  --model <name>              Override the configured model
+  --allow-spec-deletions      Allow plans that include deleted specs
+  --help, -h                  Show this help
+`);
+}
+
+function parseImplementArgs(args: string[]): ImplementCommandOptions {
+  const options: ImplementCommandOptions = {
+    allowSpecDeletions: false,
+    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 === "--allow-spec-deletions") {
+      options.allowSpecDeletions = true;
+      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 implement option: ${arg}`);
+  }
+
+  return options;
+}
+
+function resolveProfile(
+  workspace: LoadedSpecWorkspace,
+  options: ImplementCommandOptions,
+): ResolvedStageProfile {
+  const local = resolveLocalOverrides(workspace.localConfigRoot);
+  if (workspace.config) {
+    const resolved = resolveStageProfile(workspace.config, "implement", {
+      profile: options.profile,
+      harness: options.harness,
+      model: options.model,
+    }, local);
+    if (!resolved) {
+      throw new Error("Unable to resolve an implement stage profile from `.specs/config.yaml`.");
+    }
+    return resolved;
+  }
+
+  return {
+    stage: "implement",
+    profileName: options.profile ?? "default-implement",
+    harness: options.harness ?? local.harness ?? "opencode",
+    model: options.model,
+    allowEdits: true,
+    args: [],
+  };
+}
+
+function decodeOutput(bytes: Uint8Array<ArrayBufferLike>): string {
+  return new TextDecoder().decode(bytes);
+}
+
+function runGitCommand(workspaceRoot: string, args: string[]): CommandExecutionResult {
+  const proc = Bun.spawnSync({
+    cmd: ["git", ...args],
+    cwd: workspaceRoot,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  return {
+    exitCode: proc.exitCode,
+    stdout: decodeOutput(proc.stdout),
+    stderr: decodeOutput(proc.stderr),
+  };
+}
+
+function resolveGitRevision(workspaceRoot: string, revision: string): string {
+  const result = runGitCommand(workspaceRoot, ["rev-parse", revision]);
+  if (result.exitCode !== 0) {
+    throw new Error(result.stderr.trim() || `Could not resolve git revision \`${revision}\`.`);
+  }
+
+  return result.stdout.trim();
+}
+
+function hasSpecWorktreeDrift(workspaceRoot: string, revision: string): boolean {
+  const result = runGitCommand(workspaceRoot, [
+    "diff",
+    "--quiet",
+    revision,
+    "--",
+    ".specs/backend",
+    ".specs/frontend",
+    ".specs/config.yaml",
+    ".specs/environments",
+  ]);
+  return result.exitCode !== 0;
+}
+
+function hasUntrackedSpecFiles(workspaceRoot: string): boolean {
+  const result = runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard", "--", ".specs"]);
+  return result.stdout.trim().length > 0;
+}
+
+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[] {
+  if (!isSafeContextPattern(pattern)) {
+    return [];
+  }
+
+  const normalized = normalizeRelativePath(pattern);
+
+  if (!hasGlobMagic(normalized)) {
+    const absolutePath = join(workspaceRoot, normalized);
+    if (!existsSync(absolutePath)) {
+      return [];
+    }
+
+    const stat = lstatSync(absolutePath);
+    if (stat.isSymbolicLink()) {
+      return [];
+    }
+
+    if (stat.isDirectory()) {
+      return workspaceFiles.filter((file) => file.startsWith(`${normalized}/`));
+    }
+
+    return [normalized];
+  }
+
+  const matcher = globToRegExp(normalized);
+  return workspaceFiles.filter((file) => matcher.test(file));
+}
+
+function rankContextMatches(matches: string[]): string[] {
+  return [...matches].sort((left, right) => {
+    const leftDepth = left.split("/").length;
+    const rightDepth = right.split("/").length;
+    if (leftDepth !== rightDepth) {
+      return leftDepth - rightDepth;
+    }
+
+    if (left.length !== right.length) {
+      return left.length - right.length;
+    }
+
+    return left.localeCompare(right);
+  });
+}
+
+function collectTargetContextMatches(
+  workspaceRoot: string,
+  patterns: string[],
+  workspaceFiles: string[],
+  limit: number,
+): string[] {
+  const matches = new Set<string>();
+
+  for (const pattern of patterns) {
+    const resolved = resolvePatternMatches(workspaceRoot, pattern, workspaceFiles);
+    for (const match of rankContextMatches(resolved).slice(0, MAX_CONTEXT_MATCHES_PER_PATTERN)) {
+      matches.add(match);
+      if (matches.size >= limit) {
+        return Array.from(matches).sort();
+      }
+    }
+  }
+
+  return Array.from(matches).sort();
+}
+
+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 formatIssuesForConsole(issues: ValidationIssue[], workspaceRoot: string): string[] {
+  return issues.map((issue) => `${issue.severity}: ${getSpecDiffRelativePath({ workspacePath: workspaceRoot, baseRef: "", headRef: "", deltas: [] }, issue.path)} - ${issue.message}`);
+}
+
+function getBlockingValidationIssues(workspace: LoadedSpecWorkspace, diff: SpecDiffReport): ValidationIssue[] {
+  const changedSpecIds = new Set(diff.deltas.map((delta) => delta.specId));
+  const changedBaseSpecIds = new Set(
+    diff.deltas.flatMap((delta) => {
+      if (delta.kind === "base") {
+        return [delta.specId];
+      }
+
+      return delta.extendsSpecId ? [delta.extendsSpecId] : [];
+    }),
+  );
+  const referencedEnvironments = new Set(
+    diff.deltas.flatMap((delta) => {
+      const document = delta.nextDocument ?? delta.previousDocument;
+      return typeof document?.frontmatter.environment === "string" ? [document.frontmatter.environment] : [];
+    }),
+  );
+  const relevantPaths = new Set<string>(diff.deltas.map((delta) => delta.path));
+
+  for (const document of workspace.documents) {
+    if (document.id && (changedSpecIds.has(document.id) || changedBaseSpecIds.has(document.id))) {
+      relevantPaths.add(document.path);
+      continue;
+    }
+
+    if (
+      document.kind !== "base" &&
+      typeof document.frontmatter.extends === "string" &&
+      changedBaseSpecIds.has(document.frontmatter.extends)
+    ) {
+      relevantPaths.add(document.path);
+    }
+  }
+
+  for (const environment of workspace.environments) {
+    if (environment.name && referencedEnvironments.has(environment.name)) {
+      relevantPaths.add(environment.path);
+    }
+  }
+
+  return workspace.issues.filter((issue) => issue.severity === "error" && relevantPaths.has(issue.path));
+}
+
+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 ensureHarnessSupportsImplementation(inspection: HarnessInspection, profile: ResolvedStageProfile, options: ImplementCommandOptions): void {
+  if (!inspection.adapter.supportedStages.includes("implement")) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` does not support the implement stage.`);
+  }
+
+  if (!profile.allowEdits) {
+    throw new Error(`Implement stage profile \`${profile.profileName}\` must declare \`allow_edits: true\`.`);
+  }
+
+  if (!inspection.capabilities.canEditFiles) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` cannot edit files, so it cannot run \`spec implement\`.`);
+  }
+
+  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: ImplementCommandIO, 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(`- can resume sessions: ${formatCapability(inspection.capabilities.canResumeSessions)}`);
+  io.print(`- supports structured output: ${formatCapability(inspection.capabilities.supportsStructuredOutput)}`);
+  io.print(`- supports model selection: ${formatCapability(inspection.capabilities.supportsModelSelection)}`);
+  io.print(`- supports read-only mode: ${formatCapability(inspection.capabilities.supportsReadOnlyMode)}`);
+  io.print("");
+}
+
+function sha1ForPath(path: string): string {
+  if (!existsSync(path)) {
+    return "missing";
+  }
+
+  const hash = createHash("sha1");
+  hash.update(readFileSync(path));
+  return hash.digest("hex");
+}
+
+function listDirtyPaths(workspaceRoot: string): string[] {
+  const outputs = [
+    runGitCommand(workspaceRoot, ["diff", "--name-only"]),
+    runGitCommand(workspaceRoot, ["diff", "--cached", "--name-only"]),
+    runGitCommand(workspaceRoot, ["ls-files", "--others", "--exclude-standard"]),
+  ];
+  const paths = new Set<string>();
+
+  for (const output of outputs) {
+    for (const line of output.stdout.split("\n")) {
+      const path = line.trim();
+      if (path.length > 0) {
+        paths.add(path);
+      }
+    }
+  }
+
+  return Array.from(paths).sort();
+}
+
+function captureDirtySnapshot(workspaceRoot: string): DirtySnapshot {
+  const files = new Map<string, string>();
+
+  for (const path of listDirtyPaths(workspaceRoot)) {
+    files.set(path, sha1ForPath(join(workspaceRoot, path)));
+  }
+
+  return { files };
+}
+
+function detectChangedFiles(before: DirtySnapshot, after: DirtySnapshot, reportedChangedFiles: string[] = []): string[] {
+  const changed = new Set<string>(reportedChangedFiles.map((path) => path.split("\\").join("/")));
+  const keys = new Set<string>([...before.files.keys(), ...after.files.keys()]);
+
+  for (const key of keys) {
+    if (before.files.get(key) !== after.files.get(key)) {
+      changed.add(key);
+    }
+  }
+
+  return Array.from(changed).sort();
+}
+
+function isProcessRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String((error as { code?: unknown }).code) : undefined;
+    return code !== "ESRCH";
+  }
+}
+
+function acquireWriterLock(workspaceRoot: string): WriterLock {
+  const runtimeDir = resolveWorkspaceLayout(workspaceRoot).runtimeRoot;
+  const lockPath = join(runtimeDir, "spec-implement.lock");
+  mkdirSync(runtimeDir, { recursive: true });
+
+  const writeLock = (): WriterLock => {
+    writeFileSync(lockPath, JSON.stringify({ pid: process.pid, createdAt: new Date().toISOString() }), { flag: "wx" });
+    return {
+      path: lockPath,
+      release(): void {
+        rmSync(lockPath, { force: true });
+      },
+    };
+  };
+
+  try {
+    return writeLock();
+  } catch (error) {
+    const code = typeof error === "object" && error !== null && "code" in error ? String((error as { code?: unknown }).code) : undefined;
+    if (code !== "EEXIST") {
+      throw error;
+    }
+
+    try {
+      const raw = JSON.parse(readFileSync(lockPath, "utf8")) as { pid?: unknown };
+      const pid = typeof raw.pid === "number" ? raw.pid : undefined;
+      if (pid !== undefined && !isProcessRunning(pid)) {
+        rmSync(lockPath, { force: true });
+        return writeLock();
+      }
+    } catch {
+      throw new Error(`Another \`spec implement\` run appears to be active (${lockPath}). Remove the lock if it is stale.`);
+    }
+
+    throw new Error(`Another \`spec implement\` run appears to be active (${lockPath}).`);
+  }
+}
+
+function buildContextFiles(
+  workspace: LoadedSpecWorkspace,
+  diff: SpecDiffReport,
+  plan: SpecImplementationPlan,
+  useWorktreeContext: boolean,
+): string[] {
+  if (!useWorktreeContext) {
+    return [];
+  }
+
+  const files = new Set<string>();
+
+  if (existsSync(workspace.configPath)) {
+    files.add(workspace.configPath);
+  }
+
+  const projectMdPath = resolveEffectiveProjectSpecPath(resolveWorkspaceLayout(workspace.workspacePath));
+  if (projectMdPath && existsSync(projectMdPath)) {
+    files.add(projectMdPath);
+  }
+
+  for (const delta of diff.deltas) {
+    if (existsSync(delta.path)) {
+      files.add(delta.path);
+    }
+  }
+
+  const workspaceFiles = listWorkspaceFiles(workspace.workspacePath);
+  for (const target of plan.impactedSpecs) {
+    const codeMatches = collectTargetContextMatches(
+      workspace.workspacePath,
+      target.codePaths,
+      workspaceFiles,
+      MAX_CONTEXT_CODE_FILES_PER_SPEC,
+    );
+    const testMatches = collectTargetContextMatches(
+      workspace.workspacePath,
+      target.testPaths,
+      workspaceFiles,
+      MAX_CONTEXT_TEST_FILES_PER_SPEC,
+    );
+
+    for (const match of [...codeMatches, ...testMatches]) {
+      files.add(join(workspace.workspacePath, match));
+    }
+
+    const specDoc = workspace.documents.find((doc) => doc.frontmatter.id === target.specId);
+    const contextPaths = Array.isArray(specDoc?.frontmatter.context_paths)
+      ? specDoc.frontmatter.context_paths.filter((entry): entry is string => typeof entry === "string")
+      : [];
+    for (const contextPath of contextPaths) {
+      const resolved = join(workspace.workspacePath, contextPath);
+      if (existsSync(resolved)) {
+        files.add(resolved);
+      }
+    }
+  }
+
+  return Array.from(files).sort();
+}
+
+function printDiffSummary(io: ImplementCommandIO, diff: SpecDiffReport): void {
+  io.print("Spec Deltas");
+  io.print(`- base: ${diff.baseRef}`);
+  io.print(`- head: ${diff.headRef}`);
+  io.print(`- changed specs: ${diff.deltas.length}`);
+  for (const delta of diff.deltas) {
+    io.print(`- ${delta.specId} (${delta.kind}, ${delta.fileChange}) at ${getSpecDiffRelativePath(diff, delta.path)}`);
+  }
+  io.print("");
+}
+
+function printPlanSummary(io: ImplementCommandIO, plan: ReturnType<typeof planSpecImplementation>): void {
+  io.print("Plan");
+  io.print(`- impacted specs: ${plan.impactedSpecs.length}`);
+  io.print(`- planned tasks: ${plan.tasks.length}`);
+  io.print(`- mapped test commands: ${plan.testCommands.length}`);
+  io.print("");
+}
+
+function printChangedFiles(io: ImplementCommandIO, changedFiles: string[]): void {
+  io.print("Changed Files");
+  if (changedFiles.length === 0) {
+    io.print("- none detected");
+  } else {
+    for (const file of changedFiles) {
+      io.print(`- ${file}`);
+    }
+  }
+  io.print("");
+}
+
+function printTestResults(io: ImplementCommandIO, results: Array<{ command: string; result: CommandExecutionResult }>): void {
+  io.print("Mapped Tests");
+  if (results.length === 0) {
+    io.print("- no mapped test commands declared by the impacted specs");
+    io.print("");
+    return;
+  }
+
+  for (const entry of results) {
+    io.print(`- ${entry.command} (${entry.result.exitCode === 0 ? "pass" : "fail"})`);
+    if (entry.result.exitCode !== 0) {
+      const stderr = entry.result.stderr.trim();
+      const stdout = entry.result.stdout.trim();
+      if (stderr) {
+        io.print(stderr);
+      } else if (stdout) {
+        io.print(stdout);
+      }
+    }
+  }
+  io.print("");
+}
+
+export async function runSpecImplementCommand(
+  args: string[],
+  cwd = process.cwd(),
+  deps: ImplementCommandDeps = {},
+): Promise<number> {
+  const io = deps.io ?? createConsoleIO();
+
+  try {
+    const options = parseImplementArgs(args);
+    if (options.help) {
+      printImplementHelp(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 implement --head <rev>` can only target the currently checked out commit. Check out that revision first or omit `--head`.");
+        return 1;
+      }
+
+      if (hasSpecWorktreeDrift(workspaceRoot, options.head)) {
+        io.error("`spec implement --head <rev>` requires the `.specs` workspace to match that revision. Commit or discard spec edits first.");
+        return 1;
+      }
+
+      if (hasUntrackedSpecFiles(workspaceRoot)) {
+        io.error("`spec implement --head <rev>` requires the `.specs` workspace to match that revision. Remove or commit untracked spec files first.");
+        return 1;
+      }
+    }
+
+    const workspace = options.head ? loadSpecWorkspaceAtRef(options.head, workspaceRoot) : loadSpecWorkspace(cwd);
+    const profile = resolveProfile(workspace, options);
+    const diff = collectSpecDiff(workspaceRoot, {
+      baseRef: options.base,
+      headRef: options.head,
+    });
+
+    if (workspace.issues.length > 0) {
+      io.print("Workspace Validation");
+      for (const issue of formatIssuesForConsole(workspace.issues, workspaceRoot)) {
+        io.print(`- ${issue}`);
+      }
+      io.print("");
+    }
+
+    if (diff.deltas.length === 0) {
+      io.print(`No changed specs detected between ${diff.baseRef} and ${diff.headRef}.`);
+      return 0;
+    }
+
+    const plan = planSpecImplementation(workspace, diff);
+    const blockingValidationIssues = getBlockingValidationIssues(workspace, diff);
+    if (blockingValidationIssues.length > 0) {
+      io.error("Refusing to run `spec implement` with validation errors in the changed spec set.");
+      return 1;
+    }
+
+    if (plan.tasks.length === 0) {
+      io.print("No implementation tasks were derived from the changed specs. Skipping the writer harness.");
+      return 0;
+    }
+
+    if (plan.deletedSpecIds.length > 0 && !options.allowSpecDeletions) {
+      io.error(`Spec deletions require explicit confirmation. Re-run with --allow-spec-deletions for: ${plan.deletedSpecIds.join(", ")}`);
+      return 1;
+    }
+
+    const inspectHarness = deps.inspectHarness ?? defaultInspectHarness;
+    const inspection = await inspectHarness(profile.harness, workspaceRoot, profile.command);
+    ensureHarnessSupportsImplementation(inspection, profile, options);
+
+    printHarnessReport(io, inspection, profile);
+    printDiffSummary(io, diff);
+    printPlanSummary(io, plan);
+
+    const prompt = renderImplementPrompt(plan);
+    const contextFiles = buildContextFiles(workspace, diff, plan, true);
+    const runHarness = deps.runHarness ?? runHarnessStage;
+    const lock = acquireWriterLock(workspaceRoot);
+
+    let changedFiles: string[] = [];
+    try {
+      const beforeSnapshot = captureDirtySnapshot(workspaceRoot);
+      const result = await runHarness(
+        profile.harness,
+        {
+          stage: "implement",
+          prompt,
+          cwd: workspaceRoot,
+          allowEdits: true,
+          contextFiles,
+          env: profile.command ? { LISA_HARNESS_COMMAND: resolveHarnessCommandOverride(profile.command, dirname(workspace.configPath)) } : undefined,
+          model: profile.model,
+          profile: profile.profileName,
+          extraArgs: profile.args,
+          limits: { maxTurns: 8 },
+        },
+        workspaceRoot,
+      );
+      const afterHarnessSnapshot = captureDirtySnapshot(workspaceRoot);
+      changedFiles = detectChangedFiles(beforeSnapshot, afterHarnessSnapshot, result.changedFiles ?? []);
+      printChangedFiles(io, changedFiles);
+
+      if (result.status !== "success") {
+        const diagnostic = result.abortReason ?? result.finalText;
+        if (diagnostic?.trim()) {
+          if (result.status === "blocked") {
+            io.error(`Operation blocked: ${diagnostic.trim()}`);
+          } else {
+            io.error(diagnostic.trim());
+          }
+        }
+        return 1;
+      }
+
+      const runCommand = deps.runCommand ?? defaultRunCommand;
+      const testResults = plan.testCommands.map((command) => ({ command, result: runCommand(command, workspaceRoot) }));
+      printTestResults(io, testResults);
+
+      if (testResults.some((entry) => entry.result.exitCode !== 0)) {
+        io.error("One or more mapped test commands failed.");
+        return 1;
+      }
+
+      const guidanceUpdate = updateAgentGuidanceSafely(workspaceRoot);
+      if (guidanceUpdate.path) {
+        io.print(`Updated agent guidance: ${guidanceUpdate.path}`);
+      }
+      if (guidanceUpdate.warning) {
+        io.print(`Agent guidance warning: ${guidanceUpdate.warning}`);
+      }
+      io.print("Implementation completed successfully.");
+      return 0;
+    } finally {
+      lock.release();
+    }
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+}