Minimente — Technical Decision Record

Document type: Companion to PRD v4.0 and Addendum A1.0 — standalone, mergeable Applies to: Minimente — Stress Management (Programme #1) and all future programmes Version: TD1.0 — DECISION RECORD Date: 2026-07-27 Owner: Engineering. Content, programme-shape, legal and clinical decisions remain with Minni and external review, and are listed — precisely — in §TD3 and §TD4. Status of PRD v4.0 and the Breathing Addendum: Frozen. This document modifies neither. Where a decision here gives effect to a v4/A1 requirement, the requirement ID is cited; where it resolves an OPEN item, the resolution is recorded here and the frozen documents' rows stand as historical record.

---

TD0. What this document is, and the authority it claims

TD0.1 Purpose

PRD v4.0 leaves 26 open questions (§10) and the Breathing Addendum leaves 9 (§A10). A previous pass treated all 35 as requiring founder sign-off. That was wrong for a specific subset: questions whose answer is engineering, architecture, infrastructure, data-model, security, or interaction-implementation judgement are engineering's to close, and a PRD described as implementation-ready that cannot name its own stack is not implementation-ready. OPEN-24 was the clearest case — and it cascades: OPEN-BR-07 (haptic pacing) is explicitly blocked on it, and §11 Phase 1 item 7 (the content schema) "cannot be specified against an unknown client platform".

This document therefore does three things:

1. Closes every technical open question as an Architecture Decision Record (ADR-01…ADR-15, §TD2), with alternatives, forcing requirements, risks, and revisit triggers.
2. Splits every mixed question: the engineering half is closed here; the residual founder/legal/clinical half is restated as a question answerable in one sitting without technical background (§TD3, §TD4).
3. States what is now unblocked (§TD5) and where the frozen documents contain tensions no technical decision can dissolve (§TD5.3).

TD0.2 On ownership

Several §10 rows name "Minni + eng" as owner. Where the substance of the row is engineering judgement (the stack, the enrolment mechanics, threshold encoding, haptics feasibility), this document takes the position that the decision is engineering's, makes it, and marks it CLOSED (technical). Minni retains a veto over anything in this document, as she does over everything — but her sign-off is not a precondition for starting build on the CLOSED items. The Phase 0 item-1 working session (v4 §11) ratifies the product-shape provisionals; it does not need to re-litigate infrastructure.

Conversely, nothing here touches what is genuinely hers or external: programme structure, module content, authored copy, positioning, pricing, market; DPIA, controller/processor, safeguarding copy and vocabulary, clinical validity of thresholds. Those remain OPEN and are restated in §TD3/§TD4 so they can be cleared in, at most, two sittings (one for Minni, one for legal/clinical).

---

TD1. Disposition table — all 35 open questions

Statuses: CLOSED (technical) — decided here, build may start. SPLIT — engineering half closed here; residual named and re-stated in §TD3/§TD4. OPEN — Minni / legal / clinical — not an engineering decision; restated in §TD3/§TD4. Two v4 rows (OPEN-17, OPEN-23) were already dispositioned in v4 itself and are listed for completeness only.

Tally: 5 closed outright (OPEN-19, OPEN-24, OPEN-BR-04, OPEN-BR-05, OPEN-BR-07), 8 split with the engineering half closed (OPEN-05, -06, -07, -10, -14, -15, -22, -26, -27 — nine, counting OPEN-27), and the remainder left open because they genuinely belong elsewhere — every one of them is content, programme shape, positioning, pricing, legal posture, or clinical validity.

---

TD2. Architecture Decision Records

Format per ADR: Decision · Closes / gives effect to · Alternatives and why they lost · Forced or constrained by · Risks and revisit triggers · Cascades.

---

ADR-01 — Technology stack, hosting, and EU residency

Closes OPEN-24. Resolves the dependency in OPEN-BR-07. Unblocks §11 Phase −1 item 0c and Phase 1 item 7.

A. Decision

TypeScript end-to-end, PWA-first, Supabase as the data platform, one EU-hosted API service. Concretely:

Monorepo layout (Phase −1 item 0d):

minimente/
├── apps/web          # PWA client
├── apps/api          # Hono service (the five §9.1 modules)
├── packages/content  # content source (YAML) + Zod schemas + publish pipeline + index build
├── packages/rules    # deterministic rule engine, shared client+server (AD-BR-03) + golden files
├── packages/shared   # types, API contracts (Zod), i18n keys
└── supabase/         # SQL migrations, RLS policies, pgTAP tests, seed

Initial dependency set — the package manifest an engineer can act on:

• apps/web: react, react-dom, typescript, vite, vite-plugin-pwa, workbox-window, @tanstack/react-router, @tanstack/react-query, zustand, dexie, minisearch, i18next, react-i18next, @radix-ui/react-dialog, @radix-ui/react-radio-group, @radix-ui/react-progress, @radix-ui/react-toast, tailwindcss, @supabase/supabase-js, zod
• apps/api: hono, @hono/node-server, pg, kysely (typed queries; migrations are SQL-first via the Supabase CLI), pg-boss, web-push, jose, zod, @sentry/node
• packages/content: zod, yaml, minisearch, tsx
• packages/rules: zero runtime dependencies by design (pure TS — AD-BR-03's client/server-identical evaluation depends on this)
• Dev/CI: vitest, @testing-library/react, playwright, @axe-core/playwright, eslint, prettier, pnpm; pgtap extension in the database (ADR-14)

B. Alternatives and why they lost

• React Native (Source D's other option). Rejected for v1: it makes web the second-class citizen when the primary usage context is a desk (§2.2 "work-integrated"), requires either a parallel web renderer or react-native-web compromises (against AD-02's "do not build separate content renderers"), and buys native capabilities (push, haptics) that the Capacitor path delivers later against the same codebase. Source D itself said "start with PWA".
• Next.js instead of Vite. Rejected: this is an authenticated app behind a login, not a content site — SSR renders personal data server-side for no SEO or first-paint benefit, complicates the offline-first service-worker story (NFR-PLAT-04), and adds a server rendering tier whose region would also need pinning. A static shell + client render is simpler and strictly better for offline.
• Firebase. Rejected: no RLS-equivalent enforcement in a relational model (NFR-SEC-04 wants the database to enforce the promise), weaker EU-residency story per component, and "Google reads the workforce's mental-health usage" is exactly the optics problem NFR-PRIV-04 exists to kill.
• Self-hosted Postgres (Hetzner) + hand-rolled auth. Strongest on sovereignty; rejected for v1 on velocity and on auth risk (building magic-link auth from scratch for special-category data is unforced risk). Recorded as the fallback if the DPIA (OPEN-11) rejects Supabase's sub-processor chain — the schema, RLS policies, and API are all portable Postgres, which is deliberate.
• AWS-native (RDS + Cognito + Lambda). Capable, EU-pinnable, and materially heavier to operate for a team of ~1 engineer; Cognito's UX for magic links is poor. Rejected on ops weight.
• Supabase Edge Functions instead of a Node service. Rejected for the sensitive path: edge execution's residency story is weaker than a region-pinned container, and the service needs long-lived workers (pg-boss) anyway. Edge functions remain available for latency-insensitive glue if ever wanted; nothing depends on them.
• Redis/BullMQ for scheduling. Rejected: one more stateful store to pin to the EU and back up. pg-boss keeps jobs in Postgres, transactional with the data they act on. Revisit only at a scale the pilot will not reach.

C. The parts of OPEN-24 the PRD demanded be addressed explicitly

1. RLS as the enforcement mechanism. Supabase is Postgres with RLS native; the anonymity promise is enforced as declarative policies in supabase/ migrations, tested in CI (ADR-02, ADR-14). This is the single strongest reason for the choice: NFR-SEC-04's "technically incapable" is delivered by the database engine, not by API discipline.
2. EU region for every component — enumerated in the table above. The one globally-distributed component (Cloudflare CDN) carries only the app shell and published content — no personal data ever transits it; all authenticated API traffic terminates in Frankfurt/Netherlands. Client IP addresses do touch Cloudflare (as they touch any CDN); this is disclosed in the sub-processor register below for the DPIA to assess.
3. Sub-processor register for the DPIA (OPEN-11 input):

4. iOS Web Push — the material risk to FR-NOT-03, stated plainly. On iOS/iPadOS, Web Push works only for web apps installed to the Home Screen, and iOS offers no programmatic install prompt — the user must perform a manual Share → Add to Home Screen flow that most users have never done. A daily-reminder feature (FR-NOT-03) whose delivery on the platform half the workforce carries depends on an unprompted manual install is a real product risk, not a footnote. Mitigations in v1: a guided, illustrated install flow shown once on iOS; email as the suggested default reminder channel on non-installed iOS (FR-NOT-02's fallback doing real work); the in-app inbox always. Trigger condition for native shells (the decision OPEN-24 was asked to state): if, after 4 weeks of pilot, the proportion of iOS users with a working push channel (installed + permission granted) is below half the Android/desktop rate, or iOS activation lags in a way attributable to install friction, then Capacitor shells are built in the following phase. Capacitor wraps the existing PWA (AD-02 preserved: one codebase, one renderer) and simultaneously unlocks haptic pacing (the Vibration API is absent from Safari on all Apple platforms — FR-BR-36) and reliable background notification delivery. This closes OPEN-BR-07: haptics are feature-detected, available on Android Chrome in v1, absent on iOS until the shells land, and no content instructs "feel the taps" unless the mode is active. One further risk on the record: Apple's 2024 DMA-era wobble over Home-Screen web apps in the EU was reversed, but the EU market (OPEN-09) means platform-policy risk on installed PWAs is non-zero; the Capacitor path is also the hedge against that.
5. AD-07 and AD-09 realisation — specified in ADR-06 and ADR-08 respectively.

D. Forced or constrained by

AD-02 (PWA-first, one codebase), AD-04 (RLS), NFR-SEC-03 (magic link / SSO), NFR-SEC-04 ("technically incapable"), NFR-PRIV-08 (EU residency, documented sub-processors), NFR-PLAT-01/04 (parity, offline), NFR-A11Y-01 (mature accessible primitives — hence Radix), FR-BR-36 (haptics reality), AD-BR-03 (rule engine identical client/server — hence shared pure-TS package).

E. Risks and revisit triggers

• Supabase sub-processor chain fails DPIA review → migrate to self-hosted Postgres + a self-hosted auth (the portable-Postgres discipline above is the insurance; auth is the only real migration cost).
• iOS push under-delivers → Capacitor trigger in §C.4.
• Railway EU guarantees prove insufficient in contract review → the API is a stateless container; move to Fly.io fra/ams or Scaleway in a day.
• Content corpus outgrows client-side search → AD-09's own revisit clause governs; not expected within several programmes.

F. Cascades

Unblocks Phase −1 (scaffold), Phase 1 item 7 (content schema — ADR-04), item 8 (data model/privacy design — ADR-02/07); resolves OPEN-BR-07; determines the concrete form of ADR-02 through ADR-14.

---

ADR-02 — Tenancy, RLS policy design, and the anonymity enforcement model

Closes OPEN-19. Closes the engineering half of OPEN-22 (per-org configuration data model). Gives effect to NFR-SEC-04, NFR-PRIV-05/10, FR-ORG-01…03, AD-04.

A. Decision

The employer-anonymity promise is enforced as Postgres RLS policies plus a physically separate aggregate path. The org-admin role has no read path to any user-level table — not a filtered path, no path.

1. Roles and claims. JWTs carry user_id, org_id, role ∈ {member, org_admin} as custom claims (set via Supabase auth hook). The API service passes the user's JWT through to Postgres so RLS applies even to API-mediated queries — the service does not run user reads as a superuser. A distinct service_role is used only by the aggregation job and the publish pipeline, never by request-serving code paths.
2. User-data tables (users, enrollments, session_states, daily_checkins, screen_responses, module_completions, toolkit_items, action_plan_entries, emergency_tool_events, right_now_events, reminders, personalisation_events, programme_feedback, safeguarding_events, exercise_outcomes, breathing_recommendation_events): single policy pattern — user_id = auth.uid() for select/insert/update; no policy exists for org_admin on any of these tables, so default-deny applies. "Technically incapable" (NFR-SEC-04) is therefore a property of the engine, verified by CI (ADR-14: pgTAP tests enumerate every user table and assert org_admin selects return zero rows / permission errors).
3. The aggregate path is a separate table, not a view. A nightly service_role job (pg-boss) computes rollups into org_aggregates (org_id, iso_week, metric, value, cohort_n) — and the k≥10 gate (NFR-PRIV-05) and weekly-or-coarser granularity (NFR-PRIV-10) are enforced at write time by the job: rows with cohort_n < 10 or sub-weekly granularity are never written, so no query, bug, or future dashboard feature can reach around the gate — the ungated numbers do not exist on the org-admin side of the wall. org_admin has a select policy on org_aggregates (own org only) and on nothing else. Free text never enters the rollup job's queries at all (NFR-PRIV-06 by construction — the job's SQL selects only numeric/enum columns).
4. Seat management without identity leakage (the OPEN-19 mechanism). Enrolment is by org invite code (default) or verified work-email domain (org option). Claiming a seat creates a pseudonymous users row; the user may register with any email address, including a personal one — the invite code, not the email domain, is what proves seat entitlement. Email lives only in Supabase's auth schema; the application schema stores auth_identifier_hash only (§7.4). org_seats.claimed_by_user_id is readable by no org-facing role: org admins see seat counts (claimed/unclaimed/revoked) via org_aggregates, and revoke by seat id, not by person. The org therefore knows how many seats are active, never which employee is which account. This resolves the anonymity-vs-licensing tension: licensing needs countable seats; it never needed identifiable ones.
5. Per-org configuration (OPEN-22 engineering half). organizations.crisis_resources_config (already in §7.4) is given a concrete schema, validated by Zod at write time: { country_key, resources: [{label, phone?, url?, description}], occupational_health?: {label, phone?, url?} }. Country-default resource sets (Finland: 112, MIELI Crisis Helpline; UK: 999, Samaritans) ship as content data; the org config overlays them. This is the destination table for PR-03 (ADR-09) and NFR-SAFE-02's signposting card. The admin UI to edit it is Phase 3 (unchanged); until then it is set at contract time by Minimente staff.

B. Alternatives and why they lost

• Security-definer views filtering user data for org admins. Rejected: a filtered path is a path — one bad WHERE clause from a breach of the core promise. No path at all is auditable at a glance and testable in CI.
• k-anonymity enforced at query/dashboard time. Rejected: enforcing at write time means the sub-threshold numbers are never materialised where an org-side credential could reach them. Belt over braces.
• Employer-verified identity (work email required). Rejected: forcing work email weakens the perceived promise for exactly the user (P2 "Jussi") who fears being found out, and gains nothing — the invite code already proves entitlement.

C. Forced or constrained by

NFR-SEC-04 (the load-bearing requirement), NFR-PRIV-04/05/06/10, FR-ORG-01…03, NFR-SAFE-05 (no employer notification — the aggregate wall is also why safeguarding events can never leak), §3.1 (data model must not make an org-less user impossible — org_id is nullable by design for the future B2C user).

D. Risks and revisit triggers

• Custom-claim plumbing is the fiddliest part of Supabase auth; it gets a dedicated integration test suite (ADR-14).
• If a future feature genuinely needs org-side per-user data (it should not), it must come back through this ADR — the default answer is no.
• The k≥10 gate means a small pilot org sees an empty dashboard for weeks. That is by design (FR-ORG-02 turns it into a trust asset) but must be set as a sales expectation — noted in §TD5.3.

E. Cascades

ADR-14 (RLS test suite), ADR-09 (safeguarding config destination), Phase 1 item 8, Phase 3 item 16.

---

ADR-03 — Identity and authentication

Completes the OPEN-19 closure. Gives effect to NFR-SEC-03.

A. Decision

Passwordless email magic link via Supabase Auth in v1; org SSO (SAML) deferred to Phase 2 as already scoped in §4.2. Specifics: magic-link emails sent through Brevo (custom SMTP) from a neutral sender identity (no "mental health" in sender name or subject — NFR-PLAT-05 applies to inboxes too, which may be work inboxes); access tokens ~1 hour, rotating refresh tokens; per-device sessions with a user-visible device list and revocation (NFR-SEC-03); API-level rate limiting on auth endpoints (the §9.1 "gateway" responsibilities — authn/z, rate limiting — are middleware in the Hono service for v1, not a separate gateway product).

B. Alternatives and why they lost

• Passkeys. Genuinely better security and UX where supported; rejected as the primary v1 method because cross-device support in workplace fleets is still uneven and NFR-SEC-03 names magic-link/SSO. Recorded as the first post-pilot auth addition.
• Password auth. Prohibited by NFR-SEC-03; also the wrong risk profile for this product.
• SSO in v1. Rejected: SSO binds the account to the employer's IdP — exactly the wrong default for the anonymity promise. When Phase 2 adds it for orgs that demand it, onboarding copy must state what the IdP operator can and cannot see; flagged forward to the DPIA (§TD4 L1).

C. Risks

Magic link means the system holds an email address — the product is pseudonymous with respect to the employer, not anonymous in the absolute. Copy must never say "anonymous" unqualified; NFR-PRIV-04's actual wording ("your employer cannot see…") is the honest and correct formulation. Flagged in §TD5.3 because marketing will be tempted.

---

ADR-04 — Content pipeline: source of truth, schema encoding, publish validation

Gives effect to FR-CORE-01/02/03/06, NFR-I18N-01/02, FR-SRCH-07, FR-BR-48/49. Closes the engineering halves of OPEN-06 (count-independence) and OPEN-08 (zero-cost note). Unblocks Phase 1 item 7.

A. Decision

Git is the CMS for v1. Content lives in packages/content as YAML files — one per module, exercise, rule set, vocabulary, and locale — validated by Zod schemas that encode §6.0's screen-type contracts, §7.4's exercise shape, and A8.2's breathing_config. A publish pipeline (CI job) performs, in order:

1. Validation: screen types against the §6.0 library; every EX_* screen references an existing exercise (FR-CORE-06); taught_exercise_id present per module (FR-CORE-07); locale completeness per NFR-I18N-02; FR-BR-49's rule checks (no non-final exercise referenced, no hold-protocol recommended for high-activation states, every need-state has a terminal fallback, no unreferenced reason_key); scale-version pinning (ADR-10); the §11 item-18 content QA checks (no placeholder copy, no mojibake — non-UTF-8-sane glyph detection — no Finnish strings in an EN bundle) run here as blocking CI, not as a manual read-through.
2. Build: compile to an immutable, hash-versioned JSON content bundle per locale, containing only copy_status = final items for release channels (placeholder content is included only in the internal channel — FR-CORE-03), plus the MiniSearch index built at publish time over released content only (FR-SRCH-03, ADR-08) and the crisis-term list (ADR-09).
3. Activate: upload the bundle to Cloudflare Pages/static storage; write a content_versions row; clients discover the new version via a version endpoint and refresh their cache. Rollback = re-activate the previous row.

Emergency Tools are content rows, not code (FR-ET-08): the 6-vs-7 tool-count question (OPEN-06) has zero engineering coupling — the drawer renders whatever exercises carry the emergency_tool surface tag, so Minni's count decision and each script's arrival are pure content publishes. Likewise mood (OPEN-08): adding a mood item to the check-in is one content field plus daily_checkins.extra — no schema change, no release; the decision is purely whether the pitch keeps the word.

B. Alternatives and why they lost

• Headless CMS (Sanity/Contentful/Strapi) now. Rejected for v1: another sub-processor for the DPIA, another EU-residency question, and the single content author currently works via documents with engineering mediation anyway. Revisit trigger: a second programme in production, or Minni needing to edit without engineering in the loop — at which point an editor UI over the same schema (not a different content model) is the path.
• Content in the database as the source of truth. Rejected: loses diffable review, CI validation, and versioned rollback — the exact disciplines that Source C's placeholder-export accident (§6.3) shows this project needs.
• JSON instead of YAML for authoring. Trivial; YAML wins on multi-paragraph copy readability. The compiled bundle is JSON regardless.

C. Risks and revisit triggers

Git-mediated authoring puts engineering in Minni's loop for every copy edit — acceptable at current cadence, and the revisit trigger is stated above. The validator set must grow with every incident: any content defect that reaches a release channel becomes a new blocking check the same week.

D. Cascades

ADR-08 (index build lives here), ADR-09 (vocabularies are content files here), ADR-10 (scale-version pinning), ADR-13 (rule content), ADR-14 (content CI).

---

ADR-05 — Offline and sync

Gives effect to NFR-PLAT-04, FR-CORE-05, FR-PROG-02/03, FR-ET-06, FR-SRCH-05 (offline search).

A. Decision

• Precache (Workbox, at service-worker install/update): app shell; the current content bundle — which by construction contains today's module, the full exercise library, all Emergency Tools, the search index, the crisis-term list, and the signposting resources (org config cached on first authenticated load). NFR-PLAT-04's floor ("today's module and all Emergency Tools") is exceeded deliberately: the whole released bundle is small, and partial caching is a bug class we decline to own. Audio assets (when they exist, ADR-12) are runtime-cached on first play, and today's module's audio is prefetched on Wi-Fi (NFR-PLAT-06).
• Writes: an outbox in Dexie. Every mutation gets a client-generated UUID and is written locally first, then synced; the API upserts idempotently on that UUID. Conflict resolution is last-write-wins per field with server timestamps, exactly as NFR-PLAT-04 specifies. session_states.draft_answers autosaves on blur/navigation (FR-PROG-03) into the outbox.
• FR-CORE-05 reconciliation, stated so no one trips on it: "every screen transition shall persist state server-side" is implemented as write-through when online, queue-then-sync when offline. The server is the source of truth for cross-device resume; the local copy is the source of truth only while offline. This is the only reading under which FR-CORE-05 and NFR-PLAT-04 can both be true.
• Reads for the personal search index (FR-SRCH-01b): Toolkit items and durable outputs are cached in Dexie on sync; the personal MiniSearch index is built and incrementally updated on-device over that cache (ADR-08).
• Offline rule evaluation (breathing recommender, personalisation) runs the shared packages/rules engine locally; the server re-evaluates on sync and is authoritative on conflict (AD-BR-03, verbatim).

B. Alternatives and why they lost

• CRDT/sync frameworks (Replicache, ElectricSQL, PowerSync). Rejected: the write patterns here are simple per-user upserts with a spec-mandated LWW-per-field policy; a sync framework adds a dependency (and possibly a sub-processor) to solve conflicts the domain barely has. Revisit if true multi-device concurrent editing ever matters (it does not for a single-user journaling flow).
• localStorage. Not serious for structured data at this size; Dexie/IndexedDB from day one.

C. Risks

Safari's storage-eviction policies for non-installed web apps can purge IndexedDB under storage pressure after prolonged disuse — one more reason the iOS install flow (ADR-06) matters. The outbox is flushed eagerly and the server holds truth, so eviction loses at most unsynced drafts; the sync interval is aggressive (on visibility change and every mutation) to shrink that window.

---

ADR-06 — Notifications, timers, and the wall-clock architecture

Gives effect to AD-07, FR-M7-05/06, FR-NOT-01…07, FR-BR-32. Implements the iOS strategy and native trigger declared in ADR-01 §C.4.

A. Decision

Two timing regimes, explicitly separated — this is the concrete realisation of AD-07:

1. Wall-clock timers (Focus Window, reminders, daily nudge) are server-anchored. Starting a Focus Window POSTs to the API, which stores started_at, returns authoritative ends_at and server_now; the client renders the countdown from a monotonic clock (performance.now()) plus the server-time offset, so backgrounding, tab suspension, clock skew, and device sleep cannot corrupt it. The completion notification is scheduled server-side (pg-boss job at ends_at) and delivered as push — so it fires even if the tab is dead; the client additionally checks for elapsed timers on every resume/visibility change (the in-app path when no push channel exists). Ending early cancels the job (FR-M7-06: a valid outcome, not a failure).
2. Sub-second pacing (breathing cycles) is purely local, driven by performance.now() (FR-BR-32). Server anchoring at this granularity is meaningless and harmful; AD-07's reasoning — never trust setInterval across backgrounding — applies, its mechanism (server anchor) does not. Recorded so no one "fixes" the pacer with network calls.

Delivery pipeline (FR-NOT-02's channels made concrete): the Notification module resolves each due reminder to channels in order — Web Push subscription if present and live → email via Brevo if opted in → in-app inbox always. Quiet hours and timezone (FR-NOT-05) are computed in the user's timezone at schedule time and re-checked at fire time (DST safety). Reminder bodies default to generic copy; user-authored content (e.g. boundary_statement) is embedded only on explicit opt-in (FR-NOT-04), and such bodies are not sent via email at all in v1 — mail sits unencrypted in a possibly-work inbox; push (E2E-encrypted to the device, RFC 8291) and in-app are the only carriers for user-authored text. Nothing in any payload names mental health (NFR-NOT-07 / NFR-PLAT-05 — neutral app name and copy in notification surfaces).

iOS posture and the native trigger: per ADR-01 §C.4 — guided install flow, email-default suggestion on non-installed iOS, and the measured Capacitor trigger. Restated here because this ADR is where the risk lives: FR-NOT-03 (daily reminder) is the requirement most at risk on the chosen stack, the mitigation is the fallback chain above, and the escape hatch is measured, not vibes-based.

B. Alternatives and why they lost

• Client-scheduled local notifications. The web platform cannot do this reliably (no Notification Triggers API in production); rejected as the primary mechanism, which is precisely AD-07's point.
• Third-party push orchestration (OneSignal etc.). Rejected: an unnecessary sub-processor with deep behavioural data access, in the one product category where that is disqualifying. web-push + pg-boss is a few hundred lines.

C. Risks and revisit triggers

Push-subscription rot (expired endpoints) is routine: subscriptions are health-checked on delivery failure and the user is prompted to re-enable on next open. The Capacitor trigger is the structural revisit. Email deliverability for magic links is operationally critical from day one (before push exists at all) — Brevo domain authentication (SPF/DKIM/DMARC) is a Phase −1 setup task, not an afterthought.

---

ADR-07 — Free-text encryption, key separation, and telemetry scrubbing

Gives effect to AD-05, NFR-SEC-01/02/05/06, FR-DATA-02.

A. Decision

• Application-layer envelope encryption in the API service for all user free text (screen_responses.value_text where is_sensitive, daily_checkins.optional_text, the thought-dump journal, reflection_letter, toolkit_items free-text payloads, reminders.body_override): AES-256-GCM via node:crypto; per-user data keys (DEKs) wrapped by a versioned master key (KEK) that lives only in the API runtime's secret store (Railway), never in the database or its backups. A database dump, a Supabase console session, or a stolen backup therefore yields ciphertext for every reflection ever written — this is AD-05's "narrower blast radius" made concrete, over and above Supabase's at-rest disk encryption (NFR-SEC-01, which alone would not survive a console-level read).
• Key rotation (NFR-SEC-02): KEK versioning — new writes wrap with the new KEK; background re-wrap of DEKs; no bulk data re-encryption needed.
• Break-glass (NFR-SEC-05): no human has standing decrypt access. Staff access to plaintext free text requires a logged break-glass invocation (justification string, actor, target, timestamp) written to an append-only admin_access_log before the decrypt path will run.
• Telemetry scrubbing (NFR-SEC-06): Sentry EU with an allowlist beforeSend — error class, stack, release, route pattern (never URL with params), internal user id only. Request bodies, breadcrumb input values, and console args are dropped wholesale. No session replay. No third-party analytics SDK exists to leak anything (ADR-01); product metrics come from our own event tables. Search queries never appear anywhere by construction (FR-SRCH-05 — they never leave the device).

B. Alternatives and why they lost

• True end-to-end (client-held keys). The strongest promise — and incompatible with the spec: cross-device resume (FR-CORE-05) with passwordless auth requires server-recoverable keys or a key-escrow UX (recovery codes) that this audience will lose. Also forecloses NFR-SAFE-04 option 3 forever, which is Minni's choice to foreclose, not ours. Recorded honestly: the product's claim is "encrypted, with audited break-glass access", not "we cannot read it" — onboarding copy must match (§TD5.3, and it constrains NFR-SAFE-04's option-1 wording "no one reads what you write", which stays true as a statement of practice backed by the audit log, not of impossibility).
• pgsodium / in-database TCE (Supabase Vault). Rejected: keeps key material adjacent to the data it protects, weakening exactly the console-read scenario AD-05 targets.
• Cloud KMS (AWS KMS) for the KEK now. Better custody than env secrets; adds an AWS control-plane dependency and sub-processor surface. Deferred with a trigger: before pilot go-live, if the DPIA or security review (Phase 3 item 17) asks for HSM-backed custody, the KEK moves to a KMS — a one-file change by design (key provider is an interface).

C. Cascades

Server-side free text is ciphertext → any future server-side scanning (NFR-SAFE-04 option 3) would need an explicit decrypt pipeline — an intentional speed bump that makes option 3 a deliberate act, never a drift. Personal-index search remains possible because the client holds plaintext after authenticated fetch (ADR-08). Export (NFR-PRIV-07) decrypts server-side through the same audited path, actor = the user.

---

ADR-08 — Client-side search: concrete build

Gives effect to AD-09, FR-SRCH-01…07, FR-TK-10, FR-BR-45. Closes the engineering half of OPEN-27.

A. Decision

• Engine: MiniSearch — small (~7 KB gz), serialisable index, fuzzy/prefix matching, zero server anywhere in its path.
• Content index is built at publish time by the ADR-04 pipeline over released, locale-matched content only (titles, psychoeducation bodies, exercise entries, extension modules) plus the OPEN-27 synonym vocabulary — authored as a content file mapping everyday phrases ("catastrophising", "can't switch off", "wound up") to target modules/exercises, exactly the FR-SRCH-02 shape; breathing tags per FR-BR-45 land in the same file, not a second artefact. The serialised index ships inside the content bundle and is versioned/invalidated with it (FR-SRCH-07).
• Personal index is built on-device over Dexie-cached Toolkit items and durable outputs (FR-CORE-09's destinations), incrementally updated on sync. Free-text reflections and the thought-dump journal are excluded unless the user opts in (FR-SRCH-01) — the opt-in flag lives in local settings and the index is rebuilt on toggle.
• Query path: normalise → crisis-term check first (ADR-09's shared evaluator; on match, pin the signposting card above whatever results render — NFR-SAFE-07) → query both indexes in-memory → render grouped results (Modules · Exercises · My Toolkit · Extensions), each deep-linking, exercises directly runnable (FR-SRCH-03). Queries are held in component state only: never in a URL, router state, history entry, log, or event (FR-SRCH-05 — enforced by there being no code path that could transmit them; no server search endpoint exists, and ADR-14 adds a CI grep-level guard that none appears).
• Works offline for free, because both indexes are local (NFR-PLAT-04).

B. Alternatives and why they lost

• FlexSearch / Lunr / Fuse.js: comparable; MiniSearch wins on serialisation ergonomics and maintenance state. Not load-bearing — swappable behind a thin interface.
• Postgres FTS or a hosted search service: prohibited outright by AD-09/FR-SRCH-05. Recorded only to say so.
• Embeddings-based retrieval: prohibited (FR-SRCH-02, §4.3). The synonym vocabulary is the deliberate, human-authored substitute — which is why OPEN-27's authoring matters and stays open for Minni + clinical.

C. Risks

Retrieval quality is exactly as good as the OPEN-27 vocabulary — an authoring dependency, stated in FR-SRCH-02 and unchanged here. Search ships dark until the vocabularies exist (§11 item 15a), but everything in this ADR is buildable now against a stub vocabulary.

---

ADR-09 — Safeguarding and personalisation rule mechanics

Closes the engineering halves of OPEN-10 and OPEN-07. Gives effect to NFR-SAFE-01…07, FR-PR-01…03, FR-SRCH-06, FR-BR-25/26, PR-01…03 encoding.

A. Decision

Everything §8.3 needs that is mechanism is decided and buildable now; everything that is copy, vocabulary, or clinical validity is packaged as three precise external asks (§TD3 Q13, §TD4 C1/C2).

1. One signposting component ("Need urgent help?") rendering the org-overlaid crisis resources from ADR-02 §A.5, mounted on: Home, Emergency Tools, "Right now", every breathing surface (FR-BR-26.2), the search crisis-pin (NFR-SAFE-07), and the onboarding disclaimer flow (NFR-SAFE-01). One component, one config source, no copies to drift.
2. Rules as data, one engine. PR-01/02/03 and NFR-SAFE-03 are rows in a personalisation_rules content set structurally identical to A8.2's breathing_recommendation_rules (ordered, declarative JSONB conditions, no code), evaluated by the shared packages/rules engine — client-side for offline, server authoritative (AD-BR-03). Firings log per FR-PR-03 / NFR-SAFE-06 (de-identified, rule-id-only for safeguarding).
3. Distinct-day evaluation (NFR-SAFE-03 v4 amendment): the engine evaluates check-in predicates over distinct calendar days in the user's timezone, implemented once in the engine, property-tested (multiple same-day completions collapse to one day's signal).
4. PR-03 encoded, not invented: condition shape stress_rating ≥ S on ≥ N distinct days of the last M check-in days, shipped with placeholder values (S=7, N=3, M=5) that are flagged clinically_unreviewed: true in content data — the publish pipeline refuses to include an unreviewed rule in a release-channel bundle, so the clinical sign-off (§TD4 C2) is structurally enforced, not remembered. Destination: the tier-aware signposting card (org occupational-health + public resources) per §7.3's own recommendation — the Tier-1 contradiction is resolved by pointing at the ADR-02 org config, which exists precisely for this.
5. The crisis-term evaluator is built once and built regardless. A local, normalised term-list matcher in packages/rules, consuming a content-data term list (OPEN-27b). It is required anyway for search (FR-SRCH-06/NFR-SAFE-07, which is independent of the NFR-SAFE-04 choice — v4 says so explicitly). Consequence, and this materially reframes Minni's decision: NFR-SAFE-04 option 2 (client-side keyword prompt on free-text inputs) is the same evaluator wired to input fields — near-zero incremental engineering. Her choice between options 1 and 2 is therefore about the promise wording and governance posture, not cost or schedule; option 3 remains a governance-gated non-option for v1 (§8.3's own warning, reinforced by ADR-07's encryption speed bump). The evaluator runs on-device only; no text or match content is transmitted; on match it renders the signposting card and logs rule-id-only per NFR-SAFE-06.
6. Employer-notification impossibility (NFR-SAFE-05): safeguarding tables sit behind the ADR-02 wall — no org-side read path exists, and the aggregation job's SQL never touches them. Verified by the ADR-14 pgTAP suite.
7. FR-BR-25/26's declared breathing signals emit into safeguarding_events in the de-identified form, exactly as A5.6 specifies — data ready for whenever §8.3's detection thresholds are clinically designed, no retrofit.

B. Alternatives and why they lost

• Hardcoding thresholds. Rejected: FR-PR-02 mandates rules-as-data, and the OPEN-26 scale coupling (thresholds pinned to scale version — ADR-10) only works if rules are data the validator can check.
• Server-side crisis-term evaluation. Rejected: transmits sensitive text, violating FR-SRCH-05's spirit and pre-empting Minni's NFR-SAFE-04 choice by architecture. Local-only preserves all three options.

C. Cascades

Unblocks Phase 2 item 12 (safeguarding flow before external testing) up to the copy dependency. §TD4 C1/C2 are the only remaining blockers to shipping it.

---

ADR-10 — Check-in control implementation and scale configuration

Closes the engineering half of OPEN-26. Gives effect to NFR-A11Y-02, FR-STD-02, the §7.3/§8.3 scale-coupling notes.

A. Decision

• The check-in control is a tappable segmented scale (Radix radio-group semantics: keyboard-operable, screen-reader-announced, numeric entry alternative, 44×44pt segments — NFR-A11Y-02/07) whose point count comes from content configuration (scale_version: "10pt-v1"), not code. Both 5- and 10-point variants are built; the Phase 2 internal test (§11 item 13) runs both, as v4 requires.
• Default pending the test: 10-point — v4's own stated default, because it leaves every threshold in §7.3 and §8.3 untouched.
• Arithmetic rescale is prevented by construction: every rule set (ADR-09) declares the scale_version its thresholds were derived against, and the publish pipeline rejects any bundle whose active scale and rule scale-versions disagree. If the test picks 5-point, the build fails until clinically re-derived thresholds (§TD4 C3) are published — engineering cannot quietly divide by two, which is exactly the prohibition v4 wrote in prose, now enforced by tooling.

B. Residual

The 5-vs-10 choice stays with Minni + design after testing (§TD3 Q16); the re-derivation, if needed, with clinical (§TD4 C3). Nothing further from engineering.

---

ADR-11 — Iconography and asset policy

Closes the engineering half of OPEN-05. Gives effect to NFR-A11Y-06, §6.3's icon recommendation.

A. Decision

Lucide as the product icon set (MIT, consistent stroke style, tree-shakeable React components), with aria-label/alt text equal to the semantic category name; raw emoji are banned from rendered content — the ADR-04 validator rejects emoji in icon-designated content fields, making the §6.3 recommendation enforceable rather than advisory. The M14 Recovery Wheel gets eight Lucide glyphs mapped from the §6.3 semantic-intent table; the M15 celebration is a static illustration with a subtle animated variant gated on prefers-reduced-motion (NFR-A11Y-05) — no confetti-by-default, consistent with the product's visual restraint (NFR-BR-07's register, applied product-wide). Alternatives: Phosphor/Heroicons — interchangeable; Lucide chosen for breadth and maintenance. Residual for Minni + design (§TD3 Q6): confirm the eight meanings (the mojibake reconstruction) and the celebration art direction — the technology carries whatever she confirms.

---

ADR-12 — Audio-optional shipping

Closes the engineering half of OPEN-15. Gives effect to AD-06, NFR-A11Y-03, UX-05, FR-BR-51.

A. Decision

v1 ships text-and-pacer only, product-wide — extending FR-BR-51's rule for breathing to every audio-guided exercise. The architecture already treats audio as an optional per-exercise asset (exercises.audio_asset_url NULL, AD-06): the exercise runtime renders transcript + pacer always, and audio controls iff an asset exists and the user opts in (no autoplay — FR-M1-04). Adding audio later is a content publish per exercise — file to Supabase Storage, URL on the row, zero code. The "headphones recommended" hint (NFR-PLAT-03) renders only when an asset exists. This is fully sanctioned by the spec — UX-05 makes audio never-required, and OPEN-15's own proposed resolution names text-only as "fully viable". Residual for Minni (§TD3 Q8): whether/when to record, voice, languages, budget — a production plan with no engineering dependency and no launch coupling.

---

ADR-13 — Breathing recommender: v1 scope and thresholds

Closes OPEN-BR-04 and OPEN-BR-05. Gives effect to FR-BR-07…18, FR-BR-50, AD-BR-03.

A. Decision

v1 ships the safety and evidence-default layers in full, and defers the history-based layers to post-pilot. All capture ships now. Concretely, of §A4's ordered layers:

• exercise_outcomes ships complete from day one (cheap, free-text-free per FR-BR-46, and it is what makes the deferral decision measurable — §A10's own proposed resolution).
• All thresholds (OPEN-BR-05) — the ≥2, 60%, 80%, 180 days, 8 — ship as content data at the addendum's stated defaults, carrying an explicit evidenced: false flag; the deferred layers' thresholds are present but dormant. They are revisited against pilot data (§11 item 22) and are never presented as tuned — the flag exists so no one can later mistake a default for a finding.
• The golden-file suite (FR-BR-50) ships with the v1 rule set from the first commit; enabling the deferred layers post-pilot is a rule-content publish plus golden-file extension, not a release.

B. Why this is engineering's call, and the honest caveat

The rules engine, data model, and player are identical under either scope — what this decides is build sequencing and claim surface, which is engineering judgement: fewer active rules means a smaller test matrix before pilot, and no implicit product claim that history-based recommendation improves anything (the addendum was explicit that it cannot claim that). The product-visible consequence — users will not see "because it worked for you before" until post-pilot — is flagged to Minni in §TD3 Q17; if she wants that surface at launch anyway, the cost is small and this ADR flips without architectural consequence. That veto path is stated here so the closure is honest rather than territorial.

---

ADR-14 — Test and CI strategy

Gives effect to FR-BR-50, §11 item 18, NFR-A11Y-01 verification, NFR-SEC-04 verification, AD-BR-03's testable determinism.

A. Decision

GitHub Actions pipeline, blocking on every merge: lint + typecheck → unit (Vitest) → rules golden files → content validation (the full ADR-04 §A.1 battery) → database tests → E2E → build.

The suite's four load-bearing, non-generic components:

1. RLS negative tests (pgTAP, against an ephemeral local Supabase): for every user-data table, assert the org_admin role cannot select, insert, update, or delete; assert a member cannot read another user's rows; assert org_aggregates never contains a row with cohort_n < 10 or sub-weekly granularity (belt-tests on the ADR-02 write-time gate). A new user-data table without its pgTAP entries fails CI via a catalog-diff check — the anonymity promise is regression-tested, not remembered.
2. Rules golden files (FR-BR-50, extended to §7.3/§8.3 rules): fixed (history, need-state, check-in) inputs → expected (action, reason-key) outputs, versioned with the rule content; any behavioural rule edit must change the golden file in the same commit. Plus a client/server determinism property test: the same engine build runs the same fixtures in a browser context and in Node and must agree (AD-BR-03).
3. Content CI (§11 item 18, automated): placeholder-copy detection, mojibake detection, locale leakage, FR-BR-49 rule validation, scale-version pinning (ADR-10), emoji-in-icon-field rejection (ADR-11), clinically_unreviewed release gating (ADR-09).
4. Accessibility and offline E2E (Playwright): axe-core scans on every screen type; keyboard-only completion of a full session; prefers-reduced-motion asserted to force the visual_reduced pacer with zero animated properties (NFR-BR-05 — tested, not trusted); an offline scenario completing today's module and an Emergency Tool with the network disabled, then syncing (NFR-PLAT-04); a grep-level guard that no search-endpoint call path exists (ADR-08).

---

ADR-15 — Post-programme module revisit semantics

Closes the engineering half of OPEN-14 (FR-POST-04's residual detail).

A. Decision

Implementation default: completed modules are revisitable read-only (the user sees the content and their own answers), and every exercise is re-runnable everywhere, forever (FR-POST-04's unconditional half, via the exercise library — FR-CORE-06). Full module re-runs (a fresh pass writing new responses) are not built in v1; the capability is a content/config flag on the module, so if Minni ratifies re-runs under OPEN-14, enabling them is additive (new module_completions row per pass; historical answers preserved, never overwritten — the data model above already supports it). Rationale: read-only revisit satisfies every stated post-programme need (§7.9), avoids ambiguity about which answers feed the Toolkit and trends, and keeps the OPEN-14 ratification a pure product choice with no schema consequence. Residual for Minni (§TD3 Q3): ratify §7.9 as a whole and say whether re-running a whole module should exist.

---

TD3. Residual questions for Minni

Every question below can be answered in one sitting, without technical background. Where v4 or the addendum made a recommendation, it is restated with its reasoning in one line. Answering Q1–Q7 in one working session is v4's Phase 0 item 1; Q8–Q18 can trail it by days without blocking build.

Q1 — Programme shape (the big one). Should the programme be (a) a 10-session core plus a browse-anytime library of 5 extra topics, unlocked after the core, or (b) a single 15-day sequence as your July content document laid it out? Option (a) — recommended — means the product can launch with only the fully written sessions 1–10; the five unfinished topics arrive later as additions; and the awkward "14-day vs 15-day" wording problem disappears because neither number is used anywhere. You'd also tell us where the closing session (reflection letter, future plan, feedback) belongs: as the finale of the core, or shown when someone finishes. Option (b) means launch waits for all fifteen sessions to be written, and you must also pick one number — 14 or 15 — for every piece of marketing and welcome copy.

Q2 — Pacing. Confirm: sessions unlock in order as each is completed — a keen user may do several in one day; the app suggests spacing but never blocks; nothing is ever labelled "Locked"; missing days carries no penalty. (This replaces the old one-per-calendar-day idea. Everything is built; this is a yes/no.)

Q3 — After the programme. Confirm: once someone finishes, their home screen becomes their Toolkit first, with the quick-help entry, emergency tools, optional light check-ins, and the extras library. And one small extra: should people be able to redo a whole session from scratch (writing fresh answers), or is revisiting what they wrote plus re-running any exercise enough? We've built the second; the first can be switched on later if you want it.

Q4 — The unwritten sessions. Three sub-decisions, in this order: (i) Session 13's topic — is it "Understanding Your Emotional Needs" (your July version) or "Meaning & Motivation" (the March plan)? These are different sessions, and the text is unwritten either way, so you are choosing what to write, not what to rename. (ii) Confirm the final titles for sessions 12, 14, 15. (iii) Then supply the missing text: sessions 12–15 in full, plus session 11's teaching text and its three remaining movement-branch scripts (the breathing branch is now covered by the new breathing library, so it's three, not four). First check whether your earlier draft still exists in your files or Drive history — the export says "keep your current text", which suggests a draft that didn't survive.

Q5 — Quick-help tools. (i) Is the tool list six or seven — is "Progressive relaxation" in or out? (ii) Then author the remaining scripts. Good news: the breathing work already covers "Breathing reset" and "Grounding", so what's left is the thought-dump journal intro, the desk stretch, the safe-place exercise — and progressive relaxation only if you keep it. These tools are visible from day one and the "help me right now" entry can't switch on until they exist, so this is the highest-value short writing task in the project.

Q6 — Icons and celebration. The eight Recovery Wheel categories lost their icons in the export. Confirm the intended meaning of each (our best guesses: Rest 🌿, Connection 🤝, Movement 🏃, Nature 🌳, Creativity 🎨, Learning 🧠, Joy & Play 🎲, Purpose ✨ — we'll render them as proper drawn icons, not emoji), and tell design what the end-of-programme celebration should look like.

Q7 — Small copy calls. (i) Sessions 1 and 2 end with the identical reflection question ("Where did you notice stress in your body today?") — intentional, or should one change? (ii) For each session, pick how it ends: do a tiny action right now / save today's tool / a "when X happens, I'll Y" intention / set a reminder / just an insight. (Reminders should be the exception, not the default.) One pass over the ten-session list.

Q8 — Audio. Version 1 will ship with written guidance and an on-screen pacer, no recorded audio — it's fully usable that way, and the silent-office design means audio was always optional. Your decision is only: do you ever want recorded voice, and if so — whose voice, which languages, and when? Adding it later needs no engineering work.

Q9 — "Mood". The pitch materials promise daily energy, stress, and mood tracking, but no session asks about mood. Either add a mood question to the daily check-in (costs nothing to add — say the word) or drop "mood" from the pitch. Which?

Q10 — Market. Finland first, English-speaking first, or both? This decides which crisis helplines ship by default, which language the missing text gets written in first, and where legal review happens. The product is built translation-ready either way.

Q11 — Money. (i) The three price tiers (€4–8 / €15–30 / €120–300 per user/month) have never been tested with a buyer — validate Tier 1 in the pilot, treat the rest as indicative. (ii) Your two decks define Tier 2 differently: message a real therapist vs smarter automatic personalisation. Different costs, different value story, different price. Settle the ladder before quoting anyone. Neither blocks the build.

Q12 — Measuring outcomes. The buyer wants numbers; the product refuses clinical questionnaires. The recommendation stands: use only the product's own simple ratings (stress, energy, confidence, the feedback screen) — no PHQ-9-style instruments. Confirm you're comfortable selling on that basis.

Q13 — Safety wording (with legal/clinical, but your voice). The safety machinery is built: the always-visible "Need urgent help?" card, the onboarding disclaimer, the supportive check-in prompt, and a fully private on-device word-check that can show the help card if someone types crisis language. Your decisions: (i) the wording of the disclaimer, the help card, and the supportive prompt — your voice, reviewed clinically; (ii) whether the word-check on things people write is on or off at launch. It costs nothing either way and never sends anything anywhere — the honest difference is the promise: with it off you can say "no one and nothing looks at what you write"; with it on you say "the app itself, privately on your device, may show you help resources if it spots concerning words". Recommendation: on.

Q14 — Microsoft Teams. No decision now — it's a question to ask the pilot customer.

Q15 — Employer dashboard. The metrics, privacy gates, and configuration are settled. Still wanted from you and design: how it should look, and the format of the pilot report you'll hand the HR buyer.

Q16 — The rating scale. Check-ins use tap-to-select buttons (no more sliders). We'll test 5 buttons vs 10 buttons with real people before the pilot; until then it's 10 (which keeps every existing safety threshold valid as-is). After the test, you and design pick. If you pick 5, the safety thresholds get clinically re-derived — the system physically won't let us just halve them.

Q17 — Breathing (three quick calls). (i) Session 1 currently teaches Box Breathing — which holds the breath, carries cautions for pregnancy and heart/lung conditions, and is the weakest-evidenced option in the library. Recommendation: teach Longer-Exhale Breathing instead (no holds, safest, the same exercise the app recommends everywhere else); Box stays available for people who like it. Swap or keep? (ii) Library size: launch with three (longer-exhale, grounded, box — only one new script to write) and add the other two soon after — confirm this phasing, or change it. (iii) Write the one-line question shown after an exercise ("How do you feel now?" — steadier / about the same / that felt uncomfortable) in your words. One heads-up, not a question: at launch the app recommends by evidence and your favourites; "because this worked for you before" suggestions come after the pilot. If you want them at launch, say so — it's a small change.

Q18 — Honesty about how well breathing works. The research says: some people find it helps a lot, most a little, and on average it's hard to distinguish from simply taking five minutes off. The app already frames it as "try it for a couple of weeks and see if it works for you". How plainly do you want to say the rest — quietly honest, or openly honest as a trust differentiator? Draft two or three framings; we'll test them internally.

---

TD4. Residual questions for legal and clinical review

L1 — Controller/processor and DPIA (legal — blocks pilot contract, not build). Decide formally: Minimente as data controller for employee wellbeing data, employer as neither controller nor processor of it (the recommendation — the alternative gives the employer arguable access rights to employee health data, destroying the product's core promise). Then complete the DPIA before pilot launch. Engineering inputs are ready: the full sub-processor register (ADR-01 §C.3), the RLS/aggregation enforcement design (ADR-02), the encryption and break-glass design (ADR-07), the new exercise_outcomes data class (A11.1 flagged it for the DPIA), and the retention recommendation (NFR-PRIV-09: free text active + 12 months — needs legal ratification). One forward flag: when org SSO arrives in Phase 2, the DPIA must cover what the employer's identity provider can observe (ADR-03).

C1 — Crisis-term vocabulary (clinical — blocks shipping search and the free-text prompt, not building them). Review and sign off the crisis/self-harm term list that the on-device matcher uses (for search routing always; for free-text prompting if Minni turns it on — Q13). Also review the search synonym vocabulary's clinical adjacency (e.g. "catastrophising" → thought reframing). Both are plain content files; the format is fixed, only the words are needed.

C2 — Safeguarding and personalisation thresholds (clinical). The rules are built and ship with placeholder values that the release pipeline refuses to publish until marked clinically reviewed: supportive-prompt trigger (currently: stress ≥9 on 3 of the last 5 distinct days, or any 10), high-stress suggestion (≥7), low-energy suggestion (≤4), and the "repeated high stress → professional-support signpost" rule (7 on 3 of 5 distinct days, placeholder). Confirm or replace the values; the mechanism, distinct-day counting, and destinations are settled.

C3 — Scale re-derivation (clinical — conditional). Only if the user test picks a 5-point check-in scale: re-derive every threshold in C2 for the new scale. The build system blocks arithmetic rescaling by engineering; this is yours alone. If 10-point wins, nothing to do.

C4 — The two situations breathing will not model (clinical + Minni). Confirm the addendum's refusal: no "acute anxiety" or "panic" routes exist, because they would require clinical labels the product forbids and because breathing for panic is contested-to-counterproductive in the current evidence. The nearest state, "It's all too much", routes to grounding plus help resources. Confirm, or propose a non-clinical framing — but do not resolve it by adding a clinical label.

C5 — Evidence-grade confirmation pass (clinical). One pass over the five breathing protocols and fifteen mapped situations confirming the addendum's evidence grades (several sources were verified at abstract level only). Fold into the C1 review session — one sitting covers both.

---

TD5. What is now unblocked — and what still is not

TD5.1 An engineer can start the moment this document is accepted

• Phase −1 in full (repo init, artefact rescue, scaffold per ADR-01's manifest — the stack ADR this document is satisfies item 0c).
• Phase 1 items 7–9: the content JSON/YAML schema and screen-type library (ADR-04), the data model + RLS policies + aggregation job (ADR-02), key separation (ADR-07), the design system build (starting from the prototype's palette, with the rating control in both scale variants per ADR-10).
• Phase 2 mechanics, end to end: the exercise runtime and library; the content renderer and Modules 1–10 (copy is final); Toolkit accrual, endings taxonomy, output destinations; offline/sync (ADR-05); notifications and the Focus Window (ADR-06); the breathing player with all four pacing modes and the reduced-motion pacer (A6, ADR-01/06 settle the haptics question); the rules engine with golden files (ADR-13/14); the safeguarding component and rule mechanics (ADR-09); client-side search built dark against a stub vocabulary (ADR-08); extension-module structures behind copy_status = placeholder; the CI suite including RLS negative tests and content QA (ADR-14).
• This week, no code: the timing test of the 5–12-minute claim on the existing prototype (§11's standing recommendation), now doubling as the OPEN-26 scale test once the two control variants exist.

TD5.2 Still not reachable, and by whom

• Releasing Modules 11–15, the Emergency Tools surface, "Right now", and search → Minni's content (Q4, Q5) and the clinical vocabulary (C1). These are the true critical path, exactly as v4's Top Risk 1 said.
• Safeguarding flow going live → copy and option choice (Q13), threshold sign-off (C2).
• Pilot contract → DPIA and controller decision (L1); the adoption kit and dashboard visuals (Q15).
• Any pricing conversation → Q11.
• Phase 0 item 1 ratification (Q1–Q3, Q7, Q17) — one working session; build proceeds on the provisional decisions meanwhile, as v4 already accepted for structure-only work, but nothing user-facing that depends on programme shape should ship before it.

TD5.3 Corners no technical decision can dissolve — stated for the record

1. iOS daily reminders on a PWA. FR-NOT-03 vs AD-02 is a genuine platform conflict: Apple gates Web Push behind manual Home-Screen installation. ADR-06 mitigates (guided install, email fallback, in-app inbox) and ADR-01 defines the measured Capacitor escape hatch — but v1 iOS reminder reach will be structurally worse than Android/desktop, and the pilot must measure it rather than hope.
2. "Anonymous" is the wrong word. Magic-link auth means the system holds an email address; encryption is server-side (ADR-07) because cross-device resume requires it. The true, strong, defensible claims are: your employer cannot see your individual data — enforced by the database and tested in CI and what you write is encrypted, and any staff access is break-glass and audited. Copy and marketing must never say "anonymous" or "we cannot read it" unqualified. This is a wording discipline, not a fixable gap.
3. The passive safety signal keeps thinning. Every v4/A1 surface that lets a user benefit without checking in ("Right now", Toolkit, breathing, search) reduces NFR-SAFE-03's data. The frozen documents already accepted the consequence — always-visible signposting is the primary net — but §8.3's eventual detection design must be built knowing check-ins are a shrinking window, and no architecture choice changes that.
4. Small orgs see an empty dashboard. k≥10 plus weekly granularity means a 12-seat pilot org may see "not enough data" for weeks. FR-ORG-02 turns this into a trust asset, but sales must set the expectation — a pilot below ~25 seats will produce a thin dashboard story for the buyer.
5. Content remains the critical path. Nothing in this document shortens Q4/Q5/C1. Engineering can now build everything; the product still cannot launch until roughly three emergency-tool scripts, the safeguarding copy, and the vocabularies exist. That was v4's Top Risk 1 and it is unchanged — merely no longer hidden behind an unratified stack.

---

End of Technical Decision Record TD1.0. PRD v4.0 and Addendum A1.0 remain frozen and unmodified.