ai-spec-dev 0.31.0 → 0.33.0

package/cli/index.ts

@@ -75,6 +75,15 @@ import { generateRunId, RunLogger, setActiveLogger } from "../core/run-logger";
 import { RunSnapshot, setActiveSnapshot } from "../core/run-snapshot";
 import { computePromptHash } from "../core/prompt-hasher";
 import { runSelfEval, printSelfEval } from "../core/self-evaluator";
+import { loadRunLogs, buildTrendReport, printTrendReport } from "../core/run-trend";
+import {
+  assessDslRichness,
+  buildDslGapRefinementPrompt,
+  extractStructuralFindings,
+  buildStructuralAmendmentPrompt,
+  printDslGaps,
+  printStructuralFindings,
+} from "../core/dsl-feedback";
 
 // ─── Config File ──────────────────────────────────────────────────────────────
 
@@ -524,6 +533,60 @@ program
       }
     }
 
+    // ── Loop 1: DSL Gap Feedback ──────────────────────────────────────────────
+    // Runs only in interactive mode (not --auto / --fast / --skip-dsl).
+    // Checks for common completeness gaps in the freshly-extracted DSL and
+    // offers a targeted spec refinement AI call to fill them before codegen.
+    // Zero extra AI calls unless the user explicitly opts in.
+    if (extractedDsl && !opts.auto && !opts.fast && !opts.skipDsl) {
+      const dslGaps = assessDslRichness(extractedDsl);
+
+      if (dslGaps.length > 0) {
+        printDslGaps(dslGaps);
+        runLogger.stageStart("dsl_gap_feedback", { gapCount: dslGaps.length, gaps: dslGaps.map((g) => g.code) });
+
+        const refineChoice = await select({
+          message: "How would you like to proceed?",
+          choices: [
+            { name: "🔧  Refine spec (AI fills the gaps, then re-extract DSL)", value: "refine" },
+            { name: "⏭   Skip — proceed with the current DSL", value: "skip" },
+          ],
+        });
+
+        if (refineChoice === "refine") {
+          console.log(chalk.blue("  Refining spec to fill DSL gaps..."));
+          try {
+            const refinedSpec = await specProvider.generate(
+              buildDslGapRefinementPrompt(finalSpec, dslGaps),
+              "You are a Senior Tech Lead doing a targeted spec revision. Output only the complete revised Markdown spec."
+            );
+            finalSpec = refinedSpec;
+            console.log(chalk.green("  ✔ Spec refined."));
+
+            // Re-extract DSL from the improved spec
+            console.log(chalk.blue("  Re-extracting DSL from refined spec..."));
+            const isFrontend2 = isFrontendDeps(context.dependencies);
+            const reExtractor = new DslExtractor(specProvider);
+            const reExtractedDsl = await reExtractor.extract(finalSpec, { auto: true, isFrontend: isFrontend2 });
+            if (reExtractedDsl) {
+              extractedDsl = reExtractedDsl;
+              console.log(chalk.green(`  ✔ DSL re-extracted: ${extractedDsl.endpoints.length} endpoint(s), ${extractedDsl.models.length} model(s).`));
+              runLogger.stageEnd("dsl_gap_feedback", { action: "refined", endpoints: extractedDsl.endpoints.length, models: extractedDsl.models.length });
+            } else {
+              console.log(chalk.yellow("  ⚠ Re-extraction failed — keeping original DSL."));
+              runLogger.stageEnd("dsl_gap_feedback", { action: "refined_but_reextract_failed" });
+            }
+          } catch (err) {
+            console.log(chalk.yellow(`  ⚠ Spec refinement failed: ${(err as Error).message} — keeping original DSL.`));
+            runLogger.stageEnd("dsl_gap_feedback", { action: "refinement_error", error: (err as Error).message });
+          }
+        } else {
+          runLogger.stageEnd("dsl_gap_feedback", { action: "skipped" });
+          console.log(chalk.gray("  Continuing with current DSL."));
+        }
+      }
+    }
+
     // ── Step 4: Git Worktree ──────────────────────────────────────────────────
     // Frontend projects (React / Vue / Next / React-Native) work directly on a
     // feature branch — no worktree needed. node_modules is not copied into
