arkgate 2.6.0 → 2.7.0

package/bin/lib/config-warnings.mjs

@@ -0,0 +1,228 @@
+/**
+ * Config validation warnings + intent layer helpers for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import path from 'node:path';
+import {
+  DEFAULT_INTENT_PREFIXES,
+  globToRegExp,
+  layerForFile,
+  patternSpecificity,
+  resolveIntentLayer,
+} from '../ark-shared.mjs';
+import { normalize } from './scan-files.mjs';
+
+export 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 }));
+}
+
+export 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);
+}
+
+export function isBlocked(rules, from, to) {
+  return rules.find((rule) => !rule.allowed && rule.from === from && rule.to === to);
+}
+
+export function configWarning(ruleId, message, extra = {}) {
+  return { ruleId, message, ...extra };
+}
+
+export 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) {
+        // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
+        // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
+        // Failing the release gate on dead preset globs caused false CI red while architecture
+        // edges were clean (deer-flow host validation). Real safety is import violations +
+        // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
+        warnings.push(
+          configWarning(
+            'CONFIG_LAYER_PATTERN_NO_MATCHES',
+            `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
+            { layer: layer.name, pattern, failsStrict: false }
+          )
+        );
+      }
+    }
+  }
+
+  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;
+}

package/bin/lib/doctor-plan.mjs

@@ -351,11 +351,15 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   });
   console.log('');
   console.log(color.bold('Operating mode'));
+  // Modes are detected states, not user-picked settings. Plain-language "what you do next".
   const modeMark = mode === 'enforce' ? ok : mode === 'adapt' ? warn : warn;
   const modeHelp = {
-    suggest: 'starter shape / thin tree — expand layers as you grow',
-    adapt: 'contract still needs to match real layout or raise coverage',
-    enforce: 'contract governs enough code; gates can honestly hold the line',
+    suggest:
+      'Setup — Ark proposes a starting architecture shape. You do not pick this mode; it means the tree is thin or new. Next: accept the shape (ark start / ark init) and add real layers as you grow.',
+    adapt:
+      'Align — contract and folders still disagree, or coverage is weak / debt is open. You do not pick this mode. Next: classify ungoverned dirs (/ark-contract, /ark-adopt), run the plan (/ark-autopilot or /ark-loop). Gates do not fully protect you yet.',
+    enforce:
+      'Guard — contract governs enough real code and edges are clean enough for gates to protect you. You do not pick this mode; you arrived here. Next: keep CI/write gates on; only NEW violations should fail.',
   };
   line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
   if (emptyScope) {
@@ -466,7 +470,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   console.log('');
   console.log(color.bold('Adoption (separate from fitness score)'));
   if (adoption.gaps.length === 0 && !adoption.layerBalance) {
-    line(ok, 'Hosts, MCP argv, core optionality, origin report, and baseline policy look complete');
+    line(
+      ok,
+      'Hosts, MCP argv, core optionality, origin report, baseline policy, and deploy-path lint/types look complete'
+    );
   } else {
     for (const gap of adoption.gaps) {
       const mark = gap.severity === 'warn' ? warn : gap.severity === 'info' ? warn : bad;

package/bin/lib/graph-cycles.mjs

@@ -0,0 +1,56 @@
+/**
+ * Import-graph cycle detection (Tarjan) for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+export 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]}.`,
+      // Graph is value/runtime edges only (type-only imports omitted).
+      cycleKind: 'value',
+    }));
+}

package/bin/lib/presets.mjs

@@ -6,6 +6,7 @@ import {
   createElevenLayerConfig,
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   DEFAULT_INTENT_PREFIXES,
+  resolveIncludeRoots,
 } from '../ark-shared.mjs';
 
 export function denyUpward(names) {
@@ -177,16 +178,25 @@ export const ARCHITECTURE_PRESETS = {
   // anywhere in the tree (`**/domain/**` hits packages/x/domain AND apps/y/src/domain),
   // so one profile governs every package. include defaults to the detected workspace
   // roots (falls back to packages+apps). Naming varies by repo — adjust and re-check.
-  monorepo: (includeDirs, root) =>
-    presetWithOverlays(
+  monorepo: (includeDirs, root) => {
+    let include =
+      includeDirs && includeDirs.length > 0 ? [...includeDirs] : [];
+    if (root) {
+      const resolved = resolveIncludeRoots(root);
+      if (resolved.length > 0) include = resolved;
+    }
+    if (include.length === 0) include = ['packages', 'apps'];
+    return presetWithOverlays(
       {
-        include: includeDirs && includeDirs.length > 0 ? includeDirs : ['packages', 'apps'],
+        include,
         layers: [
           {
             name: 'DomainModel',
             description:
               'Pure business rules and entities, in any package. No I/O, no framework, no ambient globals.',
-            patterns: ['**/domain/**', '**/entities/**'],
+            // Domain by intentional folders only — NOT bare **/types.ts (that mis-classifies
+            // application bags like frontend/src/core/**/types.ts as Domain and creates false edges).
+            patterns: ['**/domain/**', '**/entities/**', '**/cinematic/types.ts'],
             forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
             optional: true,
           },
