feat: Journey Matcher — the delta explains the journey (Delta -> Journey, ADR-011)

The sanctioned last architectural building block. Reverses the order: not Goal -> Journey -> Delta
but Goal -> Required -> Delta -> Journey. A Journey is the EXPLANATION of the Capability Delta, not
its cause — so this is a Matcher/Explainer, not a Selector.

New module compliance/journey_matcher/ = the third independent, interchangeable function of the
pipeline, beside Company 2A (Evidence -> Capability) and RS-005 (Capability -> Delta):

  match_journeys(delta, journeys, context) -> ranked, auditable explanation

- Looks ONLY at the Capability Delta — never at certificates, regulation, tenders or the goal.
  Journey signatures are certificate-agnostic capability clusters (Input -> Output pattern).
- score = share of the delta a journey explains (recall over the missing capabilities); journey_only
  documents where a journey reaches beyond the delta so a broad journey is not silently preferred.
- Deliberately dumb + deterministic (pure set overlap; NO ML/embeddings/LLM), fully auditable
  (matched / unexplained / journey_only / context signals); a learning ranker can sit on top later.
- Signatures injected, engine hermetic. mypy --strict clean.

Validated on the real patterns (demo): a CRA+MaschinenVO delta ranks the convergence journey 100%,
"ISO27001 -> CRA" 56% (misses the machine-safety caps), "ISMS -> TISAX" 0%. This resolves the
"Scope -> Journey" jump from Customer Mission #1. Freeze exception explicitly authorised; non-runtime
-> no deploy. 12 tests pass, check-loc 0.
This commit is contained in:
Benjamin Admin
2026-06-28 10:36:43 +02:00
parent 3c6e2a2acc
commit 80bf1993e0
8 changed files with 511 additions and 0 deletions
@@ -0,0 +1,54 @@
# ADR-011: Journey Matcher — the delta explains the journey (Delta -> Journey)
- **Status:** Accepted
- **Datum:** 2026-06-28
- **Typ:** Architektur-Entscheidung (neues Modul — vom User ausdrücklich freigegeben)
- **Bezug:** [ADR-003](ADR-003-capability-delta-engine-with-renderers.md), [ADR-002](ADR-002-transition-is-data-not-architecture.md), [[transition-reasoning]], [[strategy-requirements-intelligence]], journey-model-spec-v1
## Kontext
Bisher war die **Journey die Ursache**: der Berater wählte vorne eine Journey (`Goal → Journey → Delta`).
Genau das war der eine offene „Sprung" aus Customer Mission #1 (Scope → Journey). Wir haben ihn bewusst
NICHT zu früh gebaut, sondern erst **fünf bewusst unterschiedliche Zielarten** validiert (Mission #1#5:
Regulation · Certification · Public Tender · OEM-Spec · Umwelt/Material). Damit existiert die Diversität,
um aus **beobachteten Fällen** zu generalisieren statt aus Annahmen — die Voraussetzung, den Selektor
überhaupt sinnvoll zu bauen.
## Entscheidung
1. **Umkehrung der Reihenfolge: `Goal → Required → Delta → Journey`.** Die Journey ist die **Erklärung**
des Capability Deltas, nicht seine Ursache. Genannt **Journey Matcher / Explainer**, nicht „Selector".
2. **Neues Modul `compliance/journey_matcher/` = die dritte Funktion `Delta → Journey`** — neben
Company 2A (`Evidence → Capability`) und RS-005 (`Capability → Delta`). Drei **unabhängige,
austauschbare** Funktionen, drei verschiedene Probleme.
3. **Der Matcher sieht NUR das Capability Delta** — keine Zertifikate, kein Regelwerk, kein Ziel.
Journey-Signaturen sind **zertifikat-agnostische Capability-Cluster** (`Input Pattern → Output Pattern`);
die IDs wie „ISO27001 → CRA" sind nur eine Beschreibung der Cluster, der Matcher liest sie nie.
**Score = Anteil des Deltas, den eine Journey erklärt** (Recall über die fehlenden Capabilities), nie
ein „Fit" oder ein Konformitätsurteil. `journey_only` dokumentiert, wo eine Journey über das Delta
hinausreicht (eine breite Journey wird nicht still bevorzugt).
4. **Bewusst dumm + deterministisch:** reine Mengenüberlappung, **kein ML, keine Embeddings, kein LLM**.
Voll auditierbar (matched / unexplained / journey_only / Kontext-Signale). Ein lernendes Ranking kann
später DAVOR gesetzt werden; der deterministische Kern bleibt nachvollziehbar. Kontext (Branche/
Produkttyp/Zielart) ist nur **dokumentierte Korroboration + Tie-Break**, nie Teil des Scores.
5. **Signaturen werden INJIZIERT**, nicht im Kern geladen — die Engine bleibt hermetisch (wie RS-005).
## Konsequenzen
- **Der „Scope → Journey"-Sprung aus Mission #1 ist aufgelöst:** es gibt keinen Journey-Matcher als
Sonderlogik je Zielart — die Journey ergibt sich aus dem Delta. An echten Pattern validiert: ein
CRA+MaschinenVO-Delta rankt die Konvergenz-Journey 100 %, „ISO27001 → CRA" 56 % (verfehlt die
Maschinensicherheit), „ISMS → TISAX" 0 %.
- **Letzter wirklich architektureller Baustein.** Alles danach ist überwiegend **Wissensarbeit,
Korpusaufbau, Domänenmodellierung** — in der Pipeline `Reality → Evidence → Capability Profile →
Required State → Capability Delta → Journey → Roadmap → Playbooks → Verification` kommt „Regulation"
nicht mehr als Sonderfall vor.
- **Freeze-Ausnahme, bewusst:** der User hat dieses EINE neue Modul ausdrücklich freigegeben. Kein
weiteres Metamodell/Graph. Non-runtime (kein App-Caller) → kein Deploy ([ADR-001](ADR-001-runtime-deploy-policy.md)).
- **Folgearbeit (nicht jetzt):** Journeys als reine `Capability Cluster A → Cluster B` (statt ISO/CRA-IDs);
`Intent → Scope → Journey`-Ebene darüber; lernendes Ranking als Vor-Stufe; `relevance(evidence, target)`
als eigene Berechnung (aus Mission #5).