# LLM-Owned Nutrition Coaching

## Goal

Replace the bounded action-ID/finite-phrase coaching path with one grounded
Coach call that owns interpretation, numeric recommendations, rationale, and
customer draft, followed by deterministic integrity/safety validation and one
free Polish call. Preserve operator approval, stale-revision rejection,
delivery-disabled behavior, silent customer free text, and trainer-only
internal handoff.

## Constraints

- Work surgically inside the existing dirty gateway and profile trees.
- Never reset, stash, clean, commit, push, call a live provider/customer, or
  enable delivery.
- Exactly one Coach and one Polish call per accepted generation.
- Code supplies facts and computes metrics; it does not preselect targets.
- Hard blocks cover only malformed or untrustworthy results and explicit safety
  violations. Aggressive/low-evidence proposals remain reviewable with soft
  warnings.
- Operator approval remains the final authority.
- Customer free text receives no AI reply.
- Trainers do not join nutrition customer rooms; they receive only concise
  training-relevant internal handoff.

## Architecture

### Coach request

Extend the judgment grounding contract with:

- schema version, customer key, authority/revision digest;
- current calorie/macronutrient targets and units;
- verified current check-in facts;
- bounded recent-history facts and computed metrics;
- available evidence identifiers and approved principles;
- data-quality/sample metadata;
- untrusted customer notes in a clearly fenced data field.

Do not include action choices or candidate target numbers.

### Coach response

Introduce a strict `nutrition-coach-response-v2` contract:

- identity and revision binding;
- decision category (`maintain`, `adjust`, `observe`, `safety_hold`);
- confidence;
- referenced evidence identifiers;
- concise interpretation/rationale;
- recommended calorie/protein/carbohydrate/fat targets with explicit units;
- next-check-in focus identifiers;
- free Korean customer draft.

### Validation

Normalize the V2 response into an immutable validated proposal.

Hard-block:

- malformed/extra/missing fields;
- identity or revision mismatch;
- non-finite, negative, or wrongly typed targets;
- unsupported or inconsistent units;
- target/delta arithmetic inconsistency;
- unknown evidence or next-focus identifiers;
- numbers in rationale/customer draft that are absent from verified inputs or
  the structured recommendation;
- explicit medication, hormone, dehydration, diagnosis, emergency-bypass, or
  other prohibited content;
- safety-hold inputs paired with an ordinary nutrition adjustment.

Soft-warn without blocking:

- low confidence;
- sparse valid samples;
- large calorie/macronutrient delta;
- adjustment while adherence or recovery is poor;
- recommendation direction that diverges from deterministic baseline/reference.

### Polish

Send the validated Coach draft, locked structured recommendation, available
facts/numbers, and tone/length guidance to one Polish call. Accept a free Korean
message when it introduces no ungrounded number, prohibited content, customer
identity, or incompatible target. Otherwise use the validated Coach draft.

### Persistence and authority

- Persist raw Coach response digest, normalized V2 proposal, validation
  warnings, raw/accepted Polish output, and final operator edits.
- Every persisted proposal binds to customer and live authority revision.
- Operator target or copy edits advance revision and invalidate stale
  Coach/Polish artifacts.
- Approval and delivery re-read live authority under the existing lock.
- V1 pending drafts remain auditable but cannot be newly approved; regenerate
  them as V2.

### Role UX

Operator card:

- verified facts and sample quality;
- Coach decision/confidence/rationale;
- current-versus-proposed calorie/macronutrient delta;
- hard-block or soft-warning section;
- editable customer copy;
- regenerate, edit, approve, and hold controls.

Customer room:

- check-in/reminder/buttons and approved bot posts only;
- ordinary customer free text gets no AI completion;
- operator continues the human conversation in the shared private room.

Trainer surface:

- internal handoff only when verified facts affect training readiness;
- concise recovery/adherence/hold summary;
- no nutrition conversation transcript and no membership in customer room.

## RED → GREEN Execution

