# Root Markdown Move Plan (Phase 1 draft)

- Scope: root-level `.md` files only. Nothing has been moved yet.
- Method: heuristic classification by prefix/keywords into target “boxes”.
  - Keep root: `README.md`, `DOCS_INDEX.md`, `HISTORY.md`, `AGENTS.md`.
  - specs/env: `ENV_VARS*`, `HAKO_MIR_FFI_SPEC.md`.
  - status: `PHASE*`, `P0_*`, `*_COMPLETION_REPORT`, `TASK_FOR*`, cleanup/source-map.
  - analysis/bug: `*ROOT_CAUSE*`, `*INVESTIGATION*`, `*ANALYSIS*`, `*CRASH*`, `*CORRUPTION*`, `*SEGV*`, `*SEGFAULT*`, `*BUG*`, `*FAILURE*`, `FALSE_POSITIVE*`, `L1D_*`.
  - design: `BOX_THEORY*`, `BOX3_REFACTORING*`, `CENTRAL_ROUTER*`, `REGION_ID_DESIGN*`, `REFACTOR*`, `SUPERSLAB_BOX*`, `PHASE12_*DESIGN*`, anything with `DESIGN`, `ARCHITECTURE`, `IMPLEMENTATION_GUIDE`, `QUICK_START`, `ROADMAP`, `PLAN`.
  - benchmarks/perf: contains `BENCH`, `PERF`, `PERFORMANCE`, `LARSON`, `MID_LARGE`, `OPTIMIZATION_QUICK_SUMMARY`, `COMPREHENSIVE_BENCHMARK`, `BENCHMARK_SUMMARY`.
  - default: `docs/archive/`.

