@holmes-lab/holmes-kit 0.10.1 → 0.12.0

package/dist/holmes/server/dashboard.js

@@ -50,6 +50,11 @@ const cpg_scanner_1 = require("../cpg/cpg-scanner");
 const language_parser_1 = require("../cpg/language-parser");
 const findings_1 = require("../review/findings");
 const ast_mutation_1 = require("../cpg/ast-mutation");
+const rtm_matrix_1 = require("./rtm-matrix");
+const ast_store_1 = require("../cpg/foundation/ast-store");
+const cfg_1 = require("../cpg/foundation/cfg");
+const cdg_1 = require("../cpg/foundation/cdg");
+const cfg_view_1 = require("./cfg-view");
 /**
  * Start a lightweight standalone Node.js HTTP server for interactive dashboard & RTM visualization.
  *
@@ -183,6 +188,8 @@ async function startDashboardServer(options) {
                 const findingsLedger = new findings_1.FindingsLedger(findingsPath);
                 const allFindings = findingsScanned ? findingsLedger.list() : [];
                 const pipelines = buildPipelineRows(specs, files, allFindings, { findingsScanned });
+                // @implements A-SPEC-545.2 — seriated REQ × stage coverage matrix (additive; pipelines unchanged).
+                const matrix = (0, rtm_matrix_1.heatmapMatrix)(pipelines);
                 const body = JSON.stringify({
                     ok: true,
                     pipelineCount: pipelines.length,
@@ -190,6 +197,7 @@ async function startDashboardServer(options) {
                     findingsScanned,
                     mutationScoreMeasured: false,
                     pipelines,
+                    matrix,
                 });
                 res.writeHead(200, { 'Content-Type': 'application/json' });
                 res.end(body);
@@ -202,6 +210,78 @@ async function startDashboardServer(options) {
             }
             return;
         }
+        // @implements A-SPEC-545.4 — one function's CFG + PDG (data/control deps), from the same cfgOf/pdgOf
+        // the taint lane uses. Honest envelope: a non-CFG language is named, never faked as an empty graph.
+        if (parsedUrl === '/api/cfg') {
+            try {
+                const q = new URL(req.url || '/', 'http://localhost').searchParams;
+                const file = q.get('file');
+                const symbol = q.get('symbol');
+                if (!file || !symbol) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, reason: 'file and symbol query params are required' }));
+                    return;
+                }
+                const files = scanner.scan(root);
+                const scanned = files.find((f) => f.sourcePath === file);
+                const sym = scanned?.symbols.find((s) => s.name === symbol);
+                const lang = (0, ast_store_1.languageFor)(file)?.lang ?? null;
+                if (!scanned || !sym) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, reason: `symbol ${symbol} not found in ${file}`, file, symbol, lang }));
+                    return;
+                }
+                if (!lang || !cfg_1.CFG_LANGUAGES.has(lang)) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, file, symbol, lang, unsupported: lang ?? 'unknown' }));
+                    return;
+                }
+                const source = fs.readFileSync(path.join(root, file), 'utf8');
+                const ast = await (0, ast_store_1.parseAst)(source, file);
+                if (!ast) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, reason: `could not parse ${file}`, file, symbol, lang }));
+                    return;
+                }
+                // Pick the function whose declaration line is closest to the scanned symbol's start line
+                // (absorbs any 0/1-based drift between the scanner and the AST byte→line mapping).
+                const fns = (0, cfg_1.functionsIn)(ast);
+                let best = null;
+                let bestDist = Infinity;
+                for (const fn of fns) {
+                    const node = ast.nodes[fn.nodeIndex];
+                    if (!node)
+                        continue;
+                    const dist = Math.abs((0, cfg_view_1.lineAtByte)(source, node.start) - sym.startLine);
+                    if (dist < bestDist) {
+                        bestDist = dist;
+                        best = fn;
+                    }
+                }
+                if (!best) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, reason: `no function body for ${symbol} in ${file}`, file, symbol, lang }));
+                    return;
+                }
+                const cfg = (0, cfg_1.cfgOf)(ast, best, source);
+                const pdg = (0, cdg_1.pdgOf)(ast, cfg, best, source);
+                const view = (0, cfg_view_1.buildCfgView)(cfg, pdg, ast, source);
+                if ('unsupported' in view) {
+                    res.writeHead(200, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true, file, symbol, lang, unsupported: view.unsupported }));
+                    return;
+                }
+                res.writeHead(200, { 'Content-Type': 'application/json' });
+                res.end(JSON.stringify({ ok: true, file, symbol, lang, cfg: view }));
+            }
+            catch (err) {
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: 'Internal Server Error' }));
+                }
+            }
+            return;
+        }
         if (parsedUrl === '/api/cpg') {
             try {
                 const files = scanner.scan(root);
@@ -388,7 +468,57 @@ function renderDashboardHtml() {
   <title>Holmes-Kit World Top-Tier Quantitative RTM Matrix & AST/CPG Graph Canvas</title>
   <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
   <style>
-    body { font-family: system-ui, -apple-system, sans-serif; background-color: #0b0f19; color: #f8fafc; margin: 0; padding: 24px; user-select: none; }
+    /* @implements A-SPEC-545.2 — design tokens: sequential coverage ramp, status, surfaces, 2 fonts.
+       Dark-first; light palette under prefers-color-scheme. The green ramp reads "traced". */
+    :root {
+      --surface-0: #0d1417; --surface-1: #131e22; --surface-2: #1b2b30; --border: #26383d;
+      --ink-0: #eaf2f0; --ink-1: #9fb2b0; --ink-2: #6b807e;
+      --ramp-0: #17211d; --ramp-1: #1f3a2c; --ramp-2: #26543a; --ramp-3: #2c7449; --ramp-4: #33a35f; --ramp-5: #46d97e;
+      --ramp-ink-lo: #8ba39c; --ramp-ink-hi: #06120c;
+      --ok: #46d97e; --warn: #e0a83c; --bad: #e5595c; --accent: #46b0d9;
+      --font-ui: ui-sans-serif, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+      --font-mono: ui-monospace, "SF Mono", "JetBrains Mono", "Cascadia Code", Menlo, Consolas, monospace;
+    }
+    @media (prefers-color-scheme: light) {
+      :root {
+        --surface-0: #f4f7f6; --surface-1: #ffffff; --surface-2: #eaf0ee; --border: #d3ddda;
+        --ink-0: #12201c; --ink-1: #4a5c58; --ink-2: #7b8d89;
+        --ramp-0: #e7efe9; --ramp-1: #c3e0cd; --ramp-2: #8fc9a5; --ramp-3: #54ac77; --ramp-4: #2f8a54; --ramp-5: #166b3c;
+        --ramp-ink-lo: #5b6f69; --ramp-ink-hi: #f4faf6;
+        --ok: #166b3c; --warn: #b7791f; --bad: #c53539; --accent: #1f7fa6;
+      }
+    }
+    body { font-family: var(--font-ui); background-color: var(--surface-0); color: var(--ink-0); margin: 0; padding: 24px; user-select: none; }
+
+    /* Seriated REQ × stage coverage matrix (2D grid) */
+    .hm-toolbar { display: flex; align-items: baseline; gap: 14px; flex-wrap: wrap; margin-bottom: 12px; color: var(--ink-1); font-size: 12px; }
+    .hm-legend { display: inline-flex; align-items: center; gap: 6px; }
+    .hm-legend-swatch { width: 16px; height: 12px; border-radius: 2px; display: inline-block; border: 1px solid var(--border); }
+    .hm-scroll { max-height: 74vh; overflow: auto; border: 1px solid var(--border); border-radius: 12px; background: var(--surface-1); }
+    table.hm-grid { border-collapse: separate; border-spacing: 0; width: 100%; font-family: var(--font-mono); }
+    table.hm-grid th, table.hm-grid td { border-bottom: 1px solid var(--surface-0); border-right: 1px solid var(--surface-0); }
+    table.hm-grid thead th { position: sticky; top: 0; z-index: 3; background: var(--surface-2); color: var(--ink-1);
+      font-family: var(--font-ui); font-size: 10px; font-weight: 700; letter-spacing: 0.6px; text-transform: uppercase;
+      padding: 10px 8px; text-align: center; white-space: nowrap; }
+    table.hm-grid thead th.hm-corner { left: 0; z-index: 4; text-align: left; }
+    table.hm-grid td.hm-rowlabel, table.hm-grid th.hm-corner { position: sticky; left: 0; z-index: 2; background: var(--surface-1);
+      min-width: 260px; max-width: 320px; padding: 7px 12px; border-right: 1px solid var(--border); }
+    .hm-req-id { font-family: var(--font-mono); font-weight: 700; color: var(--ink-0); font-size: 12px; }
+    .hm-req-title { font-family: var(--font-ui); color: var(--ink-2); font-size: 11px; margin-left: 8px;
+      overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+    .hm-rowlabel-flex { display: flex; align-items: baseline; overflow: hidden; }
+    table.hm-grid td.hm-cell { text-align: center; font-variant-numeric: tabular-nums; font-size: 11px; padding: 7px 6px;
+      color: var(--ramp-ink-hi); cursor: default; min-width: 62px; }
+    table.hm-grid tbody tr:hover td.hm-cell { outline: 1px solid var(--accent); outline-offset: -2px; }
+    .hm-b0 { background: var(--ramp-0); color: var(--ramp-ink-lo); }
+    .hm-b1 { background: var(--ramp-1); color: var(--ramp-ink-lo); }
+    .hm-b2 { background: var(--ramp-2); color: var(--ramp-ink-hi); }
+    .hm-b3 { background: var(--ramp-3); color: var(--ramp-ink-hi); }
+    .hm-b4 { background: var(--ramp-4); color: var(--ramp-ink-hi); }
+    .hm-b5 { background: var(--ramp-5); color: var(--ramp-ink-hi); }
+    .hm-summary-pill { font-family: var(--font-ui); font-weight: 700; font-size: 11px; padding: 2px 8px; border-radius: 999px; }
+    .hm-pill-ok { background: color-mix(in srgb, var(--ok) 22%, transparent); color: var(--ok); border: 1px solid var(--ok); }
+    .hm-pill-warn { background: color-mix(in srgb, var(--warn) 22%, transparent); color: var(--warn); border: 1px solid var(--warn); }
     .header { margin-bottom: 20px; border-bottom: 1px solid rgba(255,255,255,0.12); padding-bottom: 16px; display: flex; justify-content: space-between; align-items: center; }
     .nav-tabs { display: flex; gap: 12px; margin-bottom: 20px; }
     .tab-btn { background: #1e293b; color: #94a3b8; border: 1px solid #334155; padding: 10px 20px; border-radius: 8px; cursor: pointer; font-weight: bold; }
@@ -541,10 +671,10 @@ function renderDashboardHtml() {
   </div>
 
   <div class="nav-tabs">
-    <button id="tabRtmBtn" class="tab-btn active" onclick="switchTab('rtm')">📊 Quantitative REQ RTM Matrix Grid</button>
-    <button id="tabHeatmapBtn" class="tab-btn" onclick="switchTab('heatmap')">🔥 REQ-Grouped Pipeline Heatmap (REQ ➔ AST)</button>
-    <button id="tabGraphBtn" class="tab-btn" onclick="switchTab('graph')">🕸️ End-to-End Human-Insight Pipeline Canvas</button>
-    <button id="tabLegacyBtn" class="tab-btn" onclick="switchTab('legacy')">🏷️ Unmapped Specs (C-SPEC · JOB)</button>
+    <button id="tabRtmBtn" class="tab-btn active" onclick="switchTab('rtm')">Quantitative REQ RTM</button>
+    <button id="tabHeatmapBtn" class="tab-btn" onclick="switchTab('heatmap')">Coverage Matrix</button>
+    <button id="tabGraphBtn" class="tab-btn" onclick="switchTab('graph')">Pipeline Canvas</button>
+    <button id="tabLegacyBtn" class="tab-btn" onclick="switchTab('legacy')">Unmapped Specs</button>
   </div>
 
   <div id="rtmTab">
@@ -570,30 +700,28 @@ function renderDashboardHtml() {
   </div>
 
   <div id="heatmapTab" style="display: none;">
-    <div class="ux-hint-banner" style="border-left-color: #f59e0b;">
-      <div style="display: flex; align-items: center; gap: 16px; flex-wrap: wrap;">
-        <div style="display: flex; align-items: center; gap: 8px;">
-          <span>🔥 <strong>3-Tier Multi-Lens:</strong></span>
-          <select id="lensSelect" class="select-box" style="border-color: #f59e0b; font-weight: bold; background: #0f172a;" onchange="changeHeatmapLens()">
-            <option value="lens1" selected>🎯 Lens 1: SDLC Trace Spine (REQ ➔ AST/CPG Core Chain)</option>
-            <option value="lens2">🛡️ Lens 2: Audit & Security Risk Overlay (Findings Ledger — shows “not scanned” when absent)</option>
-            <option value="lens3">🧪 Lens 3: Mutation & Robustness Overlay (Static AST Mutants — score unmeasured)</option>
-          </select>
-        </div>
-        
-        <div style="display: flex; align-items: center; gap: 8px;">
-          <span>🔍 <strong>Filter Status:</strong></span>
-          <select id="pipelineFilterSelect" class="select-box" style="border-color: #38bdf8; font-weight: bold; background: #0f172a;" onchange="changeHeatmapLens()">
-            <option value="all" selected>All REQ Pipelines</option>
-            <option value="uncovered">Only Uncovered / Active Traces</option>
-            <option value="findings">Only Traces with Open Findings</option>
-          </select>
-        </div>
-      </div>
-    </div>
-    <div class="heatmap-wrapper">
-      <div id="heatmapContainer">Loading REQ-grouped 6-stage pipeline heatmap...</div>
+    <div class="hm-toolbar">
+      <span style="font-family: var(--font-ui); font-weight: 700; color: var(--ink-0); font-size: 13px;">Requirement × Pipeline-Stage Coverage</span>
+      <span style="color: var(--ink-2);">rows seriated by completeness · cell = share of a REQ's chains reaching that stage</span>
+      <span style="display: inline-flex; align-items: center; gap: 8px;">
+        <label for="pipelineFilterSelect" style="color: var(--ink-1);">Rows</label>
+        <select id="pipelineFilterSelect" class="select-box" onchange="changeHeatmapLens()">
+          <option value="all" selected>All requirements</option>
+          <option value="uncovered">Incomplete only</option>
+        </select>
+      </span>
+      <span class="hm-legend">
+        <span style="color: var(--ink-2);">0%</span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-0);"></span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-1);"></span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-2);"></span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-3);"></span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-4);"></span>
+        <span class="hm-legend-swatch" style="background: var(--ramp-5);"></span>
+        <span style="color: var(--ink-2);">100%</span>
+      </span>
     </div>
+    <div id="heatmapContainer">Loading coverage matrix…</div>
   </div>
 
   <div id="graphTab" style="display: none;">
@@ -844,144 +972,70 @@ function renderDashboardHtml() {
       }
     }
 
