ai-spec-dev 0.33.0 → 0.36.1

package/cli/index.ts

@@ -1,169 +1,26 @@
 #!/usr/bin/env node
 import { Command } from "commander";
-import * as path from "path";
-import * as fs from "fs-extra";
-import chalk from "chalk";
 import * as dotenv from "dotenv";
-import { input, confirm, select, checkbox } from "@inquirer/prompts";
 
 dotenv.config();
 
-import {
-  SpecGenerator,
-  createProvider,
-  DEFAULT_MODELS,
-  ENV_KEY_MAP,
-  SUPPORTED_PROVIDERS,
-  PROVIDER_CATALOG,
-  AIProvider,
-} from "../core/spec-generator";
-import { ContextLoader, isFrontendDeps } from "../core/context-loader";
-import { SpecRefiner } from "../core/spec-refiner";
-import { CodeGenerator, CodeGenMode } from "../core/code-generator";
-import { CodeReviewer } from "../core/reviewer";
-import { GitWorktreeManager } from "../git/worktree";
-import { ConstitutionGenerator, CONSTITUTION_FILE, printConstitutionHint } from "../core/constitution-generator";
-import { ConstitutionConsolidator } from "../core/constitution-consolidator";
-import { TaskGenerator, printTasks } from "../core/task-generator";
-import { generateSpecWithTasks } from "../core/combined-generator";
-import {
-  slugify,
-  findLatestVersion,
-  nextVersionPath,
-  computeDiff,
-  printDiff,
-  printDiffSummary,
-} from "../core/spec-versioning";
-import { DslExtractor } from "../core/dsl-extractor";
-import { TestGenerator } from "../core/test-generator";
-import { runErrorFeedback } from "../core/error-feedback";
-import { assessSpec, printSpecAssessment } from "../core/spec-assessor";
-import { accumulateReviewKnowledge, appendDirectLesson } from "../core/knowledge-memory";
-import {
-  WorkspaceLoader,
-  WorkspaceConfig,
-  RepoConfig,
-  WORKSPACE_CONFIG_FILE,
-  detectRepoType,
-} from "../core/workspace-loader";
-import {
-  loadGlobalConstitution,
-  saveGlobalConstitution,
-  GLOBAL_CONSTITUTION_FILE,
-} from "../core/global-constitution";
-import { getSavedKey, saveKey, clearAllKeys, clearKey, KEY_STORE_FILE } from "../core/key-store";
-import {
-  globalConstitutionSystemPrompt,
-  buildGlobalConstitutionPrompt,
-} from "../prompts/global-constitution.prompt";
-import { RequirementDecomposer, DecompositionResult, RepoRequirement } from "../core/requirement-decomposer";
-import { buildFrontendApiContract, buildContractContextSection } from "../core/contract-bridge";
-import { loadFrontendContext, buildFrontendContextSection } from "../core/frontend-context-loader";
-import { buildFrontendSpecPrompt, frontendSpecSystemPrompt } from "../prompts/frontend-spec.prompt";
-import { SpecDSL } from "../core/dsl-types";
-import {
-  generateMockAssets,
-  findLatestDslFile,
-  applyMockProxy,
-  restoreMockProxy,
-  startMockServerBackground,
-  saveMockServerPid,
-} from "../core/mock-server-generator";
-import { SpecUpdater } from "../core/spec-updater";
-import { exportOpenApi } from "../core/openapi-exporter";
-import { generateRunId, RunLogger, setActiveLogger } from "../core/run-logger";
-import { RunSnapshot, setActiveSnapshot } from "../core/run-snapshot";
-import { computePromptHash } from "../core/prompt-hasher";
-import { runSelfEval, printSelfEval } from "../core/self-evaluator";
-import { loadRunLogs, buildTrendReport, printTrendReport } from "../core/run-trend";
-import {
-  assessDslRichness,
-  buildDslGapRefinementPrompt,
-  extractStructuralFindings,
-  buildStructuralAmendmentPrompt,
-  printDslGaps,
-  printStructuralFindings,
-} from "../core/dsl-feedback";
-
-// ─── Config File ──────────────────────────────────────────────────────────────
-
-interface AiSpecConfig {
-  provider?: string;
-  model?: string;
-  codegen?: CodeGenMode;
-  codegenProvider?: string;
-  codegenModel?: string;
-  /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
-  minSpecScore?: number;
-}
-
-const CONFIG_FILE = ".ai-spec.json";
-
-async function loadConfig(dir: string): Promise<AiSpecConfig> {
-  const p = path.join(dir, CONFIG_FILE);
-  if (await fs.pathExists(p)) {
-    return fs.readJson(p);
-  }
-  return {};
-}
-
-// ─── API Key Resolution ────────────────────────────────────────────────────────
-
-async function resolveApiKey(
-  providerName: string,
-  cliKey?: string
-): Promise<string> {
-  if (cliKey) return cliKey;
-
-  const envVar = ENV_KEY_MAP[providerName];
-  if (envVar && process.env[envVar]) return process.env[envVar]!;
-
-  // Check saved key and offer reuse
-  const savedKey = await getSavedKey(providerName);
-  if (savedKey) {
-    const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);
-    const choice = await select({
-      message: `${providerName} API key (saved: ${masked}):`,
-      choices: [
-        { name: "Use saved key", value: "reuse" },
-        { name: "Enter a new key", value: "new" },
-      ],
-    });
-    if (choice === "reuse") return savedKey;
-  }
-
-  // Fresh input — save for next time
-  const newKey = await input({
-    message: `Enter your ${providerName} API key${envVar ? ` (or set ${envVar} env var)` : ""}:`,
-    validate: (v) => v.trim().length > 0 || "API key cannot be empty",
-  });
-  await saveKey(providerName, newKey.trim());
-  console.log(chalk.gray(`  Key saved to ${KEY_STORE_FILE}`));
-  return newKey.trim();
-}
-
-// ─── Banner ───────────────────────────────────────────────────────────────────
-
-function printBanner(opts: {
-  specProvider: string;
-  specModel: string;
-  codegenMode: string;
-  codegenProvider: string;
-  codegenModel: string;
-}) {
-  console.log(chalk.blue("\n" + "─".repeat(52)));
-  console.log(chalk.bold("  ai-spec — AI-driven Development Orchestrator"));
-  console.log(chalk.blue("─".repeat(52)));
-  console.log(chalk.gray(`  Spec    : ${opts.specProvider} / ${opts.specModel}`));
-  console.log(
-    chalk.gray(
-      `  Codegen : ${opts.codegenMode} (${opts.codegenProvider} / ${opts.codegenModel})`
-    )
-  );
-  console.log(chalk.blue("─".repeat(52) + "\n"));
-}
-
-// ─── Program ──────────────────────────────────────────────────────────────────
+import { registerCreate } from "./commands/create";
+import { registerReview } from "./commands/review";
+import { registerInit } from "./commands/init";
+import { registerConfig } from "./commands/config";
+import { registerModel } from "./commands/model";
+import { registerWorkspace } from "./commands/workspace";
+import { registerUpdate } from "./commands/update";
+import { registerExport } from "./commands/export";
+import { registerMock } from "./commands/mock";
+import { registerLearn } from "./commands/learn";
+import { registerRestore } from "./commands/restore";
+import { registerTrend } from "./commands/trend";
+import { registerLogs } from "./commands/logs";
+import { registerTypes } from "./commands/types";
+import { registerDashboard } from "./commands/dashboard";
+import { registerVcr } from "./commands/vcr";
+import { registerScan } from "./commands/scan";
 
 const program = new Command();
 
