Pet milestones

Document version	Date	Summary
v1	2026-07-17	Initial milestone and release plan
v2	2026-07-20	Plan v0.2.0 as the desktop reference app release
v3	2026-07-20	Link the v0.2.0 architecture document
v4	2026-07-24	Record v0.2.0 completion, tick its exit criteria, and link its release archive
v5	2026-07-25	Plan v0.3.0 as the embedded firmware foundation and project UX release
v6	2026-07-27	Record the accepted v0.3.0 architecture
v7	2026-07-27	Record completed workflow criteria and the E20 embedded build evidence
v8	2026-07-27	Clarify the T-Display family and selected S3 variant boundary
v9	2026-08-01	Record v0.3.0 completion, tick its exit criteria, and link its release archive
v10	2026-08-02	Plan v0.4.0 as the local persistence foundation release
v11	2026-08-04	Complete v0.4.0 and link its release archive
v12	2026-08-04	Plan v0.5.0 as the board runtime and embedded asset pipeline release

Status: Draft

Related documents: Product specification, general architecture, version architecture documents, the release planning process, and the release process

1. Purpose

This document defines product milestones and the releases that contribute to them.

A milestone represents a product outcome. A release is a versioned delivery within a milestone. Releases follow Semantic Versioning 2.0.0.

Major version zero represents initial product development. New functionality increments the minor version. Compatible bug fixes increment the patch version.

flowchart TD
    M[V0 milestone]
    R1[v0.1.0 Headless Core]
    R2[v0.2.0 Desktop Reference App]
    R3[v0.3.0 Embedded Firmware Foundation]
    R4[v0.4.0 Local Persistence Foundation]
    R5[v0.5.0 Board Runtime and Embedded Asset Pipeline]
    RF[Later V0 releases]
    V1[V1 milestone]

    M --> R1
    M --> R2
    M --> R3
    M --> R4
    M --> R5
    M --> RF
    RF --> V1

2. Status model

Milestones and releases use the following statuses:

• Proposed: the outcome is being considered
• Planned: the outcome is accepted but implementation has not started
• In progress: at least one included PBI is active
• Blocked: progress requires a missing decision or dependency
• Completed: all exit criteria are satisfied
• Dropped: the outcome is no longer planned

3. V0 milestone

Title: Software companion foundation

Status: In progress

Purpose: Validate the product idea and establish a portable software foundation before committing to final hardware or a production product shape.

V0 covers all 0.x.y releases. It begins with a headless Pet Core and grows through small, independently verifiable product releases. V0 is complete only when the project has enough product and architecture evidence to define v1.0.0 responsibly.

3.1 Intended outcome

By the end of V0, the project should provide a small but meaningful pet experience that:

• feels present without demanding maintenance
• runs through a portable ISO C99 Pet Core
• has at least one useful visual frontend
• accepts semantic input independent of physical controls
• preserves authoritative state locally
• demonstrates deterministic time based behaviour
• demonstrates early identity development
• keeps platform effects outside the Core
• can be evaluated for a future embedded frontend

V0 does not need to provide the complete commercial product.

3.2 V0 constraints

• no final hardware purchase or custom hardware design is required
• no cloud account or network service is required
• no pet transfer or synchronisation is required
• no multiple pet world is required
• no generative AI feature is required
• no production plugin ecosystem is required
• every release must remain small enough to verify independently
• product rules must remain inside the Pet Core

3.3 Known V0 releases

Release	Title	Status	Primary outcome
v0.1.0	Headless Pet Core	Completed	A portable and deterministic Core can run and be tested without a visual frontend
v0.2.0	Desktop reference app	Completed	A desktop app presents and interacts with the Core through a pinned SDL frontend, canonical assets, and verified app and frontend boundaries
v0.3.0	Embedded firmware foundation and project UX	Completed	An ESP-IDF firmware foundation proves the Core and selected frontend-neutral components can enter an ESP32 T-Display firmware build, while daily project workflows become simpler
v0.4.0	Local persistence foundation	Completed	One world can be saved and restored through a versioned binary format the Core owns and a storage boundary the host owns
v0.5.0	Board runtime and embedded asset pipeline	In progress	A classic LILYGO T-Display runs Pet continuously, presents it from a build-generated embedded asset pack, and answers its board buttons as semantic actions

