From 2daadb8ba69c13569d14ec9d69072e6c07048b80 Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Tue, 11 Aug 2026 12:00:00 +0000 Subject: [PATCH] docs: add migration design doc, Gate 1 (product) Problem statement built on the four drift patterns from the Session-1 field test, six numeric acceptance criteria, non-goals (no history rewrite, no push, no component rollout, no forge-state destruction), announcement paragraph. Gates 2-5 deliberately not pre-filled, per WORKFLOW.md. Frontmatter validates against neckbeard v0.1.1 schema with 0 errors for this file. Co-Authored-By: Claude Fable 5 --- docs/design/2026-08-11-neckbeard-migration.md | 129 ++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 docs/design/2026-08-11-neckbeard-migration.md diff --git a/docs/design/2026-08-11-neckbeard-migration.md b/docs/design/2026-08-11-neckbeard-migration.md new file mode 100644 index 0000000..432e526 --- /dev/null +++ b/docs/design/2026-08-11-neckbeard-migration.md @@ -0,0 +1,129 @@ +--- +type: design +status: gate-1 +date: 2026-08-11 +size: L +related: + - "PROJECT.md" + - "decisions/0005-pm-framework-kanban.md" + - "decisions/0009-commit-konventionen-und-historien-anonymisierung.md" + - "decisions/0010-haertung-eigener-meilenstein.md" +--- + +# Design: Migration des Management-Systems auf neckbeard + +Grundlage: der Feldtest-Report auf dem Branch `Neckbeard-v0.1.1-analyse-1` +(Session 1, eingefroren; Befunde F-001…F-017), gemessen gegen neckbeard +v0.1.1 @ `823a08cac6b03a47d7e2f661200a49ac6e09d38d`. Bindende Vorgabe aus +der Übergabe: **erst die Fehlermuster beider Ansätze durcharbeiten und den +Wert des alten Ansatzes in neckbeard einfalten — Übernahme erst danach.** + +## Gate 1 — Produkt + +### Problem + +Das Management-Repo steuert fünf Komponenten-Repos und sich selbst mit +einem eigenen Regelwerk. Der Feldtest zeigt: Das Regelwerk ist nicht +verfallen, sondern **ungleich durchgesetzt**. Wo ein Werkzeug die Regel +hält, hält sie vollständig — alle 71 offenen Issues haben genau einen +Meilenstein, das WIP-Limit steht, 0 von 161 Dokument-Links sind tot +(F-014). Wo nichts prüft — Prosa, Git-Metadaten, Übereinstimmung zweier +Dateien — versagt dasselbe Regelwerk wiederholt, in vier Mustern: + +- **A** — Entscheidung im Werkzeug vollzogen, Doku nicht nachgezogen: + M5 existiert und trägt 14 Issues, aber `roadmap.md` stellt ihn als + offene Frage dar und die kanonische Arbeitsgrundlage bindet Issues an + „M1–M4" (F-001; ferner F-005, F-007, F-010, F-017). +- **B** — Regel repo-weit erklärt, auf eine Teilmenge angewandt: + Zeitstempel-Anonymisierung erreicht 1 von 6 Repos, 5 Autor-Identitäten + einer Person überleben, 4 von 5 Komponenten haben kein versprochenes + CLAUDE.md, fünf Komponenten tragen vier Namensschemata (F-002, F-003, + F-008, F-011). +- **C** — zwei Backlogs, eine Regel: fünf offene Arbeitspunkte leben nur + in `hosts/`-Markdown, unsichtbar für Board, Meilenstein und Priorität + (F-004, F-009). +- **D** — Artefakte überleben ihren Zweck ohne Eigentümer: verwaiste + Branches publizieren Vor-Rewrite-Historie, zitierte SHAs sind + unauflösbar (F-006, F-012). + +Betroffen sind sorb und jede Agenten-Session: Jede neue Session wird von +der kanonischen Datei falsch geprimt und würde vollzogene Entscheidungen +rückgängig machen. Neckbeard adressiert genau diese Klasse — hält aber +selbst sieben im Feldtest belegte Lücken, allen voran: ADR-0001 löst +„ein Repo, viele Harnesse", dieses Projekt ist „viele Repos, ein +Regelwerk", und für die Frage, wo die 71 offenen GitLab-Issues nach der +Migration leben, existiert nur eine aufgeschobene Option C. Beide +Entscheidungen fallen in Gate 2, jeweils als ADR. + +Das Produkt dieser Undertaking: das Management-System dieses Repos auf +neckbeard umziehen, so dass die vorhandene Disziplin von Stellen, die +nur ein Mensch prüfen kann, an Stellen wandert, die ein Skript prüft — +nachdem der Wert des alten Ansatzes (F-013…F-016, Meilenstein-/ +Prioritäts-Evidenz, Mirror-Topologie-Prosa) in neckbeard eingefaltet +wurde. + +### Akzeptanzkriterien (verifizierbar) + +1. **Deterministische Gates grün:** `scripts/validate.py` meldet auf dem + migrierten Repo 0 Fehler; `scripts/gen_status.py --check` meldet + STATUS.md aktuell. +2. **Entscheidungen portiert:** alle 10 Entscheidungen + (`decisions/0001…0010`) liegen als ADRs mit schema-konformem + Frontmatter unter `docs/adr/` — 10/10 validieren. +3. **Ein Backlog:** die fünf Arbeitspunkte aus F-004 (OVERMIND-01, + CFGMON-11/12/13, MATRIX-05) existieren als Issues im kanonischen + System — 5/5; 0 offene „Nächste Schritte" in `hosts/` ohne + Issue-Referenz. +4. **Generierte statt behaupteter Zustand:** 0 handgepflegte Zählungen + und „Stand"-Etiketten in kanonischen Dateien, wo ein Generat sie + ersetzt; kein kanonisches Dokument widerspricht dem Werkzeugstand + bei den Meilensteinen (M1–M5). +5. **Muster → Mechanismus:** für jedes Driftmuster A–D benennt das + Design mindestens einen deterministischen Check, und pro Muster feuert + mindestens ein Check nachweislich auf dem Vor-Migrations-Stand — 4/4 + demonstriert. +6. **Ernte dokumentiert:** 7/7 neckbeard-Lücken mit Disposition + (eingefaltet / als Framework-Issue notiert / verworfen mit Grund); + 4/4 Works-well-Befunde mit benanntem Erhaltungsmechanismus oder + begründetem Verzicht. + +### Nicht-Ziele + +- **Keine Historien-Umschreibung.** Die F-002/F-003-Remediation ist ein + eigener Vorgang mit eigener bindender Auflage (Zuordnung im Stil von + `shared/commit-zuordnung-2026-08-07.md`); diese Undertaking darf ihr + nur nicht im Weg stehen. +- **Kein Push** nach git.lab oder Gitea; der Branch bleibt lokal bis zur + Freigabe durch sorb. +- **Keine Änderung am neckbeard-Upstream.** Lücken werden hier + dispositioniert; sie dort einzureichen ist ein eigener Akt. +- **Kein Rollout in die fünf Komponenten-Repos** über das hinaus, was + die Shared-Ruleset-Entscheidung (Gate 2) zwingend erfordert; der + Rollout wird als Folge-Issues angelegt, nicht hier gebaut. +- **Kein Forge-Zustand wird zerstört:** keine Löschung von + GitLab-Issues, Labels, Meilensteinen oder dem Board durch die + Migration selbst. +- **`analysis/` bleibt eingefroren** — der Branch von Session 1 wird + weder verändert noch umgebaut. +- **Kein inhaltliches Umschreiben** des Host-/Visions-/Verfahrenswissens: + Umzug, Frontmatter und Korrektur werkzeugwidersprechender Aussagen ja, + Neuformulierung nein. + +### Ankündigung + +Das Management-Repo der Gruppe axion1337.chat zieht auf das +neckbeard-Framework um. Die vorhandene Disziplin — Meilensteinpflicht, +Status-Disziplin, ADR-Pflicht, AARs — bleibt erhalten, wandert aber von +Stellen, die nur ein Mensch prüfen kann, an Stellen, die ein Skript +prüft: Frontmatter statt Prosa, generiertes STATUS.md statt +handgepflegter Zählungen, `validate.py` statt Konventionstreue aus dem +Gedächtnis. Die vier Driftmuster des Feldtests bekommen je einen +deterministischen Check, und was der alte Ansatz besser kann als +neckbeard, wird zuerst ins Framework eingefaltet statt verworfen. +Zielgruppe sind sorb und alle Agenten-Sessions, die künftig von einer +Quelle starten, die sich nicht selbst widerspricht. + +### UI + +Keine UI beteiligt — Artefakte sind Markdown-Dateien, die Oberfläche +bleibt GitLab/Obsidian/Editor. Mockups entfallen.