# Pre-first-customer nutrition readiness gate

Status: **BLOCK**

This gate is the launch authority for the first real nutrition customer. A room-bootstrap
activation receipt alone is not sufficient evidence that nutrition coaching is safe to start.

## Current-state evidence

- Customer Telegram self-intake collects daily check-in values, not onboarding baseline.
- The operator-created profile has goals, calorie/macronutrient targets, restrictions,
  allergies, preferences, supplements, digestion, sleep, recovery, and training context.
- The profile schema has no age/date of birth, equation sex basis, height, activity basis,
  target weight/date, medication, condition, pregnancy/breastfeeding applicability, or
  calculation provenance.
- The enabled synthetic fixture has 12 plan weeks but one distinct target set and no
  BMR/TDEE method/version, input digest, reviewer receipt, or adjustment policy.
- Customer-specific meal constraints and approved artifacts are versioned and digest-pinned.
- The knowledge layer is a limited post-checkin doctrine/source catalog, not a versioned
  restriction/contraindication knowledge base.
- The live Gate-D preflight detects its stale plan window but does not detect the missing
  baseline, calculation provenance, or global restriction knowledge.

## Chosen authority boundary

Use a two-phase authority model:

1. `nutrition-start-readiness-v1` is committed while the customer is still disabled.
2. Canonical activation consumes that exact committed readiness receipt.
3. Meal-plan/coaching entry requires both the readiness receipt and canonical activation
   receipt, while all delivery/activation feature flags remain false.

Do not add these checks directly to the existing post-activation Gate-D preflight. That
preflight requires an enabled customer and activation receipt, which would make a
pre-activation safety check circular.

## Required canonical artifacts

All artifacts must be private regular files, non-symlinked, canonical-JSON digest-pinned,
versioned, timestamped in KST, and approved by the canonical owner. Raw health values must
never appear in readiness command output.

### Global artifact

`knowledge/nutrition-safety/restriction-kb-v1.json`

Required fields:

- `schema_version`
- `knowledge_version`
- `effective_at_kst`
- `reviewed_at_kst`
- `reviewed_by`
- `sources[]`: source identifier, title, URL/DOI/PMID, publication/review date
- `allergens[]`
- `intolerances[]`
- `religious_ethical_exclusions[]`
- `medication_condition_rules[]`
- `hard_contraindications[]`
- `cross_contact_rules[]`
- `substitution_rules[]`
- `digest`

Every rule needs a stable ID, severity, applicability conditions, action
(`exclude`, `require_human_review`, or `inform`), and source IDs.

### Customer baseline artifact

`data/customers/<customer_key>/nutrition-onboarding/baseline-v1.json`

Required fields:

- identity reference: customer key and Telegram authority digest, not duplicated display data
- date of birth or validated adult age
- equation sex basis, stored explicitly as the calculation input rather than inferred identity
- height with source unit and normalized centimetres
- current weight with source unit and normalized kilograms
- baseline activity category and coach-reviewed rationale
- goal type, target weight, target date, and maintenance intent
- dietary preferences and disliked foods
- allergies and intolerances
- religious/ethical exclusions
- conditions and medications relevant to nutrition/weight management
- pregnancy/breastfeeding applicability
- cooking access, budget band, meal count, and schedule constraints
- customer attestation timestamp
- owner and trainer review receipts
- digest and superseded digest

The gate rejects under-18 customers, pregnancy/breastfeeding, medically material
conditions/medications, implausible measurements, or an unsafe requested trajectory from
automatic planning. These cases require an explicit external qualified-clinician clearance
receipt before any automated plan.

### Calculation artifact

`data/customers/<customer_key>/nutrition-onboarding/initial-plan-v1.json`

Required fields:

- `method_id`: e.g. `mifflin_st_jeor_1990`
- `method_version`
- `baseline_digest`
- `restriction_kb_digest`
- normalized input digest
- estimated REE/BMR and units
- activity assumption and reviewed TDEE estimate
- goal trajectory and safe-rate guardrail
- 12 ordered weekly calorie/macronutrient targets
- minimum/maximum safety bounds
- reviewer identity, review timestamp, and review decision
- calculation digest

The initial estimate is separate from adaptation. Formula output is an estimate, never an
unreviewed truth value.

### Adjustment-policy artifact

`data/customers/<customer_key>/nutrition-onboarding/adjustment-policy-v1.json`

Required fields:

- policy version and effective date
- minimum observation window
- weight-trend method
- adherence and actual-intake inputs
- activity-change inputs
- adjustment thresholds and maximum step size
- plateau/weight-gain escalation rules
- medical/safety stop rules
- manual-override receipt requirements
- reviewer identity and digest

Weekly changes use observed trajectory, adherence, actual intake, and activity changes.
They must not blindly preserve the initial deficit or react to one weigh-in.

