@sigloch/graphcode-client 2.0.0 → 3.0.0

package/dist/index.d.ts

@@ -18,5 +18,5 @@
  */
 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, MARK_LABELS, computeMarks, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, type IncoseScope, type ReadinessDimension, type ReadinessMark, type ReadinessReport, } from './readiness.js';
+export { GRAPHCODE_INCOSE_SCOPE, MARK_LABELS, computeMarks, countByStage, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, type IncoseScope, type ReadinessMark, type StageCount, type ReadinessReport, } from './readiness.js';
 export * from './panels.js';

package/dist/index.js

@@ -18,5 +18,5 @@
  */
 export { HOST_SOCK_BASENAME, callHost, } from './host-client.js';
 export { MARKDOWN_VIEWS, VIEW_FILENAMES } from './view-catalog.js';
-export { GRAPHCODE_INCOSE_SCOPE, MARK_LABELS, computeMarks, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, } from './readiness.js';
+export { GRAPHCODE_INCOSE_SCOPE, MARK_LABELS, computeMarks, countByStage, summarizeReadiness, computeReadiness, scoreReadiness, getFamilyRuleIds, } from './readiness.js';
 export * from './panels.js';

package/dist/panels.d.ts

@@ -18,9 +18,6 @@ import type { ReadinessReport, ReadinessMark } from './readiness.js';
 import type { RuleViolation, LiveUpdateEvent } from '@sigloch/contracts/harness';
 import type { Graph } from '@sigloch/graph-api-core';
 export interface ReadinessPanel {
-    compliancePct: number;
-    totalElements: number;
-    elementsWithErrors: number;
     /** SRR, PDR, CDR, TRR, Bau — reached or not, with the findings that hold each (CR-SM-395). */
     marks: ReadinessMark[];
 }

package/dist/panels.js

