bf-infra/docs/session-20260828-decisions.md

Session-Anker 2026-08-28 — Pre-OpenCode-Migration: Diskussionsentscheidungen

Zweck: Mini-Anker für die nächste Session. Was im Handoff 2026-08-28-pre-opencode-migration.md an Status steht, steht hier an Warum. Diese Datei + Handoff + TP35 in teilprojekte.md = vollständiger Diskussionsstand, ohne dass die nächste Session 90 Minuten Chat nachlesen muss.

Lese-Reihenfolge für nächste Session:

1. docs/handoff-20260828-pre-opencode-migration.md (Status, Backups, Lessons)
2. Diese Datei (Warum, Entscheidungen, Übergabe-Mechanik)
3. docs/teilprojekte.md → TP35 (Scope, Abgrenzung, Verweise)

Was wir entschieden haben (F1–F5 mit Begründung)

Frage	Antwort	Warum
F1 — Reihenfolge	(b) TP anlegen → Handover-Posts pro Projekt → globale CLAUDE.md → Backup-Guard	Handover-Posts entstehen vor globaler CLAUDE.md, weil die Posts darauf verweisen. Guard zuletzt, weil er die Struktur aus den anderen Schichten braucht.
F2 — Wo leben Handover-Posts	(ii) Pro Projekt eigene Datei im jeweiligen Repo	Posts sind projektspezifisch — gehören ins Projekt-Repo, nicht in ein zentrales Sammel-File. Format-Vorschlag: docs/MCP-SCHICHTUNG-VORSCHLAG.md pro Projekt.
F3 — Welche Regeln in globale CLAUDE.md	(ii) Die 5 Lessons aus bf-infra + „Single Point of Contact für Infrastruktur"	SoC-Prinzip ist explizit gewollt: bei Infrastruktur-Touchpoints soll jede Session bf-infra konsultieren, nicht selbst entscheiden.
F4 — Backup-Guard-Hook	Hybrid (Pre-Commit-Hook + manueller Session-Start-Snippet)	Pre-Commit deckt Schreibzugriffe ab. Session-Start-Snippet fängt Read-only-Sessions ab, falls opencode das unterstützt.
F5 — TP35-Format	(ii) Mittel: Titel + Scope-Absatz + Abgrenzung + Verweise	Voll zu lang, minimal zu wenig. „Briefing/Infos dazupacken, wenn in Handoffs vorhanden" = genau diese Form.

Drei Korrekturen unterwegs (Ollama, uwe-job-bewerbung, Backup-Guard-Definition)

1. Ollama läuft auf 2 Hosts lokal (MacBook + Mac mini), beide auf localhost:11434. Default in der MCP-Config = http://localhost:11434. Wer BF-LAN-Remote will: export OLLAMA_HOST=http://10.40.20.167:11434 in der Shell.
2. uwe-job-bewerbung ist doch ein Projekt — Backup-Verzeichnis ist da, 12/12 valid (Stand jetzt, 17:02 nach erfolgreichem Retry des abgebrochenen Backups). Christoph hatte es im ersten Anlauf ausgeschlossen, dann korrigiert.
3. Backup-Guard: „3 Tage aktive Arbeit", nicht 3 Tage Standzeit. Definition: git log --since=<guard-date> ≥ 5 Commits ODER git diff --shortstat <guard-date> HEAD ≥ 1000 Zeilen. Beide Schwellen nobel.

