management/docs/design/2026-08-11-neckbeard-migration.md

type, status, date, size, related

type	status	date	size	related
design	gate-2	2026-08-11	L	PROJECT.md decisions/0005-pm-framework-kanban.md decisions/0009-commit-konventionen-und-historien-anonymisierung.md decisions/0010-haertung-eigener-meilenstein.md docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md docs/adr/0012-gruppenregeln-kanonisch-mit-pruefung.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.

Gate 2 — Architektur

Gelesen (Pflichtlektüre vor den Optionen)

Alt-Ansatz: CLAUDE.md, roadmap.md, decisions/README.md und die tragenden Entscheidungen 0001, 0002, 0005, 0009, 0010, verfahren/refinement.md, verfahren/stillstandspruefung.md, .gitlab-ci.yml, Auszüge aus hosts/. Neckbeard v0.1.1: AGENTS.md, WORKFLOW.md, ADR-0001…0004/0006, schema.yaml, validate.py, gen_status.py, Schöpfungs-AAR, docs/wiki/index.md. Session-1-Daten (lesend vom Analyse-Branch): gitlab_issues.json — 111 Issues, 71 offen; 71/71 mit genau einem Meilenstein (M1 19 · M2 22 · M3 4 · M4 12 · M5 14) und 71/71 mit genau einer Priorität (low 32, medium 34, high 5). Die Entscheidungen 0003/0004/0006/0007/0008 werden bei der Portierung (Gate 4) vollständig gelesen; sie tragen keine Architekturfrage dieser Undertaking.

Ernte, Teil 1 — die Fehlermuster beider Ansätze

Wo genau versagte der alte Ansatz, was hält neckbeard dagegen, und wo bleibt auch mit neckbeard ein Loch:

Muster	Wurzel im Alt-Ansatz	Neckbeard-Gegenstück	Verbleibendes Loch → Mechanismus dieser Migration
A — Doku nicht nachgezogen (F-001, F-005, F-007, F-010, F-017)	Zustand steht als behauptete Zahl/Prosa an mehreren Stellen; nichts vergleicht	Generiertes STATUS.md (gen_status.py --check in CI), ADRs nie editiert nur abgelöst	Prosa, die Forge-Zustand behauptet, prüft neckbeard nicht → Drift-Prüfung Repo↔GitLab; Meilenstein-Satz als Schema-Enum (eine Quelle); „Stand"-Etiketten entfallen ersatzlos (git log antwortet)
B — Regel repo-weit, Anwendung Teilmenge (F-002, F-003, F-008, F-011)	Regel gilt „für alle Repos", kein Artefakt zählt die Repos auf, kein Skript läuft über alle	Lücke — ADR-0001 endet an der Repo-Grenze	Komponenten-Artefakt + Abgleich gegen die zur Laufzeit gelesene Gruppenliste (ADR-0012); Git-Hygiene-Prüfung (12:00Z-Zeitstempel, kanonische Identität) über alle deklarierten Repos
C — zwei Backlogs (F-004, F-009)	hosts/-Markdown hielt „Nächste Schritte" neben dem Board	In-Repo-Issues, ein Ort	Wiki-Seiten können wieder Aufgabenprosa ansammeln → Prüfregel: Aufgaben-Marker („Nächster Schritt", offene Checkboxen) in Wiki-Seiten ohne Issue-Verweis sind ein Befund
D — Artefakte ohne Eigentümer überleben (F-006, F-012)	Branches/SHA-Zitate hat niemand je gelesen	warn_if_orphan nur für Wiki-Seiten	Branch-Hygiene (Alter/Divergenz verwaister Branches) und SHA-Auflösung inkl. Zuordnungstabelle in der Prüf-Familie; Refinement-Agenda erhält den Punkt

Die sieben neckbeard-Lücken, Disposition (Akzeptanzkriterium 6, 7/7):

#	Lücke	Disposition
1	Viele Repos, ein Regelwerk	Eingefaltet: ADR-0012 (Pointer + Prüfung)
2	Kein Komponenten-Artefakt	Eingefaltet: Schema-Typ component, docs/components/ (ADR-0012)
3	Kein Meilenstein-Konzept	Eingefaltet: Pflichtfeld milestone im Issue-Schema (ADR-0011)
4	SHA-Zitate unaufgelöst	Eingefaltet (projektseitig): Prüfskript nach Vorbild inv_shas.py; Upstream-Kandidat
5	Git-Hygiene außerhalb des Blickfelds	Eingefaltet (projektseitig): Hygiene-Prüfung in der CI-Familie; Upstream-Kandidat
6	Externe Link-Ziele ungeprüft	Teilweise eingefaltet: Sperrliste stillgelegter Ziele (toter Gitea-Tracker, F-005) als deterministische Prüfung; echte Erreichbarkeitsprüfung verworfen (netzabhängig, nichtdeterministisch — widerspricht validate-Philosophie)
7	Prioritätsfeld als YAGNI verworfen	Eingefaltet: Pflichtfeld priority — der Feldtest liefert die Evidenz (71/71, klar getrennt vom Meilenstein), die das Schöpfungs-AAR fürs Wiedervorlegen verlangte
+8	(neu, diese Session) validate.py lehnt Verzeichnis-Links ab	Migration ersetzt Verzeichnis- durch Datei-Ziele; Upstream-Kandidat (Meinungsfrage)
+9	(neu) Kein definierter Ort für Projektregeln im übernommenen AGENTS.md	Projektregeln als ausgewiesener eigener Abschnitt unter den unveränderten Upstream-Abschnitten; Upstream-Kandidat

