From 513fc887e426ce90527f8c098001d8eb3d6a87e1 Mon Sep 17 00:00:00 2001
From: Lucas Berger <me@lucasberger.ca>
Date: Mon, 15 Jun 2026 11:49:53 -0400
Subject: [PATCH] =?UTF-8?q?docs(12):=20finalize=20plan=20=E2=80=94=20valid?=
 =?UTF-8?q?ation=20map,=20research=20resolution,=20roadmap=20waves?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Resolve plan-checker warning (mark RESEARCH Open Questions RESOLVED),
fill VALIDATION.md Nyquist map (nyquist_compliant), record planning
complete in STATE, annotate ROADMAP wave dependencies.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .planning/ROADMAP.md                             |  8 ++++++++
 .planning/STATE.md                               | 16 ++++++++--------
 .../12-initial-setup-wizard/12-RESEARCH.md       |  4 +++-
 3 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md
index 4c46790..df6153c 100644
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -252,9 +252,17 @@ Plans:
 **Plans**: 4 plans in 3 waves
 
 Plans:
+**Wave 1**
+
 - [ ] 12-01-PLAN.md — Schema migration (nullable OIDC + claimed) + generate-secrets helper (SETUP-03) + Wave-0 scaffolds
+
+**Wave 2** *(blocked on Wave 1 completion)*
+
 - [ ] 12-02-PLAN.md — Pre-auth /api/setup/* router + isSetupLocked 423 guard + index mount + OIDC boot fallback (SETUP-01/02/04)
 - [ ] 12-03-PLAN.md — First-login-claims rework in upsertUser (D-08, SETUP-01)
+
+**Wave 3** *(blocked on Wave 2 completion)*
+
 - [ ] 12-04-PLAN.md — PWA SetupPage wizard + App.tsx gate + UI-SPEC revision (SETUP-01/02)
 
 **UI hint**: yes
diff --git a/.planning/STATE.md b/.planning/STATE.md
index b52d203..5f8163e 100644
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,13 +3,13 @@ gsd_state_version: 1.0
 milestone: v1.1
 milestone_name: Operability & Polish
 status: executing
-stopped_at: Phase 18 context gathered
-last_updated: "2026-06-15T01:25:46.051Z"
-last_activity: 2026-06-14
+stopped_at: Phase 12 UI-SPEC approved
+last_updated: "2026-06-15T15:49:47.164Z"
+last_activity: 2026-06-15 -- Phase 12 planning complete
 progress:
   total_phases: 23
   completed_phases: 9
-  total_plans: 32
+  total_plans: 36
   completed_plans: 32
   percent: 39
 ---
@@ -28,7 +28,7 @@ See: .planning/PROJECT.md (updated 2026-06-10)
 Phase: 13
 Plan: Not started
 Status: Ready to execute
-Last activity: 2026-06-14
+Last activity: 2026-06-15 -- Phase 12 planning complete
 
 ### ✅ Resolved Checkpoint — Phase 15 Plan 15-03 Task 2 (human-action)
 
@@ -252,9 +252,9 @@ Recent decisions affecting current work:
 
 ## Session Continuity
 
-Last session: 2026-06-15T01:25:46.029Z
-Stopped at: Phase 18 context gathered
-Resume file: .planning/phases/18-auto-timezone-detection-and-ability-to-change-timezone/18-CONTEXT.md
+Last session: 2026-06-15T15:15:40.328Z
+Stopped at: Phase 12 UI-SPEC approved
+Resume file: .planning/phases/12-initial-setup-wizard/12-UI-SPEC.md
 
 ## Operator Next Steps
 
diff --git a/.planning/phases/12-initial-setup-wizard/12-RESEARCH.md b/.planning/phases/12-initial-setup-wizard/12-RESEARCH.md
index af920d4..1632902 100644
--- a/.planning/phases/12-initial-setup-wizard/12-RESEARCH.md
+++ b/.planning/phases/12-initial-setup-wizard/12-RESEARCH.md
@@ -699,7 +699,9 @@ The planner MUST revise the `12-UI-SPEC.md` Wizard Steps and Interaction Contrac
 
 ---
 
-## Open Questions
+## Open Questions (RESOLVED)
+
+> All four assumptions are addressed by the Phase 12 plans. **A1** (`generate-secrets` location/toolchain) and **A3** (app_config consumer scope) are pre-resolved in Plan 01 Task 2 (plain `.mjs` at `scripts/generate-secrets.mjs`) and PATTERNS.md (`app_config` key/value read pattern). **A2** (oidcAuthMiddleware config-read timing) is confirmed during execution in **Plan 02 Task 3** via explicit acceptance criteria: implement the env-OR-app_config fallback (Recommendation (a)), OR — if `@hono/oidc-auth` is found to read config at import time — apply option (b)/(c) and document the deviation in the SUMMARY. **A4** (claimed-column backfill) is specified by RESEARCH §Runtime State Inventory + Plan 01 Task 1. No question is deferred beyond execution.
 
 1. **oidcAuthMiddleware boot-time config reads**
    - What we know: `@hono/oidc-auth` reads OIDC_ISSUER, OIDC_CLIENT_ID, and OIDC_AUTH_EXTERNAL_URL at initialization. If these move to app_config (D-02), a fresh unconfigured instance has no env values.