diff --git a/.planning/v1425-handoff-session-2.md b/.planning/v1425-handoff-session-2.md new file mode 100644 index 000000000..a65962bfe --- /dev/null +++ b/.planning/v1425-handoff-session-2.md @@ -0,0 +1,275 @@ +# v1.4.25 Handoff — Session 2 → Session 3 + +**Created**: 2026-05-14 spät abends. Session 2 context exhausted at ~78%. +**Next session reads this first, then `.planning/v1425-handoff.md` (Session 1's handoff) for older context.** + +--- + +## TL;DR — Where we are + +- **PR #168 open**: https://github.com/MBombeck/HealthLog/pull/168 (Draft, develop → main, title "Release v1.4.25") +- **Latest develop commit**: `d75d47b` (Fix-H integration alignment) plus W19c paused without commits and W14b-Foundation running in background +- **CI on PR #168**: Lint/Typecheck/Test + Dependency Audit + Secret Scanning + integration **all PASS**; e2e + Build amd64/arm64 pending (Fix-G's `dd44a0d` likely makes these green) +- **Test count**: 3383+ unit passing (was 2244 at session start of original handoff — net delta ~1140 tests added) +- **Migrations shipped**: 0051 (Measurement.device_type) · 0052 (3 AH enum values) · 0053 (Workout + Route) · 0054 (PersonalRecord) · 0055 (sleep-stage composite) · 0056 (MedicationInventoryItem) +- **Marc explicitly STOP-Punkt unchanged**: NO TAG, NO MAIN-PUSH. Marc tags after his UAT. + +--- + +## What landed in Session 2 (after the original `v1425-handoff.md`) + +In order, by wave: + +### Pre-W10 cleanup +- **W7c** baseline enum-drift fix (W5d Withings carry-over) — `ca3c225` +- **W7d** dev-server repair (Tailwind v4 color-mix + api-handler) — `782731a`, `15d9183` +- **W7e** atomic dead-code Cat-A cleanup — `1149ae5`, `784105d`, `94e048f`, `5743760` + +### W8 series — cross-page + iOS foundation +- **W8** cross-page consistency + Settings/Admin icon-heading + mobile-first — `00105e2` → `8f54993` +- **W8c** Source-priority Two-Axis (metric × deviceType) — `f05c55f` → `53278cc` (Migration 0051) +- **W8d** AH-Server-Prep — `41ba79b` → `b324e6c` (Migrations 0052 + 0053 + 0054, VO2 tile, PR-direction helper) +- **W8e** Health-Score provenance accordion — `86737fd` → `2fd31f2` + +### W9 series — translation +- **W9e** FR/ES/IT/PL + MaintainershipBanner — `3c4bbde`, `5d5a934` +- **W9f** hot-fix format-locale + missing key — `89fb3bc`, `6a7da4b` + +### W10 — Multi-Agent QA + reconcile +- 6 review-agent reports written to `.planning/research/w10-*.md` +- **Fix-A Design**: 4 commits applying 16 findings (0 deferrals) — `bd1cb2c`, `e14466e`, `72fcdc6`, `8f54993` +- **Fix-B Architecture**: 6 commits applying 7 findings — `db5e07a` → `3dff934` +- **Fix-C Security+Auth+API** (iOS-blocker H2 + GLP-1 prompt-injection + batch race fix + audit-log): 6 commits — `c38a2c8` → `53a7992` +- **Fix-D Simplifier**: 6 commits (62 LOC out) — `38023ee` → `ec484e0` +- **Fix-E** i18n hot-fix → no-op (already done) — `4745d7f` + +### W11 series — release-prep +- **W11** release-prep — `cb07d5c` (version bump 1.4.24 → 1.4.25, CHANGELOG 387 lines, PR #168 opened) +- **W11a** multi-arch Docker (linux/amd64 + linux/arm64 via ubuntu-24.04-arm matrix) — `3e78da6` + +### Round 3 expansion (Marc-directive: pull v1.4.26 backlog into v1.4.25) +- **W14a** OpenAPI drift-gate hard-flip — `74bf608`, `41147bd` (gate now fails on drift; was warn-only) +- **W17a** Withings webhook secret as URL path-segment — `a1ffa49` +- **W16a** Schema-logic quick wins — `b4df3ae`, `0e51007`, `bff13e7` (iOS-17/18 HK long-tail + VO2 chart-row + workout dedup helper) +- **W14c** Native FR/ES/IT/PL Coach prompts — `84af00d` → `75fce6c` (safety-contract matrix YAML + 1680+ adversarial probes + maintainership banner update). DE keeps hand-curated body, matrix only powers parity for DE. +- **W16b** POST /api/workouts/batch typed ingest — `62e4b1d` → `5a7d252` +- **W17b+c** Withings Activity + Sleep v2 sync — `df5a82b` (Migration 0055) → `dab7de3` (webhook expansion + 2 pg-boss queues at :00 and :15) +- **W19a** EMA drug knowledge layer — `cee5bf5`, `da73e06`, `45bbfe4` (5 EMA-approved drugs, ~200 cited values, drift-guard) +- **W20a** Dashboard top-tile polish — `c10b4ca`, `135b375`, `a7cc5de` (single-line headings + inline trend arrow + baseline alignment) +- **W16c** PR Detection worker — `05c20c9` → `223b8a9` (pg-boss queue + batch-route hooks + badge) +- **W19b** Pen/vial inventory + 30-day clock — `570b14d` → `7f133a1` (Migration 0056) + +### Post-Round-3 hot-fixes +- **Fix-G** CI hot-fix (health-score determinism + glp1-drift parse + TZ split + observer pattern + safety-contracts cwd path) — `4feeafa` → `dd44a0d` +- **Fix-H** integration alignment (coach-snapshot tz + coach-prefs round-trip + batch-delete fixture) — `82c138f`, `afe8634`, `d75d47b` + +--- + +## Currently in-flight (Session 2 left running) + +| Agent | Status | Touch-scope | Expected commits | +|---|---|---|---| +| **W14b-Foundation** | 🟡 running | `prisma/migrations/00_user_onboarding_step/`, `prisma/schema.prisma` (User), `src/app/onboarding/**`, `src/components/onboarding/**`, `src/app/api/onboarding/step/`, `messages.onboarding.*` | 4 atomic (Migration, nested routes scaffold, OnboardingShell primitive, i18n key surface) | +| **W19c** | ⏸ **paused untouched** at 78% context, NO commits | will touch: `prisma/migrations/00_user_research_mode/`, `src/lib/medications/glp1-pk.ts`, `src/components/medications/drug-level-chart.tsx`, `src/components/medications/research-mode-acknowledgment-dialog.tsx`, `src/app/api/auth/me/research-mode/`, settings, coach-prompt + 6 safety-contract YAMLs, `messages.medications.researchMode.*`, `messages.settings.researchMode.*` | 8 atomic (recommended split into 3 sequential agents per W19c agent's own recommendation — see "How to resume" below) | + +--- + +## Marc-confirmed strategic decisions (don't re-litigate) + +1. **W14c**: Reco-A modified — LLM-draft + structural matrix coverage (Marc cannot review native translations). MaintainershipBanner acknowledges AI-drafted safety-critical content. ✅ shipped. +2. **W17b+c**: Reco-A — Migration 0055 for sleep-stage composite. ✅ shipped. +3. **W14b**: Reco-A — Apple Health card as "coming soon" disabled in onboarding source-step. ✅ planned, in flight via W14b-Foundation. +4. **W19 series final 6 sub-waves** (Marc reversed initial defer of W19c + W19e): + - W19a EMA drug knowledge ✅ shipped + - W19b Pen/vial inventory ✅ shipped + - W19c Drug-level chart + MDR-acknowledgment-gate ⏸ pending + - W19d Side-effect taxonomy expansion (21 entries / 5 categories) ⏸ pending + - W19e Reminders + cadence-viz + compliance chips (reuse existing pg-boss + notifications/dispatcher — Marc-correction that no new infra needed) ⏸ pending + - W19f Titration ladder display ⏸ pending + - **DEFER to v1.4.26**: W19g (doctor-share TTL), W19h-folded-into-W19e, W19i (LLM paste-import) +5. **W20a Dashboard top-tile polish** ✅ shipped (Marc-asked mid-session — single-line headings + inline trend arrow + baseline alignment) + +--- + +## Remaining work (in execution order) + +### Wave 4a — running now / pending finish + +| Wave | Status | Notes | +|---|---|---| +| W14b-Foundation | 🟡 running in background | Should finish in ~30-60 min | +| **W14b-Content** | ⏸ next dispatch after Foundation commits | Value-prop carousel + goals chip-picker + source 4-card grid + welcome-back banner. ~3-4 commits | +| **W19c-Backend** (recommended split) | ⏸ pending | 19c.1 Migration 00_user_research_mode + 19c.2 glp1-pk.ts module + 19c.4 API endpoint. ~3 commits | +| **W19c-Frontend** | ⏸ after W19c-Backend | 19c.3 acknowledgment-dialog + 19c.5 drug-level-chart + 19c.6 settings-toggle. ~3 commits | +| **W19c-Safety** | ⏸ after W19c-Frontend | 19c.7 Coach GROUND RULE 15 + 6 safety-contract YAMLs + refusal-probe test + 19c.8 lazy 90-day check. ~2 commits | + +### Wave 4b — sequential medication-detail-page touches + +| Wave | Notes | +|---|---| +| **W19d** Side-effect taxonomy | 21 entries × 5 categories (GI, Metabolic, Injection-site, Cognitive, GLP-1-specific). Severity 1-5 Likert. Extends existing mood/symptom tag system. Touches `messages.medications.sideEffects.*` | +| **W19e** Reminders + cadence-viz + compliance chips | Reuse pg-boss + notifications/dispatcher (Marc-correction). GLP-1 schedule logic from W19a knowledge layer. Cadence-viz timeline/heatmap on medication detail. Compliance chips (streaks, missed-dose). Touches `messages.medications.reminders.*` + `medications.cadence.*` | +| **W19f** Titration ladder display | Static EMA dose-escalation display per drug. Reads W19a knowledge. Touches `messages.medications.titration.*` | + +### Wave 5 — cleanup waves + +| Wave | Notes | +|---|---| +| **W15** Hygiene cluster | 414 dead i18n keys cleanup (with spot-check for `classifications.alerts.*` 26 keys + `targets.*` iOS shadow) + BASE_SYSTEM_PROMPT + INSIGHTS_SYSTEM_PROMPT removal + W7d hardening (safeRequestProp narrow-catch + @source path-resilience) + Cat-C typo fix | +| **W18** W10 Low+care cluster | 12 items per `.planning/research/w10-*-findings.md` Low/apply-with-care sections — lazy locale bundles, chart-tick tz, errorCode rename, glp1-plateau tests, dead testables, audit-log decision, deviceType enum, drift-guard, design polish, hsl(var) anti-pattern, S1/S3/S9/S10/S12 simplifier, S11/S14/S15 discuss-first | +| **W20** P6 Polish cluster (W20a already done) | 11 items per `.planning/v1426-backlog.md` P6 — Pearson, sentinel obs, Coolify toggle, Coach lastYear/row-tap, sleep stacked column, locale date formats, GH translation template, prose hand-review, Cat-B triage, mood verbal labels | + +### Wave 6 — Final QA + Release + +| Wave | Notes | +|---|---| +| **W21** Multi-Agent QA | 6 parallel reviewers (code-review, security, design, senior-dev, simplifier, product-lead). Same pattern as W10. Read prior W10 findings to know the rubric. Plus i18n-runtime probe (Fix-G fixed dev server) — now can run live | +| **W21-reconcile** | Apply all Medium+/High+/Critical findings (Marc-directive). Defer Low to v1.4.27 | +| **W22** Release-redo | Update CHANGELOG.md to reflect Wave 4-5 additions (~500 lines total). Version stays 1.4.25. New commit `chore(release): expand v1.4.25 with Wave 4-5 features` on develop. Push. Move PR #168 from Draft → Ready-for-review | +| **W23** STOP — Marc UAT | Marc reviews, runs his own Q&A audits (he said "verschiedene Q&A Audits am Ende noch mal drüber"), tags v1.4.25 + merges PR #168 → main | +| **W24** Deploy + Deliverables | Demo redeploy to v1.4.25 (compose tag bump on edge01), docs/landing sync, repo config sweep (FUNDING.yml decision, social preview, branch-protection required-status-checks flip), `docs/audit/v1425-summary.md` (Marc-brief style v1421-summary), 0-10 score per area, Codex audit prompt, `v15-ios-handoff.md` (locked server contracts + 2 research reports) | + +--- + +## Critical research files (read as needed) + +Located in `/Users/marc/Projects/HealthLog/.planning/research/`: + +- `apple-health-ecosystem-scan.md` (~3850 words) — Apple Health OSS landscape +- `apple-health-sync-deep-dive.md` — iOS sync patterns +- `glp1-feature-inspiration.md` (~7100 words) — Marc-cited EMA EPAR + ASCPT psp4.13099 + my-glp-shot clean-room deep-dive. **CRITICAL for W19c-f** +- `glp1-injection-tracking.md` — earlier W4d research +- `health-score-provenance-ux.md` — W8e UX research +- `insights-sub-pages-ux.md` — W4 research +- `open-wearables-comparison.md` (~3800 words) — Apple Health vs Withings vs HealthLog +- `source-priority-two-axis.md` (~2400 words) — W8c research +- `w10-code-review-findings.md` — W10 reviewer outputs (5 files: code, security, design, senior-dev, simplifier, product-lead) +- `w10-dead-code-candidates.md` — Cat-A/B/C inventory (Cat-A applied W7e; Cat-B/C pending W18) +- `w10-i18n-runtime-gaps.md` — i18n runtime probe (1 missing-key fixed; 414 dead keys deferred to W15) +- `w14b-onboarding-rebuild.md` (~3177 words) — **W14b-Content critical reference** +- `w14c-native-coach-prompts.md` (~3.6k words) — W14c shipped per recommendations +- `w16b-workout-ingest.md` (~2589 words) — W16b shipped per recommendations +- `w16c-pr-detection.md` (~2501 words) — W16c shipped per recommendations +- `w17b-c-withings-activity-sleep.md` (~2050 words) — W17b+c shipped per recommendations +- `w8d-implementation-outline.md` (~3000 words) — W8d shipped per recommendations +- `withings-api-coverage.md` — older Withings audit +- `withings-plus-comparison.md` — older Withings competitive intel +- `zielwerte-redesign.md` — older targets research + +Phase reports in `/Users/marc/Projects/HealthLog/.planning/`: +- `phase-W*.md` files — one per implementation wave (~20+ files) +- `v1425-handoff.md` — Session 1's handoff +- `v1426-backlog.md` — 38-item backlog (P0-P6 + deferred + "things explicitly rejected") +- `v1425-handoff-session-2.md` — THIS FILE + +--- + +## Critical conventions (NON-NEGOTIABLE) + +- **NO `Co-Authored-By: Claude` trailer** on any commit +- **NO `--no-verify`** on any commit +- **Marc-Voice**: English commits + CHANGELOG; professional, terse, technical; never "AI", "Claude", "agent", "marathon", "phase", "wave" in user-facing artifacts +- **NO PII**: Marc's name, health figures, IPs never in CHANGELOG / release notes / docs/audit/v*-summary.md / public marketing +- **Branch model**: commit to `develop`, release via PR #168 → main, Marc tags +- **Quality gates per commit**: typecheck + lint + relevant tests must pass before commit +- **Migration number**: read from `ls prisma/migrations/ | sort | tail -3` and pick next free (gaps OK; ordering matters) +- **NO TAG, NO MAIN-PUSH** until Marc UAT confirms + +--- + +## Marathon-orchestration pattern (proven this session) + +Pattern from `~/.claude/skills/release-marathon/` (created this session): +1. **Touch-disjoint** is the dispatch guarantee +2. **4-6 concurrent agents** default cadence +3. **Research-first** for architecturally-new work (research agent → markdown → implementation agent reads it) +4. **Sub-wave decomposition** when one wave is too large for one agent's context +5. **Marathon-skill triggered via `/marathon` slash command** — already installed +6. **Phase report per wave** at `.planning/phase-W-v1425--report.md` + +If you need the skill content: `~/.claude/skills/release-marathon/SKILL.md`. If you need the slash command: `~/.claude/commands/marathon.md`. + +--- + +## How to resume in Session 3 + +### Step 0: Read this file + check W14b-Foundation status + +```bash +gh pr checks 168 +git log --oneline -10 +ls .planning/phase-W14b-Foundation-v1425-report.md # may exist if W14b-Foundation finished +``` + +If W14b-Foundation finished while Session 2 was paused, it has 4 commits ready. If not, wait for the agent to finish before Session 3 starts (or check the agent state via `gh pr checks 168` showing develop's progress). + +### Step 1: Dispatch the rest in waves + +**Wave 4a-finish (parallel — should be 2 agents)**: +- W14b-Content (carousel + goals + source + banner — touches `messages.onboarding.*`, `src/app/onboarding/**/page.tsx`, `src/components/onboarding/**`) +- W19c-Backend (Migration + glp1-pk + API — touches `prisma/`, NEW `src/lib/medications/glp1-pk.ts`, `src/app/api/auth/me/research-mode/`) + +**Wave 4a-continue (sequential — after W19c-Backend)**: +- W19c-Frontend (dialog + chart + settings toggle) +- W19c-Safety (Coach GROUND RULE 15 + safety YAMLs + refusal-probe) + +**Wave 4b (sequential — all touch medication detail page)**: +- W19d Side-effect taxonomy +- W19e Reminders + cadence-viz + compliance +- W19f Titration ladder display + +**Wave 5 (cleanup, can parallelize across disjoint namespaces)**: +- W15 Hygiene (414 dead i18n + system-prompts removal + W7d hardening) +- W18 W10 Low+care cluster +- W20-rest P6 Polish cluster (W20a already done) + +**Wave 6 (final)**: +- W21 Multi-Agent QA (6 parallel reviewers, same pattern as W10) +- W21-reconcile fix-agents (3-4 parallel touch-disjoint) +- W22 Release-redo (expand CHANGELOG to reflect Wave 4-5 additions, push, PR #168 Ready-for-review) +- W23 STOP — Marc UAT +- W24 Deploy + Deliverables (after Marc tags) + +### Step 2: After Marc tags + +Then W24: +- Demo redeploy: `ssh edge-01 && docker compose ... up -d --force-recreate app` (compose pinned to GHCR, just bump tag) +- Sister repos: healthlog-docs (3 image-pin spots like v1.4.23 + ai-insights callout) · healthlog-landing (softwareVersion JSON-LD bump) +- `docs/audit/v1425-summary.md` — Marc-brief, model on `docs/audit/v1421-summary.md` +- 0-10 score per area: Insights / Dashboard / Coach / Settings / Admin / Mobile / Tests / CI / Docs / Repo / Demo +- Codex audit prompt: TS/Next.js edge cases + Prisma migration safety on 6 new migrations (0051-0056) +- `.planning/v15-ios-handoff.md` for iOS-Claude-session: locked server contracts (batch endpoints, source-priority, OpenAPI 3.1, GROUND RULE 9+15), 2 research reports cross-linked + +--- + +## Open Marc-decisions (none currently outstanding) + +All 4 strategic decisions from Session 2 are confirmed (W14c author-model, W17b+c sleep-stage composite, W14b Apple Health "coming soon", W19 pruning to 6 sub-waves with W19c MDR-mitigation pattern). + +Session 3 should NOT need new Marc decisions unless something architecturally-new surfaces from W19d/e/f or the final QA. Default to recommend + proceed pattern. + +--- + +## Test count progression for the CHANGELOG W22 update + +| Snapshot | Unit | Integration | +|---|---|---| +| v1.4.24 baseline | 2244 | ~140 | +| Post-W7c (Session 2 start) | 2543 | ~140 | +| Post-W10 reconcile | 2652 | ~150 | +| Post-W14c (refusal-probe matrix) | 3371 | ~150 | +| Post-W17b+c | 3383+ | ~165 | +| Post-Fix-H | 3400+ | ~170 | +| **Current** | **~3400** | **~170** | + +Expected at v1.4.25 tag: **~3800-4000 unit** + ~200 integration (after Wave 4-5 + W21). + +--- + +## Closing note + +Marc explicitly said "Ich möchte das hier in dieser Session machen" early in Session 2 — but the scope grew with my agreement (W19 expanded from 4 to 6, plus W14b/c/d/e/f). The expanded scope physically cannot fit in one session's context window. This handoff preserves the state for clean continuation. + +The marathon-skill pattern proven this session is solid — Marc just needs to start a fresh session and say "marathon — continue v1.4.25 per `.planning/v1425-handoff-session-2.md`". The fresh session reads this, dispatches the remaining 8-15 agents, and converges to W23 STOP for Marc UAT. + +PR #168 is alive and accumulating CI verification with every push. Branch model preserved. STOP-Punkt at W23 honored — Marc tags after his UAT, never the orchestrator.