my little airport =)

13 min read

Pet epics

Document versionDateSummary
v72026-07-24Archive the completed v0.2.0 epics and open the next release map
v82026-07-25Define the v0.3.0 embedded firmware foundation and project UX epics
v92026-07-25Add v0.3.0 release verification and hardening as the final epic
v102026-07-27Complete E17 after accepting the v0.3.0 architecture and release scope
v112026-07-27Record completion of E18, E19, and E20
v122026-07-27Clarify the T-Display family and selected S3 variant contract
v132026-07-28Record completion of E21
v142026-07-28Record completion of E22

Status: Draft

Current release: v0.3.0

Related documents: Product specification, milestones, general architecture, architecture for v0.3.0, and the release archives for v0.1.0 and v0.2.0.

1. Purpose

This document defines the product and engineering outcomes required by each epic.

An epic belongs to one release and contains multiple PBIs. An epic describes a verifiable outcome rather than a source directory, implementation phase, or team activity.

Epic identifiers are permanent and are not reused. Future releases continue the sequence instead of restarting at E01.

2. Epic completion rules

An epic is completed only when:

  • all child PBIs are completed
  • all epic completion criteria are satisfied
  • required tests pass
  • accepted architecture decisions are reflected in code and documentation
  • new limitations are recorded in known-limitations.md
  • deferred defects are recorded in bugs.md
  • architecture deviations are documented
  • verified support claims are not broader than the available evidence

An epic must not be marked completed because its main implementation exists while tests or required documentation remain unfinished.

3. Archived releases

Completed v0.1.0 epics are archived in release v0.1.0. That archive holds E01 through E07 with their full outcomes, scope, and completion criteria.

Completed v0.2.0 epics are archived in release v0.2.0. That archive holds E08 through E16 with their full outcomes, scope, and completion criteria.

Epic identifiers continue from E17. They are permanent and are not reused, so a future release never restarts the sequence.

4. Release v0.3.0 epic map

EpicTitleStatusPrimary outcome
E17v0.3.0 architecture and release scopeCompletedThe embedded firmware foundation, project UX, board, TFT, asset, dependency, and support-claim boundaries for v0.3.0 are documented and accepted
E18Simple project command entrypointCompletedCommon build, test, run, verify, and clean workflows can be driven through one small project-owned command without replacing CMake or the gate
E19Dependency and local override policyCompletedFetched dependencies have a documented local override policy, closing or narrowing LIM-005 without weakening pinned default builds
E20ESP-IDF firmware foundationCompletedA reusable apps/firmware foundation builds and links through ESP-IDF for the selected ESP32-S3 T-Display S3 target, narrowing LIM-012 to hardware runtime evidence
E21Embedded-safe component and verification boundariesCompletedSelected frontend-neutral components and Core verification checks are made suitable for embedded build evidence, including explicit coverage of LIM-003
E22TFT presentation behaviour cleanupCompletedThe presentation priority issue that hides the attentive activity is fixed or deliberately replaced by a documented product rule, closing or narrowing LIM-010
E23Release verification and hardeningPlannedThe release meets its workflow, embedded build, boundary, limitation, and support-claim evidence requirements

The release goal and expected capabilities are recorded in milestones. The concrete architecture is recorded in architecture for v0.3.0. PBIs for this release start at PBI-064.

4.1 Dependency view

flowchart TD
    E17[E17 Architecture and scope]
    E18[E18 Project command entrypoint]
    E19[E19 Dependency overrides]
    E20[E20 ESP-IDF firmware foundation]
    E21[E21 Embedded component boundaries]
    E22[E22 TFT presentation cleanup]
    E23[E23 Release verification]

    E17 --> E18
    E17 --> E19
    E17 --> E20
    E17 --> E21
    E17 --> E22
    E17 --> E23
    E19 --> E20
    E20 --> E21
    E18 --> E23
    E19 --> E23
    E20 --> E23
    E21 --> E23
    E22 --> E23

E18 can proceed after E17 because it wraps existing workflows before embedded implementation is complete. E19 should land before E20 where dependency configuration affects ESP-IDF, SDL, or cmocka builds. E21 depends on the firmware foundation because embedded suitability needs a real build target. E22 can proceed after E17 because it is a product and presentation behaviour correction, not a release hardening bucket. E23 is the release-level convergence point.

