Preset Upkeep

Preset upkeep

The integration presets in custom_components/home_keeper/declarative_presets_catalog.py select entities by the translation_key that each upstream integration gives them. Each entry names its English translation file (source) and the upstream commit we last read (verified.ref). This skill finds what changed upstream since then, fixes or extends the catalog, and opens one draft PR. Two scripts do the finding with no judgment. You do the judgment.

Follow AGENTS.md for everything this file does not say: ASD-STE100 English in all user text, tests before a push, CHANGELOG rules, the beta bump, /q review after a push. Never merge, and never comment on a GitHub issue.

1. Start

1. Work on the branch the session gives you. When it gives none, branch from origin/main as preset-upkeep-YYYY-MM-DD.

2. source .venv/bin/activate (see AGENTS.md, "Session setup").

3. Run the key check and keep the report:

   python ci/check_preset_keys.py --report /tmp/preset-report.json

4. Get the core translation files and list the candidates:

   rm -rf /tmp/ha-core
   git clone -q --depth 1 --filter=blob:none --sparse \
       https://github.com/home-assistant/core /tmp/ha-core
   git -C /tmp/ha-core sparse-checkout set --no-cone \
       '/homeassistant/components/*/strings.json'
   python ci/find_preset_candidates.py --core /tmp/ha-core --json /tmp/candidates.json

2. Breaks: keys that are gone

For each record in the report with missing keys or a fetch_error:

• Read the upstream file at pinned_ref and at head_ref (https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>), and the integration's entity code when the file does not say enough.
• A renamed key: change it in the catalog. Keep the task name.
• A removed key: remove it. When a duty loses all its keys, remove the duty.
• Never remove a preset id that is in tests/unit/shipped_preset_ids.txt. A saved companion keeps its id, and test_shipped_preset_ids_never_change fails when one goes away. When an entry or a shape loses all its keys, keep it as it is and ask the maintainer in the PR.
• branch ... not found: the default branch changed. Find it with git ls-remote --symref https://github.com/<owner>/<repo> HEAD and fix source.
• A file that moved: fix source to the new path.
• cannot reach the repository: a network error, not a change upstream. Run the check again for that domain (python ci/check_preset_keys.py <domain>). When it still fails, leave the entry and list it in the PR.
• pin_error (no diff, the pinned commit is gone, for example after a force push): the head was still checked. Read the upstream history of the file by hand for new keys, then pin the entry as usual.

3. New keys in integrations we cover

For each record with added keys, start with hints:

• Read the entity description upstream: unit, device class, what the value counts, and whether the device can reset it.
• When the key is a maintenance duty, add it to the duty that has the same task, or add a duty. A duty needs a shape from SHAPES in declarative_presets.py (percent_low, life_low, wear_high, reading_low, reading_high, alert) and a limit (see the catalog docstring). A wear counter that counts events, not time, gets "counted": True.
• A new task name goes in DUTY_NAMES in declarative_preset_text.py, in all 16 languages. Use the words that the other entries use.
• A key that is not a duty (a status, a setting, a mode) is skipped. List it in the PR as skipped, with one short reason.