# Adaptive Nutrition Workflow — Planner Revision 12

## Status
Deliberate planning only; pending consensus and execution approval.

## Principles
1. Deterministic policy owns eligibility and all numeric proposals; LLM only explains validated outputs.
2. No individualized plan reaches a customer without exact operator-topic authorization and explicit approval.
3. Inputs, metrics, proposals, edits, approvals, effective plans, adherence, and evaluations are append-only.
4. Sparse, unsafe, inconsistent, or out-of-window data defaults to observe/human review, never adjustment.
5. Preserve current single-customer routing, safety holds, correction chain, outbox, 탄·단·지, Meal input, and Bristol display.

## Drivers
Safety/auditability; correctness with sparse corrected data; usable operator topic 59 workflow.

## Options
A) LLM computes plans: flexible but nondeterministic/unsafe; reject.
B) Deterministic analytics and policy + LLM explanation + operator approval: chosen.
C) Deterministic fixed templates: safe fallback when model unavailable.

## Architecture
Add six boundaries: correction-aware observation projection; versioned 7-day/prior-7-day trend snapshot; eligibility/numeric policy engine; catalog-bound meal-slot compiler; bounded LLM explanation with numeric allowlist validator; topic-59 operator lifecycle using existing outbox.

### Trend snapshot
Store customer key, KST date/D+, source event IDs/digests and correction head, policy/formula versions. Calculate current/prior 7-day weight sample counts/means/change %, calories and carb/protein/fat samples/means/active-plan adherence, sleep/readiness, training category, Bristol/digestion, appetite/stress, missingness, anomalies, confidence. Never impute; exclude superseded events; preserve zero; explicit rounding.

### Conservative gates
Before plan start/after 12 weeks, safety/consent/activation/schema/correction errors: human_review, no numbers. <4 weight samples/7 days: observe. <10 weight samples/14 days: no calorie change. <5 complete nutrition days/7: no macro/carb cycle. Missing training schedule: no high/medium/low assignment. Repeated concerning digestion/eating risk/very low recovery/implausible rate: human_review. Numeric adjustment remains disabled until operator configures target weekly rate, calorie bounds, protein/fat bounds, max change, cooldown and training schedule.

Outcomes: maintain, observe, calorie_adjustment_candidate, macro_redistribution_candidate, human_review; each has typed reasons and failed gates.

### Numeric policy
Derive weekly energy first. Protein remains within operator-approved range, fat above approved floor, carbs get remaining energy using 4/4/9 kcal/g. High/medium/low days redistribute only within bounds and reconcile exactly to weekly energy/macros. No adjustment during cooldown or when adherence is too low to interpret.

### Meal plans
Meal 1..N slots with macro ranges/timing and validated food-equivalent IDs. Produce Korean-food default, equivalent swaps, convenience/eating-out fallback. Catalog rows require serving units, macro source/version, allergens/restrictions and availability. LLM cannot invent foods/portions/macros. Missing preferences, allergies, restrictions, budget, cooking access, meal count, training time or digestion context yields meal_plan_inputs_missing.

### Doctrine boundary
Public doctrine remains non-prescriptive. Add separate operator_approved_personal_nutrition_policy allowing deterministic advisory candidates only with consent, configured bounds, sufficient observations, active window and operator approval. LLM receives immutable numbers and writes <=500-char Korean rationale. Reject prose containing unknown nutrition numbers and use deterministic template fallback.

### Topic 59 UX
Only `(8693203710,-1004290459350,59)`. Show customer/date/D+, active plan/version, coverage/confidence, trend/adherence/recovery/training/digestion, gate result, deterministic calories and 탄·단·지, high/medium/low table, Meal plans/swaps/fallback, evidence and versions. Buttons: 수정/승인/보류; send is separate after approval. No internal analysis in trainer/customer topics.

### Append-only lifecycle
trend_snapshot_created, policy_decision_created, plan_proposed, plan_explained, plan_edited, plan_held, plan_approved, plan_effective, delivery_reserved, delivered, sent_audited, adherence_recorded, evaluated, superseded. Approval binds proposal+revision+digest+operator+destination. Edits invalidate approval. Receipt retries reconcile without resend.

## Sequence
1 schemas/builders/store; 2 projector/trends; 3 gates/numeric policy disabled by default; 4 catalog/meal compiler; 5 LLM explanation validator/fallback; 6 coordinator/outbox lifecycle; 7 topic-59 cards/callbacks; 8 adherence/evaluation/weekly report; 9 additive migration; 10 shadow mode then operator-only candidates then separately approved delivery.

## Migration/Rollback
Existing events/12-week plan remain authoritative. Additive schemas and rebuildable projections. No automatic effective plan. Feature/policy disabled by default. Rollback disables proposals while retaining audit events and current plan/check-in flow.

## Observability
Counters for gates/reasons, coverage, versions, LLM rejection/fallback, edit/approve/hold, outbox/no-resend, projection mismatch. No raw meals/PII in logs. Operator health shows stale policy/catalog and unknown delivery.

## Premortem
1 Sparse/noisy data causes cuts: sample/adherence/cooldown/shadow gates. 2 LLM invents values: immutable proposal, numeric validator, catalog, fallback. 3 duplicate/wrong-space delivery: exact topic, digest binding, durable receipt and no-resend reconciliation.

## Tests
Unit: correction projection, windows/KST/D+, missing/zero/outlier, confidence, gates, 4/4/9 math, rounding/reconciliation, catalog/restrictions, numeric prose validator. Integration: events-to-proposal, disabled defaults, consent/safety revocation, approval invalidation, pinned versions, rebuild, crash/concurrency outbox. E2E: synthetic 14-day maintain/observe/adjust/review, topic 59 isolation, edit/hold/approve/send once, restart and retry no duplicate. Observability: counters, no PII, stale config and digest alerts.

## Acceptance
Byte-stable outputs for same inputs/versions; latest cumulative correction only; no adjustment without configured bounds/minimum evidence; safety/consent/window failures block; high/medium/low reconciles; meal catalog only; LLM cannot alter numbers; internals only topic 59; every revision reconstructable; exactly-once approved delivery; existing flow regression-clean when disabled.

## Open intent items
Target weekly weight-rate by goal; max calorie change/cooldown; protein/fat bounds; carb-cycle spread/schedule; meal count/catalog/budget/cooking/allergy constraints. These require user confirmation before numeric proposals are enabled.