cold_display_guard/docs/plans/2026-04-27-cold-display-guard.md

Cold Display Guard Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Build a standalone Python project for refrigerated display food-batch timing and 3-hour disposal compliance alerts.

Architecture: Keep camera and model logic outside the first business core. Implement a pure Python batch engine that consumes timestamped zone occupancy and trash-bin events, emits JSON-compatible compliance events, and can later be driven by a video adapter.

Tech Stack: Python 3.11+ standard library, TOML config via tomllib, tests via unittest.

---

Task 1: Project Skeleton

Files:

• Create: pyproject.toml
• Create: src/cold_display_guard/__init__.py
• Create: README_zh.md
• Create: config/example.toml

Steps:

1. Create packaging metadata with a console script named cold-display-guard.
2. Create a Chinese README documenting the confirmed business rules.
3. Create default TOML config for camera id, thresholds, 4x2 zones, and trash ROI placeholder.
4. Verify imports with python3 -m unittest discover -s tests.

Task 2: Batch Engine

Files:

• Create: src/cold_display_guard/models.py
• Create: src/cold_display_guard/engine.py
• Test: tests/test_engine.py

Steps:

1. Write tests for batch start, normal consumption, over-threshold pending disposal, trash confirmation, mixed-batch violation, overdue return violation, and missing disposal violation.
2. Implement dataclasses for observations, batches, zones, and events.
3. Implement BatchEngine.process().
4. Run python3 -m unittest tests.test_engine -v.

Task 3: Config and CLI

Files:

• Create: src/cold_display_guard/config.py
• Create: src/cold_display_guard/cli.py
• Test: tests/test_config.py

Steps:

1. Load TOML config into an engine settings dataclass.
2. Add CLI support for processing a JSONL observation file.
3. Write emitted events to stdout as JSONL.
4. Run python3 -m unittest discover -s tests -v.

Task 4: Git

Steps:

1. Initialize git in ~/Code/cold_display_guard.
2. Review git status --short.
3. Commit the initial project.