@sigloch/contracts 10.12.0 → 10.14.0

package/dist/se/rule-help.js

@@ -31,8 +31,11 @@
  * 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.
+ * Sprache: Englisch, wie die Regelbeschreibungen selbst — ausser `vorschlag`, der Satz, den ein Nutzer
+ * seinem Agenten schickt (CR-SM-384): Deutsch, weil er in der Sprache des Nutzers steht, nicht in der
+ * des Katalogs. Bis CR-SM-384 lag er als `VORSCHLAG_REGEL` in graphcode, ein paralleler Pfad zu
+ * `plain` und `fix_hint` mit derselben Driftgefahr wie oben. Reine Strings — der `./browser`-Eintrag
+ * bleibt transitiv `node:`-frei (CR-SM-230), Strings ziehen nichts nach.
  *
  * @author andreas@siglochconsulting
  */
@@ -93,6 +96,7 @@ export const RULE_HELP = {
     'BW-02': {
         plain: "This block hands out many different kinds of data at its edge → whoever uses it has to understand all of them, so either bundle them or split the block.",
         se: "Whitebox boundary width: distinct `SCHEMA` contracts on `FUNC` `io` `FLOW` `io` `FUNC` paths with one endpoint inside the `compose` subtree and one outside, judged against `metricPolicy.boundaryWidth.warning`. Parnas, information hiding — what a boundary HIDES is what makes it worth having. Rolled up over the subtree because a decomposed `FUNC` carries no `io` edges of its own (CR-SM-283).",
+        vorschlag: 'Bündle die Datenformate an der Grenze von {n} oder teile den Block.',
     },
     'CL-01': {
         plain: "Someone only ever uses the system in one way, which usually means their other situations are missing → describe the scenarios you left out.",
@@ -102,6 +106,7 @@ export const RULE_HELP = {
     'CR-01': {
         plain: "Two parts exchange an unusually large amount of data, which usually means the boundary is in the wrong place → reconsider the cut.",
         se: "High crossing `io` FLOW count between two `MOD`s — a coupling metric, advisory.",
+        vorschlag: 'Prüfe den Schnitt zwischen {n}, dort fließen ungewöhnlich viele Daten.',
     },
     'CR-R01': {
         plain: "A change is recorded but says nothing about what it changes → link it to what it touches.",
@@ -115,41 +120,56 @@ export const RULE_HELP = {
         plain: "Several open changes touch the same thing, so they will collide → sequence them or merge them.",
         se: "One element tracked by more than one `CR` with `status` open/in-progress.",
     },
+    'CR-R05': {
+        plain: "This smallest-piece requirement has no work order — no change request points at it or at the function that fulfils it, and that function is not built yet, so no plan will ever build it → attach it to the change request that builds it.",
+        se: "Leaf `REQ` (no `compose`→`REQ` children) with no build order: no `CR -relation->` on the REQ itself nor on a `FUNC` that `satisfy`s it (CR-SM-343; the REQ side of CR-R01). A `FUNC` that is already built — valid `realRef` or `external`, not `concept` — covers the REQ without a CR (CR-SM-375). A CR on a `MOD`/`SYS` carrier does not count — a module is a container; such REQs take a direct `CR -relation-> REQ`. Silent, and not scored, on a graph without any `CR` node (`RULE_PRECONDITION`).",
+        prompt: "se-plan",
+    },
     'FC-02': {
         plain: "A scenario that is not broken into sub-scenarios has no described sequence of steps → add one, even if the steps are done by hand.",
         se: "Leaf `UC` (no `UC -compose-> UC`) with no `FCHAIN`. A chain may consist of EXISTING FUNCs an actor strings together — it costs a node plus compose edges, not code.",
         prompt: "se:author-uc",
+        vorschlag: 'Beschreibe die Abläufe {n} als Kette von Funktionen.',
     },
     'FC-03': {
         plain: "A step inside a sequence contains further steps, so the sequence has hidden depth → lift them to the same level.",
         se: "`FUNC` inside an `FCHAIN` that itself `compose`s other `FUNC`s. Chains are flat by construction.",
+        vorschlag: 'Hebe die inneren Schritte der Funktionen {n} auf die Ebene ihrer Kette.',
     },
     'FC-04': {
         plain: "A sequence either has nobody starting it or nothing coming back out → wire both ends to whoever uses it.",
         se: "`FCHAIN` lacking an entry (`ACTOR -io-> FLOW -io-> FUNC∈chain`) or an exit (`FUNC∈chain -io-> FLOW -io-> ACTOR`). Stricter than FC-01: both directions, at FUNC/FLOW level, no UC-level bypass.",
+        vorschlag: 'Verbinde Anfang und Ende der Funktionsketten {n} mit dem Nutzer.',
+    },
+    'FC-05': {
+        plain: "The steps of this sequence do not hand their results to each other — it falls apart into pieces, so nobody can say how long it is or where it gets stuck → add the missing step, connect the pieces with a data flow, or split it into separate sequences.",
+        se: "`FCHAIN` whose member `FUNC`s do not form one (weakly) connected component along producer → consumer (`FUNC -io-> FLOW -io-> FUNC`, both ends members). Per side component the cause: `missing-link` (main and side part are joined through a `FUNC` outside the chain — compose it) or `bag` (no FUNC joins them: a missing FLOW between members, or parallel services at a shared source — split). One finding per chain, components in `context.side_components` (CR-SM-242). Silent while any member lacks an io input or output (R-31 first); entry/exit belong to FC-04 (CR-SM-363).",
+        vorschlag: 'Verbinde die Schritte der Funktionsketten {n} über Datenflüsse.',
     },
     'FM-01': {
         plain: "A requirement is marked as a risk but carries no risk ratings → rate how bad, how likely and how detectable it is (1-10 each).",
-        se: "Risk `REQ` missing `severity` / `occurrence` / `detection` attributes (AIAG-VDA).",
+        se: "`REQ` with `role:\"risk\"` missing `severity` / `occurrence` / `detection` attributes (AIAG-VDA). The role is the requirement's motivation, not its kind — satisfy-neutral (CR-SM-365).",
         prompt: "se-fmea",
     },
     'FM-02': {
         plain: "A known risk has nothing planned against it → write the countermeasure as its own requirement.",
-        se: "Risk `REQ` with no `compose`d mitigation `REQ` (`kinds:[\"mitigation\"]`).",
+        se: "`REQ` with `role:\"risk\"` and no `compose`d `REQ` with `role:\"mitigation\"`. The mitigation keeps its own kind (functional or non-functional) and is satisfied like any REQ of that kind (CR-SM-365).",
         prompt: "se-fmea",
     },
     'FM-03': {
         plain: "A high risk has no test that actually passed → add a test proving the countermeasure works.",
-        se: "Risk `REQ` with RPN > 100 and no `TEST` carrying `testResult:\"passed\"` verifying it.",
+        se: "`REQ` with `role:\"risk\"`, Action Priority High (AIAG-VDA, RPN band as interim) and no verifying `TEST` whose every `testRefs` entry has `result:\"passed\"`.",
         prompt: "se-fmea",
     },
     'IO-01': {
         plain: "Two steps in the same sequence have no described data passing between them → add the data one hands to the other.",
         se: "A `FUNC` pair inside one `FCHAIN` with no `io` path (`FUNC -io-> FLOW -io-> FUNC`) connecting them.",
+        vorschlag: 'Ergänze den Datenfluss zwischen den Schritten {n}.',
     },
     'IO-02': {
         plain: "Two different places write into the same flow, so a reader cannot tell which version arrives \u2192 give each source its own flow; they may keep sharing one contract.",
         se: "`FLOW` with more than one producer (`FUNC`/`ACTOR -io-> FLOW`). R-10 checks the LOWER bound of the same axis (at least one producer, at least one consumer); the two can never fire on the same FLOW, so there is no double count. Only the producer side is bounded: several consumers are the normal shape of a shared contract \u2014 one source, many readers, which is exactly how a central configuration looks. One finding per FLOW, `value` = number of producers, `threshold` 1. Severity `error` (hygiene) and deliberately NOT in STEER_RULES — a decision, not a measured conflict: a split flow keeps its `SCHEMA`, so BW-02 (distinct contracts per boundary) does not rise. Whether a gate blocks a new finding is the consumer's gating choice, not part of the rule.",
+        vorschlag: 'Gib jeder Quelle der Datenflüsse {n} einen eigenen Datenfluss.',
     },
     'MS-01': {
         plain: "A milestone has no work assigned to it → assign the work items that belong to it.",
@@ -167,10 +187,12 @@ export const RULE_HELP = {
     'MT-01': {
         plain: "This module draws more from others than others draw from it → it will keep changing whenever they do. Measured, not judged: no threshold is set by default.",
         se: "Instability I = fan_out / (fan_in + fan_out), counted in DISTINCT CONTRACTS crossing the module boundary — the same `moduleCrossings` definition CR-01, R-04 and BW-02 use (CR-SM-274/276). CR-SM-293 fixed both halves: it used to count every trace touching the module, of which only 34 % was coupling (`allocate` is module SIZE, `satisfy` is specification); and the direction was inverted — the CONSUMER depends, so supplying outward is fan_in (Martin's Ca) and drawing inward is fan_out (Ce). `metricPolicy.instability` defaults to `null`: the distribution is bimodal, so no threshold can be read from it. The number stays in every `graph_metrics` module row, next to `uphillDependencies` (CR-SM-301).",
+        vorschlag: 'Prüfe die Abhängigkeiten des Moduls {n}.',
     },
     'MT-02': {
         plain: "The parts inside this module never talk to each other → it is really several modules in one.",
         se: "LCOM4 over the BOXES of this module whitebox: its sub-MODs (`MOD -compose-> MOD`) plus its directly allocated `FUNC`s. A box owns its whole subtree, so a decomposed block carries the contracts of its leaves — the same ownership chain R-04 (CR-SM-282), BW-02 (CR-SM-283) and R-23 (CR-SM-321) use; without it a container counted as an empty group of its own and the number grew with decomposition DEPTH (CR-SM-326). Connected means a shared CONTRACT (`FLOW -relation-> SCHEMA`, else the untyped flow) — the same counting base as CR-01/R-04/MT-01 since CR-SM-274/276, not FLOW identity. CR-SM-297 dropped `satisfy`: two FUNCs meeting the same requirement can be fully decoupled at runtime, and if they share one, the REQUIREMENT is what needs decomposing. `null` (no judgement) below two boxes and where no box carries a contract at all — an unwired FUNC is R-31's statement, at the element. `info` from `metricPolicy.lcom4.info`, `warning` from `.warning` (CR-GC-329).",
+        vorschlag: 'Teile das Modul {n}, seine Teile arbeiten nicht zusammen.',
     },
     'MT-04': {
         plain: "This block's parts never talk to each other → it is really two blocks that happen to sit under one name.",
@@ -179,32 +201,39 @@ export const RULE_HELP = {
     'ND-01': {
         plain: "Two functions look like the same function written twice → merge them, or make clear what each one does differently.",
         se: "Near-duplicate `FUNC` above 0.85 similarity (name, description and legal trace partners). Since CR-SM-286 the similarity is computed IN the rule, cached per graph — before that it had to be injected, and without injection the rule returned green, indistinguishable from \"no duplicates\".",
+        vorschlag: 'Führe die doppelten Funktionen {n} zusammen oder grenze sie ab.',
     },
     'ND-02': {
         plain: "Two data contracts describe the same thing twice → merge them, or say what distinguishes them.",
         se: "Near-duplicate `SCHEMA` above 0.85 similarity (name, description, fields and legal trace partners). Partners are filtered through `isValidTrace`: a rule must not reach its verdict via an edge R-18 rejects (CR-SM-286).",
+        vorschlag: 'Führe die doppelten Datenformate {n} zusammen oder grenze sie ab.',
     },
     'NFR-01': {
         plain: "Something measured exceeds the limit that was set for it → fix it or change the limit deliberately.",
         se: "Measured value above its declared budget on a `MOD` (physical) or `FUNC`/`FCHAIN` (behavioural).",
+        vorschlag: 'Bringe {n} unter sein Budget oder ändere das Budget bewusst.',
     },
     'R-01': {
         plain: "A feature you've promised has no test proving it's met, so you can't show it works → add or author a test for it.",
         se: "`REQ` with no incoming `verify` trace (test→requirement coverage, INCOSE V&V).",
         prompt: "se:close-violations",
+        vorschlag: 'Ergänze Tests für die Anforderungen {n}.',
     },
     'R-02': {
         plain: "A function isn't linked to any feature it's meant to build, so it may be dead code → link it to the feature it serves, or delete it.",
         se: "`FUNC` with no `satisfy` trace to a `REQ` (design→requirement traceability).",
+        vorschlag: 'Ordne die Funktionen {n} den Anforderungen zu, die sie erfüllen.',
     },
     'R-04': {
         plain: "Too many different data formats cross this module's boundary → merge formats, or move the functions that carry them.",
         se: "`MOD` whose boundary is crossed by `metricPolicy.boundaryWidth.warning` or more DISTINCT contracts (`SCHEMA` on the io path `FUNC` ─io→ `FLOW` ─io→ `FUNC` across the boundary, union over all neighbours — CR-SM-276). Same question and same threshold as BW-02 on the FUNC tree (CR-SM-312); module SIZE is RD-04's question since CR-SM-311.",
         prompt: "se-view:arch",
+        vorschlag: 'Verringere die Datenformate an der Grenze des Moduls {n}.',
     },
     'R-05': {
         plain: "A test doesn't check any feature you promised → link it to the feature it tests, or remove it.",
         se: "`TEST` with no `verify` trace at all — neither to a `REQ` (test→requirement coverage) nor to a `SCHEMA` (contract test, CR-SM-317).",
+        vorschlag: 'Ordne die Tests {n} den Anforderungen zu, die sie prüfen.',
     },
     'R-32': {
         plain: "A data contract exists in code but no test exercises it as a contract → add a test that tries every variant, including the ones it must reject, and link it to the schema.",
@@ -213,30 +242,37 @@ export const RULE_HELP = {
     'R-08': {
         plain: "A link points at something that no longer exists → repair or remove the broken link.",
         se: "Trace whose source or target element is missing (dangling reference).",
+        vorschlag: 'Repariere oder entferne die Verbindungen an {n}, deren Ziel fehlt.',
     },
     'R-10': {
         plain: "A piece of data goes nowhere — nothing produces or consumes it → connect it to a function or a person/outside system.",
         se: "`FLOW` with no `io` trace to a `FUNC` or `ACTOR`.",
+        vorschlag: 'Vervollständige die Datenflüsse {n}: woher sie kommen und wohin sie gehen.',
     },
     'R-12': {
         plain: "Two items depend on each other in a loop, so neither can stand alone → remove or redirect one of the two links.",
         se: "Direct cycle: A→B and B→A via the same trace type, checked on `compose` / `allocate` / `relation` only. Data (`io`) is exempt — a function that reads and writes the same `FLOW` is normal reuse, not a dependency cycle.",
+        vorschlag: 'Löse die zyklische Abhängigkeit um {n} auf.',
     },
     'R-15': {
-        plain: "A sequence of steps for a use case is empty → add the functions that make it up.",
-        se: "`FCHAIN` with no `compose` to any `FUNC`.",
+        plain: "A sequence of steps is empty, or serves no use case → add the functions that make it up, and attach it to the use case it belongs to.",
+        se: "`FCHAIN` with no `compose` to any `FUNC`, or with no incoming `compose` from a `UC` — one rule_id, up to two findings per chain (pattern of R-10).",
+        vorschlag: 'Gib den Funktionsketten {n} ihre Funktionen und ordne sie ihrem Ablauf zu.',
     },
     'R-16': {
         plain: "A person or outside system isn't connected to anything → connect it to the data it sends or receives.",
         se: "`ACTOR` with no `io` trace to a `FLOW`.",
+        vorschlag: 'Verbinde den Nutzer {n} über Datenflüsse mit den Funktionen.',
     },
     'R-17': {
         plain: "The top level of your project is empty — nothing is inside it → add the main use cases, features, or modules.",
         se: "`SYS` with no `compose` to `UC` / `REQ` / `MOD`.",
+        vorschlag: 'Lege die Abläufe des Systems {n} an.',
     },
     'R-18': {
         plain: "You connected two items in a combination that isn't allowed → use an allowed link, or fix what's at each end.",
         se: "Trace whose (source-type, target-type) pair isn't an allowed combination in the metamodel of legal links.",
+        vorschlag: 'Korrigiere die unzulässigen Verbindungen an {n}.',
     },
     'R-19': {
         plain: "A test that's meant to run doesn't point to a test file → add the link to the test file, or, if it isn't written yet, mark it not-yet-written.",
@@ -247,16 +283,19 @@ export const RULE_HELP = {
         se: "Realized `FUNC` with no valid `realRef` `{file, symbol}` (graph↔code binding); else `concept:true` / `external:true`.",
     },
     'R-21': {
-        plain: "Two functions hand data over, but they are not in one chain together — or they are, and nothing tests the hand-off → put both into the same chain, and give that chain an integration test.",
-        se: "FUNC↔FUNC handover (`FUNC` ─io→ `FLOW` ─io→ `FUNC`), two findings. (a) endpoints share NO `FCHAIN` → finding at the PRODUCER: no integration scope is declared. (b) endpoints share one, but no shared chain carries a verified integration test (`TEST` ─verify→ `REQ` ←satisfy─ `FCHAIN`) → finding at the chain. SILENT when either endpoint is in no chain at all (that is R-30's statement) and when either is infrastructure (`chains >= policy.criticality.infrastructure`): a handover into a function that runs through every chain is a bus, not a missing test.",
+        plain: "Two functions hand data over, but they are not in one chain together — or they are, and the chain is not covered: some function in it has no requirement, and no end-to-end test checks the chain → give each function of the chain a requirement it fulfils, or give the chain an end-to-end quality requirement and a test for it.",
+        se: "FUNC↔FUNC handover (`FUNC` ─io→ `FLOW` ─io→ `FUNC`), two findings. (a) endpoints share NO `FCHAIN` → finding at the PRODUCER: no integration scope is declared. (b) endpoints share one, but no shared chain is covered → finding at the chain, naming the member FUNCs without a REQ. A chain is covered either (1) through its members — EVERY member FUNC (`FCHAIN` ─compose→ `FUNC`) satisfies at least one `REQ`; verifying those REQs is R-01's job (CR-SM-376) — or (2) end-to-end — a verified integration test (`TEST` ─verify→ `REQ` ←satisfy─ `FCHAIN`); an `FCHAIN` satisfies only non-functional REQs (CR-SM-366). SILENT when either endpoint is in no chain at all (that is R-30's statement) and when either is infrastructure (`chains >= policy.criticality.infrastructure`): a handover into a function that runs through every chain is a bus, not a missing test.",
+        vorschlag: 'Bringe die Übergaben an {n} in eine Funktionskette, deren Funktionen Anforderungen erfüllen oder die ein Integrationstest prüft.',
     },
     'R-22': {
         plain: "A function isn't assigned to any building block, so it has no home in the structure → put it on a module.",
         se: "`FUNC` with no `allocate` trace to a `MOD` (deployment assignment); every function lives on exactly one module.",
+        vorschlag: 'Ordne die Funktionen {n} Modulen zu.',
     },
     'R-23': {
         plain: "A building block is empty — no function is assigned to it or to any block inside it → put a function on it, or remove the empty block.",
         se: "`MOD` with no `FUNC` ─allocate→ trace anywhere in its `compose` subtree (`subtreeFuncs`, the same count R-04 uses, CR-SM-321); the module-side complement of R-22 (empty-container signal like R-14/R-16/R-17). A container `MOD` whose sub-modules hold functions is not empty.",
+        vorschlag: 'Gib den Modulen {n} Funktionen oder entferne sie.',
     },
     'R-26': {
         plain: "A data format in the model isn't linked to the schema code that defines it → link it to the schema (or mark it concept/outside).",
@@ -269,10 +308,12 @@ export const RULE_HELP = {
     'R-30': {
         plain: "This function sits in no chain of effects, so nobody can say which use case it serves — and the checks that would prove its wiring never look at it → add it to the chain of the use case it belongs to.",
         se: "FUNC belongs to a function chain (CR-GC-366): a `FUNC` needs an incoming `FCHAIN -compose-> FUNC`, directly or inherited from a parent `FUNC` it decomposes from. R-15 demanded the opposite direction — that a chain has functions — and nothing demanded that a function has a chain. That gap is load-bearing: IO-01 (FLOW paths between chain members) and R-21 (integration test per chain) both scope themselves to a chain, so a function outside every chain falls through both nets silently. Severity `warning`, not error: on a real model this fires on the majority of functions, and an error would block every further mutation through the delta gate.",
+        vorschlag: 'Ordne die Funktionen {n} der Kette ihres Ablaufs zu.',
     },
     'R-31': {
         plain: "This function has no input or no output, so it is a dead block in the picture — only an actor is allowed to be an end point → connect it to a flow on the missing side.",
         se: "FUNC is wired (CR-GC-366): a `FUNC` needs at least one incoming `FLOW -io-> FUNC` and one outgoing `FUNC -io-> FLOW`. Only an `ACTOR` may terminate a chain. R-10 asks the same question from the FLOW side ('does this flow have a producer and a consumer?') and therefore never sees a function with no io edge at all — it does not appear in the FLOW loop. IO-01 presupposes chain membership and misses it too. One finding per FUNC naming the missing side(s), not one per side: otherwise the counter exceeds its own denominator contribution, the mis-measurement documented in CR-SM-242.",
+        vorschlag: 'Verbinde die Funktionen {n} auf der fehlenden Seite mit einem Datenfluss.',
     },
     'RC-01': {
         plain: "A function points to code that isn't there anymore (file moved or name changed) → repoint it to the current code.",
@@ -310,46 +351,58 @@ export const RULE_HELP = {
         plain: "Code somewhere reads a data contract on its own, but the model does not know that place → go through the one translator the model names, or add the new translator to the model.",
         se: "Zod-bound `SCHEMA` parsed (import + `.parse`/`.safeParse`) in a file that is neither its definition nor the `realRef` of a `FUNC` io-connected to a `FLOW` of this SCHEMA. The first code → model check: a second translator of one contract is a parallel path (spike CR-GC-637 — such paths share a contract, they are not similar). One finding per SCHEMA; test files exempt; runs only with `fileScope: 'all'` (CR-SM-358).",
     },
+    'RC-10': {
+        plain: "No file in the code can be assigned to this building block, so nobody can check whether its imports cross boundaries the model does not know → give the block its source folder, or point one of its functions at its code.",
+        se: "`MOD` with neither a `path` attribute nor an allocated `FUNC` carrying a bound `realRef` — the only two ways a file resolves to a module. Without either, RC-05 and the boundary measurement are blind for this module by construction (sigllm: 0 RC-05 findings at 19 % import coverage, 8 at 81 %). The message names the cost from `importCoverage`. `concept`/`external` modules are exempt, as for R-20 (CR-SM-344).",
+    },
     'RD-01': {
         plain: "A smallest-piece feature has nothing built to fulfil it → add what implements it.",
         se: "Leaf `REQ` (no `compose`→`REQ` children) with no `satisfy` from a `FUNC`/`FCHAIN`/`MOD`/`SYS`.",
         prompt: "se:close-violations",
+        vorschlag: 'Lege an, was die Anforderungen {n} erfüllt.',
     },
     'RD-02': {
         plain: "You split a feature into smaller features but you're also building the big one directly → build only the small pieces, not both.",
         se: "Parent `REQ` (has `compose`→`REQ` children) carrying a direct `FUNC` `satisfy`; the satisfy belongs on the children.",
+        vorschlag: 'Lass die Anforderungen {n} nur über ihre Teilanforderungen erfüllen.',
     },
     'RD-04': {
         plain: "One thing has more than 9 parts directly under it → group them, so each level stays readable.",
         se: "Decomposition breadth above `metricPolicy.decompositionBreadth.warning` children on one level — `FUNC` `compose` `FUNC`, `SYS` `compose` `MOD`, a `MOD`'s sub-`MOD`s plus its own leaf `FUNC` (`allocate`), and the root `FUNC` forest anchored at `SYS` (CR-SM-282). Default 9, the upper end of 7±2 (CR-SM-296). CR-SM-311: a module level counts its own functions again — breadth, not size; module coupling is R-04. The lower bound is RD-05.",
+        vorschlag: 'Gruppiere die Teile unter {n}, es sind zu viele auf einer Ebene.',
     },
     'RD-05': {
         plain: "A level has only one or two parts under it → it groups nothing; fold it into the level above, or gather the parts that belong together under it.",
-        se: "Decomposition breadth below `metricPolicy.decompositionBreadth.min` (default 3, exclusive) on one level, counted exactly like RD-04 (CR-SM-311, Z3). A level abstracts nothing below it. The finding carries no `value`/`threshold` and does not enter the steering score: it is readability, not boundary width. A level with no children at all is not this rule (empty MOD: R-23; FUNC without children is a leaf).",
+        se: "Decomposition breadth below `metricPolicy.decompositionBreadth.min` (default 3, exclusive) on one level, counted exactly like RD-04 (CR-SM-311, Z3). A level abstracts nothing below it. The finding carries no `value`/`threshold` and does not enter the steering score: it is readability, not boundary width. A level with no children at all is not this rule (empty MOD: R-23; FUNC without children is a leaf). The root level directly under `SYS` (`SYS` `compose` `MOD`, root `FUNC` forest) is exempt — there is no level above it, and one module or one root function is an architecture decision (CR-SM-388); RD-04 still applies there.",
+        vorschlag: 'Löse die Ebene {n} in die Ebene darüber auf oder sammle unter ihr, was zusammengehört.',
     },
     'SC-02': {
         plain: "A data format is defined but nothing uses it → connect it to the data it describes, or drop it.",
         se: "`SCHEMA` not referenced by any `FLOW` via a `relation` trace.",
+        vorschlag: 'Verbinde das Datenformat {n} mit seinem Datenfluss oder entferne es.',
     },
     'UC-01': {
         plain: "A scenario says what someone wants to do but never says what the system must provide → write down the requirements it needs.",
         se: "`UC` with no `compose` trace to any `REQ`. The use case carries no requirement content.",
         prompt: "se:author-req",
+        vorschlag: 'Lege für die Abläufe {n} Anforderungen mit Test an: fachliche je Funktion, Ende-zu-Ende-Vorgaben an der Kette.',
     },
     'UC-02': {
         plain: "A scenario has nobody who triggers it → name who or what starts it.",
-        se: "`UC` with no `ACTOR` connected by an `io` trace (directly or via a `FLOW` of its chain).",
-        prompt: "se:author-uc",
+        se: "`UC` that no `ACTOR` reaches: the one legal path is `ACTOR -io-> FLOW -io-> FUNC` (or back, `FUNC -io-> FLOW -io-> ACTOR`), the FUNC a member of one of the UC's chains (`UC -compose-> FCHAIN -compose-> FUNC`). A direct `ACTOR -io-> UC` is rejected by R-18. No skill prompt (CR-SM-370): `se:author-uc` shows creating UCs and `se:author-actor` says to leave actors unwired — neither is this work.",
+        vorschlag: 'Lege für die Abläufe {n} die Funktionen an, die der Nutzer über einen Datenfluss auslöst.',
     },
     'UC-03': {
         plain: "A scenario says what should be possible but not how it runs → describe the steps as a chain of functions.",
         se: "`UC` with no `compose` trace to an `FCHAIN`. No behavioural scenario is declared.",
         prompt: "se:author-uc",
+        vorschlag: 'Beschreibe die Abläufe {n} als Kette von Funktionen.',
     },
     'UC-04': {
         plain: "A scenario has no real description, or still carries a placeholder like TBD → write what the user actually wants to achieve.",
         se: "`UC` description shorter than 10 characters or containing TBD/TODO/FIXME/placeholder/XXX. Description IS the goal (CR-150).",
         prompt: "se:author-uc",
+        vorschlag: 'Beschreibe das Ziel der Abläufe {n}.',
     },
     'VR-01': {
         plain: "A test exists but no result was ever recorded, so nobody knows if it passed → record the outcome.",

package/dist/se/rules.d.ts

@@ -81,6 +81,14 @@ export declare const ViolationContext: z.ZodObject<{
     parent_module: z.ZodOptional<z.ZodString>;
     current_description: z.ZodOptional<z.ZodString>;
     also_affects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    side_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        members: z.ZodArray<z.ZodString>;
+        cause: z.ZodEnum<{
+            "missing-link": "missing-link";
+            bag: "bag";
+        }>;
+        via: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>>>;
     trace_rejection: z.ZodOptional<z.ZodObject<{
         reason: z.ZodEnum<{
             "no-pattern": "no-pattern";
@@ -212,6 +220,14 @@ export declare const RuleViolation: z.ZodObject<{
         parent_module: z.ZodOptional<z.ZodString>;
         current_description: z.ZodOptional<z.ZodString>;
         also_affects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        side_components: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            members: z.ZodArray<z.ZodString>;
+            cause: z.ZodEnum<{
+                "missing-link": "missing-link";
+                bag: "bag";
+            }>;
+            via: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>>;
         trace_rejection: z.ZodOptional<z.ZodObject<{
             reason: z.ZodEnum<{
                 "no-pattern": "no-pattern";

package/dist/se/rules.js

@@ -35,6 +35,17 @@ export const ViolationContext = z.object({
      * unterschlagen.
      */
     also_affects: z.array(z.string()).optional(),
+    /**
+     * CR-SM-363 (FC-05): die NEBENKOMPONENTEN einer zerfallenen FCHAIN, je mit Ursache —
+     * `missing-link` (Haupt- und Nebenteil sind ueber eine FUNC ausserhalb der Kette verbunden;
+     * `via` nennt sie) oder `bag` (nur eine gemeinsame Quelle, parallele Dienste). EIN Befund je
+     * Kette (CR-SM-242), die Komponenten hier statt als n Befunde.
+     */
+    side_components: z.array(z.object({
+        members: z.array(z.string()),
+        cause: z.enum(['missing-link', 'bag']),
+        via: z.array(z.string()),
+    })).optional(),
     /**
      * CR-SM-341: der Ablehnungsgrund von R-18, maschinenlesbar statt nur als Satz.
      *
@@ -242,24 +253,15 @@ function funcMustSatisfyReq(graph) {
                 .map(st => idx.byId.get(st.target))
                 .filter((e) => !!e)
             : [];
-        // Also include constraints whose description mentions this func's name
-        const namePattern = fn.name.toLowerCase();
-        const matchingConstraints = allReqs.filter(r => r.kinds?.includes('non-functional') && r.description.toLowerCase().includes(namePattern));
         // CR-SM-346 (ITEM-2026-299): der Kandidatenkreis wird am META-MODELL gefiltert, nicht
-        // an einer zweiten, hier abgeschriebenen kinds-Liste. `FUNC -satisfy-> REQ` laesst nur
-        // BEHAVIOURAL_KINDS zu; bis hierher bot die Regel ALLE REQ an — gemessen an sigllm hatte
-        // damit KEINER von 33 Befunden einen legalen Kandidaten, und die Vorlage aus CR-SM-342
-        // gab korrekt `null` zurueck. 86 Befunde, 0 Empfehlungen: der Befund war unbedienbar.
+        // an einer zweiten, hier abgeschriebenen kinds-Liste — `isValidTrace` statt Eigenbau: eine
+        // Regel, die Kandidaten anbietet, die ihr eigenes Meta-Modell abweist, erzeugt Waste statt
+        // Fuehrung. `FUNC -satisfy-> REQ` laesst nur `functional` zu (CR-SM-366).
         //
-        // Besonders der `matchingConstraints`-Zweig zog gezielt `non-functional` herein — genau
-        // die Sorte, die das Muster abweist. Er bleibt stehen (ein REQ kann mehrere kinds tragen,
-        // und die Namensnennung ist ein echtes Relevanzsignal), aber er entscheidet nicht mehr
-        // ueber die Legalitaet.
-        //
-        // `isValidTrace` statt Eigenbau: eine Regel, die Kandidaten anbietet, die ihr eigenes
-        // Meta-Modell abweist, erzeugt Waste statt Fuehrung — und zwei Wahrheiten ueber dieselbe
-        // Grammatik sind genau der Defekt, den CR-SM-286/-302 beseitigt haben.
-        const candidates = [...new Map([...siblingReqs, ...matchingConstraints, ...allReqs].map(e => [e.id, e])).values()]
+        // CR-SM-366: der fruehere `matchingConstraints`-Zweig (non-functional-REQ, deren Text den
+        // FUNC-Namen nennt) ist entfallen. Er zog genau die Sorte herein, die das Muster abweist;
+        // seit ein REQ genau EIN kind traegt, konnte kein Treffer den Filter je passieren.
+        const candidates = [...new Map([...siblingReqs, ...allReqs].map(e => [e.id, e])).values()]
             .filter(r => isValidTrace({ source: 'FUNC', target: 'REQ', type: 'satisfy', targetKinds: r.kinds }));
         return {
             rule_id: 'R-02',
@@ -744,6 +746,12 @@ function decompositionBreadth(graph, policy) {
 // deshalb keine Zahl im Kontext und steuert nicht — sie ist Lesbarkeit, nicht Randbreite.
 // Eine Ebene ohne jedes Kind ist nicht ihr Fall: ein leeres MOD meldet R-23, eine FUNC ohne Kinder
 // ist ein Blatt.
+//
+// CR-SM-388 (ITEM-2026-731): die WURZEL ist ausgenommen — die Ebene direkt unter SYS, also beide
+// Zaehlungen mit SYS als Eltern (`SYS compose MOD` und der FUNC-Wurzelwald). Der Rat „in die Ebene
+// darueber aufloesen" ist dort nicht ausfuehrbar, ueber SYS liegt keine; und ein System aus einem
+// Modul oder einer Wurzelfunktion ist eine Architekturentscheidung, keine leere Abstraktion.
+// RD-04 (Obergrenze) gilt an der Wurzel weiter.
 // ---------------------------------------------------------------------------
 function decompositionNarrow(graph, policy) {
     const band = policy.decompositionBreadth;
@@ -751,7 +759,7 @@ function decompositionNarrow(graph, policy) {
         return [];
     const byId = indexOf(graph).byId;
     return breadthCounts(graph)
-        .filter(c => c.n < band.min)
+        .filter(c => c.n < band.min && byId.get(c.parentId)?.type !== 'SYS')
         .map(c => {
         const parent = byId.get(c.parentId);
         return {
@@ -827,7 +835,9 @@ function actorMustHaveTrace(graph) {
         severity: 'warning',
         element_id: a.id,
         message: `${a.id} has no io traces (disconnected actor)`,
-        fix_hint: 'Link to a UC or FLOW via io trace',
+        // CR-SM-371: ein ACTOR hat genau zwei legale Kanten (ACTOR -io-> FLOW, FLOW -io-> ACTOR);
+        // der UC wird ueber den FLOW an einer FUNC seiner Kette erreicht, nie direkt (R-18).
+        fix_hint: `Wire the actor through a FLOW via graph_mutate Format-E: \`${a.id} -io-> FLOW-x\` (it sends) or \`FLOW-x -io-> ${a.id}\` (it receives), plus \`FLOW-x -io-> FUNC-y\` or \`FUNC-y -io-> FLOW-x\` for a FUNC in the use case's chain — never an io edge to the UC itself`,
         context: {
             element_type: a.type,
             element_name: a.name,
@@ -927,7 +937,6 @@ function validTracePattern(graph) {
         });
         if (!why)
             return [];
-        const { detail, hint } = explainRejection(why, t, src, tgt);
         // CR-SM-341: derselbe Grund, den `detail` in Prosa giesst — hier zusaetzlich als Struktur.
         // Keine zweite Rechnung: `why` liegt vor, die Alternativen befragen `isValidTrace`.
         const shape = {
@@ -936,6 +945,7 @@ function validTracePattern(graph) {
             targetKinds: idx.byId.get(t.target)?.kinds,
         };
         const alt = admittingAlternatives(shape);
+        const { detail, hint } = explainRejection(why, t, src, tgt, alt.sources);
         const where = why.reason === 'no-pattern' ? undefined : why.pattern.where;
         return [{
                 rule_id: 'R-18',
@@ -970,7 +980,7 @@ function validTracePattern(graph) {
  * `kinds` steht da und passt nicht (Kante heben oder Kind korrigieren). Wer das nicht
  * unterscheiden kann, sucht am falschen Ende.
  */
-function explainRejection(why, t, src, tgt) {
+function explainRejection(why, t, src, tgt, admittingSources) {
     if (why.reason === 'no-pattern') {
         return {
             detail: `${src} → ${tgt} is not a valid ${t.type} pattern`,
@@ -991,7 +1001,11 @@ function explainRejection(why, t, src, tgt) {
         }
         : {
             detail: `${admits}, but ${end} declares {${[...why.declared].sort().join(', ')}}`,
-            hint: `Correct '${where.field}' on ${end}, or use a source type whose ${t.type} pattern admits them (FCHAIN carries every kind)`,
+            // CR-SM-366: den Erfueller NENNEN statt "FCHAIN carries every kind" — das galt nie fuer
+            // die Code-Bindung und gilt seit dem FCHAIN-where gar nicht mehr.
+            hint: admittingSources.length > 0
+                ? `Correct '${where.field}' on ${end}, or ${t.type} it from ${admittingSources.join(' | ')} — the pattern admitting {${[...why.declared].sort().join(', ')}}`
+                : `Correct '${where.field}' on ${end} to a subset of {${allowed}} — no source type admits {${[...why.declared].sort().join(', ')}} (retired kind? split a mixed REQ)`,
         };
 }
 /**
@@ -1270,7 +1284,7 @@ function funcMustHaveCodeBinding(graph) {
                 severity: 'warning',
                 element_id: fn.id,
                 message: `${fn.id} is not fully realized — unbound compose ${leafList.length === 1 ? 'child' : 'children'}: ${leafList.join(', ')}`,
-                fix_hint: `Realize the leaves ${leafList.join(', ')} (graph_realize) — the parent inherits their binding`,
+                fix_hint: `Bind the leaves via graph_mutate Format-E (${leafList.map((id) => `\`~ ${id} @realRef {"file":…,"symbol":…}\``).join(', ')}) — the parent inherits their binding`,
                 context: { element_type: fn.type, element_name: fn.name },
             });
         }
@@ -1300,6 +1314,10 @@ function funcMustHaveCodeBinding(graph) {
 //       Co-adjacency at a shared FLOW is not an asserted interface — treating it
 //       as one produced P·C findings per hub FLOW and made reuse the expensive
 //       choice. The FCHAIN is the modelled claim; the test is owed on the claim.
+//       CR-SM-376: second way to cover a chain. Since CR-SM-366 an FCHAIN carries
+//       only NFRs; its effect is covered through its members when EVERY member
+//       FUNC (FCHAIN ─compose→ FUNC) satisfies at least one REQ. Verifying those
+//       member REQs is R-01's job, not R-21's.
 // ---------------------------------------------------------------------------
 function fchainMustHaveIntegrationTest(graph, policy) {
     const idx = indexOf(graph);
@@ -1333,6 +1351,22 @@ function fchainMustHaveIntegrationTest(graph, policy) {
             testedChains.add(t.source);
         }
     }
+    // CR-SM-376: der zweite Weg — die Kette ist ueber ihre Glieder gedeckt, wenn JEDE Glied-FUNC
+    // (direkte FCHAIN -compose-> FUNC, dieselbe Definition wie `chainsByFunc`) eine REQ erfuellt.
+    // `unmetMembers` liefert die Glieder ohne REQ; leer = gedeckt. Eine Kette ohne Glied kann hier
+    // nicht auftauchen: ZWEIG 2 hat mindestens die beiden Enden der Uebergabe als Glieder.
+    const funcsWithReq = new Set(idx.tracesOfType('satisfy').filter(t => isFunc(t.source) && typeOf.get(t.target) === 'REQ').map(t => t.source));
+    const membersOf = new Map();
+    for (const [fn, chains] of chainsOf) {
+        for (const ch of chains) {
+            const list = membersOf.get(ch);
+            if (list)
+                list.push(fn);
+            else
+                membersOf.set(ch, [fn]);
+        }
+    }
+    const unmetMembers = (ch) => (membersOf.get(ch) ?? []).filter(fn => !funcsWithReq.has(fn)).sort();
     // CR-SM-313: die Infrastruktur-Ausnahme. Die ZAHL kommt aus der Kennzahl (CR-SM-314), nicht
     // aus einer zweiten Rechnung — eine Uebergabe an eine Funktion, die quer durch alle Ketten
     // laeuft, ist kein fehlender Integrationstest, sondern ein Bus. `null` = keine Ausnahme.
@@ -1372,8 +1406,9 @@ function fchainMustHaveIntegrationTest(graph, policy) {
             });
             continue;
         }
-        // ZWEIG 2 — gemeinsame Kette, aber keine davon geprueft: Befund an der Kette. Unveraendert.
-        if (shared.some(ch => testedChains.has(ch)))
+        // ZWEIG 2 — gemeinsame Kette, aber keine davon gedeckt: Befund an der Kette. Gedeckt heisst
+        // (a) verifizierte Ketten-REQ oder (b, CR-SM-376) jede Glied-FUNC erfuellt eine REQ.
+        if (shared.some(ch => testedChains.has(ch) || unmetMembers(ch).length === 0))
             continue;
         const anchor = shared[0];
         const key = `${anchor}|${p}>${c}`;
@@ -1385,8 +1420,8 @@ function fchainMustHaveIntegrationTest(graph, policy) {
             rule_id: 'R-21',
             severity: 'warning',
             element_id: anchor,
-            message: `${anchor} has no integration test covering connection ${p} → ${c}`,
-            fix_hint: 'Verify an FCHAIN-satisfied REQ with an integration TEST',
+            message: `${anchor} has no integration test covering connection ${p} → ${c}; member FUNCs without a REQ: ${unmetMembers(anchor).join(', ')}`,
+            fix_hint: 'Give each member FUNC of the chain a REQ it satisfies (FUNC -satisfy-> REQ), or attach an end-to-end non-functional REQ to the chain (FCHAIN -satisfy-> REQ) and verify it with an integration TEST',
             context: { element_type: anchorEl?.type, element_name: anchorEl?.name },
         });
     }
@@ -1650,7 +1685,7 @@ export const V3_RULES = [
     { id: 'R-19', name: 'Runnable TEST binding', severity: 'warning', evaluate: testMustHaveRunnableBinding, domain: ['TEST'] },
     { id: 'R-29', name: 'Test file exclusivity', severity: 'error', evaluate: testFileExclusivity, domain: ['TEST'] },
     { id: 'R-20', name: 'FUNC realRef binding', severity: 'warning', evaluate: funcMustHaveCodeBinding, domain: ['FUNC'] },
-    { id: 'R-21', name: 'FUNC↔FUNC handover needs a shared chain and an integration test', severity: 'warning', evaluate: fchainMustHaveIntegrationTest, domain: ['FCHAIN', 'FUNC'] },
+    { id: 'R-21', name: 'FUNC↔FUNC handover needs a shared chain covered by member REQs or an integration test', severity: 'warning', evaluate: fchainMustHaveIntegrationTest, domain: ['FCHAIN', 'FUNC'] },
     { id: 'R-22', name: 'FUNC must be allocated to MOD', severity: 'warning', evaluate: funcMustBeAllocated, domain: ['FUNC'] },
     { id: 'R-23', name: 'MOD must have allocated FUNC', severity: 'warning', evaluate: modMustHaveAllocatedFunc, domain: ['MOD'] },
     { id: 'R-26', name: 'SCHEMA must have realRef', severity: 'warning', evaluate: schemaMustHaveSchemaRef, domain: ['SCHEMA'] },
@@ -1658,7 +1693,7 @@ export const V3_RULES = [
     { id: 'RD-01', name: 'Unresolved requirement', severity: 'warning', evaluate: unresolvedRequirement, domain: ['REQ'] },
     { id: 'RD-02', name: 'Decomposition consistency', severity: 'warning', evaluate: decompositionConsistency, domain: ['REQ'] },
     { id: 'RD-04', name: 'Decomposition breadth', severity: 'warning', evaluate: decompositionBreadth, domain: ['FUNC', 'MOD', 'SYS'] },
-    { id: 'RD-05', name: 'Decomposition too narrow', severity: 'warning', evaluate: decompositionNarrow, domain: ['FUNC', 'MOD', 'SYS'] },
+    { id: 'RD-05', name: 'Decomposition too narrow', severity: 'warning', evaluate: decompositionNarrow, domain: ['FUNC', 'MOD'] },
     { id: 'MS-01', name: 'Milestone empty scope', severity: 'warning', evaluate: msEmptyScope, domain: ['MS'] },
     { id: 'MS-02', name: 'Milestone dangling dependency', severity: 'warning', evaluate: msDanglingDependency, domain: ['MS'] },
     { id: 'R-30', name: 'FUNC leaf must belong to a function chain', severity: 'warning', evaluate: funcMustBeInEffectChain, domain: ['FUNC'] },

package/dist/se/uc-quality-rules.js

@@ -1,4 +1,5 @@
 import { indexOf } from './graph-index.js';
+import { hasPlaceholder } from './placeholder.js';
 // ---------------------------------------------------------------------------
 // UC-01: UC must have compose→REQ trace (CR-165: satisfy UC→REQ is invalid per meta-model)
 // ---------------------------------------------------------------------------
@@ -94,13 +95,12 @@ export function uc03HasScenario(graph) {
 // UC-04: UC must have meaningful description (CR-150: description = goal)
 // ---------------------------------------------------------------------------
 const UC_DESC_MIN_LEN = 10;
-const PLACEHOLDER_RE = /\b(tbd|todo|fixme|placeholder|xxx)\b/i;
 export function uc04GoalDefined(graph) {
     return graph.elements
         .filter(e => e.type === 'UC')
         .filter(uc => {
         const d = uc.description?.trim() ?? '';
-        return d.length < UC_DESC_MIN_LEN || PLACEHOLDER_RE.test(d);
+        return d.length < UC_DESC_MIN_LEN || hasPlaceholder(d);
     })
         .map(uc => ({
         rule_id: 'UC-04',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sigloch/contracts",
-  "version": "10.12.0",
+  "version": "10.14.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",