# Pending Approval — Adaptive Nutrition & Meal-Plan Workflow

## Status
**pending execution approval**

Planning only; no adaptive-nutrition product source has been implemented in this Ralplan run. The five-pass review ceiling was reached. Stages 13–18 contain the normative technical plan, and stage 19 records the reconciled user intent. Terminal review findings were incorporated into stage 18, but a fresh Architect/Critic pass was not run beyond the configured ceiling; execution must preserve all fail-closed gates and verification listed below.

## Goal
Add an operator-topic-59-only workflow that converts corrected check-ins, the immutable 12-week baseline, trainer schedule/actual sessions, and approved 최코치 evidence into deterministic trend calculations and operator-reviewable nutrition candidates. The LLM explains immutable structured outputs; it never calculates or decides. A customer receives only an explicitly approved exact revision.

## Confirmed product behavior
- Customer-specific weekly weight target; missing target means observe and ask the operator.
- D+29–D+84 extension is customer-specific; no approval means shadow only. D+85 requires review.
- Weight trend determines adjustment direction. Low adherence causes plan maintenance and barrier investigation, not numeric adjustment.
- Protein/fat/calorie-step/cooldown recommendations are allowed, but operator approval is mandatory and global absolute safety bounds remain.
- Actual trainer session evidence overrides planned schedule for high/medium/low carb assignment; ambiguity asks the operator.
- Registration stores versioned Meal count, allergies/exclusions, budget, cooking access, preferences, and training time. Missing inputs block meal-plan compilation.
- Approved catalog only; Meal 1..N, equivalent swaps, and convenience/eating-out fallbacks are deterministic.

## Architecture
1. Keep canonical check-in/trainer events read-only and preserve old-reader compatibility.
2. Add a customer-scoped append-only adaptive stream, strict source-day/sequence/authority journals, and rebuildable projection.
3. Fold corrections through canonical `supersedes`, actual EventType mappings, independent flow namespaces, and orthogonal safety union.
4. Compute deterministic KST current/prior seven-day snapshots, coverage, adherence, confidence, and hard-gate reasons.
5. Resolve one bitemporal active target: immutable baseline or one approved effective overlay.
6. Compile exact integer calorie/macronutrient and high/medium/low candidates; infeasible arithmetic becomes human_review.
7. Compile Meal slots from a versioned approved food catalog and customer constraint digest.
8. Render numbers, foods, quantities, dates, and D+ deterministically. LLM output is digit/quantity-free bounded prose; validator/fallback prevents invention.
9. Use compiler-constrained operator edits, exact revision approval, hold/release, activation, and append-only history.
10. Deliver through an adaptive-only, one-call strict-topic Telegram primitive. Any post-call non-success is unknown and never resent automatically.

## Safety and authority
Hard-gate order: schema/correction integrity → activation/consent/customer → all safety_flag/safety_audit/safety-bearing events → policy/catalog/epoch → date window → samples → adherence/cooldown → feasibility. Every mutating transition reloads live authority under a customer-wide lock. Consent/safety/authority changes block stale cards, approval, activation, and transport.

## Delivery guarantee
One durable reservation and at most one provider invocation per approved revision/destination. A valid single receipt is persisted before sent audit. Unknown result remains unknown unless immutable evidence binds chat, topic 59, message ID, body digest, delivery/revision/attempt, and operator identity. No blind retry or topic fallback.

## Implementation order
1. Schemas, canonical serializer, source-day/sequence/authority journals, lock API.
2. Observation fold and deterministic shadow projector; no personalized values.
3. Bitemporal resolver and disabled policy configuration.
4. Numeric compiler and golden vectors after operator policy configuration.
5. Versioned food catalog, customer meal constraints, Meal compiler.
6. Safe explanation renderer/validator and deterministic fallback.
7. Append-only proposal/revision/approval/effective lifecycle.
8. Adaptive delivery adapter and strict topic-59 transport.
9. Topic-59 Telegram cards/callbacks and operator-console parity.
10. Adherence/evaluation, migration, privacy/runbook, rollback, and complete verification.

## Release gates
- **Gate A — shadow analytics:** all source/journal/crash/rebuild fixtures pass; candidate numeric fields remain null.
- **Gate B — deterministic candidates:** reconciled customer policy/catalog is present and golden arithmetic/meal tests pass.
- **Gate C — operator-only:** exact topic-59 auth, edits, hold/release, stale/race/model fallback tests pass; customer transport remains disabled.
- **Gate D — delivery:** manual test-account proof, strict one-call receipt matrix, consent/safety races, restart reconciliation, and no-resend tests pass.

## Verification requirements
Focused and full profile/gateway suites, compileall, byte-golden canonical fixtures, D+0/1/28/29/84/85, 3/4 and 9/10 weights, 4/5 nutrition days, normal multi-flow days, every correction/journal crash point, overlay replacement/rollback as-of history, Unicode/Decimal order, integer energy lattice, Meal serving/tolerance ties, all feature-flag combinations, actual independent-writer races, every Telegram certainty result, and live topic-59/browser evidence. Existing customer/trainer/manual/scheduled check-in, safety, correction, draft/outbox, 탄·단·지, Meal entry, and Bristol workflows must remain regression-clean.

## Migration / rollback / privacy
Additive 0700 directories and 0600 files/locks only; no rewrite of current events or baseline. Preflight backup/digests/permissions/privacy evidence; idempotent dry run; monotonic feature epochs. Rollback advances epoch and disables delivery→activation→candidates→analytics while preserving audit history. Manual deletion/retention/backup procedure must inventory adaptive streams, indexes, transport caches, exports, Telegram evidence, backups, and restored tombstones.

## ADR
### Decision
Separate append-only adaptive overlay with deterministic policy/meal compilers, strict operator approval, and strict-topic delivery.

### Drivers
Safety and auditability; correction-aware deterministic behavior; operator usability without breaking current pilot workflows.

### Alternatives considered
- LLM-generated calculations/plans — rejected as nondeterministic and unsafe.
- Extending existing draft/check-in lifecycle — rejected due to old-reader, rollback, and authority coupling.
- Observe-only dashboard — retained as Gate A/fallback but insufficient as final capability.

### Why chosen
It keeps the baseline immutable, makes every recommendation reproducible, separates explanation from authority, enables rollback, and provides a clear approval/delivery boundary.

### Consequences
More schemas, journals, locks, migration tests, catalog maintenance, and operator policy setup are required. Missing or contradictory data produces observe/human_review rather than a guessed plan.

### Follow-ups
Populate global absolute safety bounds and customer policy/meal inputs; curate/approve the food catalog; capture manual Gate-D evidence before real customer delivery.

## Intent Reconciliation
The confirmed decisions in stage 19 are binding: customer-specific targets/extensions, trend-first interpretation, low-adherence maintenance, recommendation-with-approval, actual-session-priority carb cycling, versioned Meal constraints, and operator-approved calorie-step/cooldown recommendations.