Git Repository Management Enhancement Plan

Document Version: 1.0
Created: 2026-02-02
Status: Proposed

---

Executive Summary

The current git management scripts (git_status.py, git_cleanup.sh, quick_push.sh) provide foundational capabilities. This document outlines enhancements to transform these into a production-grade developer operations toolkit aligned with Coditect's autonomous development methodology.

---

Current State Assessment

✅ What's Working

Component	Capability	Status
git_status.py	Multi-format reporting (JSON, Markdown, text)	✅ Complete
git_status.py	Auto-categorization by path patterns	✅ Complete
git_status.py	Staleness detection	✅ Complete
git_cleanup.sh	Batch push with dry-run	✅ Complete
git_cleanup.sh	Divergence resolution (interactive)	✅ Complete
quick_push.sh	Fast submodule push	✅ Complete

⚠️ Gaps Identified

Gap	Impact	Priority
No automation (manual execution required)	Drift accumulates unnoticed	P1
No HTML/visual dashboard	Poor at-a-glance visibility	P2
Submodule hierarchy not properly handled	rollout-master sync is fragile	P1
No git hooks for proactive warnings	Issues caught late	P2
No integration with Coditect workflows	Standalone tooling	P3
Missing .gitignore templates	Manual fixes required	P1

---

Proposed Enhancements

Phase 1: Immediate Value (This Week)

1.1 Daily Automation (macOS launchd)

Purpose: Automatically generate status reports and alert on drift.

Deliverables:

• com.coditect.git-status.plist — LaunchAgent for daily scans
• git_daily_report.sh — Wrapper script with notifications
• Cron alternative for Linux environments

Trigger: Daily at 9:00 AM local time

Actions:

1. Run git_status.py --format all
2. Compare to previous day's report
3. Send macOS notification if:
   • New dirty repos detected
   • Repos >7 days without push
   • Divergence detected

1.2 Submodule Sync Script

Purpose: Handle coditect-rollout-master and its nested submodules properly.

Deliverables:

• submodule_sync.sh — Recursive submodule operations

Capabilities:

./submodule_sync.sh status      # Show all submodule states
./submodule_sync.sh pull        # Recursive pull (fetch + merge)
./submodule_sync.sh push        # Push all (bottom-up order)
./submodule_sync.sh commit-all  # Stage and commit all dirty submodules

Key Feature: Respects dependency order (children before parents).

1.3 Ready-to-Use .gitignore Templates

Purpose: Fix the noisy home directory and PROJECTS repos.

Deliverables:

• templates/gitignore-home.txt — For ~/halcasteel
• templates/gitignore-projects.txt — For ~/PROJECTS
• templates/gitignore-coditect.txt — Standard Coditect repo ignore patterns

---

Phase 2: Enhanced Visibility (Next 2 Weeks)

2.1 HTML Dashboard

Purpose: Visual status dashboard for the 34-repo portfolio.

Deliverables:

• git_status.py --format html — New output format
• Self-contained HTML with embedded CSS
• Color-coded status indicators
• Filterable/sortable table
• Export to PDF capability

Mockup:

┌─────────────────────────────────────────────────────────────┐
│  CODITECT Repository Dashboard          🔴 24 Dirty  ✅ 10 Clean │
├─────────────────────────────────────────────────────────────┤
│  [Filter: All ▼] [Category: All ▼] [Sort: Status ▼]        │
├─────────────────────────────────────────────────────────────┤
│  ⚠️ coditect-rollout-master    main   +10 unstaged   5d ago │
│  ⚠️ coditect-task-orchestrator main   +1 untracked   5d ago │
│  ✅ coditect-compliance-core   main   clean          1d ago │
│  ...                                                        │
└─────────────────────────────────────────────────────────────┘

2.2 Git Hooks Package

Purpose: Proactive warnings before problems occur.

Deliverables:

• hooks/pre-push — Warns about dirty sibling repos
• hooks/post-commit — Updates local status cache
• install_hooks.sh — Installs hooks to all Coditect repos

Pre-push behavior:

⚠️  WARNING: 3 sibling repos have unpushed changes:
    - coditect-telemetry (+2 commits)
    - coditect-task-orchestrator (+1 commit)
    - coditect-compliance-core (+1 commit)

Push anyway? [y/N]

---

Phase 3: Coditect Integration (Month 2)

3.1 MCP Server for Git Status

