arkgate 4.8.24 → 4.8.25

package/CHANGELOG.md

@@ -5,7 +5,78 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.8.25 — 2026-10-05
+
+**Patch** over **4.8.24**. Weekly accumulate (#342, #344, #345, #346, #347, #348, #349, #350). **Write. Check. Ship.** **No required config migration.** `childSlices.arkRulesFile` and pinned `sliceAliases` need 4.8.25. No `schemaVersion` bump. Does not close `K01` / `Z09`. This mother `ark.config.json` still does **not** turn `arkOrder` on.
+
+**Status: released** (tag `v4.8.25`). Run `npm view arkgate@4.8.25 version` to confirm (#314).
+
 ### Added
+- Per-slice ArkRules file `childSlices.arkRulesFile` and pinned `sliceAliases` (#342, #341).
+- `arkgate-check --probe-invariants[=<id>]` checks that the tests covering an
+  invariant actually pin it. A test title that names the rule proves the test
+  exists, not that it would fail if the rule broke. For each invariant with a
+  `coverage.symbol`, the probe copies the project to a temporary folder and
+  runs only the covering tests (titles that name the id, and tests that import
+  the symbol's file) with your own runner — vitest, jest or `node --test`:
+  unchanged, then with the file throwing on load, then with the symbol
+  throwing when called, then with at most three small changes inside it
+  (negate a guard, drop a `throw`, flip or shift a comparison, shift a
+  constant). Each invariant reads `killed`, `survived`, `not-reached`,
+  `inconclusive` or `unprobeable`, with the change that went unnoticed and the
+  line. Your files are never changed. Report by default; `--write` saves
+  `.ark/invariant-probe.json` (new schema export `arkgate/schema/invariant-probe`).
+  Exit 0 when nothing survived, 1 when something did, 2 when it could not run.
+  Not a score.
+- Promotion reads the committed probe result. When `.ark/invariant-probe.json`
+  has a fresh `survived` or `not-reached` row — the symbol file, its covering
+  tests and the invariant unchanged since the run — `--promote` and the policy
+  delta refuse to promote that invariant to `enforced` (blocker
+  `probe-survived`). A stale, `killed`, `inconclusive` or missing result
+  changes nothing, so every promotion without the file behaves as before.
+  Status and `--rules-inventory` show the probe state per invariant when the
+  file exists; new catalog id `INVARIANT_PROBE_SURVIVED` (advisory, never in
+  the check). The probe runs only when you start it: never from the write
+  hook, MCP, ESLint, the GitHub Action or `--strict-merge`, and it refuses to
+  combine with them. The runner gets a short environment allowlist (no
+  tokens); that is best effort, not a sandbox. No config key, no new skill;
+  `/ark-contract` and `/ark-coverage` explain the blocker and the next test to
+  write.
+- Status lists code copied across a wall. When a slice wall denies an import,
+  the cheapest way around it is a copy, and a copy is not an import.
+  `--doctor --all`, the HTML report and `--doctor --all --json` (under
+  `doctor.crossWallDuplication`) now list near-identical code whose copies sit
+  on two sides of a slice wall, in two child slices of one universe, or in two
+  layers, with a place the shared code could live (the declared shared root,
+  the universe common folder, or the lower layer both sides may import).
+  Copies inside one slice are counted, never listed. It reads token
+  fingerprints taken while status runs, with the TypeScript ArkGate already
+  loaded; they never enter the check, so the verdict and `factsHash` do not
+  change. Tests, `.d.ts`, generated files and files over 256 KB are skipped.
+  Fixed thresholds (at least 50 tokens, 5 lines, most names matching), no
+  config key. Compact status never runs it; its JSON says `not-run` and names
+  the command. When a cap stops the pass the section says `partial` and how
+  much was left. New catalog ids `CROSS_WALL_DUPLICATE` and
+  `CROSS_LAYER_DUPLICATE` (advisory). Never a score, never in the write hook,
+  MCP, ESLint, `--changed`, or `--strict-merge`. No new skill; `/ark-place`
+  names the destination and `/ark-fix` moves one copy at a time.
+- Status lists the files nothing imports. A governed file with no importer —
+  no governed file, test, project script, or known entry point — shows in
+  `--doctor --all`, the HTML report, and `--doctor --json` under
+  `doctor.orphanModules`; compact status prints one count line at most. It
+  reads the import edges the check already resolved, so the verdict and
+  `factsHash` do not change. Entry points come from `package.json` (built
+  `dist/` paths map back to source), CI workflow run steps, Next / Vite / Nest /
+  Vercel / Storybook conventions, the arkRun / arkOrder roots, config and setup
+  files, ambient declaration files, and an optional `.ark/entry-points.json`
+  (glob + reason + optional `reviewBy`; not a config key). Files only tests
+  import are counted, not listed. When a dynamic import, `import.meta.glob`, a
+  quoted path, or an unresolved import may still reach a file, the item says
+  so and the list is `partial`. `--doctor --all` and `--report` also list
+  exports nothing imports by name. New catalog ids `ORPHAN_MODULE` and
+  `UNUSED_EXPORT` (advisory). Never a score, never in the write hook, MCP
+  write tools, ESLint, or `--strict-merge`. No new skill; `/ark-explore` maps
+  the list and `/ark-fix` deletes one file at a time through the write gate.
 - Soft doctor residual when Domain is declared but empty and the UI holds the
   rules (`noDomainFrontend`). Projects empty Domain + presentation share, or
   the existing `domain-logic-in-ui` smell. Friendly next step: one Domain file
@@ -48,6 +119,10 @@ in the immutable pre-2.0 archive linked below.
   short phrase templates so the shape is visible. No new skill, schema, or flag.
 
 ### Changed
+- `brace-expansion` is overridden to 5.0.12 (Dependabot medium, quadratic expansion) (#350).
+- Eval fixtures pin Next.js 16.3.6 (#346).
+- The package no longer ships `bin/lib/ark-order-invariants.mjs`, `bin/lib/ark-order-error.mjs`, or `bin/lib/stable-hash.mjs`; no CLI loaded them. ArkOrder invariants still ship in `arkgate/order`. One new generated CLI module, `bin/lib/schema-validation.mjs`, holds the JSON-Schema walker shared by the config and ArkRules contracts.
+- Internal cleanup with no public export or behavior change: about 390 unused internal exports removed (knip) and hand-written copy/paste duplication cut from 1.01% to 0% (jscpd). Maintainers: `npm run check:knip` and `npm run check:duplication` run in the CI build job.
 - Compact `--doctor` names ArkRules only when the `arkRules` map is on
   (one breath + counts, not a score). Absence stays silent. Reuses
   `rulesUnderContract` — no new schema, flag, or skill. `--doctor --all`
@@ -66,6 +141,16 @@ in the immutable pre-2.0 archive linked below.
   Required CI is still the shared merge line. No new skill, schema, or host.
 
 ### Fixed
+- `writes-via-aggregate` flags tagged-template SQL writes (`UPDATE`, `MERGE`, `TRUNCATE`, including `ONLY`, quoted names, and interpolated tables). Comments, `FOR UPDATE`, and `DO UPDATE SET` stay silent (#344, #343).
+- `--policy-base` and MCP policy-delta now judge an advisory → enforced
+  invariant promotion with the declared `coverage.coverageRoots`, the same way
+  `--promote` does. Before, a covered promotion with roots declared came out
+  `judgment-required` ("Declare coverage.coverageRoots…") while `--promote`
+  allowed it.
+- The flat-parent suggestion in status reads the resolved importer index
+  instead of re-reading every file for import text.
+- Doctor sees CI jobs gated by `needs:`: a job that runs the fail-closed Ark check behind unconditional jobs (such as a CI-profile job) now counts as a merge gate; `ciMergeBoundary.ci.workflowPresent` / `merge-gate` no longer report it absent. Jobs a profile output can skip, jobs with `continue-on-error`, and chains with a conditional job still do not count.
+- With `ARK_DOCTOR_GITHUB=1`, the Ark check counts as required only when every job that can skip it is required too (a skipped job satisfies branch protection); otherwise the doctor reports `unverified`, `arkCheckUpstreamNotRequired`, and the gap `enforcement-ark-check-upstream-not-required`. Required checks bound to the GitHub Actions app now correlate (`arkCheckSourceBound: true`).
 - Write hook and `ark-check` now agree on overlapping layer globs: the hook
   probes the same specifier extensions as `ark-check` and classifies with
   `layerForRelativePath` (explicit `money.ts` beats `src/lib/**`). Field

package/README.md

@@ -25,11 +25,11 @@ Design the boundary before you implement. Put a small interface in front of the
 
 ## Try it
 
-One command. Preview only — no files change. Current release is **4.8.24**
+One command. Preview only — no files change. Current release is **4.8.25**
 (check npm `latest` with `npm view arkgate version`):
 
 ```bash
-npx arkgate@4.8.24 start
+npx arkgate@4.8.25 start
 ```
 
 ## What a red result looks like

package/bin/ark-check-runtime.mjs

@@ -77,6 +77,7 @@ import {
   printViolationBreakdown,
   printHumanWarnings,
   CONCENTRATION_MIN_VIOLATIONS,
+  color,
 } from './lib/violations.mjs';
 import {
   detectBestFitModel,
@@ -1033,15 +1034,6 @@ function readManifest(root, manifestPath) {
   return readJson(fullPath);
 }
 
-const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
-const color = {
-  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
-  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
-  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
-  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
-  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
-};
-
 /**
  * Monorepo honesty: when cwd/--root has no ark.config.json, walk parents (bounded).
  * Stamps configRoot / configWalkedUp. Mutates args.root only for read paths, or
@@ -1147,6 +1139,14 @@ async function main() {
     return;
   }
 
+  if (args.probeInvariants) {
+    // ADR 0039: owner-invoked, outside the gate path. Loaded only here; parseArgs
+    // refuses every pairing with --strict-merge, --changed, --local or --doctor.
+    const { runProbeInvariants } = await import('./lib/invariant-probe-cli.mjs');
+    await runProbeInvariants(args, readConfig);
+    return;
+  }
+
   if (args.sensors) {
     const { runSensors } = await import('./lib/sensor-promote-cli.mjs');
     await withSensorsPartialModeHonesty(args, () => runSensors(args, readConfig));
@@ -1437,7 +1437,7 @@ async function main() {
 
   const {
     violations: rawViolations, warnings, safety, parseHealth, completeness, completenessReasons,
-    mode, policyHash, resolverIdentity, factsHash, candidateTreeHash,
+    mode, policyHash, resolverIdentity, factsHash, candidateTreeHash, importGraph,
   } = runArchitectureScan({
     root,
     config,
@@ -1449,6 +1449,8 @@ async function main() {
     files: args.changed ? files : [],
     ts,
     args,
+    // ADR 0037: doctor / report read a compact importer index, never the verdict path.
+    graphProjection: Boolean(args.doctor || args.report) && !args.changed,
   });
 
   if (args.changed) pruneScopedPatternWarnings(warnings, root, loadGovernedFiles);
@@ -1508,8 +1510,8 @@ async function main() {
       configWalkedUp: args.configWalkedUp === true,
       safety, designDelta,
       ts, parseHealth, completeness,
-      all: args.all === true, requireGates: args.requireGates === true,
-      warnings,
+      all: args.all === true, changed: args.changed === true, requireGates: args.requireGates === true,
+      warnings, architectureFacts: importGraph ? { importGraph } : undefined,
     });
     if (designDelta) process.exitCode = !designDelta.complete ? 2 : designDelta.valid ? 0 : 1; return;
   }
@@ -1790,8 +1792,9 @@ async function main() {
           files,
           ts,
           parseHealth,
-          undefined,
-          activeViolations
+          importGraph ? { importGraph } : undefined,
+          activeViolations,
+          { details: true, changed: args.changed === true }
         ),
         // Doctor parity: always emit improvement compass when doctor would (reportParity).
         ...(designDepth?.improvementCompass

package/bin/ark-layer-match.mjs

@@ -132,7 +132,7 @@ export function globToRegExp(pattern) {
  * Used for path-anchored ranking so a domain folder glob can beat a broad
  * Application bag like src/lib when the file actually sits under domain/.
  */
-export function concreteGlobSegments(pattern) {
+function concreteGlobSegments(pattern) {
     const glob = normalizeGlobSeparators(String(pattern));
     return glob
         .split('/')
@@ -393,7 +393,7 @@ function bindAnchoredSlice(parts, pattern, offset, identity = 'path') {
  * literal, and everything after it. Literals before the last literal drop.
  * Returns null when the pattern has no literal.
  */
-export function starsKeptSegmentIndexes(segments) {
+function starsKeptSegmentIndexes(segments) {
     let lastLiteral = -1;
     for (let at = 0; at < segments.length; at += 1) {
         if (segments[at] !== '*')
@@ -681,6 +681,7 @@ export function peerIsolationMustDeny(input) {
     return peerIsolationDecision(input).denied;
 }
 export const SLICE_ALIAS_DEBT = 'Aliases are an owed move, not a destination. These files are not finished.';
+const PINNED_ALIAS_NOTE = 'Pinned aliases stay where they are. They are not an owed move.';
 function aliasGlobPattern(glob) {
     return trimTrailingSlashes(glob.trim().replace(/\\/g, '/')).toLowerCase();
 }
@@ -781,7 +782,7 @@ function literalsMatch(shape, parts) {
  * New-id shapes (`*` for a star) that a 4.8.23 stars id maps to. Empty when the id is
  * already a new id or no shape takes it. Config load rejects more than one.
  */
-export function legacyStarsIdTargets(folders, id) {
+function legacyStarsIdTargets(folders, id) {
     const parts = id.split('/').filter(Boolean).map((part) => part.toLowerCase());
     const shapes = starsUniverseShapes(folders);
     if (parts.length === 0 || shapes.some((shape) => literalsMatch(shape.literals, parts)))
@@ -937,11 +938,93 @@ export function sliceAliasDestination(file, childId, child) {
 export function anySliceAlias(rules) {
     return (rules ?? []).some((rule) => (rule?.childSlices?.sliceAliases?.length ?? 0) > 0);
 }
+/** True when an alias is still an owed move. `pinned: true` does not count. A reason alone does. */
+export function sliceAliasOwesMove(rules) {
+    return (rules ?? []).some((rule) => (rule?.childSlices?.sliceAliases ?? []).some((alias) => alias?.pinned !== true));
+}
+const SLICE_RULE_LAYER_TOKEN = '<Layer>';
+function sliceRuleFileName(pattern, layer) {
+    const token = SLICE_RULE_LAYER_TOKEN;
+    if (!pattern.includes(token) || pattern.split(token).length !== 2)
+        return null;
+    if (/[*\\/]/.test(pattern))
+        return null;
+    const name = pattern.replace(token, layer);
+    if (!name || name.includes('..'))
+        return null;
+    return name;
+}
+/**
+ * Child-slice ArkRules files this wall already named.
+ * Roots come from the governed file index. The pattern is a filename, not a search.
+ */
+export function resolveSliceRulePlan(input) {
+    const layers = [...new Set(input.layers.filter((name) => typeof name === 'string' && name.length > 0))].sort();
+    const entries = [];
+    const seen = new Set();
+    for (const rule of input.rules ?? []) {
+        const child = rule?.childSlices;
+        const pattern = child?.arkRulesFile;
+        if (!child || typeof pattern !== 'string')
+            continue;
+        const roots = new Map();
+        for (const file of input.files) {
+            if (typeof file !== 'string' || file.length === 0)
+                continue;
+            const universeId = rule.sliceFolders?.length
+                ? sliceIdForPath(file, rule.sliceFolders, rule.sliceIdentity)
+                : undefined;
+            const resolved = resolveChildSliceId(file, universeId, child);
+            if (!resolved.childId || roots.has(resolved.childId))
+                continue;
+            const root = sliceAliasDestination(file, resolved.childId, child);
+            if (root)
+                roots.set(resolved.childId, root);
+        }
+        for (const [childId, sliceRoot] of [...roots.entries()].sort((left, right) => left[0].localeCompare(right[0]))) {
+            for (const layer of layers) {
+                const name = sliceRuleFileName(pattern, layer);
+                if (!name)
+                    continue;
+                const rel = `${sliceRoot}/${name}`.replace(/\\/g, '/');
+                if (seen.has(`${layer}\0${rel}`))
+                    continue;
+                seen.add(`${layer}\0${rel}`);
+                entries.push({
+                    path: rel,
+                    childId,
+                    layer,
+                    defaultAppliesTo: [`${sliceRoot}/**`],
+                });
+            }
+        }
+    }
+    return entries;
+}
+/** Ids from the effective catalog that belong to the child slice of this file. */
+export function sliceRuleIdsForFile(filePath, rules, catalog) {
+    const childIds = new Set();
+    for (const rule of rules ?? []) {
+        if (!rule?.childSlices)
+            continue;
+        const universeId = rule.sliceFolders?.length
+            ? sliceIdForPath(filePath, rule.sliceFolders, rule.sliceIdentity)
+            : undefined;
+        const resolved = resolveChildSliceId(filePath, universeId, rule.childSlices);
+        if (resolved.childId)
+            childIds.add(resolved.childId);
+    }
+    return catalog
+        .filter((row) => typeof row.childId === 'string' && childIds.has(row.childId))
+        .map((row) => row.id)
+        .sort();
+}
 /** Doctor list. Absent when no rule sets sliceAliases, so the key stays off. */
 export function sliceAliasReport(rules, files) {
     if (!anySliceAlias(rules))
         return null;
     const moves = new Map();
+    const pinned = new Map();
     for (const rule of rules ?? []) {
         const child = rule?.childSlices;
         if (!child?.sliceAliases)
@@ -950,10 +1033,19 @@ export function sliceAliasReport(rules, files) {
             if (!alias || typeof alias.from !== 'string' || typeof alias.to !== 'string')
                 continue;
             const key = `${aliasGlobPattern(alias.from)}\0${aliasGlobPattern(alias.to)}`;
-            let move = moves.get(key);
+            const bucket = alias.pinned === true ? pinned : moves;
+            let move = bucket.get(key);
             if (!move) {
-                move = { from: alias.from, to: alias.to, destination: '', files: [] };
-                moves.set(key, move);
+                move = {
+                    from: alias.from,
+                    to: alias.to,
+                    destination: '',
+                    files: [],
+                    ...(alias.pinned === true && typeof alias.reason === 'string' && alias.reason.length > 0
+                        ? { reason: alias.reason }
+                        : {}),
+                };
+                bucket.set(key, move);
             }
             const seen = new Set(move.files);
             for (const file of files) {
@@ -967,7 +1059,7 @@ export function sliceAliasReport(rules, files) {
         }
     }
     const universes = knownUniverseIds(rules, files);
-    const listed = [...moves.values()].map((move) => {
+    const decorate = (move) => {
         const target = splitAliasTarget(move.to);
         const unknown = universes !== null && target !== null && !universes.has(target.universeId);
         return {
@@ -980,9 +1072,19 @@ export function sliceAliasReport(rules, files) {
                 }
                 : {}),
         };
-    });
-    listed.sort((left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to));
-    return { notAScore: true, finished: false, debt: SLICE_ALIAS_DEBT, moves: listed };
+    };
+    const listed = [...moves.values()].map((move) => decorate(move));
+    const pinnedListed = [...pinned.values()].map((move) => decorate(move));
+    const byAlias = (left, right) => left.from.localeCompare(right.from) || left.to.localeCompare(right.to);
+    listed.sort(byAlias);
+    pinnedListed.sort(byAlias);
+    return {
+        notAScore: true,
+        finished: false,
+        debt: listed.length > 0 ? SLICE_ALIAS_DEBT : PINNED_ALIAS_NOTE,
+        moves: listed,
+        ...(pinnedListed.length > 0 ? { pinned: pinnedListed } : {}),
+    };
 }
 /**
  * Universe ids that real (non-aliased) files resolve to, across rules that set
@@ -1062,7 +1164,7 @@ function isCommonFolderName(segment, commonFolders) {
  * (`features/projects/rfi/domain/**`) belongs to that child. A child id that
  * does not extend the universe id is not used; the caller warns.
  */
-export function resolveChildSliceId(relPath, universeId, child) {
+function resolveChildSliceId(relPath, universeId, child) {
     if (!relPath || !child?.sliceFolders?.length)
         return {};
     const raw = sliceIdForPath(relPath, child.sliceFolders, child.sliceIdentity);
@@ -1123,7 +1225,7 @@ export function importerInEnforcedSubtree(fromPath, fromChild, entries) {
  * value deny every one. An object denies the importer only when it is listed,
  * unless `default` is already `deny`.
  */
-export function siblingCrossingAdvisory(siblings, fromPath, fromChild) {
+function siblingCrossingAdvisory(siblings, fromPath, fromChild) {
     if (siblings == null || siblings === 'deny')
         return false;
     if (siblings === 'advisory')
@@ -1206,7 +1308,7 @@ function childAllowanceSpansUniverses(from, to) {
  * Universe wall, then the child wall. An allow from the child wall never
  * overturns a universe deny: that deny returns before the child wall runs.
  */
-export function evaluateNestedSliceWall(input) {
+function evaluateNestedSliceWall(input) {
     const universe = peerIsolationDecision({
         fromPath: input.fromPath,
         toPath: input.toPath,

package/bin/ark-mcp-runtime.mjs

@@ -28,6 +28,7 @@ import { createImportTargetResolver } from './lib/import-resolve.mjs';
 import { validateWithAutoPatch, resolveImportFileAbs } from './lib/auto-patch.mjs';
 import { composePrepareWrite } from './lib/prepare-write.mjs';
 import { placementDescriptionFields } from './lib/layer-description.mjs';
+import { sliceRuleIdsForFile } from './ark-layer-match.mjs';
 import { loadArkConfigContract } from './lib/config-contract.mjs';
 import { loadEffectiveArkRulesFromDisk } from './lib/effective-contract-load.mjs';
 import { loadArkRulesContract } from './lib/arkrules-contract.mjs';
@@ -112,6 +113,7 @@ import {
   startResidentHookServer,
 } from './lib/resident-hook.mjs';
 import { resolveArchitectureSnapshot } from './lib/architecture-scan.mjs';
+import { projectImporterIndex } from './lib/import-graph-projection.mjs';
 import { runDoctor } from './lib/doctor-plan.mjs';
 import {
   evaluateWriteDesignDelta,
@@ -126,6 +128,23 @@ import {
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
 const arkMcpLauncher = fileURLToPath(new URL('./ark-mcp.mjs', import.meta.url));
 
+/** MCP tool result for a thrown error: its message as text, flagged isError. */
+function toolErrorResult(error) {
+  return {
+    content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+    isError: true,
+  };
+}
+
+/** MCP tool result for a `{ valid }` verdict: pretty JSON text + structuredContent. */
+function validityToolResult(result) {
+  return {
+    content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+    structuredContent: result,
+    isError: !result.valid,
+  };
+}
+
 /**
  * W4 — opt-in hook repair payload.
  * True when CLI `--hook-repair` or env ARK_HOOK_REPAIR is 1/true/yes.
@@ -1266,7 +1285,9 @@ function createResidentDoctorSession(args, config, ts) {
   const resolutionInputs = snapshotInputPaths(snapshot.inputs);
   const ledger = createResidentInputLedger([...after.paths, ...resolutionInputs]);
   if (!ledger.matches([...after.paths, ...resolutionInputs])) return null;
-  return { root: args.root, files: after.files, ledger, resolutionInputs, rules, snapshot };
+  // Same importer index the cold doctor projects (ADR 0037), built once per snapshot.
+  const importGraph = projectImporterIndex(snapshot.facts);
+  return { root: args.root, files: after.files, ledger, resolutionInputs, rules, snapshot, importGraph };
 }
 
 function verifyResidentDoctorSession(session) {
@@ -1287,6 +1308,7 @@ function renderResidentDoctor(session, args, config, ts) {
     ts,
     parseHealth: session.snapshot.result.parseHealth,
     completeness: session.snapshot.result.completeness,
+    architectureFacts: { importGraph: session.importGraph },
     writeJson: (value) => {
       stdout += `${value}\n`;
     },
@@ -2788,16 +2810,9 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         }),
         { root: args.root, acknowledgement, failClosed: true }
       );
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        structuredContent: result,
-        isError: !result.valid,
-      };
+      return validityToolResult(result);
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-        isError: true,
-      };
+      return toolErrorResult(error);
     }
   }
 
@@ -2859,6 +2874,11 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       rules.some((rule) => !rule.allowed && rule.from === layerName && rule.to === to)
     );
     const mayImport = otherNames.filter((name) => !mustNotImport.includes(name));
+    const sliceCatalog = [
+      ...(args.arkRulesSnapshot?.arkRules?.structure ?? []),
+      ...(args.arkRulesSnapshot?.arkRules?.invariants ?? []),
+    ].map((row) => ({ id: row.id, childId: row.provenance?.childId }));
+    const sliceRules = sliceRuleIdsForFile(filePath, rules, sliceCatalog);
     return withGolden({
       filePath,
       layer: layerName,
@@ -2866,6 +2886,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
       ...placementDescriptionFields(layerMeta),
       forbiddenGlobals: layerMeta?.forbiddenGlobals ?? [],
       ...(layerMeta?.mayImportInfrastructure ? { mayImportInfrastructure: true } : {}),
+      ...(sliceRules.length > 0 ? { sliceRules } : {}),
       mayImport,
       mustNotImport,
       note:
@@ -2978,16 +2999,9 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         tsconfig: args.tsconfig,
         manifest: projectManifest,
       });
-      return {
-        content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-        structuredContent: result,
-        isError: !result.valid,
-      };
+      return validityToolResult(result);
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-        isError: true,
-      };
+      return toolErrorResult(error);
     }
   }
 
@@ -3028,10 +3042,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         isError: binding?.status === 'mismatch',
       };
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-        isError: true,
-      };
+      return toolErrorResult(error);
     }
   }
 
@@ -3049,10 +3060,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         structuredContent: payload,
       };
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-        isError: true,
-      };
+      return toolErrorResult(error);
     }
   }
 
@@ -3086,10 +3094,7 @@ export async function runArkMcp({ hookInput, hookRoot } = {}) {
         isError: false,
       };
     } catch (error) {
-      return {
-        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
-        isError: true,
-      };
+      return toolErrorResult(error);
     }
   }
 

package/bin/ark-shared.mjs

@@ -19,10 +19,8 @@ import {
   execCommandParts,
   isPnpmWorkspaceRoot,
   isNpmYarnWorkspaceRoot,
-  normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
-  arkPackageRecoveryCommand,
 } from './lib/package-manager.mjs';
 
 /**
@@ -566,16 +564,8 @@ export function collectForbiddenGlobalUses(ts, sourceFile, forbidden) {
 export {
   globToRegExp,
   patternSpecificity,
-  concreteGlobSegments,
   matchingLayersForRelativePath,
   layerForFile,
-  layerForRelativePath,
-  isEdgeDenied,
-  findDeniedEdgeRule,
-  sliceIdForPath,
-  inferSliceFoldersFromPatterns,
-  DEFAULT_GENERATED_FILE_GLOBS,
-  scanExcludePatterns,
   isScanExcludedRelative,
 } from './ark-layer-match.mjs';
 
@@ -601,7 +591,6 @@ export function looksLikeIntent(value) {
  * Generated CLI load path: bin/lib/remediation.mjs (`npm run generate:cli-pure`).
  */
 export {
-  REMEDIATION_CLASSES,
   classifyRemediation,
   enrichViolationWithFixClass,
 } from './lib/remediation.mjs';
@@ -671,11 +660,8 @@ export {
   arkCommand,
   execCommandParts,
   isPnpmWorkspaceRoot,
-  isNpmYarnWorkspaceRoot,
-  normalizeArkgateInstallSpec,
   packageInstallArgv,
   installDevHint,
-  arkPackageRecoveryCommand,
 };
 
 // FX01–FX02: registry-aware skip lives in upgrade-package-decision (injectable probe).
@@ -684,7 +670,6 @@ export {
   buildPackageInstallSkipPayload,
   formatPackageInstallDecisionHuman,
   compareSemverCore,
-  probeRegistryArkgateLatest,
 } from './lib/upgrade-package-decision.mjs';
 
 export const ARCHETYPE_IDS = [
@@ -880,7 +865,7 @@ const SKIP_DIR_NAMES = new Set([
  * (`isSkippedSourceDir` in scan-files). Start/recommend/discovery must not
  * treat playground, fixtures, scaffolds, or tests as production architecture.
  */
-export const NON_PRODUCT_SOURCE_DIR_NAMES = new Set([
+const NON_PRODUCT_SOURCE_DIR_NAMES = new Set([
   'bench',
   'benches',
   'benchmark',
@@ -902,10 +887,6 @@ export const NON_PRODUCT_SOURCE_DIR_NAMES = new Set([
   'tests',
 ]);
 
-export function isNonProductSourceDirName(name) {
-  return NON_PRODUCT_SOURCE_DIR_NAMES.has(name);
-}
-
 export function isNonProductRelativePath(relPath) {
   return String(relPath)
     .split(/[/\\]/)
@@ -1067,7 +1048,7 @@ function packageRole(rel, pkg) {
 }
 
 /** Path tokens already treated as UI app folders in discoverRepoUnits (root scan). */
-export const UI_PACKAGE_PATH_TOKENS = new Set(['web', 'frontend', 'client', 'ui']);
+const UI_PACKAGE_PATH_TOKENS = new Set(['web', 'frontend', 'client', 'ui']);
 
 const UI_PACKAGE_DEP_NAMES =
   /^(react|react-dom|vue|svelte|preact|solid-js|next|@angular\/core|@sveltejs\/kit)$/i;
@@ -2218,7 +2199,7 @@ export function writeAdoptionPlan(root, recommendation, filename = ADOPTION_PLAN
 
 const __arkSharedDir = path.dirname(fileURLToPath(import.meta.url));
 
-export function defaultPolicyPacksPath() {
+function defaultPolicyPacksPath() {
   return path.resolve(__arkSharedDir, '../templates/policy-packs');
 }
 
@@ -2271,7 +2252,7 @@ export function loadPolicyPackMeta(packId, packsPath = defaultPolicyPacksPath())
  * (`INV-*` invariants keep their prefix: `INV-<LAYER>-…`).
  */
 
-export function kebabLayerName(layerName) {
+function kebabLayerName(layerName) {
   return String(layerName)
     .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
     .replace(/[^A-Za-z0-9]+/g, '-')

package/bin/lib/adoption-stance.mjs

@@ -5,8 +5,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-export const ADOPTION_STANCE_REL = '.ark/adoption-stance.json';
-export const ADOPTION_STANCE_VALUE = 'advisory-only';
+const ADOPTION_STANCE_REL = '.ark/adoption-stance.json';
+const ADOPTION_STANCE_VALUE = 'advisory-only';
 export const ADOPTED_REQUIRED_MERGE = 'required-merge';
 export const ADOPTED_ADVISORY_ACKED = 'advisory-only-acked';
 export const ADOPTED_NOT = 'not-adopted';