@sigloch/contracts 9.1.0 → 10.1.0

package/dist/se/quality-rules.js

@@ -23,14 +23,37 @@ const measurablePattern = /(\d+[\s]*(ms|s|sec|min|%|percent|byte|MB|GB|times|x|s
 function reqElements(graph) {
     return graph.elements.filter(e => e.type === 'REQ');
 }
+/**
+ * CR-SM-275: `description` ist im Zod-Schema Pflicht, aber die Regeln bekommen Graphen aus
+ * Store/Import ohne Re-Parse — dort fehlt das Feld. `req.description.trim()` warf dann
+ * `TypeError` und riss `evaluateAllRules` ab (gemessen am kadjar-Graphen, Spike CR-GC-438 §7).
+ * EIN Normalisierungspunkt statt eines Guards je Fundstelle: eine fehlende Beschreibung ist
+ * die leere Beschreibung — ein BEFUND (BQ-06/BQ-07 melden sie), kein Absturz.
+ */
+/**
+ * CR-SM-285: `?? ''` faengt nur `null`/`undefined`. Ein Graph aus einer fremden Quelle (Import,
+ * fremdes Tool, handgeschriebene Fixture) kann `description` als Zahl, Objekt oder Array tragen —
+ * dann warf `.trim()` und `evaluateAllRules` STARB, statt zu urteilen. Am Gate heisst das:
+ * Stacktrace statt `block`-Verdict, der Aufrufer sieht kein Urteil.
+ *
+ * Gemessen vor dem Fix: `null` ok, `42`/`{}`/`[]`/`true` -> "descriptionOf(...).trim is not a
+ * function". Vier von fuenf Typen.
+ *
+ * Nicht-Strings werden zu `''` — also behandelt wie "keine Beschreibung". Das ist die richtige
+ * Deutung: ein Objekt IST keine Beschreibung, und die Regel soll das melden statt zu raten oder
+ * zu sterben.
+ */
+function descriptionOf(el) {
+    return typeof el.description === 'string' ? el.description : '';
+}
 // ---------------------------------------------------------------------------
 // BQ-01 Unambiguous — detect weasel words in REQ descriptions
 // ---------------------------------------------------------------------------
 export function bq01Unambiguous(graph) {
     return reqElements(graph)
-        .filter(req => weaselPattern.test(req.description))
+        .filter(req => weaselPattern.test(descriptionOf(req)))
         .map(req => {
-        const match = req.description.match(weaselPattern);
+        const match = descriptionOf(req).match(weaselPattern);
         return {
             rule_id: 'BQ-01',
             severity: 'warning',
@@ -50,7 +73,7 @@ export function bq01Unambiguous(graph) {
 // ---------------------------------------------------------------------------
 export function bq02Verifiable(graph) {
     return reqElements(graph)
-        .filter(req => !measurablePattern.test(req.description))
+        .filter(req => !measurablePattern.test(descriptionOf(req)))
         .map(req => ({
         rule_id: 'BQ-02',
         severity: 'warning',
@@ -85,6 +108,24 @@ export function setBQ04SimilarityMatrix(data) {
 /**
  * BQ-04 checks for duplicate / near-duplicate requirements using
  * pre-computed embedding similarity. Returns [] when no matrix is set.
+ *
+ * CR-SM-286: **bewusst NICHT angeschlossen — anders als ND-01/ND-02.**
+ *
+ * Die Naht ist dieselbe und sie ist genauso tot: `setBQ04SimilarityMatrix()` ruft im gesamten
+ * Familienbaum niemand (CR-SM-278, erneut geprueft). Der Unterschied liegt in der Eingabe. ND-01
+ * und ND-02 nennen deterministische Formeln ueber Graphinhalt (Jaccard ueber Beschreibung,
+ * Verb, io-Topologie, Felder) — die konnten nach `similarity.ts` wandern und tun dort dasselbe.
+ * BQ-04 verlangt laut eigener Zeile "pre-computed EMBEDDING similarity", und Embeddings kann ein
+ * reines Vertragspaket nicht berechnen: kein Modell, kein Netz, kein Zufall.
+ *
+ * Ein Ersatzmass haette ich erfinden muessen. Ein Versuch mit 0.7*Beschreibung + 0.3*Name lief:
+ * **0 Befunde an allen neun Familiengraphen** und 4950 an einer templatierten Fixture — also
+ * genau die zwei Gate-7-Ausreisser zugleich ("0 Befunde am Selbstmodell" und "quadratisch mit
+ * der Graphgroesse"). Erfundene Gewichte ohne Messung sind keine Reparatur.
+ *
+ * Damit ist BQ-04 der naechste AO-D03-Fall: entweder eine Eingabe, die der Host liefern MUSS
+ * (dann gehoert die Regel nicht in ein reines Paket), oder streichen. Das ist eine
+ * Grammatik-Entscheidung — `se-grammar-review`, eigener CR, nicht hier nebenbei.
  */
 export function bq04Necessary(graph) {
     if (!_bq04Matrix)
@@ -141,7 +182,7 @@ const conformingPatternDE = /\b(soll|muss|darf nicht)\s+\w+/i;
 export function bq06Conforming(graph) {
     return reqElements(graph)
         .filter(req => {
-        const desc = req.description.trim();
+        const desc = descriptionOf(req).trim();
         return !conformingPattern.test(desc) && !conformingPatternDE.test(desc);
     })
         .map(req => ({
@@ -174,17 +215,18 @@ export function bq07Complete(graph) {
     // zulaessig ist. Das ist die Fehlmessung und deshalb R-18/error; das blosse Fehlen der
     // Angabe ist ein Vollstaendigkeitssignal und deshalb hier/warning — dieselbe Trennung, die
     // CR-SM-262 fuer RC-06 begruendet hat.
-    const isIncomplete = (req) => req.description.trim().length < BQ07_MIN_DESC_LENGTH ||
-        placeholderPattern.test(req.description) ||
+    const isIncomplete = (req) => descriptionOf(req).trim().length < BQ07_MIN_DESC_LENGTH ||
+        placeholderPattern.test(descriptionOf(req)) ||
         normalizeReqKinds(req.kinds).length === 0;
     return reqElements(graph)
         .filter(isIncomplete)
         .map(req => {
+        const desc = descriptionOf(req);
         const reasons = [];
-        if (req.description.trim().length < BQ07_MIN_DESC_LENGTH) {
-            reasons.push(`description too short (${req.description.trim().length}/${BQ07_MIN_DESC_LENGTH} chars)`);
+        if (desc.trim().length < BQ07_MIN_DESC_LENGTH) {
+            reasons.push(`description too short (${desc.trim().length}/${BQ07_MIN_DESC_LENGTH} chars)`);
         }
-        if (placeholderPattern.test(req.description)) {
+        if (placeholderPattern.test(desc)) {
             reasons.push('contains placeholder');
         }
         if (normalizeReqKinds(req.kinds).length === 0) {

package/dist/se/readiness.d.ts

@@ -9,24 +9,24 @@
  */
 import { z } from 'zod/v4';
 export declare const ReadinessDimension: z.ZodEnum<{
+    schema: "schema";
     req: "req";
     uc: "uc";
     arch: "arch";
     alloc: "alloc";
     ver: "ver";
-    schema: "schema";
     cr: "cr";
     ms: "ms";
 }>;
 export type ReadinessDimensionType = z.infer<typeof ReadinessDimension>;
 export declare const ReadinessScore: z.ZodObject<{
     dimension: z.ZodEnum<{
+        schema: "schema";
         req: "req";
         uc: "uc";
         arch: "arch";
         alloc: "alloc";
         ver: "ver";
-        schema: "schema";
         cr: "cr";
         ms: "ms";
     }>;
@@ -49,12 +49,12 @@ export type ReadinessScoreType = z.infer<typeof ReadinessScore>;
 export declare const ReadinessReport: z.ZodObject<{
     scores: z.ZodArray<z.ZodObject<{
         dimension: z.ZodEnum<{
+            schema: "schema";
             req: "req";
             uc: "uc";
             arch: "arch";
             alloc: "alloc";
             ver: "ver";
-            schema: "schema";
             cr: "cr";
             ms: "ms";
         }>;
@@ -67,6 +67,28 @@ export declare const ReadinessReport: z.ZodObject<{
     timestamp: z.ZodISODateTime;
 }, z.core.$strip>;
 export type ReadinessReportType = z.infer<typeof ReadinessReport>;
+/**
+ * CR-SM-305 — welche Profile in die readiness-Zahlen eingehen, und warum `conformance` nicht.
+ *
+ * Der Nenner jeder Dimension ist `Σ (Elemente der Grundgesamtheit)` ueber die Regeln der
+ * Dimension (`readiness-compute.ts`). Eine Regel, die DEKLARIERT, aber nicht AUSGEWERTET wird,
+ * traegt damit zum Nenner bei und liefert null Verstoesse — der Score STEIGT, weil eine
+ * Pruefung nicht gelaufen ist. Dieselbe Fail-open-Klasse wie ND-01/02 vor CR-SM-286, nur an der
+ * Stelle, die am lautesten gelesen wird.
+ *
+ * Gemessen ueber vier Familien-Repos, was die sechs RC-Regeln in `arch`/`ver`/`schema`
+ * geschenkt haetten: graph-view-edit `schema` +5,0 Punkte (Nenner 24 → 40), graphify `arch`
+ * +2,1 und `ver` +1,8, alles Uebrige ≤ 0,2. Der Ausschlag sitzt genau dort, wo die Zahl am
+ * meisten wiegt — in der kleinen Dimension.
+ *
+ * Deshalb steht keine RC-ID in `RULE_TO_DIMENSION` oder `RULE_TO_PHASE`. Das ist keine Luecke,
+ * sondern die Aussage „nicht ausgewertet, also weder Zaehler noch Nenner";
+ * `computeApplicable` ueberspringt eine Regel ohne Dimension bereits von selbst
+ * (`if (!dim) continue`). Sichtbar wird RC ueber die Ableitung `ALL_RULE_DEFS minus
+ * ausgewertet` beim Host: sechs Regeln, die als NICHT GEPRUEFT dastehen, solange kein Lauf
+ * `CodeFacts` mitbringt.
+ */
+export declare const READINESS_SCORED_PROFILES: readonly ["se", "coding"];
 /**
  * Rule → dimension mapping. Some rules belong to multiple dimensions;
  * here we assign primary dimension per rule. R-01 appears in 'ver' (primary)

package/dist/se/readiness.js

@@ -14,7 +14,7 @@ export const ReadinessDimension = z.enum([
     'arch', // Functional architecture (R-02, R-03, R-10, R-12)
     'alloc', // Module allocation (R-04)
     'ver', // Test coverage (R-01, R-05)
-    'schema', // Interface completeness (R-26 binding, SC-02/SC-04 usage)
+    'schema', // Interface completeness (R-26 binding, SC-02 usage)
     'cr', // CR traceability (CR-R01..R03)
     'ms', // Milestone planning (MS-01..02)
 ]);
@@ -62,6 +62,28 @@ export const ReadinessReport = z.object({
     scores: z.array(ReadinessScore),
     timestamp: z.iso.datetime(),
 });
+/**
+ * CR-SM-305 — welche Profile in die readiness-Zahlen eingehen, und warum `conformance` nicht.
+ *
+ * Der Nenner jeder Dimension ist `Σ (Elemente der Grundgesamtheit)` ueber die Regeln der
+ * Dimension (`readiness-compute.ts`). Eine Regel, die DEKLARIERT, aber nicht AUSGEWERTET wird,
+ * traegt damit zum Nenner bei und liefert null Verstoesse — der Score STEIGT, weil eine
+ * Pruefung nicht gelaufen ist. Dieselbe Fail-open-Klasse wie ND-01/02 vor CR-SM-286, nur an der
+ * Stelle, die am lautesten gelesen wird.
+ *
+ * Gemessen ueber vier Familien-Repos, was die sechs RC-Regeln in `arch`/`ver`/`schema`
+ * geschenkt haetten: graph-view-edit `schema` +5,0 Punkte (Nenner 24 → 40), graphify `arch`
+ * +2,1 und `ver` +1,8, alles Uebrige ≤ 0,2. Der Ausschlag sitzt genau dort, wo die Zahl am
+ * meisten wiegt — in der kleinen Dimension.
+ *
+ * Deshalb steht keine RC-ID in `RULE_TO_DIMENSION` oder `RULE_TO_PHASE`. Das ist keine Luecke,
+ * sondern die Aussage „nicht ausgewertet, also weder Zaehler noch Nenner";
+ * `computeApplicable` ueberspringt eine Regel ohne Dimension bereits von selbst
+ * (`if (!dim) continue`). Sichtbar wird RC ueber die Ableitung `ALL_RULE_DEFS minus
+ * ausgewertet` beim Host: sechs Regeln, die als NICHT GEPRUEFT dastehen, solange kein Lauf
+ * `CodeFacts` mitbringt.
+ */
+export const READINESS_SCORED_PROFILES = ['se', 'coding'];
 /**
  * Rule → dimension mapping. Some rules belong to multiple dimensions;
  * here we assign primary dimension per rule. R-01 appears in 'ver' (primary)
@@ -79,8 +101,7 @@ export const RULE_TO_DIMENSION = {
     // CR-SM-231: R-29 (Testdatei-Exklusivitaet) gehoert zu 'ver' wie R-19 — beide bewerten die
     // Evidenz-Bindung einer Abnahme, R-19 ihre Praesenz, R-29 ihre Eindeutigkeit.
     'R-29': 'ver',
-    'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema', 'R-27': 'arch',
-    // CR-GC-366: R-30 (Wirkketten-Bindung) und R-31 (io-Verdrahtung) bewerten beide, ob ein
+    'R-22': 'alloc', 'R-23': 'alloc', 'R-26': 'schema', // CR-GC-366: R-30 (Wirkketten-Bindung) und R-31 (io-Verdrahtung) bewerten beide, ob ein
     // Funktionsblock ueberhaupt im Bauplan haengt — dieselbe Dimension wie R-20 (realRef).
     // NICHT 'uc': R-14..R-17 fragen, ob ein Behaelter gefuellt ist;
     // diese beiden fragen von der FUNC aus, ob sie angeschlossen ist.
@@ -88,19 +109,19 @@ export const RULE_TO_DIMENSION = {
     // uc
     'UC-01': 'uc', 'UC-02': 'uc', 'UC-03': 'uc', 'UC-04': 'uc',
     'UC-05': 'uc', 'UC-06': 'uc',
-    'R-14': 'uc', 'R-15': 'uc', 'R-16': 'uc', 'R-17': 'uc',
+    'R-15': 'uc', 'R-16': 'uc', 'R-17': 'uc',
     // FC-04 (CR-SM-226): FCHAIN actor-bounded (trigger+consumer) — same dimension as FC-01..03.
-    'FC-01': 'uc', 'FC-02': 'uc', 'FC-03': 'uc', 'FC-04': 'uc',
+    'FC-02': 'uc', 'FC-03': 'uc', 'FC-04': 'uc',
     // arch
-    'R-02': 'arch', 'R-03': 'arch', 'R-10': 'arch', 'R-12': 'arch',
+    'R-02': 'arch', 'R-10': 'arch', 'R-12': 'arch',
     // alloc
     'R-04': 'alloc',
     // ver
     'R-01': 'ver', 'R-05': 'ver',
     // schema
     'SC-02': 'schema', // SC-01/SC-03 deleted (BOK-CR-026) — R-26 is the binding rule
-    // CR-SM-226: SC-04 sharp per-FLOW SCHEMA-binding check — same dimension as SC-02.
-    'SC-04': 'schema',
+    // SC-04 entfiel mit CR-SM-271: FLOW ohne SCHEMA ist jetzt Grammatik (R-18-Bein, error)
+    // und zaehlt damit unter R-18/'arch' statt als eigene 'schema'-Zeile.
     // structural rules without primary dimension → assigned by closest concern
     'R-08': 'arch',
     // near-duplicate detection
@@ -110,12 +131,12 @@ export const RULE_TO_DIMENSION = {
     // rule (CR-SM-223) — a per-module advisory would depress this score permanently.
     'MT-01': 'alloc', 'MT-02': 'alloc',
     // CR traceability
-    'CR-R01': 'cr', 'CR-R02': 'cr', 'CR-R03': 'cr', 'CR-R04': 'cr',
-    // architecture optimization
-    'AO-D01': 'arch', 'AO-D03': 'arch',
+    'CR-R01': 'cr', 'CR-R02': 'cr', 'CR-R03': 'cr', // architecture optimization
+    // CR-SM-283: BW-02 (Whitebox-Randbreite) ersetzt AO-D03 an dieser Stelle — dieselbe
+    // Dimension, denn beide fragen nach der Struktur des Funktionsschnitts, nicht nach Evidenz.
+    'BW-02': 'arch',
     // allocation rules (CR-191)
-    'CR-01': 'arch', 'RT-01': 'arch', 'PH-01': 'arch', 'CA-01': 'arch',
-    // milestone planning
+    'CR-01': 'arch', // milestone planning
     'MS-01': 'ms', 'MS-02': 'ms', 'MS-03': 'ms',
     // FMEA / risk
     'FM-01': 'req', 'FM-02': 'req', 'FM-03': 'ver',
@@ -161,7 +182,7 @@ export const RULE_TO_PHASE = {
     'BQ-01': 'SRR', 'BQ-02': 'SRR', 'BQ-04': 'SRR', 'BQ-06': 'SRR', 'BQ-07': 'SRR',
     'RD-01': 'SRR', 'RD-02': 'SRR', 'RD-03': 'SRR',
     'UC-01': 'SRR', 'UC-02': 'SRR', 'UC-03': 'SRR', 'UC-04': 'SRR', 'UC-05': 'SRR', 'UC-06': 'SRR',
-    'R-14': 'SRR', 'R-16': 'SRR', 'R-17': 'SRR',
+    'R-16': 'SRR', 'R-17': 'SRR',
     'FC-02': 'SRR',
     'CL-01': 'SRR',
     'FM-01': 'SRR', 'FM-02': 'SRR',
@@ -169,21 +190,18 @@ export const RULE_TO_PHASE = {
     'MS-01': 'SRR', 'MS-02': 'SRR', 'MS-03': 'SRR',
     // PDR — architecture/functional completeness.
     'RD-04': 'PDR',
-    'R-02': 'PDR', 'R-03': 'PDR', 'R-08': 'PDR', 'R-10': 'PDR', 'R-12': 'PDR', 'R-18': 'PDR',
+    'R-02': 'PDR', 'R-08': 'PDR', 'R-10': 'PDR', 'R-12': 'PDR', 'R-18': 'PDR',
     'R-04': 'PDR', 'R-22': 'PDR', 'R-23': 'PDR',
     'R-15': 'PDR',
-    'FC-01': 'PDR', 'FC-03': 'PDR', 'FC-04': 'PDR',
+    'FC-03': 'PDR', 'FC-04': 'PDR',
     // CR-GC-366: Anschluss des Funktionsbaus — gehoert an dasselbe Gate wie R-15/IO-01,
     // die auf derselben Kette aufsetzen.
     'R-30': 'PDR', 'R-31': 'PDR',
     'MT-01': 'PDR', 'MT-02': 'PDR',
     'ND-01': 'PDR',
-    'AO-D01': 'PDR', 'AO-D03': 'PDR', 'CR-01': 'PDR', 'RT-01': 'PDR', 'PH-01': 'PDR', 'CA-01': 'PDR',
-    'IO-01': 'PDR', // CR-SM-226: extended to all FCHAIN FUNC-pairs, added to the phase axis.
-    'CR-R04': 'PDR',
+    'BW-02': 'PDR', 'CR-01': 'PDR', 'IO-01': 'PDR', // CR-SM-226: extended to all FCHAIN FUNC-pairs, added to the phase axis.
     // CDR — critical design/schema completeness.
-    'R-26': 'CDR', 'R-27': 'CDR',
-    'SC-02': 'CDR', 'SC-04': 'CDR', // SC-04: FLOW→SCHEMA sharp rule (CR-SM-226)
+    'R-26': 'CDR', 'SC-02': 'CDR', // SC-04 entfiel mit CR-SM-271 — der FLOW-ohne-SCHEMA-Fall haengt an R-18/PDR
     'ND-02': 'CDR',
     'NFR-01': 'CDR',
     // TRR — test readiness.

package/dist/se/rule-help.d.ts

@@ -0,0 +1,52 @@
+/**
+ * rule-help.ts — die Regelhilfe liegt NEBEN der Regel (CR-SM-300).
+ *
+ * Ein Hilfeeintrag ist keine Annotation *ueber* einer Regel, er ist **Teil ihrer Lieferung**:
+ * eine Regel, deren Befund niemand lesen kann, ist nicht fertig. Bis hierher lag die Schicht in
+ * graphcode (CR-GC-227, bewusst, aus Tempo — dort brauchte sie keinen Bump und kein Review), und
+ * derselbe CR hat die Verschiebung ausdruecklich als spaetere Entscheidung notiert. Sie ist jetzt
+ * getroffen; der Grund ist die Drift, die sie erzeugt hat: 11 Eintraege zu geloeschten Regeln und
+ * 8 Katalogregeln ohne Eintrag, unbemerkt ueber vier Releases. Hinter einem Symlink gilt kein
+ * Versionsbereich (CR-GC-488 §1a) — eine Pruefung im ungelesenen Repo ist keine Pruefung.
+ *
+ * ## Was hier NICHT steht
+ *
+ * - **Abgeleitetes** — Titel, Severity, Meldung und `fix_hint` stehen an der Regeldefinition
+ *   (`ALL_RULE_DEFS`), die Dimensions-/Phasenzuordnung in `readiness.ts`. Kein Wort davon wird
+ *   hier wiederholt; ein zweiter Speicher derselben Wahrheit laeuft auseinander.
+ * - **`fix_hint` gegen `plain`/`se`** — `fix_hint` ist die Anweisung an den AGENTEN („Add a
+ *   `verify` trace"), `plain`/`se` die Erklaerung fuer den MENSCHEN („was ist hier eigentlich
+ *   kaputt, und wie heisst das in der SE-Literatur"). Verschiedene Leser, verschiedene Laenge,
+ *   verschiedene Sprache — deshalb drei Felder und nicht eines.
+ * - **Nicht-Regel-Hilfe** — Dashboard-Panels, Artefakte, das Vokabular und die sechs
+ *   Metrik-Dimensionen (`HELP_METRICS`, CR-GC-458) bleiben in graphcode: sie sind an dessen
+ *   Oberflaeche gebunden, nicht an den Regelkatalog.
+ *
+ * ## Was die Version haelt
+ *
+ * **Die PRAESENZ ist Oberflaeche** und haengt an `RULES_VERSION`: eine Regel ohne Hilfeeintrag
+ * kann nicht landen, ein Eintrag ohne Regel auch nicht (`tests/unit/se-rule-help.test.ts`,
+ * beidseitig, gegen die lebenden Registraturen — nie gegen eine Handzaehlung).
+ * **Der TEXT ist es nicht.** „Prosa ist ein Patch-Bump, keine Grammatik" (CR-SM-244): ein
+ * umformulierter Satz darf keinen Major ausloesen, deshalb steht im Golden-File nur die
+ * Schluesselmenge, nicht die Prosa.
+ *
+ * Sprache: Englisch, wie die Regelbeschreibungen selbst. 18,6 KB reine Strings — der
+ * `./browser`-Eintrag bleibt transitiv `node:`-frei (CR-SM-230), Strings ziehen nichts nach.
+ *
+ * @author andreas@siglochconsulting
+ */
+/** Ein verfasster Hilfeeintrag: die zwei Klartext-Schichten, dazu ein Kopier-Prompt, wo einer passt. */
+export interface RuleHelpEntry {
+    /** Schicht 0 — ohne SE-Jargon; endet mit der EINEN einfachen Handlung. */
+    readonly plain: string;
+    /** Schicht 1 — uebersetzt unsere Kodierung in den Standardbegriff der Systems-Engineering-Literatur. */
+    readonly se: string;
+    /** Schicht 2 — ein kopierbarer Prompt (`se:*`-Skill oder MCP-Aufruf), wo einer passt. */
+    readonly prompt?: string;
+}
+/**
+ * Je Regel-ID der Hilfeeintrag — Katalogregeln (`ALL_RULE_DEFS`) UND Conformance-Regeln
+ * (`CODE_CONFORMANCE_RULES`). Vollstaendig in beide Richtungen, erzwungen im Test.
+ */
+export declare const RULE_HELP: Record<string, RuleHelpEntry>;