@delegance/claude-autopilot 2.5.0 → 5.0.0-alpha.2

package/src/core/pipeline/review-phase.ts

@@ -1,12 +1,15 @@
 import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
 import type { Finding } from '../findings/types.ts';
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 import { buildReviewChunks, type ReviewChunk } from '../chunking/index.ts';
+import { GuardrailError } from '../errors.ts';
+import { hasFrontendFiles, loadDesignContext } from '../ui/design-context-loader.ts';
 
 export interface ReviewPhaseResult {
   phase: 'review';
   status: 'pass' | 'warn' | 'fail' | 'skip';
   findings: Finding[];
+  rawOutputs?: string[];
   costUSD?: number;
   usage?: { input: number; output: number };
   durationMs: number;
@@ -15,32 +18,55 @@ export interface ReviewPhaseResult {
 export interface ReviewPhaseInput {
   touchedFiles: string[];
   engine: ReviewEngine;
-  config: AutopilotConfig;
+  config: GuardrailConfig;
   cwd?: string;
   gitSummary?: string;
+  designSchema?: string;
   budgetRemainingUSD?: number;
   base?: string;
 }
 
 interface ChunkResult {
   findings: Finding[];
+  rawOutput: string;
   inputTokens: number;
   outputTokens: number;
   costUSD: number;
 }
 
-async function reviewChunk(chunk: ReviewChunk, input: ReviewPhaseInput): Promise<ChunkResult> {
-  const output = await input.engine.review({
-    content: chunk.content,
-    kind: chunk.kind,
-    context: { stack: input.config.stack, cwd: input.cwd, gitSummary: input.gitSummary },
-  });
-  return {
-    findings: output.findings,
-    inputTokens: output.usage?.input ?? 0,
-    outputTokens: output.usage?.output ?? 0,
-    costUSD: output.usage?.costUSD ?? 0,
-  };
+function backoffMs(attempt: number, strategy: 'exp' | 'linear' | 'none'): number {
+  if (strategy === 'none') return 0;
+  if (strategy === 'linear') return attempt * 2000;
+  return Math.min(Math.pow(2, attempt) * 1000, 32000); // exp: 1s, 2s, 4s, 8s … 32s cap
+}
+
+async function reviewChunkWithRetry(chunk: ReviewChunk, input: ReviewPhaseInput): Promise<ChunkResult> {
+  const strategy = input.config.chunking?.rateLimitBackoff ?? 'exp';
+  const maxAttempts = strategy === 'none' ? 1 : 4;
+
+  for (let attempt = 0; attempt < maxAttempts; attempt++) {
+    try {
+      const output = await input.engine.review({
+        content: chunk.content,
+        kind: chunk.kind,
+        context: { stack: input.config.stack, cwd: input.cwd, gitSummary: input.gitSummary, designSchema: input.designSchema },
+      });
+      return {
+        findings: output.findings,
+        rawOutput: output.rawOutput,
+        inputTokens: output.usage?.input ?? 0,
+        outputTokens: output.usage?.output ?? 0,
+        costUSD: output.usage?.costUSD ?? 0,
+      };
+    } catch (err) {
+      const isRateLimit = err instanceof GuardrailError && err.code === 'rate_limit';
+      const isLast = attempt === maxAttempts - 1;
+      if (!isRateLimit || isLast) throw err;
+      const delay = backoffMs(attempt + 1, strategy);
+      await new Promise(r => setTimeout(r, delay));
+    }
+  }
+  throw new Error('unreachable');
 }
 
 /** Run up to `limit` promises concurrently, preserving result order. */
@@ -71,18 +97,28 @@ export async function runReviewPhase(input: ReviewPhaseInput): Promise<ReviewPha
     return { phase: 'review', status: 'skip', findings: [], durationMs: Date.now() - start };
   }
 
+  let designSchema: string | undefined;
+  if (hasFrontendFiles(input.touchedFiles) && input.config.brand?.componentLibrary) {
+    const loaded = loadDesignContext(
+      input.config.brand.componentLibrary,
+      input.cwd ?? process.cwd(),
+    );
+    if (loaded) designSchema = loaded;
+  }
+  const enrichedInput: ReviewPhaseInput = designSchema ? { ...input, designSchema } : input;
+
   const chunks = await buildReviewChunks({
-    touchedFiles: input.touchedFiles,
-    strategy: input.config.reviewStrategy ?? 'auto',
-    chunking: input.config.chunking,
-    engine: input.engine,
-    cwd: input.cwd,
-    protectedPaths: input.config.protectedPaths,
-    base: input.base,
+    touchedFiles: enrichedInput.touchedFiles,
+    strategy: enrichedInput.config.reviewStrategy ?? 'auto',
+    chunking: enrichedInput.config.chunking,
+    engine: enrichedInput.engine,
+    cwd: enrichedInput.cwd,
+    protectedPaths: enrichedInput.config.protectedPaths,
+    base: enrichedInput.base,
   });
 
-  const parallelism = input.config.chunking?.parallelism ?? 3;
-  const budgetUSD = input.budgetRemainingUSD;
+  const parallelism = enrichedInput.config.chunking?.parallelism ?? 3;
+  const budgetUSD = enrichedInput.budgetRemainingUSD;
 
   // For budget tracking we still need to enforce it — run serially if budget set,
   // parallel otherwise (budget check between serial chunks is the safe path).
@@ -93,7 +129,7 @@ export async function runReviewPhase(input: ReviewPhaseInput): Promise<ReviewPha
     let budgetExceeded = false;
     for (const chunk of chunks) {
       if (spent >= budgetUSD) { budgetExceeded = true; break; }
-      const r = await reviewChunk(chunk, input);
+      const r = await reviewChunkWithRetry(chunk, enrichedInput);
       spent += r.costUSD;
       chunkResults.push(r);
     }
@@ -109,20 +145,22 @@ export async function runReviewPhase(input: ReviewPhaseInput): Promise<ReviewPha
           protectedPath: false,
           createdAt: new Date().toISOString(),
         }],
