caution.jsonl

{"date":"2026-09-26","area":"HACS publishing metadata","note":"GitHub documentation URL, issue tracker, code owner, and brand icon are not yet available; do not treat this scaffold as publish-ready."}
{"date":"2026-09-26","area":"Control state and lifecycle","note":"Do not equate service completion with an observed actuator transition, cached temperature reads with new reports, or restored timestamps with valid monotonic timers. Phase 1 must follow docs/phase_1_spec.md."}
{"date":"2026-09-26","area":"Config Flow validation","note":"Boundary tests do not prove Home Assistant runtime or frontend compatibility. Config Flow setup currently saves configuration only and must not be described as controlling heating. Shared boiler control is not inferred from room switches."}
{"date":"2026-09-26","area":"Standalone runtime lifecycle","note":"As of dev.4, standalone controls heating while multi-zone remains configuration-only. Never detach callbacks after OFF confirmation without rechecking for state changes during awaited persistence. An ON demand must not cancel a pending OFF confirmation. Live HA runtime validation is still required."}
{"date":"2026-09-26","area":"Thermal observation","note":"Phase 2 diagnostics are observation-only. Never feed unvalidated thermal measurements into the Phase 1 controller or mark a partial/interrupted heating cycle complete. Restart and sensor gaps invalidate rolling history and active-cycle measurements."}
{"date":"2026-09-26","area":"Thermal learning","note":"Phase 3 EWMA estimates are diagnostic only. Keep each metric's sample count/variance independent, reject outliers after the three-sample baseline, validate the complete persisted snapshot, and never use learned values for switching before a separately reviewed predictive-control phase."}
{"date":"2026-09-26","area":"Climate mode and occupancy presets","note":"OFF is observation-only in steady state; HEAT applies hysteresis and AUTO adds confidence-weighted learned predictions. Keep minimum-ON/OFF deadlines, faults, startup gating, and late-ON recovery. HOME/AWAY change only the target to configured 23°C/18°C defaults and do not switch HVAC mode. Legacy heat plus auto_control migrates to AUTO only when the legacy flag is true. Live Home Assistant and physical temperature validation remain necessary."}
{"date":"2026-09-26","area":"Learned-control architecture","note":"All Climate modes continue observing valid cycles and updating the aggregate model. Only AUTO may use learned values in heater decisions; HEAT remains hysteresis-only and OFF remains observation-only apart from a safe stop on transition. Keep the architecture document aligned with runtime.py, history.py, thermal_model.py, and the Phase 4 behavior specification."}
{"date":"2026-09-26","area":"Diagnostic sensor metadata","note":"Use duration for minute-based delays and temperature_delta for measured temperature differences. Reserve total_increasing for cumulative counters. Do not assign temperature to °C/h rates or confidence percentage merely because their units resemble a standard class; units and device class semantics must match."}
{"date":"2026-09-26","area":"Temperature availability and learning","note":"Use the currently registered HA sensor state for control whenever it is a valid finite temperature, regardless of last report age. A missing, unknown, unavailable, or invalid state blocks control. Sensor report-gap limits break only thermal learning continuity; polling a cached value must never create temperature-learning samples."}
{"date":"2026-09-26","area":"Heating hysteresis defaults","note":"Keep mode-specific stop offsets explicit: heating-start is 0.5°C below target in both modes, AUTO stop offset defaults to 0.5°C above target, and HEAT stop offset defaults to 0°C. Existing persisted user option values must remain intact unless migration is explicitly designed."}
{"date":"2026-09-26","area":"Integrated multi-room actuation","note":"A single integrated Climate shares one sensor and learning model across its room switches. Confirm the aggregate state only when every switch reports the same ON/OFF state; do not learn from partial group transitions. Mixed or unavailable states must fault and request OFF for the complete switch group. Reserve and release ownership for every member switch."}
{"date":"2026-09-26","area":"Optional temperature sensor configuration","note":"Keep outdoor, supply, and return sensor selectors optional and restricted to temperature-class sensors with finite °C/°F states. Persist selected IDs in ConfigEntry.options, preserve them when the options form omits unchanged fields, and do not claim they affect control or learning until runtime integration is implemented."}
{"date":"2026-09-27","area":"Documentation status and local-only development records","note":"Keep development specifications, tree.md, changelog.jsonl and caution.jsonl untracked as requested. Earlier dated notes describe historical phases, not current feature restrictions. Optional sensors now support diagnostic-only heat-loss learning; AUTO uses learned peak delay. Distinguish automated test success from pending live HA acceptance."}
{"date":"2026-09-27","area":"Adaptive slope selection","note":"Choose slope samples by latest actual report interval: over five minutes uses up to five reports, otherwise 45 minutes. Preserve actual timestamps, three-point/ten-minute minimum and 24-hour retention. Do not synthesize reports or alter cycle-specific regressions. Development records remain untracked."}
{"date":"2026-09-29","area":"AUTO prediction selector and entity IDs","note":"Keep predictive OFF and post-OFF waiting in eco, balanced, and comfort. Only predictive ON changes: eco skips it, balanced uses half the confidence-weighted response delay, and comfort uses the full delay. Balanced is the default when no selection is saved. Keep unique IDs stable; entity IDs use one shared prefix for a single config entry and room_n prefixes when multiple entries exist. Number config entries, not switches inside one integrated entry."}
{"date":"2026-09-30","area":"Five-minute curve learning","note":"A change-only room sensor retains its last valid HA state at five-minute boundaries; do not synthesize new thermal reports. Preserve measured zero buckets, reject unavailable intervals and interrupted cycles, update each of four persistent standards only after quality checks, and keep the existing AUTO estimator as the fallback. Field validation of deviation thresholds and live HA behavior is still required."}
{"date":"2026-10-02","area":"Independent learned OFF prediction","note":"An ON trajectory is not a counterfactual OFF response. Learn measured post-OFF response at comparable duration/slope states; distinguish equivalent response hours from time-to-peak. Confidence gates prediction and must not simply shrink the physical rise. A flat plateau does not confirm Peak; use the last actual pre-decline report. Preserve Cold return intent until an accepted Cold segment, and never infer Cold from a long HOME OFF period."}
{"date":"2026-10-02","area":"Current and Long-term curve memory","note":"Do not confuse permanent storage with an independent Long-term model. Promote only stable Current, never raw cycles; distinguish promotion counts from independent evidence and migrate unknown variance honestly. Preserve Long-term through raw TTL and non-heating seasons. Use one blend weight over an OFF response to avoid an artificial peak, and publish in-memory changes only after the complete SQLite transaction commits."}
{"date":"2026-10-03","area":"Delayed response and Peak confirmation","note":"A short heating pulse can stay flat or cool at OFF and warm only later. Never divide by near-zero or negative OFF slope, invent unknown thermal context, or treat the first downward report as Peak. Match measured duration and thermal state, keep initial negative trajectory points, require actual sustained post-response cooling, and preserve the original peak/report timestamps. Valid immediate zero-coast responses need a zero-time singleton trajectory to avoid duplicate timestamps and division by zero. A matched residual forecast must precede predictive ON, and failed modern matching must not fall back to an unrelated global residual mean. Numerical similarity, decline and waiting-release thresholds still need physical field calibration."}
{"date":"2026-10-03","area":"Recorder diagnostics and sensor cleanup","note":"Separate last confirmed OFF forecasts from last completed actual Peak; retain cycle timestamps and never compute new errors from historical forecasts after invalidation or restart. Missing predictions are unknown, not zero. Distinguish aggregate basic learning confidence from the selected or fallback prediction confidence and annotate its source/model. Sensor getters must not run predictors, write storage or dispatch commands. Default-disabled descriptions do not override existing registry enablement. Pipe residual-rise and peak-delay diagnostics measure indoor temperature, not water. Optional diagnostic corruption must not reset valid thermostat intent; wall-clock metadata is not a monotonic control deadline."}
{"date":"2026-10-04","area":"Sidebar shell","note":"Stage one serves only local static UI through HA HTTP and panel_custom; do not represent placeholders as live telemetry or implement heater commands. Shared panel registration follows the integration's HA lifetime, not an individual room's unload. Actual HA frontend acceptance remains pending."}
{"date":"2026-10-04","area":"Sidebar state presentation","note":"Identify Climate ownership with registry platform and stable unique IDs, never entity-name prefixes. Actuator pending false means OFF confirmation is pending; null means no pending command. Follow HA display temperature units, suppress unavailable/disconnected readings and dispose subscriptions including late async completions. Browser fixtures do not prove live HA permissions or frontend acceptance."}
{"date":"2026-10-04","area":"Sidebar Climate controls","note":"Dispatch only existing Climate services to the current registry ID of the selected unique ID, never switch services. Service completion does not confirm physical heating; keep pushed HA state as the display source. Preserve temperature drafts, honor HA display units and entity bounds, block duplicate/unavailable calls and never auto-retry a timeout with unknown outcome. Validate permissions and actual actuation in live HA separately."}
{"date":"2026-10-04","area":"Sidebar history graphs","note":"Query full Climate attributes with significant_changes_only/minimal_response/no_attributes false; HVAC state alone misses temperature and actuator changes. Decode compressed lu/a/s timestamps as Unix seconds and preserve unavailable gaps. Held graph values are recorder states, not synthesized thermal samples or measured heat delivery. History requires HA Recorder/History access and retention; renamed old entity IDs and unlabelled past temperature-unit changes are not automatically reconstructed."}
{"date":"2026-10-04","area":"Sidebar completed-cycle comparison","note":"Use last_peak_comparison's own predictions/errors, never the latest OFF forecasts from another cycle. Show confidence from last_off_prediction only for equal valid OFF timestamps. Missing predictions are unknown, not zero. Nested runtime diagnostic temperatures remain Celsius; Fahrenheit absolute temperatures need the offset while signed errors need only the scale factor. Legacy metadata omissions do not invalidate otherwise valid completed values."}
{"date":"2026-10-04","area":"Sidebar learned curve display","note":"CurveMemory.current/long_term store per-five-minute deltas, not cumulative temperature or condition-matched OFF response trajectories. Bucket zero covers minutes 0-5 after ON, or after Peak for Cooling; preserve zero means and gaps. Long-term promotions are not independent cycles and inherited bucket evidence must not be summed into cycle totals. Check Climate registry ownership and entity read permissions before exposing detached snapshots; never invoke learning/prediction or database writes from reads."}
{"date":"2026-10-04","area":"Sidebar Select controls","note":"Resolve existing Select entities by platform, exact config-entry and integration unique ID; never guess entity IDs from names. Reject ambiguous/hidden/disabled/missing targets and unsupported options. Use select.select_option with HA permissions, keep reported state after service completion and preserve unrelated target-temperature drafts. Model/policy selection applies to AUTO; it does not change the learning algorithm."}
{"date":"2026-10-04","area":"Sidebar sensor history","note":"Only expose graph choices with valid numeric Recorder evidence for the selected period and room-owned active registry entities. Use sensor-reported units, exclude timestamp/enum states, preserve zero and unknown/unit-change gaps, and invalidate late responses on context changes. Empty history must retain refresh discovery so newly recorded data can appear."}
{"date":"2026-10-04","area":"Live forecast overlay","note":"OFF-response points are minute/Celsius deltas assuming OFF now, not forecasts of continued heating. Anchor them to the forecast's own wall-clock timestamp and Celsius baseline, never the controller's monotonic loop time or an old last_off_prediction. Gate on confirmed ON and accepted evidence for the actual predictor; do not invent a curve or extend measured history into future time."}
{"date":"2026-10-06","area":"Cycle investigation and compressed history","note":"A rejected curve segment is not a physical heater transition, and the completed-Peak comparison is not the rejection ledger. Identify records by both ID and curve type; retain the first-failure quality reason plus independently recorded checks. Store measurements, exact thresholds, reference buckets and learning before/after evidence at commit time, never reconstruct legacy omissions from current curves. Original bucket count and confirmed pruning must survive raw TTL. Use read-only SQLite queries with entity permissions and isolate late room/filter responses. Compressed Recorder state and attributes carry forward when omitted, but explicit empty attributes and unavailable states must still clear readings."}
{"date":"2026-10-06","area":"Measured Peak confirmation and observation horizon","note":"A long plateau is not a failed heater cycle. Confirm only after observed heating response, a real report at least 0.3 C below the maximum and an additional 0.1 C fall on the next distinct report; equal repeats and timer ticks are insufficient. Keep the last maximum timestamp separate from confirmation and retain pre-Peak held buckets honestly. A changed OFF horizon must agree across both observers, quality checks, profile validation, memory restore/prediction and raw sampling; keep the four-hour cap to avoid indefinite or next-day observation. Persist exact thresholds and drops for new evidence; never reinterpret or re-learn old rejected rows using new criteria. Image-based simulations approximate reports and cannot prove physical acceptance or sensor accuracy."}
{"date":"2026-10-06","area":"Peak first-fall relaxation","note":"Current first-drop threshold is 0.2 C followed by at least another 0.1 C on the next distinct actual report. Do not confuse cumulative 0.3 C confirmation with a first 0.3 C threshold; retain the four-hour cap and stored historical policy. Screenshot-derived simulations are approximate; a temporary 0.3 C dip followed by renewed warming can confirm early."}
{"date":"2026-10-06","area":"Sidebar plot refresh","note":"Do not clear ready SVG plots when same-context refresh starts. Reuse unchanged SVG nodes to preserve pointer details and avoid redraws on unrelated HA pushes or ResizeObserver callbacks. Include context, units, timezone, forecast and width in relevant plot signatures; clear prior-context plots on selection changes and disconnect, and retain explicit error cleanup. Browser fixtures cannot establish whether a physical HA page navigates or reloads."}