Testing is not deferred to E23. Every implementation epic includes its own tests and evidence. E23 adds release-level integration, final gates, support-claim review, limitation status review, and documentation hardening.

5. E17: v0.3.0 architecture and release scope [+]

Release: v0.3.0

Status: Completed

Dependencies: None

5.1 Outcome

The release architecture defines the embedded firmware foundation, ESP-IDF platform boundary, T-Display family and variant configuration, TFT frontend direction, generated embedded asset direction, project command surface, dependency policy, and support-claim limits for v0.3.0.

The result is an accepted implementation plan that can guide PBIs without allowing ESP-IDF, board pins, display controllers, generated assets, or workflow convenience to define Core behaviour.

5.2 In scope

  • arch-v0.3.0.md
  • firmware app foundation boundary
  • ESP-IDF platform glue boundary
  • T-Display family selection and variant configuration boundary
  • TFT frontend direction with ST7789 as the first controller family
  • generated embedded asset direction
  • project command entrypoint scope
  • dependency override policy scope
  • embedded support claim levels
  • explicit release handling for LIM-012, LIM-005, LIM-003, and LIM-010

5.3 Out of scope

  • implementing the firmware foundation
  • implementing a complete TFT renderer
  • implementing board button input
  • implementing generated asset conversion
  • implementing persistence, identity, adapters, networking, or power management
  • creating generic host or frontend support libraries

5.4 Completion criteria

  • arch-v0.3.0.md exists and follows the version architecture policy
  • the firmware app, platform glue, board configuration, and TFT frontend direction are separated
  • the generated embedded asset direction is recorded without creating a premature format promise
  • the support matrix distinguishes build, cross-compile, and runtime evidence
  • carried limitations in release scope are linked to the epic that owns their resolution
  • open decisions are named for PBI or later-release resolution

5.5 Traceability

  • SPEC-PR-007: one Core and multiple frontends
  • SPEC-FR-026: varied frontend capabilities
  • SPEC-FR-029: frontend independence
  • SPEC-NFR-001: portability
  • SPEC-NFR-006: maintainability
  • SPEC-NFR-007: compatibility awareness
  • LIM-012, LIM-005, LIM-003, LIM-010
  • arch-v0.3.0: sections 1, 2, 4, 5, 8, 9, 10, and 11

6. E18: Simple project command entrypoint [+]

Release: v0.3.0

Status: Completed

Dependencies: E17

6.1 Outcome

Common project workflows can be run through one small command entrypoint while CMake, CTest, gate.py, and direct run commands remain the underlying source of truth.

The result makes everyday development easier without duplicating composition rules or hiding the actual verification commands.

6.2 In scope

  • project-owned command entrypoint
  • build, test, run desktop, verify, and clean workflows
  • dry-run or command planning output where useful for tests
  • clear errors for missing tools or unsupported command combinations
  • documentation of the daily workflow
  • tests for command parsing and command planning

6.3 Out of scope

  • replacing gate.py
  • replacing CMake presets
  • creating a second composition registry
  • CI provider integration
  • package manager or installer commands
  • embedded flash or monitor commands unless a PBI explicitly includes them

6.4 Completion criteria

  • common commands are implemented and documented
  • the entrypoint delegates to existing project workflows
  • unsupported command combinations fail clearly
  • tests cover parsing and command planning
  • direct CMake and gate commands remain documented for maintainer use

6.5 Traceability

7. E19: Dependency and local override policy [+]

Release: v0.3.0

Status: Completed

Dependencies: E17

7.1 Outcome

Fetched dependencies keep pinned default behaviour while developers can use project-owned local override configuration without editing source files.

The result closes or narrows LIM-005 for the dependencies the release supports.

7.2 In scope

  • local override policy for fetched dependencies
  • cmocka override handling where practical
  • SDL override handling where practical
  • ESP-IDF integration guidance that avoids creating a new ad hoc dependency path
  • documentation for pinned defaults and local overrides
  • verification that override configuration does not affect Core dependency boundaries

7.3 Out of scope

  • vendoring third-party dependency source into the repository
  • supporting every package manager
  • making offline first configure guaranteed for every developer environment
  • replacing ESP-IDF installation or setup
  • changing third-party diagnostic ownership rules

