feat: slice 1 - the neckbeard framework chain runs end to end

Tracer bullet of the migration design (Gate 4, slice 1): pinned v0.1.1 baseline under docs/sources/upstream/ with provenance note, the Karpathy block moved verbatim to docs/sources/regelwerk/ (standing rule mapped onto the sources read-only mechanism), AGENTS.md assembled from the byte-true upstream sections plus the project section 6 (group rules condensed from the old CLAUDE.md), CLAUDE.md reduced to the upstream pointer, WORKFLOW.md and all four templates copied, schema.yaml extended (issue milestone/priority/status columns, component type, wiki area vision - all flagged in the header), validate.py and gen_status.py forked with marked extensions, pruefe_upstream_drift.py added, STATUS.md generated, CI gains the offline validate job, README directory link defused. Verified: validate 0 errors 0 warnings (the three pre-existing directory-link errors are gone), gen_status --check current, drift check 0 findings, baseline byte-identical to the reference checkout (10/10 files), four negative tests fire (WIP limit 3x in-progress, waiting without wartegrund, component slug mismatch, single-byte drift in WORKFLOW.md). gen_status needs Python >= 3.10 locally (write_text newline) - noted for the design AAR. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-08-11 12:00:00 +00:00
parent 5e46372ea8
commit e36ed337a7
27 changed files with 2311 additions and 235 deletions
@@ -1,233 +1 @@
-# CLAUDE.md — übergreifende Arbeitskonventionen (kanonisch)
-
-Diese Datei gilt für **jede Claude-/Agenten-Session in allen Projekten** der
-Gruppe (axion1337.chat-Stack, ThreadNet-Repos, CFGMON/threadnet-operating,
-Homelab). Projekt-Repos haben eigene CLAUDE.mds für ihre Spezifika (z. B. die
-ESS-/Flux-Details in „ThreadNet Server Suite" = `axion1337.chat-gitops`) — bei
-Widerspruch gilt für Arbeitsweise und Prozess **diese** Datei.
-
-> **Für Sessions ohne Lab-Zugang** (CFGMON, MATRIX, …): dieses Repo ist als
-> Push-Mirror unter `https://rohana.axion1337.de/sorb/management` von überall
-> **lesbar** — dort diese Datei und die ADRs nachschlagen. Nur pushen ist tabu.
->
-> 📋 **Kopierbare Kurzfassungen zum Voranstellen:**
-> [verfahren/textbloecke.md](verfahren/textbloecke.md) — Session-Start, Host-Session,
-> Deploy-Übergabe, Abschluss, Entscheidungsvorlage. Diese Datei hier bleibt die
-> Quelle; die Bausteine verweisen nur darauf.
-
-## Projektrealitäten (Stand 2026-08-01)
-
-**Das Lab ist die Quelle der Wahrheit** ([ADR-0002](decisions/0002-issues-und-management-ins-lab.md)):
-
- Kanonische Repos liegen auf `git.lab/axion1337.chat/*` (nur im Lab/VPN
-  auflösbar). Gitea/rohana wird per **Push-Mirror** beliefert und bleibt
-  Flux-Source, Container-/npm-Registry und Release-Download
-  ([ADR-0001](decisions/0001-gitlab-kanonisch-push-mirror.md)).
- **Warum überhaupt zwei Orte — und warum das kein Altbestand ist:** Auf git.lab
-  liegen die *Baupläne*, auf Gitea eine Kopie, die der Cluster **ohne verfügbares
-  Lab** erreicht. Der Hetzner-Cluster muss sich bauen und neu ausrollen lassen,
-  wenn das Homelab aus ist, im Umbau steckt oder niemand zu Hause ist — er darf
-  deshalb nicht von einem Host abhängen, der nur im Lab antwortet.
-  ⚠️ **Die Flux-Quelle nicht „geradeziehen"** auf git.lab: Das sähe aufgeräumter
-  aus und würde die Verfügbarkeit der Produktion an das Lab koppeln — genau das,
-  was die Trennung verhindert.
- **Nie direkt zu Gitea pushen** (gespiegelte Repos) — der Mirror überschreibt
-  per Force.
- **Gespiegelt wird nur die Gruppe `axion1337.chat`** (die fünf Produkt-Repos und
-  `management`). Die Gruppe **`homelab`** (`docs`, `wiki`, `wiki-bookstack`) hat
-  bewusst **keine Mirrors**: Sie beschreibt und konfiguriert ausschließlich
-  Lab-Infrastruktur, und seit dem Site-to-Site-VPN
-  ([ADR-0004](decisions/0004-site-to-site-vpn-hetzner-lab.md)) erreichen auch
-  Host-Sessions git.lab direkt — Tunnel einschalten genügt. Betriebslehren, die
-  von außen lesbar sein müssen, gehören deshalb in die **AARs** unter
-  `verfahren/aar/` (dieses Repo ist gespiegelt), nicht nur in die READMEs der
-  Lab-Repos.
- Landet doch ein Commit auf Gitea (z. B. aus einer Host-Session ohne Lab-Route):
-  **Kanonisierungs-Verfahren** in
-  [verfahren/deploy-uebergabe.md](verfahren/deploy-uebergabe.md) — `.patch`
-  von Gitea ziehen, `git am` (erhält Autorschaft), Push über git.lab.
- **Issues leben auf git.lab.** Die alten Gitea-Issues sind geschlossen und
-  verweisen dorthin. ⚠️ gitops-Nummern haben sich beim Umzug verschoben
-  (Gitea zählte PRs mit; z. B. Gitea#48 → GitLab#46) — alte „gitops#N"-Verweise
-  meinen die Gitea-Nummer; verbindlich ist der Migrations-Fußtext im Issue.
- **Ausnahme** (bewusst entschieden, nur noch eine): der
-  TURN-Rotations-CronJob schreibt weiter nach Gitea, weil er im Cluster läuft und
-  git.lab nicht erreicht.
-  **Die Rotation nicht von Hand nachziehen und den PR nie auf Gitea mergen** —
-  das erledigt seit 2026-08-02 der geplante CI-Job `canonize_rotation` im
-  gitops-Repo täglich von git.lab aus. Scheitert er, bleibt die Pipeline rot;
-  diese rote Pipeline **ist** der Alarm, einen zusätzlichen Termin gibt es
-  bewusst nicht.
- **Dokumentation** ([ADR-0006](decisions/0006-wikis-konsolidieren-docusaurus.md)):
-  Das gitops-Wiki liegt seit 2026-08-02 auf git.lab (*Wiki*-Reiter im Projekt);
-  ⚠️ der `wiki`-**Branch** im gitops-Repo ist ein überholter Mai-Abzug von `docs/`
-  und nicht die gepflegte Fassung. Alle Quellen zusammen erscheinen unter
-  **axionwiki.lab** ([`homelab/wiki`](https://git.lab/homelab/wiki), Docusaurus) —
-  Inhalte werden beim Bau geholt, **Änderungen gehören ins Quell-Repo**.
-
-## Arbeitsframework ([ADR-0005](decisions/0005-pm-framework-kanban.md))
-
-Kanban-Rückgrat mit leichten Scrum-Elementen:
-
- **Alles Offene ist ein Issue** — host-/infra-Scope hier im management-Projekt
-  (`host:`-Labels, alte IDs wie `CFGMON-01` bleiben im Titel), Projekt-Scope im
-  jeweiligen Projekt. Kein neues Backlog-Markdown anlegen; `hosts/`/`shared/`
-  sind nur Bestand + Historie.
- **Status über Labels**, genau eins pro Issue: `status:next` (die einzige
-  Zusage), `status:doing` (**WIP-Limit 2** — auch sessionübergreifend zu
-  verteidigen), `status:wartet` (nur mit benanntem Grund). Ohne Label = Backlog.
- **ADR-Pflicht** ([decisions/](decisions/)) bei Architektur-/Prozess-
-  entscheidungen und **jeder dauerhaften Ausnahme von einer Regel**. Eine
-  Ausnahme nur zu dokumentieren statt sie als Entscheidung vorzulegen, ist ein
-  Fehler.
- **Deploy-Übergaben** („einer baut, ein anderer rollt aus") laufen über das
-  Issue-Template und die Pflichtfelder in
-  [verfahren/deploy-uebergabe.md](verfahren/deploy-uebergabe.md) — das ist
-  unsere Definition of Done für Deployments. Nach Deploys mit Übergabe und nach
-  Incidents: **AAR** ([verfahren/aar/](verfahren/aar/), Vorlage liegt daneben).
- Prioritäten über `priority:*`; Zeitkritisches bekommt ein **Datum** im Issue,
-  nicht „bald".
- **Der Titel trägt keine Priorität.** Präfixe wie `[HIGH]`/`[MEDIUM]`/`[LOW]`
-  gehören nicht in den Titel — die Priorität steht im Label, und zwar nur dort.
-  Alte Kennungen wie `CFGMON-01` bleiben, die benennen den Gegenstand, nicht die
-  Dringlichkeit.
-  ⚠️ Der Grund ist keine Ästhetik: Aus der Gitea-Migration trugen 34 Issues ein
-  Präfix, davon **zwei mit einer anderen Aussage als ihr Label** — wer nach Titel
-  sortierte, bekam ein anderes Bild als wer nach Label sortierte. Zwei Wahrheiten
-  über dieselbe Sache sind schlimmer als eine unvollständige. Bereinigt 2026-08-06.
- **Jedes Issue gehört zu genau einem Meilenstein** (Gruppen-Milestones M1–M4,
-  siehe [roadmap.md](roadmap.md)). Label und Meilenstein beantworten verschiedene
-  Fragen: `priority:*` sagt **wie dringend**, der Meilenstein sagt **worauf es
-  einzahlt**. Ein Issue ohne Meilenstein taucht in keiner Roadmap-Ansicht auf und
-  ist damit praktisch unsichtbar — es existiert nur noch für den, der es angelegt
-  hat.
-  M1–M4 haben **bewusst kein Enddatum**: Sie bündeln, sie simulieren keinen
-  Termindruck. Termindruck steht als Datum am einzelnen Issue.
-
-## Secrets & Credentials
-
- **Token-/Secret-Werte niemals anzeigen, loggen oder in Dateien echoen** —
-  anzeigen = Exposure = Rotation. Echte Credentials tippt/legt sorb selbst an;
-  Sessions referenzieren sie nur über Dateipfade (z. B.
-  `~/.config/gitlab-lab/token`) oder maskierte CI-Variablen.
- Nicht-geheime Konfiguration wird direkt geschrieben und committet — die
-  Trennung ist „Credential vs. Config", nicht „alles über den Menschen".
-
-## Commit-Konventionen (seit 2026-08-07)
-
-Gilt für **alle** Repos der Gruppe `axion1337.chat` und die ThreadNet-Dienste.
-
- **Nachrichten auf Englisch**, Conventional-Commit-Stil: `feat:`, `fix:`,
-  `docs:`, `chore:`, `ci:`, `refactor:`. Der Betreff sagt *was*, der Rumpf *warum*.
- **Zeitstempel anonymisieren.** Autor- **und** Committer-Datum werden auf
-  **12:00:00 UTC des laufenden Tages** gesetzt, damit sich aus der Historie keine
-  persönlichen Arbeitszeiten ablesen lassen:
-
-  ```bash
-  export GIT_AUTHOR_DATE="$(date -u +%Y-%m-%d)T12:00:00Z" \
-         GIT_COMMITTER_DATE="$(date -u +%Y-%m-%d)T12:00:00Z"
-  git commit -m "…"
-  ```
-
-  ⚠️ **Beide Variablen setzen.** Nur `GIT_AUTHOR_DATE` zu setzen bringt nichts —
-  `git log` zeigt zwar das Autordatum, das Committer-Datum bleibt aber im Objekt
-  und ist über `git log --format=%cd` und in jeder Weboberfläche sichtbar.
-
-  📎 Die Umstellung der Alt-Historie am 2026-08-07 hat 251 Commits neue SHAs
-  gegeben. Ältere Verweise bleiben über
-  [`shared/commit-zuordnung-2026-08-07.md`](shared/commit-zuordnung-2026-08-07.md)
-  auflösbar — **statt** geschriebene Issue-Kommentare nachträglich zu ändern. Wer
-  eine SHA nicht findet, hat einen Commit von vor der Grenze vor sich; der gilt
-  unverändert.
-
-  ⚠️ **Das schützt nur die Git-Historie.** Push-Zeiten, Issue- und
-  Kommentar-Zeitstempel, Pipeline-Läufe und Paket-Veröffentlichungen tragen
-  weiterhin die echte Uhrzeit und liegen im selben GitLab bzw. auf dem
-  öffentlichen Gitea-Spiegel. Wer daraus wirklich keine Muster ableitbar haben
-  will, muss dort ansetzen — die Commit-Datumsregel allein reicht dafür nicht.
-
-## Redlichkeit & gelebte Lehren
-
- **Aussagen mit Quelle:** Verifiziert (Messung/Konsole) klar von Vermutung
-  trennen; nicht selbst Geprüftes als solches kennzeichnen. Korrelation ≠
-  Kausalität — ein plausibler Verdacht ist kein Befund.
- **Config-Dateien textuell/chirurgisch editieren, nie re-dumpen** (YAML/JSON
-  neu serialisieren hat zweimal real Schaden angerichtet). Compose-/YAML-
-  Änderungen vor dem Push validieren (`docker compose config`, YAML-Parse).
- Fehlschläge und übersprungene Schritte werden benannt, nicht geglättet;
-  „fertig" heißt verifiziert.
-
---
-name: karpathy-guidelines
-description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
-license: MIT
---
-
-# Karpathy Guidelines
-
-Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
-
-**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
-
-## 1. Think Before Coding
-
-**Don't assume. Don't hide confusion. Surface tradeoffs.**
-
-Before implementing:
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them - don't pick silently.
- If a simpler approach exists, say so. Push back when warranted.
- If something is unclear, stop. Name what's confusing. Ask.
-
-## 2. Simplicity First
-
-**Minimum code that solves the problem. Nothing speculative.**
-
- No features beyond what was asked.
- No abstractions for single-use code.
- No "flexibility" or "configurability" that wasn't requested.
- No error handling for impossible scenarios.
- If you write 200 lines and it could be 50, rewrite it.
-
-Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
-
-## 3. Surgical Changes
-
-**Touch only what you must. Clean up only your own mess.**
-
-When editing existing code:
- Don't "improve" adjacent code, comments, or formatting.
- Don't refactor things that aren't broken.
- Match existing style, even if you'd do it differently.
- If you notice unrelated dead code, mention it - don't delete it.
-
-When your changes create orphans:
- Remove imports/variables/functions that YOUR changes made unused.
- Don't remove pre-existing dead code unless asked.
-
-The test: Every changed line should trace directly to the user's request.
-
-## 4. Goal-Driven Execution
-
-**Define success criteria. Loop until verified.**
-
-Transform tasks into verifiable goals:
- "Add validation" → "Write tests for invalid inputs, then make them pass"
- "Fix the bug" → "Write a test that reproduces it, then make it pass"
- "Refactor X" → "Ensure tests pass before and after"
-
-For multi-step tasks, state a brief plan:
-```
-1. [Step] → verify: [check]
-2. [Step] → verify: [check]
-3. [Step] → verify: [check]
-```
-
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
---
-
-*Der Karpathy-Block oben ist wortgleich aus der gitops-CLAUDE.md übernommen und
-darf nicht bearbeitet werden (stehende Regel von sorb). Änderungen an dieser
-Datei insgesamt: nur mit sorb abgestimmt — sie ist die gemeinsame
-Arbeitsgrundlage aller Sessions.*
+Read AGENTS.md — the canonical instruction file for this repository. All rules live there.