fix: ignore global lighting shifts in occupancy

docs/project.md

@@ -50,6 +50,8 @@ The `v1.2 轨迹识别` batch adds source-zone trajectory evidence for disposal
   - Stored under `[trash] roi`.
   - Does not use a food zone number.
 - v1.2 trajectory settings:
+  - `lighting_shift_guard_enabled`: freezes occupancy changes when many regions shift brightness in the same direction.
+  - `lighting_shift_min_regions`, `lighting_shift_region_fraction`, `lighting_shift_mean_delta`: tune the global lighting/exposure guard.
   - `trajectory_enabled`: enables source-zone trajectory evidence.
   - `trajectory_window_seconds`: seconds after a zone clears where movement can confirm disposal.
   - `trajectory_sample_interval_seconds`: faster runtime delay while a candidate is active.
@@ -78,6 +80,7 @@ The current tracker is a motion backend only. A later trained YOLO detector shou
 - Runtime diagnostics JSONL records one item per runtime iteration.
 - Root `disposal_evidence` is the exact evidence list passed into the engine for that iteration.
 - `diagnostics.zones` contains occupancy metrics used to derive `zone_counts`.
+- `diagnostics.lighting_shift` reports whether global brightness drift suppressed occupancy transitions.
 - `diagnostics.trash` contains generic trash-motion metrics and cooldown state.
 - `diagnostics.trajectory` contains v1.2 candidate counts, emitted evidence count, motion point count, and per-candidate emitted/rejected/expired records.
 - Capture failures still keep the v1.2 schema with root `disposal_evidence: []` and `diagnostics.trajectory.reason = "frame_capture_failed"`.
@@ -122,6 +125,7 @@ In v1.2, `batch_discarded` can be triggered by zone-scoped `disposal_evidence` b
 ## Known Risks
 
 - The current vision detector is heuristic and reports binary occupancy, not item counts.
+- The lighting-shift guard suppresses multi-zone brightness/exposure jumps; if operators intentionally fill most zones at once under a large lighting change, diagnostics should be reviewed before treating that interval as clean data.
 - v1.2 motion tracking improves disposal matching but can still miss movement if the hand/object path is occluded, too broad, too small, or sampled too sparsely.
 - YOLO config fields are present for compatibility, but no trained YOLO model is part of the current runtime.
 - If food is already present during baseline collection, those regions may be treated as empty baseline until visual changes occur.