ai-spec-dev 0.33.0 → 0.36.1

package/core/dsl-validator.ts

@@ -74,6 +74,22 @@ export function validateDsl(raw: unknown): DslValidationResult {
     for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
       validateEndpoint(eps[i], `endpoints[${i}]`, errors);
     }
+    // ── Endpoint ID uniqueness ──────────────────────────────────────────────
+    const seenEpIds = new Set<string>();
+    for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
+      const ep = eps[i] as Record<string, unknown> | null;
+      if (ep && typeof ep === "object" && typeof ep["id"] === "string") {
+        const id = ep["id"] as string;
+        if (seenEpIds.has(id)) {
+          errors.push({
+            path: `endpoints[${i}].id`,
+            message: `Duplicate endpoint id "${id}" — each endpoint must have a unique id`,
+          });
+        } else {
+          seenEpIds.add(id);
+        }
+      }
+    }
   }
 
   // ── behaviors (optional, but must be array if present) ────────────────────
@@ -149,6 +165,22 @@ function validateModel(
     for (let j = 0; j < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j++) {
       validateModelField(fields[j], `${path}.fields[${j}]`, errors);
     }
+    // ── Field name uniqueness within model ──────────────────────────────────
+    const seenFieldNames = new Set<string>();
+    for (let j = 0; j < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j++) {
+      const f = fields[j] as Record<string, unknown> | null;
+      if (f && typeof f === "object" && typeof f["name"] === "string") {
+        const name = f["name"] as string;
+        if (seenFieldNames.has(name)) {
+          errors.push({
+            path: `${path}.fields[${j}].name`,
+            message: `Duplicate field name "${name}" — each field within a model must have a unique name`,
+          });
+        } else {
+          seenFieldNames.add(name);
+        }
+      }
+    }
   }
 
   // relations: optional array of strings

package/core/error-feedback.ts

@@ -22,6 +22,22 @@ interface FixResult {
   explanation: string;
 }
 
