@sigloch/graphcode-client 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -6,11 +6,18 @@
  * no harness. The write path is unchanged — `callHost` forwards to the host's
  * ONE `mutate()` gate; this package never opens a second one.
  *
- * Scope split (CR-GC-264):
- *   - here          : host-socket client, view catalog (+ readiness/panels in CR-GC-265)
+ * Scope split (CR-GC-264/265):
+ *   - here               : host-socket client, view catalog, readiness projection, dashboard panels
  *   - @sigloch/graphcode : store, gate, MCP server, exporters, host election
  *
+ * The rule of thumb for what belongs here: it takes plain data in and returns
+ * plain data out. Anything that needs the store, the gate or a process stays in
+ * the substrate.
+ *
  * @author andreas@siglochconsulting
  */
 export { HOST_SOCK_BASENAME, callHost, type ShimRequest, type ShimResponse, } from './host-client.js';
 export { MARKDOWN_VIEWS, VIEW_FILENAMES, type MarkdownView } from './view-catalog.js';
+export { GRAPHCODE_INCOSE_SCOPE, PHASE_GATE_RULES, PHASE_GATE_LABELS, PHASE_GATE_CREATIONS, IMPL_GATE_PHASE, IMPL_GATE_MILESTONES, IMPL_GATE_RULES, ABSENT_CREATION_PROVIDER, creationBlockingMsg, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, type IncoseScope, type CreationCurrency, type CreationCurrencyProvider, type ReadinessDimension, type ReadinessGate, type ReadinessReport, } from './readiness.js';
+export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, hasOutTo, refFile, hasTestRef, hasCodeRef, isLeafFunc, fchainActorBounded, type CGraph, type CNode, type GateCompleteness, type CompletenessLeg, } from './readiness-completeness.js';
+export * from './panels.js';

package/dist/index.js

@@ -6,11 +6,18 @@
  * no harness. The write path is unchanged — `callHost` forwards to the host's
  * ONE `mutate()` gate; this package never opens a second one.
  *
- * Scope split (CR-GC-264):
- *   - here          : host-socket client, view catalog (+ readiness/panels in CR-GC-265)
+ * Scope split (CR-GC-264/265):
+ *   - here               : host-socket client, view catalog, readiness projection, dashboard panels
  *   - @sigloch/graphcode : store, gate, MCP server, exporters, host election
  *
+ * The rule of thumb for what belongs here: it takes plain data in and returns
+ * plain data out. Anything that needs the store, the gate or a process stays in
+ * the substrate.
+ *
  * @author andreas@siglochconsulting
  */
 export { HOST_SOCK_BASENAME, callHost, } from './host-client.js';
 export { MARKDOWN_VIEWS, VIEW_FILENAMES } from './view-catalog.js';
+export { GRAPHCODE_INCOSE_SCOPE, PHASE_GATE_RULES, PHASE_GATE_LABELS, PHASE_GATE_CREATIONS, IMPL_GATE_PHASE, IMPL_GATE_MILESTONES, IMPL_GATE_RULES, ABSENT_CREATION_PROVIDER, creationBlockingMsg, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, } from './readiness.js';
+export { NEUTRAL_COMPLETENESS, COMPLETENESS_SLICES, scoreCompleteness, typeOf, hasOutTo, refFile, hasTestRef, hasCodeRef, isLeafFunc, fchainActorBounded, } from './readiness-completeness.js';
+export * from './panels.js';

package/dist/panels.d.ts

