feat(knowledge-intake): classify a document + assess its impact before extraction

Phase A1. The real knowledge production is not writing — it is TARGETED UPDATING: when 20 documents
arrive, which 5 change our knowledge and which 15 are ignorable? Before the parser, Knowledge Intake
classifies a new document (no content extraction) and intersects its signals with an index of the
existing knowledge to emit a Knowledge Package (an impact analysis).

- compliance/knowledge_intake/: build_knowledge_index(patterns, playbooks, reference_scenarios,
  obligation_index) + assess_document_impact(descriptor, index) -> KnowledgePackage. Deterministic,
  NO content extraction, NO LLM. Surfaces affected capabilities / playbooks / transition patterns /
  reference scenarios / (injected) obligations, whether it is a new domain, and a triage level
  (HIGH / LOW / NONE / NEW_DOMAIN) with a recommendation.
- ADR-006: Knowledge Intake = classify + impact before extraction; full factory Intake -> Package ->
  Parser -> Draft -> Review -> Published; phase order A1 Intake / A2 Draft / A3 Review.
- reference suite: "Knowledge Intake" section triages 3 example documents (CRA SBOM-FAQ -> high,
  14C/2PB/3RTS/2Obl; environmental guidance -> new_domain; marketing blog -> ignorable). Section
  lives in _helpers.py to keep generate.py under the 500-LOC budget.
- Honest known refinement surfaced by intake: regulation-ID normalization (CRA vs Cyber Resilience Act).

10 intake tests (60 with the adjacent modules), mypy --strict clean (16 files), check-loc 0.
Product code with no app caller + ADR/reference = non-runtime -> no deploy (ADR-001). Freeze-safe.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Benjamin Admin
2026-06-27 13:58:59 +02:00
parent d51bcd77c7
commit 07e392913f
8 changed files with 419 additions and 2 deletions
@@ -0,0 +1,54 @@
# ADR-006: Knowledge Intake — classify and assess impact before extraction
- **Status:** Accepted
- **Datum:** 2026-06-27
- **Typ:** Architektur-Entscheidung
- **Bezug:** [ADR-005](ADR-005-knowledge-production-pipeline.md), [ADR-002](ADR-002-transition-is-data-not-architecture.md), Architektur-Freeze v1.0, [[transition-reasoning]], [[iace-quality-architecture]]
## Kontext
Vier Produktionspipelines folgen demselben Muster `Rohwissen → deterministischer Entwurf →
Expertenreview → veröffentlichter Wissensbaustein` (Obligations, Capabilities, Playbook-Drafts,
Reference-Szenarien). Aber **woher kommt das Rohwissen, und wie verarbeitet man es effizient?**
Heute beginnt die Pipeline beim Parser (`PDF → Parser → Review`). Damit startet man bei JEDEM neuen
Dokument wieder bei Null. Der eigentliche Aufwand der Wissensproduktion ist nicht das Schreiben,
sondern das **gezielte Aktualisieren**: wenn morgen 20 Dokumente erscheinen — welche 15 kann man
ignorieren und welche 5 verändern tatsächlich den Wissensbestand?
## Entscheidung
1. **Vor dem Parser steht eine neue Stufe: Knowledge Intake.** Sie extrahiert KEINEN Inhalt, sondern
ordnet ein neues Dokument nur ein (Klassifikation) und bestimmt seinen **Impact** auf den
bestehenden Wissensbestand.
2. **Output ist ein `KnowledgePackage` (Impact-Analyse), kein Inhalt:** welche bestehenden
Capabilities / Playbooks / Transition Patterns / Reference-Szenarien / (injizierten) Obligations
das Dokument wahrscheinlich betrifft, ob es eine **neue Domäne** ist, und ein Triage-Level
(`HIGH / LOW / NONE / NEW_DOMAIN`) mit Empfehlung.
3. **Deterministisch, kein LLM.** Intake schneidet die Dokument-Signale (deklarierte Regelwerke +
Stichworte) gegen einen Index des vorhandenen Wissens. Optionale Modell-Anreicherung bleibt
offline/advisory (vgl. [[iace-quality-architecture]]).
4. **Vollständige Wissensfabrik:**
`Knowledge Intake → Knowledge Package → Parser → Draft Generator → Expert Review →
Published Knowledge → Reference Suite`.
## Konsequenzen
- **Targeted Updating statt Schreiben:** statt „hier sind 200 Seiten PDF" liefert das System eine
Impact-Analyse („betrifft 4 Capabilities, 2 Playbooks, RTS-003; keine neue Domäne"). Das spart
enorm viel Review-Aufwand und ist die eigentliche Knowledge Production.
- **Neue Quellen werden automatisch eingeordnet:** CRA-FAQ, MaschinenVO-Guidance, ENISA-Empfehlung,
BSI-Orientierungshilfe → je eine Impact-Analyse statt Rohtext.
- **Geänderte Phasen-Reihenfolge:** **A1 Knowledge Intake** (klassifizieren + Impact + Knowledge
Package) → **A2 Draft Production** (Transition Patterns / Playbooks / Reference-Szenarien) →
**A3 Expert Review** (Review / Versionierung / Veröffentlichung). Erst danach Phase B (neue Domänen).
- **Freeze-konform:** kein neues Metamodell, kein Graph, kein neuer Corpus. `compliance/knowledge_intake`
ist eine reine, deterministische Sicht (computed-not-stored); Obligations werden injiziert. Bekannte
Verfeinerung: Regelwerk-ID-Normalisierung (CRA ↔ Cyber Resilience Act) — vom Intake ehrlich sichtbar.
- **Strategische Bedeutung:** die Plattform wird von einem Compliance-Produkt zu einer **kontinuierlich
lernenden regulatorischen Wissensbasis** — und Intake ist der Filter, der bestimmt, was überhaupt
Arbeit auslöst.
- Diese ADR ist non-runtime → kein Deploy (siehe [ADR-001](ADR-001-runtime-deploy-policy.md)).