Later V0 releases will be added once v0.5.0 has turned embedded suitability from build evidence into runtime evidence on a named board.

3.4 Provisional V0 exit criteria

These criteria define the current direction. They may be refined before the final V0 release is planned.

• a user can observe and interact with one persistent pet
• the experience includes non punitive autonomous behaviour
• the pet can gain at least one lasting identity characteristic
• local save and restore preserve the supported world state
• at least one visual frontend uses Core presentation state
• frontend input is translated into semantic actions
• time and randomness are explicit and reproducible in tests
• Core code has no required frontend, operating system, network, or hardware SDK dependency
• at least one embedded toolchain has reached cross compile tested status
• supported platform claims are recorded in version architecture documents
• known limitations and deferred defects are recorded and linked to PBIs
• the scope and compatibility promise for v1.0.0 can be stated clearly

4. Release v0.1.0

Title: Headless Pet Core

Milestone: V0

Status: Completed

Architecture: Architecture for v0.1.0

Release archive: release v0.1.0

4.1 Release goal

Prove that the smallest meaningful Pet Core can exist as portable ISO C99 code without a visual frontend, platform API, sensor, adapter, or network dependency.

The release is a technical and domain foundation. It is not a public product demo.

4.2 Included capabilities

• one world containing one pet
• explicit world lifecycle
• explicit elapsed time input
• a minimal autonomous state transition
• at least one semantic user action
• deterministic Core behaviour
• a minimal read only presentation snapshot
• a headless diagnostic program or test scenario
• unit tests for the supported state transitions
• GCC and Clang build verification on the development host
• strict C99 compilation
• fixed-capacity caller-owned or inline Core state
• no dynamic memory allocation inside Pet Core
• a Windows MSVC configuration designed for later verification

4.3 Excluded capabilities

• visual frontend
• SDL or another rendering library
• product ready user interface
• durable save files
• physical sensors
• digital activity adapters
• plugin loading
• audio
• networking
• pet transfer
• multiple pets
• final maturity and formative event systems
• embedded runtime support claims

4.4 Release exit criteria

• the Pet Core builds as ISO C99 with documented GCC and Clang commands
• the Core can be used without a graphical or operating system specific API
• one pet world can be initialised, updated, inspected, and destroyed safely
• elapsed time is supplied explicitly
• at least one semantic action produces an observable domain result
• at least one autonomous transition produces an observable domain result
• a presentation snapshot can be produced without exposing mutable world state
• the same controlled input sequence produces the same observable result
• invalid public input is rejected without partial state corruption
• unit tests and configured runtime diagnostics pass
• Core initialisation and runtime operations perform no dynamic memory allocation
• Core capacities and temporary work are bounded and documented
• Windows compatibility remains designed but unverified until tested on Windows
• no feature excluded by this release is required by the Core
• the version architecture document reflects the implemented system

5. Release v0.2.0

Title: Desktop reference app

Milestone: V0

Status: Completed

Architecture: Architecture for v0.2.0

Release archive: release v0.2.0

5.1 Release goal

Present the Pet Core through the first real desktop application and validate the complete path from platform time and input to Core state, presentation snapshot, asset-backed animation, and visible feedback.

This release is both an early product demonstration and a reference architecture for later frontends. It should establish app and frontend composition, canonical visual asset handling, snapshot driven rendering, semantic input mapping, and composition aware verification without allowing SDL, assets, or platform policy to define Core behaviour. The first frontend should also establish the maintenance rule for later Core growth: new presentable Core states must either map through data driven presentation roles or fall back calmly instead of requiring renderer rewrites.

5.2 Expected capabilities

