openspec(backport-keg-catalog): sync entities spec + archive
Syncs the delta into openspec/specs/entities/spec.md, retrofitting the Keg name sensor and Keg product ID sensor requirements that PR #2 shipped without ever updating the spec, and adding both to the entity-name translations scenario. Note that openspec validate --specs still fails on all five spec files for a missing "## Purpose" section. That is pre-existing and repo-wide, not caused by this sync — verified by stashing the change and re-running. Left alone rather than fixed across five files here. PROJECT_HYGIENE learnings, three of them found while doing this work: - Never add a non-numeric key to keg_catalog.json. The loader's {int(k): v ...} raises on it and the except clause returns an empty dict, so the whole catalog dies silently at debug level. This is a trap precisely because embedding provenance in that file is the obvious next idea. - test_harness.py is stale: it reads a user_id key that .credentials.json no longer has, so it exits immediately. - All five openspec/specs files already fail validation, so a failing spec validation does not imply you broke something. Group 5 (on-device) is recorded as verification debt rather than marked done. The catalog was replaced wholesale and verified statically only; the live resolve path is unexercised because no HA is reachable from the dev host and the harness refresh token has expired. v0.3.2 exists so that check can happen through HACS.
This commit is contained in:
@@ -191,6 +191,10 @@ When the user corrects your approach, append a one-line rule here before ending
|
||||
|
||||
- **`numberOfPoursSinceStartup` resets to 0 on a machine power cycle** (confirmed 2026-06-01: power-cycled the machine at pours=16, reloaded the integration, Pours read 0). It counts since machine startup, NOT since keg insertion. Do not base keg-change detection on the pour counter — a power cycle (outage, unplug, firmware update) would false-trigger it. `kegVolume` (Keg Remaining) was confirmed unchanged across the same power cycle/reload, so a power cycle produces no spurious volume jump — volume-jump signals (b/c) and the manual button are the power-cycle-safe detectors; prefer them.
|
||||
- **TODO — verification debt, do this when the next keg is fitted: confirm the keg-freshness baseline survives a reauth.** `fix-reauth-flow` (archived 2026-09-06) was verified on-device for the reauth flow itself, but the machine had no keg in the tap, so there was no freshness countdown to preserve and task 6.6 could not be checked. The fix uses `async_update_reload_and_abort`, which reloads the config entry — the exact moment a `RestoreEntity` baseline could be lost. After the next keg change, trigger a reauth (or reload the integration) and confirm Keg Freshness keeps its countdown instead of resetting to unknown. If it resets, that is a real regression in `PerfectDraftKegFreshnessSensor`'s restore path, not in the config flow.
|
||||
- **Never add a non-numeric key to `keg_catalog.json`.** `_load_keg_catalog` in `sensor.py` builds `{int(k): v for k, v in raw.items()}` and catches `ValueError` by returning `{}`. A single `_meta` or `_source` key therefore disables the *entire* catalog — every keg reports no name — and says so only at debug level. Recording provenance or attribution inside that file requires changing the loader first. `tests/test_keg_catalog.py::test_keys_are_numeric` guards this.
|
||||
- **TODO — verification debt from `backport-keg-catalog` (archived 2026-09-06), clear this after installing v0.3.2 via HACS: confirm the `Keg` sensor still resolves the fitted keg.** The catalog file was replaced wholesale (86 → 114 entries) and verified statically only: exact diff shape, 114 int keys through the loader, and format guards in `tests/test_keg_catalog.py`. What was never exercised is the live path. On-device checks were impossible at the time — no HA on the dev host, and `.credentials.json`'s refresh token had expired (`NotAuthorizedException: Refresh Token has expired`), so even `test_harness.py` could not reach the API. Task group 5 in the archived change lists the four checks.
|
||||
- **`test_harness.py` is stale: it reads `user_id` from `.credentials.json`, which now holds `email` / `access_token` / `id_token` / `refresh_token`.** It exits before doing anything useful. Fix the key names (and refresh the token per the README's reCAPTCHA step) before relying on it.
|
||||
- **All five files in `openspec/specs/` fail `openspec validate --specs`** for a missing `## Purpose` section. Pre-existing and repo-wide as of 2026-09-06, so a failing spec validation is not necessarily caused by your change — check whether the error is only the Purpose one before chasing it.
|
||||
- **TODO — own OpenSpec change: persist Cognito-refreshed tokens back to the config entry.** `PerfectDraftApiClient.refresh_access_token()` updates `_access_token`/`_id_token` in memory only, so every HA restart reloads the stale access token and burns a wasted 401-plus-refresh round trip before the first successful poll. Harmless today because the refresh token is what actually gates reauth and Cognito's `REFRESH_TOKEN_AUTH` never issues a new one, so nothing is lost — just wasteful. Deferred out of `fix-reauth-flow` to keep that diff surgical.
|
||||
- **TODO — own OpenSpec change + release: remove pour-count-based keg detection** from `PerfectDraftKegFreshnessSensor` in `sensor.py`: trigger (a) `pours == 0 && kegVolume > 5.5 && last_pours != 0`, plus the `_last_pours` field and its restore/exposure/rebaseline. It can false-fire on a power cycle while the keg is above ~92% full, and adds nothing the volume triggers (b/c) and the Mark Keg Changed button don't already cover.
|
||||
|
||||
|
||||
+7
-4
@@ -28,7 +28,10 @@
|
||||
|
||||
## 5. Verify on the machine
|
||||
|
||||
**BLOCKED — needs the repo owner.** No Home Assistant instance is reachable from the
|
||||
**DEFERRED to post-release on-device check — carried as verification debt.**
|
||||
The v0.3.2 release exists so the owner can install via HACS and run this group live.
|
||||
|
||||
**Why it could not be done here.** No Home Assistant instance is reachable from the
|
||||
dev host (nothing on `localhost:8123`), and the standalone route failed too: the
|
||||
refresh token in `.credentials.json` is expired, so `refresh_access_token()` returns
|
||||
`NotAuthorizedException: Refresh Token has expired`. Recovering it needs the browser
|
||||
@@ -54,6 +57,6 @@ fitted keg after the file was replaced wholesale.
|
||||
- [x] 6.1 Run `openspec validate --changes backport-keg-catalog` and fix any reported issues
|
||||
- [x] 6.2 Commit in the worktree with a message explaining the provenance of the data and naming the 4 corrections
|
||||
- [x] 6.3 Mark tasks complete and commit the artifact updates in the main checkout
|
||||
- [ ] 6.4 Sync the `entities` delta into `openspec/specs/entities/spec.md`
|
||||
- [ ] 6.5 Merge `agent/backport-keg-catalog` into `master`, push, and archive the change
|
||||
- [ ] 6.6 Remove the worktree and branch: `git worktree remove .worktree/backport-keg-catalog --force && git branch -d agent/backport-keg-catalog`
|
||||
- [x] 6.4 Sync the `entities` delta into `openspec/specs/entities/spec.md`
|
||||
- [x] 6.5 Merge `agent/backport-keg-catalog` into `master`, push, and archive the change
|
||||
- [x] 6.6 Remove the worktree and branch: `git worktree remove .worktree/backport-keg-catalog --force && git branch -d agent/backport-keg-catalog`
|
||||
@@ -42,6 +42,50 @@ The integration SHALL expose the keg's remaining volume as a percentage.
|
||||
- **THEN** the sensor SHALL report `details.kegVolume / 6.0 * 100` rounded to 1 decimal
|
||||
- **THEN** it SHALL have unit %, state class MEASUREMENT, and icon mdi:keg
|
||||
|
||||
### Requirement: Keg product ID sensor
|
||||
The integration SHALL expose the numeric product ID of the keg currently fitted in the machine, extracted from the API's `kegActive.keg` resource reference.
|
||||
|
||||
#### Scenario: Product ID extracted from resource reference
|
||||
- **WHEN** the coordinator has data AND `kegActive.keg` holds a resource reference
|
||||
- **THEN** the sensor SHALL report the trailing path segment of that reference as an integer
|
||||
- **THEN** it SHALL have icon mdi:barcode
|
||||
|
||||
#### Scenario: No keg fitted
|
||||
- **WHEN** `kegActive.keg` is absent or empty
|
||||
- **THEN** the sensor SHALL report no value
|
||||
|
||||
#### Scenario: Reference is not numeric
|
||||
- **WHEN** the trailing path segment of `kegActive.keg` cannot be parsed as an integer
|
||||
- **THEN** the sensor SHALL report no value and SHALL NOT raise
|
||||
|
||||
### Requirement: Keg name sensor
|
||||
The integration SHALL expose the name of the tapped beer, resolved from the keg product ID through a catalog bundled with the integration at `keg_catalog.json`. The catalog SHALL cover every keg the PerfectDraft app can select, including discontinued kegs that may still be fitted in a machine, and SHALL contain at least 114 product IDs.
|
||||
|
||||
Catalog entries SHALL be observed directly from a machine reporting that product ID rather than inferred from shop listings, because the product IDs cannot be queried in bulk from the API. Entry names SHALL be the beer's name only, excluding shop-listing artefacts such as pack size, "Short Date" prefixes, or best-before dates.
|
||||
|
||||
#### Scenario: Known product ID resolves to a name
|
||||
- **WHEN** the keg product ID is present in the catalog
|
||||
- **THEN** the sensor SHALL report the catalog's name for that ID
|
||||
- **THEN** it SHALL have icon mdi:beer
|
||||
|
||||
#### Scenario: Unknown product ID
|
||||
- **WHEN** the keg product ID is not present in the catalog
|
||||
- **THEN** the sensor SHALL report no value
|
||||
|
||||
#### Scenario: No keg fitted
|
||||
- **WHEN** no keg product ID can be determined
|
||||
- **THEN** the sensor SHALL report no value
|
||||
|
||||
#### Scenario: Catalog unreadable or malformed
|
||||
- **WHEN** `keg_catalog.json` is missing or cannot be parsed
|
||||
- **THEN** the integration SHALL treat the catalog as empty and continue loading
|
||||
- **THEN** the keg name sensor SHALL report no value while every other entity SHALL be unaffected
|
||||
|
||||
#### Scenario: Catalog format
|
||||
- **WHEN** the catalog file is read
|
||||
- **THEN** it SHALL be a flat JSON object mapping the product ID as a string key to the display name as a string value
|
||||
- **THEN** keys SHALL be ordered numerically
|
||||
|
||||
### Requirement: Connection sensor
|
||||
The integration SHALL expose the machine's connectivity status.
|
||||
|
||||
@@ -162,4 +206,4 @@ All entities SHALL have translated names via `translation_key` and corresponding
|
||||
|
||||
#### Scenario: Names displayed
|
||||
- **WHEN** HA renders the entity list
|
||||
- **THEN** each sensor SHALL display its translated name (Temperature, Keg Remaining, Connection, Door, Pours, Last Pour, Firmware, Mode, Keg Freshness)
|
||||
- **THEN** each sensor SHALL display its translated name (Temperature, Keg Remaining, Keg Product, Keg, Connection, Door, Pours, Last Pour, Firmware, Mode, Keg Freshness)
|
||||
|
||||
Reference in New Issue
Block a user