HealthLog/docs/audit/v1420-summary.md

HealthLog v1.4.20 — Release Summary

Release brief

Live: v1.4.20 (image digest sha256:b112a31947b9…, /api/version=1.4.20).

v1.4.20 is the deliberately-loud release that cashes in the runway v1.4.19 set up. The redesigned /insights page lands a hero strip with greeting + suggested-prompt chips, a Daily Briefing card, an AI Coach drawer with SSE-streaming chat and encrypted conversation history, three pre-defined correlation cards (BP × medication compliance, mood × pulse, weight × weekday), a Trends row with AI annotations, a printable Weekly Report at /insights/report/[week], and a Personal Health Score panel (composite 0-100 with three bands). The polish-vs-feature ratio inverted to roughly 30/70 — the right ratio for a release that means to ship new product.

PROMPT_VERSION ratcheted 4.19.0 → 4.20.2 across three controlled bumps; aiInsightResponseSchema gained five optional blocks (dailyBriefing, trendAnnotations, weeklyReport, storyboardAnnotations, healthScore). Every new field is nullable + optional, so insights cached before v1.4.20 still parse without a re-run — the v1.4.17 lesson is wired in by construction now, not by audit.

Hard-Reload (Cmd+Shift+R) for SW reset.

v1.4.20 is also the first release shipped through the new develop → main branch model introduced in this milestone's foundation phase: feature work lands on develop and stays out of the GHCR build path; only the release-merge to main plus the annotated tag trigger image publication. The model is documented in CONTRIBUTING.md and on the public docs site under /contributing/branch-model/.

---

Production deploy

Field	Value
URL	https://healthlog.bombeck.io
/api/version	1.4.20 (flipped at 2026-05-10T16:49:25Z)
Image digest BEFORE	sha256:b48f93874cdbcd6c2d729f1b8eeb63a6d1bbb90d56f629846ef6eab6cf272aa9 (v1.4.19)
Image digest AFTER	sha256:b112a31947b91f2fdb4bb01b60c6b17a0b8ec128ae116d37e1094da5c3decaa6 (v1.4.20)
Release-prep commit (develop)	aac8b5e chore(release): v1.4.20
Develop ↔ main sync commit	dd2ef57 Merge main into develop — sync Dependabot dep bumps before v1.4.20 tag
Release-merge commit (main)	666f6ee Release v1.4.20
Tag	v1.4.20 (annotated) at 666f6ee
GHCR — tag run	25633807964 success (4m02s)
Coolify auto-deploy	NO — webhook secret still missing on the deploy server (same fault mode as v1.4.19); host-side retag fallback used
Smoke (curl, no session)	/api/version 200 · /auth/login 200 · all gated routes return 307 → /auth/login (expected proxy.ts behaviour without a session cookie)
GH release	https://github.com/MBombeck/HealthLog/releases/tag/v1.4.20
Docs site	0b83430 on healthlog-docs/main (updates.mdx + scaling.mdx version pins; ai-insights.mdx v1.4.20 callout)
Landing site	43ce4c7 on healthlog-landing/main (softwareVersion JSON-LD bumped, three new featureList entries)

The tag-build pipeline succeeded; the deploy webhook still isn't wired on apps-01, so v1.4.20 was promoted via the documented host-side fallback path:

docker pull ghcr.io/mbombeck/healthlog:1.4.20
docker tag ghcr.io/mbombeck/healthlog:1.4.20 ghcr.io/mbombeck/healthlog:latest
cd /data/coolify/applications/pg8wggwogo8c4gc4ks0kk4ss
docker compose up -d --force-recreate app

/api/version flipped to 1.4.20 on the first poll cycle after recreate — well inside the 5-minute cap. The Coolify-managed restart-and-redeploy path was tried twice first (d10hrd3he27w… and tgkn9ewch46c…); both ran cleanly to "finished" but neither pulled a fresh manifest, so the running container kept serving v1.4.19. Wiring an image-digest auto-deploy hook on apps-01 is captured in .planning/v1421-backlog.md.

---

Smoke results

The previous releases' brief showed 200s because they ran with a live session cookie that's not persisted on this run. Without the cookie, every authenticated route correctly returns 307 → /auth/login, so the smoke verifies the proxy gate is healthy end-to-end:

