shchukins · shchukins · May 20, 2026 · May 20, 2026
diff --git a/README.md b/README.md
@@ -36,9 +36,9 @@ Strava and Apple Health are the connectors. Everything else is yours.
 
 ## What it does
 
-**Morning readiness briefing** — every morning you get your recovery state, training load trend, and a concrete recommendation for the day. Not a score. An answer.
+**Morning readiness briefing** — the backend already produces a daily readiness result with explanation, a deterministic recommendation zone, and Telegram/iOS-friendly briefing text.
 
-**Adaptive training suggestion** — the system knows your calendar, your available time, and your current readiness. It suggests a workout that fits your actual day — duration, intensity, timing.
+**Deterministic training guidance** — the current product maps readiness into explicit training guidance like `recovery`, `endurance`, `moderate`, or `high_intensity`. Broader day-planning logic such as calendar-aware timing or duration selection remains planned.
 
 **Explainable outputs** — every recommendation shows its reasoning. HRV down, sleep short, high fatigue — you see exactly why. No black box.
 
@@ -73,7 +73,7 @@ The core is deterministic and reproducible. AI is an auxiliary layer, not the pr
 
 ## Status
 
-Active prototype. Core pipeline is working end-to-end — readiness is computed daily from real Strava and HealthKit data, delivered to iOS. Product features are in active development.
+Active prototype. Core pipeline is working end-to-end: Strava and HealthKit data flow into daily load, recovery, readiness, and deterministic recommendation outputs. Daily readiness is available through the API and Telegram delivery. Broader planning and calibration work remain in active development.
 
 ---
 

diff --git a/README.ru.md b/README.ru.md
@@ -42,15 +42,17 @@ Strava и Apple Health — точки подключения, а не закры
 
 ### Утренний брифинг
 
-Каждое утро система формирует краткую сводку: восстановление, тренд нагрузки, факторы усталости и рекомендацию на день.
+Система уже формирует ежедневный readiness-результат с объяснением, детерминированной зоной рекомендации и кратким briefing-текстом для API, Telegram и iOS.
 
 Не только метрики, но и интерпретацию состояния.
 
 ---
 
-### Адаптивные рекомендации
+### Детерминированные рекомендации
 
-Human Engine учитывает текущее состояние, накопленную нагрузку и доступное время, чтобы предложить тренировку, которая реалистично вписывается в твой день — по длительности, интенсивности и моменту выполнения.
+Текущий baseline переводит readiness в явную рекомендацию: `recovery`, `endurance`, `moderate` или `high_intensity`.
+
+Более широкий decision layer с учетом календаря, доступного времени и выбора длительности остается следующим этапом, а не текущей реализованной возможностью.
 
 ---
 
@@ -96,9 +98,9 @@ Strava + Apple Health
 
 Активный прототип.
 
-Основной pipeline уже работает end-to-end: данные из Strava и HealthKit ежедневно обрабатываются, рассчитывается оценка готовности, а результат доставляется в iOS-приложение.
+Основной pipeline уже работает end-to-end: данные из Strava и HealthKit ежедневно обрабатываются, рассчитываются load, recovery, readiness и детерминированный recommendation output.
 
-Продуктовые сценарии и модель рекомендаций находятся в активной разработке.
+Daily readiness доступен через API и Telegram delivery. Более широкий planning layer и calibration остаются в активной разработке.
 
 ---
 

diff --git a/docs/ai/CURRENT_PRIORITIES.md b/docs/ai/CURRENT_PRIORITIES.md
@@ -146,6 +146,8 @@ RAG рассматривается как:
 - стабилизация `load_state_daily_v2`
 - стабилизация `health_recovery_daily`
 - стабилизация `readiness_daily`
+- стабилизация deterministic `decision_engine` и briefing contract поверх readiness
+- устранение дублирования recommendation / briefing logic между `decision_engine` и legacy notification formatting
 - readiness / probability calibration как следующий шаг, а не новый black-box слой
 
 ---

diff --git a/docs/ai/GLOSSARY.md b/docs/ai/GLOSSARY.md
@@ -153,7 +153,18 @@ Recovery не заменяет fatigue, а корректирует readiness п
 - допустимую интенсивность
 - ограничения по дню
 
