ai-spec-dev 0.41.0 → 0.46.0

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);

package/core/cli-ui.ts

@@ -0,0 +1,136 @@
+import chalk from "chalk";
+
+// ─── Spinner ──────────────────────────────────────────────────────────────────
+
+const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+export interface Spinner {
+  /** Update the text shown after the spinner. */
+  update(text: string): void;
+  /** Stop the spinner and show a final message. */
+  stop(finalText?: string): void;
+  /** Stop with a success (✔) mark. */
+  succeed(text: string): void;
+  /** Stop with a failure (✘) mark. */
+  fail(text: string): void;
+}
+
+/**
+ * Start a CLI spinner that renders on a single line.
+ * Works in any TTY; silently degrades to static text in non-TTY (CI).
+ */
+export function startSpinner(text: string): Spinner {
+  const isTTY = process.stderr.isTTY;
+  let frame = 0;
+  let currentText = text;
+  let stopped = false;
+
+  function render() {
+    if (stopped) return;
+    const symbol = chalk.cyan(SPINNER_FRAMES[frame % SPINNER_FRAMES.length]);
+    if (isTTY) {
+      process.stderr.write(`\r  ${symbol} ${currentText}${" ".repeat(10)}`);
+    }
+    frame++;
+  }
+
+  // Print initial line for non-TTY
+  if (!isTTY) {
+    process.stderr.write(`  … ${currentText}\n`);
+  }
+
+  const timer = setInterval(render, 80);
+  render();
+
+  return {
+    update(newText: string) {
+      currentText = newText;
+    },
+    stop(finalText?: string) {
+      if (stopped) return;
+      stopped = true;
+      clearInterval(timer);
+      if (isTTY) {
+        process.stderr.write(`\r${" ".repeat(currentText.length + 20)}\r`);
+      }
+      if (finalText) {
+        process.stderr.write(`  ${finalText}\n`);
+      }
+    },
+    succeed(successText: string) {
+      this.stop(chalk.green(`✔ ${successText}`));
+    },
+    fail(failText: string) {
+      this.stop(chalk.red(`✘ ${failText}`));
+    },
+  };
+}
+
+// ─── Retry Countdown ──────────────────────────────────────────────────────────
+
+/**
+ * Show an animated countdown during retry wait.
+ * Displays error details + a live seconds countdown.
+ */
+export async function retryCountdown(opts: {
+  attempt: number;
+  maxAttempts: number;
+  waitMs: number;
+  errorMessage: string;
+  label: string;
+}): Promise<void> {
+  const { attempt, maxAttempts, waitMs, errorMessage, label } = opts;
+  const isTTY = process.stderr.isTTY;
+
+  // Error box
+  const shortErr = errorMessage.length > 120
+    ? errorMessage.slice(0, 117) + "..."
+    : errorMessage;
+
+  process.stderr.write("\n");
+  process.stderr.write(chalk.yellow(`  ┌─ Retry ${attempt}/${maxAttempts} `) + chalk.gray(`[${label}]`) + chalk.yellow(` ${"─".repeat(Math.max(1, 40 - label.length))}\n`));
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.white(shortErr) + "\n");
+  process.stderr.write(chalk.yellow(`  │ `) + chalk.gray(`Waiting before retry...`) + "\n");
+
+  // Animated countdown
+  const totalSeconds = Math.ceil(waitMs / 1000);
+  for (let s = totalSeconds; s > 0; s--) {
+    const bar = chalk.green("█".repeat(totalSeconds - s)) + chalk.gray("░".repeat(s));
+    const line = chalk.yellow(`  │ `) + `${bar} ${chalk.bold.white(`${s}s`)}`;
+    if (isTTY) {
+      process.stderr.write(`\r${line}${" ".repeat(10)}`);
+    }
+    await new Promise<void>((r) => setTimeout(r, 1000));
+  }
+
+  if (isTTY) {
+    process.stderr.write(`\r${" ".repeat(70)}\r`);
+  }
+  process.stderr.write(chalk.yellow(`  └─ `) + chalk.cyan(`Retrying now...`) + "\n\n");
+}
+
+// ─── Stage Progress ───────────────────────────────────────────────────────────
+
+const STAGE_ICONS: Record<string, string> = {
+  context_load: "📂",
+  design_dialogue: "💬",
+  spec_gen: "📝",
+  spec_refine: "✏️ ",
+  spec_assess: "📊",
+  dsl_extract: "🔗",
+  dsl_gap_feedback: "🔍",
+  codegen: "⚙️ ",
+  test_gen: "🧪",
+  error_feedback: "🔧",
+  review: "🔎",
+  self_eval: "📈",
+};
+
+/**
+ * Start a pipeline stage with a spinner.
+ * Returns a handle to succeed/fail/update the stage display.
+ */
+export function startStage(stageKey: string, label: string): Spinner {
+  const icon = STAGE_ICONS[stageKey] ?? "▸";
+  return startSpinner(`${icon}  ${label}`);
+}

