docs(spec): Transition Reasoning spec v1 + MDQ Registry + ADR-002
Second reasoning mode (extends, does not replace): BreakPilot answers MIGRATION questions (start state -> target state -> delta), not regulation Q&A. New package compliance/transition_reasoning/ (spec only). Transition Reasoning is RCI generalized; reuses Company 2A (have), Master Capability Registry (MCAP) and RCI. MDQ Registry = 4th identity-machine instance (after Master Controls/Obligations/ Capabilities): every Master Delta Question is a versioned, identifiable knowledge unit (verifies MCAP, supports obligations, transition patterns, evidence types, information gain, confidence impact, follow-up). Transition Patterns hold only MDQ references -> reuse across transitions. Delta interview = information-gain optimization, not a sequential questionnaire. ADR-002: transitions are DATA (patterns + capability/MDQ knowledge), never engine or metamodel extensions. 100 seed questions captured as v1. Spec only (no code; freeze-respecting: additive package, no new graph/base class/ meta-model class). Non-runtime docs -> no deploy (ADR-001). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
@@ -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).
|
||||
Reference in New Issue
Block a user