Design docs: engine spec and decision record

[leiklier]

What

The normative contract for the new integration, before any code:

• docs/ENGINE_SPEC.md — numbered rules (§1 visibility, §2 plant-day budget, §3 decisions/timing, §4 enforcement, §5 persistence, §6 tunables) that code and tests cite verbatim.
• docs/DECISION.md — the ADR: why plant-day instead of rolling 24 h, why one unified visibility model (analysis showed the legacy weekday template's is_morning_routine and arrival_cutoff clauses were redundant — awake+home already forced off), why the weekend after-wake latch is deliberately dropped, refuge zones instead of workday-calendar guessing, greedy scheduling with hysteresis only, fail-safe direction unknown ⇒ observed ⇒ light off, and truth-based budget accounting.

Review focus

The behavioral deltas vs. the live templates are all in DECISION.md §2–§3: no weekend latch, away schedule = anchor+budget instead of the fixed 22:00–14:00 window, workday/vacation inputs dropped. If any of those should be preserved instead, this is the PR to say so.

Part 1 of 3 (docs → core → adapter).

🤖 Generated with Claude Code

[leiklier]

Added rule 1.3b (trigger entities) to the spec: momentary movement signals (the bedroom door contact) whose transitions pulse the viewer-activity clock without sustaining it — instant cut on door-open during sleep, normal clear-hold relight, and a door left open can never block the schedule (its level is never read).

[leiklier]

Second refinement (owner decision, now DECISION.md §8): refuge continuity over absolute invisibility. Rule 1.3c — during confirmed refuge, viewer activity cuts only once continuously active for exposure_grace (300 s); shorter episodes and trigger pulses neither cut nor impose a hold. Rule 1.7 — confirmed refuge is held across evidence gaps up to refuge_hold (600 s), so office-sensor decay during a coffee run doesn't release the block. Asleep/away contexts unchanged: every blip still cuts instantly.