Design abgeschlossen am 2026-10-04 und in drei Bau-Issues zerlegt:#177 (A - Erfassung aus Git, Manifest, raw status, Bundle-Ersatz), #178 (B - unbeaufsichtigter Intake-Lauf als PR, main mechanisch einmergen; blockiert durch #177), #179 (C - Leitlinien-Export). Die Bau-Spezifikation steht dort; hier stehen Anforderung, Befund und die Entscheidungen mit ihren verworfenen Alternativen.
Anforderung
Ein Betreiber mit mehreren eigenen Software- und Infrastruktur-Repositories will:
Lokal arbeitsfähig: Jedes Repository trägt genug Dokumentation, um darin zu arbeiten (README, AGENTS.md, Kontext-Doku).
Aufwärts: Ändert sie sich, wird die Instanz aktualisiert - "idealerweise automatisch". Die Instanz kennt als übergreifende Wissensbasis Architektur und Einstiegspunkte jedes Repositories.
Abwärts: Wissen wird in der Instanz aggregiert, damit unterschiedliche Repositories dieselben Leitlinien verwenden.
Für Infrastruktur ist die Instanz die gemeinsame Basis; Software dokumentiert ihren aktuellen Stand im eigenen Projekt. (Wortlaut des ursprünglichen Stubs: erster Kommentar.)
Befund (gegen den Baum und reale Repositories geprüft, 2026-10-04)
Kein Ersatz eines Ordner-Bundles als Ganzes (raw_cmd.py: "A folder has no --replaces")
raw accept --page
Erweitert raw_files: einer Quelle
Refusal bei verschachteltem Bundle (raw_cmd.py ~Z. 251-257)
raw fetch <url>
Öffentliche URL nach incoming/
Keine Auth (privat erst mit #169), kein Ordner, keine Revision
MCP submit → upload accept
Fremde Einzeldatei hinter Upload Review Gate
Kein Ordner, kein Editionsbegriff; strukturell unpassend: upload accept läuft im Checkout des Servers (INSTALL-MCP.md Schritt 7), der per Timer reset --hard gehalten wird (Schritt 6) - nicht der Checkout einer Ingest-Sitzung
Nichts verband "Repository X hat sich geändert" mit "Quelle Y ist veraltet".
Handübernahme in der privaten Instanz (Struktur, keine Inhalte): die docs/ eines GitOps-Infrastruktur-Repos als sieben getrennte, umbenannte Bundles, pro Datei eine Quellseite, nirgends Repo oder Commit; die Stack-Doku dieses Repos ebenso, dazu Issue-Texte aus dem Tracker.
Die beiden betrachteten Kandidaten (Infrastruktur, Software-Projekt) haben keinen CI-Workflow.
Konfigurations-Repositories (etckeeper-Art) und Archiv-YAMLs unter docs/ enthalten Dateien, die nie in eine Instanz gehören → Pfad-Positivliste mit Globs.
publish --branch existiert; für die MCP-Aktualität hat der Stack schon Polling statt Webhook gewählt (INSTALL-MCP.md Schritt 6).
reconcile() (git_publish.py) zählt generierte Dateien in den Überlappungstest; zwei beliebige Ingests landen deshalb immer im Rebase-Review-Gate - Teil von #178.
raw/CONTRACT.md schließt "Anything the LLM wrote" als Quelle aus → Exporte der Instanz dürfen nie zurückfließen.
Entscheidungen (Betreiber, 2026-10-04)
D1 Abgrenzung. Das Repo besitzt, wie man in ihm arbeitet und seinen aktuellen Stand; die Instanz besitzt repo-übergreifendes Wissen und erfasst Repo-Doku als Quelle (verbatim, normativ), statt sie nachzuschreiben. Die Instanz kennt Architektur und Einstiegspunkte jedes Repos; die Gegenrichtung (Leitlinien abwärts) gehört dazu. Grundsatz: Was die Instanz über ein Repo weiß, steht vorher als Doku im Repo - sie liest keinen Code. Verworfen: Instanz als alleiniger Besitzer, Repos verlinken nur (verletzt Anforderung 1).
D2/D3 Auslöser und Transport. Inhalt kommt immer per Git-Pull zu einem Commit (inhaltsadressiert, forge-neutral, keine Zugangsdaten in wikitool); ein Manifest im Bundle ist die einzige Deklaration. Auslöser trägt keinen Inhalt: Timer als Grundlinie, Push-Signal (CI, Webhook, Markierungsdatei) optional. Verworfen: CI pusht Inhalt (Workflow und Schreibrecht in jedem Repo, nicht inhaltsadressiert, Repos ohne CI außen vor); MCP submit (Einzeldatei, falscher Checkout, s. Befund); raw fetch auf Raw-URLs (öffentlich, ohne Revision, ohne Ordner); PR am Eingang (zeigte nur den Rohdiff, zwei Freigaben).
D4 Granularität. Ganze Dokumente; ein Bundle pro Repository, Ersatz als Ganzes inklusive im Repo gelöschter Dateien; der Diff wird zur Lesezeit aus Git abgeleitet. Verworfen: eine Quelle pro Datei (neue und gelöschte Dateien würden zu neuen bzw. verwaisten Quellen); Diffs als Quelle (verletzt "replaceable as a whole").
D5 Freigabe. Erkennung, Erfassung, raw accept und Ingest laufen unbeaufsichtigt auf einem intake/-Branch; der Merge der Intake-PR durch den Menschen ist die Freigabe. Gates beenden den Lauf, werden nie geöffnet. Verworfen: Freigabe jedes Schritts in einer Sitzung (widerspricht "automatisch").
D6 Leitlinien abwärts. Mechanisch generierte Datei mit Export-Kopf, per PR ins Repo, Opt-in durch Vorhandensein; Auswahl über search-Filter ohne neues Schema. Verworfen: Abruf zur Laufzeit über MCP (ohne Server keine Leitlinien, Anforderung 1).
D7 Schnitt. Drei Bau-Issues #177/#178/#179; dieses Issue schließt.
D8 Mergen statt neu erzeugen (Vorschlag des Betreibers). Bewegt sich main, wird es in den Intake-Branch eingemergt, nicht der Lauf wiederholt: Indizes und kb/provenance.md werden neu erzeugt, kb/log.md als Vereinigung, Referenz-Arrays im Frontmatter als Menge; Seitentext über Gits Drei-Wege-Merge - ein LLM nur für echte Textkonflikte. Merge statt Rebase, weil Force-Push verboten bleibt. Eine offene Intake-PR wächst, statt dass eine zweite entsteht. Verworfen: Branch verwerfen und Lauf wiederholen (wiederholt LLM-Arbeit, die Git mechanisch erhalten kann).
Ablauf an zwei Beispielen
GitOps-Infrastruktur-Repo (privat, Gitea), Ref main.raw capture ssh://…/<infra>.git --ref main --path README.md --path 'docs/**/*.md' --path 'apps/*/README.md' --path 'apps/*/*/README.md' --path 'infrastructure/*/README.md' --name <infra> → ein Bundle mit Repo-Struktur statt sieben umbenannter; die Globs lassen Archiv-YAMLs draußen. Ändert der Betreiber einen Runbook, legt eine Betriebsdoku an und löscht eine Audit-Datei, meldet raw statusM/A/D mit zitierenden Seiten, und der Lauf legt eine PR an, in der der Runbook-Diff neben den aktualisierten Seiten steht.
chemenu (öffentlich, Gitea), Ref v*.raw capture https://gitea.nehmer.net/torben/chemenu.git --ref 'v*' --path README.md --path AGENTS.md --path '*/CONTRACT.md' --path 'docs/*.md' --path 'instructions/**/*.md' --name chemenu → eine Intake-PR pro Release statt pro Commit. Installierter Stack ist Laufzeit, erfasster ist Quelle. Issue-Texte liegen nicht in Git und bleiben außerhalb.
Repos außerhalb von Gitea
Aufwärts geht eine GitHub-URL direkt (reines Git, Zugangsdaten des Hosts); ein Gitea-Pull-Mirror ist eine valide Minimallösung (Instanz verfolgt die Mirror-URL, GitHub-Zugangsdaten nur in Gitea; Kosten: Mirror-Intervall als Latenz).
Ein Push-Signal aus GitHub Actions erreicht ein privates Netz nicht ohne Weiteres; der Timer deckt das ab.
Die Intake-PR geht immer gegen das Instanz-Repo, unabhängig vom Quell-Forge.
Abwärts braucht ein GitHub-Repo ein GitHub-Werkzeug in der Sitzung (gh, GitHub-MCP); ein Pull-Mirror ist schreibgeschützt.
Nicht Stack, sondern Instanzarbeit
Repo-Landkarte, eine Seite pro Repo mit Architektur und Einstiegspunkten, das Herausarbeiten der Leitlinien aus den verstreuten Repo-Regeln und vorhandenen Interviews, die einmalige Ablösung der Hand-Bundles durch erfasste Bundles, und die Instanzkonvention, welche Seiten Leitlinien sind (kb/CONVENTIONS.md).
Akzeptanzkriterien
Entscheidung zu Auslöser und Transport, mit verworfenen Alternativen (D2/D3).
Abgrenzung Repo-Doku gegen Instanz-Doku festgehalten (D1).
Kein Weg erreicht main ohne menschliche Freigabe - als Kriterium in #178, Freigabe am PR-Merge (D5).
In Bau-Issues mit prüfbaren Kriterien zerlegt (D7).
Ablauf an mindestens einem Repository mit CI/CD erprobt - verschoben in #177 (raw status an einem echten Repo) und #178 (Lauf bis zum Merge); "mit CI/CD" entfällt, weil der Auslöser nach D2/D3 kein CI braucht.
Versionsteil
Kein eigener: dieses Issue ändert keine Datei. #177, #178 und #179 sind je --minor.
Herkunft
Anforderung des Betreibers aus einem Interview in einer privaten Instanz; Instanzinhalte und private Repo-/Hostnamen bewusst weggelassen.
**Design abgeschlossen am 2026-10-04 und in drei Bau-Issues zerlegt:** #177 (A - Erfassung aus Git, Manifest, `raw status`, Bundle-Ersatz), #178 (B - unbeaufsichtigter Intake-Lauf als PR, `main` mechanisch einmergen; blockiert durch #177), #179 (C - Leitlinien-Export). Die Bau-Spezifikation steht dort; hier stehen Anforderung, Befund und die Entscheidungen mit ihren verworfenen Alternativen.
## Anforderung
Ein Betreiber mit mehreren eigenen Software- und Infrastruktur-Repositories will:
1. **Lokal arbeitsfähig:** Jedes Repository trägt genug Dokumentation, um darin zu arbeiten (README, AGENTS.md, Kontext-Doku).
2. **Aufwärts:** Ändert sie sich, wird die Instanz aktualisiert - "idealerweise automatisch". Die Instanz kennt als übergreifende Wissensbasis Architektur und Einstiegspunkte jedes Repositories.
3. **Abwärts:** Wissen wird in der Instanz aggregiert, damit unterschiedliche Repositories dieselben Leitlinien verwenden.
Für Infrastruktur ist die Instanz die gemeinsame Basis; Software dokumentiert ihren aktuellen Stand im eigenen Projekt. (Wortlaut des ursprünglichen Stubs: erster Kommentar.)
## Befund (gegen den Baum und reale Repositories geprüft, 2026-10-04)
**Intake-Wege vor diesem Design** (`raw/CONTRACT.md`):
| Weg | Was er kann | Was ihm hier fehlt |
|---|---|---|
| `incoming/` + `raw accept` | Datei, Stem-Bundle, ganzer Ordner (Struktur bleibt) | Weiß nichts über Herkunft-Repo oder Revision |
| `raw accept --replaces` | Neue Edition **einer** Datei, eine für eine | Kein Ersatz eines Ordner-Bundles als Ganzes (`raw_cmd.py`: "A folder has no --replaces") |
| `raw accept --page` | Erweitert `raw_files:` einer Quelle | Refusal bei verschachteltem Bundle (`raw_cmd.py` ~Z. 251-257) |
| `raw fetch <url>` | Öffentliche URL nach `incoming/` | Keine Auth (privat erst mit #169), kein Ordner, keine Revision |
| MCP `submit` → `upload accept` | Fremde Einzeldatei hinter Upload Review Gate | Kein Ordner, kein Editionsbegriff; strukturell unpassend: `upload accept` läuft im Checkout des Servers (`INSTALL-MCP.md` Schritt 7), der per Timer `reset --hard` gehalten wird (Schritt 6) - nicht der Checkout einer Ingest-Sitzung |
- Nichts verband "Repository X hat sich geändert" mit "Quelle Y ist veraltet".
- **Handübernahme in der privaten Instanz** (Struktur, keine Inhalte): die `docs/` eines GitOps-Infrastruktur-Repos als sieben getrennte, umbenannte Bundles, pro Datei eine Quellseite, nirgends Repo oder Commit; die Stack-Doku dieses Repos ebenso, dazu Issue-Texte aus dem Tracker.
- Die beiden betrachteten Kandidaten (Infrastruktur, Software-Projekt) haben keinen CI-Workflow.
- Konfigurations-Repositories (etckeeper-Art) und Archiv-YAMLs unter `docs/` enthalten Dateien, die nie in eine Instanz gehören → Pfad-Positivliste mit Globs.
- `publish --branch` existiert; für die MCP-Aktualität hat der Stack schon Polling statt Webhook gewählt (`INSTALL-MCP.md` Schritt 6).
- `reconcile()` (`git_publish.py`) zählt generierte Dateien in den Überlappungstest; zwei beliebige Ingests landen deshalb immer im Rebase-Review-Gate - Teil von #178.
- `raw/CONTRACT.md` schließt "Anything the LLM wrote" als Quelle aus → Exporte der Instanz dürfen nie zurückfließen.
## Entscheidungen (Betreiber, 2026-10-04)
- **D1 Abgrenzung.** Das Repo besitzt, wie man in ihm arbeitet und seinen aktuellen Stand; die Instanz besitzt repo-übergreifendes Wissen und erfasst Repo-Doku als **Quelle** (verbatim, normativ), statt sie nachzuschreiben. Die Instanz kennt Architektur und Einstiegspunkte jedes Repos; die Gegenrichtung (Leitlinien abwärts) gehört dazu. Grundsatz: Was die Instanz über ein Repo weiß, steht vorher als Doku im Repo - sie liest keinen Code. *Verworfen:* Instanz als alleiniger Besitzer, Repos verlinken nur (verletzt Anforderung 1).
- **D2/D3 Auslöser und Transport.** Inhalt kommt immer per **Git-Pull zu einem Commit** (inhaltsadressiert, forge-neutral, keine Zugangsdaten in `wikitool`); ein Manifest im Bundle ist die einzige Deklaration. Auslöser trägt keinen Inhalt: Timer als Grundlinie, Push-Signal (CI, Webhook, Markierungsdatei) optional. *Verworfen:* CI pusht Inhalt (Workflow und Schreibrecht in jedem Repo, nicht inhaltsadressiert, Repos ohne CI außen vor); MCP `submit` (Einzeldatei, falscher Checkout, s. Befund); `raw fetch` auf Raw-URLs (öffentlich, ohne Revision, ohne Ordner); PR am Eingang (zeigte nur den Rohdiff, zwei Freigaben).
- **D4 Granularität.** Ganze Dokumente; ein Bundle pro Repository, Ersatz als Ganzes inklusive im Repo gelöschter Dateien; der Diff wird zur Lesezeit aus Git abgeleitet. *Verworfen:* eine Quelle pro Datei (neue und gelöschte Dateien würden zu neuen bzw. verwaisten Quellen); Diffs als Quelle (verletzt "replaceable as a whole").
- **D5 Freigabe.** Erkennung, Erfassung, `raw accept` und Ingest laufen unbeaufsichtigt auf einem `intake/`-Branch; **der Merge der Intake-PR durch den Menschen ist die Freigabe**. Gates beenden den Lauf, werden nie geöffnet. *Verworfen:* Freigabe jedes Schritts in einer Sitzung (widerspricht "automatisch").
- **D6 Leitlinien abwärts.** Mechanisch generierte Datei mit Export-Kopf, per PR ins Repo, Opt-in durch Vorhandensein; Auswahl über `search`-Filter ohne neues Schema. *Verworfen:* Abruf zur Laufzeit über MCP (ohne Server keine Leitlinien, Anforderung 1).
- **D7 Schnitt.** Drei Bau-Issues #177/#178/#179; dieses Issue schließt.
- **D8 Mergen statt neu erzeugen** (Vorschlag des Betreibers). Bewegt sich `main`, wird es in den Intake-Branch **eingemergt**, nicht der Lauf wiederholt: Indizes und `kb/provenance.md` werden neu erzeugt, `kb/log.md` als Vereinigung, Referenz-Arrays im Frontmatter als Menge; Seitentext über Gits Drei-Wege-Merge - ein LLM nur für echte Textkonflikte. Merge statt Rebase, weil Force-Push verboten bleibt. Eine offene Intake-PR wächst, statt dass eine zweite entsteht. *Verworfen:* Branch verwerfen und Lauf wiederholen (wiederholt LLM-Arbeit, die Git mechanisch erhalten kann).
## Ablauf an zwei Beispielen
**GitOps-Infrastruktur-Repo (privat, Gitea), Ref `main`.** `raw capture ssh://…/<infra>.git --ref main --path README.md --path 'docs/**/*.md' --path 'apps/*/README.md' --path 'apps/*/*/README.md' --path 'infrastructure/*/README.md' --name <infra>` → ein Bundle mit Repo-Struktur statt sieben umbenannter; die Globs lassen Archiv-YAMLs draußen. Ändert der Betreiber einen Runbook, legt eine Betriebsdoku an und löscht eine Audit-Datei, meldet `raw status` `M`/`A`/`D` mit zitierenden Seiten, und der Lauf legt eine PR an, in der der Runbook-Diff neben den aktualisierten Seiten steht.
**chemenu (öffentlich, Gitea), Ref `v*`.** `raw capture https://gitea.nehmer.net/torben/chemenu.git --ref 'v*' --path README.md --path AGENTS.md --path '*/CONTRACT.md' --path 'docs/*.md' --path 'instructions/**/*.md' --name chemenu` → eine Intake-PR pro Release statt pro Commit. Installierter Stack ist Laufzeit, erfasster ist Quelle. Issue-Texte liegen nicht in Git und bleiben außerhalb.
## Repos außerhalb von Gitea
- Aufwärts geht eine GitHub-URL direkt (reines Git, Zugangsdaten des Hosts); ein Gitea-Pull-Mirror ist eine valide Minimallösung (Instanz verfolgt die Mirror-URL, GitHub-Zugangsdaten nur in Gitea; Kosten: Mirror-Intervall als Latenz).
- Ein Push-Signal aus GitHub Actions erreicht ein privates Netz nicht ohne Weiteres; der Timer deckt das ab.
- Die Intake-PR geht immer gegen das Instanz-Repo, unabhängig vom Quell-Forge.
- Abwärts braucht ein GitHub-Repo ein GitHub-Werkzeug in der Sitzung (`gh`, GitHub-MCP); ein Pull-Mirror ist schreibgeschützt.
## Nicht Stack, sondern Instanzarbeit
Repo-Landkarte, eine Seite pro Repo mit Architektur und Einstiegspunkten, das Herausarbeiten der Leitlinien aus den verstreuten Repo-Regeln und vorhandenen Interviews, die einmalige Ablösung der Hand-Bundles durch erfasste Bundles, und die Instanzkonvention, welche Seiten Leitlinien sind (`kb/CONVENTIONS.md`).
## Akzeptanzkriterien
- [x] Entscheidung zu Auslöser und Transport, mit verworfenen Alternativen (D2/D3).
- [x] Abgrenzung Repo-Doku gegen Instanz-Doku festgehalten (D1).
- [x] Kein Weg erreicht `main` ohne menschliche Freigabe - als Kriterium in #178, Freigabe am PR-Merge (D5).
- [x] In Bau-Issues mit prüfbaren Kriterien zerlegt (D7).
- [ ] ~~Ablauf an mindestens einem Repository mit CI/CD erprobt~~ - verschoben in #177 (`raw status` an einem echten Repo) und #178 (Lauf bis zum Merge); "mit CI/CD" entfällt, weil der Auslöser nach D2/D3 kein CI braucht.
## Versionsteil
Kein eigener: dieses Issue ändert keine Datei. #177, #178 und #179 sind je `--minor`.
## Herkunft
Anforderung des Betreibers aus einem Interview in einer privaten Instanz; Instanzinhalte und private Repo-/Hostnamen bewusst weggelassen.
Changelog: Stub ausgearbeitet (issue-tracking.md § Incoming stubs). Body gegen den Baum geprüft und umgeschrieben: Befund um die gemessenen Grenzen der Intake-Wege ergänzt (Ordner-Bundle ohne --replaces, --page scheitert an verschachtelten Bundles, submit nur Einzeldatei ohne Editionsbegriff, kein Feld für Repo/Revision); offene Fragen als D1-D5 mit Empfehlung, aber unentschieden; Akzeptanzkriterien als prüfbare Eigenschaften; Versionsteil vorläufig. Labels: area/workflow → area/kb (Intake nach raw/, nicht Git/Publish), kind/decision, prio/planned, size/L; status/incoming entfernt.
Der Stub im Wortlaut:
Befund
Ein Betreiber mit mehreren eigenen Software- und Infrastruktur-Repositories will zweierlei: Jedes Repository traegt lokal genug Dokumentation, um darin zu arbeiten (README, AGENTS.md, Kontext-Doku), und bei Aenderungen wird die zugehoerige Chemenu-Instanz aktualisiert, "idealerweise zukuenftig automatisch". Fuer Infrastruktur soll die Instanz die gemeinsame Basis sein; Software dokumentiert ihren aktuellen Stand im eigenen Projekt.
Gemessen: raw accept nimmt nur Dateien aus incoming/ an (raw/CONTRACT.md), und raw accept --replaces ersetzt eine bestehende Quelle als neue Edition. Ein Fremdzugang existiert ueber das MCP-submit-Tool mit Upload Review Gate. Angenommen, nicht geprueft: Es gibt keinen Mechanismus, der "Repository X hat sich geaendert" mit "Quelle Y in der Instanz ist veraltet" verbindet.
Offene Fragen (stack-dev)
Ausloeser: CI-Job im Projekt-Repository, periodischer Abgleich aus der Instanz, oder manuell?
Transport: MCP submit + upload accept, raw accept --replaces gegen ein ausgechecktes Repository, oder ein neuer Weg (vgl. #169)?
Granularitaet: ganze Doku-Dateien als neue Edition oder nur Aenderungen?
Wie weit darf das ohne Agentensitzung laufen? Kompilieren nach kb/ braucht heute einen Agenten, die Gates einen Menschen.
Abgrenzung: Welche Doku gehoert ins Repository, welche in die Instanz, damit keine zwei Kopien driften (Invariante 8)?
Loesungsvorschlag
Noch keiner; das Issue haelt die Anforderung fuer die Design-Phase fest.
Akzeptanzkriterien
Entscheidung zu Ausloeser und Transport, mit verworfenen Alternativen
Abgrenzung Repo-Doku gegen Instanz-Doku festgehalten
Ablauf an mindestens einem Repository mit CI/CD erprobt
Kein Weg publiziert ohne menschliche Freigabe nach kb/
Herkunft
Anforderung des Betreibers aus einem Interview in einer privaten Instanz; Instanzinhalte bewusst weggelassen.
**Changelog:** Stub ausgearbeitet (issue-tracking.md § Incoming stubs). Body gegen den Baum geprüft und umgeschrieben: Befund um die gemessenen Grenzen der Intake-Wege ergänzt (Ordner-Bundle ohne `--replaces`, `--page` scheitert an verschachtelten Bundles, `submit` nur Einzeldatei ohne Editionsbegriff, kein Feld für Repo/Revision); offene Fragen als D1-D5 mit Empfehlung, aber unentschieden; Akzeptanzkriterien als prüfbare Eigenschaften; Versionsteil vorläufig. Labels: `area/workflow` → `area/kb` (Intake nach `raw/`, nicht Git/Publish), `kind/decision`, `prio/planned`, `size/L`; `status/incoming` entfernt.
Der Stub im Wortlaut:
> ## Befund
>
> Ein Betreiber mit mehreren eigenen Software- und Infrastruktur-Repositories will zweierlei: Jedes Repository traegt lokal genug Dokumentation, um darin zu arbeiten (README, AGENTS.md, Kontext-Doku), und bei Aenderungen wird die zugehoerige Chemenu-Instanz aktualisiert, "idealerweise zukuenftig automatisch". Fuer Infrastruktur soll die Instanz die gemeinsame Basis sein; Software dokumentiert ihren aktuellen Stand im eigenen Projekt.
>
> Gemessen: `raw accept` nimmt nur Dateien aus `incoming/` an (`raw/CONTRACT.md`), und `raw accept --replaces` ersetzt eine bestehende Quelle als neue Edition. Ein Fremdzugang existiert ueber das MCP-`submit`-Tool mit Upload Review Gate. Angenommen, nicht geprueft: Es gibt keinen Mechanismus, der "Repository X hat sich geaendert" mit "Quelle Y in der Instanz ist veraltet" verbindet.
>
> ## Offene Fragen (stack-dev)
>
> - Ausloeser: CI-Job im Projekt-Repository, periodischer Abgleich aus der Instanz, oder manuell?
> - Transport: MCP `submit` + `upload accept`, `raw accept --replaces` gegen ein ausgechecktes Repository, oder ein neuer Weg (vgl. #169)?
> - Granularitaet: ganze Doku-Dateien als neue Edition oder nur Aenderungen?
> - Wie weit darf das ohne Agentensitzung laufen? Kompilieren nach `kb/` braucht heute einen Agenten, die Gates einen Menschen.
> - Abgrenzung: Welche Doku gehoert ins Repository, welche in die Instanz, damit keine zwei Kopien driften (Invariante 8)?
>
> ## Loesungsvorschlag
>
> Noch keiner; das Issue haelt die Anforderung fuer die Design-Phase fest.
>
> ## Akzeptanzkriterien
>
> - [ ] Entscheidung zu Ausloeser und Transport, mit verworfenen Alternativen
> - [ ] Abgrenzung Repo-Doku gegen Instanz-Doku festgehalten
> - [ ] Ablauf an mindestens einem Repository mit CI/CD erprobt
> - [ ] Kein Weg publiziert ohne menschliche Freigabe nach `kb/`
>
> ## Herkunft
>
> Anforderung des Betreibers aus einem Interview in einer privaten Instanz; Instanzinhalte bewusst weggelassen.
torben
changed title from Dokumentation aus Projekt-Repositories in eine Instanz zurueckfuehren (Design gesucht) to Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design gesucht)2026-10-04 20:02:23 +00:00
Changelog: Betreiberantworten eingearbeitet: D1 entschieden inkl. Gegenrichtung (Leitlinien abwärts, Architektur/Einstiegspunkte in der Instanz), D4 entschieden (ein Bundle pro Repo, Ersatz als Ganzes), D5 entschieden. Befund erweitert um reale Repositories (Handübernahme in der privaten Instanz, fehlende CI, Positivliste nötig), MCP-submit als strukturell unpassend erkannt, publish --branch und die Polling-Präzedenz. Neuer Entwurf A/B/C: Erfassung per Git mit Manifest als Deklaration, PR am Ausgang als Freigabe, Leitlinien-Export mit Rückfluss-Ausschluss. Offen jetzt: D2/D3' (Pull vs. CI-Push), D5' (Freigabe am Merge), D6 (Leitlinien per Datei vs. MCP), D7 (Schnitt in drei Bau-Issues). #169 keine Abhängigkeit mehr.
**Changelog:** Betreiberantworten eingearbeitet: D1 entschieden inkl. Gegenrichtung (Leitlinien abwärts, Architektur/Einstiegspunkte in der Instanz), D4 entschieden (ein Bundle pro Repo, Ersatz als Ganzes), D5 entschieden. Befund erweitert um reale Repositories (Handübernahme in der privaten Instanz, fehlende CI, Positivliste nötig), MCP-`submit` als strukturell unpassend erkannt, `publish --branch` und die Polling-Präzedenz. Neuer Entwurf A/B/C: Erfassung per Git mit Manifest als Deklaration, PR am Ausgang als Freigabe, Leitlinien-Export mit Rückfluss-Ausschluss. Offen jetzt: D2/D3' (Pull vs. CI-Push), D5' (Freigabe am Merge), D6 (Leitlinien per Datei vs. MCP), D7 (Schnitt in drei Bau-Issues). #169 keine Abhängigkeit mehr.
Changelog: Intake-PR (B) als Ablauf in fünf Schritten präzisiert: ein Lauf = eine PR mit einem Commit pro Repo, eine offene Intake-PR zur Zeit, Verwerfen statt Mergen bei bewegtem main, geschlossene PR = Fassung abgelehnt. A ergänzt um Ref-Regel pro Repo (Branch oder jüngstes Tag), Globs in der Positivliste, Arbeitsnamen (raw capture, raw status, --replaces-bundle), Umgang mit entfernten Dateien. Neue Abschnitte: Ablauf an zwei Beispielen (Infrastruktur-Repo, chemenu) und Repos außerhalb von Gitea (GitHub direkt oder per Pull-Mirror).
**Changelog:** Intake-PR (B) als Ablauf in fünf Schritten präzisiert: ein Lauf = eine PR mit einem Commit pro Repo, eine offene Intake-PR zur Zeit, Verwerfen statt Mergen bei bewegtem `main`, geschlossene PR = Fassung abgelehnt. A ergänzt um Ref-Regel pro Repo (Branch oder jüngstes Tag), Globs in der Positivliste, Arbeitsnamen (`raw capture`, `raw status`, `--replaces-bundle`), Umgang mit entfernten Dateien. Neue Abschnitte: Ablauf an zwei Beispielen (Infrastruktur-Repo, chemenu) und Repos außerhalb von Gitea (GitHub direkt oder per Pull-Mirror).
torben
changed title from Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design gesucht) to Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design, zerlegt in #177/#178/#179)2026-10-04 20:41:28 +00:00
Changelog: D2/D3, D5', D6, D7 vom Betreiber bestätigt; D8 neu (Vorschlag des Betreibers): main mechanisch in den Intake-Branch mergen statt Lauf wiederholen. Zerlegt in #177 (A), #178 (B, blockiert durch #177), #179 (C). Body auf Endstand gebracht: Entscheidungen mit verworfenen Alternativen, Bau-Details nur noch in den Folge-Issues, Erprobungs-Kriterium nach #177/#178 verschoben. Geschlossen.
**Changelog:** D2/D3, D5', D6, D7 vom Betreiber bestätigt; D8 neu (Vorschlag des Betreibers): `main` mechanisch in den Intake-Branch mergen statt Lauf wiederholen. Zerlegt in #177 (A), #178 (B, blockiert durch #177), #179 (C). Body auf Endstand gebracht: Entscheidungen mit verworfenen Alternativen, Bau-Details nur noch in den Folge-Issues, Erprobungs-Kriterium nach #177/#178 verschoben. Geschlossen.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Design abgeschlossen am 2026-10-04 und in drei Bau-Issues zerlegt: #177 (A - Erfassung aus Git, Manifest,
raw status, Bundle-Ersatz), #178 (B - unbeaufsichtigter Intake-Lauf als PR,mainmechanisch einmergen; blockiert durch #177), #179 (C - Leitlinien-Export). Die Bau-Spezifikation steht dort; hier stehen Anforderung, Befund und die Entscheidungen mit ihren verworfenen Alternativen.Anforderung
Ein Betreiber mit mehreren eigenen Software- und Infrastruktur-Repositories will:
Für Infrastruktur ist die Instanz die gemeinsame Basis; Software dokumentiert ihren aktuellen Stand im eigenen Projekt. (Wortlaut des ursprünglichen Stubs: erster Kommentar.)
Befund (gegen den Baum und reale Repositories geprüft, 2026-10-04)
Intake-Wege vor diesem Design (
raw/CONTRACT.md):incoming/+raw acceptraw accept --replacesraw_cmd.py: "A folder has no --replaces")raw accept --pageraw_files:einer Quelleraw_cmd.py~Z. 251-257)raw fetch <url>incoming/submit→upload acceptupload acceptläuft im Checkout des Servers (INSTALL-MCP.mdSchritt 7), der per Timerreset --hardgehalten wird (Schritt 6) - nicht der Checkout einer Ingest-Sitzungdocs/eines GitOps-Infrastruktur-Repos als sieben getrennte, umbenannte Bundles, pro Datei eine Quellseite, nirgends Repo oder Commit; die Stack-Doku dieses Repos ebenso, dazu Issue-Texte aus dem Tracker.docs/enthalten Dateien, die nie in eine Instanz gehören → Pfad-Positivliste mit Globs.publish --branchexistiert; für die MCP-Aktualität hat der Stack schon Polling statt Webhook gewählt (INSTALL-MCP.mdSchritt 6).reconcile()(git_publish.py) zählt generierte Dateien in den Überlappungstest; zwei beliebige Ingests landen deshalb immer im Rebase-Review-Gate - Teil von #178.raw/CONTRACT.mdschließt "Anything the LLM wrote" als Quelle aus → Exporte der Instanz dürfen nie zurückfließen.Entscheidungen (Betreiber, 2026-10-04)
wikitool); ein Manifest im Bundle ist die einzige Deklaration. Auslöser trägt keinen Inhalt: Timer als Grundlinie, Push-Signal (CI, Webhook, Markierungsdatei) optional. Verworfen: CI pusht Inhalt (Workflow und Schreibrecht in jedem Repo, nicht inhaltsadressiert, Repos ohne CI außen vor); MCPsubmit(Einzeldatei, falscher Checkout, s. Befund);raw fetchauf Raw-URLs (öffentlich, ohne Revision, ohne Ordner); PR am Eingang (zeigte nur den Rohdiff, zwei Freigaben).raw acceptund Ingest laufen unbeaufsichtigt auf einemintake/-Branch; der Merge der Intake-PR durch den Menschen ist die Freigabe. Gates beenden den Lauf, werden nie geöffnet. Verworfen: Freigabe jedes Schritts in einer Sitzung (widerspricht "automatisch").search-Filter ohne neues Schema. Verworfen: Abruf zur Laufzeit über MCP (ohne Server keine Leitlinien, Anforderung 1).main, wird es in den Intake-Branch eingemergt, nicht der Lauf wiederholt: Indizes undkb/provenance.mdwerden neu erzeugt,kb/log.mdals Vereinigung, Referenz-Arrays im Frontmatter als Menge; Seitentext über Gits Drei-Wege-Merge - ein LLM nur für echte Textkonflikte. Merge statt Rebase, weil Force-Push verboten bleibt. Eine offene Intake-PR wächst, statt dass eine zweite entsteht. Verworfen: Branch verwerfen und Lauf wiederholen (wiederholt LLM-Arbeit, die Git mechanisch erhalten kann).Ablauf an zwei Beispielen
GitOps-Infrastruktur-Repo (privat, Gitea), Ref
main.raw capture ssh://…/<infra>.git --ref main --path README.md --path 'docs/**/*.md' --path 'apps/*/README.md' --path 'apps/*/*/README.md' --path 'infrastructure/*/README.md' --name <infra>→ ein Bundle mit Repo-Struktur statt sieben umbenannter; die Globs lassen Archiv-YAMLs draußen. Ändert der Betreiber einen Runbook, legt eine Betriebsdoku an und löscht eine Audit-Datei, meldetraw statusM/A/Dmit zitierenden Seiten, und der Lauf legt eine PR an, in der der Runbook-Diff neben den aktualisierten Seiten steht.chemenu (öffentlich, Gitea), Ref
v*.raw capture https://gitea.nehmer.net/torben/chemenu.git --ref 'v*' --path README.md --path AGENTS.md --path '*/CONTRACT.md' --path 'docs/*.md' --path 'instructions/**/*.md' --name chemenu→ eine Intake-PR pro Release statt pro Commit. Installierter Stack ist Laufzeit, erfasster ist Quelle. Issue-Texte liegen nicht in Git und bleiben außerhalb.Repos außerhalb von Gitea
gh, GitHub-MCP); ein Pull-Mirror ist schreibgeschützt.Nicht Stack, sondern Instanzarbeit
Repo-Landkarte, eine Seite pro Repo mit Architektur und Einstiegspunkten, das Herausarbeiten der Leitlinien aus den verstreuten Repo-Regeln und vorhandenen Interviews, die einmalige Ablösung der Hand-Bundles durch erfasste Bundles, und die Instanzkonvention, welche Seiten Leitlinien sind (
kb/CONVENTIONS.md).Akzeptanzkriterien
mainohne menschliche Freigabe - als Kriterium in #178, Freigabe am PR-Merge (D5).Ablauf an mindestens einem Repository mit CI/CD erprobt- verschoben in #177 (raw statusan einem echten Repo) und #178 (Lauf bis zum Merge); "mit CI/CD" entfällt, weil der Auslöser nach D2/D3 kein CI braucht.Versionsteil
Kein eigener: dieses Issue ändert keine Datei. #177, #178 und #179 sind je
--minor.Herkunft
Anforderung des Betreibers aus einem Interview in einer privaten Instanz; Instanzinhalte und private Repo-/Hostnamen bewusst weggelassen.
Changelog: Stub ausgearbeitet (issue-tracking.md § Incoming stubs). Body gegen den Baum geprüft und umgeschrieben: Befund um die gemessenen Grenzen der Intake-Wege ergänzt (Ordner-Bundle ohne
--replaces,--pagescheitert an verschachtelten Bundles,submitnur Einzeldatei ohne Editionsbegriff, kein Feld für Repo/Revision); offene Fragen als D1-D5 mit Empfehlung, aber unentschieden; Akzeptanzkriterien als prüfbare Eigenschaften; Versionsteil vorläufig. Labels:area/workflow→area/kb(Intake nachraw/, nicht Git/Publish),kind/decision,prio/planned,size/L;status/incomingentfernt.Der Stub im Wortlaut:
Dokumentation aus Projekt-Repositories in eine Instanz zurueckfuehren (Design gesucht)to Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design gesucht)Changelog: Betreiberantworten eingearbeitet: D1 entschieden inkl. Gegenrichtung (Leitlinien abwärts, Architektur/Einstiegspunkte in der Instanz), D4 entschieden (ein Bundle pro Repo, Ersatz als Ganzes), D5 entschieden. Befund erweitert um reale Repositories (Handübernahme in der privaten Instanz, fehlende CI, Positivliste nötig), MCP-
submitals strukturell unpassend erkannt,publish --branchund die Polling-Präzedenz. Neuer Entwurf A/B/C: Erfassung per Git mit Manifest als Deklaration, PR am Ausgang als Freigabe, Leitlinien-Export mit Rückfluss-Ausschluss. Offen jetzt: D2/D3' (Pull vs. CI-Push), D5' (Freigabe am Merge), D6 (Leitlinien per Datei vs. MCP), D7 (Schnitt in drei Bau-Issues). #169 keine Abhängigkeit mehr.Changelog: Intake-PR (B) als Ablauf in fünf Schritten präzisiert: ein Lauf = eine PR mit einem Commit pro Repo, eine offene Intake-PR zur Zeit, Verwerfen statt Mergen bei bewegtem
main, geschlossene PR = Fassung abgelehnt. A ergänzt um Ref-Regel pro Repo (Branch oder jüngstes Tag), Globs in der Positivliste, Arbeitsnamen (raw capture,raw status,--replaces-bundle), Umgang mit entfernten Dateien. Neue Abschnitte: Ablauf an zwei Beispielen (Infrastruktur-Repo, chemenu) und Repos außerhalb von Gitea (GitHub direkt oder per Pull-Mirror).Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design gesucht)to Dokumentation aus Projekt-Repositories in eine Instanz zurückführen (Design, zerlegt in #177/#178/#179)Changelog: D2/D3, D5', D6, D7 vom Betreiber bestätigt; D8 neu (Vorschlag des Betreibers):
mainmechanisch in den Intake-Branch mergen statt Lauf wiederholen. Zerlegt in #177 (A), #178 (B, blockiert durch #177), #179 (C). Body auf Endstand gebracht: Entscheidungen mit verworfenen Alternativen, Bau-Details nur noch in den Folge-Issues, Erprobungs-Kriterium nach #177/#178 verschoben. Geschlossen.