@@ -0,0 +1,151 @@
+/**
+ * MOD-dashboard — headless panel data-layer (CR-GC-115, moved here CR-GC-265).
+ *
+ * The READ-ONLY data layer behind every dashboard panel: pure functions that
+ * shape tool outputs (graph_readiness / graph_impact / rules_get_violations /
+ * host /health) into view-models an external renderer mounts. No HTTP, no DOM,
+ * no mutation — REQ-dashboard-readonly is structural (these are pure projections
+ * of read-only inputs).
+ *
+ * Lives in graphcode-client, not graphcode: a renderer needs these functions and
+ * nothing else from the substrate. Importing them from `@sigloch/graphcode` also
+ * dragged in kuzu-wasm and the MCP SDK — a viewer that is forbidden from opening
+ * a store was installing an embedded graph database to draw a panel.
+ *
+ * @author andreas@siglochconsulting
+ */
+import type { ReadinessReport, ReadinessGate, CreationCurrency, CreationCurrencyProvider } from './readiness.js';
+import type { RuleViolation, LiveUpdateEvent } from '@sigloch/contracts/harness';
+export interface GatePanel {
+    id: string;
+    label: string;
+    passed: boolean;
+    score: number;
+    /** The blocking elements — the drill-down behind the traffic light. */
+    blocking: string[];
+    /**
+     * Structural completeness (CR-GC-250): ONE value per gate (covered/total) for
+     * the panel; `missing[]` is the on-click per-leg drill-down, same mechanic as
+     * `blocking`. REQ-completeness-single-value.
+     */
+    completeness: ReadinessGate['completeness'];
+}
+export interface ReadinessPanel {
+    compliancePct: number;
+    totalElements: number;
+    elementsWithErrors: number;
+    phaseGates: GatePanel[];
+    implGates: GatePanel[];
+}
+export declare function readinessPanel(report: ReadinessReport): ReadinessPanel;
+export interface RecommendationItem {
+    ruleId: string;
+    severity: 'error' | 'warning' | 'info';
+    elementId?: string;
+    message: string;
+    fixHint?: string;
+    /** The single top-ranked candidate to link (CR-GC-203 items 1+3), if any. */
+    topCandidate?: {
+        id: string;
+        type: string;
+        name: string;
+    };
+}
+export interface RecommendationsPanel {
+    items: RecommendationItem[];
+    total: number;
+}
+export declare function recommendationsPanel(violations: RuleViolation[], limit?: number): RecommendationsPanel;
+export type Freshness = 'live' | 'stale' | 'absent';
+/**
+ * Two artifact kinds with TWO distinct staleness mechanisms (CR-GC-222):
+ * - `render`   — a deterministic `docs/views/*.md` projection; stale via file mtime vs graph.
+ * - `analysis` — judgment work (FMEA/ConOps/Trade/…); stale when the analyzed SCOPE moved,
+ *                NEVER via mtime. The single `staleVsGraph` boolean was the defect (it applied
+ *                an mtime check to analyses that don't refresh on mtime).
+ */
+export type ArtifactKind = 'render' | 'analysis';
+/** INCOSE/SE-standard vs graphcode-specific — so non-INCOSE rows are not mislabeled as INCOSE. */
+export type ArtifactGroup = 'incose' | 'graphcode';
+/** Catalog entry: the SSOT for an artifact's kind/group/label (labels are NAMES, never `id==label`). */
+export interface ArtifactCatalogEntry {
+    id: string;
+    label: string;
+    kind: ArtifactKind;
+    group: ArtifactGroup;
+}
+/**
+ * The canonical INCOSE-tab artifact catalog (readiness-artifact-model.md §6). Renders are the
+ * deterministic CR-GC-220 views; the 5 analysis ids are exactly CR-GC-221's creation keys
+ * (`conops`/`assumption-review`/`fmea`/`trade`/`implplan`). `irr` is renamed to "Assumption
+ * Review" and grouped graphcode-specific (it is not a standard INCOSE artifact).
+ */
+export declare const ARTIFACT_CATALOG: readonly ArtifactCatalogEntry[];
+/** Classify a RENDER artifact. `exists` = doc present; `staleVsGraph` = graph changed since render. */
+export declare function artifactFreshness(exists: boolean, staleVsGraph: boolean): Freshness;
+/** Classify an ANALYSIS artifact from its scope-currency — 🟢 current / 🟡 stale / 🔴 absent. */
+export declare function analysisFreshness(currency: CreationCurrency): Freshness;
+export interface ArtifactStatus {
+    id: string;
+    label: string;
+    kind: ArtifactKind;
+    group: ArtifactGroup;
+    freshness: Freshness;
+}
+/** One artifact's freshness signal: render rows carry exists/staleVsGraph, analysis rows carry currency. */
+export interface ArtifactSignal {
+    id: string;
+    /** RENDER: a materialized doc is present. */
+    exists?: boolean;
+    /** RENDER: the graph changed since the doc was generated (mtime). */
+    staleVsGraph?: boolean;
+    /** ANALYSIS: scope-currency of the judgment work (the ONLY signal read for analysis rows). */
+    currency?: CreationCurrency;
+}
+export interface ArtifactsPanel {
+    artifacts: ArtifactStatus[];
+    liveCount: number;
+    staleCount: number;
+    absentCount: number;
+}
+/**
+ * Shape artifact freshness signals into the tab view-model. The catalog decides each row's
+ * kind/group/label; the kind decides WHICH mechanism classifies it — render rows go through
+ * the mtime path, analysis rows through the scope-currency path (so a creation is NEVER
+ * classified by mtime, even if a caller passes `staleVsGraph` — it is ignored). Renderer groups
+ * by `group` to show "INCOSE / SE-standard" and "graphcode-specific" separately.
+ */
+export declare function artifactsPanel(signals: ArtifactSignal[]): ArtifactsPanel;
+/**
+ * Build the CreationCurrencyProvider that CR-GC-221's readiness scorer consumes (CR-GC-222
+ * delivers the `analysis`-currency to 221). Maps each creation id → its scope-currency; an
+ * unknown/never-analyzed creation reads as 🔴 absent.
+ */
+export declare function creationCurrencyProvider(analysis: Array<{
+    id: string;
+    currency: CreationCurrency;
+}>): CreationCurrencyProvider;
+export interface ImpactPanel {
+    root: string;
+    blastRadiusNodes: number;
+    blastRadiusEdges: number;
+}
+export declare function impactPanel(impact: {
+    rootId: string;
+    nodeCount: number;
+    edgeCount: number;
+}): ImpactPanel;
+export interface HealthPanel {
+    ok: boolean;
+    store: string;
+    gate: string;
+    versions: Record<string, unknown>;
+}
+export declare function healthPanel(health: {
+    status?: string;
+    store?: string;
+    gate?: string;
+    versions?: Record<string, unknown>;
+}): HealthPanel;
+/** Which panel ids a viewer should refresh for this invalidation event. */
+export declare function panelsForEvent(event: LiveUpdateEvent): string[];

package/dist/panels.js

