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

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)).

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: <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: **~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).

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?