Pet epics

Document version	Date	Summary
v1	2026-07-17	Initial epics for release v0.1.0
v2	2026-07-19	Archive the completed v0.1.0 epics and open the v0.2.0 map
v3	2026-07-20	Define v0.2.0 desktop reference app epics
v4	2026-07-20	Complete the v0.2.0 architecture and compatibility contracts
v5	2026-07-22	Refine E13 around the shared presentation component
v6	2026-07-22	Record E13 completion
v6	2026-07-22	Add the v0.2.0 epic dependency view

Status: Draft

Current release: v0.2.0

Related documents: Product specification, milestones, general architecture, and the release archive. The v0.2.0 version architecture is written during its planning.

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.

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

4. Release v0.2.0 epic map

Epic	Title	Status	Primary outcome
E08	v0.2.0 architecture and compatibility contracts	Completed	The app, frontend, composition, asset, and presentation maintenance boundaries for v0.2.0 are documented and accepted
E09	Composition registry and gate selection	Completed	The build and verification workflows can select valid app and frontend compositions from one declared registry
E10	Pinned SDL desktop frontend foundation	Completed	The SDL frontend has pinned dependencies, a stable component layout, and a buildable target
E11	Desktop app host lifecycle	Completed	pet_desktop composes the Core and SDL frontend, drives time and lifecycle, and shuts down cleanly
E12	Canonical visual assets and manifest	Completed	Canonical visual assets are loaded through a bounded manifest with guaranteed fallback presentation
E13	Presentation roles and animation model	Completed	A shared component maps Core snapshots through presentation roles into deterministic animations without renderer rewrites
E14	Snapshot driven SDL rendering and layout	Completed	The SDL frontend renders public presentation state on a documented logical canvas with stable scaling
E15	Semantic desktop input	Completed	Keyboard and pointer input produce semantic Core actions while host controls remain outside product actions
E16	Frontend, app, and release verification	Completed	The desktop composition and Core boundaries are covered by repeatable tests, gates, and release evidence

The release goal and expected capabilities are recorded in milestones. PBIs for this release start at PBI-035.

4.1 Dependency view

flowchart TD
    E08[E08 Architecture contracts]
    E09[E09 Composition registry]
    E10[E10 SDL frontend foundation]
    E11[E11 Desktop lifecycle]
    E12[E12 Assets and manifest]
    E13[E13 Presentation roles and animation]
    E14[E14 SDL rendering and layout]
    E15[E15 Semantic desktop input]
    E16[E16 Release verification]

    E08 --> E09
    E09 --> E10
    E10 --> E11
    E10 --> E12
    E11 --> E13
    E12 --> E13
    E13 --> E14
    E11 --> E15
    E14 --> E16
    E15 --> E16

E11 and E12 may proceed independently after E10 establishes the SDL frontend foundation. E13 builds on the SDL presentation lifecycle from E11 and the accepted asset manifest records from E12, and E14 consumes both the loaded assets and the shared presentation selection. E15 can proceed beside E12 through E14 once the desktop lifecycle exists. E16 is the release-level convergence point: it verifies the full set of completed v0.2.0 epics, even where the graph shows only the primary path into it.

5. E08: v0.2.0 architecture and compatibility contracts [+]

Release: v0.2.0

Status: Completed

Dependencies: None

5.1 Outcome

The release architecture defines the desktop reference app, the SDL frontend, the app and frontend composition model, the canonical visual asset contract, and the presentation mapping rule that keeps future Core growth from forcing renderer rewrites.

The result is an accepted implementation plan that can guide PBIs without allowing SDL, assets, app lifecycle policy, or gate mechanics to define Core behaviour.

5.2 In scope

• arch-v0.2.0.md
• SDL dependency decision
• canonical visual asset and manifest decision
• app and frontend directory contracts
• app and frontend README template requirements
• presentation role and fallback policy
• app and frontend composition contract
• host conformance rules for the desktop app
• frontend maintenance rule for unmapped presentable Core states
• Linux, Windows, and embedded support claim boundaries

5.3 Out of scope

• implementing the desktop executable
• implementing the SDL frontend
• implementing assets, rendering, or input
• implementing a generic host support library
• implementing a generic frontend support library
• implementing embedded runtime support
• implementing persistence, adapters, networking, or audio

5.4 Architecture requirements

• the Core remains independent of SDL, image formats, asset paths, platform clocks, input devices, and renderers
• apps/desktop owns one executable target and follows the app documentation contract
• app and frontend components use include/ and src/ ownership consistently unless the version architecture records a narrower local exception
• frontend code consumes public presentation state and never mutable Core world storage
• new Core states that are presentable but unmapped by this frontend use a calm fallback
• accepted decisions with meaningful alternatives are recorded in ADRs under docs/adr/
• idea documents remain non-authoritative until their content is moved into architecture, ADR, milestone, epic, or PBI documents