package/core/code-generator.ts

@@ -22,6 +22,7 @@ import {
 } from "./codegen/helpers";
 import { topoSortLayerTasks, printTaskProgress, LAYER_ICONS } from "./codegen/topo-sort";
 import { estimateTokens, getDefaultBudget } from "./token-budget";
+import { startSpinner } from "./cli-ui";
 
 // Re-export public symbols for backward compatibility
 export { extractBehavioralContract } from "./codegen/helpers";
@@ -654,6 +655,7 @@ ${constitutionSection}
 === ${existingContent ? "Existing content (modify and return the complete file)" : "Create this file from scratch"} ===
 ${existingContent || "Output only the complete file content."}`;
 
+      const fileSpinner = startSpinner(`${prefix}Generating ${chalk.bold(item.file)}...`);
       try {
         const raw = await this.provider.generate(codePrompt, systemPrompt);
         const fileContent = stripCodeFences(raw);
@@ -661,11 +663,11 @@ ${existingContent || "Output only the complete file content."}`;
         await fs.ensureDir(path.dirname(fullPath));
         await fs.writeFile(fullPath, fileContent, "utf-8");
         getActiveLogger()?.fileWritten(item.file);
-        console.log(`${prefix}${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)} ${chalk.green("✔")}`);
+        fileSpinner.succeed(`${existingContent ? chalk.yellow("~") : chalk.green("+")} ${chalk.bold(item.file)}`);
         successCount++;
         writtenFiles.push(item.file);
       } catch (err) {
-        console.log(`${prefix}${chalk.red("✘")} ${chalk.bold(item.file)} — ${chalk.red((err as Error).message)}`);
+        fileSpinner.fail(`${chalk.bold(item.file)} — ${(err as Error).message}`);
       }
     }
 

package/core/config-defaults.ts

@@ -0,0 +1,44 @@
+/**
+ * config-defaults.ts — Centralized default values for all configurable constants.
+ *
+ * Modules import their defaults from here instead of defining local magic numbers.
+ * The pipeline can override any value via AiSpecConfig at runtime.
+ */
+
+// ─── Directory & File Names ─────────────────────────────────────────────────
+
+export const DEFAULT_LOG_DIR = ".ai-spec-logs";
+export const DEFAULT_VCR_DIR = ".ai-spec-vcr";
+export const DEFAULT_BACKUP_DIR = ".ai-spec-backup";
+export const DEFAULT_REVIEW_HISTORY_FILE = ".ai-spec-reviews.json";
+
+// ─── URLs ───────────────────────────────────────────────────────────────────
+
+export const DEFAULT_OPENAPI_SERVER_URL = "http://localhost:3000";
+
+// ─── Numeric Limits ─────────────────────────────────────────────────────────
+
+/** Max chars captured from build/test/lint command output before parsing. */
+export const DEFAULT_MAX_COMMAND_OUTPUT_CHARS = 30_000;
+
+/** Max chars of an existing file sent to the AI for auto-fix. */
+export const DEFAULT_MAX_FIX_FILE_CHARS = 60_000;
+
+/** Max DSL extraction retries on parse failure. */
+export const DEFAULT_DSL_MAX_RETRIES = 2;
+
+/** Max constitution chars in codegen prompts (trimmed if exceeded). */
+export const DEFAULT_MAX_CONSTITUTION_CHARS = 4_000;
+
+/** Max chars of file content sent per file in review (reviewFiles mode). */
+export const DEFAULT_MAX_REVIEW_FILE_CHARS = 3_000;
+
+// ─── Token Budgets ──────────────────────────────────────────────────────────
+
+export const DEFAULT_TOKEN_BUDGETS: Record<string, number> = {
+  gemini: 900_000,
+  claude: 180_000,
+  openai: 120_000,
+  deepseek: 60_000,
+  default: 100_000,
+};

