Merge pull request 'feat: start the Environmental Knowledge Program (law-first domain, not architecture)' (#22) from feat/environmental-knowledge-program into main

backend-compliance/knowledge/programs/README.md

@@ -0,0 +1,51 @@
+# Domain Knowledge Programs — from architecture to domains
+
+**The architecture is stable. From here the value comes from DOMAINS, not more software.**
+The runtime architecture (scope, regulatory map, capability delta, optimization, playbooks, intake,
+production, completeness) is frozen. A new regulatory domain is a **data + knowledge** project that
+extends every existing view automatically — no new runtime framework (see ADR-008, Freeze v1.0).
+
+## The production line (reusable for EVERY domain)
+
+```
+Regulatory Corpus → Obligations → Capabilities → Transition Patterns → Playbooks → Reference Scenarios → Completeness
+```
+
+Each domain delivers the SAME artifacts. Once they land, the existing engines automatically extend:
+Scope · Gap · Capability Delta · Optimization · Playbooks · Reference Scenarios · Regulatory Completeness.
+
+## Law-first (a deliberate ordering)
+
+Start from the **law**, not from a management system. A management system (e.g. ISO 14001) is NOT
+the domain — it is one possible source state. The customer asks *„welche Anforderungen gelten für mein
+Produkt?"*, not *„wie komme ich von ISO 14001 weg?"*. So the order is:
+
+```
+Recht → Obligations → Capabilities → (Managementsystem) → Delta
+```
+
+A management-system→corpus transition pattern is built LAST, once BOTH sides are known.
+
+## Ownership per stage (coordinate via the board, do not duplicate)
+
+| Stage | Artifact | Owner |
+|---|---|---|
+| B1 Corpus + Obligations | legal sources, obligations registry | **Legal Knowledge / Obligation Registry** |
+| B2 Capability Model | new capabilities in the Master Capability Registry | **Compliance Execution** |
+| B3 Transition Patterns | source-state → corpus delta patterns | **Reasoning (Knowledge Acquisition)** |
+| Playbooks | implementation playbooks per capability | **Reasoning** |
+| Reference Scenarios | canonical regression + expected outcomes | **Reasoning** |
+| Completeness | corpus-status registry per domain | **Reasoning / curation** |
+
+## Programs (planned)
+
+| Program | File | Status |
+|---|---|---|
+| Environmental Knowledge Program | `environmental.yaml` | started (B1 handed off) |
+| Automotive Knowledge Program | _planned_ | — |
+| OT / IEC 62443 Knowledge Program | _planned_ | — |
+| Functional Safety Knowledge Program | _planned_ | — |
+
+Each program is a machine-readable definition (`*.yaml`) consumed by the reference suite to track its
+progress; future sessions flip stage `status` as artifacts land, and the Completeness engine reports
+the domain flipping `unsupported → validated` automatically.

backend-compliance/knowledge/programs/environmental.yaml

@@ -0,0 +1,57 @@
+# Environmental Knowledge Program — a regulatory DOMAIN, not an ISO-14001 project.
+# Machine-readable program definition consumed by the reference suite to track progress.
+# LAW-FIRST: Umweltrecht -> Obligations -> Capabilities -> ISO 14001 -> Delta (never the reverse).
+
+id: PROG-environmental
+name: "Environmental Knowledge Program"
+customer_question: "Welche Umweltanforderungen gelten für mein Produkt (z. B. Industriespülmaschine)?"
+status: started                 # planned | started | in_progress | complete
+
+principle: >
+  ISO 14001 ist KEIN Umweltrecht, sondern ein Managementsystem. Wir starten beim Recht und fragen
+  erst danach, welche vorhandenen Managementsysteme davon wahrscheinlich schon etwas abdecken.
+
+# the reusable production line, instantiated for this domain
+blueprint: [corpus, obligations, capabilities, transition_patterns, playbooks, reference_scenarios, completeness]
+
+stages:
+  - id: B1
+    name: "Environmental Regulatory Corpus"
+    owner: "Legal Knowledge / Obligation Registry"
+    status: open                # handed off — not built here
+    note: "Zunächst NUR Rechtsquellen + Pflichten (noch keine ISO, keine Capabilities)."
+    areas:                      # the six environmental obligation areas the customer actually faces
+      - water                   # Wasser / Abwasser
+      - chemicals               # Chemikalien (REACH/CLP)
+      - emissions               # Emissionen
+      - energy                  # Energie
+      - waste                   # Abfall
+      - product_responsibility  # Produktverantwortung
+
+  - id: B2
+    name: "Environmental Capability Model"
+    owner: "Compliance Execution"
+    status: open                # depends on B1; Registry grows here
+    depends_on: [B1]
+    capabilities:
+      - chemical_management
+      - wastewater_management
+      - emissions_monitoring
+      - hazardous_substance_management
+      - energy_data_capture
+      - environmental_incident_management
+
+  - id: B3
+    name: "Transition Patterns (ISO 14001 -> Environmental Corpus)"
+    owner: "Reasoning (Knowledge Acquisition)"
+    status: blocked             # LAST — only once both sides (corpus + capabilities) are known
+    depends_on: [B1, B2]
+    note: "Erst jetzt sinnvoll: ISO 14001 als Quellzustand gegen den Umwelt-Korpus (User: law-first)."
+
+# once B1-B3 land these extend AUTOMATICALLY via the existing engines (no new runtime architecture)
+downstream_auto: [playbooks, reference_scenarios, optimization, scope, capability_delta, completeness]
+
+acceptance: >
+  Regulatory Completeness kippt `Environmental` von unsupported/open auf assessed; die sechs Bereiche
+  sind als Obligations + Capabilities im validierten Korpus, das ISO-14001-Delta als Transition Pattern.
+  Messbar an der Reference Suite (Environmental-Zelle UNSUPPORTED -> PASS).

backend-compliance/reference_scenarios/_helpers.py

@@ -139,3 +139,38 @@ def completeness_section() -> None:
         ("Begründete Ausschlüsse (Korpus/Anwendbarkeit)", "PASS", "%d Ausschlüsse, alle mit Grund" % len(rep.exclusions)),
         ("Fortschritts-Doku je Domäne", "PASS", "Environmental offen→validated bei Korpus-Landung"),
     ])
