Ready2Blob/.planning/RETROSPECTIVE.md

# Project Retrospective

*A living document updated after each milestone. Lessons feed forward into future planning.*

## Milestone: v1.0 — MVP

**Shipped:** 2026-03-27
**Phases:** 4 | **Plans:** 18 | **Timeline:** 2 days

### What Was Built
- Backend Schema Registry as single source of truth driving form rendering, Zod validation, and config generation for 3 backends
- 4 pure generator functions (rclone.conf, Intune install/detection, RMM script) with 61 tests and strict PowerShell encoding/path requirements
- 4-step multi-step wizard (backend selection → config → deployment options → review/download) with full back-navigation
- Review and download layer: live preview, security gate, individual file downloads, ZIP bundle, clipboard copy

### What Worked
- **Inside-out build order** (foundation → generators → wizard UI → download layer): front-loaded high-risk correctness work (PowerShell encoding, SYSTEM-context paths, credential handling) before any UI existed — each phase was independently verifiable
- **Wave 0 TDD with `expect.fail` stubs**: defining the API contract in RED before implementation forced explicit interface design and caught integration issues upfront; named failure messages made debugging fast
- **BACKEND_REGISTRY as single source of truth**: zero field-name duplication between form rendering, Zod schemas, and config generation — no drift possible across phases
- **useReducer + Context API with no external state lib**: sufficient for a 4-step wizard, kept bundle lean

### What Was Inefficient
- **scriptTargets collected but never consumed**: `DeploymentStep` dispatches `scriptTargets` but `ReviewStep` ignores it — all output blocks render unconditionally. This was knowable at Phase 2 design time but deferred to v1.1 as tech debt
- **BACKENDS constant hardcoded in BackendSelectionStep**: adding to BACKEND_REGISTRY does not surface in UI — a maintainability gap that was an obvious fix but left unaddressed
- **ReviewStep missing Back button**: UX inconsistency with all other steps — a trivial add that was missed

### Patterns Established
- Wave 0 TDD pattern: stub all requirement behaviors RED before any implementation — use `expect.fail('not yet implemented')` not import errors
- Embed requirement IDs in test describe blocks (WIZD-01, BACK-02, etc.) for direct test-to-requirement traceability
- Generator functions self-contained: `buildRcloneConfContent` duplicated inline in rmm-script.ts to avoid circular dependency risk
- INITIAL_STATE defaults to both targets selected — users deselect rather than discover

### Key Lessons
1. **Define data flow end-to-end before implementing any step**: the `scriptTargets` disconnect would have been caught if the full data flow (DeploymentStep → state → ReviewStep) had been traced before Phase 4 started
2. **Registry-driven UI is strictly better than hardcoded lists**: the BACKEND_REGISTRY pattern proved its value — extending it for the UI selector should have been done at the same time
3. **Inside-out build order works well for correctness-heavy tools**: generator correctness (PowerShell encoding edge cases) was much easier to verify without UI noise

### Cost Observations
- Sessions: ~6 (4 execution phases + planning + verification)
- Notable: Pure frontend with no external API calls kept the scope tight — all phases parallelized within themselves

---

## Milestone: v1.2 — UI Polish & Clarity

**Shipped:** 2026-04-01
**Phases:** 5 (8–12) | **Plans:** 14 | **Stats:** 78 files, +9,908 / -287 lines

### What Was Built
- Full MD3 color token system in a single token file; all components use semantic utility classes (`bg-surface`, `text-on-primary`) instead of hardcoded Tailwind colors
- System/Light/Dark theme toggle persisted in localStorage with zero flash of unstyled content (DOM class toggle, not React Context)
- TextFieldMD3 with CSS-only floating label, MD3 button hierarchy constants, rebuilt StepIndicator with numbered circles + checkmarks + connectors
- App intro section, step descriptions on all 4 steps, remote name live config preview, contextual help/tooltip enrichment across all credential fields
- Mobile-responsive layout, `focus-visible` ring-3 indicators, step fade/slide transition with `prefers-reduced-motion` guard, auto-scroll to first validation error
- Dark mode visibility fixes: semantic tokens on select, h2 headings, DeploymentStep form controls, ReviewStep security checkbox

### What Worked
- **Bottom-up migration order** (tokens → primitives → content → polish → fixes): each phase stood on solid ground from the one below; no circular rework
- **CSS-only floating label** (`peer-[:not(:placeholder-shown)]`) with no JS state — simpler to reason about, trivially animatable, one fewer React state variable
- **DOM class toggle for dark mode** (not React Context): theme switch is instant and doesn't trigger a re-render cascade across 150+ components
- **`key={state.currentStep}` on step wrapper**: one-line way to force React remount and reset CSS animation to initial state — no animation JS state needed
- **TDD discipline held** on Phase 12 dark mode fixes: found and fixed selector issues before they became regressions

### What Was Inefficient
- **Phase 12 inserted as a gap fix**: dark mode regressions were discovered post-Phase 11 instead of being caught in Phase 11 validation — cost 1 extra phase
- **`aria-label` / `getByLabelText` selector ambiguity** recurred across Phases 9, 10, and 12 — the DEBT-01 pattern (`{ selector: 'input' }`) had to be applied three times in three different phases instead of being resolved once and documented
- **Traceability table in REQUIREMENTS.md not updated** as plans completed — table showed "Planned" for completed items, causing confusion at milestone close

