Cap false optimal readiness states (#176)

* fix(readiness): cap false optimal recovery states

* fix(readiness): address review feedback

* fix(readiness): close remaining review gaps

Author: dzarlax

cmd/readiness_probe/main.go

@@ -96,12 +96,22 @@ type YesterdayInputs struct {
 // design. The RECOVERY prompt itself focuses on autonomic trajectories and
 // does not reference EnergyBank.
 type RecoveryInputs struct {
-	LastDate  string
-	HRV       []float64
-	RHR       []float64
-	VO2       []float64
-	Sleep     []float64
-	Readiness *float64
+	LastDate string
+	HRV      []float64
+	RHR      []float64
+	VO2      []float64
+	Sleep    []float64
+	Context  InsightContext
+}
+
+type InsightContext struct {
+	ReadinessScore      int    `json:"readiness_score,omitempty"`
+	ReadinessRawScore   int    `json:"readiness_raw_score,omitempty"`
+	ReadinessConfidence string `json:"readiness_confidence,omitempty"`
+	ReadinessCapReason  string `json:"readiness_cap_reason,omitempty"`
+	AIAdviceMode        string `json:"ai_advice_mode,omitempty"`
+	CheckinStatus       string `json:"checkin_status,omitempty"`
+	CheckinAnswer       string `json:"checkin_answer,omitempty"`
 }
 
 // HashSleep / HashYesterday / HashRecovery extract and hash per-block subsets.
@@ -135,18 +145,18 @@ func HashYesterday(r *health.RawMetrics) string {
 	})
 }
 
