@holmes-lab/holmes-kit 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 <!-- @implements A-SPEC-209 -->
+## [0.12.0] - 2026-09-05
+
+World-top-tier RTM dashboard, in flight. The `holmes-kit serve` dashboard stops being a table of
+accordions and becomes a real coverage matrix, gains a one-call launcher, and learns to serve CFG/PDG
+for a function. Additive and backward-compatible — every existing `/api/*` payload keeps its shape and
+values; these are new fields, a new endpoint, a new tool, and a rebuilt heatmap view.
+
+### Added
+
+- **2D coverage matrix** (REQ-545): the heatmap tab is now a single **requirement × pipeline-stage
+  grid** — rows are requirements ordered by completeness (seriation), each cell a sequential-ramp
+  colour with the coverage percent printed in it (so magnitude never rides on colour alone). Replaces
+  the per-REQ accordion-of-tables. `/api/rtm/heatmap` gains an additive `matrix` field
+  (`{reqs, stages, values, order, buckets}`) built by pure, unit-tested `buildStageMatrix` +
+  `seriateRows` + `coverageBucket`.
+- **`rtm_dashboard` MCP tool** (REQ-545): ask to *see* the RTM heatmap / coverage matrix and the
+  server launches (idempotently — a second call reuses the live one) and returns `{ url, running,
+  census }`, where `census` is an honesty summary (`reqCount, pipelineCount, coveredCount,
+  coveragePct, retiredCount, findingsScanned`). No more starting `serve` by hand.
+- **`/api/cfg` — control-flow + program-dependence for one function** (REQ-545): `?file=&symbol=`
+  returns that function's CFG (blocks with source line/label, control-flow edges) and PDG (block-level
+  control deps + reaching-def data deps), consumed from the same `cfgOf`/`pdgOf` the taint lane uses.
+  A non-CFG language is named as `unsupported`, never faked as an empty graph. (Graph-view rendering
+  of this lands next.)
+
+### Changed
+
+- **Dashboard design tokens** (REQ-545): the palette moved off the Tailwind-default + emoji-marker
+  look to a tokenised system — a single-hue sequential coverage ramp, reserved status colours, a
+  UI/mono type pairing (data in tabular-nums), surfaces and ink, with a light and a dark palette via
+  `prefers-color-scheme`. Applied to the new matrix view and the tab bar; structure emoji removed
+  (meaning markers only). The rest of the dashboard tokenises incrementally in the follow-on slice.
+- **Upgrade nudges point at one command** (REQ-544): the session banner's drift line and doctor's
+  version-drift fix hint now name `holmes-kit upgrade` (the right binary per platform — `npx.cmd` on
+  win32) instead of spelling out a manual `npm i` + `init --force`.
+
 ## [0.11.0] - 2026-09-05
 
 Zero-config upgrades — preparation is automatic, execution is your explicit choice. Additive and

package/README.md