@@ -0,0 +1,121 @@
+function toGatePanel(g) {
+    return { id: g.id, label: g.label, passed: g.passed, score: g.score, blocking: g.blocking, completeness: g.completeness };
+}
+export function readinessPanel(report) {
+    return {
+        compliancePct: Math.round(report.compliance.score * 1000) / 10,
+        totalElements: report.compliance.totalElements,
+        elementsWithErrors: report.compliance.elementsWithErrors,
+        phaseGates: report.phaseGates.map(toGatePanel),
+        implGates: report.implGates.map(toGatePanel),
+    };
+}
+const SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
+export function recommendationsPanel(violations, limit = 5) {
+    const ranked = [...violations].sort((a, b) => (SEVERITY_RANK[a.severity] ?? 9) - (SEVERITY_RANK[b.severity] ?? 9));
+    const items = ranked.slice(0, limit).map((v) => {
+        const ctx = v.context;
+        return {
+            ruleId: v.ruleId,
+            severity: v.severity,
+            elementId: v.elementId,
+            message: v.message,
+            fixHint: v.fixHint,
+            topCandidate: ctx?.candidate_targets?.[0],
+        };
+    });
+    return { items, total: violations.length };
+}
+/**
+ * The canonical INCOSE-tab artifact catalog (readiness-artifact-model.md §6). Renders are the
+ * deterministic CR-GC-220 views; the 5 analysis ids are exactly CR-GC-221's creation keys
+ * (`conops`/`assumption-review`/`fmea`/`trade`/`implplan`). `irr` is renamed to "Assumption
+ * Review" and grouped graphcode-specific (it is not a standard INCOSE artifact).
+ */
+export const ARTIFACT_CATALOG = [
+    // Renders — INCOSE/SE-standard deterministic views (mtime-classified).
+    { id: 'srs', label: 'Requirements Spec (SRS)', kind: 'render', group: 'incose' },
+    { id: 'architecture', label: 'Architecture (SDD)', kind: 'render', group: 'incose' },
+    { id: 'rtm', label: 'Req-Test Traceability Matrix', kind: 'render', group: 'incose' },
+    { id: 'nfr', label: 'NFR Register', kind: 'render', group: 'incose' },
+    { id: 'icd', label: 'Interface Control Document', kind: 'render', group: 'incose' },
+    { id: 'testconcept', label: 'Test Concept', kind: 'render', group: 'incose' },
+    { id: 'testmatrix', label: 'Test Matrix (VCRM)', kind: 'render', group: 'incose' },
+    { id: 'intplan', label: 'Integration & Test Plan', kind: 'render', group: 'incose' },
+    { id: 'changelog', label: 'Change Log', kind: 'render', group: 'incose' },
+    { id: 'references', label: 'Requirements Traceability', kind: 'render', group: 'incose' },
+    // Creations — judgment work (scope-classified, NEVER mtime).
+    { id: 'conops', label: 'Concept of Operations', kind: 'analysis', group: 'incose' },
+    { id: 'fmea', label: 'FMEA', kind: 'analysis', group: 'incose' },
+    { id: 'trade', label: 'Trade Study', kind: 'analysis', group: 'incose' },
+    { id: 'implplan', label: 'Implementation Plan', kind: 'analysis', group: 'incose' },
+    { id: 'assumption-review', label: 'Assumption Review', kind: 'analysis', group: 'graphcode' },
+];
+/** Classify a RENDER artifact. `exists` = doc present; `staleVsGraph` = graph changed since render. */
+export function artifactFreshness(exists, staleVsGraph) {
+    if (!exists)
+        return 'absent';
+    return staleVsGraph ? 'stale' : 'live';
+}
+/** Classify an ANALYSIS artifact from its scope-currency — 🟢 current / 🟡 stale / 🔴 absent. */
+export function analysisFreshness(currency) {
+    return currency === 'current' ? 'live' : currency === 'stale' ? 'stale' : 'absent';
+}
+/**
+ * Shape artifact freshness signals into the tab view-model. The catalog decides each row's
+ * kind/group/label; the kind decides WHICH mechanism classifies it — render rows go through
+ * the mtime path, analysis rows through the scope-currency path (so a creation is NEVER
+ * classified by mtime, even if a caller passes `staleVsGraph` — it is ignored). Renderer groups
+ * by `group` to show "INCOSE / SE-standard" and "graphcode-specific" separately.
+ */
+export function artifactsPanel(signals) {
+    const byId = new Map(ARTIFACT_CATALOG.map((e) => [e.id, e]));
+    const statuses = signals.map((s) => {
+        const entry = byId.get(s.id);
+        const kind = entry?.kind ?? 'render';
+        const freshness = kind === 'analysis'
+            ? analysisFreshness(s.currency ?? 'absent')
+            : artifactFreshness(s.exists ?? false, s.staleVsGraph ?? false);
+        return { id: s.id, label: entry?.label ?? s.id, kind, group: entry?.group ?? 'graphcode', freshness };
+    });
+    return {
+        artifacts: statuses,
+        liveCount: statuses.filter((s) => s.freshness === 'live').length,
+        staleCount: statuses.filter((s) => s.freshness === 'stale').length,
+        absentCount: statuses.filter((s) => s.freshness === 'absent').length,
+    };
+}
+/**
+ * Build the CreationCurrencyProvider that CR-GC-221's readiness scorer consumes (CR-GC-222
+ * delivers the `analysis`-currency to 221). Maps each creation id → its scope-currency; an
+ * unknown/never-analyzed creation reads as 🔴 absent.
+ */
+export function creationCurrencyProvider(analysis) {
+    const m = new Map(analysis.map((a) => [a.id, a.currency]));
+    return (creation) => m.get(creation) ?? 'absent';
+}
+export function impactPanel(impact) {
+    return { root: impact.rootId, blastRadiusNodes: impact.nodeCount, blastRadiusEdges: impact.edgeCount };
+}
+export function healthPanel(health) {
+    return {
+        ok: health.status === 'ok',
+        store: health.store ?? 'unknown',
+        gate: health.gate ?? 'unknown',
+        versions: health.versions ?? {},
+    };
+}
+// ---------------------------------------------------------------------------
+// FUNC-subscribe-updates — map a live-update event (CR-GC-114 SSE) to the panel
+// ids that must refresh. The viewer subscribes once and re-fetches only those.
+// ---------------------------------------------------------------------------
+const DOMAIN_TO_PANELS = {
+    graph: ['graph', 'impact', 'artifacts'],
+    rules: ['recommendations', 'readiness'],
+    readiness: ['readiness', 'implGates', 'artifacts'],
+    suggestions: ['recommendations'],
+};
+/** Which panel ids a viewer should refresh for this invalidation event. */
+export function panelsForEvent(event) {
+    return [...new Set(event.domains.flatMap((d) => DOMAIN_TO_PANELS[d] ?? []))];
+}

package/dist/readiness-completeness.d.ts

@@ -0,0 +1,64 @@
+/**
+ * readiness-completeness.ts — the COMPLETENESS dimension of readiness (CR-GC-250,
+ * split out of readiness.ts by CR-GC-260).
+ *
+ * Its own module because it answers a different question than the rest of readiness:
+ * compliance/gates ask "does any element violate a rule", completeness asks "is the
+ * structural chain covered at all" — the absence case rules cannot see (0 FCHAIN → a
+ * per-element warning rule fires 0 times and the gate reads green).
+ *
+ * BROWSER-SAFE — no `node:*` import may enter this file: the panels layer builds on it.
+ *
+ * @author andreas@siglochconsulting
+ */
+import type { Graph } from '@sigloch/graph-api-core';
+export type CGraph = Pick<Graph, 'nodes' | 'edges'>;
+export type CNode = Graph['nodes'][number];
+/** A gate's structural completeness over its driving population. */
+export interface GateCompleteness {
+    /** Source elements whose chain leg is complete. */
+    covered: number;
+    /** Total source elements evaluated across the gate's legs (the denominator). */
+    total: number;
+    /** Per-leg misses as `"<leg>: <uid>"` — the on-click drill-down detail. */
+    missing: string[];
+}
+/** Neutral completeness for gates that carry no chain slice (impl gates). */
+export declare const NEUTRAL_COMPLETENESS: GateCompleteness;
+/**
+ * One completeness leg: every node of `sourceType` (the driving population)
+ * must satisfy `holds`, else it is a `missing` source for the owning gate.
+ * Cardinality legs use the id `"<SRC>→<TGT>"` so the drift test can match them
+ * against the meta-model's `1..*` patterns.
+ */
+export interface CompletenessLeg {
+    id: string;
+    sourceType: string;
+    holds: (node: CNode, graph: CGraph, byId: Map<string, CNode>) => boolean;
+}
+export declare const typeOf: (byId: Map<string, CNode>, id: string) => string | undefined;
+/** True iff `src` has ≥1 out-edge of `edgeType` to a node of `targetType`. */
+export declare function hasOutTo(g: CGraph, byId: Map<string, CNode>, src: string, edgeType: string, targetType: string): boolean;
+export declare const refFile: (ref: unknown) => string | undefined;
+export declare const hasTestRef: (n: CNode) => boolean;
+export declare const hasCodeRef: (n: CNode) => boolean;
+/** A leaf FUNC has no `compose→FUNC` children (parents are realized by children — meta-model §28). */
+export declare const isLeafFunc: (n: CNode, g: CGraph, byId: Map<string, CNode>) => boolean;
+/**
+ * A FCHAIN is actor-bounded iff its function set has a trigger AND a consumer:
+ * `ACTOR —io→ FLOW —io→ FUNC∈chain` (entry) and `FUNC∈chain —io→ FLOW —io→ ACTOR`
+ * (exit). Catches the "hollow chain" — functions with no who-triggers / who-consumes.
+ */
+export declare function fchainActorBounded(fchain: CNode, g: CGraph, byId: Map<string, CNode>): boolean;
+/**
+ * Phase-gate → chain legs that must be complete AT THAT PHASE. `concept:true`
+ * stays valid through CDR (spec allows unbound tests/funcs); only TRR demands
+ * real bindings. The `1..*` cardinality legs (SYS→UC, UC→FCHAIN, UC→REQ,
+ * FCHAIN→FUNC) are drift-locked against the meta-model by TEST-readiness-completeness.
+ */
+export declare const COMPLETENESS_SLICES: Record<string, CompletenessLeg[]>;
+/**
+ * Score one phase gate's structural completeness over its driving population.
+ * `total === 0` (no source elements to cover) → vacuously complete (ratio 1).
+ */
+export declare function scoreCompleteness(gateId: string, graph: CGraph): GateCompleteness;