• one desktop host application
• one SDL based visual frontend
• pinned SDL dependencies
• a declared app and frontend composition model
• a declarative composition registry used by development workflows
• canonical visual assets with a manifest based contract
• PNG asset loading if accepted by the version architecture
• a simple animation model with explicit elapsed time input
• presentation role mapping between Core snapshots and frontend animations
• rendering based only on read only presentation state
• logical canvas layout with integer scaling where practical
• platform input mapped to semantic actions
• visible autonomous pet behaviour
• one or more short direct interactions
• desktop process lifecycle, monotonic elapsed time handling, and clean shutdown
• enough visual identity to communicate the companion idea
• a guaranteed fallback presentation when external assets are unavailable
• component owned tests for frontend and app behaviour
• composition aware quality gates
• continued headless Core testing
• truthful Linux, Windows, and embedded support claims

5.3 Expected exclusions

• physical hardware frontend
• embedded runtime implementation
• production quality art direction
• audio implementation
• broad activity integration
• persistence and save compatibility
• complete progression and maturity systems
• multiple pets
• networking and synchronisation
• pet transfer
• production packaging and installers
• asset editors, hot reload, sprite atlas generation, and a complete asset conversion pipeline
• generic host support library
• generic frontend support library
• runtime frontend plugin system
• plugin marketplace or commercial unlock system

5.4 Release exit criteria

• a user can launch pet_desktop locally on the verified Linux desktop environment
• the desktop app creates, updates, snapshots, and resets a Core world through the public API
• the SDL frontend displays a snapshot produced by the Pet Core
• the renderer never receives a mutable PetWorld pointer
• at least one platform input becomes a semantic action
• host control events, such as quit, are not treated as product actions
• the pet produces a visible response to direct interaction
• the pet performs at least one visible autonomous behaviour
• canonical visual assets are loaded through a manifest or a guaranteed fallback is used
• unknown or unmapped presentable Core states fall back without crashing or blocking the app
• renderer code is insulated from direct Core enum handling by a presentation mapping boundary
• animation selection is deterministic from explicit frontend elapsed time
• the selected logical canvas and scaling policy are documented and tested where practical
• no product rule is implemented only inside the frontend
• the Core continues to build and run without the visual frontend
• the headless diagnostic host continues to pass its scenario
• frontend and app tests cover the supported desktop composition
• quality gates can select at least the headless and desktop app compositions
• SDL and any image loading dependency are pinned and recorded
• Linux desktop support evidence is recorded
• Windows and embedded support are not overstated beyond available evidence
• the release has its own version architecture document

The pet performs a visible autonomous behaviour through the idle activity and neutral expression that a live world and its snapshot produce without input, and a greet produces the visible response, both observed on the Wayland and X11 drivers. The complete evidence is recorded in release v0.2.0 evidence.

6. Release v0.3.0

Title: Embedded firmware foundation and project UX

Milestone: V0

Status: Completed

Architecture: Accepted in Architecture for v0.3.0

Release archive: release v0.3.0

6.1 Release goal

Prove that Pet’s portable Core and selected frontend-neutral components can be built and linked inside an ESP-IDF firmware foundation for a classic LILYGO T-Display board, without turning embedded SDK, board, display, filesystem, or asset runtime details into Core dependencies.

This release also simplifies the daily project workflow after the composition-aware v0.2.0 build surface. Common build, test, run, verify, and clean tasks should be available through one small project-owned entrypoint while direct CMake and gate usage remain available for maintainers.

v0.3.0 is an embedded readiness release. It is not the first complete hardware product runtime. The firmware foundation should be useful later rather than a disposable probe application.

6.2 Expected capabilities

• an accepted v0.3.0 version architecture document
• a persistent embedded firmware app foundation that can grow into the later hardware runtime
• ESP-IDF build and link evidence for the firmware foundation
• a selectable LILYGO T-Display family contract with classic variant facts, including display geometry, relevant pins, buttons, and backlight policy where known
• a clear split between firmware app, ST7789 display frontend direction, T-Display family selection, classic variant facts, and ESP-IDF platform glue
• Pet Core built without ESP-IDF, board, display, SDL, filesystem, or network dependencies
• selected frontend-neutral components evaluated under the embedded build boundary
• a documented direction that embedded runtime assets are generated artefacts from canonical PNG and manifest sources, not runtime text manifest or PNG decoder requirements
• a simple project command entrypoint for common development workflows
• dependency and local override policy for fetched third-party dependencies
• continued headless and desktop SDL verification
• cleanup, closure, or narrowing of selected carried limitations: embedded support, dependency overrides, allocation-probe coverage, and the presentation role priority issue
• truthful platform support claims that distinguish cross-compile or build evidence from runtime evidence on hardware