+// ─── Budgets ────────────────────────────────────────────────────────────────────
+
+/**
+ * Maximum characters captured from a single command's output before parsing.
+ * ~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;
+
+/**
+ * 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;
+
 // ─── Error Detection ────────────────────────────────────────────────────────────
 
 function runCommand(cmd: string, cwd: string): { success: boolean; output: string } {
@@ -30,7 +46,13 @@ function runCommand(cmd: string, cwd: string): { success: boolean; output: strin
     return { success: true, output };
   } catch (err) {
     const e = err as { stdout?: string; stderr?: string; message?: string };
-    return { success: false, output: e.stdout || e.stderr || e.message || "" };
+    const raw = e.stdout || e.stderr || e.message || "";
+    // Apply output budget: cap before parsing to prevent huge outputs from
+    // filling up the AI context on subsequent fix cycles.
+    const output = raw.length > MAX_COMMAND_OUTPUT_CHARS
+      ? raw.slice(0, MAX_COMMAND_OUTPUT_CHARS) + `\n... [output truncated at ${MAX_COMMAND_OUTPUT_CHARS} chars]`
+      : raw;
+    return { success: false, output };
   }
 }
 
@@ -328,6 +350,13 @@ async function attemptFix(
     const dslSection = dsl ? `\n${buildDslContextSection(dsl)}\n` : "";
     const errorSummary = fileErrors.map((e) => `[${e.source}] ${e.message}`).join("\n");
 
+    // Apply file content budget — very large files are truncated with a notice.
+    // The AI still has enough context to fix the errors (which reference specific lines).
+    const fileContent = existingContent.length > MAX_FIX_FILE_CHARS
+      ? existingContent.slice(0, MAX_FIX_FILE_CHARS) +
+        `\n\n// ... [file truncated at ${MAX_FIX_FILE_CHARS} chars — fix only the error lines above]`
+      : existingContent;
+
     const prompt = `Fix the following errors in the file.
 
 File: ${file}
@@ -336,7 +365,7 @@ ${dslSection}
 ${errorSummary}
 
 === Current File Content ===
-${existingContent}
+${fileContent}
 
 Output ONLY the complete fixed file content. No markdown fences, no explanations.`;
 
@@ -394,6 +423,8 @@ export async function runErrorFeedback(
 
   if (buildCmd) console.log(chalk.gray(`  Type-check: ${buildCmd}`));
 
+  let prevErrorCount = Infinity; // circuit-breaker: tracks error count from previous cycle
+
   for (let cycle = 1; cycle <= maxCycles; cycle++) {
     const allErrors: ErrorEntry[] = [];
 
@@ -462,6 +493,19 @@ export async function runErrorFeedback(
       return true;
     }
 
+    // Circuit breaker: if the fix cycle made no progress (error count did not
+    // decrease), stop immediately rather than spending another AI cycle.
+    if (allErrors.length >= prevErrorCount) {
+      console.log(
+        chalk.yellow(
+          `\n  ⚠ Auto-fix made no progress (${allErrors.length} error(s) before and after). Stopping early.`
+        )
+      );
+      console.log(chalk.gray("    Manual intervention needed."));
+      return false;
+    }
+    prevErrorCount = allErrors.length;
+
     if (cycle < maxCycles) {
       console.log(chalk.cyan(`\n  Attempting auto-fix (${allErrors.length} error(s))...`));
       await attemptFix(provider, allErrors, workingDir, dsl);

package/core/key-store.ts

@@ -11,16 +11,17 @@ async function readStore(): Promise<KeyStore> {
     if (await fs.pathExists(KEY_STORE_FILE)) {
       return await fs.readJson(KEY_STORE_FILE);
     }
-  } catch {
-    // ignore corrupt file
+  } catch (err) {
+    console.warn(`Warning: Could not read key store at ${KEY_STORE_FILE}: ${(err as Error).message}. Using empty store.`);
   }
   return {};
 }
 
 async function writeStore(store: KeyStore): Promise<void> {
-  await fs.writeJson(KEY_STORE_FILE, store, { spaces: 2 });
-  // Restrict permissions to owner only (600)
+  // Ensure file exists with restricted permissions BEFORE writing sensitive data
+  await fs.ensureFile(KEY_STORE_FILE);
   await fs.chmod(KEY_STORE_FILE, 0o600);
+  await fs.writeJson(KEY_STORE_FILE, store, { spaces: 2 });
 }
 
 export async function getSavedKey(provider: string): Promise<string | undefined> {

package/core/project-index.ts

@@ -0,0 +1,301 @@
+/**
+ * project-index.ts — Persistent project discovery & index.
+ *
+ * Scans a root directory for sub-projects (any dir with a recognisable
+ * project manifest), and maintains an incremental JSON index file at
+ * .ai-spec-index.json in the scan root.
+ *
+ * Incremental rules:
+ *  - New project found   → added with firstSeen = now
+ *  - Existing project    → techStack / type / role / hasConstitution refreshed, lastSeen = now
+ *  - Previously indexed but directory gone → marked missing:true, NOT deleted
+ *
+ * The index is intentionally lightweight — no AI calls, pure filesystem scan.
+ */
+
+import * as fs from "fs-extra";
+import * as path from "path";
+import { detectRepoType, RepoType, RepoRole, WORKSPACE_CONFIG_FILE } from "./workspace-loader";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+export const INDEX_FILE = ".ai-spec-index.json";
+
+// ─── Key dependency lists for tech-stack extraction ──────────────────────────
+
+const KEY_DEPS: string[] = [
+  // Frameworks
+  "express", "fastify", "koa", "@nestjs/core", "hapi",
+  "next", "react", "vue", "nuxt", "svelte",
+  "react-native", "expo",
+  // DB / ORM
+  "prisma", "@prisma/client", "mongoose", "typeorm", "sequelize", "drizzle-orm",
+  // Auth
+  "jsonwebtoken", "passport", "next-auth", "@clerk/nextjs",
+  // Build / Lang
+  "typescript", "vite", "webpack", "esbuild", "turbo",
+  // Testing
+  "jest", "vitest", "mocha", "cypress", "playwright",
+  // Infra
+  "redis", "bull", "socket.io", "graphql", "@trpc/server",
+];
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface ProjectEntry {
+  /** Directory name */
+  name: string;
+  /** Path relative to scanRoot */
+  path: string;
+  type: RepoType;
+  role: RepoRole;
+  /** Key dependencies detected (subset of package.json deps or language markers) */
+  techStack: string[];
+  /** Whether .ai-spec-constitution.md exists */
+  hasConstitution: boolean;
+  /** Whether .ai-spec-workspace.json exists (this repo is a workspace root) */
+  hasWorkspace: boolean;
+  /** ISO timestamp of first discovery */
+  firstSeen: string;
+  /** ISO timestamp of last successful scan */
+  lastSeen: string;
+  /** true when the directory no longer exists on disk */
+  missing?: boolean;
+}
+
+export interface ProjectIndex {
+  /** Absolute path of the directory that was scanned */
+  scanRoot: string;
+  /** ISO timestamp of last scan */
+  lastScanned: string;
+  projects: ProjectEntry[];
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/** Directories to always skip during scan */
+const SKIP_DIRS = new Set([
+  "node_modules", ".git", ".svn", "dist", "build", "out", ".next",
+  ".nuxt", "coverage", ".turbo", ".cache", "__pycache__", "vendor",
+  ".ai-spec-vcr", ".ai-spec-logs", "specs",
+]);
+
+/** Manifest files that identify a directory as a project root */
+const MANIFEST_FILES = [
+  "package.json",
+  "go.mod",
+  "Cargo.toml",
+  "pom.xml",
+  "build.gradle",
+  "build.gradle.kts",
+  "requirements.txt",
+  "pyproject.toml",
+  "setup.py",
+  "composer.json",
+];
+
+async function isProjectRoot(absPath: string): Promise<boolean> {
+  for (const manifest of MANIFEST_FILES) {
+    if (await fs.pathExists(path.join(absPath, manifest))) return true;
+  }
+  return false;
+}
+
+async function extractTechStack(absPath: string, type: RepoType): Promise<string[]> {
+  const stack: string[] = [];
+
+  // Language marker for non-Node projects
+  if (type === "go")     stack.push("go");
+  if (type === "rust")   stack.push("rust");
+  if (type === "java")   stack.push("java");
+  if (type === "python") stack.push("python");
+  if (type === "php")    stack.push("php");
+
+  const pkgPath = path.join(absPath, "package.json");
+  if (!(await fs.pathExists(pkgPath))) return stack;
+
+  let pkg: Record<string, unknown> = {};
+  try { pkg = await fs.readJson(pkgPath); } catch { return stack; }
+
+  const allDeps = {
+    ...((pkg.dependencies as Record<string, string>) ?? {}),
+    ...((pkg.devDependencies as Record<string, string>) ?? {}),
+  };
+  const depKeys = new Set(Object.keys(allDeps));
+
+  for (const dep of KEY_DEPS) {
+    if (depKeys.has(dep)) stack.push(dep);
+  }
+
+  return stack;
+}
+
+// ─── Scan ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Discover all project roots under `rootDir` up to `maxDepth` levels deep.
+ * Returns paths relative to rootDir.
+ */
+async function discoverProjects(
+  rootDir: string,
+  maxDepth: number
+): Promise<string[]> {
+  const found: string[] = [];
+
+  async function walk(absDir: string, depth: number): Promise<void> {
+    if (depth > maxDepth) return;
+
+    let entries: fs.Dirent[];
+    try {
+      entries = await fs.readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+
+      const childAbs = path.join(absDir, entry.name);
+
+      // Skip git worktrees — they have a .git *file* (not directory)
+      const gitPath = path.join(childAbs, ".git");
+      if (await fs.pathExists(gitPath)) {
+        const gitStat = await fs.stat(gitPath);
+        if (gitStat.isFile()) continue; // git worktree — skip
+      }
+
+      if (await isProjectRoot(childAbs)) {
+        found.push(path.relative(rootDir, childAbs));
+        // Don't recurse into a project root — avoids picking up nested node_modules etc.
+      } else {
+        await walk(childAbs, depth + 1);
+      }
+    }
+  }
+
+  await walk(rootDir, 0);
+  return found;
+}
+
+// ─── Index load / save ────────────────────────────────────────────────────────
+
+export async function loadIndex(scanRoot: string): Promise<ProjectIndex | null> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  try {
+    return await fs.readJson(filePath);
+  } catch {
+    return null;
+  }
+}
+
+export async function saveIndex(scanRoot: string, index: ProjectIndex): Promise<string> {
+  const filePath = path.join(scanRoot, INDEX_FILE);
+  await fs.writeJson(filePath, index, { spaces: 2 });
+  return filePath;
+}
+
+// ─── Incremental merge ────────────────────────────────────────────────────────
+
+export interface ScanResult {
+  index: ProjectIndex;
+  added: ProjectEntry[];
+  updated: ProjectEntry[];
+  unchanged: ProjectEntry[];
+  nowMissing: ProjectEntry[];
+}
+
+/**
+ * Run an incremental scan of `scanRoot`, merge with the existing index, and
+ * return the updated index along with a change summary.
+ */
+export async function runScan(
+  scanRoot: string,
+  maxDepth = 2
+): Promise<ScanResult> {
+  const now = new Date().toISOString();
+  const existing = await loadIndex(scanRoot);
+  const existingMap = new Map<string, ProjectEntry>(
+    (existing?.projects ?? []).map((p) => [p.path, p])
+  );
+
+  const discoveredPaths = await discoverProjects(scanRoot, maxDepth);
+
+  const added: ProjectEntry[] = [];
+  const updated: ProjectEntry[] = [];
+  const unchanged: ProjectEntry[] = [];
+  const seenPaths = new Set<string>();
+
+  for (const relPath of discoveredPaths) {
+    const absPath = path.join(scanRoot, relPath);
+    seenPaths.add(relPath);
+
+    const { type, role } = await detectRepoType(absPath);
+    const techStack = await extractTechStack(absPath, type);
+    const hasConstitution = await fs.pathExists(path.join(absPath, CONSTITUTION_FILE));
+    const hasWorkspace = await fs.pathExists(path.join(absPath, WORKSPACE_CONFIG_FILE));
+    const name = path.basename(relPath);
+
+    const prev = existingMap.get(relPath);
+    if (!prev) {
+      const entry: ProjectEntry = {
+        name,
+        path: relPath,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        firstSeen: now,
+        lastSeen: now,
+      };
+      added.push(entry);
+      existingMap.set(relPath, entry);
+    } else {
+      // Check if anything changed
+      const changed =
+        prev.type !== type ||
+        prev.role !== role ||
+        prev.hasConstitution !== hasConstitution ||
+        prev.hasWorkspace !== hasWorkspace ||
+        JSON.stringify(prev.techStack.sort()) !== JSON.stringify(techStack.sort());
+
+      const entry: ProjectEntry = {
+        ...prev,
+        type,
+        role,
+        techStack,
+        hasConstitution,
+        hasWorkspace,
+        lastSeen: now,
+        missing: undefined, // clear missing flag if it came back
+      };
+      existingMap.set(relPath, entry);
+
+      if (changed) {
+        updated.push(entry);
+      } else {
+        unchanged.push(entry);
+      }
+    }
+  }
+
+  // Mark previously known projects as missing if their directory is gone
+  const nowMissing: ProjectEntry[] = [];
+  for (const [relPath, entry] of existingMap) {
+    if (!seenPaths.has(relPath) && !entry.missing) {
+      const gone: ProjectEntry = { ...entry, missing: true };
+      existingMap.set(relPath, gone);
+      nowMissing.push(gone);
+    }
+  }
+
+  const projects = [...existingMap.values()].sort((a, b) => a.path.localeCompare(b.path));
+
+  const index: ProjectIndex = {
+    scanRoot,
+    lastScanned: now,
+    projects,
+  };
+
+  return { index, added, updated, unchanged, nowMissing };
+}

