V0 candidate roadmap

Document version	Date	Summary
v1	2026-07-24	Capture the candidate v0.3.0 to v0.7.0 sequence after v0.2.0

Status: Planning note, not a commitment

Authority: None. This document preserves direction only. A release becomes active only when it is accepted into milestones, version architecture, epics, and PBIs.

Related documents: milestones, epics, PBIs, general architecture, known limitations, and host support layer idea.

1. Purpose

This roadmap records the current candidate sequence for the next V0 releases. It exists so the post-v0.2.0 planning context is not lost while the project still keeps official release scope in the normal product documents.

The strongest current direction is to make v0.3.0 an embedded firmware foundation and developer workflow release, not a full hardware runtime release. That keeps the next step small, gives the selected LILYGO T-Display S3 a concrete role, and avoids making an unsupported board demo into a support claim.

2. Current Baseline

v0.2.0 completed the desktop reference app, SDL frontend, canonical pet presentation assets, presentation roles, layout, semantic desktop input, and composition-aware gates.

The active planning documents are rolled over. No later V0 release is active yet. New PBIs continue from PBI-064, and new epics continue from E17.

The main open areas relevant to this roadmap are:

• local persistence
• early formative events and lasting identity development
• bounded maturity
• first physical frontend
• first physical adapter
• first digital activity adapter
• host support layer evaluation
• frontend support layer evaluation
• embedded cross compilation
• embedded runtime validation

3. Candidate Release Sequence

Release	Candidate title	Primary outcome	Main reason
v0.3.0	Embedded firmware foundation and project UX	The project can build and link a reusable ESP-IDF firmware foundation for the LILYGO T-Display S3 target, and daily build commands are simple	Reduces the largest portability uncertainty before adding more product state
v0.4.0	Local persistence foundation	One world can be saved and restored through a versioned, validated local format	A pet cannot feel persistent until identity survives process lifetime
v0.5.0	T-Display S3 runtime prototype	The selected LILYGO T-Display S3 runs a minimal Pet loop with buttons and display output	Converts embedded suitability from build evidence into real runtime evidence
v0.6.0	Early identity development	The pet gains at least one lasting identity characteristic that survives save and restore	Moves from presentation demo to attachment-forming product behaviour
v0.7.0	First activity or environment adapter	One bounded adapter path reports a semantic event or capability without direct state mutation	Proves the adapter boundary with one real source before a plugin system exists

The sequence is intentionally conservative. It alternates platform risk and product value instead of piling hardware, persistence, identity, and adapters into one release.

4. Candidate v0.3.0

Candidate title: Embedded firmware foundation and project UX

Recommended scope:

• write docs/arch/arch-v0.3.0.md
• keep the accepted ./pet.py project command in the release scope
• keep direct CMake usage available for maintainers
• avoid a broad CMake rewrite until wrapper evidence identifies real duplication
• add a reusable embedded firmware app foundation rather than a disposable probe
• add ESP-IDF build proof for the LILYGO T-Display S3 target
• keep SDL, desktop file I/O, and platform windows out of embedded builds
• record the firmware app, small TFT frontend direction, T-Display board configuration, and ESP-IDF platform glue as separate ownership areas
• evaluate whether a host conformance checklist is enough before creating pet_host_support
• narrow or close the embedded limitation if evidence supports it

Expected exclusions:

• no full T-Display runtime app
• no display driver ownership inside Pet Core
• no LVGL, Arduino, ESP-IDF, or LILYGO dependency in Pet Core
• no production asset conversion pipeline
• no persistence format
• no generic host support library unless the release produces stronger duplication evidence than expected

Likely epics:

• E17 v0.3.0 architecture and release scope
• E18 simple project command entrypoint
• E19 CMake and dependency UX cleanup
• E20 ESP-IDF firmware foundation
• E21 embedded boundary verification and support claim update

Rationale:

The V0 milestone wants at least one embedded toolchain at cross-compile tested status before the V0 foundation is done. v0.2.0 preserved embedded suitability but did not prove it. The selected LILYGO T-Display S3 is a useful forcing function, but the first release should prove the build and boundary shape before it promises a working device experience.

The build UX work belongs early because v0.2.0 left the CMake and gate surface powerful but too complex for daily use. A wrapper can hide that complexity without deleting the composition model that release evidence relies on.

5. Candidate v0.4.0

