@wkronmiller/lisa 0.1.0

package/src/spec/workflows/import.ts

@@ -0,0 +1,986 @@
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "path";
+import { createInterface } from "readline/promises";
+import { stdin as input, stdout as output } from "process";
+
+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 { resolveStageProfile } from "../config";
+import { resolveLocalOverrides } from "../local-config";
+import { buildImportPromptGuidance, validateImportBundleWithExtensions } from "../extensions/registry";
+import { loadSpecWorkspace } from "../loader";
+import { parseSpecEnvironmentConfig, parseSpecDocument } from "../parser";
+import { renderImportPrompt } from "../prompt-renderer";
+import type {
+  LoadedSpecWorkspace,
+  ParsedEnvironmentConfig,
+  ParsedSpecDocument,
+  ResolvedStageProfile,
+  SpecImportReport,
+  SpecImportUncertainty,
+  ValidationIssue,
+} from "../types";
+import { SPEC_IMPORT_UNCERTAINTY_LEVELS } from "../types";
+import { validateEnvironmentConfig, validateLoadedSpecWorkspace, validateSpecDocument } from "../validator";
+import { assertSafeLisaStorageWritePath, resolveEffectiveProjectSpecPath, resolveSpecWriteRoot, resolveWorkspaceLayout, toLogicalPath, type SpecWriteScope } from "../workspace";
+import type { ParsedImportBundle } from "../extensions/types";
+
+interface ImportCommandOptions {
+  paths: string[];
+  profile?: string;
+  harness?: string;
+  model?: string;
+  scope?: SpecWriteScope;
+  force: boolean;
+  dryRun: boolean;
+  help: boolean;
+}
+
+interface ImportDraftFile {
+  path: string;
+  content: string;
+}
+
+interface ImportParsedDrafts {
+  documents: ParsedSpecDocument[];
+  environments: ParsedEnvironmentConfig[];
+}
+
+export interface ImportCommandIO {
+  ask(question: string): Promise<string>;
+  print(message: string): void;
+  error(message: string): void;
+  close?(): void;
+}
+
+export interface ImportCommandDeps {
+  io?: ImportCommandIO;
+  runHarness?: (harnessId: string, request: HarnessRequest, cwd: string) => Promise<HarnessResult>;
+  inspectHarness?: (harnessId: string, cwd: string, commandOverride?: string) => Promise<HarnessInspection>;
+}
+
+function createConsoleIO(): ImportCommandIO {
+  if (!input.isTTY) {
+    const rl = createInterface({ input, terminal: false });
+    const answers: string[] = [];
+    const waiters: Array<(answer: string) => void> = [];
+    let closed = false;
+
+    rl.on("line", (line) => {
+      const waiter = waiters.shift();
+      if (waiter) {
+        waiter(line);
+        return;
+      }
+      answers.push(line);
+    });
+
+    rl.on("close", () => {
+      closed = true;
+      while (waiters.length > 0) {
+        const waiter = waiters.shift();
+        waiter?.("");
+      }
+    });
+
+    return {
+      async ask(question: string): Promise<string> {
+        output.write(question);
+        if (answers.length > 0) {
+          return answers.shift() ?? "";
+        }
+
+        if (closed) {
+          return "";
+        }
+
+        return new Promise((resolve) => {
+          waiters.push(resolve);
+        });
+      },
+      print(message: string): void {
+        console.log(message);
+      },
+      error(message: string): void {
+        console.error(message);
+      },
+      close(): void {
+        rl.close();
+      },
+    };
+  }
+
+  const rl = createInterface({ input, output });
+
+  return {
+    async ask(question: string): Promise<string> {
+      return rl.question(question);
+    },
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+    close(): void {
+      rl.close();
+    },
+  };
+}
+
+function printImportHelp(io: ImportCommandIO): void {
+  io.print(`Lisa spec import
+
+Usage:
+  lisa spec import <path...> [options]
+
+Options:
+  --profile <name>   Override the import stage profile
+  --harness <id>     Override the configured harness adapter
+  --model <name>     Override the configured model
+  --scope <name>     Write to the shared repo layer or worktree override layer
+  --force            Skip approval prompts and write immediately
+  --dry-run          Show the proposed patch without writing files
+  --help, -h         Show this help
+`);
+}
+
+function parseImportArgs(args: string[]): ImportCommandOptions {
+  const options: ImportCommandOptions = {
+    paths: [],
+    force: false,
+    dryRun: 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 === "--force") {
+      options.force = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
+    if (arg === "--profile" || arg === "--harness" || arg === "--model" || arg === "--scope") {
+      const value = args[index + 1];
+      if (!value) {
+        throw new Error(`${arg} requires a value.`);
+      }
+
+      index += 1;
+      if (arg === "--profile") {
+        options.profile = value;
+      } else if (arg === "--harness") {
+        options.harness = value;
+      } else if (arg === "--scope") {
+        if (value !== "repo" && value !== "worktree") {
+          throw new Error("--scope requires `repo` or `worktree`.");
+        }
+        options.scope = value;
+      } else {
+        options.model = value;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("--")) {
+      throw new Error(`Unknown lisa spec import option: ${arg}`);
+    }
+
+    options.paths.push(arg);
+  }
+
+  if (!options.help && options.paths.length === 0) {
+    throw new Error("lisa spec import requires at least one path to analyze.");
+  }
+
+  return options;
+}
+
+function normalizeBooleanAnswer(answer: string, fallback = false): boolean {
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+
+  if (["y", "yes"].includes(normalized)) {
+    return true;
+  }
+
+  if (["n", "no"].includes(normalized)) {
+    return false;
+  }
+
+  return fallback;
+}
+
+async function promptYesNo(io: ImportCommandIO, question: string, fallback = false): Promise<boolean> {
+  const label = fallback ? "Y/n" : "y/N";
+  const answer = await io.ask(`${question} [${label}]: `);
+  return normalizeBooleanAnswer(answer, fallback);
+}
+
+function assertSafeImportSourcePath(workspaceRoot: string, targetPath: string): void {
+  const workspaceRealPath = realpathSync(workspaceRoot);
+  let cursor = targetPath;
+
+  while (cursor.startsWith(workspaceRoot)) {
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`Import paths must not traverse symlinked segments: ${targetPath}`);
+    }
+    if (cursor === workspaceRoot) {
+      break;
+    }
+    cursor = dirname(cursor);
+  }
+
+  const realTargetPath = realpathSync(targetPath);
+  if (realTargetPath !== workspaceRealPath && !realTargetPath.startsWith(`${workspaceRealPath}/`)) {
+    throw new Error(`Import paths must stay inside the workspace: ${targetPath}`);
+  }
+}
+
+function shouldTraverseImportDirectory(name: string): boolean {
+  return ![".git", "node_modules", ".lisa"].includes(name);
+}
+
+function shouldIncludeImportFile(path: string): boolean {
+  const name = basename(path);
+  if (/^\.env(?:\..*)?$/i.test(name) || /(?:secret|token|credential|private)/i.test(name)) {
+    return false;
+  }
+
+  if ([".pem", ".key", ".p12", ".pfx", ".crt", ".cer", ".der", ".jks", ".keystore"].some((suffix) => name.toLowerCase().endsWith(suffix))) {
+    return false;
+  }
+
+  const extension = name.includes(".") ? name.slice(name.lastIndexOf(".")).toLowerCase() : "";
+  if ([".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".pdf", ".zip", ".gz", ".tar", ".mp4", ".mov", ".mp3", ".wav"].includes(extension)) {
+    return false;
+  }
+
+  if (["Dockerfile", "Makefile", "README", "README.md", "README.txt"].includes(name)) {
+    return true;
+  }
+
+  return [
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".json", ".md", ".mdx", ".yaml", ".yml", ".toml", ".txt", ".py", ".rb",
+    ".go", ".rs", ".java", ".kt", ".swift", ".php", ".c", ".cc", ".cpp", ".h", ".hpp", ".cs", ".sh", ".sql", ".graphql",
+    ".proto", ".html", ".css", ".scss", ".sass", ".less", ".xml",
+  ].includes(extension);
+}
+
+function resolveProfile(workspace: LoadedSpecWorkspace, options: ImportCommandOptions): ResolvedStageProfile {
+  const local = resolveLocalOverrides(workspace.localConfigRoot);
+  if (workspace.config) {
+    const resolved = resolveStageProfile(workspace.config, "import", {
+      profile: options.profile,
+      harness: options.harness,
+      model: options.model,
+    }, local);
+    if (!resolved) {
+      throw new Error("Unable to resolve an import stage profile from `.specs/config.yaml`.");
+    }
+    return resolved;
+  }
+
+  return {
+    stage: "import",
+    profileName: options.profile ?? "default-import",
+    harness: options.harness ?? local.harness ?? "opencode",
+    model: options.model,
+    allowEdits: false,
+    args: [],
+  };
+}
+
+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 ensureHarnessSupportsImport(inspection: HarnessInspection, profile: ResolvedStageProfile, options: ImportCommandOptions): void {
+  if (!inspection.adapter.supportedStages.includes("import")) {
+    throw new Error(`Harness \`${inspection.adapter.id}\` does not support the import stage.`);
+  }
+
+  if (profile.allowEdits) {
+    throw new Error(`Import 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: ImportCommandIO, 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(`- supports model selection: ${formatCapability(inspection.capabilities.supportsModelSelection)}`);
+  io.print(`- supports read-only mode: ${formatCapability(inspection.capabilities.supportsReadOnlyMode)}`);
+  io.print(`- workspace isolation: yes (snapshot import context)`);
+  io.print("");
+}
+
+function extractJsonPayload(text: string): string | undefined {
+  const markerMatch = text.match(/LISA_IMPORT_JSON_START\s*([\s\S]*?)\s*LISA_IMPORT_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 parseJsonPayloadWithRecovery(payload: string): unknown {
+  const attempts = [payload];
+  if (payload.includes('\\"')) {
+    attempts.push(payload.replace(/\\"/g, '"'));
+  }
+
+  for (const attempt of attempts) {
+    try {
+      return JSON.parse(attempt);
+    } catch {
+      // Try the next recovery strategy.
+    }
+  }
+
+  return undefined;
+}
+
+function parseImportBundle(result: HarnessResult): ParsedImportBundle {
+  const raw = typeof result.structuredOutput === "object" && result.structuredOutput !== null
+    ? result.structuredOutput
+    : result.finalText
+      ? parseJsonPayloadWithRecovery(extractJsonPayload(result.finalText) ?? "null")
+      : null;
+
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error("Harness did not return a valid JSON import payload.");
+  }
+
+  const files = Array.isArray((raw as { files?: unknown[] }).files)
+    ? (raw as { files: unknown[] }).files
+      .filter(
+        (entry): entry is { path: string; content: string } =>
+          typeof entry === "object"
+          && entry !== null
+          && typeof (entry as { path?: unknown }).path === "string"
+          && typeof (entry as { content?: unknown }).content === "string",
+      )
+      .map((entry) => ({ path: entry.path.trim(), content: entry.content.trim() }))
+    : [];
+
+  if (files.length === 0) {
+    throw new Error("Harness import payload did not include any draft files.");
+  }
+
+  const notes = Array.isArray((raw as { notes?: unknown[] }).notes)
+    ? (raw as { notes: unknown[] }).notes.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+
+  const uncertainties = Array.isArray((raw as { uncertainties?: unknown[] }).uncertainties)
+    ? (raw as { uncertainties: unknown[] }).uncertainties
+      .filter(
+        (entry): entry is SpecImportUncertainty =>
+          typeof entry === "object"
+          && entry !== null
+          && typeof (entry as { detail?: unknown }).detail === "string"
+          && typeof (entry as { level?: unknown }).level === "string"
+          && SPEC_IMPORT_UNCERTAINTY_LEVELS.includes((entry as { level: SpecImportUncertainty["level"] }).level),
+      )
+      .map((entry) => ({
+        path: typeof entry.path === "string" && entry.path.trim().length > 0 ? entry.path.trim() : undefined,
+        specId: typeof entry.specId === "string" && entry.specId.trim().length > 0 ? entry.specId.trim() : undefined,
+        level: entry.level,
+        detail: entry.detail.trim(),
+        question: typeof entry.question === "string" && entry.question.trim().length > 0 ? entry.question.trim() : undefined,
+      }))
+    : [];
+
+  return { files, notes, uncertainties };
+}
+
+function normalizeDraftPaths(workspaceRoot: string, drafts: ImportDraftFile[], scope: SpecWriteScope = "repo"): ImportDraftFile[] {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const writeRoot = resolveSpecWriteRoot(workspaceRoot, scope);
+  return drafts.map((draft) => ({
+    path: (() => {
+      if (draft.path.startsWith(".specs/")) {
+        return resolve(writeRoot, draft.path.replace(/^\.specs\//, ""));
+      }
+
+      if (isAbsolute(draft.path)) {
+        const logicalPath = toLogicalPath(layout, draft.path);
+        if (logicalPath.startsWith(".specs/")) {
+          return resolve(writeRoot, logicalPath.replace(/^\.specs\//, ""));
+        }
+      }
+
+      return resolve(workspaceRoot, draft.path);
+    })(),
+    content: draft.content,
+  }));
+}
+
+function isAllowedImportPath(workspaceRoot: string, targetPath: string): boolean {
+  const relativePath = toLogicalPath(resolveWorkspaceLayout(workspaceRoot), targetPath);
+  if ((relativePath.startsWith(".specs/backend/") || relativePath.startsWith(".specs/frontend/")) && relativePath.endsWith(".md")) {
+    return true;
+  }
+
+  if (relativePath.startsWith(".specs/environments/") && (relativePath.endsWith(".yaml") || relativePath.endsWith(".yml"))) {
+    return true;
+  }
+
+  return false;
+}
+
+function enforceAllowedImportPaths(workspaceRoot: string, drafts: ImportDraftFile[]): void {
+  for (const draft of drafts) {
+    if (!isAllowedImportPath(workspaceRoot, draft.path)) {
+      throw new Error(`Harness returned an unexpected import file path: ${draft.path}`);
+    }
+  }
+}
+
+function normalizeHeading(title: string): string {
+  return title.toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+function hasSection(document: ParsedSpecDocument, expectedTitle: string): boolean {
+  const expected = normalizeHeading(expectedTitle);
+
+  for (const [index, section] of document.sections.entries()) {
+    if (normalizeHeading(section.title) !== expected) {
+      continue;
+    }
+
+    if (section.content.length > 0) {
+      return true;
+    }
+
+    for (let childIndex = index + 1; childIndex < document.sections.length; childIndex += 1) {
+      const childSection = document.sections[childIndex];
+      if (childSection.level <= section.level) {
+        break;
+      }
+
+      if (childSection.content.length > 0) {
+        return true;
+      }
+    }
+  }
+
+  return false;
+}
+
+function parseImportedDrafts(drafts: ImportDraftFile[]): ImportParsedDrafts {
+  const documents: ParsedSpecDocument[] = [];
+  const environments: ParsedEnvironmentConfig[] = [];
+
+  for (const draft of drafts) {
+    if (draft.path.endsWith(".md")) {
+      documents.push(parseSpecDocument(draft.path, draft.content));
+      continue;
+    }
+
+    if (draft.path.endsWith(".yaml") || draft.path.endsWith(".yml")) {
+      environments.push(parseSpecEnvironmentConfig(draft.path, draft.content));
+    }
+  }
+
+  return { documents, environments };
+}
+
+function validateImportedDrafts(
+  workspace: LoadedSpecWorkspace,
+  bundle: ParsedImportBundle,
+  drafts: ImportDraftFile[],
+): ValidationIssue[] {
+  const layout = resolveWorkspaceLayout(workspace.workspacePath);
+  const issues: ValidationIssue[] = [];
+  const parsed = parseImportedDrafts(drafts);
+
+  for (const document of parsed.documents) {
+    issues.push(...validateSpecDocument(document));
+
+    const logicalDocumentPath = toLogicalPath(layout, document.path);
+    const existingDocument = workspace.documents.find((entry) => toLogicalPath(layout, entry.path) === logicalDocumentPath);
+    if (existingDocument && existingDocument.status !== "draft") {
+      issues.push({
+        severity: "error",
+        path: document.path,
+        message: `Import cannot overwrite existing non-draft spec \`${existingDocument.id ?? document.path}\` without an explicit migration step.`,
+      });
+    }
+
+    if (document.status !== "draft") {
+      issues.push({
+        severity: "error",
+        path: document.path,
+        message: "Imported specs must declare `status: draft`.",
+      });
+    }
+
+    if (document.kind === "base") {
+      for (const title of ["Summary", "Use Cases", "Invariants", "Acceptance Criteria", "Out of Scope", "Open Questions", "Uncertainty"]) {
+        if (!hasSection(document, title)) {
+          issues.push({
+            severity: "error",
+            path: document.path,
+            message: `Imported base specs must include a non-empty \`${title}\` section.`,
+          });
+        }
+      }
+    }
+  }
+
+  for (const environment of parsed.environments) {
+    issues.push(...validateEnvironmentConfig(environment));
+
+    const logicalEnvironmentPath = toLogicalPath(layout, environment.path);
+    const existingEnvironment = workspace.environments.find((entry) => toLogicalPath(layout, entry.path) === logicalEnvironmentPath);
+    if (existingEnvironment) {
+      issues.push({
+        severity: "error",
+        path: environment.path,
+        message: `Import cannot overwrite existing environment config \`${existingEnvironment.name ?? environment.path}\` without an explicit migration step.`,
+      });
+    }
+  }
+
+  if (bundle.uncertainties.length === 0) {
+    issues.push({
+      severity: "error",
+      path: workspace.specRoot,
+      message: "Imported bundles must capture at least one uncertainty entry.",
+    });
+  }
+
+  const replacedPaths = new Set(drafts.map((draft) => toLogicalPath(layout, draft.path)));
+  const mergedDocuments = [
+    ...workspace.documents.filter((document) => !replacedPaths.has(toLogicalPath(layout, document.path))),
+    ...parsed.documents,
+  ];
+  const mergedEnvironments = [
+    ...workspace.environments.filter((environment) => !replacedPaths.has(toLogicalPath(layout, environment.path))),
+    ...parsed.environments,
+  ];
+
+  issues.push(...validateLoadedSpecWorkspace({
+    workspacePath: workspace.workspacePath,
+    config: workspace.config,
+    documents: mergedDocuments,
+    environments: mergedEnvironments,
+  }));
+  issues.push(...validateImportBundleWithExtensions(bundle, workspace));
+  return issues;
+}
+
+function buildPatchPreview(workspaceRoot: string, targetPath: string, nextContent: string): string {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const currentContent = existsSync(targetPath) ? readFileSync(targetPath, "utf8") : "";
+  const tempDir = mkdtempSync(join(tmpdir(), "lisa-import-preview-"));
+  const beforePath = join(tempDir, "before.txt");
+  const afterPath = join(tempDir, "after.txt");
+  writeFileSync(beforePath, currentContent);
+  writeFileSync(afterPath, nextContent);
+
+  try {
+    const proc = Bun.spawnSync({
+      cmd: ["git", "diff", "--no-index", "--no-color", "--", beforePath, afterPath],
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const relativePath = toLogicalPath(layout, targetPath) || targetPath;
+    const beforeLabel = `a/${relativePath}`;
+    const afterLabel = `b/${relativePath}`;
+    const stdout = new TextDecoder().decode(proc.stdout);
+
+    if (!stdout.trim()) {
+      return `diff --git ${beforeLabel} ${afterLabel}\n(no content changes)`;
+    }
+
+    return stdout
+      .split(beforePath).join(relativePath)
+      .split(afterPath).join(relativePath)
+      .split(`a/${beforePath}`).join(beforeLabel)
+      .split(`b/${afterPath}`).join(afterLabel);
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+}
+
+function assertSafeWritePath(workspaceRoot: string, targetPath: string): void {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  if (layout.storageMode === "external") {
+    const normalizedTargetPath = resolve(targetPath);
+    const allowedRoots = [layout.repoSpecRoot, layout.worktreeSpecRoot].filter((root): root is string => Boolean(root));
+    const writeRoot = allowedRoots.find((root) => normalizedTargetPath === resolve(root) || normalizedTargetPath.startsWith(`${resolve(root)}/`));
+    if (!writeRoot) {
+      throw new Error(`Refusing to write imported drafts outside the Lisa workspace: ${targetPath}`);
+    }
+    assertSafeLisaStorageWritePath(writeRoot, targetPath, "Lisa spec import");
+    return;
+  }
+
+  const allowedRoots = [
+    workspaceRoot,
+    layout.repoSpecRoot,
+    layout.worktreeSpecRoot,
+    layout.runtimeRoot,
+  ]
+    .filter((root): root is string => Boolean(root))
+    .map((root) => existsSync(root) ? realpathSync(root) : resolve(root));
+  let existingPath = targetPath;
+
+  while (!existsSync(existingPath)) {
+    const parentPath = dirname(existingPath);
+    if (parentPath === existingPath) {
+      throw new Error(`Could not resolve a safe parent directory for ${targetPath}`);
+    }
+    existingPath = parentPath;
+  }
+
+  let cursor = existingPath;
+  while (cursor.startsWith(workspaceRoot)) {
+    if (existsSync(cursor) && lstatSync(cursor).isSymbolicLink()) {
+      throw new Error(`Refusing to write through symlinked import path: ${cursor}`);
+    }
+    if (cursor === workspaceRoot) {
+      break;
+    }
+    cursor = dirname(cursor);
+  }
+
+  const realExistingPath = realpathSync(existingPath);
+  if (!allowedRoots.some((root) => realExistingPath === root || realExistingPath.startsWith(`${root}/`))) {
+    throw new Error(`Refusing to write imported drafts outside the workspace: ${targetPath}`);
+  }
+
+  if (existsSync(targetPath)) {
+    const realTargetPath = realpathSync(targetPath);
+    if (!allowedRoots.some((root) => realTargetPath === root || realTargetPath.startsWith(`${root}/`))) {
+      throw new Error(`Refusing to overwrite imported draft outside the workspace: ${targetPath}`);
+    }
+  }
+}
+
+function writeDrafts(workspaceRoot: string, drafts: ImportDraftFile[]): void {
+  for (const draft of drafts) {
+    assertSafeWritePath(workspaceRoot, draft.path);
+    mkdirSync(dirname(draft.path), { recursive: true });
+    writeFileSync(draft.path, `${draft.content.trim()}\n`);
+  }
+}
+
+interface ImportContextFile {
+  sourcePath: string;
+  snapshotRelativePath: string;
+}
+
+function collectImportContextFiles(workspaceRoot: string, selectedPaths: string[]): ImportContextFile[] {
+  const candidates = new Map<string, ImportContextFile>();
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+
+  const addCandidate = (sourcePath: string, snapshotRelativePath: string): void => {
+    candidates.set(snapshotRelativePath, { sourcePath, snapshotRelativePath });
+  };
+
+  const visit = (targetPath: string): void => {
+    assertSafeImportSourcePath(workspaceRoot, targetPath);
+    const stats = lstatSync(targetPath);
+
+    if (stats.isDirectory()) {
+      for (const entry of readdirSync(targetPath)) {
+        if (!shouldTraverseImportDirectory(entry)) {
+          continue;
+        }
+        visit(join(targetPath, entry));
+      }
+      return;
+    }
+
+    if (!stats.isFile() || !shouldIncludeImportFile(targetPath)) {
+      return;
+    }
+
+    addCandidate(targetPath, relative(workspaceRoot, targetPath).split("\\").join("/"));
+  };
+
+  for (const selectedPath of selectedPaths) {
+    visit(selectedPath);
+  }
+
+  for (const common of ["README.md", ".specs/config.yaml", "package.json"]) {
+    const fullPath = join(workspaceRoot, common);
+    if (existsSync(fullPath)) {
+      visit(fullPath);
+    }
+  }
+
+  const projectSpecPath = resolveEffectiveProjectSpecPath(layout);
+  if (projectSpecPath && existsSync(projectSpecPath)) {
+    const logicalPath = toLogicalPath(layout, projectSpecPath);
+    if (logicalPath.startsWith(".specs/")) {
+      addCandidate(projectSpecPath, logicalPath);
+    }
+  }
+
+  return Array.from(candidates.values()).sort((left, right) => left.snapshotRelativePath.localeCompare(right.snapshotRelativePath));
+}
+
+function buildImportSnapshot(_workspaceRoot: string, files: ImportContextFile[]): { snapshotRoot: string; contextFiles: string[] } {
+  const snapshotRoot = mkdtempSync(join(tmpdir(), "lisa-import-context-"));
+
+  for (const file of files) {
+    const destinationPath = join(snapshotRoot, file.snapshotRelativePath);
+    mkdirSync(dirname(destinationPath), { recursive: true });
+    writeFileSync(destinationPath, readFileSync(file.sourcePath));
+  }
+
+  return {
+    snapshotRoot,
+    contextFiles: files.map((file) => join(snapshotRoot, file.snapshotRelativePath)),
+  };
+}
+
+function writeImportArtifact(workspaceRoot: string, report: SpecImportReport): string {
+  const runtimeDir = resolveWorkspaceLayout(workspaceRoot).runtimeRoot;
+  mkdirSync(runtimeDir, { recursive: true });
+  const artifactPath = join(runtimeDir, "spec-import-report.json");
+  writeFileSync(artifactPath, JSON.stringify(report, null, 2) + "\n");
+  return artifactPath;
+}
+
+function printUncertainties(io: ImportCommandIO, uncertainties: SpecImportUncertainty[]): void {
+  if (uncertainties.length === 0) {
+    return;
+  }
+
+  io.print("Captured Uncertainties");
+  for (const uncertainty of uncertainties) {
+    io.print(`- ${uncertainty.level}: ${uncertainty.specId ?? uncertainty.path ?? "(unspecified target)"} - ${uncertainty.detail}`);
+    if (uncertainty.question) {
+      io.print(`  question: ${uncertainty.question}`);
+    }
+  }
+  io.print("");
+}
+
+export async function runSpecImportCommand(
+  args: string[],
+  cwd = process.cwd(),
+  deps: ImportCommandDeps = {},
+): Promise<number> {
+  const io = deps.io ?? createConsoleIO();
+
+  try {
+    const options = parseImportArgs(args);
+    if (options.help) {
+      printImportHelp(io);
+      return 0;
+    }
+
+    const layout = resolveWorkspaceLayout(cwd);
+    const workspaceRoot = layout.workspacePath;
+    const workspace = loadSpecWorkspace(workspaceRoot);
+    const profile = resolveProfile(workspace, options);
+    const inspectHarness = deps.inspectHarness ?? defaultInspectHarness;
+    const inspection = await inspectHarness(profile.harness, workspaceRoot, profile.command);
+    ensureHarnessSupportsImport(inspection, profile, options);
+    printHarnessReport(io, inspection, profile);
+
+    const selectedPaths = options.paths.map((entry) => resolve(workspaceRoot, entry));
+    for (const path of selectedPaths) {
+      const relativePath = relative(workspaceRoot, path).split("\\").join("/");
+      if (relativePath === ".." || relativePath.startsWith("../")) {
+        throw new Error(`Import paths must stay inside the workspace: ${path}`);
+      }
+
+      if (!existsSync(path)) {
+        throw new Error(`Import path does not exist: ${relative(workspaceRoot, path) || path}`);
+      }
+
+      assertSafeImportSourcePath(workspaceRoot, path);
+    }
+
+    io.print("Selection");
+    for (const selectedPath of selectedPaths) {
+      io.print(`- ${relative(workspaceRoot, selectedPath) || selectedPath}`);
+    }
+    io.print("");
+
+    const prompt = renderImportPrompt({
+      workspacePath: workspaceRoot,
+      selectedPaths: selectedPaths.map((path) => relative(workspaceRoot, path) || path),
+      existingDocuments: workspace.documents,
+      extensionGuidance: buildImportPromptGuidance({
+        workspace,
+        selectedPaths: selectedPaths.map((path) => relative(workspaceRoot, path) || path),
+      }),
+      directContextOnly: inspection.adapter.id === "opencode",
+    });
+    const runHarness = deps.runHarness ?? runHarnessStage;
+    const importContextFiles = collectImportContextFiles(workspaceRoot, selectedPaths);
+    const snapshot = buildImportSnapshot(workspaceRoot, importContextFiles);
+    let result: HarnessResult;
+    try {
+      result = await runHarness(
+        profile.harness,
+        {
+          stage: "import",
+          prompt,
+          cwd: snapshot.snapshotRoot,
+          allowEdits: false,
+          contextFiles: snapshot.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: 4 },
+        },
+        workspaceRoot,
+      );
+    } finally {
+      rmSync(snapshot.snapshotRoot, { recursive: true, force: true });
+    }
+
+    if (result.status === "failed" || result.status === "blocked") {
+      io.error(result.abortReason || result.finalText || "Harness failed to draft imported specs.");
+      return 1;
+    }
+
+    const bundle = parseImportBundle(result);
+    const normalizedDrafts = normalizeDraftPaths(workspaceRoot, bundle.files, options.scope ?? "repo");
+    enforceAllowedImportPaths(workspaceRoot, normalizedDrafts);
+    const issues = validateImportedDrafts(workspace, bundle, normalizedDrafts);
+
+    io.print("Proposed patch");
+    io.print("");
+    for (const draft of normalizedDrafts) {
+      io.print(buildPatchPreview(workspaceRoot, draft.path, draft.content));
+      io.print("");
+    }
+
+    if (bundle.notes.length > 0) {
+      io.print("Import Notes");
+      for (const note of bundle.notes) {
+        io.print(`- ${note}`);
+      }
+      io.print("");
+    }
+
+    printUncertainties(io, bundle.uncertainties);
+
+    if (issues.length > 0) {
+      io.print("Validation issues");
+      for (const issue of issues) {
+        io.print(`- ${issue.severity}: ${toLogicalPath(layout, issue.path) || issue.path} - ${issue.message}`);
+      }
+      io.print("");
+    }
+
+    if (issues.some((issue) => issue.severity === "error")) {
+      io.error("Refusing to write imported specs with validation errors.");
+      return 1;
+    }
+
+    const report: SpecImportReport = {
+      workspacePath: workspaceRoot,
+      generatedAt: new Date().toISOString(),
+      selectedPaths: selectedPaths.map((path) => relative(workspaceRoot, path) || path),
+      profile: profile.profileName,
+      harness: profile.harness,
+      files: normalizedDrafts.map((draft) => toLogicalPath(layout, draft.path) || draft.path),
+      notes: bundle.notes,
+      uncertainties: bundle.uncertainties,
+      dryRun: options.dryRun,
+    };
+
+    if (options.dryRun) {
+      io.print("Dry run complete. No files were written.");
+      return 0;
+    }
+
+    if (!options.force) {
+      const approved = await promptYesNo(io, "Write the proposed imported spec patch now?", false);
+      if (!approved) {
+        io.print("Cancelled. No files were written.");
+        return 0;
+      }
+    }
+
+    writeDrafts(workspaceRoot, normalizedDrafts);
+    const artifactPath = writeImportArtifact(workspaceRoot, report);
+    const guidanceUpdate = updateAgentGuidanceSafely(workspaceRoot);
+    io.print(`Wrote ${normalizedDrafts.length} imported spec file${normalizedDrafts.length === 1 ? "" : "s"}.`);
+    io.print(`Import report: ${layout.storageMode === "external" ? artifactPath : relative(workspaceRoot, artifactPath) || artifactPath}`);
+    if (guidanceUpdate.path) {
+      io.print(`Updated agent guidance: ${guidanceUpdate.path}`);
+    }
+    if (guidanceUpdate.warning) {
+      io.print(`Agent guidance warning: ${guidanceUpdate.warning}`);
+    }
+    return 0;
+  } catch (error) {
+    io.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  } finally {
+    io.close?.();
+  }
+}