package/core/provider-utils.ts

@@ -22,14 +22,49 @@ function classifyError(err: unknown, label: string): ProviderError {
   const status = e.status ?? e.response?.status;
 
   if (status === 401 || status === 403)
-    return new ProviderError(`Auth error — check your API key (${label})`, "auth", err);
+    return new ProviderError(
+      `Auth error (${label}): API key is invalid or expired.\n` +
+      `  → Check that the correct API key is set in your environment or ~/.ai-spec-keys.json\n` +
+      `  → Run "ai-spec model" to reconfigure your provider and key`,
+      "auth", err
+    );
   if (status === 429)
-    return new ProviderError(`Rate limit hit (${label}) — try again later or switch provider`, "rate_limit", err);
+    return new ProviderError(
+      `Rate limit hit (${label}): too many requests.\n` +
+      `  → Wait a few minutes and retry, or switch to a different provider/model\n` +
+      `  → Check your provider's billing dashboard for quota status`,
+      "rate_limit", err
+    );
   if ((e as Error & { _timeout?: boolean })._timeout || e.message?.toLowerCase().includes("timed out"))
     return new ProviderError(`Request timed out (${label})`, "timeout", err);
   if (e.code === "ECONNRESET" || e.code === "ENOTFOUND" || e.code === "ECONNREFUSED")
-    return new ProviderError(`Network error — check connection/proxy (${label}): ${e.message}`, "network", err);
-  return new ProviderError(`Provider error (${label}): ${e.message}`, "provider", err);
+    return new ProviderError(
+      `Network error (${label}): ${e.message}\n` +
+      `  → Check your internet connection and proxy settings (HTTPS_PROXY)\n` +
+      `  → If behind a firewall, ensure the provider's API endpoint is reachable`,
+      "network", err
+    );
+
+  // Check for common model-not-found errors
+  const msg = e.message ?? "";
+  if (status === 404 || msg.includes("model") && (msg.includes("not found") || msg.includes("does not exist")))
+    return new ProviderError(
+      `Model not found (${label}): ${msg}\n` +
+      `  → Run "ai-spec model" to see available models for your provider\n` +
+      `  → The model name may have changed — check your provider's documentation`,
+      "provider", err
+    );
+
+  // Check for insufficient balance / quota exhaustion
+  if (msg.includes("insufficient") || msg.includes("quota") || msg.includes("balance"))
+    return new ProviderError(
+      `Quota/balance error (${label}): ${msg}\n` +
+      `  → Check your provider's billing dashboard\n` +
+      `  → Consider switching to a different provider with "ai-spec model"`,
+      "provider", err
+    );
+
+  return new ProviderError(`Provider error (${label}): ${msg}`, "provider", err);
 }
 
 function isRetryable(err: unknown): boolean {

package/core/reviewer.ts

@@ -4,10 +4,37 @@ import * as path from "path";
 import * as fs from "fs-extra";
 import { AIProvider } from "./spec-generator";
 import {
+  specComplianceSystemPrompt,
   reviewArchitectureSystemPrompt,
   reviewImplementationSystemPrompt,
   reviewImpactComplexitySystemPrompt,
 } from "../prompts/codegen.prompt";
+import { CONSTITUTION_FILE } from "./constitution-generator";
+
+// ─── Constitution Lessons Helper ──────────────────────────────────────────────
+
+/**
+ * Extract the §9 accumulated lessons section from a constitution file.
+ * Returns null if the section is absent or the file cannot be read.
+ */
+async function loadAccumulatedLessons(projectRoot: string): Promise<string | null> {
+  const constitutionPath = path.join(projectRoot, CONSTITUTION_FILE);
+  let content: string;
+  try {
+    content = await fs.readFile(constitutionPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const marker = "## 9. 积累教训";
+  const idx = content.indexOf(marker);
+  if (idx === -1) return null;
+  // Extract from §9 header to end of file (or next top-level section)
+  const section = content.slice(idx);
+  const nextSection = section.slice(marker.length).match(/\n## \d/);
+  return nextSection
+    ? section.slice(0, marker.length + nextSection.index!)
+    : section;
+}
 
 // ─── Review History ────────────────────────────────────────────────────────────
 
@@ -15,6 +42,7 @@ interface ReviewHistoryEntry {
   date: string;
   specFile: string;
   score: number;
+  complianceScore?: number;
   topIssues: string[];
   impactLevel?: "低" | "中" | "高";
   complexityLevel?: "低" | "中" | "高";
@@ -55,6 +83,18 @@ function extractScore(reviewText: string): number {
   return match ? parseFloat(match[1]) : 0;
 }
 
+/** Extract compliance score from Pass 0 output (looks for "ComplianceScore: X/10") */
+export function extractComplianceScore(complianceText: string): number {
+  const match = complianceText.match(/ComplianceScore:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return match ? parseFloat(match[1]) : 0;
+}
+
+/** Count missing requirements from Pass 0 output */
+export function extractMissingCount(complianceText: string): number {
+  const summaryMatch = complianceText.match(/Missing:\s*(\d+)/i);
+  return summaryMatch ? parseInt(summaryMatch[1], 10) : 0;
+}
+
 /** Extract impact level from Pass 3 review ("影响等级：低/中/高") */
 function extractImpactLevel(reviewText: string): "低" | "中" | "高" | undefined {
   const match = reviewText.match(/影响等级[：:]\s*(低|中|高)/);
@@ -126,8 +166,9 @@ export class CodeReviewer {
   }
 
   /**
-   * Three-pass review:
-   *   Pass 1 — architecture (spec compliance, layer separation, auth)
+   * Four-pass review:
+   *   Pass 0 — spec compliance (exhaustive requirement coverage audit)
+   *   Pass 1 — architecture (layer separation, contract design, auth posture)
    *   Pass 2 — implementation details (validation, error handling, edge cases)
    *             + historical issue recurrence check
    *   Pass 3 — impact assessment + code complexity
@@ -137,11 +178,43 @@ export class CodeReviewer {
     codeContext: string,
     specFile?: string
   ): Promise<string> {
-    console.log(chalk.gray("  Pass 1/3: Architecture review..."));
+    // ── Pass 0: Spec Compliance (skip if no spec provided) ───────────────────
+    let complianceReview = "";
+    if (specContent && specContent.trim() && specContent !== "(No spec — review for general code quality)") {
+      console.log(chalk.gray("  Pass 0/3: Spec compliance check..."));
+      const compliancePrompt = `Check whether the implementation covers every requirement in the spec.
 
-    // ── Pass 1: Architecture ──────────────────────────────────────────────────
-    const archPrompt = `Review the architecture of this change.
+=== Feature Spec ===
+${specContent}
+
+=== Code ===
+${codeContext}`;
+      complianceReview = await this.provider.generate(compliancePrompt, specComplianceSystemPrompt);
+
+      // Surface compliance score immediately
+      const complianceScore = extractComplianceScore(complianceReview);
+      const missingCount = extractMissingCount(complianceReview);
+      if (complianceScore > 0) {
+        const scoreColor = complianceScore >= 8 ? chalk.green : complianceScore >= 6 ? chalk.yellow : chalk.red;
+        console.log(
+          chalk.gray("  Pass 0 result: ") +
+          scoreColor(`ComplianceScore ${complianceScore}/10`) +
+          (missingCount > 0 ? chalk.red(` · ${missingCount} missing requirement(s)`) : chalk.green(" · all requirements covered"))
+        );
+      }
+    }
 
+    console.log(chalk.gray(`  Pass 1/3: Architecture review...`));
+
+    // ── Pass 1: Architecture (+ §9 lessons cross-check) ──────────────────────
+    const accumulatedLessons = await loadAccumulatedLessons(this.projectRoot);
+    const archPrompt = `Review the architecture of this change.
+${complianceReview
+  ? `\n=== Spec Compliance Report (Pass 0 — already audited, do NOT re-audit missing requirements) ===\n${complianceReview}\n`
+  : ""}
+${accumulatedLessons
+  ? `\n=== §9 历史积累教训 (Accumulated Lessons — check if any are repeated in this code) ===\n${accumulatedLessons}\n`
+  : ""}
 === Feature Spec ===
 ${specContent || "(No spec — review for general code quality)"}
 
@@ -189,10 +262,14 @@ ${implReview}`;
 
     // ── Combine ───────────────────────────────────────────────────────────────
     const sep = "─".repeat(52);
-    const combined = `${archReview}\n\n${sep}\n\n${implReview}\n\n${sep}\n\n${impactReview}`;
+    const parts = complianceReview
+      ? [complianceReview, archReview, implReview, impactReview]
+      : [archReview, implReview, impactReview];
+    const combined = parts.join(`\n\n${sep}\n\n`);
 
     // ── Persist history ───────────────────────────────────────────────────────
     const score = extractScore(implReview) || extractScore(archReview);
+    const complianceScore = extractComplianceScore(complianceReview);
     const topIssues = extractTopIssues(implReview);
     const impactLevel = extractImpactLevel(impactReview);
     const complexityLevel = extractComplexityLevel(impactReview);
@@ -201,6 +278,7 @@ ${implReview}`;
         date: new Date().toISOString().slice(0, 10),
         specFile: path.relative(this.projectRoot, specFile),
         score,
+        ...(complianceScore > 0 ? { complianceScore } : {}),
         topIssues,
         ...(impactLevel ? { impactLevel } : {}),
         ...(complexityLevel ? { complexityLevel } : {}),