+
+
+def domain_programs_section(base_dir) -> None:
+    """Render the Domain Knowledge Programs section (kept here so generate.py stays under the LOC budget)."""
+    import os
+    import yaml
+    from compliance.completeness import assess_completeness
+
+    pdir = os.path.join(base_dir, "..", "knowledge", "programs")
+    progs = [yaml.safe_load(open(os.path.join(pdir, f), encoding="utf-8"))
+             for f in sorted(os.listdir(pdir)) if f.endswith(".yaml")]
+    w("## Domain Knowledge Programs — ab jetzt Domänen, nicht Architektur")
+    w("")
+    w('_Die Runtime-Architektur ist eingefroren. Eine neue Domäne = Daten + Wissen, die jede Sicht automatisch erweitern. Produktionsstraße: Corpus→Obligations→Capabilities→Transition→Playbooks→Reference→Completeness. **Law-first: Recht → Pflichten → Capabilities → Managementsystem → Delta.**_')
+    w("")
+    for p in progs:
+        w("**%s** — _%s_ (status: `%s`)" % (p["name"], p["customer_question"], p["status"]))
+        w("")
+        w("| Stufe | Artefakt | Owner | Status |")
+        w("|---|---|---|---|")
+        for s in p.get("stages", []):
+            w("| %s | %s | %s | **%s** |" % (s["id"], s["name"], s["owner"], s["status"]))
+        w("")
+        areas = next((s.get("areas", []) for s in p.get("stages", []) if s.get("id") == "B1"), [])
+        if areas:
+            rep = assess_completeness(identified_regulations=areas, corpus_status={})   # all unknown -> open baseline
+            w("- **Baseline (Completeness):** %s — die 6 Bereiche: %s" % (rep.completeness_summary, ", ".join(areas)))
+        w("")
+    w("_Jedes Programm liefert dieselben Artefakte; Status `open/blocked` kippt automatisch, wenn die Stufen landen — Reference Suite + Completeness dokumentieren den Fortschritt je Domäne._")
+    w("")
+    coverage_table([
+        ("Domain Program Blueprint (wiederverwendbar)", "PASS", "Corpus→…→Completeness, law-first, Ownership je Stufe"),
+        ("Environmental Program (Daten)", "PASS", "B1@Legal-KG · B2@Execution · B3@Reasoning (blocked)"),
+        ("Phase B = Domänen, keine Architektur", "PASS", "kein neues Runtime-Framework (Freeze, ADR-008)"),
+    ])