package/core/constitution-generator.ts

@@ -4,6 +4,7 @@ import * as path from "path";
 import { AIProvider } from "./spec-generator";
 import { ContextLoader, ProjectContext } from "./context-loader";
 import { constitutionSystemPrompt } from "../prompts/constitution.prompt";
+import { DEFAULT_MAX_CONSTITUTION_CHARS } from "./config-defaults";
 
 export const CONSTITUTION_FILE = ".ai-spec-constitution.md";
 
@@ -41,7 +42,7 @@ function buildConstitutionPrompt(context: ProjectContext, projectRoot: string):
   }
 
   if (context.schema) {
-    parts.push(`=== Prisma Schema ===\n${context.schema.slice(0, 4000)}\n`);
+    parts.push(`=== Prisma Schema ===\n${context.schema.slice(0, DEFAULT_MAX_CONSTITUTION_CHARS)}\n`);
   }
 
   if (context.errorPatterns) {

package/core/dsl-extractor.ts

@@ -13,6 +13,7 @@ import {
 } from "../prompts/dsl.prompt";
 import { estimateTokens, getDefaultBudget } from "./token-budget";
 import { parseJsonFromAiOutput } from "./safe-json";
+import { DEFAULT_DSL_MAX_RETRIES } from "./config-defaults";
 
 // ─── DSL Sanitizer ───────────────────────────────────────────────────────────
 
@@ -50,7 +51,7 @@ function sanitizeDsl(raw: unknown): unknown {
 // ─── Constants ────────────────────────────────────────────────────────────────
 
 /** Maximum AI attempts (1 initial + up to this many retries). */
-const MAX_RETRIES = 2;
+const MAX_RETRIES = DEFAULT_DSL_MAX_RETRIES;
 
 /** Default maximum spec length passed to AI. Overridden by token budget when provider is known. */
 const DEFAULT_MAX_SPEC_CHARS = 12_000;

package/core/error-feedback.ts

@@ -7,6 +7,8 @@ import { getCodeGenSystemPrompt } from "../prompts/codegen.prompt";
 import { SpecDSL } from "./dsl-types";
 import { buildDslContextSection } from "./dsl-extractor";
 import { getActiveSnapshot } from "./run-snapshot";
+import { startSpinner } from "./cli-ui";
+import { DEFAULT_MAX_COMMAND_OUTPUT_CHARS, DEFAULT_MAX_FIX_FILE_CHARS } from "./config-defaults";
 
 // ─── Types ──────────────────────────────────────────────────────────────────────
 
@@ -29,14 +31,14 @@ interface FixResult {
  * ~10K tokens — enough for any realistic error listing; prevents a pathological
  * build output (e.g. 10MB of warnings) from ballooning the AI context.
  */
-const MAX_COMMAND_OUTPUT_CHARS = 50_000;
+const MAX_COMMAND_OUTPUT_CHARS = DEFAULT_MAX_COMMAND_OUTPUT_CHARS;
 
 /**
  * Maximum characters of an existing file sent to the AI for auto-fix.
  * ~12K tokens — covers large files; content beyond this is truncated with a
  * notice so the AI knows it may be seeing an incomplete file.
  */
-const MAX_FIX_FILE_CHARS = 60_000;
+const MAX_FIX_FILE_CHARS = DEFAULT_MAX_FIX_FILE_CHARS;
 
 // ─── Error Detection ────────────────────────────────────────────────────────────
 
@@ -369,16 +371,17 @@ ${fileContent}
 
 Output ONLY the complete fixed file content. No markdown fences, no explanations.`;
 
+    const fixSpinner = startSpinner(`Fixing ${chalk.bold(file)} (${fileErrors.length} error(s))...`);
     try {
       const raw = await provider.generate(prompt, getCodeGenSystemPrompt());
       const fixed = raw.replace(/^```\w*\n?/gm, "").replace(/\n?```$/gm, "").trim();
       await getActiveSnapshot()?.snapshotFile(fullPath);
       await fs.writeFile(fullPath, fixed, "utf-8");
       results.push({ fixed: true, file, explanation: `Fixed ${fileErrors.length} error(s)` });
-      console.log(chalk.green(`  ✔ Auto-fixed: ${file}`));
+      fixSpinner.succeed(`Auto-fixed: ${file}`);
     } catch (err) {
       results.push({ fixed: false, file, explanation: `AI fix failed: ${(err as Error).message}` });
-      console.log(chalk.yellow(`  ⚠ Could not auto-fix: ${file}`));
+      fixSpinner.fail(`Could not auto-fix: ${file}`);
     }
   }
 

package/core/openapi-exporter.ts

@@ -1,6 +1,7 @@
 import * as path from "path";
 import * as fs from "fs-extra";
 import { SpecDSL, ApiEndpoint, DataModel, ModelField, FieldMap } from "./dsl-types";
+import { DEFAULT_OPENAPI_SERVER_URL } from "./config-defaults";
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -272,7 +273,7 @@ function buildYamlDoc(obj: Record<string, unknown>): string {
  * Convert a SpecDSL to an OpenAPI 3.1.0 document.
  * Returns the document as a plain JS object (can be serialised to YAML or JSON).
  */
-export function dslToOpenApi(dsl: SpecDSL, serverUrl = "http://localhost:3000"): Record<string, unknown> {
+export function dslToOpenApi(dsl: SpecDSL, serverUrl = DEFAULT_OPENAPI_SERVER_URL): Record<string, unknown> {
   // ── Info ──────────────────────────────────────────────────────────────────
   const info = {
     title: dsl.feature.title,
@@ -338,7 +339,7 @@ export async function exportOpenApi(
   opts: OpenApiExportOptions = {}
 ): Promise<string> {
   const format = opts.format ?? "yaml";
-  const serverUrl = opts.serverUrl ?? "http://localhost:3000";
+  const serverUrl = opts.serverUrl ?? DEFAULT_OPENAPI_SERVER_URL;
   const defaultName = `openapi.${format}`;
   const outputPath = opts.outputPath
     ? path.isAbsolute(opts.outputPath)

package/core/provider-utils.ts

@@ -1,6 +1,5 @@
 import chalk from "chalk";
-
-const sleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));
+import { retryCountdown } from "./cli-ui";
 
 // ─── Error Classification ──────────────────────────────────────────────────────
 
@@ -112,12 +111,14 @@ export async function withReliability<T>(
         throw classifyError(err, label);
       }
       const waitMs = attempt === 0 ? 2_000 : 6_000;
-      console.warn(
-        chalk.yellow(`  ⚠ ${label} failed (attempt ${attempt + 1}/${retries + 1}), retrying in ${waitMs / 1000}s`) +
-          chalk.gray(` — ${(err as Error).message}`)
-      );
       onRetry?.(attempt + 1, err);
-      await sleep(waitMs);
+      await retryCountdown({
+        attempt: attempt + 1,
+        maxAttempts: retries + 1,
+        waitMs,
+        errorMessage: (err as Error).message ?? String(err),
+        label,
+      });
     }
   }
   /* istanbul ignore next */

package/core/repo-store.ts

@@ -0,0 +1,95 @@
+import * as fs from "fs-extra";
+import * as path from "path";
+import * as os from "os";
+import { RepoType, RepoRole } from "./workspace-loader";
+
+const REPO_STORE_FILE = path.join(os.homedir(), ".ai-spec-repos.json");
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+export interface RegisteredRepo {
+  /** Display name (defaults to directory basename) */
+  name: string;
+  /** Absolute path to the repo root */
+  path: string;
+  /** Auto-detected repo type */
+  type: RepoType;
+  /** Auto-detected repo role */
+  role: RepoRole;
+  /** Whether a project constitution has been generated */
+  hasConstitution: boolean;
+  /** ISO timestamp of registration */
+  registeredAt: string;
+}
+
+interface RepoStoreData {
+  repos: RegisteredRepo[];
+}
+
+// ─── Read / Write ────────────────────────────────────────────────────────────
+
+async function readStore(): Promise<RepoStoreData> {
+  try {
+    if (await fs.pathExists(REPO_STORE_FILE)) {
+      return await fs.readJson(REPO_STORE_FILE);
+    }
+  } catch (err) {
+    console.warn(`Warning: Could not read repo store at ${REPO_STORE_FILE}: ${(err as Error).message}.`);
+  }
+  return { repos: [] };
+}
+
+async function writeStore(store: RepoStoreData): Promise<void> {
+  await fs.ensureFile(REPO_STORE_FILE);
+  await fs.writeJson(REPO_STORE_FILE, store, { spaces: 2 });
+}
+
+// ─── Public API ──────────────────────────────────────────────────────────────
+
+/** Get all registered repos. */
+export async function getRegisteredRepos(): Promise<RegisteredRepo[]> {
+  const store = await readStore();
+  return store.repos;
+}
+
+/** Find a registered repo by its absolute path. */
+export async function getRepoByPath(absPath: string): Promise<RegisteredRepo | undefined> {
+  const store = await readStore();
+  return store.repos.find((r) => r.path === absPath);
+}
+
+/** Register a new repo. If already registered (by path), update it. */
+export async function registerRepo(repo: RegisteredRepo): Promise<void> {
+  const store = await readStore();
+  const idx = store.repos.findIndex((r) => r.path === repo.path);
+  if (idx >= 0) {
+    store.repos[idx] = repo;
+  } else {
+    store.repos.push(repo);
+  }
+  await writeStore(store);
+}
+
+/** Remove a registered repo by path. */
+export async function unregisterRepo(absPath: string): Promise<boolean> {
+  const store = await readStore();
+  const before = store.repos.length;
+  store.repos = store.repos.filter((r) => r.path !== absPath);
+  if (store.repos.length < before) {
+    await writeStore(store);
+    return true;
+  }
+  return false;
+}
+
+/** Update the hasConstitution flag for a repo. */
+export async function markRepoConstitution(absPath: string, has: boolean): Promise<void> {
+  const store = await readStore();
+  const repo = store.repos.find((r) => r.path === absPath);
+  if (repo) {
+    repo.hasConstitution = has;
+    await writeStore(store);
+  }
+}
+
+export { REPO_STORE_FILE };

package/core/reviewer.ts

@@ -10,6 +10,7 @@ import {
   reviewImpactComplexitySystemPrompt,
 } from "../prompts/codegen.prompt";
 import { CONSTITUTION_FILE } from "./constitution-generator";
+import { DEFAULT_REVIEW_HISTORY_FILE, DEFAULT_MAX_REVIEW_FILE_CHARS } from "./config-defaults";
 
 // ─── Constitution Lessons Helper ──────────────────────────────────────────────
 
@@ -48,7 +49,7 @@ interface ReviewHistoryEntry {
   complexityLevel?: "低" | "中" | "高";
 }
 
-const REVIEW_HISTORY_FILE = ".ai-spec-reviews.json";
+const REVIEW_HISTORY_FILE = DEFAULT_REVIEW_HISTORY_FILE;
 
 async function loadReviewHistory(projectRoot: string): Promise<ReviewHistoryEntry[]> {
   const historyPath = path.join(projectRoot, REVIEW_HISTORY_FILE);
@@ -225,16 +226,19 @@ ${codeContext}`;
     console.log(chalk.gray("  Pass 2/3: Implementation review..."));
 
     // ── Pass 2: Implementation + History ─────────────────────────────────────
+    // Token savings: Pass 2/3 receive a spec digest instead of the full spec,
+    // and omit the raw code context (Pass 1 already analyzed it).
+    const specDigest = specContent && specContent.length > 600
+      ? specContent.slice(0, 600) + "\n... [spec truncated — see Pass 0/1 for full text]"
+      : specContent || "(No spec)";
+
     const history = await loadReviewHistory(this.projectRoot);
     const historyContext = buildHistoryContext(history);
 
     const implPrompt = `Review the implementation details of this change.
 
-=== Feature Spec ===
-${specContent || "(No spec — review for general code quality)"}
-
-=== Code ===
-${codeContext}
+=== Feature Spec (digest — full spec was provided in Pass 0/1) ===
+${specDigest}
 
 === Architecture Review (Pass 1 — do NOT repeat these findings) ===
 ${archReview}
@@ -246,11 +250,8 @@ ${historyContext}`;
     // ── Pass 3: Impact & Complexity ───────────────────────────────────────────
     const impactPrompt = `Assess the impact and complexity of this change.
 
-=== Feature Spec ===
-${specContent || "(No spec — review for general code quality)"}
-
-=== Code ===
-${codeContext}
+=== Feature Spec (digest) ===
+${specDigest}
 
 === Architecture Review (Pass 1 — do NOT repeat) ===
 ${archReview}
@@ -338,8 +339,8 @@ ${implReview}`;
       const fullPath = path.join(workingDir, filePath);
       try {
         const content = await fs.readFile(fullPath, "utf-8");
-        filesSection += `\n\n=== ${filePath} ===\n${content.slice(0, 3000)}`;
-        if (content.length > 3000) filesSection += `\n... (truncated, ${content.length} chars total)`;
+        filesSection += `\n\n=== ${filePath} ===\n${content.slice(0, DEFAULT_MAX_REVIEW_FILE_CHARS)}`;
+        if (content.length > DEFAULT_MAX_REVIEW_FILE_CHARS) filesSection += `\n... (truncated, ${content.length} chars total)`;
       } catch {
         filesSection += `\n\n=== ${filePath} ===\n(file not found)`;
       }

package/core/run-logger.ts

@@ -1,8 +1,7 @@
 import * as fs from "fs-extra";
 import * as path from "path";
 import chalk from "chalk";
-
-const LOG_DIR = ".ai-spec-logs";
+import { DEFAULT_LOG_DIR } from "./config-defaults";
 
 // ─── JSONL helpers ────────────────────────────────────────────────────────────
 // Each event is synchronously appended as one JSON line to a `.jsonl` shadow
@@ -131,8 +130,8 @@ export class RunLogger {
     meta?: { provider?: string; model?: string; specPath?: string }
   ) {
     this.startMs = Date.now();
-    this.logPath  = path.join(workingDir, LOG_DIR, `${runId}.json`);
-    this.jsonlPath = path.join(workingDir, LOG_DIR, `${runId}.jsonl`);
+    this.logPath  = path.join(workingDir, DEFAULT_LOG_DIR, `${runId}.json`);
+    this.jsonlPath = path.join(workingDir, DEFAULT_LOG_DIR, `${runId}.jsonl`);
     this.log = {
       runId,
       startedAt: new Date().toISOString(),

package/core/run-snapshot.ts

@@ -1,7 +1,6 @@
 import * as fs from "fs-extra";
 import * as path from "path";
-
-const BACKUP_DIR = ".ai-spec-backup";
+import { DEFAULT_BACKUP_DIR } from "./config-defaults";
 
 // ─── RunSnapshot ──────────────────────────────────────────────────────────────
 /**
@@ -18,7 +17,7 @@ export class RunSnapshot {
     private readonly workingDir: string,
     readonly runId: string
   ) {
-    this.backupRoot = path.join(workingDir, BACKUP_DIR, runId);
+    this.backupRoot = path.join(workingDir, DEFAULT_BACKUP_DIR, runId);
   }
 
   /**