prometeu-runtime/discussion/workflow/plans/PLN-0160-add-dummy-boy-visual-switch-test-cartridge.md

id	ticket	title	status	created	ref_decisions	tags
PLN-0160	system-os-cartridge-switch-orchestrator	Add Dummy Boy Visual Switch Test Cartridge	done	2026-07-05	DEC-0039	runtime os lifecycle game cartridge architecture

Briefing

DEC-0039 requires minimum evidence using two distinct test cartridges. The existing stress cartridge proves execution/logging but is not visually distinct enough for switch validation. A second cartridge, dummy-boy, must render an oscillating-color square.

Objective

Add a simple test-cartridges/dummy-boy cartridge that renders a visible square with changing colors so Game switching can prove visual/session identity.

Dependencies

• Source decision: DEC-0039.
• Can be implemented independently of PLN-0157 through PLN-0159.
• Required before PLN-0161 end-to-end validation.

Scope

• Add test-cartridges/dummy-boy/manifest.json.
• Generate or add test-cartridges/dummy-boy/program.pbx.
• Add empty or minimal assets payload if the loader requires assets.pa.
• Implement Dummy Boy behavior:
  • Game cartridge identity distinct from stress;
  • deterministic visible square;
  • color oscillates across frames;
  • no dependency on final launcher UX.
• Add build/generation documentation or tests so the cartridge can be regenerated safely if needed.

Non-Goals

• Do not add final game content.
• Do not add .pmc.
• Do not depend on host screenshots for the first validation unless an existing harness already supports it.
• Do not change stress cartridge behavior.

Execution Method

1. Inspect the stress cartridge and any PBX generator tooling:
   • test-cartridges/stress-console;
   • crates/tools/pbxgen-stress;
   • bytecode assembler helpers in crates/console/prometeu-bytecode.
2. Choose the smallest maintainable generator path:
   • extend existing PBX generator if appropriate; or
   • add a focused pbxgen-dummy-boy tool; or
   • add deterministic generated PBX with source instructions.
3. Create manifest.json with unique app_id, title Dummy Boy, Game mode, and version.
4. Generate program.pbx that renders the square and advances color over frames.
5. Add tests or smoke checks that the cartridge is discoverable by games-root discovery.

Acceptance Criteria

• test-cartridges/dummy-boy exists and loads as a Game cartridge.
• Dummy Boy has a unique app_id and title distinct from Stress.
• Dummy Boy renders a visible square.
• Square color changes deterministically over time.
• Games-root discovery sees both Stress and Dummy Boy.
• Existing stress cartridge remains unchanged.

Tests

• cargo test -p prometeu-hal
• cargo test -p prometeu-system
• cargo test -p prometeu-firmware
• Run any cartridge generator tests added by this plan.
• Add or update tests for games-root discovery including Dummy Boy.

Affected Artifacts

• test-cartridges/dummy-boy/manifest.json
• test-cartridges/dummy-boy/program.pbx
• test-cartridges/dummy-boy/assets.pa if required
• crates/tools/* cartridge generator tooling if needed
• crates/console/prometeu-system/src/services/game_library.rs tests if needed