arkgate 4.8.3 → 4.8.4

package/bin/lib/architecture-scan.mjs

@@ -12,6 +12,7 @@ import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { resolveCandidateFacts } from './resolved-candidate-facts.mjs';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import {
+  coverageOptionsFromConfig,
   invariantIdsFromCatalog,
   loadInvariantCoverageInputs,
 } from './invariant-coverage-io.mjs';
@@ -72,6 +73,7 @@ export function resolveArchitectureSnapshot({
   const coverageInputs = hasInvariants
     ? loadInvariantCoverageInputs(root, facts, {
         invariantIds: invariantIdsFromCatalog(arkRulesLoad.arkRules),
+        ...coverageOptionsFromConfig(effectiveConfig),
       })
     : undefined;
   // AR07: Tooling fileHints for orchestration-only / thin-adapter (reuse coverage contents when present).

package/bin/lib/arkrules-contract.mjs

@@ -251,9 +251,16 @@ function validateSemantics(candidate, issues) {
         if (typeof entry.sensor === 'string' &&
             isTier2Sensor(entry.sensor) &&
             entry.mode === 'enforced') {
+            // Name the rule the AUTHOR wrote, not only the sensor it delegates to.
+            // A rule called "types-only" on `no-anemic-model` used to be refused with
+            // an error naming an id that appears nowhere in the author's file, and
+            // finding the connection cost a full run each time. `--sensors` reports
+            // the same fact before the attempt.
             issues.push({
                 path: `$.structure[${index}].mode`,
-                message: `sensor ${JSON.stringify(entry.sensor)} is Tier-2 advisory-only and cannot be enforced`,
+                message: `${id ? `rule ${JSON.stringify(id)} uses sensor ` : 'sensor '}` +
+                    `${JSON.stringify(entry.sensor)}, which is Tier-2 advisory-only and cannot be enforced` +
+                    `${id ? ' (arkgate-check --sensors lists which sensors can)' : ''}`,
             });
         }
         if (Array.isArray(entry.appliesTo) && entry.appliesTo.length === 0) {

package/bin/lib/check-args.mjs

@@ -51,6 +51,10 @@ export function parseArgs(argv) {
     migrateCommands: false,
     doctor: false,
     plan: false,
+    pathDrift: false,
+    sensors: false,
+    promote: undefined,
+    apply: false,
     recommend: false,
     writePlan: false,
     listPolicyPacks: false,
@@ -112,6 +116,24 @@ export function parseArgs(argv) {
     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 === '--path-drift') args.pathDrift = true;
+    else if (arg === '--sensors') args.sensors = true;
+    else if (arg === '--promote' || arg.startsWith('--promote=')) {
+      // Optional value, same shape as --report / --baseline: bare --promote
+      // previews every declared rule from ONE run, which is the point (the loop
+      // it replaces was one full run per attempted promotion); a value narrows
+      // to that rule id.
+      // `--promote=<id>` too: a rule id may legally begin with '-', and the
+      // lookahead form can never pass one.
+      const eq = arg.indexOf('=');
+      if (eq > 0) {
+        args.promote = arg.slice(eq + 1);
+      } else {
+        const next = argv[i + 1];
+        args.promote = next && !next.startsWith('-') ? argv[++i] : true;
+      }
+    }
+    else if (arg === '--apply') args.apply = 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;
@@ -170,5 +192,49 @@ export function parseArgs(argv) {
     else if (arg === '--version' || arg === '-V') args.version = true;
     else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
   }
+  // A write flag that silently does nothing is how a caller comes to believe a
+  // change landed. --apply belongs to --promote; the other write surfaces use
+  // --write.
+  if (args.apply && !args.promote) {
+    throw new Error(
+      '--apply applies to --promote. Run `arkgate-check --promote <ruleId> --apply`; the other write surfaces use --write.'
+    );
+  }
+  // Every report mode below returns from main() BEFORE --promote is reached, so
+  // pairing one with --promote --apply printed that report and exited 0 having
+  // written nothing. Same defect the guard above exists for, one level up.
+  if (args.promote) {
+    const shadowing = [
+      args.sensors && '--sensors',
+      args.pathDrift && '--path-drift',
+      args.coverage && '--coverage',
+      args.recommend && '--recommend',
+      args.doctor && '--doctor',
+      args.plan && '--plan',
+      args.rulesInventory && '--rules-inventory',
+      args.suggestInclude && '--suggest-include',
+      args.adoptContract && '--adopt-contract',
+      args.migrateContract && '--migrate-contract',
+    ].filter(Boolean);
+    if (shadowing.length > 0) {
+      throw new Error(
+        `--promote cannot be combined with ${shadowing.join(', ')}: that mode answers first and --promote would silently do nothing. Run them separately.`
+      );
+    }
+    // A narrowed scope cannot price a promotion. --changed counts findings over
+    // the changed files only and --baseline suppresses findings AFTER --promote
+    // has already returned, so either one turns the cost into an undercount
+    // printed as a fact.
+    const narrowing = [
+      args.changed && '--changed',
+      args.against && '--against',
+      args.baseline && '--baseline',
+    ].filter(Boolean);
+    if (narrowing.length > 0) {
+      throw new Error(
+        `--promote cannot be combined with ${narrowing.join(', ')}: the promotion cost must be measured over the whole governed tree, and a narrowed or baselined scope would report an undercount as the price.`
+      );
+    }
+  }
   return args;
 }

package/bin/lib/config-contract.mjs

@@ -105,6 +105,8 @@ export const ARK_CONFIG_SCHEMA = {
                 allowDisabledPeerIsolation: false,
             },
         },
+        /** Invariant-coverage scan controls (test globs + file budget). Absence keeps defaults. */
+        coverage: { $ref: '#/$defs/coverage' },
         /** ADR 0012 — layer name → relative path to arkrules/<Layer>.json */
         arkRules: {
             type: 'object',
@@ -172,6 +174,20 @@ export const ARK_CONFIG_SCHEMA = {
                 message: { type: 'string', minLength: 1 },
                 peerIsolation: { type: 'boolean' },
                 sliceFolders: { ...stringArraySchema, minItems: 1 },
+                sharedRoots: { ...stringArraySchema, minItems: 1 },
+                allowedCrossSlice: {
+                    type: 'array',
+                    minItems: 1,
+                    items: {
+                        type: 'object',
+                        additionalProperties: false,
+                        required: ['from', 'to'],
+                        properties: {
+                            from: { type: 'string', minLength: 1 },
+                            to: { type: 'string', minLength: 1 },
+                        },
+                    },
+                },
             },
         },
         safety: {
@@ -184,6 +200,16 @@ export const ARK_CONFIG_SCHEMA = {
                 allowDisabledPeerIsolation: { type: 'boolean', default: false },
             },
         },
+        coverage: {
+            type: 'object',
+            additionalProperties: false,
+            description: 'Invariant coverage scan controls. testGlobs replaces the built-in test-name heuristic; maxFiles raises or lowers the evidence file budget; coverageRoots declares where the project runs its tests, so a covering test found outside them is reported instead of silently certifying an invariant.',
+            properties: {
+                testGlobs: { ...stringArraySchema, minItems: 1 },
+                maxFiles: { type: 'integer', minimum: 1 },
+                coverageRoots: { ...stringArraySchema, minItems: 1 },
+            },
+        },
         arkRun: ARK_RUN_SCHEMA_DEF,
         arkOrder: ARK_ORDER_SCHEMA_DEF,
     },

package/bin/lib/design-smells.mjs

@@ -490,6 +490,91 @@ export function summarizeDesignFitness(smells, ctx = {}) {
   };
 }
 
+/** How many smell ids the green-run pointer names before it counts the rest. */
+export const GREEN_PLAN_POINTER_MAX_IDS = 4;
+
+/**
+ * Name `--plan` on a run that passed.
+ *
+ * `--plan` is where the design bets live, and a green run never pointed at it:
+ * a whole adopter session went by without opening it, because `✔ Ark check
+ * passed` reads as *finished*. Clean import edges are not a settled design, and
+ * the summary was saying only the first half of what the run already knows.
+ *
+ * Report only, and deliberately quiet. Its weakness test is `isDesignWeak` with
+ * the **blocking** violation count, the same input doctor uses, so the two
+ * surfaces can never disagree about `designWeak`. It never changes the exit
+ * code, and it stays silent when there is nothing behind the pass — a line that
+ * always prints is a line nobody reads. The caller passes the runner-correct
+ * command so this stays pure.
+ *
+ * A baselined run is not a clean run: violations suppressed by the ratchet are
+ * still violations, and the summary line directly above says so. The opening
+ * clause reports which of the two it is.
+ *
+ * @param {DesignSmell[]} smells
+ * @param {{ blockingViolations?: number, governedPercent?: number|null, totalFiles?: number|null, suppressedCount?: number }} ctx
+ * @param {string} planCommand
+ * @returns {string | null}
+ */
+export function formatGreenPlanPointer(smells, ctx = {}, planCommand = 'ark-check --plan') {
+  const weak = isDesignWeak(smells, {
+    activeViolations: ctx.blockingViolations ?? 0,
+    governedPercent: ctx.governedPercent ?? null,
+    totalFiles: ctx.totalFiles ?? null,
+  });
+  if (!weak) return null;
+  const ids = [...new Set((smells || []).map((smell) => smell?.id).filter(Boolean))].sort();
+  if (ids.length === 0) return null;
+  const shown = ids.slice(0, GREEN_PLAN_POINTER_MAX_IDS);
+  const hidden = ids.length - shown.length;
+  const named = hidden > 0 ? `${shown.join(', ')}, +${hidden} more` : shown.join(', ');
+  const plural = ids.length === 1 ? '' : 's';
+  const suppressed = ctx.suppressedCount ?? 0;
+  const opening =
+    suppressed > 0
+      ? `No blocking import-rule violations (${suppressed} suppressed by baseline)`
+      : 'Import rules are clean';
+  return (
+    `${opening}; the design bets are not settled — ${ids.length} design smell${plural} ` +
+    `(${named}). They never fail this check: ${planCommand}`
+  );
+}
+
+/**
+ * The same pointer, composed against the tree the run just analyzed.
+ *
+ * Kept here rather than in the CLI entry: the smell scan is filesystem work and
+ * `bin/ark-check-runtime.mjs` is orchestration under a line budget. A failure
+ * is swallowed on purpose — a discoverability hint must never change the
+ * outcome of a green run — but it is not silent under `ARK_DEBUG`, or a
+ * refactor could leave this permanently dead with no signal anywhere.
+ *
+ * @param {{ root: string, config: object, files: string[], coverage: object|null,
+ *           blockingViolations: number, suppressedCount?: number, planCommand: string }} options
+ * @returns {string | null}
+ */
+export function greenPlanPointer(options) {
+  try {
+    const { root, config, files, coverage } = options;
+    return formatGreenPlanPointer(
+      detectDesignSmells(root, config, files, coverage),
+      {
+        blockingViolations: options.blockingViolations,
+        governedPercent: coverage?.governed?.percent ?? null,
+        totalFiles: coverage?.totalFiles ?? null,
+        suppressedCount: options.suppressedCount ?? 0,
+      },
+      options.planCommand
+    );
+  } catch (error) {
+    if (process.env.ARK_DEBUG === '1') {
+      console.error(`[ark-check] green --plan pointer skipped: ${error?.message ?? error}`);
+    }
+    return null;
+  }
+}
+
 /**
  * Build plan-B pattern bets from smells (P03). Never mechanical-safe.
  *

package/bin/lib/diagnostic-catalog.mjs

@@ -55,7 +55,8 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('ARKRULE_STRUCTURE', 'arkrules', 'ArkRule structure sensor failed', 'An opt-in ArkRules structure sensor (private state, factory shape, event publish, persistence write outside an aggregate, …) failed on a governed file for a declared arkruleId.', 'Restore the declared structure for the ArkRule (see arkruleSource), then preflight again. Do not demote the rule without a hash-bound policy acknowledgement.'),
     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('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.'),
+    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 }),
     // ── ArkRun (opt-in extra; RN05 dual-depth nextAction) ────────────────────
     entry('ARKRUN_MISSING_ROOT', 'arkrun', 'No kernel factory in composition roots', 'The ArkRun extra is on but no createArkKernel / createStrictArkKernel / createArkKernelFromConfig / createStrictArkKernelFromConfig factory was found in arkRun.compositionRoots, so agents can skip the kernel while the write gate stays green.', 'Import createStrictArkKernel from arkgate/runtime (same npm package; @arkgate/runtime is deprecated) and call it in a composition root listed in arkRun.compositionRoots, then preflight again. Never mechanical-safe — factory placement is a design decision.'),
     entry('ARKRUN_KERNEL_IN_DOMAIN', 'arkrun', 'Domain-role layer imports the kernel', 'A Domain-role layer imports arkgate/runtime, @arkgate/runtime, or kernel types. Domain stays kernel-free; composition roots and adapters own the factory.', 'Move the kernel import out of the Domain-role layer into a composition root or adapter. Import from arkgate/runtime (same npm package; @arkgate/runtime is deprecated), then preflight again. Never mechanical-safe.'),
@@ -85,6 +86,7 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     // ── analysis completeness / host ─────────────────────────────────────────
     entry('ANALYSIS_PARSE_INCOMPLETE', 'analysis', 'Parse incomplete', 'Governed source could not be fully parsed; evidence includes the TypeScript diagnostic (line + message). Incremental mid-edit parse is normal for agents. Contract exclude paths skip the write hook.', 'Finish the source or fix the reported syntax error, then re-run `npx arkgate-check`. The write hook does not deny solely on mid-edit parse. Partial never means pass.'),
     entry('LEXICAL_EVIDENCE_INCOMPLETE', 'analysis', 'Lexical evidence incomplete', 'Single-file validation cannot prove project module resolution. The write hook is already the verdict.', 'Re-run `npx arkgate-check --root . --config ark.config.json`, or treat the hook deny as final. Do not call ark_prepare_change from a hook deny.'),
+    entry('ANALYSIS_COVERS_NO_FILES', 'analysis', 'Analysis covered no files', 'No file matched the contract include and layer patterns under the analyzed root, so the run had nothing to check. Every rule is vacuously satisfied on an empty set: a green here would read exactly like a green over a governed tree while certifying nothing. Usual causes are a --root that is not the tree the contract describes (including a contract found outside the requested root, whose directory is then adopted as the project root), include / exclude patterns that match nothing, or layer patterns written for a different layout.', 'Point --root at the tree the contract describes, or keep the contract inside that tree, or fix the include / exclude / layer patterns so they match real files — then re-run `npx arkgate-check --root . --config ark.config.json`. This is a refusal about ArkGate\u2019s own inputs, not a finding about your code; no baseline or policy acknowledgement can suppress it.'),
     entry('ANALYSIS_HOST_UNAVAILABLE', 'analysis', 'Analysis host unavailable', 'No usable TypeScript / analysis host was available for this invocation.', 'Install a supported TypeScript version visible to the project, then re-run. Unavailable analysis is fail-closed.'),
     entry('ADAPTER_NOT_ALLOWED_FOR_PORT', 'adapter', 'Adapter not allowed for port', 'Runtime/port wiring selected an adapter implementation that the architecture profile does not allow for that port.', 'Bind an allowed adapter for the port, or adjust the profile with an explicit policy decision — then re-run.'),
     // ── AI snippet gate policy surface ───────────────────────────────────────
@@ -109,6 +111,9 @@ export const DIAGNOSTIC_CATALOG = Object.freeze([
     entry('CONFIG_RULE_UNKNOWN_TO_LAYER', 'config', 'Rule unknown to layer', 'A dependency rule references a target layer name that is not declared.', 'Fix the rule’s to field to a declared layer name.', { oftenAdvisory: true }),
     entry('CONFIG_AMBIGUOUS_LAYERS', 'config', 'Ambiguous layer classification', 'Some files match multiple layers at equal specificity; classification falls back to declaration order.', 'Disambiguate overlapping patterns so each file has one clear layer owner.', { oftenAdvisory: true }),
     entry('CONFIG_UNCLASSIFIED_FILES', 'config', 'Unclassified included files', 'Included source files match no layer pattern; import rules will not enforce on them.', 'Extend layer patterns or narrow include so every governed file is classified.', { oftenAdvisory: true }),
+    // ── 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 }),
     // ── 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/first-run-help.mjs

@@ -117,6 +117,18 @@ export function checkUsageAll() {
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
+    '       ark-check --path-drift [--base-ref <git-ref>] [--all] [--json] [--write]',
+    '           literal path drift: repo paths inside strings, comments and docstrings that no longer resolve.',
+    '           Anchored on the rename set vs --base-ref, so each finding carries a replacement; --write applies them.',
+    '           --all adds the unanchored advisory sweep (candidates, not a verdict; never written).',
+    '           Exit 0 ran and clean, 1 drift remains, 2 could not run (no usable base ref).',
+    '       ark-check --sensors [--json]           every sensor with its tier and whether it can EVER be enforced, plus every declared rule',
+    '           with its local id, the sensor it delegates to, its source file, its mode and why it can or cannot be promoted.',
+    '           Contract + coverage-evidence only: no TypeScript, no analysis. Exit 0 on a report, 2 if the contract will not load.',
+    '       ark-check --promote [<ruleId>] [--json] [--apply]',
+    '           what enforcing would cost: the findings each advisory rule already produces, from ONE run rather than one run per attempt.',
+    '           Plan by default; --promote <ruleId> --apply (or --promote=<ruleId>) writes mode "enforced" into the ArkRules file that declares it.',
+    '           A cost the run could not measure (incomplete analysis, classification floor) is named and --apply refuses. Exit 0 / 1 refused / 2 bad args.',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
     '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',

package/bin/lib/invariant-coverage-io.mjs

@@ -9,10 +9,20 @@ import path from 'node:path';
 const DEFAULT_TEST_NAME_RE =
   /\.(test|spec)\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$|\/__tests__\/|\/tests?\//i;
 
-/** Max files to load for coverage evidence (budget). */
-const MAX_COVERAGE_FILES = 400;
+/** Default max files to load for coverage evidence (budget). Config: `coverage.maxFiles`. */
+export const DEFAULT_MAX_COVERAGE_FILES = 400;
+/**
+ * Hard ceiling on `coverage.maxFiles`. The config validator implements no
+ * `maximum` keyword for integers, so a schema bound would be accepted and then
+ * silently ignored — the clamp here is the only real enforcement. Retained
+ * files are held in memory at up to MAX_FILE_BYTES each, so an unbounded cap is
+ * an unbounded heap.
+ */
+export const MAX_COVERAGE_FILES_CAP = 20_000;
 /** Max bytes per file when reading for title/symbol mining. */
 const MAX_FILE_BYTES = 256 * 1024;
+/** Max directory depth for the test walk. Deeper directories are counted, not silent. */
+const MAX_WALK_DEPTH = 8;
 
 /**
  * True when absolute is root or a file under root (separator-safe).
@@ -62,6 +72,30 @@ function matchSimpleGlob(glob, file) {
   return new RegExp(`^${out}$`).test(target);
 }
 
+/**
+ * Coverage scan options carried by ark.config.json (`coverage`).
+ * Absent config → `{}`: the built-in heuristic and default budget stay in force.
+ * @param {{ coverage?: { testGlobs?: unknown, maxFiles?: unknown, coverageRoots?: unknown } } | null | undefined} config
+ * @returns {{ testGlobs?: string[], maxFiles?: number, coverageRoots?: string[] }}
+ */
+export function coverageOptionsFromConfig(config) {
+  const coverage = config?.coverage;
+  if (!coverage || typeof coverage !== 'object') return {};
+  const options = {};
+  if (Array.isArray(coverage.testGlobs)) {
+    const globs = coverage.testGlobs.filter((g) => typeof g === 'string' && g.length > 0);
+    if (globs.length > 0) options.testGlobs = globs;
+  }
+  if (Number.isInteger(coverage.maxFiles) && coverage.maxFiles > 0) {
+    options.maxFiles = Math.min(coverage.maxFiles, MAX_COVERAGE_FILES_CAP);
+  }
+  if (Array.isArray(coverage.coverageRoots)) {
+    const roots = coverage.coverageRoots.filter((r) => typeof r === 'string' && r.length > 0);
+    if (roots.length > 0) options.coverageRoots = roots;
+  }
+  return options;
+}
+
 /**
  * Declared invariant ids from an Effective catalog. Empty when the extra is off.
  * @param {{ invariants?: Array<{ id?: unknown }> } | null | undefined} arkRules
@@ -76,18 +110,65 @@ export function invariantIdsFromCatalog(arkRules) {
 /**
  * @param {string} root
  * @param {{ files?: Array<{ path: string }> }} facts
- * @param {{ testGlobs?: string[], invariantIds?: string[] }} [opts]
+ * @param {{ testGlobs?: string[], invariantIds?: string[], maxFiles?: number, coverageRoots?: string[] }} [opts]
  * @returns {{
  *   fileContents: Record<string, string>,
  *   testFiles: string[],
  *   testGlobsMissing: boolean,
  *   coverageBudgetExhausted: boolean,
+ *   coverageRoots?: string[],
+ *   stats: {
+ *     filesRead: number,
+ *     filesLoaded: number,
+ *     testFilesRetained: number,
+ *     maxFiles: number,
+ *     discarded: {
+ *       budget: number,
+ *       noInvariantMention: number,
+ *       oversize: number,
+ *       unreadable: number,
+ *       depthLimited: number,
+ *       outOfRoot: number,
+ *     },
+ *   },
  * }}
  */
 export function loadInvariantCoverageInputs(root, facts, opts = {}) {
   const fileContents = {};
   const testFiles = [];
   const seen = new Set();
+  // Every path pushFile has already judged, retained or not. `seen` holds only
+  // what was retained, so without this the walk roots overlap ('.' contains
+  // 'tests' and 'src') and one discarded file is counted — and read — once per
+  // overlapping root. The numbers we print must count files, not visits.
+  const offered = new Set();
+  const maxFiles =
+    Number.isInteger(opts.maxFiles) && opts.maxFiles > 0
+      ? Math.min(opts.maxFiles, MAX_COVERAGE_FILES_CAP)
+      : DEFAULT_MAX_COVERAGE_FILES;
+  // Reads, not retentions. A test is read before it can be judged for naming an
+  // invariant, so the budget bounds what we KEEP, not what we open. Reporting
+  // only the retained count made maxFiles look like an I/O knob it is not.
+  let filesRead = 0;
+  // Every discard is counted. A file dropped without a number is a coverage
+  // verdict the user cannot explain.
+  const discarded = {
+    budget: 0,
+    noInvariantMention: 0,
+    oversize: 0,
+    unreadable: 0,
+    depthLimited: 0,
+    outOfRoot: 0,
+  };
+  // Root with every symlink resolved, computed once: the containment test for
+  // symlinked candidates compares resolved path to resolved root.
+  let realRoot = root;
+  try {
+    realRoot = fs.realpathSync.native(root);
+  } catch {
+    // Unresolvable root: fall back to the literal path rather than failing the
+    // whole scan. Containment is then as strict as it was before.
+  }
   // Declared invariant ids. When present, a test file is RETAINED only if it
   // mentions one: scanning is cheap (hundreds of small files), retaining is
   // what costs memory. Without this the budget goes to whichever N tests the
@@ -112,31 +193,61 @@ export function loadInvariantCoverageInputs(root, facts, opts = {}) {
     const rel = String(relPath || '')
       .replace(/\\/g, '/')
       .replace(/^\.\//, '');
-    if (!rel || seen.has(rel) || seen.size >= MAX_COVERAGE_FILES) return;
+    if (!rel || offered.has(rel)) return;
+    offered.add(rel);
     const absolute = path.resolve(root, rel);
     if (!isPathInsideRoot(root, absolute)) return;
     try {
       const stat = fs.statSync(absolute);
-      if (!stat.isFile() || stat.size > MAX_FILE_BYTES) return;
+      // Not a file (directory, socket, symlink to a directory): never a
+      // coverage candidate, so it is not a discard either.
+      if (!stat.isFile()) return;
+      // statSync followed the link. A symlink that leaves the root must not
+      // become evidence: an out-of-root file naming an invariant would forge
+      // coverage for a test that is not in this repo. Compared against the
+      // resolved root so a repo living under a symlinked prefix (macOS /tmp)
+      // is not mistaken for an escape. Counted, never silent.
+      if (!isPathInsideRoot(realRoot, fs.realpathSync.native(absolute))) {
+        discarded.outOfRoot += 1;
+        return;
+      }
+      if (stat.size > MAX_FILE_BYTES) {
+        discarded.oversize += 1;
+        return;
+      }
+      // The budget bounds candidates, not visits: a directory or an
+      // out-of-root path was never going to be evidence, so counting it as a
+      // budget casualty would send the user to raise a cap that was not the
+      // reason. Checked here so a file past the cap is never read either.
+      if (seen.size >= maxFiles) {
+        discarded.budget += 1;
+        return;
+      }
       const content = fs.readFileSync(absolute, 'utf8');
+      filesRead += 1;
       const asTest = forceAsTest || isTestPath(rel);
       // A test that names no invariant is evidence of nothing: scan it, drop
       // it, and let it cost no budget.
-      if (asTest && !mentionsInvariant(content)) return;
+      if (asTest && !mentionsInvariant(content)) {
+        discarded.noInvariantMention += 1;
+        return;
+      }
       seen.add(rel);
       fileContents[rel] = content;
       if (asTest) testFiles.push(rel);
     } catch {
-      // skip unreadable
+      // Unreadable (permissions, broken symlink, file moved mid-scan): counted,
+      // never dropped in silence.
+      discarded.unreadable += 1;
     }
   };
 
   // Tests FIRST, then production files.
   //
-  // The order is load-bearing, not stylistic. `pushFile` stops at
-  // MAX_COVERAGE_FILES, and a real repo has far more production files than the
-  // budget — so walking facts first consumed the whole budget and the test walk
-  // pushed nothing. Coverage then reported `testGlobsMissing: true`, which the
+  // The order is load-bearing, not stylistic. `pushFile` stops at the file
+  // budget (`coverage.maxFiles`, default 400), and a real repo has far more
+  // production files than the budget — so walking facts first consumed the
+  // whole budget and the test walk pushed nothing. Coverage then reported `testGlobsMissing: true`, which the
   // caller renders as "never-had-tests": a claim about the USER's repo that was
   // actually about our own budget. Measured on a 4511-file project: every
   // invariant reported uncovered while its test sat on disk with the invariant
@@ -145,24 +256,59 @@ export function loadInvariantCoverageInputs(root, facts, opts = {}) {
   const testWalkRoots = useCustomGlobs
     ? ['.', 'tests', 'test', 'src', '__tests__', 'spec']
     : ['tests', 'test', 'src', '__tests__'];
+  // Directories, deduplicated across overlapping walk roots. '.' contains
+  // 'tests' and 'src', so the same directory is offered to the walk more than
+  // once: counting each visit would report N subtrees where one exists. And a
+  // directory refused at depth under one root may be entered from a nearer
+  // root, so 'depth-limited' is only the ones NO walk ever entered.
+  const dirs = { walked: new Set(), depthLimited: new Set(), unreadable: new Set() };
   for (const dir of testWalkRoots) {
     const absDir = path.join(root, dir === '.' ? '' : dir);
     if (!fs.existsSync(absDir)) continue;
-    walkTestFiles(absDir, root, (rel) => {
-      if (isTestPath(rel)) pushFile(rel, true);
-    });
+    walkTestFiles(
+      absDir,
+      root,
+      (rel) => {
+        if (isTestPath(rel)) pushFile(rel, true);
+      },
+      0,
+      dirs
+    );
+  }
+  for (const dir of dirs.depthLimited) {
+    if (!dirs.walked.has(dir)) discarded.depthLimited += 1;
+  }
+  for (const dir of dirs.unreadable) {
+    if (!dirs.walked.has(dir)) discarded.unreadable += 1;
   }
 
   for (const file of facts?.files ?? []) {
     if (file?.path) pushFile(file.path);
   }
 
+  // Echoed, not applied here: the roots are a declaration Domain compares the
+  // scan against. Tooling filtering by them would hide the disagreement that is
+  // the whole point of the declaration.
+  const coverageRoots = Array.isArray(opts.coverageRoots)
+    ? opts.coverageRoots.filter((r) => typeof r === 'string' && r.length > 0)
+    : [];
   const testGlobsMissing = testFiles.length === 0;
   return {
     fileContents,
     testFiles,
     testGlobsMissing,
-    coverageBudgetExhausted: seen.size >= MAX_COVERAGE_FILES,
+    ...(coverageRoots.length > 0 ? { coverageRoots } : {}),
+    // Exhausted means the cap actually cost the user a file. Landing exactly
+    // on the cap with nothing dropped is a full budget, not an exhausted one:
+    // reporting it would tell the user to raise a cap that discarded nothing.
+    coverageBudgetExhausted: discarded.budget > 0,
+    stats: {
+      filesRead,
+      filesLoaded: seen.size,
+      testFilesRetained: testFiles.length,
+      maxFiles,
+      discarded,
+    },
   };
 }
 
@@ -171,23 +317,33 @@ export function loadInvariantCoverageInputs(root, facts, opts = {}) {
  * @param {string} root
  * @param {(rel: string) => void} onFile
  * @param {number} [depth]
+ * @param {{ walked: Set<string>, depthLimited: Set<string>, unreadable: Set<string> }} [dirs]
  */
-function walkTestFiles(dir, root, onFile, depth = 0) {
-  if (depth > 8) return;
+function walkTestFiles(dir, root, onFile, depth = 0, dirs) {
+  if (depth > MAX_WALK_DEPTH) {
+    // The whole subtree is dropped here. Recorded by path, not counted: a
+    // nearer walk root may still reach it within the depth limit.
+    if (dirs) dirs.depthLimited.add(dir);
+    return;
+  }
   let entries;
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
   } catch {
+    if (dirs) dirs.unreadable.add(dir);
     return;
   }
+  if (dirs) dirs.walked.add(dir);
   for (const entry of entries) {
     if (entry.name === 'node_modules' || entry.name === 'dist' || entry.name === '.git') continue;
     const absolute = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      walkTestFiles(absolute, root, onFile, depth + 1);
+      walkTestFiles(absolute, root, onFile, depth + 1, dirs);
       continue;
     }
-    if (!entry.isFile()) continue;
+    // Symlinks are candidates too: pushFile stats through them, so a broken one
+    // is counted as unreadable instead of vanishing from the walk.
+    if (!entry.isFile() && !entry.isSymbolicLink()) continue;
     const rel = path.relative(root, absolute).replace(/\\/g, '/');
     onFile(rel);
   }