-В текущем состоянии recommendation layer остается planned.
+В текущем backend baseline recommendation layer уже реализован как deterministic mapping от `readiness_score`:
+
+- `< 40` -> `recovery`
+- `40 <= score < 60` -> `endurance`
+- `60 <= score <= 75` -> `moderate`
+- `> 75` -> `high_intensity`
+
+Важно:
+
+- это baseline decision support, а не полноценный training planner
+- recommendation не пересчитывает readiness, а использует уже сохраненный readiness output
+- более широкий planning layer остается planned
 
 ---
 
@@ -166,7 +177,18 @@ Recovery не заменяет fatigue, а корректирует readiness п
 - стабильным
 - опираться на readiness layer, а не на свободный текст
 
-В текущем состоянии ride briefing layer остается planned.
+В текущем backend baseline ride briefing уже реализован как deterministic formatting layer поверх:
+
+- `readiness_score`
+- `status_text`
+- `recommendation`
+- `reason`
+
+Важно:
+
+- briefing используется в readiness API response и notification flows
+- это не LLM-generated coaching text
+- richer multi-surface briefing orchestration остается partial / evolving
 
 ---
 

diff --git a/docs/ai/PRODUCT_CONTEXT.md b/docs/ai/PRODUCT_CONTEXT.md
@@ -131,7 +131,8 @@ Recommendation
 
 - HealthKit ingestion и full-sync уже работают в backend
 - recovery и readiness уже materialized как отдельные daily layers
-- decision / recommendation layer остается planned
+- baseline decision / recommendation layer уже реализован как deterministic mapping поверх `readiness_daily`
+- более широкий recommendation / planning layer остается planned
 
 ---
 

diff --git a/docs/architecture/OPEN_DECISIONS.md b/docs/architecture/OPEN_DECISIONS.md
@@ -167,11 +167,18 @@ partially resolved
 
 Ride briefing — важный output системы.
 
-Базовая readiness layer уже реализована, но не зафиксировано:
+Что уже реализовано:
 
-- окончательный формат user-facing briefing
-- уровень детализации
-- mapping from readiness to recommendation
+- baseline deterministic `recommendation`
+- baseline deterministic `reason`
+- baseline deterministic `briefing`
+- readiness API response с decision output
+
+Что остается незафиксированным окончательно:
+
+- окончательный multi-surface формат user-facing briefing
+- уровень детализации на разных surfaces
+- граница между `decision_engine` и legacy notification formatting
 
 ---
 
@@ -193,6 +200,38 @@ Ride briefing — важный output системы.
 
 ### Status
 
+partially resolved
+
+---
+
+## OD-008: Decision formatting unification
+
+### Context
+
+В текущем backend уже есть явный `decision_engine` для recommendation / briefing.
+
+Одновременно часть legacy notification formatting logic продолжает жить в `notification_service`.
+
+Это не нарушает boundary между AI и deterministic core, но создает риск постепенного drift:
+
+- тексты могут начать расходиться
+- пороги и формулировки могут дублироваться
+- ответственность decision layer станет менее явной
+
+### Minimal correction strategy
+
+1. Считать `decision_engine` canonical source для readiness-to-guidance mapping
+2. Постепенно свести user-facing readiness wording к одному formatting path
+3. Оставить `notification_service` orchestration-слоем, а не вторым decision-слоем
+
+### Open questions
+
+- какие notification-specific embellishments допустимы вне canonical decision path
+- нужно ли выделять отдельный formatter module между decision и delivery
+- как покрыть унификацию tests без избыточной связанности
+
+### Status
+
 open
 
 ---

diff --git a/docs/product/CURRENT_STATE.md b/docs/product/CURRENT_STATE.md
@@ -1,6 +1,6 @@
 # Human Engine — CURRENT STATE
 
-Last updated: 2026-04-17
+Last updated: 2026-05-21
 
 ---
 
@@ -239,24 +239,70 @@ good_day_probability = readiness_score / 100
 
 ---
 