6.3 Expected exclusions

• complete T-Display runtime presentation
• required ST7789 rendering implementation
• board button input dispatched to Core actions
• runtime PNG decoding on embedded firmware
• runtime text manifest parsing on embedded firmware
• a complete asset conversion pipeline
• local persistence and save compatibility
• early identity, trait, memory, maturity, or formative event systems
• physical sensor adapters
• digital activity adapters
• Wi-Fi, Bluetooth, networking, synchronisation, peer discovery, and pet transfer
• production power management
• final hardware selection or custom hardware design
• generic host support library
• generic frontend support library
• Windows build verification unless a real Windows environment or runner is available during the release

6.4 Release exit criteria

• the release has its own accepted version architecture document
• common daily workflows can be run through the project command entrypoint and are documented
• direct CMake and gate workflows remain available for maintainer use
• the ESP-IDF firmware foundation configures, builds, and links on the selected development host
• the firmware foundation is not a disposable probe and has a documented path to later display and input runtime work
• Pet Core builds for the selected embedded target without including or linking ESP-IDF, board, display, SDL, filesystem, or network dependencies
• selected frontend-neutral components are either embedded-build verified or explicitly excluded with a recorded reason
• the embedded asset direction records generated runtime artefacts as derived from canonical PNG and manifest sources
• no embedded runtime claim is made for display output, buttons, persistence, sensors, or networking
• the headless and desktop SDL compositions continue to pass the required release gate
• dependency override policy is documented and verified where practical
• LIM-012, LIM-005, LIM-003, and LIM-010 are closed, narrowed, or linked to explicit follow-up PBIs with recorded evidence
• support claims are recorded at the level actually evidenced by the release

7. Release v0.4.0

Title: Local persistence foundation

Milestone: V0

Status: Completed

Architecture: Accepted in Architecture for v0.4.0

Release archive: release v0.4.0

7.1 Release goal

Prove that one world can leave the process and return unchanged, through a versioned binary payload that Pet Core owns and a storage boundary that the host owns.

The release establishes the save format, its validation rules, and its compatibility promise while the authoritative state is still small. Later identity, maturity, and hardware work should extend a decided format rather than invent one under pressure.

v0.4.0 is a persistence foundation release. It is not a session continuity feature. Deciding when a running product saves and restores by itself belongs to the frontend that becomes the real product surface, and the desktop app is a reference application rather than that surface.

7.2 Expected capabilities

• an accepted v0.4.0 version architecture document
• a Core save operation that writes a complete payload into caller-owned storage
• a Core load operation that validates a payload fully before it activates any of it
• an explicit little-endian binary format carrying a magic value, a format version, and an integrity check, encoded field by field rather than by copying structure storage
• a documented compatibility promise for format version 1
• a host-supplied wall-clock stamp in the payload, with an explicit value for a host that has none
• a bounded absence added to simulation time on load, replaying no missed update
• a frontend-neutral storage contract with a desktop implementation over the standard C file operations, following the existing asset reader pattern
• explicit save and load options on the desktop and headless applications
• deterministic round-trip tests over the complete supported world state
• rejection tests over truncated, corrupted, mistyped, misversioned, and oversized payloads
• allocation probe coverage over the new public operations
• continued headless and desktop SDL verification
• truthful support claims that record desktop file evidence and claim no embedded storage

7.3 Expected exclusions

• automatic load at startup, automatic save at exit, and periodic autosave
• any absence behaviour beyond advancing simulation time, including a reunion acknowledgement
• a migration framework or support for reading a second format version
• an embedded storage implementation, a flash layout, or non-volatile storage usage
• save file discovery relative to an executable, a bundle, or an install prefix
• multiple save slots, profiles, worlds, or pets
• pet export, device transfer, networking, and synchronisation
• identity, trait, memory, maturity, and formative event content in the saved state
• encryption, signing, and tamper resistance beyond an integrity check
• Windows build or runtime verification

