markitect-main/history/MAIN_BRANCH_OPTIMIZATION_GAMEPLAN.md

Main Branch Optimization Gameplan

Executive Summary

This gameplan provides a low-risk, incremental approach to optimizing the markitect project on the main branch. Each optimization is designed to be safe, reversible, and testable without requiring protective branching.

Current State Analysis

• Directory Structure: Hybrid layout with both root-level modules and src/ structure
• Test Coverage: 307 tests passing, good foundation
• Critical Issues: Mock pollution creating 200+ directories, dual package structures
• Git Management: Good .gitignore already in place

---

Phase 1: Critical Infrastructure Cleanup (Zero Risk)

1.1 Mock Directory Cleanup (IMMEDIATE - HIGH PRIORITY)

Risk Level: ⚪ Zero Risk Impact: 🔥 Critical Duration: 5 minutes

Problem: MagicMock/Path.cwd().__truediv__()/ contains 200+ pollution directories Action: rm -rf MagicMock/ (these are test artifacts) Validation:

• Run full test suite before/after
• Confirm no legitimate files are removed
• Directory should not regenerate

1.2 Database File Management

Risk Level: ⚪ Zero Risk Impact: 🟡 Low Duration: 2 minutes

Problem: markitect.db tracked in git (should be generated) Action:

1. git rm markitect.db
2. Add to .gitignore if not already present Validation: Database regenerates on first run

---

Phase 2: Package Structure Rationalization (Low Risk)

2.1 Eliminate Dual Package Structure

Risk Level: 🟡 Low Risk Impact: 🔥 High Duration: 15 minutes

Problem: Both root-level markitect/ and src/markitect/ exist Strategy: Keep root-level, remove src/ (simpler imports) Action:

1. Compare both package structures
2. Merge any missing files from src/ to root
3. Remove src/ directory
4. Update any import references Validation: All tests pass, imports work correctly

2.2 Root-Level Module Organization

Risk Level: 🟡 Low Risk Impact: 🟢 Medium Duration: 10 minutes

Problem: Root-level modules mixed with package directories Action: Move standalone files into appropriate directories:

• tddai_cli.py → cli/tddai_cli.py or scripts/
• Shell scripts → scripts/ directory Validation: Scripts still executable, paths updated

---

Phase 3: Development Workflow Enhancement (Low Risk)

3.1 Test Organization Review

Risk Level: 🟡 Low Risk Impact: 🟢 Medium Duration: 20 minutes

Problem: Potential test duplication (282 vs 307 tests suggests missing tests) Action:

1. Identify missing tests by comparing with feature branch
2. Review for actual duplicate test cases
3. Consolidate overlapping functionality Validation: Test count stabilizes, coverage maintained

3.2 Makefile Enhancement

Risk Level: ⚪ Zero Risk Impact: 🟢 Medium Duration: 10 minutes

Current: Basic Makefile exists Action: Add standard development targets:

• make clean (remove artifacts)
• make test-quick (fast test subset)
• make lint (code quality)
• make check (pre-commit checks) Validation: All targets work correctly

---

Phase 4: Code Quality Infrastructure (Low Risk)

4.1 Import Organization

Risk Level: 🟡 Low Risk Impact: 🟢 Medium Duration: 15 minutes

Problem: Inconsistent import ordering Action:

1. Add isort configuration to pyproject.toml
2. Run isort . to standardize imports
3. Add import checking to Makefile Validation: Imports consistent, tests pass

4.2 Code Formatting Standards

Risk Level: 🟡 Low Risk Impact: 🟢 Medium Duration: 10 minutes

Action:

1. Add black configuration if not present
2. Run formatting check
3. Add formatting targets to Makefile Validation: Code style consistent

---

Phase 5: Documentation Structure (Zero Risk)

5.1 Documentation Consolidation

Risk Level: ⚪ Zero Risk Impact: 🟢 Medium Duration: 15 minutes

Problem: Multiple gameplan docs in root Action:

1. Create docs/development/gameplans/ directory
2. Move all *_GAMEPLAN.md files there
3. Update references in main docs Validation: Documentation accessible, links work

5.2 README Optimization

Risk Level: ⚪ Zero Risk Impact: 🟢 Medium Duration: 10 minutes

Action: Review and update README for current structure Validation: Setup instructions work for new users

---

Implementation Strategy

Execution Order (Strict Sequence)

1. Phase 1: Must be done first (cleans critical issues)
2. Phase 2: Core structure (foundation for later phases)
3. Phase 3: Development workflow (builds on structure)
4. Phase 4: Quality tools (requires stable structure)
5. Phase 5: Documentation (final cleanup)

Safety Protocols

• Test First: Run full test suite before any change
• Single Change: One optimization at a time
• Immediate Validation: Test after each change
• Rollback Ready: Use git commits for each step
• No Branching Required: All changes safe enough for main

Success Criteria

• ✅ All 307 tests continue to pass
• ✅ No functionality regression
• ✅ Cleaner project structure
• ✅ Improved developer experience
• ✅ Better maintainability

Estimated Total Time

• Phase 1: 7 minutes (critical)
• Phase 2: 25 minutes (structure)
• Phase 3: 30 minutes (workflow)
• Phase 4: 25 minutes (quality)
• Phase 5: 25 minutes (docs)
• Total: ~2 hours of focused work

---

Risk Mitigation

Before Starting

1. Ensure clean git working directory
2. Run test suite to confirm baseline
3. Create backup branch if paranoid: git branch backup-before-optimization

During Implementation

1. Commit after each successful optimization
2. If any test fails, immediately revert that change
3. Never proceed with broken tests

Rollback Strategy

Each phase can be reverted independently:

git revert <commit-hash>  # Revert specific optimization
git reset --hard <commit>  # Nuclear option to specific point

---

Next Steps

Start with Phase 1.1 (Mock cleanup) - it's zero risk and high impact. The entire gameplan can be executed in a single session or spread across multiple sessions as time allows.

Each optimization builds value incrementally while maintaining project stability.