arkgate 4.8.20 → 4.8.22

package/bin/lib/upgrade-command.mjs

@@ -10,6 +10,13 @@ import {
   formatPackageInstallDecisionHuman,
 } from '../ark-shared.mjs';
 import { describePackageVersionDualTruth } from './field-install.mjs';
+import {
+  exitCodeFor,
+  formatBlockedAssets,
+  formatPostUpgradeHuman,
+  runPostUpgradeVerification,
+  upgradeOutcome,
+} from './upgrade-outcome.mjs';
 import { __packageRoot } from './gate-files.mjs';
 import {
   applyManagedUpgrade,
@@ -316,15 +323,13 @@ export function buildUpgradeNextCommand(args, planDigest) {
   return arkCommand(args.root, 'arkgate', argsStr);
 }
 
-function verify(root, json, arkCheck, runArkCheck) {
-  const args = ['--root', root, '--config', 'ark.config.json', '--strict-merge'];
-  if (!json) return { exitCode: runArkCheck(args, { cwd: root }) };
-  const result = spawnSync(process.execPath, [arkCheck, ...args, '--json'], {
-    cwd: root,
-    stdio: ['ignore', 'pipe', 'pipe'],
-    encoding: 'utf8',
-  });
-  return { exitCode: result.status ?? 1, stderr: result.stderr?.trim() || undefined };
+function stampBlockedNextCommands(plan, args) {
+  if ((plan?.summary?.blocked ?? 0) === 0) return plan;
+  const command = buildUpgradeNextCommand({ ...args, acceptConflicts: true }, plan.planDigest);
+  for (const asset of plan.assets ?? []) {
+    if (asset.blocked) asset.nextCommand = command;
+  }
+  return plan;
 }
 
 function runProjectLocalCli({ root, script, argv }) {
@@ -544,11 +549,14 @@ export function runUpgradeCommand(args, dependencies) {
     }).status ?? 1;
   }
 
-  const plan = planManagedUpgrade(root, {
-    tools: args.tools,
-    acceptConflicts: args.acceptConflicts,
-    refreshSkills: args.refreshSkills === true,
-  });
+  const plan = stampBlockedNextCommands(
+    planManagedUpgrade(root, {
+      tools: args.tools,
+      acceptConflicts: args.acceptConflicts,
+      refreshSkills: args.refreshSkills === true,
+    }),
+    args
+  );
   if (!args.apply) {
     const wouldWrite = plan.summary?.wouldWrite ?? 0;
     const blocked = plan.summary?.blocked ?? 0;
@@ -577,11 +585,14 @@ export function runUpgradeCommand(args, dependencies) {
       );
     } else {
       renderManagedUpgrade(plan, {
-        next: needsApply
-          ? args.install
-            ? `Update the package and recompute this preview with: ${command}`
-            : `Apply the exact preview with: ${command}`
-          : undefined,
+        next:
+          blocked > 0
+            ? undefined
+            : needsApply
+              ? args.install
+                ? `Update the package and recompute this preview with: ${command}`
+                : `Apply the exact preview with: ${command}`
+              : undefined,
         skillDrift,
         hostSelection: hostHonesty,
       });
@@ -600,54 +611,80 @@ export function runUpgradeCommand(args, dependencies) {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error(message);
-    return 2;
+    return exitCodeFor(upgradeOutcome({ error }));
   }
   if (applied.blocked) {
+    stampBlockedNextCommands(applied, args);
     const command = buildUpgradeNextCommand(
       { ...args, acceptConflicts: true },
       applied.planDigest
     );
+    const refusal = formatBlockedAssets(applied, { refused: true }).join('\n');
+    console.error(refusal);
     if (args.json) {
       console.log(
         managedUpgradeJson(applied, {
           blocked: true,
+          outcome: 'blocked',
           reasonCode: applied.reasonCode ?? 'managed-consent-required',
           nextCommand: command,
         })
       );
     } else {
-      renderManagedUpgrade(applied, {
-        next: 'Preview again with --accept-conflicts, then use that preview\'s exact next command.',
-      });
+      renderManagedUpgrade(applied, { refused: true });
     }
-    return 1;
+    return exitCodeFor(upgradeOutcome({ blocked: true }));
   }
   if (applied.nothingToApply && !applied.applied) {
-    if (args.json) console.log(JSON.stringify(applied, null, 2));
+    const idle = upgradeOutcome({ nothingToApply: true, applied: false });
+    if (args.json) console.log(JSON.stringify({ ...applied, outcome: idle.kind }, null, 2));
     else {
       renderManagedUpgrade(applied);
       console.log('No managed content writes pending.');
     }
-    return 0;
+    return exitCodeFor(idle);
   }
-  const verification = args.strict
-    ? { mode: 'strict-merge', ...verify(root, args.json, dependencies.arkCheck, dependencies.runArkCheck) }
-    : { mode: 'skipped', exitCode: 0 };
+  const postUpgrade = runPostUpgradeVerification(root, {
+    strict: args.strict,
+    arkCheck: dependencies.arkCheck,
+    packageVersion: dependencies.cliVersion,
+    ...(dependencies.checkResult ? { checkResult: dependencies.checkResult } : {}),
+    ...(typeof dependencies.spawnArchitectureCheck === 'function'
+      ? { checkResult: dependencies.spawnArchitectureCheck(root) }
+      : {}),
+  });
+  const outcome = upgradeOutcome({ applied: true, postUpgrade });
+  const verification = {
+    mode: postUpgrade.mode,
+    exitCode: postUpgrade.exitCode,
+    ...(postUpgrade.stderr ? { stderr: postUpgrade.stderr } : {}),
+  };
   const dualTruth = describePackageVersionDualTruth(root);
   const skillDrift = buildSkillDriftSummary(applied);
   const hostHonesty = buildHostSelectionHonesty(applied);
   // FX05: post-upgrade verification block (advisory, notAScore).
   const postUpgradeChecks = buildPostUpgradeChecks(root, {
     cliVersion: dependencies.cliVersion,
-    verification,
+    verification: {
+      ...verification,
+      verdict: postUpgrade.verdict,
+      failing: postUpgrade.failing,
+    },
     dualTruth,
   });
+  const postUpgradePayload = {
+    verdict: postUpgrade.verdict,
+    failing: postUpgrade.failing,
+    behaviorChanges: postUpgrade.behaviorChanges,
+  };
   if (args.json) {
     console.log(
       JSON.stringify(
         {
           ...applied,
+          outcome: outcome.kind,
           verification,
+          postUpgrade: postUpgradePayload,
           skillDrift,
           hostSelection: hostHonesty,
           postUpgradeChecks,
@@ -673,6 +710,7 @@ export function runUpgradeCommand(args, dependencies) {
     );
   } else {
     renderManagedUpgrade(applied, { skillDrift, hostSelection: hostHonesty });
+    for (const line of formatPostUpgradeHuman(postUpgrade)) console.log(line);
     if (!args.strict) console.log('Architecture verification skipped (--no-strict).');
     if (args.install === false || dualTruth.dualTruth) {
       console.log(
@@ -690,5 +728,5 @@ export function runUpgradeCommand(args, dependencies) {
       console.log(`  [note] mcp: ${postUpgradeChecks.mcpNote}`);
     }
   }
-  return verification.exitCode;
+  return exitCodeFor(outcome);
 }

package/bin/lib/upgrade-outcome.mjs

@@ -0,0 +1,359 @@
+/**
+ * UpgradeOutcome — one value for `upgrade --apply`.
+ *
+ * Sketch (D2). Callers see one object and one exit mapping. Gitignore
+ * detection, rule aggregation, and version-note lookup stay in here.
+ *
+ *   classifyManagedAsset({ ..., gitignored }) →
+ *     { state: 'absent-local', requiresConsent: false } when recorded + gitignored + missing
+ *
+ *   runPostUpgradeVerification(root) →
+ *     { verdict: 'green'|'red'|'skipped', failing: [{ ruleId, count, sample }], behaviorChanges: string[] }
+ *
+ *   exitCodeFor(outcome) →
+ *     0 applied+green (also nothing-to-apply / verification skipped)
+ *     3 applied+red
+ *     2 blocked
+ *     1 error
+ *
+ * JSON fields on the existing upgrade payload are additive (`outcome`, `postUpgrade`,
+ * per-asset `reason` / `nextCommand`, state `absent-local`).
+ */
+import { spawnSync } from 'node:child_process';
+
+import { behaviorChangeLines } from './upgrade-behavior-changes.mjs';
+
+/**
+ * @typedef {'applied-green'|'applied-skipped'|'applied-red'|'blocked'|'error'|'nothing'|'preview'} UpgradeOutcomeKind
+ * @typedef {{ ruleId: string, count: number, sample: string }} FailingRule
+ * @typedef {{
+ *   verdict: 'green'|'red'|'skipped',
+ *   failing: FailingRule[],
+ *   behaviorChanges: string[],
+ *   mode: 'strict-merge'|'skipped',
+ *   exitCode: number,
+ *   stderr?: string,
+ * }} PostUpgradeVerification
+ * @typedef {{
+ *   kind: UpgradeOutcomeKind,
+ *   applied: boolean,
+ *   blocked: boolean,
+ *   postUpgrade: PostUpgradeVerification|null,
+ *   error?: string,
+ * }} UpgradeOutcome
+ */
+
+export const ABSENT_LOCAL_REASON =
+  'Recorded managed file is missing and gitignored (per-machine file). Recreated without consent.';
+
+/**
+ * @param {string} state
+ * @returns {string}
+ */
+export function blockedAssetReason(state) {
+  if (state === 'missing') {
+    return 'Recorded managed file is missing and is not gitignored. Apply will not recreate a deleted file without consent.';
+  }
+  if (state === 'conflicted') {
+    return 'Managed base and local edits both changed. Apply will not overwrite without consent.';
+  }
+  return 'Apply needs consent before changing this managed file.';
+}
+
+/**
+ * Paths git would ignore. Not a git repo, or git missing → empty set
+ * (fail closed toward consent). Global excludes are not consulted.
+ *
+ * @param {string} root
+ * @param {string[]} relativePaths
+ * @returns {Set<string>}
+ */
+export function gitignoredPathSet(root, relativePaths) {
+  const paths = [...new Set(relativePaths.filter((entry) => typeof entry === 'string' && entry.length > 0))];
+  if (paths.length === 0) return new Set();
+  let result;
+  try {
+    result = spawnSync(
+      'git',
+      ['-c', 'core.excludesFile=/dev/null', 'check-ignore', '-z', '--stdin'],
+      {
+        cwd: root,
+        input: `${paths.join('\0')}\0`,
+        encoding: 'utf8',
+        timeout: 5000,
+        env: {
+          ...process.env,
+          GIT_CONFIG_NOSYSTEM: '1',
+          GIT_CONFIG_GLOBAL: '/dev/null',
+        },
+      }
+    );
+  } catch {
+    return new Set();
+  }
+  if (!result || result.error || (result.status !== 0 && result.status !== 1)) return new Set();
+  const ignored = new Set();
+  for (const entry of String(result.stdout ?? '').split('\0')) {
+    if (entry) ignored.add(entry);
+  }
+  return ignored;
+}
+
+/**
+ * @param {unknown} check
+ * @returns {FailingRule[]}
+ */
+export function aggregateFailingRules(check) {
+  const violations = Array.isArray(check?.violations) ? check.violations : [];
+  /** @type {Map<string, FailingRule>} */
+  const groups = new Map();
+  for (const violation of violations) {
+    if (!violation || typeof violation !== 'object') continue;
+    if (violation.failsStrict === false) continue;
+    const ruleId = typeof violation.ruleId === 'string' && violation.ruleId.trim()
+      ? violation.ruleId.trim()
+      : 'UNKNOWN';
+    const existing = groups.get(ruleId) ?? { ruleId, count: 0, sample: '' };
+    existing.count += 1;
+    if (!existing.sample) existing.sample = sampleForViolation(violation, ruleId);
+    groups.set(ruleId, existing);
+  }
+  return [...groups.values()].sort(
+    (left, right) => right.count - left.count || left.ruleId.localeCompare(right.ruleId)
+  );
+}
+
+/**
+ * @param {Record<string, unknown>} violation
+ * @param {string} ruleId
+ */
+function sampleForViolation(violation, ruleId) {
+  const file = typeof violation.file === 'string'
+    ? violation.file
+    : typeof violation.path === 'string'
+      ? violation.path
+      : '';
+  const line = Number.isInteger(violation.line) ? `:${violation.line}` : '';
+  const where = file ? `${file}${line}` : '';
+  const message = typeof violation.message === 'string' ? violation.message.trim() : '';
+  const sample = [where, message].filter(Boolean).join(' — ') || ruleId;
+  return sample.length > 180 ? `${sample.slice(0, 177)}...` : sample;
+}
+
+/**
+ * @param {string} stdout
+ * @returns {Record<string, unknown>|null}
+ */
+export function parseCheckStdout(stdout) {
+  const text = typeof stdout === 'string' ? stdout.trim() : '';
+  if (!text) return null;
+  try {
+    const parsed = JSON.parse(text);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  } catch {
+    const start = text.indexOf('{');
+    const end = text.lastIndexOf('}');
+    if (start === -1 || end <= start) return null;
+    try {
+      const parsed = JSON.parse(text.slice(start, end + 1));
+      return parsed && typeof parsed === 'object' ? parsed : null;
+    } catch {
+      return null;
+    }
+  }
+}
+
+/**
+ * @param {string} root
+ * @param {string} arkCheck
+ * @returns {{ exitCode: number, stdout: string, stderr: string }}
+ */
+function spawnArchitectureCheck(root, arkCheck) {
+  if (typeof arkCheck !== 'string' || !arkCheck) {
+    return { exitCode: 1, stdout: '', stderr: 'architecture check binary is missing' };
+  }
+  const result = spawnSync(
+    process.execPath,
+    [arkCheck, '--root', root, '--config', 'ark.config.json', '--strict-merge', '--json'],
+    {
+      cwd: root,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+    }
+  );
+  return {
+    exitCode: result.status ?? 1,
+    stdout: result.stdout ?? '',
+    stderr: result.stderr ?? '',
+  };
+}
+
+/**
+ * Structured post-upgrade verification. Reuses check JSON (rule ids), and
+ * attaches behavior-change lines from the shipped per-version table.
+ *
+ * @param {string} root
+ * @param {{
+ *   strict?: boolean,
+ *   arkCheck?: string,
+ *   packageVersion?: string,
+ *   checkResult?: { exitCode?: number, status?: number, stdout?: string, stderr?: string },
+ * }} [options]
+ * @returns {PostUpgradeVerification}
+ */
+export function runPostUpgradeVerification(root, options = {}) {
+  const behaviorChanges = behaviorChangeLines();
+  if (options.strict === false) {
+    return {
+      verdict: 'skipped',
+      failing: [],
+      behaviorChanges,
+      mode: 'skipped',
+      exitCode: 0,
+    };
+  }
+  const raw = options.checkResult ?? spawnArchitectureCheck(root, options.arkCheck);
+  const parsed = parseCheckStdout(raw.stdout ?? '');
+  const failing = aggregateFailingRules(parsed);
+  const exitCode = raw.exitCode ?? raw.status ?? 1;
+  const red = exitCode !== 0 || parsed?.ok === false || parsed?.valid === false;
+  if (red && failing.length === 0) {
+    const sampleSource = String(raw.stderr || 'architecture check failed').trim() || 'architecture check failed';
+    failing.push({
+      ruleId: 'ARCHITECTURE_CHECK',
+      count: 1,
+      sample: sampleSource.length > 180 ? `${sampleSource.slice(0, 177)}...` : sampleSource,
+    });
+  }
+  const stderr = typeof raw.stderr === 'string' && raw.stderr.trim() ? raw.stderr.trim() : undefined;
+  return {
+    verdict: red ? 'red' : 'green',
+    failing: red ? failing : [],
+    behaviorChanges,
+    mode: 'strict-merge',
+    exitCode: red ? (exitCode || 1) : 0,
+    ...(stderr ? { stderr } : {}),
+  };
+}
+
+/**
+ * @param {{
+ *   applied?: boolean,
+ *   blocked?: boolean,
+ *   nothingToApply?: boolean,
+ *   postUpgrade?: PostUpgradeVerification|null,
+ *   error?: unknown,
+ * }} input
+ * @returns {UpgradeOutcome}
+ */
+export function upgradeOutcome(input) {
+  if (input.error != null && input.error !== false) {
+    const message = input.error instanceof Error ? input.error.message : String(input.error);
+    return { kind: 'error', applied: false, blocked: false, postUpgrade: null, error: message };
+  }
+  if (input.blocked) {
+    return { kind: 'blocked', applied: false, blocked: true, postUpgrade: null };
+  }
+  if (input.nothingToApply && !input.applied) {
+    return { kind: 'nothing', applied: false, blocked: false, postUpgrade: null };
+  }
+  const postUpgrade = input.postUpgrade ?? null;
+  if (postUpgrade?.verdict === 'red') {
+    return { kind: 'applied-red', applied: true, blocked: false, postUpgrade };
+  }
+  if (postUpgrade?.verdict === 'skipped') {
+    return { kind: 'applied-skipped', applied: Boolean(input.applied), blocked: false, postUpgrade };
+  }
+  return { kind: 'applied-green', applied: Boolean(input.applied), blocked: false, postUpgrade };
+}
+
+/**
+ * @param {UpgradeOutcome|null|undefined} outcome
+ * @returns {0|1|2|3}
+ */
+export function exitCodeFor(outcome) {
+  switch (outcome?.kind) {
+    case 'applied-green':
+    case 'applied-skipped':
+    case 'nothing':
+    case 'preview':
+      return 0;
+    case 'applied-red':
+      return 3;
+    case 'blocked':
+      return 2;
+    case 'error':
+      return 1;
+    default:
+      return 1;
+  }
+}
+
+/**
+ * @param {{ mode?: string, exitCode?: number, verdict?: string }} [verification]
+ * @returns {boolean|null}
+ */
+export function architectureVerificationOk(verification) {
+  if (!verification || verification.mode === 'skipped' || verification.verdict === 'skipped') return null;
+  if (verification.verdict === 'green') return true;
+  if (verification.verdict === 'red') return false;
+  if (verification.exitCode === 0) return true;
+  if (typeof verification.exitCode === 'number') return false;
+  return null;
+}
+
+/**
+ * @param {{ mode?: string, exitCode?: number, verdict?: string, failing?: FailingRule[] }} [verification]
+ * @returns {string}
+ */
+export function architectureVerificationDetail(verification) {
+  if (!verification || verification.mode === 'skipped' || verification.verdict === 'skipped') {
+    return 'Strict architecture verification was skipped (--no-strict).';
+  }
+  const code = verification.exitCode;
+  if (architectureVerificationOk(verification) === true) {
+    return 'Strict-merge architecture verification passed.';
+  }
+  const failing = Array.isArray(verification.failing) ? verification.failing : [];
+  const rules = failing.map((row) => `${row.ruleId} ×${row.count}`).join(', ');
+  const head = `Architecture verification exit ${code ?? 'unknown'}.`;
+  if (!rules) return head;
+  return `${head} Failing rules: ${rules}. Read behaviorChanges before editing code.`;
+}
+
+/**
+ * @param {{ assets?: Array<{ blocked?: boolean, path?: string, state?: string, reason?: string, nextCommand?: string }>, blocked?: boolean, nextCommand?: string }} plan
+ * @param {{ refused?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function formatBlockedAssets(plan, options = {}) {
+  const blocked = (plan?.assets ?? []).filter((asset) => asset?.blocked);
+  if (blocked.length === 0) return [];
+  const lines = [options.refused ? 'Apply refused.' : 'Blocked until you consent:'];
+  for (const asset of blocked) {
+    const reason = asset.reason || blockedAssetReason(asset.state ?? '');
+    lines.push(`  ${asset.path} — ${reason}`);
+  }
+  const next = blocked.find((asset) => asset.nextCommand)?.nextCommand ?? plan?.nextCommand;
+  if (next) lines.push(`Next: ${next}`);
+  return lines;
+}
+
+/**
+ * @param {PostUpgradeVerification|null|undefined} postUpgrade
+ * @returns {string[]}
+ */
+export function formatPostUpgradeHuman(postUpgrade) {
+  if (!postUpgrade) return [];
+  const lines = [`Post-upgrade verification: ${postUpgrade.verdict}.`];
+  if (postUpgrade.verdict !== 'red') return lines;
+  lines.push('Failing rules:');
+  const failing = postUpgrade.failing ?? [];
+  if (failing.length === 0) lines.push('  (check returned red without a rule id)');
+  for (const row of failing) {
+    lines.push(`  ${row.ruleId} ×${row.count} — ${row.sample}`);
+  }
+  lines.push('Read behaviorChanges before editing code.');
+  for (const note of postUpgrade.behaviorChanges ?? []) lines.push(`  ${note}`);
+  return lines;
+}

package/bin/lib/violations.mjs

@@ -97,6 +97,115 @@ export function printWarning(warning) {
   );
 }
 
+/** Advisory the engine emits once per shared-root → slice edge. Humans see a group. */
+export const SHARED_IMPORTS_SLICE_RULE_ID = 'SHARED_IMPORTS_SLICE';
+
+/**
+ * Where the full per-edge list lives. Human check output names this on every
+ * grouped line. `--json` is the machine list; `--doctor` prints every edge.
+ */
+export const SHARED_IMPORTS_SLICE_FULL_LIST =
+  'Full list: ark-check --json or ark-check --doctor';
+
+const SHARED_IMPORTS_SLICE_EXAMPLE_LIMIT = 3;
+
+function formatAdvisoryCount(count) {
+  return String(count).replace(/\B(?=(\d{3})+(?!\d))/g, ',');
+}
+
+function layerLabel(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : '?';
+}
+
+/** Group key: one fact per rule and layer edge. */
+export function sharedImportsSliceGroupKey(warning) {
+  return [
+    typeof warning?.ruleId === 'string' ? warning.ruleId : SHARED_IMPORTS_SLICE_RULE_ID,
+    layerLabel(warning?.fromLayer),
+    layerLabel(warning?.toLayer),
+  ].join('\0');
+}
+
+function formatSharedImportsSliceExample(warning) {
+  const file = typeof warning?.file === 'string' && warning.file.trim() ? warning.file.trim() : 'unknown';
+  const line = Number.isInteger(warning?.line) && warning.line > 0 ? warning.line : 1;
+  const slice =
+    typeof warning?.toSlice === 'string' && warning.toSlice.trim() ? warning.toSlice.trim() : 'slice';
+  const target =
+    typeof warning?.target === 'string' && warning.target.trim() ? ` (${warning.target.trim()})` : '';
+  return `${file}:${line} → ${slice}${target}`;
+}
+
+/** One human line for a (ruleId, fromLayer → toLayer) group. Count plus top 3 edges. */
+export function formatSharedImportsSliceSummary(group) {
+  const sample = group[0] ?? {};
+  const ruleId =
+    typeof sample.ruleId === 'string' ? sample.ruleId : SHARED_IMPORTS_SLICE_RULE_ID;
+  const count = group.length;
+  const noun = count === 1 ? 'bridge' : 'bridges';
+  const examples = group
+    .slice(0, SHARED_IMPORTS_SLICE_EXAMPLE_LIMIT)
+    .map(formatSharedImportsSliceExample)
+    .join('; ');
+  return (
+    `warning ${ruleId} ${layerLabel(sample.fromLayer)} → ${layerLabel(sample.toLayer)}: ` +
+    `${formatAdvisoryCount(count)} shared-root → slice ${noun} (e.g. ${examples}). ` +
+    `The wall is direct-only. ${SHARED_IMPORTS_SLICE_FULL_LIST}`
+  );
+}
+
+/**
+ * Human check lines. SHARED_IMPORTS_SLICE collapses to one line per group.
+ * Every other warning stays one line. Does not mutate `warnings` — `--json`
+ * and doctor still walk the per-edge array.
+ */
+export function humanWarningLines(warnings) {
+  const groups = new Map();
+  const slots = [];
+  for (const warning of warnings ?? []) {
+    if (warning?.ruleId !== SHARED_IMPORTS_SLICE_RULE_ID) {
+      slots.push({ kind: 'line', line: formatWarningLine(warning) });
+      continue;
+    }
+    const key = sharedImportsSliceGroupKey(warning);
+    let group = groups.get(key);
+    if (!group) {
+      group = [];
+      groups.set(key, group);
+      slots.push({ kind: 'group', key });
+    }
+    group.push(warning);
+  }
+  return slots.map((slot) =>
+    slot.kind === 'line' ? slot.line : formatSharedImportsSliceSummary(groups.get(slot.key))
+  );
+}
+
+function printColoredWarningLine(line) {
+  const painted = line.startsWith('warning ')
+    ? `${color.yellow('warning')}${line.slice('warning'.length)}`
+    : line;
+  console.error(painted);
+}
+
+/** ark-check human renderer. Grouping stops here; the warnings array is unchanged. */
+export function printHumanWarnings(warnings) {
+  for (const line of humanWarningLines(warnings)) {
+    printColoredWarningLine(line);
+  }
+}
+
+/** Doctor human list: every shared-root → slice edge, not the grouped summary. */
+export function printSharedImportsSliceBridgeList(warnings) {
+  const lines = (warnings ?? [])
+    .filter((warning) => warning?.ruleId === SHARED_IMPORTS_SLICE_RULE_ID)
+    .map((warning) => formatWarningLine(warning));
+  if (lines.length === 0) return;
+  console.log('');
+  console.log(`Shared-root → slice bridges (${formatAdvisoryCount(lines.length)}):`);
+  for (const line of lines) console.log(line);
+}
+
 /** Non-blocking type-only placement debt: exit stays 0; do not paint ✖. */
 export function isNonBlockingPlacementDebt(violation) {
   return violation?.failsStrict === false;

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

@@ -49,6 +49,8 @@ type ArkConfigLayer = {
     /** Alias of reserved — empty pattern matches are allowed. */
     allowEmpty?: boolean;
 };
+/** How a starred `sliceFolders` prefix is named. Absent equals `path`. */
+type ArkConfigSliceIdentity = 'path' | 'stars';
 type ArkConfigRule = {
     from: string;
     to: string;
@@ -56,6 +58,11 @@ type ArkConfigRule = {
     message?: string;
     peerIsolation?: boolean;
     sliceFolders?: string[];
+    /**
+     * How a starred `sliceFolders` prefix is named.
+     * Absent and `path` keep today's ids. `stars` is the last literal plus the star bindings.
+     */
+    sliceIdentity?: ArkConfigSliceIdentity;
     /** Roots the repo declares shared on purpose — evidence, not unclassifiable. */
     sharedRoots?: string[];
     /** Directed slice→slice edges the repo declares on purpose. */