7.4 Release exit criteria

• the release has its own accepted version architecture document
• a saved world restores into a world that is byte for byte identical to the original
• the round trip is deterministic and covered by tests over the complete supported state
• the payload carries a magic value, a format version, and an integrity check
• a payload with an unknown format version is rejected rather than interpreted
• truncated, corrupted, mistyped, and oversized payloads are rejected
• a rejected load leaves the destination world byte for byte untouched
• save and load perform no dynamic allocation and are covered by the allocation probe
• Core save and load name no file, path, handle, or platform interface
• the storage contract compiles in the embedded build with no implementation selected
• the desktop and headless applications can save and load through explicit options
• the save location is supplied by the operator and no discovery policy is claimed
• the compatibility promise for format version 1 is recorded in the version architecture
• no automatic session continuity is implemented or claimed
• the payload carries a host-supplied save stamp and a host without a clock stays supported
• a load adds a bounded absence to simulation time without replaying a missed update
• a backwards, wrong, or extreme clock produces a clamped absence rather than a failure
• the headless and desktop SDL compositions pass the required release gate
• limitations for embedded storage, absent time handling, and save location are recorded
• support claims are recorded at the level actually evidenced by the release

Every criterion above is satisfied by a check that was run. The complete evidence is recorded in release v0.4.0 evidence.

8. Release v0.5.0

Title: Board runtime and embedded asset pipeline

Milestone: V0

Status: In progress

Architecture: Accepted in Architecture for v0.5.0

Release archive: created at release time under docs/releases/v0.5.0/

8.1 Release goal

Prove that the classic LILYGO T-Display runs Pet as a continuous time-driven firmware application, presents derived pet state from a build-generated embedded asset pack, and translates physical board input into semantic product actions.

Embedded suitability is build evidence today. LIM-012 records that the selected board has never been flashed or run, and LIM-013 records that no embedded asset path exists at all. This release converts the largest open unknown of the project into recorded runtime evidence on a named board.

The panel comes before the pipeline. The generated pack decides its pixel encoding against a measured panel rather than against vendor documentation, because an artefact designed for a display nobody has lit is a guess with a file format.

v0.5.0 is a runtime and pipeline release. It is not a hardware product, and it keeps no pet across a power cycle.

8.2 Expected capabilities

• an accepted v0.5.0 version architecture document
• a project command path for flashing the firmware and reading its serial output
• a measured board and panel profile for the classic variant, covering the visible area, the panel offsets, the native orientation, the transfer orientation, and the panel colour order
• a firmware application whose normal run does not return, driven by a monotonic platform clock and a bounded elapsed delta, with no busy spin
• a TFT frontend whose rendering decisions and button filtering compile and run their tests on the development host without ESP-IDF
• ESP-IDF display and GPIO backends that live inside the TFT frontend and are selected only by the embedded build
• a registered firmware-tft composition that builds and tests the firmware orchestration boundary and the common TFT sources on the host, with the ESP-IDF backends deselected
• a deterministic build-time converter from the canonical PNG and manifest sources to one embedded asset pack, generated into the build directory rather than committed
• a pack format decision recorded as an ADR, carrying a magic value, a format version, and an entry table, and carrying no board offset and no rotation
• a zero-copy embedded pack reader in components/assets, selected out of the desktop build
• the pack linked into the firmware image as embedded read-only bytes rather than into a partition
• both board buttons sampled and debounced through a pure rule, with at least one mapped to an existing semantic action
• a contractual key-value serial diagnostic line format with a documented event vocabulary
• device evidence recorded as maintainer observation, covering the panel, the buttons, and a two-hour continuous run
• continued headless and desktop SDL verification
• truthful support claims that separate hosted build evidence, embedded cross-build evidence, and physical device observation

8.3 Expected exclusions

