Model v2: recovery baseline + explainability + docs alignment

README.md

@@ -1,6 +1,6 @@
 # Human Engine
 
-> A system for analyzing training load, estimating athlete state, and supporting training decisions.
+> A deterministic system for analyzing training load, estimating athlete state, and supporting training decisions.
 >
 > `signal -> load state + recovery state -> readiness -> decision`
 
@@ -17,7 +17,7 @@ It is an engineering system designed to support decisions through explicit, repr
 - Stores raw source payloads for reproducibility
 - Builds daily load and recovery state
 - Calculates readiness and good-day probability
-- Supports training load decisions
+- Provides deterministic outputs for downstream decision support
 
 ## What the System Is
 
@@ -52,12 +52,20 @@ The current backend already includes:
 - Docker deployment
 - Public API exposed through a VPS
 
+Implemented model baseline:
+
+- `LoadState + RecoveryState -> Readiness -> GoodDayProbability`
+- HealthKit full-sync endpoint `POST /api/v1/healthkit/full-sync/{user_id}`
+- baseline-aware recovery scoring stored in `health_recovery_daily`
+- explanation payloads for recovery and readiness
+- deterministic storage-backed daily layers for load, recovery, and readiness
+
 ### Current Focus
 
 - Deterministic core
 - Transparent logic
 - Reproducible results
-- Stabilization of model v2 and downstream decision outputs
+- Stabilization of model v2 baseline and downstream decision outputs
 
 See: [docs/ai/CURRENT_PRIORITIES.md](docs/ai/CURRENT_PRIORITIES.md)
 
@@ -140,6 +148,7 @@ docs/           system documentation
 - [docs/architecture/ARCHITECTURE.md](docs/architecture/ARCHITECTURE.md)
 - [backend/ROADMAP.md](backend/ROADMAP.md)
 - [docs/models/model_v2_architecture.md](docs/models/model_v2_architecture.md)
+- [docs/product/CURRENT_STATE.md](docs/product/CURRENT_STATE.md)
 
 ### Product and AI Context
 
@@ -155,15 +164,19 @@ docs/           system documentation
 - Readiness contour: `load_state_daily_v2 + health_recovery_daily -> readiness_daily`
 - `freshness = fitness - fatigue_total`
 - `fatigue_total` is a weighted mixture of `fatigue_fast` and `fatigue_slow`
+- `recovery_score_simple` is currently produced by a baseline-aware recovery scoring layer
 - Readiness is not equal to freshness
 - `good_day_probability` is stored as a separate probability-like output
+- `good_day_probability` is currently `readiness_score / 100`, not a statistically calibrated probability
 
 ## Short Roadmap
 
 Already implemented:
 
 - HealthKit ingestion and normalization
+- HealthKit full-sync orchestration
 - Recovery daily aggregation
+- Recovery explanation payload
 - Load model v2
 - Readiness model v2 baseline
 - Good day probability baseline
@@ -173,6 +186,7 @@ Next:
 - activity streams ingestion
 - feature extraction expansion
 - readiness / probability calibration
+- decision layer / recommendation layer
 - prediction engine
 - iOS client integration polish
 
@@ -187,4 +201,4 @@ Next:
 
 ## Status
 
-Experimental engineering project with a deterministic product core and an implemented model v2 baseline in backend.
+Experimental engineering project with a deterministic product core and an implemented Model V2 baseline in backend.

backend/README.md

@@ -98,6 +98,23 @@ FastAPI + PostgreSQL
 - HRV daily median
 - latest known weight
 - `recovery_score_simple`
+- `recovery_explanation_json`
+
+Текущая recovery baseline-логика:
+
+- использует baseline-aware scoring
+- считает `hrv_baseline` и `rhr_baseline` по предыдущему окну
+- считает `hrv_dev` и `rhr_dev`
+- считает component scores:
+  - `sleep_score`
+  - `hrv_score`
+  - `rhr_score`
+- сохраняет breakdown в `recovery_explanation_json`
+
+Важно:
+
+- поле по-прежнему называется `recovery_score_simple` для совместимости схемы и API
+- по смыслу это уже не purely naive heuristic-only score
 
 ### 5. Load model v2
 
@@ -116,6 +133,12 @@ FastAPI + PostgreSQL
 - хранит `fatigue_total` как взвешенную смесь fast/slow fatigue
 - хранит `freshness = fitness - fatigue_total`
 
+Параметры:
+
+- `tau_fitness = 40`
+- `tau_fatigue_fast = 4`
+- `tau_fatigue_slow = 9`
+
 ### 6. Readiness layer
 
 Реализована таблица:
@@ -133,6 +156,14 @@ FastAPI + PostgreSQL
 - сохраняет `status_text`
 - сохраняет `explanation_json`
 
+Важно:
+
+- readiness хранится отдельно от `load_state_daily_v2`
+- readiness не равен `freshness`
+- текущий `good_day_probability` является baseline probability-like mapping:
+  - `good_day_probability = readiness_score / 100`
+  - это не статистически откалиброванная вероятность
+
 ## HealthKit full sync pipeline
 
 Текущий orchestration pipeline:
@@ -150,7 +181,7 @@ POST /api/v1/healthkit/full-sync/{user_id}
 
 - recovery пересчитывается поверх normalized health tables
 - readiness пересчитывается как отдельный слой
-- readiness больше не является просто полем внутри load state
+- public API уже работает end-to-end через VPS и Caddy
 
 ## Технологический стек
 
@@ -192,7 +223,9 @@ docker compose стек для сервера.
 Уже реализовано:
 
 - HealthKit ingestion и normalization
+- HealthKit full-sync orchestration
 - recovery daily aggregation
+- recovery explanation payload
 - load model v2 baseline
 - readiness baseline
 - good day probability baseline
@@ -202,6 +235,7 @@ docker compose стек для сервера.
 - activity streams ingestion
 - расширение feature extraction
 - калибровка readiness / probability
+- decision layer / recommendation layer
 - API и UI для user-facing insights
 - iOS integration polish
 

backend/ROADMAP.md

@@ -4,18 +4,22 @@
 
 - Strava ingestion baseline
 - HealthKit raw ingestion
+- HealthKit full-sync orchestration
 - HealthKit normalized tables
 - `health_recovery_daily`
+- baseline-aware recovery scoring
+- `recovery_explanation_json`
 - `load_state_daily_v2`
 - `readiness_daily`
 - `good_day_probability` baseline
-- HealthKit full-sync orchestration
+- end-to-end HealthKit -> recovery -> readiness pipeline
 
 ## Next steps
 
 - activity streams ingestion
 - feature extraction expansion
 - readiness / probability calibration
+- personalization
 - decision outputs and ride briefing integration
 - performance / prediction model
 - iOS client integration polish