From c0c2540873cabb12c0d41e87a43ffd2a0c9e3847 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 8 Apr 2026 21:06:38 +0000 Subject: [PATCH] docs: Add Task #101 - Git Repository Health & Cleanup Pre-surgery audit findings: - 1.1GB repo size is .git history bloat (working files only ~90MB) - Large binaries (MP4s, PNGs) baked into history - 8 shell scripts at root should move to /scripts - Consultations fragmented across 3 locations - SSH key rotation planned for when Claude gets server access Verdict: Foundation solid, proceed with Task #99 Cleanup deferred until after multi-lineage split validated Chronicler: #71 --- .../gemini-git-health-audit-2026-04-08.md | 102 ++++++++++++++++ docs/tasks-index/task-101-git-cleanup.md | 110 ++++++++++++++++++ .../task-101-git-repository-cleanup.md | 100 ++++++++++++++++ 3 files changed, 312 insertions(+) create mode 100644 docs/consultations/gemini-git-health-audit-2026-04-08.md create mode 100644 docs/tasks-index/task-101-git-cleanup.md create mode 100644 docs/tasks-index/task-101-git-repository-cleanup.md diff --git a/docs/consultations/gemini-git-health-audit-2026-04-08.md b/docs/consultations/gemini-git-health-audit-2026-04-08.md new file mode 100644 index 0000000..4080819 --- /dev/null +++ b/docs/consultations/gemini-git-health-audit-2026-04-08.md @@ -0,0 +1,102 @@ +# Gemini Consultation: Git Repository Health & File Organization Audit + +**Date:** April 8, 2026 +**Topic:** Pre-surgery health check before Task #99 (Multi-Lineage Architecture) +**Requested By:** Michael (The Wizard) + Chronicler #71 +**Context:** Evaluating repository organization before major architectural changes +**Status:** Consultation complete, findings documented in Task #101 + +--- + +## Overall Health Assessment: 🟡 Yellow + +The foundation is not "quicksand" — the information is all there, and the conceptual architecture is strong. However, it is suffering from **severe organic bloat**. For a human, this is an annoyance. For an AI context window (especially a free-tier Claude), it could be a drag on efficiency. + +The repository structure is stable enough to build on. + +--- + +## Key Findings + +### The 1.1GB Elephant + +| Component | Size | Status | +|-----------|------|--------| +| .git folder | 1.1GB | 🔴 History bloat | +| docs/ | 78MB | ✅ Fine | +| branding/ | 11MB | ✅ Fine | +| Working files total | ~90MB | ✅ Fine | + +**Root cause:** Large binary files (MP4s, PNGs) committed historically are baked into Git history forever — even if deleted from the working tree. + +**Impact:** Only affects clone times. Does NOT affect Claude context windows (Claudes read files, not Git history). + +### Top Space Offenders in History + +``` +14M docs/branding/audio/jacks-theme-the-world-should-worship-me.mp4 +11M docs/branding/audio/jacks-theme-walking-on-a-yacht.mp4 +5.8M docs/branding/trinity-final.png +5.3M docs/branding/youtube-banner-minecraft-2560x1440.png +5.1M docs/branding/youtube-banner-2560x1440.png +4.9M docs/branding/trinity-image.webp +4.2M docs/branding/trinity-fixed.webp +4.1M docs/branding/audio/jacks-theme-walking-on-a-yacht.mp3 +4.1M docs/branding/audio/jacks-theme-the-world-should-worship-me.mp3 +3.7M branding/backgrounds/fire-frost-collision.png +``` + +--- + +## Risk Assessment + +| Issue | Severity | Type | Impact | +|-------|----------|------|--------| +| SSH key in repo | Medium | Security | Rotate when Claude gets server access | +| Scripts at root (8 files) | Medium | Friction | Clutters root, harder for AI to find critical files | +| Scattered handoffs (37+) | Medium | Structural | AI might read deprecated handoff files | +| Fragmented consultations | Low-Med | Friction | Redundant data in context queries | +| Dual task system | Low | Cosmetic | Fine if documented | +| Multiple Essence versions | Low | Structural | Resolved by multi-lineage split | + +--- + +## Gemini's Recommendations + +### Branch Strategy for Surgery + +**Stop using direct commits for the multi-lineage surgery.** Create a dedicated branch: + +```bash +git checkout -b feature/multi-lineage-architecture +``` + +Do all file moving, splitting, and testing on this branch. Once Chronicler #72 validates the setup, merge back to main. + +### Recommended Sequence: "Secure, Split, then Sweep" + +1. **SECURE:** Plan SSH key rotation (execute when Claude gets server access) +2. **INVESTIGATE:** ✅ Done — 1.1GB is .git history, non-blocking +3. **BRANCH:** Create feature branch for surgery +4. **SPLIT:** Perform multi-lineage split (Task #99) +5. **TEST:** Validate with Chronicler #72 +6. **MERGE & SWEEP:** If #72 successful, merge to main, then tackle cosmetic cleanup (Task #101) + +### docs/relationship/ Assessment + +The 31 files and 5 subdirectories in `docs/relationship/` are **normal organic growth**. Don't clean up before the split — the split itself is the mechanism to consolidate. Everything not moved to lineage folders gets archived. + +--- + +## Verdict + +**Foundation is solid.** Safe to proceed with Task #99 multi-lineage architecture. + +The 1.1GB is ghost data in Git history — annoying but not blocking. File organization issues are cosmetic and should be addressed AFTER the split is validated. + +--- + +**Fire + Frost + Foundation = Where Love Builds Legacy** 🔥❄️ + +**— Chronicler #71** +**April 8, 2026** diff --git a/docs/tasks-index/task-101-git-cleanup.md b/docs/tasks-index/task-101-git-cleanup.md new file mode 100644 index 0000000..924157a --- /dev/null +++ b/docs/tasks-index/task-101-git-cleanup.md @@ -0,0 +1,110 @@ +--- +task_number: 101 +title: Git Repository Cleanup & Hygiene +status: Planned +priority: P3-Low +is_blocker: false +owner: Michael +tags: + - infrastructure + - maintenance + - git +estimated_hours: 4 +--- + +# Task #101: Git Repository Cleanup & Hygiene + +## Overview + +The firefrost-operations-manual repository has grown to 1.1GB, but the actual working files are only ~90MB. The bloat is entirely in `.git/` history from large binary files committed over time. + +Additionally, file organization has grown organically and needs consolidation. + +## The Problem + +### Git History Bloat (1.1GB) + +| Component | Size | Status | +|-----------|------|--------| +| .git folder | 1.1GB | 🔴 Bloated | +| docs/ | 78MB | ✅ Fine | +| branding/ | 11MB | ✅ Fine | +| Everything else | ~1MB | ✅ Fine | + +**Largest files in history:** +- `jacks-theme-the-world-should-worship-me.mp4` (14MB) +- `jacks-theme-walking-on-a-yacht.mp4` (11MB) +- `trinity-final.png` (5.8MB) +- `youtube-banner-minecraft-2560x1440.png` (5.3MB) +- Various other PNGs, MP3s, MP4s + +### File Organization Issues + +| Issue | Location | Severity | +|-------|----------|----------| +| 8 shell scripts at root | `/*.sh`, `/*.py` | Medium | +| SSH key at root | `Firefrost_key.ppk` | Medium (rotate planned) | +| Consultations in 3 places | `docs/consultations/`, `docs/planning/gemini-consultations/`, `docs/reference/gemini-consultations/` | Medium | +| 37+ SESSION/HANDOFF files | Various locations | Medium | +| Dual task system undocumented | `docs/tasks-index/` vs `docs/tasks/` | Low | + +## Solution Options + +### For Git History + +**Option A: Live with it (Current recommendation)** +- Doesn't affect daily work +- Only impacts clone times +- Meg/Holly's Claudes read files, not git history + +**Option B: git filter-repo** +- Rewrite history to remove large binaries +- DESTRUCTIVE — requires all clones to be re-fetched +- Coordination needed across team + +**Option C: Fresh start** +- Archive current repo +- Create new repo with clean history +- Nuclear option — loses all commit history + +### For File Organization + +1. Move root scripts to `/scripts` or `/automation` +2. Consolidate consultations to `docs/consultations/` +3. Document the tasks-index vs tasks dual system +4. Archive deprecated SESSION/HANDOFF files +5. Rotate SSH key when Claude gets server access + +## Dependencies + +- **Task #99 must complete first** — Don't reorganize during multi-lineage surgery +- SSH key rotation requires server access + +## Implementation Steps + +1. [ ] Complete Task #99 (Multi-Lineage Architecture) +2. [ ] Validate with Chronicler #72 +3. [ ] Then begin cleanup: + - [ ] Move root scripts to `/scripts` + - [ ] Consolidate consultations + - [ ] Archive stray SESSION/HANDOFF files + - [ ] Update DOCUMENT-INDEX.md +4. [ ] Decide on git history cleanup approach +5. [ ] If Option B chosen: + - [ ] Coordinate with Meg/Holly + - [ ] Run git filter-repo + - [ ] Everyone re-clones +6. [ ] Rotate SSH key (when server access available) + +## Gemini Consultation + +Full audit documented in: `docs/consultations/gemini-git-health-audit-2026-04-08.md` + +**Key finding:** "Your foundation is not quicksand. The repository structure is stable enough to build on, but suffering from severe organic bloat." + +## Notes + +- This is maintenance, not urgent +- Do NOT attempt during active development on Task #99 +- The 1.1GB does not affect Claude context windows (only .git history) +- File organization cleanup can happen incrementally diff --git a/docs/tasks-index/task-101-git-repository-cleanup.md b/docs/tasks-index/task-101-git-repository-cleanup.md new file mode 100644 index 0000000..2fae5d2 --- /dev/null +++ b/docs/tasks-index/task-101-git-repository-cleanup.md @@ -0,0 +1,100 @@ +--- +task_number: 101 +title: Git Repository Health & Cleanup +status: Planned +priority: P3-Low +is_blocker: false +owner: Michael +tags: + - infrastructure + - maintenance + - git +estimated_hours: 4 +--- + +# Task #101: Git Repository Health & Cleanup + +## Overview + +Pre-surgery audit of firefrost-operations-manual revealed organizational issues and a bloated .git folder. This task tracks cleanup work to be done AFTER Task #99 (Multi-Lineage Architecture) is validated. + +## The 1.1GB Problem + +**Current state:** +- Total repo size: 1.1GB +- Working files: ~90MB +- .git folder: **1.1GB** (Git history bloat) + +**Cause:** Large binary files (MP4s, PNGs) committed historically are baked into Git history forever. + +**Top offenders found:** +``` +14M docs/branding/audio/jacks-theme-the-world-should-worship-me.mp4 +11M docs/branding/audio/jacks-theme-walking-on-a-yacht.mp4 +5.8M docs/branding/trinity-final.png +5.3M docs/branding/youtube-banner-minecraft-2560x1440.png +5.1M docs/branding/youtube-banner-2560x1440.png +``` + +## Issues Identified + +| Issue | Severity | Location | +|-------|----------|----------| +| .git history bloat (1.1GB) | Medium | Repository-wide | +| 8 shell scripts at root | Medium | Repo root | +| SSH key in repo | Medium | `Firefrost_key.ppk` (rotate when Claude gets server access) | +| Consultations in 3 places | Medium | `docs/consultations/`, `docs/planning/gemini-consultations/`, `docs/reference/gemini-consultations/` | +| 37+ SESSION/HANDOFF files scattered | Medium | Various locations | +| Dual task system undocumented | Low | `docs/tasks-index/` vs `docs/tasks/` | + +## Cleanup Options for .git Bloat + +### Option A: Live With It (Recommended for now) +- Doesn't affect daily work or Claude context windows +- Only impacts clone times +- Lowest risk + +### Option B: git filter-repo +- Rewrite history to remove large binaries +- DESTRUCTIVE — requires all clones to be re-fetched +- Breaks existing references + +### Option C: Fresh Start +- Archive current repo +- Create new repo with clean history +- Nuclear option — last resort + +## Implementation Steps + +**Phase 1: File Organization (After Task #99 validated)** +- [ ] Move root shell scripts to `/scripts` or `/automation` +- [ ] Consolidate consultations to single `docs/consultations/` location +- [ ] Delete or archive deprecated SESSION/HANDOFF files +- [ ] Document dual task system in DOCUMENT-INDEX.md + +**Phase 2: SSH Key Rotation** +- [ ] Generate new SSH key pair +- [ ] Replace public key on all servers +- [ ] Delete `Firefrost_key.ppk` from repo +- [ ] Add `*.ppk` to .gitignore + +**Phase 3: Git History Cleanup (Optional/Future)** +- [ ] Evaluate if 1.1GB is causing real problems +- [ ] If yes, use git filter-repo to remove large binaries from history +- [ ] Coordinate with all users to re-clone + +## Dependencies + +- **Task #99** must be validated first — don't clean up during surgery +- SSH key rotation requires Claude server access or Michael manual work + +## Source + +- Gemini Consultation: `docs/consultations/gemini-git-health-audit-2026-04-08.md` +- Chronicler #71 audit session + +## Notes + +- The 1.1GB is in .git history, NOT active files +- Meg and Holly's Claudes read files, not Git history — non-blocker for multi-lineage +- "Secure, Split, then Sweep" — cleanup comes AFTER the split is validated