Pet epics

Document version	Date	Summary
v1	2026-07-17	Initial epics for release v0.1.0

Status: Draft

Current release: v0.1.0

Related documents: Product specification, milestones, general architecture, and architecture for v0.1.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. Release v0.1.0 epic map

Epic	Title	Status	Primary outcome
E01	Build and portability baseline	Completed	The project has a strict and repeatable ISO C99 build and test foundation
E02	World and pet lifecycle	Completed	One world owns one valid pet through an explicit and safe lifecycle
E03	Deterministic behaviour loop	Completed	Explicit time can produce one reproducible autonomous transition
E04	Semantic interaction	Completed	One platform independent action can change pet behaviour safely
E05	Read only presentation snapshot	Completed	Observable pet state can be consumed without mutable Core access
E06	Headless architecture demonstration	Completed	A small host demonstrates the public Core contracts without product rules
E07	Release verification and hardening	Completed	The release meets its quality, portability, and architecture claims

3.1 Dependency view

flowchart TD
    E01[E01 Build baseline]
    E02[E02 World lifecycle]
    E03[E03 Behaviour loop]
    E04[E04 Semantic action]
    E05[E05 Snapshot]
    E06[E06 Headless demo]
    E07[E07 Release verification]

    E01 --> E02
    E02 --> E03
    E02 --> E04
    E03 --> E05
    E04 --> E05
    E05 --> E06
    E06 --> E07

E03 and E04 may proceed independently after E02 establishes the world lifecycle and shared public types.

Testing is not deferred to E07. Every epic includes its own tests. E07 adds release level integration, compiler, diagnostic, and architecture verification.

4. E01: Build and portability baseline [+]

Release: v0.1.0

Status: Completed

Dependencies: None

4.1 Outcome

The project can build an empty or minimal Pet Core and execute its test target through documented, repeatable commands using strict ISO C99 settings.

The build foundation distinguishes desktop verification from future embedded support. It must not claim support for a platform that has not been tested.

4.2 In scope

• initial repository source layout
• selected build system
• normal build target
• test build and execution target
• strict warning configuration
• GCC verification configuration
• Clang verification configuration
• development diagnostic configuration
• public and private include boundaries
• initial test framework decision
• documented developer commands

4.3 Out of scope

• embedded cross compilation
• package installation
• release archives
• visual frontend dependencies
• hardware SDK dependencies
• production deployment
• CI service integration unless required by a later PBI

4.4 Architecture requirements

• the Core language baseline is ISO C99
• public headers do not expose platform or test framework types
• compiler extensions are not required for correct Core behaviour
• the test framework is a development dependency rather than a Core runtime dependency
• CMocka is the host test framework and remains private to test targets
• portable tests do not depend on GNU linker wrapping
• MSVC is the native Windows compatibility compiler
• optional Windows Clang and Ninja presets own Clang analysis and sanitiser checks
• support claims use the levels defined in the general architecture

4.5 Completion criteria

• one documented command builds the project with GCC
• one documented command builds the project with Clang
• the verification configuration uses strict ISO C99
• configured warnings are treated as errors
• one documented command builds and executes tests
• the Core target has no SDL, operating system, network, or hardware SDK dependency
• public and internal headers have separate ownership
• the selected build and test tools are recorded in the version architecture or an ADR
• Linux GCC and Clang strict gates are repeatable
• the Windows configuration avoids POSIX shell and path assumptions
• Windows remains marked unverified until executed on an actual Windows environment
• a clean checkout can follow the documented commands without undocumented manual steps

4.6 Traceability

• SPEC-NFR-001: portability
• SPEC-NFR-003: testability
• SPEC-NFR-006: maintainability
• SPEC-NFR-010: language and terminology
• arch-v0.1.0: sections 2, 5, and 7

5. E02: World and pet lifecycle [+]

Release: v0.1.0

Status: Completed

Dependencies: E01

5.1 Outcome

The Pet Core can establish, validate, and release one world containing one pet through an explicit ownership and lifecycle contract.

The result is the minimum valid authoritative state on which later behaviour, actions, and snapshots can operate.

5.2 In scope

• public status representation
• core domain types required by one world and one pet
• world initialisation or creation
• world destruction or reset
• fixed-capacity inline or caller-owned world storage
• compile-time capacity definitions
• bounded initialisation of configuration-dependent state
• zero dynamic memory allocation inside Pet Core
• explicit ownership rules
• valid lifecycle order
• invalid lifecycle handling
• internal invariant validation required by public operations
• tests for success and failure paths

5.3 Out of scope

• multiple worlds active through one manager
• multiple pets in one world
• durable persistence
• mood system
• maturity system
• memories and traits
• frontend state
• adapter state
• networking identity

5.4 Architecture requirements