@@ -172,2362 +29,22 @@ program
   .description("AI-driven Development Orchestrator — spec, generate, review")
   .version("0.14.1");
 
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: create
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("create")
-  .description("Generate a feature spec and kick off code generation")
-  .argument("[idea]", "Feature idea in natural language (prompted if omitted)")
-  .option(
-    "--provider <name>",
-    `AI provider for spec generation (${SUPPORTED_PROVIDERS.join("|")})`,
-    undefined
-  )
-  .option("--model <name>", "Model name for spec generation")
-  .option("-k, --key <apiKey>", "API key (overrides env var)")
-  .option(
-    "--codegen <mode>",
-    "Code generation mode: claude-code | api | plan",
-    undefined
-  )
-  .option(
-    "--codegen-provider <name>",
-    "AI provider for code generation (defaults to --provider)"
-  )
-  .option("--codegen-model <name>", "Model for code generation")
-  .option("--codegen-key <key>", "API key for code generation (if different)")
-  .option("--skip-worktree", "Skip git worktree creation (auto-set for frontend projects)")
-  .option("--worktree", "Force git worktree creation even for frontend projects")
-  .option("--skip-review", "Skip automated code review")
-  .option("--skip-tasks", "Skip task generation (just generate spec)")
-  .option("--auto", "Run claude non-interactively via -p flag (saves tokens)")
-  .option("--fast", "Skip interactive spec refinement, proceed immediately with initial spec")
-  .option("--resume", "Resume an interrupted run — skip tasks already marked as done")
-  .option("--skip-dsl", "Skip DSL extraction step")
-  .option("--skip-tests", "Skip test skeleton generation")
-  .option("--skip-error-feedback", "Skip error feedback loop (test/lint auto-fix)")
-  .option("--tdd", "TDD mode: generate failing tests first, then generate implementation to pass them")
-  .option("--skip-assessment", "Skip spec quality pre-assessment before the Approval Gate")
-  .option("--force", "Bypass the spec quality score gate even if score is below minSpecScore")
-  .option("--serve", "After workspace pipeline completes, auto-start mock server + patch frontend proxy")
-  .action(async (idea: string | undefined, opts) => {
-    const currentDir = process.cwd();
-    const config = await loadConfig(currentDir);
-
-    // ── Resolve idea ──────────────────────────────────────────────────────────
-    if (!idea) {
-      idea = await input({
-        message: "What feature do you want to build?",
-        validate: (v) => v.trim().length > 0 || "Please describe your feature",
-      });
-    }
-
-    // ── Detect workspace mode ─────────────────────────────────────────────────
-    const workspaceLoader = new WorkspaceLoader(currentDir);
-    const workspaceConfig = await workspaceLoader.load();
-
-    if (workspaceConfig) {
-      console.log(chalk.cyan(`\n[Workspace] Detected workspace: ${workspaceConfig.name}`));
-      console.log(chalk.gray(`  Repos: ${workspaceConfig.repos.map((r) => r.name).join(", ")}`));
-      const pipelineResults = await runMultiRepoPipeline(idea!, workspaceConfig, opts, currentDir, config);
-
-      // ── Auto-serve: start mock server + patch frontend proxy ──────────────
-      if (opts.serve) {
-        console.log(chalk.blue("\n─── Auto-serve: starting mock server ───────────"));
-        const backendResult = pipelineResults.find((r) => r.role === "backend" && r.status === "success" && r.dsl);
-        const frontendResult = pipelineResults.find((r) => (r.role === "frontend" || r.role === "mobile") && r.status === "success");
-
-        if (!backendResult) {
-          console.log(chalk.yellow("  No successful backend with DSL found — skipping auto-serve."));
-        } else {
-          const mockPort = 3001;
-          // Generate mock assets in backend repo
-          const mockResult = await generateMockAssets(backendResult.dsl!, backendResult.repoAbsPath, { port: mockPort });
-          const serverJsPath = path.join(backendResult.repoAbsPath, "mock", "server.js");
-          console.log(chalk.green(`  ✔ Mock assets generated (${mockResult.files.length} file(s))`));
-
-          // Start mock server
-          const pid = startMockServerBackground(serverJsPath, mockPort);
-          console.log(chalk.green(`  ✔ Mock server started (PID ${pid}) → http://localhost:${mockPort}`));
-
-          // Patch frontend proxy
-          if (frontendResult) {
-            const proxyResult = await applyMockProxy(frontendResult.repoAbsPath, mockPort, backendResult.dsl!.endpoints);
-            await saveMockServerPid(frontendResult.repoAbsPath, pid);
-            if (proxyResult.applied) {
-              console.log(chalk.green(`  ✔ Frontend proxy patched (${proxyResult.framework})`));
-              console.log(chalk.bold.cyan(`\n  Ready! Run your frontend dev server:`));
-              console.log(chalk.white(`    cd ${frontendResult.repoAbsPath}`));
-              console.log(chalk.white(`    ${proxyResult.devCommand}`));
-              console.log(chalk.gray(`\n  When done, restore: ai-spec mock --restore --frontend ${frontendResult.repoAbsPath}`));
-            } else {
-              console.log(chalk.yellow(`  ⚠ Auto-patch not available for ${proxyResult.framework}.`));
-              if (proxyResult.note) console.log(chalk.gray(`    ${proxyResult.note}`));
-              console.log(chalk.gray(`    Mock server: http://localhost:${mockPort}`));
-            }
-          } else {
-            console.log(chalk.gray(`  No frontend repo found — mock server is running at http://localhost:${mockPort}`));
-            console.log(chalk.gray(`  Configure your frontend proxy manually to point to http://localhost:${mockPort}`));
-          }
-        }
-      }
-
-      return;
-    }
-
-    // ── Resolve spec provider ─────────────────────────────────────────────────
-    const specProviderName = opts.provider || config.provider || "gemini";
-    const specModelName =
-      opts.model || config.model || DEFAULT_MODELS[specProviderName];
-    const specApiKey = await resolveApiKey(specProviderName, opts.key);
-
-    // ── Resolve codegen ───────────────────────────────────────────────────────
-    const codegenMode: CodeGenMode =
-      (opts.codegen as CodeGenMode) || config.codegen || "claude-code";
-    const codegenProviderName =
-      opts.codegenProvider || config.codegenProvider || specProviderName;
-    const codegenModelName =
-      opts.codegenModel ||
-      config.codegenModel ||
-      DEFAULT_MODELS[codegenProviderName];
-    const codegenApiKey =
-      codegenProviderName === specProviderName
-        ? specApiKey
-        : await resolveApiKey(codegenProviderName, opts.codegenKey);
-
-    printBanner({
-      specProvider: specProviderName,
-      specModel: specModelName,
-      codegenMode,
-      codegenProvider: codegenProviderName,
-      codegenModel: codegenModelName,
-    });
-
-    // ── Run tracking ──────────────────────────────────────────────────────────────
-    const runId = generateRunId();
-    console.log(chalk.gray(`  Run ID: ${runId}`));
-    const runSnapshot = new RunSnapshot(currentDir, runId);
-    setActiveSnapshot(runSnapshot);
-    const runLogger = new RunLogger(currentDir, runId, {
-      provider: specProviderName,
-      model: specModelName,
-    });
-    setActiveLogger(runLogger);
-
-    // Record prompt hash immediately — links this RunLog to the prompt version
-    // in use, enabling cross-run harnessScore comparisons (Harness Engineering).
-    const promptHash = computePromptHash();
-    runLogger.setPromptHash(promptHash);
-
-    // ── Step 1: Context ───────────────────────────────────────────────────────
-    console.log(chalk.blue("[1/6] Loading project context..."));
-    runLogger.stageStart("context_load");
-    const loader = new ContextLoader(currentDir);
-    const context = await loader.loadProjectContext();
-    const { type: detectedRepoType } = await detectRepoType(currentDir);
-    runLogger.stageEnd("context_load", { techStack: context.techStack, repoType: detectedRepoType });
-    console.log(chalk.gray(`  Tech stack  : ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
-    console.log(chalk.gray(`  Dependencies: ${context.dependencies.length} packages`));
-    console.log(chalk.gray(`  API files   : ${context.apiStructure.length} files`));
-    if (context.schema) {
-      console.log(chalk.gray(`  Prisma schema: found`));
-    }
-    if (context.constitution) {
-      console.log(chalk.green(`  Constitution : found (.ai-spec-constitution.md)`));
-      if (context.constitution.length > 6000) {
-        console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
-      }
-    } else {
-      // Auto-run init: generate constitution before proceeding
-      console.log(chalk.yellow("  Constitution : not found — auto-generating..."));
-      try {
-        const constitutionGen = new ConstitutionGenerator(
-          createProvider(specProviderName, specApiKey, specModelName)
-        );
-        const constitutionContent = await constitutionGen.generate(currentDir);
-        await constitutionGen.saveConstitution(currentDir, constitutionContent);
-        context.constitution = constitutionContent;
-        console.log(chalk.green(`  Constitution : ✔ generated and saved (.ai-spec-constitution.md)`));
-      } catch (err) {
-        console.log(chalk.yellow(`  Constitution : ⚠ auto-generation failed (${(err as Error).message}), continuing without it.`));
-      }
-    }
-
-    // ── Step 2: Spec + Tasks Generation (single AI call) ─────────────────────
-    console.log(chalk.blue(`\n[2/6] Generating spec with ${specProviderName}/${specModelName}...`));
-    const specProvider = createProvider(specProviderName, specApiKey, specModelName);
-
-    let initialSpec: string;
-    let initialTasks: import("../core/task-generator").SpecTask[] = [];
-
-    runLogger.stageStart("spec_gen", { provider: specProviderName, model: specModelName });
-    try {
-      if (opts.skipTasks) {
-        // Tasks skipped: use SpecGenerator alone
-        const generator = new SpecGenerator(specProvider);
-        initialSpec = await generator.generateSpec(idea, context);
-        console.log(chalk.green("  ✔ Spec generated."));
-      } else {
-        // Combined: spec + tasks in one call
-        const result = await generateSpecWithTasks(specProvider, idea, context);
-        initialSpec = result.spec;
-        initialTasks = result.tasks;
-        console.log(chalk.green(`  ✔ Spec generated.`));
-        if (initialTasks.length > 0) {
-          console.log(chalk.green(`  ✔ ${initialTasks.length} tasks generated (combined call).`));
-        } else {
-          console.log(chalk.yellow("  ⚠ Tasks not parsed from response — will retry separately after refinement."));
-        }
-      }
-      runLogger.stageEnd("spec_gen", { taskCount: initialTasks.length });
-    } catch (err) {
-      runLogger.stageFail("spec_gen", (err as Error).message);
-      console.error(chalk.red("  ✘ Spec generation failed:"), err);
-      process.exit(1);
-    }
-
-    // ── Step 3: Interactive Refinement ────────────────────────────────────────
-    let finalSpec: string;
-    if (opts.fast) {
-      console.log(chalk.gray("\n[3/6] Skipping refinement (--fast)."));
-      finalSpec = initialSpec;
-    } else {
-      console.log(chalk.blue("\n[3/6] Interactive spec refinement..."));
-      runLogger.stageStart("spec_refine");
-      const refiner = new SpecRefiner(specProvider);
-      finalSpec = await refiner.refineLoop(initialSpec);
-      runLogger.stageEnd("spec_refine");
-    }
-
-    // Compute slug once — used in Approval Gate diff preview and versioned file save
-    const featureSlug = slugify(idea!);
-
-    // ── Step 3.4: Spec Quality Pre-Assessment ────────────────────────────────
-    // Skipped in --skip-assessment mode.
-    // In --auto mode: skipped UNLESS minSpecScore is configured — the hard gate
-    // must still enforce even in CI/auto runs (only the interactive display is skipped).
-    const minScore = config.minSpecScore ?? 0;
-    const shouldRunAssessment = !opts.skipAssessment && (!opts.auto || minScore > 0);
-
-    if (shouldRunAssessment) {
-      if (!opts.auto) {
-        console.log(chalk.blue("\n[3.4/6] Spec quality assessment..."));
-      }
-      runLogger.stageStart("spec_assess");
-      const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? undefined);
-      if (assessment) {
-        runLogger.stageEnd("spec_assess", { overallScore: assessment.overallScore });
-        if (!opts.auto) printSpecAssessment(assessment);
-
-        if (minScore > 0 && assessment.overallScore < minScore) {
-          if (opts.force) {
-            console.log(chalk.yellow(`\n  ⚠ Score gate: ${assessment.overallScore}/10 < minimum ${minScore}/10 — bypassed with --force.`));
-          } else {
-            runLogger.stageFail("spec_assess", `Score gate: ${assessment.overallScore} < ${minScore}`);
-            console.log(chalk.red(`\n  ✘ Spec quality gate failed: overallScore ${assessment.overallScore}/10 < minimum ${minScore}/10`));
-            if (!opts.auto) {
-              console.log(chalk.gray(`  Address the issues above and re-run, or use --force to bypass.`));
-            } else {
-              console.log(chalk.gray(`  Auto mode: gate enforced. Fix the spec or lower minSpecScore, or use --force to bypass.`));
-            }
-            console.log(chalk.gray(`  Gate threshold set in .ai-spec.json → "minSpecScore": ${minScore}`));
-            process.exit(1);
-          }
-        }
-      } else {
-        runLogger.stageEnd("spec_assess", { skipped: true });
-        if (!opts.auto) {
-          console.log(chalk.gray("  (Assessment skipped — AI call failed or timed out)"));
-        }
-      }
-    }
-
-    // ── Step 3.5: Approval Gate ───────────────────────────────────────────────
-    if (!opts.auto) {
-      console.log(chalk.blue("\n[3.5/6] Approval Gate — review before code generation"));
-
-      // Show spec stats
-      const specLines = finalSpec.split("\n").length;
-      const specWords = finalSpec.split(/\s+/).length;
-      const taskCountHint = initialTasks.length > 0 ? `  Tasks generated : ${initialTasks.length}` : "";
-      console.log(chalk.gray(`  Spec length     : ${specLines} lines / ${specWords} words`));
-      if (taskCountHint) console.log(chalk.gray(taskCountHint));
-
-      // Show diff vs previous version if one exists
-      const previewSpecsDir = path.join(currentDir, "specs");
-      const slug = featureSlug;
-      const prevVersion = await findLatestVersion(previewSpecsDir, slug);
-      if (prevVersion) {
-        console.log(chalk.gray(`  Previous version: v${prevVersion.version} (${prevVersion.filePath})`));
-        const diff = computeDiff(prevVersion.content, finalSpec);
-        console.log(chalk.cyan("\n  ── Changes vs previous version ──────────────"));
-        printDiffSummary(diff, `v${prevVersion.version} → v${prevVersion.version + 1}`);
-        printDiff(diff);
-        console.log(chalk.cyan("  ────────────────────────────────────────────"));
-      }
-
-      const gate = await select({
-        message: "Ready to proceed to code generation?",
-        choices: [
-          { name: "✅  Proceed — start code generation", value: "proceed" },
-          { name: "📋  View full spec", value: "view" },
-          { name: "❌  Abort", value: "abort" },
-        ],
-      });
-
-      if (gate === "view") {
-        console.log(chalk.cyan("\n" + "─".repeat(52)));
-        console.log(finalSpec);
-        console.log(chalk.cyan("─".repeat(52) + "\n"));
-
-        const confirm2 = await select({
-          message: "Proceed to code generation?",
-          choices: [
-            { name: "✅  Proceed", value: "proceed" },
-            { name: "❌  Abort", value: "abort" },
-          ],
-        });
-        if (confirm2 === "abort") {
-          console.log(chalk.yellow("  Aborted. Spec was NOT saved."));
-          process.exit(0);
-        }
-      } else if (gate === "abort") {
-        console.log(chalk.yellow("  Aborted. Spec was NOT saved."));
-        process.exit(0);
-      }
-
-      console.log(chalk.green("  ✔ Approved — continuing to code generation."));
-    } else {
-      console.log(chalk.gray("[3.5/6] Approval Gate: skipped (--auto)."));
-    }
-
-    // ── Step 3.8: DSL Extraction + Validation ─────────────────────────────────
-    // Runs after approval, before worktree, so the DSL is saved alongside the spec.
-    // We extract from finalSpec (already approved). The DSL file is saved in Step 5.
-    let extractedDsl: import("../core/dsl-types").SpecDSL | null = null;
-
-    if (opts.skipDsl) {
-      console.log(chalk.gray("\n[DSL] Skipped (--skip-dsl)."));
-    } else {
-      console.log(chalk.blue("\n[DSL] Extracting structured DSL from spec..."));
-      console.log(chalk.gray(`  Provider: ${specProviderName}/${specModelName}`));
-      runLogger.stageStart("dsl_extract");
-      try {
-        const isFrontend = isFrontendDeps(context.dependencies);
-        if (isFrontend) console.log(chalk.gray("  Frontend project detected — using ComponentSpec extractor"));
-        const dslExtractor = new DslExtractor(specProvider);
-        extractedDsl = await dslExtractor.extract(finalSpec, { auto: opts.auto, isFrontend });
-        if (extractedDsl) {
-          runLogger.stageEnd("dsl_extract", { endpoints: extractedDsl.endpoints?.length ?? 0, models: extractedDsl.models?.length ?? 0 });
-          console.log(chalk.green("  ✔ DSL extracted and validated."));
-        } else {
-          runLogger.stageEnd("dsl_extract", { skipped: true });
-          console.log(chalk.yellow("  ⚠ DSL skipped — codegen will use Spec + Tasks only."));
-        }
-      } catch (err) {
-        // Unexpected error (not user abort — that would have called process.exit)
-        runLogger.stageFail("dsl_extract", (err as Error).message);
-        console.log(chalk.yellow(`  ⚠ DSL extraction error: ${(err as Error).message} — continuing without DSL.`));
-      }
-    }
-
-    // ── Loop 1: DSL Gap Feedback ──────────────────────────────────────────────
-    // Runs only in interactive mode (not --auto / --fast / --skip-dsl).
-    // Checks for common completeness gaps in the freshly-extracted DSL and
-    // offers a targeted spec refinement AI call to fill them before codegen.
-    // Zero extra AI calls unless the user explicitly opts in.
-    if (extractedDsl && !opts.auto && !opts.fast && !opts.skipDsl) {
-      const dslGaps = assessDslRichness(extractedDsl);
-
-      if (dslGaps.length > 0) {
-        printDslGaps(dslGaps);
-        runLogger.stageStart("dsl_gap_feedback", { gapCount: dslGaps.length, gaps: dslGaps.map((g) => g.code) });
-
-        const refineChoice = await select({
-          message: "How would you like to proceed?",
-          choices: [
-            { name: "🔧  Refine spec (AI fills the gaps, then re-extract DSL)", value: "refine" },
-            { name: "⏭   Skip — proceed with the current DSL", value: "skip" },
-          ],
-        });
-
-        if (refineChoice === "refine") {
-          console.log(chalk.blue("  Refining spec to fill DSL gaps..."));
-          try {
-            const refinedSpec = await specProvider.generate(
-              buildDslGapRefinementPrompt(finalSpec, dslGaps),
-              "You are a Senior Tech Lead doing a targeted spec revision. Output only the complete revised Markdown spec."
-            );
-            finalSpec = refinedSpec;
-            console.log(chalk.green("  ✔ Spec refined."));
-
-            // Re-extract DSL from the improved spec
-            console.log(chalk.blue("  Re-extracting DSL from refined spec..."));
-            const isFrontend2 = isFrontendDeps(context.dependencies);
-            const reExtractor = new DslExtractor(specProvider);
-            const reExtractedDsl = await reExtractor.extract(finalSpec, { auto: true, isFrontend: isFrontend2 });
-            if (reExtractedDsl) {
-              extractedDsl = reExtractedDsl;
-              console.log(chalk.green(`  ✔ DSL re-extracted: ${extractedDsl.endpoints.length} endpoint(s), ${extractedDsl.models.length} model(s).`));
-              runLogger.stageEnd("dsl_gap_feedback", { action: "refined", endpoints: extractedDsl.endpoints.length, models: extractedDsl.models.length });
-            } else {
-              console.log(chalk.yellow("  ⚠ Re-extraction failed — keeping original DSL."));
-              runLogger.stageEnd("dsl_gap_feedback", { action: "refined_but_reextract_failed" });
-            }
-          } catch (err) {
-            console.log(chalk.yellow(`  ⚠ Spec refinement failed: ${(err as Error).message} — keeping original DSL.`));
-            runLogger.stageEnd("dsl_gap_feedback", { action: "refinement_error", error: (err as Error).message });
-          }
-        } else {
-          runLogger.stageEnd("dsl_gap_feedback", { action: "skipped" });
-          console.log(chalk.gray("  Continuing with current DSL."));
-        }
-      }
-    }
-
-    // ── Step 4: Git Worktree ──────────────────────────────────────────────────
-    // Frontend projects (React / Vue / Next / React-Native) work directly on a
-    // feature branch — no worktree needed. node_modules is not copied into
-    // worktrees by default, so running the dev server would break.
-    // Auto-skip unless the user explicitly passes --worktree.
-    const isFrontendProject = isFrontendDeps(context.dependencies ?? []);
-    const skipWorktree = opts.worktree
-      ? false
-      : opts.skipWorktree || isFrontendProject;
-
-    let workingDir = currentDir;
-    if (!skipWorktree) {
-      console.log(chalk.blue("\n[4/6] Setting up git worktree..."));
-      const worktreeManager = new GitWorktreeManager(currentDir);
-      const worktreePath = await worktreeManager.createWorktree(idea);
-      if (worktreePath) workingDir = worktreePath;
-    } else {
-      const reason = opts.worktree
-        ? ""
-        : isFrontendProject
-        ? " (frontend project — use --worktree to override)"
-        : " (--skip-worktree)";
-      console.log(chalk.gray(`[4/6] Skipping worktree${reason}.`));
-    }
-
-    // ── Step 5: Save Spec (versioned) + Generate Tasks ────────────────────────
-    const specsDir = path.join(workingDir, "specs");
-    await fs.ensureDir(specsDir);
-
-    const { filePath: specFile, version: specVersion } = await nextVersionPath(specsDir, featureSlug);
-    await fs.writeFile(specFile, finalSpec, "utf-8");
-    console.log(chalk.green(`\n[5/6] ✔ Spec saved: ${specFile}`) + chalk.gray(` (v${specVersion})`));
-
-    // Save DSL alongside the spec if extraction succeeded
-    let savedDslFile: string | null = null;
-    if (extractedDsl) {
-      const dslExtractor = new DslExtractor(specProvider);
-      savedDslFile = await dslExtractor.saveDsl(extractedDsl, specFile);
-      console.log(chalk.green(`  ✔ DSL saved : ${savedDslFile}`));
-    }
-
-    if (!opts.skipTasks) {
-      const taskGen = new TaskGenerator(specProvider);
-      let tasksToSave = initialTasks;
-
-      // If combined call didn't produce tasks (parse failed), retry as a separate call
-      if (tasksToSave.length === 0) {
-        console.log(chalk.blue(`\n  Generating tasks (separate call)...`));
-        try {
-          tasksToSave = await taskGen.generateTasks(finalSpec, context);
-        } catch (err) {
-          console.log(chalk.yellow(`  ⚠ Task generation failed: ${(err as Error).message}`));
-        }
-      }
-
-      if (tasksToSave.length > 0) {
-        const sorted = taskGen.sortByLayer(tasksToSave);
-        const tasksFile = await taskGen.saveTasks(sorted, specFile);
-        printTasks(sorted);
-        console.log(chalk.green(`  ✔ Tasks saved: ${tasksFile}`));
-      } else {
-        console.log(chalk.yellow("  ⚠ No tasks generated — code generation will use fallback file planning."));
-      }
-    }
-
-    // ── Step 6: Code Generation ───────────────────────────────────────────────
-    console.log(chalk.blue(`\n[6/6] Code generation (mode: ${codegenMode})...`));
-    const codegenProvider =
-      codegenProviderName === specProviderName && codegenApiKey === specApiKey
-        ? specProvider
-        : createProvider(codegenProviderName, codegenApiKey, codegenModelName);
-
-    // ── TDD: generate failing tests BEFORE implementation ────────────────────
-    let generatedTestFiles: string[] = [];
-    if (opts.tdd && extractedDsl) {
-      console.log(chalk.cyan("\n[TDD] Generating pre-implementation tests (will fail until code is written)..."));
-      const testGen = new TestGenerator(codegenProvider);
-      generatedTestFiles = await testGen.generateTdd(extractedDsl, workingDir);
-    }
-
-    runLogger.stageStart("codegen", { mode: codegenMode, provider: codegenProviderName, model: codegenModelName });
-    const codegen = new CodeGenerator(codegenProvider, codegenMode);
-    const generatedFiles = await codegen.generateCode(specFile, workingDir, context, {
-      auto: opts.auto,
-      resume: opts.resume,
-      dslFilePath: savedDslFile ?? undefined,
-      repoType: detectedRepoType,
-    });
-    runLogger.stageEnd("codegen", { filesGenerated: generatedFiles.length });
-
-    // ── Step 7: Test Skeleton Generation (skipped in TDD mode — tests already written) ──
-    if (opts.tdd) {
-      console.log(chalk.gray("\n[7/9] TDD mode — test files already written pre-implementation."));
-    } else if (opts.skipTests) {
-      console.log(chalk.gray("\n[7/9] Skipping test generation (--skip-tests)."));
-    } else if (!extractedDsl) {
-      console.log(chalk.gray("\n[7/9] Skipping test generation (no DSL available)."));
-    } else {
-      console.log(chalk.blue(`\n[7/9] Test skeleton generation...`));
-      runLogger.stageStart("test_gen");
-      const testGen = new TestGenerator(codegenProvider);
-      generatedTestFiles = await testGen.generate(extractedDsl, workingDir);
-      runLogger.stageEnd("test_gen", { filesGenerated: generatedTestFiles.length });
-    }
-
-    // ── Step 8: Error Feedback Loop ───────────────────────────────────────────
-    // In TDD mode, the error feedback loop is the primary driver:
-    // it runs tests, collects failures, and fixes implementation until tests pass.
-    let compilePassed = false;
-    if (opts.skipErrorFeedback) {
-      console.log(chalk.gray("[8/9] Skipping error feedback (--skip-error-feedback)."));
-      compilePassed = true; // treat skip as neutral pass for self-eval
-    } else {
-      if (opts.tdd) {
-        console.log(chalk.cyan("[8/9] TDD mode — error feedback loop driving implementation to pass tests..."));
-      }
-      runLogger.stageStart("error_feedback");
-      compilePassed = await runErrorFeedback(codegenProvider, workingDir, extractedDsl, {
-        maxCycles: opts.tdd ? 3 : 2,  // TDD gets one extra cycle
-      });
-      runLogger.stageEnd("error_feedback");
-    }
-
-    // ── Step 9: Code Review ───────────────────────────────────────────────────
-    let reviewResult = "";
-    if (!opts.skipReview) {
-      console.log(chalk.blue("\n[9/9] Automated code review (3-pass: architecture + implementation + impact/complexity)..."));
-      runLogger.stageStart("review");
-      const reviewer = new CodeReviewer(specProvider, currentDir);
-      const savedSpec = await fs.readFile(specFile, "utf-8");
-
-      if (codegenMode === "api" && generatedFiles.length > 0) {
-        // api mode: review the generated files directly (no git diff available)
-        reviewResult = await reviewer.reviewFiles(savedSpec, generatedFiles, workingDir, specFile);
-      } else {
-        // claude-code / plan mode: review via git diff
-        const originalDir = process.cwd();
-        try {
-          process.chdir(workingDir);
-          reviewResult = await reviewer.reviewCode(savedSpec, specFile);
-        } finally {
-          process.chdir(originalDir);
-        }
-      }
-      runLogger.stageEnd("review");
-
-      // Knowledge Memory: extract lessons from review and append to constitution §9
-      await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
-    }
-
-    // ── Loop 2: Review → DSL Structural Feedback ─────────────────────────────
-    // Runs only in interactive mode when a review was produced.
-    // Classifies Pass 1 (architecture) findings as design-level vs implementation-
-    // level issues. Design issues belong in the Spec/DSL — not just in §9.
-    // If found: offer to amend the spec → re-extract DSL → overwrite saved DSL file.
-    // The user can then run `ai-spec update --codegen` to regenerate affected files.
-    if (reviewResult && !opts.skipReview && !opts.auto && extractedDsl && savedDslFile) {
-      const structuralFindings = extractStructuralFindings(reviewResult);
-
-      if (structuralFindings.length > 0) {
-        printStructuralFindings(structuralFindings);
-        runLogger.stageStart("review_dsl_feedback", { findingCount: structuralFindings.length, categories: structuralFindings.map((f) => f.category) });
-
-        const savedSpecContent = await fs.readFile(specFile, "utf-8");
-
-        const patchChoice = await select({
-          message: "These are design issues in the Spec/DSL. How would you like to handle them?",
-          choices: [
-            { name: "🔧  Amend spec + update DSL (AI fixes the design issues, no regen yet)", value: "amend" },
-            { name: "📝  Note in §9 only (already done — no DSL change)", value: "note" },
-            { name: "⏭   Skip", value: "skip" },
-          ],
-        });
-
-        if (patchChoice === "amend") {
-          console.log(chalk.blue("  Amending spec to address structural findings..."));
-          try {
-            const amendedSpec = await specProvider.generate(
-              buildStructuralAmendmentPrompt(savedSpecContent, structuralFindings),
-              "You are a Senior Tech Lead doing a targeted spec correction. Output only the complete revised Markdown spec."
-            );
-
-            // Snapshot spec + DSL before overwriting so `ai-spec restore <runId>` works
-            await runSnapshot.snapshotFile(specFile);
-            if (savedDslFile) await runSnapshot.snapshotFile(savedDslFile);
-
-            // Overwrite the saved spec file with the amendment
-            await fs.writeFile(specFile, amendedSpec, "utf-8");
-            console.log(chalk.green(`  ✔ Spec updated: ${specFile}`));
-
-            // Re-extract DSL from the amended spec
-            console.log(chalk.blue("  Re-extracting DSL from amended spec..."));
-            const isFrontend3 = isFrontendDeps(context.dependencies);
-            const amendExtractor = new DslExtractor(specProvider);
-            const amendedDsl = await amendExtractor.extract(amendedSpec, { auto: true, isFrontend: isFrontend3 });
-            if (amendedDsl) {
-              // Overwrite saved DSL file
-              const dslWriter = new DslExtractor(specProvider);
-              const newDslPath = await dslWriter.saveDsl(amendedDsl, specFile);
-              extractedDsl = amendedDsl;
-              console.log(chalk.green(`  ✔ DSL updated: ${newDslPath}`));
-              console.log(chalk.cyan(
-                `\n  Next step: run ${chalk.white("ai-spec update --codegen")} to regenerate files affected by the DSL change.`
-              ));
-              runLogger.stageEnd("review_dsl_feedback", {
-                action: "amended",
-                endpoints: amendedDsl.endpoints.length,
-                models: amendedDsl.models.length,
-              });
-            } else {
-              console.log(chalk.yellow("  ⚠ DSL re-extraction failed — spec was updated but DSL file unchanged."));
-              runLogger.stageEnd("review_dsl_feedback", { action: "amended_spec_only" });
-            }
-          } catch (err) {
-            console.log(chalk.yellow(`  ⚠ Spec amendment failed: ${(err as Error).message}`));
-            runLogger.stageEnd("review_dsl_feedback", { action: "amendment_error", error: (err as Error).message });
-          }
-        } else {
-          runLogger.stageEnd("review_dsl_feedback", { action: patchChoice });
-          if (patchChoice === "note") {
-            console.log(chalk.gray("  Structural findings retained in §9. DSL unchanged."));
-          }
-        }
-      }
-    }
-
-    // ── Step 10: Harness Self-Evaluation ──────────────────────────────────────
-    // Zero AI calls — deterministic scoring from file-system state + review text.
-    // Records harnessScore + promptHash in RunLog for cross-run trend analysis.
-    runLogger.stageStart("self_eval");
-    const selfEvalResult = runSelfEval({
-      dsl: extractedDsl,
-      generatedFiles,
-      compilePassed,
-      reviewText: reviewResult,
-      promptHash,
-      logger: runLogger,
-    });
-    printSelfEval(selfEvalResult);
-
-    // ── Done ──────────────────────────────────────────────────────────────────
-    runLogger.finish();
-    console.log(chalk.bold.green("\n✔ All done!"));
-    console.log(chalk.gray(`  Spec        : ${specFile}`));
-    if (savedDslFile) console.log(chalk.gray(`  DSL         : ${savedDslFile}`));
-    if (generatedTestFiles.length > 0) {
-      console.log(chalk.gray(`  Tests       : ${generatedTestFiles.length} skeleton file(s) generated`));
-    }
-    console.log(chalk.gray(`  Working dir : ${workingDir}`));
-    if (workingDir !== currentDir) {
-      console.log(chalk.gray(`  Run \`cd ${workingDir}\` to enter the worktree.`));
-    }
-    runLogger.printSummary();
-    if (runSnapshot.fileCount > 0) {
-      console.log(chalk.gray(`  To undo changes: ai-spec restore ${runId}`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: review
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("review")
-  .description("Run AI code review on current git diff against a spec")
-  .argument("[specFile]", "Path to spec file (auto-detects latest in specs/ if omitted)")
-  .option(
-    "--provider <name>",
-    `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
-    undefined
-  )
-  .option("--model <name>", "Model name")
-  .option("-k, --key <apiKey>", "API key")
-  .action(async (specFile: string | undefined, opts) => {
-    const currentDir = process.cwd();
-    const config = await loadConfig(currentDir);
-
-    const providerName = opts.provider || config.provider || "gemini";
-    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
-    const apiKey = await resolveApiKey(providerName, opts.key);
-
-    const provider = createProvider(providerName, apiKey, modelName);
-    const reviewer = new CodeReviewer(provider, currentDir);
-
-    let specContent = "";
-    let resolvedSpecFile: string | undefined;
-
-    if (specFile && (await fs.pathExists(specFile))) {
-      specContent = await fs.readFile(specFile, "utf-8");
-      resolvedSpecFile = specFile;
-      console.log(chalk.gray(`Using spec: ${specFile}`));
-    } else {
-      // Auto-detect the latest spec in specs/
-      const specsDir = path.join(currentDir, "specs");
-      if (await fs.pathExists(specsDir)) {
-        const files = (await fs.readdir(specsDir))
-          .filter((f) => f.endsWith(".md"))
-          .sort()
-          .reverse();
-        if (files.length > 0) {
-          const latest = path.join(specsDir, files[0]);
-          specContent = await fs.readFile(latest, "utf-8");
-          resolvedSpecFile = latest;
-          console.log(chalk.gray(`Auto-detected spec: specs/${files[0]}`));
-        }
-      }
-    }
-
-    if (!specContent) {
-      console.log(chalk.yellow("No spec file found. Running review without spec context."));
-    }
-
-    await reviewer.reviewCode(specContent, resolvedSpecFile);
-    await reviewer.printScoreTrend();
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: init  —  generate Project Constitution
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("init")
-  .description(`Analyze codebase and generate Project Constitution (${CONSTITUTION_FILE})`)
-  .option(
-    "--provider <name>",
-    `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
-    undefined
-  )
-  .option("--model <name>", "Model name")
-  .option("-k, --key <apiKey>", "API key")
-  .option("--force", "Overwrite existing constitution")
-  .option(
-    "--global",
-    `Generate a Global Constitution (~/${GLOBAL_CONSTITUTION_FILE}) instead of a project-level one`
-  )
-  .option("--consolidate", "Consolidate §9 accumulated lessons into §1–§8 core rules (prune & rebase)")
-  .option("--dry-run", "Preview consolidation result without writing (use with --consolidate)")
-  .action(async (opts) => {
-    const currentDir = process.cwd();
-    const config = await loadConfig(currentDir);
-
-    const providerName = opts.provider || config.provider || "gemini";
-    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
-    const apiKey = await resolveApiKey(providerName, opts.key);
-    const provider = createProvider(providerName, apiKey, modelName);
-
-    // ── Consolidate mode ─────────────────────────────────────────────────
-    if (opts.consolidate) {
-      const consolidator = new ConstitutionConsolidator(provider);
-      try {
-        const result = await consolidator.consolidate(currentDir, {
-          dryRun: opts.dryRun,
-          auto: opts.auto,
-        });
-        if (result.written) {
-          console.log(chalk.blue("\n  Summary:"));
-          console.log(chalk.gray(`  Lines : ${result.before.totalLines} → ${result.after.totalLines} (${result.before.totalLines - result.after.totalLines > 0 ? "-" : "+"}${Math.abs(result.before.totalLines - result.after.totalLines)})`));
-          console.log(chalk.gray(`  §9    : ${result.before.lessonCount} → ${result.after.lessonCount} lessons remaining`));
-          if (result.backupPath) {
-            console.log(chalk.gray(`  Backup: ${path.basename(result.backupPath)}`));
-          }
-        }
-      } catch (err) {
-        console.error(chalk.red(`  ✘ Consolidation failed: ${(err as Error).message}`));
-        process.exit(1);
-      }
-      return;
-    }
-
-    // ── Global constitution mode ──────────────────────────────────────────
-    if (opts.global) {
-      const existing = await loadGlobalConstitution([currentDir]);
-      if (existing && !opts.force) {
-        console.log(chalk.yellow(`\n  Global constitution already exists at: ${existing.source}`));
-        console.log(chalk.gray("  Use --force to overwrite it."));
-        return;
-      }
-
-      console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
-      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-      console.log(chalk.gray("  Scanning repos in workspace..."));
-
-      // Build per-repo summaries from sibling directories
-      const loader = new ContextLoader(currentDir);
-      const ctx = await loader.loadProjectContext();
-      const summary = [
-        `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
-        `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
-      ].join("\n");
-
-      const prompt = buildGlobalConstitutionPrompt([{ name: path.basename(currentDir), summary }]);
-      let globalConstitution: string;
-      try {
-        globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);
-      } catch (err) {
-        console.error(chalk.red("  ✘ Failed to generate global constitution:"), err);
-        process.exit(1);
-      }
-
-      const saved = await saveGlobalConstitution(globalConstitution, currentDir);
-      console.log(chalk.green(`\n  ✔ Global constitution saved: ${saved}`));
-      console.log(chalk.gray("  This will be automatically merged into all project constitutions in this workspace."));
-      console.log(chalk.gray("  Project-level rules always override global rules.\n"));
-      console.log(chalk.bold("  Preview:"));
-      console.log(chalk.gray(globalConstitution.split("\n").slice(0, 12).join("\n")));
-      if (globalConstitution.split("\n").length > 12) {
-        console.log(chalk.gray(`  ... (${globalConstitution.split("\n").length} lines total)`));
-      }
-      return;
-    }
-
-    // ── Project constitution mode (default) ───────────────────────────────
-    const constitutionPath = path.join(currentDir, CONSTITUTION_FILE);
-
-    if (!opts.force && (await fs.pathExists(constitutionPath))) {
-      console.log(chalk.yellow(`\n  ${CONSTITUTION_FILE} already exists.`));
-      console.log(chalk.gray("  Use --force to overwrite it."));
-      console.log(chalk.gray(`  Or edit it directly: ${constitutionPath}`));
-      return;
-    }
-
-    console.log(chalk.blue("\n─── Generating Project Constitution ─────────────"));
-    console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-    console.log(chalk.gray("  Analyzing codebase..."));
-
-    const generator = new ConstitutionGenerator(provider);
-
-    let constitution: string;
-    try {
-      constitution = await generator.generate(currentDir);
-    } catch (err) {
-      console.error(chalk.red("  ✘ Failed to generate constitution:"), err);
-      process.exit(1);
-    }
-
-    const saved = await generator.saveConstitution(currentDir, constitution);
-
-    // Note if a global constitution will also be applied
-    const globalResult = await loadGlobalConstitution([path.dirname(currentDir)]);
-    if (globalResult) {
-      console.log(chalk.cyan(`\n  ℹ Global constitution detected: ${globalResult.source}`));
-      console.log(chalk.gray("    It will be merged with this project constitution at runtime."));
-      console.log(chalk.gray("    Project rules take priority over global rules."));
-    }
-
-    console.log(chalk.green(`\n  ✔ Constitution saved: ${saved}`));
-    console.log(chalk.gray("  This file will be automatically used in all future `ai-spec create` runs."));
-    console.log(chalk.gray("  Edit it to add custom rules or red lines for your project.\n"));
-    console.log(chalk.bold("  Preview:"));
-    console.log(chalk.gray(constitution.split("\n").slice(0, 15).join("\n")));
-    if (constitution.split("\n").length > 15) {
-      console.log(chalk.gray(`  ... (${constitution.split("\n").length} lines total)`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: config
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("config")
-  .description(`Set default configuration for this project (saved to ${CONFIG_FILE})`)
-  .option("--provider <name>", "Default AI provider for spec generation")
-  .option("--model <name>", "Default model for spec generation")
-  .option(
-    "--codegen <mode>",
-    "Default code generation mode (claude-code|api|plan)"
-  )
-  .option("--codegen-provider <name>", "Default provider for code generation")
-  .option("--codegen-model <name>", "Default model for code generation")
-  .option("--min-spec-score <score>", "Minimum overall spec score (1-10) to pass Approval Gate (0 = disabled)")
-  .option("--show", "Print current configuration")
-  .option("--reset", "Reset configuration to empty")
-  .option("--clear-keys", "Delete all saved API keys from ~/.ai-spec-keys.json")
-  .option("--clear-key <provider>", "Delete saved API key for a specific provider")
-  .option("--list-keys", "Show which providers have a saved key")
-  .action(async (opts) => {
-    const currentDir = process.cwd();
-    const configPath = path.join(currentDir, CONFIG_FILE);
-
-    if (opts.clearKeys) {
-      await clearAllKeys();
-      console.log(chalk.green(`✔ All saved API keys cleared.`));
-      return;
-    }
-
-    if (opts.clearKey) {
-      await clearKey(opts.clearKey);
-      console.log(chalk.green(`✔ Saved key for "${opts.clearKey}" removed.`));
-      return;
-    }
-
-    if (opts.listKeys) {
-      const store: Record<string, string> = await fs.readJson(KEY_STORE_FILE).catch(() => ({}));
-      const providers = Object.keys(store);
-      if (providers.length === 0) {
-        console.log(chalk.gray("No saved API keys."));
-      } else {
-        console.log(chalk.bold("Saved API keys:"));
-        for (const p of providers) {
-          const k = store[p];
-          console.log(chalk.gray(`  ${p}: ${k.slice(0, 6)}...${k.slice(-4)}`));
-        }
-        console.log(chalk.gray(`\nFile: ${KEY_STORE_FILE}`));
-      }
-      return;
-    }
-
-    if (opts.reset) {
-      await fs.writeJson(configPath, {}, { spaces: 2 });
-      console.log(chalk.green(`✔ Config reset: ${configPath}`));
-      return;
-    }
-
-    const existing: AiSpecConfig = await loadConfig(currentDir);
-
-    if (opts.show) {
-      if (Object.keys(existing).length === 0) {
-        console.log(chalk.gray("No config file found. Using built-in defaults."));
-      } else {
-        console.log(chalk.bold(`${configPath}:`));
-        console.log(JSON.stringify(existing, null, 2));
-      }
-      return;
-    }
-
-    const updated: AiSpecConfig = { ...existing };
-    if (opts.provider) updated.provider = opts.provider;
-    if (opts.model) updated.model = opts.model;
-    if (opts.codegen) updated.codegen = opts.codegen as CodeGenMode;
-    if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
-    if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
-    if (opts.minSpecScore !== undefined) {
-      const score = parseInt(opts.minSpecScore, 10);
-      if (isNaN(score) || score < 0 || score > 10) {
-        console.error(chalk.red("  --min-spec-score must be a number between 0 and 10"));
-        process.exit(1);
-      }
-      updated.minSpecScore = score;
-    }
-
-    await fs.writeJson(configPath, updated, { spaces: 2 });
-    console.log(chalk.green(`✔ Config saved to ${configPath}`));
-    console.log(JSON.stringify(updated, null, 2));
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: model  —  interactive model switcher
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("model")
-  .description("Interactively switch the active AI provider/model and save to .ai-spec.json")
-  .option("--list", "List all available providers and models")
-  .action(async (opts) => {
-    const currentDir = process.cwd();
-    const configPath = path.join(currentDir, CONFIG_FILE);
-
-    // ── --list: just print the catalog ────────────────────────────────────────
-    if (opts.list) {
-      console.log(chalk.bold("\nAvailable providers & models:\n"));
-      for (const [key, meta] of Object.entries(PROVIDER_CATALOG)) {
-        console.log(
-          `  ${chalk.bold.cyan(key.padEnd(10))} ${chalk.white(meta.displayName)}`
-        );
-        console.log(chalk.gray(`             ${meta.description}`));
-        console.log(
-          chalk.gray(
-            `             env: ${meta.envKey}  |  models: ${meta.models.join(", ")}`
-          )
-        );
-        console.log();
-      }
-      return;
-    }
-
-    const existing: AiSpecConfig = await loadConfig(currentDir);
-
-    console.log(chalk.blue("\n─── Model Switcher ─────────────────────────────"));
-    if (Object.keys(existing).length > 0) {
-      console.log(
-        chalk.gray(
-          `  Current: spec=${existing.provider ?? "gemini"}/${existing.model ?? DEFAULT_MODELS[existing.provider ?? "gemini"]}` +
-            (existing.codegenProvider
-              ? `  codegen=${existing.codegenProvider}/${existing.codegenModel ?? ""}`
-              : "")
-        )
-      );
-    }
-    console.log();
-
-    // ── What to configure ─────────────────────────────────────────────────────
-    const target = await select({
-      message: "Configure model for:",
-      choices: [
-        { name: "Spec generation  (used for spec writing & refinement)", value: "spec" },
-        { name: "Code generation  (used when --codegen api is active)", value: "codegen" },
-        { name: "Both             (same provider/model for all tasks)", value: "both" },
-      ],
-    });
-
-    // ── Helper: pick provider + model ─────────────────────────────────────────
-    async function pickProviderAndModel(label: string): Promise<{ provider: string; model: string }> {
-      const providerKey = await select({
-        message: `${label} — select provider:`,
-        choices: Object.entries(PROVIDER_CATALOG).map(([key, meta]) => ({
-          name: `${meta.displayName.padEnd(22)} ${chalk.gray(meta.description)}`,
-          value: key,
-          short: meta.displayName,
-        })),
-      });
-
-      const meta = PROVIDER_CATALOG[providerKey];
-      const modelChoices = [
-        ...meta.models.map((m) => ({ name: m, value: m })),
-        { name: chalk.italic("✎  Enter custom model name..."), value: "__custom__" },
-      ];
-
-      let chosenModel = await select({
-        message: `${label} — select model (${meta.displayName}):`,
-        choices: modelChoices,
-      });
-
-      if (chosenModel === "__custom__") {
-        chosenModel = await input({
-          message: "Enter model name:",
-          validate: (v) => v.trim().length > 0 || "Model name cannot be empty",
-        });
-      }
-
-      return { provider: providerKey, model: chosenModel };
-    }
-
-    // ── Run picker(s) ─────────────────────────────────────────────────────────
-    const updated: AiSpecConfig = { ...existing };
-
-    if (target === "spec" || target === "both") {
-      const { provider, model } = await pickProviderAndModel("Spec");
-      updated.provider = provider;
-      updated.model = model;
-    }
-
-    if (target === "codegen" || target === "both") {
-      if (target === "both") {
-        updated.codegenProvider = updated.provider;
-        updated.codegenModel = updated.model;
-      } else {
-        const { provider, model } = await pickProviderAndModel("Codegen");
-        updated.codegenProvider = provider;
-        updated.codegenModel = model;
-      }
-
-      // claude-code 模式只支持 Claude provider。
-      // 如果选了非 claude provider，自动把 codegen 模式改为 api。
-      const effectiveCodegenProvider = updated.codegenProvider ?? updated.provider ?? "gemini";
-      if (effectiveCodegenProvider !== "claude") {
-        if (!updated.codegen || updated.codegen === "claude-code") {
-          updated.codegen = "api";
-          console.log(
-            chalk.yellow(
-              `\n  ⚠  provider "${effectiveCodegenProvider}" 不支持 "claude-code" 模式。`
-            )
-          );
-          console.log(chalk.gray(`  已自动将 codegen 模式设为 "api"。`));
-        }
-      }
-    }
-
-    // ── Confirm & save ────────────────────────────────────────────────────────
-    console.log(chalk.blue("\n  Preview:"));
-    console.log(chalk.gray(`    spec    → ${updated.provider}/${updated.model}`));
-    if (updated.codegenProvider) {
-      console.log(
-        chalk.gray(
-          `    codegen → ${updated.codegenProvider}/${updated.codegenModel}  (mode: ${updated.codegen ?? "claude-code"})`
-        )
-      );
-    }
-
-    const ok = await confirm({ message: "Save to .ai-spec.json?", default: true });
-    if (!ok) {
-      console.log(chalk.gray("  Cancelled."));
-      return;
-    }
-
-    await fs.writeJson(configPath, updated, { spaces: 2 });
-    console.log(chalk.green(`\n  ✔ Saved to ${configPath}`));
-
-    // Remind about env var if not set
-    const providerToCheck = updated.provider ?? "gemini";
-    const envKey = ENV_KEY_MAP[providerToCheck];
-    if (envKey && !process.env[envKey]) {
-      console.log(
-        chalk.yellow(
-          `  ⚠  Remember to set ${envKey} in your environment or .env file.`
-        )
-      );
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Multi-Repo Pipeline
-// ═══════════════════════════════════════════════════════════════════════════════
-
-/**
- * Run a single repo through the full spec→dsl→worktree→codegen→tests→review pipeline.
- * Returns the extracted DSL (or null) for contract bridging.
- */
-async function runSingleRepoPipelineInWorkspace(opts: {
-  idea: string;
-  specProvider: ReturnType<typeof createProvider>;
-  specProviderName: string;
-  specModelName: string;
-  codegenProvider: ReturnType<typeof createProvider>;
-  codegenMode: CodeGenMode;
-  repoAbsPath: string;
-  repoName: string;
-  cliOpts: Record<string, unknown>;
-  contractContextSection?: string;
-}): Promise<{ dsl: SpecDSL | null; specFile: string | null }> {
-  const {
-    idea,
-    specProvider,
-    specProviderName,
-    specModelName,
-    codegenProvider,
-    codegenMode,
-    repoAbsPath,
-    repoName,
-    cliOpts,
-    contractContextSection,
-  } = opts;
-
-  console.log(chalk.blue(`\n  [${repoName}] Loading project context...`));
-  const loader = new ContextLoader(repoAbsPath);
-  let context = await loader.loadProjectContext();
-
-  // Detect repo language so the correct codegen system prompt is used
-  const { type: detectedRepoType } = await detectRepoType(repoAbsPath);
-
-  console.log(chalk.gray(`    Tech stack: ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
-  console.log(chalk.gray(`    Dependencies: ${context.dependencies.length} packages`));
-  if (context.constitution && context.constitution.length > 6000) {
-    console.log(chalk.yellow(`    ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
-  }
-
-  if (!context.constitution) {
-    console.log(chalk.yellow(`    Constitution: not found — auto-generating...`));
-    try {
-      const constitutionGen = new ConstitutionGenerator(specProvider);
-      const constitutionContent = await constitutionGen.generate(repoAbsPath);
-      await constitutionGen.saveConstitution(repoAbsPath, constitutionContent);
-      context.constitution = constitutionContent;
-      console.log(chalk.green(`    Constitution: generated`));
-    } catch (err) {
-      console.log(chalk.yellow(`    Constitution: auto-generation failed (${(err as Error).message}), continuing.`));
-    }
-  } else {
-    console.log(chalk.green(`    Constitution: found`));
-  }
-
-  // Build the spec idea: inject contract context if available
-  let fullIdea = idea;
-  if (contractContextSection) {
-    fullIdea = `${idea}\n\n${contractContextSection}`;
-  }
-
-  console.log(chalk.blue(`  [${repoName}] Generating spec...`));
-  let finalSpec: string;
-  try {
-    const result = await generateSpecWithTasks(specProvider, fullIdea, context);
-    finalSpec = result.spec;
-    console.log(chalk.green(`    Spec generated.`));
-  } catch (err) {
-    console.error(chalk.red(`    Spec generation failed: ${(err as Error).message}`));
-    return { dsl: null, specFile: null };
-  }
-
-  // DSL Extraction
-  let extractedDsl: SpecDSL | null = null;
-  if (!cliOpts.skipDsl) {
-    console.log(chalk.blue(`  [${repoName}] Extracting DSL...`));
-    try {
-      const dslExtractor = new DslExtractor(specProvider);
-      const repoIsFrontend = isFrontendDeps(context.dependencies);
-      extractedDsl = await dslExtractor.extract(finalSpec, { auto: true, isFrontend: repoIsFrontend });
-      if (extractedDsl) {
-        console.log(chalk.green(`    DSL extracted.`));
-      }
-    } catch (err) {
-      console.log(chalk.yellow(`    DSL extraction failed: ${(err as Error).message}`));
-    }
-  }
-
-  // Git Worktree — auto-skip for frontend repos
-  const isFrontendRepo = isFrontendDeps(context.dependencies ?? []);
-  const skipWorktreeForRepo = cliOpts.worktree
-    ? false
-    : cliOpts.skipWorktree || isFrontendRepo;
-
-  let workingDir = repoAbsPath;
-  if (!skipWorktreeForRepo) {
-    console.log(chalk.blue(`  [${repoName}] Setting up git worktree...`));
-    try {
-      const worktreeManager = new GitWorktreeManager(repoAbsPath);
-      const worktreePath = await worktreeManager.createWorktree(idea);
-      if (worktreePath) workingDir = worktreePath;
-    } catch (err) {
-      console.log(chalk.yellow(`    Worktree setup failed: ${(err as Error).message}. Using main branch.`));
-    }
-  } else {
-    console.log(chalk.gray(`  [${repoName}] Skipping worktree${isFrontendRepo ? " (frontend repo)" : ""}.`));
-  }
-
-  // Save Spec
-  const specsDir = path.join(workingDir, "specs");
-  await fs.ensureDir(specsDir);
-  const featureSlug = slugify(idea);
-  const { filePath: specFile } = await nextVersionPath(specsDir, featureSlug);
-  await fs.writeFile(specFile, finalSpec, "utf-8");
-  console.log(chalk.green(`    Spec saved: ${path.relative(repoAbsPath, specFile)}`));
-
-  let savedDslFile: string | null = null;
-  if (extractedDsl) {
-    const dslExtractorForSave = new DslExtractor(specProvider);
-    savedDslFile = await dslExtractorForSave.saveDsl(extractedDsl, specFile);
-    console.log(chalk.green(`    DSL saved: ${path.relative(repoAbsPath, savedDslFile)}`));
-  }
-
-  // Code Generation
-  console.log(chalk.blue(`  [${repoName}] Running code generation (mode: ${codegenMode})...`));
-  try {
-    const codegen = new CodeGenerator(codegenProvider, codegenMode);
-    await codegen.generateCode(specFile, workingDir, context, {
-      auto: true,
-      dslFilePath: savedDslFile ?? undefined,
-      repoType: detectedRepoType,
-    });
-    console.log(chalk.green(`    Code generation complete.`));
-  } catch (err) {
-    console.log(chalk.yellow(`    Code generation failed: ${(err as Error).message}`));
-  }
-
-  // Test Generation
-  if (!cliOpts.skipTests && extractedDsl) {
-    console.log(chalk.blue(`  [${repoName}] Generating test skeletons...`));
-    try {
-      const testGen = new TestGenerator(codegenProvider);
-      const testFiles = await testGen.generate(extractedDsl, workingDir);
-      console.log(chalk.green(`    ${testFiles.length} test file(s) generated.`));
-    } catch (err) {
-      console.log(chalk.yellow(`    Test generation failed: ${(err as Error).message}`));
-    }
-  }
-
-  // Error Feedback
-  if (!cliOpts.skipErrorFeedback) {
-    try {
-      await runErrorFeedback(codegenProvider, workingDir, extractedDsl, { maxCycles: 1 });
-    } catch (err) {
-      console.log(chalk.yellow(`    Error feedback failed: ${(err as Error).message}`));
-    }
-  }
-
-  // Code Review
-  if (!cliOpts.skipReview) {
-    console.log(chalk.blue(`  [${repoName}] Running code review...`));
-    try {
-      const reviewer = new CodeReviewer(specProvider);
-      // git diff must run in the repo's working directory (may be a worktree),
-      // not in wherever the CLI was invoked from.
-      const originalDir = process.cwd();
-      let reviewResult: string;
-      try {
-        process.chdir(workingDir);
-        reviewResult = await reviewer.reviewCode(finalSpec);
-      } finally {
-        process.chdir(originalDir);
-      }
-      await accumulateReviewKnowledge(specProvider, repoAbsPath, reviewResult);
-      console.log(chalk.green(`    Code review complete.`));
-    } catch (err) {
-      console.log(chalk.yellow(`    Code review failed: ${(err as Error).message}`));
-    }
-  }
-
-  return { dsl: extractedDsl, specFile };
-}
-
-/**
- * Multi-repo pipeline: decompose → order repos → run each repo in order → bridge contracts.
- */
-type MultiRepoResult = {
-  repoName: string;
-  status: "success" | "failed" | "skipped";
-  specFile: string | null;
-  dsl: SpecDSL | null;
-  repoAbsPath: string;
-  role: string;
-};
-
-async function runMultiRepoPipeline(
-  idea: string,
-  workspace: WorkspaceConfig,
-  opts: Record<string, unknown>,
-  currentDir: string,
-  config: AiSpecConfig
-): Promise<MultiRepoResult[]> {
-  // ── Resolve providers ──────────────────────────────────────────────────────
-  const specProviderName = (opts.provider as string) || config.provider || "gemini";
-  const specModelName = (opts.model as string) || config.model || DEFAULT_MODELS[specProviderName];
-  const specApiKey = await resolveApiKey(specProviderName, opts.key as string | undefined);
-  const specProvider = createProvider(specProviderName, specApiKey, specModelName);
-
-  const codegenMode: CodeGenMode = ((opts.codegen as string) as CodeGenMode) || config.codegen || "claude-code";
-  const codegenProviderName = (opts.codegenProvider as string) || config.codegenProvider || specProviderName;
-  const codegenModelName = (opts.codegenModel as string) || config.codegenModel || DEFAULT_MODELS[codegenProviderName];
-  const codegenApiKey =
-    codegenProviderName === specProviderName
-      ? specApiKey
-      : await resolveApiKey(codegenProviderName, opts.codegenKey as string | undefined);
-  const codegenProvider =
-    codegenProviderName === specProviderName && codegenApiKey === specApiKey
-      ? specProvider
-      : createProvider(codegenProviderName, codegenApiKey, codegenModelName);
-
-  printBanner({
-    specProvider: specProviderName,
-    specModel: specModelName,
-    codegenMode,
-    codegenProvider: codegenProviderName,
-    codegenModel: codegenModelName,
-  });
-
-  const workspaceLoader = new WorkspaceLoader(currentDir);
-
-  // ── Step 1: Load per-repo contexts ─────────────────────────────────────────
-  console.log(chalk.blue("\n[W1] Loading per-repo contexts..."));
-  const contexts = new Map<string, import("../core/context-loader").ProjectContext>();
-  const frontendContexts = new Map<string, import("../core/frontend-context-loader").FrontendContext>();
-
-  for (const repo of workspace.repos) {
-    const repoAbsPath = workspaceLoader.resolveAbsPath(repo);
-    try {
-      const loader = new ContextLoader(repoAbsPath);
-      const ctx = await loader.loadProjectContext();
-      contexts.set(repo.name, ctx);
-
-      // Load frontend context for frontend/mobile repos
-      if (repo.role === "frontend" || repo.role === "mobile") {
-        const fctx = await loadFrontendContext(repoAbsPath);
-        frontendContexts.set(repo.name, fctx);
-        console.log(chalk.gray(`  ${repo.name}: ${fctx.framework} / ${fctx.httpClient} / hooks:${fctx.hookFiles.length} stores:${fctx.storeFiles.length}`));
-      } else {
-        console.log(chalk.gray(`  ${repo.name}: ${ctx.techStack.join(", ") || "unknown"} (${ctx.dependencies.length} deps)`));
-      }
-    } catch (err) {
-      console.log(chalk.yellow(`  ${repo.name}: context load failed — ${(err as Error).message}`));
-    }
-  }
-
-  // ── Step 2: Decompose requirement ─────────────────────────────────────────
-  console.log(chalk.blue("\n[W2] Decomposing requirement across repos..."));
-  const decomposer = new RequirementDecomposer(specProvider);
-  let decomposition: DecompositionResult;
-
-  try {
-    decomposition = await decomposer.decompose(idea, workspace, contexts, frontendContexts);
-    console.log(chalk.green(`  Summary: ${decomposition.summary}`));
-    console.log(chalk.gray(`  Repos affected: ${decomposition.repos.map((r) => r.repoName).join(", ")}`));
-    if (decomposition.coordinationNotes) {
-      console.log(chalk.gray(`  Coordination: ${decomposition.coordinationNotes}`));
-    }
-  } catch (err) {
-    console.error(chalk.red(`  Decomposition failed: ${(err as Error).message}`));
-    console.log(chalk.yellow("  Falling back to running all repos independently."));
-    // Fallback: create basic requirements for all repos
-    decomposition = {
-      originalRequirement: idea,
-      summary: idea,
-      coordinationNotes: "",
-      repos: workspace.repos.map((repo) => ({
-        repoName: repo.name,
-        role: repo.role,
-        specIdea: idea,
-        isContractProvider: repo.role === "backend",
-        dependsOnRepos: repo.role !== "backend" ? workspace.repos.filter((r) => r.role === "backend").map((r) => r.name) : [],
-        uxDecisions: null,
-      })),
-    };
-  }
-
-  // ── Step 3: Show decomposition preview + confirmation ─────────────────────
-  if (!opts.auto) {
-    console.log(chalk.cyan("\n[W3] Decomposition Preview:"));
-    console.log(chalk.cyan("─".repeat(52)));
-    for (const r of decomposition.repos) {
-      console.log(chalk.bold(`  ${r.repoName} (${r.role})`));
-      console.log(chalk.gray(`    ${r.specIdea.slice(0, 150)}${r.specIdea.length > 150 ? "..." : ""}`));
-      if (r.uxDecisions) {
-        const ux = r.uxDecisions;
-        const uxSummary = [
-          ux.throttleMs ? `throttle ${ux.throttleMs}ms` : "",
-          ux.debounceMs ? `debounce ${ux.debounceMs}ms` : "",
-          ux.optimisticUpdate ? "optimistic-update" : "",
-          ux.errorRollback ? "rollback" : "",
-        ]
-          .filter(Boolean)
-          .join(", ");
-        if (uxSummary) console.log(chalk.cyan(`    UX: ${uxSummary}`));
-      }
-      if (r.dependsOnRepos.length > 0) {
-        console.log(chalk.gray(`    Depends on: ${r.dependsOnRepos.join(", ")}`));
-      }
-    }
-    console.log(chalk.cyan("─".repeat(52)));
-
-    const gate = await select({
-      message: "Proceed with multi-repo pipeline?",
-      choices: [
-        { name: "Proceed — run all repos", value: "proceed" },
-        { name: "Abort", value: "abort" },
-      ],
-    });
-
-    if (gate === "abort") {
-      console.log(chalk.yellow("  Aborted."));
-      process.exit(0);
-    }
-  }
-
-  // ── Step 4: Sort repos by dependency order ─────────────────────────────────
-  const sortedRepoRequirements = RequirementDecomposer.sortByDependency(decomposition.repos);
-
-  // Contract accumulator: repoName → extracted DSL
-  const contractDsls = new Map<string, SpecDSL>();
-
-  // ── Step 5: Run each repo's pipeline ──────────────────────────────────────
-  console.log(chalk.blue(`\n[W4] Running pipeline for ${sortedRepoRequirements.length} repo(s)...`));
-
-  const results: MultiRepoResult[] = [];
-
-  for (const repoReq of sortedRepoRequirements) {
-    // Find repo config in workspace
-    const repoConfig = workspace.repos.find((r) => r.name === repoReq.repoName);
-    if (!repoConfig) {
-      console.log(chalk.yellow(`  Skipping ${repoReq.repoName} — not found in workspace config.`));
-      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null, repoAbsPath: "", role: repoReq.role });
-      continue;
-    }
-
-    const repoAbsPath = workspaceLoader.resolveAbsPath(repoConfig);
-
-    console.log(chalk.bold.blue(`\n  ── ${repoReq.repoName} (${repoReq.role}) ──────────────────────`));
-
-    // Build contract context from upstream repos
-    let contractContextSection: string | undefined;
-    if (repoReq.dependsOnRepos.length > 0) {
-      const contractParts: string[] = [];
-      for (const depName of repoReq.dependsOnRepos) {
-        const depDsl = contractDsls.get(depName);
-        if (depDsl) {
-          console.log(chalk.gray(`    Using API contract from: ${depName}`));
-          const contract = buildFrontendApiContract(depDsl);
-          contractParts.push(buildContractContextSection(contract));
-        }
-      }
-      if (contractParts.length > 0) {
-        contractContextSection = contractParts.join("\n\n");
-      }
-    }
-
-    // For frontend repos, also load frontend context and inject UX decisions
-    let specIdea = repoReq.specIdea;
-    if (
-      (repoReq.role === "frontend" || repoReq.role === "mobile") &&
-      repoReq.uxDecisions
-    ) {
-      const frontendCtx = await loadFrontendContext(repoAbsPath);
-      const frontendCtxSection = buildFrontendContextSection(frontendCtx);
-
-      specIdea = buildFrontendSpecPrompt({
-        specIdea: repoReq.specIdea,
-        apiContractSection: contractContextSection,
-        uxDecisions: repoReq.uxDecisions,
-        frontendContext: frontendCtx,
-      });
-
-      // contractContextSection is already injected via buildFrontendSpecPrompt
-      contractContextSection = undefined;
-
-      console.log(chalk.gray(`    Frontend context: ${frontendCtx.framework} / ${frontendCtx.httpClient} / ${frontendCtx.uiLibrary}`));
-    }
-
-    try {
-      const { dsl, specFile } = await runSingleRepoPipelineInWorkspace({
-        idea: specIdea,
-        specProvider,
-        specProviderName,
-        specModelName,
-        codegenProvider,
-        codegenMode,
-        repoAbsPath,
-        repoName: repoReq.repoName,
-        cliOpts: opts,
-        contractContextSection,
-      });
-
-      // Store DSL for downstream repos if this is a contract provider
-      if (repoReq.isContractProvider && dsl) {
-        contractDsls.set(repoReq.repoName, dsl);
-        console.log(chalk.green(`    Contract stored for downstream repos.`));
-      }
-
-      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl, repoAbsPath, role: repoReq.role });
-      console.log(chalk.green(`  ✔ ${repoReq.repoName} complete`));
-    } catch (err) {
-      console.error(chalk.red(`  ✘ ${repoReq.repoName} failed: ${(err as Error).message}`));
-      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null, repoAbsPath, role: repoReq.role });
-      // Continue — don't abort other repos
-    }
-  }
-
-  // ── Done ──────────────────────────────────────────────────────────────────
-  console.log(chalk.bold.green("\n✔ Multi-repo pipeline complete!"));
-  console.log(chalk.gray(`  Workspace: ${workspace.name}`));
-  console.log(chalk.gray(`  Requirement: ${idea}`));
-  console.log();
-  for (const r of results) {
-    const icon = r.status === "success" ? chalk.green("✔") : r.status === "failed" ? chalk.red("✘") : chalk.gray("−");
-    const specInfo = r.specFile ? chalk.gray(` → ${r.specFile}`) : "";
-    console.log(`  ${icon} ${r.repoName} (${r.status})${specInfo}`);
-  }
-
-  return results;
-}
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: workspace
-// ═══════════════════════════════════════════════════════════════════════════════
-
-const workspaceCmd = program
-  .command("workspace")
-  .description("Manage multi-repo workspace configuration");
-
-// workspace init
-workspaceCmd
-  .command("init")
-  .description(`Interactive workspace setup — creates ${WORKSPACE_CONFIG_FILE}`)
-  .action(async () => {
-    const currentDir = process.cwd();
-    const configPath = path.join(currentDir, WORKSPACE_CONFIG_FILE);
-
-    if (await fs.pathExists(configPath)) {
-      const overwrite = await confirm({
-        message: `${WORKSPACE_CONFIG_FILE} already exists. Overwrite?`,
-        default: false,
-      });
-      if (!overwrite) {
-        console.log(chalk.gray("  Cancelled."));
-        return;
-      }
-    }
-
-    console.log(chalk.blue("\n─── Workspace Setup ────────────────────────────"));
-
-    const workspaceName = await input({
-      message: "Workspace name:",
-      validate: (v) => v.trim().length > 0 || "Name cannot be empty",
-    });
-
-    const repos: RepoConfig[] = [];
-
-    // ── Auto-scan option ──────────────────────────────────────────────────────
-    const useAutoScan = await confirm({
-      message: "Auto-scan sibling directories for repos?",
-      default: true,
-    });
-
-    if (useAutoScan) {
-      const workspaceLoader = new WorkspaceLoader(currentDir);
-      const detected = await workspaceLoader.autoDetect();
-
-      if (detected.length === 0) {
-        console.log(chalk.yellow("  No recognizable repos found in sibling directories."));
-      } else {
-        console.log(chalk.cyan("\n  Detected repos:"));
-        for (const r of detected) {
-          console.log(chalk.gray(`    - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
-        }
-
-        const keepAll = await confirm({
-          message: `Include all ${detected.length} detected repo(s)?`,
-          default: true,
-        });
-
-        if (keepAll) {
-          repos.push(...detected);
-        } else {
-          // Let user cherry-pick
-          for (const r of detected) {
-            const keep = await confirm({
-              message: `Include "${r.name}" (${r.role}, ${r.type})?`,
-              default: true,
-            });
-            if (keep) repos.push(r);
-          }
-        }
-        console.log(chalk.green(`  ✔ ${repos.length} repo(s) added from auto-scan.`));
-      }
-    }
-
-    // ── Manual add (always offered after auto-scan) ───────────────────────────
-    const repoTypeChoices = [
-      { name: "node-express (Node.js/Express backend)", value: "node-express" },
-      { name: "node-koa (Node.js/Koa backend)", value: "node-koa" },
-      { name: "go (Go backend)", value: "go" },
-      { name: "python (Python backend)", value: "python" },
-      { name: "java (Java/Spring backend)", value: "java" },
-      { name: "rust (Rust backend)", value: "rust" },
-      { name: "php (PHP/Lumen/Laravel backend)", value: "php" },
-      { name: "react (React frontend)", value: "react" },
-      { name: "next (Next.js)", value: "next" },
-      { name: "vue (Vue frontend)", value: "vue" },
-      { name: "react-native (React Native mobile)", value: "react-native" },
-      { name: "unknown", value: "unknown" },
-    ];
-
-    let addMore = await confirm({
-      message: repos.length > 0 ? "Manually add more repos?" : "Add repos manually?",
-      default: repos.length === 0,
-    });
-
-    while (addMore) {
-      console.log(chalk.cyan(`\n  Adding repo #${repos.length + 1}`));
-
-      const repoName = await input({
-        message: "Repo name (e.g. api, web, app):",
-        validate: (v) => {
-          if (!v.trim()) return "Name cannot be empty";
-          if (repos.some((r) => r.name === v.trim())) return "Name already used";
-          return true;
-        },
-      });
-
-      const repoPath = await input({
-        message: `Relative path to "${repoName}" from here (default: ./${repoName}):`,
-        default: `./${repoName}`,
-      });
-
-      // Try to auto-detect type
-      const absPath = path.resolve(currentDir, repoPath);
-      let detectedType = "unknown";
-      let detectedRole = "shared";
-
-      if (await fs.pathExists(absPath)) {
-        const { type, role } = await detectRepoType(absPath);
-        detectedType = type;
-        detectedRole = role;
-        console.log(chalk.gray(`    Auto-detected: type=${type}, role=${role}`));
-      } else {
-        console.log(chalk.yellow(`    Path "${absPath}" not found — type/role will be manual.`));
-      }
-
-      const repoType = await select({
-        message: `Repo type for "${repoName}":`,
-        choices: repoTypeChoices,
-        default: detectedType,
-      });
-
-      const repoRole = await select({
-        message: `Repo role for "${repoName}":`,
-        choices: [
-          { name: "backend", value: "backend" },
-          { name: "frontend", value: "frontend" },
-          { name: "mobile", value: "mobile" },
-          { name: "shared", value: "shared" },
-        ],
-        default: detectedRole,
-      });
-
-      repos.push({
-        name: repoName,
-        path: repoPath,
-        type: repoType as RepoConfig["type"],
-        role: repoRole as RepoConfig["role"],
-      });
-
-      console.log(chalk.green(`  ✔ Added: ${repoName} (${repoRole}, ${repoType})`));
-
-      addMore = await confirm({
-        message: "Add another repo?",
-        default: false,
-      });
-    }
-
-    const workspaceConfig: WorkspaceConfig = { name: workspaceName, repos };
-
-    // Show summary
-    console.log(chalk.cyan("\n  Workspace summary:"));
-    console.log(chalk.gray(`  Name: ${workspaceName}`));
-    for (const r of repos) {
-      console.log(chalk.gray(`  - ${r.name}: ${r.role} (${r.type}) at ${r.path}`));
-    }
-
-    const ok = await confirm({ message: `Save to ${WORKSPACE_CONFIG_FILE}?`, default: true });
-    if (!ok) {
-      console.log(chalk.gray("  Cancelled."));
-      return;
-    }
-
-    const loader = new WorkspaceLoader(currentDir);
-    const saved = await loader.save(workspaceConfig);
-    console.log(chalk.green(`\n  ✔ Workspace saved: ${saved}`));
-    console.log(chalk.gray(`  Run \`ai-spec create "your feature"\` — workspace mode will activate automatically.`));
-  });
-
-// workspace status
-workspaceCmd
-  .command("status")
-  .description("Show current workspace configuration")
-  .action(async () => {
-    const currentDir = process.cwd();
-    const loader = new WorkspaceLoader(currentDir);
-    const config = await loader.load();
-
-    if (!config) {
-      console.log(chalk.yellow(`No ${WORKSPACE_CONFIG_FILE} found in ${currentDir}`));
-      console.log(chalk.gray("  Run `ai-spec workspace init` to create one."));
-      return;
-    }
-
-    console.log(chalk.bold(`\nWorkspace: ${config.name}`));
-    console.log(chalk.gray(`  Config: ${path.join(currentDir, WORKSPACE_CONFIG_FILE)}`));
-    console.log(chalk.gray(`  Repos (${config.repos.length}):\n`));
-
-    for (const repo of config.repos) {
-      const absPath = loader.resolveAbsPath(repo);
-      const exists = await fs.pathExists(absPath);
-      const status = exists ? chalk.green("found") : chalk.red("not found");
-
-      console.log(
-        `  ${chalk.bold(repo.name.padEnd(12))} ${repo.role.padEnd(10)} ${repo.type.padEnd(16)} ${status}`
-      );
-      console.log(chalk.gray(`    path: ${absPath}`));
-      if (repo.constitution) {
-        console.log(chalk.green(`    constitution: found`));
-      }
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: update  —  Incremental spec + code update pipeline
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("update")
-  .description("Update an existing spec with a change request, re-extract DSL, and identify affected files")
-  .argument("[change]", "Change description (prompted if omitted)")
-  .option("--provider <name>", `AI provider (${SUPPORTED_PROVIDERS.join("|")})`, undefined)
-  .option("--model <name>", "Model name")
-  .option("-k, --key <apiKey>", "API key")
-  .option("--spec <path>", "Path to the existing spec file (auto-detected if omitted)")
-  .option("--codegen", "Regenerate affected files automatically after updating spec")
-  .option("--codegen-provider <name>", "Provider for code generation")
-  .option("--codegen-model <name>", "Model for code generation")
-  .option("--codegen-key <key>", "API key for code generation")
-  .option("--skip-affected", "Skip identifying affected files")
-  .action(async (change: string | undefined, opts) => {
-    const currentDir = process.cwd();
-    const config = await loadConfig(currentDir);
-
-    // ── Resolve change ────────────────────────────────────────────────────────
-    if (!change) {
-      change = await input({
-        message: "Describe the change you want to make:",
-        validate: (v) => v.trim().length > 0 || "Change description cannot be empty",
-      });
-    }
-
-    // ── Resolve provider ──────────────────────────────────────────────────────
-    const providerName = opts.provider || config.provider || "gemini";
-    const modelName = opts.model || config.model || DEFAULT_MODELS[providerName];
-    const apiKey = await resolveApiKey(providerName, opts.key);
-    const provider = createProvider(providerName, apiKey, modelName);
-
-    console.log(chalk.blue("\n─── ai-spec update ─────────────────────────────"));
-    console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-
-    // ── Run tracking (snapshot + log) ─────────────────────────────────────────
-    const updateRunId = generateRunId();
-    const updateSnapshot = new RunSnapshot(currentDir, updateRunId);
-    setActiveSnapshot(updateSnapshot);
-    const updateLogger = new RunLogger(currentDir, updateRunId, { provider: providerName, model: modelName });
-    setActiveLogger(updateLogger);
-    console.log(chalk.gray(`  Run ID: ${updateRunId}`));
-
-    // ── Find existing spec ────────────────────────────────────────────────────
-    let specPath: string | null = opts.spec ?? null;
-    if (!specPath) {
-      const specsDir = path.join(currentDir, "specs");
-      const latest = await SpecUpdater.findLatestSpec(specsDir);
-      if (!latest) {
-        console.error(chalk.red("  No spec files found in specs/. Run `ai-spec create` first or use --spec <path>."));
-        process.exit(1);
-      }
-      specPath = latest.filePath;
-      console.log(chalk.gray(`  Using spec: ${path.relative(currentDir, specPath)} (v${latest.version})`));
-    }
-
-    // ── Load context ──────────────────────────────────────────────────────────
-    console.log(chalk.gray("  Loading project context..."));
-    const loader = new ContextLoader(currentDir);
-    const context = await loader.loadProjectContext();
-    if (context.constitution && context.constitution.length > 6000) {
-      console.log(chalk.yellow(`  ⚠ Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
-    }
-
-    // ── Detect repo type ──────────────────────────────────────────────────────
-    const { detectRepoType: _detectRepoType } = await import("../core/workspace-loader");
-    const { type: repoType } = await _detectRepoType(currentDir);
-
-    // ── Run update ────────────────────────────────────────────────────────────
-    const updater = new SpecUpdater(provider);
-    let result;
-    try {
-      result = await updater.update(change!, specPath, currentDir, context, {
-        skipAffectedFiles: opts.skipAffected,
-        repoType,
-      });
-    } catch (err) {
-      console.error(chalk.red(`  Update failed: ${(err as Error).message}`));
-      process.exit(1);
-    }
-
-    console.log(chalk.green(`\n  ✔ Spec updated → v${result.newVersion}: ${path.relative(currentDir, result.newSpecPath)}`));
-    if (result.newDslPath) {
-      console.log(chalk.green(`  ✔ DSL updated: ${path.relative(currentDir, result.newDslPath)}`));
-    }
-
-    // ── Show affected files ───────────────────────────────────────────────────
-    if (result.affectedFiles.length > 0) {
-      console.log(chalk.cyan("\n  Affected files:"));
-      for (const f of result.affectedFiles) {
-        const icon = f.action === "create" ? chalk.green("+") : chalk.yellow("~");
-        console.log(`    ${icon} ${f.file}: ${chalk.gray(f.description)}`);
-      }
-    }
-
-    // ── Optional: regenerate affected files ───────────────────────────────────
-    if (opts.codegen && result.affectedFiles.length > 0) {
-      const codegenProviderName = opts.codegenProvider || config.codegenProvider || providerName;
-      const codegenModelName = opts.codegenModel || config.codegenModel || DEFAULT_MODELS[codegenProviderName];
-      const codegenApiKey = opts.codegenKey ?? (codegenProviderName === providerName ? apiKey : await resolveApiKey(codegenProviderName, opts.codegenKey));
-      const codegenProvider = createProvider(codegenProviderName, codegenApiKey, codegenModelName);
-
-      console.log(chalk.blue("\n  Regenerating affected files..."));
-      const codeGenerator = new CodeGenerator(codegenProvider, "api");
-
-      const specContent = await fs.readFile(result.newSpecPath, "utf-8");
-      const constitutionSection = context.constitution
-        ? `\n=== Project Constitution (MUST follow) ===\n${context.constitution}\n`
-        : "";
-      const dslSection = result.updatedDsl
-        ? `\n=== DSL Context ===\n${JSON.stringify(result.updatedDsl, null, 2).slice(0, 3000)}\n`
-        : "";
-
-      updateLogger.stageStart("update_codegen");
-      for (const affected of result.affectedFiles) {
-        const fullPath = path.join(currentDir, affected.file);
-        let existing = "";
-        try { existing = await fs.readFile(fullPath, "utf-8"); } catch { /* new file */ }
-
-        const codePrompt = `Apply this change to the file.
-
-Change: ${change}
-File: ${affected.file}
-Purpose: ${affected.description}
-
-=== Feature Spec (updated) ===
-${specContent}
-${constitutionSection}${dslSection}
-=== ${existing ? "Current File (return the FULL updated content)" : "New File"} ===
-${existing || "Create from scratch."}`;
-
-        process.stdout.write(`  ${existing ? chalk.yellow("~") : chalk.green("+")} ${affected.file}... `);
-        try {
-          const { getCodeGenSystemPrompt: _getPrompt } = await import("../prompts/codegen.prompt");
-          const raw = await codegenProvider.generate(codePrompt, _getPrompt(repoType));
-          const content = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
-          await fs.ensureDir(path.dirname(fullPath));
-          // Snapshot original before overwrite so `ai-spec restore` can undo
-          await updateSnapshot.snapshotFile(fullPath);
-          await fs.writeFile(fullPath, content, "utf-8");
-          updateLogger.fileWritten(affected.file);
-          console.log(chalk.green("✔"));
-        } catch (err) {
-          updateLogger.stageFail("update_codegen", `${affected.file}: ${(err as Error).message}`);
-          console.log(chalk.red(`✘ ${(err as Error).message}`));
-        }
-      }
-      updateLogger.stageEnd("update_codegen", { filesUpdated: result.affectedFiles.length });
-
-      // Knowledge Memory: run a lightweight review on the updated spec and accumulate lessons
-      const updatedSpecContent = await fs.readFile(result.newSpecPath, "utf-8").catch(() => "");
-      if (updatedSpecContent) {
-        const updateReviewer = new CodeReviewer(provider, currentDir);
-        const reviewResult = await updateReviewer.reviewCode(updatedSpecContent, result.newSpecPath).catch(() => "");
-        if (reviewResult && reviewResult !== "No changes") {
-          await accumulateReviewKnowledge(provider, currentDir, reviewResult);
-        }
-      }
-    }
-
-    // ── Finish run tracking ────────────────────────────────────────────────────
-    updateLogger.finish();
-    updateLogger.printSummary();
-    if (updateSnapshot.fileCount > 0) {
-      console.log(chalk.gray(`  To undo changes: ai-spec restore ${updateRunId}`));
-    }
-
-    // ── Hints ─────────────────────────────────────────────────────────────────
-    if (!opts.codegen && result.affectedFiles.length > 0) {
-      console.log(chalk.blue("\n  Next steps:"));
-      console.log(chalk.gray(`  • Re-run with --codegen to regenerate affected files automatically`));
-      console.log(chalk.gray(`  • Or update files manually based on the affected files list above`));
-      console.log(chalk.gray(`  • Run \`ai-spec mock\` to refresh the mock server with the new DSL`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: export  —  Export DSL to OpenAPI / other formats
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("export")
-  .description("Export the latest DSL to OpenAPI 3.1.0 (YAML or JSON)")
-  .option("--openapi", "Export as OpenAPI 3.1.0 (default behaviour)")
-  .option("--format <fmt>", "Output format: yaml | json (default: yaml)", "yaml")
-  .option("--output <path>", "Output file path (default: openapi.yaml)")
-  .option("--server <url>", "API server URL in the OpenAPI document (default: http://localhost:3000)")
-  .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
-  .action(async (opts) => {
-    const currentDir = process.cwd();
-
-    // ── Find DSL ──────────────────────────────────────────────────────────────
-    let dslPath: string | null = opts.dsl ?? null;
-    if (!dslPath) {
-      dslPath = await findLatestDslFile(currentDir);
-      if (!dslPath) {
-        console.error(chalk.red("  No .dsl.json file found. Run `ai-spec create` first or use --dsl <path>."));
-        process.exit(1);
-      }
-      console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
-    }
-
-    let dsl: SpecDSL;
-    try {
-      dsl = await fs.readJson(dslPath);
-    } catch (err) {
-      console.error(chalk.red(`  Failed to read DSL: ${(err as Error).message}`));
-      process.exit(1);
-    }
-
-    // ── Export ────────────────────────────────────────────────────────────────
-    console.log(chalk.blue("\n─── ai-spec export ─────────────────────────────"));
-
-    const format = (opts.format === "json" ? "json" : "yaml") as "yaml" | "json";
-    const serverUrl = opts.server || "http://localhost:3000";
-
-    try {
-      const outputPath = await exportOpenApi(dsl, currentDir, {
-        format,
-        serverUrl,
-        outputPath: opts.output,
-      });
-      const rel = path.relative(currentDir, outputPath);
-      console.log(chalk.green(`  ✔ OpenAPI ${format.toUpperCase()} exported: ${rel}`));
-      console.log(chalk.gray(`  Feature  : ${dsl.feature.title}`));
-      console.log(chalk.gray(`  Endpoints: ${dsl.endpoints.length}`));
-      console.log(chalk.gray(`  Models   : ${dsl.models.length}`));
-      console.log(chalk.gray(`  Server   : ${serverUrl}`));
-      console.log(chalk.blue("\n  Next steps:"));
-      console.log(chalk.gray(`  • Import ${rel} into Postman / Insomnia / Swagger UI`));
-      console.log(chalk.gray(`  • Use openapi-generator to generate client SDKs`));
-    } catch (err) {
-      console.error(chalk.red(`  Export failed: ${(err as Error).message}`));
-      process.exit(1);
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: mock  —  Generate mock server, proxy config, and MSW handlers from DSL
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("mock")
-  .description("Generate a standalone mock server + proxy config from the latest DSL")
-  .option("--port <n>", "Mock server port (default: 3001)", "3001")
-  .option("--msw", "Also generate MSW (Mock Service Worker) handlers at src/mocks/")
-  .option("--proxy", "Also generate frontend proxy config snippet")
-  .option("--dsl <path>", "Path to a specific .dsl.json file (auto-detected if omitted)")
-  .option("--workspace", "Generate mock assets for all backend repos in the workspace")
-  .option("--serve", "Start mock server in background + patch frontend proxy (use with --frontend)")
-  .option("--frontend <path>", "Path to frontend project for proxy patching (used with --serve/--restore)")
-  .option("--restore", "Undo proxy changes and stop mock server (requires --frontend or auto-detects)")
-  .action(async (opts) => {
-    const currentDir = process.cwd();
-    const port = parseInt(opts.port, 10) || 3001;
-
-    console.log(chalk.blue("\n─── ai-spec mock ───────────────────────────────"));
-
-    // ── Restore mode ──────────────────────────────────────────────────────────
-    if (opts.restore) {
-      const frontendDir = opts.frontend ? path.resolve(opts.frontend) : currentDir;
-      const r = await restoreMockProxy(frontendDir);
-      if (r.restored) {
-        console.log(chalk.green("  ✔ Proxy restored and mock server stopped."));
-      } else {
-        console.log(chalk.yellow(`  ${r.note ?? "Nothing to restore."}`));
-      }
-      return;
-    }
-
-    // ── Workspace mode ────────────────────────────────────────────────────────
-    if (opts.workspace) {
-      const workspaceLoader = new WorkspaceLoader(currentDir);
-      const workspaceConfig = await workspaceLoader.load();
-      if (!workspaceConfig) {
-        console.error(chalk.red(`  No ${WORKSPACE_CONFIG_FILE} found. Run \`ai-spec workspace init\` first.`));
-        process.exit(1);
-      }
-
-      const backendRepos = workspaceConfig.repos.filter((r) => r.role === "backend");
-      if (backendRepos.length === 0) {
-        console.log(chalk.yellow("  No backend repos found in workspace."));
-        return;
-      }
-
-      for (const repo of backendRepos) {
-        const repoAbsPath = workspaceLoader.resolveAbsPath(repo);
-        console.log(chalk.cyan(`\n  Repo: ${repo.name} (${repoAbsPath})`));
-
-        const dslFile = await findLatestDslFile(repoAbsPath);
-        if (!dslFile) {
-          console.log(chalk.yellow(`    No DSL file found — skipping.`));
-          continue;
-        }
-
-        const dsl: SpecDSL = await fs.readJson(dslFile);
-        const result = await generateMockAssets(dsl, repoAbsPath, {
-          port,
-          msw: opts.msw,
-          proxy: opts.proxy,
-        });
-
-        for (const f of result.files) {
-          console.log(chalk.green(`    ✔ ${f.path}`));
-          console.log(chalk.gray(`      ${f.description}`));
-        }
-      }
-      return;
-    }
-
-    // ── Single-repo mode ──────────────────────────────────────────────────────
-    let dslPath: string | null = opts.dsl ?? null;
-
-    if (!dslPath) {
-      dslPath = await findLatestDslFile(currentDir);
-      if (!dslPath) {
-        console.error(
-          chalk.red(
-            "  No .dsl.json file found in .ai-spec/. Run `ai-spec create` first or use --dsl <path>."
-          )
-        );
-        process.exit(1);
-      }
-      console.log(chalk.gray(`  Using DSL: ${path.relative(currentDir, dslPath)}`));
-    }
-
-    let dsl: SpecDSL;
-    try {
-      dsl = await fs.readJson(dslPath);
-    } catch (err) {
-      console.error(chalk.red(`  Failed to read DSL file: ${(err as Error).message}`));
-      process.exit(1);
-    }
-
-    const result = await generateMockAssets(dsl, currentDir, {
-      port,
-      msw: opts.msw,
-      proxy: opts.proxy,
-    });
-
-    console.log(chalk.green(`\n  ✔ Mock assets generated (${result.files.length} file(s)):`));
-    for (const f of result.files) {
-      console.log(chalk.green(`    ${f.path}`));
-      console.log(chalk.gray(`      ${f.description}`));
-    }
-
-    // ── Serve mode: start mock server + patch frontend proxy ──────────────────
-    if (opts.serve) {
-      const serverJsPath = path.join(currentDir, "mock", "server.js");
-      if (!(await fs.pathExists(serverJsPath))) {
-        console.error(chalk.red("  mock/server.js not found — generation may have failed."));
-        process.exit(1);
-      }
-
-      // Start mock server in background
-      const pid = startMockServerBackground(serverJsPath, port);
-      console.log(chalk.green(`\n  ✔ Mock server started (PID ${pid}) → http://localhost:${port}`));
-
-      // Apply frontend proxy patch
-      if (opts.frontend) {
-        const frontendDir = path.resolve(opts.frontend);
-        const proxyResult = await applyMockProxy(frontendDir, port, dsl.endpoints);
-        await saveMockServerPid(frontendDir, pid);
-
-        if (proxyResult.applied) {
-          console.log(chalk.green(`  ✔ Frontend proxy patched (${proxyResult.framework})`));
-          console.log(chalk.bold.cyan(`\n  Ready! Open a new terminal and run:`));
-          console.log(chalk.white(`    cd ${frontendDir}`));
-          console.log(chalk.white(`    ${proxyResult.devCommand}`));
-          console.log(chalk.gray(`\n  When done: ai-spec mock --restore --frontend ${frontendDir}`));
-        } else {
-          console.log(chalk.yellow(`  ⚠ Auto-patch not available for ${proxyResult.framework}.`));
-          if (proxyResult.note) console.log(chalk.gray(`    ${proxyResult.note}`));
-        }
-      } else {
-        console.log(chalk.gray(`  Tip: use --frontend <path> to also auto-patch your frontend proxy config.`));
-        console.log(chalk.gray(`  Mock server: http://localhost:${port}`));
-      }
-      return;
-    }
-
-    console.log(chalk.blue("\n─── Quick start ────────────────────────────────"));
-    console.log(chalk.white(`  1. Install express (if not already):`));
-    console.log(chalk.gray(`       npm install --save-dev express`));
-    console.log(chalk.white(`  2. Start mock server:`));
-    console.log(chalk.gray(`       node mock/server.js`));
-    console.log(chalk.gray(`       # or: ai-spec mock --serve --frontend <path-to-frontend>`));
-    console.log(chalk.white(`  3. Configure your frontend to proxy API calls to:`));
-    console.log(chalk.gray(`       http://localhost:${port}`));
-    if (opts.proxy) {
-      console.log(chalk.gray(`     (See the generated proxy config file for framework-specific instructions)`));
-    }
-    if (opts.msw) {
-      console.log(chalk.white(`  4. MSW: import and start the worker in your app entry:`));
-      console.log(chalk.gray(`       import { worker } from './mocks/browser';`));
-      console.log(chalk.gray(`       if (process.env.NODE_ENV === 'development') worker.start();`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: learn  —  zero-friction knowledge injection into constitution §9
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("learn")
-  .description("Append a lesson or engineering decision directly to constitution §9")
-  .argument("[lesson]", "The lesson or decision to record (prompted if omitted)")
-  .action(async (lesson: string | undefined) => {
-    const currentDir = process.cwd();
-
-    if (!lesson) {
-      const { default: inquirerInput } = await import("@inquirer/prompts").then(
-        (m) => ({ default: m.input })
-      );
-      lesson = await inquirerInput({
-        message: "What lesson or engineering decision should be recorded?",
-        validate: (v) => v.trim().length > 0 || "Please enter a lesson",
-      });
-    }
-
-    const result = await appendDirectLesson(currentDir, lesson.trim());
-
-    if (result.appended) {
-      console.log(chalk.green(`\n  ✔ Lesson appended to constitution §9`));
-      console.log(chalk.gray(`  File: .ai-spec-constitution.md`));
-    } else {
-      console.log(chalk.yellow(`\n  ⚠ Not appended: ${result.reason}`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: restore
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("restore")
-  .description("Restore files modified by a previous run")
-  .argument("<runId>", "Run ID shown at the end of a create / generate run")
-  .action(async (runId: string) => {
-    const currentDir = process.cwd();
-    const snapshot = new RunSnapshot(currentDir, runId);
-    console.log(chalk.blue(`Restoring run: ${runId}...`));
-    const restored = await snapshot.restore();
-    if (restored.length === 0) {
-      console.log(chalk.yellow("  No backup found for this run ID."));
-    } else {
-      restored.forEach((f) => console.log(chalk.green(`  ✔ restored: ${f}`)));
-      console.log(chalk.bold.green(`\n✔ ${restored.length} file(s) restored.`));
-    }
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: trend
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("trend")
-  .description("Show harness score trend across past create runs")
-  .option("--last <n>", "Number of recent scored runs to show (default: 15)", "15")
-  .option("--prompt <hash>", "Filter to a specific prompt hash (prefix match)")
-  .option("--json", "Output raw JSON instead of formatted table")
-  .action(async (opts: { last: string; prompt?: string; json?: boolean }) => {
-    const currentDir = process.cwd();
-    const last = parseInt(opts.last, 10) || 15;
-
-    const logs = await loadRunLogs(currentDir);
-    if (logs.length === 0) {
-      console.log(chalk.yellow(
-        "\n  No run logs found. Run `ai-spec create` at least once to start tracking.\n"
-      ));
-      return;
-    }
-
-    const report = buildTrendReport(logs, {
-      last,
-      promptFilter: opts.prompt,
-    });
-
-    if (opts.json) {
-      console.log(JSON.stringify(report, null, 2));
-      return;
-    }
-
-    printTrendReport(report, currentDir);
-  });
-
-// ═══════════════════════════════════════════════════════════════════════════════
-// Command: logs
-// ═══════════════════════════════════════════════════════════════════════════════
-
-program
-  .command("logs")
-  .description("List recent run logs with stage timing")
-  .argument("[runId]", "Show detailed stage breakdown for a specific run ID")
-  .option("--last <n>", "Number of runs to list (default: 10)", "10")
-  .action(async (runId: string | undefined, opts: { last: string }) => {
-    const currentDir = process.cwd();
-    const logDir = path.join(currentDir, ".ai-spec-logs");
-
-    if (!(await fs.pathExists(logDir))) {
-      console.log(chalk.yellow("\n  No run logs found (.ai-spec-logs/ does not exist).\n"));
-      return;
-    }
-
-    if (runId) {
-      // ── Detail view for a single run ──────────────────────────────────────
-      const logPath = path.join(logDir, `${runId}.json`);
-      if (!(await fs.pathExists(logPath))) {
-        console.log(chalk.red(`\n  Run not found: ${runId}\n`));
-        return;
-      }
-      const log = await fs.readJson(logPath);
-
-      console.log(chalk.cyan(`\n─── Run: ${log.runId} ─────────────────────────────────`));
-      console.log(chalk.gray(`  Started : ${log.startedAt}`));
-      if (log.endedAt) console.log(chalk.gray(`  Ended   : ${log.endedAt}`));
-      if (log.totalDurationMs !== undefined)
-        console.log(chalk.gray(`  Duration: ${(log.totalDurationMs / 1000).toFixed(1)}s`));
-      if (log.provider) console.log(chalk.gray(`  Provider: ${log.provider} / ${log.model ?? "?"}`));
-      if (log.promptHash) console.log(chalk.gray(`  Prompt  : ${log.promptHash}`));
-      if (log.harnessScore !== undefined)
-        console.log(chalk.white(`  Score   : ${log.harnessScore}/10`));
-      if (log.filesWritten?.length)
-        console.log(chalk.gray(`  Files   : ${log.filesWritten.length} written`));
-      if (log.errors?.length)
-        console.log(chalk.yellow(`  Errors  : ${log.errors.length}`));
-
-      if (log.entries?.length) {
-        console.log(chalk.bold("\n  Stages:\n"));
-        const doneEvents = (log.entries as Array<{ event: string; data?: Record<string, unknown>; ts: string }>)
-          .filter((e) => e.event.endsWith(":done") || e.event.endsWith(":failed"));
-
-        for (const entry of doneEvents) {
-          const isOk  = entry.event.endsWith(":done");
-          const stage = entry.event.replace(/:done$|:failed$/, "");
-          const dur   = entry.data?.durationMs
-            ? chalk.gray(` ${(Number(entry.data.durationMs) / 1000).toFixed(1)}s`)
-            : "";
-          const mark  = isOk ? chalk.green("✔") : chalk.red("✘");
-          console.log(`    ${mark}  ${stage.padEnd(20)}${dur}`);
-        }
-      }
-      console.log(chalk.cyan("─".repeat(52)));
-      return;
-    }
-
-    // ── List view ─────────────────────────────────────────────────────────────
-    const logs = await loadRunLogs(currentDir);
-    const last  = parseInt(opts.last, 10) || 10;
-    const shown = logs.slice(0, last);
-
-    if (shown.length === 0) {
-      console.log(chalk.yellow("\n  No run logs found.\n"));
-      return;
-    }
-
-    console.log(chalk.cyan("\n─── Run Logs ────────────────────────────────────────────────"));
-    console.log(chalk.gray(
-      "\n  " +
-      "Run ID                  ".padEnd(26) +
-      "Date      " +
-      "Score ".padStart(6) +
-      "  Files  Dur\n"
-    ));
-
-    for (const log of shown) {
-      const date  = log.startedAt.slice(0, 10);
-      const score = log.harnessScore !== undefined
-        ? (log.harnessScore >= 8 ? chalk.green : log.harnessScore >= 6 ? chalk.yellow : chalk.red)(
-            log.harnessScore.toFixed(1).padStart(5)
-          )
-        : chalk.gray("    —");
-      const files = String(log.filesWritten?.length ?? 0).padStart(5);
-      const dur   = log.totalDurationMs !== undefined
-        ? chalk.gray((log.totalDurationMs / 1000).toFixed(0) + "s")
-        : chalk.gray("—");
-      const errMark = (log.errors?.length ?? 0) > 0
-        ? chalk.yellow(` ⚠${log.errors.length}`)
-        : "";
-
-      console.log(`  ${chalk.white(log.runId.padEnd(25))} ${chalk.gray(date)} ${score}  ${chalk.gray(files)}  ${dur}${errMark}`);
-    }
-
-    console.log(chalk.gray(`\n  Showing ${shown.length} of ${logs.length} run(s)  ·  logs: .ai-spec-logs/`));
-    console.log(chalk.cyan("─".repeat(63)));
-    console.log(chalk.gray(`  Tip: ai-spec logs <runId>   to see stage breakdown`));
-    console.log(chalk.gray(`       ai-spec trend          to see score trend by prompt version\n`));
-  });
+registerCreate(program);
+registerReview(program);
+registerInit(program);
+registerConfig(program);
+registerModel(program);
+registerWorkspace(program);
+registerUpdate(program);
+registerExport(program);
+registerMock(program);
+registerLearn(program);
+registerRestore(program);
+registerTrend(program);
+registerLogs(program);
+registerTypes(program);
+registerDashboard(program);
+registerVcr(program);
+registerScan(program);
 
 program.parse();