Product Backlog Items

Document version	Date	Summary
v1	2026-07-17	Initial V0 product backlog
v2	2026-07-18	Define deterministic memory and platform-specific quality gates
v3	2026-07-18	Add automated Core boundary, header, and allocation verification
v4	2026-07-19	Prepare semantic interaction PBIs for explicit transition tables
v5	2026-07-19	Record quality checks as gate and script delivery rather than CMake targets

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|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. E01 Build and portability baseline

PBI-001 Establish the repository source layout [+]

Epic: E01 Build and portability baseline

Outcome: The repository has explicit ownership boundaries for Pet Core, the headless host, tests, and build support files.

Included work:

• create the root source layout
• reserve public headers under include/pet
• place Pet Core implementation under src
• place the host executable under apps/headless
• place tests and test support under tests
• reserve reusable CMake modules under cmake

Acceptance criteria:

• every planned v0.1.0 source file has one architectural owner
• Pet Core does not depend on files beneath apps or tests
• paths use portable naming and do not rely on case-insensitive filesystems
• no platform-specific source directory is presented as supported
• the layout agrees with the architecture for v0.1.0

Dependencies: None

PBI-002 Establish the root CMake project [+]

Epic: E01 Build and portability baseline

Outcome: A clean checkout can be configured without Makefiles maintained by hand.

Included work:

• require CMake 3.25 or later
• declare a C language project
• add target-based project options
• keep compiler flags and dependencies scoped to their owning targets
• keep generated content outside source directories

Acceptance criteria:

• configuration succeeds with Ninja using GCC and Clang
• no global CFLAGS contract is required
• no compiler executable path or version suffix is hard-coded
• paths and CMake commands are valid for future Windows generator use
• an empty build directory is sufficient for a clean rebuild

Dependencies: PBI-001

PBI-003 Establish the portable C99 Pet Core target [+]

Epic: E01 Build and portability baseline

Outcome: Pet Core exists as a standalone static library with an explicit portable language contract.

Included work:

• create the pet_core static library
• create the pet::core alias
• expose only intended public include paths
• require ISO C99
• disable compiler-specific C language extensions
• establish that Pet Core has no dynamic allocator dependency

Acceptance criteria:

• Pet Core builds without the headless host and tests
• C_STANDARD is 99 and required
• C_EXTENSIONS is disabled
• public headers compile as C and are guarded against repeated inclusion
• Pet Core has no operating system, frontend, storage, sensor, networking, or test dependency
• Pet Core does not link to or call malloc, calloc, realloc, or free
• the target structure can be consumed by a future Windows CMake build

Dependencies: PBI-002

PBI-004 Establish shared CMake presets [+]

Epic: E01 Build and portability baseline

Outcome: Developers use named and repeatable configure, build, and test commands.

Included work:

• add CMakePresets.json
• add Linux GCC and Linux Clang debug presets using Ninja
• add matching build and test presets
• reserve CMakeUserPresets.json for local overrides
• configure compilation database generation where supported

Acceptance criteria:

• preset names describe platform, compiler, and purpose
• GCC and Clang presets use unversioned executable names
• project presets contain no developer-specific absolute paths
• CMakeUserPresets.json is not required for a normal build
• compilation commands are available for analysis tooling
• the preset structure can accept a Windows preset without changing Pet Core

Dependencies: PBI-002, PBI-003

PBI-005 Establish formatting configuration and targets [+]

Epic: E01 Build and portability baseline

Outcome: C formatting is deterministic and can be checked without modifying files.

Included work:

• add .clang-format using the baseline in this document
• provide an explicit formatting check and a formatting rewrite
• include project C sources and headers
• exclude build outputs and dependencies

Acceptance criteria:

• clang-format is invoked without a version suffix
• the check fails when a project C source or header is not formatted
• the rewrite modifies only project-owned C sources and headers
• generated and third-party files are excluded
• all existing project C sources and headers pass the check

Delivered by tools/verify/format.py, with --fix for the rewrite, under the tooling boundary in code rules.

Dependencies: PBI-001, PBI-002

PBI-006 Establish compiler warning policies [+]

Epic: E01 Build and portability baseline

Outcome: Project code is compiled with a strict C warning baseline without imposing project warnings on dependencies or consumers.

