diff --git a/docs-src/architecture/adr/ADR-002-transition-is-data-not-architecture.md b/docs-src/architecture/adr/ADR-002-transition-is-data-not-architecture.md new file mode 100644 index 00000000..1f72e88c --- /dev/null +++ b/docs-src/architecture/adr/ADR-002-transition-is-data-not-architecture.md @@ -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)). diff --git a/docs-src/architecture/transition-reasoning-spec-v1.md b/docs-src/architecture/transition-reasoning-spec-v1.md new file mode 100644 index 00000000..308b5c0c --- /dev/null +++ b/docs-src/architecture/transition-reasoning-spec-v1.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: ; 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: **~300–500 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: 10–20 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). diff --git a/docs-src/architecture/transition-reasoning/master-delta-questions-v1.md b/docs-src/architecture/transition-reasoning/master-delta-questions-v1.md new file mode 100644 index 00000000..18143ab0 --- /dev/null +++ b/docs-src/architecture/transition-reasoning/master-delta-questions-v1.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 **~300–500 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 (1–10) +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 (11–20) +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 (21–30) +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 (31–40) +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 (41–50) +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 (51–60) +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 (61–70) +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 (71–80) +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 (81–90) +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 (91–100) +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?