Skip to main content

Documentation Consolidation Report internal/project/

Documentation Consolidation Report - internal/project/

Scope: internal/project/ directory Initial Count: 132 markdown files across 24 subdirectories Target Count: 30 total files (including v2/ folder with 56 files) Reduction: ~75% file reduction, ~80% folder reduction

Executive Summary​

The internal/project/ directory contains extensive project management documentation accumulated over multiple development phases. Most documentation is historical or superseded by the v2/ epic structure created December 2025.

Key Findings:

  • v2/ folder is ACTIVE (56 files) - Modern epic-based roadmap, DO NOT MODIFY
  • Legacy planning docs - Multiple outdated PROJECT-PLAN variants need consolidation
  • Duplicate tasklists - 8+ tasklists with overlapping content
  • Historical phases/sprints - Superseded by v2/ epic structure
  • Orphaned folders - orchestration/, reports/, checkpoints/ mostly obsolete

Consolidation Strategy: Preserve active v2/ structure, consolidate legacy plans into 3 master files, archive or delete historical documentation.

Directory Analysis​

KEEP AS-IS (Do Not Modify)​

v2/ (56 files) - ACTIVE ROADMAP​

Status: Production, actively maintained Scope: 10 epics, 10 sprints, complete v2.0 roadmap Files:

  • V2-MASTER-project-plan.md
  • V2-STRUCTURE-SUMMARY.md
  • INDEX.md
  • README.md
  • epics/E001-E010 (10 epic folders with EPIC-OVERVIEW.md + tasklist.md each)
  • sprints/Sprint-25 through Sprint-56 (32 sprint folders with SPRINT-PLAN.md each)

Rationale: This is the AUTHORITATIVE v2.0 roadmap created December 2025. All other planning docs are superseded by this structure.

Action: NO CHANGES

CONSOLIDATE​

1. plans/ (15 files) → 3 files​

Current Files:

plans/
├── 00-MASTER-PLAN.md                                      # Points to phase folders (outdated)
├── 05-PROJECT-PLAN-REFERENCE.md                           # Legacy reference
├── 1-2-3-HOW-TO-CREATE-V2-PROJECT-PLANS.md               # Meta-guide (keep)
├── COMPONENT-ACTIVATION-project-plan.md                   # Superseded by v2/E001
├── COMPONENT-UPGRADE-project-plan.md                      # Historical
├── legacy-project-plan.md                                 # Historical
├── PHASE-3-PLAN-CORE-RESTRUCTURING.md                     # Historical phase
├── PILOT-LAUNCH-CONSOLIDATED-PLAN.md                      # Superseded by v2/E010
├── PROJECT-PLAN-README-STANDARDIZATION.md                 # Completed task
├── PROJECT-PLAN-REPO-REORGANIZATION.md                    # Historical
├── PROJECT-PLAN-SKILLS-STANDARDIZATION.md                 # Completed task
├── PROJECT-PLAN-UPDATE-2025-11-16-ARCHITECTURE-SPRINT.md  # Historical sprint
├── project-plan.md                                        # Master plan (keep core)
├── V2-PROJECT-PLAN-CONSOLIDATION-SUMMARY.md              # Meta-doc about v2/
├── WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md              # Historical

Consolidation Target:

File 1: MASTER-project-plan.md (NEW - Consolidates key content)

  • Merge: project-plan.md (core content only)
  • Add reference to v2/ as authoritative roadmap
  • Include high-level historical context (phases 1-5 summary)
  • Reference component activation from v2/E001
  • Token budget: ~3000 tokens

File 2: CURRENT-SPRINT-PLAN.md (NEW - Points to active sprint)

  • Single-page quick reference to current sprint
  • Links to v2/sprints/Sprint-XX/
  • Current blockers and risks
  • Weekly status update template
  • Token budget: ~800 tokens

File 3: PLANNING-ARCHIVE-INDEX.md (NEW - Historical reference)

  • Index of all archived planning docs with descriptions
  • When each plan was created/superseded
  • Links to archived files (move to archive/ folder)
  • Token budget: ~500 tokens

