arkgate 4.8.19 → 4.8.20

package/bin/lib/config-contract.mjs

@@ -228,6 +228,7 @@ export const ARK_CONFIG_SCHEMA = {
                         },
                     },
                 },
+                sharedImportsSlice: { type: 'string', enum: ['deny'] },
             },
         },
         safety: {

package/bin/lib/doctor-advisories.mjs

@@ -200,7 +200,8 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     physicalCohesion,
     files,
     root,
-    decisionMemory
+    decisionMemory,
+    { layers: config?.layers, rules: rules ?? config?.rules }
   );
   // Prefer architecture facts paths when available; still union the doctor walk
   // so an empty-catalog residual can see Domain files the facts subset missed.

package/bin/lib/doctor-plan.mjs

@@ -59,6 +59,7 @@ import {
 import {
   buildCoverageHonesty,
   computeDoctorEnforcementHonesty,
+  physicalCohesionResidualRemains,
 } from './enforcement-honesty.mjs';
 import {
   computePureLayerOptInNudge,
@@ -693,6 +694,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       github: githubForBoundary,
       adoptionStance: stanceFile,
       stewardNudge: doctorAdvisories.stewardNudge,
+      physicalCohesionResidual: physicalCohesionResidualRemains(doctorAdvisories.physicalCohesion),
     });
 
   // Improvement compass: projection only — never feeds ok/valid/goal.met.

package/bin/lib/enforcement-honesty.mjs

@@ -288,14 +288,26 @@ export function buildWritePathHonesty(activeHost, hardWriteActive = false, extra
  *   primaryNextAction?: string | null,
  *   operatingMode?: string | null,
  *   activeBlockingViolations?: number | null,
+ *   physicalCohesionResidual?: boolean,
  * }} input
  */
+export function physicalCohesionResidualRemains(cohesion) {
+  const findings = Array.isArray(cohesion?.findings) ? cohesion.findings : [];
+  if (findings.length === 0) return false;
+  const covered = new Set();
+  for (const row of cohesion?.reshapeDecisions?.current ?? []) {
+    if (row?.suppressesPilot === true && typeof row.concept === 'string') covered.add(row.concept);
+  }
+  return findings.some((finding) => !covered.has(finding?.concept));
+}
+
 export function buildProductHonesty(input = {}) {
   const reasons = [];
   const cov = input.coverageHonesty;
   const base = input.baselineHonesty;
   const write = input.writePathHonesty;
   const designWeak = input.designWeak === true;
+  const cohesionResidual = input.physicalCohesionResidual === true;
   const dualTruth = input.packageVersionTruth?.dualTruth === true;
   const pinCode = input.packageVersionTruth?.code || write?.packagePinCode || null;
   const pinAbsent =
@@ -365,6 +377,14 @@ export function buildProductHonesty(input = {}) {
     });
   }
 
