arkgate 4.8.24 → 4.8.25

package/bin/lib/config-contract.mjs

@@ -10,13 +10,14 @@
 
 import { ARK_ORDER_SCHEMA_DEF, ARK_RUN_SCHEMA_DEF, defaultedArkOrder, defaultedArkRun, validateArkOrderExtra, validateArkRunExtra, } from './config-extras.mjs';
 import { CHILD_SLICES_SCHEMA_DEF, SHARED_IMPORTS_SLICE_SCHEMA_DEF, validateSliceContract, } from './config-contract-slices.mjs';
+import { isObject, propertyPath, validateSchemaNode, valueType } from './schema-validation.mjs';
 import { canonicalStewardId } from './team-parliament.mjs';
 /** Current published ark.config.json schema version (ADR 0027: 1.3 adds optional arkOrder). */
 export const ARK_CONFIG_SCHEMA_VERSION = '1.3';
 /** Closed layer trust tags. Optional; absence is silent. Not a schemaVersion bump. */
 export const LAYER_TRUST_BOUNDARIES = ['public', 'auth', 'admin', 'internal'];
 /** Future house: empty globs are expected; missing owners stay silent even when required. */
-export function isFutureHouseLayer(layer) {
+function isFutureHouseLayer(layer) {
     return layer?.optional === true || layer?.reserved === true || layer?.allowEmpty === true;
 }
 /**
@@ -141,10 +142,21 @@ export const ARK_CONFIG_SCHEMA = {
          *  maxFiles also bounds structural-hint preload (orchestration-only / thin-adapter /
          *  writes-via-aggregate). There is no arkrules.hintBudget. */
         coverage: { $ref: '#/$defs/coverage' },
-        /** ADR 0012 — layer name → relative path to arkrules/<Layer>.json */
+        /** ADR 0012 — layer name → one path, or a list of paths merged into that layer. */
         arkRules: {
             type: 'object',
-            additionalProperties: { type: 'string', minLength: 1 },
+            additionalProperties: {
+                description: 'A project-relative ArkRules path, or a list of paths merged into one catalog for this layer. A string keeps today\'s behaviour. An older build that types this value as a string rejects an array at config load.',
+                oneOf: [
+                    { type: 'string', minLength: 1 },
+                    {
+                        type: 'array',
+                        minItems: 1,
+                        uniqueItems: true,
+                        items: { type: 'string', minLength: 1 },
+                    },
+                ],
+            },
             default: {},
         },
         /** ADR 0020 — optional ArkRun extra. Absence is silent; unknown keys fail closed. */
@@ -278,123 +290,33 @@ export class ArkConfigValidationError extends Error {
         this.issues = issues;
     }
 }
