Merge pull request 'docs(spec): Transition Reasoning v1 + MDQ Registry + ADR-002' (#8) from feat/transition-reasoning-spec into main

This commit is contained in:
pilotadmin
2026-06-27 07:03:43 +02:00
3 changed files with 317 additions and 0 deletions
@@ -0,0 +1,35 @@
# ADR-002: Transition = Data, not Architecture
- **Status:** Accepted
- **Datum:** 2026-06-27
- **Typ:** Architektur-Entscheidung
- **Bezug:** [`../transition-reasoning-spec-v1.md`](../transition-reasoning-spec-v1.md), [[regulatory-intelligence-vision]], Architektur-Freeze v1.0
## Kontext
BreakPilot wird von einem Compliance-Fragebogen zu einer **Transition Engine**: sie beantwortet
`Ausgangszustand → Zielzustand → Delta` (z. B. ISO 27001 → CRA, ISMS → TISAX, MaschRL → MaschVO).
Das Risiko: jede neue regulatorische „Reise" als Engine- oder Metamodell-Erweiterung zu bauen — das
würde die Architektur mit jeder Transition aufblähen und genau den Effekt erzeugen, den der
Architektur-Freeze verhindern soll.
## Entscheidung
1. **BreakPilot modelliert keine vollständigen Regelwerke als Interviews — sondern ausschließlich
den minimalen Informationsgewinn, der nötig ist, um einen vorhandenen Unternehmenszustand in
einen gewünschten regulatorischen Zielzustand zu überführen.**
2. **Jede neue Transition (z. B. ISO 27001 → CRA oder ISMS → TISAX) muss ausschließlich durch neue
Transition Patterns und Capability-/MDQ-Wissen (Daten) entstehen. Weder die Engine noch das
Metamodell dürfen dafür erweitert werden.**
## Konsequenzen
- Jede neue regulatorische Reise ist ein **Datenproblem**, kein Architekturproblem — exakt das Ziel
des Architektur-Freeze.
- Eine neue Transition besteht aus: neuen/wiederverwendeten **Master Delta Questions** (MDQ Registry),
einem **Transition Pattern** (nur MDQ-Referenzen) und **Required-Capability-Wissen** (Compliance
Execution). Kein neuer Code im Reasoning-Kern, keine neue Objektklasse im Metamodell.
- Wiederverwendung wird zum Normalfall: `IEC 62443 → CRA` teilt die meisten MDQs mit `ISO 27001 → CRA`
und ergänzt nur wenige neue.
- Diese ADR ist non-runtime → kein Deploy (siehe [ADR-001](ADR-001-runtime-deploy-policy.md)).
@@ -0,0 +1,139 @@
# Transition Reasoning — Spezifikation v1 (zweiter Reasoning-Modus)
- **Status:** Proposal / Spec v1 — 2026-06-27
- **Scope:** erweitert die Reasoning-Session um einen zweiten Modus; ersetzt nichts.
- **Freeze-konform:** additiv, **kein** neuer Graph, **keine** Basisklasse, **keine** Meta-Model-Klasse. Nur ein neues Paket + Daten.
## Paradigmenwechsel
BreakPilot beantwortet **Migrationsfragen**, nicht Regelwerk-Fragen. Nicht `Regelwerk → Gap`,
sondern **`Ausgangszustand → Zielzustand → Delta`**. Der Kunde sagt nicht „Hilf mir beim CRA",
sondern „Hilf mir von meinem heutigen Zustand zu meinem regulatorischen Zielzustand". Das Ziel ist
beliebig: `ISMS→TISAX`, `DSGVO→CRA`, `ISO9001→IATF16949`, `MaschRL→MaschVO`, `CRA2025→CRA2028`.
**Immer dieselbe Engine.**
Die Fragenbibliothek enthält **kein** ISO27001-Wissen, sondern **Wissen über die Differenz**:
nicht `ISO27001 → 100 Fragen`, sondern `ISO27001 → CRA → 12 Delta-Fragen`. Das ist viel kleiner.
## Verhältnis zur bestehenden Architektur (erweitern, NICHT ersetzen)
- Zweiter Modus **neben** Compliance Reasoning (`Produkt → Applicable → Obligations → Interpretation → Gap`). Neues Paket `backend-compliance/compliance/transition_reasoning/`.
- **Transition Reasoning ist RCI verallgemeinert.** RCI ist der Spezialfall „start = heute, target = heute + Änderung". Demo `CRA2025→CRA2028` **ist** RCI. `assess_transition` ist Geschwister von `assess_change`.
- **Wiederverwendung (kein neuer Kern):** Company Capability Profile (Phase 2A) = „habe" · Master Capability Registry (Phase 2C, `MCAP`) = stabile Identitäten + computed status · RCI = Delta-Mechanik · Reference Scenario Suite = Demos/Coverage **und** Lern-Signal für Information Gain.
## Kernobjekte (`compliance/transition_reasoning/`)
- **`TransitionContext`** — `start_state` {company_context, product_profile, known_regulations, known_certifications, declared/inferred/confirmed capabilities (aus Company 2A)} + `target_state` {target_regulation | target_certification | target_framework}.
- **`TransitionGoal`** — das Ziel; **nicht** regelwerk-beschränkt. Auflösbar zu **Required Capabilities** (Execution-owned, injiziert).
- **`TransitionAssessment`** (Output, **KEINE** Prozentzahlen) — je Required Capability `status ∈ {already_covered, probably_covered, needs_confirmation, missing, not_applicable, unsupported}` + die nächsten priorisierten MDQs.
## MDQ Registry — das Herzstück (4. Identitätsmaschine-Instanz)
Nach **Master Controls → Master Obligations → Master Capabilities** folgt **Master Delta Questions**.
Kernumkehr: **Die Frage ist nicht das Primäre — sie ist eine Messsonde, um Unsicherheit über
Capabilities zu reduzieren.** Jede Frage ist eine **identifizierbare, versionierte Wissenseinheit**.
**`MasterDeltaQuestion` (MDQ)** — stabile Identität, versioniert (genau wie Master Controls):
```yaml
id: MDQ-00017
question: "Wie lange stellen Sie Sicherheitsupdates für dieses Produkt bereit?"
answer_type: duration # | yes_no_document | enum | ...
verifies: [MCAP-00042] # welche Operational Capability(s) — Execution-owned
supports_obligations: [CRA.OBL.145, CRA.OBL.233]
transition_patterns: [ISO27001->CRA, IEC62443->CRA, TISAX->CRA] # nur Referenzen
expected_evidence: [support_policy, product_lifecycle_policy]
information_gain: HIGH # v1 statisch -> v2 computed (Entropy Reduction)
confidence_impact: # die Antwort MUTIERT den Trust State (via 2C-Policy)
document_uploaded: {MCAP-00042: "inferred -> confirmed"}
certs_that_reduce_probability: [ISO27001]
certs_that_do_not_reduce_probability: [ISO9001]
follow_up:
if_unknown: MDQ-00018
if_below_required: MDQ-00021
if_no: TRANSITION_BLOCK
# versionierung + lifecycle (wie Master Controls)
version: 1
status: active # | deprecated
created: <ts>; deprecated: null; redirect_to: null
provenance: {author, basis}
# v2, strukturell vorgesehen (NICHT v1): Lern-Statistik
observed: {asked: 0, changed_assessment: 0, useless: 0, average_information_gain: null}
```
- **`verifies → MCAP`:** die MDQ misst eine Operational Capability (Execution-owned `MCAP`-id). **Indexierung nach Capability, NICHT nach Regelwerk** → Wiederverwendung über Transitions.
- **`confidence_impact` = Bindeglied zur 2A/2C-Trust-Mechanik:** eine Antwort liefert eine Relation + Evidence (z. B. „Dokument hochgeladen" = `confirms` + `artifact`), aus der die bestehende `evaluate_relation`-Policy (Master Capability Registry) den Status **neu berechnet** (`inferred → confirmed`). Die MDQ **speichert keine Confidence** — sie erzeugt den Input, der computed-not-stored ausgewertet wird. Mutiert das Company Capability Profile (2A).
- **Identitäts-Disziplin = dieselbe wie Controls/Obligations/Capabilities:** `Candidate → Dedup → stabile MDQ-id → Relationen → Versionierung → Lifecycle (merge/deprecate/redirect)`. Ziel: **~300500 Master Delta Questions** statt tausender Einzelfragen.
## Transition Patterns (nur Referenzen)
Ein Pattern speichert **keine** Fragen-Texte, nur MDQ-Referenzen:
```text
TransitionPattern ISO27001 -> CRA = [MDQ-17, MDQ-21, MDQ-33, MDQ-52, ...]
```
Folge: eine neue Transition `IEC62443 -> CRA` = großteils Wiederverwendung + wenige neue MDQs
(z. B. 3 neue statt 30). Patterns liefern **Candidate Questions**; die **Product Map filtert**
(dieselbe Transition braucht beim Maschinenbauer andere Fragen als beim SaaS-Unternehmen).
## Algorithmus — Delta-Interview als Optimierung
1. `TransitionGoal` → Required Capabilities (MCAP-Set) — **Execution, injiziert**.
2. `have` = Company Capability Profile (confirmed inferred declared) — **2A**.
3. Delta je Required Capability → status; unsichere (`probably_covered` / `needs_confirmation` / `missing`) bleiben offen.
4. Candidate-MDQs aus dem/den Transition Pattern(s), **gefiltert durch die Product Map**.
5. **Nicht sequenziell** — die Engine wählt iterativ die MDQ mit dem **höchsten erwarteten Informationsgewinn** für DIESEN Kunden (Entropy Reduction über die unsicheren Required Capabilities). Antwort → `confidence_impact` → Profil aktualisiert → neu priorisieren. Abbruch, wenn keine MDQ mehr nennenswert Unsicherheit reduziert (**Ziel: 1020 Fragen, nicht 150**).
6. Ergebnis: aktualisiertes Capability Profile → `TransitionAssessment`.
**Information Gain (deterministisch + erklärbar):** v1 = `HIGH/MEDIUM/LOW` bzw. deterministischer Score
= #unsichere Required Capabilities, die die Antwort auflöst × #abhängige Ziel-Obligations ( Redundanz).
v2 = verfeinert aus `observed`-Statistik (asked / changed_assessment / useless) realer Kunden +
Reference-Suite — aber **erklärbar, kein opaker ML-Score** (sonst die „0.58-Theater"-Falle). Gespeichert
werden Statistik-Fakten, **abgeleitet** wird der Score → computed-not-stored.
## Ownership (Freeze- und Domänen-konform)
| Domäne | besitzt |
|---|---|
| **Legal Knowledge** | Ziel-Regelwerke + Obligations |
| **Compliance Execution** | Required Capabilities (`obligation → required MCAP`), MCAP / Capability Registry |
| **Reasoning (dieser Modus)** | Transition Engine, Priorisierung (Information Gain), Delta Interview, Assessment, **MDQ Registry** (Fragen-Wortlaut + Relationen + Versionierung + Follow-up) |
Reasoning **konsumiert** Required Capabilities (injiziert — wie 2As `EMPTY_MAPPING`, keine
Required-Capability-Daten im Reasoning-Produktcode). **Keine** neuen Capability-Mappings, **keine**
neuen Regelwerke, **keine** Meta-Model-Klasse.
## Akzeptanzkriterien (Demos → neue Reference-Suite-Szenarien)
- **ISMS → TISAX:** Engine stellt **< 20 Fragen** (nicht 150).
- **DSGVO → CRA:** erkennt vorhandenen Datenschutz, fragt gezielt **SBOM / Vulnerability Handling / Security Updates / Product Security**.
- **ISO9001 → IATF16949:** **nur** Delta-Fragen.
- **CRA2025 → CRA2028:** RCI liefert das Delta, Transition Engine formuliert daraus das Interview.
Jede Demo wird eine Coverage-Zeile in der [[reference-scenario-suite]] (`Transition` TODO → PASS).
## Architektur-Invariante (→ ADR-002)
1. **BreakPilot modelliert keine vollständigen Regelwerke als Interviews — sondern ausschließlich den minimalen Informationsgewinn, der nötig ist, um einen Ausgangszustand in einen regulatorischen Zielzustand zu überführen.**
2. **Jede neue Transition entsteht AUSSCHLIESSLICH durch neue Transition Patterns + Capability-/MDQ-Wissen (DATEN). Weder die Engine noch das Metamodell werden dafür erweitert.**
→ Jede neue regulatorische Reise ist ein **Datenproblem**, kein Architekturproblem (= das Ziel des Architektur-Freeze).
## Naming
„Onboarding-Fragen" → **Transition Interview**. Es fragt nicht „Wie arbeiten Sie?", sondern „Was
müssen wir noch wissen, um Ihren heutigen Zustand zuverlässig in den Zielzustand zu überführen?".
## Sequenzierung / Abhängigkeit (ehrlich)
Voller Wert braucht **Executions Required-Capabilities-pro-Obligation + MCAP-IDs** (dieselbe
Abhängigkeit wie RS-003 Company-Gap). Baubar als **v0 in der Reasoning-Spur** mit injizierten
Required-Capabilities + kleiner Seed-MDQ-Library (wie Company 2A injizierte Mappings konsumierte);
v2 (computed Information Gain + Lern-Statistik) folgt strukturell. = neues Epic **RS-005 Transition
Reasoning + MDQ Registry**, eng verwandt mit RS-003. **Spec jetzt, Bau pro Go.**
## Anhang
- Master Delta Questions v1 (100 Seed-Fragen): [`transition-reasoning/master-delta-questions-v1.md`](transition-reasoning/master-delta-questions-v1.md).
- Architektur-Entscheidung: [`adr/ADR-002-transition-is-data-not-architecture.md`](adr/ADR-002-transition-is-data-not-architecture.md).
@@ -0,0 +1,143 @@
# Master Delta Questions — v1 (Seed-Library)
- **Status:** v1 Seed — 2026-06-27. Gehört zu [`../transition-reasoning-spec-v1.md`](../transition-reasoning-spec-v1.md).
- **Sortierung nach Operational Capability, nicht nach Regelwerk** — dadurch werden Fragen über
Transitions hinweg wiederverwendbar (dieselbe Frage ist für CRA, IEC 62443, NIS2 und teils TISAX relevant).
## Herkunft der Fragen (warum es wenige sind)
- **Regulatorische Pflichten** (CRA, MaschVO, NIS2, Data Act, Umweltrecht …) sagen, **welche
Capability benötigt** wird.
- **Bestehende Zertifizierungen** (ISO 27001, TISAX, ISO 9001, ISO 14001, IATF 16949 …) sagen,
**welche Capability wahrscheinlich bereits existiert**.
- Die Bibliothek schließt **nur die Unsicherheit dazwischen** → dieselbe Frage in vielen Übergängen
wiederverwendbar. Erwartung: am Ende **~300500 Master Delta Questions**, nicht 5.000.
## v1 → v2 (Ziel)
Diese 100 sind v1: noch nach Themen gruppiert, noch **un-indexiert**. v2 hebt jede Frage in das
MDQ-Schema (siehe Spec): `id (MDQ-xxxxx)` · `verifies: [MCAP-id]` · `supports_obligations` ·
`transition_patterns` · `expected_evidence` · `information_gain` · `confidence_impact` · `follow_up`
· `version/status/lifecycle`. Erst dann werden sie zur **MDQ Registry** (4. Identitätsmaschine-Instanz).
---
## Bereich A — Unternehmenskontext (110)
1. Welche Managementsysteme sind aktuell im Unternehmen eingeführt?
2. Welche Zertifizierungen sind derzeit gültig?
3. Welche Zertifizierungen befinden sich aktuell in Vorbereitung?
4. Welche regulatorischen Anforderungen möchten Sie als Nächstes erfüllen?
5. Welche Länder und Märkte beliefern Sie?
6. Welche Rolle nehmen Sie ein (Hersteller, Integrator, Importeur, Betreiber, Service)?
7. Entwickeln Sie eigene Produkte oder integrieren Sie Komponenten Dritter?
8. Entwickeln Sie eigene Software oder Firmware?
9. Welche Nachweise können Sie heute bereits unmittelbar bereitstellen?
10. Welche regulatorischen Themen bereiten Ihnen derzeit die größten Schwierigkeiten?
## Bereich B — Produktentwicklung (1120)
11. Gibt es einen dokumentierten Entwicklungsprozess?
12. Werden Anforderungen versioniert?
13. Werden Änderungen nachvollziehbar dokumentiert?
14. Werden Architekturentscheidungen dokumentiert?
15. Existieren Design Reviews?
16. Werden Sicherheitsanforderungen bereits in der Entwicklung berücksichtigt?
17. Gibt es definierte Freigabekriterien?
18. Existiert ein Releaseprozess?
19. Werden Softwareversionen eindeutig identifiziert?
20. Existiert eine Produktstückliste (BOM)?
## Bereich C — Software & Firmware (2130)
21. Enthält Ihr Produkt Software?
22. Enthält Ihr Produkt Firmware?
23. Werden Firmwareupdates ausgeliefert?
24. Erfolgen Updates lokal oder remote?
25. Können Updates automatisiert verteilt werden?
26. Werden Updatepakete signiert?
27. Wird die Integrität von Updates geprüft?
28. Existiert eine Rollback-Strategie?
29. Werden Softwarekomponenten versioniert?
30. Werden Drittanbieterbibliotheken dokumentiert?
## Bereich D — SBOM & Komponenten (3140)
31. Wird für jede Version automatisch eine SBOM erzeugt?
32. Welches SBOM-Format verwenden Sie?
33. Wird die SBOM versioniert?
34. Enthält die SBOM alle Softwarekomponenten?
35. Enthält sie Open-Source-Komponenten?
36. Enthält sie proprietäre Komponenten?
37. Wird die SBOM Kunden bereitgestellt?
38. Wird sie intern gepflegt?
39. Wird sie automatisiert erzeugt?
40. Wie wird ihre Aktualität sichergestellt?
## Bereich E — Vulnerability Management (4150)
41. Existiert ein dokumentierter Vulnerability-Management-Prozess?
42. Wer bewertet gemeldete Schwachstellen?
43. Wie werden CVEs verfolgt?
44. Gibt es definierte Reaktionszeiten?
45. Werden Schwachstellen priorisiert?
46. Existiert ein PSIRT?
47. Gibt es einen Meldeprozess für Kunden?
48. Werden Security Advisories veröffentlicht?
49. Werden behobene Schwachstellen dokumentiert?
50. Wird der Prozess regelmäßig überprüft?
## Bereich F — Security Updates (5160)
51. Gibt es eine dokumentierte Update-Richtlinie?
52. Wie lange liefern Sie Sicherheitsupdates?
53. Wie informieren Sie Kunden über Updates?
54. Wie wird die Authentizität von Updates sichergestellt?
55. Werden Notfallupdates unterstützt?
56. Können Updates zurückgezogen werden?
57. Können Kunden Updates ablehnen?
58. Werden Updatefehler protokolliert?
59. Gibt es einen definierten Update-Lifecycle?
60. Wer verantwortet den Updateprozess?
## Bereich G — Lieferanten (6170)
61. Werden Lieferanten sicherheitsbezogen bewertet?
62. Gibt es Sicherheitsanforderungen an Lieferanten?
63. Werden Softwarelieferanten regelmäßig überprüft?
64. Werden Lieferantenänderungen dokumentiert?
65. Werden Sicherheitsvorfälle von Lieferanten verfolgt?
66. Werden Lieferantenverträge regelmäßig überprüft?
67. Existieren Mindestanforderungen für Softwarelieferanten?
68. Werden Lieferanten auditiert?
69. Gibt es einen Eskalationsprozess?
70. Wie werden kritische Lieferanten identifiziert?
## Bereich H — Betrieb & Support (7180)
71. Existiert ein Incident-Response-Prozess?
72. Gibt es einen Security-Support?
73. Werden Sicherheitsvorfälle dokumentiert?
74. Gibt es definierte Eskalationsstufen?
75. Werden Kunden über Vorfälle informiert?
76. Existiert ein Backupkonzept?
77. Gibt es Wiederherstellungstests?
78. Werden Supportanfragen klassifiziert?
79. Gibt es definierte Servicezeiten?
80. Werden Lessons Learned dokumentiert?
## Bereich I — Nachweise (8190)
81. Welche Richtlinien können Sie unmittelbar bereitstellen?
82. Welche Prozesse sind dokumentiert?
83. Welche Arbeitsanweisungen existieren?
84. Welche Auditberichte liegen vor?
85. Welche Zertifikate liegen aktuell vor?
86. Welche technischen Nachweise können Sie liefern?
87. Welche Protokolle werden archiviert?
88. Welche Nachweise werden versioniert?
89. Welche Nachweise sind öffentlich verfügbar?
90. Welche Nachweise fehlen derzeit?
## Bereich J — Neue regulatorische Anforderungen (91100)
91. Erzeugen Sie Nutzungsdaten Ihrer Produkte?
92. Unterstützen Ihre Produkte Fernwartung?
93. Enthalten Ihre Produkte Funkmodule?
94. Werden sicherheitsrelevante Ereignisse protokolliert?
95. Gibt es Umweltaspekte wie Chemikalien oder Abwasser?
96. Werden Umweltmessdaten dokumentiert?
97. Gibt es produktspezifische Entsorgungsanforderungen?
98. Gibt es dokumentierte Cyber-Risikoanalysen?
99. Welche neuen regulatorischen Anforderungen sehen Sie selbst als größte Herausforderung?
100. Welche regulatorischen Nachweise möchten Sie innerhalb der nächsten zwölf Monate erstmals oder zusätzlich erfüllen?