Skip to content

Task Plan — Reconcile Shelfery documentation with the pantryplus implementation repository

Objective

Evaluate the local implementation repository C:\Users\Stuart\repos\pantryplus (GitHub: brokenlyre/pantryplus) against this repository's Shelfery venture documentation, fill the resulting gaps here (as drafts/observed evidence, never as approvals), and record the inconsistencies found in both repositories with refactoring recommendations.

Scope

  • Update Shelfery strategy documents (venture-brief.md, assumptions-and-open-questions.md, roadmap.md, brand-and-positioning.md) to reflect the observed, implemented reality of the pantryplus repository, labeled as observed evidence per docs/company/research-and-evidence-principles.md.
  • Update ventures/shelfery/docs/architecture/repository-boundary.md to reflect the de facto separate implementation repository.
  • Draft a new ADR (status proposed) recognizing pantryplus as Shelfery's de facto implementation repository, following up ADR-0007.
  • Register the pantryplus repository in ventures/shelfery/venture.json, portfolio/venture-registry.json, and portfolio/repository-registry.json.
  • Create a new alignment record documenting inconsistencies between the two repositories and recommended refactorings (in pantryplus and here).
  • Note in ventures/shelfery/product/README.md that specification back-fill from the implemented product is now the pending work, requiring a human decision to start.

Out of scope

  • Editing anything in the pantryplus repository (recommendations only).
  • Populating product/product-brief.md, product-requirements.md, feature-inventory.md, or acceptance-criteria.md with full back-filled specifications — that is a large follow-on task that needs explicit human authorization (see Decisions required).
  • Changing any document to status: approved.
  • Rewriting ventures/shelfery/AGENTS.md or docs/ai/guardrails.md — their "do not treat as decided" lists are now partially stale, but changing a policy's meaning needs its own reviewed task; flagged in the alignment record instead.
  • Any brand approval. Brand conclusions in pantryplus (name, palette, voice) are treated as evidence of a working direction, not approval.

Applicable authority

  • AGENTS.md (root), ventures/shelfery/AGENTS.md
  • docs/governance/authority-and-inheritance.md
  • docs/ai/context-loading-order.md (sequence c — Shelfery)
  • docs/company/research-and-evidence-principles.md (evidence labeling)
  • ventures/shelfery/docs/domain/trust-safety-and-food-claims.md
  • docs/decisions/ADR-0007-implementation-repository-boundary-remains-open.md

Files expected to change

  • work/active/2026-07-11-shelfery-pantryplus-reconciliation.md (this plan)
  • docs/decisions/ADR-0010-shelfery-implementation-repository-pantryplus.md (new)
  • ventures/shelfery/docs/strategy/venture-brief.md
  • ventures/shelfery/docs/strategy/assumptions-and-open-questions.md
  • ventures/shelfery/docs/strategy/roadmap.md
  • ventures/shelfery/docs/strategy/brand-and-positioning.md
  • ventures/shelfery/docs/architecture/repository-boundary.md
  • ventures/shelfery/docs/architecture/implementation-alignment.md (new)
  • ventures/shelfery/product/README.md
  • ventures/shelfery/venture.json
  • portfolio/venture-registry.json
  • portfolio/repository-registry.json

Assumptions

  • The pantryplus repository at C:\Users\Stuart\repos\pantryplus is the authoritative, current implementation of the product this venture documents. Basis: its own docs record the rename decision to "Shelfery" and the shelfery.app domain acquisition; product domain, palette, and tone match this venture's provisional direction exactly.
  • Facts stated in pantryplus/docs/ai/ (deployment on Vercel, shipped feature list, decisions log) are accurate records of that project. They are treated as observed evidence from that repository, not independently verified.
  • The product owner of pantryplus and the Founder/Venture Lead here are the same person, so pantryplus "product owner decided" entries are genuine decisions — but they have not passed this repository's governance (ADR/approval) process, so they land here as proposed/observed, not approved.

Risks

  • Food-safety adjacency: the implemented product tracks expiration dates and plans expiry alerts and AI meal suggestions. This task only documents that reality — it adds no shelf-life guidance — but the alignment record touches the food-claims standard, so it is flagged for human review.
  • Contradiction risk: several statements here ("no application has shipped") are now false; several pantryplus decisions bypass this repo's gates. Handled by surfacing contradictions explicitly rather than silently editing them away.

Validation plan

  • python scripts/check.py must pass.
  • python -m unittest discover tests where applicable.
  • Human review of the new ADR, the alignment record, and every status change before any of it is treated as ratified.

Progress checklist

  • [x] Read root and venture contracts, context-loading order, key Shelfery docs
  • [x] Read pantryplus docs (docs/ai/*, README, AGENTS.md)
  • [x] Write this plan
  • [x] Draft ADR-0010 (proposed)
  • [x] Update venture-brief.md
  • [x] Update assumptions-and-open-questions.md
  • [x] Update strategy/roadmap.md
  • [x] Update brand-and-positioning.md
  • [x] Update architecture/repository-boundary.md
  • [x] Write implementation-alignment.md
  • [x] Update product/README.md
  • [x] Update venture.json and both portfolio registries
  • [x] Validation run and passing
  • [x] Handoff notes written

Decisions required (human)

  1. Ratify ADR-0010 — recognize pantryplus as Shelfery's implementation repository (or reject and direct a different structure).
  2. Authorize specification back-fill — whether to populate ventures/shelfery/product/ (brief, requirements, feature inventory, acceptance criteria) from the implemented product's observed behavior.
  3. Brand ratification — the name "Shelfery" and the warm/terracotta direction are now implemented-or-decided in pantryplus; decide whether to run the formal brand approval step this repo requires.
  4. Governance sync mechanism — how future material decisions made in pantryplus (e.g. monetization model, platform changes) get recorded here.
  5. Food-claims review — whether pantryplus's shipped/planned expiration-related features meet ventures/shelfery/docs/domain/trust-safety-and-food-claims.md.

Handoff notes

Completed 2026-07-11. All planned edits made; python scripts/check.py and python -m unittest discover tests both pass. The five human decisions above are the open items; the alignment record (ventures/shelfery/docs/architecture/implementation-alignment.md) is the durable inventory of cross-repo inconsistencies and recommended pantryplus refactorings. Nothing was changed in the pantryplus repository itself.

2026-07-27 update: decision #2 above ("Authorize specification back-fill" into ventures/shelfery/product/) is resolved, not as originally framed. Per ADR-0017, the Founder decided this repository does not hold per-venture product specifications at all — ventures/shelfery/product/ (referenced at lines 45, 83, and 144 above) was retired outright rather than back-filled. Shelfery's product specification, if and when one is written, belongs entirely in the shelfery implementation repository's own docs/ai/.

Report an issue about this page