Product Backlog Items

Document version	Date	Summary
v1	2026-07-17	Create the V0 backlog
v2	2026-07-20	Add and refine the v0.2.0 backlog
v3	2026-07-24	Archive v0.2.0 and open the next backlog
v4	2026-07-27	Add v0.3.0 and complete E17 planning
v5	2026-07-27	Record completed v0.3.0 PBIs through E20
v6	2026-07-27	Clarify the T-Display family and selected S3 variant contract

1. Purpose

This document defines the Product Backlog Items for V0. It decomposes the epics in epics into independently verifiable increments.

The backlog is ordered by dependency and risk. A PBI may be refined before implementation, but its outcome and acceptance criteria must remain aligned with the specification, milestones, the general architecture, and the active version architecture document.

2. PBI structure

Each PBI contains:

• an epic reference
• an intended outcome
• the work included in the PBI
• acceptance criteria
• dependencies

Implementation details may change when evidence supports a better solution. Acceptance criteria describe required behaviour and evidence rather than a preferred internal implementation.

3. Shared Definition of Done

Every completed PBI must satisfy all applicable acceptance criteria and the following shared rules.

3.1 Required strict quality gate

The strict quality gate must run after every PBI that changes code, build configuration, tests, or developer tooling. It includes:

1. formatting verification with clang-format
2. a clean GCC build using ISO C99 without compiler extensions
3. the complete unit test suite built and run with GCC
4. a clean Clang build using ISO C99 without compiler extensions
5. the complete unit test suite built and run with Clang
6. the agreed GCC and Clang warnings treated as errors for project code
7. Cppcheck analysis of project code
8. parallel Clang-Tidy analysis of project code
9. an AddressSanitizer build and test run
10. an UndefinedBehaviourSanitizer build and test run
11. a Pet Core symbol scan against the allowlist for the toolchain that built the archive
12. a self-containment compilation of every public header, alone, for GCC and Clang

A documentation-only PBI does not require compiler checks unless it changes a technical contract that can be verified immediately.

If a required check cannot run, the PBI is not complete unless the maintainer explicitly accepts and records the exception.

The canonical strict gate runs on Linux. A Windows developer runs the native Windows gate before handover. The PBI remains incomplete until the canonical Linux strict gate also passes. This keeps the completion rule consistent without requiring Linux-only tools on Windows.

The native Windows gate includes formatting verification, MSVC warnings, an MSVC build, CTest, and Cppcheck. An optional Windows Clang and Ninja gate adds parallel Clang-Tidy, ASan, and UBSan where the selected toolchain supports them. Valgrind is not a Windows requirement.

3.2 Audit quality gate

The audit quality gate includes the strict gate plus:

• branch coverage generation
• Valgrind memory analysis
• runtime allocation verification of Pet Core, requiring zero heap usage
• clean rebuilds from empty build directories
• release support matrix verification

The audit gate runs:

• before a version release
• before closing a milestone
• after material ownership, storage layout, capacity, or lifetime changes
• when requested by the assigned PBI

Coverage and Valgrind do not need to run after every ordinary PBI.

3.3 Scope and documentation

Before a PBI is complete:

• its acceptance criteria must be checked
• relevant tests must be added or updated
• affected component knowledge files must be updated when required by agent rules
• progress and last development must be updated according to agent rules
• newly discovered deferred work must be recorded in the appropriate backlog or limitation file
• unrelated behaviour must not be added to the PBI

3.4 Portability status

Linux GCC and Linux Clang are the verified host toolchains for v0.1.0.

Windows compatibility is a design requirement from the first PBI. Project code, public headers, paths, CMake logic, tests, and developer workflows must avoid unnecessary POSIX assumptions. Windows must not be described as build tested until the project has been built and tested using an actual Windows developer environment or Windows CI runner.

Embedded portability is also a design requirement. It does not mean that v0.1.0 supports an embedded deployment. Pet Core must remain independent from operating system windows, filesystems, sockets, threads, sensors, and platform clocks.