Included work:

• create a reusable project warning interface target
• configure supported GCC and Clang warnings
• add an option for warnings as errors
• provide a separate MSVC warning mapping for the Windows preset

Acceptance criteria:

• the agreed warning set is enabled for project targets
• warnings are errors in strict presets
• third-party targets do not inherit project warning flags
• public consumers do not inherit private warning policy
• compiler-specific flags are guarded by compiler identity
• project sources build without warnings using GCC and Clang
• the MSVC mapping does not weaken the GCC and Clang C99 gate

Dependencies: PBI-003, PBI-004

PBI-007 Establish CTest and CMocka infrastructure [+]

Epic: E01 Build and portability baseline

Outcome: Pet Core behaviour can be verified through isolated host-side C tests.

Included work:

• enable CTest through a project option
• integrate a pinned CMocka dependency for host tests
• add the first smoke test target
• keep CMocka private to tests
• support normal console test output
• avoid GNU linker wrapping and other platform-specific mocking mechanisms

Acceptance criteria:

• tests can be disabled without affecting Pet Core
• Pet Core public headers contain no CMocka dependency
• CMocka headers and sources are treated as external code
• the smoke test is discovered and run by CTest
• GCC and Clang both build and run the test suite
• test code avoids unnecessary POSIX dependencies so it can later run on Windows
• test seams use explicit inputs or interfaces rather than --wrap linker behaviour

Dependencies: PBI-003, PBI-004, PBI-006

PBI-008 Establish fast static analysis [+]

Epic: E01 Build and portability baseline

Outcome: Common C defects and portability problems are detected during every PBI quality gate.

Included work:

• add a Cppcheck analysis check
• enable warning, style, performance, and portability analysis
• analyse project code using the C99 model
• fail the check when findings violate the configured policy

Acceptance criteria:

• cppcheck is invoked without a version suffix
• only project-owned code is selected for analysis
• dependencies, generated content, and build directories are excluded
• the check is part of the strict quality gate
• the current project passes the configured analysis

Delivered by tools/verify/cppcheck.py under the tooling boundary in code rules.

Dependencies: PBI-003, PBI-006

PBI-009 Establish parallel deep static analysis [+]

Epic: E01 Build and portability baseline

Outcome: Clang-Tidy performs deeper analysis without slowing every normal compilation.

Included work:

• add .clang-tidy using the baseline in this document
• add an explicit deep analysis check
• use run-clang-tidy with the compilation database
• allow parallel execution based on available processors
• restrict findings to project code
• keep Visual Studio generator builds independent from compilation database analysis

Acceptance criteria:

• normal builds do not run Clang-Tidy implicitly
• clang-tidy and run-clang-tidy are invoked without version suffixes
• analysis runs in parallel when more than one worker is available
• only project translation units are selected
• project headers are checked
• system headers, generated files, fetched dependencies, and third-party files are excluded from project diagnostics
• findings are treated as errors
• the check is part of the strict quality gate
• a future Windows deep analysis preset uses Clang with Ninja rather than requiring the Visual Studio generator to emit compile_commands.json

Delivered by tools/verify/tidy.py, which takes the build directory holding the compilation database, under the tooling boundary in code rules.

Dependencies: PBI-004, PBI-006, PBI-007

PBI-010 Establish AddressSanitizer and UndefinedBehaviourSanitizer presets [+]

Epic: E01 Build and portability baseline

Outcome: Memory safety and undefined behaviour defects are detected after every implementation PBI.

Included work:

• add dedicated ASan and UBSan configure presets
• retain frame pointers and debug information
• run the complete test suite under each sanitizer
• keep sanitizer flags private to supported host targets

Acceptance criteria:

• ASan and UBSan use independent build directories
• both configurations build and run through CTest
• UBSan stops on the first reported undefined behaviour
• sanitizer settings do not affect ordinary or future embedded builds
• unsupported compiler and platform combinations fail clearly or remain disabled
• both sanitizer runs are part of the strict quality gate
• Windows UBSan belongs to an optional Clang preset rather than the MSVC build contract
• Windows ASan is enabled only after its selected MSVC or Clang configuration is verified

Dependencies: PBI-004, PBI-007

PBI-011 Establish coverage and Valgrind audit checks [+]

