From 6b8869f160b1cd43ff32d3a7950e02cb21227dec Mon Sep 17 00:00:00 2001 From: Thore Cimbal Date: Tue, 11 Aug 2026 12:00:00 +0000 Subject: [PATCH] docs: design doc Gate 2 (architecture) with ADR-0011 and ADR-0012 Two-way harvest as mandated by the Session-1 handoff: failure patterns of both approaches tabled with the mechanism that closes each, all seven neckbeard gaps dispositioned (plus two new ones found this session), and the old approach's proven value folded into the target architecture. Two directional decisions filed as proposed ADRs: issues live in-repo with GitLab as a deterministically mirrored view (0011), group rules canonical here with pointer components and a checkable components artifact (0012). Migration map, check architecture split offline/runtime, constraints, upstream feedback candidates. Co-Authored-By: Claude Fable 5 --- .../0011-issues-im-repo-gitlab-als-spiegel.md | 88 +++++++++ ...12-gruppenregeln-kanonisch-mit-pruefung.md | 85 +++++++++ docs/design/2026-08-11-neckbeard-migration.md | 167 +++++++++++++++++- 3 files changed, 339 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md create mode 100644 docs/adr/0012-gruppenregeln-kanonisch-mit-pruefung.md diff --git a/docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md b/docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md new file mode 100644 index 0000000..c39b739 --- /dev/null +++ b/docs/adr/0011-issues-im-repo-gitlab-als-spiegel.md @@ -0,0 +1,88 @@ +--- +type: adr +id: "0011" +status: proposed +date: 2026-08-11 +supersedes: null +superseded_by: null +related: + - "docs/design/2026-08-11-neckbeard-migration.md" + - "decisions/0002-issues-und-management-ins-lab.md" + - "decisions/0005-pm-framework-kanban.md" +--- + +# ADR-0011: Issues leben im Repo; GitLab wird deterministisch bespiegelt + +## Kontext + +Die Gruppe führt 111 Issues auf git.lab, davon 71 offen; die Disziplin ist +belegt intakt (F-014: 71/71 mit genau einem Meilenstein, 71/71 mit +Priorität, WIP-Limit gehalten). Neckbeards ADR-0002 macht In-Repo-Issues +zum Default und vertagt die Spiegel-Option C. Der Feldtest zeigt beides: +Die Forge erzwingt sichtbar, was Prosa nicht hält (F-001, F-017 — +Dokumente widersprechen dem Board), und Host-Sessions ohne Lab-Zugang +können GitLab-Issues gar nicht lesen, wohl aber den Gitea-Mirror dieses +Repos. Der alte Grundsatz „Alles Offene ist ein Issue" (altes ADR-0005) +scheiterte nur dort, wo Arbeitspunkte in `hosts/`-Markdown lebten (F-004) +— am zweiten Backlog, nicht am Board. + +## Optionen + +**A: GitLab bleibt kanonisch, Repo hält nur einen Export.** Tagesablauf +unverändert, Board bleibt Arbeitsfläche. Aber: dauerhafte Ausnahme von +neckbeards ADR-0002 (nach eigener Regel ADR-pflichtig), Issues bleiben +für Host-Sessions unsichtbar und für Agenten nur per API erreichbar, und +die Klasse „Prosa widerspricht Board" (F-001) bleibt strukturell offen — +generierte Dokumente hingen an einem Netzzugriff. + +**B: Reine In-Repo-Issues, GitLab-Issues geschlossen.** Sauberste +neckbeard-Form. Aber: das Gruppenboard verliert den Management-Scope, +Meilenstein-Ansichten werden unvollständig, das Refinement liest zwei +Systeme — genau die belegte Disziplin (F-014) würde ihres Werkzeugs +beraubt. Der Report warnt ausdrücklich: nicht per Board-Löschung +migrieren. + +**C: Repo kanonisch, GitLab als generierter Spiegel.** Die Issue-Wahrheit +liegt als `docs/issues/NNNN-slug.md` im Repo (grepbar, offline, über den +Gitea-Mirror überall lesbar); ein deterministisches Skript spiegelt +Titel, Status, Meilenstein, Priorität und Fälligkeit nach GitLab, damit +Board-, Meilenstein- und Label-Ansichten weiterarbeiten. Eine +Drift-Prüfung meldet Abweichungen zwischen Board und Repo rot. + +## Entscheidung + +**Option C, beschränkt auf den Management-Scope.** + +- `docs/issues/` wird kanonisch für die Issues des management-Projekts. + Die offenen management-Issues werden aus dem GitLab-Stand importiert + und behalten ihre Nummern (GitLab-iid = Datei-id; keine dritte + Nummernwelt). Alt-IDs wie `CFGMON-01` bleiben im Titel. +- Das Schema trägt die belegten Pflichten: `milestone` (Pflicht, M1–M5) + und `priority` (Pflicht, high/medium/low), dazu `due` (Datum statt + „bald"), optional `host`/`area`. Der Status-Enum wird um die + Board-Spalten erweitert (`next`, `waiting` mit benanntem Grund); das + WIP-Limit (max. 2 in-progress) wird eine Validator-Regel. +- Der Spiegel ist **ein** deterministisches Skript (Repo → GitLab), + Standard `--dry-run`; echte Läufe stößt sorb an. Board-Handgriffe + bleiben erlaubt, sind aber nicht kanonisch: Was nicht nachgezogen + wird, meldet die Drift-Prüfung. Die Zusage-Spalten (`next`, + `in-progress`) vergibt weiterhin nur sorb — Prozessregel, nicht + Mechanik. +- **Komponenten-Tracker bleiben unangetastet** (gitops 60 Issues usw.), + bis die jeweilige Komponente selbst adoptiert; das wird als + Folge-Issues angelegt. Bis dahin gilt für Komponenten-Issues GitLab + als Wahrheit — ausgewiesen, nicht verschwiegen. + +## Konsequenzen + +- Statusänderung = Commit; `git log` ersetzt die Issue-Chronik. STATUS.md + und Roadmap-Zahlen werden generiert statt behauptet (F-001-Klasse + geschlossen). +- Host-Sessions lesen den vollständigen Management-Backlog erstmals von + überall (Gitea-Mirror des Repos). +- GitLab-seitige Änderungen ohne Nachzug sind ab jetzt ein Befund, kein + stiller Zustand — die Drift-Prüfung übernimmt die Alarmfunktion der + roten Pipeline. +- Das geschlossene GitLab-Altbestand-Archiv (40 geschlossene Issues) + wird nicht importiert; es bleibt als Historie auf git.lab, erreichbar + über die bestehenden Verweise. diff --git a/docs/adr/0012-gruppenregeln-kanonisch-mit-pruefung.md b/docs/adr/0012-gruppenregeln-kanonisch-mit-pruefung.md new file mode 100644 index 0000000..9cb79bb --- /dev/null +++ b/docs/adr/0012-gruppenregeln-kanonisch-mit-pruefung.md @@ -0,0 +1,85 @@ +--- +type: adr +id: "0012" +status: proposed +date: 2026-08-11 +supersedes: null +superseded_by: null +related: + - "docs/design/2026-08-11-neckbeard-migration.md" + - "decisions/0001-gitlab-kanonisch-push-mirror.md" +--- + +# ADR-0012: Gruppenregeln kanonisch im management-Repo, Komponenten zeigen und werden geprüft + +## Kontext + +Fünf Komponenten-Repos und dieses Repo teilen ein Regelwerk. Neckbeards +ADR-0001 löst „ein Repo, viele Harnesse", nicht „viele Repos, ein +Regelwerk" — die schärfste Lücke des Feldtests. Der alte Ansatz war +bereits Pointer-basiert („Projekt-Repos haben eigene CLAUDE.mds", die +Arbeitsgrundlage liegt im management-Repo, über den Gitea-Mirror von +überall lesbar) und scheiterte nicht am Mechanismus, sondern an der +Anwendung: 4 von 5 Komponenten haben schlicht keine Pointer-Datei +(F-011), und nichts prüfte das. Zusätzlich tragen fünf Komponenten vier +Namensschemata, ohne dass ein Artefakt den kanonischen Slug festhält +(F-008) — diese Session musste die Slugs erfragen. + +## Optionen + +**A: Regelkopien in jede Komponente stempeln** (generiert, mit +Quell-SHA; Prüfskript vergleicht). Funktioniert offline im +Komponenten-Checkout. Aber: sechs Kopien derselben Regeln sind genau die +Drift-Maschine, die ADR-0001 upstream verwirft — der Stempel macht Drift +erkennbar, nicht unmöglich, und jeder Regeländerung folgt ein +Sechs-Repo-Commit-Zug. + +**B: Git-Submodule/Subtree eines Regel-Repos.** Mechanisch streng, aber: +koppelt jeden Komponenten-Clone an Lab-Erreichbarkeit, ist in Obsidian +und Forge-Ansichten sperrig, und die Gruppe hat mit Submodules keinerlei +Praxis — Reibung ohne belegten Bedarf. + +**C: Pointer + deterministische Prüfung.** Die Gruppenregeln stehen +genau einmal, im AGENTS.md dieses Repos (das gespiegelt und damit +überall lesbar ist). Jede Komponente trägt nur Projektspezifika plus +einen Pointer auf die Gruppenregeln (git.lab-Pfad und Mirror-URL). Neu +gegenüber dem alten Ansatz ist der prüfende Teil: ein Artefakt benennt +die Gruppe, ein Skript prüft die Anwendung. + +## Entscheidung + +**Option C.** + +- **Kanonisch:** die Gruppenregeln leben als ausgewiesener Abschnitt im + `AGENTS.md` dieses Repos. `CLAUDE.md` wird Ein-Zeilen-Pointer + (neckbeard ADR-0001). +- **Komponenten-Artefakt:** `docs/components/.md` (neuer + Schema-Typ) deklariert je Repo den kanonischen Slug, Anzeigenamen, + Mirror-Pfad und die Phase (`active` / `staged` / `external`) — damit + ist F-008 maschinenlesbar beantwortet und die bewusst gestaffelte + Dormanz von `thread-net-git`/`threadnet-operating` (F-009-Addendum) + erstmals repräsentierbar statt nur mündlich. +- **Prüfung, zweigeteilt:** offline prüft `validate.py` die + Komponenten-Artefakte wie jedes andere Artefakt; in der Lab-CI prüft + die Stillstandsprüfungs-Familie (a) dass jede deklarierte Komponente + die Pointer-Datei tatsächlich trägt (schließt F-011) und (b) dass die + **zur Laufzeit gelesene** Gruppenliste und `docs/components/` + deckungsgleich sind — die Projektliste bleibt bewusst ungehärtet im + Code (Retro-Lehre: eine gepflegte Liste ist die Stelle, an der ein + neues Repo jahrelang durchrutscht); neu auftauchende Repos werden + Befund statt Lücke. +- **Rollout** der Pointer-Dateien in die fünf Komponenten ist nicht Teil + dieser Undertaking: fünf Folge-Issues, eines je Komponente. + +## Konsequenzen + +- Regeländerung = ein Commit in einem Repo; Komponenten folgen per + Verweis, nicht per Kopie. +- Eine Komponente ohne Pointer ist ab dem Rollout ein roter + CI-Befund, kein stiller Zustand über Wochen (F-011-Klasse). +- Die Slug-Unregelmäßigkeiten selbst (`thread-net-git`, + CamelCase-`ThreadNet-Web`) werden hier **nicht** bereinigt — ein + Rename fasst Forge-Zustand an und wird eigenes Issue mit eigener + Abwägung; das Artefakt dokumentiert bis dahin den Ist-Stand. +- Host-Sessions ohne Lab finden Regeln und Gruppenliste über den + Gitea-Mirror; der Pointer nennt beide Wege. diff --git a/docs/design/2026-08-11-neckbeard-migration.md b/docs/design/2026-08-11-neckbeard-migration.md index 432e526..f9259ef 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-1 +status: gate-2 date: 2026-08-11 size: L related: @@ -8,6 +8,8 @@ related: - "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 @@ -127,3 +129,166 @@ Quelle starten, die sich nicht selbst widerspricht. 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/refinement.md), +[verfahren/stillstandspruefung.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](../adr/0012-gruppenregeln-kanonisch-mit-pruefung.md)); 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](../adr/0012-gruppenregeln-kanonisch-mit-pruefung.md) (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](../adr/0011-issues-im-repo-gitlab-als-spiegel.md)) | +| 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/.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. + +```mermaid +flowchart LR + S[Session-Start] --> A[CLAUDE.md → AGENTS.md
+ PROJECT.md + STATUS.md] + A --> W[Arbeit nach Gates
Artefakte in docs/] + W --> C[Commit 12:00Z] + C --> V{CI: validate.py +
gen_status --check} + V -- rot --> W + V -- grün --> M[Spiegel-Skript
dry-run → sorb triggert] + M --> B[GitLab-Board/Meilensteine
= Ansicht, nicht Wahrheit] + B --> R[Refinement sonntags
Board + STATUS.md] + R --> W + P[Stillstandsprüfung + Gruppen-Checks
geplant, Lab-CI] -. Befund = Issue .-> R +``` + +### Entscheidungen + +Die zwei tragenden Richtungsentscheidungen stehen als ADRs (Status +`proposed`, werden mit diesem Gate wirksam): + +- **[ADR-0011](../adr/0011-issues-im-repo-gitlab-als-spiegel.md)** — + Issues im Repo kanonisch (Management-Scope), GitLab als + deterministisch bespielter Spiegel; Optionen A/B/C abgewogen im ADR. +- **[ADR-0012](../adr/0012-gruppenregeln-kanonisch-mit-pruefung.md)** — + 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`.