arkgate 4.8.21 → 4.8.23

package/bin/lib/doctor-plan.mjs

@@ -21,10 +21,10 @@ import { collectStatesTransitionsResidual } from './states-transitions-presence.
 import { collectStatusTransitionCatalogResidual } from './status-transition-catalog.mjs';
 import { collectNoDomainFrontendResidual } from './no-domain-frontend.mjs';
 import { collectInvariantCoverageResiduals } from './invariant-tests-path.mjs';
+import { anyChildWallAdvisory, anySliceAlias } from '../ark-layer-match.mjs';
 export { printAdrPresenceHint };
 export { printDoctorCompactHuman, printDoctorDetailsHuman };
 export { summarizeRulesUnderContract };
-
 /** Optional S3 dual-match classifier when ark-shared exports it (soft dep for S5 landing). */
 const matchingLayersForRelativePath =
   typeof arkShared.matchingLayersForRelativePath === 'function'
@@ -694,7 +694,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       github: githubForBoundary,
       adoptionStance: stanceFile,
       stewardNudge: doctorAdvisories.stewardNudge,
-      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion),
+      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion), childWallAdvisory: anyChildWallAdvisory(config?.rules), sliceAliasDebt: anySliceAlias(config?.rules),
     });
 
   // Improvement compass: projection only — never feeds ok/valid/goal.met.

package/bin/lib/enforcement-honesty.mjs

@@ -289,6 +289,8 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
  *   operatingMode?: string | null,
  *   activeBlockingViolations?: number | null,
  *   physicalCohesionResidual?: boolean,