MSVC is the native Windows compatibility compiler. Windows uses C17 mode to compile the C99 Core because MSVC does not provide a C99 language mode. GCC and Clang remain the strict C99 conformance toolchains. An optional Windows Clang and Ninja configuration owns compilation database analysis and sanitiser checks.

4. Quality tooling policy

4.1 Tool names

Project configuration and commands use unversioned executable names:

gcc
clang
clang-format
clang-tidy
run-clang-tidy
cppcheck
gcovr
valgrind
cmake
ninja
nm
python3

Local environments may select a specific installed version outside project files when required.

4.2 Formatting baseline

The initial .clang-format configuration is:

Language:        C
BasedOnStyle:    LLVM
IndentWidth:     4
UseTab:          Never
ColumnLimit:     100
PointerAlignment: Right
 
BreakBeforeBraces:          Attach
SpaceBeforeParens:          ControlStatements
SpaceAfterCStyleCast:       false
IndentCaseLabels:           true
BreakBeforeBinaryOperators: None
SortIncludes:               Never
 
KeepEmptyLinesAtTheStartOfBlocks: false
MaxEmptyLinesToKeep:              1
 
AlignConsecutiveAssignments:
  Enabled:          true
  AcrossEmptyLines: false
  AcrossComments:   false
  AlignCompound:    true
  PadOperators:     false
 
AlignConsecutiveDeclarations:
  Enabled:          true
  AcrossEmptyLines: false
  AcrossComments:   false

4.3 Clang-Tidy baseline

The initial .clang-tidy configuration is based on:

Checks: >
  clang-analyzer-*,
  bugprone-*,
  cert-*,
  misc-*,
  performance-*,
  portability-*,
  readability-*,
  -readability-magic-numbers,
  -readability-identifier-length,
  -readability-function-cognitive-complexity,
  -readability-braces-around-statements,
  -misc-include-cleaner,
  -bugprone-easily-swappable-parameters,
  -performance-enum-size
 
WarningsAsErrors: '*'
HeaderFilterRegex: '.*/(src|include|frontends|tests)/.*'
ExcludeHeaderFilterRegex: '.*/(build|_deps|third_party)/.*'
SystemHeaders: false
FormatStyle: file

Clang-Tidy must analyse only project translation units and project headers. Dependencies may still be parsed when required to understand project code, but diagnostics from system headers, generated files, fetched dependencies, and third-party code must not be treated as project findings.

The check list may be refined when a check is demonstrably unsuitable for C99 or conflicts with an explicit project rule. Disabling a check requires a short recorded reason.

5. Archived releases

Completed v0.1.0 PBIs are archived in release v0.1.0. That archive holds PBI-001 through PBI-034 with their outcomes, included work, acceptance criteria, and dependencies, grouped by epic E01 through E07.

Completed v0.2.0 PBIs are archived in release v0.2.0. That archive holds PBI-035 through PBI-063 with their outcomes, included work, acceptance criteria, and dependencies, grouped by epic E08 through E16.

PBI identifiers continue after PBI-063. They are permanent and are not reused, so a future release never restarts the sequence.

6. Release v0.3.0 PBIs

The release goal and expected capabilities are recorded in milestones. The epics are recorded in epics. The architecture is recorded in architecture for v0.3.0. PBI identifiers continue from PBI-064.

A new PBI is added under its epic heading and follows the structure in section 2, the shared Definition of Done in section 3, and the quality tooling policy in section 4.

E17 v0.3.0 architecture and release scope

PBI-064 Accept the v0.3.0 version architecture [+]

Epic: E17 v0.3.0 architecture and release scope

Outcome: The v0.3.0 release has an accepted architecture document that defines the embedded firmware foundation, ESP-IDF boundary, T-Display family and variant configuration, TFT frontend direction, project command entrypoint, generated embedded asset direction, and support-claim limits before implementation begins.

Included work:

