# 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
```