@@ -1,11 +1,6 @@
 import { AnalysisArtifactId, AnalysisFreshnessStampSchema } from '@sigloch/contracts/se';
 export function readinessPanel(report) {
-    return {
-        compliancePct: Math.round(report.compliance.score * 1000) / 10,
-        totalElements: report.compliance.totalElements,
-        elementsWithErrors: report.compliance.elementsWithErrors,
-        marks: report.marks,
-    };
+    return { marks: report.marks };
 }
 const SEVERITY_RANK = { error: 0, warning: 1, info: 2 };
 export function recommendationsPanel(violations, limit = 5) {

package/dist/readiness.d.ts

@@ -1,62 +1,5 @@
-/**
- * Readiness — compliance and the marks (CR-GC-107, CR-GC-125; rebuilt CR-SM-395).
- *
- * Computed purely from rule violations of `@sigloch/contracts` (the family rule base, never a
- * foreign rule set) and the stage each rule carries at its definition. There is no gate
- * computation of its own in this package any more.
- *
- * THE MARKS. The rule catalog orders its sets in twelve stages (`STAGE_SETS`); a mark lies
- * between two stages: SRR after stage 4, PDR after 7, CDR after 8, TRR after 9, Bau after 12.
- * A mark is REACHED iff no finding holds it. A finding holds a mark when its rule lies at or
- * before the mark's stage — or at every stage (`'immer'`) — and it is
- *   - an error, or
- *   - a finding of an existence rule: a set the stage requires is missing.
- * Other warnings do not hold a mark; "free of warnings" is a separate statement.
- *
- * The mark Bau additionally is held by every warning of the stages 10 to 12 (plan, binding,
- * conformance): those findings ARE the work list of the build, and the mark reads "nothing left
- * to plan, bind or reconcile". It opens again with every change.
- *
- * A NOTE (severity `info`, e.g. MS-03, VR-01) holds no mark, at no stage (CR-SM-396).
- *
- * AN ACCEPTED FINDING HOLDS ITS MARK (CR-SM-396). The rules keep firing on a finding the human
- * accepted with a reason (`acceptedFindings`), and the marks are computed from all of them: an
- * accepted AF-05 ("unbuilt, no order") still holds Bau. Acceptance takes a finding out of the
- * work focus; it is no way to read a mark as reached. Callers pass the findings UNFILTERED.
- *
- * Why "0 of 0" cannot read as reached: every mandatory set is demanded by an existence rule of
- * the stage before it (no system → R-33, no use case → R-17, …). An empty set is therefore either
- * voluntary, or the existence rule before it is open and holds the mark. Stage 8 (schema) carries
- * no existence rule of its own (CR-SM-396): a data flow without a schema is a grammar error
- * (R-18, every stage), and no data flow at all is held by R-31 (stage 6).
- *
- * What is gone with CR-SM-395: the three-valued gate state and its labels, the gate score, the
- * gate completeness and its legs (`COMPLETENESS_SLICES`), the four build gates bound to milestone
- * ids, the required creations per gate and the currency of analysis artifacts. The assignment
- * rule → mark is `ALL_RULE_DEFS[].mark` in contracts, not a list here.
- *
- * Host/dashboard wiring (panels) lives in `panels.ts`; this module provides the scoring
- * primitive only — no dashboard, no renderer.
- *
- * @author andreas@siglochconsulting
- */
-import type { Graph } from '@sigloch/graph-api-core';
-import { type MarkType } from '@sigloch/contracts/se';
+import { type MarkType, type RuleStage } from '@sigloch/contracts/se';
 import type { RuleViolation } from '@sigloch/contracts/harness';
-/**
- * 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, analyses are lightweight
@@ -80,16 +23,30 @@ export interface ReadinessMark {
 }
 /** The marks in order, each with the findings that hold it. */
 export declare function computeMarks(violations: RuleViolation[]): ReadinessMark[];
+/** One stage of the rule catalog and the number of findings whose rule lies at it. */
+export interface StageCount {
+    /** 1–12, or `'immer'` for the rules over all elements. */
+    stage: RuleStage;
+    /** The set of the stage (`STAGE_SETS`); `'immer'` carries its own value. */
+    name: string;
+    /** Number of findings of the rules at this stage — every severity, accepted or not. */
+    findings: number;
+}
+/**
+ * The findings counted per stage: the stages 1 to 12 in order, then `'immer'` — always 13 entries.
+ * Derived from the stage each rule carries at its definition and from nothing else: no table, no
+ * denominator, no percentage. The sum over the entries is the number of findings. A finding of a
+ * rule the catalog does not know throws, as in `holds`.
+ *
+ * This replaces the eight readiness dimensions and their scores (decision of the author,
+ * 2026-10-07: "Stufe statt Dimension, Befunde zaehlen statt Prozent").
+ */
+export declare function countByStage(violations: RuleViolation[]): StageCount[];
 /**
  * Full readiness snapshot derived from rule violations.
  * All violation ruleIds are contracts rule-IDs — never a foreign rule set.
  */
 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;
     /** The marks SRR, PDR, CDR, TRR, Bau — in order. */
@@ -111,23 +68,22 @@ export interface ReadinessReport {
  */
 export declare function summarizeReadiness(report: ReadinessReport): ReadinessReport;
 /**
- * Compute readiness from a violations array + the full graph (nodes + edges).
+ * Compute readiness from a violations array — and from nothing else (CR-SM-402: the graph was
+ * read for the compliance percentage only).
  *
  * @param violations - from `harness.evaluateRules()` (contracts rule IDs), UNFILTERED: a finding
  *                     the human accepted with a reason still holds its mark (CR-SM-396).
- * @param graph      - from `harness.getGraph()` (elements + traces)
  */
-export declare function computeReadiness(violations: RuleViolation[], graph: Pick<Graph, 'nodes' | 'edges'>): ReadinessReport;
+export declare function computeReadiness(violations: RuleViolation[]): ReadinessReport;
 /**
- * Convenience wrapper: runs `evaluateRules()` + `getGraph()` on the harness
- * and returns the full ReadinessReport.
+ * Convenience wrapper: runs `evaluateRules()` 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

package/dist/readiness.js

@@ -1,5 +1,51 @@
+/**
+ * Readiness — the marks and the findings (CR-GC-107, CR-GC-125; rebuilt CR-SM-395).
+ *
+ * Computed purely from rule violations of `@sigloch/contracts` (the family rule base, never a
+ * foreign rule set) and the stage each rule carries at its definition. There is no gate
+ * computation of its own in this package any more.
+ *
+ * THE MARKS. The rule catalog orders its sets in twelve stages (`STAGE_SETS`); a mark lies
+ * between two stages: SRR after stage 4, PDR after 7, CDR after 8, TRR after 9, Bau after 12.
+ * A mark is REACHED iff no finding holds it. A finding holds a mark when its rule lies at or
+ * before the mark's stage — or at every stage (`'immer'`) — and it is
+ *   - an error, or
+ *   - a finding of an existence rule: a set the stage requires is missing.
+ * Other warnings do not hold a mark; "free of warnings" is a separate statement.
+ *
+ * The mark Bau additionally is held by every warning of the stages 10 to 12 (plan, binding,
+ * conformance): those findings ARE the work list of the build, and the mark reads "nothing left
+ * to plan, bind or reconcile". It opens again with every change.
+ *
+ * A NOTE (severity `info`, e.g. MS-03, VR-01) holds no mark, at no stage (CR-SM-396).
+ *
+ * AN ACCEPTED FINDING HOLDS ITS MARK (CR-SM-396). The rules keep firing on a finding the human
+ * accepted with a reason (`acceptedFindings`), and the marks are computed from all of them: an
+ * accepted AF-05 ("unbuilt, no order") still holds Bau. Acceptance takes a finding out of the
+ * work focus; it is no way to read a mark as reached. Callers pass the findings UNFILTERED.
+ *
+ * Why "0 of 0" cannot read as reached: every mandatory set is demanded by an existence rule of
+ * the stage before it (no system → R-33, no use case → R-17, …). An empty set is therefore either
+ * voluntary, or the existence rule before it is open and holds the mark. Stage 8 (schema) carries
+ * no existence rule of its own (CR-SM-396): a data flow without a schema is a grammar error
+ * (R-18, every stage), and no data flow at all is held by R-31 (stage 6).
+ *
+ * What is gone with CR-SM-395: the three-valued gate state and its labels, the gate score, the
+ * gate completeness and its legs (`COMPLETENESS_SLICES`), the four build gates bound to milestone
+ * ids, the required creations per gate and the currency of analysis artifacts. The assignment
+ * rule → mark is `ALL_RULE_DEFS[].mark` in contracts, not a list here.
+ *
+ * What is gone with CR-SM-402: the compliance percentage (share of elements without an error
+ * finding) with its denominator and its two counts. The report carries marks and findings — what
+ * the agent reads and acts on — and nothing a viewer would see on top of that.
+ *
+ * Host/dashboard wiring (panels) lives in `panels.ts`; this module provides the scoring
+ * primitive only — no dashboard, no renderer.
+ *
+ * @author andreas@siglochconsulting
+ */
 import { SE_DESCRIPTOR } from '@sigloch/graph-api-core';
-import { ALL_RULE_DEFS, CODE_CONFORMANCE_RULES, Mark, MARK_STAGE } from '@sigloch/contracts/se';
+import { ALL_RULE_DEFS, CODE_CONFORMANCE_RULES, Mark, MARK_STAGE, STAGE_SETS } from '@sigloch/contracts/se';
 /** graphcode's declared scope. */
 export const GRAPHCODE_INCOSE_SCOPE = 'lean';
 // ---------------------------------------------------------------------------
@@ -16,14 +62,14 @@ export const MARK_LABELS = {
 const RULES = new Map(ALL_RULE_DEFS.map((r) => [r.id, r]));
 /** Does this finding hold this mark? See the module header for the rule. */
 function holds(v, mark) {
+    // A finding of a rule the catalog does not know is a programming error and throws (CR-SM-399).
+    const rule = RULES.get(v.ruleId);
+    const stage = rule.stage;
     if (v.severity === 'info')
         return false; // a note holds no mark (CR-SM-396)
-    const rule = RULES.get(v.ruleId);
-    // A finding of a rule the catalog does not know cannot be placed on the ladder: like `'immer'`.
-    const stage = rule?.stage ?? 'immer';
     if (stage !== 'immer' && stage > MARK_STAGE[mark])
         return false;
-    if (v.severity === 'error' || rule?.role === 'existence')
+    if (v.severity === 'error' || rule.role === 'existence')
         return true;
     return mark === 'Bau' && stage !== 'immer' && stage > MARK_STAGE.TRR;
 }
@@ -34,6 +80,22 @@ export function computeMarks(violations) {
         return { id, label: MARK_LABELS[id], reached: holding.length === 0, holding };
     });
 }
+/**
+ * The findings counted per stage: the stages 1 to 12 in order, then `'immer'` — always 13 entries.
+ * Derived from the stage each rule carries at its definition and from nothing else: no table, no
+ * denominator, no percentage. The sum over the entries is the number of findings. A finding of a
+ * rule the catalog does not know throws, as in `holds`.
+ *
+ * This replaces the eight readiness dimensions and their scores (decision of the author,
+ * 2026-10-07: "Stufe statt Dimension, Befunde zaehlen statt Prozent").
+ */
+export function countByStage(violations) {
+    const count = (stage) => violations.filter((v) => RULES.get(v.ruleId).stage === stage).length;
+    return [
+        ...STAGE_SETS.map((name, i) => ({ stage: (i + 1), name, findings: count((i + 1)) })),
+        { stage: 'immer', name: 'immer', findings: count('immer') },
+    ];
+}
 /**
  * Summary projection of a ReadinessReport (CR-GC-203 item 2): drops the heavy
  * per-element lists — `violations` and every mark's `holding` — while keeping
@@ -53,16 +115,13 @@ export function summarizeReadiness(report) {
 // Scorer
 // ---------------------------------------------------------------------------
 /**
- * Compute readiness from a violations array + the full graph (nodes + edges).
+ * Compute readiness from a violations array — and from nothing else (CR-SM-402: the graph was
+ * read for the compliance percentage only).
  *
  * @param violations - from `harness.evaluateRules()` (contracts rule IDs), UNFILTERED: a finding
  *                     the human accepted with a reason still holds its mark (CR-SM-396).
- * @param graph      - from `harness.getGraph()` (elements + traces)
  */
-export function computeReadiness(violations, graph) {
-    const totalElements = graph.nodes.length;
-    const elementsWithErrors = new Set(violations.filter((v) => v.severity === 'error' && v.elementId !== undefined).map((v) => v.elementId)).size;
-    const complianceScore = totalElements > 0 ? (totalElements - elementsWithErrors) / totalElements : 1;
+export function computeReadiness(violations) {
     const violationsByRule = {};
     for (const v of violations) {
         violationsByRule[v.ruleId] = (violationsByRule[v.ruleId] ?? 0) + 1;
@@ -71,12 +130,6 @@ export function computeReadiness(violations, graph) {
     const severityRank = { error: 0, warning: 1, info: 2 };
     const sorted = [...violations].sort((a, b) => (severityRank[a.severity] ?? 3) - (severityRank[b.severity] ?? 3));
     return {
-        compliance: {
-            score: complianceScore,
-            label: 'Compliance (V3_RULES, error-severity)',
-            totalElements,
-            elementsWithErrors,
-        },
         incoseScope: GRAPHCODE_INCOSE_SCOPE,
         marks: computeMarks(violations),
         violationsByRule,
@@ -85,14 +138,14 @@ export function computeReadiness(violations, graph) {
     };
 }
 /**
- * Convenience wrapper: runs `evaluateRules()` + `getGraph()` on the harness
- * and returns the full ReadinessReport.
+ * Convenience wrapper: runs `evaluateRules()` 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) {
-    return computeReadiness(harness.evaluateRules(), harness.getGraph());
+    return computeReadiness(harness.evaluateRules());
 }
 /**
  * The authoritative set of family rule-IDs (derived at runtime from

package/dist/view-catalog.d.ts

@@ -22,7 +22,7 @@
  * grouped by type and answered the same question as `srs` (the ISO-29148 narrative)
  * with different completeness — two requirements documents, one truth. `srs` stays.
  */
-export declare const MARKDOWN_VIEWS: readonly ["architecture", "cr-list", "references", "srs", "nfr", "rtm", "icd", "testconcept", "testmatrix", "intplan", "changelog", "fmea", "conops", "trade", "implplan"];
+export declare const MARKDOWN_VIEWS: readonly ["architecture", "cr-list", "references", "srs", "nfr", "rtm", "icd", "testconcept", "testmatrix", "intplan", "changelog", "fmea", "conops", "implplan"];
 export type MarkdownView = (typeof MARKDOWN_VIEWS)[number];
 /** Default file name for each view (under docs/views/). */
 export declare const VIEW_FILENAMES: Record<MarkdownView, string>;

package/dist/view-catalog.js

@@ -38,7 +38,6 @@ export const MARKDOWN_VIEWS = [
     'changelog',
     'fmea',
     'conops',
-    'trade',
     'implplan',
 ];
 /** Default file name for each view (under docs/views/). */
@@ -56,6 +55,5 @@ export const VIEW_FILENAMES = {
     changelog: 'changelog.md',
     fmea: 'fmea.md',
     conops: 'conops.md',
-    trade: 'trade.md',
     implplan: 'implplan.md',
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/graphcode-client",
-  "version": "2.0.0",
+  "version": "3.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -40,11 +40,11 @@
     "zod": "^4.3.6"
   },
   "peerDependencies": {
-    "@sigloch/contracts": ">=11 <12",
+    "@sigloch/contracts": ">=12 <13",
     "@sigloch/graph-api-core": ">=5 <6"
   },
   "devDependencies": {
-    "@sigloch/contracts": ">=11 <12",
+    "@sigloch/contracts": ">=12 <13",
     "@sigloch/graph-api-core": ">=5.4 <6"
   }
 }