package/dist/readiness-completeness.js

@@ -0,0 +1,79 @@
+/** Neutral completeness for gates that carry no chain slice (impl gates). */
+export const NEUTRAL_COMPLETENESS = { covered: 0, total: 0, missing: [] };
+export const typeOf = (byId, id) => byId.get(id)?.type;
+/** True iff `src` has ≥1 out-edge of `edgeType` to a node of `targetType`. */
+export function hasOutTo(g, byId, src, edgeType, targetType) {
+    return g.edges.some((e) => e.sourceId === src && e.edgeType === edgeType && typeOf(byId, e.targetId) === targetType);
+}
+export const refFile = (ref) => ref?.file;
+export const hasTestRef = (n) => !!refFile(n.attributes?.testRef);
+export const hasCodeRef = (n) => !!refFile(n.attributes?.realRef);
+/** A leaf FUNC has no `compose→FUNC` children (parents are realized by children — meta-model §28). */
+export const isLeafFunc = (n, g, byId) => !hasOutTo(g, byId, n.uid, 'compose', 'FUNC');
+/**
+ * A FCHAIN is actor-bounded iff its function set has a trigger AND a consumer:
+ * `ACTOR —io→ FLOW —io→ FUNC∈chain` (entry) and `FUNC∈chain —io→ FLOW —io→ ACTOR`
+ * (exit). Catches the "hollow chain" — functions with no who-triggers / who-consumes.
+ */
+export function fchainActorBounded(fchain, g, byId) {
+    const funcs = new Set(g.edges.filter((e) => e.sourceId === fchain.uid && e.edgeType === 'compose' && typeOf(byId, e.targetId) === 'FUNC').map((e) => e.targetId));
+    if (funcs.size === 0)
+        return false;
+    const io = g.edges.filter((e) => e.edgeType === 'io');
+    const entry = io.some((e) => funcs.has(e.targetId) && typeOf(byId, e.sourceId) === 'FLOW' &&
+        io.some((a) => a.targetId === e.sourceId && typeOf(byId, a.sourceId) === 'ACTOR'));
+    const exit = io.some((e) => funcs.has(e.sourceId) && typeOf(byId, e.targetId) === 'FLOW' &&
+        io.some((a) => a.sourceId === e.targetId && typeOf(byId, a.targetId) === 'ACTOR'));
+    return entry && exit;
+}
+/**
+ * Phase-gate → chain legs that must be complete AT THAT PHASE. `concept:true`
+ * stays valid through CDR (spec allows unbound tests/funcs); only TRR demands
+ * real bindings. The `1..*` cardinality legs (SYS→UC, UC→FCHAIN, UC→REQ,
+ * FCHAIN→FUNC) are drift-locked against the meta-model by TEST-readiness-completeness.
+ */
+export const COMPLETENESS_SLICES = {
+    // Behavioral spine exists: system has use cases, every UC derives a chain AND requirements.
+    SRR: [
+        { id: 'SYS→UC', sourceType: 'SYS', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'UC') },
+        { id: 'UC→FCHAIN', sourceType: 'UC', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'FCHAIN') },
+        { id: 'UC→REQ', sourceType: 'UC', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'REQ') },
+    ],
+    // Functional architecture: every chain has functions AND is actor-bounded (trigger + consumer).
+    PDR: [
+        { id: 'FCHAIN→FUNC', sourceType: 'FCHAIN', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'compose', 'FUNC') },
+        { id: 'FCHAIN-actor-bounded', sourceType: 'FCHAIN', holds: (n, g, b) => fchainActorBounded(n, g, b) },
+    ],
+    // Interfaces carry a data contract: every FLOW has a SCHEMA (CR-GC-106 schema-before-code).
+    CDR: [
+        { id: 'FLOW→SCHEMA', sourceType: 'FLOW', holds: (n, g, b) => hasOutTo(g, b, n.uid, 'relation', 'SCHEMA') },
+    ],
+    // Binding: tests are runnable and leaf functions carry code — concept no longer counts here.
+    TRR: [
+        { id: 'TEST.testRef', sourceType: 'TEST', holds: (n) => hasTestRef(n) },
+        { id: 'FUNC.realRef', sourceType: 'FUNC', holds: (n, g, b) => !isLeafFunc(n, g, b) || hasCodeRef(n) },
+    ],
+};
+/**
+ * Score one phase gate's structural completeness over its driving population.
+ * `total === 0` (no source elements to cover) → vacuously complete (ratio 1).
+ */
+export function scoreCompleteness(gateId, graph) {
+    const legs = COMPLETENESS_SLICES[gateId] ?? [];
+    const byId = new Map(graph.nodes.map((n) => [n.uid, n]));
+    let covered = 0;
+    let total = 0;
+    const missing = [];
+    for (const leg of legs) {
+        for (const node of graph.nodes) {
+            if (node.type !== leg.sourceType)
+                continue;
+            total += 1;
+            if (leg.holds(node, graph, byId))
+                covered += 1;
+            else
+                missing.push(`${leg.id}: ${node.uid}`);
+        }
+    }
+    return { covered, total, missing };
+}

package/dist/readiness.d.ts