Epic: E01 Build and portability baseline

Outcome: Release audits can inspect exercised branches and host-side memory behaviour.

Included work:

• add a GCC coverage configuration
• generate HTML and XML coverage reports with Gcovr
• add a Valgrind check with leak and origin tracking
• store generated reports beneath _reports

Acceptance criteria:

• coverage measures project source rather than test or dependency code
• branch coverage is reported
• Valgrind fails on detected memory errors and definite leaks
• report and build outputs remain outside tracked source files
• the checks are part of the audit gate rather than the ordinary strict gate
• Valgrind and the initial coverage workflow are documented as Linux audit tools

The GCC coverage configuration stays in CMake as pet::coverage, because instrumentation flags are build graph. Report generation is tools/verify/coverage.py and the memory check is tools/verify/alloc.py, under the tooling boundary in code rules.

Dependencies: PBI-007

PBI-012 Establish repeatable quality workflows [+]

Epic: E01 Build and portability baseline

Outcome: Developers and agents can run the required gates through documented, repeatable commands.

Included work:

• expose fast, strict, and audit workflows through a single documented command each
• document prerequisites and commands
• keep orchestration independent from GNU Make
• report unavailable optional tools clearly
• distinguish the canonical Linux gate from native and optional Windows gates

Acceptance criteria:

• the fast workflow runs the formatting check, one host build, tests, and Cppcheck
• the strict workflow covers every check in section 3.1
• the audit workflow covers every check in section 3.2
• strict is the required completion gate for every implementation PBI
• the commands contain no local absolute paths or version-suffixed tool names
• core build and test commands remain usable by future Windows developers
• the native Windows gate contains formatting, MSVC warnings, build, tests, and Cppcheck
• the optional Windows Clang gate contains parallel Clang-Tidy and supported sanitisers
• Valgrind is not required on Windows

Delivered by the root gate.py, which sequences CMake presets and the checks under tools/verify. Each gate contains the one before it. See the tooling boundary in code rules.

Dependencies: PBI-005 through PBI-011

PBI-013 Provide an unverified Windows developer configuration [+]

Epic: E01 Build and portability baseline

Outcome: Windows developers have a defined starting configuration without claiming unperformed verification.

Included work:

• add or document a Visual Studio MSVC CMake preset
• compile the C99 codebase using MSVC C17 mode
• reserve a Clang and Ninja preset for optional Windows analysis and sanitisers
• map the required project warning policy where supported
• avoid POSIX-only commands in ordinary build and test paths
• record the current verification status

Acceptance criteria:

• the Windows configuration does not affect Linux presets
• source and test paths do not assume POSIX separators or shell syntax
• Pet Core code contains no Linux-specific APIs
• MSVC is the native Windows compatibility compiler
• the C99 language contract continues to be enforced by GCC and Clang
• the support matrix marks Windows as designed but unverified
• Windows is promoted to build tested only after evidence from a Windows environment or runner

Dependencies: PBI-004, PBI-006, PBI-007

6. E02 World and pet lifecycle

PBI-014 Define the initial domain types and deterministic memory model [+]

Epic: E02 World and pet lifecycle

Outcome: The first public C contracts represent one world and one pet using fixed-capacity, caller-owned storage with no Core heap dependency.

Included work:

• define fixed-width public value types where required
• define world construction and initialisation contracts
• establish pet_ function, Pet type, and PET_ constant naming
• document ownership and valid lifetime rules
• define compile-time capacities for every bounded collection
• select a caller-owned world representation that does not return mutable nested state pointers
• document maximum persistent and temporary Core storage

Acceptance criteria:

• public types contain no frontend or platform type
• ownership is unambiguous
• invalid null and range inputs have defined behaviour
• public operations do not expose mutable pointers into nested world state
• every collection has a compile-time maximum
• Pet Core has no allocator, arena, heap-owned world, or hidden mutable storage
• the representation permits more than one independently owned world
• public headers compile cleanly with GCC and Clang as C99

Dependencies: PBI-003, PBI-007

PBI-015 Initialise a deterministic world [+]

Epic: E02 World and pet lifecycle

Outcome: The same valid initialisation input always creates the same valid initial world.

Included work:

• implement world initialisation
• establish initial pet state
• reject invalid initialisation without partial mutation
• validate all configuration and derive reusable bounded values during initialisation
• initialise every fixed-capacity collection and lifecycle marker
• add boundary and invariant tests

Acceptance criteria:

• equivalent inputs produce equivalent worlds
• no platform clock or global random source is read
• invalid input leaves the destination in a documented safe state
• all initial world invariants are tested
• initialisation performs bounded work using only caller-owned, inline, and bounded stack storage
• initialisation performs no dynamic allocation
• configuration-dependent preparation is not deferred to the first runtime update

Dependencies: PBI-014

PBI-016 Define world validity and lifecycle rules [+]

Epic: E02 World and pet lifecycle

Outcome: Valid and invalid lifecycle transitions are explicit and testable.

Included work:

• define world validity checks
• define reset and end-of-lifetime behaviour
• document value ownership and copying restrictions
• test repeated and invalid lifecycle operations

Acceptance criteria:

• lifecycle operations cannot create a partially valid world
• repeated reset behaviour is defined
• lifecycle completion does not need to free Core memory or release a platform resource
• no hidden allocation, arena, allocator, or platform resource is introduced
• tests cover valid and invalid operation order

Dependencies: PBI-015

7. E03 Deterministic behaviour loop

PBI-017 Define explicit simulation time [+]

Epic: E03 Deterministic behaviour loop

Outcome: Pet Core advances only from caller-provided time values.

Included work:

• define the simulation time representation
• define accepted delta bounds
• define invalid, zero, and large delta behaviour
• add deterministic time tests

Acceptance criteria:

• Pet Core never reads a platform clock
• equal world and time inputs produce equal results
• invalid time cannot partially mutate the world
• overflow and range boundaries are tested
• time processing performs bounded work
• time processing performs no allocation, deallocation, or deferred initialisation

Dependencies: PBI-015

PBI-018 Implement the first autonomous state transition [+]

Epic: E03 Deterministic behaviour loop

Outcome: A pet can change state over time without requiring user attention.

Included work:

• implement one minimal autonomous behaviour
• keep behaviour calm and non-punitive
• define the transition as a pure domain rule where practical
• add table-driven transition tests

Acceptance criteria:

• the transition depends only on explicit world and time input
• inactivity cannot kill, injure, or permanently punish the pet
• transition boundaries are deterministic and tested
• repeated updates preserve world validity
• the transition mutates only caller-owned fixed-capacity state
• the transition performs no allocation or deferred setup

Dependencies: PBI-017

PBI-019 Define deterministic random input [+]

Epic: E03 Deterministic behaviour loop

Outcome: Behaviour may use variation without depending on a hidden global random generator.

Included work:

• define a minimal random value input contract
• establish valid ranges and consumption rules
• support deterministic test doubles
• defer any platform random implementation to the host

Acceptance criteria:

• Pet Core does not call rand or a platform entropy API
• supplied random values produce repeatable outcomes
• invalid random input has defined safe behaviour
• tests can force every relevant branch
• random input handling performs no allocation

Dependencies: PBI-017

PBI-020 Verify update determinism and bounded work [+]

Epic: E03 Deterministic behaviour loop

Outcome: The first update loop has evidence for reproducibility and constrained execution.

Included work:

• add sequence and replay-style tests
• test long but bounded update sequences
• inspect memory and work bounds
• document current limits

Acceptance criteria:

• identical input sequences produce equivalent final worlds
• update order is stable and documented
• no update performs unbounded iteration, allocation, deallocation, resizing, or lazy setup
• maximum loop counts and temporary storage are derivable from declared capacities
• sanitizer and Valgrind audit checks pass
• discovered limits are recorded with a backlog reference

Dependencies: PBI-018, PBI-019

8. E04 Semantic interaction

PBI-021 Define the semantic action contract [+]

Epic: E04 Semantic interaction

Outcome: Pet Core receives product actions rather than keys, buttons, gestures, or device events.

Included work:

• define the initial PetAction representation
• define dispatch results and invalid action behaviour
• define semantic actions as transition triggers rather than platform commands
• decide the internal transition table shape for activity and expression state
• define where static transition tables live and how new transitions are reviewed
• record that activity is no longer derived only from total elapsed world time
• reserve extension rules without speculative adapter categories
• test action validation

