arkgate 2.6.0 → 2.7.0

package/bin/ark-shared.mjs

@@ -224,6 +224,10 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/services/**',
       'src/use-cases/**',
       'src/lib/**',
+      // Common Next "app core" bags (API clients, hooks, auth, stores) — not UI routes.
+      // Without these, monorepos like */src/core/** stay ungoverned and produce false greens.
+      'src/core/**',
+      '**/core/**',
       'src/actions/**',
       'src/**/actions.ts',
       'src/**/actions.tsx',
@@ -244,6 +248,20 @@ export function applyFrameworkLayoutOverlays(config, root) {
       'src/lib/prisma/**',
       'src/server/db/**',
     ]);
+    // Demo assets, generated public output, and tool configs are not architecture surface.
+    const nextExcludes = [
+      '**/public/**',
+      '**/*.config.js',
+      '**/*.config.ts',
+      '**/*.config.mjs',
+      '**/playwright*.ts',
+      '**/eslint.config.*',
+      '**/postcss.config.*',
+      '**/prettier.config.*',
+      '**/rstest.config.*',
+      '**/scripts/**',
+    ];
+    next.exclude = [...new Set([...(next.exclude ?? []), ...nextExcludes])];
     next.frameworkOverlay = next.frameworkOverlay
       ? `${next.frameworkOverlay}+next`
       : 'next';
@@ -362,13 +380,16 @@ export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
   return uses;
 }
 