@@ -674,6 +737,82 @@ program
       await accumulateReviewKnowledge(specProvider, currentDir, reviewResult);
     }
 
+    // ── Loop 2: Review → DSL Structural Feedback ─────────────────────────────
+    // Runs only in interactive mode when a review was produced.
+    // Classifies Pass 1 (architecture) findings as design-level vs implementation-
+    // level issues. Design issues belong in the Spec/DSL — not just in §9.
+    // If found: offer to amend the spec → re-extract DSL → overwrite saved DSL file.
+    // The user can then run `ai-spec update --codegen` to regenerate affected files.
+    if (reviewResult && !opts.skipReview && !opts.auto && extractedDsl && savedDslFile) {
+      const structuralFindings = extractStructuralFindings(reviewResult);
+
+      if (structuralFindings.length > 0) {
+        printStructuralFindings(structuralFindings);
+        runLogger.stageStart("review_dsl_feedback", { findingCount: structuralFindings.length, categories: structuralFindings.map((f) => f.category) });
+
+        const savedSpecContent = await fs.readFile(specFile, "utf-8");
+
+        const patchChoice = await select({
+          message: "These are design issues in the Spec/DSL. How would you like to handle them?",
+          choices: [
+            { name: "🔧  Amend spec + update DSL (AI fixes the design issues, no regen yet)", value: "amend" },
+            { name: "📝  Note in §9 only (already done — no DSL change)", value: "note" },
+            { name: "⏭   Skip", value: "skip" },
+          ],
+        });
+
+        if (patchChoice === "amend") {
+          console.log(chalk.blue("  Amending spec to address structural findings..."));
+          try {
+            const amendedSpec = await specProvider.generate(
+              buildStructuralAmendmentPrompt(savedSpecContent, structuralFindings),
+              "You are a Senior Tech Lead doing a targeted spec correction. Output only the complete revised Markdown spec."
+            );
+
+            // Snapshot spec + DSL before overwriting so `ai-spec restore <runId>` works
+            await runSnapshot.snapshotFile(specFile);
+            if (savedDslFile) await runSnapshot.snapshotFile(savedDslFile);
+
+            // Overwrite the saved spec file with the amendment
+            await fs.writeFile(specFile, amendedSpec, "utf-8");
+            console.log(chalk.green(`  ✔ Spec updated: ${specFile}`));
+
+            // Re-extract DSL from the amended spec
+            console.log(chalk.blue("  Re-extracting DSL from amended spec..."));
+            const isFrontend3 = isFrontendDeps(context.dependencies);
+            const amendExtractor = new DslExtractor(specProvider);
+            const amendedDsl = await amendExtractor.extract(amendedSpec, { auto: true, isFrontend: isFrontend3 });
+            if (amendedDsl) {
+              // Overwrite saved DSL file
+              const dslWriter = new DslExtractor(specProvider);
+              const newDslPath = await dslWriter.saveDsl(amendedDsl, specFile);
+              extractedDsl = amendedDsl;
+              console.log(chalk.green(`  ✔ DSL updated: ${newDslPath}`));
+              console.log(chalk.cyan(
+                `\n  Next step: run ${chalk.white("ai-spec update --codegen")} to regenerate files affected by the DSL change.`
+              ));
+              runLogger.stageEnd("review_dsl_feedback", {
+                action: "amended",
+                endpoints: amendedDsl.endpoints.length,
+                models: amendedDsl.models.length,
+              });
+            } else {
+              console.log(chalk.yellow("  ⚠ DSL re-extraction failed — spec was updated but DSL file unchanged."));
+              runLogger.stageEnd("review_dsl_feedback", { action: "amended_spec_only" });
+            }
+          } catch (err) {
+            console.log(chalk.yellow(`  ⚠ Spec amendment failed: ${(err as Error).message}`));
+            runLogger.stageEnd("review_dsl_feedback", { action: "amendment_error", error: (err as Error).message });
+          }
+        } else {
+          runLogger.stageEnd("review_dsl_feedback", { action: patchChoice });
+          if (patchChoice === "note") {
+            console.log(chalk.gray("  Structural findings retained in §9. DSL unchanged."));
+          }
+        }
+      }
+    }
+
     // ── Step 10: Harness Self-Evaluation ──────────────────────────────────────
     // Zero AI calls — deterministic scoring from file-system state + review text.
     // Records harnessScore + promptHash in RunLog for cross-run trend analysis.
