feat: Smart Onboarding Advisor — make the knowledge usable in onboarding (ADR-012)

The user-named "right next runtime step": stop building knowledge, start using it automatically in
onboarding — no sales training, no regulation picking. compliance/onboarding/ is an ORCHESTRATOR (not
a new engine) wiring Company 2A -> RS-005 -> optimization -> completeness:

  advisor_start(input, cert_hypotheses, target_requirements, ...) -> AdvisorResult

From (company + products + certifications + target) it returns inferred_assumptions, rejected_
assumptions, next_best_questions (<=5, ranked by information_gain + leverage + unknown_high_risk +
evidence_missing, each self-explaining), capability_delta, top_measures, evidence_requests,
unsupported_domains, completeness_summary. apply_answer() updates the profile (delta shrinks).

Welt-1 throughout: certificates REDUCE questions but satisfy nothing automatically (verification_
required); relevance(evidence,target) keeps ISO 14001 out of the CRA result. Certificate->capability
hypotheses + target requirements are INJECTED (curated knowledge, outsourced; not in code).

All 7 acceptance criteria pass; mypy --strict clean. First app-caller wiring the engines into a
product flow — still no endpoint/persistence, so 0 runtime effect -> no deploy yet (deploys when
POST /onboarding/advisor-start + frontend are wired). check-loc 0.
This commit is contained in:
Benjamin Admin
2026-06-28 12:45:49 +02:00
parent 009083882a
commit 3ba90f49cf
7 changed files with 487 additions and 0 deletions
@@ -0,0 +1,45 @@
# ADR-012: Smart Onboarding Advisor — make the knowledge usable in onboarding (orchestration)
- **Status:** Accepted
- **Datum:** 2026-06-28
- **Typ:** Architektur-Entscheidung (Runtime-Schritt — Orchestrierung, KEINE neue Engine)
- **Bezug:** [ADR-003](ADR-003-capability-delta-engine-with-renderers.md), [ADR-011](ADR-011-journey-matcher-delta-explains-journey.md), [[strategy-knowledge-layers-and-hypotheses]], [[evidence-attributed-to-origin]], [[transition-reasoning]]
## Kontext
Das Wissen ist gebaut; der nächste Schritt ist, es **automatisch im Onboarding** nutzbar zu machen — der
Vertrieb ist nicht schulbar und darf KEINE Regelwerke auswählen oder interpretieren. Zugleich gilt die
reale Grenze: **proprietäre Normen (ISO/TISAX/PCI…) dürfen nicht ingestiert werden** — also wird aus den
Zertifikaten über eine **kuratierte Hypothese** (Welt-1) auf *wahrscheinlich vorhandene* Fähigkeiten
geschlossen, nie auf „erfüllt".
## Entscheidung
1. **`compliance/onboarding/` ist ein ORCHESTRATOR, keine neue Engine.** Er verdrahtet die bestehenden
Bausteine zu einem Flow: Company 2A (`Evidence→Capability`) → RS-005 (`Capability→Delta`) →
Optimization (`Delta→Roadmap`) → Completeness. Keine neue Reasoning-Engine, Capability-Registry oder
Metamodell (Freeze).
2. **`advisor_start(input, cert_hypotheses, target_requirements, …)`** liefert: `inferred_assumptions`,
`rejected_assumptions`, `next_best_questions` (≤5), `capability_delta`, `top_measures`,
`evidence_requests`, `unsupported_domains`, `completeness_summary`.
3. **Welt-1-Disziplin:** Zertifikate **reduzieren Fragen, erfüllen aber NICHTS automatisch**
(`verification_required`). **`relevance(evidence, target)`** hält ISO 14001 aus dem CRA-Ergebnis heraus
(nicht-relevante Zertifikate → `rejected_assumptions`, Grund „relevance = 0").
4. **Nur die nächsten besten Fragen** (≤5), deterministisch gerankt nach
`information_gain + leverage (regulatory+business) + unknown_high_risk + evidence_missing`; **jede Frage
erklärt sich** (`why`). **Jede Antwort aktualisiert das Profil** (`apply_answer` → Delta schrumpft).
5. **Zertifikat→Capability-Hypothesen und Ziel-Anforderungen werden INJIZIERT** — kuratiertes Wissen,
NICHT im Code ([[evidence-attributed-to-origin]]). Die Hypothesen-Kuratierung ist ein eigener,
ausgelagerter Knowledge-Task.
## Konsequenzen
- **Erster „App-Caller", der die Engines zu einem Produkt-Flow verbindet** — der vom User benannte
„richtige nächste Runtime-Schritt". Noch OHNE Endpoint/DB-Persistenz → aktuell **kein Runtime-Effekt →
kein Deploy** ([ADR-001](ADR-001-runtime-deploy-policy.md)); Deploy, sobald `POST /onboarding/advisor-start`
+ Persistenz + Frontend verdrahtet sind (Folgeschritt).
- **7 Akzeptanzkriterien erfüllt + getestet** (Multi-Cert · ISO 14001 nicht fälschlich relevant ·
Welt-1 · ≤5 Fragen · Frage erklärt sich · Antwort updatet Profil · Vertrieb interpretiert nichts).
- **Langfristiger Moat = EMPIRIE:** `confidence` der Hypothesen kommt später aus BEOBACHTUNGEN
(bestätigt/widerlegt je Kunde), nicht vom LLM — drei Wissensebenen
([[strategy-knowledge-layers-and-hypotheses]]).