### Coach V2 domain

1. Characterize current approval, delivery-disabled, and stale-revision
   behavior.
2. Add failing tests showing a grounded, non-preoffered numeric recommendation
   and free draft are rejected/ignored.
3. Add failing hard-block cases: malformed, non-finite, negative, bad unit,
   arithmetic mismatch, unknown evidence, unsafe content, wrong identity, stale
   revision.
4. Add failing soft-warning cases proving aggressive/sparse/low-confidence
   output must remain reviewable.
5. Implement the smallest typed V2 request, response, validator, and normalized
   proposal until focused tests pass.

Command:

```bash
cd /home/cube/projects/richard/hermes-agent
.venv/bin/pytest -q tests/gateway/test_nutrition_coaching_judgment.py \
  -k 'v2 or free_numeric or hard_block or soft_warning'
```

Evidence: `/tmp/ulw-coach-v2-evidence/coach-validation.txt`

### Free Polish

1. Add a failing test proving a valid free Korean rewrite is rejected by the
   current finite variant contract.
2. Add failing changed/new-number and prohibited-content cases.
3. Implement free Polish parsing and integrity validation with Coach-draft
   fallback.

Command:

```bash
cd /home/cube/projects/richard/hermes-agent
.venv/bin/pytest -q tests/gateway/test_korean_humanizer.py \
  -k 'coach_v2 or free_polish or numeric_integrity'
```

Evidence: `/tmp/ulw-coach-v2-evidence/polish.txt`

### Integration and role surfaces

1. Add failing nc1/adaptive tests for V2 current/proposed/warning rendering,
   exactly one Coach/Polish call, operator edits, and revision drift.
2. Add failing role tests proving customer free text remains silent and trainer
   sees only internal handoff.
3. Wire nc1/adaptive through shared V2 generation, validation, Polish, and
   authority recheck.
4. Render the operator review sections and controls without changing delivery
   policy.

Command:

```bash
cd /home/cube/projects/richard/hermes-agent
.venv/bin/pytest -q \
  tests/gateway/test_telegram_nutrition_onboarding.py \
  tests/gateway/test_nutrition_coaching.py \
  -k 'coach_v2 or operator_card or revision_drift or preapproval'
```

Evidence: `/tmp/ulw-coach-v2-evidence/operator-integration.txt`

### Real-surface QA

Run deterministic local provider/transport doubles through the actual gateway
handlers:

```bash
cd /home/cube/projects/richard/hermes-agent
.venv/bin/python /tmp/ulw_coach_v2_role_qa.py \
  | tee /tmp/ulw-coach-v2-evidence/role-surface.txt
```

Required observables:

```text
coach_calls=1
polish_calls=1
operator_state=pending
operator_has_facts=true
operator_has_delta=true
operator_has_warning=true
customer_approved_post=true
customer_free_text_ai_replies=0
trainer_handoff_only=true
trainer_in_customer_room=false
customer_sends=0
cleanup=pass
```

Remove the driver and all QA-only customer/profile state immediately after
capture.

### Regression and review

- Run full relevant gateway nutrition, Telegram, adaptive, operator, canonical,
  and dual-profile suites.
- Run Ruff, compileall, `git diff --check`, canonical/dual parity,
  delivery-disabled, no-new-skip/xfail, and QA residue audits.
- Record `/tmp/ulw-coach-v2-evidence/regression.txt`.
- Submit this plan, diff, notepad, and evidence to momus.
- Fix every criterion-cited blocker and rerun only affected scenarios.
- Stop only after unconditional approval, completed todos, cleanup, and the
  registered goal completion audit.

## Delegation

- Architecture child: attempted for the cross-domain schema/UX design but
  closed inconclusive after four silent checks; this direct plan uses the
  already-read call graph and contracts.
- Lead: sole writer and verifier to preserve RED-before-GREEN ordering in the
  shared dirty worktree.
- Momus: final plan-gated read-only reviewer after all evidence exists.