arkgate 2.6.0 → 2.7.0

package/bin/ark-check.mjs

@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 import { spawnSync } from 'node:child_process';
-import crypto from 'node:crypto';
 import fs from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -15,7 +13,6 @@ import {
   DEFAULT_RULES,
   applyFrameworkLayoutOverlays,
   arkCommand,
-  collectForbiddenGlobalUses,
   ADOPTION_PLAN_FILENAME,
   buildArchitectureRecommendation,
   createElevenLayerConfig,
@@ -23,43 +20,27 @@ import {
   listPolicyPackIds,
   loadPolicyPackMeta,
   writeAdoptionPlan,
-  classifyRemediation,
-  detectPackageManager,
-  execCommandParts,
-  execRunner,
+  detectWorkspaces,
+  detectTsPackageRoots,
+  resolveIncludeRoots,
   formatArchitectureRecommendationHuman,
-  globToRegExp,
   installDevHint,
-  presentLockfiles,
   layerForFile,
-  looksLikeIntent,
-  patternSpecificity,
-  resolveIntentLayer,
-  resolveOperatingMode,
-  shouldShowNewHereNudge,
-  usableTypescript,
-  typescriptUsabilityHint,
 } from './ark-shared.mjs';
 
 import {
   runInstallAgentGates,
-  runMigrateCommands,
   loadTypeScript,
-  collectAdoptionGaps,
   detectSkillGaps,
   detectCodexHomeGap,
   missingGates,
   staleRunnerGateFiles,
   brokenMcpGateFiles,
   readJson,
-  readPackageJson,
   hasCheckArchitectureScript,
-  hasArkWorkflow,
   checkArchitectureScriptSnippet,
   arkCheckCommand,
   arkPackageVersion,
-  agentInstructions,
-  packageManager,
   REQUIRED_GATE_FILES,
   codexPromptsDir,
 } from './lib/agent-gates.mjs';
@@ -78,33 +59,35 @@ import {
   runCoverage,
   runPlan,
   runDoctor,
-  buildRemediationPlan,
 } from './lib/doctor-plan.mjs';
 import {
   baselineKey,
   readBaseline,
   summarizeViolations,
-  violationEdge,
   writeBaseline,
   printViolation,
   printViolationBreakdown,
   CONCENTRATION_MIN_VIOLATIONS,
 } from './lib/violations.mjs';
 import {
-  buildUnclassifiedSuggestions,
   suggestLayerForDir,
-  suggestLayerForPath,
   detectBestFitModel,
   dirSegmentsFromGlob,
 } from './lib/suggestions.mjs';
 import {
   ARCHITECTURE_PRESETS,
-  CANONICAL_LAYER_NAMES,
-  denyUpward,
-  presetWithOverlays,
-  FRAMEWORK_INTERNAL_EXCLUDE,
 } from './lib/presets.mjs';
 
+import {
+  collectGovernedFiles,
+  normalize,
+  walk,
+} from './lib/scan-files.mjs';
+import {
+  configWarning,
+} from './lib/config-warnings.mjs';
+import { runArchitectureScan } from './lib/architecture-scan.mjs';
+
 
 function parseArgs(argv) {
   const args = {
@@ -168,6 +151,9 @@ function parseArgs(argv) {
     else if (arg === '--write-plan') args.writePlan = true;
     else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
     else if (arg === '--apply-policy-pack') args.applyPolicyPack = argv[++i];
+    else if (arg === '--suggest-include') args.suggestInclude = true;
+    else if (arg === '--adopt-contract') args.adoptContract = true;
+    else if (arg === '--write') args.write = true;
     else if (arg === '--watch') args.watch = true;
     else if (arg === '--beginner') args.beginner = true;
     else if (arg === '--codex-home') args.codexHome = true;
@@ -213,8 +199,10 @@ function usage() {
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
-    '       ark-check --list-policy-packs            enthusiast preset configs (hexagonal, layered, feature-sliced, monorepo)',
+    '       ark-check --list-policy-packs            enthusiast preset configs (hexagonal, layered, feature-sliced, monorepo, ui-surface)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',
+    '       ark-check --suggest-include [--json]   propose include roots (TS packages / workspaces)',
+    '       ark-check --adopt-contract [--write]   expand include + UI patterns from ungoverned dirs (contract adopt)',
     '       ark-check --watch                      re-run the check when governed files change (debounced)',
     '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive]',
     '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
@@ -249,6 +237,7 @@ function usage() {
     'Config shape:',
     '{',
     '  "include": ["src"],',
+    '  // optional: "exclude": ["**/vendor/**"], "excludeGenerated": false  (default skips *.gen.ts / *.generated.ts)',
     '  "layers": [',
     '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."],',
     '      "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"] }',
@@ -289,7 +278,6 @@ function usage() {
   ].join('\n');
 }
 
-
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
     ? configPath
@@ -306,6 +294,9 @@ function readConfig(root, configPath) {
     include: raw.include ?? ['src'],
     layers: raw.layers ?? [],
     rules: raw.rules ?? DEFAULT_RULES,
+    ...(raw.exclude ? { exclude: raw.exclude } : {}),
+    ...(raw.excludeGenerated !== undefined ? { excludeGenerated: raw.excludeGenerated } : {}),
+    ...(raw.cyclePolicy ? { cyclePolicy: raw.cyclePolicy } : {}),
   };
 }
 
@@ -362,39 +353,8 @@ function uncoveredDirectories(root, srcDir, layers) {
     });
 }
 
-// Reads workspace globs from package.json (npm/yarn/bun `workspaces`, array or
-// `{ packages: [] }`) and pnpm-workspace.yaml, returning the distinct base directories
-// (the glob prefix before the first `*`), e.g. "packages/*" -> "packages". Empty when
-// the project declares no workspaces — the signal that says "this is a monorepo".
-function detectWorkspaces(root) {
-  const dirs = new Set();
-  const addGlob = (glob) => {
-    if (typeof glob !== 'string') return;
-    const beforeStar = glob.split('*')[0].replace(/\/+$/, '');
-    if (beforeStar && beforeStar !== '.') dirs.add(normalize(beforeStar));
-  };
-  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)) {
-    // Minimal read (no YAML dep): collect list items under the top-level `packages:` key
-    // ONLY. pnpm files also carry other list-valued keys (onlyBuiltDependencies, catalog,
-    // …) whose items are NOT workspace globs — a key-agnostic scan would pull those in.
-    let inPackages = false;
-    for (const line of fs.readFileSync(pnpmFile, 'utf8').split('\n')) {
-      const keyMatch = line.match(/^([A-Za-z0-9_-]+):/); // top-level key (no indentation)
-      if (keyMatch) {
-        inPackages = keyMatch[1] === 'packages';
-        continue;
-      }
-      if (!inPackages) continue;
-      const item = line.match(/^\s+-\s*['"]?([^'"#]+?)['"]?\s*$/); // indented list item
-      if (item) addGlob(item[1].trim());
-    }
-  }
-  return [...dirs];
-}
+// detectWorkspaces: shared implementation in ark-shared.mjs (npm/pnpm/rush/lerna +
+// conventional multi-package roots).
 
 // Deny every "upward" edge for an ordered layer list (index 0 = outermost/top,
 // which may import everything below it). Inner/lower layers must not import outer
