ai-spec-dev 0.17.0 → 0.24.0

package/dist/cli/index.mjs

@@ -96,9 +96,17 @@ CRITICAL \u2014 Route/Store index registration (MUST follow):
 
 CRITICAL \u2014 Cross-file function name consistency (MUST follow):
 17. When you see an "=== Files Already Generated in This Run ===" section, those file contents are the AUTHORITATIVE source
-    of truth for exported function/variable names.
-    NEVER rename, guess, or substitute alternative names. If the file exports "getTaskList", import "getTaskList" \u2014 not "getTasks".
-    If no such section is present, derive function names strictly from the DSL endpoint IDs shown in the spec.`;
+    of truth for exported function/variable/action names.
+    NEVER rename, guess, or substitute alternative names. Copy-paste the exact identifier.
+    Common hallucination patterns to AVOID:
+    - Adding suffixes: fetchTasks \u2192 fetchTaskList, fetchTaskData, fetchTaskAll  \u2190 ALL WRONG
+    - Changing verb: fetchTasks \u2192 getTasks, loadTasks, queryTasks  \u2190 WRONG unless that's in the cache
+    - Changing number: createTask \u2192 createTasks  \u2190 WRONG
+    For Pinia stores specifically: the "// public API (return object):" section or the full store content
+    shows EVERY available action name. If it shows "fetchTasks", that is the ONLY valid name.
+    If no such section is present, derive function names strictly from the DSL endpoint IDs shown in the spec.
+    ALSO applies to file paths: if you see "// exists: src/views/task-management/TaskManagement.vue",
+    the router import MUST use that exact path \u2014 NOT "@/views/task-management/index.vue" or any other guess.`;
     codeGenGoSystemPrompt = `You are a Senior Go Developer implementing features based on provided specifications.
 
 Rules:
@@ -4068,7 +4076,7 @@ ${content.slice(0, 1500)}`);
         try {
           const content = await fs3.readFile(path2.join(this.projectRoot, f), "utf-8");
           parts.push(`// ${f}
-${content.slice(0, 800)}`);
+${content.slice(0, 2e3)}`);
         } catch {
         }
       }
@@ -4473,7 +4481,7 @@ Each task object must have these exact fields:
   "id": "TASK-001",           // sequential, zero-padded
   "title": "...",             // short action phrase, e.g. "Add UserFavorite Prisma model"
   "description": "...",       // 1-2 sentences, specific and actionable
-  "layer": "data|service|api|test|infra",  // implementation layer
+  "layer": "data|service|api|view|route|test|infra",  // implementation layer
   "filesToTouch": ["..."],    // VERIFIED paths only \u2014 see rules below
   "acceptanceCriteria": ["..."],  // verifiable completion conditions
   "dependencies": ["TASK-001"],  // task ids that must complete first (empty array if none)
@@ -4481,11 +4489,34 @@ Each task object must have these exact fields:
 }
 
 Layer ordering guidance (implement in this order):
-1. "data"    \u2014 DB schema changes, migrations, seed data
+1. "data"    \u2014 DB schema changes, migrations, seed data; TypeScript type/interface definition files
 2. "infra"   \u2014 config, env vars, external service setup
-3. "service" \u2014 business logic, service classes
-4. "api"     \u2014 controllers, routes, middleware, validators
-5. "test"    \u2014 unit tests, integration tests
+3. "service" \u2014 business logic, service classes; for frontend: HTTP API call files ONLY (src/api/ or src/apis/)
+4. "api"     \u2014 controllers, routes, middleware, validators; for frontend: state stores ONLY (src/stores/, Pinia/Vuex/Zustand/Redux)
+5. "view"    \u2014 FRONTEND ONLY: page/view components (src/views/, src/pages/) \u2014 generated AFTER stores
+6. "route"   \u2014 FRONTEND ONLY: router module files (src/router/routes/) \u2014 generated AFTER view components
+7. "test"    \u2014 unit tests, integration tests
+
+CRITICAL \u2014 Frontend four-layer dependency rule (prevents BOTH naming AND filename hallucinations):
+For Vue/React frontend projects, STRICTLY follow this assignment:
+  "service" \u2192 src/api/* or src/apis/* files   (HTTP functions: getTaskList, createTask)
+  "api"     \u2192 src/stores/* files               (stores call service layer \u2014 see exact function names)
+  "view"    \u2192 src/views/* or src/pages/* files (pages use stores \u2014 see exact action names)
+  "route"   \u2192 src/router/routes/* files        (router imports views \u2014 sees EXACT component filenames)
+
+WHY "route" must come after "view":
+The router file imports the view component by filename, e.g.:
+  import('@/views/task-management/TaskManagement.vue')
+If the router is generated BEFORE the view file exists in cache, the AI will guess a generic name
+like "index.vue" (the most common fallback) instead of the real filename "TaskManagement.vue".
+By generating the router AFTER the view, the cache contains "// exists: src/views/task-management/TaskManagement.vue"
+and the AI uses the EXACT path.
+
+EXAMPLE (correct, four-layer):
+  TASK-001 layer:"service"  src/apis/taskManagement.ts        (exports getTaskList, createTask)
+  TASK-002 layer:"api"      src/stores/taskStore.ts            (calls getTaskList \u2014 visible in cache \u2713)
+  TASK-003 layer:"view"     src/views/task-management/TaskManagement.vue  (uses taskStore \u2014 visible in cache \u2713)
+  TASK-004 layer:"route"    src/router/routes/taskManagement.ts (imports TaskManagement.vue \u2014 filename visible in cache \u2713)
 
 CRITICAL \u2014 filesToTouch Rules (hallucination prevention):
 - ONLY use paths that appear in the "Verified File Inventory" section of the prompt.
@@ -4535,7 +4566,7 @@ function buildTaskPrompt(spec, context) {
   if (context.constitution) {
     parts.push(`
 === Project Constitution (rules to follow) ===
-${context.constitution.slice(0, 1500)}`);
+${context.constitution}`);
   }
   if (context.techStack.length > 0) {
     parts.push(`
@@ -4550,7 +4581,9 @@ var LAYER_ORDER = {
   infra: 1,
   service: 2,
   api: 3,
-  test: 4
+  view: 4,
+  route: 5,
+  test: 6
 };
 var TaskGenerator = class {
   constructor(provider) {
@@ -4592,6 +4625,8 @@ function printTasks(tasks) {
     infra: chalk3.gray,
     service: chalk3.blue,
     api: chalk3.cyan,
+    view: chalk3.yellow,
+    route: chalk3.white,
     test: chalk3.green
   };
   console.log(chalk3.bold(`
@@ -5811,16 +5846,111 @@ function buildInstalledPackagesSection(context) {
 ${context.dependencies.join(", ")}
 `;
 }
+function extractBehavioralContract(content) {
+  const lines = content.split("\n");
+  const contractLines = [];
+  const throwLines = [];
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+    if (/^export\s+(interface|type|class|abstract\s+class|enum)\s/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      if (trimmed.includes("{")) {
+        let depth = (trimmed.match(/\{/g) ?? []).length - (trimmed.match(/\}/g) ?? []).length;
+        i++;
+        while (i < lines.length && depth > 0) {
+          const inner = lines[i];
+          contractLines.push(inner.trimEnd());
+          depth += (inner.match(/\{/g) ?? []).length;
+          depth -= (inner.match(/\}/g) ?? []).length;
+          i++;
+        }
+      } else {
+        i++;
+      }
+      continue;
+    }
+    if (/^export\s+const\s+\w+\s*=\s*(defineStore|createStore|createSlice)\s*\(/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      let depth = (trimmed.match(/\(/g) ?? []).length - (trimmed.match(/\)/g) ?? []).length;
+      i++;
+      while (i < lines.length && depth > 0) {
+        const inner = lines[i];
+        contractLines.push(inner.trimEnd());
+        depth += (inner.match(/\(/g) ?? []).length;
+        depth -= (inner.match(/\)/g) ?? []).length;
+        i++;
+      }
+      continue;
+    }
+    if (/^return\s*\{/.test(trimmed)) {
+      contractLines.push("// public API (return object):");
+      contractLines.push(line.trimEnd());
+      let depth = (trimmed.match(/\{/g) ?? []).length - (trimmed.match(/\}/g) ?? []).length;
+      i++;
+      while (i < lines.length && depth > 0) {
+        const inner = lines[i];
+        contractLines.push(inner.trimEnd());
+        depth += (inner.match(/\{/g) ?? []).length;
+        depth -= (inner.match(/\}/g) ?? []).length;
+        i++;
+      }
+      continue;
+    }
+    if (/^export\s+default\s+(async\s+)?(function|class)\b/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+      if (trimmed.includes("{")) {
+        let depth = (trimmed.match(/\{/g) ?? []).length - (trimmed.match(/\}/g) ?? []).length;
+        i++;
+        while (i < lines.length && depth > 0) {
+          const inner = lines[i];
+          contractLines.push(inner.trimEnd());
+          depth += (inner.match(/\{/g) ?? []).length;
+          depth -= (inner.match(/\}/g) ?? []).length;
+          i++;
+        }
+      } else {
+        i++;
+      }
+      continue;
+    }
+    if (/^export\s/.test(trimmed)) {
+      contractLines.push(line.trimEnd());
+    }
+    if (/throw\s+(new\s+)?\w*[Ee]rror\b|throw\s+create[A-Z]\w*|@throws/.test(line) && throwLines.length < 20) {
+      throwLines.push("  // " + trimmed);
+    }
+    i++;
+  }
+  if (contractLines.length === 0 && throwLines.length === 0) {
+    return content.slice(0, 3e3);
+  }
+  const parts = [...contractLines];
+  if (throwLines.length > 0) {
+    parts.push("", "// Error contracts (throws / validation):", ...throwLines);
+  }
+  return parts.join("\n");
+}
 function buildGeneratedFilesSection(cache) {
   if (cache.size === 0) return "";
   const lines = [
-    "\n=== Files Already Generated in This Run \u2014 USE EXACT EXPORTS (do not rename or invent alternatives) ==="
+    "\n=== Files Already Generated in This Run \u2014 USE EXACT EXPORTS (do not rename or invent alternatives) ===",
+    "// CRITICAL: function/action names and file paths below are ground truth. Copy them EXACTLY.",
+    "// Do NOT add suffixes (List, Data, All, Info) or change casing.",
+    "// For '// exists:' entries: use the EXACT filename shown \u2014 do NOT substitute index.vue or other defaults."
   ];
   for (const [filePath, content] of cache) {
+    const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(filePath);
+    if (isViewFile) {
+      lines.push(`
+// exists: ${filePath}`);
+      continue;
+    }
     lines.push(`
 --- ${filePath} ---`);
-    lines.push(content.slice(0, 800));
-    if (content.length > 800) lines.push("... (truncated)");
+    const isStoreOrComposable = /src[\\/](stores?|composables?)[\\/]/i.test(filePath);
+    lines.push(isStoreOrComposable ? content : extractBehavioralContract(content));
   }
   return lines.join("\n") + "\n";
 }