• authoritative world state has one owner
• no hidden global mutable world exists
• partial initialisation failure has a safe cleanup path
• expected failures use explicit status values
• invalid public input does not partially mutate active state
• the lifecycle strategy remains practical for later embedded evaluation
• runtime operations do not allocate, free, or resize Core storage
• large temporary buffers and variable length arrays are not used

5.5 Completion criteria

• one valid world containing one pet can be initialised
• every owned resource has a documented owner
• valid destruction or reset releases or clears owned state safely
• invalid arguments return documented status values
• rejected lifecycle operations leave existing valid state unchanged
• partial initialisation failure has documented and tested behaviour
• all Core capacity limits are compile-time constants or bounded initialisation inputs
• Core initialisation, update, action, and snapshot operations perform no heap allocation
• maximum persistent state and temporary work requirements are documented
• no platform, frontend, adapter, or storage object is required
• lifecycle tests cover valid and invalid order
• the accepted memory and lifecycle strategy is recorded in the version architecture or an ADR

5.6 Traceability

• SPEC-NFR-002: resource awareness
• SPEC-NFR-003: testability
• SPEC-NFR-004: robustness
• SPEC-NFR-006: maintainability
• arch-v0.1.0: sections 5, 8, and 9

6. E03: Deterministic behaviour loop [+]

Release: v0.1.0

Status: Completed

Dependencies: E02

6.1 Outcome

The host can supply explicit elapsed time to the Pet Core and cause one minimal autonomous state transition in a reproducible way.

The behaviour proves that the pet can change without direct user input while remaining independent of frame rate and wall clock access.

6.2 In scope

• selected public time representation
• documented time unit and valid range
• explicit update operation
• one minimal autonomous transition
• transition observability through authoritative state or a temporary test contract
• deterministic replay
• invalid time handling
• overflow and boundary behaviour required by the selected representation
• unit tests

6.3 Out of scope

• calendar dates
• time zones
• missed session summaries
• sleep schedules based on local wall time
• complex mood selection
• long autonomous activity catalogue
• random behaviour unless required by the accepted minimal transition

6.4 Architecture requirements

• the Core does not read the system clock
• time enters through explicit input
• update behaviour does not depend on host frame rate
• transition work is bounded
• random state is explicit and controllable if randomness is introduced
• rejected time input leaves authoritative state unchanged

6.5 Completion criteria

• the public contract defines one time type and unit
• accepted time ranges and invalid values are documented
• explicit elapsed time can produce one autonomous transition
• the same initial state and controlled input produce the same result
• update behaviour does not read wall clock time
• update behaviour does not depend on a graphical loop
• invalid time input is rejected safely
• boundary and overflow behaviour are tested
• the selected transition remains small and does not introduce deferred product systems

6.6 Traceability

• SPEC-FR-013: explicit time progression
• SPEC-FR-014: autonomous activities
• SPEC-FR-017: reproducible Core behaviour
• SPEC-NFR-002: resource awareness
• SPEC-NFR-003: testability
• arch-v0.1.0: sections 6 and 8

7. E04: Semantic interaction [+]

Release: v0.1.0

Status: Completed

Dependencies: E02

7.1 Outcome

The Pet Core accepts at least one semantic action and produces an observable, deterministic domain response without knowing which physical or software input created the action.

7.2 In scope

• first semantic action selection
• action type and validation contract
• action dispatch operation
• one observable pet response
• unsupported and invalid action handling
• repeated action behaviour where relevant
• unit tests

7.3 Out of scope

• keyboard mappings
• button mappings
• touch gestures
• visual menus
• sensor adapters
• Git hooks
• plugin commands
• broad action catalogue
• activity reward systems

7.4 Architecture requirements

• actions represent user intent rather than platform input
• the Core does not include key codes, button numbers, or hardware identifiers
• invalid actions do not partially mutate state
• action handling remains independent of any frontend
• the first action does not require a future mood or progression system

7.5 Completion criteria

• one semantic action is selected and documented
• the action can be dispatched through the public Core contract
• the action produces an observable pet state change
• the action does not contain platform input data
• unsupported and invalid values return documented status values
• rejected actions leave authoritative state unchanged
• repeated action behaviour is defined where relevant
• action tests cover valid and invalid cases

7.6 Traceability

• SPEC-FR-008: semantic actions
• SPEC-FR-009: limited input operation
• SPEC-FR-010: valid absence
• SPEC-FR-017: reproducible Core behaviour
• SPEC-NFR-004: robustness
• arch-v0.1.0: sections 4, 5, and 6

8. E05: Read only presentation snapshot [+]

Release: v0.1.0

Status: Completed

Dependencies: E03, E04

8.1 Outcome

The Pet Core can derive a minimal presentation snapshot that allows a future frontend and the current headless host to observe supported pet behaviour without access to mutable world state.

8.2 In scope