@@ -2253,4 +2392,142 @@ program
     }
   });
 
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: trend
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("trend")
+  .description("Show harness score trend across past create runs")
+  .option("--last <n>", "Number of recent scored runs to show (default: 15)", "15")
+  .option("--prompt <hash>", "Filter to a specific prompt hash (prefix match)")
+  .option("--json", "Output raw JSON instead of formatted table")
+  .action(async (opts: { last: string; prompt?: string; json?: boolean }) => {
+    const currentDir = process.cwd();
+    const last = parseInt(opts.last, 10) || 15;
+
+    const logs = await loadRunLogs(currentDir);
+    if (logs.length === 0) {
+      console.log(chalk.yellow(
+        "\n  No run logs found. Run `ai-spec create` at least once to start tracking.\n"
+      ));
+      return;
+    }
+
+    const report = buildTrendReport(logs, {
+      last,
+      promptFilter: opts.prompt,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+
+    printTrendReport(report, currentDir);
+  });
+
+// ═══════════════════════════════════════════════════════════════════════════════
+// Command: logs
+// ═══════════════════════════════════════════════════════════════════════════════
+
+program
+  .command("logs")
+  .description("List recent run logs with stage timing")
+  .argument("[runId]", "Show detailed stage breakdown for a specific run ID")
+  .option("--last <n>", "Number of runs to list (default: 10)", "10")
+  .action(async (runId: string | undefined, opts: { last: string }) => {
+    const currentDir = process.cwd();
+    const logDir = path.join(currentDir, ".ai-spec-logs");
+
+    if (!(await fs.pathExists(logDir))) {
+      console.log(chalk.yellow("\n  No run logs found (.ai-spec-logs/ does not exist).\n"));
+      return;
+    }
+
+    if (runId) {
+      // ── Detail view for a single run ──────────────────────────────────────
+      const logPath = path.join(logDir, `${runId}.json`);
+      if (!(await fs.pathExists(logPath))) {
+        console.log(chalk.red(`\n  Run not found: ${runId}\n`));
+        return;
+      }
+      const log = await fs.readJson(logPath);
+
+      console.log(chalk.cyan(`\n─── Run: ${log.runId} ─────────────────────────────────`));
+      console.log(chalk.gray(`  Started : ${log.startedAt}`));
+      if (log.endedAt) console.log(chalk.gray(`  Ended   : ${log.endedAt}`));
+      if (log.totalDurationMs !== undefined)
+        console.log(chalk.gray(`  Duration: ${(log.totalDurationMs / 1000).toFixed(1)}s`));
+      if (log.provider) console.log(chalk.gray(`  Provider: ${log.provider} / ${log.model ?? "?"}`));
+      if (log.promptHash) console.log(chalk.gray(`  Prompt  : ${log.promptHash}`));
+      if (log.harnessScore !== undefined)
+        console.log(chalk.white(`  Score   : ${log.harnessScore}/10`));
+      if (log.filesWritten?.length)
+        console.log(chalk.gray(`  Files   : ${log.filesWritten.length} written`));
+      if (log.errors?.length)
+        console.log(chalk.yellow(`  Errors  : ${log.errors.length}`));
+
+      if (log.entries?.length) {
+        console.log(chalk.bold("\n  Stages:\n"));
+        const doneEvents = (log.entries as Array<{ event: string; data?: Record<string, unknown>; ts: string }>)
+          .filter((e) => e.event.endsWith(":done") || e.event.endsWith(":failed"));
+
+        for (const entry of doneEvents) {
+          const isOk  = entry.event.endsWith(":done");
+          const stage = entry.event.replace(/:done$|:failed$/, "");
+          const dur   = entry.data?.durationMs
+            ? chalk.gray(` ${(Number(entry.data.durationMs) / 1000).toFixed(1)}s`)
+            : "";
+          const mark  = isOk ? chalk.green("✔") : chalk.red("✘");
+          console.log(`    ${mark}  ${stage.padEnd(20)}${dur}`);
+        }
+      }
+      console.log(chalk.cyan("─".repeat(52)));
+      return;
+    }
+
+    // ── List view ─────────────────────────────────────────────────────────────
+    const logs = await loadRunLogs(currentDir);
+    const last  = parseInt(opts.last, 10) || 10;
+    const shown = logs.slice(0, last);
+
+    if (shown.length === 0) {
+      console.log(chalk.yellow("\n  No run logs found.\n"));
+      return;
+    }
+
+    console.log(chalk.cyan("\n─── Run Logs ────────────────────────────────────────────────"));
+    console.log(chalk.gray(
+      "\n  " +
+      "Run ID                  ".padEnd(26) +
+      "Date      " +
+      "Score ".padStart(6) +
+      "  Files  Dur\n"
+    ));
+
+    for (const log of shown) {
+      const date  = log.startedAt.slice(0, 10);
+      const score = log.harnessScore !== undefined
+        ? (log.harnessScore >= 8 ? chalk.green : log.harnessScore >= 6 ? chalk.yellow : chalk.red)(
+            log.harnessScore.toFixed(1).padStart(5)
+          )
+        : chalk.gray("    —");
+      const files = String(log.filesWritten?.length ?? 0).padStart(5);
+      const dur   = log.totalDurationMs !== undefined
+        ? chalk.gray((log.totalDurationMs / 1000).toFixed(0) + "s")
+        : chalk.gray("—");
+      const errMark = (log.errors?.length ?? 0) > 0
+        ? chalk.yellow(` ⚠${log.errors.length}`)
+        : "";
+
+      console.log(`  ${chalk.white(log.runId.padEnd(25))} ${chalk.gray(date)} ${score}  ${chalk.gray(files)}  ${dur}${errMark}`);
+    }
+
+    console.log(chalk.gray(`\n  Showing ${shown.length} of ${logs.length} run(s)  ·  logs: .ai-spec-logs/`));
+    console.log(chalk.cyan("─".repeat(63)));
+    console.log(chalk.gray(`  Tip: ai-spec logs <runId>   to see stage breakdown`));
+    console.log(chalk.gray(`       ai-spec trend          to see score trend by prompt version\n`));
+  });
+
 program.parse();

package/cli/utils.ts

@@ -0,0 +1,83 @@
+import * as path from "path";
+import * as fs from "fs-extra";
+import chalk from "chalk";
+import { input, select } from "@inquirer/prompts";
+import { CodeGenMode } from "../core/code-generator";
+import { ENV_KEY_MAP } from "../core/spec-generator";
+import { getSavedKey, saveKey, KEY_STORE_FILE } from "../core/key-store";
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+export interface AiSpecConfig {
+  provider?: string;
+  model?: string;
+  codegen?: CodeGenMode;
+  codegenProvider?: string;
+  codegenModel?: string;
+  /** Minimum overall spec score (1-10) required to pass Approval Gate. 0 = disabled (default). */
+  minSpecScore?: number;
+}
+
+export const CONFIG_FILE = ".ai-spec.json";
+
+export async function loadConfig(dir: string): Promise<AiSpecConfig> {
+  const p = path.join(dir, CONFIG_FILE);
+  if (await fs.pathExists(p)) {
+    return fs.readJson(p);
+  }
+  return {};
+}
+
+// ─── API Key Resolution ───────────────────────────────────────────────────────
+
+export async function resolveApiKey(
+  providerName: string,
+  cliKey?: string
+): Promise<string> {
+  if (cliKey) return cliKey;
+
+  const envVar = ENV_KEY_MAP[providerName];
+  if (envVar && process.env[envVar]) return process.env[envVar]!;
+
+  const savedKey = await getSavedKey(providerName);
+  if (savedKey) {
+    const masked = savedKey.slice(0, 6) + "..." + savedKey.slice(-4);
+    const choice = await select({
+      message: `${providerName} API key (saved: ${masked}):`,
+      choices: [
+        { name: "Use saved key", value: "reuse" },
+        { name: "Enter a new key", value: "new" },
+      ],
+    });
+    if (choice === "reuse") return savedKey;
+  }
+
+  const newKey = await input({
+    message: `Enter your ${providerName} API key${envVar ? ` (or set ${envVar} env var)` : ""}:`,
+    validate: (v) => v.trim().length > 0 || "API key cannot be empty",
+  });
+  await saveKey(providerName, newKey.trim());
+  console.log(chalk.gray(`  Key saved to ${KEY_STORE_FILE}`));
+  return newKey.trim();
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+
+export function printBanner(opts: {
+  specProvider: string;
+  specModel: string;
+  codegenMode: string;
+  codegenProvider: string;
+  codegenModel: string;
+}) {
+  console.log(chalk.blue("\n" + "─".repeat(52)));
+  console.log(chalk.bold("  ai-spec — AI-driven Development Orchestrator"));
+  console.log(chalk.blue("─".repeat(52)));
+  console.log(chalk.gray(`  Spec    : ${opts.specProvider} / ${opts.specModel}`));
+  console.log(
+    chalk.gray(
+      `  Codegen : ${opts.codegenMode} (${opts.codegenProvider} / ${opts.codegenModel})`
+    )
+  );
+  console.log(chalk.blue("─".repeat(52) + "\n"));
+}

package/core/dsl-feedback.ts

@@ -0,0 +1,255 @@
+/**
+ * dsl-feedback.ts — Two pipeline feedback loops for ai-spec create
+ *
+ * Loop 1 (DSL → Spec):  after DSL extraction, detect sparse/incomplete DSL
+ *   and offer a targeted spec refinement pass before codegen starts.
+ *
+ * Loop 2 (Review → DSL): after 3-pass review, detect design-level findings
+ *   (as opposed to implementation issues) and offer to amend the spec + DSL
+ *   so the next update/regen starts from a corrected contract.
+ *
+ * Design constraints:
+ *  - Both loops are SKIPPED in --auto / --fast / --skip-dsl modes.
+ *  - Zero extra AI calls until the user explicitly opts in.
+ *  - Non-blocking: user can always skip.
+ */
+
+import chalk from "chalk";
+import { SpecDSL } from "./dsl-types";
+
+// ─── Loop 1 Types ─────────────────────────────────────────────────────────────
+
+export interface DslGap {
+  /** Short machine key for RunLog serialisation */
+  code: "sparse_model" | "missing_errors" | "generic_endpoint_desc" | "no_models_no_endpoints";
+  /** Human-readable message shown to the user */
+  message: string;
+  /** Concrete suggestion injected into the refinement prompt */
+  hint: string;
+}
+
+// ─── Loop 1: DSL Richness Assessment ─────────────────────────────────────────
+
+/**
+ * Inspect a freshly-extracted DSL for common completeness gaps.
+ * Returns a list of DslGap objects (empty = DSL looks adequate).
+ *
+ * All checks are pure heuristics — zero AI calls.
+ */
+export function assessDslRichness(dsl: SpecDSL): DslGap[] {
+  const gaps: DslGap[] = [];
+
+  // ── No endpoints AND no models ────────────────────────────────────────────
+  if (dsl.endpoints.length === 0 && dsl.models.length === 0) {
+    gaps.push({
+      code: "no_models_no_endpoints",
+      message: "DSL has no endpoints and no models — spec may be too abstract for structured extraction",
+      hint: "Please add explicit API endpoint definitions (method, path, request/response) and any data models that this feature requires.",
+    });
+    return gaps; // no point checking the rest
+  }
+
+  // ── Endpoints with very generic / short descriptions ─────────────────────
+  const GENERIC_DESC_KEYWORDS = ["handles", "processes", "manages", "操作", "处理", "管理"];
+  const GENERIC_DESC_MIN_LEN  = 15;
+
+  for (const ep of dsl.endpoints) {
+    const desc = (ep.description ?? "").trim();
+    const isGeneric =
+      desc.length < GENERIC_DESC_MIN_LEN ||
+      GENERIC_DESC_KEYWORDS.some((kw) => desc.toLowerCase().startsWith(kw));
+
+    if (isGeneric) {
+      gaps.push({
+        code: "generic_endpoint_desc",
+        message: `Endpoint ${ep.method} ${ep.path} has a vague description: "${desc}"`,
+        hint: `Clarify what ${ep.method} ${ep.path} does: what inputs are required, what the success response contains, and what business rule it enforces.`,
+      });
+    }
+  }
+
+  // ── Endpoints with no error definitions (but spec text likely mentions them) ──
+  const endpointsWithoutErrors = dsl.endpoints.filter(
+    (ep) => !ep.errors || ep.errors.length === 0
+  );
+  if (endpointsWithoutErrors.length > 0 && dsl.endpoints.length >= 2) {
+    gaps.push({
+      code: "missing_errors",
+      message: `${endpointsWithoutErrors.length}/${dsl.endpoints.length} endpoints have no error definitions`,
+      hint: `For each endpoint, specify at least the main error cases: e.g. 400 validation errors, 401 auth failures, 404 not found, 409 conflict. Include an error code (e.g. INVALID_INPUT) and description for each.`,
+    });
+  }
+
+  // ── Models with fewer than 2 fields ──────────────────────────────────────
+  for (const model of dsl.models) {
+    if (!model.fields || model.fields.length < 2) {
+      gaps.push({
+        code: "sparse_model",
+        message: `Model "${model.name}" has only ${model.fields?.length ?? 0} field(s) — likely incomplete`,
+        hint: `List all fields for "${model.name}" with their types and whether they are required. Include at minimum an id, created_at, and the core domain fields this model needs.`,
+      });
+    }
+  }
+
+  return gaps;
+}
+
+// ─── Loop 1: Targeted Spec Refinement Prompt ─────────────────────────────────
+
+/**
+ * Build a targeted AI refinement prompt that focuses the LLM on filling
+ * only the specific gaps detected by `assessDslRichness`.
+ */
+export function buildDslGapRefinementPrompt(spec: string, gaps: DslGap[]): string {
+  const gapList = gaps
+    .map((g, i) => `${i + 1}. [${g.code}] ${g.message}\n   → ${g.hint}`)
+    .join("\n\n");
+
+  return `The following feature spec has been structurally analysed. The DSL extracted from it was found to be incomplete in these specific areas:
+
+${gapList}
+
+Your task: revise the spec below to address ONLY the gaps listed above.
+- Do NOT change the overall feature scope or business logic.
+- Do NOT rewrite sections that are already complete.
+- Add missing error cases, clarify vague endpoint descriptions, complete sparse model field lists.
+- Output ONLY the complete revised Markdown spec. No preamble, no explanation.
+
+=== Current Spec ===
+${spec}`;
+}
+
+// ─── Loop 2 Types ─────────────────────────────────────────────────────────────
+
+export interface StructuralFinding {
+  /** Short label for display + RunLog */
+  category: "auth_design" | "model_design" | "api_contract" | "layer_violation" | "other_design";
+  description: string;
+}
+
+// ─── Loop 2: Review Structural Issue Classifier ───────────────────────────────
+
+/**
+ * Parse a 3-pass review text to extract Pass 1 (architecture) findings
+ * that indicate design-level issues in the Spec/DSL — as opposed to
+ * implementation-level issues that belong in §9 knowledge.
+ *
+ * Returns an empty array if no structural issues are found or if the
+ * review score for Pass 1 is high (≥ 8), indicating overall approval.
+ */
+export function extractStructuralFindings(reviewText: string): StructuralFinding[] {
+  // Split by the separator used between passes ("─────...")
+  const parts = reviewText.split(/─{20,}/);
+  // Pass 1 is always the first section
+  const pass1Text = parts[0] ?? "";
+
+  // If Pass 1 scored well, treat as no structural issues
+  const pass1Score = extractPassScore(pass1Text);
+  if (pass1Score !== null && pass1Score >= 8) return [];
+
+  const findings: StructuralFinding[] = [];
+
+  // ── Auth / 认证 design issues ──────────────────────────────────────────
+  if (
+    /缺少认证|missing auth|auth.*false|未加认证|鉴权.*缺|endpoint.*public.*should/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:缺少认证|missing auth|auth.*false|未加认证|鉴权.*缺|endpoint.*public.*should)[^。\n]*/i);
+    findings.push({
+      category: "auth_design",
+      description: match ? match[0].trim() : "One or more endpoints may have incorrect authentication requirements",
+    });
+  }
+
+  // ── API contract / 接口设计 issues ────────────────────────────────────
+  if (
+    /接口设计.*问题|接口.*不合理|API design|response.*missing|request.*missing|接口.*缺少/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:接口设计.*问题|接口.*不合理|API design|response.*missing|接口.*缺少)[^。\n]*/i);
+    findings.push({
+      category: "api_contract",
+      description: match ? match[0].trim() : "API contract design may have issues",
+    });
+  }
+
+  // ── Model / 数据模型 design issues ────────────────────────────────────
+  if (
+    /模型.*缺少字段|model.*missing field|数据结构.*问题|schema.*incomplete|字段.*missing/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:模型.*缺少字段|model.*missing field|数据结构.*问题|schema.*incomplete)[^。\n]*/i);
+    findings.push({
+      category: "model_design",
+      description: match ? match[0].trim() : "Data model design may be incomplete",
+    });
+  }
+
+  // ── Layer separation / 层级分离 violations ────────────────────────────
+  if (
+    /层级.*违反|layer.*violation|business logic.*controller|controller.*service.*混|分层.*问题/i.test(pass1Text)
+  ) {
+    const match = pass1Text.match(/[^。\n]*(?:层级.*违反|layer.*violation|business logic.*controller|分层.*问题)[^。\n]*/i);
+    findings.push({
+      category: "layer_violation",
+      description: match ? match[0].trim() : "Layer separation may be violated in the generated code",
+    });
+  }
+
+  return findings;
+}
+
+/** Extract the numeric score from a single pass section. */
+function extractPassScore(text: string): number | null {
+  const m = text.match(/Score:\s*(\d+(?:\.\d+)?)\s*\/\s*10/i);
+  return m ? parseFloat(m[1]) : null;
+}
+
+// ─── Loop 2: Spec Amendment Prompt ────────────────────────────────────────────
+
+/**
+ * Build a prompt asking the AI to produce a minimal spec amendment
+ * that addresses the structural findings from the review.
+ *
+ * The amendment is a targeted addition/correction — NOT a full rewrite.
+ */
+export function buildStructuralAmendmentPrompt(
+  spec: string,
+  findings: StructuralFinding[]
+): string {
+  const findingList = findings
+    .map((f, i) => `${i + 1}. [${f.category}] ${f.description}`)
+    .join("\n");
+
+  return `A code review of the feature built from this spec found the following DESIGN-LEVEL issues.
+These are problems in the spec/contract itself, not in the implementation.
+
+=== Structural Findings ===
+${findingList}
+
+Your task:
+- Revise the spec below to correct the design issues listed above.
+- Do NOT change the feature scope, business logic, or sections unrelated to these findings.
+- Be minimal: only change what is necessary to fix the design issues.
+- Output ONLY the complete revised Markdown spec. No preamble, no explanation.
+
+=== Current Spec ===
+${spec}`;
+}
+
+// ─── Display Helpers ──────────────────────────────────────────────────────────
+
+export function printDslGaps(gaps: DslGap[]): void {
+  console.log(chalk.yellow("\n  ⚠ DSL Completeness Check — gaps detected:"));
+  for (const gap of gaps) {
+    console.log(chalk.yellow(`    · ${gap.message}`));
+  }
+  console.log(chalk.gray("    → A targeted spec refinement can fill these gaps before codegen."));
+}
+
+export function printStructuralFindings(findings: StructuralFinding[]): void {
+  console.log(chalk.yellow("\n  ⚠ Review — structural (design-level) issues found:"));
+  for (const f of findings) {
+    const label = chalk.gray(`[${f.category}]`);
+    console.log(`    ${label} ${f.description}`);
+  }
+  console.log(chalk.gray("    → These are contract issues in the Spec/DSL, not just implementation problems."));
+  console.log(chalk.gray("    → Fixing the spec now means the next run generates correct code from the start."));
+}