@@ -6008,7 +6138,7 @@ Implement ONLY this task. Do not implement other tasks.`;
     const spec = await fs8.readFile(specFilePath, "utf-8");
     const constitutionSection = context?.constitution ? `
 === Project Constitution (MUST follow) ===
-${context.constitution.slice(0, 2e3)}
+${context.constitution}
 ` : "";
     const contextSummary = context ? `Tech Stack: ${context.techStack.join(", ")}
 Existing files: ${context.fileStructure.slice(0, 20).join(", ")}` : "";
@@ -6102,7 +6232,7 @@ Output ONLY a valid JSON array:
         printTaskProgress(completedTasks++, tasks.length, task, "skip");
       }
     }
-    const LAYER_ORDER2 = ["data", "infra", "service", "api", "test"];
+    const LAYER_ORDER2 = ["data", "infra", "service", "api", "view", "route", "test"];
     const layerGroups = [];
     for (const layer of LAYER_ORDER2) {
       const group = pendingTasks.filter((t) => t.layer === layer);
@@ -6125,10 +6255,9 @@ Output ONLY a valid JSON array:
       } else {
         printTaskProgress(completedTasks, tasks.length, layerTasks[0], "run");
       }
-      const generatedFilesSection = buildGeneratedFilesSection(generatedFileCache);
-      const taskResultPromises = layerTasks.map(async (task) => {
+      const executeTask = async (task, batchIsParallel) => {
         if (task.filesToTouch.length === 0) {
-          if (!isParallel) console.log(chalk6.gray("    No files specified, skipping."));
+          if (!batchIsParallel) console.log(chalk6.gray("    No files specified, skipping."));
           return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration: false };
         }
         const filePlan = await Promise.all(
@@ -6143,10 +6272,11 @@ Output ONLY a valid JSON array:
         );
         const createsNewFiles = filePlan.some((f) => f.action === "create");
         const taskText = `${task.title} ${task.description}`.toLowerCase();
-        const impliesRegistration = createsNewFiles && (taskText.includes("route") || taskText.includes("router") || taskText.includes("page") || taskText.includes("view") || taskText.includes("store") || taskText.includes("service") || taskText.includes("component") || taskText.includes("menu") || taskText.includes("navigation") || taskText.includes("\u6A21\u5757") || taskText.includes("\u9875\u9762") || taskText.includes("\u8DEF\u7531") || taskText.includes("\u6CE8\u518C"));
+        const impliesRegistration = createsNewFiles && (task.layer === "route" || task.layer === "view" || task.layer === "api" || taskText.includes("route") || taskText.includes("router") || taskText.includes("page") || taskText.includes("view") || taskText.includes("store") || taskText.includes("service") || taskText.includes("component") || taskText.includes("menu") || taskText.includes("navigation") || taskText.includes("\u6A21\u5757") || taskText.includes("\u9875\u9762") || taskText.includes("\u8DEF\u7531") || taskText.includes("\u6CE8\u518C"));
         if (filePlan.length === 0) {
           return { task, files: [], createdFiles: [], success: 0, total: 0, impliesRegistration };
         }
+        const currentGeneratedFilesSection = buildGeneratedFilesSection(generatedFileCache);
         const taskContext = `Task: ${task.id} \u2014 ${task.title}
 ${task.description}
 Acceptance: ${task.acceptanceCriteria.join("; ")}`;
@@ -6157,15 +6287,38 @@ Acceptance: ${task.acceptanceCriteria.join("; ")}`;
 === Current Task ===
 ${taskContext}`,
           workingDir,
-          constitutionSection + frontendSection + sharedConfigSection + generatedFilesSection,
+          constitutionSection + frontendSection + sharedConfigSection + currentGeneratedFilesSection,
           systemPrompt,
-          isParallel ? task.id : void 0
+          batchIsParallel ? task.id : void 0
           // prefix output lines with task ID in parallel mode
         );
         const createdFiles = filePlan.filter((fp) => fp.action === "create").map((fp) => fp.file);
         return { task, files, createdFiles, success, total, impliesRegistration };
-      });
-      const layerResults = await Promise.all(taskResultPromises);
+      };
+      const updateCacheFromBatch = async (results) => {
+        for (const result of results) {
+          for (const writtenFile of result.files) {
+            const isCodeFile = /src[\\/](api[s]?|services?|stores?|composables?)[\\/]/i.test(writtenFile);
+            const isViewFile = /src[\\/](views?|pages?)[\\/]/i.test(writtenFile);
+            if (isCodeFile || isViewFile) {
+              try {
+                const content = isViewFile ? `// view component \u2014 use this exact path for router imports` : await fs8.readFile(path7.join(workingDir, writtenFile), "utf-8");
+                generatedFileCache.set(writtenFile, content);
+              } catch {
+              }
+            }
+          }
+        }
+      };
+      const taskBatches = topoSortLayerTasks(layerTasks);
+      const layerResults = [];
+      for (const batch of taskBatches) {
+        const batchIsParallel = batch.length > 1;
+        const batchResultPromises = batch.map((task) => executeTask(task, batchIsParallel));
+        const batchResults = await Promise.all(batchResultPromises);
+        layerResults.push(...batchResults);
+        await updateCacheFromBatch(batchResults);
+      }
       if (isParallel) {
         console.log("");
       }