| file | target | rule |
| --- | --- | --- |
| 100K_SEGV_ROOT_CAUSE_FINAL.md | docs/analysis/ | analysis/bug |
| ACE_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| ACE_PHASE1_IMPLEMENTATION_TODO.md | docs/archive/ | default-archive |
| ACE_PHASE1_PROGRESS.md | docs/archive/ | default-archive |
| ACE_PHASE1_TEST_RESULTS.md | docs/archive/ | default-archive |
| ACE_POOL_ARCHITECTURE_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| AGENTS.md | (keep-root) | entrance |
| ANALYSIS_INDEX.md | docs/analysis/ | analysis/bug |
| ATOMIC_FREELIST_IMPLEMENTATION_STRATEGY.md | docs/archive/ | default-archive |
| ATOMIC_FREELIST_INDEX.md | docs/archive/ | default-archive |
| ATOMIC_FREELIST_QUICK_START.md | docs/design/ | design/general |
| ATOMIC_FREELIST_SITE_BY_SITE_GUIDE.md | docs/archive/ | default-archive |
| ATOMIC_FREELIST_SUMMARY.md | docs/archive/ | default-archive |
| BENCHMARK_SUMMARY_20251122.md | docs/benchmarks/ | bench/perf |
| BENCH_FIXED_SIZE_WORKSET64_CRASH_REPORT.md | docs/analysis/ | analysis/bug |
| BITMAP_FIX_FAILURE_ANALYSIS.md | docs/analysis/ | analysis/bug |
| BOTTLENECK_ANALYSIS_REPORT_20251114.md | docs/analysis/ | analysis/bug |
| BOX3_REFACTORING.md | docs/design/ | design/architecture |
| BOX_THEORY_ARCHITECTURE_REPORT.md | docs/design/ | design/architecture |
| BOX_THEORY_EXECUTIVE_SUMMARY.md | docs/design/ | design/architecture |
| BOX_THEORY_VERIFICATION_REPORT.md | docs/design/ | design/architecture |
| BOX_THEORY_VERIFICATION_SUMMARY.md | docs/design/ | design/architecture |
| BRANCH_OPTIMIZATION_QUICK_START.md | docs/design/ | design/general |
| BRANCH_PREDICTION_OPTIMIZATION_REPORT.md | docs/archive/ | default-archive |
| BUG_FLOW_DIAGRAM.md | docs/analysis/ | analysis/bug |
| C2_CORRUPTION_ROOT_CAUSE_FINAL.md | docs/analysis/ | analysis/bug |
| C6_TLS_SLL_HEAD_CORRUPTION_ROOT_CAUSE.md | docs/analysis/ | analysis/bug |
| C7_TLS_SLL_CORRUPTION_ANALYSIS.md | docs/analysis/ | analysis/bug |
| C7_TLS_SLL_CORRUPTION_FIX_REPORT.md | docs/analysis/ | analysis/bug |
| CENTRAL_ROUTER_BOX_DESIGN.md | docs/design/ | design/architecture |
| CLAUDE.md | docs/archive/ | default-archive |
| CLEANUP_SUMMARY_2025_11_01.md | docs/status/ | cleanup/status |
| COMPREHENSIVE_BENCHMARK_REPORT_20251122.md | docs/benchmarks/ | bench/perf |
| CRITICAL_BUG_REPORT.md | docs/analysis/ | analysis/bug |
| CURRENT_TASK.md | docs/archive/ | default-archive |
| DEBUG_100PCT_STABILITY.md | docs/analysis/ | analysis/bug |
| DEBUG_LOGGING_POLICY.md | docs/analysis/ | analysis/bug |
| DESIGN_FLAWS_ANALYSIS.md | docs/analysis/ | analysis/bug |
| DESIGN_FLAWS_SUMMARY.md | docs/design/ | design/general |
| DOCS_INDEX.md | (keep-root) | entrance |
| ENV_VARS.md | docs/specs/ | specs/env |
| ENV_VARS_COMPLETE.md | docs/specs/ | specs/env |
| FALSE_POSITIVE_REPORT.md | docs/analysis/ | analysis/bug |
| FALSE_POSITIVE_SEGV_FIX.md | docs/analysis/ | analysis/bug |
| FAST_CAP_0_SEGV_ROOT_CAUSE_ANALYSIS.md | docs/analysis/ | analysis/bug |
| FEATURE_AUDIT_REMOVE_LIST.md | docs/archive/ | default-archive |
| FINAL_ANALYSIS_C2_CORRUPTION.md | docs/analysis/ | analysis/bug |
| FIX_IMPLEMENTATION_GUIDE.md | docs/design/ | design/general |
| FOLDER_REORGANIZATION_2025_11_01.md | docs/archive/ | default-archive |
| FREELIST_CORRUPTION_ROOT_CAUSE.md | docs/analysis/ | analysis/bug |
| FREE_INC_SUMMARY.md | docs/archive/ | default-archive |
| FREE_PATH_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| FREE_PATH_ULTRATHINK_ANALYSIS.md | docs/analysis/ | analysis/bug |
| FREE_TO_SS_INVESTIGATION_INDEX.md | docs/analysis/ | analysis/bug |
| FREE_TO_SS_SEGV_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| FREE_TO_SS_TECHNICAL_DEEPDIVE.md | docs/archive/ | default-archive |
| HAKO_MIR_FFI_SPEC.md | docs/specs/ | specs/env |
| HISTORY.md | (keep-root) | entrance |
| HOTPATH_PERFORMANCE_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| INVESTIGATION_RESULTS.md | docs/analysis/ | analysis/bug |
| INVESTIGATION_SUMMARY.md | docs/analysis/ | analysis/bug |
| L1D_ANALYSIS_INDEX.md | docs/analysis/ | analysis/bug |
| L1D_CACHE_MISS_ANALYSIS_REPORT.md | docs/analysis/ | analysis/bug |
| L1D_CACHE_MISS_EXECUTIVE_SUMMARY.md | docs/analysis/ | analysis/bug |
| L1D_CACHE_MISS_HOTSPOT_DIAGRAM.md | docs/analysis/ | analysis/bug |
| L1D_OPTIMIZATION_QUICK_START_GUIDE.md | docs/analysis/ | analysis/bug |
| LARGE_FILES_ANALYSIS.md | docs/analysis/ | analysis/bug |
| LARGE_FILES_QUICK_REFERENCE.md | docs/archive/ | default-archive |
| LARGE_FILES_REFACTORING_PLAN.md | docs/design/ | design/general |
| LARSON_CATASTROPHIC_SLOWDOWN_ROOT_CAUSE.md | docs/analysis/ | analysis/bug |
| LARSON_CRASH_ROOT_CAUSE_REPORT.md | docs/analysis/ | analysis/bug |
| LARSON_DIAGNOSTIC_PATCH.md | docs/benchmarks/ | bench/perf |
| LARSON_GUIDE.md | docs/benchmarks/ | bench/perf |
| LARSON_INVESTIGATION_SUMMARY.md | docs/analysis/ | analysis/bug |
| LARSON_OOM_ROOT_CAUSE_ANALYSIS.md | docs/analysis/ | analysis/bug |
| LARSON_PERFORMANCE_ANALYSIS_2025_11_05.md | docs/analysis/ | analysis/bug |
| LARSON_QUICK_REF.md | docs/benchmarks/ | bench/perf |
| LARSON_SLOWDOWN_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| LRU_CACHE_MMAP_ROOT_CAUSE_ANALYSIS.md | docs/analysis/ | analysis/bug |
| MALLOC_FALLBACK_REMOVAL_REPORT.md | docs/archive/ | default-archive |
| MID_LARGE_FINAL_AB_REPORT.md | docs/benchmarks/ | bench/perf |
| MID_LARGE_LOCK_CONTENTION_ANALYSIS.md | docs/analysis/ | analysis/bug |
| MID_LARGE_MINCORE_AB_TESTING_SUMMARY.md | docs/benchmarks/ | bench/perf |
| MID_LARGE_MINCORE_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| MID_LARGE_P0_FIX_REPORT_20251114.md | docs/benchmarks/ | bench/perf |
| MID_LARGE_P0_PHASE_REPORT.md | docs/benchmarks/ | bench/perf |
| MID_MT_COMPLETION_REPORT.md | docs/status/ | phase/status |
| MIMALLOC_ANALYSIS_REPORT.md | docs/analysis/ | analysis/bug |
| MIMALLOC_IMPLEMENTATION_ROADMAP.md | docs/design/ | design/general |
| MIMALLOC_KEY_FINDINGS.md | docs/archive/ | default-archive |
| OPTIMIZATION_QUICK_SUMMARY.md | docs/benchmarks/ | bench/perf |
| OPTIMIZATION_REPORT_2025_11_12.md | docs/archive/ | default-archive |
| P0_BUG_STATUS.md | docs/status/ | phase/status |
| P0_DIRECT_FC_ANALYSIS.md | docs/status/ | phase/status |
| P0_DIRECT_FC_SUMMARY.md | docs/status/ | phase/status |
| P0_INVESTIGATION_FINAL.md | docs/status/ | phase/status |
| P0_ROOT_CAUSE_FOUND.md | docs/status/ | phase/status |
| P0_SEGV_ANALYSIS.md | docs/status/ | phase/status |
| PAGE_BOUNDARY_SEGV_FIX.md | docs/analysis/ | analysis/bug |
| PERFORMANCE_DROP_INVESTIGATION_2025_11_21.md | docs/analysis/ | analysis/bug |
| PERFORMANCE_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| PERFORMANCE_REGRESSION_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| PERF_ANALYSIS_2025_11_05.md | docs/analysis/ | analysis/bug |
| PERF_BASELINE_FRONT_DIRECT.md | docs/benchmarks/ | bench/perf |
| PHASE11_SUPERSLAB_PREWARM_IMPLEMENTATION_REPORT.md | docs/status/ | phase/status |
| PHASE12_SHARED_SUPERSLAB_POOL_DESIGN.md | docs/status/ | phase/status |
| PHASE12_SP_SLOT_BOX_IMPLEMENTATION_REPORT.md | docs/status/ | phase/status |
| PHASE15_BUG_ANALYSIS.md | docs/status/ | phase/status |
| PHASE15_BUG_ROOT_CAUSE_FINAL.md | docs/status/ | phase/status |
| PHASE15_REGISTRY_LOOKUP_INVESTIGATION.md | docs/status/ | phase/status |
| PHASE15_WRAPPER_DOMAIN_CHECK_FIX.md | docs/status/ | phase/status |
| PHASE19_AB_TEST_RESULTS.md | docs/status/ | phase/status |
| PHASE19_FRONTEND_METRICS_FINDINGS.md | docs/status/ | phase/status |
| PHASE1_EXECUTIVE_SUMMARY.md | docs/status/ | phase/status |
| PHASE1_REFILL_INVESTIGATION.md | docs/status/ | phase/status |
| PHASE23_CAPACITY_OPTIMIZATION_RESULTS.md | docs/status/ | phase/status |
| PHASE2A_IMPLEMENTATION_REPORT.md | docs/status/ | phase/status |
| PHASE2A_SUPERSLAB_DYNAMIC_EXPANSION.md | docs/status/ | phase/status |
| PHASE2B_IMPLEMENTATION_REPORT.md | docs/status/ | phase/status |
| PHASE2B_QUICKSTART.md | docs/status/ | phase/status |
| PHASE2B_TLS_ADAPTIVE_SIZING.md | docs/status/ | phase/status |
| PHASE2C_BIGCACHE_L25_DYNAMIC.md | docs/status/ | phase/status |
| PHASE2C_IMPLEMENTATION_REPORT.md | docs/status/ | phase/status |
| PHASE6_3_FIX_SUMMARY.md | docs/status/ | phase/status |
| PHASE6_3_REGRESSION_ULTRATHINK.md | docs/status/ | phase/status |
| PHASE6_EVALUATION.md | docs/status/ | phase/status |
| PHASE6_INTEGRATION_STATUS.md | docs/status/ | phase/status |
| PHASE6_RESULTS.md | docs/status/ | phase/status |
| PHASE7_4T_STABILITY_VERIFICATION.md | docs/status/ | phase/status |
| PHASE7_ACTION_PLAN.md | docs/status/ | phase/status |
| PHASE7_BENCHMARK_PLAN.md | docs/status/ | phase/status |
| PHASE7_BUG3_FIX_REPORT.md | docs/status/ | phase/status |
| PHASE7_BUG_FIX_REPORT.md | docs/status/ | phase/status |
| PHASE7_COMPREHENSIVE_BENCHMARK_RESULTS.md | docs/status/ | phase/status |
| PHASE7_CRITICAL_FINDINGS_SUMMARY.md | docs/status/ | phase/status |
| PHASE7_DEBUG_COMMANDS.md | docs/status/ | phase/status |
| PHASE7_DESIGN_REVIEW.md | docs/status/ | phase/status |
| PHASE7_FINAL_BENCHMARK_RESULTS.md | docs/status/ | phase/status |
| PHASE7_PERFORMANCE_INVESTIGATION_REPORT.md | docs/status/ | phase/status |
| PHASE7_QUICK_BENCHMARK_RESULTS.md | docs/status/ | phase/status |
| PHASE7_SUMMARY.md | docs/status/ | phase/status |
| PHASE7_SYSCALL_BOTTLENECK_ANALYSIS.md | docs/status/ | phase/status |
| PHASE7_TASK3_RESULTS.md | docs/status/ | phase/status |
| PHASE9_LRU_ARCHITECTURE_ISSUE.md | docs/status/ | phase/status |
| PHASE_B_COMPLETION_REPORT.md | docs/status/ | phase/status |
| PHASE_E3-1_INVESTIGATION_REPORT.md | docs/status/ | phase/status |
| PHASE_E3-1_SUMMARY.md | docs/status/ | phase/status |
| PHASE_E3-2_IMPLEMENTATION.md | docs/status/ | phase/status |
| PHASE_E3_SEGV_ROOT_CAUSE_REPORT.md | docs/status/ | phase/status |
| POINTER_CONVERSION_BUG_ANALYSIS.md | docs/analysis/ | analysis/bug |
| POINTER_FIX_SUMMARY.md | docs/archive/ | default-archive |
| POOL_FULL_FIX_EVALUATION.md | docs/archive/ | default-archive |
| POOL_HOT_PATH_BOTTLENECK.md | docs/archive/ | default-archive |
| POOL_IMPLEMENTATION_CHECKLIST.md | docs/archive/ | default-archive |
| POOL_TLS_INVESTIGATION_FINAL.md | docs/analysis/ | analysis/bug |
| POOL_TLS_LEARNING_DESIGN.md | docs/design/ | design/general |
| POOL_TLS_PHASE1_5A_FIX.md | docs/archive/ | default-archive |
| POOL_TLS_QUICKSTART.md | docs/archive/ | default-archive |
| POOL_TLS_SEGV_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| POOL_TLS_SEGV_ROOT_CAUSE.md | docs/analysis/ | analysis/bug |
| QUICK_REFERENCE.md | docs/archive/ | default-archive |
| RANDOM_MIXED_BOTTLENECK_ANALYSIS.md | docs/analysis/ | analysis/bug |
| RANDOM_MIXED_SUMMARY.md | docs/archive/ | default-archive |
| README.md | (keep-root) | entrance |
| README_CLEAN.md | docs/archive/ | default-archive |
| REFACTORING_BOX_ANALYSIS.md | docs/analysis/ | analysis/bug |
| REFACTORING_PLAN_TINY_ALLOC.md | docs/design/ | design/architecture |
| REFACTOR_EXECUTIVE_SUMMARY.md | docs/design/ | design/architecture |
| REFACTOR_IMPLEMENTATION_GUIDE.md | docs/design/ | design/architecture |
| REFACTOR_INTEGRATION_PLAN.md | docs/design/ | design/architecture |
| REFACTOR_PLAN.md | docs/design/ | design/architecture |
| REFACTOR_PROGRESS.md | docs/design/ | design/architecture |
| REFACTOR_QUICK_START.md | docs/design/ | design/architecture |
| REFACTOR_STEP1_IMPLEMENTATION.md | docs/design/ | design/architecture |
| REFACTOR_SUMMARY.md | docs/design/ | design/architecture |
| REGION_ID_DESIGN.md | docs/design/ | design/architecture |
| RELEASE_DEBUG_OVERHEAD_REPORT.md | docs/analysis/ | analysis/bug |
| REMAINING_BUGS_ANALYSIS.md | docs/analysis/ | analysis/bug |
| REMOVE_MALLOC_FALLBACK_TASK.md | docs/archive/ | default-archive |
| RING_CACHE_ACTIVATION_GUIDE.md | docs/archive/ | default-archive |
| SANITIZER_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| SANITIZER_PHASE1_RESULTS.md | docs/archive/ | default-archive |
| SEGFAULT_INVESTIGATION_REPORT.md | docs/analysis/ | analysis/bug |
| SEGFAULT_ROOT_CAUSE_FINAL.md | docs/analysis/ | analysis/bug |
| SEGV_FIX_REPORT.md | docs/analysis/ | analysis/bug |
| SEGV_FIX_SUMMARY.md | docs/analysis/ | analysis/bug |
| SEGV_ROOT_CAUSE_COMPLETE.md | docs/analysis/ | analysis/bug |
| SFC_ROOT_CAUSE_ANALYSIS.md | docs/analysis/ | analysis/bug |
| SLAB_INDEX_FOR_INVESTIGATION.md | docs/analysis/ | analysis/bug |
| SLL_REFILL_BOTTLENECK_ANALYSIS.md | docs/analysis/ | analysis/bug |
| SOURCE_MAP.md | docs/status/ | cleanup/status |
| SPLIT_DETAILS.md | docs/archive/ | default-archive |
| STABILITY_POLICY.md | docs/archive/ | default-archive |
| STRUCTURAL_ANALYSIS.md | docs/analysis/ | analysis/bug |
| SUPERSLAB_BOX_REFACTORING_COMPLETE.md | docs/design/ | design/architecture |
| SUPERSLAB_REFILL_BREAKDOWN.md | docs/archive/ | default-archive |
| TASK_FOR_OTHER_AI.md | docs/status/ | phase/status |
| TESTABILITY_ANALYSIS.md | docs/analysis/ | analysis/bug |
| TINY_256B_1KB_SEGV_FIX_REPORT.md | docs/analysis/ | analysis/bug |
| TINY_DRAIN_INTERVAL_AB_REPORT.md | docs/archive/ | default-archive |
| TINY_HEAP_V2_TASK_SPEC.md | docs/archive/ | default-archive |
| TINY_LEARNING_LAYER.md | docs/archive/ | default-archive |
| TINY_PERF_PROFILE_EXTENDED.md | docs/benchmarks/ | bench/perf |
| TINY_PERF_PROFILE_STEP1.md | docs/benchmarks/ | bench/perf |
| ULTRATHINK_ANALYSIS.md | docs/analysis/ | analysis/bug |
| ULTRATHINK_ANALYSIS_2025_11_07.md | docs/analysis/ | analysis/bug |
| ULTRATHINK_SUMMARY.md | docs/archive/ | default-archive |
| debug_analysis_final_$(date +%Y%m%d_%H%M%S).md | docs/archive/ | default-archive |
| debug_logs_$(date +%Y%m%d_%H%M%S).md | docs/archive/ | default-archive |
| debug_logs_round2_$(date +%Y%m%d_%H%M%S).md | docs/archive/ | default-archive |