From 9c02c2c4a2cff32b5818a14603daf6ffbec75128 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Sat, 27 Jun 2026 14:36:03 +0200 Subject: [PATCH] =?UTF-8?q?feat(programs):=20start=20the=20Environmental?= =?UTF-8?q?=20Knowledge=20Program=20=E2=80=94=20domains,=20not=20architect?= =?UTF-8?q?ure?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The architecture is stable; from here the value comes from DOMAINS, not more software. Phase B is organized as law-first Domain Knowledge Programs, each delivering the same production line: Corpus -> Obligations -> Capabilities -> Transition Patterns -> Playbooks -> Reference Scenarios -> Completeness. No new runtime framework (Freeze v1.0). - knowledge/programs/README.md: reusable Domain Program blueprint (production line, per-stage ownership, law-first ordering, planned programs Environmental/Automotive/IEC62443/Functional-Safety). - knowledge/programs/environmental.yaml: the Environmental domain as DATA. Law-first: B1 Environmental Regulatory Corpus (water/chemicals/emissions/energy/waste/product-responsibility — law + obligations only) -> B2 Capability Model -> B3 Transition Patterns (ISO 14001 -> corpus, built LAST). ISO 14001 is a source state, NOT the domain. - Ownership handoffs: B1 -> Legal Knowledge, B2 -> Compliance Execution, B3+/playbooks/reference -> Reasoning. Coordinate via the board; no session builds another's artifacts. - reference suite: "Domain Knowledge Programs" section renders the program stages + a measurable Completeness baseline (6 areas, 0 assessed today) that flips automatically as stages land. - ADR-008: from architecture to domains; Phase B as law-first programs; architecture frozen. 6 program-contract tests (law-first order + ownership pinned), check-loc 0. Knowledge data + ADR + reference harness = non-runtime -> no deploy (ADR-001). No new module, no runtime change. Co-Authored-By: Claude Opus 4.7 --- .../knowledge/programs/README.md | 51 +++++++++++++++++ .../knowledge/programs/environmental.yaml | 57 +++++++++++++++++++ .../reference_scenarios/_helpers.py | 35 ++++++++++++ .../reference_scenarios/generate.py | 3 +- .../reference_scenario_suite_v1.md | 28 ++++++++- .../tests/test_domain_programs.py | 55 ++++++++++++++++++ .../ADR-008-from-architecture-to-domains.md | 52 +++++++++++++++++ 7 files changed, 278 insertions(+), 3 deletions(-) create mode 100644 backend-compliance/knowledge/programs/README.md create mode 100644 backend-compliance/knowledge/programs/environmental.yaml create mode 100644 backend-compliance/tests/test_domain_programs.py create mode 100644 docs-src/architecture/adr/ADR-008-from-architecture-to-domains.md diff --git a/backend-compliance/knowledge/programs/README.md b/backend-compliance/knowledge/programs/README.md new file mode 100644 index 00000000..4d0cd003 --- /dev/null +++ b/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. diff --git a/backend-compliance/knowledge/programs/environmental.yaml b/backend-compliance/knowledge/programs/environmental.yaml new file mode 100644 index 00000000..19209419 --- /dev/null +++ b/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). diff --git a/backend-compliance/reference_scenarios/_helpers.py b/backend-compliance/reference_scenarios/_helpers.py index 977fb745..c0744466 100644 --- a/backend-compliance/reference_scenarios/_helpers.py +++ b/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)"), + ]) diff --git a/backend-compliance/reference_scenarios/generate.py b/backend-compliance/reference_scenarios/generate.py index af2191ab..5f966ddd 100644 --- a/backend-compliance/reference_scenarios/generate.py +++ b/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)") diff --git a/backend-compliance/reference_scenarios/reference_scenario_suite_v1.md b/backend-compliance/reference_scenarios/reference_scenario_suite_v1.md index 64645d61..3b8e7b52 100644 --- a/backend-compliance/reference_scenarios/reference_scenario_suite_v1.md +++ b/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** -- PASS: **33** · PARTIAL: 3 · UNSUPPORTED: 1 · TODO: 6 · N/A: 1 · NEEDS_FACTS: 0 +- Coverage-Zellen gesamt: **47** +- 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). diff --git a/backend-compliance/tests/test_domain_programs.py b/backend-compliance/tests/test_domain_programs.py new file mode 100644 index 00000000..202f15f8 --- /dev/null +++ b/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"] diff --git a/docs-src/architecture/adr/ADR-008-from-architecture-to-domains.md b/docs-src/architecture/adr/ADR-008-from-architecture-to-domains.md new file mode 100644 index 00000000..57326ae9 --- /dev/null +++ b/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)).