@@ -6185,17 +6338,6 @@ ${taskContext}`,
         }
       }
       completedTasks += layerTasks.length;
-      for (const result of layerResults) {
-        for (const writtenFile of result.files) {
-          if (/src[\\/](api[s]?|services?|stores?|composables?)[\\/]/.test(writtenFile)) {
-            try {
-              const content = await fs8.readFile(path7.join(workingDir, writtenFile), "utf-8");
-              generatedFileCache.set(writtenFile, content);
-            } catch {
-            }
-          }
-        }
-      }
       const anyImpliesRegistration = layerResults.some((r) => r.impliesRegistration);
       if (anyImpliesRegistration && sharedConfigPaths.size > 0 && context?.sharedConfigFiles) {
         const allCreatedInLayer = layerResults.flatMap((r) => r.createdFiles);
@@ -6295,11 +6437,48 @@ ${spec}`,
     console.log(chalk6.cyan("\n") + plan);
   }
 };
+function topoSortLayerTasks(tasks) {
+  if (tasks.length <= 1) return [tasks];
+  const idSet = new Set(tasks.map((t) => t.id));
+  const taskById = new Map(tasks.map((t) => [t.id, t]));
+  const inDegree = /* @__PURE__ */ new Map();
+  const dependents = /* @__PURE__ */ new Map();
+  for (const task of tasks) {
+    inDegree.set(task.id, 0);
+    dependents.set(task.id, []);
+  }
+  for (const task of tasks) {
+    const intraDeps = task.dependencies.filter((dep) => idSet.has(dep));
+    inDegree.set(task.id, intraDeps.length);
+    for (const dep of intraDeps) {
+      dependents.get(dep).push(task.id);
+    }
+  }
+  const batches = [];
+  const remaining = new Set(tasks.map((t) => t.id));
+  while (remaining.size > 0) {
+    const batch = [...remaining].filter((id) => inDegree.get(id) === 0).map((id) => taskById.get(id));
+    if (batch.length === 0) {
+      batches.push([...remaining].map((id) => taskById.get(id)));
+      break;
+    }
+    batches.push(batch);
+    for (const task of batch) {
+      remaining.delete(task.id);
+      for (const dependent of dependents.get(task.id)) {
+        inDegree.set(dependent, inDegree.get(dependent) - 1);
+      }
+    }
+  }
+  return batches;
+}
 var LAYER_ICONS = {
   data: "\u{1F4BE}",
   infra: "\u2699\uFE0F ",
   service: "\u{1F527}",
   api: "\u{1F310}",
+  view: "\u{1F5A5}\uFE0F ",
+  route: "\u{1F5FA}\uFE0F ",
   test: "\u{1F9EA}"
 };
 function printTaskProgress(completed, total, task, mode) {
@@ -6808,7 +6987,7 @@ function parseConstitutionStats(content) {
   for (let i = section9Start + 1; i < lines.length; i++) {
     if (lines[i].match(/^## \d/) && i > section9Start) break;
     section9Lines++;
-    if (lines[i].trim().startsWith("-")) lessonCount++;
+    if (/^-\s+.*\*\*\[\d{4}-\d{2}-\d{2}\]\*\*/.test(lines[i].trim())) lessonCount++;
   }
   return { totalLines, section9Lines, lessonCount };
 }
@@ -7297,7 +7476,7 @@ function detectLintCommand(workingDir) {
 function parseErrors(output, source) {
   const errors = [];
   if (!output.trim()) return errors;
-  const lines = output.split("\n").slice(-80);
+  const lines = output.split("\n");
   for (const line of lines) {
     const trimmed = line.trim();
     if (!trimmed) continue;
@@ -7306,13 +7485,15 @@ function parseErrors(output, source) {
     if (trimmed.startsWith("at ")) continue;
     if (trimmed.startsWith("Node.js ")) continue;
     const fileMatch = trimmed.match(/^([^:]+\.(?:ts|js|tsx|jsx|go|py|java|rs|php)):\d+/);
+    if (!fileMatch) continue;
     errors.push({
       source,
-      message: trimmed.slice(0, 300),
-      file: fileMatch?.[1]
+      message: trimmed.slice(0, 400),
+      file: fileMatch[1]
     });
+    if (errors.length >= 20) break;
   }
-  return errors.slice(0, 20);
+  return errors;
 }
 async function attemptFix(provider, errors, workingDir, dsl) {
   const results = [];
@@ -7503,7 +7684,7 @@ async function assessSpec(provider, spec, constitution) {
   const prompt = `Assess the following feature specification.
 ${constitution ? `
 === Project Constitution (check consistency against this) ===
-${constitution.slice(0, 1500)}
+${constitution}
 ` : ""}
 === Feature Spec ===
 ${spec}`;
@@ -7622,6 +7803,42 @@ async function appendLessonsToConstitution(projectRoot, issues) {
     );
   }
 }
+async function appendDirectLesson(projectRoot, lessonText) {
+  const constitutionPath = path14.join(projectRoot, CONSTITUTION_FILE);
+  let content = "";
+  try {
+    content = await fs15.readFile(constitutionPath, "utf-8");
+  } catch {
+    return { appended: false, reason: "No constitution file found. Run `ai-spec init` first." };
+  }
+  const normalized = lessonText.toLowerCase().slice(0, 60);
+  if (content.toLowerCase().includes(normalized)) {
+    return { appended: false, reason: "Similar lesson already exists in the constitution." };
+  }
+  const date = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
+  const entry = `- \u{1F4DD} **[${date}]** ${lessonText.trim()}`;
+  const hasMemorySection = content.includes(MEMORY_SECTION_MARKER);
+  let updatedContent;
+  if (hasMemorySection) {
+    const sectionStart = content.indexOf(MEMORY_SECTION_MARKER);
+    const afterHeader = sectionStart + MEMORY_SECTION_HEADER.length;
+    const nextSectionMatch = content.slice(afterHeader).match(/\n## \d/);
+    const insertPos = nextSectionMatch ? afterHeader + nextSectionMatch.index : content.length;
+    updatedContent = content.slice(0, insertPos) + entry + "\n" + content.slice(insertPos);
+  } else {
+    updatedContent = content + MEMORY_SECTION_HEADER + entry + "\n";
+  }
+  await fs15.writeFile(constitutionPath, updatedContent, "utf-8");
+  const stats = parseConstitutionStats(updatedContent);
+  if (stats.lessonCount >= 8) {
+    console.log(
+      chalk14.yellow(
+        `  \u26A0 \xA79 now has ${stats.lessonCount} lessons. Run \`ai-spec init --consolidate\` to prune and rebase.`
+      )
+    );
+  }
+  return { appended: true };
+}
 async function accumulateReviewKnowledge(provider, projectRoot, reviewText) {
   console.log(chalk14.blue("\n\u2500\u2500\u2500 Knowledge Memory \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   const issues = extractIssuesFromReview(reviewText);
@@ -8290,6 +8507,7 @@ Existing API/service files:`);
 // core/mock-server-generator.ts
 import * as path18 from "path";
 import * as fs19 from "fs-extra";
+import { spawn } from "child_process";
 function typeToFixture(fieldName, typeDesc) {
   const t = typeDesc.toLowerCase();
   if (t.includes("boolean") || t === "bool") return true;
@@ -8616,6 +8834,151 @@ import { handlers } from './handlers';
 export const worker = setupWorker(...handlers);
 `;
 }
+var MOCK_LOCK_FILE = ".ai-spec-mock.lock.json";
+function findViteConfigFile(projectDir) {
+  for (const f of ["vite.config.ts", "vite.config.mts", "vite.config.js", "vite.config.mjs"]) {
+    if (fs19.existsSync(path18.join(projectDir, f))) return f;
+  }
+  return null;
+}
+function buildViteProxyEntries(endpoints, mockPort) {
+  const prefixes = /* @__PURE__ */ new Set();
+  for (const ep of endpoints) {
+    const parts = ep.path.split("/").filter(Boolean);
+    if (parts.length > 0) prefixes.add(`/${parts[0]}`);
+  }
+  if (prefixes.size === 0) prefixes.add("/api");
+  const target = `http://localhost:${mockPort}`;
+  return Array.from(prefixes).map((p) => `        '${p}': { target: '${target}', changeOrigin: true },`).join("\n");
+}
+function generateViteMockConfigTs(baseConfigFile, mockPort, endpoints) {
+  const importPath = `./${baseConfigFile.replace(/\.(ts|mts|js|mjs)$/, "")}`;
+  const proxyEntries = buildViteProxyEntries(endpoints, mockPort);
+  return `// Auto-generated by ai-spec mock --serve
+// LOCAL DEVELOPMENT ONLY \u2014 do not commit this file
+// Remove with: ai-spec mock --restore
+import { defineConfig, mergeConfig } from 'vite';
+
+export default defineConfig(async (env) => {
+  const mod = await import('${importPath}');
+  const baseConfigOrFn = mod.default;
+  const baseConfig =
+    typeof baseConfigOrFn === 'function'
+      ? await baseConfigOrFn(env)
+      : baseConfigOrFn;
+
+  return mergeConfig(baseConfig ?? {}, {
+    server: {
+      proxy: {
+${proxyEntries}
+      },
+    },
+  });
+});
+`;
+}
+async function applyMockProxy(frontendDir, mockPort, endpoints = []) {
+  const framework = detectFrontendFramework(frontendDir);
+  const actions = [];
+  if (framework === "vite") {
+    const viteConfigFile = findViteConfigFile(frontendDir) ?? "vite.config.ts";
+    const mockConfigContent = generateViteMockConfigTs(viteConfigFile, mockPort, endpoints);
+    const mockConfigPath = path18.join(frontendDir, "vite.config.ai-spec-mock.ts");
+    await fs19.writeFile(mockConfigPath, mockConfigContent, "utf-8");
+    actions.push({ type: "wrote-file", filePath: "vite.config.ai-spec-mock.ts" });
+    const pkgPath = path18.join(frontendDir, "package.json");
+    if (await fs19.pathExists(pkgPath)) {
+      const pkg = await fs19.readJson(pkgPath);
+      pkg.scripts = pkg.scripts ?? {};
+      const originalValue = pkg.scripts["dev:mock"] ?? null;
+      pkg.scripts["dev:mock"] = "vite --config vite.config.ai-spec-mock.ts";
+      await fs19.writeJson(pkgPath, pkg, { spaces: 2 });
+      actions.push({ type: "added-pkg-script", key: "dev:mock", originalValue });
+    }
+    const lock2 = { framework, mockPort, frontendDir, actions };
+    await fs19.writeJson(path18.join(frontendDir, MOCK_LOCK_FILE), lock2, { spaces: 2 });
+    return { framework, applied: true, devCommand: "npm run dev:mock" };
+  }
+  if (framework === "cra") {
+    const pkgPath = path18.join(frontendDir, "package.json");
+    if (await fs19.pathExists(pkgPath)) {
+      const pkg = await fs19.readJson(pkgPath);
+      const originalProxy = pkg.proxy ?? null;
+      pkg.proxy = `http://localhost:${mockPort}`;
+      await fs19.writeJson(pkgPath, pkg, { spaces: 2 });
+      actions.push({ type: "patched-pkg-proxy", originalProxy });
+      const lock2 = { framework, mockPort, frontendDir, actions };
+      await fs19.writeJson(path18.join(frontendDir, MOCK_LOCK_FILE), lock2, { spaces: 2 });
+      return { framework, applied: true, devCommand: "npm start" };
+    }
+    return { framework, applied: false, devCommand: null, note: "No package.json found." };
+  }
+  const lock = { framework, mockPort, frontendDir, actions };
+  await fs19.writeJson(path18.join(frontendDir, MOCK_LOCK_FILE), lock, { spaces: 2 });
+  const manualNote = framework === "next" ? `Add rewrites in next.config.js to proxy API calls to http://localhost:${mockPort}` : `Add proxy in webpack.config.js devServer to target http://localhost:${mockPort}`;
+  return { framework, applied: false, devCommand: null, note: manualNote };
+}
+async function restoreMockProxy(frontendDir) {
+  const lockPath = path18.join(frontendDir, MOCK_LOCK_FILE);
+  if (!await fs19.pathExists(lockPath)) {
+    return { restored: false, note: "No lock file found \u2014 nothing to restore." };
+  }
+  const lock = await fs19.readJson(lockPath);
+  for (const action of lock.actions) {
+    if (action.type === "wrote-file") {
+      const fp = path18.join(frontendDir, action.filePath);
+      if (await fs19.pathExists(fp)) await fs19.remove(fp);
+    } else if (action.type === "added-pkg-script") {
+      const pkgPath = path18.join(frontendDir, "package.json");
+      if (await fs19.pathExists(pkgPath)) {
+        const pkg = await fs19.readJson(pkgPath);
+        if (action.originalValue == null) {
+          delete pkg.scripts?.[action.key];
+        } else {
+          pkg.scripts = pkg.scripts ?? {};
+          pkg.scripts[action.key] = action.originalValue;
+        }
+        await fs19.writeJson(pkgPath, pkg, { spaces: 2 });
+      }
+    } else if (action.type === "patched-pkg-proxy") {
+      const pkgPath = path18.join(frontendDir, "package.json");
+      if (await fs19.pathExists(pkgPath)) {
+        const pkg = await fs19.readJson(pkgPath);
+        if (action.originalProxy == null) {
+          delete pkg.proxy;
+        } else {
+          pkg.proxy = action.originalProxy;
+        }
+        await fs19.writeJson(pkgPath, pkg, { spaces: 2 });
+      }
+    }
+  }
+  if (lock.mockServerPid) {
+    try {
+      process.kill(lock.mockServerPid, "SIGTERM");
+    } catch {
+    }
+  }
+  await fs19.remove(lockPath);
+  return { restored: true };
+}
+function startMockServerBackground(serverJsPath, port) {
+  const child = spawn("node", [serverJsPath], {
+    detached: true,
+    stdio: "ignore",
+    env: { ...process.env, MOCK_PORT: String(port) }
+  });
+  child.unref();
+  return child.pid;
+}
+async function saveMockServerPid(frontendDir, pid) {
+  const lockPath = path18.join(frontendDir, MOCK_LOCK_FILE);
+  if (await fs19.pathExists(lockPath)) {
+    const lock = await fs19.readJson(lockPath);
+    lock.mockServerPid = pid;
+    await fs19.writeJson(lockPath, lock, { spaces: 2 });
+  }
+}
 async function generateMockAssets(dsl, projectDir, opts = {}) {
   const port = opts.port ?? 3001;
   const outputDir = path18.join(projectDir, opts.outputDir ?? "mock");
@@ -8752,7 +9115,7 @@ Rules:
 function buildSpecUpdatePrompt(changeRequest, existingSpec, existingDsl, context) {
   const constitutionSection = context?.constitution ? `
 === Project Constitution (all changes must comply) ===
-${context.constitution.slice(0, 1500)}
+${context.constitution}
 ` : "";
   const dslSummary = existingDsl ? `
 === Current DSL Summary (for reference) ===
@@ -9264,7 +9627,7 @@ program.command("create").description("Generate a feature spec and kick off code
 ).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 \u2014 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").action(async (idea, opts) => {
+).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 \u2014 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, opts) => {
   const currentDir = process.cwd();
   const config2 = await loadConfig(currentDir);
   if (!idea) {
@@ -9279,7 +9642,42 @@ program.command("create").description("Generate a feature spec and kick off code
     console.log(chalk17.cyan(`
 [Workspace] Detected workspace: ${workspaceConfig.name}`));
     console.log(chalk17.gray(`  Repos: ${workspaceConfig.repos.map((r) => r.name).join(", ")}`));
-    await runMultiRepoPipeline(idea, workspaceConfig, opts, currentDir, config2);
+    const pipelineResults = await runMultiRepoPipeline(idea, workspaceConfig, opts, currentDir, config2);
+    if (opts.serve) {
+      console.log(chalk17.blue("\n\u2500\u2500\u2500 Auto-serve: starting mock server \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+      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(chalk17.yellow("  No successful backend with DSL found \u2014 skipping auto-serve."));
+      } else {
+        const mockPort = 3001;
+        const mockResult = await generateMockAssets(backendResult.dsl, backendResult.repoAbsPath, { port: mockPort });
+        const serverJsPath = path21.join(backendResult.repoAbsPath, "mock", "server.js");
+        console.log(chalk17.green(`  \u2714 Mock assets generated (${mockResult.files.length} file(s))`));
+        const pid = startMockServerBackground(serverJsPath, mockPort);
+        console.log(chalk17.green(`  \u2714 Mock server started (PID ${pid}) \u2192 http://localhost:${mockPort}`));
+        if (frontendResult) {
+          const proxyResult = await applyMockProxy(frontendResult.repoAbsPath, mockPort, backendResult.dsl.endpoints);
+          await saveMockServerPid(frontendResult.repoAbsPath, pid);
+          if (proxyResult.applied) {
+            console.log(chalk17.green(`  \u2714 Frontend proxy patched (${proxyResult.framework})`));
+            console.log(chalk17.bold.cyan(`
+  Ready! Run your frontend dev server:`));
+            console.log(chalk17.white(`    cd ${frontendResult.repoAbsPath}`));
+            console.log(chalk17.white(`    ${proxyResult.devCommand}`));
+            console.log(chalk17.gray(`
+  When done, restore: ai-spec mock --restore --frontend ${frontendResult.repoAbsPath}`));
+          } else {
+            console.log(chalk17.yellow(`  \u26A0 Auto-patch not available for ${proxyResult.framework}.`));
+            if (proxyResult.note) console.log(chalk17.gray(`    ${proxyResult.note}`));
+            console.log(chalk17.gray(`    Mock server: http://localhost:${mockPort}`));
+          }
+        } else {
+          console.log(chalk17.gray(`  No frontend repo found \u2014 mock server is running at http://localhost:${mockPort}`));
+          console.log(chalk17.gray(`  Configure your frontend proxy manually to point to http://localhost:${mockPort}`));
+        }
+      }
+    }
     return;
   }
   const specProviderName = opts.provider || config2.provider || "gemini";
@@ -9308,6 +9706,9 @@ program.command("create").description("Generate a feature spec and kick off code
   }
   if (context.constitution) {
     console.log(chalk17.green(`  Constitution : found (.ai-spec-constitution.md)`));
+    if (context.constitution.length > 6e3) {
+      console.log(chalk17.yellow(`  \u26A0 Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+    }
   } else {
     console.log(chalk17.yellow("  Constitution : not found \u2014 auto-generating..."));
     try {
@@ -9357,12 +9758,32 @@ program.command("create").description("Generate a feature spec and kick off code
     finalSpec = await refiner.refineLoop(initialSpec);
   }
   const featureSlug = slugify(idea);
-  if (!opts.auto && !opts.skipAssessment) {
-    console.log(chalk17.blue("\n[3.4/6] Spec quality assessment..."));
+  const minScore = config2.minSpecScore ?? 0;
+  const shouldRunAssessment = !opts.skipAssessment && (!opts.auto || minScore > 0);
+  if (shouldRunAssessment) {
+    if (!opts.auto) {
+      console.log(chalk17.blue("\n[3.4/6] Spec quality assessment..."));
+    }
     const assessment = await assessSpec(specProvider, finalSpec, context.constitution ?? void 0);
     if (assessment) {
-      printSpecAssessment(assessment);
-    } else {
+      if (!opts.auto) printSpecAssessment(assessment);
+      if (minScore > 0 && assessment.overallScore < minScore) {
+        if (opts.force) {
+          console.log(chalk17.yellow(`
+  \u26A0 Score gate: ${assessment.overallScore}/10 < minimum ${minScore}/10 \u2014 bypassed with --force.`));
+        } else {
+          console.log(chalk17.red(`
+  \u2718 Spec quality gate failed: overallScore ${assessment.overallScore}/10 < minimum ${minScore}/10`));
+          if (!opts.auto) {
+            console.log(chalk17.gray(`  Address the issues above and re-run, or use --force to bypass.`));
+          } else {
+            console.log(chalk17.gray(`  Auto mode: gate enforced. Fix the spec or lower minSpecScore, or use --force to bypass.`));
+          }
+          console.log(chalk17.gray(`  Gate threshold set in .ai-spec.json \u2192 "minSpecScore": ${minScore}`));
+          process.exit(1);
+        }
+      }
+    } else if (!opts.auto) {
       console.log(chalk17.gray("  (Assessment skipped \u2014 AI call failed or timed out)"));
     }
   }
@@ -9696,7 +10117,7 @@ program.command("init").description(`Analyze codebase and generate Project Const
 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("--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) => {
+).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 = path21.join(currentDir, CONFIG_FILE);
   if (opts.clearKeys) {
@@ -9746,6 +10167,14 @@ File: ${KEY_STORE_FILE}`));
   if (opts.codegen) updated.codegen = opts.codegen;
   if (opts.codegenProvider) updated.codegenProvider = opts.codegenProvider;
   if (opts.codegenModel) updated.codegenModel = opts.codegenModel;
+  if (opts.minSpecScore !== void 0) {
+    const score = parseInt(opts.minSpecScore, 10);
+    if (isNaN(score) || score < 0 || score > 10) {
+      console.error(chalk17.red("  --min-spec-score must be a number between 0 and 10"));
+      process.exit(1);
+    }
+    updated.minSpecScore = score;
+  }
   await fs22.writeJson(configPath, updated, { spaces: 2 });
   console.log(chalk17.green(`\u2714 Config saved to ${configPath}`));
   console.log(JSON.stringify(updated, null, 2));
@@ -9889,6 +10318,9 @@ async function runSingleRepoPipelineInWorkspace(opts) {
   const { type: detectedRepoType } = await detectRepoType(repoAbsPath);
   console.log(chalk17.gray(`    Tech stack: ${context.techStack.join(", ") || "unknown"} [${detectedRepoType}]`));
   console.log(chalk17.gray(`    Dependencies: ${context.dependencies.length} packages`));
+  if (context.constitution && context.constitution.length > 6e3) {
+    console.log(chalk17.yellow(`    \u26A0 Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+  }
   if (!context.constitution) {
     console.log(chalk17.yellow(`    Constitution: not found \u2014 auto-generating...`));
     try {
@@ -10109,7 +10541,7 @@ async function runMultiRepoPipeline(idea, workspace, opts, currentDir, config2)
     const repoConfig = workspace.repos.find((r) => r.name === repoReq.repoName);
     if (!repoConfig) {
       console.log(chalk17.yellow(`  Skipping ${repoReq.repoName} \u2014 not found in workspace config.`));
-      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null });
+      results.push({ repoName: repoReq.repoName, status: "skipped", specFile: null, dsl: null, repoAbsPath: "", role: repoReq.role });
       continue;
     }
     const repoAbsPath = workspaceLoader.resolveAbsPath(repoConfig);
@@ -10160,11 +10592,11 @@ async function runMultiRepoPipeline(idea, workspace, opts, currentDir, config2)
         contractDsls.set(repoReq.repoName, dsl);
         console.log(chalk17.green(`    Contract stored for downstream repos.`));
       }
-      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl });
+      results.push({ repoName: repoReq.repoName, status: "success", specFile, dsl, repoAbsPath, role: repoReq.role });
       console.log(chalk17.green(`  \u2714 ${repoReq.repoName} complete`));
     } catch (err) {
       console.error(chalk17.red(`  \u2718 ${repoReq.repoName} failed: ${err.message}`));
-      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null });
+      results.push({ repoName: repoReq.repoName, status: "failed", specFile: null, dsl: null, repoAbsPath, role: repoReq.role });
     }
   }
   console.log(chalk17.bold.green("\n\u2714 Multi-repo pipeline complete!"));
@@ -10176,6 +10608,7 @@ async function runMultiRepoPipeline(idea, workspace, opts, currentDir, config2)
     const specInfo = r.specFile ? chalk17.gray(` \u2192 ${r.specFile}`) : "";
     console.log(`  ${icon} ${r.repoName} (${r.status})${specInfo}`);
   }
+  return results;
 }
 var workspaceCmd = program.command("workspace").description("Manage multi-repo workspace configuration");
 workspaceCmd.command("init").description(`Interactive workspace setup \u2014 creates ${WORKSPACE_CONFIG_FILE}`).action(async () => {
@@ -10373,6 +10806,9 @@ program.command("update").description("Update an existing spec with a change req
   console.log(chalk17.gray("  Loading project context..."));
   const loader = new ContextLoader(currentDir);
   const context = await loader.loadProjectContext();
+  if (context.constitution && context.constitution.length > 6e3) {
+    console.log(chalk17.yellow(`  \u26A0 Constitution is long (${context.constitution.length.toLocaleString()} chars). Consider running: ai-spec init --consolidate`));
+  }
   const { detectRepoType: _detectRepoType } = await Promise.resolve().then(() => (init_workspace_loader(), workspace_loader_exports));
   const { type: repoType } = await _detectRepoType(currentDir);
   const updater = new SpecUpdater(provider);
@@ -10408,7 +10844,7 @@ program.command("update").description("Update an existing spec with a change req
     const specContent = await fs22.readFile(result.newSpecPath, "utf-8");
     const constitutionSection = context.constitution ? `
 === Project Constitution (MUST follow) ===
-${context.constitution.slice(0, 2e3)}
+${context.constitution}
 ` : "";
     const dslSection = result.updatedDsl ? `
 === DSL Context ===
@@ -10493,13 +10929,20 @@ program.command("export").description("Export the latest DSL to OpenAPI 3.1.0 (Y
     process.exit(1);
   }
 });
-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"
-).action(async (opts) => {
+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(chalk17.blue("\n\u2500\u2500\u2500 ai-spec mock \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+  if (opts.restore) {
+    const frontendDir = opts.frontend ? path21.resolve(opts.frontend) : currentDir;
+    const r = await restoreMockProxy(frontendDir);
+    if (r.restored) {
+      console.log(chalk17.green("  \u2714 Proxy restored and mock server stopped."));
+    } else {
+      console.log(chalk17.yellow(`  ${r.note ?? "Nothing to restore."}`));
+    }
+    return;
+  }
   if (opts.workspace) {
     const workspaceLoader = new WorkspaceLoader(currentDir);
     const workspaceConfig = await workspaceLoader.load();
@@ -10565,11 +11008,43 @@ program.command("mock").description("Generate a standalone mock server + proxy c
     console.log(chalk17.green(`    ${f.path}`));
     console.log(chalk17.gray(`      ${f.description}`));
   }
+  if (opts.serve) {
+    const serverJsPath = path21.join(currentDir, "mock", "server.js");
+    if (!await fs22.pathExists(serverJsPath)) {
+      console.error(chalk17.red("  mock/server.js not found \u2014 generation may have failed."));
+      process.exit(1);
+    }
+    const pid = startMockServerBackground(serverJsPath, port);
+    console.log(chalk17.green(`
+  \u2714 Mock server started (PID ${pid}) \u2192 http://localhost:${port}`));
+    if (opts.frontend) {
+      const frontendDir = path21.resolve(opts.frontend);
+      const proxyResult = await applyMockProxy(frontendDir, port, dsl.endpoints);
+      await saveMockServerPid(frontendDir, pid);
+      if (proxyResult.applied) {
+        console.log(chalk17.green(`  \u2714 Frontend proxy patched (${proxyResult.framework})`));
+        console.log(chalk17.bold.cyan(`
+  Ready! Open a new terminal and run:`));
+        console.log(chalk17.white(`    cd ${frontendDir}`));
+        console.log(chalk17.white(`    ${proxyResult.devCommand}`));
+        console.log(chalk17.gray(`
+  When done: ai-spec mock --restore --frontend ${frontendDir}`));
+      } else {
+        console.log(chalk17.yellow(`  \u26A0 Auto-patch not available for ${proxyResult.framework}.`));
+        if (proxyResult.note) console.log(chalk17.gray(`    ${proxyResult.note}`));
+      }
+    } else {
+      console.log(chalk17.gray(`  Tip: use --frontend <path> to also auto-patch your frontend proxy config.`));
+      console.log(chalk17.gray(`  Mock server: http://localhost:${port}`));
+    }
+    return;
+  }
   console.log(chalk17.blue("\n\u2500\u2500\u2500 Quick start \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   console.log(chalk17.white(`  1. Install express (if not already):`));
   console.log(chalk17.gray(`       npm install --save-dev express`));
   console.log(chalk17.white(`  2. Start mock server:`));
   console.log(chalk17.gray(`       node mock/server.js`));
+  console.log(chalk17.gray(`       # or: ai-spec mock --serve --frontend <path-to-frontend>`));
   console.log(chalk17.white(`  3. Configure your frontend to proxy API calls to:`));
   console.log(chalk17.gray(`       http://localhost:${port}`));
   if (opts.proxy) {
@@ -10581,6 +11056,27 @@ program.command("mock").description("Generate a standalone mock server + proxy c
     console.log(chalk17.gray(`       if (process.env.NODE_ENV === 'development') worker.start();`));
   }
 });
+program.command("learn").description("Append a lesson or engineering decision directly to constitution \xA79").argument("[lesson]", "The lesson or decision to record (prompted if omitted)").action(async (lesson) => {
+  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: (v2) => v2.trim().length > 0 || "Please enter a lesson"
+    });
+  }
+  const result = await appendDirectLesson(currentDir, lesson.trim());
+  if (result.appended) {
+    console.log(chalk17.green(`
+  \u2714 Lesson appended to constitution \xA79`));
+    console.log(chalk17.gray(`  File: .ai-spec-constitution.md`));
+  } else {
+    console.log(chalk17.yellow(`
+  \u26A0 Not appended: ${result.reason}`));
+  }
+});
 if (process.argv.length <= 2) {
   (async () => {
     const currentDir = process.cwd();