-## 6. Основные ограничения текущей версии
+## 6. Decision, delivery and feedback layers
+
+### 6.1 Deterministic decision baseline
+
+Поверх `readiness_daily` уже работает baseline decision layer:
+
+- `recommendation`
+- `reason`
+- `briefing`
+
+Текущий mapping:
+
+- `< 40` -> `recovery`
+- `40 <= score < 60` -> `endurance`
+- `60 <= score <= 75` -> `moderate`
+- `> 75` -> `high_intensity`
+
+Важно:
+
+- decision layer не меняет readiness formula
+- decision layer не использует AI / LLM
+- это baseline guidance, а не полноценный planner по времени, длительности и контексту дня
+
+### 6.2 Delivery layer
+
+Уже реализованы:
+
+- GET readiness API с `recommendation`, `reason`, `briefing`, `data_quality`
+- daily Telegram readiness delivery
+- deterministic formatting для iOS / Today-style consumption
+
+### 6.3 Subjective feedback layer
+
+Уже реализованы:
+
+- post-ride RPE prompt
+- next-day recovery prompt
+- `activity_subjective_feedback`
+- `subjective_feedback_prompt_log`
+
+Важно:
+
+- feedback не меняет deterministic core calculations
+- feedback сохраняется как evaluation / calibration dataset
+
+## 7. Основные ограничения текущей версии
 
 1. Recovery baseline уже реализован, но еще не откалиброван на популяционных или персональных outcome данных.
 2. `load_input_nonlinear` пока фактически линейный.
 3. `good_day_probability` пока является простым mapping от readiness score.
-4. Decision layer и recommendation layer еще не реализованы как отдельный production layer.
-5. Персонализация и calibration остаются следующим этапом.
-
----
+4. Decision layer уже реализован, но пока остается узким baseline mapping без time-aware planning и duration guidance.
+5. В notification / briefing flows сохраняется риск архитектурного дрейфа: часть legacy formatting logic еще живет вне `decision_engine`, что может со временем разъехать тексты и правила.
+6. Персонализация и calibration остаются следующим этапом.
 
-## 7. Ключевые архитектурные решения
+## 8. Ключевые архитектурные решения
 
 - Load и Recovery разделены
 - Readiness не равен freshness
 - Readiness хранится отдельно в `readiness_daily`
 - Recovery влияет на readiness, но не переписывает load model
 - используется daily aggregation
 - используется probability layer (`good_day_probability`)
+- baseline decision layer отделен от readiness formula
+- subjective feedback хранится отдельно от model state как calibration dataset
 - deterministic core остается приоритетом
 
 ---

diff --git a/docs/ui/READINESS_TODAY_SCREEN.md b/docs/ui/READINESS_TODAY_SCREEN.md
@@ -99,7 +99,23 @@ HRV: 64
 
 ⸻
 
-4.5 Короткое объяснение (опционально)
+4.5 Recommendation блок
+
+В текущем backend уже доступен deterministic decision output:
+	•	recommendation
+	•	reason
+	•	briefing / briefing_text
+
+Это уже часть MVP data contract, а не future-only идея.
+
+Пример:
+
+Recommendation: endurance
+Briefing: Сегодня нормальная готовность. Рекомендуется спокойная аэробная тренировка.
+
+⸻
+
+4.6 Короткое объяснение (опционально)
 
 1–2 строки интерпретации.
 
@@ -160,11 +176,14 @@ HRV: 64
 В первой версии не делаем:
 	•	сложные графики
 	•	baseline как отдельные метрики
-	•	рекомендации тренировок
 	•	планирование
 	•	сравнение с другими днями (кроме простого тренда)
 	•	пользовательские настройки
 
+Важно:
+	•	baseline recommendation и briefing уже есть
+	•	не реализованы более широкие planning features: duration suggestion, calendar-aware timing, workout construction
+
 ⸻
 
 7. Критерии качества
@@ -180,14 +199,22 @@ HRV: 64
 
 Экран использует:
 
-Основной endpoint
+Основные endpoints
+
+GET /api/v1/model/readiness-daily/{user_id}/latest
+
+или
 
 GET /api/v1/model/readiness-daily/{user_id}/{date}
 
 Данные внутри:
 	•	readiness_score
 	•	good_day_probability
 	•	status_text
+	•	recommendation
+	•	reason
+	•	briefing
+	•	data_quality
 	•	explanation_json:
 	•	freshness
 	•	freshness_norm
@@ -200,14 +227,14 @@ GET /api/v1/model/readiness-daily/{user_id}/{date}
 
 После реализации базового экрана:
 
-1. Recommendation layer
-	•	“что делать сегодня”
-
-2. Trend UI
+1. Trend UI
 	•	нормальный график
 
-3. История
+2. История
 	•	экран истории readiness
 
+3. Более широкий planning layer
+	•	duration / timing / context-aware guidance
+
 4. Адаптивные подсказки
-	•	объяснения уровня “инсайтов”
+	•	объяснения уровня “инсайтов” без нарушения deterministic core