@@ -0,0 +1,218 @@
+/**
+ * ReadinessScorer — CR-GC-107 (compliance) + CR-GC-125 (readiness model).
+ *
+ * Computes readiness for a graphcode graph purely from `@sigloch/contracts`
+ * V3_RULES violations (via `harness.evaluateRules()`, the L2 gate — see
+ * FCHAIN-apply-gate) PLUS the MS milestone nodes and element status. This is
+ * the in-repo deliverable that proves readiness is measured against the FAMILY
+ * rule base, NOT the aimprove predecessor rules (BQ-2.0.0 / INCOSE-style
+ * BQ-06/BQ-02). The foreign BQ path is explicitly NOT used; it is removed from
+ * family readiness scoring.
+ *
+ * REQ-readiness-model (CR-GC-125) — the model, defined here AND in the graph:
+ *
+ *   INCOSE-Artifact-Scope = LEAN, refined (CR-GC-226, supersedes the CR-GC-125
+ *   `lean = no artifacts` stance). graphcode is a headless QM-level governance
+ *   harness, not an ASIL-rated system. The graph is the SSOT and every RENDER
+ *   (SRS/SDD/RTM/ICD/…) is a DETERMINISTIC PROJECTION of it (CR-GC-220) — not a
+ *   separate hand-authored deliverable. CREATION artifacts (ConOps, FMEA,
+ *   Assumption Review, Trade, Impl Plan) ARE in scope as lightweight judgment
+ *   inputs and gate preconditions — tracked in the artifact tab (CR-GC-222) and
+ *   required by the gates (CR-GC-221). Only ASIL-D-grade evidence (full FMEA
+ *   S/O/D rigor, ASIL isolation proof) stays out of scope — graphcode carries no
+ *   `asil`-rated elements. Refined model: docs/proposals/readiness-artifact-model.md §3.
+ *
+ *   Phase-Readiness — 4 INCOSE technical-review gates (SRR/PDR/CDR/TRR), each a
+ *   DISJOINT + EXHAUSTIVE partition of the element-level V3_RULES. A gate is
+ *   `passed` iff none of its rules fire an error-severity violation; warnings/
+ *   info are advisory (`open`). The four gates collectively == element
+ *   compliance, so nothing is measured outside V3_RULES.
+ *
+ *   Implementation-Readiness — 4 program/build acceptance gates
+ *   (SAR/FCA/SVR/FRR), each bound to a milestone tier (MS-1..MS-4). A gate is
+ *   `ready` iff every CR assigned to its milestone (CR -relation-> MS) is
+ *   status=done AND the milestone scope (MS -compose-> X) carries no
+ *   error-severity violation. Derived from the MS nodes + element status, i.e.
+ *   the MS-01/MS-02 milestone-rule concerns — the remaining 2 of the 17 rules.
+ *
+ * Host/dashboard wiring (panels) lives in MOD-dashboard (CR-GC-115); this module
+ * provides the scoring primitive only — no dashboard, no renderer.
+ *
+ * @author andreas@siglochconsulting
+ */
+import type { Graph } from '@sigloch/graph-api-core';
+import type { RuleViolation } from '@sigloch/contracts/harness';
+import { type GateCompleteness } from './readiness-completeness.js';
+/**
+ * A readiness dimension score in [0, 1].
+ * 0 = fully non-compliant, 1 = fully compliant.
+ */
+export interface ReadinessDimension {
+    /** Score in [0, 1]. */
+    score: number;
+    /** Short human-readable label for display. */
+    label: string;
+    /** How many elements were evaluated. */
+    totalElements: number;
+    /** How many elements carry at least one error-severity violation. */
+    elementsWithErrors: number;
+}
+/**
+ * INCOSE artifact scope for the system under governance.
+ * `lean`  — graph = SSOT; renders are deterministic projections, creations are
+ *           lightweight judgment inputs + gate preconditions (graphcode's stance,
+ *           refined CR-GC-226). NOT "no artifacts".
+ * `full`  — ASIL-D-grade evidence (full FMEA S/O/D rigor, ASIL isolation) (not graphcode).
+ */
+export type IncoseScope = 'lean' | 'full';
+/** graphcode's declared scope — see the module header for the rationale. */
+export declare const GRAPHCODE_INCOSE_SCOPE: IncoseScope;
+/**
+ * Phase-Readiness gates (INCOSE technical reviews) → the element-level V3_RULES
+ * each gate owns. DISJOINT + EXHAUSTIVE over the 15 element rules; verified by
+ * TEST-readiness-model against SE_DESCRIPTOR at runtime (never hardcoded count).
+ */
+export declare const PHASE_GATE_RULES: Record<string, readonly string[]>;
+/** Human labels for the phase gates. */
+export declare const PHASE_GATE_LABELS: Record<string, string>;
+/**
+ * Creation artifacts each phase gate requires (CR-GC-221): the judgment work
+ * ("rule-green ≠ analysis-done") a rule-clean structure cannot prove was ever
+ * done. A gate is only `passed` if its required creations are 🟢-current.
+ * TRR carries none (tests are inline in the graph, not a separate creation).
+ */
+export declare const PHASE_GATE_CREATIONS: Record<string, readonly string[]>;
+/** Impl gate → the phase whose creations it inherits as an anti-vacuous-green precondition. */
+export declare const IMPL_GATE_PHASE: Record<string, string>;
+/** Currency of a creation artifact: 🟢 current / 🟡 stale / 🔴 absent. */
+export type CreationCurrency = 'current' | 'stale' | 'absent';
+/**
+ * Resolves whether a creation artifact is current/stale/absent (CR-GC-221 = the
+ * INTERFACE; CR-GC-222's classifier supplies the real implementation). When no
+ * provider is passed to `computeReadiness`, creation enforcement is OFF
+ * (back-compat) — the gates still report their `creationArtifacts`, but currency
+ * is not checked until 222 wires a provider in.
+ */
+export type CreationCurrencyProvider = (creation: string) => CreationCurrency;
+/** Default stub provider (CR-GC-221, "Default 🔴"): everything absent until CR-GC-222 lands. */
+export declare const ABSENT_CREATION_PROVIDER: CreationCurrencyProvider;
+/** Format a "<Creation> not performed (<gate> creation)" blocking message.
+ *  Exported so the help layer (CR-GC-228) can identify creation blockers in
+ *  `ReadinessGate.blocking[]` without re-deriving the format (single source). */
+export declare function creationBlockingMsg(creation: string, gateId: string): string;
+/**
+ * Implementation-Readiness gates (program/build acceptance) → milestone tier.
+ * Ready iff every CR assigned to the MS is done + the MS scope is error-clean.
+ */
+export declare const IMPL_GATE_MILESTONES: Record<string, {
+    ms: string;
+    label: string;
+}>;
+/**
+ * The 2 milestone-level V3_RULES the impl gates embody (MS-01 empty scope,
+ * MS-02 dangling dependency). Together with the phase-gate rules these span
+ * V3_RULES exhaustively — so the model covers it with nothing left over.
+ */
+export declare const IMPL_GATE_RULES: readonly string[];
+/**
+ * A single readiness gate outcome.
+ * `passed` is the hard verdict (no blocking/error item); `score` ∈ [0,1] is a
+ * continuous maturity indicator; `open` items are advisory (warnings/CR debt).
+ */
+export interface ReadinessGate {
+    /** Gate id — SRR/PDR/CDR/TRR (phase) or SAR/FCA/SVR/FRR (impl). */
+    id: string;
+    /** Human-readable review name. */
+    label: string;
+    /** True iff no blocking (error-severity / not-done) item remains. */
+    passed: boolean;
+    /** Continuous maturity in [0, 1]. */
+    score: number;
+    /** Blocking items that hold the gate closed (errors / open CRs / scope errors). */
+    blocking: string[];
+    /** Advisory items surfaced but not blocking (warnings, info, scope notes). */
+    open: string[];
+    /** Creation artifacts this gate requires (CR-GC-221) — judgment work, not rules. */
+    creationArtifacts: string[];
+    /**
+     * Structural completeness of the derivation chain owned by this gate
+     * (CR-GC-250) — orthogonal to violation severity. `covered/total` over the
+     * DRIVING population, so absence counts (0 FCHAIN → all UCs incomplete → SRR
+     * red). One value per gate for the dashboard; `missing[]` is the on-click
+     * per-leg detail. A gate cannot pass while `covered < total`. Impl gates carry
+     * a neutral `{0,0,[]}` (completeness is a phase-gate concept).
+     */
+    completeness: GateCompleteness;
+}
+/**
+ * Full readiness snapshot derived from V3_RULES evaluation + MS + status.
+ * All violation ruleIds are contracts rule-IDs (R-xx / RD-xx / MS-xx) — never BQ-*.
+ */
+export interface ReadinessReport {
+    /**
+     * Compliance dimension: fraction of graph elements with NO error-severity
+     * violation. 1.0 = all elements clean, 0.0 = all elements have ≥1 error.
+     */
+    compliance: ReadinessDimension;
+    /** Declared INCOSE artifact scope for this system (graphcode = `lean`). */
+    incoseScope: IncoseScope;
+    /** Phase-Readiness gates (INCOSE technical reviews) in lifecycle order. */
+    phaseGates: ReadinessGate[];
+    /** Implementation-Readiness gates (program/build acceptance) in tier order. */
+    implGates: ReadinessGate[];
+    /**
+     * Per-contracts-rule-ID violation counts. Keys are exactly the
+     * `SE_DESCRIPTOR.rules` members that fired. Foreign BQ-* IDs cannot appear —
+     * the scorer delegates exclusively to the V3 rule engine.
+     */
+    violationsByRule: Record<string, number>;
+    /** All raw violations, ordered by severity (error → warning → info). */
+    violations: RuleViolation[];
+    /**
+     * Whether creation-artifact currency was ENFORCED in this report (CR-GC-259).
+     * `off` means no `CreationCurrencyProvider` was supplied, so every gate's
+     * `creationArtifacts` was REPORTED but never checked — a gate can read
+     * `passed` with a never-performed FMEA/ConOps behind it. Made explicit because
+     * a silently-unenforced gate is the same false-green class CR-GC-250 closed:
+     * a consumer cannot distinguish "no creation blockers" from "not checked".
+     * graphcode itself has no classifier yet (the real provider is fed by the
+     * dashboard), so the product path reports `off` until one lands.
+     */
+    creationEnforcement: 'on' | 'off';
+    /** Timestamp (ISO 8601) when this report was computed. */
+    computedAt: string;
+}
+/**
+ * Summary projection of a ReadinessReport (CR-GC-203 item 2): drops the heavy
+ * per-element lists — `violations` and every gate's `blocking`/`open` — while
+ * keeping scores, counts and `violationsByRule`. `graph_readiness` returns this
+ * by default; `detail:true` returns the full lists. On a fully-red graph the
+ * full report inlined every blocking element (86k+ chars, past the MCP tool
+ * result limit) forcing a file-spill; the summary stays small.
+ */
+export declare function summarizeReadiness(report: ReadinessReport): ReadinessReport;
+/**
+ * Compute readiness from a violations array + the full graph (nodes + edges).
+ *
+ * @param violations - from `harness.evaluateRules()` (contracts V3 rule IDs)
+ * @param graph      - from `harness.getGraph()` (elements + traces)
+ */
+export declare function computeReadiness(violations: RuleViolation[], graph: Pick<Graph, 'nodes' | 'edges'>, creationCurrency?: CreationCurrencyProvider): ReadinessReport;
+/**
+ * Convenience wrapper: runs `evaluateRules()` + `getGraph()` on the harness
+ * and returns the full ReadinessReport.
+ *
+ * Accepts a minimal harness-duck-type so callers can pass `GraphCodeHarness`
+ * directly without importing its class (avoids circular dep risk in consumers).
+ */
+export declare function scoreReadiness(harness: {
+    evaluateRules(): RuleViolation[];
+    getGraph(): Pick<Graph, 'nodes' | 'edges'>;
+}): ReadinessReport;
+/**
+ * The authoritative set of family rule-IDs (derived at runtime from
+ * SE_DESCRIPTOR — the graph rules — plus the contracts RC conformance rules
+ * (CR-GC-253); never hardcoded here). Exposed for test assertions and
+ * dashboard consumers.
+ */
+export declare function getFamilyRuleIds(): Set<string>;