DELETE:

  • 00-MASTER-PLAN.md (superseded by v2/)
  • 05-PROJECT-PLAN-REFERENCE.md (historical)
  • COMPONENT-ACTIVATION-project-plan.md (superseded by v2/E001)
  • COMPONENT-UPGRADE-project-plan.md (historical)
  • legacy-project-plan.md (historical)
  • PHASE-3-PLAN-CORE-RESTRUCTURING.md (completed, archive)
  • PILOT-LAUNCH-CONSOLIDATED-PLAN.md (superseded by v2/E010)
  • PROJECT-PLAN-README-STANDARDIZATION.md (completed task)
  • PROJECT-PLAN-REPO-REORGANIZATION.md (historical)
  • PROJECT-PLAN-SKILLS-STANDARDIZATION.md (completed task)
  • PROJECT-PLAN-UPDATE-2025-11-16-ARCHITECTURE-SPRINT.md (historical)
  • V2-PROJECT-PLAN-CONSOLIDATION-SUMMARY.md (now in v2/README.md)
  • WORK-ITEM-HIERARCHY-ORCHESTRATION-PLAN.md (historical)

KEEP (Move to archive/):

  • 1-2-3-HOW-TO-CREATE-V2-PROJECT-PLANS.md (useful meta-guide)

2. tasklists/ (8 files) → 2 files​

Current Files:

tasklists/
├── 01-TASKLIST-INDEX.md                            # Index file (useful)
├── COMPONENT-ACTIVATION-tasklist.md                # Superseded by v2/E001
├── COMPONENT-UPGRADE-TASKLIST-WITH-CHECKBOX.md     # Historical
├── HELP-DOCUMENTATION-tasklist.md                  # Historical
├── legacy-tasklist.md                              # Historical
├── MASTER-TASKLISTS-CONSOLIDATED.md                # Master checklist (keep/update)
├── PHASE-3-TASKLIST-CORE-RESTRUCTURING.md          # Historical phase
├── tasklist-with-checkboxes.md                     # Another master (duplicate)

Consolidation Target:

File 1: ACTIVE-tasklist.md (NEW - Consolidates current tasks)

  • Merge: MASTER-TASKLISTS-CONSOLIDATED.md + tasklist-with-checkboxes.md
  • Remove completed tasks (archive them)
  • Link to v2/ epic tasklists for detailed breakdowns
  • Focus on framework-wide tasks not in v2/ epics
  • Token budget: ~2000 tokens

File 2: COMPLETED-TASKS-ARCHIVE.md (NEW - Historical record)

  • All completed tasks from legacy tasklists
  • Organized by completion date
  • Reference to achievements
  • Token budget: ~1500 tokens (or delete if not valuable)

DELETE:

  • COMPONENT-ACTIVATION-tasklist.md (superseded by v2/E001/tasklist.md)
  • COMPONENT-UPGRADE-TASKLIST-WITH-CHECKBOX.md (historical)
  • HELP-DOCUMENTATION-tasklist.md (historical)
  • legacy-tasklist.md (historical)
  • PHASE-3-TASKLIST-CORE-RESTRUCTURING.md (completed, archive)
  • tasklist-with-checkboxes.md (merge into ACTIVE-tasklist.md)
  • MASTER-TASKLISTS-CONSOLIDATED.md (merge into ACTIVE-tasklist.md)

KEEP:

  • 01-TASKLIST-INDEX.md (useful index, update to reference ACTIVE-tasklist.md)

3. status/ (4 files) → 1 file​

Current Files:

status/
├── 02-PROJECT-STATUS.md                # Historical status
├── 03-ROADMAP.md                       # Historical roadmap
├── PROJECT-STATUS.md                   # Current status (keep/update)
├── ROADMAP-AND-CHANGELOG.md            # Changelog (keep/update)

Consolidation Target:

File 1: PROJECT-STATUS.md (UPDATE - Comprehensive status)

  • Merge: PROJECT-STATUS.md + 02-PROJECT-STATUS.md (recent updates only)
  • Add reference to v2/ for roadmap
  • Include framework maturity metrics
  • Component inventory (link to config/component-counts.json)
  • Recent milestones and current focus
  • Token budget: ~2500 tokens

File 2: ROADMAP-AND-CHANGELOG.md (KEEP - Update to reference v2/)

  • Keep as changelog
  • Add note that v2/ contains active roadmap
  • Historical version releases
  • Token budget: ~2000 tokens

DELETE:

  • 02-PROJECT-STATUS.md (merge recent content into PROJECT-STATUS.md)
  • 03-ROADMAP.md (superseded by v2/ and ROADMAP-AND-CHANGELOG.md)

DELETE (Historical/Superseded)​

phases/ (6 folders) - Superseded by v2/​

Content: Phase 1-5 planning from 2025 pre-v2 structure Status: Superseded by v2/ epic structure (December 2025)

Action: DELETE entire phases/ folder Rationale: v2/ epic structure (E001-E010, 10 sprints) replaces the phase-based planning model. All phase content is either completed or migrated to v2/ epics.

Files to Delete:

  • phases/phase-1-foundation/
  • phases/phase-2-documentation/
  • phases/phase-3-standards/
  • phases/phase-4-autonomy/ (superseded by v2/E001-AUTONOMY)
  • phases/phase-5-production/ (superseded by v2/E006-PRODUCTION-READINESS)

sprints/ (6 folders) - Superseded by v2/sprints/​

Content: Pre-v2 sprint planning (Sprint 1-6 roughly) Status: Superseded by v2/sprints/Sprint-25 through Sprint-56

Action: DELETE entire sprints/ folder Rationale: v2/sprints/ contains current sprint structure. Old sprints are historical.

orchestration/ (6 folders) - Historical​

Content: Orchestration planning documents from autonomy research Status: Superseded by v2/E001-AUTONOMY

Action: DELETE entire orchestration/ folder Rationale: Autonomy planning consolidated into v2/E001. Orchestration details now in v2/E001/tasklist.md.

reports/ (4 folders) - Historical​

Content: Task extraction pipeline reports, analysis reports Status: Point-in-time snapshots, no ongoing value

Action: DELETE entire reports/ folder OR move to archive/reports/ if needed for reference Rationale: Reports are historical snapshots. Current status is in status/PROJECT-STATUS.md and v2/.

documentation-project/ (8 files) - Historical​

Content: Documentation reorganization project (Phase 2, completed December 2025) Status: Completed project

Action: DELETE entire documentation-project/ folder Rationale: Documentation reorganization is complete (customer/contributor split done December 21, 2025). No ongoing project management needed.

migration-plans/ (2 folders) - Historical​

Content: Migration strategies for framework upgrades Status: Completed migrations

Action: DELETE entire migration-plans/ folder Rationale: Migrations are one-time events. If needed, can be documented in ROADMAP-AND-CHANGELOG.md.

submodule-plans/ (2 folders) - Evaluate​

Content: Submodule-specific planning documents Status: Unknown without inspection

Action: READ contents first, then decide:

  • If active: Move to relevant v2/ epic
  • If historical: DELETE
  • If reference: Move to archive/

archive/ (3 folders) - Keep as Archive​

Content: Already archived content Status: Archive repository

Action: KEEP - Use this as destination for any docs worth preserving but not actively used

Root-Level Files (13 files)​

Keep:

  • CLAUDE.md (directory index)
  • README.md (if exists)

Evaluate:

  • DOC-CONSOLIDATION-MOE-PLAN.md (meta-planning, can delete after consolidation complete)
  • MASTER-PROJECT-TIMELINE-AND-STRATEGY.md (superseded by v2/)
  • PILOT-LAUNCH-CHECKLIST.md (superseded by v2/E010)
  • V2-CONSOLIDATION-* files (meta-docs, can delete after v2/ stable)
  • WORK-ITEM-HIERARCHY-* files (historical, can delete)
  • legacy-project-management-README.md (delete)