-// Layer glob matching — single source of truth in ark-layer-match.mjs (also used by ESLint).
+// Layer glob matching — generated from canonical src/domain/layerMatch.ts (see generate:layer-match).
 export {
   globToRegExp,
   patternSpecificity,
   layerForFile,
   layerForRelativePath,
   isEdgeDenied,
+  DEFAULT_GENERATED_FILE_GLOBS,
+  scanExcludePatterns,
+  isScanExcludedRelative,
 } from './ark-layer-match.mjs';
 
 function normalizePrefix(prefix) {
@@ -410,102 +431,15 @@ export function looksLikeIntent(value) {
 }
 
 /**
- * Co-pilot Phase F — the work classifier. Every architecture violation is remediated in one of
- * three ways, and this is the TRUST BOUNDARY that decides what an agent may auto-apply:
- *
- *   - 'mechanical-safe' : behavior-preserving AND gate-verifiable → an agent may auto-apply it.
- *   - 'judgment'        : real coupling or a design choice → Ark PROPOSES it, a human decides.
- *   - 'deferred'        : not enough signal to place it → a human should look first.
- *
- * Deliberately biased toward 'judgment': a false 'mechanical-safe' that auto-lands a bad edit
- * is the failure mode that sinks trust. Only statically-provable type-surface fixes earn 'auto':
- *   (1) whole source file is pure type-surface + type-only edge → relocate the file
- *   (2) import/export already marked type-only → move/re-export the type
- *   (3) static value-syntax import of a pure type-only *target* module → import type
- * Pure function of one violation object so CLI, MCP, and apply-loop classify identically.
- * Returns { class, confidence, rationale, remediationKind? }.
+ * Co-pilot Phase F — work classifier + fix-class enrich (R4).
+ * Canonical TypeScript: src/domain/remediation.ts
+ * Generated CLI load path: bin/lib/remediation.mjs (`npm run generate:cli-pure`).
  */
-export const REMEDIATION_CLASSES = ['mechanical-safe', 'judgment', 'deferred'];
-
-export function classifyRemediation(violation) {
-  const ruleId = violation?.ruleId;
-  if (ruleId === 'LAYER_IMPORT_VIOLATION') {
-    // Pure type-only *source file* with a type-only edge: relocating the whole file is
-    // behavior-preserving (no runtime body). Distinct from a single import-type move.
-    if (violation.typeOnly && violation.sourcePureTypeModule) {
-      return {
-        class: 'mechanical-safe',
-        confidence: 0.88,
-        remediationKind: 'pure-type-file-relocate',
-        rationale:
-          'Whole source file is type-only surface (no runtime statements) with a type-only cross-layer edge: relocate the file to the owning layer (or extract the type there). Behavior-preserving; gate verifies.',
-      };
-    }
-    if (violation.typeOnly) {
-      return {
-        class: 'mechanical-safe',
-        confidence: 0.9,
-        remediationKind: 'type-only-import-move',
-        rationale:
-          'Type-only import (erased at runtime): move the type to the layer that owns it and re-export for back-compat. Behavior-preserving, and the gate verifies it.',
-      };
-    }
-    // Target module is a pure type-surface file AND the edge is a static import/export
-    // (flag only set on those edges). Value-syntax `import { T }` → convert to import type.
-    // require()/import() never get this flag (runtime load). Mixed modules stay judgment.
-    if (violation.targetTypeOnlyExports) {
-      const kind = violation.edgeKind;
-      if (kind === 'require' || kind === 'dynamic-import') {
-        return {
-          class: 'judgment',
-          confidence: 0.75,
-          rationale:
-            'Runtime module load (require/import()) of a type-only module still executes the target file — not auto-safe; rewrite to a static import type if appropriate.',
-        };
-      }
-      return {
-        class: 'mechanical-safe',
-        confidence: 0.85,
-        remediationKind: 'import-type-from-pure-type-module',
-        rationale:
-          'Static import targets a pure type-only module: convert to `import type` (erased at runtime) and place the type in a shared/owning layer. No runtime coupling; gate verifies.',
-      };
-    }
-    return {
-      class: 'judgment',
-      confidence: 0.7,
-      rationale:
-        'Value import — real runtime coupling. Relocating it (e.g. a route reaching the DB → a repository) is a refactor whose organization is a human choice.',
-    };
-  }
-  if (ruleId === 'FORBIDDEN_GLOBAL') {
-    return {
-      class: 'judgment',
-      confidence: 0.8,
-      rationale:
-        'Ambient global in a pure layer: inject the capability through a port (Clock, Config, Http). Introducing the port is a design decision.',
-    };
-  }
-  if (ruleId === 'CIRCULAR_DEPENDENCY') {
-    return {
-      class: 'judgment',
-      confidence: 0.7,
-      rationale: 'Dependency cycle: breaking it means deciding which side owns the shared abstraction.',
-    };
-  }
-  if (typeof ruleId === 'string' && ruleId.length > 0) {
-    return {
-      class: 'judgment',
-      confidence: 0.6,
-      rationale: 'Needs a human decision on how to satisfy the contract without weakening the gate.',
-    };
-  }
-  return {
-    class: 'deferred',
-    confidence: 0.3,
-    rationale: 'Unrecognized violation shape — a human should look before anything is changed.',
-  };
-}
+export {
+  REMEDIATION_CLASSES,
+  classifyRemediation,
+  enrichViolationWithFixClass,
+} from './lib/remediation.mjs';
 
 /**
  * Normalize a required/imported TypeScript module for ark-check's host.
@@ -719,7 +653,15 @@ function readPackageJson(root) {
   }
 }
 
-/** Workspace roots from package.json workspaces and pnpm-workspace.yaml (no YAML dependency). */
+/**
+ * Workspace / multi-package roots for monorepo include.
+ * Sources (universal — no project-specific names):
+ * 1. package.json workspaces + pnpm-workspace.yaml
+ * 2. rush.json projectFolder top segments (JSONC-tolerant)
+ * 3. lerna.json packages globs
+ * 4. If still empty: conventional multi-package top-level dirs that exist and
+ *    contain at least one package.json (packages, apps, plugins, services, …)
+ */
 export function detectWorkspaces(root) {
   const dirs = new Set();
   const addGlob = (glob) => {
@@ -727,9 +669,16 @@ export function detectWorkspaces(root) {
     const beforeStar = glob.split('*')[0].replace(/\/+$/, '');
     if (beforeStar && beforeStar !== '.') dirs.add(normalizeRel(beforeStar));
   };
+  const addTop = (rel) => {
+    if (typeof rel !== 'string') return;
+    const top = rel.split(/[/\\]/).filter(Boolean)[0];
+    if (top && top !== '.') dirs.add(normalizeRel(top));
+  };
+
   const pkg = readPackageJson(root);
   const ws = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
   if (Array.isArray(ws)) ws.forEach(addGlob);
+
   const pnpmFile = path.join(root, 'pnpm-workspace.yaml');
   if (fs.existsSync(pnpmFile)) {
     let inPackages = false;
@@ -744,9 +693,183 @@ export function detectWorkspaces(root) {
       if (item) addGlob(item[1].trim());
     }
   }
+
+  // Rush monorepos often have no root package.json workspaces — only rush.json.
+  const rushFile = path.join(root, 'rush.json');
+  if (fs.existsSync(rushFile)) {
+    try {
+      let text = fs.readFileSync(rushFile, 'utf8');
+      text = text.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+      const rush = JSON.parse(text);
+      for (const project of rush.projects || []) {
+        if (typeof project?.projectFolder === 'string') addTop(project.projectFolder);
+      }
+    } catch {
+      /* ignore malformed rush.json */
+    }
+  }
+
+  // Lerna packages globs.
+  const lernaFile = path.join(root, 'lerna.json');
+  if (fs.existsSync(lernaFile)) {
+    try {
+      const lerna = JSON.parse(fs.readFileSync(lernaFile, 'utf8'));
+      if (Array.isArray(lerna.packages)) lerna.packages.forEach(addGlob);
+    } catch {
+      /* ignore */
+    }
+  }
+
+  // Conventional multi-package roots when no explicit workspace manifest listed roots.
+  if (dirs.size === 0) {
+    const conventional = [
+      'packages',
+      'apps',
+      'plugins',
+      'services',
+      'server',
+      'servers',
+      'server-plugins',
+      'libs',
+      'lib',
+      'modules',
+      'foundations',
+      'pods',
+      'models',
+      'clients',
+      'sdks',
+      'tools',
+      'tooling',
+      'desktop',
+      'common',
+    ];
+    for (const name of conventional) {
+      const abs = path.join(root, name);
+      if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
+      if (dirContainsPackageJson(abs, 2)) dirs.add(name);
+    }
+  }
+
   return [...dirs];
 }
 
+/** True if dir (or a child within maxDepth) has a package.json — multi-package root signal. */
+function dirContainsPackageJson(dir, maxDepth) {
+  try {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return true;
+    if (maxDepth <= 0) return false;
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      if (dirContainsPackageJson(path.join(dir, entry.name), maxDepth - 1)) return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+const SKIP_DIR_NAMES = new Set([
+  'node_modules',
+  'dist',
+  'build',
+  'coverage',
+  '.git',
+  '.next',
+  '.turbo',
+  '.cache',
+  'vendor',
+  '__pycache__',
+]);
+
+function dirHasTsSources(dir, maxDepth) {
+  try {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isFile() && /\.(tsx?|jsx?|mts|cts)$/i.test(entry.name)) return true;
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      if (maxDepth > 0 && dirHasTsSources(path.join(dir, entry.name), maxDepth - 1)) return true;
+    }
+  } catch {
+    return false;
+  }
+  return false;
+}
+
+/**
+ * Discover package roots that contain TypeScript/JS sources (polyglot-safe).
+ * Returns relative paths (e.g. remotion-composer, packages/ui). Caps depth/count
+ * to avoid scanning huge trees. Universal — no project-specific names.
+ */
+export function detectTsPackageRoots(root, options = {}) {
+  const maxDepth = options.maxDepth ?? 3;
+  const maxRoots = options.maxRoots ?? 40;
+  const found = [];
+
+  const visit = (abs, rel, depth) => {
+    if (found.length >= maxRoots || depth > maxDepth) return;
+    let entries;
+    try {
+      entries = fs.readdirSync(abs, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    const hasPkg = entries.some((e) => e.isFile() && e.name === 'package.json');
+    if (hasPkg && rel && dirHasTsSources(abs, 3)) {
+      found.push(rel.split(path.sep).join('/'));
+      // Do not descend into nested packages under an already-selected package root
+      // unless maxDepth allows and we want monorepo packages/* children — still scan children
+      // for nested packages (packages/foo).
+    }
+    if (depth >= maxDepth) return;
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (SKIP_DIR_NAMES.has(entry.name) || entry.name.startsWith('.')) continue;
+      // Skip agent skill asset trees (not app code).
+      if (entry.name === 'skills' || entry.name === 'templates' || entry.name === 'fixtures') continue;
+      const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+      visit(path.join(abs, entry.name), childRel, depth + 1);
+    }
+  };
+
+  visit(root, '', 0);
+  // Also treat root itself if it has package.json + TS
+  if (fs.existsSync(path.join(root, 'package.json')) && dirHasTsSources(root, 2)) {
+    if (!found.includes('.')) {
+      // Prefer explicit '.' only when no nested packages found
+      if (found.length === 0) found.push('.');
+    }
+  }
+  return [...new Set(found)].sort();
+}
+
+/**
+ * Merge workspace globs with TS package roots. If workspaces alone would miss
+ * all TS (or are empty), fill from detectTsPackageRoots.
+ */
+export function resolveIncludeRoots(root) {
+  const workspaces = detectWorkspaces(root);
+  const tsRoots = detectTsPackageRoots(root);
+  if (workspaces.length === 0) {
+    if (tsRoots.length > 0) return tsRoots.filter((r) => r !== '.');
+    return [];
+  }
+  // Workspaces present: keep them, add TS package roots not covered by a workspace prefix
+  const merged = new Set(workspaces);
+  for (const tr of tsRoots) {
+    if (tr === '.') continue;
+    const covered = workspaces.some(
+      (w) => tr === w || tr.startsWith(`${w}/`) || w.startsWith(`${tr}/`)
+    );
+    if (!covered) merged.add(tr.split('/')[0]); // top segment if nested
+    // Prefer full package path when it's a direct child
+    if (!tr.includes('/') || workspaces.includes(tr.split('/')[0])) {
+      if (fs.existsSync(path.join(root, tr, 'package.json'))) merged.add(tr);
+    }
+  }
+  return [...merged];
+}
+
 function isSourceFile(name) {
   return /\.(tsx?|jsx?|mjsx?|cjsx?|mts|cts)$/i.test(name);
 }
@@ -822,6 +945,47 @@ function countTsxFiles(files) {
   return files.filter((f) => /\.(tsx|jsx)$/i.test(f)).length;
 }
 
+/**
+ * Merge root + nested package.json dependencies (frontend/, packages/*, apps/*, …).
+ * Hosts that only put `arkgate` at the monorepo root and Next under frontend/ must
+ * still detect nextFramework so layout overlays (src/core/**) apply on day one.
+ */
+export function collectAggregatedDeps(root) {
+  const deps = {};
+  const mergePkg = (pkg) => {
+    if (!pkg || typeof pkg !== 'object') return;
+    for (const key of ['dependencies', 'devDependencies', 'peerDependencies', 'optionalDependencies']) {
+      const block = pkg[key];
+      if (block && typeof block === 'object') Object.assign(deps, block);
+    }
+  };
+  mergePkg(readPackageJson(root));
+  let entries = [];
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return deps;
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+    const childRoot = path.join(root, entry.name);
+    mergePkg(readPackageJson(childRoot));
+    // One level under conventional multi-package roots
+    if (['packages', 'apps', 'services', 'plugins', 'packages-internal'].includes(entry.name)) {
+      try {
+        for (const sub of fs.readdirSync(childRoot, { withFileTypes: true })) {
+          if (sub.isDirectory() && !sub.name.startsWith('.')) {
+            mergePkg(readPackageJson(path.join(childRoot, sub.name)));
+          }
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+  }
+  return deps;
+}
+
 /**
  * Collect deterministic repo shape signals for architecture archetype scoring.
  * Vendor packages may appear in toolHints only — never as the primary label.
@@ -830,7 +994,20 @@ export function collectRepoShapeSignals(root) {
   const pkg = readPackageJson(root);
   const workspaceDirs = detectWorkspaces(root);
   const workspaces = workspaceDirs.length > 0;
-  const srcDirs = ['src', 'lib', 'api', 'packages', 'apps'].filter((d) =>
+  // Include frontend/web/client — common Next monorepo app folders (deer-flow-style).
+  const candidateScanDirs = [
+    'src',
+    'lib',
+    'api',
+    'packages',
+    'apps',
+    'frontend',
+    'web',
+    'client',
+    'app',
+    ...workspaceDirs,
+  ];
+  const srcDirs = [...new Set(candidateScanDirs)].filter((d) =>
     fs.existsSync(path.join(root, d))
   );
   const scanRoots = srcDirs.length > 0 ? srcDirs.map((d) => path.join(root, d)) : [root];
@@ -838,13 +1015,14 @@ export function collectRepoShapeSignals(root) {
   const sourceFileCount = sourceFiles.length;
   const tinyTree = sourceFileCount < 3;
 
-  const deps = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
+  // Nested package.json deps (not root-only) — critical for monorepo Next under frontend/
+  const deps = collectAggregatedDeps(root);
   const hasUiFramework = Object.keys(deps).some((name) =>
     /^(react|react-dom|vue|svelte|preact|solid-js)$/i.test(name.split('/')[0])
   );
   const srcUiFiles = sourceFiles.filter((file) => {
     const rel = path.relative(root, file).split(path.sep).join('/');
-    return rel.startsWith('src/') && /\.(tsx|jsx)$/i.test(file);
+    return (rel.includes('/src/') || rel.startsWith('src/')) && /\.(tsx|jsx)$/i.test(file);
   });
 
   const topNames = new Set(srcDirs.flatMap((d) => listTopLevelDirNames(root, d)));
@@ -860,7 +1038,8 @@ export function collectRepoShapeSignals(root) {
       const rel = path.relative(root, file).split(path.sep).join('/');
       return (
         /(^|\/)next\.config\./.test(rel) ||
-        /(^|\/)app\/.*\/page\.(t|j)sx?$/.test(rel) ||
+        // app/page.tsx OR app/dashboard/page.tsx (middle segment optional)
+        /(^|\/)app\/(?:.*\/)?page\.(t|j)sx?$/.test(rel) ||
         /(^|\/)pages\/.+\.(t|j)sx?$/.test(rel)
       );
     });
@@ -1127,7 +1306,15 @@ export function scoreArchetypes(signals, playbook) {
   const rawConfidence = top.score / top.maxPositive;
   const margin =
     second && second.score > 0 ? (top.score - second.score) / Math.max(top.score, 1) : 0.25;
-  const confidence = Math.min(1, Math.max(0.1, rawConfidence * 0.7 + margin * 0.3));
+  let confidence = Math.min(1, Math.max(0.1, rawConfidence * 0.7 + margin * 0.3));
+  // Thin / zero TS surface: never present a high-confidence archetype as the sole answer.
+  const thinTs =
+    !signals.sourceFileCount ||
+    signals.sourceFileCount < 8 ||
+    signals.tinyTree;
+  if (thinTs) {
+    confidence = Math.min(confidence, 0.28);
+  }
 
   return {
     ranked: scored,
@@ -1135,6 +1322,13 @@ export function scoreArchetypes(signals, playbook) {
     label: top.label,
     preset: top.preset,
     confidence: Math.round(confidence * 1000) / 1000,
+    ...(thinTs
+      ? {
+          thinTsSurface: true,
+          caution:
+            'TypeScript/JS surface is thin or missing — treat the archetype as a weak hint. Prefer ark-check --suggest-include / --adopt-contract on the real package roots before scaffolding.',
+        }
+      : {}),
     phases: top.phases,
     analogy: top.analogy,
     antiPatterns: top.antiPatterns,
@@ -1169,6 +1363,7 @@ export function buildArchitectureRecommendation(root, options = {}) {
     label: result.label,
     preset: result.preset,
     confidence: result.confidence,
+    ...(result.thinTsSurface ? { thinTsSurface: true, caution: result.caution } : {}),
     phases: result.phases,
     adoptInOrder,
     analogy: result.analogy,
@@ -1265,75 +1460,19 @@ export function shouldShowNewHereNudge(root, configPath, governedPercent, config
   return false;
 }
 
-/**
- * Deterministic fix-class labels for JSON output (English, shared with future skills).
- */
-export function enrichViolationWithFixClass(violation) {
-  const enriched = { ...violation };
-  switch (violation.ruleId) {
-    case 'LAYER_IMPORT_VIOLATION':
-      if (violation.typeOnly || violation.targetTypeOnlyExports) {
-        enriched.fixClass = 'file-move';
-        enriched.effort = 'small';
-        enriched.enthusiastHint = violation.targetTypeOnlyExports
-          ? 'The imported module only exports types — use `import type` and place the type in a layer both sides may share.'
-          : 'This is a type-only import — move the type to a layer both sides may share, or relocate the file to match its role.';
-      } else {
-        enriched.fixClass = 'port-inversion';
-        enriched.effort = 'medium';
-        enriched.enthusiastHint = `${violation.fromLayer ?? 'This layer'} must not import ${violation.toLayer ?? 'that layer'} directly. Define an interface (port) where you need the capability and inject the implementation from the outer layer.`;
-      }
-      break;
-    case 'FORBIDDEN_GLOBAL':
-      enriched.fixClass = 'inject-port';
-      enriched.effort = 'small';
-      enriched.enthusiastHint = `Do not call "${violation.target ?? 'that global'}" here. Pass the capability in through a small interface (for example a Clock, HttpPort, or Config provider).`;
-      break;
-    case 'RAW_EVENT_PUBLISH':
-      enriched.fixClass = 'registered-intent';
-      enriched.effort = 'small';
-      enriched.enthusiastHint =
-        'Register the event intent first, then publish through the creator returned by the registry — not a raw string or object.';
-      break;
-    case 'PUBLISH_MISSING_SOURCE':
-      enriched.fixClass = 'add-source-metadata';
-      enriched.effort = 'small';
-      enriched.enthusiastHint =
-        'Add metadata.source to the publish call so Ark knows which layer is publishing the event.';
-      break;
-    case 'PUBLISH_SOURCE_LAYER_MISMATCH':
-      enriched.fixClass = 'fix-source-layer';
-      enriched.effort = 'small';
-      enriched.enthusiastHint =
-        'Use a source intent that belongs to the same layer as this file, or move the publish call to the layer that owns the source.';
-      break;
-    case 'LAYER_INTENT_REFERENCE_VIOLATION':
-      enriched.fixClass = 'intent-relocation';
-      enriched.effort = 'small';
-      enriched.enthusiastHint =
-        'Reference that intent from a layer allowed to know about it — usually an adapter or application layer, not the domain core.';
-      break;
-    case 'CIRCULAR_DEPENDENCY':
-      enriched.fixClass = 'break-cycle';
-      enriched.effort = 'medium';
-      enriched.enthusiastHint =
-        'Two modules import each other in a loop. Extract shared code, invert one dependency behind a port, or merge them if they are really one unit.';
-      break;
-    default:
-      enriched.fixClass = 'review-contract';
-      enriched.effort = 'small';
-      enriched.enthusiastHint =
-        'Read the violation message and the layer rules in ark.config.json, then adjust imports or move code to the correct layer.';
-  }
-  return enriched;
-}
-
 export function formatArchitectureRecommendationHuman(recommendation) {
   const lines = [];
   lines.push('Ark architecture recommendation (application shape, not vendor stack)');
   lines.push('');
   lines.push(`Archetype: ${recommendation.archetype} — ${recommendation.label}`);
   lines.push(`Preset: ${recommendation.preset} (confidence ${recommendation.confidence})`);
+  if (recommendation.thinTsSurface) {
+    lines.push('');
+    lines.push(
+      `⚠ Thin TypeScript surface (${recommendation.signals?.sourceFileCount ?? 0} files) — confidence is capped. Do not treat this as a firm shape.`
+    );
+    if (recommendation.caution) lines.push(recommendation.caution);
+  }
   if (recommendation.runnerUp?.id) {
     lines.push(
       `Runner-up: ${recommendation.runnerUp.id}${recommendation.runnerUp.label ? ` (${recommendation.runnerUp.label})` : ''}`