5.5 Completion criteria

• arch-v0.2.0.md exists and follows the version architecture policy
• the SDL dependency decision is recorded
• the canonical visual asset and manifest decision is recorded
• app and frontend source layout rules are documented
• the desktop app contract names what the app may and must not own
• the SDL frontend contract names what the frontend may and must not own
• the presentation role and fallback maintenance rule is documented
• the composition registry and gate selection scope is documented
• host support and frontend support libraries are explicitly deferred
• Linux, Windows, and embedded support claims are bounded by expected evidence

5.6 Traceability

• SPEC-PR-007: one Core and multiple frontends
• SPEC-FR-025: presentation state
• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-027: desktop reference frontend
• SPEC-FR-029: frontend independence
• SPEC-NFR-006: maintainability
• SPEC-NFR-007: compatibility awareness
• 01-milestones.md: release v0.2.0
• arch-v0.2.0: sections 1, 2, 4, 5, 8, 9, and 11

6. E09: Composition registry and gate selection [+]

Release: v0.2.0

Status: Completed

Dependencies: E08

6.1 Outcome

The project can describe supported app and frontend combinations in one declarative registry and use that registry from development workflows to select, reject, and verify compositions.

The result prevents future frontend growth from duplicating compatibility rules across CMake, Python, and release documentation.

6.2 In scope

• app and frontend composition registry schema
• initial headless and desktop app entries
• initial none and sdl frontend entries
• app default frontend resolution
• incompatible pair rejection
• executable composition helper under tools/
• gate.py app and frontend selection options
• --all-compositions verification path
• separate build directories per preset and composition
• direct CMake usage with explicit app and frontend selection

6.3 Out of scope

• runtime frontend plugin loading
• unrestricted Cartesian product generation
• CI service integration
• production packaging matrix generation
• embedded app implementation
• automatically generating source files from the registry unless required by a PBI

6.4 Architecture requirements

• CMake remains responsible for targets, dependencies, include paths, build directories, and CTest registration
• Python remains responsible for workflow orchestration, registry validation, and gate matrix expansion
• compatibility between apps and frontends has one source of truth
• direct CMake configure and build commands remain possible
• a selected composition must not change Core source, public Core headers, or Core compile options
• default gates continue to cover the headless composition

6.5 Completion criteria

• the composition registry schema is documented and validated
• headless with none is a valid composition
• desktop with sdl is a valid composition
• invalid app and frontend pairs are rejected before compilation
• gate.py can select an app and its default frontend
• gate.py can select an explicit app and frontend pair
• gate.py can run all valid compositions when requested
• each selected preset and composition uses an isolated build directory
• direct CMake use with explicit app and frontend values remains documented
• Python tools added for this epic are directly executable and import safe

6.6 Traceability

• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-027: desktop reference frontend
• SPEC-FR-028: headless operation
• SPEC-FR-029: frontend independence
• SPEC-NFR-003: testability
• SPEC-NFR-006: maintainability
• arch-v0.2.0: sections 5, 7, and 10

