@wkronmiller/lisa 0.1.0

package/src/spec/workflows/generate.ts

@@ -0,0 +1,1270 @@
+import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { tmpdir } from "os";
+import { basename, dirname, 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 { runHarnessStage } from "../../harness/runner";
+import type { HarnessRequest, HarnessResult } from "../../harness/types";
+import { updateAgentGuidanceSafely } from "../agent-guidance";
+import { resolveStageProfile } from "../config";
+import { resolveLocalOverrides } from "../local-config";
+import { loadSpecWorkspace } from "../loader";
+import { parseSpecDocument } from "../parser";
+import type {
+  LoadedSpecWorkspace,
+  ParsedSpecDocument,
+  ResolvedStageProfile,
+  SpecArea,
+  ValidationIssue,
+} from "../types";
+import { SPEC_AREAS } from "../types";
+import { validateLoadedSpecWorkspace, validateSpecDocument } from "../validator";
+import { assertSafeLisaStorageWritePath, resolveEffectiveProjectSpecPath, resolveSpecWriteRoot, resolveWorkspaceLayout, toLogicalPath, type SpecWriteScope } from "../workspace";
+
+interface GenerateCommandOptions {
+  area?: SpecArea;
+  name?: string;
+  prompt?: string;
+  profile?: string;
+  harness?: string;
+  model?: string;
+  scope?: SpecWriteScope;
+  force: boolean;
+  dryRun: boolean;
+  help: boolean;
+}
+
+interface GenerateDefaults {
+  summary?: string;
+  useCases: string[];
+  invariants: string[];
+  failureModes: string[];
+  acceptanceCriteria: string[];
+  outOfScope: string[];
+  codePaths: string[];
+  testPaths: string[];
+  testCommands: string[];
+  owners: string[];
+}
+
+interface BenchmarkDefaults {
+  environment?: string;
+  command?: string;
+  required?: boolean;
+  metrics: Record<string, string>;
+  notes: string[];
+  sourcePath?: string;
+  content?: string;
+}
+
+interface GenerateBrief {
+  area: SpecArea;
+  name: string;
+  specId: string;
+  targetPath: string;
+  existingBasePath?: string;
+  existingBaseContent?: string;
+  benchmarkPath?: string;
+  summary: string;
+  useCases: string[];
+  invariants: string[];
+  failureModes: string[];
+  acceptanceCriteria: string[];
+  outOfScope: string[];
+  codePaths: string[];
+  testPaths: string[];
+  testCommands: string[];
+  owners: string[];
+  benchmark?: {
+    environment: string;
+    command: string;
+    required: boolean;
+    metrics: Record<string, string>;
+    notes: string[];
+    existingPath?: string;
+    existingContent?: string;
+  };
+}
+
+interface GeneratedFileDraft {
+  path: string;
+  content: string;
+}
+
+interface GeneratedDraftBundle {
+  files: GeneratedFileDraft[];
+  notes: string[];
+}
+
+export interface GenerateCommandIO {
+  ask(question: string): Promise<string>;
+  print(message: string): void;
+  error(message: string): void;
+  isInputClosed?(): boolean;
+  close?(): void;
+}
+
+export interface GenerateCommandDeps {
+  io?: GenerateCommandIO;
+  runHarness?: (harnessId: string, request: HarnessRequest, cwd: string) => Promise<HarnessResult>;
+}
+
+function createConsoleIO(): GenerateCommandIO {
+  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);
+      },
+      isInputClosed(): boolean {
+        return closed;
+      },
+      close(): void {
+        rl.close();
+      },
+    };
+  }
+
+  const rl = createInterface({ input, output });
+  let closed = false;
+  rl.on("close", () => {
+    closed = true;
+  });
+
+  return {
+    async ask(question: string): Promise<string> {
+      if (closed) {
+        return "";
+      }
+
+      return rl.question(question);
+    },
+    print(message: string): void {
+      console.log(message);
+    },
+    error(message: string): void {
+      console.error(message);
+    },
+    isInputClosed(): boolean {
+      return closed;
+    },
+    close(): void {
+      rl.close();
+    },
+  };
+}
+
+function printGenerateHelp(io: GenerateCommandIO): void {
+  io.print(`Lisa spec generate
+
+Usage:
+  lisa spec generate [backend|frontend] [name] [options]
+
+Options:
+  --prompt <text>    Generate from a single natural-language description (skips interactive Q&A)
+  --profile <name>   Override the generate 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 parseGenerateArgs(args: string[]): GenerateCommandOptions {
+  const positionals: string[] = [];
+  const options: GenerateCommandOptions = {
+    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 === "--prompt" || arg === "--profile" || arg === "--harness" || arg === "--model" || arg === "--scope") {
+      const value = args[index + 1];
+      if (!value && arg !== "--prompt") {
+        throw new Error(`${arg} requires a value.`);
+      }
+
+      index += 1;
+      if (arg === "--prompt") {
+        options.prompt = value ?? "";
+      } else 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 generate option: ${arg}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals[0] && SPEC_AREAS.includes(positionals[0] as SpecArea)) {
+    options.area = positionals[0] as SpecArea;
+  } else if (positionals[0]) {
+    throw new Error(`Expected first positional argument to be one of: ${SPEC_AREAS.join(", ")}.`);
+  }
+
+  if (positionals[1]) {
+    options.name = positionals[1];
+  }
+
+  if (positionals.length > 2) {
+    throw new Error("lisa spec generate accepts at most two positional arguments: [backend|frontend] [name].");
+  }
+
+  return options;
+}
+
+function normalizeSpecName(inputName: string): string {
+  return inputName
+    .trim()
+    .replace(/\.md$/i, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function splitList(value: string): string[] {
+  return value
+    .split(/[;\n]/)
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
+function extractListFromSection(document: ParsedSpecDocument, title: string): string[] {
+  const section = document.sections.find((entry) => entry.title.toLowerCase() === title.toLowerCase());
+  if (!section || section.content.trim().length === 0) {
+    return [];
+  }
+
+  const bullets = section.content
+    .split("\n")
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith("- "))
+    .map((line) => line.slice(2).trim())
+    .filter((line) => line.length > 0);
+
+  return bullets.length > 0 ? bullets : [section.content.trim()];
+}
+
+function extractSummary(document: ParsedSpecDocument): string | undefined {
+  return document.sections.find((section) => section.title.toLowerCase() === "summary")?.content.trim() || undefined;
+}
+
+function formatDefaultList(values: string[]): string | undefined {
+  return values.length > 0 ? values.join("; ") : undefined;
+}
+
+function formatMetricThresholds(metrics: Record<string, string>): string | undefined {
+  const entries = Object.entries(metrics).map(([metric, threshold]) => `${metric}${threshold.replace(/^\s*/, "")}`);
+  return entries.length > 0 ? entries.join("; ") : undefined;
+}
+
+function parseMetricThresholds(inputValue: string): Record<string, string> {
+  const metrics: Record<string, string> = {};
+
+  for (const entry of splitList(inputValue)) {
+    const match = entry.match(/^([A-Za-z0-9_.-]+)\s*(<=|>=|==|=|<|>)\s*(.+)$/);
+    if (!match) {
+      throw new Error(`Could not parse benchmark metric threshold: ${entry}`);
+    }
+
+    const [, name, operator, rawValue] = match;
+    const normalizedOperator = operator === "=" ? "==" : operator;
+    metrics[name] = `${normalizedOperator} ${rawValue.trim()}`;
+  }
+
+  return metrics;
+}
+
+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 promptValue(
+  io: GenerateCommandIO,
+  question: string,
+  options: { defaultValue?: string; required?: boolean } = {},
+): Promise<string> {
+  const suffix = options.defaultValue ? ` [${options.defaultValue}]` : "";
+
+  while (true) {
+    const answer = (await io.ask(`${question}${suffix}: `)).trim();
+    const resolved = answer || options.defaultValue || "";
+
+    if (!options.required || resolved.trim().length > 0) {
+      return resolved;
+    }
+
+    if (io.isInputClosed?.()) {
+      throw new Error(`${question} is required.`);
+    }
+
+    io.print(`${question} is required.`);
+  }
+}
+
+async function promptYesNo(io: GenerateCommandIO, 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 resolveProfile(
+  workspace: LoadedSpecWorkspace,
+  options: GenerateCommandOptions,
+): ResolvedStageProfile {
+  const local = resolveLocalOverrides(workspace.localConfigRoot);
+  if (workspace.config) {
+    const resolved = resolveStageProfile(workspace.config, "generate", {
+      profile: options.profile,
+      harness: options.harness,
+      model: options.model,
+    }, local);
+    if (!resolved) {
+      throw new Error("Unable to resolve a generate stage profile from `.specs/config.yaml`.");
+    }
+    return resolved;
+  }
+
+  return {
+    stage: "generate",
+    profileName: options.profile ?? "default-generate",
+    harness: options.harness ?? local.harness ?? "opencode",
+    model: options.model,
+    allowEdits: false,
+    args: [],
+  };
+}
+
+function emptyGenerateDefaults(): GenerateDefaults {
+  return {
+    useCases: [],
+    invariants: [],
+    failureModes: [],
+    acceptanceCriteria: [],
+    outOfScope: [],
+    codePaths: [],
+    testPaths: [],
+    testCommands: [],
+    owners: [],
+  };
+}
+
+function buildGenerateDefaults(document: ParsedSpecDocument): GenerateDefaults {
+  const codePaths = Array.isArray(document.frontmatter.code_paths)
+    ? document.frontmatter.code_paths.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const testPaths = Array.isArray(document.frontmatter.test_paths)
+    ? document.frontmatter.test_paths.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const testCommands = Array.isArray(document.frontmatter.test_commands)
+    ? document.frontmatter.test_commands.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const owners = Array.isArray(document.frontmatter.owners)
+    ? document.frontmatter.owners.filter((entry): entry is string => typeof entry === "string")
+    : [];
+
+  return {
+    summary: extractSummary(document),
+    useCases: extractListFromSection(document, "Use Cases"),
+    invariants: extractListFromSection(document, "Invariants"),
+    failureModes: extractListFromSection(document, "Failure Modes"),
+    acceptanceCriteria: extractListFromSection(document, "Acceptance Criteria"),
+    outOfScope: extractListFromSection(document, "Out of Scope"),
+    codePaths,
+    testPaths,
+    testCommands,
+    owners,
+  };
+}
+
+function readExistingBaseDefaults(targetPath: string): GenerateDefaults {
+  if (!existsSync(targetPath)) {
+    return emptyGenerateDefaults();
+  }
+
+  return buildGenerateDefaults(parseSpecDocument(targetPath, readFileSync(targetPath, "utf8")));
+}
+
+function findBenchmarkCandidates(areaPath: string, name: string): string[] {
+  if (!existsSync(areaPath)) {
+    return [];
+  }
+
+  return readdirSync(areaPath)
+    .filter((entry) => entry.startsWith(`${name}.bench.`) && entry.endsWith(".md"))
+    .sort()
+    .map((entry) => join(areaPath, entry));
+}
+
+function readBenchmarkDefaults(areaPath: string, name: string): BenchmarkDefaults | undefined {
+  const benchmarkPaths = findBenchmarkCandidates(areaPath, name);
+  const sourcePath = benchmarkPaths[0];
+  if (!sourcePath) {
+    return undefined;
+  }
+
+  const content = readFileSync(sourcePath, "utf8");
+  const document = parseSpecDocument(sourcePath, content);
+  return buildBenchmarkDefaults(document, sourcePath, content);
+}
+
+function buildBenchmarkDefaults(document: ParsedSpecDocument, sourcePath?: string, content?: string): BenchmarkDefaults {
+  const metrics = document.frontmatter.metrics && typeof document.frontmatter.metrics === "object" && !Array.isArray(document.frontmatter.metrics)
+    ? Object.fromEntries(
+      Object.entries(document.frontmatter.metrics).filter((entry): entry is [string, string] => typeof entry[1] === "string"),
+    )
+    : {};
+
+  return {
+    environment: typeof document.frontmatter.environment === "string" ? document.frontmatter.environment : undefined,
+    command: typeof document.frontmatter.command === "string" ? document.frontmatter.command : undefined,
+    required: typeof document.frontmatter.required === "boolean" ? document.frontmatter.required : undefined,
+    metrics,
+    notes: extractListFromSection(document, "Notes"),
+    sourcePath,
+    content,
+  };
+}
+
+async function collectGenerateBrief(
+  io: GenerateCommandIO,
+  workspace: LoadedSpecWorkspace,
+  options: GenerateCommandOptions,
+): Promise<GenerateBrief> {
+  const workspaceRoot = workspace.workspacePath;
+  const area = options.area ?? (await promptValue(io, "Spec area (backend or frontend)", { required: true })) as SpecArea;
+  if (!SPEC_AREAS.includes(area)) {
+    throw new Error(`Spec area must be one of: ${SPEC_AREAS.join(", ")}.`);
+  }
+
+  const rawName = options.name ?? (await promptValue(io, "Spec name", { required: true }));
+  const name = normalizeSpecName(rawName);
+  if (!name) {
+    throw new Error("Spec name must contain at least one alphanumeric character.");
+  }
+
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const areaPath = join(resolveSpecWriteRoot(workspaceRoot, options.scope ?? "repo"), area);
+  const targetPath = join(areaPath, `${name}.md`);
+  const logicalTargetPath = join(".specs", area, `${name}.md`).split("\\").join("/");
+  const specId = `${area}.${name}`;
+  const existingBaseDocument = workspace.documents.find(
+    (document) => document.kind === "base" && toLogicalPath(layout, document.path) === logicalTargetPath,
+  );
+  const existingBasePath = existsSync(targetPath) ? targetPath : existingBaseDocument?.path;
+  const baseDefaults = existsSync(targetPath)
+    ? readExistingBaseDefaults(targetPath)
+    : existingBaseDocument
+      ? buildGenerateDefaults(existingBaseDocument)
+      : emptyGenerateDefaults();
+  const benchmarkPrefix = join(".specs", area, `${name}.bench.`).split("\\").join("/");
+  const existingBenchmarkDocument = workspace.documents.find(
+    (document) => document.extensionKind === "benchmark" && toLogicalPath(layout, document.path).startsWith(benchmarkPrefix),
+  );
+  const benchmarkDefaults = findBenchmarkCandidates(areaPath, name).length > 0
+    ? readBenchmarkDefaults(areaPath, name)
+    : existingBenchmarkDocument
+      ? buildBenchmarkDefaults(existingBenchmarkDocument, existingBenchmarkDocument.path, readFileSync(existingBenchmarkDocument.path, "utf8"))
+      : undefined;
+
+  io.print("");
+  io.print(`Collecting input for ${toLogicalPath(layout, targetPath) || basename(targetPath)}.`);
+  io.print("Use semicolons for multi-item answers. Leave optional prompts blank to keep existing values.");
+
+  const summary = await promptValue(io, "Summary", { defaultValue: baseDefaults.summary, required: true });
+  const useCases = splitList(await promptValue(io, "Use Cases", { defaultValue: formatDefaultList(baseDefaults.useCases), required: true }));
+  const invariants = splitList(await promptValue(io, "Invariants", { defaultValue: formatDefaultList(baseDefaults.invariants), required: true }));
+  const failureModes = splitList(
+    await promptValue(io, "Failure modes / edge cases", { defaultValue: formatDefaultList(baseDefaults.failureModes), required: true }),
+  );
+  const acceptanceCriteria = splitList(
+    await promptValue(io, "Acceptance Criteria", { defaultValue: formatDefaultList(baseDefaults.acceptanceCriteria), required: true }),
+  );
+  const outOfScope = splitList(
+    await promptValue(io, "Out of Scope", { defaultValue: formatDefaultList(baseDefaults.outOfScope), required: true }),
+  );
+  const codePaths = splitList(await promptValue(io, "Code paths", { defaultValue: formatDefaultList(baseDefaults.codePaths), required: true }));
+  const testPaths = splitList(await promptValue(io, "Test paths", { defaultValue: formatDefaultList(baseDefaults.testPaths) }));
+  const testCommands = splitList(await promptValue(io, "Test commands", { defaultValue: formatDefaultList(baseDefaults.testCommands) }));
+  const owners = splitList(await promptValue(io, "Owners", { defaultValue: formatDefaultList(baseDefaults.owners) }));
+
+  if (testPaths.length === 0 && testCommands.length === 0) {
+    throw new Error("At least one test path or test command is required.");
+  }
+
+  const wantsBenchmark = await promptYesNo(io, "Add or update a benchmark sidecar?", Boolean(benchmarkDefaults));
+  if (!wantsBenchmark) {
+    return {
+      area,
+      name,
+        specId,
+        targetPath,
+        existingBasePath,
+        existingBaseContent: existingBasePath ? readFileSync(existingBasePath, "utf8") : undefined,
+        summary,
+      useCases,
+      invariants,
+      failureModes,
+      acceptanceCriteria,
+      outOfScope,
+      codePaths,
+      testPaths,
+      testCommands,
+      owners,
+    };
+  }
+
+  const environment = await promptValue(io, "Benchmark environment", {
+    defaultValue: benchmarkDefaults?.environment,
+    required: true,
+  });
+  const benchmarkPath = join(areaPath, `${name}.bench.${environment}.md`);
+
+  const benchmarkCommand = await promptValue(io, "Benchmark command", {
+    defaultValue: benchmarkDefaults?.command,
+    required: true,
+  });
+  const benchmarkRequired = await promptYesNo(io, "Require this benchmark for the environment?", benchmarkDefaults?.required ?? true);
+  const benchmarkMetricsInput = await promptValue(io, "Benchmark metric thresholds", {
+    defaultValue: formatMetricThresholds(benchmarkDefaults?.metrics ?? {}),
+    required: true,
+  });
+  const benchmarkNotes = splitList(await promptValue(io, "Benchmark notes", { defaultValue: formatDefaultList(benchmarkDefaults?.notes ?? []) }));
+
+  return {
+    area,
+    name,
+    specId,
+    targetPath,
+    existingBasePath,
+    existingBaseContent: existingBasePath ? readFileSync(existingBasePath, "utf8") : undefined,
+    benchmarkPath,
+    summary,
+    useCases,
+    invariants,
+    failureModes,
+    acceptanceCriteria,
+    outOfScope,
+    codePaths,
+    testPaths,
+    testCommands,
+    owners,
+    benchmark: {
+      environment,
+      command: benchmarkCommand,
+      required: benchmarkRequired,
+      metrics: parseMetricThresholds(benchmarkMetricsInput),
+      notes: benchmarkNotes,
+      existingPath: benchmarkDefaults?.sourcePath,
+      existingContent: benchmarkDefaults?.content,
+    },
+  };
+}
+
+function readProjectContext(workspaceRoot: string): string | undefined {
+  const projectMdPath = resolveEffectiveProjectSpecPath(resolveWorkspaceLayout(workspaceRoot));
+  if (!projectMdPath || !existsSync(projectMdPath)) {
+    return undefined;
+  }
+  const content = readFileSync(projectMdPath, "utf8").trim();
+  return content || undefined;
+}
+
+function indentBlock(content: string): string {
+  return content
+    .split("\n")
+    .map((line) => `    ${line}`)
+    .join("\n");
+}
+
+function buildGeneratePrompt(workspace: LoadedSpecWorkspace, brief: GenerateBrief): string {
+  const layout = resolveWorkspaceLayout(workspace.workspacePath);
+  const baseExisting = brief.existingBaseContent ?? (existsSync(brief.targetPath) ? readFileSync(brief.targetPath, "utf8") : undefined);
+  const benchmarkExisting = brief.benchmark?.existingContent;
+  const relativeBasePath = toLogicalPath(layout, brief.targetPath);
+  const relativeBenchmarkPath = brief.benchmarkPath ? toLogicalPath(layout, brief.benchmarkPath) : undefined;
+
+  return `You are generating Lisa spec files for a spec-driven engineering workflow.
+
+Return JSON only between these exact markers:
+LISA_GENERATE_JSON_START
+<json>
+LISA_GENERATE_JSON_END
+
+JSON shape:
+{
+  "files": [
+    { "path": "${relativeBasePath}", "content": "full markdown document" }
+${relativeBenchmarkPath ? `    ,{ "path": "${relativeBenchmarkPath}", "content": "full markdown document" }` : ""}
+  ],
+  "notes": ["optional short notes"]
+}
+
+Rules:
+- If you cannot complete this request safely because required capabilities or repository access are unavailable, respond with only:
+  LISA_ABORT_START
+  <short reason>
+  LISA_ABORT_END
+- Generate exactly one base spec file at ${relativeBasePath}.
+- ${relativeBenchmarkPath ? `If benchmark coverage was requested, also generate exactly one benchmark sidecar at ${relativeBenchmarkPath}.` : "Do not generate any benchmark sidecar."}
+- Keep the output scoped to the requested files only.
+- Base specs must include YAML frontmatter with id, status, code_paths, and at least one of test_paths or test_commands.
+- Base specs generated by this workflow must set status: active.
+- Active base specs must include Summary, Use Cases, Invariants, Acceptance Criteria, and Out of Scope sections.
+- Base specs must also include a non-empty Failure Modes section that preserves every prompted failure mode or edge case.
+- Benchmark sidecars must declare kind: benchmark, extends, status, required, environment, command, and metrics.
+- Use concise, concrete language grounded in the provided answers.
+
+Requested base spec:
+- area: ${brief.area}
+- name: ${brief.name}
+- id: ${brief.specId}
+- status: active
+- path: ${relativeBasePath}
+- summary: ${brief.summary}
+- use_cases: ${brief.useCases.join(" | ")}
+- invariants: ${brief.invariants.join(" | ")}
+- failure_modes: ${brief.failureModes.join(" | ")}
+- acceptance_criteria: ${brief.acceptanceCriteria.join(" | ")}
+- out_of_scope: ${brief.outOfScope.join(" | ")}
+- code_paths: ${brief.codePaths.join(" | ")}
+- test_paths: ${brief.testPaths.join(" | ") || "(none)"}
+- test_commands: ${brief.testCommands.join(" | ") || "(none)"}
+- owners: ${brief.owners.join(" | ") || "(none)"}
+
+${brief.benchmark ? `Requested benchmark sidecar:
+- path: ${relativeBenchmarkPath}
+- extends: ${brief.specId}
+- environment: ${brief.benchmark.environment}
+- required: ${brief.benchmark.required}
+- command: ${brief.benchmark.command}
+- metrics: ${Object.entries(brief.benchmark.metrics).map(([name, threshold]) => `${name}${threshold.replace(/^\s*/, "")}`).join(" | ")}
+- notes: ${brief.benchmark.notes.join(" | ") || "(none)"}
+
+` : ""}Existing config status:
+- workspace config present: ${workspace.config ? "yes" : "no"}
+- environment count: ${workspace.environments.length}
+
+${(() => { const projectContext = readProjectContext(workspace.workspacePath); return projectContext ? `Project context (.specs/project.md):\n${indentBlock(projectContext)}\n\n` : ""; })()}${baseExisting ? `Existing base spec content:
+${indentBlock(baseExisting)}
+
+` : `No existing base spec content.
+
+`}${benchmarkExisting ? `Existing benchmark sidecar content:
+${indentBlock(benchmarkExisting)}
+
+` : ""}Respond with the JSON payload only inside the required markers.`;
+}
+
+function buildPromptBasedGeneratePrompt(
+  workspace: LoadedSpecWorkspace,
+  area: SpecArea,
+  name: string,
+  specId: string,
+  targetPath: string,
+  existingBasePath: string | undefined,
+  userPrompt: string,
+): string {
+  const layout = resolveWorkspaceLayout(workspace.workspacePath);
+  const baseExisting = existingBasePath && existsSync(existingBasePath) ? readFileSync(existingBasePath, "utf8") : undefined;
+  const relativeBasePath = toLogicalPath(layout, targetPath) || targetPath;
+
+  return `You are generating Lisa spec files for a spec-driven engineering workflow.
+
+Return JSON only between these exact markers:
+LISA_GENERATE_JSON_START
+<json>
+LISA_GENERATE_JSON_END
+
+JSON shape:
+{
+  "files": [
+    { "path": "${relativeBasePath}", "content": "full markdown document" }
+  ],
+  "notes": ["optional short notes"]
+}
+
+Rules:
+- If you cannot complete this request safely because required capabilities or repository access are unavailable, respond with only:
+  LISA_ABORT_START
+  <short reason>
+  LISA_ABORT_END
+- Generate exactly one base spec file at ${relativeBasePath}.
+- Do not generate any benchmark sidecar.
+- Keep the output scoped to the requested files only.
+- Base specs must include YAML frontmatter with id, status, code_paths, and at least one of test_paths or test_commands.
+- Base specs generated by this workflow must set status: active.
+- Active base specs must include Summary, Use Cases, Invariants, Acceptance Criteria, and Out of Scope sections.
+- Base specs must also include a non-empty Failure Modes section.
+- Use concise, concrete language grounded in the provided description.
+- Infer code_paths, test_paths, and test_commands from the description when not explicitly specified; use reasonable placeholders the user can refine.
+
+Requested base spec:
+- area: ${area}
+- name: ${name}
+- id: ${specId}
+- status: active
+- path: ${relativeBasePath}
+
+User description:
+${userPrompt}
+
+Existing config status:
+- workspace config present: ${workspace.config ? "yes" : "no"}
+- environment count: ${workspace.environments.length}
+
+${(() => { const projectContext = readProjectContext(workspace.workspacePath); return projectContext ? `Project context (.specs/project.md):\n${indentBlock(projectContext)}\n\n` : ""; })()}${baseExisting ? `Existing base spec content:
+${indentBlock(baseExisting)}
+
+` : `No existing base spec content.
+
+`}Respond with the JSON payload only inside the required markers.`;
+}
+
+function extractJsonPayload(text: string): string | undefined {
+  const markerMatch = text.match(/LISA_GENERATE_JSON_START\s*([\s\S]*?)\s*LISA_GENERATE_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 parseGeneratedDraft(result: HarnessResult): GeneratedDraftBundle {
+  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("Harness did not return a valid JSON draft payload.");
+  }
+
+  const rawFiles = Array.isArray((raw as Record<string, unknown>).files) ? (raw as Record<string, unknown>).files : [];
+  const files = rawFiles
+    .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 draft payload did not include any files.");
+  }
+
+  const notes = Array.isArray((raw as Record<string, unknown>).notes)
+    ? (raw as Record<string, unknown>).notes.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+
+  return { files, notes };
+}
+
+function validateGeneratedFiles(
+  workspace: LoadedSpecWorkspace,
+  drafts: GeneratedFileDraft[],
+  brief: GenerateBrief,
+): ValidationIssue[] {
+  const layout = resolveWorkspaceLayout(workspace.workspacePath);
+  const parsedDocs = drafts.map((draft) => parseSpecDocument(draft.path, draft.content));
+  const issues = parsedDocs.flatMap((document) => validateSpecDocument(document));
+  const baseDocument = parsedDocs.find((document) => document.path === brief.targetPath);
+  if (!baseDocument || baseDocument.status !== "active") {
+    issues.push({
+      severity: "error",
+      path: brief.targetPath,
+      message: "Generated base specs must declare `status: active`.",
+    });
+  }
+  if (!baseDocument || extractListFromSection(baseDocument, "Failure Modes").length === 0) {
+    issues.push({
+      severity: "error",
+      path: brief.targetPath,
+      message: "Generated base specs must include a non-empty `Failure Modes` section.",
+    });
+  }
+  const replacedPaths = new Set(drafts.map((draft) => toLogicalPath(layout, draft.path)));
+  const mergedDocuments = [
+    ...workspace.documents.filter((document) => !replacedPaths.has(toLogicalPath(layout, document.path))),
+    ...parsedDocs,
+  ];
+
+  return [...issues, ...validateLoadedSpecWorkspace({
+    workspacePath: workspace.workspacePath,
+    config: workspace.config,
+    documents: mergedDocuments,
+    environments: workspace.environments,
+  })];
+}
+
+function normalizeDraftPaths(workspaceRoot: string, drafts: GeneratedFileDraft[], scope: SpecWriteScope = "repo"): GeneratedFileDraft[] {
+  const writeRoot = resolveSpecWriteRoot(workspaceRoot, scope);
+  return drafts.map((draft) => ({
+    path: draft.path.startsWith(".specs/")
+      ? resolve(writeRoot, draft.path.replace(/^\.specs\//, ""))
+      : resolve(workspaceRoot, draft.path),
+    content: draft.content,
+  }));
+}
+
+function enforceAllowedPaths(brief: GenerateBrief, drafts: GeneratedFileDraft[]): void {
+  const allowedPaths = new Set([brief.targetPath, ...(brief.benchmarkPath ? [brief.benchmarkPath] : [])]);
+
+  for (const draft of drafts) {
+    if (!allowedPaths.has(draft.path)) {
+      throw new Error(`Harness returned an unexpected file path: ${draft.path}`);
+    }
+  }
+
+  if (!drafts.some((draft) => draft.path === brief.targetPath)) {
+    throw new Error(`Harness did not return the required base spec file: ${brief.targetPath}`);
+  }
+
+  if (brief.benchmarkPath && !drafts.some((draft) => draft.path === brief.benchmarkPath)) {
+    throw new Error(`Harness did not return the requested benchmark sidecar: ${brief.benchmarkPath}`);
+  }
+}
+
+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-spec-preview-"));
+  const beforePath = join(tempDir, "before.md");
+  const afterPath = join(tempDir, "after.md");
+  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);
+    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 writeGeneratedFiles(workspaceRoot: string, scope: SpecWriteScope, drafts: GeneratedFileDraft[]): void {
+  const writeRoot = resolveSpecWriteRoot(workspaceRoot, scope);
+  for (const draft of drafts) {
+    assertSafeLisaStorageWritePath(writeRoot, draft.path, "Lisa spec generate");
+    mkdirSync(dirname(draft.path), { recursive: true });
+    writeFileSync(draft.path, `${draft.content.trim()}\n`);
+  }
+}
+
+function ensureParentDirectory(path: string): void {
+  mkdirSync(dirname(path), { recursive: true });
+}
+
+function buildGenerateSnapshot(workspaceRoot: string, paths: string[]): { snapshotRoot: string; contextFiles: string[] } {
+  const layout = resolveWorkspaceLayout(workspaceRoot);
+  const snapshotRoot = mkdtempSync(join(tmpdir(), "lisa-generate-"));
+  const contextFiles = new Set<string>();
+
+  for (const path of paths) {
+    if (!existsSync(path)) {
+      continue;
+    }
+
+    const logicalPath = toLogicalPath(layout, path).replace(/^\.\//, "");
+    if (!logicalPath || logicalPath === "." || logicalPath === ".." || logicalPath.startsWith("../") || logicalPath.startsWith("..\\")) {
+      continue;
+    }
+
+    const snapshotRelativePath = logicalPath;
+    ensureParentDirectory(join(snapshotRoot, snapshotRelativePath));
+    writeFileSync(join(snapshotRoot, snapshotRelativePath), readFileSync(path));
+    const snapshotPath = join(snapshotRoot, snapshotRelativePath);
+    if (existsSync(snapshotPath)) {
+      contextFiles.add(snapshotPath);
+    }
+  }
+
+  return {
+    snapshotRoot,
+    contextFiles: Array.from(contextFiles).sort(),
+  };
+}
+
+export async function runSpecGenerateCommand(
+  args: string[],
+  cwd = process.cwd(),
+  deps: GenerateCommandDeps = {},
+): Promise<number> {
+  const io = deps.io ?? createConsoleIO();
+
+  try {
+    const options = parseGenerateArgs(args);
+    if (options.help) {
+      printGenerateHelp(io);
+      return 0;
+    }
+
+    const layout = resolveWorkspaceLayout(cwd);
+    const workspaceRoot = layout.workspacePath;
+    const workspace = loadSpecWorkspace(cwd);
+    const profile = resolveProfile(workspace, options);
+    if (options.prompt !== undefined) {
+      if (!options.prompt.trim()) {
+        io.error("The --prompt value must not be empty.");
+        return 1;
+      }
+
+      const area = options.area;
+      if (!area || !SPEC_AREAS.includes(area)) {
+        io.error(`Spec area is required and must be one of: ${SPEC_AREAS.join(", ")}.`);
+        return 1;
+      }
+
+      const rawName = options.name;
+      if (!rawName) {
+        io.error("Spec name is required.");
+        return 1;
+      }
+
+      const name = normalizeSpecName(rawName);
+      if (!name) {
+        io.error("Spec name must contain at least one alphanumeric character.");
+        return 1;
+      }
+
+      const specId = `${area}.${name}`;
+      const targetPath = join(resolveSpecWriteRoot(workspaceRoot, options.scope ?? "repo"), area, `${name}.md`);
+      const existingDoc = workspace.documents.find((doc) => doc.frontmatter.id === specId);
+      const existingBasePath = existsSync(targetPath) ? targetPath : existingDoc?.path;
+      const prompt = buildPromptBasedGeneratePrompt(workspace, area, name, specId, targetPath, existingBasePath, options.prompt);
+      const runHarness = deps.runHarness ?? runHarnessStage;
+      const specContextPaths = Array.isArray(existingDoc?.frontmatter.context_paths)
+        ? existingDoc.frontmatter.context_paths
+            .filter((entry): entry is string => typeof entry === "string")
+            .map((p) => join(workspaceRoot, p))
+        : [];
+      const projectMdPath = resolveEffectiveProjectSpecPath(layout);
+      const snapshotPaths = [workspace.configPath, targetPath, ...specContextPaths];
+      if (projectMdPath && existsSync(projectMdPath)) {
+        snapshotPaths.push(projectMdPath);
+      }
+      const snapshot = buildGenerateSnapshot(workspaceRoot, snapshotPaths);
+      let result: HarnessResult;
+      try {
+        result = await runHarness(
+          profile.harness,
+          {
+            stage: "generate",
+            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: 1 },
+          },
+          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 a spec.");
+        return 1;
+      }
+
+      const rawDrafts = parseGeneratedDraft(result);
+      const normalizedDrafts = normalizeDraftPaths(workspaceRoot, rawDrafts.files, options.scope ?? "repo");
+      const promptBrief: GenerateBrief = {
+        area,
+        name,
+        specId,
+        targetPath,
+        summary: "",
+        useCases: [],
+        invariants: [],
+        failureModes: [],
+        acceptanceCriteria: [],
+        outOfScope: [],
+        codePaths: [],
+        testPaths: [],
+        testCommands: [],
+        owners: [],
+      };
+      enforceAllowedPaths(promptBrief, normalizedDrafts);
+
+      const issues = validateGeneratedFiles(workspace, normalizedDrafts, promptBrief);
+
+      io.print("");
+      io.print("Proposed patch");
+      io.print("");
+      for (const draft of normalizedDrafts) {
+        io.print(buildPatchPreview(workspaceRoot, draft.path, draft.content));
+        io.print("");
+      }
+
+      if (rawDrafts.notes.length > 0) {
+        io.print("Harness notes");
+        for (const note of rawDrafts.notes) {
+          io.print(`- ${note}`);
+        }
+        io.print("");
+      }
+
+      if (issues.length > 0) {
+        io.print("Validation issues");
+        for (const issue of issues) {
+          io.print(`- ${issue.severity}: ${relative(workspaceRoot, issue.path) || issue.path} - ${issue.message}`);
+        }
+        io.print("");
+      }
+
+      if (issues.some((issue) => issue.severity === "error")) {
+        io.error("Refusing to write generated specs with validation errors.");
+        return 1;
+      }
+
+      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 spec patch now?", false);
+        if (!approved) {
+          io.print("Cancelled. No files were written.");
+          return 0;
+        }
+      }
+
+      writeGeneratedFiles(workspaceRoot, options.scope ?? "repo", normalizedDrafts);
+      const guidanceUpdate = updateAgentGuidanceSafely(workspaceRoot);
+      io.print(`Wrote ${normalizedDrafts.length} spec file${normalizedDrafts.length === 1 ? "" : "s"}.`);
+      if (guidanceUpdate.path) {
+        io.print(`Updated agent guidance: ${guidanceUpdate.path}`);
+      }
+      if (guidanceUpdate.warning) {
+        io.print(`Agent guidance warning: ${guidanceUpdate.warning}`);
+      }
+      return 0;
+    }
+
+    const brief = await collectGenerateBrief(io, workspace, options);
+    const prompt = buildGeneratePrompt(workspace, brief);
+    const runHarness = deps.runHarness ?? runHarnessStage;
+    const interactiveProjectMdPath = resolveEffectiveProjectSpecPath(layout);
+    const interactiveSnapshotPaths = [workspace.configPath, brief.targetPath, ...(brief.benchmarkPath ? [brief.benchmarkPath] : [])];
+    if (interactiveProjectMdPath && existsSync(interactiveProjectMdPath)) {
+      interactiveSnapshotPaths.push(interactiveProjectMdPath);
+    }
+    const snapshot = buildGenerateSnapshot(workspaceRoot, interactiveSnapshotPaths);
+    let result: HarnessResult;
+    try {
+      result = await runHarness(
+        profile.harness,
+        {
+          stage: "generate",
+          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: 1 },
+        },
+        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 a spec.");
+      return 1;
+    }
+
+    const rawDrafts = parseGeneratedDraft(result);
+    const normalizedDrafts = normalizeDraftPaths(workspaceRoot, rawDrafts.files, options.scope ?? "repo");
+    enforceAllowedPaths(brief, normalizedDrafts);
+
+    const issues = validateGeneratedFiles(workspace, normalizedDrafts, brief);
+
+    io.print("");
+    io.print("Proposed patch");
+    io.print("");
+    for (const draft of normalizedDrafts) {
+      io.print(buildPatchPreview(workspaceRoot, draft.path, draft.content));
+      io.print("");
+    }
+
+    if (rawDrafts.notes.length > 0) {
+      io.print("Harness notes");
+      for (const note of rawDrafts.notes) {
+        io.print(`- ${note}`);
+      }
+      io.print("");
+    }
+
+    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 generated specs with validation errors.");
+      return 1;
+    }
+
+    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 spec patch now?", false);
+      if (!approved) {
+        io.print("Cancelled. No files were written.");
+        return 0;
+      }
+    }
+
+    writeGeneratedFiles(workspaceRoot, options.scope ?? "repo", normalizedDrafts);
+    const guidanceUpdate = updateAgentGuidanceSafely(workspaceRoot);
+    io.print(`Wrote ${normalizedDrafts.length} spec file${normalizedDrafts.length === 1 ? "" : "s"}.`);
+    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?.();
+  }
+}