cold_display_guard/docs/superpowers/plans/2026-05-29-v1.2-trajectory-recognition.md

# v1.2 Trajectory Recognition Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Add source-zone trajectory evidence so alarmed items moved to the trash are discarded by their actual source zone, while keeping YOLO as a future optional backend.

**Architecture:** Extend `Observation` with backend-neutral `disposal_evidence`, make `BatchEngine` consume matching evidence before generic trash fallback, then add a no-dependency motion trajectory tracker in the vision layer. Runtime writes diagnostics and uses faster sampling only while trajectory candidates are active.

**Tech Stack:** Python 3.11+ standard library, existing `Frame` RGB bytes, `unittest`, Vite/Node tests only if frontend files change.

---

### Task 1: Data Contract And Engine Evidence Handling

**Files:**
- Modify: `src/cold_display_guard/models.py`
- Modify: `src/cold_display_guard/engine.py`
- Test: `tests/test_engine.py`

- [ ] **Step 1: Write failing tests**

Add tests for:
- `Observation.from_dict()` normalizes `disposal_evidence`.
- Matching evidence discards the pending batch for the same source zone.
- Evidence for zone 4 does not discard pending zone 1.
- Same-observation removal plus evidence closes the newly pending batch.
- Low-confidence evidence is ignored.

- [ ] **Step 2: Run RED tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_engine -v`

Expected: FAIL because `Observation` has no `disposal_evidence` and engine ignores evidence.

- [ ] **Step 3: Implement minimal contract and engine logic**

Add a `DisposalEvidence` dataclass and `Observation.disposal_evidence`. In `BatchEngine.process()`, apply evidence to matching `pending_disposal` before generic trash deposits and again after zone transitions for same-frame removals.

- [ ] **Step 4: Run GREEN tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_engine -v`

Expected: PASS.

- [ ] **Step 5: Commit phase**

Run:

```bash
git add src/cold_display_guard/models.py src/cold_display_guard/engine.py tests/test_engine.py
git commit -m "feat: add disposal evidence engine handling"
```

### Task 2: Lightweight Motion Trajectory Backend

**Files:**
- Modify: `src/cold_display_guard/vision.py`
- Test: `tests/test_vision.py`

- [ ] **Step 1: Write failing tests**

Add synthetic RGB-frame tests for:
- Motion from source zone to trash ROI emits evidence.
- Motion that starts away from source zone is rejected.
- Motion that never reaches trash ROI is rejected.
- One-frame reflection flash is rejected.
- Multiple active candidates do not cross-close each other.

- [ ] **Step 2: Run RED tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_vision -v`

Expected: FAIL because no trajectory tracker exists.

- [ ] **Step 3: Implement minimal motion tracker**

Add trajectory settings, candidate state, motion blob extraction from frame deltas, confidence scoring, and diagnostics. Keep the implementation standard-library only.

- [ ] **Step 4: Run GREEN tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_vision -v`

Expected: PASS.

- [ ] **Step 5: Commit phase**

Run:

```bash
git add src/cold_display_guard/vision.py tests/test_vision.py
git commit -m "feat: add lightweight trajectory tracking"
```

### Task 3: Runtime Configuration And Diagnostics Integration

**Files:**
- Modify: `src/cold_display_guard/main.py`
- Modify: `src/cold_display_guard/vision.py`
- Modify: `config/example.toml`
- Test: `tests/test_vision.py`
- Test: `tests/test_main.py`

- [ ] **Step 1: Write failing tests**

Add tests that verify runtime defaults include trajectory settings with YOLO disabled and diagnostics rows include emitted evidence when present.

- [ ] **Step 2: Run RED tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_vision tests.test_main -v`

Expected: FAIL because runtime does not pass evidence into `Observation` or expose trajectory sampling state.

- [ ] **Step 3: Implement runtime integration**

Return `disposal_evidence` from vision observation, write it to diagnostics, pass it to `Observation`, and use `trajectory_sample_interval_seconds` while candidates are active.

- [ ] **Step 4: Run GREEN tests**

Run: `PYTHONPATH=src python3 -m unittest tests.test_vision tests.test_main -v`

Expected: PASS.

- [ ] **Step 5: Commit phase**

Run:

```bash
git add src/cold_display_guard/main.py src/cold_display_guard/vision.py config/example.toml tests/test_vision.py tests/test_main.py
git commit -m "feat: integrate trajectory runtime diagnostics"
```

### Task 4: Documentation, Full Verification, And Deployment Prep

**Files:**
- Modify: `README_zh.md`
- Modify: `docs/project.md`
- Modify: `task_plan.md`
- Modify: `findings.md`
- Modify: `progress.md`
- Modify: `memories.md`

- [ ] **Step 1: Update docs**

Document v1.2 trajectory settings, evidence semantics, tests, and remote deployment notes.

- [ ] **Step 2: Run full verification**

Run:

```bash
PYTHONPATH=src python3 -m unittest discover -s tests -v
node --test web/test/zone-state.test.js
cd web && pnpm build
```

Expected: PASS for all commands. If frontend files did not change, frontend commands still provide regression coverage for the management console.

- [ ] **Step 3: Commit phase**

Run:

```bash
git add README_zh.md docs/project.md task_plan.md findings.md progress.md memories.md docs/superpowers/plans/2026-05-29-v1.2-trajectory-recognition.md
git commit -m "docs: document v1.2 trajectory recognition"
```

- [ ] **Step 4: Prepare remote deploy**

Use rsync excluding `config/example.toml`, rebuild runtime/API, and verify Docker services. Record the exact commands and results in `progress.md`.