Ernte, Teil 2 — Wert des Alt-Ansatzes, eingefaltet (4/4 + Zusatz)

Wert	Erhaltungsmechanismus
F-014 Issue-Hygiene (Meilensteinpflicht, eine Priorität, ein Status, WIP-Limit, keine ID-Wiederverwendung)	Wird von Konvention zu Schema: milestone/priority Pflichtfelder, Status-Enum, WIP-Limit als Validator-Regel, Duplikat-ID-Prüfung existiert in validate.py bereits; Board bleibt via Spiegel erhalten (ADR-0011)
F-013 Mirror-Topologie mit Begründung, Gegenargument, Rettungspfad	Alt-ADRs 0001/0004 werden unverändert portiert; die „Warum zwei Orte"-Prosa und der Rettungspfad ziehen als Wiki-Seiten um; Mirror-Sync bleibt Stillstandsprüfung
F-015 Rewrite-Zuordnung, 251/251 verifiziert	shared/commit-zuordnung-2026-08-07.md → docs/sources/ (unveränderlich, agentenschreibgeschützt); SHA-Prüfung löst über die Tabelle auf; die Zuordnungs-Auflage für künftige Rewrites steht im portierten ADR-0009
F-016 Redliche Selbstdokumentation	„Redlichkeit"-Regeln ziehen in den Projektabschnitt von AGENTS.md; AAR-/Retro-Kultur bleibt (AARs → docs/aar/, Retro-Protokolle → docs/sources/)
Stillstandsprüfungs-Prinzipien	Bleiben wörtlich: Prüfungen nur aus realen Fällen; „kann nicht prüfen" ist Befund, nicht Skip; Abbruch statt stillem Überspringen; Projektliste zur Laufzeit. Die neuen Gruppen-Prüfungen (ADR-0012, Hygiene, Drift) treten dieser Familie bei
Board-Pflege-Rechte (Zusage-Spalten nur sorb)	Prozessregel im AGENTS.md-Projektabschnitt; Refinement-Ablauf zieht als Wiki-Seite um und instanziiert die WORKFLOW-Agenda (Board rechts-nach-links, Nachziehen, Entscheidungsvorlagen mit Empfehlung, Datumspflicht)
ADR-Pflicht bei dauerhaften Ausnahmen	Übernommen in den Projektabschnitt — neckbeard kennt diese Regel selbst nicht (Upstream-Kandidat)

Zielarchitektur

