docs: Architekturplan, ADRs, Spezifikationen und Umsetzungsplan

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/IMPLEMENTATION.md

@@ -0,0 +1,35 @@
+# Umsetzungsplan
+
+Vorgehen pro Baustein: **Spec → Implementierung → Tests → Commit**. Bis zum gemeinsamen Deployment wird nichts auf Produktivsysteme ausgerollt. Alle externen Aufrufe (LLMs, Proxmox, Portainer, n8n) sind hinter Schnittstellen gekapselt und in Tests durch Fakes ersetzt.
+
+## Arbeitspakete
+
+| # | Paket | Spec | Inhalt | Status |
+|---|---|---|---|---|
+| 1 | Grundlagen | SPEC-core §1–2 | Settings, Registry, Skill-Parser, Store (SQLAlchemy, SQLite/Postgres) | ✅ |
+| 2 | Routing | SPEC-core §3–4 | Embedding-Client, Skill-Index, Reranker, Token-Budget, Router, Eskalation | ✅ |
+| 3 | Ausführung | SPEC-core §5–7 | LLM-Client, Executor (Stufe 0–3), Signale, Verifier, Fälle/Präferenzpaare, Kalibrierung | ✅ |
+| 4 | Pflege | SPEC-maintenance | Policy, Vorschläge, Service-Routine, Befehlsgrammatik, Intent-Mapper | ✅ |
+| 5 | Healing | SPEC-healer | Regel-Engine, Treiber (Portainer, Proxmox, Notify), Dry-Run | ✅ |
+| 6 | Lifecycle | SPEC-lifecycle | Kandidaten-Zustandsmaschine, Promote/Rollback, Graduierung | ✅ |
+| 7 | Portabilität | SPEC-inventory | Inventar-Parser, Katalog, Placement, CLI | ✅ |
+| 8 | API | SPEC-core §8 | FastAPI-App, Auth, Metriken | ✅ |
+| 9 | Deployment-Artefakte | PLAN §1, §3 | Compose pro Rolle, LiteLLM, Prometheus-Regeln, Alertmanager, n8n-Workflows | ✅ |
+| 10 | Plattform | ADR-0001/0002 | OpenTofu (bpg/proxmox), Ansible-Rollen (Treiber-Pinning, Docker) | ✅ (ungetestet gegen echten Cluster) |
+| 11 | CI | – | Gitea Actions: Tests, Lint, Compose-Validierung | ✅ |
+
+## Teststrategie
+
+- **Unit-Tests** pro Modul (`core/tests`), deterministisch und ohne Netz. Für Embeddings kommt ein `HashingEmbedder` zum Einsatz (Bag-of-Words, normalisiert). Er liefert reproduzierbare Ähnlichkeiten.
+- **Integrationstests** der API mit FastAPI-`TestClient`, Fake-LLM und SQLite im Speicher. Sie decken die komplette `/v1/run`-Schleife inkl. Eskalation und Präferenzpaar ab.
+- **Artefakt-Tests:** Compose-Dateien, Prometheus-Regeln, LiteLLM-Konfiguration und n8n-Workflows werden strukturell geprüft (YAML/JSON gültig, referenzierte Knoten vorhanden, Slots konsistent zur Registry).
+- **Nicht getestet bis zum gemeinsamen Deployment:** echte Modelle, Proxmox-API, Portainer-Aktionen, OpenTofu-Apply.
+
+## Gemeinsames Deployment (später)
+
+1. Inventarlauf auf allen Nodes → `sites/knaster/inventory.yaml` ergänzen → `knaster placement plan`
+2. Proxmox: ZFS-Pools, Resource Mappings, Templates (`platform/proxmox`)
+3. Infra-LXC: `deploy/compose/infra` mit `KNASTER_DRY_RUN=true`
+4. GPU-VMs nacheinander, nach jeder Rolle Canary-Checks
+5. n8n-Workflows importieren (zuerst inaktiv), Credentials setzen
+6. Dry-Run eine Woche beobachten, dann Aktionen einzeln freischalten