@@ -206,6 +216,8 @@ export const ARCHITECTURE_PRESETS = {
               '**/controllers/**',
               '**/http/**',
               '**/routes/**',
+              '**/hooks/**',
+              '**/lib/**',
             ],
             optional: true,
           },
@@ -231,6 +243,65 @@ export const ARCHITECTURE_PRESETS = {
         ],
       },
       root
+    );
+  },
+
+  /**
+   * UI / Vite / Remotion-style surface: presentation-heavy trees with hooks, lib, routes,
+   * components. Use when the TS surface is mostly UI (no deep domain folders yet).
+   */
+  'ui-surface': (_workspaces, root) =>
+    presetWithOverlays(
+      {
+        include: (() => {
+          if (!root) return ['src'];
+          try {
+            const roots = resolveIncludeRoots(root);
+            return roots.length > 0 ? roots : ['src'];
+          } catch {
+            return ['src'];
+          }
+        })(),
+        layers: [
+          {
+            name: 'DomainModel',
+            description: 'Shared types and pure view-models (optional on UI-first trees).',
+            // Avoid bare **/types.ts — see monorepo DomainModel note (false Domain on core/**/types.ts).
+            patterns: ['**/domain/**', '**/cinematic/types.ts'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+            optional: true,
+          },
+          {
+            name: 'PresentationAdapters',
+            description: 'UI, routes, hooks, components, compositions.',
+            patterns: [
+              '**/src/**',
+              '**/components/**',
+              '**/hooks/**',
+              '**/lib/**',
+              '**/routes/**',
+              '**/app/**',
+              '**/pages/**',
+            ],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+          {
+            name: 'PersistenceAdapters',
+            description: 'Client data access and external API adapters (when present).',
+            patterns: ['**/infrastructure/**', '**/adapters/**', '**/repositories/**'],
+            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
+            optional: true,
+          },
+        ],
+        rules: [
+          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
+          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
+          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+        ],
+      },
+      root
     ),
 };
 

package/bin/lib/remediation.mjs

@@ -0,0 +1,150 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/remediation.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/remediation.mjs). Zero Node I/O.
+ */
+
+export const REMEDIATION_CLASSES = [
+    'mechanical-safe',
+    'judgment',
+    'deferred',
+];
+/**
+ * Co-pilot work classifier — the TRUST BOUNDARY for auto-apply.
+ * Biased toward 'judgment': false mechanical-safe is worse than an extra human approval.
+ */
+export function classifyRemediation(violation) {
+    const ruleId = violation?.ruleId;
+    if (ruleId === 'LAYER_IMPORT_VIOLATION') {
+        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.',
+            };
+        }
+        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.',
+    };
+}
+/**
+ * Deterministic fix-class labels for JSON output (English, shared with skills/reports).
+ */
+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;
+}

package/bin/lib/scan-files.mjs

@@ -0,0 +1,69 @@
+/**
+ * Governed source file walk / collection for ark-check.
+ * Extracted from ark-check entry (R3).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isScanExcludedRelative } from '../ark-shared.mjs';
+
+export 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. */
+export const TEST_FILE_NAME =
+  /\.(spec|test)\.(tsx?|jsx?|mts|cts)$/i;
+
+export function isGovernableSourceFile(name) {
+  return SOURCE_FILE_NAME.test(name) && !name.endsWith('.d.ts') && !TEST_FILE_NAME.test(name);
+}
+
+export 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'
+  );
+}
+
+export 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;
+}
+
+/** Walk include roots then drop codegen / config.exclude (universal scan filter). */
+export function collectGovernedFiles(root, config) {
+  const raw = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+  return raw.filter((abs) => {
+    const rel = normalize(path.relative(root, abs));
+    return !isScanExcludedRelative(rel, config);
+  });
+}
+
+export function normalize(value) {
+  return value.split(path.sep).join('/');
+}