ai-spec-dev 0.33.0 → 0.36.1

package/dist/index.mjs

@@ -107,7 +107,14 @@ model ExampleModel {
 
 ---
 
-\u6839\u636E\u7528\u6237\u7684\u60F3\u6CD5\u548C\u9879\u76EE\u4E0A\u4E0B\u6587\u751F\u6210\u4E0A\u8FF0\u5B8C\u6574 Spec\u3002\u786E\u4FDD API \u8BBE\u8BA1\u4E0E\u73B0\u6709\u9879\u76EE\u7684\u8DEF\u7531\u98CE\u683C\u3001\u9519\u8BEF\u7801\u89C4\u8303\u4FDD\u6301\u4E00\u81F4\uFF0C\u6570\u636E\u6A21\u578B\u4E0E\u73B0\u6709 Prisma Schema \u534F\u8C03\u3002`;
+\u6839\u636E\u7528\u6237\u7684\u60F3\u6CD5\u548C\u9879\u76EE\u4E0A\u4E0B\u6587\u751F\u6210\u4E0A\u8FF0\u5B8C\u6574 Spec\u3002\u786E\u4FDD API \u8BBE\u8BA1\u4E0E\u73B0\u6709\u9879\u76EE\u7684\u8DEF\u7531\u98CE\u683C\u3001\u9519\u8BEF\u7801\u89C4\u8303\u4FDD\u6301\u4E00\u81F4\uFF0C\u6570\u636E\u6A21\u578B\u4E0E\u73B0\u6709 Prisma Schema \u534F\u8C03\u3002
+
+CRITICAL \u2014 \u5386\u53F2\u6559\u8BAD\u5E94\u7528\uFF08Accumulated Lessons\uFF09\uFF1A
+\u5982\u679C\u9879\u76EE\u5BAA\u6CD5\u4E2D\u5305\u542B"\xA79 \u79EF\u7D2F\u6559\u8BAD (Accumulated Lessons)"\u7AE0\u8282\uFF0C\u4F60\u5FC5\u987B\uFF1A
+1. \u5728\u751F\u6210 \xA75 API \u8BBE\u8BA1\u548C \xA76 \u6570\u636E\u6A21\u578B\u4E4B\u524D\uFF0C\u9010\u6761\u5BA1\u9605\u6240\u6709\u6559\u8BAD\u6761\u76EE
+2. \u786E\u4FDD\u672C\u6B21 Spec \u7684\u8BBE\u8BA1\u4E0D\u91CD\u8E48\u5DF2\u77E5\u95EE\u9898\uFF08\u4F8B\u5982\uFF1A\u67D0\u6559\u8BAD\u8BF4"\u907F\u514D N+1 \u67E5\u8BE2"\uFF0C\u5219\u5728 \xA78 \u5B9E\u65BD\u8981\u70B9\u4E2D\u660E\u786E\u8BF4\u660E\u6279\u91CF\u52A0\u8F7D\u7B56\u7565\uFF09
+3. \u5BF9\u4E8E\u6BCF\u6761\u76F4\u63A5\u76F8\u5173\u7684\u6559\u8BAD\uFF0C\u5728 \xA78 \u5B9E\u65BD\u8981\u70B9\u672B\u5C3E\u8FFD\u52A0\u4E00\u884C\uFF1A\u300C\u26A0 \u57FA\u4E8E\u5386\u53F2\u6559\u8BAD\uFF1A[\u7B80\u8FF0\u672C\u6B21 spec \u5982\u4F55\u89C4\u907F\u8BE5\u95EE\u9898]\u300D
+4. \u5982\u65E0\u76F8\u5173\u6559\u8BAD\uFF0C\xA78 \u4E0D\u5FC5\u8FFD\u52A0\u4EFB\u4F55\u5185\u5BB9`;
 
 // core/provider-utils.ts
 import chalk from "chalk";
@@ -124,14 +131,49 @@ function classifyError(err, label) {
   const e = err;
   const status = e.status ?? e.response?.status;
   if (status === 401 || status === 403)
-    return new ProviderError(`Auth error \u2014 check your API key (${label})`, "auth", err);
+    return new ProviderError(
+      `Auth error (${label}): API key is invalid or expired.
+  \u2192 Check that the correct API key is set in your environment or ~/.ai-spec-keys.json
+  \u2192 Run "ai-spec model" to reconfigure your provider and key`,
+      "auth",
+      err
+    );
   if (status === 429)
-    return new ProviderError(`Rate limit hit (${label}) \u2014 try again later or switch provider`, "rate_limit", err);
+    return new ProviderError(
+      `Rate limit hit (${label}): too many requests.
+  \u2192 Wait a few minutes and retry, or switch to a different provider/model
+  \u2192 Check your provider's billing dashboard for quota status`,
+      "rate_limit",
+      err
+    );
   if (e._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 \u2014 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}
+  \u2192 Check your internet connection and proxy settings (HTTPS_PROXY)
+  \u2192 If behind a firewall, ensure the provider's API endpoint is reachable`,
+      "network",
+      err
+    );
+  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}
+  \u2192 Run "ai-spec model" to see available models for your provider
+  \u2192 The model name may have changed \u2014 check your provider's documentation`,
+      "provider",
+      err
+    );
+  if (msg.includes("insufficient") || msg.includes("quota") || msg.includes("balance"))
+    return new ProviderError(
+      `Quota/balance error (${label}): ${msg}
+  \u2192 Check your provider's billing dashboard
+  \u2192 Consider switching to a different provider with "ai-spec model"`,
+      "provider",
+      err
+    );
+  return new ProviderError(`Provider error (${label}): ${msg}`, "provider", err);
 }
 function isRetryable(err) {
   const e = err;
@@ -258,17 +300,23 @@ var PROVIDER_CATALOG = {
   },
   glm: {
     displayName: "\u667A\u8C31 GLM (Zhipu AI)",
-    description: "\u667A\u8C31 AI \u2014 GLM-5 / GLM-4 series + Z1 reasoning",
+    description: "\u667A\u8C31 AI \u2014 GLM-5.1 / GLM-5 / GLM-4 series",
     models: [
+      "glm-5.1",
+      // GLM-5.1 — latest flagship (2026)
       "glm-5",
-      // GLM-5 flagship (如不可用请确认最新 model ID)
-      "glm-5-flash",
+      // GLM-5 — premium (Max/Pro plans)
+      "glm-5-turbo",
+      // GLM-5-Turbo — fast & cost-efficient
+      "glm-4.7",
+      // GLM-4.7
+      "glm-4.6",
+      // GLM-4.6
+      "glm-4.5-air",
+      // GLM-4.5-Air — lightweight
       "glm-z1",
-      // GLM-Z1 reasoning model
-      "glm-z1-flash",
-      "glm-4-plus",
-      "glm-4-flash",
-      "glm-4-long"
+      // GLM-Z1 — reasoning model
+      "glm-z1-flash"
     ],
     envKey: "ZHIPU_API_KEY",
     baseURL: "https://open.bigmodel.cn/api/paas/v4/"
@@ -464,8 +512,15 @@ var SpecGenerator = class {
   constructor(provider) {
     this.provider = provider;
   }
-  async generateSpec(idea, context) {
+  async generateSpec(idea, context, architectureDecision) {
     const parts = [idea];
+    if (architectureDecision) {
+      parts.push(
+        `
+=== Architecture Decision (MUST follow this approach in the spec) ===
+${architectureDecision}`
+      );
+    }
     if (context) {
       if (context.constitution) {
         parts.push(
@@ -4053,7 +4108,7 @@ ${currentSpec}`,
 
 // core/code-generator.ts
 import chalk8 from "chalk";
-import { execSync } from "child_process";
+import { execSync, spawnSync } from "child_process";
 import * as path6 from "path";
 import * as fs10 from "fs-extra";
 
@@ -4220,34 +4275,110 @@ function getCodeGenSystemPrompt(repoType) {
       return codeGenSystemPrompt;
   }
 }
-var reviewArchitectureSystemPrompt = `You are a Senior Software Architect reviewing the HIGH-LEVEL design of a code change.
+var specComplianceSystemPrompt = `You are a QA Engineer performing a SPEC COMPLIANCE CHECK.
+
+Your sole job is to verify that the implementation covers every requirement stated in the feature spec.
+This is a completeness audit \u2014 NOT a code quality review. Do not comment on architecture, style, or implementation details.
+
+## How to audit:
+
+1. Parse the spec and extract EVERY stated requirement into these categories:
+   - **Endpoints**: each HTTP method + path listed or implied
+   - **Data Models**: each entity, field, constraint mentioned
+   - **Business Rules**: validations, conditions, calculations stated
+   - **Auth Requirements**: which endpoints need auth, which roles are allowed
+   - **Error Cases**: explicit error codes or failure scenarios mentioned
+   - **Side Effects**: emails sent, events fired, caches invalidated, etc.
+
+2. For each extracted requirement, check the provided code:
+   - \u2705 **Covered** \u2014 clearly implemented
+   - \u26A0\uFE0F **Partial** \u2014 exists but incomplete (e.g. endpoint exists but missing a field or error case)
+   - \u274C **Missing** \u2014 requirement stated in spec but not found in code
+
+3. Output a compliance checklist. Be exhaustive \u2014 list every single requirement.
+
+## Output format:
+
+## \u{1F4CB} Spec Compliance Report
+
+### Endpoints
+\u2705 / \u26A0\uFE0F / \u274C  METHOD /path \u2014 one-line status
+
+### Data Models
+\u2705 / \u26A0\uFE0F / \u274C  ModelName \u2014 one-line status
+
+### Business Rules
+\u2705 / \u26A0\uFE0F / \u274C  Rule description \u2014 one-line status
+
+### Auth & Permissions
+\u2705 / \u26A0\uFE0F / \u274C  Requirement \u2014 one-line status
+
+### Error Cases
+\u2705 / \u26A0\uFE0F / \u274C  Error scenario \u2014 one-line status
+
+### Side Effects
+\u2705 / \u26A0\uFE0F / \u274C  Side effect \u2014 one-line status (omit section if none in spec)
+
+---
+
+## \u{1F4CA} Compliance Summary
+Covered: N  |  Partial: N  |  Missing: N  |  Total: N
+
+## \u{1F522} Compliance Score
+ComplianceScore: X/10
+
+(10 = all requirements implemented, 0 = nothing implemented.
+Deduct 1 point per missing requirement, 0.5 per partial.
+Round to nearest integer.)
+
+## \u{1F6A8} Blockers (Missing requirements that MUST be implemented before ship)
+List only \u274C Missing items here, ordered by severity. If none, write "None".
+
+---
+
+IMPORTANT: Be exhaustive. A requirement not listed here is assumed to be covered.
+If the spec is vague, note the ambiguity as \u26A0\uFE0F Partial rather than assuming coverage.`;
+var reviewArchitectureSystemPrompt = `You are a Senior Software Architect reviewing the HIGH-LEVEL DESIGN of a code change.
+
+A spec compliance check (Pass 0) has already verified feature completeness. Do NOT re-audit whether requirements are missing \u2014 focus purely on HOW the present implementation is architected.
 
 Focus ONLY on:
-1. **Spec compliance** \u2014 Does the implementation match the spec? Are there missing or extra endpoints/components?
-2. **Layer separation** \u2014 Does each layer have the right responsibilities? (e.g., no business logic in controllers, no HTTP in stores)
-3. **API contract** \u2014 Are request/response shapes correct? Are all error codes from the spec implemented?
-4. **Data model integrity** \u2014 Are constraints, unique fields, and relationships correct?
-5. **Security posture** \u2014 Are auth checks applied to the right endpoints? Any obvious missing auth?
+1. **Layer separation** \u2014 Does each layer have the right responsibilities? (e.g., no business logic in controllers, no HTTP in stores)
+2. **API contract quality** \u2014 Are request/response shapes well-designed? Are error codes consistent with project conventions?
+3. **Data model integrity** \u2014 Are constraints, unique fields, and relationships modelled correctly?
+4. **Security posture** \u2014 Are auth checks applied correctly? Any privilege escalation risks?
 
 DO NOT comment on:
+- Whether specific endpoints or features are missing (covered by Pass 0)
 - Code style, naming conventions, formatting
 - Minor implementation details (variable names, inline comments)
 - Performance micro-optimizations
 
 Format:
 
-## \u{1F3D7} \u67B6\u6784\u5408\u89C4\u6027 (Spec Compliance)
-Does the implementation match the spec? List any missing or wrong endpoints/components.
-
 ## \u{1F500} \u5C42\u804C\u8D23\u5206\u79BB (Layer Separation)
 Any layer boundary violations?
 
 ## \u{1F512} \u5B89\u5168\u4E0E\u6743\u9650 (Security & Auth)
 Any missing auth checks, exposed data, or privilege issues?
 
+## \u{1F4D0} \u5951\u7EA6\u4E0E\u6A21\u578B\u8BBE\u8BA1 (Contract & Model Design)
+Response shape issues, missing constraints, relationship problems.
+
 ## \u{1F4CB} \u67B6\u6784\u8BC4\u5206 (Architecture Score)
 Score: X/10 \u2014 One short paragraph.
 
+## \u{1F50D} \u7ED3\u6784\u6027\u53D1\u73B0 JSON (Structural Findings \u2014 for pipeline processing)
+Output a JSON block with any design-level issues found above.
+Categories: "auth_design" | "api_contract" | "model_design" | "layer_violation" | "other_design"
+If no findings, output an empty array.
+
+\`\`\`json
+{"structuralFindings": [{"category": "...", "description": "one sentence referencing the specific endpoint/model/file"}]}
+\`\`\`
+
+IMPORTANT: Always include this JSON block, even when structuralFindings is []. This block is parsed by the pipeline.
+
 Be specific. Reference file names or endpoint paths.`;
 var reviewImplementationSystemPrompt = `You are a Senior Engineer reviewing the IMPLEMENTATION DETAILS of a code change.
 
@@ -4340,7 +4471,8 @@ Each task object must have these exact fields:
   "description": "...",       // 1-2 sentences, specific and actionable
   "layer": "data|service|api|view|route|test|infra",  // implementation layer
   "filesToTouch": ["..."],    // VERIFIED paths only \u2014 see rules below
-  "acceptanceCriteria": ["..."],  // verifiable completion conditions
+  "acceptanceCriteria": ["..."],  // behavioral completion conditions (the "what")
+  "verificationSteps": ["..."],   // concrete runnable checks with expected output (the "how to verify") \u2014 see rules below
   "dependencies": ["TASK-001"],  // task ids that must complete first (empty array if none)
   "priority": "high|medium|low"
 }
@@ -4382,8 +4514,32 @@ CRITICAL \u2014 filesToTouch Rules (hallucination prevention):
 - If you are unsure of the exact path for a new file, leave it as "TBD:<description>" rather than guessing.
 - Cross-check: after writing all tasks, verify every path in filesToTouch exists in the inventory or is a logical new sibling. If it doesn't pass this check, fix it.
 
+CRITICAL \u2014 verificationSteps Rules:
+Each step must be a concrete, self-contained check with an observable expected outcome.
+
+Good examples (specific command + expected result):
+  "POST /api/tasks with body {"title":"test"} \u2192 HTTP 201, response body contains {id, status:"pending"}"
+  "GET /api/tasks/:id with unknown id \u2192 HTTP 404 with {code: 4040X, message: "..."}"
+  "npm run build exits 0 with no TypeScript errors"
+  "Prisma schema has Task model with fields: id, title, status, createdAt"
+  "Store action createTask sets loading:true during request, loading:false on completion"
+  "Route /tasks renders TaskList component, visible in router DevTools"
+
+Bad examples (too vague \u2014 do NOT use these):
+  "The endpoint works correctly" \u2717
+  "Data is saved to the database" \u2717
+  "UI displays the correct data" \u2717
+  "Error handling works" \u2717
+
+Rules:
+- At least 2 verification steps per task, max 5
+- Each step must be independently runnable/checkable
+- Backend tasks: include at least one HTTP request/response check and one data-layer check
+- Frontend tasks: include at least one UI render check and one state check
+- Build/compile tasks: always include "npm run build exits 0" or equivalent
+
 Other rules:
-- acceptanceCriteria must be verifiable (not vague like "works correctly")
+- acceptanceCriteria: behavioral statements ("order is created with pending status") \u2014 complementary to verificationSteps, not duplicates
 - dependencies must reflect real implementation order
 - Aim for 4-10 tasks total \u2014 not too granular, not too coarse
 - Each task should be completable in one focused coding session`;
@@ -4493,6 +4649,14 @@ function printTasks(tasks) {
     const badge = color(`[${task.layer}]`);
     const prio = task.priority === "high" ? chalk4.red("\u25CF") : task.priority === "medium" ? chalk4.yellow("\u25CF") : chalk4.gray("\u25CF");
     console.log(`  ${prio} ${chalk4.bold(task.id)} ${badge} ${task.title}`);
+    if (task.verificationSteps?.length) {
+      for (const step of task.verificationSteps.slice(0, 2)) {
+        console.log(chalk4.gray(`       \u2713 ${step}`));
+      }
+      if (task.verificationSteps.length > 2) {
+        console.log(chalk4.gray(`       + ${task.verificationSteps.length - 2} more verification step(s)`));
+      }
+    }
   }
 }
 async function loadTasksForSpec(specFilePath) {
@@ -4571,6 +4735,21 @@ function validateDsl(raw) {
     for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
       validateEndpoint(eps[i], `endpoints[${i}]`, errors);
     }
+    const seenEpIds = /* @__PURE__ */ new Set();
+    for (let i = 0; i < Math.min(eps.length, MAX_ENDPOINTS); i++) {
+      const ep = eps[i];
+      if (ep && typeof ep === "object" && typeof ep["id"] === "string") {
+        const id = ep["id"];
+        if (seenEpIds.has(id)) {
+          errors.push({
+            path: `endpoints[${i}].id`,
+            message: `Duplicate endpoint id "${id}" \u2014 each endpoint must have a unique id`
+          });
+        } else {
+          seenEpIds.add(id);
+        }
+      }
+    }
   }
   if (obj["behaviors"] !== void 0) {
     if (!Array.isArray(obj["behaviors"])) {
@@ -4627,6 +4806,21 @@ function validateModel(raw, path10, errors) {
     for (let j2 = 0; j2 < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j2++) {
       validateModelField(fields[j2], `${path10}.fields[${j2}]`, errors);
     }
+    const seenFieldNames = /* @__PURE__ */ new Set();
+    for (let j2 = 0; j2 < Math.min(fields.length, MAX_FIELDS_PER_MODEL); j2++) {
+      const f = fields[j2];
+      if (f && typeof f === "object" && typeof f["name"] === "string") {
+        const name = f["name"];
+        if (seenFieldNames.has(name)) {
+          errors.push({
+            path: `${path10}.fields[${j2}].name`,
+            message: `Duplicate field name "${name}" \u2014 each field within a model must have a unique name`
+          });
+        } else {
+          seenFieldNames.add(name);
+        }
+      }
+    }
   }
   if (m["relations"] !== void 0) {
     if (!Array.isArray(m["relations"])) {
@@ -5657,9 +5851,10 @@ ${tasks.map((t) => `${t.id} [${t.layer}] ${t.title}
       console.log(chalk8.cyan(`  \u{1F916} Auto mode: running claude -p (non-interactive)...`));
       console.log(chalk8.gray(`  Spec: ${specFilePath}`));
       try {
-        execSync(`${claudeCmd} -p "${promptContent.replace(/"/g, '\\"')}"`, {
+        spawnSync(claudeCmd, ["-p", promptContent], {
           cwd: workingDir,
-          stdio: "inherit"
+          stdio: "inherit",
+          shell: false
         });
         console.log(chalk8.green("\n  \u2714 Claude Code completed."));
       } catch {
@@ -5711,9 +5906,10 @@ Full spec is at: ${specFilePath}
 Implement ONLY this task. Do not implement other tasks.`;
       let taskStatus = "done";
       try {
-        execSync(`${claudeCmd} -p "${taskPrompt.replace(/"/g, '\\"').replace(/\n/g, "\\n")}"`, {
+        spawnSync(claudeCmd, ["-p", taskPrompt], {
           cwd: workingDir,
-          stdio: "inherit"
+          stdio: "inherit",
+          shell: false
         });
         completed++;
       } catch {
@@ -6116,27 +6312,202 @@ function printTaskProgress(completed, total, task, mode) {
 }
 
 // core/reviewer.ts
-import chalk9 from "chalk";
+import chalk10 from "chalk";
 import { execSync as execSync2 } from "child_process";
-import * as path7 from "path";
+import * as path8 from "path";
+import * as fs12 from "fs-extra";
+
+// core/constitution-generator.ts
+import chalk9 from "chalk";
 import * as fs11 from "fs-extra";
+import * as path7 from "path";
+
+// prompts/constitution.prompt.ts
+var constitutionSystemPrompt = `You are a Senior Software Architect. Analyze the provided project codebase context and generate a concise "Project Constitution" \u2014 a living document that captures the architectural rules, conventions, and red lines that ALL future feature specs and code generation MUST follow.
+
+Output a Markdown document with EXACTLY these sections. Be specific and derive rules directly from the observed codebase \u2014 no generic advice.
+
+---
+
+# Project Constitution
+
+## 1. \u67B6\u6784\u89C4\u5219 (Architecture Rules)
+\u5217\u51FA\u9879\u76EE\u7684\u6838\u5FC3\u67B6\u6784\u6A21\u5F0F\u548C\u5F3A\u5236\u7EA6\u675F\uFF08\u4ECE\u4EE3\u7801\u4E2D\u63D0\u53D6\uFF0C\u800C\u975E\u901A\u7528\u5EFA\u8BAE\uFF09\u3002
+- \u5206\u5C42\u67B6\u6784\u89C4\u5219\uFF08\u5982\uFF1Aroutes \u2192 controllers \u2192 services \u2192 DB\uFF09
+- \u7981\u6B62\u8DE8\u5C42\u76F4\u63A5\u8C03\u7528\u7684\u89C4\u5219
+- \u6A21\u5757\u7EC4\u7EC7\u89C4\u8303
+
+## 2. \u547D\u540D\u89C4\u8303 (Naming Conventions)
+- \u6587\u4EF6\u547D\u540D\u89C4\u5219\uFF08\u9A7C\u5CF0/\u4E0B\u5212\u7EBF/kebab\uFF09
+- \u53D8\u91CF\u3001\u51FD\u6570\u3001\u7C7B\u7684\u547D\u540D\u6A21\u5F0F
+- \u8DEF\u7531\u8DEF\u5F84\u7684\u547D\u540D\u89C4\u8303
+
+## 3. API \u89C4\u8303 (API Patterns)
+- \u8DEF\u7531\u524D\u7F00\u89C4\u5219\uFF08\u5982 /api/v1/client/... vs /api/v1/admin/...\uFF09
+- \u7EDF\u4E00\u54CD\u5E94\u7ED3\u6784\u6A21\u677F\uFF08code/message/data \u683C\u5F0F\uFF09
+- \u9519\u8BEF\u7801\u89C4\u8303\uFF08\u5DF2\u6709\u7684\u9519\u8BEF\u7801\u8303\u56F4\u548C\u542B\u4E49\uFF09
+- \u8BA4\u8BC1/\u9274\u6743\u6A21\u5F0F\uFF08middleware \u540D\u79F0\u548C\u4F7F\u7528\u4F4D\u7F6E\uFF09
+
+## 4. \u6570\u636E\u5C42\u89C4\u8303 (Data Layer Rules)
+- ORM/\u6570\u636E\u5E93\u8BBF\u95EE\u89C4\u5219\uFF08\u4EC5\u901A\u8FC7 service \u5C42\u8BBF\u95EE\uFF1F\u76F4\u63A5\u7528 Prisma/Mongoose\uFF1F\uFF09
+- \u5DF2\u6709\u7684\u6570\u636E\u6A21\u578B\u547D\u540D\u89C4\u8303
+- \u4E8B\u52A1\u5904\u7406\u6A21\u5F0F
+
+## 5. \u9519\u8BEF\u5904\u7406\u89C4\u8303 (Error Handling Patterns)
+- \u7EDF\u4E00\u9519\u8BEF\u5904\u7406 middleware \u7684\u4F7F\u7528\u89C4\u5219
+- \u9519\u8BEF\u629B\u51FA\u548C\u6355\u83B7\u7684\u6A21\u5F0F
+- \u5DF2\u77E5\u9519\u8BEF\u7801\u5217\u8868\uFF08\u4ECE\u4EE3\u7801\u4E2D\u63D0\u53D6\uFF09
+
+## 6. \u7981\u533A (Red Lines \u2014 Never Violate)
+\u660E\u786E\u5217\u51FA\u7EDD\u5BF9\u4E0D\u80FD\u505A\u7684\u4E8B\u60C5\uFF08\u4ECE\u73B0\u6709\u4EE3\u7801/\u67B6\u6784\u63A8\u65AD\uFF09\uFF1A
+- [ ] \u7981\u6B62 ...
+- [ ] \u7981\u6B62 ...
+
+## 7. \u6D4B\u8BD5\u89C4\u8303 (Testing Rules)
+- \u6D4B\u8BD5\u6587\u4EF6\u5B58\u653E\u4F4D\u7F6E
+- \u5FC5\u987B\u8986\u76D6\u7684\u6D4B\u8BD5\u573A\u666F\u7C7B\u578B
+- \u6D4B\u8BD5\u6846\u67B6\u548C\u5DE5\u5177
+
+## 8. \u5171\u4EAB\u914D\u7F6E\u6587\u4EF6\u6E05\u5355 (Shared Config Files \u2014 Append-Only)
+
+CRITICAL: The following files are **singleton config files** that already exist in the project.
+When any feature needs to add entries (translations, constants, routes, enums, etc.), they MUST be
+appended/merged into these existing files. **NEVER create a new parallel file.**
+
+For each discovered file, list it as:
+- \`<relative-path>\` \u2014 <category> \u2014 **MODIFY ONLY, never recreate**
+
+If the project context includes i18n/locale files: list ALL of them with their paths.
+If the project context includes constants/enums files: list ALL of them.
+If the project context includes route index files: list ALL of them.
+If none are provided in the context, write: "(No shared config files detected \u2014 will be populated on first run)"
+
+---
+
+Be concise. Each rule must be specific enough to enforce, not a vague principle.
+**Section 8 is the most important section for preventing file duplication bugs.**`;
+
+// core/constitution-generator.ts
+var CONSTITUTION_FILE = ".ai-spec-constitution.md";
+var ConstitutionGenerator = class {
+  constructor(provider) {
+    this.provider = provider;
+  }
+  async generate(projectRoot) {
+    const loader = new ContextLoader(projectRoot);
+    const context = await loader.loadProjectContext();
+    const prompt = buildConstitutionPrompt(context, projectRoot);
+    return this.provider.generate(prompt, constitutionSystemPrompt);
+  }
+  async saveConstitution(projectRoot, content) {
+    const filePath = path7.join(projectRoot, CONSTITUTION_FILE);
+    await fs11.writeFile(filePath, content, "utf-8");
+    return filePath;
+  }
+};
+function buildConstitutionPrompt(context, projectRoot) {
+  const parts = [
+    "Analyze this project and generate its Project Constitution.\n",
+    `=== Tech Stack ===
+${context.techStack.join(", ") || "unknown"}
+`,
+    `=== Dependencies (top 30) ===
+${context.dependencies.slice(0, 30).join(", ")}
+`
+  ];
+  if (context.apiStructure.length > 0) {
+    parts.push(`=== API/Route Files ===
+${context.apiStructure.join("\n")}
+`);
+  }
+  if (context.routeSummary) {
+    parts.push(`=== Route Code Samples ===
+${context.routeSummary}
+`);
+  }
+  if (context.schema) {
+    parts.push(`=== Prisma Schema ===
+${context.schema.slice(0, 4e3)}
+`);
+  }
+  if (context.errorPatterns) {
+    parts.push(`=== Error Handling Patterns ===
+${context.errorPatterns}
+`);
+  }
+  if (context.sharedConfigFiles && context.sharedConfigFiles.length > 0) {
+    const grouped = context.sharedConfigFiles.reduce(
+      (acc, f) => {
+        (acc[f.category] ??= []).push(f);
+        return acc;
+      },
+      {}
+    );
+    const sections = [];
+    for (const [category, files] of Object.entries(grouped)) {
+      sections.push(`--- ${category} ---`);
+      for (const f of files) {
+        sections.push(`File: ${f.path}
+${f.preview.slice(0, 600)}
+`);
+      }
+    }
+    parts.push(`=== Existing Shared Config Files (Append-Only \u2014 NEVER Recreate) ===
+${sections.join("\n")}
+`);
+  }
+  return parts.join("\n");
+}
+async function loadConstitution(projectRoot) {
+  const filePath = path7.join(projectRoot, CONSTITUTION_FILE);
+  if (await fs11.pathExists(filePath)) {
+    return fs11.readFile(filePath, "utf-8");
+  }
+  return void 0;
+}
+function printConstitutionHint(exists) {
+  if (!exists) {
+    console.log(
+      chalk9.yellow(
+        "  \u26A1 Tip: Run `ai-spec init` to generate a Project Constitution for better spec quality."
+      )
+    );
+  }
+}
+
+// core/reviewer.ts
+async function loadAccumulatedLessons(projectRoot) {
+  const constitutionPath = path8.join(projectRoot, CONSTITUTION_FILE);
+  let content;
+  try {
+    content = await fs12.readFile(constitutionPath, "utf-8");
+  } catch {
+    return null;
+  }
+  const marker = "## 9. \u79EF\u7D2F\u6559\u8BAD";
+  const idx = content.indexOf(marker);
+  if (idx === -1) return null;
+  const section = content.slice(idx);
+  const nextSection = section.slice(marker.length).match(/\n## \d/);
+  return nextSection ? section.slice(0, marker.length + nextSection.index) : section;
+}
 var REVIEW_HISTORY_FILE = ".ai-spec-reviews.json";
 async function loadReviewHistory(projectRoot) {
-  const historyPath = path7.join(projectRoot, REVIEW_HISTORY_FILE);
+  const historyPath = path8.join(projectRoot, REVIEW_HISTORY_FILE);
   try {
-    if (await fs11.pathExists(historyPath)) {
-      return await fs11.readJson(historyPath);
+    if (await fs12.pathExists(historyPath)) {
+      return await fs12.readJson(historyPath);
     }
   } catch {
   }
   return [];
 }
 async function appendReviewHistory(projectRoot, entry) {
-  const historyPath = path7.join(projectRoot, REVIEW_HISTORY_FILE);
+  const historyPath = path8.join(projectRoot, REVIEW_HISTORY_FILE);
   const existing = await loadReviewHistory(projectRoot);
   const updated = [...existing, entry].slice(-20);
   try {
-    await fs11.writeJson(historyPath, updated, { spaces: 2 });
+    await fs12.writeJson(historyPath, updated, { spaces: 2 });
   } catch {
   }
 }
@@ -6144,6 +6515,14 @@ function extractScore(reviewText) {
   const match = reviewText.match(/Score:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
   return match ? parseFloat(match[1]) : 0;
 }
+function extractComplianceScore(complianceText) {
+  const match = complianceText.match(/ComplianceScore:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return match ? parseFloat(match[1]) : 0;
+}
+function extractMissingCount(complianceText) {
+  const summaryMatch = complianceText.match(/Missing:\s*(\d+)/i);
+  return summaryMatch ? parseInt(summaryMatch[1], 10) : 0;
+}
 function extractImpactLevel(reviewText) {
   const match = reviewText.match(/影响等级[：:]\s*(低|中|高)/);
   return match ? match[1] : void 0;
@@ -6162,7 +6541,7 @@ function buildHistoryContext(history) {
   const lines = ["\n=== \u5386\u53F2\u5BA1\u67E5\u95EE\u9898 (Past Review Issues \u2014 check if any recur) ==="];
   for (const entry of recent) {
     lines.push(`
-[${entry.date}] ${path7.basename(entry.specFile)} \u2014 Score: ${entry.score}/10`);
+[${entry.date}] ${path8.basename(entry.specFile)} \u2014 Score: ${entry.score}/10`);
     entry.topIssues.forEach((issue) => lines.push(`  \xB7 ${issue}`));
   }
   return lines.join("\n") + "\n";
@@ -6197,23 +6576,52 @@ var CodeReviewer = class {
     };
   }
   /**
-   * 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
    */
   async runThreePassReview(specContent, codeContext, specFile) {
-    console.log(chalk9.gray("  Pass 1/3: Architecture review..."));
-    const archPrompt = `Review the architecture of this change.
+    let complianceReview = "";
+    if (specContent && specContent.trim() && specContent !== "(No spec \u2014 review for general code quality)") {
+      console.log(chalk10.gray("  Pass 0/3: Spec compliance check..."));
+      const compliancePrompt = `Check whether the implementation covers every requirement in the spec.
 
+=== Feature Spec ===
+${specContent}
+
+=== Code ===
+${codeContext}`;
+      complianceReview = await this.provider.generate(compliancePrompt, specComplianceSystemPrompt);
+      const complianceScore2 = extractComplianceScore(complianceReview);
+      const missingCount = extractMissingCount(complianceReview);
+      if (complianceScore2 > 0) {
+        const scoreColor = complianceScore2 >= 8 ? chalk10.green : complianceScore2 >= 6 ? chalk10.yellow : chalk10.red;
+        console.log(
+          chalk10.gray("  Pass 0 result: ") + scoreColor(`ComplianceScore ${complianceScore2}/10`) + (missingCount > 0 ? chalk10.red(` \xB7 ${missingCount} missing requirement(s)`) : chalk10.green(" \xB7 all requirements covered"))
+        );
+      }
+    }
+    console.log(chalk10.gray(`  Pass 1/3: Architecture review...`));
+    const accumulatedLessons = await loadAccumulatedLessons(this.projectRoot);
+    const archPrompt = `Review the architecture of this change.
+${complianceReview ? `
+=== Spec Compliance Report (Pass 0 \u2014 already audited, do NOT re-audit missing requirements) ===
+${complianceReview}
+` : ""}
+${accumulatedLessons ? `
+=== \xA79 \u5386\u53F2\u79EF\u7D2F\u6559\u8BAD (Accumulated Lessons \u2014 check if any are repeated in this code) ===
+${accumulatedLessons}
+` : ""}
 === Feature Spec ===
 ${specContent || "(No spec \u2014 review for general code quality)"}
 
 === Code ===
 ${codeContext}`;
     const archReview = await this.provider.generate(archPrompt, reviewArchitectureSystemPrompt);
-    console.log(chalk9.gray("  Pass 2/3: Implementation review..."));
+    console.log(chalk10.gray("  Pass 2/3: Implementation review..."));
     const history = await loadReviewHistory(this.projectRoot);
     const historyContext = buildHistoryContext(history);
     const implPrompt = `Review the implementation details of this change.
@@ -6228,7 +6636,7 @@ ${codeContext}
 ${archReview}
 ${historyContext}`;
     const implReview = await this.provider.generate(implPrompt, reviewImplementationSystemPrompt);
-    console.log(chalk9.gray("  Pass 3/3: Impact & complexity assessment..."));
+    console.log(chalk10.gray("  Pass 3/3: Impact & complexity assessment..."));
     const impactPrompt = `Assess the impact and complexity of this change.
 
 === Feature Spec ===
@@ -6244,24 +6652,23 @@ ${archReview}
 ${implReview}`;
     const impactReview = await this.provider.generate(impactPrompt, reviewImpactComplexitySystemPrompt);
     const sep = "\u2500".repeat(52);
-    const combined = `${archReview}
+    const parts = complianceReview ? [complianceReview, archReview, implReview, impactReview] : [archReview, implReview, impactReview];
+    const combined = parts.join(`
 
 ${sep}
 
-${implReview}
-
-${sep}
-
-${impactReview}`;
+`);
     const score = extractScore(implReview) || extractScore(archReview);
+    const complianceScore = extractComplianceScore(complianceReview);
     const topIssues = extractTopIssues(implReview);
     const impactLevel = extractImpactLevel(impactReview);
     const complexityLevel = extractComplexityLevel(impactReview);
     if (score > 0 && specFile) {
       await appendReviewHistory(this.projectRoot, {
         date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
-        specFile: path7.relative(this.projectRoot, specFile),
+        specFile: path8.relative(this.projectRoot, specFile),
         score,
+        ...complianceScore > 0 ? { complianceScore } : {},
         topIssues,
         ...impactLevel ? { impactLevel } : {},
         ...complexityLevel ? { complexityLevel } : {}
@@ -6270,43 +6677,43 @@ ${impactReview}`;
     return combined;
   }
   async reviewCode(specContent, specFile) {
-    console.log(chalk9.cyan("\n\u2500\u2500\u2500 Automated Code Review \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(chalk10.cyan("\n\u2500\u2500\u2500 Automated Code Review \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
     const diff = this.getGitDiff();
     if (!diff.trim()) {
       console.log(
-        chalk9.yellow("  No git diff found. Stage or commit changes first, then run review.")
+        chalk10.yellow("  No git diff found. Stage or commit changes first, then run review.")
       );
-      console.log(chalk9.gray("  Tip: run `git add .` then `ai-spec review` to review your work."));
+      console.log(chalk10.gray("  Tip: run `git add .` then `ai-spec review` to review your work."));
       return "No changes";
     }
     const { files, added, removed } = this.getDiffStats(diff);
     console.log(
-      chalk9.gray(`  Diff: ${files} file(s), ${chalk9.green("+" + added)} ${chalk9.red("-" + removed)}`)
+      chalk10.gray(`  Diff: ${files} file(s), ${chalk10.green("+" + added)} ${chalk10.red("-" + removed)}`)
     );
     console.log(
-      chalk9.blue(`  Reviewing with ${this.provider.providerName}/${this.provider.modelName}...`)
+      chalk10.blue(`  Reviewing with ${this.provider.providerName}/${this.provider.modelName}...`)
     );
     const codeContext = diff.slice(0, 1e4);
     const reviewResult = await this.runThreePassReview(specContent, codeContext, specFile);
-    console.log(chalk9.cyan("\n\u2500\u2500\u2500 Review Result \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(chalk10.cyan("\n\u2500\u2500\u2500 Review Result \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(reviewResult);
-    console.log(chalk9.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+    console.log(chalk10.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
     return reviewResult;
   }
   /**
    * Review directly from generated file contents (for api mode where git diff is empty).
    */
   async reviewFiles(specContent, filePaths, workingDir, specFile) {
-    console.log(chalk9.cyan("\n\u2500\u2500\u2500 Automated Code Review (file-based) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
-    console.log(chalk9.gray(`  Reviewing ${filePaths.length} generated file(s)...`));
+    console.log(chalk10.cyan("\n\u2500\u2500\u2500 Automated Code Review (file-based) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+    console.log(chalk10.gray(`  Reviewing ${filePaths.length} generated file(s)...`));
     console.log(
-      chalk9.blue(`  Reviewing with ${this.provider.providerName}/${this.provider.modelName}...`)
+      chalk10.blue(`  Reviewing with ${this.provider.providerName}/${this.provider.modelName}...`)
     );
     let filesSection = "";
     for (const filePath of filePaths) {
-      const fullPath = path7.join(workingDir, filePath);
+      const fullPath = path8.join(workingDir, filePath);
       try {
-        const content = await fs11.readFile(fullPath, "utf-8");
+        const content = await fs12.readFile(fullPath, "utf-8");
         filesSection += `
 
 === ${filePath} ===
@@ -6321,189 +6728,31 @@ ${content.slice(0, 3e3)}`;
       }
     }
     const reviewResult = await this.runThreePassReview(specContent, filesSection, specFile);
-    console.log(chalk9.cyan("\n\u2500\u2500\u2500 Review Result \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(chalk10.cyan("\n\u2500\u2500\u2500 Review Result \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(reviewResult);
-    console.log(chalk9.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
+    console.log(chalk10.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n"));
     return reviewResult;
   }
   /** Print score trend from history (last N reviews) */
   async printScoreTrend(limit = 5) {
     const history = await loadReviewHistory(this.projectRoot);
     if (history.length === 0) {
-      console.log(chalk9.gray("  No review history yet."));
+      console.log(chalk10.gray("  No review history yet."));
       return;
     }
     const recent = history.slice(-limit);
-    console.log(chalk9.cyan("\n\u2500\u2500\u2500 Review Score Trend \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(chalk10.cyan("\n\u2500\u2500\u2500 Review Score Trend \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"));
     for (const entry of recent) {
       const bar = "\u2588".repeat(entry.score) + "\u2591".repeat(10 - entry.score);
-      const color = entry.score >= 8 ? chalk9.green : entry.score >= 6 ? chalk9.yellow : chalk9.red;
-      const impactTag = entry.impactLevel ? chalk9.gray(` \u5F71\u54CD:${entry.impactLevel === "\u9AD8" ? chalk9.red(entry.impactLevel) : entry.impactLevel === "\u4E2D" ? chalk9.yellow(entry.impactLevel) : chalk9.green(entry.impactLevel)}`) : "";
-      const complexityTag = entry.complexityLevel ? chalk9.gray(` \u590D\u6742\u5EA6:${entry.complexityLevel === "\u9AD8" ? chalk9.red(entry.complexityLevel) : entry.complexityLevel === "\u4E2D" ? chalk9.yellow(entry.complexityLevel) : chalk9.green(entry.complexityLevel)}`) : "";
-      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}${impactTag}${complexityTag}  ${path7.basename(entry.specFile)}`);
+      const color = entry.score >= 8 ? chalk10.green : entry.score >= 6 ? chalk10.yellow : chalk10.red;
+      const impactTag = entry.impactLevel ? chalk10.gray(` \u5F71\u54CD:${entry.impactLevel === "\u9AD8" ? chalk10.red(entry.impactLevel) : entry.impactLevel === "\u4E2D" ? chalk10.yellow(entry.impactLevel) : chalk10.green(entry.impactLevel)}`) : "";
+      const complexityTag = entry.complexityLevel ? chalk10.gray(` \u590D\u6742\u5EA6:${entry.complexityLevel === "\u9AD8" ? chalk10.red(entry.complexityLevel) : entry.complexityLevel === "\u4E2D" ? chalk10.yellow(entry.complexityLevel) : chalk10.green(entry.complexityLevel)}`) : "";
+      console.log(`  ${entry.date}  [${color(bar)}] ${color(entry.score + "/10")}${impactTag}${complexityTag}  ${path8.basename(entry.specFile)}`);
     }
-    console.log(chalk9.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
+    console.log(chalk10.cyan("\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\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500"));
   }
 };
 
-// core/constitution-generator.ts
-import chalk10 from "chalk";
-import * as fs12 from "fs-extra";
-import * as path8 from "path";
-
-// prompts/constitution.prompt.ts
-var constitutionSystemPrompt = `You are a Senior Software Architect. Analyze the provided project codebase context and generate a concise "Project Constitution" \u2014 a living document that captures the architectural rules, conventions, and red lines that ALL future feature specs and code generation MUST follow.
-
-Output a Markdown document with EXACTLY these sections. Be specific and derive rules directly from the observed codebase \u2014 no generic advice.
-
----
-
-# Project Constitution
-
-## 1. \u67B6\u6784\u89C4\u5219 (Architecture Rules)
-\u5217\u51FA\u9879\u76EE\u7684\u6838\u5FC3\u67B6\u6784\u6A21\u5F0F\u548C\u5F3A\u5236\u7EA6\u675F\uFF08\u4ECE\u4EE3\u7801\u4E2D\u63D0\u53D6\uFF0C\u800C\u975E\u901A\u7528\u5EFA\u8BAE\uFF09\u3002
-- \u5206\u5C42\u67B6\u6784\u89C4\u5219\uFF08\u5982\uFF1Aroutes \u2192 controllers \u2192 services \u2192 DB\uFF09
-- \u7981\u6B62\u8DE8\u5C42\u76F4\u63A5\u8C03\u7528\u7684\u89C4\u5219
-- \u6A21\u5757\u7EC4\u7EC7\u89C4\u8303
-
-## 2. \u547D\u540D\u89C4\u8303 (Naming Conventions)
-- \u6587\u4EF6\u547D\u540D\u89C4\u5219\uFF08\u9A7C\u5CF0/\u4E0B\u5212\u7EBF/kebab\uFF09
-- \u53D8\u91CF\u3001\u51FD\u6570\u3001\u7C7B\u7684\u547D\u540D\u6A21\u5F0F
-- \u8DEF\u7531\u8DEF\u5F84\u7684\u547D\u540D\u89C4\u8303
-
-## 3. API \u89C4\u8303 (API Patterns)
-- \u8DEF\u7531\u524D\u7F00\u89C4\u5219\uFF08\u5982 /api/v1/client/... vs /api/v1/admin/...\uFF09
-- \u7EDF\u4E00\u54CD\u5E94\u7ED3\u6784\u6A21\u677F\uFF08code/message/data \u683C\u5F0F\uFF09
-- \u9519\u8BEF\u7801\u89C4\u8303\uFF08\u5DF2\u6709\u7684\u9519\u8BEF\u7801\u8303\u56F4\u548C\u542B\u4E49\uFF09
-- \u8BA4\u8BC1/\u9274\u6743\u6A21\u5F0F\uFF08middleware \u540D\u79F0\u548C\u4F7F\u7528\u4F4D\u7F6E\uFF09
-
-## 4. \u6570\u636E\u5C42\u89C4\u8303 (Data Layer Rules)
-- ORM/\u6570\u636E\u5E93\u8BBF\u95EE\u89C4\u5219\uFF08\u4EC5\u901A\u8FC7 service \u5C42\u8BBF\u95EE\uFF1F\u76F4\u63A5\u7528 Prisma/Mongoose\uFF1F\uFF09
-- \u5DF2\u6709\u7684\u6570\u636E\u6A21\u578B\u547D\u540D\u89C4\u8303
-- \u4E8B\u52A1\u5904\u7406\u6A21\u5F0F
-
-## 5. \u9519\u8BEF\u5904\u7406\u89C4\u8303 (Error Handling Patterns)
-- \u7EDF\u4E00\u9519\u8BEF\u5904\u7406 middleware \u7684\u4F7F\u7528\u89C4\u5219
-- \u9519\u8BEF\u629B\u51FA\u548C\u6355\u83B7\u7684\u6A21\u5F0F
-- \u5DF2\u77E5\u9519\u8BEF\u7801\u5217\u8868\uFF08\u4ECE\u4EE3\u7801\u4E2D\u63D0\u53D6\uFF09
-
-## 6. \u7981\u533A (Red Lines \u2014 Never Violate)
-\u660E\u786E\u5217\u51FA\u7EDD\u5BF9\u4E0D\u80FD\u505A\u7684\u4E8B\u60C5\uFF08\u4ECE\u73B0\u6709\u4EE3\u7801/\u67B6\u6784\u63A8\u65AD\uFF09\uFF1A
-- [ ] \u7981\u6B62 ...
-- [ ] \u7981\u6B62 ...
-
-## 7. \u6D4B\u8BD5\u89C4\u8303 (Testing Rules)
-- \u6D4B\u8BD5\u6587\u4EF6\u5B58\u653E\u4F4D\u7F6E
-- \u5FC5\u987B\u8986\u76D6\u7684\u6D4B\u8BD5\u573A\u666F\u7C7B\u578B
-- \u6D4B\u8BD5\u6846\u67B6\u548C\u5DE5\u5177
-
-## 8. \u5171\u4EAB\u914D\u7F6E\u6587\u4EF6\u6E05\u5355 (Shared Config Files \u2014 Append-Only)
-
-CRITICAL: The following files are **singleton config files** that already exist in the project.
-When any feature needs to add entries (translations, constants, routes, enums, etc.), they MUST be
-appended/merged into these existing files. **NEVER create a new parallel file.**
-
-For each discovered file, list it as:
-- \`<relative-path>\` \u2014 <category> \u2014 **MODIFY ONLY, never recreate**
-
-If the project context includes i18n/locale files: list ALL of them with their paths.
-If the project context includes constants/enums files: list ALL of them.
-If the project context includes route index files: list ALL of them.
-If none are provided in the context, write: "(No shared config files detected \u2014 will be populated on first run)"
-
----
-
-Be concise. Each rule must be specific enough to enforce, not a vague principle.
-**Section 8 is the most important section for preventing file duplication bugs.**`;
-
-// core/constitution-generator.ts
-var CONSTITUTION_FILE = ".ai-spec-constitution.md";
-var ConstitutionGenerator = class {
-  constructor(provider) {
-    this.provider = provider;
-  }
-  async generate(projectRoot) {
-    const loader = new ContextLoader(projectRoot);
-    const context = await loader.loadProjectContext();
-    const prompt = buildConstitutionPrompt(context, projectRoot);
-    return this.provider.generate(prompt, constitutionSystemPrompt);
-  }
-  async saveConstitution(projectRoot, content) {
-    const filePath = path8.join(projectRoot, CONSTITUTION_FILE);
-    await fs12.writeFile(filePath, content, "utf-8");
-    return filePath;
-  }
-};
-function buildConstitutionPrompt(context, projectRoot) {
-  const parts = [
-    "Analyze this project and generate its Project Constitution.\n",
-    `=== Tech Stack ===
-${context.techStack.join(", ") || "unknown"}
-`,
-    `=== Dependencies (top 30) ===
-${context.dependencies.slice(0, 30).join(", ")}
-`
-  ];
-  if (context.apiStructure.length > 0) {
-    parts.push(`=== API/Route Files ===
-${context.apiStructure.join("\n")}
-`);
-  }
-  if (context.routeSummary) {
-    parts.push(`=== Route Code Samples ===
-${context.routeSummary}
-`);
-  }
-  if (context.schema) {
-    parts.push(`=== Prisma Schema ===
-${context.schema.slice(0, 4e3)}
-`);
-  }
-  if (context.errorPatterns) {
-    parts.push(`=== Error Handling Patterns ===
-${context.errorPatterns}
-`);
-  }
-  if (context.sharedConfigFiles && context.sharedConfigFiles.length > 0) {
-    const grouped = context.sharedConfigFiles.reduce(
-      (acc, f) => {
-        (acc[f.category] ??= []).push(f);
-        return acc;
-      },
-      {}
-    );
-    const sections = [];
-    for (const [category, files] of Object.entries(grouped)) {
-      sections.push(`--- ${category} ---`);
-      for (const f of files) {
-        sections.push(`File: ${f.path}
-${f.preview.slice(0, 600)}
-`);
-      }
-    }
-    parts.push(`=== Existing Shared Config Files (Append-Only \u2014 NEVER Recreate) ===
-${sections.join("\n")}
-`);
-  }
-  return parts.join("\n");
-}
-async function loadConstitution(projectRoot) {
-  const filePath = path8.join(projectRoot, CONSTITUTION_FILE);
-  if (await fs12.pathExists(filePath)) {
-    return fs12.readFile(filePath, "utf-8");
-  }
-  return void 0;
-}
-function printConstitutionHint(exists) {
-  if (!exists) {
-    console.log(
-      chalk10.yellow(
-        "  \u26A1 Tip: Run `ai-spec init` to generate a Project Constitution for better spec quality."
-      )
-    );
-  }
-}
-
 // core/combined-generator.ts
 var TASKS_SEPARATOR = "---TASKS_JSON---";
 var tasksInstruction = `
@@ -6512,11 +6761,21 @@ var tasksInstruction = `
 After outputting the complete spec above, append EXACTLY this line on its own (no extra text before or after it):
 ${TASKS_SEPARATOR}
 Then output a valid JSON array of implementation tasks. Each element must have these exact fields:
-{"id":"TASK-001","title":"...","description":"1-2 sentences, specific","layer":"data|infra|service|api|test","filesToTouch":["src/..."],"acceptanceCriteria":["verifiable condition"],"dependencies":[],"priority":"high|medium|low"}
+{"id":"TASK-001","title":"...","description":"1-2 sentences, specific","layer":"data|infra|service|api|test","filesToTouch":["src/..."],"acceptanceCriteria":["behavioral condition"],"verificationSteps":["concrete runnable check \u2192 expected result"],"dependencies":[],"priority":"high|medium|low"}
+verificationSteps rules: each step is a specific command or action with observable expected output (e.g. "POST /api/orders \u2192 201 {id, status:'pending'}"). At least 2 per task, max 5. Never vague.
 Layer order: data \u2192 infra \u2192 service \u2192 api \u2192 test. 4-10 tasks total. filesToTouch must use real paths from the project context.`;
-async function generateSpecWithTasks(provider, idea, context) {
+async function generateSpecWithTasks(provider, idea, context, architectureDecision) {
   const contextBlock = buildTaskPrompt("", context).trim();
-  const fullPrompt = [idea, contextBlock].filter(Boolean).join("\n\n");
+  const parts = [idea];
+  if (architectureDecision) {
+    parts.push(
+      `
+=== Architecture Decision (MUST follow this approach in the spec) ===
+${architectureDecision}`
+    );
+  }
+  if (contextBlock) parts.push(contextBlock);
+  const fullPrompt = parts.join("\n\n");
   const combinedSystemPrompt = specPrompt + tasksInstruction;
   const raw = await provider.generate(fullPrompt, combinedSystemPrompt);
   return parseSpecAndTasks(raw);
@@ -6651,6 +6910,9 @@ export {
   TaskGenerator,
   buildTaskPrompt,
   createProvider,
+  extractBehavioralContract,
+  extractComplianceScore,
+  extractMissingCount,
   generateSpecWithTasks,
   isFrontendDeps,
   loadConstitution,