Lehren für die Übergabe-Mechanik (Format-Vorlage für „go")

[Aktion]:      ein Satz, was konkret passieren soll
Scope:         welche Dateien/Repos/Systeme
Stop-Bedingung: was ich NICHT anfassen darf
Checkpoint:    was ich zurückmelde, wenn fertig
Bei Fehler:    rollback oder fragen

Nicht ein ganzes Bündel als „go" formulieren — eine Entscheidung pro „go". Oder explizit „Plan-Modus: Vorschlag zuerst".

Lehren für mich (Mid-Action-Checkpoint)

Bei komplexen Plänen (mehrere Schichten, mehrere Dateien) vor dem ersten Tool-Aufruf einen Mid-Action-Checkpoint setzen:

„Backups ✅, jetzt fange ich Schicht 2 an: globale Config. Wenn du jetzt anders entscheidst, ist das hier der Punkt zum Stoppen."

Christoph hat zweimal „go" gesagt und beim zweiten Mal korrigiert — wäre der Checkpoint vorher gekommen, hätte er beim ersten „go" schon differenzieren können.

Was noch zu klären ist (für nächste Session)

• TP35-Schicht 6 zuerst (/projektstatus-Skill globalisieren) — alle Projekte sollen dasselbe Skill verwenden. Vorschlag: nach ~/.config/opencode/skills/projektstatus/ linken oder kopieren.
• Ankündigungs-Format: wie sieht eine „Breaking News" aus? Mein Vorschlag: kurzes Markdown mit ## Datum — Titel, 3–5 Zeilen, plus optionaler Verweis auf TP-Nummer. SSoT: bf-infra/docs/announcements.md (in Arbeit, Datei existiert noch nicht).
• Opencode-Skill-Verzeichnis: ~/.config/opencode/skills/ oder ~/.claude/skills/? Opencode-Syntax ist ~/.config/opencode/..., claude ist ~/.claude/.... Mein Vorschlag: opencode-Verzeichnis, weil das der aktive Werkzeugkasten ist.
• TP34 + TP35-Berührung: TP34 (Caddyfile via Nautobot/GC) und TP35 (MCP-Schichtung) sind beide „Repository-Pattern für externe Konfiguration". Nicht zusammenführen — verschiedene Schichten (TP34 = Datenmodell, TP35 = lokale Tool-Konfiguration), aber im Master-Architektur-Dokument Querverweis setzen.

Commit-Hinweis-Regel (neu autorisiert 2026-08-28)

Wenn ich denke, dass ein Commit ein guter Zeitpunkt ist und Christoph es übersieht: aktiv darauf hinweisen mit einem Satz wie „Wäre jetzt ein guter Commit-Zeitpunkt — soll ich?". Nicht „einfach committen". Christoph bestätigt oder verwirft. Kontrolle bleibt beim Anwender.

Status-Stand zum Session-Ende (für nächste Session als Referenz)

Backups:           12/12 valid (1,4 GB in ~/dev/.pre-opencode-migration-backups/20260828-150335/)
Repos:             alle sauber (HEADs identisch zu vor Session, außer bf-infra)
Globale Configs:   alle md5-identisch zu vor Session
Commits in Ssn:    2 (bf-infra 799e3ef = Handoff, dieser hier = TP35 + Anker)
TP35:              angelegt, wartet auf Scope-Ausarbeitung in eigener Session
Synology Drive:    läuft (manuell, quick-and-dirty, Christoph)

Hinweis zum Session-Revert in opencode

Christoph hat die opencode-Option „Revert undo messages and file changes" getestet und abgebrochen. Leseart:

• „messages" = Session-Konversationshistorie (weg)
• „file changes" = alle nicht-committeten Tool-Mutationen (weg)
• Commits bleiben — Commits sind im Repo-Layer, nicht im Session-Layer
• Backup-Files (*.tar.gz) zählen als „file changes" und würden verschwinden

Für unsere Sitzung: ein Revert hätte nichts Wertvolles entfernt (die Backups waren Sicherheitsnetz, kein Dauerzustand), aber den Session-Kontext. Nicht nötig, weil State sauber ist.

MCP-Status-Check (Cold-Start-Race + Accept-Header-Strike)

Beim ersten Aufruf von opencode mcp list kann einzelne Server als ✗ failed erscheinen, obwohl sie in der Sidebar grün sind. Live verifiziert 2026-08-28, 17:08: n8n-mcp war beim ersten opencode mcp list als failed angezeigt (Sidebar grün). Beim zweiten Aufruf mit sleep 2 davor war der Server ✓ connected. Ursache: Initial-Race beim Cold-Start — dasselbe Muster wie Handoff 2026-08-28 M4.

Zweite Ursache (live diagnostiziert 2026-08-28, 17:11): n8n-mcp verlangt für MCP-Antworten zwingend Accept: application/json, text/event-stream (StreamableHTTP-Modus mit SSE). Ein Probe-Request mit nur Accept: application/json antwortet mit 406 Not Acceptable, Client must accept both application/json and text/event-stream. opencode's mcp list-Prober schickt offenbar nur application/json und wertet 406 als failed. Der echte Tool-Aufruf verwendet den korrekten Accept-Header und läuft.

Verifiziert mit curl:

• Ohne Bearer: HTTP 401 (Auth-Fehler, normal)
• Bearer + Accept application/json: HTTP 406 Not Acceptable (das ist der Probe-Fehler)
• Bearer + Accept application/json, text/event-stream: HTTP 200 mit serverInfo: n8n-documentation-mcp 2.57.1

Merkregel für nächste Session: bei failed zuerst 2 Sekunden warten und erneut prüfen. Erst beim zweiten failed ist es ein echtes Problem. Sidebar-Status ist die Wahrheit, opencode mcp list ist die Konsolen-Sicht mit zwei Toleranz-Quellen: Cold-Start-Race (M4) und Accept-Header-Striktheit bei StreamableHTTP-Servern.

Offene Frage / Follow-up (kein Blocker): opencode könnte den Probe-Header gegen Accept: application/json, text/event-stream härten — wäre ein upstream-Bug-Report wert, nicht für nächste Session.

Schlusswort

Diskussion hat ~1 Stunde gedauert, Ergebnis sind 3 Commits (Handoff + TP35 + dieser Anker), 12 valide Backups, 1 synology-Sync als zusätzliche Sicherung. Ausführung der TP35-Schichten erfolgt in separaten Sessions, pro Projekt einer.

Auth-Sanierung (Bearer) — gehört in TP16.3

🔴 Drift-Korrektur (Anwender 2026-08-28): dieser Punkt existiert bereits — TP16.3 „cloudflared-Reduktion: was der Mesh als Datenpfad kann (und was nicht)", ⏳ Probe läuft seit 2026-08-24, Sektion docs/teilprojekte.md Zeile 401, Quick-Index Zeile 194, Runbook docs/tp16.3-nautobot-mesh-only-runbook.md. Mein Fehler: ich habe im Index nicht nachgeschaut und einen „Vorab-Punkt" formuliert, der TP16.3 doppelt. Technische Notiz in TP16.3 selbst eingepflegt (🆕 Notiz 2026-08-28 — n8n-mcp Accept-Header-Strike + Auth-Sanierung direkt nach dem TP16.3-Body), mit dem Befund, der SSE-Header-Konsequenz für künftiges Caddy-Fronting, und der Reihenfolge-Regel TP16.3 → TP35.

Was in TP16.3 inhaltlich gehört (nicht in den Anker):

• n8n-mcp Accept-Header-Strike (406): gehört als technische Notiz in TP16.3, weil dort das „Caddy oder CF + Caddy"-Fronting sowieso diskutiert wird.
• Bearer-Authentifizierung einmal sauber: gehört in TP16.3, weil der TP-Scope „cloudflared-Reduktion + Caddy-Fronting" genau diesen Auth-Pfad vorsieht.
• TP35 Schicht 2 (Credentials-Schichtung) Endform: bleibt TP35, aber Endform hängt von TP16.3 ab — Reihenfolge ist also: erst TP16.3 klärt das Fronting, dann TP35 Schicht 2 zieht nach.

Merkregel für mich: vor jeder Aussage „gibt's noch nicht" oder „neuer Punkt nötig": erst grep auf den Quick-Index in teilprojekte.md. Doppel-Claims sind Drift, auch in der Doku. Anwender hat das in dieser Session explizit hervorgehoben („das darf dir kein 2. mal passieren") — als Lernschritt übernommen.