arkgate 4.6.6 → 4.7.0

package/bin/lib/ark-run-sensors.mjs

@@ -0,0 +1,309 @@
+/**
+ * GENERATED FILE — do not edit by hand.
+ *
+ * Canonical algorithm: src/domain/arkRunSensors.ts
+ * Regenerate: node scripts/generate-cli-pure.mjs
+ * Drift check: node scripts/generate-cli-pure.mjs --check
+ *
+ * Pure CLI helper (bin/lib/ark-run-sensors.mjs). Zero Node I/O.
+ */
+
+import { extractArkRunImportedConstructorNamesFromSource, extractArkRunKernelCallsFromSource, extractArkRunManagedNewsFromSource, extractArkRunValueImportDependenciesFromSource, isArkRunKernelModuleSpecifier, isArkRunTransportBypassSpecifier, } from './ark-run-facts.mjs';
+import { extraMergeTeethAllowed, } from './extra-merge-teeth.mjs';
+import { deterministicNextAction } from './remediation.mjs';
+export const ARKRUN_TIER1_SENSOR_IDS = [
+    'arkrun-missing-root',
+    'arkrun-kernel-in-domain',
+    'arkrun-direct-new',
+    'arkrun-undeclared-emit',
+    'arkrun-undeclared-handle',
+    'arkrun-undeclared-depend',
+    'arkrun-transport-bypass',
+];
+/**
+ * Import / `new` envelope for `arkgate/eslint`.
+ * Missing-root and undeclared-* stay CLI/MCP/preflight (project-wide or declaration facts).
+ */
+export const ARKRUN_EDITOR_SENSOR_IDS = [
+    'arkrun-kernel-in-domain',
+    'arkrun-direct-new',
+    'arkrun-transport-bypass',
+];
+const EDITOR_SENSOR_SET = new Set(ARKRUN_EDITOR_SENSOR_IDS);
+export function isArkRunEditorSensor(sensor) {
+    return EDITOR_SENSOR_SET.has(sensor);
+}
+export const ARKRUN_RULE_IDS = {
+    'arkrun-missing-root': 'ARKRUN_MISSING_ROOT',
+    'arkrun-kernel-in-domain': 'ARKRUN_KERNEL_IN_DOMAIN',
+    'arkrun-direct-new': 'ARKRUN_DIRECT_NEW',
+    'arkrun-undeclared-emit': 'ARKRUN_UNDECLARED_EMIT',
+    'arkrun-undeclared-handle': 'ARKRUN_UNDECLARED_HANDLE',
+    'arkrun-undeclared-depend': 'ARKRUN_UNDECLARED_DEPEND',
+    'arkrun-transport-bypass': 'ARKRUN_TRANSPORT_BYPASS',
+};
+export const ARKRUN_INTERACTION_NAME_INCOMPLETE = 'ARKRUN_INTERACTION_NAME_INCOMPLETE';
+function isDomainRoleLayer(layer, intentPrefixes = []) {
+    const name = layer.trim();
+    // Start-anchored Domain/entity/aggregate — unanchored "model" matches ReportingReadModels.
+    if (/^domain(?:model)?$/i.test(name) || /^domain(?=[A-Z_\-\s])/i.test(name))
+        return true;
+    if (/^(?:entit(?:y|ies)|aggregates?)(?:$|(?=[A-Z_\-\s]))/i.test(name))
+        return true;
+    return intentPrefixes.some((prefix) => {
+        const normalized = prefix.trim().replace(/\.+$/, '');
+        return normalized === 'Domain' || normalized.startsWith('Domain.');
+    });
+}
+function compareFindings(left, right) {
+    return (left.file.localeCompare(right.file) ||
+        left.ruleId.localeCompare(right.ruleId) ||
+        left.line - right.line ||
+        left.message.localeCompare(right.message));
+}
+function finding(extra, sensor, file, line, message, extras, teethAllowed) {
+    const failsStrict = extra.mode === 'enforced' && teethAllowed;
+    return {
+        ruleId: ARKRUN_RULE_IDS[sensor],
+        sensor,
+        message,
+        file,
+        line,
+        ...(extras?.fromLayer ? { fromLayer: extras.fromLayer } : {}),
+        ...(extras?.target ? { target: extras.target } : {}),
+        severity: failsStrict ? 'error' : 'warning',
+        failsStrict,
+        nextAction: deterministicNextAction({
+            ruleId: ARKRUN_RULE_IDS[sensor],
+            fromLayer: extras?.fromLayer,
+            target: extras?.target,
+        }),
+    };
+}
+function bagForFile(declarations, file) {
+    const uses = [];
+    const reactsTo = [];
+    const raises = [];
+    const sends = [];
+    for (const entry of declarations) {
+        if (entry.file !== file)
+            continue;
+        uses.push(...entry.uses);
+        reactsTo.push(...entry.reactsTo);
+        raises.push(...entry.raises);
+        sends.push(...entry.sends);
+    }
+    return {
+        uses: new Set(uses),
+        reactsTo: new Set(reactsTo),
+        raises: new Set(raises),
+        sends: new Set(sends),
+    };
+}
+function emitKinds(kind) {
+    return kind === 'publisher' || kind === 'publish' || kind === 'raise' || kind === 'send';
+}
+function handleKinds(kind) {
+    return kind === 'subscribe' || kind === 'register-handler';
+}
+function dependKinds(kind) {
+    return kind === 'resolve' || kind === 'resolve-singleton';
+}
+function evaluateMissingRoot(extra, hits, teethAllowed) {
+    const out = [];
+    const roots = extra.compositionRoots;
+    if (roots.length === 0) {
+        out.push(finding(extra, 'arkrun-missing-root', 'ark.config.json', 1, 'ArkRun compositionRoots is empty; no createArkKernel factory site is declared.', undefined, teethAllowed));
+        return out;
+    }
+    const hitsByRoot = new Map();
+    for (const hit of hits) {
+        const list = hitsByRoot.get(hit.matchedRoot) ?? [];
+        list.push(hit);
+        hitsByRoot.set(hit.matchedRoot, list);
+    }
+    for (const pattern of roots) {
+        const matched = [...(hitsByRoot.get(pattern) ?? [])].sort((left, right) => left.file.localeCompare(right.file));
+        if (matched.length === 0) {
+            out.push(finding(extra, 'arkrun-missing-root', 'ark.config.json', 1, `ArkRun composition root ${JSON.stringify(pattern)} matched no governed files and has no createArkKernel factory.`, { target: pattern }, teethAllowed));
+            continue;
+        }
+        // Factory required in the root set, not in every glob hit.
+        if (matched.some((hit) => hit.hasKernelFactory))
+            continue;
+        const first = matched[0];
+        out.push(finding(extra, 'arkrun-missing-root', first.file, 1, `ArkRun composition root ${JSON.stringify(pattern)} has no createArkKernel / createStrictArkKernel factory.`, { target: pattern }, teethAllowed));
+    }
+    return out;
+}
+function evaluateKernelInDomain(extra, layers, dependencies, layerForFile, teethAllowed) {
+    const prefixes = new Map(layers.map((layer) => [layer.name, layer.intentPrefixes ?? []]));
+    const out = [];
+    for (const dependency of dependencies) {
+        const specifier = dependency.specifier;
+        if (!specifier || !isArkRunKernelModuleSpecifier(specifier))
+            continue;
+        const fromLayer = layerForFile(dependency.from);
+        if (!fromLayer)
+            continue;
+        if (!isDomainRoleLayer(fromLayer, prefixes.get(fromLayer) ?? []))
+            continue;
+        out.push(finding(extra, 'arkrun-kernel-in-domain', dependency.from, dependency.line, `${fromLayer} must not import kernel module ${JSON.stringify(specifier)}.`, { fromLayer, target: specifier }, teethAllowed));
+    }
+    return out;
+}
+function evaluateDirectNew(extra, layers, managedNews, hits, layerForFile, teethAllowed) {
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return [];
+    const prefixes = new Map(layers.map((layer) => [layer.name, layer.intentPrefixes ?? []]));
+    const admittedFactories = new Set(hits.filter((hit) => hit.hasKernelFactory).map((hit) => hit.file));
+    const out = [];
+    for (const constructed of managedNews) {
+        if (admittedFactories.has(constructed.file))
+            continue;
+        const fromLayer = layerForFile(constructed.file);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        if (isDomainRoleLayer(fromLayer, prefixes.get(fromLayer) ?? []))
+            continue;
+        out.push(finding(extra, 'arkrun-direct-new', constructed.file, constructed.line, `${fromLayer} must not construct ${constructed.typeName} with new outside an ArkRun composition-root factory.`, { fromLayer, target: constructed.typeName }, teethAllowed));
+    }
+    return out;
+}
+function evaluateUndeclared(extra, kernelCalls, declarations, layerForFile, teethAllowed) {
+    const findings = [];
+    const completenessReasons = [];
+    if (extra.requireDeclarations !== true) {
+        return { findings, completenessReasons };
+    }
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return { findings, completenessReasons };
+    for (const call of kernelCalls) {
+        if (!emitKinds(call.kind) && !handleKinds(call.kind) && !dependKinds(call.kind))
+            continue;
+        const fromLayer = layerForFile(call.file);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        if (!call.nameLiteral) {
+            if (extra.mode === 'enforced') {
+                completenessReasons.push({
+                    code: ARKRUN_INTERACTION_NAME_INCOMPLETE,
+                    file: call.file,
+                    message: `ArkRun ${call.kind} call in ${call.file} has no string-literal name; enforced extra cannot prove the declaration.`,
+                });
+            }
+            continue;
+        }
+        const bag = bagForFile(declarations, call.file);
+        if (emitKinds(call.kind)) {
+            if (bag.raises.has(call.nameLiteral) || bag.sends.has(call.nameLiteral))
+                continue;
+            findings.push(finding(extra, 'arkrun-undeclared-emit', call.file, call.line, `Emit ${JSON.stringify(call.nameLiteral)} is not declared in raises or sends.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+            continue;
+        }
+        if (handleKinds(call.kind)) {
+            if (bag.reactsTo.has(call.nameLiteral))
+                continue;
+            findings.push(finding(extra, 'arkrun-undeclared-handle', call.file, call.line, `Handle ${JSON.stringify(call.nameLiteral)} is not declared in reactsTo.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+            continue;
+        }
+        if (bag.uses.has(call.nameLiteral))
+            continue;
+        findings.push(finding(extra, 'arkrun-undeclared-depend', call.file, call.line, `Depend ${JSON.stringify(call.nameLiteral)} is not declared in uses.`, { fromLayer, target: call.nameLiteral }, teethAllowed));
+    }
+    return { findings, completenessReasons };
+}
+function evaluateTransportBypass(extra, dependencies, layerForFile, teethAllowed) {
+    const managed = new Set(extra.managedLayers);
+    if (managed.size === 0)
+        return [];
+    const out = [];
+    for (const dependency of dependencies) {
+        if (dependency.typeOnly)
+            continue;
+        const specifier = dependency.specifier;
+        if (!specifier || !isArkRunTransportBypassSpecifier(specifier))
+            continue;
+        const fromLayer = layerForFile(dependency.from);
+        if (!fromLayer || !managed.has(fromLayer))
+            continue;
+        out.push(finding(extra, 'arkrun-transport-bypass', dependency.from, dependency.line, `${fromLayer} must not import broker/queue/emitter ${JSON.stringify(specifier)}; use the ArkRun kernel transport.`, { fromLayer, target: specifier }, teethAllowed));
+    }
+    return out;
+}
+/**
+ * Evaluate closed tier-1 ArkRun sensors. Empty extra → no findings (silent).
+ */
+export function evaluateArkRunSensors(input) {
+    const extra = input.arkRun;
+    if (!extra)
+        return { findings: [], completenessReasons: [] };
+    const teethAllowed = extraMergeTeethAllowed(input.classification);
+    const undeclared = evaluateUndeclared(extra, input.kernelCalls, input.declarations, input.layerForFile, teethAllowed);
+    const findings = [
+        ...evaluateMissingRoot(extra, input.compositionRootHits, teethAllowed),
+        ...evaluateKernelInDomain(extra, input.layers, input.dependencies, input.layerForFile, teethAllowed),
+        ...evaluateDirectNew(extra, input.layers, input.managedNews, input.compositionRootHits, input.layerForFile, teethAllowed),
+        ...undeclared.findings,
+        ...evaluateTransportBypass(extra, input.dependencies, input.layerForFile, teethAllowed),
+    ].sort(compareFindings);
+    const completenessReasons = [...undeclared.completenessReasons].sort((left, right) => {
+        const leftKey = `${left.code}\0${left.file ?? ''}\0${left.message}`;
+        const rightKey = `${right.code}\0${right.file ?? ''}\0${right.message}`;
+        return leftKey < rightKey ? -1 : leftKey > rightKey ? 1 : 0;
+    });
+    return { findings, completenessReasons };
+}
+/**
+ * Same sensors as `evaluateArkRunSensors`, filtered to the ESLint import/`new` envelope.
+ * Does not emit missing-root or undeclared-* (those need project-wide / declaration facts).
+ */
+export function evaluateArkRunEditorSensors(input) {
+    const result = evaluateArkRunSensors(input);
+    return {
+        findings: result.findings.filter((item) => isArkRunEditorSensor(item.sensor)),
+        completenessReasons: [],
+    };
+}
+function fileMatchesCompositionRoot(pattern, file) {
+    if (pattern === file)
+        return true;
+    const star = pattern.indexOf('*');
+    if (star < 0)
+        return false;
+    const prefix = pattern.slice(0, star).replace(/\/$/, '');
+    return prefix.length > 0 && (file === prefix || file.startsWith(`${prefix}/`));
+}
+function compositionRootHitsForSource(extra, file, source) {
+    const hasFactory = extractArkRunKernelCallsFromSource(file, source).some((call) => call.kind === 'factory');
+    const hits = [];
+    for (const pattern of extra.compositionRoots) {
+        if (!fileMatchesCompositionRoot(pattern, file))
+            continue;
+        hits.push({ file, matchedRoot: pattern, hasKernelFactory: hasFactory });
+    }
+    return hits;
+}
+/**
+ * Import / `new` envelope from one proposed source (hook Write/Edit, snippet MCP).
+ * Missing-root and undeclared-* stay project-wide CLI/MCP/preflight.
+ */
+export function evaluateArkRunEditorSensorsFromSource(input) {
+    const extra = input.arkRun;
+    if (!extra)
+        return { findings: [], completenessReasons: [] };
+    const admitted = new Set(extractArkRunImportedConstructorNamesFromSource(input.source));
+    return evaluateArkRunEditorSensors({
+        arkRun: extra,
+        layers: input.layers,
+        kernelCalls: [],
+        managedNews: extractArkRunManagedNewsFromSource(input.file, input.source, admitted),
+        compositionRootHits: compositionRootHitsForSource(extra, input.file, input.source),
+        declarations: [],
+        dependencies: extractArkRunValueImportDependenciesFromSource(input.file, input.source),
+        layerForFile: input.layerForFile,
+        classification: input.classification,
+    });
+}

package/bin/lib/check-args.mjs

@@ -0,0 +1,173 @@
+/**
+ * ark-check CLI flag parsing.
+ */
+import path from 'node:path';
+import { discoverLocalBaseRef, normalizePolicyBaseRef } from './policy-delta-io.mjs';
+
+export function resolveDesignDeltaBaseRef(root, explicit, env = process.env) {
+  const flag = typeof explicit === 'string' ? explicit.trim() : '';
+  if (flag) return flag;
+  const envRef = normalizePolicyBaseRef(env.ARK_POLICY_BASE_REF);
+  if (envRef) return envRef;
+  const githubBase = typeof env.GITHUB_BASE_REF === 'string' ? env.GITHUB_BASE_REF.trim() : '';
+  if (githubBase) return `origin/${githubBase}`;
+  return discoverLocalBaseRef(root) || undefined;
+}
+
+export function parseArgs(argv) {
+  const args = {
+    root: process.cwd(),
+    config: 'ark.config.json',
+    manifest: undefined,
+    printConfig: undefined,
+    tsconfig: undefined,
+    json: false,
+    strictConfig: false,
+    strictMerge: false,
+    requireGates: false,
+    requireWriteHook: undefined,
+    init: false,
+    installAgentGates: false,
+    compact: false,
+    tools: undefined,
+    force: false,
+    skillsOnly: false,
+    baseline: undefined,
+    policyBase: undefined,
+    policyBaseRef: undefined,
+    policyAck: undefined, failOnNewSmells: false, baseRef: undefined,
+    contractSession: false,
+    contractDiff: false,
+    changed: false,
+    against: undefined,
+    base: undefined,
+    persona: undefined,
+    author: undefined,
+    failUngoverned: false,
+    updateBaseline: false,
+    noCache: false,
+    resident: false,
+    coverage: false,
+    migrateCommands: false,
+    doctor: false,
+    plan: false,
+    recommend: false,
+    writePlan: false,
+    listPolicyPacks: false,
+    applyPolicyPack: undefined,
+    watch: false,
+    beginner: false,
+    openReport: false,
+    noOpenReport: false,
+    version: false,
+    help: false,
+    all: false,
+    followConfigRoot: false,
+  };
+  const requireValue = (flag, index) => {
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('-')) {
+      throw new Error(`Missing value for ${flag}. Run arkgate-check --help for usage.`);
+    }
+    return value;
+  };
+  for (let i = 2; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--json') args.json = true;
+    else if (arg === '--strict' || arg === '--strict-merge') {
+      args.strictConfig = true;
+      args.requireGates = true;
+      args.strictMerge = true;
+    }
+    else if (arg === '--strict-config') args.strictConfig = true;
+    else if (arg === '--require-gates') {
+      args.requireGates = true;
+      args.strictConfig = true;
+    }
+    else if (arg === '--require-write-hook') {
+      args.requireWriteHook = requireValue(arg, i++).trim().toLowerCase();
+    }
+    else if (arg === '--init') args.init = true;
+    else if (arg === '--preset') args.preset = requireValue(arg, i++);
+    else if (arg === '--install-agent-gates') args.installAgentGates = true;
+    else if (arg === '--compact') args.compact = true;
+    else if (arg === '--tools') {
+      // Consume the next arg only when it isn't another flag (same rule as --baseline),
+      // so `--tools --force` can't silently eat --force as a "tool name".
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        i += 1;
+        args.tools = next
+          .split(',')
+          .map((tool) => tool.trim().toLowerCase())
+          .filter(Boolean);
+      } else {
+        args.tools = []; // flag without a value — rejected in runInstallAgentGates
+      }
+    }
+    else if (arg === '--force') args.force = true;
+    else if (arg === '--follow-config-root') args.followConfigRoot = true;
+    else if (arg === '--skills-only') args.skillsOnly = true;
+    else if (arg === '--coverage') args.coverage = true;
+    else if (arg === '--doctor') args.doctor = true;
+    else if (arg === '--plan') args.plan = true;
+    else if (arg === '--rules-inventory') args.rulesInventory = true;
+    else if (arg === '--recommend') args.recommend = true;
+    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 = requireValue(arg, i++);
+    else if (arg === '--suggest-include') args.suggestInclude = true;
+    else if (arg === '--adopt-contract') args.adoptContract = true;
+    else if (arg === '--migrate-contract') args.migrateContract = true;
+    else if (arg === '--ratchet-cores') args.ratchetCores = 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;
+    else if (arg === '--claude-home') args.claudeHome = true;
+    else if (arg === '--grok-home') args.grokHome = true;
+    else if (arg === '--agent-homes') {
+      args.agentHomes = true;
+      args.codexHome = true;
+      args.claudeHome = true;
+      args.grokHome = true;
+    }
+    else if (arg === '--migrate-commands') args.migrateCommands = true;
+    else if (arg === '--no-cache') args.noCache = true;
+    else if (arg === '--resident') args.resident = true;
+    else if (arg === '--report') {
+      const next = argv[i + 1];
+      args.report = next && !next.startsWith('-') ? argv[++i] : 'ark-report.html';
+    }
+    else if (arg === '--reset-origin') args.resetOrigin = true;
+    else if (arg === '--no-archive') args.noArchive = true;
+    else if (arg === '--open') args.openReport = true;
+    else if (arg === '--no-open') args.noOpenReport = true;
+    else if (arg === '--baseline' || arg === '--update-baseline') {
+      if (arg === '--update-baseline') args.updateBaseline = true;
+      // optional path value: consume the next arg only when it isn't another flag
+      const next = argv[i + 1];
+      args.baseline = next && !next.startsWith('-') ? argv[++i] : '.ark-baseline.json';
+    }
+    else if (arg === '--policy-base') args.policyBase = requireValue(arg, i++);
+    else if (arg === '--policy-base-ref') args.policyBaseRef = requireValue(arg, i++);
+    else if (arg === '--policy-ack') args.policyAck = requireValue(arg, i++); else if (arg === '--fail-on-new-smells') args.failOnNewSmells = true; else if (arg === '--base-ref') args.baseRef = requireValue(arg, i++);
+    else if (arg === '--contract-session') args.contractSession = true;
+    else if (arg === '--contract-diff') args.contractDiff = true;
+    else if (arg === '--changed') args.changed = true;
+    else if (arg === '--against') args.against = requireValue(arg, i++);
+    else if (arg === '--base') args.base = requireValue(arg, i++);
+    else if (arg === '--persona') args.persona = requireValue(arg, i++);
+    else if (arg === '--author') args.author = requireValue(arg, i++);
+    else if (arg === '--root') args.root = path.resolve(requireValue(arg, i++));
+    else if (arg === '--config') args.config = requireValue(arg, i++);
+    else if (arg === '--manifest') args.manifest = requireValue(arg, i++);
+    else if (arg === '--print-config') args.printConfig = requireValue(arg, i++);
+    else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
+    else if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--all') args.all = true;
+    else if (arg === '--version' || arg === '-V') args.version = true;
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
+  }
+  return args;
+}

