tomoaki/hakorune
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
5597b78f0de343628f9942fbca0e413005e08aa7
hakorune/docs/private/roadmap/phases/phase-20-variant-box/INDEX.md

12 KiB
Raw Blame History

Phase 20 VariantBox - Complete Documentation Index

Last Updated: 2025-10-08 Status: Ready for Implementation (after Phase 15.7)

🎯 Quick Navigation

START HERE

For Implementers

For Designers/Reviewers

📚 Document Categories

1. Project Planning & Execution (New: 2025-10-08)

Primary Documents:

  1. ENUM_MATCH_PROJECT_PLAN.md (41KB)

    • Complete project plan for Choice A'' (macro-only approach)
    • Daily task breakdown (Days 1-17)
    • Risk analysis with mitigation strategies
    • Success criteria and acceptance tests
    • Rollback plans (Option 1: @enum-only, Option 2: Full rollback)
    • Quality gates and go/no-go decisions
    • 📖 Use this: As your main execution guide

  2. ENUM_MATCH_QUICK_START.md (5.6KB)

    • 2-page summary of project plan
    • 3-week schedule at a glance
    • Critical risks (top 3)
    • Quick commands and daily checklist
    • 📖 Use this: For daily reference

  3. ENUM_MATCH_TIMELINE.md (13KB)

    • Gantt-style timeline visualization
    • Critical path analysis
    • Resource allocation by week
    • Time budget breakdown
    • Monte Carlo simulation results (14-15 day median)
    • Daily success indicators
    • 📖 Use this: For progress tracking and stakeholder updates

  4. DAILY_LOG_TEMPLATE.md (12KB)

    • Copy-paste templates for each day
    • Task checklists, issue tracking, test results
    • Quality gate decision templates
    • Weekly summary templates
    • 📖 Use this: Copy relevant section each day, fill in as you work

2. Technical Design (Original: 2025-10-08)

Architecture Documents:

  1. DESIGN.md (11KB)

    • VariantBox core design
    • Philosophical alignment (Everything-is-Box, MIR16 維持)
    • @enum/@match desugaring examples
    • Comparison with alternatives (MapBox, Box inheritance, MIR extension)
    • Future extensions (SymbolBox, static exhaustiveness, GADT)
    • 📖 Use this: For understanding design decisions

  2. @enum-macro-implementation-spec.md (41KB)

    • Complete @enum macro specification
    • Parser changes, AST nodes, macro expansion
    • Code generation details
    • Test patterns and edge cases
    • 📖 Use this: When implementing @enum (Days 1-5)

  3. @match-macro-implementation-spec.md (37KB)

    • Complete @match macro specification
    • Pattern matching semantics
    • Desugaring to if-else chain
    • Exhaustiveness checking (runtime)
    • 📖 Use this: When implementing @match (Days 6-11)

3. Result Box Specific (Original: 2025-10-08)

Result<T,E> Design Series:

  1. RESULT_BOX_COMPLETE_DESIGN.md (16KB)

    • Complete Result<T,E> design
    • Comparison: Manual ResultBox vs @enum Result
    • Migration roadmap
    • 📖 Use this: For Result-specific implementation (Day 12)

  2. RESULT_BOX_MIGRATION_PLAN.md (10KB)

    • Step-by-step migration guide
    • Backward compatibility strategy
    • Risk mitigation for existing code
    • 📖 Use this: For Day 12 (Option/Result v2)

  3. RESULT_BOX_SUMMARY.md (5.2KB)

    • 1-minute summary
    • Quick reference for Result usage
    • 📖 Use this: For quick lookups

  4. result_box_v2_reference.hako (467 lines)

    • Reference implementation with @enum
    • Copy-paste starting point
    • 📖 Use this: As implementation template (Day 12)

4. Quick References

Quick Start Guides:

  1. @enum-quick-start.md (6.2KB)

    • @enum syntax cheatsheet
    • Common patterns
    • Quick examples
    • 📖 Use this: During @enum implementation (Days 1-5)

  2. @match-quick-start.md (9.9KB)

    • @match syntax cheatsheet
    • Pattern matching examples
    • Common pitfalls
    • 📖 Use this: During @match implementation (Days 6-11)

  3. README-match-implementation.md (8.2KB)

    • @match implementation FAQ
    • Troubleshooting guide
    • 📖 Use this: When debugging @match issues

🚀 Getting Started Checklist

Before Day 1

Day 1 Morning

Each Day

  • Morning: Review day's section in ENUM_MATCH_PROJECT_PLAN.md (5 min)
  • Work: Follow daily task list
  • Track: Fill in daily log template as you work
  • EOD: Update CURRENT_TASK.md with summary
  • EOD: Review tomorrow's tasks

At Quality Gates (Days 5, 11, 14)

  • Run: All tests (unit + smoke)
  • Measure: Performance (benchmark)
  • Decide: Go / Caution / No-Go (use template in DAILY_LOG_TEMPLATE.md)
  • Update: CURRENT_TASK.md with gate decision
  • If No-Go: Consult rollback plans in ENUM_MATCH_PROJECT_PLAN.md Section 4

