arkgate 4.8.2 → 4.8.4

package/bin/ark-check-runtime.mjs

@@ -97,10 +97,20 @@ import {
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
 import { checkUsage, checkUsageAll } from './lib/first-run-help.mjs';
 import { createAdapterResult } from './lib/adapter-contract.mjs';
-import { collectGovernedFiles, normalize, walk } from './lib/scan-files.mjs';
+import {
+  UNGOVERNED_PROBE_CAP,
+  collectGovernedFiles,
+  countUngovernedSourceFiles,
+  normalize,
+  walk,
+} from './lib/scan-files.mjs';
 import { configWarning } from './lib/config-warnings.mjs';
 import { runArchitectureScan } from './lib/architecture-scan.mjs';
-import { ANALYSIS_COMPLETENESS, analysisIncompleteStatement } from './lib/analysis-completeness.mjs';
+import {
+  ANALYSIS_COMPLETENESS,
+  analysisIncompleteStatement,
+  emptyAnalysisRefusal,
+} from './lib/analysis-completeness.mjs';
 import { reportUnavailableAnalysis } from './lib/unavailable-analysis.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
 import {
@@ -574,6 +584,201 @@ function runAdoptContract(args) {
   }
 }
 
+/**
+ * Literal path drift (LPD) — repo paths that live inside strings, comments and
+ * docstrings, and no longer resolve.
+ *
+ * `tsc` resolves imports, not strings, and ESLint does not either, so this
+ * whole class compiles green. Report only by default (house convention:
+ * plan-by-default, `--write` to mutate) and only the ANCHORED findings are ever
+ * written — an unanchored one has no destination to propose.
+ */
+async function runPathDrift(args) {
+  const root = args.root;
+  const { scanLiteralPathDrift, writeLiteralPathDrift } = await import(
+    './lib/literal-path-drift-io.mjs'
+  );
+  let config;
+  try {
+    config = readConfig(root, args.config);
+  } catch {
+    // The scan reads text, not the contract's rules: a contract too broken to
+    // parse must not hide the drift. `include` only widens the roots.
+    config = { include: ['src'] };
+  }
+  const baseRef = resolveDesignDeltaBaseRef(root, args.baseRef);
+  const report = scanLiteralPathDrift(root, config, { baseRef, tsconfig: args.tsconfig });
+  const written = args.write ? writeLiteralPathDrift(root, report.anchored) : null;
+  // After a write the findings that were applied no longer exist on disk, so
+  // reporting them as findings would describe a tree that is already gone.
+  const remainingAnchored = written
+    ? report.anchored.filter((finding) => !wasApplied(finding, written))
+    : report.anchored;
+  // Both sinks describe the tree as it now stands: after a write the applied
+  // findings are gone from disk, and printing them as findings would contradict
+  // the "wrote ..." lines directly underneath.
+  const shown = { ...report, anchored: remainingAnchored };
+
+  // The unanchored sweep is opt-in (`--all`). On a repo that WRITES about paths
+  // it produced 4085 candidates out of 9536 literals, almost all of them
+  // illustrative paths in prose and help text — that is ArkGate's inability to
+  // resolve a string reported as a fact about the user's code, the same defect
+  // class as the coverage budget. The count is always printed, so opting out of
+  // the list is never opting out of knowing.
+  const payload = {
+    ...report,
+    anchored: remainingAnchored,
+    unanchoredCount: report.unanchoredCount,
+    unanchored: args.all ? report.unanchored : [],
+    unanchoredListed: args.all,
+  };
+  if (args.json) {
+    console.log(JSON.stringify({ pathDrift: payload, ...(written ? { written } : {}) }, null, 2));
+  } else {
+    printPathDrift(root, args, shown, written);
+  }
+  // Anchored drift is a fact about the tree: the source is gone and a rename
+  // says where it went. Unanchored drift is advisory — ArkGate cannot tell a
+  // dead reference from one it simply cannot resolve.
+  // Three outcomes, and CI must be able to tell them apart from the exit code
+  // alone — a tick the terminal withholds is no use to a pipeline that only
+  // reads the status:
+  //   0  anchored mode ran and found nothing left
+  //   1  anchored drift remains
+  //   2  anchored mode could not run (no usable base ref) — this run proved
+  //      nothing, and exiting 0 here would be the false green one level down.
+  if (!report.renameSet.available) process.exitCode = 2;
+  else process.exitCode = remainingAnchored.length > 0 ? 1 : 0;
+}
+
+/**
+ * True when THIS finding was one of the replacements written.
+ *
+ * Matched by identity, not by file: a file holding two findings where only one
+ * still matched its token must keep the other one in the remaining set.
+ */
+function wasApplied(finding, written) {
+  const entry = written.written.find((row) => row.file === finding.file);
+  if (!entry) return false;
+  return (entry.appliedFindings ?? []).some(
+    (applied) =>
+      applied.line === finding.line &&
+      applied.column === finding.column &&
+      applied.token === finding.token
+  );
+}
+
+/**
+ * A path from git or from the filesystem is raw bytes, and it is about to be
+ * printed to a terminal. A control character there can repaint or erase the
+ * findings above it.
+ */
+function renderPath(value) {
+  return String(value).replace(/[\u0000-\u001f\u007f]/g, (ch) =>
+    `\\u${ch.charCodeAt(0).toString(16).padStart(4, '0')}`
+  );
+}
+
+function printPathDrift(root, args, report, written) {
+  console.log(color.bold('Literal path drift'));
+  console.log(
+    color.dim(
+      `  scanned ${report.scannedFiles} text file(s), ${report.candidates} path-shaped literal(s)`
+    )
+  );
+  if (!report.renameSet.available) {
+    console.log(
+      color.yellow(
+        `  No rename set (${report.renameSet.reason}) — anchored mode is OFF, so nothing below carries a suggested replacement. Pass --base-ref <git-ref> to enable it.`
+      )
+    );
+  } else {
+    console.log(
+      color.dim(
+        `  rename set vs ${report.baseRef}: ${report.renameSet.renames} rename(s), ${report.anchorsConsidered} usable anchor(s)`
+      )
+    );
+  }
+  if (report.ambiguousAnchors.length > 0) {
+    console.log(
+      color.dim(
+        `  ${report.ambiguousAnchors.length} rename source(s) map to more than one destination and anchor nothing (e.g. ${renderPath(report.ambiguousAnchors[0])})`
+      )
+    );
+  }
+  const discarded = report.scan.discarded;
+  const dropped = Object.values(discarded).reduce((sum, n) => sum + n, 0);
+  if (dropped > 0) {
+    console.log(
+      color.dim(
+        `  not read: ${discarded.generated} generated, ${discarded.oversize} oversize, ${discarded.budget} past the ${report.scan.maxFiles}-file budget, ${discarded.byteBudget} past the ${Math.round(report.scan.maxTotalBytes / (1024 * 1024))}MB total budget, ${discarded.unreadable} unreadable, ${discarded.depthLimited} past the depth limit, ${discarded.symlink} symlinked file(s), ${discarded.symlinkDir} symlinked director(ies)`
+      )
+    );
+  }
+
+  for (const finding of report.anchored) {
+    console.log(
+      `${color.red('\u2716')} ${finding.ruleId} ${renderPath(finding.file)}:${finding.line} [${finding.form}]`
+    );
+    console.log(
+      finding.suggestedToken === null
+        ? `  ${renderPath(finding.token)} -> ${renderPath(finding.suggestedTarget)} (outside the alias root of this literal — rewrite by hand)`
+        : `  ${renderPath(finding.token)} -> ${renderPath(finding.suggestedToken)}`
+    );
+  }
+  if (report.unanchoredCount > 0) {
+    if (args.all) {
+      for (const finding of report.unanchored) {
+        console.log(
+          `${color.yellow('warning')} ${finding.ruleId} ${renderPath(finding.file)}:${finding.line} [${finding.form}] ${renderPath(finding.token)}`
+        );
+      }
+    }
+    console.log(
+      color.yellow(
+        `  ${report.unanchoredCount} unanchored candidate(s)${args.all ? ` listed above${report.truncated.unanchored ? ` (first ${report.unanchored.length}; the list is capped at ${report.findingCap}, the count is not)` : ''}` : ' not listed (--all)'} — literals that look like a repo path and do not resolve. Advisory only: with no rename to anchor them ArkGate cannot tell a dead reference from an illustrative one, so read them, do not gate on them.`
+      )
+    );
+  }
+
+  if (written) {
+    for (const entry of written.written) {
+      console.log(color.green(`  wrote ${renderPath(entry.file)} (${entry.applied})`));
+    }
+    for (const entry of written.skipped) {
+      console.log(color.yellow(`  skipped ${renderPath(entry.file)}: ${entry.reason} (${entry.count})`));
+    }
+  }
+
+  if (report.anchored.length === 0) {
+    if (!report.renameSet.available) {
+      // No tick. A green mark over a check that never ran is the false green
+      // this whole patch exists to remove.
+      console.log(
+        color.yellow(
+          '\u25CB Anchored mode did not run — no rename set. This says nothing about drift.'
+        )
+      );
+    } else {
+      console.log(color.green('\u2714 No anchored literal path drift.'));
+      console.log(
+        color.dim(
+          '  Every literal explained by the rename set resolves. This is a text match over strings and comments: it proves no scanned literal is stale against those renames, not that every path in the repo is live.'
+        )
+      );
+    }
+  }
+  if (!written && report.anchored.length > 0) {
+    const writable = report.anchored.filter((finding) => finding.suggestedToken !== null).length;
+    const byHand = report.anchored.length - writable;
+    console.log(
+      color.dim(
+        `  Report only. Re-run with --write to apply ${writable} of the ${report.anchored.length} anchored replacement(s)${byHand > 0 ? `; ${byHand} must be rewritten by hand` : ''}. Unanchored findings are never written.`
+      )
+    );
+  }
+}
+
 /**
  * Additive P0-A contract retrofit: inject high-spec app/api → Application when missing.
  * Does not remove existing patterns or weaken rules (DL-P0A-RETROFIT).
@@ -849,6 +1054,9 @@ function applyConfigRootWalkUp(args) {
     return args;
   }
   const writeMode = isMutatingCliCommand(args);
+  // The root the caller asked for, before any walk-up adopts the config's directory.
+  // An empty analysis must be able to say which of the two it actually walked.
+  args.requestedRoot = path.resolve(args.root);
   const effective = resolveEffectiveProjectRoot(args.root, {
     configName: args.config,
     writeMode,
@@ -924,6 +1132,17 @@ async function main() {
     return;
   }
 
+  if (args.pathDrift) {
+    await runPathDrift(args);
+    return;
+  }
+
+  if (args.sensors) {
+    const { runSensors } = await import('./lib/sensor-promote-cli.mjs');
+    await runSensors(args, readConfig);
+    return;
+  }
+
   if (args.recommend) {
     try {
       const recommendation = buildArchitectureRecommendation(args.root);
@@ -964,6 +1183,59 @@ async function main() {
     return;
   }
 
+  // Empty analysis is a refusal: on zero governed files every later gate reports on
+  // nothing. It outranks --require-gates, so the caller hears the real reason instead
+  // of "Ark gates are not installed" in whatever directory the contract happened to
+  // live in — but it is evaluated LAZILY, so the cheap exits (a --changed run whose
+  // diff touches no product path, --require-gates with the gates present) still pay
+  // nothing for a filesystem walk they never needed.
+  //
+  // Report modes are exempt: --plan, --coverage and --doctor are how a user sees and
+  // fixes an empty scope (they already carry the `empty-scope` adoption gap), so
+  // refusing there would remove the only surface that explains the refusal.
+  const root = args.root;
+  const verdictPath = !args.plan && !args.coverage && !args.doctor;
+  let configCache = null;
+  const loadConfig = () => (configCache ??= readConfig(root, args.config));
+  let governedCache = null;
+  const loadGovernedFiles = () => (governedCache ??= collectGovernedFiles(root, loadConfig()));
+  const emptyAnalysisRefusalNow = () => {
+    const governedCount = loadGovernedFiles().length;
+    return emptyAnalysisRefusal({
+      governedFileCount: governedCount,
+      // Probed only when nothing is governed, and never through the contract's own
+      // exclude: the config under suspicion must not get to answer the question about
+      // itself (`exclude: ["**"]` would otherwise read as greenfield and pass).
+      ungovernedSourceCount: governedCount === 0 ? countUngovernedSourceFiles(root) : 0,
+      ungovernedSourceCap: UNGOVERNED_PROBE_CAP,
+      root,
+      requestedRoot: args.requestedRoot,
+      configPath: path.isAbsolute(args.config) ? args.config : path.join(root, args.config),
+      configWalkedUp: args.configWalkedUp === true,
+    });
+  };
+  const reportEmptyAnalysis = (refusal) => {
+    if (args.json) {
+      console.log(
+        JSON.stringify(
+          {
+            ok: false,
+            error: refusal.ruleId,
+            completeness: ANALYSIS_COMPLETENESS.unavailable,
+            message: refusal.message,
+            nextAction: refusal.nextAction,
+          },
+          null,
+          2
+        )
+      );
+    } else {
+      console.error(`${color.red('\u2716')} ${refusal.ruleId} ${refusal.message}`);
+      console.error(`Next: ${refusal.nextAction}`);
+    }
+    process.exitCode = 1;
+  };
+
   if (args.requireGates || args.requireWriteHook) {
     let writeRequest = null;
     if (args.requireWriteHook) {
@@ -994,6 +1266,24 @@ async function main() {
       missing.push(`${writeRequest.host} hard-write hook`);
     }
     if (missing.length > 0) {
+      // "Gates not installed" is the wrong reason for a run that would have analyzed
+      // nothing: it sends the user to `ark init` for a problem they do not have. Only
+      // here do we pay for the walk — with the gates present we fall through and the
+      // verdict path below checks at its usual point. A contract that cannot even be
+      // read is not evidence of an empty analysis, so that throw falls back to the
+      // gate report instead of masking it.
+      let refusal = null;
+      if (verdictPath) {
+        try {
+          refusal = emptyAnalysisRefusalNow();
+        } catch {
+          refusal = null;
+        }
+      }
+      if (refusal) {
+        reportEmptyAnalysis(refusal);
+        return;
+      }
       const payload = {
         ok: false,
         error: 'missing-gates',
@@ -1037,10 +1327,9 @@ async function main() {
     }
   }
 
-  const root = args.root;
   const bound = bindTeamBaseRefs(args, root);
   Object.assign(args, bound.args);
-  const config = readConfig(root, args.config);
+  const config = loadConfig();
   const policyDelta = analyzePolicyTransition({
     root,
     configPath: args.config,
@@ -1088,7 +1377,14 @@ async function main() {
   }
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
-  const allGovernedFiles = collectGovernedFiles(root, config);
+  const allGovernedFiles = loadGovernedFiles();
+  if (verdictPath) {
+    const refusal = emptyAnalysisRefusalNow();
+    if (refusal) {
+      reportEmptyAnalysis(refusal);
+      return;
+    }
+  }
   if (args.failUngoverned && teamParliament?.changeSet?.productPaths?.length) {
     const governedRel = new Set(
       allGovernedFiles.map((abs) => normalize(path.relative(root, abs)))
@@ -1164,6 +1460,31 @@ async function main() {
     populatedLayerCount,
   });
 
+  // --promote reuses the analysis that just ran rather than running its own:
+  // the advisory findings it counts are already in `violations` + `warnings`,
+  // stamped with the rule that produced them. Placed before the design-delta
+  // check so a preview does not pay for a base-ref diff it never reads.
+  if (args.promote) {
+    // The floor the merge gate itself applies: below it every enforced
+    // extra-plane finding is demoted to a warning, so a promotion made here
+    // buys a label and not a tooth. `violations` above was already demoted by
+    // it; the preview has to know, or it sells teeth the gate then removes.
+    const { extraMergeTeethAllowed } = await import('./lib/extra-merge-teeth.mjs');
+    const teethDemotedByFloor = !extraMergeTeethAllowed({
+      governedPercent: preCov.governed?.percent ?? null,
+      populatedLayerCount,
+    });
+    const { runPromote } = await import('./lib/sensor-promote-cli.mjs');
+    await runPromote(root, config, args, {
+      files,
+      all: [...violations, ...(warnings ?? [])],
+      completeness,
+      completenessReasons,
+      teethDemotedByFloor,
+    });
+    return;
+  }
+
   const createdPathsOnly = Boolean(args.strictMerge && !args.failOnNewSmells);
   const designCheck = createDesignDeltaCheck({
     enabled: args.failOnNewSmells || args.strictMerge,
@@ -1670,6 +1991,20 @@ async function main() {
           `${color.green('✔')} Ark check passed with ${warnings.length} config warning(s).${baselineNote}`
         );
       }
+      // `--plan` is where the design bets live and a green run never named it.
+      // Not on the strict-config branch above (it printed a failure), not on
+      // `--changed` (a partial scan would print one slice's count as the tree's),
+      // not on `--watch` (a line that repeats every save is a line nobody reads).
+      if (!(args.strictConfig && strictWarnings.length > 0) && !args.changed && !args.watch) {
+        const { greenPlanPointer } = await import('./lib/design-smells.mjs');
+        const pointer = greenPlanPointer({
+          root, config, files, coverage: preCov,
+          blockingViolations: blockingViolations.length,
+          suppressedCount: suppressed.length,
+          planCommand: arkCommand(root, 'ark-check', '--plan'),
+        });
+        if (pointer) console.log(color.dim(pointer));
+      }
     } else {
       console.error(
         blockingViolations.length > 0

package/bin/ark-layer-match.mjs

@@ -258,20 +258,165 @@ function resolveSliceFolders(rule, layerName, layers) {
     const layer = (layers ?? []).find((l) => l.name === layerName);
     return inferSliceFoldersFromPatterns(layer?.patterns);
 }
+function normalizeSegments(value) {
+    return String(value)
+        .split(/[/\\]/)
+        .filter((part) => Boolean(part) && part !== '.')
+        .map((part) => part.toLowerCase());
+}
 /**
- * PeerIsolation deny decision given resolved path/slice evidence (DF04 pure core).
+ * Trim trailing slashes without a regex.
  *
- * Fail-closed: missing path, no classifiable folders, or unclassifiable either
- * side → deny. Same-slice → allow (return false). Cross-slice → deny.
+ * `/\/+$/` is a polynomial ReDoS on a value that comes from the repo's own
+ * contract but is still library input: a root of many slashes makes the engine
+ * retry from every start position. A scan is linear and says the same thing.
  */
-export function peerIsolationMustDeny(input) {
-    if (!input.fromPath || !input.toPath)
+function trimTrailingSlashes(value) {
+    let end = value.length;
+    while (end > 0 && value[end - 1] === '/')
+        end -= 1;
+    return value.slice(0, end);
+}
+/** Source folders a declared shared root may sit under without being named. */
+const SHARED_ROOT_SOURCE_PREFIXES = ['src', 'app'];
+/** A root that would disable the wall wholesale is not a root. */
+function isBlanketRoot(raw) {
+    const trimmed = trimTrailingSlashes(raw.replace(/^[./]+/, ''));
+    return trimmed === '*' || trimmed === '**';
+}
+/**
+ * Is `relPath` under one of the roots the rule declares shared on purpose?
+ *
+ * **Anchored**, unlike `sliceIdForPath`: the root must start the repo-relative
+ * path, optionally after a single conventional source folder, so `ui` covers
+ * `ui/button.tsx` and `src/ui/button.tsx` but NOT `modules/a/ui/x.tsx` — an
+ * unanchored root would exempt a whole tree the author never declared. Deeper
+ * or monorepo roots are written out (`packages/web/src/ui`) or globbed
+ * (`packages/*​/src/ui`). Matching is case-insensitive; a root containing `*`
+ * is matched as a glob (also case-insensitively) against the whole path, and a
+ * bare `*` / `**` is refused because it would disable fail-closed wholesale.
+ */
+export function pathUnderSharedRoot(relPath, sharedRoots) {
+    if (!relPath || !sharedRoots?.length)
+        return false;
+    const rel = String(relPath).split(/[/\\]/).join('/');
+    const lowerRel = rel.toLowerCase();
+    const parts = normalizeSegments(rel);
+    for (const raw of sharedRoots) {
+        if (typeof raw !== 'string' || raw.length === 0)
+            continue;
+        if (isBlanketRoot(raw))
+            continue;
+        if (raw.includes('*')) {
+            const glob = trimTrailingSlashes(raw.toLowerCase());
+            if (globToRegExp(glob).test(lowerRel) || globToRegExp(`${glob}/**`).test(lowerRel)) {
+                return true;
+            }
+            continue;
+        }
+        const root = normalizeSegments(raw);
+        if (root.length === 0)
+            continue;
+        // Anchor at segment 0, or at segment 1 when the path opens with a source
+        // folder the root does not itself name.
+        const offsets = SHARED_ROOT_SOURCE_PREFIXES.includes(parts[0]) && root[0] !== parts[0] ? [0, 1] : [0];
+        for (const offset of offsets) {
+            if (offset + root.length > parts.length)
+                continue;
+            let hit = true;
+            for (let j = 0; j < root.length; j += 1) {
+                if (parts[offset + j] !== root[j]) {
+                    hit = false;
+                    break;
+                }
+            }
+            if (hit)
+                return true;
+        }
+    }
+    return false;
+}
+function sliceMatchesDeclaration(declared, sliceId) {
+    const want = String(declared).split(/[/\\]/).filter(Boolean).join('/').toLowerCase();
+    if (!want)
+        return false;
+    const have = sliceId.toLowerCase();
+    if (want === have)
         return true;
+    // Bare slice name: `auth` matches `features/auth`.
+    return !want.includes('/') && have.endsWith(`/${want}`);
+}
+/** Has the rule declared this directed slice→slice edge? */
+export function crossSliceEdgeAllowed(allowedCrossSlice, fromSlice, toSlice) {
+    if (!allowedCrossSlice?.length || !fromSlice || !toSlice)
+        return false;
+    return allowedCrossSlice.some((edge) => edge &&
+        typeof edge.from === 'string' &&
+        typeof edge.to === 'string' &&
+        sliceMatchesDeclaration(edge.from, fromSlice) &&
+        sliceMatchesDeclaration(edge.to, toSlice));
+}
+/**
+ * PeerIsolation deny decision with the reason that fired (DF04 pure core).
+ *
+ * Fail-closed stays fail-closed: absent evidence denies. What changed in 4.8.4
+ * is what counts as evidence — a declared shared root, or a declared directed
+ * cross-slice edge, is the repo telling us its design, so it is no longer
+ * "unclassifiable". Order: no paths → no slice folders → a side that is neither
+ * in a slice nor declared shared → same slice → declared cross edge → deny.
+ */
+export function peerIsolationDecision(input) {
+    if (!input.fromPath || !input.toPath)
+        return { denied: true, reason: 'missing-path' };
     if (input.folderCount <= 0)
-        return true;
+        return { denied: true, reason: 'no-slice-folders' };
+    const fromClassified = Boolean(input.fromSlice) || input.fromShared === true;
+    const toClassified = Boolean(input.toSlice) || input.toShared === true;
+    if (!fromClassified || !toClassified)
+        return { denied: true, reason: 'unclassifiable-path' };
+    // At least one side is declared shared (and carries no slice id): the repo
+    // said this code belongs to no slice, so there is no cross-slice edge here.
     if (!input.fromSlice || !input.toSlice)
-        return true;
-    return input.fromSlice !== input.toSlice;
+        return { denied: false };
+    if (input.fromSlice === input.toSlice)
+        return { denied: false };
+    if (input.crossSliceAllowed)
+        return { denied: false };
+    return { denied: true, reason: 'cross-slice' };
+}
+/**
+ * Boolean face of {@link peerIsolationDecision}, kept for parity consumers.
+ *
+ * Fail-closed: missing path, no classifiable folders, or unclassifiable either
+ * side → deny. Same-slice → allow (return false). Cross-slice → deny unless the
+ * rule declared that directed edge.
+ */
+export function peerIsolationMustDeny(input) {
+    return peerIsolationDecision(input).denied;
+}
+/**
+ * One human sentence naming which peerIsolation reason fired — so the denial
+ * reports a fact about their code (`cross-slice`) or a fact about our evidence
+ * (everything else), never one dressed as the other.
+ */
+export function peerIsolationDenyExplanation(reason, context) {
+    switch (reason) {
+        case 'cross-slice':
+            return `cross-slice edge ${context.fromSlice ?? '?'} → ${context.toSlice ?? '?'}. Extract the shared code, use events/ports across slices, or declare the edge in the rule's allowedCrossSlice.`;
+        case 'unclassifiable-path': {
+            const unplaced = [
+                context.fromSlice ? undefined : context.fromPath,
+                context.toSlice ? undefined : context.toPath,
+            ].filter((path) => Boolean(path));
+            const which = unplaced.length > 0 ? ` (${unplaced.join(', ')})` : '';
+            return `unclassifiable path${which} — ArkGate cannot place it in a slice, so it cannot prove this is not a cross-slice edge. Move it into a slice, or declare its root in the rule's sharedRoots.`;
+        }
+        case 'no-slice-folders':
+            return 'no slice folders — peerIsolation is on but no slice folder resolves from the rule or the layer patterns. Set sliceFolders on the rule.';
+        case 'missing-path':
+        default:
+            return 'no path evidence for this edge — peerIsolation needs the importer and importee paths.';
+    }
 }
 /**
  * Find the first denying rule for a layer edge.
@@ -286,6 +431,14 @@ export function peerIsolationMustDeny(input) {
  *   allow a possible cross-slice edge.
  */
 export function findDeniedEdgeRule(rules, from, to, options) {
+    return findDeniedEdgeDecision(rules, from, to, options)?.rule;
+}
+/**
+ * {@link findDeniedEdgeRule} with the denial reason attached, so adapters can
+ * say *why* a peerIsolation rule fired instead of emitting one opaque message
+ * for a real cross-slice import and for a file we simply could not place.
+ */
+export function findDeniedEdgeDecision(rules, from, to, options) {
     for (const rule of rules ?? []) {
         if (rule.from !== from || rule.to !== to)
             continue;
@@ -297,21 +450,25 @@ export function findDeniedEdgeRule(rules, from, to, options) {
             const folders = resolveSliceFolders(rule, from, options?.layers);
             const fromSlice = fromPath && toPath ? sliceIdForPath(fromPath, folders) : undefined;
             const toSlice = fromPath && toPath ? sliceIdForPath(toPath, folders) : undefined;
-            if (peerIsolationMustDeny({
+            const decision = peerIsolationDecision({
                 fromPath,
                 toPath,
                 folderCount: folders.length,
                 fromSlice,
                 toSlice,
-            })) {
-                return rule;
+                fromShared: !fromSlice && pathUnderSharedRoot(fromPath, rule.sharedRoots),
+                toShared: !toSlice && pathUnderSharedRoot(toPath, rule.sharedRoots),
+                crossSliceAllowed: crossSliceEdgeAllowed(rule.allowedCrossSlice, fromSlice, toSlice),
+            });
+            if (decision.denied) {
+                return { rule, peerIsolationReason: decision.reason, fromSlice, toSlice };
             }
-            continue; // same slice: this peerIsolation rule does not deny
+            continue; // same slice, declared shared, or declared cross edge: no denial
         }
         // Classic deny — same-layer always allowed without peerIsolation
         if (from === to)
             continue;
-        return rule;
+        return { rule };
     }
     return undefined;
 }

package/bin/ark-mcp-runtime.mjs

@@ -260,14 +260,21 @@ async function loadArk() {
   const url = new URL('../dist/index.js', import.meta.url);
   if (!fs.existsSync(url)) {
     throw new Error(
-      'ark-mcp requires the built library at dist/index.js. Run "npm run build" first.'
+      'ark-mcp requires the built library at dist/index.js, and this install does not have it. ' +
+        'The npm tarball ships dist/; a git install (git+https://…/arkgate) ships only the ' +
+        'committed sources, so arkgate/arkgate-check work but ark-mcp and every "import arkgate*" ' +
+        'do not. Install from npm (npm i arkgate); building is only possible in a clone of the ' +
+        'repository, not in this node_modules copy, which ships no devDependencies. ' +
+        'See docs/package-surface.md, "Installing from git".'
     );
   }
   try {
     return await import('../dist/index.js');
   } catch (err) {
     throw new Error(
-      `ark-mcp failed to load dist/index.js (rebuild with "npm run build"): ${
+      `ark-mcp failed to load dist/index.js — it exists but will not import, so this is a ` +
+        `broken or partial build rather than a git install (rebuild with "npm run build" in a ` +
+        `clone of the repository): ${
         err instanceof Error ? err.message : String(err)
       }`
     );