# wellness-nourish — Deep Quality Audit · 2026-05-08

**Status**: complete
**Scope**: `wellness-nourish` core + delx-wellness ecosystem standardization
**Auditor**: Hermes Agent (Nous Research) running in long-session mode
**Reviewer / second pass**: Claude (Delx Code) on Opus 4.7
**Time on target**: ~11 hours (10:23 – 21:21 UTC)
**Outcome**: 14 PRs merged across 6 repos · CI green on all · 1 CVE caught

---

## 1. Summary

`wellness-nourish` was deep-audited end-to-end for bugs, resilience, security,
correctness, agent UX, and locale handling. The audit drove **8 stacked
release sprints** (versions `0.2.3` → `0.2.10`), each landing a category of
fixes or features with regression tests. Total: **13 bugs fixed**, **5
features added**, **1 CVE caught and patched**, **1 cross-MCP standard
defined and registered** (`delx-wellness-context/v1`).

This document reconstitutes the chat-ephemeral findings of the audit so they
are committed to the repo and survive context compaction.

### Goal alignment

> *"testar profundamente o nosso mcp nourish para achar o maximo de bugs e
> pontos de melhorias e gerar uma relatorio extramemnte completo para deixar
> esse mcp perfeito"* — David, 2026-05-08

- **Bugs and improvements found**: 13 bugs, 5 feature gaps, 1 CVE → all
  addressed with regression tests in the same release.
- **Complete report**: this document.
- **Nourish "perfect"**: ~80%. Two known gaps remain after the campaign:
  wearable-aware coach reasoning, and Vitest/Jest test infrastructure
  migration. Both are tracked in §10.

---

## 2. Methodology

The audit used a roadmap-driven sprint pattern, each sprint scoped to a
category of QA findings:

1. **Static read** of every tool registered in `src/tools/nourish-tools.ts`
   (32 → 38 over the campaign), the supporting services in
   `src/services/`, and every provider in `src/providers/`.
2. **Behavioral probes** via MCP stdio JSON-RPC against the running server,
   exercising each tool with valid + adversarial inputs.
3. **Runtime probes** for concurrency (parallel calls to `setGoals`,
   `rememberMeal`), timezone edge cases, file-path handling on image
   tools, and provider-down scenarios (USDA / Open Food Facts).
4. **Per-finding categorization** P1 / A1-A2 / B1-B5 / C1-C5 / D1-D3 /
   E1, prioritized by impact.
