uto_manager/development_status.md

UTO Manager — Development Status

Last updated: 2026-08-09

---

Current Branch

main (feature/phase-3-templates-validation-export merged)

Overall Progress

Phase	Title	Status
1	Domain Foundation	✅ Complete
2	Canvas Engine & Persistence	✅ Complete
3	Template Library & Import/Export	✅ Complete
4	Reporting & Analytics	🔲 Not started
5	Multi-user / Sync	🔲 Not started

---

Phase 1 — Domain Foundation ✅

Completed items:

• Echelon entity with doctrinal hierarchy validation (isValidParent, isValidChild)
• DoctrinalBranch entity with display names
• AuthorizedRank entity with pay grade, category flags, meetsMinimum, gradeLevel
• DutyMos value object with MOS dictionary validation and unvalidated constructor
• UnitNode entity with copyWith, isRoot, isValidParentNode
• PositionSlot entity with isVacant, isFilled, isKeyLeader
• PersonnelRecord entity with ReadinessState, copyWith, isUnassigned
• UnitRepository abstract interface
• PersonnelRepository abstract interface
• domain_entities.dart barrel export
• Full unit test coverage for all domain entities and value objects

Test count (Phase 1): 60 tests

---

Phase 2 — Canvas Engine & Persistence ✅

Completed items:

Domain Services

• UnitTreeService — buildTree, getSubtree, getAncestors, validateReparent, validateAssignment, calculateFillRate, getVacantKeyLeaderSlots, getMosMismatches
• AssignmentService — assign, unassign, aggregateReadiness with ReadinessColor

Infrastructure — Database

• Drift schema: Units, PositionSlots, Personnel, Templates tables
• AppDatabase with forTesting(NativeDatabase.memory()) constructor
• UnitDao — full CRUD + watch streams
• PersonnelDao — full CRUD + assignToSlot / unassignFromSlot + watch streams
• PositionSlotDao — full CRUD + assignPersonnel / clearAssignment + watch streams
• TemplateDao — full CRUD + upsertTemplate
• build_runner code generation (.g.dart files)

Infrastructure — Repositories

• DriftUnitRepository — implements UnitRepository with domain↔Drift mapping
• DriftPersonnelRepository — implements PersonnelRepository with domain↔Drift mapping
• DriftPositionSlotRepository — concrete slot repository

Application — BLoC

• UnitTreeCubit / UnitTreeState (sealed) — tree loading, selection, reparent, subtree delete
• PersonnelCubit / PersonnelState (sealed) — roster loading, filter, assign/unassign
• TemplateCubit / TemplateState (sealed) — template save/load/delete

Presentation

• HomeScreen — three-pane adaptive layout (personnel | canvas | inspector)
• UtoCanvasWidget — InteractiveViewer pan/zoom org chart with drag-and-drop reparent
• UnitNodeCard — echelon-colored card with fill rate progress bar
• PositionSlotCard — DragTarget slot card with MOS badge and readiness color
• PersonnelListTile — Draggable soldier tile for assignment
• Status bar with live unit/slot fill counts

App Wiring

• main.dart — MultiBlocProvider wiring all cubits with production database

Test count (Phase 2): 77 new tests (137 total)

---

Phase 3 — Template Library & Import/Export ✅

Completed items:

Domain Services

• DoctrinalTemplates — Pure-Dart library of all five 2026 BCT templates:
  • mbct — Mobile Brigade Combat Team (3× Mobile Infantry Battalions, Cav Squadron, FA Battalion, MDEP, HKP, Engineer Battalion, Support Battalion)
  • sbct — Stryker Brigade Combat Team (3× Stryker Infantry Battalions, Cav Recon Squadron, FA Battalion, Engineer Battalion, Support Battalion)
  • abct — Armored Brigade Combat Team (2× Armor-Heavy CABs, 1× Infantry-Heavy CAB, Armored Cav Squadron, M109A7 FA Battalion, Engineer Battalion)
  • cabHeavy — Combat Aviation Brigade Heavy (Attack Bn AH-64E, Assault Bn UH-60M/CH-47F, Air Ambulance Co, Aviation Support Bn)
  • cabLight — Combat Aviation Brigade Light (Attack Recon Bn AH-64E+MQ-9A, Assault Bn, Medical Assault Bn, Aviation Support Bn)
