ai-spec-dev 0.42.0 → 0.46.0

package/cli/commands/init.ts

@@ -2,7 +2,9 @@ import { Command } from "commander";
 import * as path from "path";
 import * as fs from "fs-extra";
 import chalk from "chalk";
-import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS } from "../../core/spec-generator";
+import { input, select, confirm } from "@inquirer/prompts";
+import { RepoRole } from "../../core/workspace-loader";
+import { createProvider, DEFAULT_MODELS, SUPPORTED_PROVIDERS, AIProvider } from "../../core/spec-generator";
 import { ContextLoader } from "../../core/context-loader";
 import { ConstitutionGenerator, CONSTITUTION_FILE } from "../../core/constitution-generator";
 import { ConstitutionConsolidator } from "../../core/constitution-consolidator";
@@ -17,11 +19,200 @@ import {
 } from "../../prompts/global-constitution.prompt";
 import { loadConfig, resolveApiKey } from "../utils";
 import { loadIndex, ProjectEntry } from "../../core/project-index";
+import { detectRepoType } from "../../core/workspace-loader";
+import {
+  RegisteredRepo,
+  getRegisteredRepos,
+  registerRepo,
+  REPO_STORE_FILE,
+} from "../../core/repo-store";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+const ROLE_LABELS: Record<RepoRole, string> = {
+  frontend: "frontend",
+  backend: "backend",
+  mobile: "mobile",
+  shared: "shared",
+};
+
+/**
+ * Prompt user to select a repo role.
+ */
+async function promptRepoRole(): Promise<RepoRole> {
+  return select<RepoRole>({
+    message: "What type of repo is this?",
+    choices: [
+      { name: "Frontend", value: "frontend" },
+      { name: "Backend", value: "backend" },
+      { name: "Mobile", value: "mobile" },
+      { name: "Shared / Other", value: "shared" },
+    ],
+  });
+}
+
+/**
+ * Prompt user for a repo absolute path with validation.
+ */
+async function promptRepoPath(role: RepoRole): Promise<string> {
+  const label = ROLE_LABELS[role];
+  const raw = await input({
+    message: `Enter your ${label} repo path (absolute path):`,
+    validate: (v) => {
+      const trimmed = v.trim();
+      if (trimmed.length === 0) return "Path cannot be empty";
+      if (!path.isAbsolute(trimmed)) return "Please provide an absolute path";
+      return true;
+    },
+  });
+
+  // Strip shell escape backslashes (e.g. "文稿\ -\ hongzhong" → "文稿 - hongzhong")
+  const cleaned = raw.trim().replace(/\\ /g, " ");
+  const resolved = path.resolve(cleaned);
+  if (!(await fs.pathExists(resolved))) {
+    console.log(chalk.red(`  Path does not exist: ${resolved}`));
+    return promptRepoPath(role);
+  }
+  const stat = await fs.stat(resolved);
+  if (!stat.isDirectory()) {
+    console.log(chalk.red(`  Not a directory: ${resolved}`));
+    return promptRepoPath(role);
+  }
+  return resolved;
+}
+
+/**
+ * Register a single repo: detect type, generate project constitution, return entry.
+ * @param roleOverride — user-selected role (takes priority over auto-detection)
+ */
+async function registerSingleRepo(
+  repoPath: string,
+  provider: AIProvider,
+  roleOverride?: RepoRole
+): Promise<RegisteredRepo> {
+  const { type, role: detectedRole } = await detectRepoType(repoPath);
+  const role = roleOverride ?? detectedRole;
+  const repoName = path.basename(repoPath);
+
+  console.log(chalk.gray(`    Detected: ${repoName} → ${type} (${role})`));
+
+  // Generate project constitution
+  const constitutionPath = path.join(repoPath, CONSTITUTION_FILE);
+  let hasConstitution = await fs.pathExists(constitutionPath);
+
+  if (!hasConstitution) {
+    console.log(chalk.blue(`    Generating project constitution for ${repoName}...`));
+    try {
+      const gen = new ConstitutionGenerator(provider);
+      const content = await gen.generate(repoPath);
+      await gen.saveConstitution(repoPath, content);
+      hasConstitution = true;
+      console.log(chalk.green(`    ✔ Constitution saved: ${constitutionPath}`));
+    } catch (err) {
+      console.log(chalk.yellow(`    ⚠ Constitution generation failed: ${(err as Error).message}`));
+    }
+  } else {
+    console.log(chalk.green(`    ✔ Constitution already exists: ${constitutionPath}`));
+  }
+
+  const entry: RegisteredRepo = {
+    name: repoName,
+    path: repoPath,
+    type,
+    role,
+    hasConstitution,
+    registeredAt: new Date().toISOString(),
+  };
+
+  await registerRepo(entry);
+  return entry;
+}
+
+/**
+ * Build per-project summaries for global constitution generation from registered repos.
+ */
+async function buildProjectSummaries(
+  repos: RegisteredRepo[]
+): Promise<Array<{ name: string; summary: string }>> {
+  const summaries: Array<{ name: string; summary: string }> = [];
+
+  for (const repo of repos) {
+    if (!(await fs.pathExists(repo.path))) continue;
+
+    const lines: string[] = [
+      `Type: ${repo.type} (${repo.role})`,
+    ];
+
+    // Load tech stack from context
+    try {
+      const loader = new ContextLoader(repo.path);
+      const ctx = await loader.loadProjectContext();
+      lines.push(`Tech stack: ${ctx.techStack.join(", ") || "unknown"}`);
+      lines.push(`Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`);
+    } catch {
+      lines.push(`Tech stack: ${repo.type}`);
+    }
+
+    // Include constitution excerpt if available
+    if (repo.hasConstitution) {
+      try {
+        const constitutionPath = path.join(repo.path, CONSTITUTION_FILE);
+        const raw = await fs.readFile(constitutionPath, "utf-8");
+        lines.push("", "Constitution excerpt:", raw.slice(0, 2000));
+      } catch { /* skip */ }
+    }
+
+    summaries.push({ name: repo.name, summary: lines.join("\n") });
+  }
+
+  return summaries;
+}
+
+/**
+ * Generate or update global constitution based on all registered repos.
+ */
+async function generateGlobalConstitution(
+  provider: AIProvider,
+  repos: RegisteredRepo[],
+  currentDir: string
+): Promise<void> {
+  console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
+  console.log(chalk.gray(`  Based on ${repos.length} registered repo(s)`));
+
+  const summaries = await buildProjectSummaries(repos);
+  if (summaries.length === 0) {
+    console.log(chalk.yellow("  No valid repos found — skipping global constitution."));
+    return;
+  }
+
+  const prompt = buildGlobalConstitutionPrompt(summaries);
+  let globalConstitution: string;
+  try {
+    globalConstitution = await provider.generate(prompt, globalConstitutionSystemPrompt);
+  } catch (err) {
+    console.error(chalk.red(`  ✘ Failed to generate global constitution: ${(err as Error).message}`));
+    return;
+  }
+
+  const saved = await saveGlobalConstitution(globalConstitution, currentDir);
+  console.log(chalk.green(`  ✔ Global constitution saved: ${saved}`));
+  console.log(chalk.gray("  Project constitutions will be merged with this at runtime."));
+
+  // Preview
+  const lines = globalConstitution.split("\n");
+  console.log(chalk.bold("\n  Preview:"));
+  console.log(chalk.gray(lines.slice(0, 10).join("\n")));
+  if (lines.length > 10) {
+    console.log(chalk.gray(`  ... (${lines.length} lines total)`));
+  }
+}
+
+// ─── Command: init ───────────────────────────────────────────────────────────
 
 export function registerInit(program: Command): void {
   program
     .command("init")
-    .description(`Analyze codebase and generate Project Constitution (${CONSTITUTION_FILE})`)
+    .description("Setup workspace: register repos, generate constitutions")
     .option(
       "--provider <name>",
       `AI provider (${SUPPORTED_PROVIDERS.join("|")})`,
@@ -29,13 +220,10 @@ export function registerInit(program: Command): void {
     )
     .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("--force", "Overwrite existing constitutions")
+    .option("--consolidate", "Consolidate §9 accumulated lessons into §1–§8 core rules")
     .option("--dry-run", "Preview consolidation result without writing (use with --consolidate)")
+    .option("--add-repo", "Add a new repo to the registered list")
     .action(async (opts) => {
       const currentDir = process.cwd();
       const config = await loadConfig(currentDir);
@@ -68,123 +256,138 @@ export function registerInit(program: Command): void {
         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;
+      // ── Add-repo shortcut ──────────────────────────────────────────────────
+      if (opts.addRepo) {
+        console.log(chalk.blue("\n─── Register New Repo ──────────────────────────"));
+        const role = await promptRepoRole();
+        const repoPath = await promptRepoPath(role);
+        const entry = await registerSingleRepo(repoPath, provider, role);
+        console.log(chalk.green(`\n  ✔ Repo registered: ${entry.name} (${entry.type} / ${entry.role})`));
+        console.log(chalk.gray(`    Saved to: ${REPO_STORE_FILE}`));
+
+        // Ask if user wants to update global constitution
+        const updateGlobal = await confirm({
+          message: "Update global constitution with this repo's context?",
+          default: true,
+        });
+        if (updateGlobal) {
+          const allRepos = await getRegisteredRepos();
+          await generateGlobalConstitution(provider, allRepos, currentDir);
         }
+        return;
+      }
 
-        console.log(chalk.blue("\n─── Generating Global Constitution ──────────────"));
-        console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-
-        // ── Build per-project summaries ────────────────────────────────────
-        const projectSummaries: Array<{ name: string; summary: string }> = [];
-        const index = await loadIndex(currentDir);
-
-        if (index && index.projects.length > 0) {
-          const active = index.projects.filter((p: ProjectEntry) => !p.missing);
-          console.log(chalk.gray(`  Found project index: ${active.length} project(s) — reading constitutions...`));
-
-          for (const entry of active) {
-            const absPath = path.join(currentDir, entry.path);
-            const lines: string[] = [
-              `Type: ${entry.type} (${entry.role})`,
-              `Tech stack: ${entry.techStack.join(", ") || "unknown"}`,
-            ];
-
-            // Include §1–§6 of project constitution if available (skip §9 lessons)
-            if (entry.hasConstitution) {
-              try {
-                const constitutionPath = path.join(absPath, CONSTITUTION_FILE);
-                const raw = await fs.readFile(constitutionPath, "utf-8");
-                // Take up to first 2000 chars (covers §1–§6 without §9 noise)
-                const excerpt = raw.slice(0, 2000);
-                lines.push("", "Constitution excerpt:", excerpt);
-              } catch { /* skip if unreadable */ }
-            }
+      // ── Full init flow ─────────────────────────────────────────────────────
+      console.log(chalk.blue("\n" + "─".repeat(52)));
+      console.log(chalk.bold("  ai-spec init — Workspace Setup"));
+      console.log(chalk.blue("─".repeat(52)));
+      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}\n`));
 
-            projectSummaries.push({ name: entry.name, summary: lines.join("\n") });
-          }
-        } else {
-          // No index — fall back to scanning just the current directory
-          console.log(chalk.yellow("  No project index found. Run `ai-spec scan` first for better results."));
-          console.log(chalk.gray("  Falling back: scanning current directory only..."));
-          const loader = new ContextLoader(currentDir);
-          const ctx = await loader.loadProjectContext();
-          projectSummaries.push({
-            name: path.basename(currentDir),
-            summary: [
-              `Tech stack: ${ctx.techStack.join(", ") || "unknown"}`,
-              `Dependencies: ${ctx.dependencies.slice(0, 20).join(", ")}`,
-            ].join("\n"),
-          });
-        }
+      const existingRepos = await getRegisteredRepos();
 
-        console.log(chalk.gray(`  Generating from ${projectSummaries.length} project(s)...`));
-        const prompt = buildGlobalConstitutionPrompt(projectSummaries);
-        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);
+      // ── Step 1: Show existing repos if any ─────────────────────────────────
+      if (existingRepos.length > 0) {
+        console.log(chalk.cyan("  Registered repos:"));
+        for (const r of existingRepos) {
+          const constitutionIcon = r.hasConstitution ? chalk.green("✔") : chalk.gray("○");
+          console.log(chalk.gray(`    ${constitutionIcon} ${r.name} (${r.type} / ${r.role}) → ${r.path}`));
         }
+        console.log();
+      }
+
+      // ── Step 2: Register repos ─────────────────────────────────────────────
+      const action = existingRepos.length > 0
+        ? await select({
+            message: "What would you like to do?",
+            choices: [
+              { name: "Add new repo(s)", value: "add" as const },
+              { name: "Re-generate constitutions for existing repos", value: "regen" as const },
+              { name: "Skip — proceed to global constitution", value: "skip" as const },
+            ],
+          })
+        : "add" as const;
+
+      const newRepos: RegisteredRepo[] = [];
 
-        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)`));
+      if (action === "add") {
+        let addMore = true;
+        while (addMore) {
+          console.log(chalk.blue(`\n  ── Register Repo #${existingRepos.length + newRepos.length + 1} ──`));
+          const role = await promptRepoRole();
+          const repoPath = await promptRepoPath(role);
+
+          // Check if already registered
+          const alreadyRegistered = [...existingRepos, ...newRepos].find((r) => r.path === repoPath);
+          if (alreadyRegistered) {
+            console.log(chalk.yellow(`    Already registered: ${alreadyRegistered.name}`));
+          } else {
+            const entry = await registerSingleRepo(repoPath, provider, role);
+            newRepos.push(entry);
+            console.log(chalk.green(`    ✔ Registered: ${entry.name}`));
+          }
+
+          addMore = await confirm({
+            message: "Add another repo?",
+            default: false,
+          });
         }
-        return;
       }
 
-      // ── Project constitution mode (default) ───────────────────────────────
-      const constitutionPath = path.join(currentDir, CONSTITUTION_FILE);
+      if (action === "regen") {
+        console.log(chalk.blue("\n  Re-generating project constitutions..."));
+        for (const repo of existingRepos) {
+          if (!(await fs.pathExists(repo.path))) {
+            console.log(chalk.yellow(`    ⚠ ${repo.name}: path not found — skipping`));
+            continue;
+          }
 
-      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;
-      }
+          const constitutionPath = path.join(repo.path, CONSTITUTION_FILE);
+          if ((await fs.pathExists(constitutionPath)) && !opts.force) {
+            console.log(chalk.gray(`    ${repo.name}: constitution exists (use --force to overwrite)`));
+            continue;
+          }
 
-      console.log(chalk.blue("\n─── Generating Project Constitution ─────────────"));
-      console.log(chalk.gray(`  Provider: ${providerName}/${modelName}`));
-      console.log(chalk.gray("  Analyzing codebase..."));
+          console.log(chalk.blue(`    ${repo.name}: generating constitution...`));
+          try {
+            const gen = new ConstitutionGenerator(provider);
+            const content = await gen.generate(repo.path);
+            await gen.saveConstitution(repo.path, content);
+            console.log(chalk.green(`    ✔ ${repo.name}: constitution saved`));
+          } catch (err) {
+            console.log(chalk.yellow(`    ⚠ ${repo.name}: failed — ${(err as Error).message}`));
+          }
+        }
+      }
 
-      const generator = new ConstitutionGenerator(provider);
+      // ── Step 3: Generate/update global constitution ────────────────────────
+      const allRepos = await getRegisteredRepos();
 
-      let constitution: string;
-      try {
-        constitution = await generator.generate(currentDir);
-      } catch (err) {
-        console.error(chalk.red("  ✘ Failed to generate constitution:"), err);
-        process.exit(1);
+      if (allRepos.length === 0) {
+        console.log(chalk.yellow("\n  No repos registered. Run `ai-spec init` again to add repos."));
+        return;
       }
 
-      const saved = await generator.saveConstitution(currentDir, constitution);
+      const existingGlobal = await loadGlobalConstitution([currentDir]);
+      const shouldGenerateGlobal = !existingGlobal || opts.force || newRepos.length > 0
+        ? true
+        : await confirm({
+            message: "Global constitution exists. Re-generate it?",
+            default: false,
+          });
 
-      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."));
+      if (shouldGenerateGlobal) {
+        await generateGlobalConstitution(provider, allRepos, currentDir);
       }
 
-      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)`));
+      // ── Done ───────────────────────────────────────────────────────────────
+      console.log(chalk.bold.green("\n✔ Init complete!"));
+      console.log(chalk.gray(`  Repos registered: ${allRepos.length}`));
+      for (const r of allRepos) {
+        const icon = r.hasConstitution ? chalk.green("✔") : chalk.gray("○");
+        console.log(chalk.gray(`    ${icon} ${r.name} (${r.type}/${r.role})`));
       }
+      console.log(chalk.gray(`\n  Repo store: ${REPO_STORE_FILE}`));
+      console.log(chalk.gray(`  Next step: ai-spec create "your feature idea"`));
+      process.exit(0);
     });
 }

package/cli/commands/model.ts

@@ -1,6 +1,4 @@
 import { Command } from "commander";
-import * as path from "path";
-import * as fs from "fs-extra";
 import chalk from "chalk";
 import { input, select, confirm } from "@inquirer/prompts";
 import {
@@ -8,7 +6,7 @@ import {
   ENV_KEY_MAP,
   PROVIDER_CATALOG,
 } from "../../core/spec-generator";
-import { AiSpecConfig, CONFIG_FILE, loadConfig } from "../utils";
+import { AiSpecGlobalConfig, GLOBAL_CONFIG_FILE, loadGlobalConfig, saveGlobalConfig } from "../utils";
 
 export function registerModel(program: Command): void {
   program
@@ -16,9 +14,6 @@ export function registerModel(program: Command): void {
     .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 ──────────────────────────────────────────────────────────────
       if (opts.list) {
         console.log(chalk.bold("\nAvailable providers & models:\n"));
@@ -37,9 +32,10 @@ export function registerModel(program: Command): void {
         return;
       }
 
-      const existing: AiSpecConfig = await loadConfig(currentDir);
+      const existing: AiSpecGlobalConfig = await loadGlobalConfig();
 
       console.log(chalk.blue("\n─── Model Switcher ─────────────────────────────"));
+      console.log(chalk.gray(`  Config: ${GLOBAL_CONFIG_FILE}`));
       if (Object.keys(existing).length > 0) {
         console.log(
           chalk.gray(
@@ -92,7 +88,7 @@ export function registerModel(program: Command): void {
         return { provider: providerKey, model: chosenModel };
       }
 
-      const updated: AiSpecConfig = { ...existing };
+      const updated: AiSpecGlobalConfig = { ...existing };
 
       if (target === "spec" || target === "both") {
         const { provider, model } = await pickProviderAndModel("Spec");
@@ -134,14 +130,14 @@ export function registerModel(program: Command): void {
         );
       }
 
-      const ok = await confirm({ message: "Save to .ai-spec.json?", default: true });
+      const ok = await confirm({ message: `Save to ${GLOBAL_CONFIG_FILE}?`, 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}`));
+      await saveGlobalConfig(updated);
+      console.log(chalk.green(`\n  ✔ Saved to ${GLOBAL_CONFIG_FILE}`));
 
       const providerToCheck = updated.provider ?? "gemini";
       const envKey = ENV_KEY_MAP[providerToCheck];

package/cli/index.ts

@@ -27,7 +27,7 @@ const program = new Command();
 program
   .name("ai-spec")
   .description("AI-driven Development Orchestrator — spec, generate, review")
-  .version("0.14.1");
+  .version(require("../package.json").version);
 
 registerCreate(program);
 registerReview(program);

package/cli/utils.ts

@@ -1,19 +1,25 @@
 import * as path from "path";
 import * as fs from "fs-extra";
+import * as os from "os";
 import chalk from "chalk";
 import { input, select } from "@inquirer/prompts";
 import { CodeGenMode } from "../core/code-generator";
-import { ENV_KEY_MAP } from "../core/spec-generator";
+import { ENV_KEY_MAP, PROVIDER_CATALOG } from "../core/spec-generator";
 import { getSavedKey, saveKey, KEY_STORE_FILE } from "../core/key-store";
 
 // ─── Config ───────────────────────────────────────────────────────────────────
 
-export interface AiSpecConfig {
+/** User-level preferences (stored in ~/.ai-spec-config.json) */
+export interface AiSpecGlobalConfig {
   provider?: string;
   model?: string;
   codegen?: CodeGenMode;
   codegenProvider?: string;
   codegenModel?: string;
+}
+
+/** Full merged config (global + project-level overrides) */
+export interface AiSpecConfig extends AiSpecGlobalConfig {
   /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
   minSpecScore?: number;
   /** Minimum harness score (1-10) required for pipeline success. 0 = disabled (default). */
@@ -22,16 +28,70 @@ export interface AiSpecConfig {
   maxErrorCycles?: number;
   /** §9 lesson count threshold for auto-consolidation (default: 12). */
   autoConsolidateThreshold?: number;
+
+  // ── Directory & file overrides ─────────────────────────────────────────────
+  /** Run log directory (default: ".ai-spec-logs") */
+  logDir?: string;
+  /** VCR recording directory (default: ".ai-spec-vcr") */
+  vcrDir?: string;
+  /** File backup directory (default: ".ai-spec-backup") */
+  backupDir?: string;
+  /** Review history file (default: ".ai-spec-reviews.json") */
+  reviewHistoryFile?: string;
+
+  // ── URL overrides ──────────────────────────────────────────────────────────
+  /** Default server URL for OpenAPI export (default: "http://localhost:3000") */
+  openApiServerUrl?: string;
+
+  // ── Numeric limits ─────────────────────────────────────────────────────────
+  /** Max chars captured from build/test/lint command output (default: 30000) */
+  maxCommandOutputChars?: number;
+  /** Max chars of source file sent to AI for auto-fix (default: 60000) */
+  maxFixFileChars?: number;
+  /** Max DSL extraction retries (default: 2) */
+  dslMaxRetries?: number;
+  /** Max constitution chars in codegen prompt (default: 4000) */
+  maxConstitutionChars?: number;
+  /** Per-provider token budget overrides (e.g. { "gemini": 900000, "claude": 180000 }) */
+  providerTokenBudgets?: Record<string, number>;
 }
 
 export const CONFIG_FILE = ".ai-spec.json";
+export const GLOBAL_CONFIG_FILE = path.join(os.homedir(), ".ai-spec-config.json");
+
+/** Load global user-level config from ~/.ai-spec-config.json */
+export async function loadGlobalConfig(): Promise<AiSpecGlobalConfig> {
+  try {
+    if (await fs.pathExists(GLOBAL_CONFIG_FILE)) {
+      return await fs.readJson(GLOBAL_CONFIG_FILE);
+    }
+  } catch { /* ignore */ }
+  return {};
+}
 
+/** Save global user-level config to ~/.ai-spec-config.json */
+export async function saveGlobalConfig(config: AiSpecGlobalConfig): Promise<void> {
+  await fs.ensureFile(GLOBAL_CONFIG_FILE);
+  await fs.writeJson(GLOBAL_CONFIG_FILE, config, { spaces: 2 });
+}
+
+/**
+ * Load merged config: global (baseline) + project-level (override).
+ * Provider/model from global, project-specific settings from local .ai-spec.json.
+ */
 export async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const globalConfig = await loadGlobalConfig();
+
+  let localConfig: AiSpecConfig = {};
   const p = path.join(dir, CONFIG_FILE);
   if (await fs.pathExists(p)) {
-    return fs.readJson(p);
+    try {
+      localConfig = await fs.readJson(p);
+    } catch { /* ignore */ }
   }
-  return {};
+
+  // Local overrides global
+  return { ...globalConfig, ...localConfig };
 }
 
 // ─── API Key Resolution ───────────────────────────────────────────────────────
@@ -45,6 +105,14 @@ export async function resolveApiKey(
   const envVar = ENV_KEY_MAP[providerName];
   if (envVar && process.env[envVar]) return process.env[envVar]!;
 
+  // Check fallback env vars (e.g. MiMo reads ANTHROPIC_AUTH_TOKEN from token-plan)
+  const meta = PROVIDER_CATALOG[providerName];
+  if (meta?.fallbackEnvKeys) {
+    for (const key of meta.fallbackEnvKeys) {
+      if (process.env[key]) return process.env[key]!;
+    }
+  }
+
   const savedKey = await getSavedKey(providerName);
   if (savedKey) {
     const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);