package/bin/lib/check-config-detect.mjs

@@ -0,0 +1,101 @@
+/**
+ * Convention-based ark.config detection used by --init.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
+  DEFAULT_INTENT_PREFIXES,
+  DEFAULT_LAYER_DIRECTORIES,
+  DEFAULT_RULES,
+} from '../ark-shared.mjs';
+import { normalize, walk } from './scan-files.mjs';
+import { suggestLayerForDir } from './suggestions.mjs';
+
+/**
+ * Infer an ark.config.json from the directories that actually exist in the project,
+ * using the same layer→directory conventions as the eleven-layer template. A directory
+ * only counts when it contains at least one source file, so an empty scaffold dir can't
+ * produce a layer whose pattern matches nothing (which --strict-config would fail).
+ */
+export function detectConfig(root) {
+  const srcDir = fs.existsSync(path.join(root, 'src')) ? 'src' : '.';
+  const layers = [];
+
+  for (const entry of DEFAULT_INTENT_PREFIXES) {
+    const directories = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? []).filter(
+      (directory) => walk(path.join(root, srcDir, directory), [], { root }).length > 0
+    );
+    if (directories.length === 0) continue;
+    layers.push({
+      name: entry.layer,
+      patterns: directories.map((directory) => `${normalize(path.join(srcDir, directory))}/**`),
+      intentPrefixes: entry.prefixes,
+      ...(entry.layer === 'DomainModel'
+        ? { forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS }
+        : {}),
+    });
+  }
+
+  const names = new Set(layers.map((layer) => layer.name));
+  const rules = DEFAULT_RULES.filter((rule) => names.has(rule.from) && names.has(rule.to));
+
+  return { srcDir, config: { include: [srcDir], layers, rules } };
+}
+
+/** Top-level directories under srcDir not covered by any detected layer pattern. */
+export function uncoveredDirectories(root, srcDir, layers) {
+  const base = path.join(root, srcDir);
+  if (!fs.existsSync(base)) return [];
+  return fs
+    .readdirSync(base, { withFileTypes: true })
+    .filter(
+      (entry) =>
+        entry.isDirectory() &&
+        entry.name !== 'node_modules' &&
+        entry.name !== 'dist' &&
+        !entry.name.startsWith('.')
+    )
+    .map((entry) => entry.name)
+    .filter((name) => {
+      const prefix = `${normalize(path.join(srcDir, name))}/`;
+      return !layers.some((layer) =>
+        layer.patterns.some((pattern) => pattern.startsWith(prefix))
+      );
+    });
+}
+
+export function proposeForUncovered(root, srcDir, layers) {
+  const proposals = [];
+  for (const top of uncoveredDirectories(root, srcDir, layers)) {
+    const direct = suggestLayerForDir(top);
+    if (direct) {
+      proposals.push({ dir: `${srcDir}/${top}`, ...direct });
+      continue;
+    }
+    let children = [];
+    try {
+      children = fs
+        .readdirSync(path.join(root, srcDir, top), { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name !== 'node_modules' && !e.name.startsWith('.'))
+        .map((e) => e.name);
+    } catch {
+      /* not a readable directory — treat as unrecognized below */
+    }
+    if (children.length > 0) {
+      // Descend: propose per child so a mixed `lib/` yields lib/repositories → Persistence
+      // AND flags lib/db as unrecognized, instead of dropping the parts Ark can't place.
+      for (const child of children) {
+        const hit = suggestLayerForDir(child);
+        proposals.push(
+          hit
+            ? { dir: `${srcDir}/${top}/${child}`, ...hit }
+            : { dir: `${srcDir}/${top}/${child}`, unrecognized: true }
+        );
+      }
+    } else {
+      proposals.push({ dir: `${srcDir}/${top}`, unrecognized: true });
+    }
+  }
+  return proposals;
+}

package/bin/lib/check-watch.mjs

@@ -0,0 +1,80 @@
+/**
+ * ark-check --watch loop (polling fallback when fs.watch is unavailable).
+ */
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+function watchFingerprint(target) {
+  const pending = [target];
+  const entries = [];
+  while (pending.length > 0) {
+    const current = pending.pop();
+    let stat;
+    try {
+      stat = fs.statSync(current);
+    } catch {
+      continue;
+    }
+    entries.push(`${current}:${stat.mtimeMs}:${stat.size}`);
+    if (!stat.isDirectory()) continue;
+    try {
+      for (const name of fs.readdirSync(current)) pending.push(path.join(current, name));
+    } catch {
+      // A concurrent delete is represented by the next fingerprint.
+    }
+  }
+  return entries.sort().join('|');
+}
+
+function watchByPolling(target, onChange) {
+  let previous = watchFingerprint(target);
+  setInterval(() => {
+    const current = watchFingerprint(target);
+    if (current === previous) return;
+    previous = current;
+    onChange();
+  }, 250);
+}
+
+export async function runWatchMode(args, { cliPath, loadConfig, dim }) {
+  const argv = process.argv.slice(2).filter((token) => token !== '--watch');
+  let debounce;
+  const rerun = () => {
+    clearTimeout(debounce);
+    debounce = setTimeout(() => {
+      const result = spawnSync(process.execPath, [cliPath, ...argv], {
+        cwd: args.root,
+        stdio: 'inherit',
+        env: process.env,
+      });
+      process.exitCode = result.status ?? 1;
+    }, 300);
+  };
+
+  let config;
+  try {
+    config = loadConfig(args.root, args.config);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+    return;
+  }
+
+  for (const entry of config.include ?? []) {
+    const target = path.join(args.root, entry);
+    if (!fs.existsSync(target)) continue;
+    try {
+      const watcher = fs.watch(target, { recursive: true }, rerun);
+      watcher.on('error', () => {
+        watcher.close();
+        watchByPolling(target, rerun);
+      });
+    } catch {
+      watchByPolling(target, rerun);
+    }
+  }
+
+  console.log(dim('Watching governed paths for changes… (Ctrl+C to stop)'));
+  await new Promise(() => {});
+}