5. **Per-sprint PR**: one PR per category, each with a regression test
   added in the same commit so the bug class cannot reappear silently.
   Sprints stacked on each other (PR #8 based on #7's branch, etc.) so
   diffs stayed reviewable.
6. **Final standardization wave**: cross-MCP `delx-wellness-context/v1`
   contract defined and applied to WHOOP / Strava / Garmin / Nourish /
   Exercise Catalog so `wellness-nourish` is composable with the rest
   of the ecosystem.

---

## 3. Findings — Bugs (P1 / A / B / C tier)

### 3.1 P1 sweep (Sprint 1, v0.2.3, PR #7)

| ID | Finding | Resolution |
|----|---------|------------|
| P1-1 | `intake_log` precedence — direct `food_ref` payload was overridden by re-estimation | `nourish-tools.ts` short-circuits to direct lookup when caller supplies `food_ref` |
| P1-2 | `custom_food` portion scaling — grams field ignored when `unit !== "g"` | `portion-engine.ts` now scales nutrients with explicit grams override |
| P1-3 | `delete_water` not exposed (existed but unregistered) | Tool registered + listed in agent-manifest |
| P1-4 | Pt-BR comma decimals (`"2,5 ovos"`) parsed as zero | Quantity parser normalizes `,` → `.` |
| P1-5 | Zero / negative quantity sliding through estimator | Schema rejects `quantity <= 0` with `USER_ACTION_REQUIRED` |

### 3.2 Resilience (Sprint 2, v0.2.4, PR #8)

| ID | Finding | Resolution |
|----|---------|------------|
| E1 | USDA / OFF calls had no timeout — agent stalls indefinitely on provider hang | New `services/http.ts` wrapper with `AbortController` 10s default + exponential backoff retry; configurable via `NOURISH_PROVIDER_TIMEOUT_MS` |
| B1 | Open Food Facts down → barcode tools error instead of degrading | Returns structured `NourishHttpError` with `transient: true`, agents can fall back to local provider |
| B5 | Image analysis errored when barcode mid-call failed | `analyze_food_image` now falls through to OCR + visual estimator on barcode failure |
| — | `connection_status` did not expose timeout config or warn on USDA demo-key throttle | Added `provider_timeout_ms`, `warnings: string[]`, `usda_using_demo_key: boolean` |

### 3.3 Date / time correctness (Sprint 3, v0.2.5, PR #9)

| ID | Finding | Resolution |
|----|---------|------------|
| A1 | Three independent `todayDate()` helpers all returned UTC ISO date — São Paulo user at 22:30 BRT got "tomorrow's" summary | Centralized into `services/local-date.ts`. Resolution order: `NOURISH_TIMEZONE` env → `Intl.DateTimeFormat().resolvedOptions().timeZone` → UTC fallback |
| B4 | `intake-store` and `hydration-store` derived `entry.date` via `timestamp.slice(0, 10)` (UTC) | Both now use `localDateFor(timestamp)` |
| — | `dateToNoonTimestamp(date)` used `${date}T12:00:00.000Z` — early-morning local for east-of-UTC users | Now writes noon-LOCAL ISO via timezone-aware helper |

### 3.4 Security & integrity (Sprint 5, v0.2.7, PR #11) ← **includes CVE**

| ID | Finding | Severity | Resolution |
|----|---------|----------|------------|
| **B3** | **Path traversal in image tools (CVE-class)** — `nourish_decode_barcode_image`, `nourish_lookup_barcode_image`, `nourish_analyze_food_image` accepted any filesystem path including `/etc/passwd`, `~/.ssh/id_rsa` | **Critical** | New allowlist: resolved path must sit under `NOURISH_LOCAL_DIR` ∪ OS temp dir ∪ `NOURISH_IMAGE_DIR`. Null-byte injection rejected; `..`-style escapes caught after `path.resolve` |
| A2 | Lost-update race in goals + personal-memory — two parallel `set_goals` or `remember_meal` calls clobbered each other | High | New `services/locked-store.ts` `withLock(key, fn)` mutex + atomic-write `writeAtomically(path, data)` consolidating temp-file + rename across stores |
| C2 | Coach pt-BR strings hardcoded — en-US agent received Portuguese text it could not feed back into estimator | Medium | Locale-keyed lookup table in `chooseSuggestionText`; en-US + pt-BR entries; unknown locales fall back to en-US |

The B3 vulnerability would have allowed an agent (or a malicious file path
passed through Telegram) to read arbitrary files on the host. Caught
during the Sprint 5 audit pass; patched in the same PR; regression tests
in `scripts/test-security-and-locks.mjs` cover `/etc/passwd`,
`/etc/../etc/passwd`, `~/../../../../etc/shadow`, and the safe-path-under-
tmpdir case.

### 3.5 Locale & parsing (final wave, v0.2.10, PR #14)

| ID | Finding | Resolution |
|----|---------|------------|
| — | `cleanUnresolvedTerm` corrupted short pt-BR food names — `"abacate"` → `"bacate"` after stripping leading "a" as quantity | Rewrote regex to require unit / whitespace / EOL boundary after a leading quantity token |
| — | No pt-BR word-quantity parsing — `"uma banana"`, `"duas bananas"`, `"três ovos"` all failed | `QUANTITY_WORDS` map (en + pt-BR) composed into `QUANTITY_PATTERN`; `parseQuantity()` resolves word tokens |
| — | `displayNamePtBr` field added to `SimpleFood` but only 12 of 35 entries populated | Tracked as gap; addressed in follow-up PR (see §10) |

---

## 4. Findings — Features added

### 4.1 Carbon-aware nutrition (Sprints 4 + 7, v0.2.6 + v0.2.9)

`wellness-nourish` is now **the only nutrition MCP that answers "how much
CO₂ is on my plate?"** — a strategic differentiator identified in the
dataset-research audit.

- 🆕 **`nourish_carbon_summary` tool** — kg CO₂-equivalent per meal or
  per logged day; lower-carbon swap suggestions; lifestyle-equivalents
  (`equivalents.km_driven_avg_car`, `smartphone_charges`); `unmatched_count`
  so agents flag missing data instead of fabricating.
- 🆕 **TACO 4 (UNICAMP/NEPA) Brazilian provider** — 58 → 106 curated
  entries (full ~597-row Excel ingest gated on UNICAMP redistribution
  license confirmation; outreach letter queued before 1.0).
- 🆕 **Carbon-footprint dataset** — 60 → 118 entries from Agribalyse
  3.1 (Etalab Open License) and Our World in Data / Poore & Nemecek
  2018 (CC-BY 4.0). Each entry tags `confidence: high | medium | low`
  so agents can decide trust.
- 🆕 **`carbon` field on `FoodItem`**, auto-populated by TACO and
  (post-Sprint 7) USDA + Open Food Facts via token + diacritic-aware
  matching.
- 🆕 **`services/carbon-enrichment.ts`** — `lookupCarbon(name)`,
  `enrichWithCarbon(food)`, `computeMealCarbon(items)`,
  `suggestCarbonSwaps(items, topN)`, `carbonDatasetSize()`.

### 4.2 Agent UX wins (Sprint 6, v0.2.8, PR #12)

- 🆕 **`nourish_bulk_log_intake`** — log 1-20 meals atomically with one
  `explicit_user_intent` flag. Per-item success/failure so partial
  failures don't lose the rest.
- 🆕 **`nourish_compare_days`** — diff per-nutrient between two dates,
  `deltas` with `percent_change`, `entry_count_delta`,
  `hydration_delta_ml`, `by_meal_changed` (≥20 kcal or ≥2g protein
  delta).
- 📊 **`nourish_daily_summary` accepts `compare_to`** — `"yesterday"`,
  `"7d_avg"`, or `"none"`. Returns `comparison` block with deltas
  (and `avg_baseline` for 7d_avg). Powers trend-aware coaching
  ("your protein is low again — third day in a row").
- 🔍 **`nourish_list_intake` filter combinators** — `since`, `until`,
  `meal_type`, `tag`, `source_trace`, `min_confidence`, `limit`, all
  AND-ed. Most-recent-first. Backward compatible.

### 4.3 Recovery primitives (Sprint 3, v0.2.5, PR #9)

- 🆕 **`nourish_undo_last`** — undo the most recent intake or hydration
  entry. Most common Telegram recovery move ("I logged the wrong
  thing"). Same `explicit_user_intent` guard as `delete_intake` /
  `clear_day`.

### 4.4 Discoverability

- `connection_status` exposes `timezone` (resolved IANA), `provider_timeout_ms`,
  `warnings: string[]`, `usda_using_demo_key: boolean`.
- Agent-manifest TOOLS list synced with every release (no orphan tools).

---

## 5. Cross-MCP standardization (final wave)

### 5.1 `delx-wellness-context/v1` contract

A single contract version applied to WHOOP / Strava / Garmin / Nourish /
Exercise Catalog. Each context payload carries:

- `context_contract_version: "delx-wellness-context/v1"` (literal)
- `context_type`: `"wellness_context"` (state — recovery / sleep) |
  `"training_context"` (activity load) | `"nutrition_context"` (intake) |
  `"exercise_context"` (catalog)
- `recommended_handoff: { tool: string, reason: string }` so producers
  declare the next step in the agent flow

Wearables added the contract to schema, builder, markdown formatter, and
fixture tests in identical-shape PRs. Strava additionally declares
`privacy: { gps: "withheld_from_context", route_details: "not_included" }`
because it is the only context source carrying GPS.

### 5.2 `context_ready` registry tier

`delx-wellness/registry.json` was updated so each connector can declare
itself `quality.tier: "context_ready"`. The
`docs/connector-quality-standard.md` defines what the tier requires:
shared field names (`recovery_score`, `recent_training_load`, etc.),
read-only context tools, fixture-testable, no network in CI.

**Known limitation**: as of the merge, the standard is doc-only and
self-asserted. A validator script that mechanically verifies a
`context_ready` connector exposes the documented fields is queued as
follow-up work (see §10).

### 5.3 Exercise Catalog orchestration

`exercise-catalog-mcp` introduced `CatalogOrchestrator` with per-exercise
`source_metadata` (provider, boundary, license, attribution_required,
commercial_use_allowed, raw_source_id, media_policy). License is enum-
typed (`private | unlicense | mit | cc-by-sa | unknown`). The current
"Befit" provider is explicitly stamped `boundary:
private_authorized_personal_use` while the open-data expansion plan
(`docs/plans/2026-05-08-open-exercise-data-expansion.md`) commits to
specific public datasets:

- Primary: yuhonas/free-exercise-db (873 exercises, Unlicense)
- Enrichment: Glowupp-app/open-exercisedb (322, MIT)
- Optional: wger API (845, CC-BY-SA, AGPL code)
- Explicitly **rejected**: ExerciseDB OSS (non-commercial, would block
  Delx commercial-use posture)

---

## 6. Test coverage

### What landed

- 15 smoke / fixture scripts under `scripts/`:
  `test-meal-estimator`, `test-providers`, `test-intake-store`,
  `test-hydration-goals`, `test-image-tools`, `test-summary`,
  `test-ux-tools`, `test-carbon`, `test-normalization`,
  `test-security-and-locks`, `test-local-date`, `test-http-helper`,
  `agent-readiness-test`, `cli-ux-test`, `privacy-redaction-test`,
  `hermes-agent-manifest-test`, `metadata-check`.
- All wired into `package.json` `test` script as a single chain;
  CI runs the full chain on Node 20 / 22 / 24.
- Each release sprint's regression tests added in the same commit
  as the fix; all sprints leave the chain green.

### What is missing

- **No Vitest / Jest unit-test framework.** All tests are smoke-style
  `.mjs` scripts using `node:assert`. There is no coverage report, no
  per-tool spec, no parameterized fixtures, no mock provider.
- **No negative tests** for schema rejection on the new
  `delx-wellness-context/v1` contract (e.g., wrong contract version,
  missing handoff).
- **No Strava GPS-absence test** — the privacy boundary is currently
  enforced by code review, not by an assertion that walks the JSON
  tree for `polyline` / `start_latlng` / `map` / `gps_*` keys.

A migration to Vitest is planned post-launch (see §10).

---

## 7. Security posture

After the campaign:

- Tokens never appear in tool output (`PRIVACY_MODE=structured` default
  redacts upstream payloads).
- Image-path tools validate against the host filesystem (post-B3 patch).
- Mutation locks prevent lost-update race in goals + personal-memory
  (post-A2 patch).
- Coach output respects caller `locale` (post-C2 patch).
- `image_path` allowlisting canonicalizes symlinks via `realpath` so
  links inside `NOURISH_LOCAL_DIR` cannot escape (post-0.2.9 hardening).

A `privacy_audit` MCP tool is exposed so an agent can verify posture
without calling the upstream API.

---

## 8. Known performance characteristics

- Default provider timeout: 10s (configurable via
  `NOURISH_PROVIDER_TIMEOUT_MS`).
- Single retry on transient failures (5xx / 429 / network / timeout)
  with exponential backoff.
- `NOURISH_CACHE=sqlite` enables provider response caching with
  `cache_ttl_seconds` (default 3600s).
- `agent-readiness-test` exercises the cold-boot agent-manifest +
  capabilities + connection-status path under 1s on the reference
  hardware.

No formal performance / latency targets were set during this audit; a
follow-up benchmark suite is queued.

---

## 9. PR ledger

All 14 PRs merged with green CI on Node 20 / 22 / 24. CodeRabbit pass
on `exercise-catalog-mcp#2`.

| Repo | PR | Title | Sprint | Version |
|------|----|-------|--------|---------|
| `wellness-nourish` | [#7](https://github.com/davidmosiah/wellness-nourish/pull/7) | P1 QA findings (intake / custom_food / hydration / pt-BR / qty) | 1 | 0.2.3 |
| `wellness-nourish` | [#8](https://github.com/davidmosiah/wellness-nourish/pull/8) | provider timeouts, graceful degradation, image fallback | 2 | 0.2.4 |
| `wellness-nourish` | [#9](https://github.com/davidmosiah/wellness-nourish/pull/9) | A1 timezone bucketing + `nourish_undo_last` | 3 | 0.2.5 |
| `wellness-nourish` | [#10](https://github.com/davidmosiah/wellness-nourish/pull/10) | TACO provider + carbon footprint + `nourish_carbon_summary` | 4 | 0.2.6 |
| `wellness-nourish` | [#11](https://github.com/davidmosiah/wellness-nourish/pull/11) | A2 mutation locks + B3 path traversal + C2 coach locale | 5 | 0.2.7 |
| `wellness-nourish` | [#12](https://github.com/davidmosiah/wellness-nourish/pull/12) | bulk_log + compare_days + summary trends + list filters | 6 | 0.2.8 |
| `wellness-nourish` | [#13](https://github.com/davidmosiah/wellness-nourish/pull/13) | TACO 58→106 + carbon 60→118 + USDA/OFF carbon enrichment | 7 | 0.2.9 |
| `wellness-nourish` | [#14](https://github.com/davidmosiah/wellness-nourish/pull/14) | pt-BR quantity parsing + localized names | final | 0.2.10 |
| `delx-wellness` | [#4](https://github.com/davidmosiah/delx-wellness/pull/4) | define context-ready wellness MCP standard | final | — |
| `whoop-mcp` | [#11](https://github.com/davidmosiah/whoop-mcp/pull/11) | version WHOOP wellness context handoff | final | — |
| `strava-mcp` | [#11](https://github.com/davidmosiah/strava-mcp/pull/11) | version Strava training context handoff (with GPS privacy) | final | — |
| `garminmcp` | [#11](https://github.com/davidmosiah/garminmcp/pull/11) | version Garmin wellness context handoff | final | — |
| `exercise-catalog-mcp` | [#2](https://github.com/davidmosiah/exercise-catalog-mcp/pull/2) | route catalog through source-aware orchestrator | final | — |
| `wellness-nourish` | [#2](https://github.com/davidmosiah/wellness-nourish/pull/2) | `coach.focus` schema default unblocks mode-aware fallback | parallel | 0.2.10 |

---

## 10. Remaining gaps & follow-up plan

The following are tracked for the next campaign:

### High priority

1. **Wearable-aware coach reasoning** — the `wellness_context` /
   `training_context` payloads are now *received* by `nourish_*` coach
   tools, but `chooseSuggestionText()` does not yet read
   `recovery_score`, `hrv_ms`, `strain_score`, `body_battery`, or
   `recent_training_load`. The agent client can reason over the
   passed-through context, but the coach itself does not. Closing
   this loop unlocks the "first cross-connector wellness coach that
   reasons across providers" narrative for the Delx Wellness launch.

2. **`displayNamePtBr` 100% coverage** — only 12 of 35 SIMPLE_FOODS
   entries had the new field populated by PR #14. Fallback to
   `food.canonical` masks the gap when canonical is already pt-BR,
   but the field is the source-of-truth for human display.

3. **`context_ready` validator** — `delx-wellness` PR #4 is doc-only
   with no CI enforcement. A connector marked `context_ready` in
   `registry.json` is not mechanically verified to expose the
   documented fields.

### Medium priority

4. **Strava `privacy.gps` typed as literal** — currently `z.string()`,
   so a typo like `"witheld_from_context"` would pass schema
   validation. Tighten to `z.literal()` and add a negative test
   asserting GPS-key absence in the JSON output.

5. **Vitest / Jest test infrastructure** — migrate the 15 smoke
   scripts to a structured framework with per-tool spec, parameterized
   fixtures, mock providers, and coverage reporting. Multi-day
   migration; queued post-launch.

6. **Bulk dataset ingest** — Agribalyse 3.1 (3,484 carbon entries),
   SU-EATABLE LIFE (3,349), TACO 4 full (~597). Curated subsets ship
   today. Ingest gated on UNICAMP redistribution license confirmation
   (TACO) and a build script for the upstream CSV/Excel files.

### Low priority

7. **Photo meal estimation accuracy bounds** — image tools tested but
   no published accuracy / error envelope.

8. **Performance benchmark suite** — no formal latency targets set.

9. **Singular `recommended_handoff`** — current shape is one object;
   declare now whether v1 will ever need plural (and whether `v2`
   will be a breaking change to `recommended_handoffs[]`) before
   external agents code against the v1 shape.

---

## 11. Appendix — environment & versions

- Audit ran against `wellness-nourish@0.2.2` (start) → `0.2.10` (end).
- npm publishes: `0.2.3` (15:23 UTC) → `0.2.10` (15:32 UTC) for the
  bug-fix wave; `0.2.10` published before the final pt-BR / standard
  wave merged.
- CI: GitHub Actions, Node 20 / 22 / 24 matrix; CodeRabbit on
  `exercise-catalog-mcp`.
- All commits authored under `davidmosiah`.
- All work happened in one ~11-hour Hermes session window with two
  context compactions; this document survives the next compaction.