-        inputTokens: 0, outputTokens: 0, costUSD: 0,
+        rawOutput: '', inputTokens: 0, outputTokens: 0, costUSD: 0,
       });
     }
   } else {
-    chunkResults = await pMap(chunks, chunk => reviewChunk(chunk, input), parallelism);
+    chunkResults = await pMap(chunks, chunk => reviewChunkWithRetry(chunk, enrichedInput), parallelism);
   }
 
   let totalInputTokens = 0;
   let totalOutputTokens = 0;
   let totalCostUSD = 0;
   const allFindings: Finding[] = [];
+  const allRawOutputs: string[] = [];
 
   for (const r of chunkResults) {
     allFindings.push(...r.findings);
+    if (r.rawOutput) allRawOutputs.push(r.rawOutput);
     totalInputTokens += r.inputTokens;
     totalOutputTokens += r.outputTokens;
     totalCostUSD += r.costUSD;
@@ -136,6 +174,7 @@ export async function runReviewPhase(input: ReviewPhaseInput): Promise<ReviewPha
     phase: 'review',
     status,
     findings: allFindings,
+    rawOutputs: allRawOutputs.length > 0 ? allRawOutputs : undefined,
     costUSD: totalCostUSD > 0 ? totalCostUSD : undefined,
     usage: totalInputTokens > 0 ? { input: totalInputTokens, output: totalOutputTokens } : undefined,
     durationMs: Date.now() - start,

package/src/core/pipeline/run.ts

@@ -1,4 +1,4 @@
-import type { AutopilotConfig } from '../config/types.ts';
+import type { GuardrailConfig } from '../config/types.ts';
 import type { StaticRule } from '../phases/static-rules.ts';
 import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
 import type { Finding } from '../findings/types.ts';
@@ -13,12 +13,13 @@ export type PhaseResult = StaticRulesPhaseResult | TestsPhaseResult | ReviewPhas
 
 export interface RunInput {
   touchedFiles: string[];
-  config: AutopilotConfig;
+  config: GuardrailConfig;
   reviewEngine?: ReviewEngine;
   staticRules?: StaticRule[];
   cwd?: string;
   gitSummary?: string;
   base?: string;
+  skipReview?: boolean;
 }
 
 export interface RunResult {
@@ -29,33 +30,64 @@ export interface RunResult {
   durationMs: number;
 }
 
-export async function runAutopilot(input: RunInput): Promise<RunResult> {
+export async function runGuardrail(input: RunInput): Promise<RunResult> {
   const start = Date.now();
   const phases: PhaseResult[] = [];
   let totalCostUSD: number | undefined;
 
-  // Static-rules phase — fail fast on critical
+  const pipelineCfg = input.config.pipeline ?? {};
+  // Default true: when the user wires up a review engine they expect it to actually run.
+  // Skipping LLM review on static-fail is exactly the "silent skip" behavior the v4.0
+  // reviewer flagged — the bugs the LLM is best at often ride alongside one a static
+  // rule already caught.
+  const runReviewOnStaticFail = pipelineCfg.runReviewOnStaticFail !== false;
+  const runReviewOnTestFail = pipelineCfg.runReviewOnTestFail === true;
+
+  // Static-rules phase — tests always run afterward, regardless of status. The
+  // runReviewOnStaticFail flag only gates the LLM review phase (matching its name);
+  // skipping tests on a static-fail would be surprising and asymmetric with
+  // runReviewOnTestFail which only gates the review phase too.
+  let staticFailed = false;
   if (input.staticRules && input.staticRules.length > 0) {
     const result = await runStaticRulesPhase({
       touchedFiles: input.touchedFiles,
       rules: input.staticRules,
+      config: input.config,
+      engine: input.reviewEngine,
     });
     phases.push(result);
-    if (result.status === 'fail') return finalize(phases, start, totalCostUSD);
+    staticFailed = result.status === 'fail';
+  }
+
+  // skipReview short-circuit: skip tests and review phases entirely
+  if (input.skipReview) {
+    const allFindings = phases.flatMap(p => p.findings ?? []);
+    const hasCritical = allFindings.some(f => f.severity === 'critical');
+    return {
+      status: hasCritical ? 'fail' : 'pass',
+      phases,
+      allFindings,
+      totalCostUSD: undefined,
+      durationMs: Date.now() - start,
+    };
   }
 
-  // Tests phase — fail fast on test failure
+  // Tests phase — always runs (unless skipReview above). The runReviewOnTestFail
+  // flag only gates the subsequent review phase.
   const testsResult = await runTestsPhase({
     touchedFiles: input.touchedFiles,
     testCommand: input.config.testCommand,
     cwd: input.cwd,
   });
   phases.push(testsResult);
-  if (testsResult.status === 'fail') return finalize(phases, start, totalCostUSD);
+  const testsFailed = testsResult.status === 'fail';
 
-  // Review phase (optional — only when engine is provided)
-  if (input.reviewEngine) {
-    const budgetUSD = (input.config.cost as { budgetUSD?: number } | undefined)?.budgetUSD;
+  // Review phase (optional — only when engine is provided, not gated off by flags)
+  const skipReviewDueToStatic = staticFailed && !runReviewOnStaticFail;
+  const skipReviewDueToTests = testsFailed && !runReviewOnTestFail;
+  if (input.reviewEngine && !skipReviewDueToStatic && !skipReviewDueToTests) {
+    const costCfg = input.config.cost as { maxPerRun?: number; budgetUSD?: number } | undefined;
+    const budgetUSD = costCfg?.maxPerRun ?? costCfg?.budgetUSD;
     const reviewResult = await runReviewPhase({
       touchedFiles: input.touchedFiles,
       engine: input.reviewEngine,

package/src/core/runtime/lock.ts

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { AutopilotError } from '../errors.ts';
+import { GuardrailError } from '../errors.ts';
 
 export interface LockHandle {
   release(): Promise<void>;
@@ -16,7 +16,7 @@ export function acquireLock(runId: string, lockDir = '.claude'): LockHandle {
       { flag: 'wx' }
     );
   } catch (err) {
-    throw new AutopilotError('Another autopilot run holds the lock', {
+    throw new GuardrailError('Another autopilot run holds the lock', {
       code: 'concurrency_lock',
       details: { lockPath, cause: err instanceof Error ? err.message : String(err) },
     });

package/src/core/runtime/state.ts

@@ -1,6 +1,6 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { AutopilotError } from '../errors.ts';
+import { GuardrailError } from '../errors.ts';
 
 export type PipelineStep =
   | 'plan' | 'worktree' | 'implement' | 'migrate' | 'validate'
@@ -72,7 +72,7 @@ export async function loadRunState(runId: string, runsDir?: string): Promise<Run
   try {
     return JSON.parse(await fs.readFile(file, 'utf8')) as RunState;
   } catch (err) {
-    throw new AutopilotError(`Run state not found: ${runId}`, {
+    throw new GuardrailError(`Run state not found: ${runId}`, {
       code: 'user_input',
       details: { runId, file, cause: err instanceof Error ? err.message : String(err) },
     });

package/src/core/schema-alignment/detector.ts

@@ -0,0 +1,59 @@
+// src/core/schema-alignment/detector.ts
+import type { SchemaAlignmentConfig } from './types.ts';
+
+const DEFAULT_PATTERNS: RegExp[] = [
+  /data[/\\]deltas[/\\].+\.sql$/,
+  /supabase[/\\]migrations[/\\].+\.sql$/,
+  /prisma[/\\]migrations[/\\].+\.sql$/,
+  /prisma[/\\]schema\.prisma$/,
+  /db[/\\]migrate[/\\].+\.rb$/,
+  /drizzle[/\\].+\.ts$/,
+  /[/\\]migrations[/\\].+\.py$/,
+];
+
+function globToPattern(glob: string): RegExp {
+  let escaped = glob;
+
+  // Escape regex special chars except * and /
+  escaped = escaped.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+
+  // Replace **/ with placeholder (matches zero or more intermediate directories)
+  escaped = escaped.replace(/\*\*\//g, '___DSTAR_SLASH___');
+
+  // Replace remaining ** with placeholder
+  escaped = escaped.replace(/\*\*/g, '___DSTAR___');
+
+  // Replace / with placeholder BEFORE handling * so we don't mess up character classes
+  escaped = escaped.replace(/\//g, '___SLASH___');
+
+  // Replace single * with placeholder (to preserve it before / restoration)
+  escaped = escaped.replace(/\*/g, '___STAR___');
+
+  // Now restore placeholders in the right order
+  // Restore / as [/\\\\] to match both forward and back slashes
+  // NOTE: In RegExp constructor, \\ becomes \, so [/\\] needs to be [/\\\\]
+  escaped = escaped.replace(/___SLASH___/g, '[/\\\\]');
+
+  // Restore * as [^/]* (matches anything except /)
+  escaped = escaped.replace(/___STAR___/g, '[^/]*');
+
+  // Restore **/ as optional directory segments with trailing separator
+  escaped = escaped.replace(/___DSTAR_SLASH___/g, '(?:.*[/\\\\])?');
+
+  // Restore remaining ** as .* (matches anything including /)
+  escaped = escaped.replace(/___DSTAR___/g, '.*');
+
+  const re = new RegExp(escaped + '$');
+  return re;
+}
+
+export function detect(touchedFiles: string[], config?: SchemaAlignmentConfig): string[] {
+  if (config?.enabled === false) return [];
+
+  const patterns = [...DEFAULT_PATTERNS];
+  for (const glob of config?.migrationGlobs ?? []) {
+    patterns.push(globToPattern(glob));
+  }
+
+  return touchedFiles.filter(f => patterns.some(re => re.test(f)));
+}

package/src/core/schema-alignment/extractor/index.ts

@@ -0,0 +1,24 @@
+// src/core/schema-alignment/extractor/index.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { SchemaEntity } from '../types.ts';
+import { extractFromSql } from './sql.ts';
+import { extractFromPrisma } from './prisma.ts';
+
+export function extract(filePath: string): SchemaEntity[] {
+  let content: string;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const ext = path.extname(filePath).toLowerCase();
+  const base = path.basename(filePath).toLowerCase();
+
+  if (ext === '.sql') return extractFromSql(content);
+  if (base === 'schema.prisma' || ext === '.prisma') return extractFromPrisma(content);
+
+  process.stderr.write(`[schema-alignment] no extractor for ${ext} files — skipping ${path.basename(filePath)}\n`);
+  return [];
+}

package/src/core/schema-alignment/extractor/prisma.ts

@@ -0,0 +1,21 @@
+// src/core/schema-alignment/extractor/prisma.ts
+import type { SchemaEntity } from '../types.ts';
+
+export function extractFromPrisma(content: string): SchemaEntity[] {
+  const entities: SchemaEntity[] = [];
+  // Match model blocks: model Name { ... }
+  const modelRe = /^model\s+(\w+)\s*\{([^}]+)\}/gm;
+  for (const modelMatch of content.matchAll(modelRe)) {
+    const table = modelMatch[1]!;
+    entities.push({ table, operation: 'create_table' });
+    const body = modelMatch[2]!;
+    // Match field lines: fieldName TypeName ...
+    const fieldRe = /^\s+(\w+)\s+\S/gm;
+    for (const fieldMatch of body.matchAll(fieldRe)) {
+      const column = fieldMatch[1]!;
+      if (column.startsWith('@') || column === 'id') continue;
+      entities.push({ table, column, operation: 'add_column' });
+    }
+  }
+  return entities;
+}

package/src/core/schema-alignment/extractor/sql.ts

@@ -0,0 +1,99 @@
+// src/core/schema-alignment/extractor/sql.ts
+import type { SchemaEntity } from '../types.ts';
+
+function unquote(s: string | undefined): string {
+  if (!s) return '';
+  return s.replace(/^["'`]|["'`]$/g, '');
+}
+
+// Identifier: quoted or unquoted word (no schema prefix captured)
+const ID = /(?:"([^"]+)"|`([^`]+)`|(\w+))/;
+const SCHEMA_OPT = /(?:\w+\.)?/;
+
+// Keywords that can follow ADD/DROP but are NOT columns
+const NON_COLUMN_KEYWORDS = new Set([
+  'CONSTRAINT', 'INDEX', 'PRIMARY', 'FOREIGN', 'UNIQUE', 'CHECK',
+  'KEY', 'EXCLUDE', 'REFERENCES',
+]);
+
+export function extractFromSql(content: string): SchemaEntity[] {
+  // Strip comments before processing
+  const normalized = content
+    .replace(/--[^\n]*/g, ' ')
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/\s+/g, ' ');
+
+  const entities: SchemaEntity[] = [];
+
+  // CREATE TABLE [IF NOT EXISTS] [schema.]name
+  const createTableRe = new RegExp(
+    `CREATE\\s+(?:OR\\s+REPLACE\\s+)?TABLE\\s+(?:IF\\s+NOT\\s+EXISTS\\s+)?${SCHEMA_OPT.source}${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(createTableRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table && table.toUpperCase() !== 'EXISTS') entities.push({ table, operation: 'create_table' });
+  }
+
+  // ALTER TABLE [schema.]name ADD [COLUMN] [IF NOT EXISTS] col
+  const addColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+ADD\\s+(?:COLUMN\\s+)?(?:IF\\s+NOT\\s+EXISTS\\s+)?${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(addColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const column = unquote(m[4] ?? m[5] ?? m[6]);
+    if (!table || !column) continue;
+    // Skip non-column ADD operations (CONSTRAINT, INDEX, PRIMARY KEY, FOREIGN KEY, UNIQUE, CHECK)
+    if (NON_COLUMN_KEYWORDS.has(column.toUpperCase())) continue;
+    entities.push({ table, column, operation: 'add_column' });
+  }
+
+  // ALTER TABLE [schema.]name DROP [COLUMN] [IF EXISTS] col
+  const dropColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+DROP\\s+(?:COLUMN\\s+)?(?:IF\\s+EXISTS\\s+)?${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(dropColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const column = unquote(m[4] ?? m[5] ?? m[6]);
+    if (!table || !column) continue;
+    // Skip non-column DROP operations (CONSTRAINT, INDEX, PRIMARY KEY, FOREIGN KEY)
+    if (NON_COLUMN_KEYWORDS.has(column.toUpperCase())) continue;
+    entities.push({ table, column, operation: 'drop_column' });
+  }
+
+  // ALTER TABLE [schema.]name RENAME [COLUMN] old TO new
+  const renameColRe = new RegExp(
+    `ALTER\\s+TABLE\\s+(?:ONLY\\s+)?${SCHEMA_OPT.source}${ID.source}\\s+RENAME\\s+(?:COLUMN\\s+)?${ID.source}\\s+TO\\s+${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(renameColRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    const oldName = unquote(m[4] ?? m[5] ?? m[6]);
+    const column = unquote(m[7] ?? m[8] ?? m[9]);
+    if (table && column) entities.push({ table, column, operation: 'rename_column', oldName });
+  }
+
+  // CREATE TYPE [schema.]name
+  const createTypeRe = new RegExp(
+    `CREATE\\s+TYPE\\s+${SCHEMA_OPT.source}${ID.source}`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(createTypeRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table) entities.push({ table, operation: 'create_type' });
+  }
+
+  // ALTER TYPE [schema.]name ADD VALUE ...
+  const alterTypeRe = new RegExp(
+    `ALTER\\s+TYPE\\s+${SCHEMA_OPT.source}${ID.source}\\s+ADD\\s+VALUE`,
+    'gi',
+  );
+  for (const m of normalized.matchAll(alterTypeRe)) {
+    const table = unquote(m[1] ?? m[2] ?? m[3]);
+    if (table) entities.push({ table, operation: 'create_type' });
+  }
+
+  return entities;
+}

package/src/core/schema-alignment/llm-check.ts

@@ -0,0 +1,91 @@
+// src/core/schema-alignment/llm-check.ts
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ReviewEngine } from '../../adapters/review-engine/types.ts';
+import type { SchemaEntity, LayerScanResult, AlignmentFinding } from './types.ts';
+
+const TOTAL_CHAR_BUDGET = 6000;
+
+function truncateTop(text: string, maxChars: number): string {
+  if (text.length <= maxChars) return text;
+  const dropped = text.length - maxChars;
+  return `<!-- [schema-alignment: truncated ${dropped} chars] -->\n` + text.slice(dropped);
+}
+
+export async function runLlmCheck(
+  migrationFiles: string[],
+  gapResults: LayerScanResult[],
+  engine: ReviewEngine,
+): Promise<AlignmentFinding[]> {
+  let budget = TOTAL_CHAR_BUDGET;
+  const migrationSnippets: string[] = [];
+
+  for (const f of migrationFiles) {
+    if (budget <= 0) break;
+    let content: string;
+    try { content = fs.readFileSync(f, 'utf8'); } catch { continue; }
+    const snippet = truncateTop(content, Math.floor(budget * 0.6));
+    migrationSnippets.push(`### Migration: ${path.basename(f)}\n\`\`\`sql\n${snippet}\n\`\`\``);
+    budget -= snippet.length;
+  }
+
+  const entitySummary = gapResults.map(r => {
+    const isDestructive = r.entity.operation === 'drop_column' || r.entity.operation === 'rename_column';
+    const gaps = isDestructive
+      ? [r.typeLayer, r.apiLayer, r.uiLayer]
+          .map((e, i) => e !== null ? (['type', 'api', 'ui'][i]) : null)
+          .filter(Boolean).join(', ')
+      : [r.typeLayer === null ? 'type' : null, r.apiLayer === null ? 'api' : null, r.uiLayer === null ? 'ui' : null]
+          .filter(Boolean).join(', ');
+    return `- ${r.entity.operation} ${r.entity.table}${r.entity.column ? '.' + r.entity.column : ''}: ${isDestructive ? 'stale ref in' : 'missing in'} [${gaps}]`;
+  }).join('\n');
+
+  const prompt = [
+    'You are reviewing schema-layer alignment for a software project.',
+    '',
+    migrationSnippets.length > 0
+      ? `The following migration files were changed:\n\n${migrationSnippets.join('\n\n')}`
+      : '(no readable migration files)',
+    '',
+    `The structural scan found these potential alignment gaps:\n${entitySummary || '(none)'}`,
+    '',
+    'For each gap, determine if it is a real problem. Return findings as a JSON array:',
+    '[{ "table": "name", "column": "name_or_null", "operation": "add_column", "layer": "type", "file": "path/to/relevant/file.ts (optional)", "message": "explanation", "severity": "warning", "confidence": "high" }]',
+    'Return only valid JSON, no prose.',
+  ].join('\n');
+
+  let rawOutput: string;
+  try {
+    const result = await engine.review({ content: prompt, kind: 'file-batch' });
+    rawOutput = result.rawOutput;
+  } catch {
+    return [];
+  }
+
+  const jsonMatch = rawOutput.match(/\[[\s\S]*\]/);
+  if (!jsonMatch) return [];
+
+  try {
+    const parsed = JSON.parse(jsonMatch[0]) as Array<{
+      table: string; column?: string; operation: string;
+      layer: string; message: string; severity: string; confidence: string;
+      file?: string;
+    }>;
+    return parsed
+      .filter(item => item.table && item.layer && item.message)
+      .map(item => ({
+        entity: {
+          table: item.table,
+          column: item.column,
+          operation: item.operation as SchemaEntity['operation'],
+        },
+        layer: item.layer as AlignmentFinding['layer'],
+        message: item.message,
+        file: item.file,
+        severity: (item.severity === 'error' ? 'error' : 'warning') as AlignmentFinding['severity'],
+        confidence: (['high', 'medium', 'low'].includes(item.confidence) ? item.confidence : 'medium') as AlignmentFinding['confidence'],
+      }));
+  } catch {
+    return [];
+  }
+}