• review docs/arch/arch-v0.3.0.md against the milestone and epics
• keep the required arc42 top level structure
• confirm the firmware app, platform glue, board configuration, and TFT frontend boundaries
• confirm that ESP-IDF and board dependencies stay outside the Core
• confirm that generated embedded assets are direction only unless a PBI implements a format
• link release-scoped limitations to the epic that owns each resolution

Acceptance criteria:

• every required architecture section exists
• the architecture states that Core stays independent of ESP-IDF, board pins, display drivers, SDL, filesystems, and networking
• the architecture records apps/firmware, platforms/esp_idf, boards/t_display, and frontends/tft ownership
• the architecture explains how the generic firmware app composes board, frontend, and platform details without owning them
• the architecture distinguishes build evidence from hardware runtime evidence
• LIM-012, LIM-005, LIM-003, and LIM-010 have explicit owning epics

Dependencies: None

PBI-065 Record the generated embedded asset direction [+]

Epic: E17 v0.3.0 architecture and release scope

Outcome: Embedded runtime assets are documented as generated artefacts derived from canonical PNG and manifest sources, without committing to a final generated format or converter contract.

Included work:

• record that canonical source remains assets/pet/manifest.petasset and assets/pet/sprites/*.png
• record that embedded runtime should not require text manifest parsing, PNG decoding, or desktop filesystem paths
• identify the future decision point for a generated asset format ADR
• update roadmap or idea notes if they conflict with the accepted architecture

Acceptance criteria:

• the direction is documented in architecture or linked planning notes
• no runtime embedded parser or PNG decoder requirement is introduced
• no generated format is described as a compatibility promise
• future converter work is explicitly deferred to a later PBI or release

Dependencies: PBI-064

E18 Simple project command entrypoint [+]

PBI-066 Define the project command surface [+]

Epic: E18 Simple project command entrypoint

Outcome: The project has a documented command surface for common daily workflows before the entrypoint is implemented.

Included work:

• choose the command name
• define build, test, run desktop, verify, and clean commands
• define whether dry-run or command planning output is required
• define error behaviour for unsupported commands and missing tools
• record which commands remain maintainer-level direct CMake or gate usage

Acceptance criteria:

• the command surface is documented
• commands delegate to existing project workflows rather than defining new verification behaviour
• direct CMake and gate.py usage remains supported
• embedded flash and monitor commands are either explicitly excluded or deferred

Dependencies: PBI-064

PBI-067 Implement the project command entrypoint [+]

Epic: E18 Simple project command entrypoint

Outcome: A small project-owned entrypoint can plan or run the documented daily workflows.

Included work:

• add the entrypoint at the repository root
• implement the commands accepted by PBI-066
• call existing CMake, CTest, gate, and run workflows
• add tests for command parsing and command planning
• keep the implementation standard-library only unless a later PBI accepts a dependency

Acceptance criteria:

• supported commands map to the documented underlying workflows
• unsupported command combinations fail clearly
• command parsing and planning are covered by tests
• the implementation does not duplicate the composition registry
• strict gate remains the authoritative implementation completion gate

Dependencies: PBI-066

PBI-068 Document the daily and maintainer workflows [+]

Epic: E18 Simple project command entrypoint

Outcome: Developers can find the simple daily commands and the direct maintainer commands without reading gate internals.

Included work:

• update the primary README or developer documentation with the daily command entrypoint
• document direct CMake and gate.py commands for maintainers
• document any command prerequisites
• link the workflow documentation from the architecture or code rules where appropriate

Acceptance criteria:

• build, test, run desktop, verify, and clean workflows are documented
• maintainer-level direct commands remain visible
• documentation does not imply unsupported embedded flash, monitor, or runtime features
• command examples match implemented command names

Dependencies: PBI-067

E19 Dependency and local override policy [+]

PBI-069 Define the dependency local override policy [+]

Epic: E19 Dependency and local override policy

Outcome: The project has a single documented policy for pinned defaults and local dependency overrides.

Included work:

• define the supported local override mechanism
• identify which fetched dependencies are covered in v0.3.0
• define what remains local environment setup
• define how override paths are verified where practical
• preserve third-party diagnostic isolation

Acceptance criteria:

• pinned defaults remain the default behaviour
• local overrides require no source edits
• unsupported package managers or local layouts are explicitly out of scope
• the policy names cmocka, SDL, and ESP-IDF setup expectations

Dependencies: PBI-064

PBI-070 Add the cmocka local override path [+]

Epic: E19 Dependency and local override policy

Outcome: The cmocka dependency can use a documented local override path where practical while keeping the pinned default path intact.

Included work:

• update dependency configuration for cmocka
• document the local override variable or setting
• add or update verification for the default path
• add or document local override verification where practical

Acceptance criteria:

• a normal clean configure still uses the pinned default dependency path
• the local override path is documented
• third-party headers remain outside project diagnostics
• no Core dependency boundary changes are introduced

Dependencies: PBI-069

PBI-071 Add the SDL local override path [+]

Epic: E19 Dependency and local override policy

Outcome: The SDL dependency can use a documented local override path where practical while remaining isolated to the SDL frontend.

Included work:

• update SDL dependency configuration
• document the local override variable or setting
• verify the default pinned SDL path still works
• verify or document the override path where practical
• keep SDL disabled when the SDL frontend is not selected

Acceptance criteria:

• a normal desktop configure still uses the pinned SDL default
• the local override path is documented
• SDL remains a frontend dependency only
• headless builds do not require SDL
• third-party diagnostics remain outside project diagnostics

Dependencies: PBI-069

PBI-072 Resolve dependency limitation LIM-005 [+]

Epic: E19 Dependency and local override policy

Outcome: LIM-005 is closed or narrowed with evidence from the dependency override work.

Included work:

• review the final cmocka and SDL override behaviour
• record what dependency scenarios are now supported
• record what remains unsupported or local environment setup
• update docs/known-limitations.md
• update release evidence expectations if required

Acceptance criteria:

• LIM-005 is closed or rewritten more narrowly
• the limitation status matches implemented evidence
• no unsupported offline rebuild claim is made
• follow-up work is linked if any dependency gap remains

Dependencies: PBI-070, PBI-071

E20 ESP-IDF firmware foundation

PBI-073 Create the reusable firmware app foundation [+]

Epic: E20 ESP-IDF firmware foundation

Outcome: The repository has a reusable embedded firmware app foundation under apps/firmware that is intended to grow into later hardware runtime work.

Included work:

• create apps/firmware source ownership
• add the minimum firmware app entry required by the selected ESP-IDF build shape
• initialise, update, and snapshot one Core world through public APIs
• avoid display output, button input, persistence, sensors, and networking
• document that the app is a foundation, not a disposable probe

Acceptance criteria:

• firmware app code uses public Core headers only
• the app owns no board pin definitions or display drawing rules
• the app can be built through the selected firmware build path after its dependencies land
• no runtime hardware capability is claimed

Dependencies: PBI-064

PBI-074 Record the T-Display family and S3 variant contract [+]

Epic: E20 ESP-IDF firmware foundation

Outcome: The T-Display family has a stable selectable board boundary, with S3 facts isolated in the only implemented variant outside the Core, firmware app lifecycle, and generic TFT frontend direction.

Included work:

• create the boards/t_display family contract and variants/s3 implementation
• select the variant through build configuration and reject undeclared variants
• map the selected variant to its ESP-IDF target
• record display controller family and display geometry
• record GPIO pins for display bus, reset, backlight, and buttons where confirmed
• record which values still need hardware verification
• keep board configuration free of product rules

Acceptance criteria:

• the stable board contract is owned by boards/t_display
• S3-specific facts are owned by boards/t_display/variants/s3
• only implemented variants are selectable
• Core code includes no board configuration headers
• TFT frontend direction does not own T-Display S3 pin choices
• unverified board values are labelled as such

Dependencies: PBI-073

PBI-075 Add ESP-IDF platform build integration [+]

Epic: E20 ESP-IDF firmware foundation

Outcome: The firmware foundation configures, builds, and links through ESP-IDF on the selected development host.

Included work:

• add platforms/esp_idf build glue
• select a declared T-Display variant and derive its ESP-IDF target
• record the selected target and toolchain expectation
• adapt project sources into the ESP-IDF build without copying ownership
• link the firmware app foundation with Pet Core
• document the exact build command

Acceptance criteria:

• ESP-IDF configure and build commands are documented
• the firmware app links successfully when the required tools are available
• the selected board variant and ESP-IDF target cannot silently disagree
• Pet Core does not include ESP-IDF headers
• SDK diagnostics are not treated as project diagnostics where practical
• desktop and headless builds remain unaffected

Dependencies: PBI-073, PBI-074

PBI-076 Resolve embedded limitation LIM-012 [+]

Epic: E20 ESP-IDF firmware foundation

Outcome: LIM-012 is closed or narrowed according to the ESP-IDF build evidence.

Included work:

• run or record the ESP-IDF build evidence
• record the exact target, toolchain, command, and result
• update the support matrix in the architecture or release evidence
• update docs/known-limitations.md
• link any remaining embedded runtime gap to future PBIs

Acceptance criteria:

• the embedded claim is no broader than executed evidence
• build-tested or cross-compile-tested status is recorded only if it was executed
• no display, button, persistence, sensor, or networking runtime support is claimed
• LIM-012 is closed or rewritten more narrowly

Dependencies: PBI-065, PBI-075

E21 Embedded-safe component and verification boundaries

PBI-077 Define the embedded component selection [+]

Epic: E21 Embedded-safe component and verification boundaries

Outcome: The release explicitly names which frontend-neutral components are required in the ESP-IDF build evidence and which are deferred.

Included work:

• review components/presentation, components/layout, components/manifest, and components/assets
• decide which components enter the ESP-IDF build proof
• record exclusions with reasons
• link the decision to architecture sections

Acceptance criteria:

• selected components are listed with rationale
• excluded components have a recorded reason
• runtime text manifest parsing and PNG decoding are not introduced as embedded requirements
• the decision is visible before component build work begins

Dependencies: PBI-075

PBI-078 Isolate the asset reader and stdio boundary [+]

Epic: E21 Embedded-safe component and verification boundaries

Outcome: components/assets can be evaluated or built for embedded use without forcing the desktop stdio reader into embedded builds.

Included work:

• review the asset reader contract and reader_stdio.c
• separate desktop stdio selection from reader-neutral asset logic where required
• update CMake or component source ownership so embedded builds can exclude stdio code
• preserve desktop runtime asset tests
• document any remaining asset limitation

Acceptance criteria:

• embedded builds do not require reader_stdio.c unless explicitly selected
• desktop asset loading behaviour remains covered
• the reader contract remains testable with memory fixtures
• no embedded filesystem requirement is introduced

Dependencies: PBI-077

PBI-079 Add embedded dependency boundary verification [+]

Epic: E21 Embedded-safe component and verification boundaries

Outcome: The project can detect forbidden embedded dependencies entering Pet Core or selected frontend-neutral components.

Included work:

• extend or configure boundary verification for ESP-IDF, board, TFT, filesystem, and network boundaries
• verify Core compile lines and includes where practical
• verify selected component boundaries where practical
• record unavailable checks explicitly

Acceptance criteria:

• Core boundary verification rejects ESP-IDF, board, display, SDL, filesystem, and network dependencies where the check can observe them
• selected component checks match the architecture boundary
• unavailable checks are recorded rather than counted as passing
• the check integrates with the appropriate gate or release verification path

Dependencies: PBI-077

PBI-080 Resolve allocation probe coverage limitation LIM-003 [+]

Epic: E21 Embedded-safe component and verification boundaries

Outcome: The runtime allocation probe cannot silently omit a public Core operation.

Included work:

• compare public Core operations against the allocation probe coverage
• add a manifest, allowlist, or automated check that fails when public operations are missing
• update the allocation probe if required
• update docs/known-limitations.md

Acceptance criteria:

• a newly added public Core operation cannot be omitted silently from allocation verification
• existing public Core operations are covered or explicitly excluded with a reason
• LIM-003 is closed or rewritten more narrowly
• audit gate expectations are updated if required

Dependencies: PBI-079

E22 TFT presentation behaviour cleanup

PBI-081 Decide the attentive and happy presentation rule [+]

Epic: E22 TFT presentation behaviour cleanup

Outcome: The intended product rule for greet, attentive activity, and happy expression is documented before behaviour changes.

Included work:

• review Core dwell times for attentive and happy states
• review presentation role priority
• decide whether attentive should become visible during a greet sequence
• record the selected rule in architecture or limitation notes
• identify the smallest implementation area for the fix

Acceptance criteria:

• the selected product rule is documented
• the decision names whether Core dwell times, presentation priority, or both should change
• the decision keeps renderer code insulated from direct Core enum handling
• the decision does not introduce new activity, mood, trait, or maturity systems

Dependencies: PBI-064

PBI-082 Implement the attentive presentation fix and resolve LIM-010 [+]

Epic: E22 TFT presentation behaviour cleanup

Outcome: The attentive activity is visible when the selected product rule says it should be, or the limitation is narrowed to the documented rule.

Included work:

• implement the selected Core or presentation-component change
• update tests for greet, happy expression, and attentive activity
• update presentation role tests where required
• update docs/known-limitations.md
• verify desktop SDL presentation still falls back calmly for unknown states

Acceptance criteria:

• tests prove the selected attentive and happy behaviour
• renderer code remains insulated from direct Core enum handling
• no broad animation or art-direction redesign is introduced
• LIM-010 is closed or rewritten more narrowly

Dependencies: PBI-081

E23 Release verification and hardening

PBI-083 Add v0.3.0 release verification evidence

Epic: E23 Release verification and hardening

Outcome: The release has repeatable evidence for hosted gates, ESP-IDF build proof, dependency policy, boundary checks, selected limitation resolutions, and support claims.

Included work:

• run or define the required release gate for hosted compositions
• run or record ESP-IDF build proof
• record project command entrypoint verification
• record dependency override evidence
• record Core and component boundary evidence
• record allocation probe coverage evidence
• record presentation behaviour evidence

Acceptance criteria:

• evidence names commands, targets, toolchains, and results
• support claims match executed evidence
• unavailable checks are recorded rather than counted as passing
• no excluded runtime capability is claimed

Dependencies: PBI-068, PBI-072, PBI-076, PBI-080, PBI-082

PBI-084 Complete the v0.3.0 release review

Epic: E23 Release verification and hardening

Outcome: v0.3.0 is ready to close with consistent release documents, support claims, limitation status, progress records, and evidence.

Included work:

• confirm all required PBIs are complete
• confirm milestone exit criteria for v0.3.0
• update release evidence
• update progress, bugs, known limitations, and last development
• prepare the release archive if the release process requires it
• record any remaining limitations with explicit follow-up PBIs

Acceptance criteria:

• all required v0.3.0 PBIs are complete
• release evidence is complete and linked
• LIM-012, LIM-005, LIM-003, and LIM-010 are closed, narrowed, or linked to follow-up PBIs
• no support claim is broader than the evidence
• release rollover work is complete according to the release process

Dependencies: PBI-083

7. Deferred backlog areas

The following areas remain outside the active PBI set:

• durable saves
• digital adapters such as Git activity
• physical sensor adapters
• networking and local device discovery
• multiple pets and household relationships
• long-term traits, marks, memories, and maturity
• embedded display runtime and hardware validation beyond the v0.3.0 ESP-IDF build proof
• a Core allocator or arena without evidence from a later version requirement
• Windows build verification without a Windows environment or runner

These areas must be introduced through a version architecture document and its PBIs rather than being added opportunistically to the current release.

A visual frontend was deferred throughout v0.1.0 and is the subject of v0.2.0, so it is no longer listed here. The list as it stood at the close of v0.1.0 is preserved in release v0.1.0.