### Readiness receipt

`data/customers/<customer_key>/nutrition-onboarding/readiness-receipt-v1.json`

The receipt pins:

- baseline digest
- global restriction-KB digest
- resolved customer-restriction reconciliation digest
- initial-plan digest
- adjustment-policy digest
- owner review receipt
- trainer review receipt
- current `privacy-v1` consent receipt
- delivery/activation feature epoch proving all flags false
- issue timestamp, expiry, and canonical owner signature/digest

## Fail-closed checks and reason codes

The read-only audit returns only booleans, counts, digests, and reason codes.

- `baseline_missing`
- `baseline_schema_invalid`
- `baseline_not_customer_attested`
- `baseline_owner_review_missing`
- `baseline_trainer_review_missing`
- `customer_not_adult`
- `pregnancy_breastfeeding_requires_clinical_review`
- `medical_clearance_required`
- `measurement_implausible`
- `goal_trajectory_unsafe`
- `restriction_kb_missing`
- `restriction_kb_stale`
- `restriction_kb_unapproved`
- `restriction_sources_incomplete`
- `customer_restrictions_unresolved`
- `hard_contraindication_unresolved`
- `calculation_missing`
- `calculation_method_unapproved`
- `calculation_inputs_stale`
- `calculation_review_missing`
- `weekly_targets_incomplete`
- `adjustment_policy_missing`
- `adjustment_policy_unapproved`
- `privacy_consent_missing`
- `authority_receipt_stale`
- `feature_flags_enabled`
- `delivery_enabled`
- `activation_receipt_missing` (post-activation start check only)

Any reason code means `ready=false`.

## Enforcement call sites

1. Add a typed, side-effect-free `audit_nutrition_start_readiness(...)` domain function next
   to the profile authority code, but keep its receipt separate from `GateDPreflightReceipt`.
2. Invoke it inside the canonical locked activation path before the registry `enabled` write.
   Activation must consume the exact committed readiness receipt digest.
3. Re-run the audit in the adaptive plan proposal/service boundary before loading approved
   meal artifacts. This prevents direct non-Telegram callers from bypassing activation.
4. Re-run the post-activation subset before customer check-in/coaching entry. Require the
   canonical activation receipt and current delivery-disabled feature epoch.
5. Keep `compile_meal_plan(...)` pure. Pass only already-reconciled constraints into it;
   profile I/O and authority checks belong in orchestration.

## RED test matrix for implementation

Before production changes, each test must fail because the current authority accepts or lacks
the named evidence:

1. Complete disabled-customer fixture produces a committed readiness receipt.
2. Missing age, equation basis, height, weight, activity, goal, or target date rejects with
   the exact baseline reason code.
3. Under-18, pregnancy/breastfeeding, unsafe trajectory, implausible measurements, and
   medically material inputs reject automatic planning.
4. Missing/stale/unapproved global KB or incomplete source provenance rejects.
5. Allergy/intolerance/medication/condition/religious-ethical conflicts reject until a
   versioned reconciliation receipt resolves them.
6. Missing/stale Mifflin-St Jeor method/version/input digest/reviewer receipt rejects.
7. Fewer than 12 ordered weekly targets or one target copied without explicit reviewed
   maintenance rationale rejects.
8. Missing adjustment policy or manual override receipt rejects.
9. Activation cannot enable the customer without the exact readiness receipt.
10. Adaptive proposal and customer coaching entry reject a stale receipt after any pinned
    artifact changes.
11. Current privacy-v1, canonical activation receipt, owner/trainer route authority, and
    delivery=false tests remain green.
12. Readiness output never contains raw age, weight, height, sex basis, condition,
    medication, or allergy values.

## Safe implementation and start sequence

1. Implement the four artifact schemas and canonical digest validators.
2. Build and approve the global restriction KB with cited sources and a review cadence.
3. Add remote customer baseline intake and explicit owner/trainer review.
4. Add the versioned initial estimate and separate adjustment-policy calculator.
5. Implement the two-phase readiness receipt and activation consumption.
6. Add the second enforcement check at adaptive proposal/coaching entry.
7. Run the RED matrix to GREEN plus existing bootstrap, activation, adaptive nutrition,
   customer-admin, and Telegram group-gating suites.
8. Run the read-only command on the real customer draft. It must be `ready=true` without
   printing personal values.
9. Keep the customer disabled and all delivery/activation flags false while performing the
   supervised Telegram rehearsal.
10. Execute canonical activation only after owner approval; verify both receipts and keep
    delivery false until the separate human rollout decision.

## Launch verdict

**BLOCK.** Do not onboard or activate the first real customer yet. Existing customer-specific
allergen filtering and artifact provenance are useful foundations, but they do not replace
the missing baseline, global safety knowledge, calculation provenance, adjustment policy,
and two-phase readiness authority.