arkgate 4.8.23 → 4.8.25

package/bin/lib/prepare-change.mjs

@@ -3,17 +3,31 @@ import path from 'node:path';
 import {
   loadArchitectureChangeMap,
   loadContract,
-  preflightResolvedChange,
+  preflightTrustedResolvedChange,
 } from './analysis-engine.mjs';
 import { createAdapterResult } from './adapter-contract.mjs';
 import { isGovernableSourceFile } from './scan-files.mjs';
 import {
   canonicalizeCandidateChanges,
+  createResolverIngestCache,
   resolveCandidateFacts,
 } from './resolved-candidate-facts.mjs';
 import { effectiveAnalysisConfig } from './analysis-policy.mjs';
 import { isScanExcludedRelative } from '../ark-shared.mjs';
 import { classifyChangeSet, evaluateTeamGate } from './team-parliament.mjs';
+import { arkRulesLoadFailed, loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
+import {
+  coverageOptionsFromConfig,
+  invariantIdsFromCatalog,
+  loadInvariantCoverageInputs,
+} from './invariant-coverage-io.mjs';
+import { catalogHasEnforcedInvariant } from './invariant-coverage.mjs';
+import {
+  declaredCoverageRootsPresent,
+  declaredInvariantTestsPathPresent,
+  scanDemandsInvariantTestsPath,
+} from './invariant-tests-path.mjs';
+import { loadArkRuleFileHints } from './arkrule-file-hints.mjs';
 
 function candidatePath(value) {
   if (typeof value !== 'string' || value.trim() === '') {
@@ -69,7 +83,7 @@ function assertInsideProject(root, relativePath) {
   }
 }
 
-export function normalizeChangeSet(input) {
+function normalizeChangeSet(input) {
   if (!Array.isArray(input)) throw new Error('changes must be an array.');
   return input.map((change, index) => {
     if (!change || typeof change !== 'object' || Array.isArray(change)) {
@@ -88,6 +102,73 @@ export function normalizeChangeSet(input) {
   });
 }
 
+function overlayContents(contents, overlay) {
+  const out = { ...(contents ?? {}) };
+  for (const change of overlay) {
+    if (change.delete === true) delete out[change.path];
+    else out[change.path] = change.content;
+  }
+  return out;
+}
+
+/**
+ * ArkRules engine inputs for base (disk) and candidate (disk + in-memory overlay):
+ * invariant coverage contents and structural file hints, loaded exactly the way
+ * architecture-scan loads them for ark-check. Undefined when ArkRules is off.
+ */
+function arkRulesAnalysisInputs({ root, config, arkRules, baseFacts, candidateFacts, overlay }) {
+  const structure = arkRules?.structure ?? [];
+  const invariants = arkRules?.invariants ?? [];
+  if (structure.length === 0 && invariants.length === 0) return {};
+  const adopted = scanDemandsInvariantTestsPath(root, {});
+  const shared = {
+    ...(adopted ? { adopted: true } : {}),
+    ...(adopted && declaredInvariantTestsPathPresent(root, config.coverage) === false
+      ? { invariantTestsPathPresent: false }
+      : {}),
+    ...(catalogHasEnforcedInvariant(invariants) &&
+    declaredCoverageRootsPresent(root, config.coverage) === false
+      ? { coverageRootsPresent: false }
+      : {}),
+  };
+  const baseCoverage =
+    invariants.length > 0
+      ? loadInvariantCoverageInputs(root, baseFacts, {
+          invariantIds: invariantIdsFromCatalog(arkRules),
+          ...coverageOptionsFromConfig(config),
+        })
+      : undefined;
+  const candidateCoverage = baseCoverage
+    ? {
+        ...baseCoverage,
+        fileContents: overlayContents(baseCoverage.fileContents, overlay),
+        testFiles: (baseCoverage.testFiles ?? []).filter(
+          (file) => !overlay.some((change) => change.delete === true && change.path === file)
+        ),
+      }
+    : undefined;
+  const baseHints = loadArkRuleFileHints(root, baseFacts, arkRules, baseCoverage?.fileContents);
+  // Candidate hints must read the overlay, never the stale on-disk text of a changed file.
+  const candidateHints = loadArkRuleFileHints(
+    root,
+    candidateFacts,
+    arkRules,
+    overlayContents(candidateCoverage?.fileContents ?? {}, overlay)
+  );
+  return {
+    baseAnalysisInputs: {
+      ...shared,
+      ...(baseCoverage ? { coverageInputs: baseCoverage } : {}),
+      ...(baseHints ? { fileHints: baseHints } : {}),
+    },
+    candidateAnalysisInputs: {
+      ...shared,
+      ...(candidateCoverage ? { coverageInputs: candidateCoverage } : {}),
+      ...(candidateHints ? { fileHints: candidateHints } : {}),
+    },
+  };
+}
+
 export function prepareChangeFromRoot({
   root,
   config,
@@ -115,10 +196,16 @@ export function prepareChangeFromRoot({
   for (const change of normalizedChanges) {
     assertInsideProject(root, change.path);
   }
-  const contract = loadContract(
-    effectiveConfig,
-    configSource ?? path.join(root, 'ark.config.json')
-  );
+  const contractSource = configSource ?? path.join(root, 'ark.config.json');
+  // Same Effective Contract as ark-check: ArkRules ride policyHash and the verdict,
+  // and a broken reference fails closed instead of silently dropping the catalog.
+  const arkRulesLoad = loadEffectiveArkRulesFromDisk(root, effectiveConfig);
+  if (arkRulesLoad.errors.length > 0) {
+    throw arkRulesLoadFailed(contractSource, arkRulesLoad.errors);
+  }
+  const contract = loadContract(effectiveConfig, contractSource, {
+    arkRules: arkRulesLoad.arkRules,
+  });
   const loadedChangeMap =
     changeMap === undefined
       ? undefined
@@ -129,24 +216,45 @@ export function prepareChangeFromRoot({
     changes: normalizedChanges,
   });
   for (const change of canonicalChanges) assertGovernedSource(effectiveConfig, change.path);
+  // Files the overlay does not touch are parsed once for both trees.
+  const ingestCache = createResolverIngestCache(contract.config);
   const baseFacts = resolveCandidateFacts({
     root,
     config: contract.config,
     ts,
+    ingestCache,
     ...(tsconfig ? { tsconfig } : {}),
   });
   const candidateFacts = resolveCandidateFacts({
     root,
     config: contract.config,
     ts,
+    ingestCache,
     changes: normalizedOverlayChanges,
     ...(tsconfig ? { tsconfig } : {}),
   });
-  const result = preflightResolvedChange({
+  ingestCache.records.clear();
+  const { baseAnalysisInputs, candidateAnalysisInputs } = arkRulesAnalysisInputs({
+    root,
+    config: effectiveConfig,
+    arkRules: arkRulesLoad.arkRules,
+    baseFacts,
+    candidateFacts,
+    overlay: canonicalizeCandidateChanges({
+      root,
+      config: contract.config,
+      changes: normalizedOverlayChanges,
+    }),
+  });
+  // Both fact sets were created (validated, frozen) by this bundle instance just
+  // above: skip re-validating two whole-project copies of each.
+  const result = preflightTrustedResolvedChange({
     contract,
     baseFacts,
     candidateFacts,
     changes: canonicalChanges,
+    ...(baseAnalysisInputs ? { baseAnalysisInputs } : {}),
+    ...(candidateAnalysisInputs ? { candidateAnalysisInputs } : {}),
     ...(loadedChangeMap ? { changeMap: loadedChangeMap } : {}),
   });
   const completeness =

package/bin/lib/prepare-write.mjs

@@ -8,11 +8,10 @@ import crypto from 'node:crypto';
 import { validateWithAutoPatch } from './auto-patch.mjs';
 import { classifyRemediation, enrichViolationWithFixClass } from './remediation.mjs';
 import {
-  layerDescriptionCaption,
   placementDescriptionFields,
 } from './layer-description.mjs';
 
-export { layerDescriptionCaption, placementDescriptionFields };
+export { placementDescriptionFields };
 
 /**
  * Stable content identity for host commit / cache keys.
@@ -41,6 +40,7 @@ export function buildJudgmentBrief(violations) {
       targetTypeOnlyExports: v.targetTypeOnlyExports,
       namedBindingsTypeOnly: v.namedBindingsTypeOnly,
       peerIsolation: v.peerIsolation ?? v.details?.peerIsolation,
+      reasonId: v.reasonId ?? v.details?.reasonId,
       edgeKind: v.edgeKind ?? v.details?.importKind,
       fromLayer: v.fromLayer,
       toLayer: v.toLayer,

package/bin/lib/presets.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   applyFrameworkLayoutOverlays,
+  cloneArchetypeForLayer,
   createElevenLayerConfig,
   DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
   discoverRepoUnits,
@@ -18,7 +19,7 @@ import { withArkConfigMetadata } from './config-contract.mjs';
 const PRESETS_DIR = path.dirname(fileURLToPath(import.meta.url));
 const ARKRULES_TEMPLATES_DIR = path.join(PRESETS_DIR, '../../templates/arkrules');
 
-export function denyUpward(names) {
+function denyUpward(names) {
   const rules = [];
   for (let i = 0; i < names.length; i += 1) {
     for (let j = i + 1; j < names.length; j += 1) {
@@ -32,7 +33,7 @@ export function denyUpward(names) {
  * peerIsolation matrix: deny only when importer/importee sit under different slices.
  * Covers same-layer and cross-layer pairs (honest DDD / vertical-slice isolation).
  */
-export function peerIsolationEdges(layerNames, sliceFolders, message) {
+function peerIsolationEdges(layerNames, sliceFolders, message) {
   const rules = [];
   for (const from of layerNames) {
     for (const to of layerNames) {
@@ -56,7 +57,7 @@ export function peerIsolationEdges(layerNames, sliceFolders, message) {
 // Framework internals under `src/kernel/**` are NOT application architecture — a broad
 // `src/**/domain/**` would otherwise swallow `src/kernel/domain`. Do NOT use `**/kernel/**`
 // (that carves out legitimate `src/shared/kernel/**` SharedKernel paths).
-export const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
+const FRAMEWORK_INTERNAL_EXCLUDE = ['src/kernel/**', '**/src/kernel/**'];
 
 /**
  * Shared high-spec domain globs. Prefer these over Application/Presentation scatter
@@ -216,18 +217,6 @@ export const APPLICATION_LIB_ORCHESTRATION_PATTERNS = Object.freeze([
   '**/lib/api-handlers/**',
 ]);
 
-/**
- * AR08 — attach lean arkRules map. Keys are always exact project layer names.
- * Sensor roles (domain-structure / orchestration / adapter-thin / generic) are
- * independent of display names so renamed layers still get the right starter.
- */
-export const DEFAULT_ARKRULES_REFS = {
-  DomainModel: 'arkrules/DomainModel.json',
-  ApplicationOrchestration: 'arkrules/ApplicationOrchestration.json',
-  PresentationAdapters: 'arkrules/PresentationAdapters.json',
-  PersistenceAdapters: 'arkrules/PersistenceAdapters.json',
-};
-
 /** Sensor roles used when selecting or synthesizing per-layer templates. */
 export const ARKRULES_SENSOR_ROLES = Object.freeze({
   DOMAIN_STRUCTURE: 'domain-structure',
@@ -240,7 +229,7 @@ export const ARKRULES_SENSOR_ROLES = Object.freeze({
  * Exact-name aliases → sensor role. Prefer this table over heuristics when the
  * project uses a known vocabulary (hexagonal, monorepo field renames, etc.).
  */
-export const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
+const LAYER_SENSOR_ROLE_ALIASES = Object.freeze({
   // Domain / pure model
   DomainModel: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
   Domain: ARKRULES_SENSOR_ROLES.DOMAIN_STRUCTURE,
@@ -371,11 +360,8 @@ export function buildArkRulesTemplateForLayer(layerName, role = resolveLayerSens
     const sourcePath = path.join(ARKRULES_TEMPLATES_DIR, archetype);
     if (fs.existsSync(sourcePath)) {
       try {
-        const parsed = JSON.parse(fs.readFileSync(sourcePath, 'utf8'));
-        return {
-          ...parsed,
-          layer: layerName,
-        };
+        // Unique ids across arkrules/*.json so `--promote <id> --apply` works on the starter.
+        return cloneArchetypeForLayer(JSON.parse(fs.readFileSync(sourcePath, 'utf8')), layerName);
       } catch {
         // Fall through to generic mold.
       }
@@ -450,7 +436,46 @@ export function writeArkRulesTemplates(root, config, { force = false } = {}) {
   return written;
 }
 
-export function presetWithOverlays(baseConfig, root) {
+/**
+ * Deny edges shared by the ports-and-adapters presets after their DomainModel
+ * rules: orchestration never reaches adapters, adapters never reach each other,
+ * and presentation never reaches the domain directly. Fresh objects per call.
+ */
+function portsAndAdaptersRules() {
+  return [
+    { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
+    { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+    { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
+    { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
+    { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+    { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+  ];
+}
+
+/**
+ * UI-surface preset rules: the domain and orchestration stay out of the UI, while
+ * presentation may reach data clients on day one (soft, `message` explains why).
+ * Persistence → Presentation stays denied. Fresh objects per call.
+ * @param {string} presentationToPersistenceMessage
+ */
+function uiSurfaceRules(presentationToPersistenceMessage) {
+  return [
+    { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
+    { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
+    { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
+    { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
+    {
+      from: 'PresentationAdapters',
+      to: 'PersistenceAdapters',
+      allowed: true,
+      message: presentationToPersistenceMessage,
+    },
+    { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+    { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
+  ];
+}
+
+function presetWithOverlays(baseConfig, root) {
   const config = root ? applyFrameworkLayoutOverlays(baseConfig, root) : baseConfig;
   return withArkConfigMetadata(withDefaultArkRules(config));
 }
@@ -513,12 +538,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
         ],
       },
       root
@@ -707,12 +727,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
         ],
       },
       root
@@ -812,24 +827,12 @@ export const ARCHITECTURE_PRESETS = {
             optional: true,
           },
         ],
-        rules: [
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          // Next RSC often imports data clients from routes; deny is ideal but day-one
-          // ui-surface keeps this as a soft guidance edge (allowed) until ports exist —
-          // Persistence → Presentation stays denied when that edge appears.
-          {
-            from: 'PresentationAdapters',
-            to: 'PersistenceAdapters',
-            allowed: true,
-            message:
-              'UI/routes may reach data clients on day one (RSC); prefer application ports as the product grows.',
-          },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-        ],
+        // Next RSC often imports data clients from routes; deny is ideal but day-one
+        // ui-surface keeps this as a soft guidance edge (allowed) until ports exist —
+        // Persistence → Presentation stays denied when that edge appears.
+        rules: uiSurfaceRules(
+          'UI/routes may reach data clients on day one (RSC); prefer application ports as the product grows.'
+        ),
       },
       root
     ),
@@ -980,12 +983,7 @@ export const ARCHITECTURE_PRESETS = {
           { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
           { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
+          ...portsAndAdaptersRules(),
           { from: 'SharedKernel', to: 'DomainModel', allowed: false },
           { from: 'SharedKernel', to: 'ApplicationOrchestration', allowed: false },
           { from: 'SharedKernel', to: 'PresentationAdapters', allowed: false },
@@ -1080,21 +1078,9 @@ export const ARCHITECTURE_PRESETS = {
             optional: true,
           },
         ],
-        rules: [
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          {
-            from: 'PresentationAdapters',
-            to: 'PersistenceAdapters',
-            allowed: true,
-            message:
-              'SPA day-one UI may reach data clients; prefer ports as the product grows.',
-          },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-        ],
+        rules: uiSurfaceRules(
+          'SPA day-one UI may reach data clients; prefer ports as the product grows.'
+        ),
       },
       root
     ),

package/bin/lib/product-copy.mjs

@@ -25,7 +25,7 @@ export const ARKRULES_FIRST_CONTACT_NEXT =
 export const ARKRULES_EMPTY_CATALOG_NEXT =
   'Next: add 1–2 short phrases to invariants[] in the Domain rules file, then ark-check --doctor.';
 
-/** Status-light leftover-design qualifier (was “design-weak”). */
+/** Status-light leftover-design qualifier (was “design-weak”); also the HTML/doctor badge text. */
 export const LEFTOVER_DESIGN_LABEL = 'leftover design work';
 
 /**
@@ -41,14 +41,9 @@ export function operatingModeTitle(mode, leftoverDesign, stewardsUnset) {
   return light;
 }
 
-/** Short HTML/doctor badge text. */
-export const LEFTOVER_DESIGN_BADGE = LEFTOVER_DESIGN_LABEL;
-
 export const POST_GREEN_HUMAN =
   'Imports check out, but the design is still messy. Next: /ark-explore, then one small refactor with /ark-autopilot and your OK.';
 
 export const POST_GREEN_LEDE =
   'Import rules are clean, but leftover design work remains. That does not fail the check — it only means “done” is still wrong until you tidy shape.';
 
-export const HARD_WRITE_HUMAN = 'pre-write block';
-export const ADVISORY_WRITE_HUMAN = 'warning only (not blocked)';

package/bin/lib/project-root.mjs

@@ -16,14 +16,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 
 /** Safety cap so a pathological tree cannot walk forever. */
-export const MAX_CONFIG_WALK_DEPTH = 32;
+const MAX_CONFIG_WALK_DEPTH = 32;
 
 /**
  * True when dir looks like a package-manager workspaces / monorepo root.
  * Used as an upper bound for walk-up (config at this root is accepted; parents are not).
  * @param {string} dir
  */
-export function isWorkspacesPackageRoot(dir) {
+function isWorkspacesPackageRoot(dir) {
   const pkgPath = path.join(dir, 'package.json');
   try {
     if (!fs.statSync(pkgPath, { throwIfNoEntry: false })?.isFile()) {
@@ -55,7 +55,7 @@ export function isWorkspacesPackageRoot(dir) {
  * True when dir is a git worktree root (.git file or directory).
  * @param {string} dir
  */
-export function isGitRoot(dir) {
+function isGitRoot(dir) {
   try {
     const git = path.join(dir, '.git');
     const st = fs.statSync(git, { throwIfNoEntry: false });
@@ -97,7 +97,7 @@ function isFile(absPath) {
 }
 
 /** True when --config is a path (nested or absolute), not a basename to walk. */
-export function configNameIsPath(configName) {
+function configNameIsPath(configName) {
   return (
     typeof configName === 'string' &&
     (path.isAbsolute(configName) || /[\\/]/.test(configName))
@@ -118,7 +118,7 @@ function isInsideRoot(root, target) {
  * @param {string} configName
  * @returns {string | null} absolute config file path
  */
-export function resolveConfigPathCandidate(startDir, configName) {
+function resolveConfigPathCandidate(startDir, configName) {
   if (typeof configName !== 'string' || configName.trim() === '') return null;
   const start = path.resolve(startDir || process.cwd());
   if (path.isAbsolute(configName)) return isFile(configName) ? path.resolve(configName) : null;
@@ -243,76 +243,45 @@ export function resolveEffectiveProjectRoot(startRoot, opts = {}) {
   // Writes adopt walked config root only with explicit opt-in.
   const adoptWalkedRoot = !writeMode || followConfigRoot;
 
+  /** Config found by walk-up (or at start); root follows it unless a plain write. */
+  const walkedResult = (found) => ({
+    root: adoptWalkedRoot ? found.root : start,
+    writeRoot: start,
+    config: configName,
+    configPath: found.configPath,
+    configRoot: found.root,
+    walkedUp: found.walkedUp,
+    configFound: true,
+    writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
+  });
+  /** Everything stays at the start directory. */
+  const startResult = (configPath, configFound) => ({
+    root: start,
+    writeRoot: start,
+    config: configName,
+    configPath,
+    configRoot: start,
+    walkedUp: false,
+    configFound,
+    writeRootFollowedConfig: false,
+  });
+
   if (typeof configName === 'string' && path.isAbsolute(configName)) {
     const found = findNearestArkConfig(start, configName, opts);
-    if (found) {
-      const root = adoptWalkedRoot ? found.root : start;
-      return {
-        root,
-        writeRoot: start,
-        config: configName,
-        configPath: found.configPath,
-        configRoot: found.root,
-        walkedUp: found.walkedUp,
-        configFound: true,
-        writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
-      };
-    }
-    return {
-      root: start,
-      writeRoot: start,
-      config: configName,
-      configPath: configName,
-      configRoot: start,
-      walkedUp: false,
-      configFound: false,
-      writeRootFollowedConfig: false,
-    };
+    return found ? walkedResult(found) : startResult(configName, false);
   }
 
   const localPath = path.join(start, configName);
   try {
     if (fs.statSync(localPath, { throwIfNoEntry: false })?.isFile()) {
-      return {
-        root: start,
-        writeRoot: start,
-        config: configName,
-        configPath: localPath,
-        configRoot: start,
-        walkedUp: false,
-        configFound: true,
-        writeRootFollowedConfig: false,
-      };
+      return startResult(localPath, true);
     }
   } catch {
     // fall through to walk-up
   }
 
   const found = findNearestArkConfig(start, configName, opts);
-  if (found) {
-    const root = adoptWalkedRoot ? found.root : start;
-    return {
-      root,
-      writeRoot: start,
-      config: configName,
-      configPath: found.configPath,
-      configRoot: found.root,
-      walkedUp: found.walkedUp,
-      configFound: true,
-      writeRootFollowedConfig: adoptWalkedRoot && found.walkedUp,
-    };
-  }
-
-  return {
-    root: start,
-    writeRoot: start,
-    config: configName,
-    configPath: localPath,
-    configRoot: start,
-    walkedUp: false,
-    configFound: false,
-    writeRootFollowedConfig: false,
-  };
+  return found ? walkedResult(found) : startResult(localPath, false);
 }
 
 /**

package/bin/lib/remediation.mjs

@@ -8,6 +8,7 @@
  * Pure CLI helper (bin/lib/remediation.mjs). Zero Node I/O.
  */
 
+import { sliceReasonHint } from './diagnostic-catalog.mjs';
 export const REMEDIATION_CLASSES = [
     'mechanical-safe',
     'judgment',
@@ -67,7 +68,15 @@ export function classifyLayerImportKind(target, extra) {
         return 'unknown';
     return 'unknown';
 }
+/** The reason's fix, plus its advisory note only when this finding is a warning. */
+function sliceHintAction(hint, violation) {
+    return violation.failsStrict === false && hint.advisoryNote ? `${hint.fix} ${hint.advisoryNote}` : hint.fix;
+}
 export function layerImportNextAction(violation) {
+    // A nested-wall reason has its own fix. It wins over the generic peer text.
+    const hint = sliceReasonHint(typeof violation.reasonId === 'string' ? violation.reasonId : undefined);
+    if (hint)
+        return `${sliceHintAction(hint, violation)} Then preflight again.`;
     if (violation.typeOnly || violation.targetTypeOnlyExports || violation.namedBindingsTypeOnly) {
         return 'Move the referenced type to a mutually allowed layer, use `import type`, then preflight again.';
     }
@@ -198,6 +207,11 @@ export function deterministicNextAction(violation) {
     switch (violation.ruleId) {
         case 'LAYER_IMPORT_VIOLATION':
             return layerImportNextAction(violation);
+        case 'CONFIG_CHILD_SLICES_VERSION':
+            // The finding already names the pinned file and the version to bump to.
+            return typeof violation.nextAction === 'string' && violation.nextAction.length > 0
+                ? violation.nextAction
+                : 'Bump the pinned arkgate named in the finding to the version it gives, then run Ark again.';
         case 'FORBIDDEN_GLOBAL':
             return `Inject ${violation.target ?? 'the capability'} through a port, test at the public interface, then preflight again.`;
         case 'CAPABILITY_VIOLATION':
@@ -423,11 +437,13 @@ export function enrichViolationWithFixClass(violation) {
                         ? 'The imported module only exports types — use `import type` and place the type in a layer both sides may share.'
                         : 'This is a type-only import — move the type to a layer both sides may share, or relocate the file to match its role.';
             }
-            else if (violation.peerIsolation) {
+            else if (violation.peerIsolation || sliceReasonHint(violation.reasonId)) {
+                const hint = sliceReasonHint(violation.reasonId);
                 enriched.fixClass = 'cross-slice-boundary';
                 enriched.effort = 'medium';
-                enriched.enthusiastHint =
-                    'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
+                enriched.enthusiastHint = hint
+                    ? `${hint.why} ${sliceHintAction(hint, violation)}`
+                    : 'Cross-slice import blocked (peerIsolation). Do not import another feature/context directly — extract shared code to a shared layer, or coordinate via events/ports. Moving code across slices is a judgment call, not a mechanical auto-fix.';
             }
             else {
                 const kind = classifyLayerImportKind(typeof violation.target === 'string' ? violation.target : '', {
@@ -539,6 +555,7 @@ export function enrichViolationWithFixClass(violation) {
         case 'ARKORDER_XI_TTL':
         case 'ARKORDER_STALE_SIGMA':
         case 'ARKORDER_UNVALVED_RELEASE':
+        case 'ARKORDER_STALE_PROPOSAL':
             enriched.fixClass = 'arkorder-usage';
             enriched.effort = 'medium';
             enriched.enthusiastHint =
@@ -560,7 +577,9 @@ export function enrichViolationWithFixClass(violation) {
                                                 ? 'Refresh σ. ξ does not expire.'
                                                 : violation.ruleId === 'ARKORDER_UNVALVED_RELEASE'
                                                     ? 'The choice is already frozen. proposeRelease then apply — do not call release() again with a different value.'
-                                                    : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
+                                                    : violation.ruleId === 'ARKORDER_STALE_PROPOSAL'
+                                                        ? 'That proposal was computed against an older pattern. Propose again, review the new blast radius, then apply.'
+                                                        : 'Call createOrderPlane from arkgate/order in a listed plane root so the app actually freezes a pattern.';
             break;
         default:
             enriched.fixClass = 'review-contract';