-func HashRecovery(r *health.RawMetrics, eb *health.EnergyBank, readiness *float64) string {
+func HashRecovery(r *health.RawMetrics, eb *health.EnergyBank, ctx InsightContext) string {
 	if r == nil {
 		return ""
 	}
 	_ = eb // see RecoveryInputs doc — intra-day fields would defeat the cache
 	return hashInputs(RecoveryInputs{
-		LastDate:  r.LastDate,
-		HRV:       r.HRV,
-		RHR:       r.RHR,
-		VO2:       r.VO2,
-		Sleep:     r.Sleep,
-		Readiness: readiness,
+		LastDate: r.LastDate,
+		HRV:      r.HRV,
+		RHR:      r.RHR,
+		VO2:      r.VO2,
+		Sleep:    r.Sleep,
+		Context:  ctx,
 	})
 }
 
@@ -163,7 +173,7 @@ func HashRecovery(r *health.RawMetrics, eb *health.EnergyBank, readiness *float6
 // EnergyBank fields. Passing the sequence lets RECOMMENDATION pick up
 // patterns like "3 rest days in a row" without re-hitting Gemini just
 // because today's verdict is unchanged.
-func HashRecommendation(sleepText, yesterdayText, recoveryText string, eb *health.EnergyBank, verdictHistory []string) string {
+func HashRecommendation(sleepText, yesterdayText, recoveryText string, eb *health.EnergyBank, verdictHistory []string, ctx InsightContext) string {
 	verdict := ""
 	var flags []string
 	if eb != nil {
@@ -180,8 +190,9 @@ func HashRecommendation(sleepText, yesterdayText, recoveryText string, eb *healt
 		// to surface the rest guidance, even if leaf texts and the
 		// verdict label are unchanged.
 		StressFlags []string
+		Context     InsightContext
 	}
-	return hashInputs(rec{sleepText, yesterdayText, recoveryText, verdict, verdictHistory, flags})
+	return hashInputs(rec{sleepText, yesterdayText, recoveryText, verdict, verdictHistory, flags, ctx})
 }
 
 // ─── orchestrator ─────────────────────────────────────────────────────────
@@ -200,7 +211,7 @@ type BlockResult struct {
 //
 // hashes carry the inputs_hash for each block so callers can compare against
 // the cache and skip Gemini when nothing has changed since last generation.
-func GenerateLeafBlocks(apiKey, model string, maxTokens int, rawMetricsJSON []byte, lang string,
+func GenerateLeafBlocks(apiKey, model string, maxTokens int, payloadForBlock func(block string) []byte, lang string,
 	skipBlock func(block string) bool) []BlockResult {
 
 	results := make([]BlockResult, 0, len(LeafBlocks))
@@ -214,7 +225,11 @@ func GenerateLeafBlocks(apiKey, model string, maxTokens int, rawMetricsJSON []by
 		go func(block string) {
 			defer wg.Done()
 			prompt := BuildBlockPrompt(block)
-			text, _, err := generateWithPrompt(apiKey, model, maxTokens, prompt, rawMetricsJSON, lang)
+			payload := []byte(nil)
+			if payloadForBlock != nil {
+				payload = payloadForBlock(block)
+			}
+			text, _, err := generateWithPrompt(apiKey, model, maxTokens, prompt, payload, lang)
 			resultsMu.Lock()
 			results = append(results, BlockResult{Block: block, Text: text, Err: err})
 			resultsMu.Unlock()
@@ -236,15 +251,35 @@ func GenerateLeafBlocks(apiKey, model string, maxTokens int, rawMetricsJSON []by
 // proper rest" instead of treating each day in isolation. Empty slice
 // is fine — the line is simply omitted from the prompt context.
 func GenerateRecommendation(apiKey, model string, maxTokens int, rawMetricsJSON []byte, lang string,
-	sleepText, yesterdayText, recoveryText string, verdictHistory []string, stressFlags []string) (string, error) {
+	sleepText, yesterdayText, recoveryText string, verdictHistory []string, stressFlags []string, ctx InsightContext) (string, error) {
 	prompt := BuildBlockPrompt(BlockRecommendation)
+	context := BuildRecommendationContext(sleepText, yesterdayText, recoveryText, verdictHistory, stressFlags, ctx)
+	text, _, err := generateWithPrompt(apiKey, model, maxTokens, prompt, append(rawMetricsJSON, []byte(context)...), lang)
+	return text, err
+}
+
+func BuildRecommendationContext(sleepText, yesterdayText, recoveryText string, verdictHistory []string, stressFlags []string, ctx InsightContext) string {
 	leafSummary := fmt.Sprintf(
 		"\n\nLEAF BLOCKS (already generated for the user):\n\nSLEEP\n%s\n\nYESTERDAY\n%s\n\nRECOVERY\n%s",
 		sleepText, yesterdayText, recoveryText)
 	if len(verdictHistory) > 0 {
 		leafSummary += "\n\nENERGYBANK_VERDICT_HISTORY (oldest→newest, last 7 EOD snapshots): " +
 			strings.Join(verdictHistory, ", ")
 	}
+	if ctx.AIAdviceMode != "" {
+		leafSummary += "\n\nREADINESS_EVIDENCE_CONTEXT: advice_mode=" + ctx.AIAdviceMode +
+			fmt.Sprintf(", readiness=%d, raw_readiness=%d, confidence=%s, cap_reason=%s",
+				ctx.ReadinessScore, ctx.ReadinessRawScore, ctx.ReadinessConfidence, ctx.ReadinessCapReason)
+		if ctx.CheckinStatus != "" || ctx.CheckinAnswer != "" {
+			leafSummary += fmt.Sprintf(", checkin_status=%s, checkin_answer=%s", ctx.CheckinStatus, ctx.CheckinAnswer)
+		}
+	}
+	switch ctx.AIAdviceMode {
+	case "withheld":
+		leafSummary += "\nINSTRUCTION: Do not provide a training or recovery recommendation. Explain briefly that the system is waiting for today's recovery data."
+	case "provisional_explanation_only", "needs_regeneration_after_sync":
+		leafSummary += "\nINSTRUCTION: Treat today's readiness as provisional. Explain what is known, what is missing, and how the user's check-in aligns or conflicts with objective signals. Do NOT give confident push-hard advice."
+	}
 	// v2.2 §4.3 hard guard for the recommendation prose — the model
 	// has a known failure mode where verdict=active_recovery but the
 	// prose still says "you can push if you feel up to it". When
@@ -264,6 +299,5 @@ func GenerateRecommendation(apiKey, model string, maxTokens int, rawMetricsJSON
 		leafSummary += "\n\nSTRESS_FLAGS (active multi-channel signals): " +
 			strings.Join(stressFlags, ", ")
 	}
-	text, _, err := generateWithPrompt(apiKey, model, maxTokens, prompt, append(rawMetricsJSON, []byte(leafSummary)...), lang)
-	return text, err
+	return leafSummary
 }

docs/ai-plans/2026-06-04-readiness-false-optimal-hardening.html

@@ -0,0 +1,68 @@
+package ai
+
+import (
+	"strings"
+	"testing"
+
+	"health-receiver/internal/health"
+)
+
+func TestHashRecoveryIncludesReadinessContextAndCheckin(t *testing.T) {
+	raw := &health.RawMetrics{
+		LastDate: "2026-06-04",
+		HRV:      []float64{40, 41, 42},
+		RHR:      []float64{60, 61, 62},
+		Sleep:    []float64{7, 7.5, 8},
+	}
+	base := InsightContext{
+		ReadinessScore:      65,
+		ReadinessRawScore:   95,
+		ReadinessConfidence: health.ReadinessConfidenceProvisional,
+		ReadinessCapReason:  "missing_same_day_evidence",
+		AIAdviceMode:        "needs_regeneration_after_sync",
+		CheckinStatus:       "answered",
+		CheckinAnswer:       "meh",
+	}
+	changed := base
+	changed.CheckinAnswer = "sick"
+
+	if got, wantNot := HashRecovery(raw, nil, base), HashRecovery(raw, nil, changed); got == wantNot {
+		t.Fatalf("HashRecovery did not change after check-in answer changed")
+	}
+}
+
+func TestHashRecommendationIncludesReadinessContextAndCheckin(t *testing.T) {
+	base := InsightContext{AIAdviceMode: "confident_advice_allowed", CheckinStatus: "answered", CheckinAnswer: "ok"}
+	changed := base
+	changed.AIAdviceMode = "provisional_explanation_only"
+
+	got := HashRecommendation("sleep", "yesterday", "recovery", nil, []string{"moderate"}, base)
+	wantNot := HashRecommendation("sleep", "yesterday", "recovery", nil, []string{"moderate"}, changed)
+	if got == wantNot {
+		t.Fatalf("HashRecommendation did not change after AI advice mode changed")
+	}
+}
+
+func TestGenerateRecommendationAddsProvisionalInstruction(t *testing.T) {
+	ctx := InsightContext{
+		ReadinessScore:      65,
+		ReadinessRawScore:   95,
+		ReadinessConfidence: health.ReadinessConfidenceProvisional,
+		ReadinessCapReason:  "missing_same_day_evidence",
+		AIAdviceMode:        "provisional_explanation_only",
+		CheckinStatus:       "answered",
+		CheckinAnswer:       "sick",
+	}
+	got := BuildRecommendationContext("sleep", "yesterday", "recovery", nil, nil, ctx)
+	for _, want := range []string{
+		"READINESS_EVIDENCE_CONTEXT",
+		"advice_mode=provisional_explanation_only",
+		"checkin_answer=sick",
+		"Treat today's readiness as provisional",
+		"Do NOT give confident push-hard advice",
+	} {
+		if !strings.Contains(got, want) {
+			t.Fatalf("recommendation context missing %q:\n%s", want, got)
+		}
+	}
+}

internal/ai/blocks.go

@@ -8,27 +8,32 @@ import (
 // Cross-metric stress thresholds — chosen with explicit research anchors.
 //
 // rhrEvolveAbsBpm (5 bpm) — Wearable HF decompensation 2025 (MDPI):
-//   nocturnal RHR rise > 5 bpm doubled CV hospitalisation/mortality risk.
-//   Below this delta the signal is dominated by device noise (Dial 2025).
+//
+//	nocturnal RHR rise > 5 bpm doubled CV hospitalisation/mortality risk.
+//	Below this delta the signal is dominated by device noise (Dial 2025).
 //
 // sleepDebtThresholdH (6.5 h) — sits below the AASM ≥ 7 h recommendation
-//   (Watson 2015) but above the U-curve worst-case (< 5 h, Li 2025), which
-//   gives a "functional debt" zone where additional autonomic stress
-//   should not be ignored.
+//
+//	(Watson 2015) but above the U-curve worst-case (< 5 h, Li 2025), which
+//	gives a "functional debt" zone where additional autonomic stress
+//	should not be ignored.
 //
 // hrvDepressedZ (-1.0) — 1 SD below personal baseline, matching the
-//   dynamic threshold approach already used in scoreRecovery (and
-//   recommended by Beattie 2024, Plews 2014).
+//
+//	dynamic threshold approach already used in scoreRecovery (and
+//	recommended by Beattie 2024, Plews 2014).
 //
 // awakeFragmentedH (0.5 h) — same threshold used by scoreSleep for the
-//   "consolidated sleep" bonus; > 30 min of nightly wake is the line
-//   above which sleep stops being restorative.
+//
+//	"consolidated sleep" bonus; > 30 min of nightly wake is the line
+//	above which sleep stops being restorative.
 //
 // stressSignalsRequired (2) — multi-signal converging evidence rule
-//   (Meeusen 2013, Plews 2014). One signal alone has too many benign
-//   explanations (illness, alcohol, late workout); two or more
-//   simultaneously is the recognised overreaching/early-illness pattern
-//   (Mishra 2024, Persistent COVID changes 2025).
+//
+//	(Meeusen 2013, Plews 2014). One signal alone has too many benign
+//	explanations (illness, alcohol, late workout); two or more
+//	simultaneously is the recognised overreaching/early-illness pattern
+//	(Mishra 2024, Persistent COVID changes 2025).
 const (
 	rhrElevateAbsBpm      = 5.0
 	sleepDebtThresholdH   = 6.5
@@ -304,27 +309,38 @@ func applyCoherencePass(resp *BriefingResponse, ls LangStrings) {
 		// converging stress markers contradict an "Optimal" verdict even if
 		// the numeric score from any single component looks fine.
 		if resp.ReadinessScore > 65 {
-			resp.ReadinessScore = 65
-			resp.ReadinessBand = ReadinessBand(65)
-			resp.ReadinessLabel = ls["readiness_fair"]
-			resp.ReadinessTip = ls["tip_fair"]
-			resp.RecoveryPct = 65
-			resp.ReadinessToday = 65
-			resp.ReadinessTodayBand = ReadinessBand(65)
-			resp.ReadinessTodayLabel = ls["readiness_fair"]
+			applyReadinessResponseCap(resp, 65, ReadinessConfidenceProvisional, "stress_headline", ls)
 		}
 	case "sleep_debt":
 		// Sleep < 6.5h alone shouldn't push readiness over 65 (Watson 2015,
 		// Walker 2017): one good HRV/RHR night doesn't pay off slept-debt.
 		if resp.ReadinessScore > 65 {
-			resp.ReadinessScore = 65
-			resp.ReadinessBand = ReadinessBand(65)
-			resp.ReadinessLabel = ls["readiness_fair"]
-			resp.ReadinessTip = ls["tip_fair"]
-			resp.RecoveryPct = 65
-			resp.ReadinessToday = 65
-			resp.ReadinessTodayBand = ReadinessBand(65)
-			resp.ReadinessTodayLabel = ls["readiness_fair"]
+			applyReadinessResponseCap(resp, 65, ReadinessConfidenceProvisional, "sleep_debt_headline", ls)
 		}
 	}
 }
+
+func applyReadinessResponseCap(resp *BriefingResponse, maxScore int, confidence, reason string, ls LangStrings) {
+	if resp == nil {
+		return
+	}
+	if resp.ReadinessRawScore == 0 {
+		resp.ReadinessRawScore = resp.ReadinessScore
+	}
+	if resp.ReadinessScore > maxScore {
+		resp.ReadinessScore = maxScore
+	}
+	resp.ReadinessDisplayScore = resp.ReadinessScore
+	resp.ReadinessBand = ReadinessBand(resp.ReadinessScore)
+	resp.ReadinessLabel, resp.ReadinessTip = readinessLabelTip(resp.ReadinessScore, ls)
+	resp.RecoveryPct = resp.ReadinessScore
+	resp.ReadinessToday = resp.ReadinessScore
+	resp.ReadinessTodayBand = resp.ReadinessBand
+	resp.ReadinessTodayLabel = resp.ReadinessLabel
+	if readinessConfidenceRank(confidence) > readinessConfidenceRank(resp.ReadinessConfidence) {
+		resp.ReadinessConfidence = confidence
+	}
+	if readinessCapReasonRank(reason) > readinessCapReasonRank(resp.ReadinessCapReason) {
+		resp.ReadinessCapReason = reason
+	}
+}

internal/ai/blocks_test.go

@@ -206,17 +206,19 @@ func ComputeIllnessSuspicion(in IllnessEvidenceInput) *IllnessSuspicion {
 // caps the prescriptive EnergyBank action when illness evidence says a hard
 // recommendation would be unsafe.
 func ApplyIllnessSafetyCap(resp *BriefingResponse, ls LangStrings) {
-	if resp == nil || resp.EnergyBank == nil || resp.IllnessSuspicion == nil {
+	if resp == nil || resp.IllnessSuspicion == nil {
 		return
 	}
 	switch resp.IllnessSuspicion.Confidence {
 	case IllnessConfidenceHigh:
-		if verdictRank(resp.EnergyBank.ActionVerdict) > verdictRank("rest") {
+		applyReadinessResponseCap(resp, readinessLowCap, ReadinessConfidenceLow, "illness_suspicion_high", ls)
+		if resp.EnergyBank != nil && verdictRank(resp.EnergyBank.ActionVerdict) > verdictRank("rest") {
 			resp.EnergyBank.ActionVerdict = "rest"
 			resp.EnergyBank.VerdictReason = ls["energy_reason_illness_suspicion_high"]
 		}
 	case IllnessConfidenceModerate:
-		if verdictRank(resp.EnergyBank.ActionVerdict) > verdictRank("active_recovery") {
+		applyReadinessResponseCap(resp, readinessFairCap, ReadinessConfidenceProvisional, "illness_suspicion_moderate", ls)
+		if resp.EnergyBank != nil && verdictRank(resp.EnergyBank.ActionVerdict) > verdictRank("active_recovery") {
 			resp.EnergyBank.ActionVerdict = "active_recovery"
 			if resp.IllnessSuspicion.Pattern == IllnessPatternAutonomicProdrome {
 				resp.EnergyBank.VerdictReason = ls["energy_reason_autonomic_prodrome_moderate"]