docs(02-02): complete doctor overlay validation plan

- SUMMARY.md with task commit, decisions, metrics
- STATE.md: Phase 2 complete (2/2 plans), ready for Phase 3

.planning/STATE.md

@@ -9,16 +9,16 @@
 ## Current Position
 
 **Phase:** 2 — Config Overlays
-**Plan:** 1 of 2 complete (02-01 done)
+**Plan:** 2 of 2 complete (02-02 done)
-**Status:** in_progress
+**Status:** complete
-**Progress:** █████░░░░░ 1/3 phases complete (02-01 of Phase 2 done)
+**Progress:** ███████░░░ 2/3 phases complete
 
 ## Phase Status
 
 | Phase | Status | Plans |
 |-------|--------|-------|
 | 1 — Daemon Decomposition | **complete** | 3/3 plans complete |
-| 2 — Config Overlays | **in_progress** | 1/2 plans complete |
+| 2 — Config Overlays | **complete** | 2/2 plans complete |
 | 3 — Live Ops Dashboard | not_started | — |
 
 ## Performance Metrics
@@ -36,6 +36,8 @@
 | Plan 01-03 tasks | 2/2 |
 | Plan 02-01 duration | 3 min |
 | Plan 02-01 tasks | 2/2 |
+| Plan 02-02 duration | ~1 min |
+| Plan 02-02 tasks | 1/1 |
 
 ## Accumulated Context
 
@@ -56,6 +58,8 @@
 - Overlay merge before env expansion and Zod validation — overlays don't need required fields
 - Arrays in overlays replace (not concat) — explicit override semantics
 - resolveOverlayPath returns path without checking existence — callers decide error handling
+- Doctor overlay check placed after checkConfigExists, before checkConfigParses — natural validation order
+- Skip status when FLYNN_ENV not set — no noise for users without overlays
 
 ### Technical Notes
 - daemon/index.ts now 140 lines — thin composition root: imports → init calls → wire → return DaemonContext
@@ -66,6 +70,7 @@
 - Config loader at src/config/loader.ts, schema at src/config/schema.ts (409 lines)
 - deepMerge + overlay-aware loadConfig in loader.ts; resolveOverlayPath + overlay-aware loadConfigSafe in cli/shared.ts
 - FLYNN_ENV maps to {configDir}/{env}.yaml sibling file; no env = no overlay (backward compatible)
+- checkOverlayExists in doctor.ts: skip (no FLYNN_ENV) / pass (file found) / fail (file missing)
 
 ### TODOs
 _(none)_
@@ -75,9 +80,9 @@ _(none)_
 
 ## Session Continuity
 
-**Last session:** Plan 02-01 (core overlay merge) completed
+**Last session:** Plan 02-02 (doctor overlay validation) completed
-**Stopped at:** Completed 02-01-PLAN.md
+**Stopped at:** Completed 02-02-PLAN.md — Phase 2 complete
-**Next action:** Execute Plan 02-02 (doctor overlay validation check)
+**Next action:** Plan Phase 3 (Live Ops Dashboard)
 
 ---
 *State initialized: 2026-02-09*

.planning/phases/02-config-overlays/02-02-SUMMARY.md

@@ -0,0 +1,84 @@
+---
+phase: 02-config-overlays
+plan: 02
+subsystem: config
+tags: [cli, doctor, overlay, FLYNN_ENV, diagnostics]
+
+# Dependency graph
+requires:
+  - phase: 02-config-overlays
+    provides: resolveOverlayPath from cli/shared.ts for FLYNN_ENV resolution
+provides:
+  - checkOverlayExists doctor check for overlay file validation
+affects: [03-live-ops-dashboard]
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns: [doctor-check-pattern, skip-pass-fail-tristate]
+
+key-files:
+  created: []
+  modified:
+    - src/cli/doctor.ts
+
+key-decisions:
+  - "Overlay check placed after checkConfigExists, before checkConfigParses — natural validation order"
+  - "Skip status when FLYNN_ENV not set — no noise for users without overlays"
+
+patterns-established:
+  - "Doctor check tristate: skip (not applicable) / pass (found) / fail (missing)"
+
+# Metrics
+duration: 1min
+completed: 2026-02-10
+---
+
+# Phase 2 Plan 2: Doctor Overlay Validation Summary
+
+**checkOverlayExists doctor check validates FLYNN_ENV overlay file exists with skip/pass/fail tristate reporting**
+
+## Performance
+
+- **Duration:** ~1 min (52s)
+- **Started:** 2026-02-10T04:59:35Z
+- **Completed:** 2026-02-10T05:00:27Z
+- **Tasks:** 1
+- **Files modified:** 1
+
+## Accomplishments
+- Added checkOverlayExists to flynn doctor checks array
+- When FLYNN_ENV is set, reports pass (file found) or fail (file missing with path detail)
+- When FLYNN_ENV is not set, check is skipped silently
+- Positioned after checkConfigExists, before checkConfigParses for natural validation flow
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add checkOverlayExists to doctor.ts** - `6bd3721` (feat)
+
+## Files Created/Modified
+- `src/cli/doctor.ts` - Added checkOverlayExists check function and inserted into allChecks array after checkConfigExists
+
+## Decisions Made
+- Placed overlay check between checkConfigExists and checkConfigParses — validates files exist before attempting to parse/validate them
+- Used 'skip' status when FLYNN_ENV is not set to avoid noise for users not using overlays
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Phase 2 (Config Overlays) complete — both overlay merge and doctor validation shipped
+- Ready for Phase 3 (Live Ops Dashboard)
+
+---
+*Phase: 02-config-overlays*
+*Completed: 2026-02-10*