+ *   childWallAdvisory?: boolean,
+ *   sliceAliasDebt?: boolean,
  * }} input
  */
 export function physicalCohesionResidualRemains(cohesion) {
@@ -489,6 +491,22 @@ export function buildProductHonesty(input = {}) {
     // Informational only when no enforced arkrule plane — does not alone make unfinished.
   }
 
+  if (input.childWallAdvisory === true) {
+    reasons.push({
+      id: 'child-wall-advisory',
+      message:
+        'A child wall lists siblings as advisory. Recorded crossings stay non-blocking, and a new sibling crossing past that baseline still fails. An enforce list makes those subtrees errors and does not finish the house. This house stays unfinished until siblings is deny.',
+    });
+  }
+
+  if (input.sliceAliasDebt === true) {
+    reasons.push({
+      id: 'slice-alias-debt',
+      message:
+        'Slice aliases are an owed move, not a destination. Aliased files are not finished until they move into the target slice folder.',
+    });
+  }
+
   // EH05: environment residual deny-list (future reason ids stay architecture debt by default).
   const ENVIRONMENT_REASON_IDS = new Set(['soft-write-host', 'native-fail-open']);
 
@@ -683,6 +701,8 @@ export function computeDoctorEnforcementHonesty({
   nativeFailClosed,
   nativeFailClosedPolicy,
   physicalCohesionResidual,
+  childWallAdvisory,
+  sliceAliasDebt,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -741,6 +761,8 @@ export function computeDoctorEnforcementHonesty({
     emptyStewards,
     stewardNudge,
     physicalCohesionResidual,
+    childWallAdvisory,
+    sliceAliasDebt,
   });
   return {
     coverageHonesty,

package/bin/lib/flat-parent-pilot.mjs

@@ -0,0 +1,252 @@
+/**
+ * Doctor suggestion: a universe-level flat file that one child slice imports.
+ * Advisory only. Not a finding, not a verdict, not a config field.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  layerForRelativePath,
+  resolveGovernedSlice,
+  sliceAliasDestination,
+  sliceIdForPath,
+} from '../ark-layer-match.mjs';
+import { destinationKeepsLayerAndSlice } from './physical-cohesion.mjs';
+
+const SPEC_MARKS = [' from "', " from '", ' from `', 'require("', "require('", 'import("', "import('"];
+const EXT = ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.mts', '.cts'];
+
+function ruleKey(rule) {
+  const child = rule?.childSlices;
+  if (!child?.sliceFolders?.length) return '';
+  return [
+    (rule.sliceFolders ?? []).join('\0'),
+    rule.sliceIdentity ?? '',
+    child.sliceFolders.join('\0'),
+    child.sliceIdentity ?? '',
+    (child.commonFolders ?? []).join('\0'),
+  ].join('\n');
+}
+
+function distinctChildRules(rules) {
+  const out = [];
+  const seen = new Set();
+  for (const rule of Array.isArray(rules) ? rules : []) {
+    const key = ruleKey(rule);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    out.push(rule);
+  }
+  return out;
+}
+
+function isFlatParent(rel, rule) {
+  const universe = sliceIdForPath(rel, rule.sliceFolders, rule.sliceIdentity);
+  const raw = sliceIdForPath(rel, rule.childSlices.sliceFolders, rule.childSlices.sliceIdentity);
+  return Boolean(universe && raw && raw.toLowerCase() === universe.toLowerCase());
+}
+
+function withoutComments(text) {
+  let out = '';
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    const n = text[i + 1];
+    if (c === '/' && n === '/') {
+      while (i < text.length && text[i] !== '\n') i += 1;
+      continue;
+    }
+    if (c === '/' && n === '*') {
+      i += 2;
+      while (i + 1 < text.length && !(text[i] === '*' && text[i + 1] === '/')) i += 1;
+      i = Math.min(text.length, i + 2);
+      continue;
+    }
+    out += c;
+    i += 1;
+  }
+  return out;
+}
+
+function relativeSpecifiers(text) {
+  const specs = [];
+  const source = withoutComments(String(text));
+  let i = 0;
+  while (i < source.length) {
+    let at = -1;
+    let mark = '';
+    for (const candidate of SPEC_MARKS) {
+      const found = source.indexOf(candidate, i);
+      if (found !== -1 && (at === -1 || found < at)) {
+        at = found;
+        mark = candidate;
+      }
+    }
+    if (at === -1) break;
+    const quote = mark[mark.length - 1];
+    const start = at + mark.length;
+    const end = source.indexOf(quote, start);
+    if (end === -1) break;
+    const spec = source.slice(start, end);
+    if (spec.startsWith('.')) specs.push(spec);
+    i = end + 1;
+  }
+  return specs;
+}
+
+function resolveRelative(fromFile, spec, fileSet) {
+  const base = fromFile.split('/');
+  base.pop();
+  for (const part of spec.split('/')) {
+    if (part === '' || part === '.') continue;
+    if (part === '..') {
+      if (base.length === 0) return null;
+      base.pop();
+      continue;
+    }
+    base.push(part);
+  }
+  const joined = base.join('/');
+  const names = [joined];
+  for (const ext of EXT) names.push(`${joined}${ext}`, `${joined}/index${ext}`);
+  for (const name of names) {
+    if (fileSet.has(name)) return name;
+  }
+  return null;
+}
+
+function readText(root, rel) {
+  try {
+    return fs.readFileSync(path.join(root, rel), 'utf8');
+  } catch {
+    return '';
+  }
+}
+
+function childImporters(flatFiles, files, rule, root) {
+  const flat = new Set(flatFiles);
+  const known = new Set(files);
+  const importers = new Map();
+  for (const file of files) {
+    const place = resolveGovernedSlice(file, rule);
+    if (!place.childId) continue;
+    for (const spec of relativeSpecifiers(readText(root, file))) {
+      const target = resolveRelative(file, spec, known);
+      if (!target || !flat.has(target) || target === file) continue;
+      let ids = importers.get(target);
+      if (!ids) {
+        ids = new Set();
+        importers.set(target, ids);
+      }
+      ids.add(place.childId);
+    }
+  }
+  return importers;
+}
+
+function basename(rel) {
+  const parts = rel.split('/');
+  return parts[parts.length - 1] ?? rel;
+}
+
+/**
+ * @param {{ root: string, files: string[], rules: object[] | undefined, layers: object[] | undefined }} input
+ * @returns {object | null}
+ */
+export function collectFlatParentPilot(input) {
+  const rules = distinctChildRules(input?.rules);
+  if (rules.length === 0) return null;
+  const files = (Array.isArray(input.files) ? input.files : [])
+    .map((file) => String(file).replace(/\\/g, '/'))
+    .filter((file) => file.length > 0);
+  const layers = input.layers;
+  const moves = [];
+  const seen = new Set();
+  for (const rule of rules) {
+    const flat = files.filter((file) => isFlatParent(file, rule));
+    if (flat.length === 0) continue;
+    const importers = childImporters(flat, files, rule, input.root);
+    for (const file of flat) {
+      if (seen.has(file)) continue;
+      const ids = importers.get(file);
+      if (!ids || ids.size !== 1) continue;
+      const importer = [...ids][0];
+      const destination = sliceAliasDestination(file, importer, rule.childSlices);
+      if (!destination) continue;
+      const destFile = `${destination}/${basename(file)}`;
+      const layer = layerForRelativePath(file, layers);
+      if (!layer || layer !== layerForRelativePath(destFile, layers)) continue;
+      const toPlace = resolveGovernedSlice(destFile, rule);
+      if ((toPlace.childId ?? '') !== importer) continue;
+      const fromPlace = resolveGovernedSlice(file, rule);
+      const keepsSlice = destinationKeepsLayerAndSlice(file, destFile, layers, [rule]);
+      const wallSame =
+        (fromPlace.universeId ?? '') === (toPlace.universeId ?? '') &&
+        (fromPlace.childId ?? '') === (toPlace.childId ?? '');
+      seen.add(file);
+      moves.push({
+        file,
+        importer,
+        destination,
+        layer,
+        keepsLayer: true,
+        keepsSlice,
+        destinationChild: toPlace.childId,
+        agreesWithWall: keepsSlice === wallSame,
+        evidence: `One child imports ${file} (${importer}). Move it into ${destination}. The ${layer} layer stays. This is a suggestion with that importer as its evidence.`,
+      });
+    }
+  }
+  if (moves.length === 0) return null;
+  moves.sort((left, right) => (left.file < right.file ? -1 : left.file > right.file ? 1 : 0));
+  return {
+    advisory: true,
+    notAScore: true,
+    proposed: true,
+    applied: false,
+    neverMechanicalSafe: true,
+    moves,
+  };
+}
+
+/** One pilot candidate per move. Appended after pattern bets and the reshape card. */
+export function flatParentCandidates(section) {
+  if (!section || !Array.isArray(section.moves)) return [];
+  return section.moves
+    .filter((move) => move && typeof move.file === 'string' && move.file.length > 0)
+    .map((move) => ({
+      source: 'flat-parent',
+      target: move.file,
+      move: typeof move.evidence === 'string' ? move.evidence : `Move ${move.file} into its one importing child. This is a suggestion.`,
+      moveSample: [{ from: move.file, to: `${move.destination}/${basename(move.file)}` }],
+      successSignal: 're-run doctor: this file is no longer a single-importer flat parent',
+      killSwitch: 'leave the file where it is',
+      doNot: [
+        'a suggestion with one importer as its evidence',
+        'leave a file in place when two children import it',
+        'one pilot at a time; re-doctor before the next card',
+        'never weaken the contract to make a move pass',
+      ],
+    }));
+}
+
+export function printFlatParentPilot(section, io) {
+  const moves = Array.isArray(section?.moves) ? section.moves : [];
+  if (moves.length === 0) return;
+  console.log('');
+  console.log(io.color.bold('Flat parent files (suggestion)'));
+  for (const move of moves.slice(0, 5)) io.line(io.warn, move.evidence);
+  if (moves.length > 5) io.line(' ', io.color.dim(`…(+${moves.length - 5} more in doctor JSON)`));
+  io.line(' ', io.color.dim('suggestion only — one importer is the evidence; the gate verdict is unchanged'));
+}
+
+export function flatParentPilotHtml(section, escape) {
+  const moves = Array.isArray(section?.moves) ? section.moves : [];
+  if (moves.length === 0) return '';
+  const esc = typeof escape === 'function' ? escape : (value) => String(value);
+  const items = moves
+    .slice(0, 5)
+    .map((move) => `<li>${esc(move.evidence ?? '')}</li>`)
+    .join('');
+  const more = moves.length > 5 ? `<p class="muted">…(+${moves.length - 5} more in doctor JSON)</p>` : '';
+  return `<section class="section card" data-advisory="flatParentPilot"><h2>Flat parent files <span class="muted">(suggestion — one importer is the evidence; not a score; the verdict is unchanged)</span></h2><ul>${items}</ul>${more}</section>`;
+}

package/bin/lib/html-report-advisories.mjs

@@ -13,6 +13,7 @@ import { formatRulesUnderContractHtml } from './rules-under-contract.mjs';
 import { formatArkRunHtml } from './ark-run-report.mjs';
 import { formatArkOrderHtml } from './ark-order-report.mjs';
 import { primaryImprovementCompassNextAction } from './improvement-compass.mjs';
+import { flatParentPilotHtml } from './flat-parent-pilot.mjs';
 
 // htmlEscape is injected by the caller (html-report.mjs) — importing it back
 // would be a dependency cycle, and the repo's own gate blocks that. The
@@ -355,6 +356,7 @@ export function renderAdvisorySections(advisories, escape) {
     deepModuleCoachHtml(advisories.deepModuleCoach),
     stewardNudgeHtml(advisories.stewardNudge),
     sliceIdentityHtml(advisories.sliceIdentity),
+    flatParentPilotHtml(advisories.flatParentPilot, esc),
     contractHealthHtml(advisories.contractHealth),
     ambientStateHtml(advisories.ambientState),
     physicalCohesionHtml(advisories.physicalCohesion),

package/bin/lib/html-report-depth.mjs

@@ -28,6 +28,7 @@ import { buildDeepModuleCoachAdvisory } from './deep-module-coach.mjs';
 import { computePhysicalCohesion } from './physical-cohesion.mjs';
 import { computeReshapeDecisionMemory } from './reshape-decisions.mjs';
 import { POST_GREEN_LEDE, operatingModeTitle } from './product-copy.mjs';
+import { anyChildWallAdvisory, anySliceAlias } from '../ark-layer-match.mjs';
 
 function esc(value) {
   return String(value)
@@ -174,7 +175,8 @@ export function buildReportDepthPayload(
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
-    physicalCohesionResidual: physicalCohesionResidualRemains(physicalCohesion),
+    physicalCohesionResidual: physicalCohesionResidualRemains(physicalCohesion), childWallAdvisory: anyChildWallAdvisory(config?.rules),
+    sliceAliasDebt: anySliceAlias(config?.rules),
   });
   // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
   const baselineStale =

package/bin/lib/invariant-coverage.mjs

@@ -133,7 +133,7 @@ function matchTestTitle(content, id) {
     if (!id)
         return undefined;
     const escaped = escapeRegExp(id);
-    const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*(['"\`])([^'"\`]*${escaped}[^'"\`]*)\\1`, 'i');
+    const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*(['"\`])((?:(?!\\1)[^\\\\]|\\\\.)*?${escaped}(?:(?!\\1)[^\\\\]|\\\\.)*?)\\1`, 'i');
     const match = re.exec(maskNonCode(content, false));
     const title = match?.[2];
     return title === undefined ? undefined : title;
@@ -160,7 +160,7 @@ function declarationShape(content, name) {
         },
         {
             shape: 'const',
-            source: `(?:^|[\\s;{}])export\\s+(?:const|let|var)\\s+${n}\\s*=`,
+            source: `(?:^|[\\s;{}])export\\s+(?:const|let|var)\\s+${n}(?:\\s*:(?:[^=]|=>)+?)?\\s*=(?!>)`,
         },
         {
             shape: 'type',
@@ -382,15 +382,36 @@ function rankCoverage(invariant, files, scanTests = true) {
             }
         }
     }
-    const best = testTitle
+    let best = testTitle
         ? { kind: 'test-title', file: testTitle.file, title: testTitle.title }
         : declaration
             ? { kind: 'declaration', file: declaration.file, shape: declaration.shape }
             : mention
                 ? { kind: 'mention-only', file: mention.file, context: mention.context }
                 : { kind: 'none' };
+    if (best.kind === 'mention-only' &&
+        best.context === 'comment' &&
+        needle &&
+        symbolInCodeElsewhere(files.fileContents, tests, needle.name, best.file)) {
+        best = { kind: 'declaration-miss', symbol: needle.name };
+    }
     return { best, ...(testTitle ? { testTitle } : {}), ...(declaration ? { declaration } : {}) };
 }
+/** True when `name` survives comment/string masking in some non-test file other than `mentionFile`. */
+function symbolInCodeElsewhere(fileContents, tests, name, mentionFile) {
+    const needle = new RegExp(`(?:^|[^A-Za-z0-9_$])${escapeRegExp(name)}(?=$|[^A-Za-z0-9_$])`);
+    const mention = normalizePath(mentionFile);
+    for (const file of Object.keys(fileContents)) {
+        if (tests.has(normalizePath(file)) || normalizePath(file) === mention)
+            continue;
+        const content = fileContents[file];
+        if (!content)
+            continue;
+        if (needle.test(maskNonCode(content, true)))
+            return true;
+    }
+    return false;
+}
 /**
  * Best coverage evidence for `invariant` in `files`.
  * test-title beats a declaration; a declaration beats a bare mention; a bare
@@ -409,6 +430,7 @@ export function countsAsCoverage(ev) {
         case 'declaration':
             return true;
         case 'mention-only':
+        case 'declaration-miss':
         case 'none':
             return false;
     }
@@ -434,6 +456,8 @@ export function describeCoverage(invariant, ev) {
             return `found \`${ev.shape} ${declaredLabel(invariant)}\` in ${ev.file}`;
         case 'mention-only':
             return `${invariant.id} appears only in ${mentionWhere(ev.context)} in ${ev.file}; put it in a describe/it title`;
+        case 'declaration-miss':
+            return `no declaration matched \`${ev.symbol}\``;
         case 'none':
             return 'no scanned test names it in a describe/it title and no declared symbol was found';
     }

package/bin/lib/physical-cohesion.mjs

@@ -15,7 +15,7 @@
  * as W01 layer roles: a miss costs a warning line, never a verdict.
  */
 import path from 'node:path';
-import { layerForRelativePath, sliceIdForPath } from '../ark-layer-match.mjs';
+import { layerForRelativePath, resolveGovernedSlice } from '../ark-layer-match.mjs';
 
 /** ADR 0010 D3 — corpus-calibrated, fixed. */
 const CLUSTER_MIN = 40;
@@ -135,23 +135,21 @@ function anchorIsConsolidationSubtree(anchor, concept) {
   return String(anchor).split('/').some((part) => part === concept);
 }
 
-function declaredSliceFolders(rules) {
-  const out = [];
-  const seen = new Set();
+/**
+ * Layer must match. Universe id and child id must match on every rule, using
+ * the same resolver as the walls (`sliceIdentity` included). A missing child
+ * id is universe common. Two children of one universe do not keep the slice.
+ */
+export function destinationKeepsLayerAndSlice(fromRel, toRel, layers, rules) {
+  if (layerForRelativePath(fromRel, layers) !== layerForRelativePath(toRel, layers)) return false;
   for (const rule of Array.isArray(rules) ? rules : []) {
-    const folders = Array.isArray(rule?.sliceFolders) ? rule.sliceFolders : [];
-    for (const folder of folders) {
-      if (typeof folder !== 'string' || folder.length === 0 || seen.has(folder.toLowerCase())) continue;
-      seen.add(folder.toLowerCase());
-      out.push(folder);
-    }
+    if (!rule || typeof rule !== 'object') continue;
+    const from = resolveGovernedSlice(fromRel, rule);
+    const to = resolveGovernedSlice(toRel, rule);
+    if ((from.universeId ?? '') !== (to.universeId ?? '')) return false;
+    if ((from.childId ?? '') !== (to.childId ?? '')) return false;
   }
-  return out;
-}
-
-function destinationKeepsLayerAndSlice(fromRel, toRel, layers, sliceFolders) {
-  return layerForRelativePath(fromRel, layers) === layerForRelativePath(toRel, layers)
-    && sliceIdForPath(fromRel, sliceFolders) === sliceIdForPath(toRel, sliceFolders);
+  return true;
 }
 
 function withheldPilot(concept, note) {
@@ -168,7 +166,7 @@ export function computeReshapePilot(cohesion, files, root, contract) {
   const top = cohesion?.findings?.[0];
   if (!top) return null;
   const layers = contract?.layers;
-  const sliceFolders = declaredSliceFolders(contract?.rules);
+  const rules = Array.isArray(contract?.rules) ? contract.rules : [];
   // Full anchor map: the finding's anchors are display-filtered (>= MIRROR_MIN).
   const byAnchor = new Map();
   const relOf = (abs) => path.relative(root, abs).split(path.sep).join('/');
@@ -193,7 +191,7 @@ export function computeReshapePilot(cohesion, files, root, contract) {
       const ranked = classifyPhysical(rel);
       if (!ranked || ranked.concept !== top.concept || ranked.anchor !== anchor.path) return false;
       const to = `${targetDir}/${rel.split('/').at(-1)}`;
-      return destinationKeepsLayerAndSlice(rel, to, layers, sliceFolders);
+      return destinationKeepsLayerAndSlice(rel, to, layers, rules);
     }).sort().map((rel) => ({ from: rel, to: `${targetDir}/${rel.split('/').at(-1)}` }));
     if (legal.length > 0) legalAnchors.push({ ...anchor, targetDir, legal });
   }

package/bin/lib/pilot-loop.mjs

@@ -9,6 +9,7 @@ import {
   buildPatternBetsFromSmells,
   isNonProductionPilotPath,
 } from './design-smells.mjs';
+import { flatParentCandidates } from './flat-parent-pilot.mjs';
 
 /** Stable product id for JSON / tests. */
 export const PILOT_LOOP_ID = 'one-pilot-redoctor';
@@ -181,7 +182,7 @@ export function formatExtractionCard(card) {
  * One proposed pilot. The loop does not know designWeak or which sensor
  * produced the card — only this list.
  *
- * @typedef {'pattern-bet' | 'reshape'} PilotSource
+ * @typedef {'pattern-bet' | 'reshape' | 'flat-parent'} PilotSource
  * @typedef {{
  *   source: PilotSource,
  *   target: string,
@@ -243,10 +244,15 @@ function extractionCardFromCandidate(candidate) {
     .filter((entry) => typeof entry === 'string' && entry.length > 0)
     .slice(0, 8);
   const reshape = candidate.source === 'reshape';
+  const flatParent = candidate.source === 'flat-parent';
   return {
     id: PILOT_LOOP_ID,
-    patternBetId: reshape ? `reshape:${candidate.target}` : `pattern-b:${candidate.target}`,
-    smellId: reshape ? 'physical-cohesion' : 'unknown',
+    patternBetId: flatParent
+      ? `flat-parent:${candidate.target}`
+      : reshape
+        ? `reshape:${candidate.target}`
+        : `pattern-b:${candidate.target}`,
+    smellId: flatParent ? 'flat-parent' : reshape ? 'physical-cohesion' : 'unknown',
     pilot: candidate.target,
     pilotTarget: candidate.target,
     evidence,
@@ -262,9 +268,11 @@ function extractionCardFromCandidate(candidate) {
     loopStep: 'one-pilot',
     reDoctor: 'ark-check --doctor --json',
     rePlan: 'ark-check --plan --json',
-    next: reshape
-      ? '/ark-loop (one reshape pilot) | re-doctor after pilot'
-      : '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
+    next: flatParent
+      ? '/ark-loop (one flat-parent suggestion) | re-doctor after the move'
+      : reshape
+        ? '/ark-loop (one reshape pilot) | re-doctor after pilot'
+        : '/ark-autopilot (one cluster / one B pilot) | re-doctor after pilot',
   };
 }
 
@@ -272,8 +280,10 @@ function extractionCardFromCandidate(candidate) {
  * Normalize design-weak pattern bets and a proposed reshape pilot into one list.
  * Pattern bets stay in selector rank (best first) and are omitted unless
  * design fitness is design-weak, so that path keeps today's card. A reshape
- * card is appended when physical cohesion proposes one. Doctor builds this
- * list after advisories, so the loop never depends on call order.
+ * card is appended when physical cohesion proposes one. A flat-parent move
+ * is appended after that: one file with one importer waits behind a card the
+ * loop already promised. Doctor builds this list after advisories, so the
+ * loop never depends on call order.
  *
  * @param {{
  *   designWeak?: boolean,
@@ -317,6 +327,9 @@ export function collectPilotCandidates(designFitness = {}, advisories = {}) {
       ...(Array.isArray(card.doNot) ? { doNot: card.doNot } : {}),
     });
   }
+  for (const candidate of flatParentCandidates(advisories?.flatParentPilot)) {
+    candidates.push(candidate);
+  }
   return candidates;
 }
 

package/bin/lib/team-parliament-io.mjs

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
+import { applyAdvisorySiblingRatchet } from '../ark-layer-match.mjs';
 import {
   baselineKeysFromDocument,
   classifyBaselineKeyDelta,
@@ -321,7 +322,8 @@ export function applyAgainstRatchet({
 }) {
   const baseRaw = readJsonMaybe(gitShowText(root, againstRef, '.ark-baseline.json'));
   const baseKeys = new Set(baselineKeysFromDocument(baseRaw));
-  const vsBaseActive = violations.filter((_, index) => !baseKeys.has(occurrenceKeys[index]));
+  const judged = baseRaw ? applyAdvisorySiblingRatchet(violations, occurrenceKeys, baseKeys) : violations;
+  const vsBaseActive = judged.filter((_, index) => !baseKeys.has(occurrenceKeys[index]));
   const changedSet = new Set(changedPaths ?? []);
   const activeViolations = changed
     ? vsBaseActive.filter((violation) =>
@@ -330,7 +332,7 @@ export function applyAgainstRatchet({
     : vsBaseActive;
   return {
     activeViolations,
-    suppressed: violations.filter((violation) => !activeViolations.includes(violation)),
+    suppressed: judged.filter((violation) => !activeViolations.includes(violation)),
   };
 }
 

package/dist/{configTypes-CTELo87-.d.ts → configTypes-Bbf_MFGe.d.ts}

@@ -67,8 +67,42 @@ type ArkConfigRule = {
     sharedRoots?: string[];
     /** Directed slice→slice edges the repo declares on purpose. */
     allowedCrossSlice?: ArkConfigCrossSliceEdge[];
-    /** When `"deny"`, a declared shared root may not import a slice. */
-    sharedImportsSlice?: 'deny';
+    /**
+     * `"deny"` blocks a shared root from importing a slice.
+     * `"deny-cross-parent"` leaves that hop allowed and asks the whole-graph
+     * check to report a slice that reaches another universe through shared.
+     */
+    sharedImportsSlice?: 'deny' | 'deny-cross-parent';
+    /**
+     * Optional inner wall. Absent keeps today's universe-wall output.
+     * `siblings` defaults to deny. An object keeps that default and lists enforced subtrees.
+     * `parentMayImportChild` defaults to false.
+     */
+    childSlices?: ArkConfigChildSlices;
+};
+type ArkConfigChildSlices = {
+    sliceFolders: string[];
+    sliceIdentity?: ArkConfigSliceIdentity;
+    commonFolders?: string[];
+    siblings?: 'deny' | 'advisory' | {
+        default: 'deny' | 'advisory';
+        enforce?: string[];
+    };
+    parentMayImportChild?: boolean;
+    /**
+     * Directed child-slice allowances. `*` is one whole path segment.
+     * Clears a sibling crossing only. The universe `allowedCrossSlice` does not read this list.
+     */
+    allowedCrossSlice?: ArkConfigCrossSliceEdge[];
+    /**
+     * Files outside the slice trees, borrowed onto a child id until they move.
+     * `to` is the universe id plus one child segment.
+     */
+    sliceAliases?: ArkConfigSliceAlias[];
+};
+type ArkConfigSliceAlias = {
+    from: string;
+    to: string;
 };
 type ArkConfigCrossSliceEdge = {
     from: string;