arkgate 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -5,6 +5,54 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.0.1 — 2026-07-24
+
+**Patch** over 4.0.0. Field footgun fix for stale global CLI on upgrade, ArkRules HTML/doctor
+catalog honesty, dual-plane product wording, and internal coverage attribution.
+**No required config migration.** Does not weaken write gate or CI. Does not close Z09 / RB-11.
+
+### Improved
+
+- **HTML / doctor ArkRules showcase:** `rulesUnderContract` is no longer counts-only.
+  When `arkRules` is active, the report lists **per-layer** structure/invariant totals,
+  **structure sensors** (id · sensor · mode · description), **uncovered** invariants,
+  and a **covered sample** — so `/ark-explain` has real [ArkRules] content to walk.
+  Skill text updated to open `arkrules/*` and name real IDs.
+- **HTML advisory cards:** doctor advisory blocks (contract health, ambient, cohesion,
+  parse health, graph blind spots, ArkRules) render with `class="section card"` so they
+  match the white panel styling of Layers / Violations / Enforcement (were bare
+  `<section data-advisory>` on the page background).
+- **Dual-plane honesty in product surfaces:** configuration / use / product-voice /
+  `/ark-explain` and the ArkRules HTML strip state that structure sensors are heuristics,
+  invariants are catalog + coverage evidence (not a business runtime), and the two planes
+  never merge into one architecture score.
+- **Coverage floors (internal):** branch threshold 83.0 → **82.5** after Fase 0 surface
+  growth (measured ~83% clean candidate); unit tests for upgrade refuse/HTML catalog use
+  ESM imports so V8 attributes hits (createRequire was under-counting).
+
+### Fixed
+
+- **Stale global CLI vs project `arkgate` (upgrade footgun):** `ark upgrade` /
+  `ark update` now **fail closed** when the running CLI package root is outside
+  the project's `node_modules/arkgate` **and** the running version is older than
+  the installed project package. Recovery prefers the package-manager runner
+  (`npx` / `pnpm exec` / `yarn` + `arkgate`) so hoisted monorepos without a
+  nested shallow path still work; shallow
+  `node node_modules/arkgate/bin/ark.mjs` is install-root secondary advice.
+  With `--json`, refuse also emits a machine-readable
+  `{ refused, reason, message, cliVersion, projectVersion, nextCommand }` on
+  stdout (exit 2). Does not block project-local CLI, newer globals, or projects
+  with no local install yet. Field context: global Homebrew **2.x** mutative
+  upgrade next to 3.8+/4.0 projects (see
+  [4.0.0 release notes](docs/releases/4.0.0.md#field-footgun--global-arkgate-2x-on-path)).
+- **`/ark-upgrade` skill:** procedure step 1 resolves the **project-local** CLI
+  first, probes for managed upgrade (`--plan-digest`), and aborts when only an
+  old PATH binary is available.
+- **Doctor `rulesUnderContract` catalog caps:** structure sensors and uncovered
+  invariants are truncated in doctor JSON (with `structureTruncated` /
+  `uncoveredTruncated`) the same way as the covered sample — HTML announces
+  overflow instead of implying the full catalog is always embedded.
+
 ## 4.0.0 — 2026-07-24
 
 **Major** over 3.9.2. **Breaking:** deprecated root subpaths `arkgate/runtime` and `arkgate/nestjs`
@@ -77,6 +125,10 @@ case-study docs are scaffolding, not a closed field gate.
 - **Dual-truth residual:** `ark upgrade --no-install` can refresh managed assets while leaving
   package.json on an older pin — doctor exposes `packageVersionTruth` and upgrade JSON/human notes
   when the pin is behind the CLI.
+- **Field note — global 2.x PATH:** bare `ark upgrade` from a global **arkgate 2.x** install is
+  mutative (pre managed content-identity) and unsafe next to 3.8+/4.0 projects — prefer
+  `npx arkgate upgrade …`. Documented in [4.0.0 release notes](docs/releases/4.0.0.md#field-footgun--global-arkgate-2x-on-path);
+  CLI fail-closed guard ships under Unreleased.
 
 ## 3.9.2 — 2026-07-23
 

package/README.md

@@ -16,9 +16,10 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.0.0** is prepared on this line (ArkRules opt-in + AR04 breaking forwarder removal).
-> Last npm `latest` remains **3.9.2** until publish. [4.0.0 notes](docs/releases/4.0.0.md) ·
-> [3.9.2](docs/releases/3.9.2.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.0.1** is the next prepared patch (stale global CLI upgrade guard + ArkRules
+> HTML/docs honesty). **npm `latest` is still 4.0.0** until publication succeeds.
+> [4.0.1 notes](docs/releases/4.0.1.md) · [4.0.0](docs/releases/4.0.0.md) ·
+> [Docs hub](docs/README.md)
 
 ---
 
@@ -186,8 +187,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Latest prepared (4.0.0) | [docs/releases/4.0.0.md](docs/releases/4.0.0.md) · [CHANGELOG](CHANGELOG.md) |
-| Last published (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |
+| Latest release (4.0.0 on npm; 4.0.1 prepared) | [4.0.1](docs/releases/4.0.1.md) · [4.0.0](docs/releases/4.0.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Previous (3.9.2) | [docs/releases/3.9.2.md](docs/releases/3.9.2.md) |
 | History / maintainer evidence | [docs/archive/](docs/archive/README.md) |
 
 ---

package/bin/lib/graph-blind.mjs

@@ -247,7 +247,7 @@ export function graphBlindSpotsHtml(state, esc = (v) => String(v)) {
     body = `<p><span class="tag warn">${state.count} unresolvable</span> dynamic edge(s) — graph incomplete (${state.templateInterpolationCount ?? 0} template-interpolation).</p><ul>${list}</ul>${more}<p class="muted">Advisory only — does not change the architecture verdict; edges are blind, not clean.</p>`;
   }
   return `
-  <section data-advisory="graphBlindSpots">
+  <section class="section card" data-advisory="graphBlindSpots">
     <h2>Graph blind spots <span class="muted">(advisory — incomplete graph honesty; never a hard verdict)</span></h2>
     ${body}
   </section>`;

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

@@ -9,6 +9,7 @@
  */
 import { effectiveCapabilityDeny } from './analysis-engine.mjs';
 import { graphBlindSpotsHtml } from './graph-blind.mjs';
+import { formatRulesUnderContractHtml } from './rules-under-contract.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
@@ -114,7 +115,7 @@ function contractHealthHtml(health) {
         })
         .join('\n');
   return `
-  <section data-advisory="contractHealth">
+  <section class="section card" data-advisory="contractHealth">
     <h2>Contract health <span class="muted">(advisory — meta-lint of the contract itself; never changes the verdict)</span></h2>
     ${invalid}
     ${body}
@@ -128,7 +129,7 @@ function ambientStateHtml(state) {
   if (!state) return '';
   if (state.available === false) {
     return `
-  <section data-advisory="ambientState">
+  <section class="section card" data-advisory="ambientState">
     <h2>Ambient state <span class="muted">(advisory)</span></h2>
     <p class="muted">${esc(state.note ?? 'Sensor unavailable in this run.')}</p>
   </section>`;
@@ -147,7 +148,7 @@ function ambientStateHtml(state) {
         (state.findingCount > 10 ? `<p class="muted">…(+${state.findingCount - 10} more in doctor JSON)</p>` : '') +
         (state.acknowledged > 0 ? `<p class="muted">acknowledged module state: ${state.acknowledged}</p>` : '');
   return `
-  <section data-advisory="ambientState">
+  <section class="section card" data-advisory="ambientState">
     <h2>Ambient state <span class="muted">(advisory — opt-in via pure layers; blocker-grade Y07 parked)</span></h2>
     ${body}
   </section>`;
@@ -211,7 +212,7 @@ function physicalCohesionHtml(pc) {
     ? `<p class="muted">next pilot (proposed, never applied): ${esc(pc.reshapePilot.nextPilot.pilotTarget)} — one pilot at a time via /ark-loop; merges are judgment cards only.</p>`
     : '';
   return `
-  <section data-advisory="physicalCohesion">
+  <section class="section card" data-advisory="physicalCohesion">
     <h2>Physical cohesion <span class="muted">(advisory — facts, not a score; the verdict is unchanged)</span></h2>
     ${body}
     ${reshapeDecisionsHtml(pc.reshapeDecisions)}
@@ -230,7 +231,7 @@ function parseHealthHtml(health) {
       `<ul>${files.map((f) => `<li><code>${esc(f.file)}</code> — ${f.diagnosticCount} parse diagnostic(s)</li>`).join('')}</ul>` +
       (health.truncated > 0 ? `<p class="muted">…(+${health.truncated} more affected file(s); doctor list capped)</p>` : '');
   return `
-  <section data-advisory="parseHealth">
+  <section class="section card" data-advisory="parseHealth">
     <h2>Parse health <span class="muted">(completeness evidence — affected syntax makes analysis partial)</span></h2>
     ${body}
   </section>`;
@@ -242,26 +243,8 @@ function parseHealthHtml(health) {
  * @param escape injected HTML escaper (dependency points html-report → here only)
  */
 function rulesUnderContractHtml(section) {
-  if (!section || typeof section !== 'object') return '';
-  const note = section.note ? `<p class="muted">${esc(section.note)}</p>` : '';
-  if (section.active === false) {
-    return `
-  <section data-advisory="rulesUnderContract">
-    <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
-    ${note}
-  </section>`;
-  }
-  return `
-  <section data-advisory="rulesUnderContract">
-    <h2>Rules under contract <span class="muted">(counts — not a score)</span></h2>
-    <ul>
-      <li>Structure rules: <strong>${Number(section.structureRules) || 0}</strong></li>
-      <li>Invariants: <strong>${Number(section.invariants) || 0}</strong></li>
-      <li>Covered invariants: <strong>${Number(section.coveredInvariants) || 0}</strong></li>
-      <li>Uncovered invariants: <strong>${Number(section.uncoveredInvariants) || 0}</strong></li>
-    </ul>
-    ${note}
-  </section>`;
+  // Detail lives in rules-under-contract.mjs so this file stays under LOC budget.
+  return formatRulesUnderContractHtml(section, esc);
 }
 
 export function renderAdvisorySections(advisories, escape) {

package/bin/lib/managed-upgrade.mjs

@@ -689,5 +689,5 @@ export function renderManagedUpgrade(plan, options = {}) {
   }
   console.log(`Planned writes: ${wouldWrite}; blocked conflicts/deletions: ${blocked}.`);
   if (options.next) console.log(options.next);
-  else console.log('Apply the exact preview with: ark upgrade --apply --no-install');
+  else console.log('Apply the exact preview with: npx arkgate upgrade --apply --no-install');
 }

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

@@ -1,11 +1,21 @@
 /**
- * AR12 — doctor/HTML "Rules under contract" counts (not a score).
+ * AR12 — doctor/HTML "Rules under contract" (ArkRules plane — counts, never a score).
  * Uses real file I/O for coverage evidence (never empty-fileContents stub).
+ * Summary includes per-layer + structure/invariant detail so showcase HTML /ark-explain
+ * can teach what is under contract, not only aggregate numbers.
  */
 import { loadEffectiveArkRulesFromDisk } from './effective-contract-load.mjs';
 import { evaluateInvariantCoverage } from './invariant-coverage.mjs';
 import { loadInvariantCoverageInputs } from './invariant-coverage-io.mjs';
 
+/**
+ * Cap long catalogs in doctor JSON (and HTML, which consumes the same summary).
+ * Covered is a sample; structure/uncovered are truncated with *Truncated counters.
+ */
+const COVERED_SAMPLE_MAX = 24;
+const STRUCTURE_CATALOG_MAX = 40;
+const UNCOVERED_CATALOG_MAX = 30;
+
 /**
  * @param {string} root
  * @param {Record<string, unknown>} config
@@ -45,6 +55,63 @@ export function summarizeRulesUnderContract(root, config, facts) {
       testFiles: coverageInputs.testFiles,
       testGlobsMissing: coverageInputs.testGlobsMissing,
     });
+    const covById = new Map(
+      (coverage.coverage ?? []).map((row) => [row.invariantId, row])
+    );
+    const byLayer = loaded.arkRules.byLayer ?? {};
+    const layers = Object.keys(byLayer)
+      .sort((a, b) => a.localeCompare(b))
+      .map((name) => {
+        const part = byLayer[name] ?? {};
+        const layerInvariants = part.invariants ?? [];
+        let covered = 0;
+        for (const inv of layerInvariants) {
+          if (covById.get(inv.id)?.covered) covered += 1;
+        }
+        return {
+          name,
+          sourceFile: part.sourceFile ?? null,
+          structureRules: (part.structure ?? []).length,
+          invariants: layerInvariants.length,
+          coveredInvariants: covered,
+          uncoveredInvariants: layerInvariants.length - covered,
+        };
+      });
+
+    const structureAll = (loaded.arkRules.structure ?? []).map((entry) => ({
+      id: entry.id,
+      sensor: entry.sensor,
+      mode: entry.mode ?? 'advisory',
+      layer: entry.provenance?.layer ?? null,
+      description: entry.description ?? null,
+      sourceFile: entry.provenance?.sourceFile ?? null,
+    }));
+    const structureTruncated = Math.max(0, structureAll.length - STRUCTURE_CATALOG_MAX);
+    const structure = structureAll.slice(0, STRUCTURE_CATALOG_MAX);
+
+    const uncoveredAll = (coverage.coverage ?? [])
+      .filter((row) => !row.covered)
+      .map((row) => ({
+        id: row.invariantId,
+        layer: row.layer ?? null,
+        mode: row.mode ?? null,
+        description: row.description ?? null,
+        sourceFile: row.sourceFile ?? null,
+      }));
+    const uncoveredTruncated = Math.max(0, uncoveredAll.length - UNCOVERED_CATALOG_MAX);
+    const uncovered = uncoveredAll.slice(0, UNCOVERED_CATALOG_MAX);
+
+    const coveredAll = (coverage.coverage ?? [])
+      .filter((row) => row.covered)
+      .map((row) => ({
+        id: row.invariantId,
+        layer: row.layer ?? null,
+        mode: row.mode ?? null,
+        description: row.description ?? null,
+      }));
+    const coveredTruncated = Math.max(0, coveredAll.length - COVERED_SAMPLE_MAX);
+    const coveredSample = coveredAll.slice(0, COVERED_SAMPLE_MAX);
+
     return {
       active: true,
       structureRules,
@@ -53,8 +120,15 @@ export function summarizeRulesUnderContract(root, config, facts) {
       uncoveredInvariants: coverage.coverage.filter((c) => !c.covered).length,
       partialCoverage: coverage.partial,
       testFilesScanned: coverageInputs.testFiles.length,
+      layers,
+      structure,
+      structureTruncated,
+      uncovered,
+      uncoveredTruncated,
+      coveredSample,
+      coveredTruncated,
       notAScore: true,
-      note: 'Counts only — never a score. Green with uncovered residual must say so.',
+      note: 'ArkRules plane (intra-layer) — counts and catalog, never a score. Green with uncovered residual must say so.',
     };
   } catch (error) {
     return {
@@ -64,3 +138,183 @@ export function summarizeRulesUnderContract(root, config, facts) {
     };
   }
 }
+
+/**
+ * Showcase HTML for the ArkRules plane (used by html-report-advisories).
+ * @param {ReturnType<typeof summarizeRulesUnderContract>|null|undefined} section
+ * @param {(v: unknown) => string} esc
+ */
+export function formatRulesUnderContractHtml(section, esc) {
+  if (!section || typeof section !== 'object') return '';
+  const escape = typeof esc === 'function' ? esc : (v) => String(v);
+  const note = section.note ? `<p class="muted">${escape(section.note)}</p>` : '';
+
+  if (section.active === false) {
+    return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules opt-in)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      Intra-layer plane (structure sensors + domain invariants as data). Separate from inter-layer import edges.
+    </p>
+    ${note}
+  </section>`;
+  }
+
+  if (Array.isArray(section.loadErrors) && section.loadErrors.length) {
+    const errs = section.loadErrors
+      .slice(0, 8)
+      .map((e) => `<li><code>${escape(e.path ?? '')}</code> — ${escape(e.message ?? e)}</li>`)
+      .join('');
+    return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(load errors)</span></h2>
+    ${note}
+    <ul class="senior-list">${errs}</ul>
+  </section>`;
+  }
+
+  const layers = Array.isArray(section.layers) ? section.layers : [];
+  const structure = Array.isArray(section.structure) ? section.structure : [];
+  const uncovered = Array.isArray(section.uncovered) ? section.uncovered : [];
+  const coveredSample = Array.isArray(section.coveredSample) ? section.coveredSample : [];
+  const coveredTruncated = Number(section.coveredTruncated) || 0;
+  const structureTruncated = Number(section.structureTruncated) || 0;
+  const uncoveredTruncated = Number(section.uncoveredTruncated) || 0;
+
+  const layerRows = layers
+    .map((row) => {
+      const cov =
+        row.invariants > 0
+          ? `${row.coveredInvariants}/${row.invariants} inv covered`
+          : 'no invariants';
+      return `<tr>
+        <td class="ln">${escape(row.name)}${
+          row.sourceFile ? `<div class="tags"><span class="tag"><code>${escape(row.sourceFile)}</code></span></div>` : ''
+        }</td>
+        <td class="num">${Number(row.structureRules) || 0}</td>
+        <td class="num">${Number(row.invariants) || 0}</td>
+        <td>${escape(cov)}${
+          row.uncoveredInvariants > 0
+            ? ` <span class="tag warn">${row.uncoveredInvariants} uncovered</span>`
+            : ''
+        }</td>
+      </tr>`;
+    })
+    .join('\n');
+
+  const layerTable = layers.length
+    ? `<table class="layers" style="margin-top:.55rem">
+        <thead><tr><th>Layer</th><th>Structure</th><th>Invariants</th><th>Coverage</th></tr></thead>
+        <tbody>${layerRows}</tbody>
+      </table>`
+    : '';
+
+  // Doctor JSON already caps catalogs; slice again only if a caller passed untruncated arrays.
+  const structureShown = structure.slice(0, STRUCTURE_CATALOG_MAX);
+  const structureOverflow =
+    structureTruncated > 0
+      ? structureTruncated
+      : Math.max(0, structure.length - STRUCTURE_CATALOG_MAX);
+  const structureItems = structureShown
+    .map((s) => {
+      const mode = s.mode === 'enforced' ? 'enforced' : s.mode === 'advisory' ? 'advisory' : String(s.mode ?? '');
+      const modeTag =
+        mode === 'enforced'
+          ? '<span class="tag">enforced</span>'
+          : `<span class="tag warn">${escape(mode || 'mode?')}</span>`;
+      return `<li>
+        <code>${escape(s.id)}</code>
+        ${modeTag}
+        <span class="dim">· ${escape(s.layer || '?')} · sensor <code>${escape(s.sensor || '')}</code></span>
+        ${s.description ? `<div class="msg">${escape(s.description)}</div>` : ''}
+      </li>`;
+    })
+    .join('\n');
+  const structureMore =
+    structureOverflow > 0
+      ? `<p class="muted">…(+${structureOverflow} more structure rule(s) in arkrules/*)</p>`
+      : '';
+
+  const uncoveredShown = uncovered.slice(0, UNCOVERED_CATALOG_MAX);
+  const uncoveredOverflow =
+    uncoveredTruncated > 0
+      ? uncoveredTruncated
+      : Math.max(0, uncovered.length - UNCOVERED_CATALOG_MAX);
+  const uncoveredItems = uncoveredShown
+    .map(
+      (u) => `<li>
+        <code>${escape(u.id)}</code>
+        <span class="tag warn">uncovered</span>
+        <span class="dim">· ${escape(u.layer || '?')}</span>
+        ${u.description ? `<div class="msg">${escape(u.description)}</div>` : ''}
+      </li>`
+    )
+    .join('\n');
+  const uncoveredMore =
+    uncoveredOverflow > 0
+      ? `<p class="muted">…(+${uncoveredOverflow} more uncovered)</p>`
+      : '';
+  const uncoveredBlock =
+    // Aggregate total (not the truncated array length) decides "all covered".
+    Number(section.uncoveredInvariants) === 0 && uncovered.length === 0
+      ? `<p class="clean-body" style="margin-top:.55rem">All catalogued invariants have coverage evidence (test/symbol scan) — residual inventory may still suggest new candidates via <code>--rules-inventory</code>.</p>`
+      : `<h3 style="margin-top:.9rem;font-size:.95rem">Uncovered invariants</h3>
+      <ul class="senior-list">${uncoveredItems}</ul>${uncoveredMore}`;
+
+  const coveredItems = coveredSample
+    .map(
+      (c) => `<li>
+        <code>${escape(c.id)}</code>
+        <span class="tag">covered</span>
+        <span class="dim">· ${escape(c.layer || '?')}</span>
+        ${c.description ? `<div class="msg">${escape(c.description)}</div>` : ''}
+      </li>`
+    )
+    .join('\n');
+  const coveredBlock =
+    coveredSample.length === 0
+      ? ''
+      : `<h3 style="margin-top:.9rem;font-size:.95rem">Covered invariants${
+          coveredTruncated > 0 ? ` <span class="dim">(sample of ${coveredSample.length})</span>` : ''
+        }</h3>
+      <ul class="senior-list">${coveredItems}</ul>
+      ${
+        coveredTruncated > 0
+          ? `<p class="muted">…(+${coveredTruncated} more covered — full catalog in <code>arkrules/*</code>)</p>`
+          : ''
+      }`;
+
+  return `
+  <section class="section card" data-advisory="rulesUnderContract">
+    <h2>Rules under contract <span class="muted">(ArkRules — not a score)</span></h2>
+    <p class="dim" style="margin:.15rem 0 .55rem;font-size:.88rem">
+      <b>[ArkRules]</b> Intra-layer plane — separate from <b>[Layer]</b> import edges above.
+      <b>Structure</b> = module-shape heuristics (not proof of Domain extraction).
+      <b>Invariants</b> = named policies + coverage evidence (symbol/test), not a business runtime
+      and not a fitness score.
+    </p>
+    <div class="kpis" style="margin-bottom:.55rem">
+      <div class="kpi"><b>${Number(section.structureRules) || 0}</b><span>Structure rules</span></div>
+      <div class="kpi"><b>${Number(section.invariants) || 0}</b><span>Invariants</span></div>
+      <div class="kpi"><b>${Number(section.coveredInvariants) || 0}</b><span>Covered</span></div>
+      <div class="kpi"><b>${Number(section.uncoveredInvariants) || 0}</b><span>Uncovered</span></div>
+    </div>
+    ${layers.length ? `<p class="dim" style="margin:0 0 .35rem;font-size:.86rem">${layers.length} layer(s) with an <code>arkRules</code> map entry · tests scanned: ${Number(section.testFilesScanned) || 0}</p>` : ''}
+    ${layerTable}
+    ${
+      structure.length
+        ? `<h3 style="margin-top:.9rem;font-size:.95rem">Structure sensors</h3>
+      <p class="muted" style="margin:.15rem 0 .4rem;font-size:.84rem">Heuristics of module shape. Enforced fails the check; it does not prove extraction to Domain.</p>
+      <ul class="senior-list">${structureItems}</ul>${structureMore}`
+        : '<p class="muted" style="margin-top:.55rem">No structure sensors in loaded ArkRules files.</p>'
+    }
+    ${uncoveredBlock}
+    ${coveredBlock}
+    ${
+      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>`
+        : ''
+    }
+    ${note}
+  </section>`;
+}