@sigloch/graph-view-edit 0.7.2 → 0.8.0

package/vite.config.js

@@ -1,10 +1,25 @@
 import { readFileSync, writeFileSync, mkdirSync, unlinkSync, existsSync, readdirSync, realpathSync, statSync, watch } from 'node:fs';
+import { execFileSync } from 'node:child_process';
 import { join, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { defineConfig } from 'vite';
 import react from '@vitejs/plugin-react';
 import { DefaultRuleEngine, SE_DESCRIPTOR, fromOntologyGraph } from '@sigloch/graph-api-core';
-import { ONTOLOGY_VERSION, RULES_VERSION } from '@sigloch/contracts/se';
+// CR-GVE-262: `moduleMetrics` ist DIESELBE Funktion, auf die graphcodes
+// graph_metrics ein dünnes Binding ist ("KEINE Rechnung hier", tools/metrics.ts)
+// — die Kohäsions-Karte rechnet also nichts selbst, sie ruft die eine Referenz.
+// CR-GVE-274: `metrics` ist DIESELBE Funktion, aus der der Host seinen Ist-Vektor
+// bildet (archMetrics -> fit-advisory.ts) — der Flugschreiber rechnet also nichts
+// Eigenes, er ruft dieselbe Referenz, genau wie er es fuer die Regeln mit
+// DefaultRuleEngine tut. Gemessen: 0,7 ms je Stand.
+import { metrics as archMetricsOf } from '@sigloch/se-engine';
+import {
+  ONTOLOGY_VERSION,
+  RULES_VERSION,
+  moduleMetrics,
+  MetricPolicySchema,
+  DEFAULT_METRIC_POLICY,
+} from '@sigloch/contracts/se';
 // CR-GC-265: these eight come from the read-side client, not the substrate.
 // They are pure projection plus a node:net socket call — depending on
 // @sigloch/graphcode for them pulled kuzu-wasm, the MCP SDK and the TypeScript
@@ -125,12 +140,22 @@ function graphStaticPlugin() {
  * (a foreign repo without its own gve config.json), the first
  * docs/graph/*.graph.json wins — the same discovery the dashboard uses, so
  * `gve --repo <path>` needs no per-repo config to find the graph.
+ *
+ * `repoRoot` (CR-GVE-271) ist KEIN Config-Feld — es steht bewusst nicht in
+ * ConfigSchema, sondern nur in dieser Antwort: es ist die Identität dieser
+ * Instanz, dieselbe wie in `/api/dashboard`. Warum hier zusätzlich: ein
+ * Starter fragt nur »bedient dieser Viewer MEIN Repo?«, und `/api/dashboard`
+ * beantwortet das erst, nachdem es Readiness über den Host gegen den Store
+ * gerechnet hat — in graphcode selbst ~1,1 s. Jede Probe mit knappem Budget
+ * las das als »kein Viewer da« und startete einen weiteren; Vite bumpte den
+ * Port, und die Waisen sammelten sich. Diese Antwort kostet keine Rechnung.
  */
 function configApiPlugin() {
   const middleware = (req, res, next) => {
     if (req.url !== '/api/config') return next();
     const repoRoot = resolveRepoRoot();
     const config = structuredClone(APP_CONFIG);
+    config.repoRoot = servedRepoRoot();
     if (!existsSync(join(repoRoot, config.graph.path))) {
       const graphDir = join(repoRoot, 'docs', 'graph');
       const hit = existsSync(graphDir)
@@ -315,6 +340,643 @@ export function autopilotStats(jsonlText) {
   };
 }
 
+/**
+ * Karte 1 „Hält der Bauplan?" (CR-GVE-262) — Kohäsion je Modul aus
+ * `moduleMetrics` (@sigloch/contracts/se), der EINEN Referenzrechnung hinter
+ * `graph_metrics.cohesion`. Reine Präsentations-Aggregation (Grenze
+ * CR-GVE-257): sortieren + summieren, keine eigene Metrik.
+ *
+ * `cohesion: null` (nicht messbar — < 2 FUNCs oder keine externe Verbindung)
+ * bleibt null und zählt NICHT in die Kennzahl: nicht messbar ist nicht 0
+ * (CR-GC-326-Regel). Sortiert nach Verbindungszahl absteigend — die
+ * Reihenfolge ist das Signal; nicht messbare Module stehen am Ende.
+ */
+export function cohesionPayload(ontologyJson) {
+  return cohesionRollup(moduleMetrics(ontologyJson));
+}
+
+/**
+ * Die Präsentations-Aggregation über fertige Modulzeilen (CR-GVE-272) — sortieren
+ * und summieren, sonst nichts. Sie ist von der QUELLE der Zeilen getrennt, weil es
+ * die Quelle ist, die sich mit diesem CR ändert: Host statt Eigenrechnung. Die
+ * Sortierung bleibt die aus CR-GVE-262 (Verbindungszahl absteigend) — den Host
+ * seine eigene Rangfolge (schlechteste Kohäsion zuerst) durchreichen zu lassen,
+ * wäre eine Änderung der DARSTELLUNG und gehört nicht in einen CR, der die HERKUNFT
+ * umstellt.
+ *
+ * Alle sechs Messungen je Modul reisen mit — vorher behielt diese Stelle
+ * `cohesion` und `allocatedFuncs` und warf `instability`, `lcom4`, `fanIn` und
+ * `fanOut` weg, weshalb die Karte den Wert hatte, aber nicht urteilen konnte.
+ */
+function cohesionRollup(rawModules) {
+  const rows = rawModules.map((m) => ({
+    moduleId: m.moduleId,
+    moduleName: m.moduleName,
+    allocatedFuncs: m.allocatedFuncs,
+    cohesion: m.cohesion,
+    instability: m.instability ?? null,
+    lcom4: m.lcom4 ?? null,
+    fanIn: m.fanIn ?? null,
+    fanOut: m.fanOut ?? null,
+  }));
+  const connections = (m) => (m.cohesion ? m.cohesion.internal + m.cohesion.external : -1);
+  rows.sort((a, b) => connections(b) - connections(a) || a.moduleId.localeCompare(b.moduleId));
+  const measurable = rows.filter((m) => m.cohesion);
+  return {
+    modules: rows,
+    internal: measurable.reduce((n, m) => n + m.cohesion.internal, 0),
+    total: measurable.reduce((n, m) => n + m.cohesion.internal + m.cohesion.external, 0),
+  };
+}
+
+/**
+ * Der Architektur-Block des Dashboards (CR-GVE-272) — EINE Stelle, die entscheidet,
+ * woher Modulzahlen, Schwellen und Zielmarke kommen, und die es ANSAGT.
+ *
+ * Mit Host: alles aus `graph_metrics`, unverändert durchgereicht — Modulzeilen,
+ * `policy`/`policySource` (CR-GC-329) und `fit` mit Ist-Vektor, Zielgewichten,
+ * Zielwerten und der Widerspruchsliste (CR-GC-451/457).
+ *
+ * Ohne Host: der bisherige lokale Weg, und `origin: 'local'` mit `reason` sagt es
+ * an — dasselbe Muster wie `readinessSource`. Was der lokale Weg NICHT kennt, ist
+ * dann `null`, nie ein erfundener Wert: `fit` gibt es lokal gar nicht (der
+ * Ist-Vektor kommt aus der se-engine, die gve nicht lädt), und aus dem Zielprofil
+ * liest der Fallback nur die Gewichte.
+ */
+export function architecturePayload({ hostMetrics, hostError, ontologyJson, repoRoot }) {
+  if (hostMetrics) {
+    return {
+      origin: 'host',
+      reason: null,
+      cohesion: cohesionRollup(hostMetrics.modules),
+      policy: hostMetrics.policy,
+      policySource: hostMetrics.policySource ?? null,
+      fit: hostMetrics.fit ?? null,
+    };
+  }
+  const local = readMetricPolicy(repoRoot);
+  return {
+    origin: 'local',
+    reason: hostError,
+    cohesion: cohesionPayload(ontologyJson),
+    policy: local.policy,
+    policySource: local.source,
+    // CR-GVE-280: der Grund reist mit, sonst ist `invalid` eine Behauptung ohne Fundstelle.
+    ...(local.reason ? { policyError: local.reason } : {}),
+    // Der Ist-Vektor ist eine Host-Zahl; ohne Host gibt es ihn nicht. Die
+    // Zielrichtung aus der Profildatei bleibt lesbar, der Zielwert kommt bewusst
+    // NICHT mit: er ist nur zusammen mit dem Ist-Wert sinnvoll, gegen den er steht.
+    fit: null,
+    profile: targetProfilePayload(repoRoot),
+  };
+}
+
+/**
+ * Die Architektur-Regeln der Befund-Tabelle (CR-GVE-262).
+ *
+ * CR-GVE-273: `R-04` (Kopplung) und `MT-02` (LCOM4) sind hier RAUS. Sie sind die
+ * Regelform von zwei Spalten, die seit CR-GVE-272 in der Modultabelle daneben
+ * stehen — dieselbe Kopplung, dieselbe Gruppenzahl, nur anders formuliert; genau
+ * der Eindruck „sieht doppelt aus" aus dem Review. Verloren geht nichts: ihr
+ * Urteil ist der Chip in der Tabelle, und der Chip nennt die Regel-ID, also ist
+ * die Regelerklärung einen Hover entfernt.
+ *
+ * `RD-04` bleibt — es feuert auch auf FUNC-Container und ist damit nicht dieselbe
+ * Aussage wie eine Modulzeile. `R-23` bleibt — es ist der Befund, zu dem es einen
+ * anwendbaren Vorschlag gibt.
+ */
+const ARCH_RULE_LABELS = {
+  'RD-04': 'Zu viele Kinder auf einer Ebene',
+  'R-23': 'Modul ohne Funktion',
+};
+
+/**
+ * Karte 2, Tabellenteil (CR-GVE-262) — die Architektur-Befunde aus dem
+ * VORHANDENEN Engine-Lauf (dieselben Violations, die rules_evaluate liefert),
+ * gefiltert auf R-04/RD-04/MT-02/R-23. `numbers` sind die Zahlen aus der
+ * Regel-Meldung SELBST (keine zweite Rechnung neben der Regel); `applicable`
+ * ist der Join gegen graph_suggest: true/false = Suggestion vorhanden und
+ * vom Gate durchgelassen/abgelehnt, null = kein Vorschlag zu diesem Befund
+ * (oder graph_suggest nicht erreichbar — das sagt `suggestAvailable`).
+ */
+export function architectureFindings(violations, suggest) {
+  return violations
+    .filter((v) => Object.hasOwn(ARCH_RULE_LABELS, v.ruleId))
+    .map((v) => {
+      const s = suggest?.suggestions?.find((x) => x.ruleId === v.ruleId && x.elementId === v.elementId);
+      return {
+        ruleId: v.ruleId,
+        label: ARCH_RULE_LABELS[v.ruleId],
+        elementId: v.elementId,
+        severity: v.severity,
+        // Kein Treffer mitten in einem Bezeichner: die 4 in "LCOM4=6" ist Teil
+        // des Regelnamens, keine Zahl der Meldung (Lookbehind auf Buchstaben).
+        numbers: (v.message.match(/(?<![A-Za-z])\d+(?:[.,]\d+)?/g) ?? []).join(' / '),
+        message: v.message,
+        applicable: s ? s.applicable === true : null,
+      };
+    });
+}
+
+/**
+ * Das hinterlegte Zielprofil (CR-GC-295, committete Steuer-Config
+ * `.graphcode/target-profile.json` des bedienten Repos) — nur GELESEN für die
+ * Zielmarken der Karte 2. Fehlt es oder ist es unlesbar: null — die Karte
+ * zeigt dann den Hinweis statt einer erfundenen Zielrichtung (AC 4).
+ */
+export function targetProfilePayload(repoRoot) {
+  const file = join(repoRoot, '.graphcode', 'target-profile.json');
+  if (!existsSync(file)) return null;
+  try {
+    const { weights } = JSON.parse(readFileSync(file, 'utf8'));
+    return weights && typeof weights === 'object' ? { weights } : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * DIE Regel-Engine-Konstruktion — eine für den Live-Stand (buildDashboard)
+ * und für die History-Messung (CR-GC-410): derselbe Messpfad, keine zweite
+ * Konfiguration, die auseinanderdriften könnte.
+ */
+function createRuleEngine() {
+  const engine = new DefaultRuleEngine(SE_DESCRIPTOR.version);
+  engine.register(SE_DESCRIPTOR.rules ?? []);
+  return engine;
+}
+
+/**
+ * JSONC → JSON für `graphcode.config.jsonc` (CR-GC-402). Zeichen-Scanner statt
+ * Regex, weil ein `//` INNERHALB eines Strings (ein Pfad, eine URL) sonst den Rest
+ * der Zeile verschluckt.
+ *
+ * Warum eine eigene Zeile Code und kein Import: die Referenz-Implementierung liegt
+ * in graphcodes `src/harness/config.ts`, und `@sigloch/graphcode` zieht kuzu-wasm
+ * plus das MCP-SDK nach — in einen Viewer, der strukturell nie einen Store öffnen
+ * darf (CR-GC-265). Ein leichter Subpath dafür existiert nicht.
+ */
+export function stripJsonComments(text) {
+  let out = '';
+  let inString = false;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < text.length; i++) {
+    const c = text[i];
+    const next = text[i + 1];
+    if (inLine) {
+      if (c === '\n') { inLine = false; out += c; }
+      continue;
+    }
+    if (inBlock) {
+      if (c === '*' && next === '/') { inBlock = false; i++; }
+      else if (c === '\n') out += c;
+      continue;
+    }
+    if (inString) {
+      out += c;
+      if (c === '\\') { out += text[++i] ?? ''; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === '/' && next === '/') { inLine = true; i++; continue; }
+    if (c === '/' && next === '*') { inBlock = true; i++; continue; }
+    out += c;
+  }
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+/**
+ * Die Urteilsschwellen des BEDIENTEN Repos (CR-GC-402) — dieselbe Datei, aus der
+ * der graphcode-Host seine Policy nimmt, gelesen für den Fall, dass kein Host
+ * antwortet. Ohne sie urteilte die Ersatzrechnung mit `DEFAULT_METRIC_POLICY` und
+ * widersprach dem Host an genau den Regeln, deren Schwelle das Repo verstellt hat
+ * (gemessen: MT-01 feuerte dashboardseitig 1×, hostseitig 0×, weil das Repo
+ * `instability: null` gesetzt hatte).
+ *
+ * Fehlt/kaputt die Datei → Default MIT Vermerk (`source`), nie ein stiller
+ * Ersatzwert: die Herkunft geht mit der Zahl an die Anzeige.
+ */
+export function readMetricPolicy(repoRoot) {
+  const file = join(repoRoot, 'graphcode.config.jsonc');
+  if (!existsSync(file)) return { policy: DEFAULT_METRIC_POLICY, source: 'default' };
+  try {
+    const parsed = JSON.parse(stripJsonComments(readFileSync(file, 'utf8')));
+    const result = MetricPolicySchema.safeParse(parsed?.metricPolicy);
+    if (result.success) return { policy: result.data, source: 'config' };
+    // CR-GVE-280: eine Datei, die DA ist und nicht passt, ist etwas anderes als keine Datei.
+    // Vorher meldete beides `default` — wer eine Schwelle eintrug und nichts geschah, sah eine
+    // Antwort, die aussah wie "es gibt hier keine Config". Gefunden hat es der eigene Test:
+    // seine Fixture-Config verlor mit CR-SM-282/-283 die Pflichtfelder `decompositionBreadth`
+    // und `boundaryWidth`, wurde still verworfen, und die Zusage "urteilt mit der Policy DES
+    // REPOS" war monatelang unbelegt. Der Viewer kann nicht abbrechen wie der Host — aber
+    // verschweigen darf er es nicht.
+    return {
+      policy: DEFAULT_METRIC_POLICY,
+      source: 'invalid',
+      reason: result.error.issues.map((i) => `${i.path.join('.') || '(Wurzel)'}: ${i.message}`).join(' · '),
+    };
+  } catch (e) {
+    return { policy: DEFAULT_METRIC_POLICY, source: 'invalid', reason: String(e?.message ?? e) };
+  }
+}
+
+/**
+ * Die Readiness beim graphcode-Host holen (CR-GC-402, Option C) — derselbe
+ * `host.sock`-Weg wie /api/mutate und graph_suggest, also DAS Gate, DER Store,
+ * EINE Rechnung. `detail:true`, weil der Payload sowohl den Report als auch die
+ * rohen Violations braucht (Empfehlungen, Blocker-Gruppen, Architektur-Befunde) —
+ * ein zweiter Aufruf von `rules_evaluate` wäre eine zweite Erhebung derselben Liste.
+ *
+ * Auch die RC-Konformanzregeln (RC-01..06) kommen nur über diesen Weg: sie brauchen
+ * den Quellbaum, den der Viewer nicht auswertet. Das war das zweite Rest-Delta des CR.
+ *
+ * Kein Host → `{report: null, error}`; der Aufrufer rechnet dann selbst UND sagt es an.
+ * Eine formfremde Antwort (fremder/alter Host) zählt genauso als „nicht verwertbar" —
+ * lieber die angesagte Ersatzrechnung als eine halbe Zahl aus unbekannter Quelle.
+ */
+export async function fetchHostReadiness(repoRoot, callHostImpl = callHost) {
+  const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+  try {
+    const report = await callHostImpl(socketPath, 'graph_readiness', { detail: true });
+    if (!report?.compliance || !Array.isArray(report.violations)) {
+      return { report: null, error: 'graph_readiness lieferte keinen verwertbaren Report (detail:true)' };
+    }
+    return { report, error: null };
+  } catch (err) {
+    return { report: null, error: err.message };
+  }
+}
+
+/**
+ * Die Architektur-Kennzahlen vom HOST (CR-GVE-272) — dieselbe Linie wie
+ * `fetchHostReadiness` eine Etage höher: der Host besitzt die Zahlen.
+ *
+ * Vorher beantwortete gve dieselbe Frage an DREI Stellen lokal: `cohesionPayload`
+ * rechnete `moduleMetrics()` über die COMMITTETE Datei (der Host misst den
+ * Live-Store — zwischen Mutation und Export sagen die zwei Verschiedenes),
+ * `readMetricPolicy` las `graphcode.config.jsonc` selbst, und
+ * `targetProfilePayload` las das Zielprofil selbst und behielt daraus nur die
+ * Gewichte. Genau diese Aufteilung verbietet CR-GC-329/451/457: Wert, Schwelle
+ * und Zielmarke verlassen den Host in EINER Antwort, und wer eine davon selbst
+ * hält, ist eine zweite Quelle für dieselbe Zahl.
+ *
+ * `modules` UND `policy` müssen da sein, sonst ist die Antwort nicht verwertbar:
+ * ein alter Host (vor CR-GC-329) liefert Zeilen ohne Schwellen, und eine Karte,
+ * die dann die Schwelle lokal ergänzt, wäre wieder die zweite Quelle. Lieber die
+ * angesagte Ersatzrechnung als eine halbe Zahl aus unbekannter Quelle.
+ */
+export async function fetchHostMetrics(repoRoot, callHostImpl = callHost) {
+  const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+  try {
+    const m = await callHostImpl(socketPath, 'graph_metrics', {});
+    if (!Array.isArray(m?.modules) || !m?.policy) {
+      return { metrics: null, error: 'graph_metrics lieferte keine verwertbaren Modulzahlen (modules + policy)' };
+    }
+    return { metrics: m, error: null };
+  } catch (err) {
+    return { metrics: null, error: err.message };
+  }
+}
+
+/**
+ * Flugschreiber „Wirkt die Arbeit?" (CR-GC-410) — jeden COMMITTETEN Graph-
+ * Stand (Git-History von docs/graph/*.graph.json) über den VORHANDENEN
+ * Messpfad bewerten: fromOntologyGraph + DefaultRuleEngine(SE_DESCRIPTOR),
+ * exakt der Weg, den buildDashboard für den Live-Stand geht (CR-GC-303/324-
+ * Lehre: kein zweiter Messpfad). Reine Lese-Funktion — `git log`/`git show`,
+ * nichts wird geschrieben; trajectory.jsonl und recordAudit bleiben unberührt.
+ *
+ * Cache je Commit-Hash (Stände sind unveränderlich): der zweite Aufruf misst
+ * nur, was neu committet wurde. Ein unparsebarer/prä-ontologischer Stand wird
+ * ÜBERSPRUNGEN und gezählt, nie als (0/0)-Punkt erfunden — nicht messbar ist
+ * nicht 0 (CR-GC-326-Regel). Kein Git-Repo / kein committeter Stand → null.
+ * Messwert 2026-08-27 (kalt): graphcode, 78 Stände → ~3.1 s (~40 ms/Stand);
+ * warm (alles im Cache) → ~70 ms fürs `git log`.
+ *
+ * CR-GC-441: je Stand zusätzlich `warnings`/`infos` — dieselben Violations,
+ * nur nach Severity aufgeteilt (`severity` ist ein geschlossenes Trio, also
+ * gilt immer errors + warnings + infos === open; keine zweite Auswertung).
+ */
+
+/**
+ * Schema-Version des Cache-Eintrags (CR-GC-441). Der Cache lebt im
+ * Prozess-Speicher (eine Map im dashboardApiPlugin, nichts auf Disk) und ist je
+ * Commit-Hash geschlüsselt — ein Stand ist unveränderlich, sein MESSERGEBNIS
+ * aber nicht: wächst die Messung um ein Feld, trägt der alte Eintrag es nicht
+ * und schlüge als `warnings: undefined` bis in die Karte durch. Die Version
+ * gehört deshalb in den Key: alte Einträge treffen nie, neu gemessen wird
+ * automatisch. Bei jedem neuen/geänderten Messfeld hochzählen.
+ */
+const HISTORY_MEASURE_SCHEMA = 3;
+
+export function measureGraphHistory(repoRoot, { cache = new Map(), gitImpl, policy: givenPolicy } = {}) {
+  const git =
+    gitImpl ??
+    ((args) =>
+      execFileSync('git', ['-C', repoRoot, ...args], {
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+        // stderr schlucken: „kein Git-Repo" ist hier ein erwarteter Zustand
+        // (→ null), kein Log-Lärm im Server-/Testlauf.
+        stdio: ['ignore', 'pipe', 'pipe'],
+      }));
+  let log;
+  try {
+    log = git(['log', '--reverse', '--format=%x01%H %cI', '--name-only', '--', 'docs/graph/*.graph.json']);
+  } catch {
+    return null; // kein Git-Repo — bekannter Zustand, kein Fehler
+  }
+  // %x01-Marker statt Zeilenraten: je Commit ein Header + die geänderten Dateien.
+  const states = [];
+  let cur = null;
+  for (const line of log.split('\n')) {
+    if (line.startsWith('\x01')) {
+      const [hash, ts] = line.slice(1).split(' ');
+      cur = { hash, ts };
+    } else if (cur && line.endsWith('.graph.json')) {
+      states.push({ ...cur, file: line });
+      cur = null; // erste Graph-Datei des Commits zählt als der Stand
+    }
+  }
+  if (states.length === 0) return null;
+  const engine = createRuleEngine();
+  // CR-GC-402: dieselben Schwellen wie die Karte daneben — sonst misst der
+  // Flugschreiber die History gegen einen anderen Maßstab.
+  //
+  // CR-GVE-272: seit die Karte ihre Schwellen vom HOST bezieht, reicht der
+  // eigene Datei-Read dafür nicht mehr — er wäre wieder die zweite Quelle, nur
+  // eine Etage tiefer und ohne Test, der es merkt. Der Aufrufer gibt die
+  // Host-Policy weiter; ohne Host bleibt der Read die Quelle des Fallbacks.
+  const { policy, source: policySource } = givenPolicy
+    ? { policy: givenPolicy.policy, source: givenPolicy.source }
+    : readMetricPolicy(repoRoot);
+  const t0 = performance.now();
+  let measured = 0;
+  let skipped = 0;
+  const out = [];
+  for (const s of states) {
+    // CR-GVE-272: die Policy-HERKUNFT gehört in den Key. Ein Stand ist
+    // unveränderlich, sein Messergebnis aber nur relativ zu den Schwellen, gegen
+    // die gemessen wurde — startet der Host mitten in der Session, träfen sonst
+    // die Einträge des lokalen Laufs weiter und die Kurve mischte zwei Maßstäbe.
+    const key = `${HISTORY_MEASURE_SCHEMA}:${policySource}:${s.hash}`;
+    let m = cache.get(key);
+    if (!m) {
+      try {
+        // CR-GVE-274: der Stand liegt hier bereits als OntologyGraph vor — genau
+        // die Form, die `metrics()` erwartet. Der Vektor kostet EINEN Aufruf auf
+        // dem schon geladenen Objekt, keinen zweiten Ladepfad und kein zweites
+        // `git show`.
+        const ontologyJson = JSON.parse(git(['show', `${s.hash}:${s.file}`]));
+        const { nodes, edges } = fromOntologyGraph(ontologyJson);
+        const violations = engine.evaluate({ nodes, edges }, policy);
+        m = {
+          elements: nodes.length,
+          open: violations.length,
+          errors: violations.filter((v) => v.severity === 'error').length,
+          warnings: violations.filter((v) => v.severity === 'warning').length,
+          infos: violations.filter((v) => v.severity === 'info').length,
+          fit: archMetricsOf(ontologyJson, { layer: 'arch' }),
+        };
+      } catch {
+        m = { skipped: true };
+      }
+      cache.set(key, m);
+      measured += 1;
+    }
+    if (m.skipped) skipped += 1;
+    else out.push({ hash: s.hash, short: s.hash.slice(0, 7), ts: s.ts, ...m });
+  }
+  return {
+    states: out,
+    skipped,
+    measured,
+    fromCache: states.length - measured,
+    measureMs: Math.round(performance.now() - t0),
+  };
+}
+
+/**
+ * y-Achsen-Maximum des Flugschreibers (CR-GC-443): die kleinste RUNDE GANZE
+ * Zahl oberhalb des Daten-Maximums, mit ~5 % Luft, damit der höchste Punkt
+ * nicht am Rahmen klebt. Ganzzahlig, weil die Achse genau diese Zahl
+ * anschreibt — eine gerundete Beschriftung über einer krummen Skala wäre
+ * gelogen. Unter 10 ist jede Zahl rund genug (Daten-Max + 1); darüber die
+ * gewohnte 1/1.2/1.5/2/2.5/…-Leiter, die nie mehr als ~25 % Höhe verschenkt.
+ */
+const FR_NICE_STEPS = [1, 1.2, 1.5, 2, 2.5, 3, 3.5, 4, 5, 6, 8, 10];
+
+export function frAxisTop(dataMax) {
+  if (!(dataMax > 0)) return 1; // alles gebunden: flache Linie unten, keine 0-Division
+  if (dataMax < 10) return Math.ceil(dataMax) + 1;
+  const target = dataMax * 1.05;
+  const mag = 10 ** Math.floor(Math.log10(target));
+  const step = FR_NICE_STEPS.find((m) => m * mag >= target) ?? 10;
+  return Math.round(step * mag);
+}
+
+/**
+ * Präsentations-Aggregation der History-Messung (CR-GC-410): Pfad in Commit-
+ * Reihenfolge (nach rechts = gebaut, nach unten = gebunden) und der
+ * Sekundärbefund „N der letzten M Stände ohne error" als Gate-Wirkungs-Nachweis
+ * (Fenster max. 24).
+ *
+ * CR-GC-441 ergänzt zwei Dinge, damit „0 der letzten 24 ohne error" nicht als
+ * Arbeitsurteil missverstanden wird:
+ * - `severityRange`: min/max je Severity über DASSELBE Fenster. Eine Spanne ist
+ *   ein Fakt über die gemessenen Stände, keine Trendaussage — genau das, was die
+ *   Daten tragen, wenn das Regelwerk sich unter ihnen bewegt hat. Fehlt die
+ *   Aufschlüsselung in den Ständen (alter Payload), ist sie `null`, nicht 0.
+ * - `rulesVersion`: mit welchem Regelstand JEDER historische Stand bewertet
+ *   wurde — der Vorbehalt, den die Karte anschreibt.
+ *
+ * CR-GC-443 ergänzt `scale`: die y-Skala folgt dem DATEN-Maximum. Sie gehört in
+ * diese Aggregation (wie errorFree), nicht in die Zeichenschicht — dort bleibt
+ * reine Pixel-Geometrie, es gibt keine zweite Skalenrechnung.
+ *
+ * CR-GVE-266 streicht die Vergleichsgerade („wenn jedes neue Element seine
+ * Verstöße mitbrächte"). Sie verließ die Skala regelmäßig nach oben und kostete
+ * dafür Kappungs-Marker, Legendensatz und drei Payload-Felder — die Skala hing
+ * schon seit CR-GC-443 nicht mehr an ihr.
+ */
+export function flightRecorderPayload(history) {
+  if (!history || history.states.length === 0) return null;
+  const maxElements = Math.max(1, ...history.states.map((s) => s.elements));
+  // Daten-Maximum über ALLE gezeichneten Serien: errors+warnings+infos === open
+  // (geschlossenes Trio, CR-GC-441), `open` ist also ihre obere Schranke —
+  // ein Maximum über die Nebenlinien wäre dieselbe Zahl.
+  const dataMax = Math.max(0, ...history.states.map((s) => s.open));
+  const yMax = frAxisTop(dataMax);
+  const windowSize = Math.min(24, history.states.length);
+  const recent = history.states.slice(-windowSize);
+  const hasSeverity = recent.every((s) => typeof s.warnings === 'number' && typeof s.infos === 'number');
+  const span = (key) => ({
+    min: Math.min(...recent.map((s) => s[key])),
+    max: Math.max(...recent.map((s) => s[key])),
+  });
+  return {
+    states: history.states,
+    scale: { maxElements, dataMax, yMax },
+    errorFree: { count: recent.filter((s) => s.errors === 0).length, window: windowSize },
+    severityRange: hasSeverity
+      ? { window: windowSize, errors: span('errors'), warnings: span('warnings'), infos: span('infos') }
+      : null,
+    // CR-GVE-274: „bewegt es sich dorthin?" — die Bewegung über DASSELBE Fenster,
+    // über das die Karte auch `errorFree` und `severityRange` aussagt. Nicht seit
+    // dem allerersten Commit: der älteste Stand dieses Repos hat 68 Elemente und
+    // keine Modulstruktur, gemessen wären das +4.06 auf coherence — wahr, aber es
+    // mischt „wir haben es gebaut" mit „wir haben es verbessert". Eine Zahl, ein
+    // Vergleich, dieselbe Spanne wie nebenan.
+    //
+    // Übersprungene Stände tragen kein `fit` und fallen heraus; unter zwei
+    // messbaren Ständen gibt es keine Bewegung, und eine Differenz gegen nichts
+    // wäre keine 0, sondern erfunden.
+    fitTrend: (() => {
+      const measured = recent.filter((s) => s.fit);
+      if (measured.length < 2) return null;
+      const first = measured[0];
+      const last = measured[measured.length - 1];
+      return { from: first.fit, to: last.fit, states: measured.length, window: windowSize, since: first.ts };
+    })(),
+    // Der Maßstab, gegen den ALLE Stände gemessen wurden — nicht der, der zum
+    // jeweiligen Commit galt. Die Karte schreibt das an.
+    rulesVersion: RULES_VERSION,
+    skipped: history.skipped,
+    measured: history.measured,
+    fromCache: history.fromCache,
+    measureMs: history.measureMs,
+  };
+}
+
+/**
+ * graph_suggest über denselben host.sock-Pfad wie /api/mutate (CR-GC-241) —
+ * das Anwendbarkeits-Urteil (`applicable`, seit CR-GC-431 im Ergebnis) braucht
+ * das Gate und existiert nur im laufenden graphcode-Host; gve kann und darf
+ * es nicht nachrechnen. Kein Host erreichbar → null, die Karte sagt das
+ * (bekannter Zustand, kein Fehler — wie autopilot: null).
+ */
+export async function fetchSuggest(repoRoot, callHostImpl = callHost) {
+  try {
+    const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+    return await callHostImpl(socketPath, 'graph_suggest', { k: 20 });
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * graph_next_step über denselben host.sock-Weg (CR-GC-433) — die Hygiene-Hälfte
+ * der Zeile „Der nächste Zug". Bis hierher lebte der Rundenschritt nur im
+ * Autopilot-Loop bzw. auf Abruf im Chat; das Dashboard hat ihn nie gezeigt.
+ *
+ * Kein Host → null. Der Viewer rechnet die Dimension NICHT nach: sie kommt aus
+ * `takeSteeringSnapshot` (contracts-Katalog inkl. der Regeln, die nur der
+ * Steering-Pfad wertet) — eine zweite Rechnung hier würde eine andere Dimension
+ * nennen als der Chat (die Lehre aus CR-GC-402).
+ */
+export async function fetchNextStep(repoRoot, callHostImpl = callHost) {
+  try {
+    const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+    return await callHostImpl(socketPath, 'graph_next_step', {});
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Regel-Erklärungen über denselben `host.sock`-Weg (CR-GVE-269). `HELP_CONTENT`
+ * in graphcode trägt zu JEDER Regel einen Klartext-Satz, die SE-Formulierung und
+ * wo anwendbar den kopierbaren Prompt; `graph_help` gibt sie heraus. gve holt sie
+ * ab und schreibt sie NICHT selbst — ein zweiter Regeltext wäre dieselbe zweite
+ * Quelle wie eine zweite Rechnung (CR-GVE-257, CR-GC-402).
+ *
+ * Je ID ein Aufruf, parallel, Fehler einzeln verschluckt: eine unbekannte ID
+ * (`graph_help` wirft dann) darf die Karte nicht mitnehmen — die Zeile steht
+ * auch ohne Erklärung, sie ist nur nackt.
+ */
+export async function fetchRuleHelp(repoRoot, ruleIds, callHostImpl = callHost) {
+  const ids = [...new Set((ruleIds ?? []).filter(Boolean))];
+  if (!ids.length) return {};
+  const socketPath = join(repoRoot, '.graphcode', HOST_SOCK_BASENAME);
+  const entries = await Promise.all(ids.map(async (id) => {
+    try {
+      const e = await callHostImpl(socketPath, 'graph_help', { token: id });
+      // Layer 1 (SE-Formulierung) bleibt draußen: das ist genau das Vokabular,
+      // das der Tooltip ersetzen soll.
+      //
+      // CR-GVE-273: bei einer KENNZAHL sind es drei Antworten, nicht eine
+      // (CR-GC-458) — was gezählt wird, wofür der Wert steht, was ihn bewegt.
+      // Auf `plain` gekürzt käme genau die Hälfte an, die der Auftraggeber
+      // vermisst hat. gve formuliert hier nichts nach: fehlt ein Feld, fehlt es.
+      if (!e?.plain) return null;
+      const base = { title: e.title ?? id, plain: e.plain, prompt: e.prompt ?? null };
+      return e.kind === 'metric'
+        ? [id, { ...base, kind: 'metric', measure: e.measure, purpose: e.purpose, lever: e.lever, scale: e.scale ?? null }]
+        : [id, base];
+    } catch {
+      return null;
+    }
+  }));
+  return Object.fromEntries(entries.filter(Boolean));
+}
+
+/**
+ * „Der nächste Zug" (CR-GC-433, Trigger-Art 2+3) — Architektur- und
+ * Hygiene-Empfehlung NEBENEINANDER, permanent, ohne Handoff-Endzustand als
+ * Voraussetzung (Entscheidung (a): Architektur läuft parallel zur Hygiene,
+ * nicht dahinter).
+ *
+ * Reine Zusammenführung zweier Host-Antworten — hier wird nichts gerankt und
+ * nichts gerechnet: `graph_suggest` liefert seine Liste bereits anwendbar-zuerst
+ * (CR-GC-431), also ist Top-1 schlicht das erste Element. Was der Payload
+ * zusätzlich trägt, ist die EHRLICHKEIT der Zeile: `applicable` und
+ * `applicableCount` trennen „ausführbarer Zug" von „Fund ohne Zug", und
+ * `available: false` trennt beides von „kein Host" — drei Zustände, die als
+ * einer dargestellt eine Empfehlung vortäuschen würden, die es nicht gibt.
+ */
+export function nextMovePayload(nextStep, suggest) {
+  const top = suggest?.suggestions?.[0] ?? null;
+  const edit = top?.edit ?? null;
+  return {
+    architecture: {
+      available: suggest != null,
+      // Anwendbar = vom Gate durchgelassen UND Δm trägt in die Zielrichtung.
+      // Ein positiver Score allein reicht nicht (der kann von der generischen
+      // Sonde stammen), das Gate-Urteil allein auch nicht (score ≤ 0 = weg vom Ziel).
+      applicableCount: (suggest?.suggestions ?? []).filter((s) => s.applicable === true && s.score > 0).length,
+      top: top && {
+        ruleId: top.ruleId,
+        elementId: top.elementId,
+        message: top.message,
+        score: top.score,
+        applicable: top.applicable === true,
+        // Der konkrete Zug, nicht nur der Fund. `retire` gesetzt heißt Umhängen:
+        // anwenden als EIN graph_mutate-Batch (CR-GC-435), `codeImpact` benennt
+        // die Code-Arbeit, die daran hängt.
+        edit: edit && {
+          source: edit.source,
+          target: edit.target,
+          type: edit.type,
+          retire: edit.retire ? { source: edit.retire.source, target: edit.retire.target, type: edit.retire.type } : null,
+          codeImpact: edit.codeImpact ?? null,
+        },
+      },
+    },
+    hygiene: {
+      available: nextStep != null,
+      // `nextStep: null` bei erreichbarem Host heißt „kein Schritt offen", NICHT
+      // „nicht messbar" — deshalb hängt `available` am Host, nicht am Schritt.
+      dimension: nextStep?.nextStep?.dimension ?? null,
+      deficit: nextStep?.nextStep?.deficit ?? null,
+      clears: nextStep?.nextStep?.clears ?? [],
+      action: nextStep?.nextStep?.action ?? null,
+      blockingErrors: nextStep?.blocking?.errors ?? null,
+    },
+  };
+}
+
 function dashboardApiPlugin() {
   const cwd = resolveRepoRoot();
   const GRAPH_DIR = join(cwd, 'docs', 'graph');
@@ -322,8 +984,10 @@ function dashboardApiPlugin() {
   // CR-GVE-257: die Trajektorie liegt im Ziel-Repo, nicht im Viewer-Repo —
   // derselbe resolveRepoRoot()-Anker wie GRAPH_DIR/host.sock.
   const TRAJECTORY_FILE = join(cwd, '.graphcode', 'trajectory.jsonl');
-  const engine = new DefaultRuleEngine(SE_DESCRIPTOR.version);
-  engine.register(SE_DESCRIPTOR.rules ?? []);
+  const engine = createRuleEngine();
+  // CR-GC-410: Ergebnis je Commit-Hash — Stände sind unveränderlich, der
+  // zweite /api/flightrecorder-Aufruf misst nur neu Committetes nach.
+  const historyCache = new Map();
 
   function findGraphFile() {
     if (!existsSync(GRAPH_DIR)) return null;
@@ -385,24 +1049,104 @@ function dashboardApiPlugin() {
     });
   }
 
-  function buildDashboard() {
+  async function buildDashboard() {
     const file = findGraphFile();
     if (!file) return { member: null, repoRoot: servedRepoRoot(), empty: true, error: 'no docs/graph/*.graph.json found', computedAt: new Date().toISOString() };
     const graph = loadGraph(file);
-    const violations = engine.evaluate(graph);
-    const report = computeReadiness(violations, graph);
-    return {
+    // CR-GC-402 (Option C): die Readiness kommt VOM HOST — dieselbe Rechnung, die
+    // der Chat zeigt, statt einer zweiten daneben. Nur ohne erreichbaren Host
+    // rechnet der Viewer selbst, dann aber MIT der Policy des Repos und mit einem
+    // sichtbaren Hinweis im Payload (`readinessSource`), den das Dashboard als
+    // Banner zeigt. Zwei Wege, keiner davon still.
+    // CR-GC-433: readiness UND next_step in EINER Welle. Beide sind reine
+    // Lesezugriffe auf denselben Graphen und stören einander nicht; nacheinander
+    // gerufen kostete der dritte Host-Roundtrip so viel, dass die Dashboard-Tests
+    // in ihr 5-s-Fenster liefen (gemessen 4,1 s → 6 s). graph_suggest bleibt
+    // BEWUSST danach und allein: es fährt je Kandidat einen dryRun und stellt die
+    // In-Memory-Kopie danach wieder her — parallel dazu zu lesen hieße, den
+    // Zwischenstand einer Sonde zu messen.
+    // CR-GVE-272: graph_metrics reist in DERSELBEN Welle mit — auch ein reiner
+    // Lesezugriff auf denselben Graphen, also derselbe Grund wie bei next_step.
+    const [host, nextStep, hostMetrics] = await Promise.all([
+      fetchHostReadiness(cwd),
+      fetchNextStep(cwd),
+      fetchHostMetrics(cwd),
+    ]);
+    const localPolicy = host.report ? null : readMetricPolicy(cwd);
+    const report = host.report ?? computeReadiness(engine.evaluate(graph, localPolicy.policy), graph);
+    // EINE Liste für Empfehlungen, Blocker-Gruppen und Architektur-Befunde — die
+    // des Reports, egal aus welcher der beiden Quellen er stammt.
+    const violations = report.violations ?? [];
+    // CR-GVE-262: graph_suggest liefert das Anwendbarkeits-Urteil — nur mit
+    // laufendem Host; ohne bleibt suggest null und die Karte sagt es.
+    const suggest = await fetchSuggest(cwd);
+    const payload = {
       member: basename(file).replace(/\.graph\.json$/, ''),
       repoRoot: servedRepoRoot(),
       empty: graph.nodes.length === 0,
+      // CR-GC-402: woher die Zahlen stammen, reist MIT den Zahlen.
+      readinessSource: host.report
+        ? { origin: 'host', reason: null, policySource: null }
+        : {
+            origin: 'local',
+            reason: host.error,
+            policySource: localPolicy.source,
+            // CR-GVE-280: `invalid` ohne Fundstelle waere eine Behauptung — der Grund reist mit,
+            // an DERSELBEN Stelle wie die Quelle, damit ein Leser nicht zwei Felder korrelieren muss.
+            ...(localPolicy.reason ? { policyError: localPolicy.reason } : {}),
+          },
       readiness: readinessPayload(report),
       recommendations: recommendationsPayload(violations, 50),
       artifacts: scanArtifacts(file, graph),
       health: synthHealth(graph),
+      // CR-GVE-262: die zwei Architektur-Karten — Kohäsion aus der
+      // graph_metrics-Referenzrechnung (contracts moduleMetrics, auf dem RAW
+      // OntologyGraph der committeten Datei), Befunde aus demselben
+      // Engine-Lauf wie rules_evaluate, applicable/Zielmarken aus
+      // graph_suggest + Zielprofil.
+      // CR-GVE-272: Modulzahlen, Schwellen und Zielmarke kommen aus EINER
+      // Host-Antwort (graph_metrics) statt aus drei lokalen Pfaden; `origin`
+      // sagt an, wenn stattdessen der Fallback gerechnet hat. `findings` bleibt,
+      // was es war — ein Filter über die vorhandenen Violations, keine Rechnung.
+      architecture: {
+        ...architecturePayload({
+          hostMetrics: hostMetrics.metrics,
+          hostError: hostMetrics.error,
+          ontologyJson: hostMetrics.metrics ? null : JSON.parse(readFileSync(file, 'utf8')),
+          repoRoot: cwd,
+        }),
+        findings: architectureFindings(violations, suggest),
+        suggestAvailable: suggest != null,
+      },
+      // CR-GC-433 (Trigger-Art 2+3): die permanente Zeile „Der nächste Zug" —
+      // Architektur (graph_suggest Top-1) und Hygiene (graph_next_step)
+      // nebeneinander, unabhängig davon, ob irgendein Gate-Endzustand erreicht ist.
+      nextMove: nextMovePayload(nextStep, suggest),
       // CR-GVE-257: Repo ohne Trajektorie → null (Karte zeigt den Hinweis).
       autopilot: existsSync(TRAJECTORY_FILE) ? autopilotStats(readFileSync(TRAJECTORY_FILE, 'utf8')) : null,
       computedAt: new Date().toISOString(),
     };
+    // CR-GVE-269: Erklärungen für GENAU die Regeln, die diese Antwort nennt —
+    // nach dem Zusammenbau, damit keine Liste doppelt gepflegt wird.
+    //
+    // Nur fragen, wenn überhaupt ein Host geantwortet hat: ohne ihn kostet jeder
+    // Aufruf einen Connect-Timeout, und die Antwort stünde ohnehin fest (leer).
+    // Ohne diese Klammer lief die /api/dashboard-Antwort in einem Repo ohne Host
+    // über ihr 5-s-Fenster (gemessen 4,0 s → 5,3 s).
+    const hostAnswered = host.report != null || suggest != null || nextStep != null;
+    payload.ruleHelp = !hostAnswered ? {} : await fetchRuleHelp(cwd, [
+      ...(payload.recommendations?.groups ?? []).map((g) => g.ruleId),
+      ...[...(payload.readiness?.phaseGates ?? []), ...(payload.readiness?.implGates ?? [])]
+        .flatMap((g) => (g.blockerGroups ?? []).map((grp) => grp.ruleId)),
+      ...(payload.readiness?.blockerRollup ?? []).map((g) => g.ruleId),
+      ...payload.architecture.findings.map((f) => f.ruleId),
+      payload.nextMove.architecture.top?.ruleId,
+      // CR-GVE-273: die Kennzahl-Namen, die Karte 2 zeigt — dieselbe Quelle wie
+      // die Regeltexte (CR-GC-458). Gefragt wird nach dem, was gezeichnet wird:
+      // ohne Ist-Vektor gibt es die Karte nicht und damit auch nichts zu erklären.
+      ...Object.keys(payload.architecture.fit?.metrics ?? {}),
+    ]);
+    return payload;
   }
 
   /**
@@ -436,9 +1180,36 @@ function dashboardApiPlugin() {
       res.end(markdown);
       return;
     }
+    // CR-GC-410: eigener Endpoint statt Huckepack auf /api/dashboard — die
+    // kalte History-Messung kostet Sekunden (78 Stände ≈ 3 s) und darf den
+    // Rest des Dashboards nicht aufhalten; die Karte holt sie separat.
+    if (url.pathname === '/api/flightrecorder') {
+      // CR-GVE-272: gegen DIESELBEN Schwellen messen, die die Karte daneben zeigt.
+      // Der Endpoint läuft eigenständig (CR-GC-410), also fragt er den Host selbst;
+      // antwortet der nicht, fällt measureGraphHistory auf den Datei-Read zurück —
+      // derselbe Fallback wie die Karte. `.then` statt async-Middleware: dasselbe
+      // Muster wie /api/dashboard eine Zeile weiter unten.
+      fetchHostMetrics(cwd).then((hm) => {
+        let payload = null;
+        try {
+          const policy = hm.metrics
+            ? { policy: hm.metrics.policy, source: hm.metrics.policySource ?? 'host' }
+            : undefined;
+          payload = flightRecorderPayload(measureGraphHistory(cwd, { cache: historyCache, policy }));
+        } catch {
+          payload = null; // Karte zeigt den Hinweis — kein 500 für eine Zusatzsicht
+        }
+        res.setHeader('Content-Type', 'application/json');
+        res.end(JSON.stringify(payload));
+      });
+      return;
+    }
     if (url.pathname !== '/api/dashboard') return next();
-    res.setHeader('Content-Type', 'application/json');
-    res.end(JSON.stringify(buildDashboard()));
+    // CR-GVE-262: buildDashboard ist async (graph_suggest über host.sock).
+    buildDashboard().then((payload) => {
+      res.setHeader('Content-Type', 'application/json');
+      res.end(JSON.stringify(payload));
+    });
   };
 
   return {