Path	Status (no session)	Notes
/api/version	200	Returns version: "1.4.20"
/auth/login	200	Public surface, renders normally
/	307 → /auth/login	Gated dashboard root
/insights	307 → /auth/login	Redesigned Insights shell
/insights/report/2026-W19	307 → /auth/login	New v1.4.20 weekly-report route
/admin/api-tokens	307 → /auth/login	Admin section
/settings/integrations	307 → /auth/login	Settings section
/achievements	307 → /auth/login	Achievements page
/dashboard	307 → /auth/login	Expected: root is the dashboard, no /dashboard route

The Coach drawer and Health Score panel can't be smoked without a live session — neither carries a public surface. Confirmed live via the /api/version check; Wave-D reviewers exercised both paths under integration coverage before tag.

---

What shipped

Hero strip + Daily Briefing + Suggested Prompts

/insights opens with a redesigned hero strip that pairs a time-of-day greeting and primary action row with a horizontal strip of suggested-prompt chips. A Daily Briefing card mounts full-width below the hero, surfacing an AI-generated paragraph plus three keyFindings drawn from the last 24-hour window. Suggested-prompt chips drive the Coach drawer with the prompt prefilled, so the shortest path from "I want to know X" to a streaming answer is one tap. The four-vitals tile row from the design artboard was intentionally deferred — the per-section status cards already render the same numbers, and the briefing fills the at-a-glance role.

AI Coach drawer with streaming chat + encrypted persistence

The biggest piece of the release. POST /api/insights/chat is an SSE endpoint that walks the existing AI provider chain, persists user + assistant turns under AES-256-GCM, and emits token → provenance → done frames. A per-user daily token budget (25 000 tokens, ≈13 turns for a heavy user) caps shared-key spend; a refusal pattern blocks prompt-injection attempts and obvious off-topic asks before the provider call. The drawer mounts from the hero strip's "Ask the coach" button and from any suggested-prompt chip; layout is three columns on lg+ (history rail · message thread · sources rail) and full-screen single-column on mobile with chevron-button trays for the rails. Source-chip provenance attaches to every assistant turn (metric, window, n-count — labels only, never raw values). parseSseChunk() is exported as a pure helper so the streaming parser is unit-testable without a live network.

Correlation cards + Trends row with AI annotations

Three pre-defined hypothesis cards mount between the Daily Briefing and the Advisor card: BP × medication compliance, mood × pulse, and weight × weekday. Pearson r is rendered with a Fisher-z confidence interval; surfacing gate is n ≥ 14 paired observations and p < 0.05. The Trends row alongside it carries short AI-generated annotations tied to specific dates in the analyzed window; the BP timeline gains storyboard markers at the same positions via an additive annotations[] prop on <HealthChart>.

Weekly Report at /insights/report/[week]

A newsletter-style printable surface with five sections: Summary, Going-well, Worth-watching, Tips, Data-quality. window.print() export via Tailwind print: variants gives a clean A4 page without a server round-trip. The hero strip surfaces fresh weekly reports with Read · Share · Export PDF actions; Share uses Web Share API with a clipboard fallback, Export deep-links to ?print=1.

Personal Health Score (composite 0–100)

A deterministic composite score with three bands (green ≥75, yellow 50–74, red <50). Weights: 30% BP-target rate + 20% weight-trend alignment + 20% mood stability + 30% medication compliance. When a sub-component is null, remaining weights scale to 100 so the score stays interpretable. The <HealthScoreCard> renders alongside the hero strip on lg+ (220 px desktop, full-width mobile) with a band-tinted progress bar, four sub-bars, "vs last week" delta line, and a score-aware "Ask the Coach" CTA that opens the drawer with "Why is my health score X out of 100?" prefilled.

---

Quality bar