package/dist/readiness.js

@@ -0,0 +1,269 @@
+import { SE_DESCRIPTOR } from '@sigloch/graph-api-core';
+import { CODE_CONFORMANCE_RULES } from '@sigloch/contracts/se';
+import { scoreCompleteness, NEUTRAL_COMPLETENESS, } from './readiness-completeness.js';
+/** graphcode's declared scope — see the module header for the rationale. */
+export const GRAPHCODE_INCOSE_SCOPE = 'lean';
+/**
+ * Phase-Readiness gates (INCOSE technical reviews) → the element-level V3_RULES
+ * each gate owns. DISJOINT + EXHAUSTIVE over the 15 element rules; verified by
+ * TEST-readiness-model against SE_DESCRIPTOR at runtime (never hardcoded count).
+ */
+export const PHASE_GATE_RULES = {
+    // System + use-case structure exists; every requirement is verifiable.
+    SRR: ['R-17', 'R-14', 'R-01'],
+    // Functional architecture: chains, actors, flows; functions trace to REQs.
+    PDR: ['R-15', 'R-16', 'R-10', 'R-02'],
+    // Detailed design: ASIL isolation, module size, no cycles, sound decomposition,
+    // valid trace patterns (R-18: every trace's element-type pair is legal — now also
+    // flags any residual REQ→MOD allocate edge, CR-228), module allocation (R-22
+    // FUNC→MOD, R-23 MOD→FUNC — CR-202/208), and FUNC→code binding — presence (R-20: every non-concept
+    // FUNC carries a realRef, CR-GC-205 Item 5) AND resolution (RC-01: the realRef
+    // points at a declared symbol on disk — CR-GC-253 conformance, with CodeFacts).
+    // SCHEMA realRef binding (R-26 presence, RC-03 resolution, RC-04 parsed-at-interface —
+    // CR-211) and physical-MOD realRef presence (R-27, CR-228) join the realRef family
+    // (R-20/RC-01) here: interfaces + parts are detailed design.
+    // RC-05 (cross-module import drift — CR-212) is module-coupling: also detailed design.
+    CDR: ['R-03', 'R-04', 'R-12', 'R-18', 'R-20', 'R-22', 'R-23', 'R-26', 'R-27', 'RC-01', 'RC-03', 'RC-04', 'RC-05', 'RD-01', 'RD-02', 'RD-03'],
+    // Verification wired (TEST→REQ) + referential trace consistency + runnable test
+    // bindings — presence (R-19) AND resolution (RC-02: file + case exist, CR-GC-253).
+    TRR: ['R-05', 'R-08', 'R-19', 'R-21', 'RC-02'],
+};
+/** Human labels for the phase gates. */
+export const PHASE_GATE_LABELS = {
+    SRR: 'System Requirements Review',
+    PDR: 'Preliminary Design Review',
+    CDR: 'Critical Design Review',
+    TRR: 'Test Readiness Review',
+};
+/**
+ * Creation artifacts each phase gate requires (CR-GC-221): the judgment work
+ * ("rule-green ≠ analysis-done") a rule-clean structure cannot prove was ever
+ * done. A gate is only `passed` if its required creations are 🟢-current.
+ * TRR carries none (tests are inline in the graph, not a separate creation).
+ */
+export const PHASE_GATE_CREATIONS = {
+    SRR: ['conops', 'assumption-review'],
+    PDR: ['fmea', 'trade'],
+    CDR: ['implplan'],
+    TRR: [],
+};
+/** Human labels for creation artifacts (used in blocking messages). */
+const CREATION_LABELS = {
+    conops: 'ConOps',
+    'assumption-review': 'Assumption Review',
+    fmea: 'FMEA',
+    trade: 'Trade study',
+    implplan: 'Impl plan',
+};
+/** Impl gate → the phase whose creations it inherits as an anti-vacuous-green precondition. */
+export const IMPL_GATE_PHASE = {
+    SAR: 'SRR',
+    FCA: 'PDR',
+    SVR: 'CDR',
+    FRR: 'TRR',
+};
+/** Default stub provider (CR-GC-221, "Default 🔴"): everything absent until CR-GC-222 lands. */
+export const ABSENT_CREATION_PROVIDER = () => 'absent';
+/** Format a "<Creation> not performed (<gate> creation)" blocking message.
+ *  Exported so the help layer (CR-GC-228) can identify creation blockers in
+ *  `ReadinessGate.blocking[]` without re-deriving the format (single source). */
+export function creationBlockingMsg(creation, gateId) {
+    return `${CREATION_LABELS[creation] ?? creation} not performed (${gateId} creation)`;
+}
+/**
+ * Implementation-Readiness gates (program/build acceptance) → milestone tier.
+ * Ready iff every CR assigned to the MS is done + the MS scope is error-clean.
+ */
+export const IMPL_GATE_MILESTONES = {
+    SAR: { ms: 'MS-1-specification', label: 'System Acceptance Review' },
+    FCA: { ms: 'MS-2-coding-vv', label: 'Functional Configuration Audit' },
+    SVR: { ms: 'MS-3-mvp-readiness', label: 'System Verification Review' },
+    FRR: { ms: 'MS-4-mvp2', label: 'Functional Readiness Review' },
+};
+/**
+ * The 2 milestone-level V3_RULES the impl gates embody (MS-01 empty scope,
+ * MS-02 dangling dependency). Together with the phase-gate rules these span
+ * V3_RULES exhaustively — so the model covers it with nothing left over.
+ */
+export const IMPL_GATE_RULES = ['MS-01', 'MS-02'];
+/**
+ * Summary projection of a ReadinessReport (CR-GC-203 item 2): drops the heavy
+ * per-element lists — `violations` and every gate's `blocking`/`open` — while
+ * keeping scores, counts and `violationsByRule`. `graph_readiness` returns this
+ * by default; `detail:true` returns the full lists. On a fully-red graph the
+ * full report inlined every blocking element (86k+ chars, past the MCP tool
+ * result limit) forcing a file-spill; the summary stays small.
+ */
+export function summarizeReadiness(report) {
+    const stripGate = (g) => ({
+        ...g,
+        blocking: [],
+        open: [],
+        // Keep the one-value covered/total for the dashboard; drop the per-leg drill-down.
+        completeness: { ...g.completeness, missing: [] },
+    });
+    return {
+        ...report,
+        phaseGates: report.phaseGates.map(stripGate),
+        implGates: report.implGates.map(stripGate),
+        violations: [],
+    };
+}
+// ---------------------------------------------------------------------------
+// Scorer
+// ---------------------------------------------------------------------------
+/** Group violations by element-id for per-element error lookups. */
+function elementsWithErrorSet(violations) {
+    return new Set(violations
+        .filter((v) => v.severity === 'error' && v.elementId !== undefined)
+        .map((v) => v.elementId));
+}
+/**
+ * Score one phase gate from the violations whose ruleId it owns, plus its
+ * required creation artifacts (CR-GC-221): a gate is only `passed` if it is
+ * rule-clean AND every required creation is 🟢-current. When `currency` is
+ * undefined, creation enforcement is OFF (back-compat) — `creationArtifacts`
+ * is still reported. Creations affect `passed`/`blocking`, not the rule `score`.
+ */
+function scorePhaseGate(id, ruleIds, violations, creations, graph, currency) {
+    const owned = violations.filter((v) => ruleIds.includes(v.ruleId));
+    const errors = owned.filter((v) => v.severity === 'error');
+    const rulesWithError = new Set(errors.map((v) => v.ruleId));
+    const ruleBlocking = errors.map((v) => `${v.ruleId}: ${v.message}`);
+    const open = owned.filter((v) => v.severity !== 'error').map((v) => `${v.ruleId}: ${v.message}`);
+    // Phase gate requires every creation 🟢-current — stale OR absent blocks.
+    const creationBlocking = currency
+        ? creations.filter((c) => currency(c) !== 'current').map((c) => creationBlockingMsg(c, id))
+        : [];
+    // Structural completeness (CR-GC-250): one aggregated blocking line, not N warnings.
+    const completeness = scoreCompleteness(id, graph);
+    const complete = completeness.covered === completeness.total;
+    const completenessBlocking = complete
+        ? []
+        : [`${id} completeness ${completeness.covered}/${completeness.total} — ${completeness.missing.join('; ')}`];
+    const blocking = [...ruleBlocking, ...creationBlocking, ...completenessBlocking];
+    // Maturity = share of the gate's hard checks with no error, floored by completeness coverage:
+    // a gate cannot read green while a mandated chain leg is empty.
+    const ruleScore = ruleIds.length > 0 ? (ruleIds.length - rulesWithError.size) / ruleIds.length : 1;
+    const completenessRatio = completeness.total > 0 ? completeness.covered / completeness.total : 1;
+    return {
+        id,
+        label: PHASE_GATE_LABELS[id] ?? id,
+        passed: rulesWithError.size === 0 && creationBlocking.length === 0 && complete,
+        score: Math.min(ruleScore, completenessRatio),
+        blocking,
+        open,
+        creationArtifacts: [...creations],
+        completeness,
+    };
+}
+/**
+ * Score one implementation gate from its milestone's CRs + scope (MS + status),
+ * plus an anti-vacuous-green creation check (CR-GC-221): the gate additionally
+ * blocks when a creation required by its phase is 🔴 **absent** — even with no
+ * representing CR (a never-done FMEA must not pass silently). Only `absent`
+ * blocks here (not `stale`); enforcement is off when `currency` is undefined.
+ */
+function scoreImplGate(id, ms, label, graph, elementsWithError, creations, currency) {
+    const msNode = graph.nodes.find((n) => n.uid === ms);
+    if (!msNode) {
+        return {
+            id,
+            label,
+            passed: false,
+            score: 0,
+            blocking: [`milestone ${ms} missing`],
+            open: [],
+            creationArtifacts: [...creations],
+            completeness: NEUTRAL_COMPLETENESS,
+        };
+    }
+    const nodeById = new Map(graph.nodes.map((n) => [n.uid, n]));
+    // CRs assigned to this milestone: CR -relation-> MS (the MS-01 scope semantics).
+    const crs = graph.edges
+        .filter((e) => e.edgeType === 'relation' && e.targetId === ms)
+        .map((e) => nodeById.get(e.sourceId))
+        .filter((n) => !!n && n.type === 'CR');
+    const openCrs = crs.filter((c) => c.attributes?.status !== 'done');
+    // Milestone scope: composed elements (MS -compose-> X) must be error-clean.
+    const scopeErrors = graph.edges
+        .filter((e) => e.sourceId === ms && e.edgeType === 'compose')
+        .map((e) => e.targetId)
+        .filter((id2) => elementsWithError.has(id2));
+    // Anti-vacuous-green: a phase creation that is 🔴 absent blocks the impl gate
+    // even when every CR is done and the scope is clean (the analysis was never done).
+    const creationBlocking = currency
+        ? creations.filter((c) => currency(c) === 'absent').map((c) => creationBlockingMsg(c, id))
+        : [];
+    const blocking = [
+        ...openCrs.map((c) => `${c.uid} not done`),
+        ...scopeErrors.map((id2) => `${id2} has an error-severity violation`),
+        ...creationBlocking,
+    ];
+    const msStatus = msNode.attributes?.status;
+    const score = crs.length > 0
+        ? (crs.length - openCrs.length) / crs.length
+        : msStatus === 'done' || msStatus === 'reviewed' ? 1 : 0;
+    return { id, label, passed: blocking.length === 0, score, blocking, open: [], creationArtifacts: [...creations], completeness: NEUTRAL_COMPLETENESS };
+}
+/**
+ * Compute readiness from a violations array + the full graph (nodes + edges).
+ *
+ * @param violations - from `harness.evaluateRules()` (contracts V3 rule IDs)
+ * @param graph      - from `harness.getGraph()` (elements + traces)
+ */
+export function computeReadiness(violations, graph, creationCurrency) {
+    const totalElements = graph.nodes.length;
+    const elementsWithError = elementsWithErrorSet(violations);
+    const elementsWithErrors = elementsWithError.size;
+    const complianceScore = totalElements > 0 ? (totalElements - elementsWithErrors) / totalElements : 1;
+    // Violation counts keyed by contracts rule-ID (never BQ-*).
+    const violationsByRule = {};
+    for (const v of violations) {
+        violationsByRule[v.ruleId] = (violationsByRule[v.ruleId] ?? 0) + 1;
+    }
+    // Sort: error → warning → info.
+    const severityRank = { error: 0, warning: 1, info: 2 };
+    const sorted = [...violations].sort((a, b) => (severityRank[a.severity] ?? 3) - (severityRank[b.severity] ?? 3));
+    const phaseGates = Object.entries(PHASE_GATE_RULES).map(([id, ruleIds]) => scorePhaseGate(id, ruleIds, violations, PHASE_GATE_CREATIONS[id] ?? [], graph, creationCurrency));
+    const implGates = Object.entries(IMPL_GATE_MILESTONES).map(([id, { ms, label }]) => scoreImplGate(id, ms, label, graph, elementsWithError, PHASE_GATE_CREATIONS[IMPL_GATE_PHASE[id]] ?? [], creationCurrency));
+    return {
+        compliance: {
+            score: complianceScore,
+            label: 'Compliance (V3_RULES, error-severity)',
+            totalElements,
+            elementsWithErrors,
+        },
+        incoseScope: GRAPHCODE_INCOSE_SCOPE,
+        phaseGates,
+        implGates,
+        violationsByRule,
+        violations: sorted,
+        creationEnforcement: creationCurrency ? 'on' : 'off',
+        computedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Convenience wrapper: runs `evaluateRules()` + `getGraph()` on the harness
+ * and returns the full ReadinessReport.
+ *
+ * Accepts a minimal harness-duck-type so callers can pass `GraphCodeHarness`
+ * directly without importing its class (avoids circular dep risk in consumers).
+ */
+export function scoreReadiness(harness) {
+    const violations = harness.evaluateRules();
+    const graph = harness.getGraph();
+    return computeReadiness(violations, graph);
+}
+/**
+ * The authoritative set of family rule-IDs (derived at runtime from
+ * SE_DESCRIPTOR — the graph rules — plus the contracts RC conformance rules
+ * (CR-GC-253); never hardcoded here). Exposed for test assertions and
+ * dashboard consumers.
+ */
+export function getFamilyRuleIds() {
+    return new Set([
+        ...(SE_DESCRIPTOR.rules ?? []).map((r) => r.id),
+        ...CODE_CONFORMANCE_RULES.map((r) => r.id),
+    ]);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graphcode-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -16,6 +16,10 @@
     "test": "vitest run",
     "prepublishOnly": "npm run build && npm run test"
   },
+  "dependencies": {
+    "@sigloch/contracts": "^0.8.0",
+    "@sigloch/graph-api-core": "^0.4.1"
+  },
   "license": "MIT",
   "description": "Read-side client for a running @sigloch/graphcode host — host-socket calls, dashboard panels, readiness projection and the markdown view catalog. Deliberately free of Kuzu and the MCP SDK so a viewer can depend on it without pulling an embedded graph database.",
   "author": "sigloch-consulting",