Migrationslandkarte (alt → neu; Inhalte unverändert, sofern nicht werkzeugwidersprechend — Nicht-Ziel „kein Umschreiben"):

Alt	Neu
CLAUDE.md	Ein-Zeilen-Pointer; Regeln → AGENTS.md (Upstream-Abschnitte wörtlich + Abschnitt „Gruppenregeln"); Karpathy-Block wortgleich → docs/sources/karpathy-guidelines.md, aus AGENTS.md zitiert (Freigabe sorb nötig — stehende Regel)
decisions/0001…0010	docs/adr/0001…0010, Frontmatter ergänzt, Text unverändert; decisions/ entfällt, Verweise nachgezogen
roadmap.md	Bleibt als Linien/Reihenfolge-Prosa; alle Zählungen und „Stand"-Blöcke raus (→ generiertes STATUS.md); M5 statt „offene Frage" (F-001)
verfahren/aar/* (5)	docs/aar/*, Frontmatter (open/harvested nach Retro-Lage)
verfahren/retro/*	docs/sources/retro/* (unveränderliche Protokolle)
verfahren/refinement.md	docs/wiki/admin/refinement.md
verfahren/deploy-uebergabe.md	docs/wiki/deployment/deploy-uebergabe.md
verfahren/stillstandspruefung.md	docs/wiki/admin/stillstandspruefung.md
verfahren/textbloecke.md	docs/wiki/admin/textbloecke.md (Pfade angepasst)
verfahren/issue-migration/	docs/sources/issue-migration/
verfahren/aar-vorlage.md	ersetzt durch neckbeards docs/aar/template.md
hosts/* (4)	docs/wiki/admin/<host>.md; offene Arbeitspunkte → Issues (F-004, 5/5)
vision/* (3)	docs/wiki/vision/* (neue Wiki-Area vision — Alt-Wert „eine Datei je Linie", altes ADR-0005)
shared/branding.md, lab-netzwerk.md, zone-axion1337.md	docs/wiki/architecture/*
shared/commit-zuordnung-2026-08-07.md	docs/sources/commit-zuordnung-2026-08-07.md
— (neu)	PROJECT.md ✓, WORKFLOW.md (wörtlich v0.1.1), schema.yaml (v0.1.1 + ausgewiesene Erweiterungen), STATUS.md (generiert), docs/components/ (6 Deklarationen: 5 Komponenten + management; game-operating/gameserver als external), docs/issues/ (importierte offene management-Issues + F-004-Nachzügler)
scripts/stillstandspruefung.py, ci/	Bleiben; dazu validate.py, gen_status.py (v0.1.1) und die neuen Prüfskripte; .gitlab-ci.yml erhält einen Offline-Job validate (jeder Push) neben der geplanten Stillstandsprüfung

Prüf-Architektur — zwei Familien, scharfe Grenze:

• Offline & deterministisch (validate.py, gen_status.py --check, SHA-Auflösung, Wiki-Aufgabenmarker, Sperrlisten-Check): läuft bei jedem Push, braucht nur den Baum. Kein Netz, keine Uhrzeit.
• Verbund & Laufzeit (Stillstandsprüfungs-Familie: Mirror-Sync, Issue-Drift Repo↔GitLab, Pointer-Präsenz, Gruppenliste↔docs/components/, Git-Hygiene über die Gruppe): geplant/manuell in der Lab-CI, Token über maskierte Variablen, Abbruch statt stillem Skip, Befund = rote Pipeline = Alarmanlage.

flowchart LR
    S[Session-Start] --> A[CLAUDE.md → AGENTS.md<br/>+ PROJECT.md + STATUS.md]
    A --> W[Arbeit nach Gates<br/>Artefakte in docs/]
    W --> C[Commit 12:00Z]
    C --> V{CI: validate.py +<br/>gen_status --check}
    V -- rot --> W
    V -- grün --> M[Spiegel-Skript<br/>dry-run → sorb triggert]
    M --> B[GitLab-Board/Meilensteine<br/>= Ansicht, nicht Wahrheit]
    B --> R[Refinement sonntags<br/>Board + STATUS.md]
    R --> W
    P[Stillstandsprüfung + Gruppen-Checks<br/>geplant, Lab-CI] -. Befund = Issue .-> R

Entscheidungen

Die zwei tragenden Richtungsentscheidungen stehen als ADRs (Status proposed, werden mit diesem Gate wirksam):

• ADR-0011 — Issues im Repo kanonisch (Management-Scope), GitLab als deterministisch bespielter Spiegel; Optionen A/B/C abgewogen im ADR.
• ADR-0012 — Gruppenregeln kanonisch hier, Komponenten tragen Pointer, ein Komponenten-Artefakt macht die Gruppe prüfbar; Kopie/Submodule verworfen im ADR.

Feature-lokale Entscheidungen (bleiben hier):

1. Framework-Dateien wörtlich übernehmen (AGENTS.md-Abschnitte 1–5, WORKFLOW.md, Templates, Skripte) — jede Abweichung vom Upstream bleibt per Diff gegen v0.1.1 sichtbar; Projektspezifika leben ausschließlich im ausgewiesenen AGENTS-Abschnitt, in ADRs, Wiki und schema.yaml-Erweiterungen.
2. Issue-Nummern: GitLab-iid = Datei-id für Importierte; neue Issues zählen ab Maximum weiter; gitlab_iid-Feld hält die Spiegelung. Keine dritte Nummernwelt, keine ID-Wiederverwendung.
3. Status-Enum erweitert um next und waiting (Grund-Pflicht bei waiting) — die Board-Spalten sind belegter Alt-Wert; ein Mapping auf nur open/in-progress würde die einzige Zusage-Semantik (status:next) wegwerfen.
4. Slugs werden nicht umbenannt (F-008): Rename = Forge-Eingriff, eigenes Issue; das Komponenten-Artefakt dokumentiert den Ist-Stand.
5. Verzeichnis-Links in Prosa werden auf Datei-Ziele umgestellt (Lücke +8).
6. analysis/ und drafts/ des Analyse-Branches bleiben dort; nichts davon wird auf diesen Branch geholt.

Constraints

• Mirror-Topologie unangetastet: Flux-Quelle bleibt Gitea, keine direkten Gitea-Pushes, Kanonisierungs-Verfahren gilt weiter.
• Kein API-Schreibzugriff ohne menschlichen Trigger; das Spiegel-Skript hat --dry-run als Default. Diese Session pusht nichts.
• Commit-Konventionen (englisch, 12:00:00 UTC, kanonische Identität) gelten für jeden Migrations-Commit.
• Artefaktsprache Deutsch (PROJECT.md), Upstream-Framework-Texte bleiben englisch — der Diff-Abgleich gegen v0.1.1 wiegt schwerer als Sprachreinheit.
• Secrets-Regeln unverändert (Token nur per Pfad/maskierter Variable).
• Die Historien-Remediation (F-002/F-003) bleibt draußen; jedes künftige Rewrite trägt die Zuordnungs-Auflage (portiertes ADR-0009).

Rückmeldungen an neckbeard (Kandidaten, eigener Akt — nicht Teil dieser Undertaking)

Lücken 1–5 und 7 mit Feldtest-Evidenz, dazu +8 (Verzeichnis-Links), +9 (Ort für Projektregeln), die fehlende ADR-Pflicht bei dauerhaften 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.