arkgate 4.8.19 → 4.8.21

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/pilot-loop.mjs

@@ -120,35 +120,39 @@ export function extractionCardFromBet(bet, preferredFiles) {
 }
 
 /**
- * Select **one** next pilot from pattern bets (or build bets from smells).
+ * Viable pattern bets, best pilot first (same rank as the historical selector).
+ * Mechanical-safe claims and non-production god-module paths are dropped.
  * @param {object[] | null | undefined} patternBets
- * @param {{ designSmells?: object[] }} [options]
- * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ * @param {object[] | null | undefined} [designSmells]
  */
-export function selectNextPilot(patternBets, options = {}) {
+function rankedPatternBets(patternBets, designSmells) {
   let bets = Array.isArray(patternBets) ? [...patternBets] : [];
-  if (bets.length === 0 && Array.isArray(options.designSmells) && options.designSmells.length) {
-    bets = buildPatternBetsFromSmells(options.designSmells);
+  if (bets.length === 0 && Array.isArray(designSmells) && designSmells.length) {
+    bets = buildPatternBetsFromSmells(designSmells);
   }
-  if (bets.length === 0) return null;
-
-  let best = null;
-  let bestScore = -Infinity;
+  const ranked = [];
   for (let i = 0; i < bets.length; i++) {
     const bet = bets[i];
     if (!bet || bet.neverMechanicalSafe === false) continue;
-    // Skip anything that claims mechanical-safe (honesty).
     if (bet.class === 'mechanical-safe') continue;
     const files = pilotFilesForBet(bet);
     if (files === null) continue;
-    const sc = scoreBet(bet, i, files);
-    if (sc > bestScore) {
-      bestScore = sc;
-      best = { bet, files };
-    }
+    ranked.push({ bet, files, score: scoreBet(bet, i, files) });
   }
-  if (!best) return null;
-  return extractionCardFromBet(best.bet, best.files);
+  ranked.sort((a, b) => b.score - a.score);
+  return ranked;
+}
+
+/**
+ * Select **one** next pilot from pattern bets (or build bets from smells).
+ * @param {object[] | null | undefined} patternBets
+ * @param {{ designSmells?: object[] }} [options]
+ * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ */
+export function selectNextPilot(patternBets, options = {}) {
+  const ranked = rankedPatternBets(patternBets, options.designSmells);
+  if (ranked.length === 0) return null;
+  return extractionCardFromBet(ranked[0].bet, ranked[0].files);
 }
 
 /**
@@ -174,15 +178,159 @@ export function formatExtractionCard(card) {
 }
 
 /**
- * Doctor/plan JSON summary of the active pilot loop step.
+ * One proposed pilot. The loop does not know designWeak or which sensor
+ * produced the card — only this list.
+ *
+ * @typedef {'pattern-bet' | 'reshape'} PilotSource
+ * @typedef {{
+ *   source: PilotSource,
+ *   target: string,
+ *   move: string,
+ *   moveSample: Array<string | { from: string, to: string }>,
+ *   successSignal: string,
+ *   killSwitch: string,
+ *   bet?: object,
+ *   files?: string[],
+ *   doNot?: string[],
+ * }} PilotCandidate
+ */
+
+/**
+ * @param {object} bet
+ * @param {string[]} files
+ * @returns {PilotCandidate}
+ */
+function candidateFromBet(bet, files) {
+  const target =
+    (files && files[0]) ||
+    (typeof bet.pilot === 'string' ? bet.pilot : null) ||
+    'src/**';
+  return {
+    source: 'pattern-bet',
+    target,
+    move:
+      typeof bet.fix === 'string' && bet.fix.trim()
+        ? bet.fix.trim()
+        : 'Apply one bounded extraction for this smell on pilot paths only',
+    moveSample: files || [],
+    successSignal:
+      typeof bet.successSignal === 'string'
+        ? bet.successSignal
+        : 'Smell evidence paths cleared on pilot without weakening the contract',
+    killSwitch:
+      typeof bet.killSwitch === 'string'
+        ? bet.killSwitch
+        : 'If pilot increases edge violations without design clarity, stop and re-map with /ark-explore',
+    bet,
+    files,
+  };
+}
+
+/**
+ * @param {PilotCandidate} candidate
+ * @returns {null | ReturnType<typeof extractionCardFromBet>}
+ */
+function extractionCardFromCandidate(candidate) {
+  if (!candidate || typeof candidate.target !== 'string' || candidate.target.length === 0) {
+    return null;
+  }
+  if (candidate.source === 'pattern-bet' && candidate.bet) {
+    return extractionCardFromBet(candidate.bet, candidate.files);
+  }
+  const sample = Array.isArray(candidate.moveSample) ? candidate.moveSample : [];
+  const evidence = sample
+    .map((entry) => (typeof entry === 'string' ? entry : entry?.from))
+    .filter((entry) => typeof entry === 'string' && entry.length > 0)
+    .slice(0, 8);
+  const reshape = candidate.source === 'reshape';
+  return {
+    id: PILOT_LOOP_ID,
+    patternBetId: reshape ? `reshape:${candidate.target}` : `pattern-b:${candidate.target}`,
+    smellId: reshape ? 'physical-cohesion' : 'unknown',
+    pilot: candidate.target,
+    pilotTarget: candidate.target,
+    evidence,
+    move: candidate.move,
+    doNot:
+      Array.isArray(candidate.doNot) && candidate.doNot.length
+        ? [...candidate.doNot]
+        : [...DEFAULT_DO_NOT],
+    successSignal: candidate.successSignal,
+    killSwitch: candidate.killSwitch,
+    neverMechanicalSafe: true,
+    class: 'judgment',
+    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',
+  };
+}
+
+/**
+ * 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.
+ *
  * @param {{
  *   designWeak?: boolean,
  *   patternBets?: object[],
  *   designSmells?: object[],
- * }} opts
+ * }} [designFitness]
+ * @param {{
+ *   physicalCohesion?: {
+ *     reshapePilot?: { proposed?: boolean, nextPilot?: object | null },
+ *   },
+ * }} [advisories]
+ * @returns {PilotCandidate[]}
  */
-export function summarizePilotLoop(opts = {}) {
-  const designWeak = opts.designWeak === true;
+export function collectPilotCandidates(designFitness = {}, advisories = {}) {
+  /** @type {PilotCandidate[]} */
+  const candidates = [];
+  if (designFitness?.designWeak === true) {
+    for (const ranked of rankedPatternBets(designFitness.patternBets, designFitness.designSmells)) {
+      candidates.push(candidateFromBet(ranked.bet, ranked.files));
+    }
+  }
+  const reshape = advisories?.physicalCohesion?.reshapePilot;
+  const card = reshape?.proposed === true ? reshape.nextPilot : null;
+  if (card && typeof card.pilotTarget === 'string' && card.pilotTarget.length > 0) {
+    candidates.push({
+      source: 'reshape',
+      target: card.pilotTarget,
+      move:
+        typeof card.move === 'string' && card.move.trim()
+          ? card.move.trim()
+          : 'Consolidate one anchor only, then re-doctor before the next card',
+      moveSample: Array.isArray(card.moveSample) ? card.moveSample : [],
+      successSignal:
+        typeof card.successSignal === 'string'
+          ? card.successSignal
+          : 're-run doctor: the cluster count drops, layer and slice id unchanged, card still proposed',
+      killSwitch:
+        typeof card.killSwitch === 'string'
+          ? card.killSwitch
+          : 'revert this move set; nothing else was touched',
+      ...(Array.isArray(card.doNot) ? { doNot: card.doNot } : {}),
+    });
+  }
+  return candidates;
+}
+
+/**
+ * Doctor/plan JSON summary. Active iff `candidates.length > 0`.
+ * Activates exactly one candidate (ADR 0010 one-pilot rule). The rest stay
+ * queued. No designWeak parameter.
+ *
+ * @param {PilotCandidate[]} [candidates]
+ */
+export function summarizePilotLoop(candidates = []) {
+  const list = (Array.isArray(candidates) ? candidates : []).filter(
+    (candidate) => candidate && typeof candidate.target === 'string' && candidate.target.length > 0
+  );
   // Same forbid bits as DESIGN_WEAK_HONESTY_FLAGS (both auto-apply aliases).
   const forbid = {
     multiPilotBatchForbidden: true,
@@ -190,55 +338,53 @@ export function summarizePilotLoop(opts = {}) {
     autoApplyPlanBForbidden: true,
   };
 
-  if (!designWeak) {
+  if (list.length === 0) {
     return {
       active: false,
       id: PILOT_LOOP_ID,
-      reason: 'not-design-weak',
+      reason: 'no-pilot-candidates',
       oneAtATime: true,
       neverMechanicalSafe: true,
       ...forbid,
     };
   }
 
-  const nextPilot = selectNextPilot(opts.patternBets, {
-    designSmells: opts.designSmells,
-  });
-  if (!nextPilot) {
+  // One pilot, not the list. Later candidates wait for a re-doctor.
+  const extractionCard = extractionCardFromCandidate(list[0]);
+  if (!extractionCard) {
     return {
       active: false,
       id: PILOT_LOOP_ID,
-      reason: 'no-pattern-bets',
+      reason: 'no-pilot-candidates',
       oneAtATime: true,
       neverMechanicalSafe: true,
       ...forbid,
     };
   }
 
-  const remaining = Array.isArray(opts.patternBets) ? opts.patternBets.length : 0;
-  const queued = Math.max(0, remaining - 1);
-
+  const queued = list.length - 1;
   return {
     active: true,
     id: PILOT_LOOP_ID,
     oneAtATime: true,
     neverMechanicalSafe: true,
     ...forbid,
-    remainingBets: remaining,
-    // Remaining pattern bets are a queue, never concurrent pilots.
+    source: list[0].source,
+    remainingBets: list.length,
     queuedBets: queued,
     ...(queued > 0
       ? {
-          queueNote: `${queued} additional pattern bet(s) stay queued — run the single nextPilot only, then re-doctor before selecting another.`,
+          queueNote: `${queued} additional pilot candidate(s) stay queued — run the single nextPilot only, then re-doctor before selecting another.`,
         }
       : {}),
-    nextPilot,
+    nextPilot: extractionCard,
+    extractionCard,
     instruction:
       'Apply ONE pilot from nextPilot (extraction card), then re-doctor. ' +
       'Do not multi-pilot batch. patternBets never mechanical-safe. ' +
       'Never silent auto-apply of plan B. ' +
       'Success = reduced smell evidence on pilot paths; residual outside pilot may remain.',
-    cardText: formatExtractionCard(nextPilot),
+    cardText: formatExtractionCard(extractionCard),
   };
 }
 

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>`