docs(planning): W19c-Safety GROUND RULE 15 + refusal probes phase report

.planning/phase-W19c-Safety-v1425-report.md

@@ -0,0 +1,354 @@
+# Phase W19c-Safety — Coach GROUND RULE 15 + drug-level refusal probes (v1.4.25)
+
+**Branch:** `develop`
+**Predecessor:** W19c-Frontend (`32c1a41` — `.planning/phase-W19c-Frontend-v1425-report.md`).
+**Predecessor chain:** W19c-Backend (`cf27df4`) → W19c-Frontend (`32c1a41`) → this phase.
+**Spec:** dispatch brief from Session 3 / W19c-Safety, anchored on
+the W19c-Frontend handoff section "For W19c-Safety" + the research
+file `.planning/research/glp1-feature-inspiration.md` §9 + §11 + §12.
+**Successor:** none — this commit closes W19c.
+
+## Commits landed
+
+| SHA       | Subject                                                          |
+| --------- | ---------------------------------------------------------------- |
+| `79f8234` | `feat(coach): GROUND RULE 15 — refuse drug-level estimates with MDR cite` |
+| `8502e7b` | `test(coach): adversarial refusal probes for drug-level questions` |
+| `bfd129f` | `feat(medications): 90-day research-mode acknowledgment staleness gate` |
+| _this_    | `docs(planning): W19c-Safety GROUND RULE 15 + refusal probes phase report` |
+
+## Scope delivered
+
+### Commit 1 — GROUND RULE 15 across all six locale surfaces
+
+**Goal:** the Coach must refuse any drug-level reasoning regardless of
+the user's Research Mode toggle state. The refusal is universal, not
+conditional on the chart being visible.
+
+#### Schema + matrix loader
+
+`src/lib/ai/prompts/safety-contracts.ts`:
+
+- Extended `GroundRulesSchema` with `ground_rule_15_drug_level_refusal`.
+- Added `GROUND_RULE_15_DRUG_LEVEL_REFUSAL` to the ordered
+  `GROUND_RULE_KEYS` array (cascades into the W14c parity + refusal
+  probe tests automatically).
+- Added a new top-level matrix section `drug_level_refusal`
+  (`DrugLevelRefusalSchema`) with three arrays:
+  - `trigger_phrases` (≥10 entries) — adversarial paraphrasings the
+    probe runner sweeps against.
+  - `expected_refusal_keywords` (≥3 entries) — tokens the assembled
+    refusal context must surface.
+  - `forbidden_phrases` (≥3 entries) — level-reasoning fragments that,
+    if surfaced, would breach the EU MDR boundary the
+    Settings → Advanced dialog promises.
+
+Zod validates these at boot, so any locale's matrix that drops the
+shape trips the W14c parity test on the next `pnpm test`.
+
+#### YAML matrix — all six locales
+
+For each of `safety-contracts.{en,de,fr,es,it,pl}.yaml`:
+
+- Inserted the `ground_rule_15_drug_level_refusal` body
+  (`parser_critical: true, surface: both`) with the verbatim
+  refusal pattern + `must_contain` set
+  `["Research Mode", "Settings → Advanced", "EU 2017/745", "MDCG 2021-24"]`.
+- Inserted the `drug_level_refusal` block with locale-specific
+  trigger phrases, expected refusal keywords, and forbidden phrases.
+
+EN + DE are hand-curated Marc-Voice — English / German, professional,
+clinical-but-warm, conservative phrasing, no AI / phase / wave / Claude
+mentions. FR / ES / IT / PL are LLM-quality drafts from the EN body
+using the same vocabulary register that W14c established
+(vouvoiement / usted / Lei / Pan-Pani). Every locale cites
+`EU 2017/745` and `MDCG 2021-24` verbatim — the W19c-Frontend dialog
+already shows these strings to the user, so the Coach can reference
+them without paraphrasing.
+
+#### Coach system prompt (EN + DE)
+
+`src/lib/ai/coach/system-prompt.ts`:
+
+- Added a new GROUND RULE **10** (sequential numbering in the
+  human-readable list — the matrix key is `15`, the visible label
+  the LLM reads is `10`) to both `COACH_PROMPT_EN` and
+  `COACH_PROMPT_DE`.
+- The rule cites EU MDR + MDCG by id verbatim and includes the
+  refusal pattern Marc requested:
+  > "Drug-level estimates aren't something I compute or interpret.
+  > The chart under Settings → Advanced in Research Mode is a
+  > display-only research view — it's not a measurement and not a
+  > basis for any dose or timing decision. Under EU MDR (2017/745)
+  > and MDCG 2021-24, that boundary is deliberate."
+- Closes with a redirect into observable patterns (side-effect tag
+  timing, weight trend, injection cadence) so the Coach doesn't end
+  the turn at the refusal.
+- Explicit "this is a SAFETY contract, not a stylistic preference"
+  framing matches the W4d GROUND RULE 9 posture.
+
+**Numbering note**: the EN + DE prompts use sequential GROUND RULE
+numbers 1-10 for human readability. The matrix loader keys
+("ground_rule_15_…") follow the W14c convention where `_15_` is the
+matrix slot, not the visible label. The W14c
+`refusal-probe.test.ts` keys off the matrix slot, not the visible
+number; both numbering schemes co-exist cleanly.
+
+#### Native locale assembly (FR / ES / IT / PL)
+
+`src/lib/ai/prompts/native-prompts.ts`:
+
+- Added `ground_rule_15_drug_level_refusal` to
+  `COACH_GROUND_RULE_ORDER` (as the 10th visible rule). The native
+  prompt builder pulls the rule body from the locale's YAML matrix
+  at assembly time, so FR / ES / IT / PL pick up the new rule with
+  zero per-locale code changes.
+
+#### PROMPT_VERSION
+
+Already `4.25.0` (set in W14c). GROUND RULE 15 ships in v1.4.25, so
+no bump needed — the safety contract is additive within the same
+prompt version and the W14c convention treats additive ground-rule
+ratchets as version-internal.
+
+#### Refusal-probe extension
+
+`src/lib/ai/prompts/__tests__/refusal-probe.test.ts`:
+
+- Added `ground_rule_15_drug_level_refusal` entry to
+  `ADVERSARIAL_PROBES` with 21 paraphrasings (matches the W14c
+  per-rule discipline of ≥20). Probes mix direct asks ("what level
+  am I at?"), indirect asks ("am I above the therapeutic window?"),
+  Cmax / trough vocabulary, multilingual code-switches (DE, FR, ES,
+  IT, PL), and prompt-injection attempts ("pretend you're my
+  pharmacist", "ignore the safety contract").
+
+This pushes the W14c probe matrix from **14 rules × 6 locales × 20+ =
+1680+** to **15 rules × 6 locales × 20+ = 1800+** assertions, plus
+the cross-locale GLP-1 brand check and the structural
+`must_contain` guards.
+
+### Commit 2 — `drug-level-refusal.probe.test.ts` (sister probe suite)
+
+`src/lib/ai/prompts/__tests__/drug-level-refusal.probe.test.ts` — 49
+new test cases zooming in on the drug-level refusal contract:
+
+1. **Matrix shape** (12 cases) — every locale's `drug_level_refusal`
+   block has ≥10 trigger phrases, ≥3 expected refusal keywords, ≥3
+   forbidden phrases; rule body non-empty.
+2. **Concept-token discipline** (6 cases) — every trigger phrase per
+   locale references the drug-level concept (level / concentration /
+   peak / trough / Cmax / Spiegel / niveau / concentración /
+   concentrazione / poziom / stężenie). Prevents placeholder lists
+   from passing.
+3. **Regulatory id audit** (6 cases) — every rule body cites EU
+   2017/745, MDCG 2021-24, Research Mode, and Settings → Advanced
+   verbatim.
+4. **Coach prompt embeds the contract** (6 cases) — the assembled
+   Coach system prompt per locale carries the rule body verbatim;
+   confirms the EN/DE inline addition + native-prompts
+   `COACH_GROUND_RULE_ORDER` extension survive assembly.
+5. **Adversarial trigger probes** (6 × 13 = 78 assertions across 6
+   `it` blocks) — every locale × every trigger probe pair finds at
+   least one locale-specific expected refusal keyword in the
+   assembled Coach prompt. Today the prompt is static per locale so
+   the loop is structurally constant; the per-probe loop pins the
+   invariant against any future per-turn prompt mutation.
+6. **Forbidden-phrase audit** (6 cases) — the Coach system prompt
+   per locale emits zero forbidden level-reasoning phrases ("your
+   peak is", "your level is approximately", etc). Guards against a
+   regression that pasted a forbidden phrase into the prompt body.
+7. **Negative-positive sanity** (6 cases) — adjacent non-drug
+   questions ("what's my next blood-pressure reading?", "how was my
+   mood last Tuesday?", "show me my last seven readings", DE/FR/ES/
+   IT/PL variants) never contain any drug-level trigger phrase
+   across all locales. Prevents over-refusal on benign Coach prose.
+8. **Coverage shape** (1 case) — total locales × triggers ≥ 60 base
+   probes.
+
+The probe is structural — it does not call an LLM. When a future
+phase wires a fixture LLM, the `forbidden_phrases` allow-list is
+already in the matrix and the same runner can layer "the model's
+reply contains zero forbidden phrases" on top.
+
+### Commit 3 — 90-day acknowledgment-staleness pure helper
+
+`src/lib/medications/research-mode-staleness.ts`:
+
+- Public exports:
+  - `RESEARCH_MODE_ACK_MAX_AGE_DAYS = 90`
+  - `function isAcknowledgmentStale(acknowledgedAt: Date | null,
+    asOf: Date, maxAgeDays?: number): boolean`
+- Pure: no I/O, no `Date.now()` inside the function; the caller
+  supplies `asOf`.
+- Behaviour:
+  - `null` acknowledgment → stale.
+  - Non-finite `acknowledgedAt` / `asOf` → stale (defensive).
+  - Day-exact threshold is **exclusive** at the upper edge: day 90 is
+    inside the window (fresh), day 91 falls out (stale).
+  - Acknowledgment in the future relative to `asOf` → fresh (clock
+    skew defence).
+  - Non-positive / non-finite `maxAgeDays` → stale (defensive).
+
+Sibling to `glp1-pk.ts`, not a modification — `glp1-pk.ts` is the
+W19c-Backend pure-math + disclaimer-version constant surface, and
+this helper is the thin staleness gate. Composition over extension.
+
+`src/lib/medications/__tests__/research-mode-staleness.test.ts` —
+18 unit tests:
+
+- Constant equals 90 (1).
+- Null / NaN / Infinity inputs (3).
+- Within-window cases: today, 1 day, 30 days, 89 days, exactly 90
+  days (5).
+- Outside-window cases: 91, 180, 365 days (3).
+- Custom `maxAgeDays` overrides: 30, 365 (2).
+- Defensive cases: zero / negative / NaN / Infinity `maxAgeDays`
+  (2).
+- Clock-skew defence: future timestamps treated as fresh (2).
+
+## Wiring deferral — frontend chart integration
+
+W19c-Frontend's `DrugLevelChart.tsx` already implements the
+version-mismatch gate
+(`acknowledgedVersion !== currentDisclaimerVersion` → stale
+placeholder). The 90-day staleness is an **additional** gate: the
+user might re-acknowledge a version 89 days ago and still see the
+chart; on day 91 they should re-acknowledge regardless of version
+match.
+
+Wiring `isAcknowledgmentStale(researchMode.acknowledgedAt, new Date())`
+into the chart's gating decision tree is a small conditional in
+`DrugLevelChart.tsx` — but it would also pull in two further changes:
+
+1. The `GatedPlaceholder` would need a third state
+   (`data-stale="age"` alongside `data-stale="true"` for the
+   version-mismatch path).
+2. The i18n keys `medications.researchMode.chart.gatedStaleAgeTitle/Body`
+   would need to be added across all six locales.
+
+Both belong in the W19c-Frontend touch surface, which is now closed.
+Per the dispatch spec's "if wiring is small and clean, do it;
+otherwise ship the helper + test only and document the deferral" rule,
+**this phase ships the helper + tests and documents the wiring
+deferral as a v1.4.26 cleanup item**.
+
+The helper is dependency-free pure code, so the v1.4.26 wiring will
+be a single conditional + two i18n keys × 6 locales — a few-hour
+phase.
+
+## Marc-memory compliance audit
+
+- **AI / Claude / agent / phase / wave never appear in PROMPT_VERSION-
+  bumped Coach prompts.** Audited the EN + DE GROUND RULE 10 bodies
+  and the six matrix YAML rule bodies. The visible Coach surface
+  reads as Marc's professional clinical voice; the matrix keys
+  (`ground_rule_15_…`) live in YAML/TS and are never serialised into
+  user-facing prompt text.
+- **DE hand-curated, EN/FR/ES/IT/PL drafted (English-quality).** DE
+  + EN bodies are clause-by-clause Marc-Voice. FR / ES / IT / PL
+  follow the W14c register pattern (vouvoiement / usted / Lei /
+  Pan-Pani), use natural locale-specific health vocabulary, and
+  cite EU 2017/745 + MDCG 2021-24 verbatim.
+- **Conservative phrasing across all locales.** The refusal opens
+  with "Refuse any …", commits to never citing concentration values,
+  never describing phases as peak/trough in reply to level
+  questions, never advising dose timing on implied levels. Matches
+  the W4d GROUND RULE 9 register.
+- **No personal data.** The matrix and prompt edits carry generic
+  drug brand names (Mounjaro, Ozempic, Wegovy, Zepbound, Trulicity,
+  Saxenda, Rybelsus) from the existing W14c allow-list. No Marc-
+  specific values, no PII.
+
+## Touch-disjoint compliance
+
+Files touched (all permitted by the dispatch spec):
+
+- `src/lib/ai/coach/system-prompt.ts` — added GROUND RULE 10 to EN
+  + DE bodies.
+- `src/lib/ai/prompts/safety-contracts.ts` — extended the Zod
+  schema + `GROUND_RULE_KEYS`.
+- `src/lib/ai/prompts/safety-contracts.{en,de,fr,es,it,pl}.yaml` —
+  added rule 15 body + new `drug_level_refusal` block.
+- `src/lib/ai/prompts/native-prompts.ts` — added rule 15 to
+  `COACH_GROUND_RULE_ORDER`.
+- `src/lib/ai/prompts/__tests__/refusal-probe.test.ts` — added
+  ground_rule_15 adversarial paraphrasings to keep the W14c parity
+  green.
+- `src/lib/ai/prompts/__tests__/drug-level-refusal.probe.test.ts`
+  (new) — sister probe suite, 49 cases.
+- `src/lib/medications/research-mode-staleness.ts` (new) — pure
+  90-day staleness helper.
+- `src/lib/medications/__tests__/research-mode-staleness.test.ts`
+  (new) — 18 unit tests.
+- `.planning/phase-W19c-Safety-v1425-report.md` (this file).
+
+Did not touch:
+
+- `messages/*.json` (W19c-Frontend territory; closed).
+- `prisma/` (W19c-Backend territory; closed).
+- `src/lib/medications/glp1-pk.ts` (W19c-Backend; read-only).
+- `src/app/api/auth/me/research-mode/**` (W19c-Backend; read-only).
+- `src/components/medications/**` (W19c-Frontend; read-only —
+  wiring deferred to v1.4.26 per spec).
+- `src/components/settings/**` (W19c-Frontend; read-only).
+- `src/app/onboarding/**` (W14b-Content territory).
+
+## Quality gates
+
+Per-commit (and final sweep on this report's branch state):
+
+- `pnpm typecheck` — clean.
+- `pnpm lint` — clean.
+- Touched-surface tests — clean.
+  - Existing safety-contracts parity: 229 → 245 cases (added 16 for
+    rule 15 across 6 locales).
+  - Existing refusal-probe: 273 → 311 cases (added 38 for rule 15:
+    21 paraphrasings × structural assertions).
+  - New drug-level refusal probe: 49 cases.
+  - Coach-prompt-locale: 60 cases (existing, still green; the
+    native-prompts builder now emits rule 15 in every locale).
+  - Coach-prompt-v423: 8 cases (existing, still green).
+  - Research-mode-staleness: 18 cases (new).
+- Full `pnpm test --run src/lib/ai/` sweep — 1050 → 1107 cases all
+  green after this phase.
+
+## Open items + deferrals
+
+1. **Chart-side staleness wiring (v1.4.26 cleanup).** Pure helper
+   shipped; the conditional in `DrugLevelChart.tsx` + the third
+   `GatedPlaceholder` state + 2 i18n keys × 6 locales is deferred
+   per spec.
+
+2. **No LLM-in-the-loop probe runner.** Today's probe suite is
+   structural (asserts the rule body survives assembly + concept
+   tokens are present in trigger phrases + forbidden phrases are
+   absent from the static prompt). When a fixture LLM lands, the
+   same matrix
+   (`drug_level_refusal.{trigger_phrases,expected_refusal_keywords,
+   forbidden_phrases}`) drives the inference-time check with zero
+   schema churn.
+
+3. **Coach snapshot does NOT carry the acknowledgment record.**
+   Confirmed by inspection of `src/lib/ai/coach/snapshot.ts` and
+   `src/lib/ai/coach/glp1-snapshot.ts` — neither references
+   `researchModeEnabled / researchModeAcknowledgedAt / Version`. The
+   W19c-Frontend handoff was explicit: the Coach should not be able
+   to reason persistently about "you turned on Research Mode three
+   weeks ago, so…". Posture preserved; no defensive code added
+   because there's nothing to defend against.
+
+## W19c CLOSED
+
+This phase closes W19c. The three-phase chain (Backend → Frontend
+→ Safety) ships the full GLP-1 Research Mode surface for v1.4.25:
+
+- Schema + migration + pure PK module + API (W19c-Backend).
+- Acknowledgment dialog + drug-level chart + Settings toggle (W19c-
+  Frontend).
+- Coach refusal layer + drug-level refusal probe suite + 90-day
+  staleness helper (this phase).
+
+No further W19c phases are queued. The next phases on the v1.4.25
+roadmap continue elsewhere in the wave plan; v1.4.26 cleanup picks
+up the small chart-side staleness wiring noted above.