• TemplateInstantiator — Converts UnitDefinition trees into concrete UnitNode + PositionSlot domain objects with injected ID generator
• MtoeValidationEngine — Pure-domain validation engine with 7 rules:
  • V001 MOS mismatch (warning)
  • V002 Rank mismatch (warning)
  • V003 Vacant key leader (critical)
  • V004 Missing combat medic 68W in platoon (advisory)
  • V005 Missing fire support specialist 13F in platoon (advisory)
  • V006 Structural hierarchy violation (critical)
  • V007 Manning below 70% (warning)

Infrastructure — Codecs

• UnitTreeCodec — JSON encode/decode for full unit tree snapshots (units + slots + personnel)
  • Schema version 1 with exportedAt timestamp
  • encode / decode (JSON string)
  • encodeToMap / decodeFromMap (Map)
  • Handles all optional fields (null parentUnitId, null assignedPersonnelId, qualifications list)

Application — BLoC

• TemplateCubit — Extended with:
  • instantiateDoctrinalTemplate(key) — instantiates any of the five BCT templates into the live database
  • saveSnapshot(name, bctType, units, slots) — saves current tree as a named template
  • exportToJson(units, slots) — encodes tree to JSON string for export
  • importFromJson(json, {replaceExisting}) — decodes and persists imported tree
• ValidationCubit / ValidationState (sealed) — wraps MtoeValidationEngine:
  • validate(units, slots, personnel) — runs all rules, emits ValidationComplete
  • clear() — resets to ValidationInitial
  • ValidationComplete exposes .critical, .warnings, .advisories, .findingsForUnit(id), .isClean

Domain Value Objects

• DutyMos — Extended format validation to accept 4-character aviation AOC codes (e.g., 153A = 3 digits + 1 letter) in addition to standard 3-character codes

App Wiring

• main.dart — Added ValidationCubit to MultiBlocProvider
• TemplateCubit — Now requires unitRepository and slotRepository parameters

Test count (Phase 3): 54 new tests (191 total)

---

Test Summary

File	Tests	Status
authorized_rank_test.dart	16	✅
echelon_test.dart	17	✅
personnel_record_test.dart	13	✅
unit_node_test.dart	15	✅
duty_mos_test.dart	32	✅
assignment_service_test.dart	16	✅
unit_tree_service_test.dart	27	✅
mtoe_validation_engine_test.dart	22	✅
template_instantiator_test.dart	18	✅
unit_tree_codec_test.dart	14	✅
widget_test.dart	1	✅
Total	191	✅ All pass

---

Known Limitations / Next Steps (Phase 4)

• No PDF/Excel export of readiness reports (Phase 4)
• No Protobuf binary export (Phase 4)
• No multi-user or sync capability (Phase 5)
• Canvas layout is vertical tree only; horizontal layout not yet implemented
• No undo/redo for assignment operations
• No search/filter on the canvas itself
• ValidationCubit findings not yet surfaced as visual node indicators on canvas (Phase 4 UI integration)
• MtoeValidationEngine runs synchronously; background Isolate offloading deferred to Phase 4
• Template instantiation does not yet persist to database in a single Drift transaction (uses sequential inserts)

---

Architecture Notes

lib/
├── domain/
│   ├── entities/          # Pure Dart domain models (no Flutter deps)
│   ├── value_objects/     # DutyMos (supports 3-char and 4-char AOC formats)
│   ├── repositories/      # Abstract interfaces
│   └── services/          # UnitTreeService, AssignmentService,
│                          # MtoeValidationEngine, TemplateInstantiator,
│                          # DoctrinalTemplates
├── infrastructure/
│   ├── codecs/            # UnitTreeCodec (JSON encode/decode)
│   ├── database/          # Drift schema, DAOs, generated code
│   └── repositories/      # Drift-backed implementations
├── application/
│   └── blocs/             # UnitTreeCubit, PersonnelCubit,
│                          # TemplateCubit, ValidationCubit
└── presentation/
    ├── screens/           # HomeScreen
    └── widgets/           # Canvas, cards, tiles