Skip to content

ADR-0015: Expiration Dates Are Data, Not Food-Safety Claims

Status

approved — ratified by the Founder on 2026-07-12.

Date

2026-07-12

Context

GitHub issue #3 (filed by the Founder) asks Shelfery to define what counts as a "food safety claim," specifically whether expiration dates fall into that category. This isn't an abstract question: planned features (expiry alerts, default expiry windows shown at put-away, AI-suggested meal ideas) are about to cross directly into this territory, and the venture needs a clear line before those features ship.

This is not greenfield. ventures/shelfery/docs/domain/trust-safety-and-food-claims.md (DD-SHELFERY-023, status: proposed) already establishes eight detailed rules governing exactly this ground and is described as "the most important domain document in the Shelfery venture" — it is cross-referenced from the venture's AGENTS.md, docs/ai/guardrails.md, product/product-requirements.md, product/acceptance-criteria.md, and docs/domain/glossary.md. It has not, however, been formally ratified, and — per ventures/shelfery/docs/architecture/implementation-alignment.md — it has not yet been referenced anywhere in the pantryplus implementation repository, even though upcoming features are about to need it.

At the company level, docs/company/customer-trust-principles.md (DD-COMPANY-007) already names "Food-safety claims (particularly relevant to Shelfery — expiration estimates, storage guidance, spoilage risk)" as a category requiring human review before content is treated as final, and states that AI-generated drafts of such content are allowed but AI-approved final versions are not.

The Founder's own recommendation in the issue is: "Dates are fine. Surfacing alerts to dates are fine. Saying that a product has gone bad or is still safe based on the date is not ok." That maps directly onto rules already drafted in the domain standard — estimates must not be represented as guarantees (rule 3), quality guidance must stay separated from safety guidance (rule 4), user-entered/derived dates must remain visually distinguishable from authoritative guidance (rule 7), and the absence of an elapsed estimate window must never imply safety (rule 8) — but those rules have never been formally decided as company/venture policy, only drafted as preliminary guidance.

Separately, ventures/shelfery/docs/strategy/assumptions-and-open-questions.md (open question Q5) notes that no authoritative source for shelf-life/freshness data has been selected. That question is real and unresolved, and this ADR does not resolve it — but it is becoming urgent precisely because of the same upcoming features (expiry alerts, default expiry windows) that prompted this issue.

Decision

Raw expiration/use-by dates, and reminders or alerts derived from them, are data and notifications — not food-safety claims by themselves. Shelfery may surface dates and date-based alerts (e.g. "this expires in 2 days") without that content being subject to food-safety-claim review, provided the date itself is what's being shown (user-entered, or a plain use-by/best-by date as printed on packaging).

Any assertion or implication, made using that date data, that an item currently is or is not safe to eat, has or has not "gone bad," or is still good/fresh in a safety sense, is a food-safety claim. That includes copy, UI treatment, notification wording, or AI-generated content that infers a safety or spoilage conclusion from an elapsed date, a stored quantity, or any combination of Shelfery's own data — regardless of whether the word "safe" is used explicitly. Any such content falls under the existing human-review requirement in docs/company/customer-trust-principles.md and must additionally satisfy rules 1, 3, 4, 5, and 8 of ventures/shelfery/docs/domain/trust-safety-and-food-claims.md.

This ADR ratifies that specific line — the distinction between showing date data and asserting a safety conclusion from it — as company/venture decision. It does not ratify the entirety of trust-safety-and-food-claims.md as approved. That standard's own text states it still needs legal review given the subject matter, and open question Q5 (no authoritative shelf-life source selected) remains genuinely unresolved. This ADR narrowly answers the question the issue actually asked; the broader standard still needs its own path to approval.

Consequences

  • Shelfery's planned expiry-alert and default-expiry-window features can proceed on the understanding that surfacing dates and reminders is not, by itself, food-safety content requiring the heavier review path — provided the copy stays on the "data" side of the line (no spoilage/safety inference).
  • Any feature or copy that crosses into asserting freshness/safety (e.g. a "still good" badge, an AI summary implying an item is safe to eat because its date hasn't passed) is now unambiguously classified as a food-safety claim, requiring human review before being treated as final, per customer-trust-principles.md.
  • Open question Q5 (no authoritative shelf-life source selected) is not resolved by this ADR, but is now flagged as directly blocking any feature that would go beyond showing raw/user-entered dates — e.g. a "typical expiry window" default at put-away would require sourced guidance under rule 1, and cannot rely on this ADR's "dates are just data" allowance, because a default window the app supplies (rather than a date the user or package provides) is itself a claim about typical shelf life.
  • trust-safety-and-food-claims.md remains status: proposed (preliminary but binding guidance, per its own text) — this ADR does not change that. A separate, future decision is still needed to fully ratify it, informed by legal review.
  • The pantryplus implementation repository still does not reference either the domain standard or this ADR — that gap needs to be closed (see Follow-up Actions) before implementation work that touches this territory should be considered aligned with venture policy.

Alternatives Considered

  • Treat any expiration-date display as a food-safety claim, full stop. Rejected: this would block the core, already-shipped feature of tracking use-by dates (a plain data field) under the heaviest review path, which the Founder's own recommendation explicitly rejects ("dates are fine"). It also doesn't match how the existing domain standard already frames the distinction.
  • Leave the question open and decide it feature-by-feature as each one ships. Rejected: the issue was filed specifically because upcoming features (expiry alerts, default windows, AI meal ideas) need this line drawn now, before they're built, not after.
  • Fully ratify trust-safety-and-food-claims.md as approved in the same motion. Rejected: that standard's own text flags a need for legal review given the subject matter, and open question Q5 is unresolved. Approving the whole document now would overstate what's actually been decided; this ADR deliberately scopes itself to the narrower question the issue raised.

Follow-up Actions

  • Once this ADR is approved, add a pointer from the pantryplus implementation repository (e.g. docs/ai/coding-standards.md or docs/ai/design-principles.md) to this ADR and to ventures/shelfery/docs/domain/trust-safety-and-food-claims.md, since implementation-alignment.md already flagged that pantryplus does not currently reference the standard at all. This is a change to the pantryplus repository, not this one — recommended, not yet made.
  • Update ventures/shelfery/docs/strategy/assumptions-and-open-questions.md (Q5) to note that authoritative shelf-life source selection is now a blocker specifically for the expiry-alert and default-expiry-window features, not just a background open question.
  • Schedule the fuller trust-safety-and-food-claims.md ratification (legal review + Q5 resolution) as separate, future work — this ADR does not substitute for it.
  • ventures/shelfery/docs/domain/trust-safety-and-food-claims.md
  • docs/company/customer-trust-principles.md
  • ventures/shelfery/docs/strategy/assumptions-and-open-questions.md
  • ventures/shelfery/docs/architecture/implementation-alignment.md
  • docs/governance/decision-rights.md

Report an issue about this page