aod-change-control

name

aod-change-control

description

Use before opening, reviewing, or merging any PR against Area Occupancy Detection (AOD) — especially anything touching Bayesian math (utils.py sigmoid pipeline), priors, decay/half-life, likelihoods, config schema (const.py CONF_*/DEFAULT_*), the config-entry migration ladder (migrations.py), or the DB schema (db/schema.py). Also load when deciding how to reply to CodeRabbit, when bumping the release version, when someone proposes a new per-sensor config knob, or when you're unsure whether a change needs a version bump, a migration, or extra validation before merge.

AOD Change Control

What this covers

How changes get classified, validated, and merged in this project: the three non-negotiable rules the retiring maintainer stated explicitly (with the incident behind each), how CI gates actually work today (not what CLAUDE.md says), the version-bump and release mechanics, and the CodeRabbit-reply convention. This is the skill for "am I allowed to ship this, and how" — process, not implementation detail.

When NOT to use this

For how the Bayesian pipeline actually computes (sigmoid/logit math, what bayesian_probability() in utils.py is and why it's dead code) use bayesian-occupancy-reference. For the historical blow-by-blow of specific incidents (full saga narratives, root causes, stale branches) use aod-failure-archaeology. For how to run tests/lint/CI locally use aod-build-and-env. For what "beyond SOTA" claims are and aren't earned yet, use aod-external-positioning. This skill only owns: classification rules, gates, the three unwritten laws, versioning/release mechanics, and the CodeRabbit convention.

---

0. Orientation trap — read this first (SETTLED 2026-07-06)

The environment banner and CLAUDE.md may both claim you're on main with a clean tree. Verify, don't trust: git status and git branch --show-current. This was a live trap through 2026-07-06: the repo was checked out on feat/adjacent-areas (PR #454) for an extended period, and an entire feature's worth of code (adjacency boost/decay-modifier, db/transitions.py, data/adjacency.py, ~10 ADJACENCY_* constants in const.py) existed only on that branch and was invisible if you assumed the banner was correct. PR #454 merged to main on 2026-07-06 (main HEAD is now 17b71d2, "feat: adjacent-areas — learned next-door room influence (#454)"); the working tree is on main and the adjacency code is now part of it. The general lesson still applies for the next long-lived feature branch — before citing any file content as "what's in main," run git show main:<path> or git diff main...HEAD -- <path> to check rather than trust the banner.

---

1. The three unwritten laws

These come directly from the maintainer. They are not aspirational — each has a real incident behind it, and violating one is treated as an unreviewable mistake, not a style nit.

Law 1 — NO SILENT MATH CHANGES

Rule: any change to Bayesian/prior/decay/likelihood output must be validated with predicted numbers before running — either against the simulator (simulator/app.py, paste a run_analysis service response and watch the recomputed probability) or against real recorder data (scripts/visualize_distributions.py). State what you expect the numbers to do, then run it, then compare.

Incidents:

• Prior inflation (issue #483 → PR #491, merged 2026-07-06, SETTLED): PriorAnalyzer.calculate_and_update_prior() (data/analysis.py) truncated the observation window at last_interval_end whenever an area had been quiet more than an hour — dropping the known-unoccupied tail from the denominator while the numerator kept all occupied time. Every hourly recalculation during a quiet stretch (overnight, weekends) pushed global_prior further toward the 0.99 cap. A real kitchen with true occupancy ~28–35% pinned at 0.99. The existing test (test_valid_calculation_sets_correct_prior) had encoded the bug — asserting 0.99 was correct — and had to be corrected to assert the true 0.25 as part of the fix. Fix on main: actual_period_end is now unconditionally now (the old conditional truncation is gone; the degenerate-period-after-startup case it was guarding is already covered by the actual_period_duration <= 0 check), and a regression test for the overnight quiet-tail case was added. Verify: gh pr view 491 --json state,mergedAt.
• Half-life override silently discarded (issue #481 → PR #493, merged 2026-07-06, SETTLED): Decay._resolve_purpose_half_life() (data/decay.py) has a sleep/awake split for the Bedroom/SLEEPING purpose (uses the area's half-life during the sleep window, switches to the purpose's fixed awake_half_life=620s outside it). The switch applied unconditionally, so a user's custom 10s half-life silently became a 620s (~10 minute) clear-out during waking hours. This is the same bug class recurring in a different code path: issue #439/PR #440 already fixed an identical "custom value gets silently normalized to a purpose default" bug for the general half-life field months earlier; #481 was the sleep/awake switch not respecting that established custom-vs-default semantics. Fix on main: _resolve_purpose_half_life() now carries an explicit "if the resolved value != the purpose default, return the base (custom) value" guard before the sleep/awake switch applies, with the adjacency modifier_factor still multiplying on top of whichever half-life (custom or default) that guard resolves to. Verify: gh pr view 493 --json state,mergedAt.

Takeaway: a test that encodes buggy output (asserts the bug's number) is not evidence a math change is safe — it's evidence nobody predicted the correct number independently before the test was written. When you touch utils.py (sigmoid/logit pipeline), data/prior.py, data/decay.py, or correlation likelihood code in db/correlation.py, compute the expected output by hand or via the simulator before trusting the test suite's green checkmark.

Law 2 — NEVER BREAK USER CONFIGS

Rule: migrations must be idempotent (safe to run twice), missing keys must be defaulted via .get(KEY, DEFAULT) rather than assumed present, and DB schema changes must not be destructive unless a CONF_VERSION bump is deliberately accepted (which wipes the whole DB — see below).

Why a version bump is dangerous: db/maintenance.py's _ensure_schema_up_to_date treats any mismatch between the stored DB version and CONF_VERSION as fatal — it deletes and recreates the entire database (all learned priors, correlations, intervals, aggregates, for every area) rather than migrating it. There is no DB-level migration script, unlike the config-entry migrations in migrations.py. Bumping CONF_VERSION for a schema change you don't actually need to gate is a real way to wipe every user's learned history on upgrade.

Precedent for additive-only schema changes: the AreaTransitions table and Areas.adjacent_areas column (feat/adjacent-areas, PR #454 — merged to main 2026-07-06, verify with gh pr view 454 --json state,mergedAt) deliberately does not bump CONF_VERSION, because the change is purely additive: a new JSON column with a default-on-missing value in the loader, plus a new table created via Base.metadata.create_all(checkfirst=True). The migrations.py comment states the rationale explicitly: bump the version and every user's DB gets wiped for no reason, since checkfirst=True on create_all only adds what's missing without touching existing tables. db/schema.py on main now has 15 tables including AreaTransitions, and CONF_VERSION was not bumped for this change (still 18 — see §4). Use create_all(checkfirst=True) for additive schema changes; reserve a CONF_VERSION bump for changes that genuinely require the nuclear wipe.

Config-entry migration pattern (migrations.py::async_migrate_entry, current on main): runs under a module-level asyncio.Lock (prevents concurrent migrations), checks config_entry.version against CONF_VERSION (currently 18 — const.py) in an explicit ladder of if config_entry.version == N blocks, and every step calls hass.config_entries.async_update_entry(config_entry, version=N+1, ...) — re-running an already-migrated entry is a no-op because the version check gates it. New optional config keys (e.g. v17→v18's exclude_from_all_areas) are handled with no data migration at all — the loader (AreaConfig._load_config) defaults the missing key via .get(), and the migration step only bumps the version number. This is the preferred pattern: prefer "loader defaults it" over "migration writes it," because the former is idempotent by construction and works even for entries that skip straight from an old version to the latest.

Entity-registry state preservation subtlety (PR #488): PR #488 made 7 diagnostic sensor classes (PriorsSensor, EvidenceSensor, DecaySensor, PresenceProbabilitySensor, EnvironmentalConfidenceSensor, ActivityConfidenceSensor, SensorHealthSensor) register with entity_registry_enabled_default=False for newly-registered areas, to cut recorder write volume (issue #467). The PR body claimed "deleting and re-adding an area counts as a new registration, so its diagnostics come up disabled" — this claim is wrong, and the PR's own shipped test disproves it: tests/test_sensor.py::test_re_add_area_restores_previous_enabled_state demonstrates that HA's entity registry keeps removed entities in a deleted_entities store and restores the previous disabled_by state when the same unique_id is re-created — async_get_or_create passing disabled_by=INTEGRATION (per enabled_default=False) is overridden by the registry's restore of the prior state. The lesson: deleted_entities restore beats enabled_default on re-registration. Don't assume delete+re-add is equivalent to a fresh install for entity-registry purposes — verify against the registry's actual restore behavior (or this test) before describing re-add semantics in a PR body.

Law 3 — CONFIG SURFACE IS SACRED

Rule: prefer purpose-based smart defaults over adding a new user-facing config knob. Every new CONF_* option is a permanent commitment (it must be defaulted forever via .get(), documented, and migrated correctly). The bar for adding one is high.

Precedent — declining a per-sensor config UI (issue #159, "Allow per Sensor active states"): maintainer's response (verify: gh issue view 159 --json comments):

"this is something I would like as well, at the moment I am limited by the options available for config in the UI, it would get very clunky, very quickly, some integrations have built their own config UI, but this is an endeavour on its own, so not likely to happen too soon."

Per-entity granularity was rejected not on principle but on config-flow UI cost — building a custom config UI to support it is treated as a separate, larger undertaking than the feature itself.

Precedent — partial-build decision (issue #466, "Configurable repair issue thresholds + ability to suppress repairs per sensor"): three asks came in; the maintainer shipped the purpose-aware defaults (#474: bedrooms get 48h, media rooms 32h, offices 24h vs 8h base; media_player.* exempted from the unavailable check entirely) and the integration-level on/off toggle (#472) plus sticky-ignore-across-flaps (#473) as smart defaults that avoid adding new knobs, then explicitly declined to build per-sensor threshold configurability and per-sensor suppression yet, verify with gh issue view 466 --json comments:

"Per-sensor configurable thresholds: not implemented. Open question whether this is worth the config-surface cost given (3) covers the main offenders."

"Leaving this open to track per-sensor suppression specifically. If the saner defaults + sticky-ignore combo turns out to cover the real-world cases, we can close this without building (1)."

Takeaway: when a feature request asks for new per-sensor/per-area knobs, first ask whether a purpose-aware default, a smoothing/fallback mechanism, or a single integration-level toggle can cover the real cases. Only add a new CONF_* option after that's demonstrably insufficient — and say so explicitly in the PR/issue, the way #466's response does.

---

2. Change classification

Classify every change before starting work — it determines what validation and review depth is required.

Class	Examples	Requires
Docs-only	docs/docs/**, README.md, docstring wording	Standard PR + CI; no math/behavior review needed. Note: docs/docs/features/sensor-health.md and docs/docs/technical/database-schema.md are already known-stale vs code (thresholds and retention numbers) — don't propagate their numbers into a new doc without re-verifying against the source file
Test-only	New/changed test cases, fixtures, no production code touched	Standard PR + CI; if the test encodes a previously-buggy expected value, treat it as a math-affecting change in disguise (see Law 1's #483 lesson)
Behavior-affecting, non-math	Health-check thresholds, repair-issue UX, service schemas, entity registry defaults	Standard PR + CI + manual verification of the specific behavior changed (e.g. scripts/develop + the synthetic sensor rig in config/configuration.yaml)
Math-affecting	Anything touching utils.py (sigmoid/logit pipeline), data/prior.py, data/decay.py, correlation/likelihood code in db/correlation.py, adjacency boost/decay-modifier math	Law 1 applies: predicted numbers before running, simulator or scripts/visualize_distributions.py validation, no reliance on tests alone
Config-schema-affecting	New CONF_*/DEFAULT_* in const.py, new options-flow field, new per-area setting	Law 3 applies: justify why a smart default can't cover it first; if shipped, .get()-based defaulting is mandatory, plus a migration-ladder entry if the key needs a version-gated introduction
DB-schema-affecting	New table/column in db/schema.py	Law 2 applies: additive-only changes use create_all(checkfirst=True) and skip the CONF_VERSION bump; anything requiring an actual data transformation needs a real migration plan, not just a version bump (a bump alone triggers the destructive full-DB recreate)

---

3. Gates as they actually exist

Five GitHub Actions workflows in .github/workflows/:

Workflow	Trigger	What it checks
test.yml ("CI: Test")	push to main, PR to main (rc/dev triggers removed 2026-07-06 — see §5)	uv run pytest --cov=custom_components/area_occupancy --cov-report=xml --cov-report=term-missing. Coverage gate: pyproject.toml [tool.coverage.report] fail_under = 85 (the inline comment says "Enforce 90% coverage minimum" — that comment is stale/wrong; the enforced number is 85, treated as the floor with 90 as an aspiration)
lint.yml ("Ruff")	push to main, PR to main	uv run ruff check . (no --fix) then uv run ruff format . --check (no mutation) — CI never auto-fixes; run scripts/lint locally first
validate.yml	push to main, PR to main, daily cron, manual dispatch	Hassfest validation (home-assistant/actions/hassfest@master) and HACS validation (hacs/action@main) — both pinned to floating @master/@main refs, so occasional failures are upstream flakiness (e.g. observed Cloudflare 525 from brands.home-assistant.io crashing HACS's brands validator), not necessarily your PR's fault — check the failure log before assuming your change broke it
release.yml	on release: published	Hard-fails if manifest.json's version doesn't equal the GitHub release's tag name; then zips custom_components/area_occupancy and uploads it as the HACS-installable asset via gh release upload
docs.yml	push to main only	Builds and deploys docs/ via mkdocs gh-deploy --force to the gh-pages branch

Branch protection: classic branch protection is absent (gh api repos/Hankanman/Area-Occupancy-Detection/branches/main/protection returns 404 Branch not protected), but a repository ruleset named "Main" does exist (gh api repos/Hankanman/Area-Occupancy-Detection/rulesets, id 6210511, enforcement: active): it forbids deletion and non-fast-forward pushes and requires changes to main to come through a pull request — however, repository admins and one GitHub App integration bypass it ("bypass_mode": "always"), so the maintainer's own direct pushes go through with a "Bypassed rule violations" warning. No status checks are required by the ruleset: CI is still advisory. Practical rule: work through PRs; treat the admin bypass as an escape hatch for meta-content (e.g. this skills library), not for code. Discipline (running scripts/lint/scripts/test locally, waiting for green CI, waiting for CodeRabbit review) remains the real gate — GitHub will not block a merge on red CI.

CodeRabbit: reviews every PR automatically (no .coderabbit.yaml present in the repo, so it runs on CodeRabbit's default configuration/GitHub App install). It posts inline suggestions and can auto-link related/duplicate issues (e.g. it flagged #465 as a possible duplicate of #466, and linked #429/#459 as related PRs).

Merge convention: the repo has all three merge strategies enabled (allow_squash_merge, allow_merge_commit, allow_rebase_merge all true per the GitHub API), but squash-merge is what's actually used in practice — verified directly: PR #489's merge commit (704c89e) has a single parent (git cat-file -p 704c89e shows one parent line), and its title is the PR title with (#489) appended, GitHub's standard squash-title format. Recent merged-PR titles consistently follow Conventional Commits (feat:, fix(health):, chore:, perf(correlation):) with a trailing (#NNN).

---

4. Versioning and release

Three files carry the version string and must be bumped together (verified against the actual bump commit 704c89e "chore: bump version to 2026.5.17 (#475)" — diff touched exactly these three files, 2 lines each):

1. pyproject.toml — version = "2026.5.17"
2. custom_components/area_occupancy/manifest.json — "version": "2026.5.17"
3. custom_components/area_occupancy/const.py — DEVICE_SW_VERSION: Final = "2026.5.17" (note: not literally named VERSION)

Do not confuse this with CONF_VERSION (currently 18) and CONF_VERSION_MINOR (currently 0) in the same const.py file — those gate the config-entry migration ladder (migrations.py) and are a completely separate axis from the release version. Bumping one does not bump the other.

Version scheme is CalVer (YYYY.M.N), not SemVer — CLAUDE.md's line "Use semantic versioning (MAJOR.MINOR.PATCH)" is stale. Actual releases (gh release list) run 2026.5.17, 2026.5.2, 2026.5.1, 2026.4.1, 2026.3.4... — year.month.increment, not major.minor.patch.

Release mechanics: create a GitHub Release (tag = the exact version string in the three files above); release.yml hard-fails the build if manifest.json's version doesn't match the release tag, so bump the version files before cutting the release, not after. Release bodies are hand-edited on top of GitHub's auto-generated "What's Changed" PR list — narrative summary + linked originating issues, then the auto-generated per-PR bullet list.

CHANGELOG.md is STALE — do not trust or update-in-place expecting continuity: the last real entry is [2026.3.3] - 2026-03-09, and the file now carries an explicit deprecation banner at the top saying so and pointing to GitHub Releases as the changelog of record. Every release since (2026.3.4 through 2026.5.17, i.e. the entire second quarter of this project's 2026 history) has no CHANGELOG.md entry — release notes live only in GitHub Releases (gh release view <tag>), not in this file. If asked to "update the changelog," clarify whether that means CHANGELOG.md (dead convention, now self-documenting its own deprecation) or a new GitHub Release body (the actual live convention).

Note on today's merge wave (2026-07-06): PRs #489, #488, #486, #491, #492, #493, #494, #495, #496, and #454 all merged to main on 2026-07-06, but the integration release version is still 2026.5.17 — none of these changes are in a tagged release yet. Don't describe them as "shipped in release 2026.5.x" until a new version is actually cut; they're merged to main but pre-release.

---

5. Branch reality (CLAUDE.md is stale here)

CLAUDE.md says: "Development happens on dev branch. PR from dev to preview for prereleases. PR from preview to main for full releases."

The repo shows this is no longer true. Verified:

• git ls-remote --heads origin — no dev, preview, or rc branches exist on the remote today.
• Every one of the last 15 merged PRs (#446 through #489, spanning 2026-04-27 through 2026-07-06) has baseRefName = main.
• The last PR merged into a non-main base was #343 into dev, dated 2026-01-30 — the dev→preview/rc→main pipeline was real practice through roughly January 2026, then abandoned in favor of direct feature-branch → main PRs from February 2026 onward.
• CI trigger cleanup (PR #495, "CI hygiene," merged 2026-07-06, SETTLED): .github/workflows/lint.yml, test.yml, and validate.yml used to still list pull_request: branches: ["main", "rc", "dev"] — triggering on PRs targeting branches that no longer existed. That dead config has been removed; all three workflows now trigger only on push/ pull_request to main (see §3). This was a stale-config smell, not evidence the old flow was still live, and it's now cleaned up.

Practical instruction: open PRs directly against main from a feature/fix branch (e.g. feat/<name>, fix/<name>, chore/<name>). Ignore CLAUDE.md's dev/preview/rc branching section — it describes a workflow this project stopped using about five months before this skill was written. CONTRIBUTING.md is consistent with this: it explicitly says to "Fork the repo and create your branch from main."

---

6. When to reply to CodeRabbit

Convention observed directly in this repo's PR history: when CodeRabbit flags something and you disagree or intentionally don't act on it, post the rationale as a reply on the PR thread rather than silently ignoring it — both so the reviewer (human or AI) sees you considered it, and so the project accumulates a record of deliberate design decisions.

Two concrete shipped examples:

• Accepting with commentary (PR #491): @coderabbitai Good catch — updated docs/docs/technical/global-prior-flow.md in the follow-up commit: the period-end rule, the code sample, and the now-obsolete known-issue entry about the 1-hour threshold all reflect the always-now behaviour.

• Declining with rationale (PR #438) — the canonical pattern for a partial/declined finding, structured as Accepted / Partially accepted / declined-with-reasoning:

  "I did not make the shell re-persist a fatal failure. The rationale: By the time save_area_data runs, delete_area_data has already succeeded — the user-visible purge is complete. [...] Raising here would tell the caller 'the purge failed' when in fact the purge succeeded and only a best-effort re-persist failed, which is misleading. If you'd prefer hard failure, happy to flip it — but the current behavior matches what the user actually experiences."

Follow this shape: state which findings you accepted (and what changed), which you partially accepted, and which you declined — with the actual reasoning, not just "won't fix." This applies to any CodeRabbit finding on math (Law 1), config (Law 3), or migration safety (Law 2) — those categories should almost never be silently dismissed without a written reason on the PR.

---

Provenance and maintenance

Date-stamped 2026-07-06 (post-merge-wave), integration release version still 2026.5.17 (pyproject.toml line 7 / manifest.json line 20 / const.py DEVICE_SW_VERSION — see §4's note on the merge wave not being released yet). Repo is checked out on main, HEAD 17b71d2 ("feat: adjacent-areas — learned next-door room influence (#454)") — see §0 for the now-settled history of that branch trap. PRs #489, #488, #486, #491, #492, #493, #494, #495, #496, and #454 all merged to main on 2026-07-06 — their content above is now described as shipped-on-main, not pending.

Re-verification commands, by volatile fact category:

• Which branch you're actually on: git status && git branch --show-current (expect main, HEAD at or descended from 17b71d2)
• Branch protection state on main: gh api repos/Hankanman/Area-Occupancy-Detection/branches/main/protection
• Merge-strategy settings: gh api repos/Hankanman/Area-Occupancy-Detection --jq '{squash:.allow_squash_merge, merge_commit:.allow_merge_commit, rebase:.allow_rebase_merge}'
• PR #454/#491/#492/#493/#494/#495/#496 merge state: gh pr view <number> --json state,mergedAt,statusCheckRollup (one number per call) — all should show state: MERGED as of 2026-07-06
• Coverage gate: grep -n "fail_under" pyproject.toml; confirm live number via scripts/test
• CI workflow trigger branches (rc/dev cleanup from PR #495): grep -n "branches" .github/workflows/*.yml — should show main only, no rc/dev
• Version triple in sync: grep -n version pyproject.toml custom_components/area_occupancy/manifest.json; grep -n DEVICE_SW_VERSION custom_components/area_occupancy/const.py
• CONF_VERSION / migration ladder: grep -n "CONF_VERSION\b" custom_components/area_occupancy/const.py; read custom_components/area_occupancy/migrations.py::async_migrate_entry
• CHANGELOG.md staleness/deprecation banner: head -15 CHANGELOG.md vs gh release list --limit 5
• Remote branch existence (dev/preview/rc): git ls-remote --heads origin
• Issue #159 / #466 maintainer responses: gh issue view 159 --json comments; gh issue view 466 --json comments
• PR #438 CodeRabbit-reply example: gh api repos/Hankanman/Area-Occupancy-Detection/issues/438/comments --jq '.[] | select(.user.login=="Hankanman")'
• PR #488 entity-registry restore test: grep -n "test_re_add_area_restores_previous_enabled_state" tests/test_sensor.py
• AreaTransitions create_all precedent (now on main post-#454):