From e4256d3222c93564c10430ecd82088ec8e215b55 Mon Sep 17 00:00:00 2001 From: DoctoDre Date: Tue, 30 Jun 2026 21:45:14 +0200 Subject: [PATCH] Add monorepo summary and presentation docs --- docs/monorepo-presentation.md | 109 ++++++++++++++++++++++ docs/monorepo-summary.md | 165 ++++++++++++++++++++++++++++++++++ 2 files changed, 274 insertions(+) create mode 100644 docs/monorepo-presentation.md create mode 100644 docs/monorepo-summary.md diff --git a/docs/monorepo-presentation.md b/docs/monorepo-presentation.md new file mode 100644 index 0000000..6c3235a --- /dev/null +++ b/docs/monorepo-presentation.md @@ -0,0 +1,109 @@ +# Monorepo-Konsolidierung – Präsentation + +--- + +## Problem + +- **18+ einzelne Repositories** — kein Überblick, kein Zusammenhang +- **Secrets manuell transportieren** — .gitignore-basiert, geht bei neuem Rechner verloren +- **3 Arbeitskontexte** (Bahn, dhive, Privat) — vermischen sich unkontrolliert +- **AI-Agenten** greifen unkontrolliert auf Dateien aller Kontexte zu +- **Team-Zusammenarbeit** erfordert separate Repos — aber ich will den Überblick behalten +- **Wissen verstreut** — Confluence, Jira, lokale Notizen, Chats, keine Suche darüber + +--- + +## Lösung: Ein Monorepo mit Kontextgrenzen + +``` +monorepo/ +├── bahn/ ← 10 DB-InfraGO-Projekte +├── dhive/ ← 2 dhive-Projekte +├── privat/ ← 2 persönliche Projekte +└── shared/ ← Übergreifende Tools, Orchestrator, Wissen +``` + +**Grundprinzip:** Alles an einem Ort, aber mit klaren Grenzen. + +--- + +## Kernideen + +### 1. Kontextbasierte Sicherheit +- Jeder Kontext hat eigene Secrets (verschlüsselt im Repo via git-crypt) +- AI-Agent im Kontext "bahn" kann nicht auf "privat"-Secrets zugreifen +- Zugriffsverletzungen werden geloggt und der Task wird abgebrochen + +### 2. Maschinenkontext +- Jeder Rechner hat nur Zugriff auf autorisierte Kontexte +- dhive-Laptop → nur dhive-Secrets entschlüsselbar +- Hauptrechner → alles entschlüsselbar +- Neue Maschine? Dokumentierter Onboarding-Prozess + +### 3. Föderierte Team-Zusammenarbeit +- Bahn-Team sieht nur `bahn/` als eigenständiges Git-Repo +- dhive-Team sieht nur `dhive/` als eigenständiges Git-Repo +- Nur ich sehe das vollständige Monorepo (Hub-and-Spoke) +- Bidirektionale Synchronisation, Team hat Vorrang bei Konflikten + +### 4. Multi-Harness AI-Dispatch +- Pro Kontext/Task den optimalen AI-Agenten wählen +- Kiro, Codex, Claude Code, Antigravity — einheitliche Schnittstelle +- Agent bekommt nur Workspace + Secrets seines Kontexts + +### 5. Übergreifender Wissensspeicher +- ETL-Pipeline für alle Wissensquellen (Markdown, Confluence, Jira, PDFs) +- Progressive Disclosure: Agent liest erst Index, lädt bei Bedarf Details +- Kontextübergreifende Suche mit Berechtigungsprüfung +- Kontextbrücke: Wissen gezielt freigeben (mit Sensitive-Content-Filter) + +--- + +## Benefits + +| Vorteil | Details | +|---------|---------| +| **Ein Repo, voller Überblick** | Alle Projekte an einem Ort, klar strukturiert | +| **Secrets sicher & portabel** | Verschlüsselt committet, nicht gitignored — kein manueller Transport | +| **AI-Agent-Sicherheit** | Kein versehentlicher Zugriff auf fremde Kontexte | +| **Team-Kollaboration** | Teams arbeiten unabhängig, ohne zu wissen dass ein Monorepo existiert | +| **Wissen verfügbar** | Jeder AI-Agent bekommt relevantes Wissen aus dem Index injiziert | +| **Multi-Maschinen** | Neuer Rechner = git clone + Schlüssel installieren, fertig | +| **Bahn-Repos unverändert** | Bestehende Workflows bleiben, Monorepo zieht nur rein | + +--- + +## Drawbacks / Risiken + +| Risiko | Mitigation | +|--------|-----------| +| **Monorepo wird groß** | Git-Subtrees statt Submodules (flache Checkouts möglich); Wissensdatenbank-Output kann via .gitignore ausgeschlossen werden | +| **git-crypt-Komplexität** | Dokumentierter Onboarding-Prozess; Schlüssel in Passwort-Manager | +| **OneDrive-Sync-Konflikte** | Index.lock-Handling dokumentiert; Steering-Files für zukünftige Sessions | +| **Single Point of Failure** | Regelmäßige Pushes zu GitHub/GitLab; Team-Repos als unabhängige Backups | +| **Federation-Komplexität** | Einfache team-wins-Strategie; Manuelle Konfliktauflösung nur bei echten Merge-Konflikten | +| **Lernkurve** | CLI-Tool `ctx-guard` vereinfacht alle Operationen; 13 dokumentierte Commands | + +--- + +## Tech Stack + +- **Python** — Alle Tools in `shared/tools/monorepo-cli/` +- **git-crypt** — Encryption at rest, pro Kontext +- **git subtree** — Repo-Einbindung und Federation +- **YAML** — Konfiguration, Frontmatter, Index +- **Hypothesis** — 27 Property-Based Tests für Korrektheit +- **300+ Tests** — Unit, Property, Integration (E2E) + +--- + +## Status + +✅ Architektur designed und implementiert (12 Module, 300+ Tests) +✅ Repos in Kontextordner migriert +✅ Wissensdatenbank als Upstream eingebunden +✅ CLI-Tool funktionsfähig +⬜ git-crypt einrichten (Schlüssel generieren) +⬜ Team-Repos auf GitLab erstellen +⬜ Knowledge-Management-System für Notizen starten +⬜ NoteGraph-Neuentwicklung auf Basis des Wissensspeichers diff --git a/docs/monorepo-summary.md b/docs/monorepo-summary.md new file mode 100644 index 0000000..49a5cc8 --- /dev/null +++ b/docs/monorepo-summary.md @@ -0,0 +1,165 @@ +# Monorepo-Konsolidierung – Zusammenfassung + +## Überblick + +18+ einzelne Git-Repositories wurden in eine einheitliche Monorepo-Struktur konsolidiert. Das System vereint drei Arbeitskontexte (privat, dhive, bahn) mit einem shared-Bereich und implementiert Sicherheitsgrenzen, einen Wissensspeicher, verschlüsselte Secrets und eine föderierte Team-Zusammenarbeit. + +--- + +## Architektur + +``` +Orchestrator/ (Monorepo Root) +├── bahn/ ← DB InfraGO Projekte (10 Repos) +│ ├── aisupport/ +│ ├── Analyse-O2C-C2S/ +│ ├── awesome-bahn-mcp-servers/ +│ ├── beam-mcp/ +│ ├── Confluence_Bot/ +│ ├── db-planet-mcp-server/ +│ ├── O2C-Harness/ +│ ├── project-audit/ +│ ├── teamlandkarte-mcp/ +│ └── wissensdatenbank/ ← Upstream-Subtree von DB GitLab +├── dhive/ ← dhive GmbH Projekte (2 Repos) +│ ├── Jury-Voting/ +│ └── Projekt-KIQ-HP/ +├── privat/ ← Persönliche Projekte (2 Repos) +│ ├── CV/ +│ └── NoteGraph/ ← Markiert für Neuentwicklung +├── shared/ ← Kontextübergreifend +│ ├── AI-Orchestrator/ ← Task-Dispatch-Engine +│ ├── OrgMyLife/ ← Persönliche Aufgabenverwaltung +│ ├── power_skills_and_more/ ← Agent-Erweiterungen +│ ├── references/symphony/ ← Read-Only-Referenz +│ ├── config/ ← Zentrale Konfiguration +│ └── tools/monorepo-cli/ ← ctx-guard CLI-Tool +├── monorepo.yaml ← Zentrale Konfiguration +└── .kiro/ ← Specs, Steering, MCP-Server +``` + +--- + +## Komponenten + +### 1. Ordnerstruktur-Manager (StructureManager) +- Flache 3-Ebenen-Hierarchie: Kontext → Projekt → Modul +- Kebab-case Namenskonvention (2–50 Zeichen) +- Duplikat-Erkennung pro Kontext + +### 2. Sicherheits-Guard (ContextGuard) +- Dateibasierte Zugriffskontrolle zwischen Kontexten +- Pro Kontext eigene .env-Datei (verschlüsselt) +- Audit-Logging bei Zugriffsverletzungen +- Konfigurierbar via `access-config.yaml` + +### 3. Secret-Encryption (SecretEncryptionManager) +- git-crypt-basierte Verschlüsselung pro Kontext +- Maschinenkontext-Konzept: Jeder Rechner hat nur autorisierte Schlüssel +- Passwort-Manager-Integration (Bitwarden, 1Password, KeePass) +- Secrets werden committet (verschlüsselt), nicht gitignored + +### 4. Wissensspeicher (KnowledgeStore) +- ETL-Pipeline basierend auf der DB-Wissensdatenbank-Architektur +- YAML-Frontmatter + YAML-Index (Progressive Disclosure) +- Scope-basierte Ordnerstruktur +- Volltextsuche mit Scope-Filterung +- Graph-Verknüpfungen zwischen Artefakten +- Inkrementelle Verarbeitung (Content-Hash) + +### 5. Externes-Repo-Manager (RepoManager) +- Git-Subtree-Einbindung (Read-Only oder Upstream) +- Bidirektionale Synchronisation mit Upstream-Repos +- Pre-commit-Hook für Read-Only-Schutz +- Konfiguriert via `repos.yaml` + +### 6. Kontextbrücke (ContextBridge) +- Kontextübergreifendes Teilen von Wissensartefakten +- Sensitive-Content-Filter (Regex: API-Keys, Endpoints, PII) +- Explizite Nutzerbestätigung vor Freigabe +- Widerruf jederzeit möglich + +### 7. Migrations-Engine (MigrationEngine) +- Git-Historie-bewahrende Migration via Subtree/Filter-Repo +- Konflikterkennung (Pfadkollision, Branch-Konflikte, Namenskonvention) +- Validierung nach Migration (Commits, Branches, Tags, Dateien) +- Rollback ohne andere Repos zu beeinflussen + +### 8. Orchestrator-Adapter (OrchestratorAdapter) +- Kontextauflösung aus Task-Metadaten (Labels, Projektzuordnung) +- Workspace-Erstellung unter dem korrekten Kontextordner +- Wissensinjection in Agenten-Prompts (YAML-Index) +- Multi-Harness-Dispatch (Kiro, Codex, Claude Code, Antigravity) +- Task-Abbruch bei Out-of-Context-Zugriff + +### 9. Shared Tooling (ConfigMerger) +- MCP-Server-Konfiguration-Merge (shared + context override) +- Shared-Tool-Versionierung (Symlinks, automatisch aktuell) +- Agent-Erweiterungen in harness-agnostischem Format +- Adapter-Mechanismus für verschiedene Agent-Harnesses + +### 10. Federation-Manager (FederationManager) +- Hub-and-Spoke-Topologie (Monorepo = Hub, Team-Repos = Spokes) +- Bidirektionale Synchronisation via git subtree +- Team-Isolation (Cross-Context-Leakage-Prüfung) +- Shared-Bereich-Spiegelung (Read-Only in Team-Repos) +- Konflikt-Auflösung (team-wins als Standard) +- Member-Onboarding ohne Monorepo-Kenntnis + +### 11. Git-Hooks (HookManager) +- Pre-commit: Read-Only-Repos schützen +- Pre-commit: Unverschlüsselte Secrets blockieren +- git-crypt-Filter-Integration +- Installation bei `ctx-guard init` + +### 12. CLI-Tool (ctx-guard) +13 Subcommands: `init`, `create-project`, `list-projects`, `add-repo`, `sync-repo`, `migrate`, `validate`, `search`, `encrypt`, `decrypt`, `onboard`, `fed-sync`, `fed-status` + +--- + +## Lösungen für spezifische Probleme + +| Problem | Lösung | +|---------|--------| +| 18+ Repos, kein Überblick | Einheitliche Kontextordner-Hierarchie | +| Secrets in .gitignore verloren beim Klonen | git-crypt: Secrets verschlüsselt committet | +| Mehrere Maschinen, verschiedene Zugriffsrechte | Maschinenkontext-Mapping (machine-context.yaml) | +| Team-Zusammenarbeit ohne Monorepo-Offenlegung | Hub-and-Spoke-Föderation mit Team-Repos | +| Wissen verstreut über Kontexte | Zentraler Wissensspeicher mit Scope-Filterung | +| AI-Agent greift auf fremde Secrets zu | ContextGuard + Audit-Logging + Task-Abbruch | +| Verschiedene AI-Tools (Kiro, Codex, Claude) | Multi-Harness-Dispatch mit einheitlicher Schnittstelle | +| DB-Wissensdatenbank separat pflegen | Upstream-Subtree, bidirektionale Sync | + +--- + +## Technische Metriken + +- **300+ Tests** (Unit + Property-Based + Integration) +- **12 Python-Module** in `shared/tools/monorepo-cli/` +- **27 Correctness Properties** (Hypothesis-basiert) +- **14 End-to-End-Integration-Tests** +- **13 CLI-Commands** vollständig verdrahtet + +--- + +## Heutige Aktionen + +1. ✅ Alle verbleibenden Spec-Tasks implementiert (Wave 13–20) +2. ✅ Monorepo-Git-Repository initialisiert +3. ✅ 17 Repos in Kontextordner verschoben +4. ✅ Wissensdatenbank als Upstream-Subtree eingebunden +5. ✅ Projekt-KIQ-HP nach dhive/ verschoben (Korrektur) +6. ✅ Clutter bereinigt (alte README, leere Placeholder, Secrets aus Git entfernt) +7. ✅ .gitignore aktualisiert (Secrets-Patterns) +8. ✅ Steering-Dateien für zukünftige Sessions erstellt +9. ✅ Knowledge-Management-Briefing für nächste Spec vorbereitet + +--- + +## Offene Punkte + +- [ ] NoteGraph komplett neu aufbauen (→ Knowledge-Management-Spec) +- [ ] git-crypt tatsächlich einrichten (Schlüssel generieren, .env verschlüsseln) +- [ ] Team-Repos auf GitLab erstellen und Federation aktivieren +- [ ] Wissensdatenbank-Upstream regelmäßig synchronisieren +- [ ] Remaining skipped Tasks (2.2–2.4, 3.2, 4.1, 11.2–11.4, 12.2–12.3) implementieren