-    // Render one pipeline stage cell. A stage with no artifact renders as an inert “missing” cell
-    // instead of a clickable id, so an empty stage can never be mistaken for a traced one.
-    function stageCell(cls, icon, label, jumpId, withArrow) {
-      const arrow = withArrow ? '<span class="arrow-sep">➔</span> ' : '';
-      if (!label) {
-        return '<td class="' + cls + ' stage-missing" title="No artifact for this stage">' + arrow + '— missing</td>';
-      }
-      const onclick = jumpId ? ' onclick="focusSpecInGraph(\\'' + escapeHtml(String(jumpId)) + '\\')"' : '';
-      return '<td class="' + cls + '"' + onclick + '>' + arrow + icon + ' ' + escapeHtml(String(label)) + '</td>';
-    }
-    // REQ-Grouped Structured 6-Stage Pipeline Heatmap Matrix Renderer
+    // @implements A-SPEC-545.2 — seriated REQ × stage coverage matrix (2D grid), painted from the
+    // server-built data.matrix. Rows are ordered by matrix.order (completeness), each cell coloured
+    // by its ramp bucket with the coverage percent shown inline (tabular-nums), so magnitude never
+    // relies on colour alone.
     function render6StagePipelineMatrix(data) {
       const container = document.getElementById('heatmapContainer');
-      const rawPipelines = data.pipelines || [];
-      const lens = document.getElementById('lensSelect').value || 'lens1';
-      const statusFilter = document.getElementById('pipelineFilterSelect').value || 'all';
+      const matrix = data.matrix || { reqs: [], stages: [], values: [], order: [], buckets: [] };
+      const filterEl = document.getElementById('pipelineFilterSelect');
+      const statusFilter = filterEl ? (filterEl.value || 'all') : 'all';
 
-      if (rawPipelines.length === 0) {
-        container.innerHTML = '<div style="color:#94a3b8; font-size:14px;">No pipeline trace chains found.</div>';
+      if (!matrix.reqs || matrix.reqs.length === 0) {
+        container.innerHTML = '<div style="color: var(--ink-1); font-size: 14px; padding: 16px;">No pipeline trace chains found.</div>';
         return;
       }
 
-      // Filter pipelines based on user status selection
-      let pipelines = rawPipelines;
-      if (statusFilter === 'uncovered') {
-        pipelines = rawPipelines.filter(p => p.status !== 'COVERED');
-      } else if (statusFilter === 'findings') {
-        pipelines = rawPipelines.filter(p => p.findingsCount > 0);
-      }
+      const isRowComplete = (i) => (matrix.values[i] || []).every(v => v >= 1);
+      let rowIdx = (matrix.order && matrix.order.length ? matrix.order : matrix.reqs.map((_, i) => i)).slice();
+      if (statusFilter === 'uncovered') rowIdx = rowIdx.filter(i => !isRowComplete(i));
 
-      // Group pipelines by reqId
-      const groupedMap = new Map();
-      pipelines.forEach(p => {
-        if (!groupedMap.has(p.reqId)) {
-          groupedMap.set(p.reqId, { reqId: p.reqId, reqTitle: p.reqTitle, items: [] });
-        }
-        groupedMap.get(p.reqId).items.push(p);
-      });
+      const fullyTraced = matrix.reqs.filter((_, i) => isRowComplete(i)).length;
+      const summaryCls = fullyTraced === matrix.reqs.length ? 'hm-pill-ok' : 'hm-pill-warn';
 
-      if (groupedMap.size === 0) {
-        const unscanned = statusFilter === 'findings' && data.findingsScanned === false;
-        container.innerHTML = unscanned
-          ? '<div style="color:#fbbf24; font-size:14px; padding:16px; border:1px dashed #64748b; border-radius:8px;">⚪ No findings ledger exists (<code>.ax/ledger/findings.jsonl</code>). This is <strong>not</strong> a clean result — no audit has been run.</div>'
-          : '<div style="color:#94a3b8; font-size:14px; padding:16px;">No pipelines match the selected filter.</div>';
+      if (rowIdx.length === 0) {
+        container.innerHTML = '<div style="color: var(--ink-1); font-size: 14px; padding: 16px;">Every requirement is fully traced — no incomplete rows to show.</div>';
         return;
       }
 
-      let extraHeader = 'Status';
-      if (lens === 'lens2') extraHeader = heatmapData && heatmapData.findingsScanned === false ? '🛡️ Security Audit (never scanned)' : '🛡️ Live Security Findings';
-      else if (lens === 'lens3') extraHeader = '🧪 Static AST Mutants (score unmeasured)';
-
-      let html = '';
-
-      groupedMap.forEach((group, reqId) => {
-        const items = group.items;
-        const totalItems = items.length;
-        const coveredItems = items.filter(i => i.status === 'COVERED').length;
-        const isReqHealthy = coveredItems === totalItems;
-
-        const reqStatusBadge = isReqHealthy
-          ? '<span class="neighbor-rel badge-covered">🟢 100% HEALTHY TRACE</span>'
-          : '<span class="neighbor-rel badge-uncovered">🔴 CONTAINS UNCOVERED TRACES</span>';
-
-        html += \`
-          <div class="req-card" style="margin-bottom: 20px;">
-            <div class="req-header" onclick="toggleAccordion('pipe-body-\${escapeHtml(reqId)}')">
-              <div class="req-title-group">
-                <span class="req-id-badge">\${escapeHtml(reqId)}</span>
-                <span class="req-title">\${escapeHtml(group.reqTitle || 'Business Requirement Pipeline')}</span>
-                \${reqStatusBadge}
-              </div>
-              <div style="display: flex; align-items: center; gap: 12px;">
-                <span style="font-size: 12px; color: #94a3b8; font-weight: bold;">\${totalItems} End-to-End Trace Chain\${totalItems > 1 ? 's' : ''}</span>
-                <button class="expand-btn">▶ Expand Pipeline Matrix</button>
+      const pct = (v) => Math.round((v || 0) * 100);
+      const headCells = matrix.stages.map(s => \`<th>\${escapeHtml(s)}</th>\`).join('');
+
+      let rows = '';
+      rowIdx.forEach(i => {
+        const req = matrix.reqs[i];
+        const vals = matrix.values[i] || [];
+        const bkts = matrix.buckets[i] || [];
+        const cells = matrix.stages.map((stage, s) => {
+          const v = vals[s] || 0;
+          const b = bkts[s] || 0;
+          const title = escapeHtml(req.id) + ' · ' + escapeHtml(stage) + ': ' + pct(v) + '% of chains reached';
+          return \`<td class="hm-cell hm-b\${b}" title="\${title}">\${pct(v)}</td>\`;
+        }).join('');
+        rows += \`
+          <tr>
+            <td class="hm-rowlabel" onclick="focusSpecInGraph('\${escapeHtml(req.id)}')" title="\${escapeHtml(req.title || '')}">
+              <div class="hm-rowlabel-flex">
+                <span class="hm-req-id">\${escapeHtml(req.id)}</span>
+                <span class="hm-req-title">\${escapeHtml(req.title || '')}</span>
               </div>
-            </div>
-
-            <div class="accordion-body open" id="pipe-body-\${escapeHtml(reqId)}" style="padding:0;">
-              <table class="pipeline-table">
-                <thead>
-                  <tr>
-                    <th>Stage 1: REQ Business</th>
-                    <th>Stage 2: H-SPEC Functional</th>
-                    <th>Stage 3: A-SPEC Architecture</th>
-                    <th>Stage 4: T-SPEC Verification</th>
-                    <th>Stage 5: Source Code File</th>
-                    <th>Stage 6: AST / CPG Symbol</th>
-                    <th>\${extraHeader}</th>
-                  </tr>
-                </thead>
-                <tbody>
-        \`;
-
-        items.forEach(p => {
-          const missing = p.missingStages || [];
-          let statusBadge = missing.length === 0
-            ? '<span class="neighbor-rel badge-covered">COVERED (6/6)</span>'
-            : \`<span class="neighbor-rel badge-uncovered" title="Missing: \${escapeHtml(missing.join(', '))}">UNCOVERED (\${p.stagesComplete}/6)</span>\`;
-
-          if (lens === 'lens2') {
-            if (!p.findingsScanned) {
-              statusBadge = '<span class="neighbor-rel badge-unmeasured" title="No .ax/ledger/findings.jsonl — this chain has never been audited">⚪ Not scanned</span>';
-            } else if (p.criticalCount > 0) {
-              statusBadge = \`<span class="neighbor-rel badge-uncovered">🔴 \${p.criticalCount} Critical Finding\${p.criticalCount > 1 ? 's' : ''}</span>\`;
-            } else if (p.findingsCount > 0) {
-              statusBadge = \`<span class="neighbor-rel" style="background:#d97706; color:#fff;">🟡 \${p.findingsCount} Open Finding\${p.findingsCount > 1 ? 's' : ''}</span>\`;
-            } else {
-              statusBadge = '<span class="neighbor-rel badge-covered">🟢 0 Open Findings</span>';
-            }
-          } else if (lens === 'lens3') {
-            // A score requires running the suite once per mutant; this endpoint only generates them
-            // statically, so it reports the mutant count and says the score is unmeasured.
-            const mutantCount = p.mutantCount || 0;
-            statusBadge = \`<span class="neighbor-rel badge-unmeasured" title="Static generation only — run mutation testing to obtain a score">🧪 \${mutantCount} Mutant\${mutantCount === 1 ? '' : 's'} · Score not measured</span>\`;
-          }
-
-          html += \`
-            <tr class="pipeline-row">
-              \${stageCell('stage-req', '🟣', p.reqId, p.reqId, false)}
-              \${stageCell('stage-hspec', '🟣', p.hspecId, p.hspecId, true)}
-              \${stageCell('stage-aspec', '🔵', p.aspecId, p.aspecId, true)}
-              \${stageCell('stage-tspec', '🔷', p.tspecId, p.tspecId, true)}
-              \${stageCell('stage-file', '📄', p.fileId ? (p.fileId.split('/').pop() || p.fileId) : null, p.fileId, true)}
-              \${stageCell('stage-symbol', '⚡', p.symbolId, p.fileId && p.symbolId ? p.fileId + '#' + p.symbolId : null, true)}
-              <td>\${statusBadge}</td>
-            </tr>
-          \`;
-        });
-
-        html += \`
-                </tbody>
-              </table>
-            </div>
-          </div>
-        \`;
+            </td>
+            \${cells}
+          </tr>\`;
       });
 
-      container.innerHTML = html;
+      container.innerHTML = \`
+        <div style="margin-bottom: 10px;">
+          <span class="hm-summary-pill \${summaryCls}">\${fullyTraced} / \${matrix.reqs.length} requirements fully traced</span>
+          <span style="color: var(--ink-2); font-size: 12px; margin-left: 10px;">showing \${rowIdx.length} row\${rowIdx.length === 1 ? '' : 's'}</span>
+        </div>
+        <div class="hm-scroll">
+          <table class="hm-grid">
+            <thead><tr><th class="hm-corner">Requirement</th>\${headCells}</tr></thead>
+            <tbody>\${rows}</tbody>
+          </table>
+        </div>\`;
     }
 
     // World Top-Tier Quantitative REQ-Centric RTM Traceability Matrix Grid Renderer

package/dist/holmes/server/rtm-matrix.d.ts

@@ -0,0 +1,47 @@
+/** The six pipeline stages, in traversal order — the columns of the matrix. */
+export declare const STAGES: readonly ["REQ", "H-SPEC", "A-SPEC", "T-SPEC", "File", "AST Symbol"];
+/** One pipeline chain row from /api/rtm/heatmap (only the fields the matrix reads). */
+export interface PipelineRow {
+    reqId: string;
+    reqTitle?: string;
+    stagesComplete: number;
+}
+export interface StageMatrix {
+    reqs: {
+        id: string;
+        title: string;
+    }[];
+    stages: string[];
+    /** values[r][s] ∈ [0,1] = fraction of REQ r's chains that reached stage s. */
+    values: number[][];
+}
+/**
+ * @implements A-SPEC-545.1
+ * Pure: turn per-chain pipeline rows into a REQ × stage coverage matrix. Rows are REQs (first-seen
+ * order), columns the six stages; each cell is the fraction of that REQ's chains that REACHED the
+ * stage (stagesComplete >= s+1). This is the overview the 2D heatmap paints — magnitude per cell.
+ */
+export declare function buildStageMatrix(pipelines: PipelineRow[]): StageMatrix;
+/**
+ * @implements A-SPEC-545.1
+ * Pure & deterministic: a row permutation that clusters similar, high-coverage rows together
+ * (Behrisch-style seriation). Key: descending row-mean, then the profile vector descending, then the
+ * original index (stable). Same input ⇒ same output.
+ */
+/**
+ * @implements A-SPEC-545.2
+ * Pure: map a coverage fraction v∈[0,1] to a sequential-ramp bucket index 0..5. Monotonic
+ * non-decreasing, clamped ([0,1]), NaN→0. The dashboard paints cell background = var(--ramp-<bucket>).
+ */
+export declare function coverageBucket(v: number): number;
+export interface HeatmapMatrix extends StageMatrix {
+    order: number[];
+    buckets: number[][];
+}
+/**
+ * @implements A-SPEC-545.2
+ * Pure server-side payload builder: buildStageMatrix + seriateRows + coverageBucket in one object,
+ * so the client render is a thin paint over data.matrix.
+ */
+export declare function heatmapMatrix(pipelines: PipelineRow[]): HeatmapMatrix;
+export declare function seriateRows(values: number[][]): number[];

package/dist/holmes/server/rtm-matrix.js

@@ -0,0 +1,83 @@
+"use strict";
+// @implements A-SPEC-545.1
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STAGES = void 0;
+exports.buildStageMatrix = buildStageMatrix;
+exports.coverageBucket = coverageBucket;
+exports.heatmapMatrix = heatmapMatrix;
+exports.seriateRows = seriateRows;
+/** The six pipeline stages, in traversal order — the columns of the matrix. */
+exports.STAGES = ['REQ', 'H-SPEC', 'A-SPEC', 'T-SPEC', 'File', 'AST Symbol'];
+/**
+ * @implements A-SPEC-545.1
+ * Pure: turn per-chain pipeline rows into a REQ × stage coverage matrix. Rows are REQs (first-seen
+ * order), columns the six stages; each cell is the fraction of that REQ's chains that REACHED the
+ * stage (stagesComplete >= s+1). This is the overview the 2D heatmap paints — magnitude per cell.
+ */
+function buildStageMatrix(pipelines) {
+    const order = [];
+    const groups = new Map();
+    for (const p of pipelines) {
+        let g = groups.get(p.reqId);
+        if (!g) {
+            g = { title: p.reqTitle ?? '', chains: [] };
+            groups.set(p.reqId, g);
+            order.push(p.reqId);
+        }
+        g.chains.push(p.stagesComplete);
+    }
+    const reqs = order.map((id) => ({ id, title: groups.get(id).title }));
+    const values = order.map((id) => {
+        const chains = groups.get(id).chains;
+        return exports.STAGES.map((_, s) => {
+            const reached = chains.filter((c) => c >= s + 1).length;
+            return Number((reached / chains.length).toFixed(3));
+        });
+    });
+    return { reqs, stages: [...exports.STAGES], values };
+}
+/**
+ * @implements A-SPEC-545.1
+ * Pure & deterministic: a row permutation that clusters similar, high-coverage rows together
+ * (Behrisch-style seriation). Key: descending row-mean, then the profile vector descending, then the
+ * original index (stable). Same input ⇒ same output.
+ */
+/**
+ * @implements A-SPEC-545.2
+ * Pure: map a coverage fraction v∈[0,1] to a sequential-ramp bucket index 0..5. Monotonic
+ * non-decreasing, clamped ([0,1]), NaN→0. The dashboard paints cell background = var(--ramp-<bucket>).
+ */
+function coverageBucket(v) {
+    if (!Number.isFinite(v) || v <= 0)
+        return 0; // NaN / -Inf / ≤0 → lowest
+    if (v >= 1)
+        return 5; // ≥1 → highest (upper clamp)
+    return Math.min(5, Math.floor(v * 6));
+}
+/**
+ * @implements A-SPEC-545.2
+ * Pure server-side payload builder: buildStageMatrix + seriateRows + coverageBucket in one object,
+ * so the client render is a thin paint over data.matrix.
+ */
+function heatmapMatrix(pipelines) {
+    const { reqs, stages, values } = buildStageMatrix(pipelines);
+    const order = seriateRows(values);
+    const buckets = values.map((row) => row.map(coverageBucket));
+    return { reqs, stages, values, order, buckets };
+}
+function seriateRows(values) {
+    const mean = (row) => row.length ? row.reduce((a, b) => a + b, 0) / row.length : 0;
+    return values
+        .map((row, i) => ({ i, m: mean(row), row }))
+        .sort((a, b) => {
+        if (b.m !== a.m)
+            return b.m - a.m; // higher coverage first
+        for (let k = 0; k < Math.max(a.row.length, b.row.length); k++) {
+            const d = (b.row[k] ?? 0) - (a.row[k] ?? 0); // then profile descending
+            if (d !== 0)
+                return d;
+        }
+        return a.i - b.i; // stable on ties
+    })
+        .map((x) => x.i);
+}

package/dist/holmes/update/update-notice.js

@@ -49,6 +49,7 @@ exports.cacheIsStale = cacheIsStale;
 // major.minor.patch — a full semver library would carry prerelease/build code this never runs), and
 // the registry query (A-SPEC-531.2) uses Node's built-in https.
 const path = __importStar(require("node:path"));
+const npx_bin_1 = require("../project/npx-bin");
 exports.NPM_URL = 'https://www.npmjs.com/package/@holmes-lab/holmes-kit';
 const DEFAULT_TTL_MS = 24 * 3600_000;
 /** Parse `major.minor.patch` to a 3-tuple; a non-numeric field becomes 0 (never throws). */
@@ -97,10 +98,11 @@ function readCache(home, readFile) {
 function installModeGuide(mode, latest, current) {
     const head = `[Holmes-Kit] Update available: ${latest} (current ${current}).`;
     switch (mode) {
+        // @implements A-SPEC-544.1 — one command installs the latest AND re-pins every wired workspace,
+        // so the nudge no longer spells out `npm i` + `init --force`. win32 → npx.cmd (REQ-542).
         case 'global-npx':
-            return `${head} Run: npm i -g @holmes-lab/holmes-kit@latest, then holmes-kit init --force (re-pins wiring; requires HOLMES_APPROVAL).`;
         case 'local-dep':
-            return `${head} Run: npm i -D @holmes-lab/holmes-kit@latest`;
+            return `${head} Run: ${(0, npx_bin_1.npxBin)()} holmes-kit upgrade`;
         case 'source':
             return null;
     }

package/dist/holmes/update/upgrade-plan.d.ts

@@ -0,0 +1,43 @@
+import { InstallMode } from './update-notice';
+import { Registry, WorkspaceEntry } from './workspaces';
+/** What `holmes-kit upgrade` would do — pure facts; wording and refusals belong to the CLI. */
+export type UpgradePlan = {
+    kind: 'noop';
+    reason: string;
+} | {
+    kind: 'run';
+    current: string;
+    latest: string;
+    installMode: InstallMode;
+    repins: WorkspaceEntry[];
+};
+/**
+ * @implements A-SPEC-543.2
+ * Pure: decide whether an upgrade runs and what it touches. Unknown latest is a noop (silence is not
+ * an install), and so is an equal or OLDER latest — upgrade never plans a downgrade. A 'run' plan
+ * carries the registry's workspaces verbatim as the re-pin list; an empty list is still a valid run
+ * (install-only, first machine).
+ */
+export declare function planUpgrade(a: {
+    current: string;
+    latest: string | null;
+    registry: Registry;
+    installMode: InstallMode;
+}): UpgradePlan;
+/** The env switch that turns SessionStart's forward self-heal re-pin OFF. */
+export declare const NO_AUTO_REPIN_ENV = "HOLMES_NO_AUTO_REPIN";
+/**
+ * @implements A-SPEC-543.3
+ * Pure: should a session auto re-pin this workspace's derived artifacts? Only when the pin is a real
+ * version, the installed package is strictly NEWER (forward-only — never a downgrade or a match), and
+ * the operator has not opted out. The install was the user's explicit choice; this completes it at
+ * the workspace level. A decision always says why.
+ */
+export declare function repinDecision(a: {
+    pinned: string | null;
+    installed: string;
+    env: NodeJS.ProcessEnv;
+}): {
+    repin: boolean;
+    reason: string;
+};