@@ -455,7 +415,10 @@ function buildConfigFromPolicyPack(packId, root) {
       `Policy pack "${packId}" references unknown preset "${pack.preset}".`
     );
   }
-  const workspaces = pack.preset === 'monorepo' ? detectWorkspaces(root) : [];
+  const workspaces =
+    pack.preset === 'monorepo' || pack.preset === 'ui-surface'
+      ? resolveIncludeRoots(root)
+      : [];
   const config = factory(workspaces, root);
   if (pack.layerDescriptions) {
     for (const layer of config.layers) {
@@ -553,7 +516,7 @@ const THIN_COVERAGE_PERCENT = 50;
 function maybeWarnBrownfield(root, config) {
   let files;
   try {
-    files = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+    files = collectGovernedFiles(root, config);
   } catch {
     return false;
   }
@@ -577,6 +540,144 @@ function maybeWarnBrownfield(root, config) {
   return true;
 }
 
+/** Propose include roots (workspaces + nested TS packages) — contract-adopt primitive. */
+function runSuggestInclude(args) {
+  const root = args.root;
+  const workspaces = detectWorkspaces(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const include = resolveIncludeRoots(root);
+  const payload = {
+    ok: true,
+    workspaces,
+    tsPackages,
+    suggestedInclude: include.length > 0 ? include : tsPackages.length > 0 ? tsPackages : ['src'],
+    note:
+      include.length === 0 && tsPackages.length === 0
+        ? 'No TS packages or workspaces found — default suggestion is src/ (create it or pass include by hand).'
+        : 'Use these paths as ark.config.json "include". Prefer --adopt-contract --write to expand patterns too.',
+  };
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(color.bold('Suggested include roots'));
+  console.log(`  workspaces: ${workspaces.join(', ') || '(none)'}`);
+  console.log(`  tsPackages: ${tsPackages.join(', ') || '(none)'}`);
+  console.log(`  suggestedInclude: ${payload.suggestedInclude.join(', ')}`);
+  console.log(color.dim(payload.note));
+}
+
+/**
+ * Contract-adopt: expand include + presentation patterns from ungoverned proposals.
+ * Read-only unless --write. Does not weaken rules or baseline violations.
+ */
+function runAdoptContract(args) {
+  const root = args.root;
+  const configPath = path.isAbsolute(args.config)
+    ? args.config
+    : path.join(root, args.config);
+  let config;
+  try {
+    config = fs.existsSync(configPath)
+      ? readConfig(root, args.config)
+      : {
+          include: ['src'],
+          layers: ARCHITECTURE_PRESETS['ui-surface']([], root).layers,
+          rules: ARCHITECTURE_PRESETS['ui-surface']([], root).rules,
+        };
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+    return;
+  }
+  const suggestedInclude = resolveIncludeRoots(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const nextInclude = [
+    ...new Set([
+      ...(config.include || []),
+      ...(suggestedInclude.length > 0 ? suggestedInclude : tsPackages),
+    ]),
+  ].filter(Boolean);
+  const files = collectGovernedFiles(root, { ...config, include: nextInclude.length ? nextInclude : config.include });
+  const cov = computeCoverage(root, { ...config, include: nextInclude.length ? nextInclude : config.include }, files, config.rules || []);
+  const uiPatterns = [
+    '**/components/**',
+    '**/hooks/**',
+    '**/lib/**',
+    '**/routes/**',
+    '**/app/**',
+    '**/pages/**',
+  ];
+  const layers = (config.layers || []).map((layer) => {
+    if (layer.name !== 'PresentationAdapters') return layer;
+    const patterns = [...new Set([...(layer.patterns || []), ...uiPatterns])];
+    return { ...layer, patterns };
+  });
+  // If no PresentationAdapters layer, leave layers as-is (don't invent full profile).
+  const proposal = {
+    ok: true,
+    before: {
+      include: config.include || [],
+      governedPercent: null,
+      totalFiles: null,
+    },
+    after: {
+      include: nextInclude.length > 0 ? nextInclude : config.include,
+      presentationPatterns: uiPatterns,
+      totalFiles: cov.totalFiles,
+      governedPercent: cov.governed.percent,
+      unclassified: cov.unclassified.count,
+    },
+    wrote: false,
+  };
+  // Compute before coverage for honesty.
+  try {
+    const beforeFiles = collectGovernedFiles(root, config);
+    const beforeCov = computeCoverage(root, config, beforeFiles, config.rules || []);
+    proposal.before.totalFiles = beforeCov.totalFiles;
+    proposal.before.governedPercent = beforeCov.governed.percent;
+  } catch {
+    /* ignore */
+  }
+
+  if (args.write) {
+    const next = {
+      ...config,
+      include: proposal.after.include,
+      layers,
+    };
+    fs.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    proposal.wrote = true;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(proposal, null, 2));
+    return;
+  }
+  console.log(color.bold('Contract adopt (coverage first)'));
+  console.log(
+    `  before: include=[${(proposal.before.include || []).join(', ')}] governed=${proposal.before.governedPercent ?? '?'}% files=${proposal.before.totalFiles ?? '?'}`
+  );
+  console.log(
+    `  after:  include=[${(proposal.after.include || []).join(', ')}] governed=${proposal.after.governedPercent}% files=${proposal.after.totalFiles} unclassified=${proposal.after.unclassified}`
+  );
+  console.log(`  presentation patterns += ${uiPatterns.join(', ')}`);
+  if (proposal.wrote) {
+    console.log(color.green(`  wrote ${path.relative(root, configPath) || args.config}`));
+    console.log(color.dim(`  Next: ${arkCommand(root, 'ark-check', '--coverage')} then --plan`));
+  } else {
+    console.log(color.dim('  Dry-run only. Re-run with --write to apply (does not weaken rules).'));
+  }
+  if ((proposal.after.totalFiles ?? 0) === 0) {
+    console.log(
+      color.yellow(
+        '  Empty scope remains — no TS packages found. Point include at your package roots manually.'
+      )
+    );
+    process.exitCode = 1;
+  }
+}
+
 function runInit(args) {
   const configPath = path.isAbsolute(args.config)
     ? args.config
@@ -597,7 +698,12 @@ function runInit(args) {
       process.exitCode = 2;
       return;
     }
-    const finalConfig = factory(detectWorkspaces(args.root), args.root);
+    const finalConfig = factory(
+      args.preset === 'monorepo' || args.preset === 'ui-surface'
+        ? resolveIncludeRoots(args.root)
+        : detectWorkspaces(args.root),
+      args.root
+    );
     fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
     console.log(`Wrote ${configPath} (${args.preset} preset)`);
     if (finalConfig.frameworkOverlay) {
@@ -625,8 +731,14 @@ function runInit(args) {
   // When no conventional src/ layout is found, a `workspaces` declaration means this is a
   // monorepo — the src/** 11-layer starter would match nothing there, so use the
   // cross-package monorepo profile anchored at the real workspace roots instead.
-  const workspaces = greenfield ? detectWorkspaces(args.root) : [];
-  const mode = !greenfield ? 'detected' : workspaces.length > 0 ? 'monorepo' : 'greenfield';
+  const includeRoots = greenfield ? resolveIncludeRoots(args.root) : [];
+  const tsPackages = greenfield ? detectTsPackageRoots(args.root) : [];
+  // Prefer monorepo/ui when nested TS packages exist without a conventional src layout.
+  const mode = !greenfield
+    ? 'detected'
+    : includeRoots.length > 0 || tsPackages.length > 0
+      ? 'monorepo'
+      : 'greenfield';
   // Greenfield: anchor the starter profile at src/ (the convention a fresh project will
   // scaffold under) even when src/ doesn't exist yet — the layers are optional, so the
   // check passes today and governance switches on the moment src/domain/ etc. appear.
@@ -635,7 +747,10 @@ function runInit(args) {
     mode === 'detected'
       ? applyFrameworkLayoutOverlays(config, args.root)
       : mode === 'monorepo'
-        ? ARCHITECTURE_PRESETS.monorepo(workspaces, args.root)
+        ? ARCHITECTURE_PRESETS.monorepo(
+            includeRoots.length > 0 ? includeRoots : tsPackages,
+            args.root
+          )
         : createElevenLayerConfig({
             rootDir: srcDir === '.' ? 'src' : srcDir,
             root: args.root,
@@ -646,10 +761,11 @@ function runInit(args) {
   console.log(`Wrote ${configPath}`);
   console.log('');
   if (mode === 'monorepo') {
-    console.log(`Monorepo detected (workspaces: ${workspaces.join(', ')}). Generated a cross-package`);
-    console.log('profile matching domain/application/presentation/persistence directories in any');
-    console.log('package. Every layer is optional, so the strict check passes now and each switches');
-    console.log('on as matching directories gain files. Adjust patterns to your naming if they differ:');
+    const roots = finalConfig.include?.join(', ') || '(none)';
+    console.log(`Multi-package / TS package surface detected (include: ${roots}). Generated a`);
+    console.log('cross-package profile matching domain/application/presentation/persistence dirs');
+    console.log('in any package. Every layer is optional, so the strict check passes now and each');
+    console.log('switches on as matching directories gain files. Adjust patterns to your naming:');
     for (const layer of finalConfig.layers) {
       console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
     }
@@ -726,7 +842,6 @@ function runInit(args) {
   printInitNextSteps(args.root);
 }
 
-
 function readManifest(root, manifestPath) {
   if (!manifestPath) return undefined;
   const fullPath = path.isAbsolute(manifestPath)
@@ -738,653 +853,6 @@ function readManifest(root, manifestPath) {
   return readJson(fullPath);
 }
 
-const SOURCE_FILE_NAME = /\.[cm]?[tj]sx?$/;
-
-/** Unit/e2e test files are not architecture surface — agents and Nest put them next
- *  to production code (*.spec.ts). Counting them as ungoverned forces false
- *  CONFIG_UNCLASSIFIED_FILES under --strict-config on every starter. */
-const TEST_FILE_NAME =
-  /\.(spec|test)\.(tsx?|jsx?|mts|cts)$/i;
-
-function isGovernableSourceFile(name) {
-  return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
-}
-
-function isSkippedSourceDir(name) {
-  return (
-    name === 'node_modules' ||
-    name === 'dist' ||
-    name === 'coverage' ||
-    name === '__tests__' ||
-    name === '__mocks__' ||
-    name === 'e2e' ||
-    // Top-level style Nest/Jest folders (not "testing" helpers inside src)
-    name === 'test' ||
-    name === 'tests'
-  );
-}
-
-function walk(dir, files = []) {
-  const stat = fs.statSync(dir, { throwIfNoEntry: false });
-  if (!stat) return files;
-  // An `include` entry may be a single file (e.g. a root-level "middleware.ts"),
-  // not just a directory — govern it directly instead of trying to scandir it
-  // (which threw ENOTDIR). The extension filter still applies.
-  if (stat.isFile()) {
-    if (isGovernableSourceFile(path.basename(dir))) files.push(dir);
-    return files;
-  }
-  if (!stat.isDirectory()) return files;
-  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-    const full = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      if (isSkippedSourceDir(entry.name)) continue;
-      walk(full, files);
-    } else if (isGovernableSourceFile(entry.name)) {
-      files.push(full);
-    }
-  }
-  return files;
-}
-
-function normalize(value) {
-  return value.split(path.sep).join('/');
-}
-
-function intentLayersFromManifest(manifest) {
-  const layers = manifest?.architecture?.layers;
-  if (!Array.isArray(layers)) return undefined;
-  return layers
-    .filter((layer) => Array.isArray(layer.prefixes) && layer.prefixes.length > 0)
-    .map((layer) => ({ name: layer.name, prefixes: layer.prefixes }));
-}
-
-function layerForIntent(intent, layers, manifestIntentLayers) {
-  // Use only layers that declare intent prefixes; fall back to the built-in defaults when
-  // none do (mirrors the write-gate). resolveIntentLayer applies the library's exact
-  // longest-prefix + trailing-dot semantics so CI and the MCP gate classify identically.
-  const configured =
-    manifestIntentLayers ??
-    layers
-      .filter((layer) => (layer.intentPrefixes ?? []).length > 0)
-      .map((layer) => ({ name: layer.name, prefixes: layer.intentPrefixes }));
-  const source =
-    configured.length > 0
-      ? configured
-      : DEFAULT_INTENT_PREFIXES.map((entry) => ({ name: entry.layer, prefixes: entry.prefixes }));
-  return resolveIntentLayer(intent, source);
-}
-
-function isBlocked(rules, from, to) {
-  return rules.find((rule) => !rule.allowed && rule.from === from && rule.to === to);
-}
-
-function configWarning(ruleId, message, extra = {}) {
-  return { ruleId, message, ...extra };
-}
-
-function collectConfigWarnings(root, config, files, rules, manifest) {
-  const warnings = [];
-  const layers = Array.isArray(config.layers) ? config.layers : [];
-  const manifestLayers = Array.isArray(manifest?.architecture?.layers)
-    ? manifest.architecture.layers
-    : [];
-  const knownLayers = new Set([
-    ...layers.map((layer) => layer.name).filter(Boolean),
-    ...manifestLayers.map((layer) => layer.name).filter(Boolean),
-  ]);
-
-  if (layers.length === 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_NO_LAYERS',
-        'No file layers are configured; ark-check cannot classify files for import-boundary enforcement.'
-      )
-    );
-  }
-
-  const seenLayers = new Set();
-  const duplicateLayers = new Set();
-  for (const layer of layers) {
-    if (!layer.name) {
-      warnings.push(
-        configWarning('CONFIG_LAYER_WITHOUT_NAME', 'A configured layer is missing a name.')
-      );
-      continue;
-    }
-    if (seenLayers.has(layer.name)) duplicateLayers.add(layer.name);
-    seenLayers.add(layer.name);
-
-    if (
-      layer.forbiddenGlobals !== undefined &&
-      (!Array.isArray(layer.forbiddenGlobals) ||
-        layer.forbiddenGlobals.some((entry) => typeof entry !== 'string'))
-    ) {
-      warnings.push(
-        configWarning(
-          'CONFIG_INVALID_FORBIDDEN_GLOBALS',
-          `Layer "${layer.name}" has an invalid forbiddenGlobals value; expected an array of strings (e.g. ["fetch", "Date.now"]). The entry is ignored.`,
-          { layer: layer.name }
-        )
-      );
-    }
-
-    const patterns = Array.isArray(layer.patterns) ? layer.patterns : [];
-    if (patterns.length === 0) {
-      warnings.push(
-        configWarning(
-          'CONFIG_LAYER_WITHOUT_PATTERNS',
-          `Layer "${layer.name}" has no file patterns and will never classify files.`,
-          { layer: layer.name }
-        )
-      );
-      continue;
-    }
-
-    for (const pattern of patterns) {
-      let re;
-      try {
-        re = globToRegExp(pattern);
-      } catch (err) {
-        warnings.push(
-          configWarning(
-            'CONFIG_INVALID_LAYER_PATTERN',
-            `Layer "${layer.name}" has an invalid pattern "${pattern}": ${
-              err instanceof Error ? err.message : String(err)
-            }`,
-            { layer: layer.name, pattern }
-          )
-        );
-        continue;
-      }
-
-      const matched = files.some((file) => {
-        const rel = normalize(path.relative(root, file));
-        return re.test(rel);
-      });
-      if (!matched && !layer.optional) {
-        warnings.push(
-          configWarning(
-            'CONFIG_LAYER_PATTERN_NO_MATCHES',
-            `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
-            { layer: layer.name, pattern }
-          )
-        );
-      }
-    }
-  }
-
-  for (const name of duplicateLayers) {
-    warnings.push(
-      configWarning(
-        'CONFIG_DUPLICATE_LAYER',
-        `Layer "${name}" is configured more than once.`,
-        { layer: name }
-      )
-    );
-  }
-
-  if (knownLayers.size > 0) {
-    for (const rule of rules ?? []) {
-      if (rule.from && !knownLayers.has(rule.from)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_FROM_LAYER',
-            `Rule references unknown source layer "${rule.from}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-      if (rule.to && !knownLayers.has(rule.to)) {
-        warnings.push(
-          configWarning(
-            'CONFIG_RULE_UNKNOWN_TO_LAYER',
-            `Rule references unknown target layer "${rule.to}".`,
-            { fromLayer: rule.from, toLayer: rule.to }
-          )
-        );
-      }
-    }
-  }
-
-  // Ambiguous overlap: a file matched by two different layers at the SAME top specificity.
-  // layerForFile breaks the tie by declaration order, but the config is genuinely undecided
-  // (unlike a facade split, where the surface pattern is strictly more specific and wins
-  // cleanly). Surface the layer pairs so the author disambiguates instead of relying on order.
-  const ambiguousPairs = new Set();
-  if (layers.length > 1) {
-    for (const file of files) {
-      const rel = normalize(path.relative(root, file));
-      let topScore = -1;
-      let topLayers = [];
-      for (const layer of layers) {
-        for (const pattern of layer.patterns ?? []) {
-          if (!globToRegExp(pattern).test(rel)) continue;
-          const score = patternSpecificity(pattern);
-          if (score > topScore) {
-            topScore = score;
-            topLayers = [layer.name];
-          } else if (score === topScore && !topLayers.includes(layer.name)) {
-            topLayers.push(layer.name);
-          }
-        }
-      }
-      if (topLayers.length > 1) {
-        ambiguousPairs.add([...topLayers].sort().join(' + '));
-      }
-    }
-  }
-  if (ambiguousPairs.size > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_AMBIGUOUS_LAYERS',
-        `Some files match multiple layers at equal specificity; classification falls back to declaration order. Disambiguate the overlapping patterns: ${[...ambiguousPairs].join(', ')}.`,
-        { pairs: [...ambiguousPairs] }
-      )
-    );
-  }
-
-  const unclassified = files.filter((file) => !layerForFile(root, file, layers));
-  if (unclassified.length > 0) {
-    warnings.push(
-      configWarning(
-        'CONFIG_UNCLASSIFIED_FILES',
-        `${unclassified.length} included source file(s) are not matched by any configured layer; ark-check will not enforce import rules for those source files.`,
-        {
-          count: unclassified.length,
-          samples: unclassified.slice(0, 5).map((file) => normalize(path.relative(root, file))),
-        }
-      )
-    );
-  }
-
-  return warnings;
-}
-
-function createModuleResolutionHost(ts) {
-  const sys = ts?.sys;
-  const fileExists = (f) => {
-    if (sys?.fileExists) return sys.fileExists(f);
-    return fs.existsSync(f);
-  };
-  const readFile = (f) => {
-    if (sys?.readFile) return sys.readFile(f);
-    try {
-      return fs.readFileSync(f, 'utf8');
-    } catch {
-      return undefined;
-    }
-  };
-  const directoryExists = (d) => {
-    if (sys?.directoryExists) return sys.directoryExists(d);
-    try {
-      return fs.statSync(d).isDirectory();
-    } catch {
-      return false;
-    }
-  };
-  return {
-    fileExists,
-    readFile,
-    directoryExists,
-    getCurrentDirectory: () =>
-      sys?.getCurrentDirectory ? sys.getCurrentDirectory() : process.cwd(),
-    getDirectories: (d) => {
-      if (sys?.getDirectories) return sys.getDirectories(d);
-      try {
-        return fs
-          .readdirSync(d, { withFileTypes: true })
-          .filter((e) => e.isDirectory())
-          .map((e) => e.name);
-      } catch {
-        return [];
-      }
-    },
-    realpath: sys?.realpath ? (p) => sys.realpath(p) : undefined,
-    useCaseSensitiveFileNames: sys?.useCaseSensitiveFileNames ?? true,
-  };
-}
-
-function parseTsconfig(ts, configPath) {
-  const host = createModuleResolutionHost(ts);
-  const read = ts.readConfigFile(configPath, host.readFile);
-  if (read.error) return {};
-  // parseJsonConfigFileContent wants a ParseConfigHost-like object; our resolution host
-  // is enough for option extraction.
-  const parsed = ts.parseJsonConfigFileContent(
-    read.config,
-    {
-      useCaseSensitiveFileNames: host.useCaseSensitiveFileNames,
-      readDirectory: ts.sys?.readDirectory
-        ? (...args) => ts.sys.readDirectory(...args)
-        : () => [],
-      fileExists: host.fileExists,
-      readFile: host.readFile,
-    },
-    path.dirname(configPath)
-  );
-  return parsed.options;
-}
-
-/**
- * Compiler options for a given source file. With --tsconfig every file uses that one
- * config; otherwise each file uses the NEAREST tsconfig.json above it (like tsc does),
- * so monorepo packages with per-package path aliases resolve correctly under one --root.
- */
-function createCompilerOptionsLookup(ts, root, tsconfigArg) {
-  if (tsconfigArg) {
-    const configPath = path.isAbsolute(tsconfigArg) ? tsconfigArg : path.join(root, tsconfigArg);
-    const options = fs.existsSync(configPath) ? parseTsconfig(ts, configPath) : {};
-    return () => options;
-  }
-  const byDir = new Map();
-  const byConfig = new Map();
-  return (file) => {
-    const dir = path.dirname(file);
-    if (byDir.has(dir)) return byDir.get(dir);
-    const configPath = ts.findConfigFile(dir, ts.sys.fileExists, 'tsconfig.json');
-    let options = {};
-    if (configPath) {
-      if (!byConfig.has(configPath)) byConfig.set(configPath, parseTsconfig(ts, configPath));
-      options = byConfig.get(configPath);
-    }
-    byDir.set(dir, options);
-    return options;
-  };
-}
-
-/**
- * Per-file scan cache. A cache entry stores the parsed file's content-derived results:
- * content violations (forbidden globals, publish checks, intent references) and the list
- * of module-edge specifiers. Edges are NEVER cached as violations — they are re-resolved
- * against the live filesystem every run, because resolution depends on files and tsconfigs
- * outside the cached file. The whole cache is keyed by the config+manifest contents, so
- * any rule change invalidates everything.
- */
-function scanCachePath(root) {
-  return path.join(root, 'node_modules', '.cache', 'ark-check.json');
-}
-
-function scanCacheKey(root, args) {
-  const read = (p) => {
-    try {
-      return fs.readFileSync(p, 'utf8');
-    } catch {
-      return '';
-    }
-  };
-  const configPath = path.isAbsolute(args.config) ? args.config : path.join(root, args.config);
-  const manifestPath = args.manifest
-    ? path.isAbsolute(args.manifest)
-      ? args.manifest
-      : path.join(root, args.manifest)
-    : undefined;
-  // Bump this schema tag whenever the cached scan shape changes, so a warm cache from an
-  // older Ark can't feed stale entries to new logic. v2: typeOnly on edges. v3: per-file
-  // exportsOnlyTypes (target-module type-only export detection for plan classifier).
-  return crypto
-    .createHash('sha1')
-    .update(`ark-check-cache-v3\0${read(configPath)}\0${manifestPath ? read(manifestPath) : ''}`)
-    .digest('hex');
-}
-
-function loadScanCache(root, key) {
-  try {
-    const data = JSON.parse(fs.readFileSync(scanCachePath(root), 'utf8'));
-    return data.key === key && data.files && typeof data.files === 'object' ? data.files : undefined;
-  } catch {
-    return undefined;
-  }
-}
-
-function saveScanCache(root, key, files) {
-  try {
-    const target = scanCachePath(root);
-    fs.mkdirSync(path.dirname(target), { recursive: true });
-    fs.writeFileSync(target, JSON.stringify({ key, files }));
-  } catch {
-    // cache is best-effort: read-only filesystems just re-parse every run
-  }
-}
-
-/**
- * Fallback resolver for extensionless relative imports whose on-disk target uses an
- * extension `ts.resolveModuleName` won't resolve without a matching tsconfig
- * (notably `.mts`/`.cts`). Mirrors the classic candidate list.
- */
-function isFile(candidate) {
-  try {
-    return fs.statSync(candidate).isFile();
-  } catch {
-    return false;
-  }
-}
-
-function resolveRelativeFallback(fromFile, specifier) {
-  const base = path.resolve(path.dirname(fromFile), specifier);
-  const candidates = [
-    base, // only used when the specifier already carries an extension (isFile filters dirs)
-    `${base}.ts`,
-    `${base}.tsx`,
-    `${base}.mts`,
-    `${base}.cts`,
-    `${base}.js`,
-    `${base}.jsx`,
-    `${base}.mjs`,
-    `${base}.cjs`,
-    path.join(base, 'index.ts'),
-    path.join(base, 'index.tsx'),
-    path.join(base, 'index.mts'),
-    path.join(base, 'index.cts'),
-  ];
-  // isFile (not existsSync) so a directory named like the specifier never shadows the
-  // real module file — e.g. `./foo` must not resolve to a `foo/` directory before `foo.mts`.
-  return candidates.find(isFile);
-}
-
-/**
- * Resolve any import specifier (relative, tsconfig path-alias, or package) to a source
- * file using TypeScript's module resolver, returning the resolved file (or undefined for
- * unresolved / declaration-only targets).
- *
- * ark-check governs one project rooted at --root. A resolved target is skipped when its
- * path RELATIVE TO ROOT either escapes the root (leading `..`) or contains a `node_modules`
- * segment. Using the root-relative path (not an absolute substring) means a project that
- * itself lives under a node_modules segment is still governed, while a broad catch-all
- * pattern (`**`) can't false-flag vendored deps or files outside the project. Monorepos can
- * run under a single --root (per-package tsconfigs are honored via the nearest-tsconfig
- * lookup); edges that resolve outside the root are still skipped.
- */
-function resolveImport(ts, specifier, containingFile, options, host, root) {
-  const res = ts.resolveModuleName(specifier, containingFile, options, host);
-  let file = res.resolvedModule?.resolvedFileName;
-  if (!file && specifier.startsWith('.')) {
-    file = resolveRelativeFallback(containingFile, specifier);
-  }
-  if (!file) return undefined;
-  if (file.endsWith('.d.ts')) return undefined;
-  const abs = path.resolve(file);
-  const segments = path.relative(root, abs).split(path.sep);
-  if (segments[0] === '..' || segments.includes('node_modules')) return undefined;
-  return abs;
-}
-
-function lineOf(sourceFile, pos) {
-  return sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
-}
-
-function textOfModuleSpecifier(node) {
-  return node.moduleSpecifier && typeof node.moduleSpecifier.text === 'string'
-    ? node.moduleSpecifier.text
-    : undefined;
-}
-
-// True when an import/export edge carries ONLY types (`import type …`, or a named import
-// where every binding is `type`-qualified). Type-only edges are erased at compile time —
-// they create no runtime coupling, only a design/type-placement dependency — so callers can
-// rank them below real value imports in a burn-down. A side-effect import (`import "x"`) or
-// any default/namespace/value binding is NOT type-only.
-function isTypeOnlyModuleReference(ts, node) {
-  if (ts.isImportDeclaration(node)) {
-    const clause = node.importClause;
-    if (!clause) return false; // side-effect import — runtime edge
-    if (clause.isTypeOnly) return true; // `import type …`
-    const named = clause.namedBindings;
-    if (named && ts.isNamedImports(named) && named.elements.length > 0) {
-      return named.elements.every((element) => element.isTypeOnly);
-    }
-    return false; // default or namespace binding of a value
-  }
-  if (ts.isExportDeclaration(node)) {
-    if (node.isTypeOnly) return true;
-    const clause = node.exportClause;
-    if (clause && ts.isNamedExports(clause) && clause.elements.length > 0) {
-      return clause.elements.every((element) => element.isTypeOnly);
-    }
-    return false;
-  }
-  return false;
-}
-
-/**
- * True when a module is a pure type-surface file: only type/interface exports and
- * type-only imports. Conservative false (→ judgment) when:
- * - any top-level runtime statement (value decls, expression stmts, side-effect imports)
- * - ambiguous `export { X }` without type keyword, export *, default/export=
- * Used so static value-syntax `import { T }` of a pure-type module can be mechanical-safe
- * (convert to `import type`). Never trust this for require()/import() edges.
- */
-function sourceFileExportsOnlyTypes(ts, sourceFile) {
-  let sawTypeExport = false;
-  const hasExportModifier = (node) =>
-    Array.isArray(node.modifiers) &&
-    node.modifiers.some((m) => m.kind === ts.SyntaxKind.ExportKeyword);
-
-  for (const stmt of sourceFile.statements) {
-    // Type-only imports OK; value or side-effect imports mean runtime load of deps.
-    if (ts.isImportDeclaration(stmt)) {
-      if (!isTypeOnlyModuleReference(ts, stmt)) return false;
-      continue;
-    }
-    if (typeof ts.isImportEqualsDeclaration === 'function' && ts.isImportEqualsDeclaration(stmt)) {
-      return false;
-    }
-    if (ts.isExportDeclaration(stmt)) {
-      if (stmt.isTypeOnly) {
-        sawTypeExport = true;
-        continue;
-      }
-      // export * from '…' can re-export values — not provably type-only.
-      if (!stmt.exportClause) return false;
-      if (ts.isNamespaceExport(stmt.exportClause)) return false;
-      if (ts.isNamedExports(stmt.exportClause)) {
-        if (stmt.exportClause.elements.length === 0) return false;
-        for (const el of stmt.exportClause.elements) {
-          if (!el.isTypeOnly) return false; // bare `export { X }` — ambiguous without checker
-        }
-        sawTypeExport = true;
-        continue;
-      }
-      return false;
-    }
-    if (ts.isExportAssignment(stmt)) return false; // export = / export default expr
-    if (ts.isTypeAliasDeclaration(stmt) || ts.isInterfaceDeclaration(stmt)) {
-      if (hasExportModifier(stmt)) sawTypeExport = true;
-      continue;
-    }
-    // Any other top-level statement (const/fn/class/enum, console.log, if, …) is runtime.
-    return false;
-  }
-  return sawTypeExport;
-}
-
-function propertyName(ts, node) {
-  if (!node) return undefined;
-  if (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) return node.text;
-  return undefined;
-}
-
-function objectProperty(ts, node, name) {
-  if (!node || !ts.isObjectLiteralExpression(node)) return undefined;
-  return node.properties.find((property) => {
-    if (!ts.isPropertyAssignment(property) && !ts.isShorthandPropertyAssignment(property)) {
-      return false;
-    }
-    return propertyName(ts, property.name) === name;
-  });
-}
-
-function objectHasProperty(ts, node, name) {
-  return objectProperty(ts, node, name) !== undefined;
-}
-
-function objectPropertyValue(ts, node, name) {
-  const property = objectProperty(ts, node, name);
-  return property && ts.isPropertyAssignment(property)
-    ? property.initializer
-    : undefined;
-}
-
-function objectHasMetadataSource(ts, node) {
-  const metadata = objectPropertyValue(ts, node, 'metadata');
-  return objectHasProperty(ts, metadata, 'source');
-}
-
-function stringLiteralText(ts, node) {
-  return node && ts.isStringLiteralLike(node) ? node.text : undefined;
-}
-
-function isPublishCall(ts, node) {
-  if (!ts.isCallExpression(node)) return false;
-  const expression = node.expression;
-  if (ts.isPropertyAccessExpression(expression)) {
-    return expression.name.text === 'publish';
-  }
-  return ts.isIdentifier(expression) && expression.text === 'publish';
-}
-
-function looksLikeIntentCreatorExpression(ts, node) {
-  if (!node) return false;
-  if (ts.isIdentifier(node)) {
-    return /^[A-Z]/.test(node.text);
-  }
-  if (ts.isPropertyAccessExpression(node)) {
-    return looksLikeIntentCreatorExpression(ts, node.name);
-  }
-  return false;
-}
-
-function isArkPublishCandidate(ts, node) {
-  if (!ts.isCallExpression(node)) return false;
-  const firstArg = node.arguments[0];
-  const rawIntent = stringLiteralText(ts, firstArg);
-  return (
-    (rawIntent !== undefined && looksLikeIntent(rawIntent)) ||
-    objectHasProperty(ts, firstArg, 'intent') ||
-    looksLikeIntentCreatorExpression(ts, firstArg)
-  );
-}
-
-function publishSourceLiteral(ts, node) {
-  if (!ts.isCallExpression(node)) return undefined;
-  const [firstArg, secondArg, thirdArg] = node.arguments;
-  const rawMetadata = objectPropertyValue(ts, firstArg, 'metadata');
-  return (
-    stringLiteralText(ts, objectPropertyValue(ts, rawMetadata, 'source')) ??
-    stringLiteralText(ts, objectPropertyValue(ts, secondArg, 'source')) ??
-    stringLiteralText(ts, objectPropertyValue(ts, thirdArg, 'source'))
-  );
-}
-
-function publishHasSource(ts, node) {
-  if (!ts.isCallExpression(node)) return false;
-  const [firstArg, secondArg, thirdArg] = node.arguments;
-  return (
-    objectHasMetadataSource(ts, firstArg) ||
-    objectHasProperty(ts, secondArg, 'source') ||
-    objectHasProperty(ts, thirdArg, 'source')
-  );
-}
 const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
 const color = {
   red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
@@ -1394,83 +862,6 @@ const color = {
   bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
 };
 
-function detectCycles(graph) {
-  let index = 0;
-  const indices = new Map();
-  const low = new Map();
-  const onStack = new Set();
-  const stack = [];
-  const components = [];
-
-  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
-  const strongconnect = (v) => {
-    indices.set(v, index);
-    low.set(v, index);
-    index += 1;
-    stack.push(v);
-    onStack.add(v);
-    for (const w of [...(graph.get(v) ?? [])].sort()) {
-      if (!graph.has(w)) continue;
-      if (!indices.has(w)) {
-        strongconnect(w);
-        low.set(v, Math.min(low.get(v), low.get(w)));
-      } else if (onStack.has(w)) {
-        low.set(v, Math.min(low.get(v), indices.get(w)));
-      }
-    }
-    if (low.get(v) === indices.get(v)) {
-      const comp = [];
-      let w;
-      do {
-        w = stack.pop();
-        onStack.delete(w);
-        comp.push(w);
-      } while (w !== v);
-      if (comp.length > 1) components.push(comp.sort());
-    }
-  };
-
-  for (const v of [...graph.keys()].sort()) {
-    if (!indices.has(v)) strongconnect(v);
-  }
-
-  return components
-    .sort((a, b) => a[0].localeCompare(b[0]))
-    .map((members) => ({
-      ruleId: 'CIRCULAR_DEPENDENCY',
-      file: members[0],
-      line: 1,
-      target: members.join(' → '),
-      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
-    }));
-}
-
-
-function moduleSpecifierFromCall(ts, node) {
-  if (!ts.isCallExpression(node)) return undefined;
-
-  if (node.expression.kind === ts.SyntaxKind.ImportKeyword) {
-    const first = node.arguments[0];
-    const value = stringLiteralText(ts, first);
-    return value ? { value, kind: 'dynamic-import' } : undefined;
-  }
-
-  if (ts.isIdentifier(node.expression) && node.expression.text === 'require') {
-    const first = node.arguments[0];
-    const value = stringLiteralText(ts, first);
-    return value ? { value, kind: 'require' } : undefined;
-  }
-
-  return undefined;
-}
-
-// --coverage: a standalone visibility report (never changes the exit code). Answers
-// "which files does each layer actually govern, and what is slipping through?" — the
-// data the /ark-coverage skill otherwise has to hand-roll with find/readdir walks.
-// Pure coverage computation (glob-only, no TypeScript): the object both `--coverage` and
-// `--doctor` render. `governed` is the headline honesty number — the share of in-scope code
-// Ark actually enforces rules on; `suggestions` proposes a layer for each ungoverned dir.
-
 async function main() {
   const args = parseArgs(process.argv);
   if (args.version) {
@@ -1509,6 +900,16 @@ async function main() {
     return;
   }
 
+  if (args.suggestInclude) {
+    runSuggestInclude(args);
+    return;
+  }
+
+  if (args.adoptContract) {
+    runAdoptContract(args);
+    return;
+  }
+
   if (args.recommend) {
     try {
       const recommendation = buildArchitectureRecommendation(args.root);
@@ -1582,7 +983,7 @@ async function main() {
   const config = readConfig(root, args.config);
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
-  const files = config.include.flatMap((entry) => walk(path.join(root, entry)));
+  const files = collectGovernedFiles(root, config);
 
   // --coverage is a pure glob/report view (no TypeScript resolver), so serve it BEFORE the
   // TS import: the report must work — and exit 0 — even when typescript isn't installed.
@@ -1627,203 +1028,15 @@ async function main() {
     );
   }
 
-  const manifestIntentLayers = intentLayersFromManifest(manifest);
-  const compilerOptionsFor = createCompilerOptionsLookup(ts, root, args.tsconfig);
-  const moduleHost = createModuleResolutionHost(ts);
-
-  const violations = [];
-  const warnings = collectConfigWarnings(root, config, files, rules, manifest);
-  const cacheKey = args.noCache ? undefined : scanCacheKey(root, args);
-  const cachedFiles = cacheKey ? loadScanCache(root, cacheKey) : undefined;
-  const nextCacheFiles = {};
-
-  // Parses one file and returns its cacheable scan result: violations derived purely from
-  // the file's content (+config/manifest, hashed into the cache key) and the module-edge
-  // specifiers found, which the driver loop below resolves fresh on every run.
-  function scanSourceFile(file, sourceLayer) {
-    const source = fs.readFileSync(file, 'utf8');
-    const sourceFile = ts.createSourceFile(file, source, ts.ScriptTarget.Latest, true);
-    const violations = [];
-    const edges = [];
-
-    const layerConfig = config.layers.find((layer) => layer.name === sourceLayer);
-    const forbiddenGlobals = Array.isArray(layerConfig?.forbiddenGlobals)
-      ? layerConfig.forbiddenGlobals.filter((entry) => typeof entry === 'string')
-      : [];
-    for (const use of collectForbiddenGlobalUses(ts, sourceFile, forbiddenGlobals)) {
-      violations.push({
-        ruleId: 'FORBIDDEN_GLOBAL',
-        file: normalize(path.relative(root, file)),
-        line: lineOf(sourceFile, use.node.getStart(sourceFile)),
-        fromLayer: sourceLayer,
-        target: use.name,
-        message: `${sourceLayer} must not use the ambient global "${use.name}".`,
-      });
-    }
-
-    const checkModuleEdge = (specifier, node, kind, typeOnly = false) => {
-      edges.push({ specifier, line: lineOf(sourceFile, node.getStart(sourceFile)), kind, typeOnly });
-    };
-
-    const visit = (node) => {
-      if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
-        const specifier = textOfModuleSpecifier(node);
-        if (specifier) {
-          checkModuleEdge(
-            specifier,
-            node,
-            ts.isImportDeclaration(node) ? 'import' : 'export',
-            isTypeOnlyModuleReference(ts, node)
-          );
-        }
-      }
-
-      if (ts.isCallExpression(node)) {
-        const moduleCall = moduleSpecifierFromCall(ts, node);
-        if (moduleCall) {
-          checkModuleEdge(moduleCall.value, node, moduleCall.kind);
-        }
-
-        if (isPublishCall(ts, node)) {
-          const firstArg = node.arguments[0];
-          const rawIntent = stringLiteralText(ts, firstArg);
-          if (
-            (rawIntent && looksLikeIntent(rawIntent)) ||
-            objectHasProperty(ts, firstArg, 'intent')
-          ) {
-            violations.push({
-              ruleId: 'RAW_EVENT_PUBLISH',
-              file: normalize(path.relative(root, file)),
-              line: lineOf(sourceFile, node.getStart(sourceFile)),
-              message:
-                'Publish through a registered intent creator; raw event objects or intent strings bypass Ark contracts and tooling.',
-            });
-          }
-
-          if (isArkPublishCandidate(ts, node) && !publishHasSource(ts, node)) {
-            violations.push({
-              ruleId: 'PUBLISH_MISSING_SOURCE',
-              file: normalize(path.relative(root, file)),
-              line: lineOf(sourceFile, node.getStart(sourceFile)),
-              fromLayer: sourceLayer,
-              message: 'Strict Ark publish calls must include metadata.source.',
-            });
-          }
-
-          const sourceIntent = publishSourceLiteral(ts, node);
-          if (sourceIntent && looksLikeIntent(sourceIntent)) {
-            const sourceIntentLayer = layerForIntent(
-              sourceIntent,
-              config.layers,
-              manifestIntentLayers
-            );
-            if (sourceIntentLayer && sourceIntentLayer !== sourceLayer) {
-              violations.push({
-                ruleId: 'PUBLISH_SOURCE_LAYER_MISMATCH',
-                file: normalize(path.relative(root, file)),
-                line: lineOf(sourceFile, node.getStart(sourceFile)),
-                fromLayer: sourceLayer,
-                toLayer: sourceIntentLayer,
-                target: sourceIntent,
-                message:
-                  `Publish source "${sourceIntent}" resolves to ${sourceIntentLayer}, but the publishing file is classified as ${sourceLayer}.`,
-              });
-            }
-          }
-        }
-      }
-
-      if (ts.isStringLiteralLike(node) && looksLikeIntent(node.text)) {
-        const targetLayer = layerForIntent(node.text, config.layers, manifestIntentLayers);
-        const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
-        if (rule) {
-          violations.push({
-            ruleId: 'LAYER_INTENT_REFERENCE_VIOLATION',
-            file: normalize(path.relative(root, file)),
-            line: lineOf(sourceFile, node.getStart(sourceFile)),
-            fromLayer: sourceLayer,
-            toLayer: targetLayer,
-            target: node.text,
-            message:
-              rule.message ??
-              `${sourceLayer} must not reference ${targetLayer} intent ${node.text}.`,
-          });
-        }
-      }
-
-      ts.forEachChild(node, visit);
-    };
-    visit(sourceFile);
-    return {
-      contentViolations: violations,
-      edges,
-      exportsOnlyTypes: sourceFileExportsOnlyTypes(ts, sourceFile),
-    };
-  }
-
-  // Pass 1: scan every governed file into nextCacheFiles (needs complete map before
-  // targetTypeOnlyExports can be resolved for import edges).
-  const importGraph = new Map();
-  const scanned = []; // { file, sourceLayer, relFile, entry }
-  for (const file of files) {
-    const sourceLayer = layerForFile(root, file, config.layers);
-    if (!sourceLayer) continue;
-    const relFile = normalize(path.relative(root, file));
-    if (!importGraph.has(relFile)) importGraph.set(relFile, new Set());
-    const stat = fs.statSync(file);
-    const fileKey = `${stat.mtimeMs}:${stat.size}`;
-    const cached = cachedFiles?.[relFile];
-    const entry =
-      cached && cached.fileKey === fileKey
-        ? cached
-        : { fileKey, ...scanSourceFile(file, sourceLayer) };
-    nextCacheFiles[relFile] = entry;
-    scanned.push({ file, sourceLayer, relFile, entry });
-  }
-
-  // Pass 2: content violations + layer edges (with target type-export surface).
-  for (const { file, sourceLayer, relFile, entry } of scanned) {
-    violations.push(...entry.contentViolations);
-    for (const edge of entry.edges) {
-      const target = resolveImport(ts, edge.specifier, file, compilerOptionsFor(file), moduleHost, root);
-      const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;
-      if (target && targetLayer) {
-        const relTarget = normalize(path.relative(root, target));
-        if (relTarget !== relFile) importGraph.get(relFile).add(relTarget);
-      }
-      const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
-      if (rule) {
-        const relTarget = normalize(path.relative(root, target));
-        // After pass 1 every in-scope target is in nextCacheFiles. Missing → not type-only.
-        // targetTypeOnlyExports only for static import/export declarations — never require()
-        // or dynamic import(), which always load the module at runtime (side effects matter).
-        const targetCached = nextCacheFiles[relTarget];
-        const staticEdge = edge.kind === 'import' || edge.kind === 'export';
-        const targetTypeOnlyExports =
-          staticEdge && Boolean(targetCached?.exportsOnlyTypes) && !edge.typeOnly;
-        // Importer is itself a pure type-surface file (no runtime body) — enables
-        // pure-type-file-relocate classification when the edge is type-only.
-        const sourcePureTypeModule = Boolean(entry.exportsOnlyTypes);
-        violations.push({
-          ruleId: 'LAYER_IMPORT_VIOLATION',
-          file: relFile,
-          line: edge.line,
-          fromLayer: sourceLayer,
-          toLayer: targetLayer,
-          target: relTarget,
-          ...(edge.typeOnly ? { typeOnly: true } : {}),
-          ...(targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
-          ...(sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
-          ...(edge.kind ? { edgeKind: edge.kind } : {}),
-          message: rule.message ?? `${sourceLayer} must not ${edge.kind} ${targetLayer}.`,
-        });
-      }
-    }
-  }
-
-  if (cacheKey) saveScanCache(root, cacheKey, nextCacheFiles);
-
-  violations.push(...detectCycles(importGraph));
+  const { violations, warnings } = runArchitectureScan({
+    root,
+    config,
+    manifest,
+    rules,
+    files,
+    ts,
+    args,
+  });
 
   if (args.doctor) {
     runDoctor(root, config, files, rules, violations, args.json, {
@@ -1848,6 +1061,24 @@ async function main() {
       process.exitCode = 2;
       return;
     }
+    const baselineName = args.baseline || '.ark-baseline.json';
+    const fullBaselinePath = path.isAbsolute(baselineName)
+      ? baselineName
+      : path.join(root, baselineName);
+    // Zero debt: do not leave an empty baseline file (unclear policy — "is ratchet on?").
+    // Delete any existing empty/orphan baseline so doctor/CI stay honest.
+    if (violations.length === 0) {
+      if (fs.existsSync(fullBaselinePath)) {
+        fs.unlinkSync(fullBaselinePath);
+        console.log(
+          `No violations to freeze — removed empty baseline ${fullBaselinePath} (zero debt; no ratchet file needed).`
+        );
+      } else {
+        console.log('No violations to freeze — baseline not written (zero debt).');
+      }
+      console.log('Gate with: ark-check --root . --config ark.config.json --strict-config');
+      return;
+    }
     const { fullPath, count } = writeBaseline(root, args.baseline, violations);
     console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);
     console.log('Commit it and gate CI with: ark-check --baseline (only NEW violations fail).');
@@ -1877,7 +1108,10 @@ async function main() {
     }
   }
 
-  const ok = activeViolations.length === 0 && (!args.strictConfig || warnings.length === 0);
+  // Soft/advisory warnings (failsStrict === false) never fail --strict-config.
+  const strictWarnings = warnings.filter((w) => w.failsStrict !== false);
+  const ok =
+    activeViolations.length === 0 && (!args.strictConfig || strictWarnings.length === 0);
 
   if (args.plan) {
     const cov = computeCoverage(root, config, files, rules);
@@ -2023,11 +1257,16 @@ async function main() {
       );
     }
     if (activeViolations.length === 0) {
+      const advisoryOnly = warnings.length > 0 && strictWarnings.length === 0;
       if (warnings.length === 0) {
         console.log(`${color.green('✔')} Ark check passed.${baselineNote}`);
-      } else if (args.strictConfig) {
+      } else if (args.strictConfig && strictWarnings.length > 0) {
         console.error(
-          `${color.red('✖')} Ark check failed with ${warnings.length} config warning(s).${baselineNote}`
+          `${color.red('✖')} Ark check failed with ${strictWarnings.length} config warning(s).${baselineNote}`
+        );
+      } else if (advisoryOnly) {
+        console.log(
+          `${color.green('✔')} Ark check passed with ${warnings.length} advisory warning(s).${baselineNote}`
         );
       } else {
         console.log(