Tarik Moussa
accd61625c
Plan ↔ reality abgleich nach tatsächlicher Implementierung in ansible-eulernest: - CONVENTIONS.md: 4 Profile (+ coder), Registry-Pull statt GGUF/DVC, SoT-Pointer auf ansible-eulernest, JP7.2 Source-Build-Note - STATE.md: W2–W4 done (via ansible-eulernest), W1/W5/W6 dropped, N1–N3 (GPU-metric, benchmarks, smoke-tests) als nächste Schritte - ROADMAP.md: Abgeschlossene Items referenzieren ansible-eulernest-Rollen; neue Items N1–N3 für verbleibende Arbeit - manifests/requirements.md: R-03–R-06 done, R-02/R-07/R-08 drift - docs/adr/0003: Registry-Pull > GGUF; ansible-eulernest als Impl-SoT - sessions/2026-06-14-reconciliation.md: Session-Log Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
77 lines
4.0 KiB
Markdown
77 lines
4.0 KiB
Markdown
# CONVENTIONS.md — gemeinsamer Vertrag
|
|
|
|
Verbindlich für **alle** Aktoren. Änderungen nur per ADR.
|
|
|
|
## Ownership
|
|
- **Kein Paket editiert Dateien eines anderen.** Integration & Konfliktlösung
|
|
ausschließlich durch den Leader.
|
|
- Jede Datei hat genau ein zuständiges Worker-Paket (siehe `STATE.md`).
|
|
|
|
## Git & Commits
|
|
- Branch je Paket: `feat/<paket>`, `audit/<scope>`, `fix/<scope>`.
|
|
- **Conventional Commits:** `feat:`, `fix:`, `docs:`, `test:`, `refactor:`,
|
|
`chore:`. Der Git-Log ist Teil der Dokumentation.
|
|
- **Model-Attribution:** jeder Commit eines Agenten enthält einen Trailer:
|
|
`Co-Authored-By: Claude <Tier> <noreply@anthropic.com>`
|
|
Tier = Capability-Bezeichnung des eingesetzten Modells, z. B. „Sonnet 4.6"
|
|
für mittlere Kapazität oder „Opus 4.8" für maximale — nicht der interne
|
|
Modell-Name. Gilt für das zum Commit-Zeitpunkt eingesetzte Modell.
|
|
Ermöglicht nachträgliche Rückverfolgung welche Kapazitätsstufe was entschieden hat.
|
|
|
|
## Review-Gate
|
|
- **Jede Implement-Session wird von einer separaten high-capacity-Session reviewed**
|
|
(aktuell: Opus-Tier). Der Review läuft kalt (eigene Session, kein Vorkontext),
|
|
prüft den Diff, und gibt APPROVE oder CHANGES-REQUESTED zurück.
|
|
- Implement-Kapazitätsstufe ≠ Review-Kapazitätsstufe: ein Modell, das sich selbst
|
|
reviewed, findet systematisch weniger als ein unabhängiger Pass auf höchster Stufe.
|
|
- Konkrete Tier-Zuordnungen: `docs/roles/model-routing.md`.
|
|
- Review-Gate-Checkliste: `docs/roles/reviewer.md`.
|
|
|
|
## Dokumentation
|
|
- **Single Source of Truth** je Information — keine Duplikate über Docs hinweg.
|
|
- Doku ist knapp: ein Dokument, das man nicht mehr liest, driftet. Größenbudget
|
|
pro Doc beachten (Faustregel < 200 Zeilen).
|
|
- Jede Code-Änderung passt das passende Doc + Manifest **in derselben Session** an.
|
|
|
|
## Definition of Done
|
|
1. Manifest-Eintrag (`manifests/requirements.md`) mit Test + Status `done`.
|
|
2. Tests grün. 3. Docs aktuell. 4. `STATE.md` aktualisiert.
|
|
5. Session-Log geschrieben. 6. Quality-Gate `PASS`.
|
|
|
|
## Projekt-Vertrag: Jetson AI / Ollama
|
|
Verbindlich für alle Worker — Änderungen nur per ADR.
|
|
|
|
> **Autoritative SoT (Implementierung):** `ansible-eulernest/group_vars/jetson/vars.yml`
|
|
> Dieses Dokument spiegelt den Vertrag; die Ansible-Vars sind die lebende Referenz.
|
|
|
|
- **Hardware:** Jetson Orin Nano Super 8 GB (~7,4 GB nutzbar). Single-User → latenz-,
|
|
nicht durchsatzgebunden. Kein Batching, keine Inferenz-Skalierung.
|
|
- **Ollama-Build:** Source-Build erforderlich (JP7.2 / sm_87 / cuda_v13) — kein
|
|
Prebuilt-Installer bis upstream JP7.2-Support liefert.
|
|
- **Profile (Ollama-Modellnamen, Registry-Pull):**
|
|
|
|
| Profil | Base-Modell | num_ctx | temp | Zweck |
|
|
|--------|-------------|---------|------|-------|
|
|
| `qwen-light` | `qwen2.5:7b` | 16384 | 0.7 | Daily driver, Chat |
|
|
| `gemma` | `gemma3:4b` | 16384 | 0.7 | Kreativ, multimodal |
|
|
| `qwen-heavy` | `deepseek-r1:7b` | 8192 | 0.7 | Hard Reasoning |
|
|
| `coder` | `qwen2.5-coder:7b` | 16384 | 0.3 | CI-ai Bot, PR-Review |
|
|
|
|
- **Pfade:** Ollama-Store `/opt/ollama/models` (Laufzeit-Cache, Registry-Pull).
|
|
`/opt/jetson-ai/models/` bleibt reserviert für zukünftige GGUFs (ADR-0003).
|
|
- **Ports / Endpoints:** Ollama `11434` (OpenAI `/v1/chat/completions`, Status
|
|
`/api/ps`); Exporter `/metrics` auf Port `8000`; Nougat `8080`; GROBID `8070`;
|
|
codex-mcp `8765`.
|
|
- **Daemon-Env:**
|
|
`OLLAMA_FLASH_ATTENTION=1`, `OLLAMA_KV_CACHE_TYPE=q8_0`,
|
|
`OLLAMA_MAX_LOADED_MODELS=1` (genau ein Modell resident, 8-GB-Schutz),
|
|
`OLLAMA_KEEP_ALIVE=30s`, `OLLAMA_MODELS=/opt/ollama/models`,
|
|
`OLLAMA_HOST=0.0.0.0:11434` (nur LAN, Firewall beschränkt Clients).
|
|
- **`num_ctx` je Profil explizit** (Ollama kürzt sonst still): light/gemma/coder 16384,
|
|
heavy 8192.
|
|
- **Secrets:** Ansible-Vault (`group_vars/jetson/vault.yml`) — nie im Klartext committen.
|
|
- **Scope-Grenze (out of repo):** nginx-Reverse-Proxy (TLS + OAuth) und
|
|
Prometheus/Grafana laufen **off-box**. Ollama hat **keine eigene Auth** → nie
|
|
direkt ins Internet binden.
|
|
- **Code:** Type Hints, Docstrings.
|