7. E10: Pinned SDL desktop frontend foundation [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E09

7.1 Outcome

The SDL frontend exists as a buildable component with pinned dependencies, a documented ownership contract, and the source layout required to support rendering, assets, animation, input, and tests.

The result gives the desktop app a real visual frontend target without making SDL a Core dependency.

7.2 In scope

• frontends/README.md
• frontends/README.template.md
• frontends/sdl/README.md
• frontends/sdl/CMakeLists.txt
• frontends/sdl/include/
• frontends/sdl/src/
• frontends/sdl/tests/
• pinned SDL3 dependency
• pinned image loading dependency or pinned SDL3 version that provides the accepted PNG path
• SDL frontend target and alias
• third party warning isolation
• system include treatment where supported
• clean dependency unavailability diagnostics

7.3 Out of scope

• finished rendering
• finished input mapping
• finished asset manifest parser
• embedded frontend target
• generic frontend support library
• runtime frontend plugin API
• packaging SDL for end users

7.4 Architecture requirements

• SDL and optional image loading dependencies are frontend dependencies only
• third party dependencies do not inherit project warnings as errors
• the Core can build with the SDL frontend disabled
• public frontend headers expose only the contract the desktop app needs
• private SDL implementation headers remain private to the frontend component
• dependency versions and override policy are recorded

7.5 Completion criteria

• the accepted SDL dependency versions are pinned
• the accepted image loading path is pinned or explicitly excluded
• pet_frontend_sdl builds as a frontend target
• the frontend target can be disabled without affecting the Core
• public and private frontend headers have documented ownership
• third party headers are not treated as project code by diagnostics
• dependency failures produce clear configuration errors
• frontends/sdl/README.md follows the frontend documentation contract

7.6 Traceability

• SPEC-PR-007: one Core and multiple frontends
• SPEC-FR-025: presentation state
• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-027: desktop reference frontend
• SPEC-FR-029: frontend independence
• SPEC-NFR-006: maintainability
• arch-v0.2.0: sections 5, 7, 8, and 9

8. E11: Desktop app host lifecycle [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E09, E10

8.1 Outcome

pet_desktop composes one Pet Core world with the SDL frontend, owns desktop lifecycle and elapsed time policy, and shuts down without leaking Core state or platform resources.

The result is the first real product application and the first platform host that can provide evidence for the host support layer idea.

8.2 In scope

• apps/desktop/README.md
• apps/desktop/CMakeLists.txt
• apps/desktop/include/
• apps/desktop/src/
• apps/desktop/tests/test_scenario.cmake
• pet_desktop executable target
• Core world initialisation, update, snapshot, action dispatch, and reset
• SDL frontend creation and destruction
• monotonic elapsed time policy
• large delta handling before calling the Core
• status handling and process exit status
• app configuration needed for the development runtime
• clean quit and shutdown ordering

8.3 Out of scope

• product behaviour outside the Core
• persistence or save files
• adapters
• audio
• embedded lifecycle
• generic host support library
• production installation layout

8.4 Architecture requirements

• the desktop app owns lifecycle and composition, not domain behaviour
• the app calls only public Core APIs
• raw platform input reaches the Core only after it becomes a supported semantic action
• host controls, such as quit, are not product actions
• the app supplies elapsed time to the Core and to frontend animation code explicitly
• the Core receives no platform clock or SDL callback
• desktop app headers are component local and do not create a reusable host library contract

8.5 Completion criteria

• pet_desktop builds for the selected desktop composition
• the app initialises and resets a Core world through the public API
• the app creates and destroys the SDL frontend in a documented order
• the app computes bounded elapsed deltas before calling pet_world_update
• a large or invalid elapsed value cannot cause an uncontrolled Core update
• Core status failures produce a clean non-zero process result
• normal quit produces clean shutdown and exit status zero
• the process scenario covers start, one update, one snapshot render path, and shutdown
• the app README follows apps/README.template.md

8.6 Traceability

• SPEC-FR-008: semantic actions
• SPEC-FR-010: valid absence
• SPEC-FR-013: explicit time progression
• SPEC-FR-016: safe clock anomalies
• SPEC-FR-025: presentation state
• SPEC-FR-027: desktop reference frontend
• SPEC-NFR-003: testability
• SPEC-NFR-005: responsiveness
• arch-v0.2.0: sections 5, 6, 7, and 8

9. E12: Canonical visual assets and manifest [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E10

9.1 Outcome

The project has one canonical visual asset source and a bounded manifest contract that the SDL frontend can load without hard-coding state-specific paths.

The result keeps future desktop and embedded frontend formats derived from the same source assets rather than requiring one source file per frontend.

9.2 In scope

• assets/README.md
• canonical visual asset directory
• manifest file format version
• accepted raster source format
• bounded manifest parser
• manifest validation errors
• duplicate identifier rejection
• invalid reference rejection
• path traversal rejection
• development runtime asset layout
• CMake asset copy for the selected build directory
• guaranteed fallback presentation when files are missing or invalid

9.3 Out of scope

• complete asset conversion pipeline
• sprite atlas generation
• hot reload
• asset editor tooling
• production packaging
• runtime download of assets
• embedded generated binary format implementation
• audio assets

9.4 Architecture requirements

• canonical assets are the source of truth
• generated target artefacts are not treated as canonical source assets
• the frontend does not hard-code state-specific asset file paths
• manifest parsing happens outside the render loop
• manifest parsing has bounded input sizes and bounded stored entries
• missing or invalid assets fall back calmly and do not make the app unusable
• the Core does not know asset identifiers, file paths, or image formats

9.5 Completion criteria

• the canonical visual asset format is documented
• the manifest schema and limits are documented
• valid manifests load successfully
• unknown manifest versions are rejected
• duplicate asset and animation identifiers are rejected
• invalid references are rejected
• path traversal attempts are rejected
• runtime asset files are available from the selected build directory
• missing asset files use guaranteed fallback presentation
• asset verification can detect missing manifest references

9.6 Traceability

• SPEC-FR-011: calm feedback
• SPEC-FR-025: presentation state
• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-027: desktop reference frontend
• SPEC-FR-029: frontend independence
• SPEC-NFR-004: robustness
• SPEC-NFR-006: maintainability
• arch-v0.2.0: sections 5, 7, 8, and 10

10. E13: Presentation roles and animation model [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E10, E11, E12

10.1 Outcome

A shared presentation component maps public Core snapshots into presentation roles and then into deterministic manifest animations, so SDL and future frontends can share the same presentation decision rules without copying renderer logic.

The result establishes the near-zero-maintenance rule for frontend behaviour as the Core grows.

10.2 In scope

• components/presentation/
• snapshot to presentation role mapping
• activity and expression role names
• initial activity/expression priority policy
• unmapped role fallback
• role to animation lookup
• single-frame animation support
• multi-frame animation data model
• explicit animation elapsed time input
• deterministic frame selection
• animation loop behaviour
• SDL frontend consumption of the shared role and frame selection output
• tests for known and unknown mapping cases

10.3 Out of scope

• skeletal animation
• tweening
• interpolation
• blending
• animation graphs
• animation editor tooling
• sprite atlas support
• SDL rendering, textures, windows, and layout
• asset file loading and PNG decoding
• moving presentation role mapping into the Core unless a PBI proves it is required

10.4 Architecture requirements

• renderer code is insulated from direct Core enum handling by a shared presentation mapping boundary
• missing or unknown presentable Core states use a documented fallback
• animation selection reads explicit elapsed time supplied by the app
• animation selection does not read wall clock time
• presentation roles are frontend presentation vocabulary, not Core authoritative state
• components/presentation has no SDL, app, frontend, filesystem, asset reader, or allocation dependency
• SDL consumes presentation decisions but does not own the reusable role and animation policy
• no SDL-specific value is added to PetSnapshot
• adding a new Core snapshot field does not force this frontend to consume it

10.5 Completion criteria

• components/presentation builds and tests as a shared component
• current Core activity values map to presentation roles
• current Core expression values map to presentation roles
• role priority or combination policy is documented
• unmapped roles use a fallback animation
• animation frame selection is deterministic for equal inputs
• loop behaviour is tested
• SDL renderer code consumes the presentation selection output rather than raw Core world state
• no Core API change is introduced only to name an asset or animation

10.6 Traceability

• SPEC-FR-011: calm feedback
• SPEC-FR-014: autonomous activities
• SPEC-FR-025: presentation state
• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-029: frontend independence
• SPEC-NFR-003: testability
• SPEC-NFR-006: maintainability
• arch-v0.2.0: sections 5, 6, 8, and 11

11. E14: Snapshot driven SDL rendering and layout [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E10, E12, E13

11.1 Outcome

The SDL frontend renders the pet from public presentation data on a documented logical canvas with stable layout, integer scaling where practical, and calm fallback presentation.

The result lets a user observe autonomous and direct interaction feedback without coupling rendering to Core internals.

11.2 In scope

• SDL renderer lifecycle inside the frontend
• fallback-only render foundation
• logical canvas selection
• shared logical canvas layout calculations
• nearest-neighbour presentation
• integer scaling where practical
• window resize handling
• calm background
• asset-backed pet drawing
• built-in fallback drawing
• tests for pure shared layout and scaling calculations

11.3 Out of scope

• production art direction
• shader effects
• advanced camera or scene graph
• sprite atlas support
• performance optimisation without evidence
• embedded display driver implementation
• audio or haptic output

11.4 Architecture requirements

• rendering consumes PetSnapshot through the shared presentation selection derived from it
• rendering never receives a mutable PetWorld *
• shared layout code is testable without real SDL resources
• the selected logical canvas is documented as a release choice, not a permanent hardware dependency
• fallback presentation is not an error notification and does not demand user action
• the first render increment may draw the guaranteed fallback before asset-backed drawing exists
• platform support claims distinguish real window verification from headless or dummy driver tests

11.5 Completion criteria

• the SDL renderer can create and destroy its resources cleanly
• a snapshot-driven render path draws a visible pet representation
• the guaranteed fallback path draws without external asset files
• the selected logical canvas is documented
• resize handling preserves the intended aspect ratio
• scaling calculations are covered by tests
• real or dummy SDL runtime evidence is recorded truthfully
• no renderer path reads Core internal headers or mutable Core world state

11.6 Traceability

• SPEC-FR-011: calm feedback
• SPEC-FR-025: presentation state
• SPEC-FR-026: varied frontend capabilities
• SPEC-FR-027: desktop reference frontend
• SPEC-FR-029: frontend independence
• SPEC-NFR-005: responsiveness
• SPEC-NFR-009: accessibility
• arch-v0.2.0: sections 5, 6, 7, 8, and 10

12. E15: Semantic desktop input [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E10, E11

12.1 Outcome

The SDL frontend translates supported keyboard and pointer input into frontend events, and the desktop app dispatches only product actions to the Core while keeping host controls separate.

The result proves the semantic input boundary through a visible desktop interaction.

12.2 In scope

• SDL keyboard input mapping
• SDL pointer input mapping
• limited input operation
• frontend event kind distinction
• product action events
• host control events
• quit handling
• dispatch of supported PetAction values
• visible response to at least one direct interaction
• tests for input mapping and host control separation

12.3 Out of scope

• broad menu system
• configurable key binding UI
• text input
• controller support unless selected by a PBI
• multi-touch gestures
• adapter supplied activities
• adding Core actions that are not required for the release evidence

12.4 Architecture requirements

• raw SDL events never reach the Core
• a frontend event can represent a product action or a host control
• quit, resize, and focus events are not product actions
• unsupported input is ignored safely
• no interaction requires rapid repeated input
• any new Core action is added only when the release needs a semantic product intent that the existing API cannot express

12.5 Completion criteria

• at least one keyboard input maps to a supported semantic action
• at least one pointer input maps to a supported semantic action
• quit input produces a host control rather than a product action
• unsupported input does not mutate Core state
• the app dispatches supported product actions through pet_world_apply_action
• direct interaction produces visible feedback through the Core and snapshot path
• input mapping tests cover action, host control, and ignored input cases

12.6 Traceability

• SPEC-FR-008: semantic actions
• SPEC-FR-009: limited input operation
• SPEC-FR-011: calm feedback
• SPEC-FR-012: capability aware behaviour
• SPEC-FR-025: presentation state
• SPEC-FR-027: desktop reference frontend
• SPEC-NFR-004: robustness
• SPEC-NFR-009: accessibility
• arch-v0.2.0: sections 5, 6, 8, and 10

13. E16: Frontend, app, and release verification [+]

Release: v0.2.0

Status: Completed

Dependencies: E08, E09, E10, E11, E12, E13, E14, E15

13.1 Outcome

Release v0.2.0 satisfies its desktop reference app exit criteria, verifies that Core boundaries remain intact, and records support claims without overstating Windows or embedded readiness.

13.2 In scope

• Core and headless gate preservation
• desktop composition strict gate
• frontend tests
• desktop process scenario
• dependency checks
• include boundary checks
• asset manifest checks
• composition matrix checks
• Linux desktop runtime evidence
• Windows support status review
• embedded support status review
• known limitation and deferred defect review
• release evidence recording
• version architecture finalisation

13.3 Out of scope

• implementing missing feature scope from another epic
• production packaging
• installer generation
• embedded runtime validation
• Windows support claims without Windows evidence
• visual polish beyond the release acceptance criteria
• performance optimisation without evidence of need

13.4 Architecture requirements

• passing the default headless gate does not imply desktop composition readiness
• passing a desktop build does not imply Windows or embedded runtime support
• Core dependency checks remain separate from frontend dependency checks
• manual visual evidence is labelled manual when no automated equivalent exists
• unavailable SDL, display, Windows, or embedded checks are recorded rather than reported as passing
• deviations from the general or version architecture are resolved or documented

13.5 Completion criteria

• all v0.2.0 epic completion criteria are satisfied
• all child PBIs are completed
• Core and headless strict checks pass
• the desktop SDL composition strict checks pass
• frontend unit tests pass
• the desktop process scenario passes or an accepted limitation records why it cannot run
• dependency and include checks verify SDL stays outside the Core
• asset checks verify the manifest and runtime asset layout
• composition checks verify valid and invalid app/frontend pairs
• Linux desktop support evidence is recorded
• Windows and embedded statuses match available evidence
• new limitations and deferred bugs are recorded
• arch-v0.2.0.md reflects the implemented system
• all release exit criteria in 01-milestones.md are satisfied

13.6 Traceability

• all specification requirements allocated to v0.2.0
• all quality requirements mapped by arch-v0.2.0.md
• 01-milestones.md: release v0.2.0 exit criteria
• arch-v0.2.0: sections 7, 10, and 11

14. 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

15. 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.

16. References

• Pet product specification
• Pet milestones
• General Pet architecture
• Pet architecture for v0.1.0
• Release v0.1.0 archive
• Release process
• Semantic Versioning 2.0.0
• arc42 architecture documentation