+  if (cohesionResidual) {
+    reasons.push({
+      id: 'physical-cohesion-residual',
+      message:
+        'Physical cohesion residual remains — the gate verdict and exit code are unchanged, and the reshape card is one judgment, not a queue to empty.',
+    });
+  }
+
   if (dualTruth) {
     reasons.push({
       id: 'package-version-dual-truth',
@@ -551,6 +571,12 @@ export function buildProductHonesty(input = {}) {
     headline = 'Advisory-only adoption — merge status is not required';
   } else if (!unfinished) {
     headline = 'Honesty clear on residual signals';
+  } else if (
+    wholeTreeGoverned &&
+    architectureReasons.length === 1 &&
+    architectureReasons[0].id === 'physical-cohesion-residual'
+  ) {
+    headline = 'Residual remaining';
   } else if (coverageIncomplete) {
     headline = 'Not finished / not whole-tree guarantee';
   } else {
@@ -592,8 +618,8 @@ export function buildProductHonesty(input = {}) {
         : 'unknown';
 
   return {
-    finished: !unfinished && wholeTreeGoverned && !designWeak && activeBlocking === 0,
-    elegant: !designWeak && !base?.dirtyBaselineRisk && !designSmellsOpenEdges && activeBlocking === 0,
+    finished: !unfinished && wholeTreeGoverned && !designWeak && !cohesionResidual && activeBlocking === 0,
+    elegant: !designWeak && !cohesionResidual && !base?.dirtyBaselineRisk && !designSmellsOpenEdges && activeBlocking === 0,
     wholeTreeGuarantee:
       wholeTreeGoverned &&
       !designWeak &&
@@ -656,6 +682,7 @@ export function computeDoctorEnforcementHonesty({
   stewardNudge,
   nativeFailClosed,
   nativeFailClosedPolicy,
+  physicalCohesionResidual,
 } = {}) {
   const coverageHonesty = buildCoverageHonesty({
     percent: governedPercent,
@@ -713,6 +740,7 @@ export function computeDoctorEnforcementHonesty({
     considerMergeBoundary: true,
     emptyStewards,
     stewardNudge,
+    physicalCohesionResidual,
   });
   return {
     coverageHonesty,

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

@@ -17,6 +17,7 @@ import {
   buildBaselineHonesty,
   buildWritePathHonesty,
   buildProductHonesty,
+  physicalCohesionResidualRemains,
 } from './enforcement-honesty.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
 import { attachExtraDoctorSections } from './doctor-advisories.mjs';
@@ -25,6 +26,7 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import { buildDoctorImprovementCompass } from './improvement-compass-doctor.mjs';
 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';
 
 function esc(value) {
@@ -153,6 +155,8 @@ export function buildReportDepthPayload(
       : packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT'
         ? 'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
         : null;
+  const physicalCohesion = computePhysicalCohesion(root, files);
+  physicalCohesion.reshapeDecisions = computeReshapeDecisionMemory(root, files).summary;
   const productHonesty = buildProductHonesty({
     coverageHonesty,
     baselineHonesty,
@@ -169,9 +173,9 @@ export function buildReportDepthPayload(
       : null,
     primaryNextAction: postGreenPath?.action ?? dualTruthNext,
     activeBlockingViolations: activeBlockingCount,
+    physicalCohesionResidual: physicalCohesionResidualRemains(physicalCohesion),
   });
   // Doctor parity: same physical-cohesion + baseline stale facts as runDoctor.
-  const physicalCohesion = computePhysicalCohesion(root, files);
   const baselineStale =
     typeof baselineSplit.baselineStale === 'number' ? baselineSplit.baselineStale : null;
   // Improvement compass — same projection as doctor; notAScore; never a gate input.

package/bin/lib/invariant-coverage.mjs

@@ -19,7 +19,7 @@ export const INVARIANT_COVERAGE_ROOTS_MESSAGE = 'A domain invariant is enforced,
  * `omitBudget` drops the budget clause and the load totals for messages whose
  * own text already carries them — the same number twice reads as two facts.
  */
-function formatCoverageDiscards(stats, omitBudget = false) {
+export function formatCoverageDiscards(stats, omitBudget = false) {
     if (!stats)
         return '';
     const d = stats.discarded;
@@ -62,22 +62,50 @@ function titleMatchesInvariant(content, id) {
     const re = new RegExp(`(?:describe|it|test|context)\\s*\\(\\s*['"\`][^'"\`]*${escaped}[^'"\`]*['"\`]`, 'i');
     return re.test(content) || content.includes(id);
 }
-function symbolPresent(fileContents, symbol) {
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * True when `name` is declared here. Imports and calls do not count.
+ * `export const name =` is the same binding shape sensors already treat as a
+ * declaration (arrow or function). The last segment of `Aggregate.method` is
+ * the name that must be declared.
+ */
+function declaresIdentifier(content, name) {
+    const n = escapeRegExp(name);
+    const functionDecl = new RegExp(`(?:^|[\\s;{}])(?:export\\s+(?:default\\s+)?)?(?:declare\\s+)?(?:async\\s+)?function\\s*\\*?\\s*${n}\\s*[(<]`);
+    const classDecl = new RegExp(`(?:^|[\\s;{}])(?:export\\s+(?:default\\s+)?)?(?:abstract\\s+)?class\\s+${n}\\b`);
+    const constDecl = new RegExp(`(?:^|[\\s;{}])export\\s+(?:const|let|var)\\s+${n}\\s*=`);
+    const methodDecl = new RegExp(`(?:^|[\\n;{}])\\s*(?:(?:public|private|protected|static|async|readonly|override|abstract|get|set|declare)\\s+)*${n}\\s*(?:<[^>\\n]*>)?\\s*\\([^;{}]*\\)\\s*(?::\\s*[^;{]+)?\\s*\\{`);
+    return (functionDecl.test(content) ||
+        classDecl.test(content) ||
+        constDecl.test(content) ||
+        methodDecl.test(content));
+}
+/** Witness path, or undefined when no non-test file declares `symbol`. */
+function symbolPresent(fileContents, testFiles, symbol) {
     if (!symbol)
-        return false;
-    // Support Aggregate.method or bare method name.
+        return undefined;
     const parts = symbol.split('.');
-    const needle = parts[parts.length - 1];
+    const needle = parts[parts.length - 1] ?? '';
+    if (!needle)
+        return undefined;
     const className = parts.length > 1 ? parts[0] : null;
-    for (const content of Object.values(fileContents)) {
+    const tests = new Set(testFiles.map((file) => file.replace(/\\/g, '/').replace(/^\.\//, '')));
+    const files = Object.keys(fileContents).sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    for (const file of files) {
+        const normalized = file.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (tests.has(normalized))
+            continue;
+        const content = fileContents[file];
+        if (!content)
+            continue;
         if (className && !content.includes(className))
             continue;
-        if (new RegExp(`(?:function\\s+|\\b)${needle.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\s*[(<]`).test(content) ||
-            content.includes(symbol)) {
-            return true;
-        }
+        if (declaresIdentifier(content, needle))
+            return file;
     }
-    return false;
+    return undefined;
 }
 export function evaluateInvariantCoverage(input) {
     const invariants = input.arkRules.invariants ?? [];
@@ -131,9 +159,11 @@ export function evaluateInvariantCoverage(input) {
             if (testEvidenceFile !== undefined)
                 evidence.push('test-title');
         }
-        if (symbol && symbolPresent(input.fileContents, symbol)) {
+        const symbolEvidenceFile = symbol
+            ? symbolPresent(input.fileContents, testFiles, symbol)
+            : undefined;
+        if (symbolEvidenceFile)
             evidence.push('symbol');
-        }
         // Covered if any requested evidence is present.
         // When coverage declares neither test nor symbol, require at least description-only advisory presence = not covered.
         const requiresEvidence = inv.coverage?.test === true || Boolean(symbol) || inv.coverage === undefined;
@@ -154,6 +184,7 @@ export function evaluateInvariantCoverage(input) {
             partial,
             description: inv.description,
             ...(testEvidenceFile !== undefined ? { testEvidenceFile } : {}),
+            ...(symbolEvidenceFile !== undefined ? { symbolEvidenceFile } : {}),
             ...(outsideDeclaredRoots !== undefined ? { outsideDeclaredRoots } : {}),
             coverageRootsDeclared: rootsDeclared,
         });

package/bin/lib/package-manager.mjs

@@ -94,9 +94,12 @@ export function arkCommand(root, bin, argsStr = '') {
 /**
  * Run an Ark binary from package `arkgate` when local bins may be missing.
  * Bare `npx arkgate-check` 404s — npx treats that bin name as its own package.
+ * Pass `packageSpec` (e.g. `arkgate@4.8.19`) when Age blocked a local add.
  */
-export function arkPackageRecoveryCommand(bin, argsStr = '') {
-  return `npx --package=arkgate ${bin}${argsStr ? ` ${argsStr}` : ''}`;
+export function arkPackageRecoveryCommand(bin, argsStr = '', packageSpec) {
+  const spec =
+    typeof packageSpec === 'string' && packageSpec.trim() ? packageSpec.trim() : 'arkgate';
+  return `npx --package=${spec} ${bin}${argsStr ? ` ${argsStr}` : ''}`;
 }
 
 /**

package/bin/lib/physical-cohesion.mjs

@@ -15,6 +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';
 
 /** ADR 0010 D3 — corpus-calibrated, fixed. */
 const CLUSTER_MIN = 40;
@@ -126,76 +127,92 @@ export function computePhysicalCohesion(root, files) {
   };
 }
 
+function governedDestinationDir(anchor, concept) {
+  return !anchor || anchor === '.' ? concept : `${anchor}/${concept}`;
+}
+
+function anchorIsConsolidationSubtree(anchor, concept) {
+  return String(anchor).split('/').some((part) => part === concept);
+}
+
+function declaredSliceFolders(rules) {
+  const out = [];
+  const seen = new Set();
+  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);
+    }
+  }
+  return out;
+}
+
+function destinationKeepsLayerAndSlice(fromRel, toRel, layers, sliceFolders) {
+  return layerForRelativePath(fromRel, layers) === layerForRelativePath(toRel, layers)
+    && sliceIdForPath(fromRel, sliceFolders) === sliceIdForPath(toRel, sliceFolders);
+}
+
+function withheldPilot(concept, note) {
+  return { proposed: true, applied: false, neverMechanicalSafe: true, concept, note, nextPilot: null };
+}
+
 /**
- * R2 — the proposed reshape pilot for the TOP finding (one at a time, Q04
- * discipline; ADR 0010 D4–D7). Proposal only: no apply path exists. Moves
- * target the smallest convention-free anchor; sampled `to` paths must fall
- * under the consolidated feature directory the agent will create via the
- * governed write path (T02 preflight validates every real move there).
+ * R2 — proposed reshape pilot (ADR 0010 D4–D7). `to` is `concept/` under the
+ * source anchor and is kept only when the generated layer and slice matchers
+ * agree. Tooling does not import Kernel preflight. Withheld when every
+ * candidate fails.
  */
-export function computeReshapePilot(cohesion, files, root) {
+export function computeReshapePilot(cohesion, files, root, contract) {
   const top = cohesion?.findings?.[0];
   if (!top) return null;
-  // Recompute the FULL anchor map for the top concept: the finding's anchors
-  // are display-filtered (>= MIRROR_MIN, capped), and pilot selection over
-  // that trimmed list falsely reported "nothing to move" when the only
-  // movable anchor sat below the display floor (cross-model review finding).
+  const layers = contract?.layers;
+  const sliceFolders = declaredSliceFolders(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('/');
-  for (const abs of Array.isArray(files) ? files : []) {
+  const fileList = Array.isArray(files) ? files : [];
+  for (const abs of fileList) {
     const rel = relOf(abs);
-    const r = classifyPhysical(rel);
-    if (!r || r.concept !== top.concept) continue;
-    byAnchor.set(r.anchor, (byAnchor.get(r.anchor) ?? 0) + 1);
+    const ranked = classifyPhysical(rel);
+    if (!ranked || ranked.concept !== top.concept) continue;
+    byAnchor.set(ranked.anchor, (byAnchor.get(ranked.anchor) ?? 0) + 1);
   }
-  const targetDir = `src/features/${top.concept}`;
   const movable = [...byAnchor.entries()]
-    .filter(
-      ([anchor]) =>
-        !CONVENTION_ANCHOR_RE.test(`${anchor}/`) &&
-        // The consolidation target subtree is DONE, not a source — without
-        // this the loop re-proposes the files it just moved, forever
-        // (end-to-end pilot-loop finding).
-        anchor !== targetDir &&
-        !anchor.startsWith(`${targetDir}/`)
-    )
+    .filter(([anchor]) => !CONVENTION_ANCHOR_RE.test(`${anchor}/`) && !anchorIsConsolidationSubtree(anchor, top.concept))
     .map(([anchor, count]) => ({ path: anchor, files: count }))
     .sort((a, b) => a.files - b.files || (a.path < b.path ? -1 : 1));
   if (movable.length === 0) {
-    return {
-      proposed: true,
-      applied: false,
-      neverMechanicalSafe: true,
-      concept: top.concept,
-      note: 'Every remaining anchor for this concept is fixed by framework convention or already consolidated — nothing to move; consider the merge-card review instead.',
-      nextPilot: null,
-    };
+    return withheldPilot(top.concept, 'Every remaining anchor for this concept is fixed by framework convention or already consolidated — nothing to move; consider the merge-card review instead.');
+  }
+  const legalAnchors = [];
+  for (const anchor of movable) {
+    const targetDir = governedDestinationDir(anchor.path, top.concept);
+    const legal = fileList.map(relOf).filter((rel) => {
+      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);
+    }).sort().map((rel) => ({ from: rel, to: `${targetDir}/${rel.split('/').at(-1)}` }));
+    if (legal.length > 0) legalAnchors.push({ ...anchor, targetDir, legal });
+  }
+  if (legalAnchors.length === 0) {
+    return withheldPilot(top.concept, 'No governed destination keeps the layer and the slice.');
   }
-  // Smallest movable cluster worth piloting; if none reaches the floor, take
-  // the largest movable anchor so the pilot still exists and stays honest.
-  const pilotAnchor = movable.find((a) => a.files >= 10) ?? movable[movable.length - 1];
-  const rels = (Array.isArray(files) ? files : [])
-    .map(relOf)
-    .filter((rel) => {
-      const r = classifyPhysical(rel);
-      return r && r.concept === top.concept && r.anchor === pilotAnchor.path;
-    })
-    .sort();
-  const moves = rels.slice(0, MAX_MOVE_SAMPLE).map((rel) => ({
-    from: rel,
-    to: `${targetDir}/${rel.split('/').at(-1)}`,
-  }));
+  // Smallest cluster of at least 10 files; otherwise the largest movable anchor.
+  const pilotAnchor = legalAnchors.find((a) => a.files >= 10) ?? legalAnchors.at(-1);
   return {
     proposed: true,
     applied: false,
     neverMechanicalSafe: true,
     concept: top.concept,
     nextPilot: {
-      pilotTarget: `${top.concept} @ ${pilotAnchor.path} (${pilotAnchor.files} file(s))`,
-      move: `Consolidate the ${top.concept} cluster from ${pilotAnchor.path} under ${targetDir}/ — one anchor only, moves proposed as an architecture change map and validated by the atomic preflight before any write.`,
-      moveSample: moves,
-      movesTotal: rels.length,
-      successSignal: `re-run doctor: the ${top.concept} cluster count drops and the verdict stays green`,
+      pilotTarget: `${top.concept} @ ${pilotAnchor.path} (${pilotAnchor.legal.length} file(s))`,
+      move: `Consolidate the ${top.concept} cluster from ${pilotAnchor.path} under ${pilotAnchor.targetDir}/ — one anchor only, same layer and slice, moves proposed as an architecture change map and validated by the atomic preflight before any write.`,
+      moveSample: pilotAnchor.legal.slice(0, MAX_MOVE_SAMPLE),
+      movesTotal: pilotAnchor.legal.length,
+      successSignal: `re-run doctor: the ${top.concept} cluster count drops, layer and slice id unchanged, card still proposed`,
       killSwitch: 'revert this move set; nothing else was touched',
       doNot: [
         'never move files under app/ or pages/ — fixed by framework convention',

package/bin/lib/reshape-decisions.mjs

@@ -214,7 +214,7 @@ export function computeReshapeDecisionMemory(root, files, today = new Date().toI
 }
 
 /** Select one actionable finding while respecting explicit current verdicts. */
-export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis) {
+export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis, contract) {
   const findings = Array.isArray(cohesion?.findings) ? cohesion.findings : [];
   if (findings.length === 0) return null;
   const currentByTarget = new Map(
@@ -224,7 +224,7 @@ export function computeDecisionAwareReshapePilot(cohesion, files, root, analysis
     const anchors = analysis.anchorSets.get(finding.concept) ?? [];
     const decision = currentByTarget.get(targetKey(finding.concept, anchors));
     if (decision?.suppressesPilot) continue;
-    const pilot = computeReshapePilot({ ...cohesion, findings: [finding] }, files, root);
+    const pilot = computeReshapePilot({ ...cohesion, findings: [finding] }, files, root, contract);
     if (!pilot?.nextPilot) return pilot;
     return {
       ...pilot,

package/bin/lib/rules-under-contract.mjs

@@ -6,7 +6,7 @@
  */
 import path from 'node:path';
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
-import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
+import { evaluateInvariantCoverage, formatCoverageDiscards } from './invariant-coverage.mjs';
 import {
   coverageOptionsFromConfig,
   invariantIdsFromCatalog,
@@ -138,9 +138,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       fileContents: coverageInputs.fileContents,
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
-      // No coverageStats / coverageRoots: this caller reads coverage ROWS and
-      // drops the violations, and both only shape violation messages. Passing
-      // them would look like wiring while changing nothing observable here.
+      // Stats shape the green doctor line (discard counts), not only a failing
+      // sentence. Roots stay out: this caller drops violations.
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
       coverageBudgetExhausted: coverageInputs.coverageBudgetExhausted === true,
     });
     const covById = new Map(
@@ -189,6 +189,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
     const uncoveredTruncated = Math.max(0, uncoveredAll.length - UNCOVERED_CATALOG_MAX);
     const uncovered = uncoveredAll.slice(0, UNCOVERED_CATALOG_MAX);
 
+    const symbolEvidence = (coverage.coverage ?? [])
+      .filter((row) => typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0)
+      .map((row) => ({ id: row.invariantId, file: row.symbolEvidenceFile }));
     const coveredAll = (coverage.coverage ?? [])
       .filter((row) => row.covered)
       .map((row) => ({
@@ -196,6 +199,9 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
         layer: row.layer ?? null,
         mode: row.mode ?? null,
         description: row.description ?? null,
+        ...(typeof row.symbolEvidenceFile === 'string' && row.symbolEvidenceFile.length > 0
+          ? { symbolEvidenceFile: row.symbolEvidenceFile }
+          : {}),
       }));
     const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
     const coveredSample = coveredAll.slice(0, COVERED_SAMPLE_MAX);
@@ -259,6 +265,8 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
       uncoveredTruncated,
       coveredSample,
       coveredTruncated,
+      symbolEvidence,
+      ...(coverageInputs.stats ? { coverageStats: coverageInputs.stats } : {}),
       mergePlanes,
       notAScore: true,
       note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so. Structure sensors are heuristics; invariants are catalog+coverage evidence, not a business runtime.',
@@ -280,6 +288,27 @@ export function summarizeRulesUnderContract(root, config, facts, classification)
   }
 }
 
+/**
+ * Symbol witness paths and discard counts. Printed on green runs too —
+ * a passing check used to hide both. Depth and byte caps stay internal;
+ * only the counts already in the failure sentence are shown.
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @returns {string[]}
+ */
+export function formatArkRulesEvidenceLines(section) {
+  if (!section || typeof section !== 'object') return [];
+  const lines = [];
+  const evidence = Array.isArray(section.symbolEvidence) ? section.symbolEvidence : [];
+  for (const row of evidence) {
+    if (typeof row?.file !== 'string' || row.file.length === 0) continue;
+    const id = typeof row.id === 'string' && row.id.length > 0 ? row.id : 'invariant';
+    lines.push(`ArkRules: ${id} symbol ${row.file}`);
+  }
+  const discard = formatCoverageDiscards(section.coverageStats);
+  if (discard) lines.push(`ArkRules:${discard}`);
+  return lines;
+}
+
 /**
  * Compact / details doctor lines. Empty when the map is off — absence is silent.
  * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
@@ -332,6 +361,7 @@ export function formatArkRulesDoctorLines(section) {
   else if (typeof section.note === 'string' && /failed/i.test(section.note)) {
     lines.push(`ArkRules: ${section.note}`);
   }
+  lines.push(...formatArkRulesEvidenceLines(section));
   return lines;
 }
 
@@ -475,6 +505,7 @@ export function formatRulesUnderContractHtml(section, esc) {
         <code>${escape(c.id)}</code>
         <span class="tag">covered</span>
         <span class="dim">· ${escape(c.layer || '?')}</span>
+        ${c.symbolEvidenceFile ? `<span class="dim">· ${escape(c.symbolEvidenceFile)}</span>` : ''}
         ${c.description ? `<div class="msg">${escape(c.description)}</div>` : ''}
       </li>`
     )
@@ -528,6 +559,11 @@ export function formatRulesUnderContractHtml(section, esc) {
     }
     ${uncoveredBlock}
     ${coveredBlock}
+    ${
+      formatArkRulesEvidenceLines(section)
+        .map((line) => `<p class="muted" style="margin-top:.35rem;font-size:.84rem">${escape(line)}</p>`)
+        .join('')
+    }
     ${
       coveredSample.length || uncovered.length
         ? `<p class="muted" style="margin-top:.65rem;font-size:.84rem">Covered = catalog evidence found (symbol and/or test title). Not a claim that business semantics are fully proven end-to-end.</p>`