Candidate title: Local persistence foundation

Recommended scope:

• define the boundary between serialisation and storage
• add a versioned save format for the currently supported world state
• validate before activation so invalid save data cannot partially mutate the active world
• add deterministic round-trip tests
• add a desktop storage implementation only as a host concern
• record the compatibility promise for the first save format

Expected exclusions:

• no cloud sync
• no pet transfer
• no multiple profiles or households
• no migration framework beyond what the first version needs
• no identity content that depends on future formative events

Rationale:

Persistence is the first big product gap after the desktop reference app. It also creates the real storage interface pressure that the host support idea explicitly names as the first likely function-pointer boundary. Doing this after v0.3.0 lets the persistence format respect embedded size and toolchain evidence instead of guessing.

6. Candidate v0.5.0

Candidate title: T-Display S3 runtime prototype

Recommended scope:

• verify the selected T-Display S3 on hardware
• choose the firmware stack for the prototype deliberately
• render a minimal Pet presentation on the board display
• map the board buttons to supported semantic actions
• use generated or packed assets if the desktop PNG runtime path is unsuitable
• record runtime-tested evidence on the named board
• keep desktop and headless compositions passing

Expected exclusions:

• no final hardware decision
• no production power optimisation
• no touch support unless the exact board makes it cheap and bounded
• no sensor adapter unless it is the whole release outcome
• no Wi-Fi, BLE, account, transfer, or sync feature

Rationale:

This is where the board becomes more than build evidence. Delaying runtime until after cross-compilation keeps the board work focused on display, input, assets, and host lifecycle instead of fighting the basic build boundary at the same time.

7. Candidate v0.6.0

Candidate title: Early identity development

Recommended scope:

• introduce one small lasting identity characteristic
• make its cause meaningful and non-punitive
• expose it through PetSnapshot only if it is deliberately presentable
• persist it through the save format
• update presentation roles or assets only for the visible slice of the feature

Expected exclusions:

• no broad trait engine
• no maturity tree
• no large cosmetic system
• no user-facing editor for every lasting detail
• no activity farming loop

Rationale:

The specification says the pet should develop identity through shared history, but this is only worth doing once the state survives process lifetime. A single well-bounded characteristic is enough to prove the model without turning the Core into a content system too early.

8. Candidate v0.7.0

Candidate title: First activity or environment adapter

Recommended scope:

• choose one adapter source: either a physical board signal or a small digital activity source
• translate source-specific data into a semantic event or capability
• validate, bound, and rate-limit the input
• keep the adapter from mutating authoritative state directly
• record whether physical and digital adapters need separate interfaces

Expected exclusions:

• no plugin marketplace
• no network service
• no continuous activity surveillance
• no broad permission system
• no support for every sensor or activity category

Rationale:

Adapters are central to the long-term product, but an adapter interface should be designed against a real source. By this point the project should have enough host, persistence, and possibly board evidence to choose one source without inventing a generic plugin platform.

9. Rejected v0.3.0 Shapes For Now

Full T-Display runtime as v0.3.0. Too much risk for one release. Display driver choice, firmware stack, asset conversion, board input, upload tooling, runtime evidence, and embedded build support would all arrive together.

Persistence as v0.3.0. Product value is high, but it leaves the embedded support gap open and forces storage decisions before the first embedded toolchain evidence.

Identity development as v0.3.0. It would make the pet feel more alive, but lasting identity without persistence is not really lasting.

Generic host support library as v0.3.0. The current evidence points to a checklist and pure helper functions first. A library should be earned by duplication from real platform hosts.

10. Open Questions

• exact display runtime configuration and controller initialisation
• whether dependency override policy should be solved in v0.3.0 or split into a smaller PBI
• whether the embedded proof includes only Core or also components/manifest, components/assets, components/presentation, and components/layout
• whether an embedded asset converter is needed before runtime or only before the first board demo
• which first adapter source creates the clearest product evidence after board and persistence work

11. Promotion Checklist

Before this roadmap becomes active planning:

• decide whether v0.3.0 is accepted as embedded readiness and project UX
• add v0.3.0 to milestones
• create docs/arch/arch-v0.3.0.md
• add the E17 onwards epic map
• add PBI-064 onwards under the active backlog
• link carried limitations to the PBIs that evaluate or close them
• delete or update any roadmap text that became authoritative elsewhere