arkgate 3.0.3 → 3.0.4

package/CHANGELOG.md

@@ -4,7 +4,40 @@ All notable changes to ArkGate (`arkgate`; formerly `ark-runtime-kernel`) are do
 
 ## Unreleased
 
-No changes are scheduled after 3.0.3.
+No changes are scheduled after 3.0.4.
+
+## 3.0.4 — 2026-07-14
+
+Report honesty + showcase depth patch. **No breaking** CLI or `ark.config.json` changes.
+**No gate weaken.**
+
+### Fixed
+
+- **HTML report false ADAPT:** `computeReportFitness` counted *any* `optional: true` layer
+  with files as `coreOptionalWithFiles`, so doctor could report **ENFORCE** while
+  `ark-report.html` / `latest.json` mode stayed **ADAPT** (secondary layers like
+  SharedKernel / Integration / Workflow). Report now uses the same `CORE_LAYER_NAMES`
+  filter as doctor adoption (`DomainModel`, `ApplicationOrchestration`,
+  `PresentationAdapters`, `PersistenceAdapters`).
+- **False adoption gap `write-path-none` on report/CI:** when `activeHost` is `unknown`
+  (plain `npx ark-check --report` outside an agent session) but the repo inventory already
+  has hard-write hooks or advisory MCP for Claude/Grok/Cursor/Codex, doctor/report no longer
+  open a `write-path-none` adoption gap. Session projection still reports `mode: none` for
+  honesty (other hosts' hooks are not a guarantee for this process). `detectActiveAgentHost`
+  also recognizes `GROK_AGENT`.
+
+### Added
+
+- **Report metric hints:** HTML showcase KPIs (hero, adoption, contract density, debt) show
+  plain-language micro-copy under each tile plus native tooltips; PASS/mode badges and score
+  parts (Coverage/Clean/Gates/Rules) explain what they mean for newcomers.
+- **Report design-depth strip:** `ark-check --report` includes doctor-parity Shape residual
+  (design-weak badge, smell outcomes, one next pilot, post-green door, optional golden pattern).
+  Clean ENFORCE with no smells shows a short “Design depth · OK” note (only when sensors ran).
+- **Report adoption extras:** write-path line (active host · mode · inventory on disk) and a
+  fixed baseline-policy legend (`keep-empty` / `active-ratchet` / `absent`).
+
+Release note: `docs/releases/3.0.4.md`.
 
 ## 3.0.3 — 2026-07-13
 

package/bin/ark-check.mjs

@@ -58,6 +58,7 @@ import {
   reportsDir,
   readJsonSafe,
 } from './lib/html-report.mjs';
+import { buildReportDepthPayload } from './lib/html-report-depth.mjs';
 import { shouldOpenHtmlReport, openHtmlInBrowser } from './lib/open-html.mjs';
 import {
   computeCoverage,
@@ -1266,6 +1267,13 @@ async function main() {
     const existingOrigin = args.resetOrigin
       ? null
       : readJsonSafe(path.join(reportsDir(root), 'origin.json'));
+    const { adoption: adoptionForReport, designDepth } = buildReportDepthPayload(
+      root,
+      config,
+      files,
+      coverage,
+      activeViolations
+    );
     const reportPayload = {
       root,
       config,
@@ -1282,6 +1290,8 @@ async function main() {
       originSnapshot: existingOrigin,
       currentSnapshot,
       originJustCreated: !existingOrigin,
+      adoption: adoptionForReport,
+      designDepth,
     };
     const html = args.beginner
       ? renderBeginnerHtmlReport(reportPayload)

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

@@ -0,0 +1,282 @@
+/**
+ * Design-depth + adoption extras for the HTML showcase report.
+ * Kept separate from html-report.mjs so the main renderer stays under LOC budget.
+ * Does not import html-report.mjs (avoids a cycle).
+ */
+import {
+  detectDesignSmells,
+  summarizeDesignFitness,
+  buildPatternBetsFromSmells,
+} from './design-smells.mjs';
+import { summarizePilotLoop } from './pilot-loop.mjs';
+import { buildPostGreenNextAction } from './post-green-path.mjs';
+import { loadGoldenPattern, summarizeGoldenPattern } from './golden-pattern.mjs';
+import { collectAdoptionGaps } from './mcp-adoption.mjs';
+
+function esc(value) {
+  return String(value)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Doctor-parity design depth + adoption for ark-check --report.
+ * @param {string} root
+ * @param {object} config
+ * @param {string[]} files
+ * @param {object} coverage
+ * @param {object[]} activeViolations
+ */
+export function buildReportDepthPayload(root, config, files, coverage, activeViolations = []) {
+  const designSmells = detectDesignSmells(root, config, files, coverage);
+  const designFitness = summarizeDesignFitness(designSmells, {
+    activeViolations: activeViolations.length,
+    governedPercent: coverage?.governed?.percent,
+    totalFiles: coverage?.governed?.totalFiles,
+  });
+  const postGreenPath = buildPostGreenNextAction(designFitness);
+  const patternBets = buildPatternBetsFromSmells(designSmells);
+  const pilotLoop = summarizePilotLoop({
+    designWeak: designFitness.designWeak,
+    patternBets,
+    designSmells,
+  });
+  const goldenPattern = summarizeGoldenPattern(loadGoldenPattern(root));
+  const adoption = collectAdoptionGaps(root, config, coverage);
+  return {
+    adoption,
+    designDepth: {
+      designFitness,
+      designSmells,
+      pilotLoop,
+      postGreenPath,
+      goldenPattern,
+    },
+  };
+}
+
+/** Write-path mode → human meaning (active host projection). */
+export function writePathModeHint(mode) {
+  switch (String(mode || '')) {
+    case 'repair':
+      return 'Hard write hook with repair payload — best co-pilot path for the active host.';
+    case 'reject-only':
+      return 'Hard write boundary without repair payload; edits can be blocked without guided re-entry.';
+    case 'mcp-only':
+      return 'Advisory MCP only — prepare-write/autoPatch available, no hard PreToolUse for this host.';
+    case 'none':
+      return 'No hard write boundary or advisory MCP for the active host (or host is unknown in this process).';
+    default:
+      return 'Session write-path capability for the active agent host.';
+  }
+}
+
+/**
+ * Configured hosts from writePath inventory (hard or advisory evidence on disk).
+ * @param {object|null|undefined} writePath
+ * @returns {string[]}
+ */
+export function inventoryConfiguredHosts(writePath) {
+  const hosts = writePath?.inventory?.hosts;
+  if (!hosts || typeof hosts !== 'object') return [];
+  return Object.entries(hosts)
+    .filter(([, rec]) => rec && rec.configured)
+    .map(([name]) => name);
+}
+
+/**
+ * Compact write-path line for the Adoption card.
+ * @param {object|null|undefined} writePath
+ */
+export function renderWritePathAdoptionBlock(writePath) {
+  if (!writePath || typeof writePath !== 'object') return '';
+  const mode = writePath.mode || 'none';
+  const host = writePath.activeHost || 'unknown';
+  const inv = inventoryConfiguredHosts(writePath);
+  const invLine =
+    inv.length > 0
+      ? `Inventory on disk: ${inv.map((h) => esc(h)).join(', ')}.`
+      : 'No host write gates found on disk yet.';
+  const unknownNote =
+    host === 'unknown' && inv.length > 0
+      ? ' Session host unknown (shell/CI) — inventory is still real; set ARK_ACTIVE_HOST or run from an agent for session-accurate mode.'
+      : '';
+  const gapNote = writePath.gap
+    ? ` Gap: <b>${esc(writePath.gap.id)}</b> — ${esc(writePath.gap.message || '')}`
+    : '';
+  // invLine / gapNote already include escaped user content; only plain strings go through esc().
+  return `<div class="write-path-block" title="${esc(writePathModeHint(mode))}">
+      <p class="dim" style="margin:.65rem 0 .2rem;font-size:.84rem">
+        <b>Write path</b> · active host <code>${esc(host)}</code>
+        · mode <code>${esc(mode)}</code>
+        ${writePath.hookRepair ? '· repair ✓' : writePath.hookPresent ? '· reject-only' : ''}
+        ${writePath.mcpPresent ? '· MCP ✓' : ''}
+      </p>
+      <p class="kpi-hint" style="max-width:none;margin:0">
+        ${esc(writePathModeHint(mode))} ${invLine}${esc(unknownNote)}${gapNote}
+      </p>
+    </div>`;
+}
+
+/** Fixed legend for baseline policy signals. */
+export function renderBaselineSignalLegend() {
+  return `<details class="baseline-legend" style="margin-top:.75rem">
+      <summary>Baseline policy signals (legend)</summary>
+      <ul class="senior-list" style="margin-top:.4rem">
+        <li><b>keep-empty</b> — ${esc(baselineLegendBody('keep-empty'))}</li>
+        <li><b>active-ratchet</b> — ${esc(baselineLegendBody('active-ratchet'))}</li>
+        <li><b>absent</b> — ${esc(baselineLegendBody('absent'))}</li>
+      </ul>
+    </details>`;
+}
+
+function baselineLegendBody(signal) {
+  switch (signal) {
+    case 'keep-empty':
+      return '`.ark-baseline.json` exists with 0 frozen keys; every violation is active (honest green).';
+    case 'active-ratchet':
+      return 'Known debt keys are frozen; new distinct violations still fail the check.';
+    case 'absent':
+      return 'No baseline file — all findings are active (or freeze not adopted).';
+    default:
+      return '';
+  }
+}
+
+/**
+ * Design-weak / Shape residual strip for the showcase report.
+ * Null HTML when there is nothing useful to show.
+ *
+ * @param {{
+ *   designFitness?: object|null,
+ *   designSmells?: object[],
+ *   pilotLoop?: object|null,
+ *   postGreenPath?: object|null,
+ *   goldenPattern?: object|null,
+ *   mode?: string,
+ * }} depth
+ */
+export function renderDesignDepthStrip(depth = {}) {
+  const fitness = depth.designFitness;
+  const smells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
+  const designWeak = fitness?.designWeak === true;
+  if (!designWeak && smells.length === 0) return '';
+
+  const mode = String(depth.mode || '').toLowerCase();
+  const title = designWeak
+    ? mode === 'enforce'
+      ? 'ENFORCE · design-weak'
+      : `${(mode || 'edges').toUpperCase()} · design-weak`
+    : 'Design smells (edges still open)';
+  const lede = designWeak
+    ? 'Contract edges are clean, but lived design residual remains. This does not fail PASS — it blocks “healthy finished” until Shape work lands.'
+    : 'Design smells exist alongside open edge debt. Fix edges first; treat smells as Shape residual after green.';
+
+  const smellItems = smells
+    .slice(0, 6)
+    .map((s) => {
+      const outcome = s.outcome || s.message || s.id;
+      const evidence = (s.evidence || [])
+        .filter((e) => typeof e === 'string' && !e.startsWith('layer:') && !e.startsWith('layout:'))
+        .slice(0, 3);
+      const ev =
+        evidence.length > 0
+          ? ` <span class="dim">· ${evidence.map((e) => `<code>${esc(e)}</code>`).join(' ')}</span>`
+          : '';
+      return `<li><b>${esc(s.id)}</b> — ${esc(outcome)}${ev}</li>`;
+    })
+    .join('');
+
+  const pilot = depth.pilotLoop?.active && depth.pilotLoop?.nextPilot ? depth.pilotLoop.nextPilot : null;
+  const pilotHtml = pilot
+    ? `<div class="pilot-card">
+        <h3 style="margin-top:.85rem">Next pilot (one at a time)</h3>
+        <p class="dim" style="margin:.15rem 0 .4rem;font-size:.86rem">
+          Judgment only — never mechanical-safe · never multi-pilot batch
+        </p>
+        <ul class="senior-list">
+          <li><b>Smell</b> · <code>${esc(pilot.smellId || pilot.id || '—')}</code></li>
+          <li><b>Target</b> · <code>${esc(pilot.pilotTarget || pilot.pilot || '—')}</code></li>
+          ${
+            pilot.move || pilot.fix
+              ? `<li><b>Move</b> · ${esc(pilot.move || pilot.fix)}</li>`
+              : ''
+          }
+          ${
+            pilot.successSignal
+              ? `<li><b>Success</b> · ${esc(pilot.successSignal)}</li>`
+              : ''
+          }
+          ${
+            pilot.killSwitch
+              ? `<li><b>Kill-switch</b> · ${esc(pilot.killSwitch)}</li>`
+              : ''
+          }
+        </ul>
+      </div>`
+    : '';
+
+  const next =
+    depth.postGreenPath?.short ||
+    depth.postGreenPath?.action ||
+    (designWeak
+      ? '/ark-explore shape-focus → dual-plan B, then /ark-autopilot only with OK'
+      : null);
+  const nextHtml = next
+    ? `<p class="meta" style="margin-top:.75rem"><b>Primary next</b> · ${esc(next)}</p>`
+    : '';
+
+  const golden = depth.goldenPattern;
+  const goldenHtml =
+    golden && golden.present !== false && (golden.name || golden.norm)
+      ? `<p class="dim" style="margin-top:.5rem;font-size:.84rem">
+          Golden pattern (advisory for <b>new</b> code only):
+          <code>${esc(golden.name || 'pattern')}</code>
+          ${golden.norm ? ` — ${esc(golden.norm)}` : ''}
+          ${golden.examplePath ? ` · e.g. <code>${esc(golden.examplePath)}</code>` : ''}
+        </p>`
+      : designWeak
+        ? `<p class="dim" style="margin-top:.5rem;font-size:.84rem">
+            No <code>.ark/golden-pattern.json</code> yet — optional; helps agents place <b>new</b> code only.
+          </p>`
+        : '';
+
+  return `<div class="section card design-strip ${designWeak ? 'is-weak' : 'has-smells'}" id="design-depth">
+      <div class="design-head">
+        <span class="badge design" title="Shape residual — separate from PASS/FAIL edge honesty">${esc(title)}</span>
+        <span class="dim" style="font-size:.86rem">${designWeak ? 'Edges clean · residual remains' : 'Smells + open edges'}</span>
+      </div>
+      <p class="dim" style="margin:.55rem 0 .5rem;font-size:.9rem">${esc(lede)}</p>
+      ${smellItems ? `<ul class="senior-list">${smellItems}</ul>` : ''}
+      ${pilotHtml}
+      ${nextHtml}
+      ${goldenHtml}
+    </div>`;
+}
+
+/**
+ * Optional clean-depth note when edges + design are both healthy.
+ * Requires designFitness from a real sensor run (object). Null/undefined means
+ * depth was not computed — do not claim “OK” from missing data.
+ * @param {{ designFitness?: object|null, ok?: boolean, mode?: string }} depth
+ */
+export function renderDesignCleanNote(depth = {}) {
+  if (!depth.ok) return '';
+  // Sensors never ran (callers that omit designDepth) → no strip.
+  if (depth.designFitness == null || typeof depth.designFitness !== 'object') return '';
+  if (depth.designFitness.designWeak) return '';
+  if ((depth.designFitness.smellCount ?? 0) > 0) return '';
+  if (String(depth.mode || '').toLowerCase() !== 'enforce') return '';
+  return `<div class="section card design-strip is-clean" id="design-depth">
+      <div class="design-head">
+        <span class="badge design-ok" title="No deterministic design smells with clean edges">Design depth · OK</span>
+        <span class="dim" style="font-size:.86rem">No design-weak residual detected</span>
+      </div>
+      <p class="dim" style="margin:.45rem 0 0;font-size:.88rem">
+        Edges and deterministic design sensors agree. Keep placing new code on the golden path;
+        re-run doctor after large refactors.
+      </p>
+    </div>`;
+}

package/bin/lib/html-report.mjs

@@ -11,6 +11,13 @@ import {
   resolveOperatingMode,
 } from '../ark-shared.mjs';
 import { collectAdoptionGaps, arkCheckCommand } from './agent-gates.mjs';
+import { CORE_LAYER_NAMES } from './core-layers.mjs';
+import {
+  renderBaselineSignalLegend,
+  renderDesignCleanNote,
+  renderDesignDepthStrip,
+  renderWritePathAdoptionBlock,
+} from './html-report-depth.mjs';
 import { FIX_HINTS } from './violations.mjs';
 
 export function detectEnforcement(root) {
@@ -58,6 +65,53 @@ export function htmlEscape(value) {
     .replace(/"/g, '"');
 }
 
+/**
+ * KPI tile with plain-language hint (visible micro-copy + native tooltip).
+ * Helps newcomers read the showcase without memorizing Ark jargon.
+ *
+ * @param {string|number} value
+ * @param {string} label short metric name
+ * @param {string} hint one-sentence meaning
+ */
+export function metricKpi(value, label, hint) {
+  const v = htmlEscape(String(value));
+  const l = htmlEscape(label);
+  const h = htmlEscape(hint);
+  return `<div class="kpi" title="${h}" aria-label="${l}: ${v}. ${h}">
+        <b>${v}</b>
+        <span>${l}</span>
+        <em class="kpi-hint">${h}</em>
+      </div>`;
+}
+
+/** Baseline policy signal → human meaning (adoption card). */
+export function baselineSignalHint(signal) {
+  switch (String(signal || '')) {
+    case 'keep-empty':
+      return 'Baseline file exists and freezes 0 keys — every violation is active (honest green).';
+    case 'active-ratchet':
+      return 'Baseline freezes known debt keys; new distinct violations still fail the check.';
+    case 'absent':
+      return 'No .ark-baseline.json — all findings are active (or you have not adopted a freeze file).';
+    default:
+      return 'How frozen debt is handled relative to active architecture violations.';
+  }
+}
+
+/** Operating mode badge tooltip. */
+export function modeBadgeHint(mode) {
+  switch (String(mode || '').toLowerCase()) {
+    case 'enforce':
+      return 'Contract matches the tree: cores are required where populated, coverage is honest, gates can hold the line.';
+    case 'adapt':
+      return 'Contract is live but still aligning (optional cores with files, empty cores, or presentation-bag false green).';
+    case 'suggest':
+      return 'Starter shape — expand layers and raise governed coverage as the codebase grows.';
+    default:
+      return 'Operating mode for co-pilot surfaces (suggest · adapt · enforce).';
+  }
+}
+
 /** Directory for origin / latest / history architecture report snapshots. */
 const ARK_REPORTS_DIR = path.join('.ark', 'reports');
 const ARK_REPORT_HISTORY_MAX = 20;
@@ -159,7 +213,10 @@ export function computeReportFitness({ coverage, violations, ok, enforcement, co
   const presentationRow = (coverage?.layers ?? []).find(
     (r) => r.name === 'PresentationAdapters'
   );
+  // Same honesty gate as doctor (`mcp-adoption` coreOptional): only the four cores
+  // matter. Secondary optional layers with files must not force ADAPT on the HTML report.
   const coreOptionalWithFiles = (config?.layers ?? []).filter((layer) => {
+    if (!CORE_LAYER_NAMES.has(layer.name)) return false;
     if (layer.optional !== true) return false;
     const row = (coverage?.layers ?? []).find((r) => r.name === layer.name);
     return (row?.files ?? 0) > 0;
@@ -396,6 +453,8 @@ export function renderHtmlReport({
   currentSnapshot = null,
   originJustCreated = false,
   adoption = null,
+  /** Optional design-depth (doctor parity): designFitness, designSmells, pilotLoop, postGreenPath, goldenPattern */
+  designDepth = null,
 }) {
   const layers = Array.isArray(config.layers) ? config.layers : [];
   const rules = Array.isArray(config.rules) ? config.rules : [];
@@ -448,6 +507,29 @@ export function renderHtmlReport({
   } = fitness;
 
   const adoptionView = adoption || collectAdoptionGaps(root, config, coverage);
+  const depth = designDepth && typeof designDepth === 'object' ? designDepth : {};
+  const designFitness = depth.designFitness ?? null;
+  const designSmells = Array.isArray(depth.designSmells) ? depth.designSmells : [];
+  const designWeakBadge =
+    designFitness?.designWeak === true
+      ? ` <span class="badge design" title="Edges can be green while lived design residual remains (Shape). Not a FAIL.">design-weak</span>`
+      : '';
+  const designStripHtml =
+    renderDesignDepthStrip({
+      designFitness,
+      designSmells,
+      pilotLoop: depth.pilotLoop,
+      postGreenPath: depth.postGreenPath,
+      goldenPattern: depth.goldenPattern,
+      mode,
+    }) ||
+    renderDesignCleanNote({
+      designFitness,
+      ok,
+      mode,
+    });
+  const writePathHtml = renderWritePathAdoptionBlock(adoptionView.writePath);
+  const baselineLegendHtml = renderBaselineSignalLegend();
 
   // ── Senior diagnostics (coupling, purity, contract density) ──────────────
   const layerNames = ordered.map((l) => l.name);
@@ -818,9 +900,33 @@ export function renderHtmlReport({
   .score-cap { color: var(--dim); font-size: .85rem; margin: 0; }
   .kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: .65rem; margin: 1rem 0 0; }
   @media (max-width: 720px) { .kpis { grid-template-columns: repeat(2, 1fr); } }
-  .kpi { background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .7rem .8rem; }
+  .kpi { background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .7rem .8rem; cursor: help; }
   .kpi b { display: block; font-size: 1.25rem; letter-spacing: -0.02em; }
   .kpi span { color: var(--dim); font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; }
+  .kpi-hint {
+    display: block; margin-top: .4rem; color: var(--dim); font-size: .68rem; font-style: normal;
+    font-weight: 450; line-height: 1.35; letter-spacing: 0; text-transform: none; max-width: 16rem;
+  }
+  .score-parts span { cursor: help; border-bottom: 1px dotted color-mix(in srgb, var(--dim) 55%, transparent); }
+  .badge[title] { cursor: help; }
+  .badge.design {
+    background: color-mix(in srgb, var(--gold) 18%, transparent); color: var(--gold);
+    border-color: color-mix(in srgb, var(--gold) 40%, transparent);
+  }
+  .badge.design-ok {
+    background: color-mix(in srgb, var(--green) 16%, transparent); color: var(--green);
+    border-color: color-mix(in srgb, var(--green) 35%, transparent);
+  }
+  .design-strip { border-left: 3px solid var(--gold); }
+  .design-strip.is-clean { border-left-color: var(--green); }
+  .design-strip.has-smells { border-left-color: var(--gold); }
+  .design-head { display: flex; flex-wrap: wrap; gap: .5rem; align-items: center; }
+  .pilot-card {
+    margin-top: .35rem; padding: .75rem .9rem; border-radius: 12px;
+    background: var(--panel2); border: 1px solid var(--line);
+  }
+  .write-path-block { margin-top: .15rem; }
+  .baseline-legend summary { cursor: pointer; color: var(--dim); font-size: .84rem; }
   .section { margin-top: 1.35rem; }
   .grid-2 { display: grid; grid-template-columns: 1.1fr 0.9fr; gap: 1rem; }
   @media (max-width: 900px) { .grid-2 { grid-template-columns: 1fr; } }
@@ -936,34 +1042,79 @@ export function renderHtmlReport({
   <div class="hero">
     <div class="card">
       <div class="brand"><i></i> Ark architecture report</div>
-      <h1>${esc(project)} <span class="badge ${status}">${status}</span> <span class="badge mode">${esc(modeLabel)}</span></h1>
-      <p class="lede">${esc(modeBlurb)} One machine-readable contract · write gate · CI · optional runtime.</p>
+      <h1>${esc(project)} <span class="badge ${status}" title="${status === 'PASS' ? 'Architecture check is green: 0 active violations against the contract.' : 'Architecture check failed: active violations remain (or the scan could not complete cleanly).'}">${status}</span> <span class="badge mode" title="${esc(modeBadgeHint(mode))}">${esc(modeLabel)}</span>${designWeakBadge}</h1>
+      <p class="lede">${esc(modeBlurb)}${designFitness?.designWeak ? ' Design residual remains (see strip below) — not a FAIL.' : ''} One machine-readable contract · write gate · CI · optional runtime.</p>
       <div class="kpis">
-        <div class="kpi"><b>${esc(govLabel)}</b><span>Governed</span></div>
-        <div class="kpi"><b>${layers.length}</b><span>Layers</span></div>
-        <div class="kpi"><b>${gatesOn}/${enforcement.length}</b><span>Gates live</span></div>
-        <div class="kpi"><b>${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}</b><span>Violations${suppressed ? ' · frozen' : ''}</span></div>
+        ${metricKpi(
+          govLabel,
+          'Governed',
+          'Share of scanned files assigned to a contract layer. 100% means every in-scope file has a home.'
+        )}
+        ${metricKpi(
+          layers.length,
+          'Layers',
+          'How many architecture layers the contract defines (cores + optional product layers).'
+        )}
+        ${metricKpi(
+          `${gatesOn}/${enforcement.length}`,
+          'Gates live',
+          'Write hook, CI workflow, ESLint plugin, and baseline file — how many enforcement points are actually present.'
+        )}
+        ${metricKpi(
+          `${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}`,
+          `Violations${suppressed ? ' · frozen' : ''}`,
+          suppressed
+            ? 'Active contract breaks right now; Δ = keys frozen in baseline (not failing until ratchet).'
+            : 'Active contract breaks (layer imports, purity, etc.). Zero means edges match the rules.'
+        )}
       </div>
       <p class="meta">${meta}</p>
       ${skillsNote}
     </div>
-    <div class="card score-card">
+    <div class="card score-card" title="Human fitness signal only — not a CI gate. Weighted blend of coverage, cleanliness, live gates, and rule density.">
       <div class="score-ring ${scoreTone}"><div><div class="score-n">${score}</div><div class="dim" style="font-size:.72rem;letter-spacing:.08em;text-transform:uppercase">Ark score</div></div></div>
       <p class="score-cap">${esc(scoreCaption)}</p>
-      <p class="meta" style="margin-top:.65rem">Coverage ${scoreCoverage} · Clean ${scoreClean} · Gates ${scoreGates} · Rules ${scoreRules}</p>
+      <p class="meta score-parts" style="margin-top:.65rem">
+        <span title="0.4 weight — governed file percent (or 50 if coverage unknown).">${esc(`Coverage ${scoreCoverage}`)}</span>
+        · <span title="0.3 weight — 100 with zero active violations; drops as violations pile up.">${esc(`Clean ${scoreClean}`)}</span>
+        · <span title="0.2 weight — share of enforcement points that are present on disk (hook, CI, ESLint, baseline).">${esc(`Gates ${scoreGates}`)}</span>
+        · <span title="0.1 weight — how dense the deny matrix is relative to layer pairs (stricter inward architecture scores higher).">${esc(`Rules ${scoreRules}`)}</span>
+      </p>
     </div>
   </div>
 
+  ${designStripHtml}
+
   <div class="section card" id="adoption">
     <h2>Adoption</h2>
     <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
       Co-pilot completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
     </p>
     <div class="kpis" style="margin-bottom:.75rem">
-      <div class="kpi"><b>${adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length}</b><span>${adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)'}</span></div>
-      <div class="kpi"><b>${adoptionView.originReport.present ? 'yes' : 'no'}</b><span>Origin report</span></div>
-      <div class="kpi"><b>${esc(adoptionView.baseline.signal)}</b><span>Baseline policy</span></div>
-      <div class="kpi"><b>${adoptionView.mcp.ok ? 'ok' : 'fix'}</b><span>Repo MCP argv</span></div>
+      ${metricKpi(
+        adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length,
+        adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)',
+        adoptionView.gaps.length === 0
+          ? 'Hosts, MCP argv, origin snapshot, and core optionality look complete for co-pilot use.'
+          : 'Install or fix the listed gaps so agents get write gates, MCP, and honest cores.'
+      )}
+      ${metricKpi(
+        adoptionView.originReport.present ? 'yes' : 'no',
+        'Origin report',
+        'First architecture snapshot under .ark/reports/origin.* — future reports show evolution deltas against it.'
+      )}
+      ${metricKpi(
+        adoptionView.baseline.signal,
+        'Baseline policy',
+        baselineSignalHint(adoptionView.baseline.signal)
+      )}
+      ${metricKpi(
+        adoptionView.mcp.ok ? 'ok' : 'fix',
+        'Repo MCP argv',
+        adoptionView.mcp.ok
+          ? 'Repo MCP config points at a single ark/arkgate MCP bin (no dual-bin conflict).'
+          : 'Broken MCP argv: more than one of ark-mcp/arkgate-mcp — migrate with --install-agent-gates --migrate-commands.'
+      )}
     </div>
     ${
       adoptionView.gaps.length
@@ -991,6 +1142,8 @@ export function renderHtmlReport({
             .join(' · ')}</p>`
         : ''
     }
+    ${writePathHtml}
+    ${baselineLegendHtml}
   </div>
 
   <div class="section grid-2">
@@ -1138,10 +1291,26 @@ export function renderHtmlReport({
 
     <h3>Contract density</h3>
     <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${denyRatio}%</b><span>Edges denied</span></div>
-      <div class="kpi"><b>${deniedCount}</b><span>Deny rules</span></div>
-      <div class="kpi"><b>${allowedCount}</b><span>Explicit allows</span></div>
-      <div class="kpi"><b>${pairCount}</b><span>Directed pairs</span></div>
+      ${metricKpi(
+        `${denyRatio}%`,
+        'Edges denied',
+        'Denied directed layer pairs ÷ all possible pairs. Higher = stricter inward dependency rules.'
+      )}
+      ${metricKpi(
+        deniedCount,
+        'Deny rules',
+        'Explicit allowed:false rules in ark.config.json (row may not import column).'
+      )}
+      ${metricKpi(
+        allowedCount,
+        'Explicit allows',
+        'Explicit allowed:true edges. Most opens are implicit (no rule) unless you document them.'
+      )}
+      ${metricKpi(
+        pairCount,
+        'Directed pairs',
+        'layers × (layers − 1) — every ordered from→to pair the matrix can constrain.'
+      )}
     </div>
     <p class="dim" style="margin:.55rem 0 0;font-size:.84rem">
       Deny ratio = denied ÷ (layers × (layers−1)). High ratio = strict inward architecture.
@@ -1270,10 +1439,26 @@ export function renderHtmlReport({
 
     <h3>Debt &amp; violation taxonomy</h3>
     <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${violations.length}</b><span>Active</span></div>
-      <div class="kpi"><b>${valueN}</b><span>Value edges</span></div>
-      <div class="kpi"><b>${typeOnlyN}</b><span>Type-only</span></div>
-      <div class="kpi"><b>${suppressed || baselineKeys}</b><span>Baseline keys</span></div>
+      ${metricKpi(
+        violations.length,
+        'Active',
+        'Violations that fail the check right now (not frozen by baseline).'
+      )}
+      ${metricKpi(
+        valueN,
+        'Value edges',
+        'Runtime import edges that cross a deny rule (stronger debt than type-only).'
+      )}
+      ${metricKpi(
+        typeOnlyN,
+        'Type-only',
+        'Type-only imports across a deny edge — often mechanical-safe to rewrite as import type.'
+      )}
+      ${metricKpi(
+        suppressed || baselineKeys,
+        'Baseline keys',
+        'Distinct frozen debt keys in .ark-baseline.json (or suppressed count for this run).'
+      )}
     </div>
     ${
       topEdges.length
@@ -1291,6 +1476,14 @@ export function renderHtmlReport({
         Coverage=${scoreCoverage}, clean=${scoreClean}, gates=${scoreGates}, rules=${scoreRules} → <b>${score}</b>.
         This is a fitness signal for humans, not a CI gate.
       </p>
+      <ul class="senior-list" style="margin-top:.45rem">
+        <li><b>Coverage</b> — % of in-scope files that match a layer pattern.</li>
+        <li><b>Clean</b> — 100 with zero active violations; falls as breaks accumulate.</li>
+        <li><b>Gates</b> — share of write / CI / ESLint / baseline enforcement points present.</li>
+        <li><b>Rules</b> — deny-matrix density (more inward denies → higher component).</li>
+        <li><b>PASS / FAIL</b> — binary edge honesty (active violations), independent of the 0–100 score.</li>
+        <li><b>SUGGEST / ADAPT / ENFORCE</b> — whether the contract is honest enough to protect the tree (not a skill grade).</li>
+      </ul>
     </details>
   </div>
 

package/bin/lib/skill-install.mjs

@@ -43,10 +43,11 @@ export function detectActiveAgentHost(env = process.env) {
     .toLowerCase();
   if (explicit) return explicit;
 
-  // Grok / xAI Build
+  // Grok / xAI Build (include GROK_AGENT — common session signal missing in older detect)
   if (
     envTruthy(env.GROK_BUILD) ||
     envTruthy(env.XAI_GROK) ||
+    envTruthy(env.GROK_AGENT) ||
     env.GROK_WORKSPACE_ROOT ||
     env.GROK_SESSION_ID
   ) {

package/bin/lib/write-path-detect.mjs

@@ -30,21 +30,32 @@ export function detectWritePathCapabilities(root, explicitHost) {
 
   const tools = installToolsForHost(activeHost);
   let gap = null;
+  // Repo inventory (any host) can show hard/advisory write while activeHost is
+  // unknown (plain shell / `npx ark-check --report` outside an agent session).
+  // Session projection stays mode=none (other hosts' hooks are not a guarantee for
+  // this process) — but do not open an adoption gap: gates exist on disk.
+  const inventoryHasWriteBoundary =
+    Boolean(inventory?.capabilities?.['hard-write']) ||
+    Boolean(inventory?.capabilities?.['advisory-write']);
   if (mode === 'none') {
-    gap = {
-      id: 'write-path-none',
-      severity: 'warn',
-      message:
-        `Active host ${activeHost} has no hard write boundary or advisory Ark MCP. ` +
-        (capabilities['merge-gate']
-          ? 'The CI check remains separate and does not block local writes.'
-          : 'No Ark CI check was detected either.'),
-      fix: arkCommand(
-        root,
-        'ark-check',
-        `--install-agent-gates --tools ${tools}`
-      ),
-    };
+    if (activeHost === 'unknown' && inventoryHasWriteBoundary) {
+      gap = null;
+    } else {
+      gap = {
+        id: 'write-path-none',
+        severity: 'warn',
+        message:
+          `Active host ${activeHost} has no hard write boundary or advisory Ark MCP. ` +
+          (capabilities['merge-gate']
+            ? 'The CI check remains separate and does not block local writes.'
+            : 'No Ark CI check was detected either.'),
+        fix: arkCommand(
+          root,
+          'ark-check',
+          `--install-agent-gates --tools ${tools}`
+        ),
+      };
+    }
   } else if (mode === 'reject-only') {
     gap = {
       id: 'write-path-reject-only',

package/dist/index.cjs

@@ -50,7 +50,7 @@ __export(gate_exports, {
 module.exports = __toCommonJS(gate_exports);
 
 // src/version.ts
-var version = "3.0.3";
+var version = "3.0.4";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/dist/index.d.cts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.cjs';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.3";
+declare const version = "3.0.4";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.d.ts

@@ -2,7 +2,7 @@ import { a as ArkConfigRule, b as ArkConfigLayer, A as ArkConfig, c as ArkConfig
 export { d as ARK_CONFIG_SCHEMA, e as ARK_CONFIG_SCHEMA_VERSION, l as loadArkConfigContract, p as parseArkConfigJson } from './configContract-BxSIwVRo.js';
 
 /** ArkGate library version — single source of truth. */
-declare const version = "3.0.3";
+declare const version = "3.0.4";
 
 /** Versioned public result contract shared by every ArkGate enforcement adapter. */
 declare const ARK_ANALYSIS_RESULT_SCHEMA_VERSION: "1.0";

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/version.ts
-var version = "3.0.3";
+var version = "3.0.4";
 
 // src/domain/adapterContract.ts
 var ARK_ANALYSIS_RESULT_SCHEMA_VERSION = "1.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkgate",
-  "version": "3.0.3",
+  "version": "3.0.4",
   "description": "ArkGate — architecture co-pilot for AI TypeScript (write gate, CI gate, plan/loop)",
   "type": "module",
   "main": "./dist/index.cjs",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/pedroknigge/arkgate",
     "source": "github"
   },
-  "version": "3.0.3",
+  "version": "3.0.4",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "arkgate",
-      "version": "3.0.3",
+      "version": "3.0.4",
       "runtimeHint": "npx",
       "transport": {
         "type": "stdio"