• minimal snapshot type
• fields required to observe the autonomous transition
• fields required to observe the semantic action response
• snapshot creation or retrieval operation
• snapshot ownership and lifetime
• derived state rules
• tests for snapshot correctness and independence

8.3 Out of scope

• pixels and sprite data
• screen coordinates
• SDL types
• animation frame timing
• text layout
• colour themes
• accessibility presentation
• complete future frontend data
• mutable view model

8.4 Architecture requirements

• the snapshot is derived from authoritative state
• the snapshot does not contain mutable internal pointers
• the snapshot does not become a second source of truth
• fields describe product meaning rather than one renderer
• snapshot retrieval has explicit ownership and lifetime
• the Core remains usable without requesting a snapshot

8.5 Completion criteria

• a minimal snapshot can be requested through the public Core contract
• the snapshot exposes the supported autonomous state
• the snapshot exposes the supported action response
• no field is specific to console output or a visual library
• callers cannot mutate authoritative state through the snapshot
• snapshot ownership and lifetime are documented
• repeated snapshot generation does not change world state
• snapshot tests cover valid state and invalid input

8.6 Traceability

• SPEC-FR-025: presentation state
• SPEC-FR-028: headless operation
• SPEC-FR-029: frontend independence
• SPEC-NFR-003: testability
• SPEC-NFR-006: maintainability
• arch-v0.1.0: sections 5 and 6

9. E06: Headless architecture demonstration [+]

Release: v0.1.0

Status: Completed

Dependencies: E05

9.1 Outcome

A small headless executable demonstrates the complete public Core path using controlled time, semantic interaction, and snapshots.

The executable proves composability. It is not a product frontend and does not define domain behaviour.

9.2 In scope

• headless executable target
• world lifecycle through public API
• controlled elapsed time sequence
• supported semantic action dispatch
• snapshot observation
• concise diagnostic output
• meaningful process exit status
• failure cleanup
• one repeatable demonstration scenario

9.3 Out of scope

• visual output
• interactive command shell
• stable diagnostic text format
• configuration files
• durable saves
• plugin loading
• platform input polling
• domain decisions in the host

9.4 Architecture requirements

• the host depends only on the public Pet API
• product rules remain in the Core
• diagnostic output is not a stable product interface
• the host supplies all effects explicitly
• the host handles Core failures without bypassing status contracts
• the same Core can be built without the host

9.5 Completion criteria

• the headless executable builds through a documented command
• it creates and destroys a world through the public API
• it supplies explicit elapsed time
• it dispatches the supported semantic action
• it observes results through snapshots
• it returns failure through process status when a required operation fails
• it contains no duplicate product transition rule
• its demonstration scenario is repeatable
• the Pet Core target remains independently buildable

9.6 Traceability

• SPEC-FR-028: headless operation
• SPEC-FR-029: frontend independence
• SPEC-NFR-003: testability
• SPEC-NFR-006: maintainability
• arch-v0.1.0: sections 3, 5, 6, and 7

10. E07: Release verification and hardening [+]

Release: v0.1.0

Status: Completed

Dependencies: E01, E02, E03, E04, E05, E06

10.1 Outcome

Release v0.1.0 satisfies its milestone exit criteria, architecture claims, compiler matrix, and documented quality requirements without overstating embedded or product readiness.

10.2 In scope

• complete GCC build and test execution
• complete Clang build and test execution
• strict warning verification
• configured runtime diagnostics
• deterministic end to end headless scenario
• public API negative tests
• automated Core boundary, header, and allocation verification
• architecture dependency review
• support claim review
• version architecture finalisation
• known limitation and deferred defect review
• release evidence recording

10.3 Out of scope

• implementation of missing feature scope from another epic
• embedded cross compilation
• packaging for end users
• product demo preparation
• visual quality review
• performance optimisation without evidence of need

10.4 Architecture requirements

• release evidence matches the platform matrix
• passing headless tests do not imply visual product readiness
• portable by design does not become an embedded support claim
• sanitiser availability is recorded per toolchain
• deviations from the general or version architecture are resolved or documented
• no release criterion is satisfied only by an undocumented manual observation

10.5 Completion criteria

• all v0.1.0 epic completion criteria are satisfied
• all child PBIs are completed
• GCC builds and tests pass
• Clang builds and tests pass
• the strict warning build passes
• configured runtime diagnostics pass where supported
• the controlled headless scenario is reproducible
• public failure contracts have negative tests
• forbidden platform dependencies are absent from the Core, verified automatically rather than by review alone
• platform claims match recorded evidence
• architecture decisions and deviations are up to date
• new limitations and deferred bugs are recorded
• arch-v0.1.0.md reflects the release architecture
• all release exit criteria in 01-milestones.md are satisfied

10.6 Traceability

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

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

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

The first PBI set should cover E01 completely before later epic implementation PBIs are marked ready.

13. References

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