Acceptance criteria:

• actions contain no SDL, keyboard, touch, Bluetooth, Git, or sensor type
• unknown and invalid actions cannot corrupt the world
• action processing has a defined deterministic result
• the contract remains suitable for future digital and physical adapters
• action validation and dispatch perform no allocation
• the selected action model can be represented on limited input hardware
• activity, expression, and later pet state changes can share the same trigger, guard, and effect vocabulary
• a private Core transition table header is planned or introduced with a note that behaviour changes must update the table
• no public transition table ABI is exposed to frontends, adapters, or hosts

Dependencies: PBI-015

PBI-022 Implement the first pet interaction [+]

Epic: E04 Semantic interaction

Outcome: One semantic action causes a visible domain state change without adding a frontend.

Included work:

• implement one calm initial interaction
• implement the first static transition table for supported pet state
• keep transition rows in a private Core header or source file that is easy to review
• add the minimum state needed for action and time transitions to compose
• update only domain-owned state
• define interaction timing and repeat behaviour
• define no-op behaviour for valid actions that do not change the current state
• add table-driven tests

Acceptance criteria:

• the interaction is invoked through PetAction
• no raw input mapping enters Pet Core
• repeated and invalid actions preserve world validity
• the interaction does not create a punishment loop
• behaviour is deterministic under controlled inputs
• the interaction uses only fixed-capacity caller-owned state
• the first interaction is expressed through the internal transition table rather than a one-off action switch
• table guards and effects are represented by Core-owned identifiers or functions with bounded work
• adding a new transition requires adding or reviewing an explicit row in the transition table
• the implementation avoids a single combined enum for activity, expression, mood, relationship, and future state

Dependencies: PBI-021

PBI-023 Verify action and update composition [+]

Epic: E04 Semantic interaction

Outcome: The order and interaction of time updates and semantic actions are explicit.

Included work:

• define host call ordering
• test action-before-update and update-before-action cases where relevant
• test invalid actions between valid updates
• test table-driven transitions across at least one time trigger and one action trigger
• test accepted no-op transitions where the selected action is valid for the contract but does not change the current state
• inspect the transition table for bounded maximum row scans
• document ordering invariants

Acceptance criteria:

• runtime ordering is unambiguous
• equivalent ordered input sequences remain deterministic
• failure of one action does not corrupt later updates
• no hidden event queue is introduced without an explicit contract
• transition table evaluation order is documented and covered by tests
• the maximum number of inspected transition rows is derivable from a compile-time table size
• adding expression, mood, relationship, memories, traits, or adapter events later does not require changing the public action dispatch shape
• rejected input cannot leave timers, activity, expression, or transition side effects partially applied

Dependencies: PBI-018, PBI-022

9. E05 Read-only presentation snapshot

PBI-024 Define the v0.1.0 snapshot contract [+]

Epic: E05 Read only presentation snapshot

Outcome: Hosts can observe presentable pet state without reading internal world storage.

Included work:

• define PetSnapshot
• select the minimal state required by the headless demonstration
• define snapshot compatibility and validity rules
• keep the structure frontend neutral

Acceptance criteria:

• snapshot fields contain domain values rather than rendering resources
• callers cannot mutate the world through a snapshot
• the snapshot contains no pointer into mutable internal state
• no SDL, terminal, display, colour, sprite, or hardware type is exposed
• the contract can support a future visual frontend without changing world ownership

Dependencies: PBI-015, PBI-018, PBI-022

PBI-025 Implement deterministic snapshot extraction [+]

Epic: E05 Read only presentation snapshot

Outcome: Equivalent worlds produce equivalent complete snapshots.

Included work:

• implement snapshot extraction
• validate source and destination inputs
• prevent partial output on failure
• add field and boundary tests

Acceptance criteria:

• snapshot extraction does not mutate the world
• every output field is initialised
• invalid input produces a documented safe result
• equivalent worlds produce equivalent snapshots
• extraction performs bounded work and no allocation

Dependencies: PBI-024

PBI-026 Verify snapshot isolation [+]

Epic: E05 Read only presentation snapshot

Outcome: Presentation consumers remain unable to bypass Pet Core rules.

Included work:

• add mutation isolation tests
• verify lifetime independence
• verify snapshots before and after actions and updates
• document snapshot ownership

Acceptance criteria:

• modifying a snapshot cannot modify its source world
• a snapshot remains valid for its documented lifetime
• action and update effects appear only after a new extraction
• internal fields not in the public contract remain inaccessible

Dependencies: PBI-025

10. E06 Headless architecture demonstration

PBI-027 Implement the minimal headless host [+]

Epic: E06 Headless architecture demonstration

Outcome: A small host demonstrates initialisation, explicit time, semantic action dispatch, update, and snapshot extraction without a visual frontend.

Included work:

• create the pet_headless executable
• keep platform clock and input ownership in the host
• print a minimal human-readable demonstration
• avoid becoming a second source of product rules

Acceptance criteria:

• the host links against pet::core
• Pet Core remains independently buildable
• the host demonstrates the documented runtime ordering
• all displayed state comes from PetSnapshot
• the host contains no duplicated domain transition rules
• ordinary host code avoids unnecessary POSIX-only APIs for future Windows compatibility

Dependencies: PBI-023, PBI-026

PBI-028 Add a deterministic headless scenario [+]

Epic: E06 Headless architecture demonstration

Outcome: Maintainers can run one stable scenario as architecture evidence.

Included work:

• define a fixed input sequence
• produce a stable final snapshot or output
• add an automated scenario test
• document how to run the demonstration

Acceptance criteria:

• repeated runs produce equivalent results
• the scenario exercises initialisation, update, action, and snapshot boundaries
• the scenario requires no network, display, filesystem persistence, or sensor
• automated verification does not depend on terminal escape behaviour

Dependencies: PBI-027

11. E07 Release verification and hardening

PBI-029 Audit public API failure behaviour [+]

Epic: E07 Release verification and hardening

Outcome: Every v0.1.0 public operation has defined and tested failure semantics.

Included work:

• enumerate public operations and invalid inputs
• verify no partial world corruption
• verify output initialisation rules
• improve missing boundary tests

Acceptance criteria:

• every public function has failure coverage
• null, invalid enum, range, and lifecycle cases are covered where applicable
• failure cannot leave a partially updated active world
• error behaviour does not rely on platform-specific process termination
• the audit quality gate passes

Dependencies: PBI-020, PBI-023, PBI-026, PBI-028

PBI-030 Automate Pet Core boundary verification [+]

Epic: E07 Release verification and hardening

Outcome: A forbidden Core dependency fails a routine quality gate instead of surviving until release verification.

Included work:

• add a verification step that reads the undefined symbols of the built Pet Core library
• maintain an explicit allowlist of permitted external symbols
• record a short reason for every allowlist entry
• report the offending symbol names on failure
• run the step in the strict gate
• support the Windows toolchain or record the mechanism as unavailable there

Acceptance criteria:

• the check fails when Pet Core references an allocator, standard input or output, clock, filesystem, thread, or other symbol outside the allowlist
• the allowlist is explicit and every entry has a recorded reason
• a deliberately introduced violation is demonstrated to fail the check
• failure names the offending symbols rather than only reporting a non-zero status
• a new forbidden reference fails the strict gate rather than release verification
• the Windows behaviour is either supported or recorded as unavailable with its reason

Delivered by tools/verify/symbols.py, which takes the built archive and the toolchain that produced it. The allowlist is closed and per toolchain. Linux only, because MSVC dumpbin output is not parsed.

Dependencies: PBI-012, PBI-016

This PBI is not blocked by E03 through E06 and should be pulled forward. Its value comes from running while Core is still growing.

PBI-031 Verify public header self-containment [+]

Epic: E07 Release verification and hardening

Outcome: Every public header compiles on its own, so no caller depends on an accidental include order.

Included work:

• generate one translation unit for each public header that includes only that header
• compile each unit with strict ISO C99, pedantic errors, and warnings as errors
• discover headers automatically rather than through a manual list
• run the step in the strict gate

Acceptance criteria:

• every header under include/pet compiles alone with GCC and Clang
• a header that relies on another header being included first fails the check
• a newly added public header is covered without editing the check
• no public header requires a test framework, platform, or generated header that callers do not have

