From d2790ff9a13fe09f0ce08bbed1af8aceb872b0d2 Mon Sep 17 00:00:00 2001
From: DoctoDre <knie@d-hive.de>
Date: Tue, 7 Jul 2026 15:43:06 +0200
Subject: [PATCH] docs: add monorepo health checklist for regular reviews

---
 docs/MONOREPO-HEALTH-CHECKLIST.md | 100 ++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 docs/MONOREPO-HEALTH-CHECKLIST.md

diff --git a/docs/MONOREPO-HEALTH-CHECKLIST.md b/docs/MONOREPO-HEALTH-CHECKLIST.md
new file mode 100644
index 0000000..6cdc15a
--- /dev/null
+++ b/docs/MONOREPO-HEALTH-CHECKLIST.md
@@ -0,0 +1,100 @@
+# Monorepo Health Checklist
+
+Run this review periodically (recommended: every 2 weeks or at the start of a focused sprint).
+
+## Quick Health Check (5 min)
+
+```powershell
+$env:PATH = "C:\Users\AndreKnie\AppData\Local\GitHubDesktop\app-3.5.8\resources\app\git\cmd;" + $env:PATH
+cd "c:\Users\AndreKnie\OneDrive - Deutsche Bahn\Coden\Orchestrator"
+
+# 1. Git status overview
+git status --short | Measure-Object -Line
+
+# 2. Untracked files by category
+git status --short | Where-Object { $_ -match '^\?\?' } | ForEach-Object { ($_ -replace '^\?\?\s+"?([^/"]+).*', '$1') } | Sort-Object -Unique
+
+# 3. Branches
+git branch -v
+
+# 4. Ahead/behind origin
+git log --oneline origin/master..master | Measure-Object -Line
+```
+
+## Component Inventory (10 min)
+
+| Check | Command | Expected |
+|-------|---------|----------|
+| All components have COMPONENT.md | `Get-ChildItem -Recurse -Filter COMPONENT.md` | 18 files |
+| No stray .git folders (except root) | `Get-ChildItem -Recurse -Filter .git -Directory` | Only root `.git/` |
+| README presence | Check each component | All have README.md |
+| Package files valid | `npm ls` / `pip check` per component | No broken deps |
+
+## Context Folders
+
+| Context | Expected Contents | Check |
+|---------|-------------------|-------|
+| bahn/ | aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp, Confluence_Bot, db-planet-mcp-server, knowledge/, O2C-Harness, project-audit, teamlandkarte-mcp, wissensdatenbank | `Get-ChildItem bahn -Name` |
+| dhive/ | Jury-Voting, knowledge/, Projekt-KIQ-HP | `Get-ChildItem dhive -Name` |
+| privat/ | CV, knowledge/, NoteGraph | `Get-ChildItem privat -Name` |
+| shared/ | AI-Orchestrator, config/, OrgMyLife, power_skills_and_more, references/, tools/ | `Get-ChildItem shared -Name` |
+
+## Upstream Sync Status
+
+Components with external upstreams need periodic sync:
+
+| Component | Upstream | Sync Method |
+|-----------|----------|-------------|
+| bahn/wissensdatenbank | git.tech.rz.db.de/einfachbahn-lab/tools/wissensdatenbank | `git subtree pull --prefix=bahn/wissensdatenbank wissensdatenbank main --squash` |
+| privat/CV | github.com/DoctoDre/CV | Add remote, fetch, `git read-tree --prefix=privat/CV/ -u cv/main` |
+| dhive/Jury-Voting | github.com/DoctoDre/Jury-Voting | Manual copy or subtree |
+| bahn/project-audit | git.tech.rz.db.de/AndreKnie/project-audit | Manual copy (DB GitLab) |
+
+## Steering Files
+
+Expected set in `.kiro/steering/`:
+- `bahn-context.md` (fileMatch: bahn/**)
+- `brevity.md` (manual)
+- `component-docs.md` (fileMatch: **/**)
+- `git-path.md` (always)
+- `mcp-servers.md` (auto)
+- `session-context.md` (auto)
+- `workspace-context.md` (auto)
+- `workspace-notes.md` (always)
+
+## Secrets & Security
+
+- [ ] `.secrets` exists and is gitignored
+- [ ] `remarkable_token.json` is gitignored
+- [ ] No plaintext secrets in tracked files: `git grep -l "password\|token\|secret\|api_key" -- ':!.secrets' ':!*.md'`
+- [ ] No `Token extern.md` or similar files in `Coden/` root
+
+## Knowledge Store Health
+
+- [ ] Each context has `knowledge/` with `_index.yaml`
+- [ ] Inbox items are being processed (not piling up indefinitely)
+- [ ] `bahn/knowledge/inbox/` count is reasonable (check with `(Get-ChildItem bahn\knowledge\inbox -File).Count`)
+
+## Workspace Consistency
+
+- [ ] `Coden/.kiro/steering/workspace-context.md` exists for Coden workspace
+- [ ] `Orchestrator/.kiro/steering/` has all 8 files
+- [ ] `privat/CV/.kiro/steering/` exists for CV workspace
+- [ ] No stale folders in `Coden/` (only `.kiro/` and `Orchestrator/`)
+
+## Monorepo CLI
+
+```powershell
+cd shared\tools\monorepo-cli
+python -m pytest tests/test_artifact.py tests/test_capture.py tests/test_bridge.py -x --tb=short -q
+```
+
+Expected: All pass (72+ tests).
+
+## Actions After Review
+
+1. Commit any untracked COMPONENT.md or generated files that should be tracked
+2. Push to origin if ahead
+3. Merge or close stale feature branches
+4. Update `session-context.md` with current priorities
+5. Run `ctx-guard components scan` to regenerate architecture overview