From 86a783e72f2536f923bb8854382efdde208aab59 Mon Sep 17 00:00:00 2001 From: Benjamin Admin Date: Sun, 28 Jun 2026 07:14:15 +0200 Subject: [PATCH] =?UTF-8?q?docs(spec):=20Journey=20model=20PROPOSAL=20?= =?UTF-8?q?=E2=80=94=20validate=20"transition=20is=20the=20unit,=20rest=20?= =?UTF-8?q?are=20renderers"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Transition Pattern, Playbook and Reference Scenario describe the same transition from different angles. The hypothesis: a single underlying object, the Journey, is the unit of knowledge; everything else is a renderer ("rendered, not modeled"). Per the user's request this is a SPECIFICATION to validate the assumption BEFORE any code — not a runtime module, not new architecture, decision pending. - Conceptual Journey schema: identity (from->to) + source_variants + likely_covered[] + delta[] + rejected_assumptions; questions/measures/evidence/verification are DERIVED. Truth hierarchy: Atomic Requirement -> Capability -> Journey (x Company context on instantiation). - Renderers: Transition Pattern (= the curated Journey core), Interview, Roadmap, Reference Scenario, Evidence view, role views (Sales/Auditor/Developer/GF) — four views, one Journey. - GROUNDED validation against the real ISO 27001 -> CRA artifacts (TP-ISO27001-CRA-v1, the sbom/CVD playbooks, RTS-001/002/003). Honest finding: the unification HOLDS with two refinements that AVOID premature abstraction: 1. Reference Scenario = Journey x Company context + expected outcome (no duplicated transition data). 2. Playbook = a CAPABILITY renderer (reused across journeys), NOT a Journey renderer — stays capability-owned (ADR-004); the Journey aggregates, it does not own. => a transition is curated exactly once; ISO9001->MaschinenVO becomes one object, not four. - Proposes the principle "rendered, not modeled" alongside computed-not-stored / derived-not-curated. No code, no runtime change (Freeze). Non-runtime doc -> no deploy (ADR-001). If accepted -> ADR-011. Co-Authored-By: Claude Opus 4.7 --- .../architecture/journey-model-spec-v1.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 backend-compliance/docs-src/architecture/journey-model-spec-v1.md diff --git a/backend-compliance/docs-src/architecture/journey-model-spec-v1.md b/backend-compliance/docs-src/architecture/journey-model-spec-v1.md new file mode 100644 index 00000000..41c1fd02 --- /dev/null +++ b/backend-compliance/docs-src/architecture/journey-model-spec-v1.md @@ -0,0 +1,102 @@ +# Journey Model — specification (PROPOSAL v1, decision pending) + +- **Status:** PROPOSAL / draft — to be VALIDATED before any code. Not an accepted ADR yet. +- **Datum:** 2026-06-28 +- **Typ:** Konzeptionelles Datenmodell (KEIN Runtime-Modul, KEINE neue Architektur) +- **Bezug:** [ADR-003](adr/ADR-003-capability-delta-engine-with-renderers.md), [ADR-004](adr/ADR-004-implementation-playbooks.md), [ADR-009](adr/ADR-009-domain-knowledge-program.md), [ADR-010](adr/ADR-010-operational-knowledge-transition-unit.md), [[transition-reasoning]] + +## 1. Problem + +Wir produzieren drei Artefakte je Transition: **Transition Pattern**, **Playbook**, **Reference +Scenario**. Alle drei beschreiben dieselbe Geschichte aus verschiedenen Blickwinkeln. Wird derselbe +Übergang (z. B. ISO 9001 → MaschinenVO) in Pattern + Playbook + Szenario + Interview je separat +modelliert, **duplizieren wir die Transition** — genau das Problem, das wir bei Controls/Capabilities/ +Requirements mit der Identitätsmaschine gelöst haben. + +> Damals: *Controls nicht duplizieren.* Heute: **Transitionen nicht duplizieren.** + +## 2. Hypothese + +Es gibt unter den Artefakten ein gemeinsames Objekt — die **Journey** — als Wissenseinheit; alles +andere ist ein **Renderer** (*rendered, not modeled*). Diese Spezifikation **prüft die Hypothese an der +vorhandenen Transition ISO 27001 → CRA**, bevor irgendetwas gebaut wird. + +## 3. Die Wissenseinheit: Journey (Vorschlag) + +``` +Journey + identity: from (Ausgangszustand) → to (Zielzustand) # = transition_goal + source_variants: certified | introduced | expired | limited_scope # Start-Zustands-Varianten + likely_covered[]: { capability, relationship, confidence_source, verification, rationale, reviewable_claim, expected_evidence } + delta[]: { capability, why_missing, needed_information, expected_evidence, priority, dropped_if } + rejected_assumptions[] + # ── alles darunter ist ABGELEITET, nicht gespeichert ── + (derived) questions ← delta (RS-005) + (derived) measures ← delta × leverage (Optimization) + (derived) evidence_needs ← likely_covered.expected_evidence + delta.expected_evidence + (derived) verification ← evidence × Reality (Vision V2, künftig) +``` + +**Wahrheits-Hierarchie:** `Atomic Requirement → Capability → Journey (× Company-Kontext bei Instanz)`. +Alles andere wird gerendert. + +## 4. Renderer (rendered, not modeled) + +| Renderer | Was er zeigt | Quelle | +|---|---|---| +| **Transition Pattern** | die KURATIERTE generische Journey (likely_covered + delta + rationale) | = der **authored core** der Journey (gespeichert/kuratiert) | +| **Interview** | fehlende Informationen → Fragen | `Journey.delta` (RS-005) | +| **Roadmap** | Maßnahmen nach regulatorischem Hebel | `Journey.delta` × Leverage (Optimization) | +| **Reference Scenario** | erwartetes Ergebnis für ein Referenz-Unternehmen | **`Journey × Company/Product-Kontext`** + Expected Outcome | +| **Evidence-View** | welche Nachweise erfüllen die Anforderung | `Journey.evidence_needs` × Reality | +| **Rollen-Views** | Sales→Executive Summary · Auditor→Capability Delta · Developer→Evidence · GF→Roadmap | gefilterte Projektionen DER EINEN Journey | + +Vier Rollen-Views, aber **nur eine Journey**. + +## 5. Validierung an ISO 27001 → CRA (grounded, nicht hypothetisch) + +Geprüft gegen die echten Artefakte: `TP-ISO27001-CRA-v1.yaml`, die Playbooks `sbom_creation`/ +`coordinated_vulnerability_disclosure`, die Reference Scenarios `RTS-001/002/003`. + +| Artefakt | Felder | projiziert aus der Journey? | +|---|---|---| +| **Transition Pattern** | `transition_goal`, `source_state_variants`, `likely_covered[]` (relationship/rationale/reviewable_claim/expected_evidence), `delta_requirements[]` (why_asked/needed_information/expected_evidence/priority/dropped_if), `rejected_assumptions` | **JA — IST der authored core der Journey** (1:1). | +| **Interview** (RS-005) | `question_requests` aus `delta` | **JA — derived.** Kein eigenes Primärdatum. | +| **Roadmap** (Optimization) | Maßnahmen nach Leverage aus `delta` | **JA — derived.** | +| **Reference Scenario** | `reference_company{sector, certs, product_traits}` + `expected_outcome{cra, maschinenvo, data_act, convergence}` | **TEILWEISE — Journey × Company-Kontext.** Die Transition-Erkenntnis (likely_covered/delta) ist DIESELBE wie im Pattern; NEU ist nur der gebundene **Company/Product-Kontext** + die Expected-Outcome-Assertion (Regression). Kein dupliziertes Transitionswissen. | +| **Playbook** | `capability_id`, `why`, `tools`, `process_steps`, `expected_evidence`, `how_others_do_it` | **NEIN — pro CAPABILITY, nicht pro Journey.** `sbom_creation` wird von JEDER Journey wiederverwendet, deren Delta SBOM enthält. Bleibt capability-owned (ADR-004); die Journey **aggregiert** die Playbooks ihrer Delta-Capabilities, besitzt sie nicht. | + +## 6. Befund (ehrlich) + +**Die Vereinheitlichung HÄLT — mit zwei Präzisierungen, die eine voreilige Abstraktion VERMEIDEN:** + +1. **Pattern · Interview · Roadmap · Evidence · Rollen-Views = dieselbe Journey** (Pattern = kuratierter + Kern; der Rest derived). → *rendered, not modeled* gilt für die abgeleiteten Sichten. +2. **Reference Scenario = `Journey × Company-Kontext` + Expected Outcome** — kein zweites + Transitionsmodell, sondern die Journey instanziiert für ein Referenz-Unternehmen (Regression). +3. **Playbook = Capability-Renderer, NICHT Journey-Renderer** (andere Achse: Capability, nicht + Transition). Die Journey aggregiert, besitzt nicht. → das ist die früh erkannte Grenze, die + verhindert, dass wir Playbooks fälschlich in die Journey zwingen. + +**Konsequenz:** Die Transition wird genau EINMAL kuratiert (heute „Transition Pattern" = der Journey- +Kern). Interview/Roadmap/Reference-Outcome/Rollen-Views werden daraus gerendert. Playbooks bleiben +capability-owned und werden referenziert. Damit ist `ISO 9001 → MaschinenVO` (und jede weitere +Transition) ein EINZIGES kuratiertes Objekt, kein vierfach gepflegtes. + +## 7. Neues Prinzip (Vorschlag) + +Neben **computed, not stored** und **derived, not curated**: + +> **rendered, not modeled** — Transition Pattern, Playbook-Aggregat, Roadmap, Interview, Rollen-View +> sind keine eigenständigen Modelle, sondern Sichten auf Journey (+ Capability + Company-Kontext). + +## 8. Was das NICHT ist / nächste Schritte + +- **Kein Code, kein Runtime-Modul, keine neue Architektur** (Freeze unberührt). Diese Spec ist ein + konzeptionelles Datenmodell zur Entscheidung. +- **Wenn akzeptiert:** der „Transition Pattern" wird zum *Journey-Dokument* (gleiche YAML-Struktur, + präziserer Name); Renderer bleiben abgeleitet; Playbook bleibt capability-owned. Dann ggf. ADR-011. +- **Wenn verworfen:** die drei Artefakte bleiben getrennt — aber dieser Befund zeigt, dass sie sich zu + ~90 % aus einer Journey ergeben; das Risiko liegt nur bei der Company-Kontext-Bindung (RTS) und der + Capability-Achse (Playbook), die ohnehin schon getrennt sind. +- Non-runtime → kein Deploy (ADR-001).