7.4 Completion criteria

  • supported override variables or configuration paths are documented
  • pinned default dependency behaviour remains reproducible
  • supported local override paths work where practical
  • third-party diagnostics remain outside project diagnostics
  • LIM-005 is closed or narrowed with recorded evidence

7.5 Traceability

  • SPEC-NFR-006: maintainability
  • SPEC-NFR-007: compatibility awareness
  • LIM-005
  • arch-v0.3.0: sections 8.5, 10.2, and 11

8. E20: ESP-IDF firmware foundation [+]

Release: v0.3.0

Status: Completed

Dependencies: E17, E19

8.1 Outcome

A reusable embedded firmware app foundation builds and links through ESP-IDF for the selected LILYGO T-Display S3 target.

The result proves embedded build suitability without claiming display output, button input, persistence, sensors, networking, or hardware runtime behaviour.

8.2 In scope

  • apps/firmware source ownership
  • platforms/esp_idf build integration
  • boards/t_display family configuration and selected s3 variant record
  • selected ESP-IDF target and toolchain evidence
  • firmware lifecycle skeleton using public Core APIs
  • build and link evidence through ESP-IDF
  • support matrix update for embedded build evidence
  • closure or narrowing of LIM-012

8.3 Out of scope

  • complete hardware runtime
  • TFT rendering
  • board button input dispatch
  • Wi-Fi, Bluetooth, networking, sensors, persistence, or power management
  • classic ESP32 T-Display support
  • Arduino or PlatformIO support
  • Core dependency on ESP-IDF

8.4 Completion criteria

  • the firmware foundation is structured as reusable app code rather than a disposable probe
  • ESP-IDF configures, builds, and links the firmware foundation
  • the firmware foundation uses public Core APIs only
  • T-Display family selection and S3 facts are recorded outside the Core and generic TFT frontend direction
  • no runtime hardware capability is claimed without execution evidence
  • LIM-012 is narrowed with recorded evidence

8.5 Traceability

  • SPEC-NFR-001: portability
  • SPEC-NFR-002: resource awareness
  • SPEC-NFR-007: compatibility awareness
  • LIM-012
  • arch-v0.3.0: sections 5.3, 5.4, 5.5, 6.1, 6.2, 7.2, and 8.8

9. E21: Embedded-safe component and verification boundaries [+]

Release: v0.3.0

Status: Completed

Dependencies: E17, E20

9.1 Outcome

Selected frontend-neutral components are either build verified under the embedded boundary or explicitly excluded with a recorded reason, and Core verification cannot silently omit public operations from the allocation probe.

The result improves embedded evidence and closes or narrows LIM-003.

9.2 In scope

  • embedded build evaluation for components/presentation
  • embedded build evaluation for components/layout
  • embedded build evaluation for components/manifest
  • components/assets reader and stdio boundary evaluation
  • exclusion of desktop-only reader implementations from embedded builds where needed
  • Core boundary checks against SDK, board, display, filesystem, and network dependencies
  • allocation probe public API coverage enforcement
  • closure or narrowing of LIM-003

9.3 Out of scope

  • complete asset converter implementation
  • runtime text manifest parsing requirement on firmware
  • runtime PNG decoding requirement on firmware
  • persistence format work
  • broad performance benchmarking on hardware
  • generic host or frontend support libraries

9.4 Completion criteria

  • selected frontend-neutral components have embedded build evidence or explicit exclusion records
  • desktop stdio/file assumptions are isolated from embedded builds where required
  • Core boundary checks cover forbidden embedded dependencies
  • allocation probe coverage cannot silently omit a public Core operation
  • LIM-003 is closed or narrowed with recorded evidence
  • any remaining embedded component limitation is linked to a future PBI

9.5 Traceability

  • SPEC-NFR-001: portability
  • SPEC-NFR-002: resource awareness
  • SPEC-NFR-003: testability
  • SPEC-NFR-006: maintainability
  • LIM-003
  • arch-v0.3.0: sections 5.7, 8.3, 8.4, 8.7, and 10.2

10. E22: TFT presentation behaviour cleanup [+]

Release: v0.3.0

Status: Completed

Dependencies: E17

10.1 Outcome

The presentation behaviour that makes the attentive activity unreachable in product runs is fixed or deliberately replaced by a documented product rule.

The result closes or narrows LIM-010 before the TFT direction starts depending on the same presentation roles.

