# 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 (IOMMU/VFIO, ZFS-Replikation, Treiber-Pinning, Xid-Exporter) | ✅ geschrieben, **nicht** gegen echten Cluster/`tofu validate` geprüft |
| 11 | CI | – | Gitea Actions: Tests, Lint, Konfig-Validierung (Runner `gitrunner-knaster`) | ✅ |
| 12 | TTS + Legacy-GPUs | ADR-0006 | Engine-Grenzen im Katalog, deaktivierte GPUs, geteilte GPU-Rollen, TTS-Slots, Piper-Dienst, TTS-Canary, `knaster bench tts` | ✅ |
| 13 | Ontologie der Datenhaltung | SPEC-ontology | `ontology/know.yaml` als Quelle, Export (Turtle/SKOS, Graph, Ansicht), Abgleich mit n8n/KNOW (nur lesend), Vorschläge `ontology_change` in der Service-Routine, `knaster ontology apply` | ✅ gegen echten n8n-Export geprüft (24 Befunde, 4 Vokabel-Vorschläge) |

## 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.

## Stand der Verifikation

| Was | Wie geprüft |
|---|---|
| Kernlogik (Router, Eskalation, Verifier, Pflege-Agent, Healer, Lifecycle, Placement) | 152 Unit- und Integrationstests (`make test`) |
| Konfiguration (Registry ↔ Skills ↔ LiteLLM ↔ Healer ↔ Policy ↔ Katalog) | `knaster validate` |
| Compose-Dateien | `docker compose config` (`make compose-check`) |
| Prometheus/Alertmanager/n8n-JSON | Strukturtests (`core/tests/test_artifacts.py`) |
| n8n, Portainer | nur lesender Erreichbarkeitstest, nichts deployt |
| Ontologie ↔ n8n | `knaster ontology check` gegen einen lesend abgerufenen Export aller Workflows (13.10.); Tests mit synthetischen Workflows |
| OpenTofu, Ansible | nur YAML/Syntax. `tofu validate` und `ansible-lint` stehen noch aus |

## Offene Punkte vor dem Deployment

- ~~Image-Tags pinnen: LiteLLM (`main-stable`) und pve-exporter (`latest`).~~ 12.10.2026: Infra-Stack vollständig gepinnt, LiteLLM entfällt (D4). Offen: vLLM-, llama.cpp- und Treiber-Versionen gegen den aktuellen Stand prüfen.
- LiteLLM-Wildcard-Routen (`tier1-general/*`) gegen die eingesetzte Version testen.
- Den n8n Chat-Trigger nach dem Import prüfen (Parameter der Knotenversion).
- `sites/knaster/*`: Hosts, VM-IDs, IPs und PCI-Adressen sind Annahmen und werden durch den Inventarlauf ersetzt.
- Classifier `ticket-kategorie.json` entsteht erst aus gelabelten Fällen (Warnung von `knaster validate`).
- Qwen3-TTS-Server für `tts-de-hq` auswählen (OpenAI-kompatibler Wrapper um faster-qwen3-tts) und Image setzen.
- Benchmark-Tag: `llama-bench` auf P2000 (und M4000), `knaster bench tts` für beide TTS-Slots, dazu Strom messen. Ergebnisse in Katalog und Registry übernehmen.

## Gemeinsames Deployment (später)

> **Abgelöst** durch [docs/superpowers/plans/2026-10-12-aufbau-cluster-knaster.md](superpowers/plans/2026-10-12-aufbau-cluster-knaster.md). Dort steht der Ablauf auf der echten Hardware, zusammengeführt mit Planner Epic 7. Die Liste unten bleibt nur zur Nachvollziehbarkeit stehen.

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