Purpose: Allow Claude agents to query repo status directly.

Deliverables:

• mcp-git-status/ — MCP server implementation
• Tools: list_repos, get_repo_status, push_repo, sync_submodules

Integration: Claude Code and Coditect agents can autonomously:

• Check repo status before making changes
• Push changes after completing tasks
• Report on portfolio health

3.2 FoundationDB Integration

Purpose: Persist repo metadata for historical analysis.

Deliverables:

• Schema for repo status events
• Loader script to ingest JSON reports
• Query interface for trends (commits/week, drift patterns)

3.3 Compliance Audit Trail

Purpose: Track repo changes for regulated workflows.

Deliverables:

• Timestamped status snapshots
• Change detection with diff
• Export to compliance report format

---

Implementation Roadmap

Week 1 (Feb 3-9)
├── Day 1-2: Daily automation (launchd + wrapper)
├── Day 3-4: Submodule sync script
└── Day 5: .gitignore templates + deployment

Week 2 (Feb 10-16)
├── Day 1-3: HTML dashboard format
└── Day 4-5: Git hooks package

Week 3-4 (Feb 17-28)
├── MCP server skeleton
├── FoundationDB schema
└── Integration testing

Month 2 (March)
├── Full MCP implementation
├── Historical analytics
└── Compliance features

---

Deliverables Summary

Phase 1 Artifacts (Immediate)

File	Description	Lines
com.coditect.git-status.plist	macOS LaunchAgent	~40
git_daily_report.sh	Daily automation wrapper	~80
submodule_sync.sh	Recursive submodule operations	~200
templates/gitignore-home.txt	Home directory ignore	~30
templates/gitignore-projects.txt	Projects directory ignore	~20
templates/gitignore-coditect.txt	Standard Coditect patterns	~50

Phase 2 Artifacts

File	Description	Lines
git_status.py (update)	Add HTML format	+150
hooks/pre-push	Sibling repo warning	~60
hooks/post-commit	Status cache update	~30
install_hooks.sh	Hook installer	~50

Phase 3 Artifacts

File	Description	Lines
mcp-git-status/server.py	MCP server	~300
mcp-git-status/tools.py	Tool implementations	~200
fdb_schema.py	FoundationDB schema	~100
fdb_loader.py	JSON to FDB loader	~150

---

Success Metrics

Metric	Current	Target	Timeline
Dirty repos	24 (71%)	<5 (15%)	2 weeks
Unpushed commits	11 repos	0 repos	1 week
Stale repos (>30d)	16 (47%)	<3 (10%)	1 month
Manual status checks	Daily	Automated	1 week
Time to detect drift	Hours/days	<1 hour	1 week

---

Appendix A: Quick Wins (Do Today)

# 1. Push all unpushed submodules
./quick_push.sh

# 2. Fix PROJECTS divergence
cd ~/PROJECTS
git fetch origin
git rebase origin/main
git push

# 3. Fix home directory noise
cd ~
echo 'PROJECTS/' >> .gitignore
echo 'Library/' >> .gitignore
echo '.cache/' >> .gitignore
git add .gitignore
git commit -m "chore: Ignore noisy directories"
git push

# 4. Schedule manual review
# Add calendar event: "Weekly Git Portfolio Review" every Monday 9 AM

---

Appendix B: Architecture Alignment

This tooling aligns with Coditect's architecture principles:

Principle	Application
Event-driven	Status changes trigger notifications
Observability	Dashboard provides visibility into repo health
Automation	Daily scans reduce manual overhead
Compliance	Audit trail supports regulated workflows
Agent-ready	MCP server enables autonomous operations

---

Appendix C: Risk Mitigation

Risk	Mitigation
Automation pushes broken code	Dry-run by default, requires explicit --execute
Hooks slow down workflow	Hooks are advisory only, can be bypassed
FDB adds complexity	FDB integration is optional, JSON reports standalone
MCP server security	Read-only by default, write operations require confirmation

---

Next Steps

Immediate (Today):

1. ✅ Review and approve this plan
2. Execute Appendix A quick wins
3. Confirm Phase 1 priorities

Request:

• Confirm which Phase 1 deliverables to build first
• Any modifications to the proposed approach?
• Timeline constraints or dependencies?

---

Document prepared for Hal Casteel, CEO/CTO AZ1.AI Inc.
Coditect Development Operations Tooling