diff --git a/docs/design/2026-08-11-neckbeard-migration.md b/docs/design/2026-08-11-neckbeard-migration.md index ab796cf..168cb20 100644 --- a/docs/design/2026-08-11-neckbeard-migration.md +++ b/docs/design/2026-08-11-neckbeard-migration.md @@ -1,6 +1,6 @@ --- type: design -status: gate-2 +status: gate-3 date: 2026-08-11 size: L related: @@ -314,3 +314,161 @@ Lücken 1–5 und 7 mit Feldtest-Evidenz, dazu +8 (Verzeichnis-Links), +9 Ausnahmen, und als Erfahrungswert: die Stillstandsprüfungs-Prinzipien (Prüfungen nur aus realen Fällen; Abbruch statt Skip) als Muster für eine künftige Laufzeit-Prüf-Familie neben `validate.py`. + +## Gate 3 — Programm-Design + +### Dateiorte (vollständig) + +**Wurzel — neu:** `AGENTS.md` (Upstream §1–5 wörtlich, dann Marke +``, dann „§6 Gruppenregeln"), `WORKFLOW.md` +(wörtlich v0.1.1), `schema.yaml` (v0.1.1 + Erweiterungen, im Kopf +ausgewiesen), `STATUS.md` (generiert). +**Wurzel — geändert:** `CLAUDE.md` → Pointer (wörtlich v0.1.1), +`roadmap.md` (Zahlen/„Stand" raus, M5 rein, Datei-Links), +`README.md` (Pfade/Struktur nachgezogen, Datei-Links), +`.gitlab-ci.yml` (+ Job `validate`, Stage `pruefen`, bei jedem Push). +**Wurzel — entfällt (git mv):** `decisions/`, `hosts/`, `verfahren/`, +`vision/`, `shared/`. + +**`docs/adr/`:** `0001…0010` portiert (Frontmatter ergänzt; Datum = +Original-Datum; Body unverändert bis auf umgezogene Link-Ziele), +`0011`/`0012` (accepted), `template.md` (v0.1.1). +**`docs/aar/`:** die 5 AARs aus `verfahren/aar/` (Dateinamen bleiben, +Frontmatter: die vier vom 2026-08-01/02 `harvested` — von der Retro +2026-08-09 geerntet; `2026-08-09-refinement-und-betrieb.md` `open`), +`template.md` (v0.1.1; ersetzt `aar-vorlage.md`). +**`docs/issues/`:** Import aller offenen management-Issues als +`NNNN-slug.md` (NNNN = GitLab-iid, vierstellig; Slug deterministisch +aus dem Titel: Kleinbuchstaben, Umlaute ae/oe/ue/ss, sonst `-`, +Alt-IDs bleiben im Titel), plus 5 neue Issues für die +F-004-Arbeitspunkte (IDs ab max(iid)+1), `template.md` (v0.1.1). +**`docs/components/`:** `management.md`, `threadnet-call.md`, +`thread-net-git.md`, `threadnet-operating.md`, +`axion1337.chat-gitops.md`, `ThreadNet-Web.md` (Dateiname = Slug, +buchstabengetreu), dazu `game-operating.md`, `gameserver.md` +(`phase: external`). +**`docs/wiki/`:** `index.md` (projektangepasst: Area-Tabelle + `vision`; +nicht in der Baseline), `admin/`: `cfgmon.md`, `game.md`, `matrix.md`, +`overmind.md`, `refinement.md`, `stillstandspruefung.md`, +`textbloecke.md`; `deployment/`: `deploy-uebergabe.md`; +`architecture/`: `branding.md`, `lab-netzwerk.md`, `zone-axion1337.md`; +`vision/`: `axion1337-chat.md`, `homelab.md`, `threadnet.md`. +**`docs/sources/`:** `regelwerk/karpathy-guidelines.md`; +`upstream/neckbeard-v0.1.1/` (AGENTS.md, CLAUDE.md, WORKFLOW.md, +schema.yaml, die 4 Templates, validate.py, gen_status.py, dazu +`HERKUNFT.md` mit Tag/SHA); `protokolle/retro-2026-08-09.md`; +`migration/commit-zuordnung-2026-08-07.md`, +`migration/issue-migration/README.md`, +`migration/import_issues.py` + `migration/issue-import-protokoll.md` +(Einmal-Werkzeug und sein Protokoll — Aufzeichnung, kein Dauerbetrieb). +**`scripts/`:** `validate.py` (v0.1.1 + 3 Regeln), `gen_status.py` +(v0.1.1 + Meilenstein-/Prioritätsspalten und -verteilung), +`pruefe_upstream_drift.py` (neu), `pruefe_prosa.py` (neu), +`gruppenpruefung.py` (neu), `spiegel_issues.py` (neu); +`stillstandspruefung.py` unangetastet. + +### Schema-Erweiterungen (exakt) + +```yaml +# issue — zusätzlich: +required: [type, id, status, created, milestone, priority] +status: { enum: [open, next, in-progress, waiting, done, rejected] } +milestone: { enum: [M1, M2, M3, M4, M5] } +priority: { enum: [high, medium, low] } +due: { kind: date, nullable: true } +host: { enum: [cfgmon, overmind, matrix, game], nullable: true } +area: { enum: [security, infrastructure, database, element], nullable: true } +wartegrund: { kind: str, nullable: true } +gitlab_iid: { pattern: "^\\d+$", nullable: true } +rules: [waiting_requires_reason] # + global: wip_limit +# component — neuer Typ: +component: + dir: "docs/components" + filename: "^[A-Za-z0-9.-]+\\.md$" + required: [type, slug, anzeigename, phase] + fields: + slug: { kind: str } # rule: slug_matches_filename + anzeigename: { kind: str } + phase: { enum: [active, staged, external] } + gitlab: { kind: str } + mirror: { kind: str, nullable: true } + related: { kind: links } + rules: [slug_matches_filename] +# wiki-page.area — Enum + vision +``` + +### Signaturen (keine Rümpfe) + +```text +validate.py [repo-root] # + Regeln: wip_limit (≤2 in-progress, repoweit), + # waiting_requires_reason, slug_matches_filename +gen_status.py [--check] [repo-root] # Issues-Tabelle + Spalten milestone/priority + # + Verteilungszeile je Meilenstein +pruefe_upstream_drift.py [repo-root] # Byte-Vergleich Arbeitsdatei ↔ sources/upstream; + # AGENTS.md: Präfix bis Marke; exit 1 bei Abweichung +pruefe_prosa.py [repo-root] # (a) SHA-Zitate in docs/** + Wurzel-*.md auflösen + # (git cat-file, sonst Zuordnungstabelle, sonst FEHLER) + # (b) Aufgabenmarker in docs/wiki/** ohne Issue-Verweis + # (c) Sperrliste stillgelegter URL-Muster (toter Gitea-Tracker) +gruppenpruefung.py # Lab-CI, Token aus Umgebung, Abbruch ohne Token: + # Gruppenliste (Laufzeit) ↔ docs/components/; + # Pointer-Präsenz je active/staged-Komponente; + # Issue-Drift docs/issues ↔ GitLab (Titel/Status/ + # Meilenstein/Priorität); Git-Hygiene (Commits nach + # 2026-08-07 ≠ 12:00:00Z oder fremde Identität = Befund) +spiegel_issues.py [--ausfuehren] # Default Dry-Run: druckt geplante API-Aufrufe; + # --ausfuehren nur durch sorb; Repo → GitLab, nie zurück +``` + +**CI-Fluss:** Job `validate` (jeder Push, offline): +`validate.py && gen_status.py --check && pruefe_upstream_drift.py && +pruefe_prosa.py`. Job `stillstandspruefung` (geplant/manuell) wie +bisher; `gruppenpruefung` daneben, gleiche Regeln (rot = Alarm, +Abbruch statt Skip). + +### Was die Prüfungen zusichern (inkl. Muster-Demonstration, Kriterium 5) + +| Prüfung | Zusicherung / Demo | +|---|---| +| Negativtests (Scratch-Bäume, je Regel einer) | 3× in-progress → Fehler; `waiting` ohne `wartegrund` → Fehler; Component-Slug ≠ Dateiname → Fehler; 1 Byte Abweichung in WORKFLOW.md → Fehler; Schöpfungs-AAR-Lehre: grüner Validator ohne Negativtest zählt nicht | +| **Muster A** | Meilenstein-Abgleich gegen den eingefrorenen Session-1-Export: Alt-`CLAUDE.md` („M1–M4") ↔ Export (M5 existiert) → feuert | +| **Muster B** | Git-Hygiene über die lokalen Komponenten-Klone → feuert (Erwartung: die 237 Echtzeit-Commits aus F-002) | +| **Muster C** | `pruefe_prosa.py` auf dem Vor-Migrations-Stand von `hosts/` → feuert auf die 5 F-004-Punkte; nach Migration: 0 | +| **Muster D** | SHA-Auflösung auf Vor-Migrations-Stand → feuert auf die 6 verwaisten Zitate aus F-012; Auflösung über die Zuordnungstabelle nachgewiesen | + +### DO NOT CHANGE + +- Der Analyse-Branch und alles unter `analysis/`. +- Substanz der portierten Texte: ADR-Bodies, AARs, Retro, Zuordnung, + Karpathy-Block, Hosts-/Visions-Prosa — nur Umzug, Frontmatter, + Link-Ziele; inhaltliche Korrektur **nur** wo ein Dokument dem + Werkzeugstand widerspricht (roadmap M5, Alt-CLAUDE-Regeln gehen in + AGENTS §6 in korrigierter Fassung). +- `scripts/stillstandspruefung.py`, `ci/lab-ca-chain.crt`, + `.gitlab/issue_templates/` — unangetastet. +- GitLab-Zustand: kein Issue, Label, Meilenstein, Board wird verändert; + `spiegel_issues.py` läuft in dieser Undertaking nur als Dry-Run. +- Kein `git push`; Tokenwert erscheint in keiner Ausgabe. +- Upstream-Framework-Texte §1–5 / WORKFLOW / Templates: byte-treu. + +### Wackligste Annahmen (benannt, Stand Gate 3) + +1. **AAR-Erntestatus**: „die vier alten AARs sind geerntet" schließe ich + aus der Retro-Existenz, nicht aus einer Erntemarke — sorb kann das + im Refinement kippen. +2. **Enums aus dem Ist-Stand eingefroren** (host/area/M1–M5): jeder + neue Host oder Meilenstein braucht künftig einen Schema-Commit. + Gewollt (sichtbare Änderung), aber Reibung. +3. **Slug-Erzeugung aus deutschen Titeln** muss deterministisch und + kollisionsfrei sein; bei Kollision entscheidet die iid, nicht der + Slug. +4. **Git-Hygiene per API vs. lokale Klone**: die Demo läuft auf den + lokalen Klonen; die CI-Fassung per API kann bei großen Historien + paginieren müssen — begrenzt auf Commits seit 2026-08-07. +5. **Verdichtung von Alt-CLAUDE.md nach AGENTS §6**: Welche Sätze + Regelrang behalten und welche ins Wiki wandern, ist Urteilssache; + Volltext überlebt in ADRs/Wiki/sources, aber eine tragende Nuance + könnte aus dem Immer-geladen-Teil fallen. +6. **`gen_status.py`-Fork-Tiefe**: je mehr das Generat zeigt, desto + weiter entfernt es sich vom Upstream; gewählt ist die kleinste + Erweiterung, die die Roadmap-Zahlen ersetzt.