backend-compliance/reference_scenarios/generate.py

@@ -46,7 +46,7 @@ import yaml
 
 from _helpers import (  # noqa: E402  (script-dir module; keeps generate.py under the LOC budget)
     OUT, ROLLUP, Row, w, coverage_table, reg_map_block, unsupported_block, interp_status,
-    knowledge_intake_section, completeness_section,
+    knowledge_intake_section, completeness_section, domain_programs_section,
 )
 
 ISO_MAP = {"ISO27001": CapabilityMappingEntry(
@@ -466,6 +466,7 @@ coverage_table([
 
 knowledge_intake_section(os.path.dirname(__file__))   # Knowledge Intake (impact triage) — kept in _helpers for LOC
 completeness_section()                                 # Regulatory Completeness — kept in _helpers for LOC
+domain_programs_section(os.path.dirname(__file__))     # Domain Knowledge Programs — kept in _helpers for LOC
 
 # ── Epics + roll-up ───────────────────────────────────────────────────────
 w("## Gaps → Epics (Backlog — nur erfasst, NICHT implementiert)")

backend-compliance/reference_scenarios/reference_scenario_suite_v1.md

@@ -365,6 +365,30 @@ _Sobald der Umwelt-Korpus (ISO 14001 etc.) landet, kippt `Environmental` automat
 | Begründete Ausschlüsse (Korpus/Anwendbarkeit) | **PASS** | 3 Ausschlüsse, alle mit Grund |
 | Fortschritts-Doku je Domäne | **PASS** | Environmental offen→validated bei Korpus-Landung |
 
+## Domain Knowledge Programs — ab jetzt Domänen, nicht Architektur
+
+_Die Runtime-Architektur ist eingefroren. Eine neue Domäne = Daten + Wissen, die jede Sicht automatisch erweitern. Produktionsstraße: Corpus→Obligations→Capabilities→Transition→Playbooks→Reference→Completeness. **Law-first: Recht → Pflichten → Capabilities → Managementsystem → Delta.**_
+
+**Environmental Knowledge Program** — _Welche Umweltanforderungen gelten für mein Produkt (z. B. Industriespülmaschine)?_ (status: `started`)
+
+| Stufe | Artefakt | Owner | Status |
+|---|---|---|---|
+| B1 | Environmental Regulatory Corpus | Legal Knowledge / Obligation Registry | **open** |
+| B2 | Environmental Capability Model | Compliance Execution | **open** |
+| B3 | Transition Patterns (ISO 14001 -> Environmental Corpus) | Reasoning (Knowledge Acquisition) | **blocked** |
+
+- **Baseline (Completeness):** Identifiziert 6 · bewertet 0 · offen 6 · Unsicherheiten 0 · Begründung ja — die 6 Bereiche: water, chemicals, emissions, energy, waste, product_responsibility
+
+_Jedes Programm liefert dieselben Artefakte; Status `open/blocked` kippt automatisch, wenn die Stufen landen — Reference Suite + Completeness dokumentieren den Fortschritt je Domäne._
+
+**Architecture Coverage**
+
+| Layer | Status | Hinweis |
+|---|---|---|
+| Domain Program Blueprint (wiederverwendbar) | **PASS** | Corpus→…→Completeness, law-first, Ownership je Stufe |
+| Environmental Program (Daten) | **PASS** | B1@Legal-KG · B2@Execution · B3@Reasoning (blocked) |
+| Phase B = Domänen, keine Architektur | **PASS** | kein neues Runtime-Framework (Freeze, ADR-008) |
+
 ## Gaps → Epics (Backlog — nur erfasst, NICHT implementiert)
 
 | Epic | Titel | schliesst Coverage-Luecke |
@@ -376,6 +400,6 @@ _Sobald der Umwelt-Korpus (ISO 14001 etc.) landet, kippt `Environmental` automat
 
 ## Suite-Status (Roll-up)
 
-- Coverage-Zellen gesamt: **44**
+- Coverage-Zellen gesamt: **47**
-- PASS: **33** · PARTIAL: 3 · UNSUPPORTED: 1 · TODO: 6 · N/A: 1 · NEEDS_FACTS: 0
+- PASS: **36** · PARTIAL: 3 · UNSUPPORTED: 1 · TODO: 6 · N/A: 1 · NEEDS_FACTS: 0
 - Fortschritt = PASS-Anteil steigt, wenn Epics RS-001…004 landen (objektiver Maßstab, kein LOC).

backend-compliance/tests/test_domain_programs.py

@@ -0,0 +1,55 @@
+"""Characterization test for the Environmental Knowledge Program definition (data, not code).
+
+Pins the LAW-FIRST contract: the domain is ordered Corpus(B1) -> Capabilities(B2) -> Transition(B3),
+not the reverse; ownership is assigned per stage; B3 (ISO 14001 -> corpus) is blocked until both sides
+exist. If a future edit reverses the order or drops an owner, this test fails.
+"""
+
+from __future__ import annotations
+
+import os
+
+import yaml
+
+_PROG = os.path.join(os.path.dirname(__file__), "..", "knowledge", "programs", "environmental.yaml")
+
+
+def _program():
+    with open(_PROG, encoding="utf-8") as f:
+        return yaml.safe_load(f)
+
+
+def test_blueprint_is_the_reusable_production_line():
+    p = _program()
+    assert p["blueprint"] == ["corpus", "obligations", "capabilities", "transition_patterns",
+                              "playbooks", "reference_scenarios", "completeness"]
+
+
+def test_stages_are_law_first_in_order():
+    stages = _program()["stages"]
+    assert [s["id"] for s in stages] == ["B1", "B2", "B3"]          # corpus -> capabilities -> transition
+    assert "Corpus" in stages[0]["name"] and "Transition" in stages[2]["name"]
+
+
+def test_ownership_assigned_per_stage():
+    by = {s["id"]: s for s in _program()["stages"]}
+    assert "Legal Knowledge" in by["B1"]["owner"]                   # corpus + obligations
+    assert "Compliance Execution" in by["B2"]["owner"]             # capability model
+    assert "Reasoning" in by["B3"]["owner"]                        # transition patterns
+
+
+def test_transition_is_blocked_until_both_sides_known():
+    b3 = {s["id"]: s for s in _program()["stages"]}["B3"]
+    assert b3["status"] == "blocked"
+    assert b3["depends_on"] == ["B1", "B2"]                         # built LAST (law-first)
+
+
+def test_b1_covers_the_six_environmental_areas():
+    b1 = {s["id"]: s for s in _program()["stages"]}["B1"]
+    assert set(b1["areas"]) == {"water", "chemicals", "emissions", "energy", "waste", "product_responsibility"}
+
+
+def test_program_is_a_domain_not_an_iso_project():
+    p = _program()
+    assert "Umweltanforderungen" in p["customer_question"]          # starts from the law, not ISO 14001
+    assert "ISO 14001 ist KEIN Umweltrecht" in p["principle"]

docs-src/architecture/adr/ADR-008-from-architecture-to-domains.md

@@ -0,0 +1,52 @@
+# ADR-008: From architecture to domains — Phase B as law-first Knowledge Programs
+
+- **Status:** Accepted
+- **Datum:** 2026-06-27
+- **Typ:** Architektur- / Strategie-Entscheidung
+- **Bezug:** [ADR-005](ADR-005-knowledge-production-pipeline.md), [ADR-006](ADR-006-knowledge-intake.md), [ADR-007](ADR-007-regulatory-completeness.md), [ADR-002](ADR-002-transition-is-data-not-architecture.md), Architektur-Freeze v1.0, [[regulatory-intelligence-vision]]
+
+## Kontext
+
+Die Plattform ist außergewöhnlich vollständig: Produkt-/Company-Profil, Scope, Regulatory Map,
+Interpretation, Capability Registry, Capability Delta, Optimization, Playbooks, Knowledge Intake,
+Knowledge Production, Regulatory Completeness, Reference Scenarios. **Der Engpass ist nicht mehr
+Software, sondern: „Ist das Wissen fachlich richtig und vollständig?"**
+
+Damit endet die Plattformentwicklung und die eigentliche Wissensentwicklung beginnt. Der
+Wettbewerbsvorteil entsteht ab jetzt aus Qualität und Tiefe des Korpus, nicht aus mehr Software.
+
+## Entscheidung
+
+1. **Die Runtime-Architektur wird bewusst stabil gehalten. Kein weiteres Runtime-Framework.**
+   Phase B fügt KEINE Architektur hinzu — sie fügt **Domänen** (Daten + Wissen) hinzu.
+
+2. **Phase B wird in Domain Knowledge Programs organisiert, nicht in einzelne Regelwerk-Features.**
+   Jedes Programm liefert dieselbe Produktionsstraße:
+   `Regulatory Corpus → Obligations → Capabilities → Transition Patterns → Playbooks →
+   Reference Scenarios → Completeness`.
+   Geplant: Environmental · Automotive · OT/IEC 62443 · Functional Safety.
+
+3. **Law-first.** Ein Managementsystem (z. B. ISO 14001) ist NICHT die Domäne, sondern ein möglicher
+   Quellzustand. Reihenfolge: **Recht → Obligations → Capabilities → (Managementsystem) → Delta.**
+   Der Kunde fragt „welche Anforderungen gelten für mein Produkt?", nicht „wie komme ich von ISO 14001 weg?".
+   Das Quellzustand→Korpus-Transition-Pattern entsteht ZULETZT, wenn beide Seiten bekannt sind.
+
+4. **Erstes Programm: Environmental Knowledge Program** (`knowledge/programs/environmental.yaml`),
+   als vollständige Domäne mit denselben Artefakten wie CRA/MaschinenVO. Stufen:
+   **B1 Environmental Regulatory Corpus** (Wasser/Chemikalien/Emissionen/Energie/Abfall/
+   Produktverantwortung — nur Recht + Pflichten) → **B2 Environmental Capability Model** →
+   **B3 Transition Patterns (ISO 14001 → Korpus)**.
+
+## Konsequenzen
+
+- **Programme statt Features:** jedes Programm ist eine maschinenlesbare Definition (`programs/*.yaml`),
+  deren Stufen-Status kippt, wenn Artefakte landen. Die Reference Suite + Completeness dokumentieren
+  den Fortschritt je Domäne automatisch (Environmental-Zelle `unsupported → validated`).
+- **Ownership-Handoffs (Board):** **B1 → Legal Knowledge / Obligation Registry**,
+  **B2 → Compliance Execution** (Capability Registry wächst), **B3 + Playbooks + Reference Scenarios →
+  Reasoning**. Keine Session baut die Artefakte einer anderen; Koordination über das Board.
+- **Jede neue Domäne erweitert AUTOMATISCH** Scope, Gap, Capability Delta, Optimization, Playbooks,
+  Reference Scenarios und Completeness — **ohne Änderung der Runtime-Architektur**. Genau das Ziel,
+  das der Freeze v1.0 erreichen sollte.
+- **Reifegrad:** bis hierher wurde Architektur gebaut; ab jetzt werden Domänen gebaut.
+- Diese ADR ist non-runtime → kein Deploy (siehe [ADR-001](ADR-001-runtime-deploy-policy.md)).