### Patterns Established
- Two-layer CSS token pattern: `@theme var()` references + `@layer base :root/.dark` raw values — required for `.dark` cascade in Tailwind v4
- `vi.stubGlobal` for localStorage/matchMedia — Node v25 experimental WebStorage breaks standard Storage API in jsdom
- CSS-only reduced-motion guard via `@media (prefers-reduced-motion: reduce)` — no JS listener needed
- Tooltip hover: dual-state (`hoverTooltip` + `showTooltip`); click-unpin clears `hoverTooltip` to prevent sticky tooltip after dismiss
- `ring-inset` on ThemeToggle focus ring because `overflow-hidden` on container clips outset rings

### Key Lessons
1. **Validate dark mode in every phase, not as a separate cleanup phase**: each component migration should include a dark-mode check, not defer it
2. **When a test selector pattern is discovered, document it once and reference it** — the `{ selector: 'input' }` guard should have been in a testing conventions note from Phase 9
3. **Keep traceability tables current** during execution, not just at planning time

---

## Milestone: v1.3 — Backend Expansion

**Shipped:** 2026-04-16
**Phases:** 1 (13) | **Plans:** 4 | **Stats:** 28 files, +3,959 / -206 lines

### What Was Built
- BACKEND_REGISTRY expanded from 7 → 18 backends; `BackendType` derived from `keyof typeof BACKEND_REGISTRY` — no manual union to maintain
- `BACKEND_SCHEMAS` auto-generated from registry keys via `Object.fromEntries` — zero per-backend boilerplate
- `OAuthInstructions` collapsible component with backend-specific `rclone authorize` commands (TDD, 4 tests)
- `GdriveAuthToggle` dual-auth component (OAuth token vs service account) — CSS hidden pattern extended from SftpAuthToggle
- `BackendSelectionStep` with 3 category groups, instant search filtering across 4 fields, inline SVG icons
- `RemoteConfigStep` wired for all 18 backends via clean `renderBackendFields()` switch function; `backendLabel` derived from registry

### What Worked
- **`as const` registry with derived BackendType**: one touch-point when adding a backend (registry entry only); Zod schemas auto-generate, type union auto-narrows
- **Incremental plan structure** (registry → components → UI → wiring): each plan had exactly the right scope — no plan was too large or too small
- **TDD for new UI components**: `OAuthInstructions` and `GdriveAuthToggle` written test-first; caught a step-prefix detection edge case before integration
- **type=search for search input**: simple attribute that prevents `getByRole('textbox')` collision — elegant selector discipline
- **renderBackendFields() switch**: 7+ backend branches are unreadable as nested ternaries; switch is flat and extensible

### What Was Inefficient
- **Registry had 18 backends but plan said 17**: a counting error in the plan caused minor confusion during 13-01 execution — plans should verify counts against reality
- **Traceability table not updated** (same as v1.2) — REMOTE-03/04/05 showed "Planned" at milestone close despite being complete

### Patterns Established
- `BackendType` from `keyof typeof BACKEND_REGISTRY` (not explicit union) — the canonical pattern going forward
- `BACKEND_SCHEMAS` from `Object.fromEntries` — zero per-backend call sites
- Registry `as const` (not `Record<BackendType,…>` cast) — cast is circular when BackendType derived from registry
- `Partial<Record<BackendType, FC<IconProps>>>` for optional icon map — missing entries render nothing (no error)
- `getByLabelText` partial regex (`/label/i` not `/^label$/i`) — TextFieldMD3 appends `*` to required field labels

### Key Lessons
1. **Update the traceability table as plans complete**, not just at the start — stale status fields caused confusion at milestone close (2nd occurrence after v1.2)
2. **Count registry entries in the plan, not just at planning time** — the 17/18 mismatch was avoidable
3. **`as const` registries with derived types are strictly superior to explicit unions**: eliminates an entire class of drift bugs, zero cost

---

## Cross-Milestone Trends

### Process Evolution

| Milestone | Phases | Plans | Key Change |
|-----------|--------|-------|------------|
| v1.0 | 4 | 18 | Wave 0 TDD pattern established; inside-out build order validated |
| v1.1 | 3 | 11 | CSS-hidden auth toggle pattern; FieldDef additive extension model |
| v1.2 | 5 | 14 | Two-layer CSS token system; DOM class dark mode; CSS-only floating label |
| v1.3 | 1 | 4 | `keyof typeof` derived BackendType; `Object.fromEntries` schema auto-gen |

### Cumulative Quality

| Milestone | Tests | Notes |
|-----------|-------|-------|
| v1.0 | 98 (12 files) | 24/24 requirements satisfied, 5/5 E2E flows |
| v1.1 | 159 (18 files) | 7 browser UI verifications deferred |
| v1.2 | 159+ (same files, heavier coverage) | All DEBT-01 + POLISH/DARK/UX requirements satisfied |
| v1.3 | 165+ | All 6 REMOTE requirements satisfied; visual verification approved |

### Top Lessons (Verified Across Milestones)

1. Single source of truth (BACKEND_REGISTRY) eliminates entire classes of drift bugs — validated at v1.0, proven at v1.3 scale (18 backends)
2. Wave 0 TDD stubs are worth the upfront cost — they define the contract and make RED→GREEN progress visible
3. **Update traceability tables as plans complete** — stale status fields caused confusion at both v1.2 and v1.3 milestone close (recurring issue)
4. CSS-only approaches (floating label, reduced-motion guard, auth toggle) are simpler than JS state — reach for CSS first
5. `as const` registries with derived types (`keyof typeof`) are strictly superior to explicit unions — zero drift possible