10.2 In scope

  • review of activity and expression dwell rules around greet, attentive, and happy states
  • review of presentation role priority for attentive and happy output
  • Core or presentation-component change if product behaviour requires it
  • tests proving attentive can be presented, or documentation proving why it should remain hidden
  • asset and role contract update only if required by the selected fix
  • closure or narrowing of LIM-010

10.3 Out of scope

  • new activity families
  • new trait, mood, identity, or maturity systems
  • broad art direction changes
  • TFT rendering implementation
  • desktop input expansion
  • generic animation system redesign

10.4 Completion criteria

  • the intended product rule for greet, happy expression, and attentive activity is documented
  • tests cover the selected behaviour
  • presentation roles still insulate renderers from direct Core enum handling
  • desktop SDL presentation continues to fall back calmly for unknown states
  • LIM-010 is closed or narrowed with recorded evidence

10.5 Traceability

  • SPEC-FR-011: calm feedback
  • SPEC-FR-014: autonomous activities
  • SPEC-FR-025: presentation state
  • SPEC-FR-029: frontend independence
  • LIM-010
  • arch-v0.3.0: sections 5.6, 8.7, and 10.2
  • arch-v0.2.0: section 8.2

11. E23: Release verification and hardening

Release: v0.3.0

Status: Planned

Dependencies: E17, E18, E19, E20, E21, E22

11.1 Outcome

The release meets its documented workflow, embedded build, dependency, boundary, presentation behaviour, limitation, and support-claim requirements.

The result is a completed v0.3.0 release whose evidence is strong enough to distinguish what was build tested, what was runtime tested, and what remains architecture-preserved or deferred.

11.2 In scope

  • final release gate over supported hosted compositions
  • ESP-IDF build evidence for the selected firmware foundation target
  • project command entrypoint verification
  • dependency override evidence
  • Core and component boundary evidence
  • allocation-probe coverage evidence
  • presentation behaviour evidence for LIM-010
  • support matrix update
  • known limitation closure, narrowing, or follow-up links for release-scoped limitations
  • release evidence record
  • final consistency review across milestones, architecture, epics, PBIs, progress, bugs, and known limitations

11.3 Out of scope

  • implementing missing feature work from earlier epics
  • adding new release scope during hardening
  • broad Windows verification without a real Windows environment or runner
  • hardware runtime claims without executed hardware evidence
  • production packaging, installers, firmware flashing workflow, or distribution automation

11.4 Completion criteria

  • all required v0.3.0 PBIs are complete
  • the required release gate passes or every exception is explicitly accepted and recorded
  • ESP-IDF build evidence names the exact target, toolchain, command, and result
  • support claims match executed evidence
  • LIM-012, LIM-005, LIM-003, and LIM-010 are closed, narrowed, or linked to explicit follow-up PBIs
  • no excluded runtime capability is claimed
  • release evidence and rollover documentation are complete

11.5 Traceability

  • SPEC-NFR-001: portability
  • SPEC-NFR-002: resource awareness
  • SPEC-NFR-006: maintainability
  • SPEC-NFR-007: compatibility awareness
  • LIM-012, LIM-005, LIM-003, LIM-010
  • arch-v0.3.0: sections 7.2, 8.7, 8.8, 10.3, 10.4, and 10.5
  • 01-milestones.md: release v0.3.0 exit criteria

12. Crosscutting rules

The following rules apply to every epic:

  • code and developer documentation use British English
  • Core code uses ISO C99
  • public domain identifiers use the pet prefix
  • no hidden global mutable world is introduced
  • time and randomness remain explicit
  • tests are implemented with the behaviour they verify
  • invalid public input must not partially mutate authoritative state
  • no frontend, adapter, storage, or networking dependency enters the Core
  • implementation remains within the assigned epic and PBI scope
  • deferred work is recorded instead of being hidden in comments

13. PBI preparation rules

The next planning document is 03-pbis.md.

PBIs derived from these epics must:

  • belong to exactly one epic
  • produce one reviewable outcome
  • include explicit in scope and out of scope boundaries
  • include testable acceptance criteria
  • identify dependencies
  • link to relevant architecture sections
  • identify required verification commands or evidence
  • avoid combining implementation, unrelated refactoring, and future feature work

A PBI set should cover its epic completely before later epic implementation PBIs are marked ready.

14. References

Graph View