📖 Reading Order Recommendations

First-Time Reader (30 min)

  1. README.md (5 min) - Overview
  2. ENUM_MATCH_QUICK_START.md (10 min) - Summary
  3. DESIGN.md (15 min) - Design rationale

Implementer (1-2 hours)

  1. ENUM_MATCH_QUICK_START.md (10 min)
  2. ENUM_MATCH_PROJECT_PLAN.md Section 1 (Day 1-17 tasks) (30 min)
  3. ENUM_MATCH_PROJECT_PLAN.md Section 2 (Risk Analysis) (15 min)
  4. ENUM_MATCH_TIMELINE.md (10 min) - Visualization
  5. @enum-macro-implementation-spec.md (20 min) - Technical details

Reviewer/Stakeholder (15 min)

  1. ENUM_MATCH_QUICK_START.md (5 min)
  2. ENUM_MATCH_TIMELINE.md (5 min) - Timeline
  3. ENUM_MATCH_PROJECT_PLAN.md Section 3 (Success Criteria) (5 min)

🔍 Find Information By Topic

Timeline & Schedule

Risks & Mitigation

Success Criteria & Testing

Rollback Plans

Design Details

Implementation Guidance

📊 Document Statistics

Total Documents: 14 Total Size: ~280 KB Total Reading Time: ~2-3 hours (full coverage) Minimum Reading Time: 30 min (quick start)

By Category:

  • Planning & Execution: 4 docs (~71 KB)
  • Technical Design: 3 docs (~89 KB)
  • Result Box Specific: 4 docs (~56 KB)
  • Quick References: 3 docs (~24 KB)

🎯 Key Success Factors

Use the Right Document at the Right Time

  • Planning phase → ENUM_MATCH_PROJECT_PLAN.md
  • Daily work → ENUM_MATCH_QUICK_START.md + DAILY_LOG_TEMPLATE.md
  • Implementation details → @enum/@match implementation specs
  • Troubleshooting → README-match-implementation.md
  • Progress tracking → ENUM_MATCH_TIMELINE.md

Don't Skip Quality Gates

  • Gate 1 (Day 5): 10/10 tests PASS or reassess
  • Gate 2 (Day 11): 15/15 tests PASS or rollback to @enum-only
  • Gate 3 (Day 14): ALL smoke tests PASS or full rollback

Track Progress Daily

  • Use DAILY_LOG_TEMPLATE.md every day
  • Update CURRENT_TASK.md at EOD
  • Escalate blockers early (don't wait for gates)

🔗 External References

Related Phases

  • Phase 15.7: Selfhost completion (prerequisite)
  • Phase 16: Macro Revolution (@derive implementation)
  • Phase 20.0-20.5: Macro Full Features (foundation)
  • Phase 25: Type System (static exhaustiveness checks)

Implementation References

  • Existing macros: apps/macros/loop_normalize_macro.nyash (393 lines)
  • Pattern matching: src/macro/pattern.rs (252 lines)
  • Macro engine: src/macro/engine.rs
  • Option/Result: apps/lib/boxes/option.hako, apps/lib/boxes/result.hako

Design Background

  • ChatGPT Pro proposal (2025-10-08)
  • Ultrathink 4-task analysis (consistency, alternatives, risks, impact)
  • Phase 20 design discussions

🚨 Important Notes

Prerequisites

  • ✅ Phase 15.7 complete (selfhost achieved)
  • ✅ StringBox/ArrayBox/MapBox stable
  • ✅ Macro system basic functionality (Phase 16 interim OK)

Assumptions

  • MIR16 instruction set remains frozen
  • Everything-is-Box principle maintained
  • Macro-only approach (no runtime/MIR changes)

Limitations (Documented)

  • Runtime exhaustiveness checking only (static checking in Phase 25)
  • StringBox tags (SymbolBox optimization in Phase 25)
  • Pattern matching limited to single-level (no nested patterns in MVP)

📝 Change Log

2025-10-08:

  • ✅ Created complete project plan (ENUM_MATCH_PROJECT_PLAN.md)
  • ✅ Created quick start guide (ENUM_MATCH_QUICK_START.md)
  • ✅ Created visual timeline (ENUM_MATCH_TIMELINE.md)
  • ✅ Created daily log template (DAILY_LOG_TEMPLATE.md)
  • ✅ Updated README.md with plan references
  • ✅ Created this index document

Previous (Before 2025-10-08):

  • DESIGN.md: Complete VariantBox design
  • Result Box design series (4 documents)
  • @enum/@match implementation specs
  • Quick references and guides

Status: ✅ READY FOR IMPLEMENTATION Approval: Pending Phase 15.7 completion Next Action: Wait for Phase 15.7, then begin Day 1 preparation

Questions? See README.md or consult ENUM_MATCH_PROJECT_PLAN.md Section 8 (Communication Plan)