Consolidation Action Plan​

Phase 1: Create Consolidated Files (Writer W4 Task)​

1. Create plans/MASTER-project-plan.md

  • Extract core content from plans/project-plan.md (lines 1-200, high-level overview)
  • Add YAML frontmatter (audience: contributor, type: spec)
  • Add "See v2/ for current roadmap" notice
  • Include Phase 1-5 historical summary
  • Token budget: ~3000

2. Create plans/CURRENT-SPRINT-PLAN.md

  • Template for weekly sprint status
  • Link to active sprint in v2/sprints/
  • Current blockers/risks section
  • Token budget: ~800

3. Create tasklists/ACTIVE-tasklist.md

  • Merge MASTER-TASKLISTS-CONSOLIDATED.md + tasklist-with-checkboxes.md
  • Remove completed tasks
  • Link to v2/ epic tasklists for detailed breakdowns
  • Token budget: ~2000

4. Update status/PROJECT-STATUS.md

  • Merge recent updates from 02-PROJECT-STATUS.md
  • Reference v2/ for roadmap
  • Update component counts
  • Token budget: ~2500

5. Update status/ROADMAP-AND-CHANGELOG.md

  • Add note: "See v2/ for active roadmap"
  • Keep as historical changelog
  • Token budget: ~2000

Phase 2: Add YAML Frontmatter (All Kept Files)​

Required Frontmatter:

---
title: "Document Title"
audience: contributor
type: spec  # or "plan", "status", "tasklist"
status: active  # or "archived", "superseded"
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
tokens: XXXX  # Estimated token count
summary: "One-sentence description"
---

Apply to:

  • All 3 new files in plans/
  • All 2 files in tasklists/
  • All 2 files in status/
  • CLAUDE.md (if not already present)
  • All files in v2/ (if frontmatter missing)

Phase 3: Deletions (Requires User Approval)​

CRITICAL: Request explicit user approval before deleting ANY files.

Folders to Delete:

  • phases/ (6 folders, ~20 files)
  • sprints/ (6 folders, ~15 files)
  • orchestration/ (6 folders, ~12 files)
  • reports/ (4 folders, ~10 files) OR move to archive/
  • documentation-project/ (8 files)
  • migration-plans/ (2 folders)
  • submodule-plans/ (evaluate first)

Files to Delete in plans/:

  • 12 legacy plan files (list above)

Files to Delete in tasklists/:

  • 6 legacy tasklist files (list above)

Files to Delete in status/:

  • 2 files (02-PROJECT-STATUS.md, 03-ROADMAP.md)

Root-level files to Delete:

  • DOC-CONSOLIDATION-MOE-PLAN.md (after consolidation complete)
  • MASTER-PROJECT-TIMELINE-AND-STRATEGY.md
  • PILOT-LAUNCH-CHECKLIST.md
  • V2-CONSOLIDATION-* files (3 files)
  • WORK-ITEM-HIERARCHY-* files (3 files)
  • legacy-project-management-README.md

Total Estimated Deletions: ~100 files across 25+ folders

Phase 4: Archive Preservation​

Move to archive/ (if worth preserving):

  • plans/1-2-3-HOW-TO-CREATE-V2-PROJECT-PLANS.md
  • Any reports/ content if deemed valuable
  • Any submodule-plans/ content if deemed valuable

Final Structure (Target: 30 files total)​

