feat(programs): start the Environmental Knowledge Program — domains, not architecture
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 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
@@ -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.
|
||||
@@ -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).
|
||||
@@ -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)"),
|
||||
])
|
||||
|
||||
@@ -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)")
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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"]
|
||||
Reference in New Issue
Block a user