• Test counts moved hard. 1672 → 2026 unit tests (+354 net), 67 → 81 integration (+14). Five new test files for the Coach alone (use-coach, source-chips, message-thread, coach-input, sources-rail, history-rail). Test files 217 → 237.
• typecheck + lint clean. 0 type errors, 13 baseline warnings unchanged (every warning is the _request / _params / intentional-unused pattern).
• Multi-reviewer Wave-D pass. Six reviewers (code, security, design, senior-dev, simplify, product-lead) filed 0 CRIT · 12 HIGH · 28 MED · 22 LOW + 5 simplify-apply-yes + 4 simplify-apply- maybe + 3 simplify-apply-no. All 12 HIGH items + the design pushback on the disabled weekly-report button + 6 MED items + every simplify-apply-yes item landed inline across 11 atomic commits on develop (e632e26 → 31fbf98). 22 MED + 16 LOW + 4 simplify-apply-maybe deferred to .planning/v1421-backlog.md under "Phase D — v1.4.20 reconcile carry-over".
• One known integration-test flake. coach-chat.test.ts / "round-trips" was observed to flake on a single run during Phase D and again during pre-flight; consistent re-runs pass. Tracked in the v1.4.21 backlog.
• format:check clean on the source tree. A small style commit (73e51d7 style: prettier on touched insights/coach surfaces) ran prettier across the new B-phase additions before tag, so the only remaining format:check warnings are the .planning/* baseline noise carried over since v1.4.16.

---

Branch model

v1.4.20 is the first release shipped through the new develop → main model:

• All B1 → B5 phase work, every Wave-D reconcile commit, the release-prep commit, the prettier sweep, and the merge-back of Dependabot's day-of dep bumps landed on develop.
• A single Release v1.4.20 no-ff merge commit on main plus the annotated v1.4.20 tag triggered the GHCR tag-build job (25633807964).
• The GHCR workflow is gated to branches: [main] + tags: ['v*'] — develop pushes neither build nor publish images, which removes the v1.4.13-era image-churn problem on GHCR.
• Two Dependabot dep-bump PRs (#161, #165) auto-merged into main after the tag build started but before the host-side fallback ran. They were absorbed into develop ahead of the release-merge via a Merge main into develop commit, so the v1.4.20 tag includes them. Three more dep-bump PRs (#153, #154, #157, #158, #159, #160) had auto-merged earlier the same day and were absorbed the same way.

---

Carry-over

Full backlog: .planning/v1421-backlog.md.

• 22 MED + 16 LOW + 4 simplify-apply-maybe items from the multi-reviewer Phase-D pass. Headline items: senior-dev call to consolidate the duplicated Pearson / linear-regression maths layer (Sr-HIGH-2 — too large for inline reconcile); refactor <CoachDrawer key={prefill}> into a controlled prefill prop (Sr-HIGH-4); transactional recordSpend() (Sec-M-4); refusal accounting and lexicon expansion (Sec-M-2 / Sec-M-3).
• Schema drift on medication_schedules.days_of_week. Worked around twice in v1.4.20 (B5 analytics, B2a coach snapshot); the migration needs to either deploy the column or drop it from schema.prisma.
• src/app/insights/page.tsx now composes nine distinct surfaces. Splitting the component is on the v1.4.21 cleanup short-list; pre-emptive splitting before the multi-reviewer pass ran was deliberately avoided.
• Coolify image-digest auto-deploy hook on apps-01. Tag-build pipeline is fine; the deploy step needs the webhook wired so /api/version flips on its own without the manual host-side retag.
• Source-comment sweep (191 maintainer-name references in src/), DE+EN bilingual CHANGELOG entries (v1.4.15 era), and CLAUDE.md / AGENTS.md filename hygiene are tracked for a hygiene PR.

---

Strategic next

v1.5 stays reserved for the iOS native app + Apple Health integration + per-metric APNs alerts. The redesigned /insights shell, AI Coach drawer, and Health Score panel were all built with that next milestone in mind: the Coach SSE endpoint accepts the same Bearer-token auth that ships for the existing native API clients (hlk_<64hex>); the Health Score formula is deterministic and pure, so an iOS port can compute the same number locally if it wants to; the source-chip provenance contract is JSON-only and labels-only, ready for an APNs payload. Strategic plan and the artboard / API-shape sketches at .planning/phase-D-v1420-product-lead-review.md.

---

GH release URL

https://github.com/MBombeck/HealthLog/releases/tag/v1.4.20

---

Hard-Reload reminder

Cmd+Shift+R (Mac) / Ctrl+Shift+R (Linux/Win) — the new service worker otherwise still serves v1.4.19 chunks from cache. One-shot is enough.