• non-volatile storage on the device, including NVS, a flash layout, save timing, and wear policy
• Wi-Fi, Bluetooth, over-the-air updates, networking, and synchronisation
• production power management and battery behaviour
• touch input
• physical sensor adapters and digital activity adapters
• any T-Display variant other than the classic one, and any other embedded target
• a new Core action invented only to occupy the second board button
• a separate asset partition and the flashing lifecycle that comes with it
• moving the desktop frontend onto the pack format, because desktop keeps the canonical PNG path
• collapsing the canonical manifest grammar onto one reader, which ADR-015 accepts and a later release implements, so this release carries two readers and records the limitation
• automatic session continuity on any host
• identity, trait, memory, maturity, and formative event content
• an automated hardware-in-the-loop verification gate
• Windows build or runtime verification

8.4 Release exit criteria

• the release has its own accepted version architecture document
• the pack format decision is recorded as an ADR before the converter is implemented
• the firmware can be flashed and monitored through a documented project command
• the classic board and panel profile records measured values rather than vendor values alone
• the firmware application runs continuously on the board and its normal run does not return
• the elapsed time reaching the Core comes from a monotonic platform clock and is bounded
• a two-hour continuous device run shows no unexpected reset, no watchdog abort, no stalled presentation, no lost input, and no continuously falling minimum free heap
• the common TFT rendering and button-filtering sources are exercised by host tests in the registered firmware-tft composition
• no ESP-IDF display or GPIO dependency enters the hosted composition
• the converter produces the pack deterministically from the canonical sources, and equal inputs produce equal bytes
• the pack carries a magic value, a format version, and an entry table, and carries no board offset and no rotation
• a truncated, corrupted, or unknown-version pack is rejected by the reader rather than interpreted
• the pack reaches the device as embedded read-only bytes and is read without copying it
• a canonical frame is generated from the canonical sources, embedded in the firmware image, read through the embedded asset path, and visibly presented on the classic T-Display
• a rejected or unavailable pack produces the documented fallback presentation without ending the application, and a run that reaches only the fallback does not satisfy the criterion above
• both board buttons are sampled and debounced, and at least one produces an existing semantic action that the serial diagnostics report
• a maintainer observes on the physical board that a button press produces a visible pet response
• the serial diagnostics follow the documented line format and event vocabulary, and a free-form status line is not accepted as evidence
• LIM-012 is closed for the classic variant on esp32 only, and no claim is made for another variant, board, or target
• LIM-013 is closed by the canonical frame criterion above
• LIM-015 remains open and its tracking column no longer names this release
• a limitation is recorded for the absent hardware-in-the-loop gate, separating hosted pixel surface assertions from physical panel and button observation
• the headless and desktop SDL compositions pass the required release gate
• no device claim is recorded as automated evidence, and the hosted firmware-tft composition is recorded as build and test evidence rather than as a device runtime claim

9. Future V0 release planning

Releases after v0.5.0 are intentionally not committed yet. Candidate outcomes include:

• early formative events and lasting identity development
• bounded maturity
• non-volatile storage on the device
• the first physical adapter
• the first digital activity adapter
• frontend support layer evaluation after the second frontend has produced evidence

Candidate outcomes are not commitments. They become releases only after review of product value, architecture cost, and dependencies.

10. V1 milestone direction

Status: Proposed

V1 represents the first product version with a deliberate compatibility promise. Its exact scope is not yet defined.

Pet transfer, peer discovery, local network interaction, multiple pets, and synchronisation are not assumed to be part of V1. They remain possible work after V1 unless later product evidence justifies a different plan.

Planning for V1 starts only when the V0 exit criteria are stable and enough V0 releases have been evaluated.

11. Traceability rules

Every release must link to:

• its parent milestone
• its version architecture document
• included epics
• included PBIs
• relevant specification requirements
• known limitations accepted for the release

Every completed release must record:

• verified compiler and platform support
• test and diagnostic evidence
• unresolved bugs
• accepted limitations
• architecture deviations
• compatibility notes

12. References

• Semantic Versioning 2.0.0
• Product specification
• General architecture
• arc42 architecture documentation