@@ -20,6 +20,7 @@
 - 🔴 **Inbuilt TDD — RED-first, enforced not asked** *(new in 0.9.0)*: the test-first discipline is a holmes-installed `holmes-tdd-slice` skill **and** a new constitution article **ART-8**. A changed A-SPEC must show a recorded `red-assertion → green` sequence in the ledger; a `red-error` (a test that could not run) is not a valid RED, so "the covering test failed *correctly*" is judged mechanically, not on trust. `test_run` classifies each covered file (`red-assertion`/`red-error`/`green`) and records per-A-SPEC outcomes the Stop hook reads. Ships at `redFirstEvidence: track` (observe-first, non-blocking; `strict`/`off` per repo), evidence-gated and jest-only for now. A T-SPEC may also declare `kills:` mutations and `test_run --mutate` reports which SURVIVED (a coverage gap). Where superpowers *asks* for RED-first and discriminating power, holmes-kit *proves* them.
 - 🧰 **Governance UX tools** *(new in 0.10.0)*: `spec_unseal` (the inverse of `spec_approve` — return a sealed spec to editable `draft` in one act, out-of-band approval required, refuses approved dependents), `approval_status` and `ledger_timeline` (read-only observability into a spec's seal state and the governance history), and a structured `conflict` on `spec_approve`'s optimistic-concurrency refusal (read vs. current version + retry). See CHANGELOG for details.
 - ⬆️ **Zero-config upgrades** *(new in 0.11.0)*: `holmes-kit upgrade` moves **every** wired workspace to the latest in one command — plan → confirm → install → re-pin all recorded workspaces (`--dry-run`/`--yes` supported). Preparation is automatic (each `init` records the workspace; a session whose pin is behind nudges you to upgrade); the re-pin **write** stays your explicit choice, never a silent auto-install. Opt out of the nudge with `HOLMES_NO_AUTO_REPIN`.
+- 📊 **World-top-tier RTM dashboard** *(new in 0.12.0, in flight)*: `holmes-kit serve` — ask to *see* the RTM heatmap and the `rtm_dashboard` MCP tool launches the server idempotently and hands back the URL plus an honesty **census** (requirement/pipeline counts, coverage %, what's excluded). The heatmap is now a real **2D coverage matrix** (requirements × pipeline stages, rows seriated by completeness, sequential-ramp cells with the percent printed in each), and `/api/cfg?file=&symbol=` serves a function's **CFG + PDG** (control-flow blocks + data/control dependence) from the same engine the taint lane uses — a non-CFG language is named, never faked. Tokenised palette + light/dark; graph-view rendering of CFG/PDG lands next.
 - 🤖 **Autonomous Approval** *(new in 0.8.0)*: with the out-of-band `HOLMES_AUTONOMOUS_APPROVAL` switch on, an agent seals **low/mid-risk** specs itself (ledgered under an `autonomous:<client>` actor) — while `gate-behavior` changes, architecture/gate/taint files, and every upstream `REQ`/`H-SPEC`/`C-SPEC` still ask a human through the in-session TUI. The switch is env-only; a session cannot set it (blocked like `HOLMES_ROLE`). Off = byte-identical to before. *(new in 0.10.0)* Set **`HOLMES_ELICIT=off`** to skip the in-session prompt entirely and route every decision to the out-of-band `holmes-kit approve` queue instead — one decision surface that behaves identically across Claude Code / Antigravity / Codex.
 - 🪧 **Session Banner + Update Notice** *(new in 0.8.0)*: every session start emits an English intro (version + governance rule + npm URL) to both the human transcript and the agent context (SessionStart hook + MCP `instructions`); when a newer published version is cached, an install-mode-aware update command is appended. Registry check is detached, fail-silent, and opts out via `HOLMES_NO_UPDATE_CHECK`/`CI`.
 - 🧱 **Deterministic Gate, Hardened** *(new in 0.8.0)*: shell writes are judged at the segment's **effective working directory** (`cd sub && cat > ../src/x.ts` is sealed, legitimate out-of-tree scratch writes are freed); the governing anchor is the **whole set**, not the first match. Every gate change ships with two consecutive clean adversarial rounds.

package/dist/.build-id

@@ -1 +1 @@
-2fb1cad-mtnmh3yo
+85d7b53-mtnr6dpp

package/dist/holmes/cli/doctor.js

@@ -757,7 +757,9 @@ async function runDoctor(packageRoot, target, opts, extraChecks) {
                 const launch = (0, mcp_version_1.mcpLaunchVersion)({ command: server.command, args: server.args }, readPkgVersionAt);
                 const verdict = (0, mcp_version_1.versionDriftVerdict)(launch, cli);
                 if (verdict === 'drift') {
-                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, `${(0, npx_bin_1.npxBin)()} @holmes-lab/holmes-kit@latest init 을 다시 실행해 .mcp.json 을 최신 버전으로 재배선하십시오 (전역 -g 업그레이드 불필요).`);
+                    add('mcp server version', 'WARN', `이 프로젝트의 MCP 서버는 holmes-kit ${launch} 를 띄우지만 이 CLI 는 ${cli} 입니다 — 재배선 전까지 옛 서버가 계속 뜹니다`, 
+                    // @implements A-SPEC-544.1 — one command installs + re-pins every workspace; init --force is the per-workspace path.
+                    `${(0, npx_bin_1.npxBin)()} holmes-kit upgrade 로 최신 설치 + 전 워크스페이스 재핀 (이 워크스페이스만 고치려면 ${(0, npx_bin_1.npxBin)()} holmes-kit init --force).`);
                 }
                 else if (verdict === 'match') {
                     add('mcp server version', 'PASS', `MCP 서버 버전 ${launch} 가 이 CLI 와 일치합니다`);

package/dist/holmes/mcp/handlers.d.ts

@@ -237,6 +237,22 @@ declare function makeRawHandlers(store: SpecStore, opts?: ElicitOpts): {
         events: import("../governance/ledger-timeline").TimelineEntry[];
         reason?: undefined;
     }>;
+    rtm_dashboard(a: {
+        root?: string;
+        port?: number;
+    }): Promise<{
+        ok: boolean;
+        reason: string;
+        url?: undefined;
+        running?: undefined;
+        census?: undefined;
+    } | {
+        ok: boolean;
+        url: string;
+        running: boolean;
+        census: import("../server/dashboard-launcher").DashboardCensus;
+        reason?: undefined;
+    }>;
     spec_approve(a: {
         root?: string;
         id: string;

package/dist/holmes/mcp/handlers.js

@@ -45,6 +45,7 @@ exports.makeHandlers = makeHandlers;
 // @implements A-SPEC-269
 // @implements A-SPEC-267
 const fs = __importStar(require("node:fs"));
+const http = __importStar(require("node:http"));
 const assoc_arm_1 = require("../assoc/assoc-arm");
 // @implements A-SPEC-478 — the semantic tier runtime, resolved HERE (the async edge) and injected
 // into the sync analysis; the replay harness injects nothing, keeping every pin untouched.
@@ -213,6 +214,21 @@ class HandlerRefusal extends Error {
     constructor(message) { super(message); this.name = 'HandlerRefusal'; }
 }
 exports.HandlerRefusal = HandlerRefusal;
+/** GET a localhost JSON endpoint (used by rtm_dashboard to read the census off the server it launched). */
+function fetchJson(url) {
+    return new Promise((resolve, reject) => {
+        http.get(url, (res) => {
+            let data = '';
+            res.on('data', (c) => (data += c));
+            res.on('end', () => { try {
+                resolve(JSON.parse(data));
+            }
+            catch (e) {
+                reject(e);
+            } });
+        }).on('error', reject);
+    });
+}
 /** Marker test that survives realm boundaries (jest's instanceof does not). */
 function isHandlerRefusal(e) {
     return !!e && typeof e === 'object' && e.holmesRefusal === true;
@@ -1322,6 +1338,24 @@ function makeRawHandlers(store, opts) {
             const events = fs.existsSync(dir) ? new ledger_store_1.FileLedgerStore(dir).loadAll() : [];
             return { ok: true, events: (0, ledger_timeline_1.timelineFrom)(events, a.id) };
         },
+        // @implements A-SPEC-545.3 — "show me the RTM dashboard" launches (idempotently) the server the
+        // agent would otherwise start by hand, and returns its URL plus an honesty census of what it shows.
+        async rtm_dashboard(a) {
+            const dest = resolveLedgerRoot(a.root);
+            if (!dest.ok)
+                return { ok: false, reason: dest.reason };
+            try {
+                const { startDashboardServer } = await Promise.resolve().then(() => __importStar(require('../server/dashboard')));
+                const { ensureDashboard, dashboardCensus } = await Promise.resolve().then(() => __importStar(require('../server/dashboard-launcher')));
+                const launch = await ensureDashboard(dest.root, a.port, (opts) => startDashboardServer(opts));
+                const rtm = await fetchJson(`${launch.url}/api/rtm`);
+                const heatmap = await fetchJson(`${launch.url}/api/rtm/heatmap`);
+                return { ok: true, url: launch.url, running: launch.running, census: dashboardCensus(rtm, heatmap) };
+            }
+            catch (err) {
+                return { ok: false, reason: `대시보드 기동 실패: ${err?.message ?? String(err)}` };
+            }
+        },
         async spec_approve(a) {
             const approvalRaw = process.env.HOLMES_APPROVAL;
             let approval;

package/dist/holmes/mcp/tool-schemas.js

@@ -133,6 +133,16 @@ exports.TOOL_SCHEMAS = {
             },
         },
     },
+    rtm_dashboard: {
+        description: "Launch (idempotently) the interactive RTM/CPG dashboard the agent would otherwise start by hand, and return { ok, url, running, census } — use it when a human asks to SEE the RTM heatmap / coverage matrix / dashboard. `url` is the localhost address to open; `running` is true when an already-live server for this project was reused (a second call never starts a second server). `census` is an honesty summary of what the dashboard shows — { reqCount, pipelineCount, coveredCount, coveragePct, retiredCount, findingsScanned } — so the caller can report coverage without scraping the page. No spec writes, no ledger append. Refuses when a supplied `root` points at a different project than the server is bound to.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                root: str('Optional when the server is bound to a file store; if supplied it must resolve to the SAME project.'),
+                port: { type: 'number', description: 'Optional port to bind when first launching (default 8080). Ignored if a server for this project is already running.' },
+            },
+        },
+    },
     spec_approve: {
         description: 'Approve a spec as a sealing ACT: confirm the ledger destination BEFORE sealing → validate (zero errors) → record approved_digest + parent_digests snapshots → status: approved (written only at the version this act read; a concurrent edit wins and the approval is refused for retry) → append spec-approved to the provenance ledger. Requires a valid out-of-band HOLMES_APPROVAL in the SERVER environment (fail-closed; nothing in the request can substitute). Refuses an unsealed approved parent — seal parents first.',
         inputSchema: {

package/dist/holmes/server/cfg-view.d.ts

@@ -0,0 +1,45 @@
+import type { Cfg, CfgEdge } from '../cpg/foundation/cfg';
+import type { Pdg } from '../cpg/foundation/cdg';
+import type { PersistedAst } from '../cpg/foundation/ast-store';
+export interface CfgViewBlock {
+    id: number;
+    line: number;
+    label: string;
+    unreachable: boolean;
+}
+export interface CfgView {
+    entry: number;
+    exit: number;
+    blocks: CfgViewBlock[];
+    edges: {
+        from: number;
+        to: number;
+        kind: CfgEdge['kind'];
+    }[];
+    ctrlDeps: {
+        ctrl: number;
+        dep: number;
+    }[];
+    dataDeps: {
+        from: number;
+        to: number;
+        name: string;
+    }[];
+}
+/**
+ * @implements A-SPEC-545.4
+ * Pure: 1-based line number of a byte offset (count of newlines in [0, offset) + 1). Clamped.
+ */
+export declare function lineAtByte(source: string, offset: number): number;
+/**
+ * @implements A-SPEC-545.4
+ * Pure: fold a foundation Cfg + Pdg into a display-ready graph — block labels/lines, control-flow
+ * edges, block-level control deps, and reaching defs projected to block pairs (deduped, no self-edge).
+ */
+export declare function buildCfgView(cfg: Cfg | {
+    unsupported: string;
+}, pdg: Pdg | {
+    unsupported: string;
+}, ast: PersistedAst, source: string): CfgView | {
+    unsupported: string;
+};

package/dist/holmes/server/cfg-view.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lineAtByte = lineAtByte;
+exports.buildCfgView = buildCfgView;
+/**
+ * @implements A-SPEC-545.4
+ * Pure: 1-based line number of a byte offset (count of newlines in [0, offset) + 1). Clamped.
+ */
+function lineAtByte(source, offset) {
+    const at = Math.max(0, Math.min(offset, source.length));
+    let line = 1;
+    for (let i = 0; i < at; i++)
+        if (source.charCodeAt(i) === 10)
+            line++;
+    return line;
+}
+/**
+ * @implements A-SPEC-545.4
+ * Pure: fold a foundation Cfg + Pdg into a display-ready graph — block labels/lines, control-flow
+ * edges, block-level control deps, and reaching defs projected to block pairs (deduped, no self-edge).
+ */
+function buildCfgView(cfg, pdg, ast, source) {
+    if ('unsupported' in cfg)
+        return cfg;
+    if ('unsupported' in pdg)
+        return pdg;
+    // stmt node index → owning block id
+    const blockOf = new Map();
+    for (const b of cfg.blocks)
+        for (const s of b.stmts)
+            blockOf.set(s, b.id);
+    const unreachable = new Set(cfg.unreachable);
+    const blocks = cfg.blocks.map((b) => {
+        const first = b.stmts.length ? b.stmts[0] : -1;
+        const node = first >= 0 ? ast.nodes[first] : undefined;
+        const line = node ? lineAtByte(source, node.start) : 0;
+        const raw = node ? source.slice(node.start, node.end) : '';
+        const label = raw.split('\n', 1)[0].slice(0, 80);
+        return { id: b.id, line, label, unreachable: unreachable.has(b.id) };
+    });
+    const edges = cfg.edges.map((e) => ({ from: e.from, to: e.to, kind: e.kind }));
+    const ctrlDeps = pdg.controlDeps.map((c) => ({ ctrl: c.ctrl, dep: c.dep }));
+    const seen = new Set();
+    const dataDeps = [];
+    for (const d of pdg.reachingDefs) {
+        const from = blockOf.get(d.defStmt);
+        const to = blockOf.get(d.useStmt);
+        if (from === undefined || to === undefined || from === to)
+            continue; // no self-edge / unresolved
+        const key = `${from}>${to}:${d.name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        dataDeps.push({ from, to, name: d.name });
+    }
+    return { entry: cfg.entry, exit: cfg.exit, blocks, edges, ctrlDeps, dataDeps };
+}

package/dist/holmes/server/dashboard-launcher.d.ts

@@ -0,0 +1,40 @@
+/** Honesty summary of what a launched dashboard shows — derived from the endpoints it serves. */
+export interface DashboardCensus {
+    reqCount: number;
+    pipelineCount: number;
+    coveredCount: number;
+    coveragePct: number;
+    retiredCount: number;
+    findingsScanned: boolean;
+}
+/**
+ * @implements A-SPEC-545.3
+ * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
+ * coveragePct never divides by zero.
+ */
+export declare function dashboardCensus(rtm: any, heatmap: any): DashboardCensus;
+export interface LaunchResult {
+    url: string;
+    port: number;
+    running: boolean;
+}
+export interface StartedHandle {
+    url: string;
+    port: number;
+    stop?: () => Promise<void>;
+}
+type Starter = (opts: {
+    root: string;
+    port?: number;
+}) => Promise<StartedHandle>;
+/**
+ * @implements A-SPEC-545.3
+ * Idempotent per-root dashboard registry: start once, reuse thereafter. `start` is injected so the
+ * idempotency is testable without a real server. A failing start registers nothing.
+ */
+export declare function ensureDashboard(root: string, port: number | undefined, start: Starter): Promise<LaunchResult>;
+/** Test hook: forget all launched servers (without stopping them). */
+export declare function _resetLauncher(): void;
+/** Test/shutdown hook: stop every launched server and clear the registry. */
+export declare function _stopAll(): Promise<void>;
+export {};

package/dist/holmes/server/dashboard-launcher.js

@@ -0,0 +1,54 @@
+"use strict";
+// @implements A-SPEC-545.3
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dashboardCensus = dashboardCensus;
+exports.ensureDashboard = ensureDashboard;
+exports._resetLauncher = _resetLauncher;
+exports._stopAll = _stopAll;
+/**
+ * @implements A-SPEC-545.3
+ * Pure: fold the /api/rtm and /api/rtm/heatmap payloads into a census. Missing fields read as 0/false;
+ * coveragePct never divides by zero.
+ */
+function dashboardCensus(rtm, heatmap) {
+    const reqCount = heatmap?.matrix?.reqs?.length ?? 0;
+    const pipelineCount = heatmap?.pipelineCount ?? 0;
+    const coveredCount = heatmap?.completeCount ?? 0;
+    const coveragePct = pipelineCount > 0 ? Math.round((coveredCount / pipelineCount) * 100) : 0;
+    return {
+        reqCount,
+        pipelineCount,
+        coveredCount,
+        coveragePct,
+        retiredCount: rtm?.retired?.count ?? 0,
+        findingsScanned: heatmap?.findingsScanned === true,
+    };
+}
+const live = new Map();
+/**
+ * @implements A-SPEC-545.3
+ * Idempotent per-root dashboard registry: start once, reuse thereafter. `start` is injected so the
+ * idempotency is testable without a real server. A failing start registers nothing.
+ */
+async function ensureDashboard(root, port, start) {
+    const existing = live.get(root);
+    if (existing)
+        return { url: existing.url, port: existing.port, running: true };
+    const h = await start({ root, port }); // a throw here registers nothing and propagates
+    live.set(root, h);
+    return { url: h.url, port: h.port, running: false };
+}
+/** Test hook: forget all launched servers (without stopping them). */
+function _resetLauncher() {
+    live.clear();
+}
+/** Test/shutdown hook: stop every launched server and clear the registry. */
+async function _stopAll() {
+    for (const h of live.values()) {
+        try {
+            await h.stop?.();
+        }
+        catch { /* best effort */ }
+    }
+    live.clear();
+}

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/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",