-function isObject(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value);
-}
-function propertyPath(parent, key) {
-    return /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(key)
-        ? `${parent}.${key}`
-        : `${parent}[${JSON.stringify(key)}]`;
-}
-function valueType(value) {
-    if (value === null)
-        return 'null';
-    if (Array.isArray(value))
-        return 'array';
-    return typeof value;
-}
-function resolveSchemaRef(ref, root) {
-    const prefix = '#/$defs/';
-    if (!ref.startsWith(prefix))
-        return undefined;
-    return root.$defs[ref.slice(prefix.length)];
-}
-function validateNode(value, schema, path, root, issues) {
-    if (schema.$ref) {
-        const referenced = resolveSchemaRef(schema.$ref, root);
-        if (!referenced) {
-            issues.push({ path, message: `schema reference ${schema.$ref} cannot be resolved` });
-            return;
-        }
-        validateNode(value, referenced, path, root, issues);
-        return;
-    }
-    if (schema.const !== undefined && !Object.is(value, schema.const)) {
-        issues.push({ path, message: `must equal ${JSON.stringify(schema.const)}` });
-        return;
-    }
-    if (schema.enum && !schema.enum.some((candidate) => Object.is(candidate, value))) {
-        issues.push({ path, message: `must be one of ${schema.enum.map(String).join(', ')}` });
-        return;
-    }
-    if (schema.type === 'object') {
-        if (!isObject(value)) {
-            issues.push({ path, message: `must be an object; received ${valueType(value)}` });
-            return;
-        }
-        const properties = schema.properties ?? {};
-        for (const key of schema.required ?? []) {
-            if (value[key] === undefined) {
-                issues.push({ path: propertyPath(path, key), message: 'is required' });
-            }
-        }
-        if (schema.additionalProperties === false) {
-            for (const key of Object.keys(value)) {
-                if (!(key in properties)) {
-                    issues.push({ path: propertyPath(path, key), message: 'unknown field' });
-                }
-            }
-        }
-        else if (schema.additionalProperties !== undefined &&
-            schema.additionalProperties !== true &&
-            typeof schema.additionalProperties === 'object') {
-            const additional = schema.additionalProperties;
-            for (const key of Object.keys(value)) {
-                if (!(key in properties)) {
-                    validateNode(value[key], additional, propertyPath(path, key), root, issues);
-                }
-            }
-        }
-        for (const [key, childSchema] of Object.entries(properties)) {
-            if (value[key] !== undefined) {
-                validateNode(value[key], childSchema, propertyPath(path, key), root, issues);
-            }
-        }
+/** The schema walk has no oneOf, so string-or-array `arkRules` values are checked here. */
+function validateArkRulesRefs(candidate, issues) {
+    const refs = candidate.arkRules;
+    if (refs === undefined || !isObject(refs))
         return;
-    }
-    if (schema.type === 'array') {
-        if (!Array.isArray(value)) {
-            issues.push({ path, message: `must be an array; received ${valueType(value)}` });
-            return;
+    for (const [layer, value] of Object.entries(refs)) {
+        const path = propertyPath('$.arkRules', layer);
+        if (typeof value === 'string') {
+            if (value.length === 0)
+                issues.push({ path, message: 'must be a non-empty relative path string' });
+            continue;
         }
-        if (schema.minItems !== undefined && value.length < schema.minItems) {
-            issues.push({ path, message: `must contain at least ${schema.minItems} item(s)` });
+        if (!Array.isArray(value) || value.length === 0) {
+            issues.push({ path, message: 'must be a non-empty path string or an array of paths' });
+            continue;
         }
-        if (schema.uniqueItems) {
-            const serialized = value.map((entry) => JSON.stringify(entry));
-            if (new Set(serialized).size !== serialized.length) {
-                issues.push({ path, message: 'must not contain duplicate items' });
+        const seen = new Set();
+        value.forEach((entry, index) => {
+            const itemPath = `${path}[${index}]`;
+            if (typeof entry !== 'string' || entry.length === 0) {
+                issues.push({ path: itemPath, message: 'must be a non-empty relative path string' });
+                return;
             }
-        }
-        if (schema.items) {
-            value.forEach((entry, index) => validateNode(entry, schema.items, `${path}[${index}]`, root, issues));
-        }
-        return;
-    }
-    if (schema.type === 'string') {
-        if (typeof value !== 'string') {
-            issues.push({ path, message: `must be a string; received ${valueType(value)}` });
-            return;
-        }
-        if (schema.minLength !== undefined && value.length < schema.minLength) {
-            issues.push({ path, message: `must contain at least ${schema.minLength} character(s)` });
-        }
-        return;
-    }
-    if (schema.type === 'boolean') {
-        if (typeof value !== 'boolean') {
-            issues.push({ path, message: `must be a boolean; received ${valueType(value)}` });
-        }
-        return;
-    }
-    if (schema.type === 'integer') {
-        if (!Number.isInteger(value)) {
-            issues.push({ path, message: `must be an integer; received ${valueType(value)}` });
-            return;
-        }
-        if (schema.minimum !== undefined && value < schema.minimum) {
-            issues.push({ path, message: `must be at least ${schema.minimum}` });
-        }
+            if (seen.has(entry))
+                issues.push({ path: itemPath, message: 'duplicate path' });
+            seen.add(entry);
+        });
     }
 }
 function validateLayerOwners(candidate, issues) {
@@ -523,11 +445,12 @@ export function migrateArkConfig(input, source = 'ark.config.json') {
 export function loadArkConfigContract(input, source = 'ark.config.json') {
     const { candidate, migratedFrom } = migrateArkConfig(input, source);
     const issues = [];
-    validateNode(candidate, ARK_CONFIG_SCHEMA, '$', ARK_CONFIG_SCHEMA, issues);
+    validateSchemaNode(candidate, ARK_CONFIG_SCHEMA, '$', ARK_CONFIG_SCHEMA, issues);
     validateArkRunExtra(candidate, issues);
     validateArkOrderExtra(candidate, issues);
     validateLayerOwners(candidate, issues);
     validateSliceContract(candidate, issues);
+    validateArkRulesRefs(candidate, issues);
     if (issues.length > 0)
         throw new ArkConfigValidationError(source, issues);
     return { config: candidate, migratedFrom };

package/bin/lib/config-extras.mjs

@@ -88,22 +88,26 @@ export function defaultedArkOrder(value) {
         xiKeys: value.xiKeys === undefined ? [] : value.xiKeys,
     };
 }
+/** Each named managed layer of an extra must be declared in `layers[]`. */
+function validateManagedLayersDeclared(config, managed, extraKey, issues) {
+    if (!Array.isArray(managed))
+        return;
+    const layerNames = declaredLayerNames(config);
+    managed.forEach((name, index) => {
+        if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
+            issues.push({
+                path: `$.${extraKey}.managedLayers[${index}]`,
+                message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
+            });
+        }
+    });
+}
 export function validateArkRunExtra(config, issues) {
     const extra = config.arkRun;
     if (extra === undefined || !isObject(extra))
         return;
-    const layerNames = declaredLayerNames(config);
     const managed = extra.managedLayers;
-    if (Array.isArray(managed)) {
-        managed.forEach((name, index) => {
-            if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
-                issues.push({
-                    path: `$.arkRun.managedLayers[${index}]`,
-                    message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
-                });
-            }
-        });
-    }
+    validateManagedLayersDeclared(config, managed, 'arkRun', issues);
     if (extra.mode === 'enforced') {
         const roots = extra.kernelRoots ?? extra.compositionRoots;
         if (!Array.isArray(roots) || roots.length === 0) {
@@ -124,18 +128,8 @@ export function validateArkOrderExtra(config, issues) {
     const extra = config.arkOrder;
     if (extra === undefined || !isObject(extra))
         return;
-    const layerNames = declaredLayerNames(config);
     const managed = extra.managedLayers;
-    if (Array.isArray(managed)) {
-        managed.forEach((name, index) => {
-            if (typeof name === 'string' && name.length > 0 && !layerNames.has(name)) {
-                issues.push({
-                    path: `$.arkOrder.managedLayers[${index}]`,
-                    message: `layer ${JSON.stringify(name)} is not declared in layers[]`,
-                });
-            }
-        });
-    }
+    validateManagedLayersDeclared(config, managed, 'arkOrder', issues);
     if (extra.mode === 'enforced') {
         const roots = extra.planeRoots;
         if (!Array.isArray(roots) || roots.length === 0) {

package/bin/lib/contract-smells.mjs

@@ -102,15 +102,22 @@ function ackMatchable(...names) {
 }
 
 /**
- * Load the optional acknowledgment sidecar. Bounded and fail-loud:
- * non-file, oversized, unparsable, or wrong-shaped content → `invalid: true`
- * with `acks: []` (a broken file never suppresses anything).
+ * Bounded, fail-loud `.ark/` acknowledgment sidecar loader (contract-smell and
+ * ambient-state acks). Missing file → `exists: false`. Non-file, oversized,
+ * unparsable, over-long, or wrong-shaped content → `invalid: true` with
+ * `acks: []` (a broken file never suppresses anything).
  *
  * @param {string} root
- * @returns {{ path: string, exists: boolean, invalid?: boolean, error?: string, acks: Array<{id: string, edge: string, reason?: string}> }}
+ * @param {string} relPath
+ * @param {{
+ *   shape: string,
+ *   isWellFormed: (ack: any) => boolean,
+ *   malformed: string,
+ *   normalize?: (acks: any[]) => any[],
+ * }} spec
+ * @returns {{ path: string, exists: boolean, invalid?: boolean, error?: string, acks: any[] }}
  */
-export function loadContractSmellAcks(root) {
-  const relPath = CONTRACT_SMELL_ACKS_PATH;
+export function loadAckSidecar(root, relPath, spec) {
   const abs = path.join(root, relPath);
   let stats;
   try {
@@ -128,21 +135,32 @@ export function loadContractSmellAcks(root) {
     return invalid(error instanceof Error ? error.message : 'unreadable JSON');
   }
   const acks = Array.isArray(parsed?.acks) ? parsed.acks : null;
-  if (!acks) return invalid('expected { acks: [{ id, edge, reason? }] }');
+  if (!acks) return invalid(`expected ${spec.shape}`);
   if (acks.length > MAX_ACK_ENTRIES) return invalid(`more than ${MAX_ACK_ENTRIES} entries`);
-  const wellFormed = acks.every(
-    (a) =>
+  if (!acks.every(spec.isWellFormed)) return invalid(spec.malformed);
+  return { path: relPath, exists: true, acks: spec.normalize ? spec.normalize(acks) : acks };
+}
+
+/**
+ * Load the optional acknowledgment sidecar. Bounded and fail-loud:
+ * non-file, oversized, unparsable, or wrong-shaped content → `invalid: true`
+ * with `acks: []` (a broken file never suppresses anything).
+ *
+ * @param {string} root
+ * @returns {{ path: string, exists: boolean, invalid?: boolean, error?: string, acks: Array<{id: string, edge: string, reason?: string}> }}
+ */
+export function loadContractSmellAcks(root) {
+  return loadAckSidecar(root, CONTRACT_SMELL_ACKS_PATH, {
+    shape: '{ acks: [{ id, edge, reason? }] }',
+    isWellFormed: (a) =>
       a !== null &&
       typeof a === 'object' &&
       typeof a.id === 'string' &&
       typeof a.edge === 'string' &&
       a.edge.trim().length > 0 &&
-      (a.reviewBy === undefined || typeof a.reviewBy === 'string')
-  );
-  if (!wellFormed) {
-    return invalid('every ack needs string id, non-empty string edge, and string reviewBy when present');
-  }
-  return { path: relPath, exists: true, acks };
+      (a.reviewBy === undefined || typeof a.reviewBy === 'string'),
+    malformed: 'every ack needs string id, non-empty string edge, and string reviewBy when present',
+  });
 }
 
 /**

package/bin/lib/core-ratchet.mjs

@@ -8,8 +8,6 @@ import { computeCoverage } from './doctor-plan.mjs';
 import { CORE_LAYER_NAMES } from './core-layers.mjs';
 import { resolveConfigPathWithinRoot } from './project-root.mjs';
 
-export { CORE_LAYER_NAMES } from './core-layers.mjs';
-
 /**
  * Core layers whose optionality matters once they match files (presets share these names).
  * Used by doctor adoption gaps and `--ratchet-cores`.

package/bin/lib/dashboard-cli.mjs

@@ -6,8 +6,8 @@
 export const DASHBOARD_DEFAULT_INTERVAL_MS = 2000;
 export const DASHBOARD_DEFAULT_TIMEOUT_MS = 5000;
 export const DASHBOARD_DEFAULT_URL = 'http://127.0.0.1:3000/snapshot';
-export const DASHBOARD_MIN_MS = 200;
-export const DASHBOARD_MAX_MS = 60_000;
+const DASHBOARD_MIN_MS = 200;
+const DASHBOARD_MAX_MS = 60_000;
 
 export const DASHBOARD_HELP = `arkgate-dashboard (alias ark-dashboard, ark dashboard) — observability TUI.
 Usage: arkgate-dashboard [--url <inspector-url>] [--interval <ms>] [--timeout <ms>] [--once]

package/bin/lib/deep-module-coach.mjs

@@ -14,12 +14,10 @@ import {
   DEEPENING_CANDIDATE_CAP,
 } from './deepening-coach.mjs';
 
-export { buildDeepeningCandidates, ARK_DEEPENING_COACH_SCHEMA_VERSION, DEEPENING_CANDIDATE_CAP };
-
 /** Recent-window commit cap for hot-path heuristic (budget). */
-export const HOT_PATH_COMMIT_LIMIT = 200;
+const HOT_PATH_COMMIT_LIMIT = 200;
 /** Max listed hot paths. */
-export const HOT_PATH_LIST_CAP = 8;
+const HOT_PATH_LIST_CAP = 8;
 /** Minimum change hits before a path is “elevated”. */
 export const HOT_PATH_MIN_HITS = 3;
 /** Kill hung git instead of stalling CI. */

package/bin/lib/deploy-path.mjs

@@ -3,7 +3,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { readPackageJson, packageScriptsHaveTypecheck } from './gate-files.mjs';
+import { readPackageJson, packageScriptsHaveTypecheck, someNestedPackageJson } from './gate-files.mjs';
 
 /**
  * Production deploy path quality (universal — any consumer repo).
@@ -62,44 +62,19 @@ export function detectDeployPathQuality(root) {
   let hasTypecheckScript = packageScriptsHaveTypecheck(scripts);
   const packageLintScripts = [];
   // Monorepo: package-level scripts count (apps/web, packages/ui, …).
-  try {
-    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-      if (!entry.isDirectory() || entry.name.startsWith('.') || entry.name === 'node_modules') continue;
-      const candidates = [path.join(root, entry.name)];
-      // one more level: packages/foo
-      try {
-        for (const child of fs.readdirSync(path.join(root, entry.name), { withFileTypes: true })) {
-          if (child.isDirectory() && !child.name.startsWith('.')) {
-            candidates.push(path.join(root, entry.name, child.name));
-          }
-        }
-      } catch {
-        /* ignore */
-      }
-      for (const dir of candidates) {
-        const pj = path.join(dir, 'package.json');
-        if (!fs.existsSync(pj)) continue;
-        try {
-          const nested = JSON.parse(fs.readFileSync(pj, 'utf8'));
-          const ns = nested.scripts && typeof nested.scripts === 'object' ? nested.scripts : {};
-          if (scriptHasLint(ns)) {
-            hasLintScript = true;
-            packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
-          }
-          if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
-          const nd = {
-            ...(nested.dependencies || {}),
-            ...(nested.devDependencies || {}),
-          };
-          if (nd.next && !engines.includes('next')) engines.push('next');
-        } catch {
-          /* ignore */
-        }
-      }
+  someNestedPackageJson(root, (nested, dir) => {
+    const ns = nested.scripts && typeof nested.scripts === 'object' ? nested.scripts : {};
+    if (scriptHasLint(ns)) {
+      hasLintScript = true;
+      packageLintScripts.push(path.relative(root, dir).split(path.sep).join('/'));
     }
-  } catch {
-    /* ignore */
-  }
+    if (packageScriptsHaveTypecheck(ns)) hasTypecheckScript = true;
+    const nd = {
+      ...(nested.dependencies || {}),
+      ...(nested.devDependencies || {}),
+    };
+    if (nd.next && !engines.includes('next')) engines.push('next');
+  });
 
   const ciTexts = collectCiWorkflowTexts(root);
   const ciJoined = ciTexts.join('\n');

package/bin/lib/design-smells.mjs

@@ -494,7 +494,7 @@ export function summarizeDesignFitness(smells, ctx = {}) {
 export const GREEN_PLAN_POINTER_MAX_IDS = 4;
 
 /** When a smell has no evidence path, say so — do not leave the reader hunting. */
-export const SMELL_UNATTRIBUTED =
+const SMELL_UNATTRIBUTED =
   'no file — leftover design, not a specific line';
 
 /**
@@ -502,7 +502,7 @@ export const SMELL_UNATTRIBUTED =
  * The pointer used to print only the id, so "1 design smell (domain-logic-in-ui)"
  * could not answer "did my change cause this?"
  */
-export function formatSmellPointerName(id, smells) {
+function formatSmellPointerName(id, smells) {
   const match = (smells || []).find((smell) => smell?.id === id);
   const evidence = Array.isArray(match?.evidence)
     ? match.evidence.filter((entry) => typeof entry === 'string' && entry.trim())

package/bin/lib/diagnostic-catalog.mjs

@@ -37,6 +37,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('LAYER_REFERENCE_VIOLATION', 'layer', 'Layer reference blocked (snippet / AI gate)', 'Snippet analysis found an intent or string reference that would couple layers in a direction the architecture profile forbids.', 'Move the reference to an allowed layer or introduce a port/event boundary, then re-run the snippet gate.'),
     entry('SHARED_IMPORTS_SLICE', 'layer', 'A shared root imports a slice', 'A declared shared root imports a slice directly. That hop is allowed while sharedImportsSlice is unset or "deny-cross-parent", so this is advisory: the universe wall is direct-only.', 'Move the code the shared root needs into the shared root, or invert the dependency. Set sharedImportsSlice: "deny" to make these edges errors. With "deny-cross-parent", a slice that reaches another universe through a shared root is reported as LAYER_IMPORT_VIOLATION with reasonId CROSS_PARENT_VIA_SHARED. This warning does not fail the check.', { oftenAdvisory: true }),
     entry('CIRCULAR_DEPENDENCY', 'layer', 'Dependency cycle', 'Two or more modules import each other in a loop. Cycles make ownership unclear and break stable layer direction.', 'Extract the shared dependency into a third module, invert one edge behind a port, or merge units that are truly one — then preflight again.'),
+    entry('CROSS_WALL_DUPLICATE', 'layer', 'Code copied across a wall', 'Near-identical code sits on two sides of a slice wall (or in two layers that may not import each other). The wall would deny the import, so the code was copied instead. Status details (`--doctor --all`) and the report list it from token fingerprints taken at status time; they never enter the check, so the verdict does not change. Same-slice copies are counted, never listed.', 'Move one copy to a shared home the wall allows — a declared shared root, the universe common folder, or a layer both sides may import — then import it from both sides. One move at a time, through the write gate (/ark-place names the destination). Advisory only — it never fails a run.', { oftenAdvisory: true }),
+    entry('CROSS_LAYER_DUPLICATE', 'layer', 'Code copied in two layers', 'Near-identical code sits in two layers, and at least one of them may import the other. Status details (`--doctor --all`) and the report list it from token fingerprints taken at status time; the verdict does not change.', 'Keep one copy in the lower layer both sides may import, and import it from the other. One move at a time, through the write gate. Advisory only — it never fails a run.', { oftenAdvisory: true }),
     // ── capability / ambient ─────────────────────────────────────────────────
     entry('FORBIDDEN_GLOBAL', 'capability', 'Forbidden ambient global or dual import', 'The file’s layer lists this ambient (or its exact import dual, e.g. process / node:process) in forbiddenGlobals. Pure layers must not reach wall-clock, network, process, or similar effects directly.', 'Inject the capability through a small port (Clock, HttpPort, Config, …), bind the implementation outside the walled layer, then preflight again.'),
     entry('CAPABILITY_VIOLATION', 'capability', 'Denied effect capability', 'The layer denies an effect capability (network, filesystem, clock, randomness, environment, process, persistence) and the candidate uses that effect via ambient or import evidence.', 'Define a capability port in the walled layer, bind the implementation in an adapter layer, then preflight again. Never mechanical-safe — port shape is a design decision.'),
@@ -57,10 +59,13 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRULE_INVARIANT', 'arkrules', 'ArkRule invariant failed', 'Reserved / remediation-recognized code for invariant-plane failures bound to an ArkRule id (coverage path also emits INVARIANT_UNCOVERED).', 'Fix the invariant for the ArkRule declared in arkrules/<Layer>.json, then preflight again. Do not demote without acknowledgement.'),
     entry('ARKRULE_SCOPE_EMPTY', 'arkrules', 'ArkRule appliesTo matched zero files', 'An ArkRule’s appliesTo globs matched no governed files — the rule cannot observe what it claims to protect.', 'Fix appliesTo globs so they match governed files, or remove the rule. Enforced empty scope fails; advisory empty scope warns.', { oftenAdvisory: true }),
     entry('ARKRULE_HINT_BUDGET_EXHAUSTED', 'arkrules', 'Structural-hint budget exhausted', 'orchestration-only, thin-adapter, and writes-via-aggregate only evaluate files the hint loader preloaded. When eligible governed files exceed that budget (coverage.maxFiles, default 400 — there is no arkrules.hintBudget), those sensors never saw the rest of their scope. Enforced + unreviewed is not green. The finding names exact hinted/governed counts and per-sensor reviewed N/M of scope.', 'Raise coverage.maxFiles in ark.config.json (this cap also bounds structural-hint preload; --doctor names the coupling) so hinted/governed counts match, then re-run with --strict-config. An enforced hint sensor that cannot see its scope fails strict.'),
-    entry('ARKRULE_FILE_UNREFERENCED', 'arkrules', 'ArkRules file not referenced', 'A JSON file under arkrules/ is not referenced by the arkRules map in ark.config.json (or no map exists), so none of its rules are enforced or reported. Drift looks like governance until someone notices.', 'Reference the file from arkRules ("<Layer>": "arkrules/<file>.json"), or delete it. Advisory only: it never fails the check.', { oftenAdvisory: true }),
+    entry('ARKRULE_FILE_UNREFERENCED', 'arkrules', 'ArkRules file not referenced', 'A JSON file under arkrules/, or a slice file named arkrules.<Layer>.json beside governed code, is not in the effective catalog, so none of its rules are enforced. Drift looks like governance until someone notices.', 'Reference a central file from arkRules, set childSlices.arkRulesFile so a slice file is discovered, or delete it. Advisory only: it never fails the check.', { oftenAdvisory: true }),
+    entry('ARKRULE_DUPLICATE_ID', 'arkrules', 'ArkRule id declared more than once', 'Two ArkRules files in one layer declare the same effective id. Central ids stay bare. A slice file is namespaced as <childId>#<localId>, so the same local id in two slices is not a duplicate.', 'Rename one id, or split the files onto different slices. Config load fails closed. The catalog is not enforced until the id is unique.'),
+    entry('ARKRULE_SCOPE_ESCAPES_SLICE', 'arkrules', 'Slice ArkRule appliesTo leaves its slice', 'A file discovered from childSlices.arkRulesFile set appliesTo to a glob that can match outside that child slice. The default, when appliesTo is omitted, is the slice directory.', 'Narrow appliesTo to the slice directory, or omit it. Config load fails closed. The escaping rule is not enforced.'),
     entry('INVARIANT_CATALOG_EMPTY', 'arkrules', 'Domain invariant catalog is empty', 'ArkRules is on and a Domain-role layer has code, but invariants[] has no phrases the code must preserve. Empty looks like “done” until someone fills the catalog.', 'Add 1–2 short phrases to invariants[] in arkrules/<Domain>.json (or the mapped file). Starters show the shape. Advisory unless a domain structure rule is already enforced — then --strict-merge can refuse. Do not freeze this finding.', { oftenAdvisory: true }),
     entry('INVARIANT_UNCOVERED', 'arkrules', 'Invariant without coverage evidence', 'An ArkRules invariant is under contract but no covering test title or declared symbol evidence was found (or coverage is partial). Kind is never-had-tests (adopt residual) vs tests-disappeared (suite exists).', 'Add a test title or declared symbol covering the arkruleId, then preflight again. Treat never-had-tests as adopt residual; treat tests-disappeared as a regression. Missing test globs report partial — never fake green. When the message reports an exhausted file budget, raise coverage.maxFiles (or narrow coverage.testGlobs) in ark.config.json.'),
     entry('INVARIANT_COVERAGE_OUTSIDE_ROOTS', 'arkrules', 'Covering test outside the declared coverage roots', 'The only test naming this invariant sits outside coverage.coverageRoots — the places the project declares its runner executes. ArkGate matches declared text and never executes tests, so it cannot tell whether that file is ever run: coverage there is a test that exists, not a test that runs.', 'Move the test under a declared coverage root, or add its root to coverage.coverageRoots in ark.config.json. Advisory: it never fails strict, but promotion to enforced refuses on it.', { oftenAdvisory: true }),
+    entry('INVARIANT_PROBE_SURVIVED', 'arkrules', 'Covering tests do not pin the invariant', 'The committed invariant probe (.ark/invariant-probe.json, written by arkgate-check --probe-invariants --write) shows, for files that have not changed since, that the covering tests still pass with the invariant\'s symbol broken on purpose (survived) or never call it (not reached). The test names the rule but does not pin it. A status and inventory line only: it never enters the check, so the verdict does not change.', 'Add a test case that fails when the rule is broken (the line names the change that went unnoticed), then re-run arkgate-check --probe-invariants --write and commit the file. Promotion to enforced refuses while the fresh artifact says survived or not reached; a stale, killed, inconclusive or missing result changes nothing.', { oftenAdvisory: true }),
     entry('INVARIANT_TESTS_PATH_MISSING', 'arkrules', 'Domain-invariant tests path missing under adopted', 'The project is adopted (required CI or explicit advisory) and has domain invariants that want test evidence, but ark.config.json does not name where those tests live. Green coverage without a real tests path is an empty checkbox.', 'Add coverage.testGlobs or coverage.coverageRoots in ark.config.json pointing at a real tests folder, then re-run. Adopted mode fails closed until that path is present. Not freezable.'),
     entry('INVARIANT_COVERAGE_ROOTS_MISSING', 'arkrules', 'Coverage roots missing while an invariant is enforced', 'A catalogued domain invariant is enforced, but ark.config.json does not name coverage.coverageRoots — the folders where the project says its test runner actually goes. Without that declaration, INVARIANT_COVERAGE_OUTSIDE_ROOTS cannot fire and coverage can certify a test no runner runs.', 'Add coverage.coverageRoots in ark.config.json pointing at the folder the test runner uses, then re-run. testGlobs alone is not enough. Fail-closed until that path is present. Not freezable.'),
     // ── ArkRun (opt-in extra; RN05 dual-depth nextAction) ────────────────────
@@ -133,6 +138,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     // ── literal path drift ───────────────────────────────────────────────────
     entry('LITERAL_PATH_DRIFT', 'drift', 'Literal path moved by a rename', 'A repo path written inside a string, a comment or a docstring no longer resolves, and the rename set says where it went. Nothing in the gate sees this class: `tsc` resolves imports, not strings, and ESLint does not either, so the rename compiles green and the reference lies afterwards. It appears in four forms — the tsconfig alias, a relative literal, a path written without the include-root prefix, and prose — and a hand sweep reliably covers one of them.', 'Apply the suggested replacement, or re-run `npx arkgate-check --path-drift --base-ref <ref> --write` to apply every writable anchored replacement at once. The rewrite is mechanical and one-directional: the destination comes from the rename, it must itself resolve and be path-shaped, and the token is rewritten in the form the author wrote it in. A destination that leaves the alias root of the literal is reported with the target only and must be rewritten by hand.'),
     entry('LITERAL_PATH_UNRESOLVED', 'drift', 'Literal path does not resolve', 'A literal that looks like a repo path does not resolve under this root, and no rename explains where it went. Unlike LITERAL_PATH_DRIFT this is a candidate, not a verdict: with nothing to anchor it, ArkGate cannot tell a dead reference from an illustrative path in a comment, an example in documentation, or a path belonging to another tree.', 'Read the candidate and decide: fix the path, or leave it. Advisory only — it never fails a run and is never rewritten by --write, because there is no destination to propose. Run `--path-drift --all` to list the sweep.', { oftenAdvisory: true }),
+    entry('ORPHAN_MODULE', 'drift', 'File nothing imports', 'No governed file, test or entry point imports this module. It is the leftover an agent leaves when a rewrite lands next to the old file. Status reads it from the import facts the check already resolved, so it never changes the verdict. When a dynamic import, an unresolved import or an unmapped entry could reach the file, the item says so (maybe-dynamic, maybe-unresolved) and the list is partial.', 'Delete the file through the write gate, one file at a time. If a framework, a script or a runtime loader uses it, add a glob with a reason to .ark/entry-points.json (optional reviewBy) instead. Advisory only — it never fails a run.', { oftenAdvisory: true }),
+    entry('UNUSED_EXPORT', 'drift', 'Export nothing imports by name', 'An export no governed file or test imports by name. Listed only in status details (`--doctor --all`) and the report. Default, namespace, star, dynamic and require use count as using every export, so those files are skipped.', 'Drop the export keyword (or the code) if nothing outside the file needs it, or keep it when it is public API an entry point exposes. Advisory only — it never fails a run.', { oftenAdvisory: true }),
     // ── meta ─────────────────────────────────────────────────────────────────
     entry('ARK_UNKNOWN', 'meta', 'Unknown diagnostic', 'A diagnostic lacked a stable ruleId/code; adapters may emit this fallback so agents never see an empty id.', 'Resolve the underlying finding without weakening ark.config.json, then run Ark again. Prefer fixing the producer to emit a catalogued ruleId.'),
 ]);

package/bin/lib/doctor-advisories.mjs

@@ -19,6 +19,15 @@ import {
 } from './reshape-decisions.mjs';
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
+import {
+  computeOrphanModules,
+  printOrphanModulesCompactLine,
+  printOrphanModulesSection,
+} from './orphan-modules-io.mjs';
+import {
+  computeCrossWallDuplication,
+  printCrossWallDuplicationSection,
+} from './duplication-io.mjs';
 import {
   formatArkRulesDoctorLines,
   summarizeRulesUnderContract,
@@ -143,6 +152,7 @@ export function printCompactExtraDoctorLines(advisories, io) {
     io.line(io.warn, flatMoves[0].evidence);
     if (flatMoves.length > 1) io.line(' ', `${flatMoves.length - 1} more flat-parent suggestion(s) in --doctor --all`);
   }
+  printOrphanModulesCompactLine(advisories?.orphanModules, io);
   const noDomain = advisories?.noDomainFrontend;
   if (noDomain?.ask) {
     console.log('');
@@ -237,8 +247,13 @@ function classificationFromCoverage(cov) {
   };
 }
 
-/** `activeViolations` must already exclude frozen baseline keys (report residual parity). */
-export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts, activeViolations) {
+/**
+ * `activeViolations` must already exclude frozen baseline keys (report residual parity).
+ * `facts.importGraph` is the scan's importer index; `view.details` (Details / report) adds
+ * the unused-exports tier and copies across a wall. `view.changed` (a changed-files scope)
+ * keeps copies across a wall `not-run`.
+ */
+export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts, activeViolations, view = {}) {
   const physicalCohesion = computePhysicalCohesion(root, files);
   const decisionMemory = computeReshapeDecisionMemory(root, files);
   physicalCohesion.reshapeDecisions = decisionMemory.summary;
@@ -325,6 +340,24 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     parseHealth: parseHealth ?? summarizeParseHealth(),
     // Y09 direction: advisory graph-blind spots (template-interpolation); never hard verdict.
     graphBlindSpots: detectGraphBlindSpots(ts, root, files),
+    // ADR 0037: files nothing imports (projection of the resolved import edges; notAScore).
+    orphanModules: computeOrphanModules({
+      root,
+      config: { ...config, rules: rules ?? config?.rules },
+      ts,
+      importGraph: facts?.importGraph,
+      details: view.details === true,
+    }),
+    // ADR 0038: copies across a wall (doctor-time token fingerprints; Details / report only).
+    crossWallDuplication: computeCrossWallDuplication({
+      root,
+      config,
+      rules: rules ?? config?.rules,
+      ts,
+      files: aliasFiles,
+      details: view.details === true,
+      changed: view.changed === true,
+    }),
     // AR12 — Rules under contract (honest counts; real test I/O, never empty-fileContents stub).
     // P1M: pass classification so extraMergeTeeth cannot arm at 0% governed.
     stewardNudge: collectStewardNudge(root, config),
@@ -342,13 +375,24 @@ export function printDoctorAdvisories(advisories, io) {
   printFlatParentPilot(advisories?.flatParentPilot, io);
   const sliceAliases = advisories?.sliceAliases;
   if (sliceAliases && sliceAliases.notAScore === true && Array.isArray(sliceAliases.moves)) {
-    console.log('');
-    console.log(io.color.bold('Slice aliases (owed move)'));
-    io.line(io.warn, sliceAliases.debt);
-    for (const move of sliceAliases.moves) {
-      io.line(io.warn, `${move.from} → ${move.to}. Move these files to ${move.destination}. They are not finished.`);
-      if (move.advisory) io.line(io.warn, move.advisory);
-      for (const file of move.files ?? []) io.line(' ', file);
+    if (sliceAliases.moves.length > 0) {
+      console.log('');
+      console.log(io.color.bold('Slice aliases (owed move)'));
+      io.line(io.warn, sliceAliases.debt);
+      for (const move of sliceAliases.moves) {
+        io.line(io.warn, `${move.from} → ${move.to}. Move these files to ${move.destination}. They are not finished.`);
+        if (move.advisory) io.line(io.warn, move.advisory);
+        for (const file of move.files ?? []) io.line(' ', file);
+      }
+    }
+    if (Array.isArray(sliceAliases.pinned) && sliceAliases.pinned.length > 0) {
+      console.log('');
+      console.log(io.color.bold('Pinned slice aliases'));
+      for (const row of sliceAliases.pinned) {
+        const label = typeof row.reason === 'string' && row.reason.length > 0 ? ` (${row.reason})` : '';
+        io.line(' ', `${row.from} → ${row.to}${label} stays. It is not an owed move.`);
+        for (const file of row.files ?? []) io.line(' ', file);
+      }
     }
   }
   const hubs = advisories?.sharedWalkHubs;
@@ -378,6 +422,8 @@ export function printDoctorAdvisories(advisories, io) {
   printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
   printParseHealthSection(advisories.parseHealth, io);
   printGraphBlindSection(advisories.graphBlindSpots, io);
+  printOrphanModulesSection(advisories.orphanModules, io);
+  printCrossWallDuplicationSection(advisories.crossWallDuplication, io);
   const nudge = advisories.stewardNudge;
   if ((nudge?.needsStewards || nudge?.drift || nudge?.emptyStewardsPastGrace) && nudge.ask) {
     console.log('');

package/bin/lib/doctor-green-cite.mjs

@@ -9,7 +9,7 @@ import { REQUIRED_GATE_WORKFLOW } from './gate-files.mjs';
 import { CI_MERGE_BOUNDARY_REL } from './ci-merge-boundary.mjs';
 
 export const HEALTHY_CLAIM = 'Healthy — nothing to do.';
-export const HEALTHY_KEEP = '  Keep write path + CI.';
+const HEALTHY_KEEP = '  Keep write path + CI.';
 export const UNCITE_SUFFIX =
   'not green until a file, config key, or test is named';
 

package/bin/lib/doctor-human.mjs

@@ -169,7 +169,7 @@ export function printDoctorCompactHuman(view) {
       adrPresence: view.adrPresence,
       statesTransitions: view.statesTransitions, statusTransitionCatalog: view.statusTransitionCatalog, noDomainFrontend: view.noDomainFrontend, invariantTestsPath: view.invariantTestsPath, invariantCoverageRoots: view.invariantCoverageRoots,
     },
-    { line, warn }
+    { line, warn, color }
   );
 
   if (violations.length === 0) {