Delivered by tools/verify/headers.py, which takes the compiler and the source and generated include directories. The check is toolchain neutral and is run for GCC and Clang.

Dependencies: PBI-012, PBI-016

This PBI is not blocked by E03 through E06 and should be pulled forward.

PBI-032 Verify the absence of Core runtime allocation [+]

Epic: E07 Release verification and hardening

Outcome: Pet Core is shown to perform no heap allocation while running, not only to avoid referencing an allocator.

Included work:

• add a minimal verification executable that links Pet Core and nothing else
• exercise the public operations available in the current release scope
• run the executable under Valgrind in the audit gate
• fail when any allocation is reported

Acceptance criteria:

• the executable links Pet Core without the test framework
• Valgrind reports zero allocations for the run
• the check runs in the audit gate
• the exercised operation set is extended when a later PBI adds a public operation
• the result is recorded as release evidence for PBI-033

Dependencies: PBI-011, PBI-016

The symbol scan in PBI-030 shows that Core does not reference an allocator. This PBI shows that Core does not allocate while running. Both statements are needed because neither implies the other.

The probe target is CMake, because compiling and linking an executable is build graph. Running it and parsing the result is tools/verify/alloc.py. The probe observes state through pet_world_snapshot rather than PetWorld fields, so the evidence does not depend on the authoritative layout. Linux only, because Valgrind does not run on Windows.

PBI-033 Verify the v0.1.0 support matrix [+]

Epic: E07 Release verification and hardening

Outcome: Platform and toolchain claims match collected build and test evidence.

Included work:

• perform clean GCC and Clang builds
• run the complete audit quality gate
• record tested tool versions
• review Windows and embedded compatibility claims
• verify the absence of Core dynamic allocation and runtime storage growth
• collect the boundary, header, and allocation evidence produced by PBI-030, PBI-031, and PBI-032

Acceptance criteria:

• Linux GCC is recorded as build and runtime tested
• Linux Clang is recorded as build and runtime tested
• Ninja and CMake versions used for verification are recorded
• Windows remains designed but unverified unless real Windows evidence exists
• embedded targets remain portable by design rather than supported
• the fixed-capacity memory model and declared limits match the implementation
• Pet Core contains no dynamic allocation path, shown by both the symbol scan and the runtime check
• failed or unavailable checks are visible and block release unless explicitly accepted

Dependencies: PBI-012, PBI-013, PBI-029, PBI-030, PBI-031, PBI-032

PBI-034 Complete the v0.1.0 release review [+]

Epic: E07 Release verification and hardening

Outcome: The v0.1.0 milestone exits with evidence that its architectural claim is true.

Included work:

• review all v0.1.0 acceptance criteria
• run the final audit workflow from clean directories
• review known bugs and limitations
• update progress and handover documentation

Acceptance criteria:

• all required v0.1.0 PBIs are complete
• the milestone exit criteria in milestones are satisfied
• Pet Core builds and tests without a frontend, adapter, storage implementation, or network
• Pet Core initialises and runs without an allocator or arena
• the deterministic headless scenario passes
• the final audit quality gate passes
• remaining limitations are explicit and linked to deferred PBIs where appropriate

Dependencies: PBI-033

12. Dependency summary

flowchart TD
    Foundation["E01 Build foundation"] --> Lifecycle["E02 World lifecycle"]
    Lifecycle --> Behaviour["E03 Behaviour loop"]
    Lifecycle --> Interaction["E04 Semantic interaction"]
    Behaviour --> Snapshot["E05 Snapshot"]
    Interaction --> Snapshot
    Snapshot --> Headless["E06 Headless demonstration"]
    Headless --> Release["E07 Release verification"]

The document order is the default implementation order. E03 and E04 may proceed in parallel after their E02 dependencies are complete. A PBI must not begin before its listed dependencies are satisfied unless the maintainer explicitly approves a backlog refinement.

PBI identifiers follow the implementation order after backlog refinement. PBI-030, PBI-031, and PBI-032 produce the boundary, header, and allocation evidence that PBI-033 collects before the final PBI-034 release review.

13. Deferred backlog areas

The following areas are intentionally outside the v0.1.0 PBI set:

• visual frontends
• 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 platform builds
• 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 later version architecture documents and PBIs rather than being added opportunistically to v0.1.0.