internal/project/
├── CLAUDE.md                                    # 1 - Directory index
├── README.md (optional)                         # 2 - High-level overview
│
├── plans/                                       # 3 files
│   ├── MASTER-project-plan.md                   # NEW - Consolidated master plan
│   ├── CURRENT-SPRINT-PLAN.md                   # NEW - Active sprint reference
│   └── PLANNING-ARCHIVE-INDEX.md (optional)     # NEW - Historical index
│
├── tasklists/                                   # 2 files
│   ├── ACTIVE-tasklist.md                       # NEW - Current tasks
│   └── 01-TASKLIST-INDEX.md                     # UPDATED - Index
│
├── status/                                      # 2 files
│   ├── PROJECT-STATUS.md                        # UPDATED - Current status
│   └── ROADMAP-AND-CHANGELOG.md                 # KEEP - Changelog
│
├── v2/                                          # 56 files (DO NOT MODIFY)
│   ├── README.md
│   ├── INDEX.md
│   ├── V2-MASTER-project-plan.md
│   ├── V2-STRUCTURE-SUMMARY.md
│   ├── V2-EPIC-STRUCTURE.json
│   ├── migration-analysis.json
│   ├── epics/E001-E010/ (10 folders, 20 files)
│   └── sprints/Sprint-25 to Sprint-56/ (32 folders, 32 files)
│
├── archive/                                     # Variable (historical reference)
│   ├── plans/
│   ├── reports/ (optional)
│   └── guides/
│
├── checkpoints/ (keep if active)                # 2 folders
├── docs/ (evaluate)                             # 1 folder
├── internal/ (evaluate)                         # 1 folder
├── master-plans/ (evaluate)                     # 1 folder
└── summaries/ (evaluate)                        # 1 folder

**Total:** ~30 files (excluding archive/ and folders marked for evaluation)

Benefits of Consolidation​

For Contributors:

  • Single source of truth for planning (v2/)
  • Clear separation: active vs. historical
  • Faster navigation (3 files in plans/ vs. 15)
  • Reduced cognitive load

For AI Agents:

  • Token efficiency: Read MASTER-project-plan.md (~3000 tokens) vs. scanning 15 files (~20,000+ tokens)
  • Clear routing: v2/ for roadmap, plans/ for meta-planning
  • Reduced context window pollution

For Maintainability:

  • Less duplication = easier updates
  • Clear deprecation path (archive/)
  • Standardized frontmatter for programmatic access

Risks & Mitigations​

Risk 1: Data Loss

  • Mitigation: Request user approval before deleting anything
  • Mitigation: Move questionable files to archive/ first
  • Mitigation: Git history preserves all deleted content

Risk 2: Breaking References

  • Mitigation: Search for internal links before deleting
  • Mitigation: Update CLAUDE.md with new structure
  • Mitigation: Add redirect notes in archived files

Risk 3: User Disagrees with Deletions

  • Mitigation: Present this plan for approval FIRST
  • Mitigation: Provide detailed rationale for each deletion
  • Mitigation: Offer archive/ as compromise

Next Steps​

Immediate (Requires User Approval):

  1. User reviews this report - Approve/modify consolidation plan
  2. User approves deletions - Explicit permission for each folder/file deletion
  3. Writer W4 proceeds - Execute approved consolidation actions

After Approval:

  1. Create 5 new/updated files (MASTER-project-plan.md, CURRENT-SPRINT-PLAN.md, ACTIVE-tasklist.md, etc.)
  2. Add YAML frontmatter to all kept files
  3. Execute approved deletions (with git commits for each major deletion)
  4. Move approved files to archive/
  5. Update CLAUDE.md to reflect new structure
  6. Generate final report with file counts and structure

Checklist​

  • User reviews consolidation plan
  • User approves folder deletions
  • User approves file deletions
  • Create plans/MASTER-project-plan.md
  • Create plans/CURRENT-SPRINT-PLAN.md
  • Create tasklists/ACTIVE-tasklist.md
  • Update status/PROJECT-STATUS.md
  • Update status/ROADMAP-AND-CHANGELOG.md
  • Add YAML frontmatter to all kept files
  • Delete approved folders (phases/, sprints/, orchestration/, reports/, documentation-project/, migration-plans/)
  • Delete approved files in plans/, tasklists/, status/, root-level
  • Move approved files to archive/
  • Update CLAUDE.md
  • Generate final structure report
  • Commit all changes

Status: PLAN READY FOR USER APPROVAL Prepared By: Writer W4 (MoE Documentation Consolidation) Date: 2025-12-22 Next Action: Await user approval before proceeding with any deletions or consolidations