Applies the change's delta specs to the main specs and files the change under openspec/changes/archive/2026-09-16-scoped-beer-override. keg-auto-detection gains the scoped-override and override-visibility requirements, and its detection precedence is rewritten so no config value can precede detection except by matching the reported product ID. card-config drops the beer_name override requirement in favour of the beer_overrides map, and records beer_name alongside beer_entity as an ignored legacy key. Also corrects three stale beer_name references in beer-catalog and beer-label. The proposal's capability list missed those two specs; the substance of their requirements is unchanged, only the key name they name, so this is a naming correction rather than a requirement change. Co-authored-by: Cursor <cursoragent@cursor.com>
9.2 KiB
keg-auto-detection Specification
Purpose
TBD - created by archiving change auto-detect-gap-closure. Update Purpose after archive.
Requirements
Requirement: Tapped beer detected from integration sensors
The card SHALL determine the tapped beer from the PerfectDraft integration's keg sensors without requiring the user to select it.
Scenario: Keg sensors resolved for the configured device
- WHEN the card has a
device_idand the device exposes sensors with translation keyskeg_product_idandkeg_name - THEN the card SHALL resolve both entity IDs and read their states on every
hassupdate - THEN the card SHALL NOT require any beer-related configuration for detection to work
Scenario: Product ID matches a catalog entry
- WHEN the
keg_product_idsensor reports a state consisting only of digits that matches thekegIdof a catalog entry - THEN the card SHALL use that catalog entry for the beer's name, brand colors, style, ABV, and keg artwork
Scenario: Product ID does not match but a name is reported
- WHEN the
keg_product_idstate is absent, non-numeric, or matches no catalog entry, AND thekeg_namesensor reports a state other thanunavailableorunknown - THEN the card SHALL resolve the beer by that reported name against the catalog
- THEN if the reported name matches no catalog entry, the card SHALL display that name against the generic color palette
Requirement: Detection precedence
The card SHALL apply a single, defined precedence order when determining which beer to display.
Scenario: Precedence order
- WHEN the card determines the beer to display
- THEN it SHALL apply the first applicable source in this order: (1) a
beer_overridesentry whose key matches the reported product ID, (2) a catalog entry matched by reported product ID, (3) a beer resolved from the reported keg name, (4) the no-keg-detected state - THEN no later source SHALL override an earlier one
Scenario: Matching override wins over successful detection
- WHEN a
beer_overridesentry matches the reported product ID AND that same product ID also resolves to a different catalog entry - THEN the card SHALL display the beer named by the override entry
- THEN the card SHALL indicate that an override is in effect rather than substituting silently
Scenario: No configured value can precede detection unconditionally
- WHEN the card determines the beer to display
- THEN no config value SHALL take precedence over detection except by matching the currently reported product ID
- THEN a config value that names a beer without reference to a product ID SHALL NOT affect the displayed beer
Requirement: Curated name preferred for the label
When the card recognises the reported product ID, it SHALL use its own catalog name for display rather than the name reported by the integration.
Scenario: Product ID resolves and names differ
- WHEN the product ID matches a catalog entry AND the
keg_namesensor reports a different string for the same keg - THEN the card SHALL display the catalog entry's curated name
- THEN the card SHALL NOT display the integration-reported name
Scenario: Product ID does not resolve
- WHEN the product ID matches no catalog entry AND a usable
keg_namestate is reported - THEN the card SHALL display the integration-reported name, as it is the only name available
Requirement: No-keg-detected state
The card SHALL never display a specific beer that it has not detected, and SHALL make the absence of a detected beer visible.
Scenario: Sensors present but no keg reported
- WHEN both keg sensors are resolved but neither yields a beer, for example because both report
unknownorunavailable - THEN the card SHALL render a neutral palette with no keg photograph and no brewery logo
- THEN the card SHALL display a label indicating that no keg is detected
- THEN the card SHALL NOT display the name or branding of any catalog beer
Scenario: Detection never falls back to an arbitrary catalog entry
- WHEN no beer can be determined from any source in the precedence order
- THEN the card SHALL NOT select a beer by catalog position, insertion order, or any other arbitrary rule
Scenario: Other sensor values still shown
- WHEN the card is in the no-keg-detected state AND the temperature or freshness sensors report usable values
- THEN the card SHALL continue to display those values
Requirement: Integration version guidance
The card SHALL distinguish an out-of-date integration from an empty machine and guide the user accordingly.
Scenario: Device resolved but keg sensors absent
- WHEN the configured device resolves and a temperature sensor is found, but no sensor with translation key
keg_product_idorkeg_nameexists for that device - THEN the card SHALL display a message stating that the PerfectDraft integration must be updated to a version that provides the keg sensors
- THEN that message SHALL be distinct from the no-keg-detected state
Scenario: Keg sensors present but idle
- WHEN the keg sensors exist for the device but report no usable value
- THEN the card SHALL show the no-keg-detected state and SHALL NOT suggest updating the integration
Requirement: Entity resolution completes as entities appear
The card SHALL continue attempting entity resolution until the expected sensors are found, so that sensors registered after the card first renders are still discovered.
Scenario: Keg sensors appear after initial resolution
- WHEN the card has already resolved a temperature entity for its device AND the keg sensors are subsequently added to that device, for example because the user updated the integration
- THEN the card SHALL resolve the keg entities on a following
hassupdate without requiring a browser reload
Scenario: Resolution stops once complete
- WHEN all expected sensor entities for the device have been resolved
- THEN the card SHALL NOT repeat the registry scan on subsequent
hassupdates
Scenario: Configured device changes
- WHEN the card's configured
device_idchanges, for example because the user picked a different device in the editor - THEN the card SHALL discard the previously resolved entity IDs and the previously detected beer
- THEN the card SHALL resolve entities afresh for the newly configured device
- THEN the card SHALL NOT display values read from the previous device
Requirement: Manual override scoped to the reported keg
A manual override SHALL apply only while the machine reports the product ID that override was recorded against, so that a correction cannot outlive the keg it corrects.
Scenario: Override applies to the keg it was recorded for
- WHEN
beer_overridescontains an entry whose key equals the state of thekeg_product_idsensor - THEN the card SHALL display the beer resolved from that entry's value, resolved by catalog name, slug, or matching
custom_beersentry - THEN the card SHALL use that beer for the name, brand colors, style, ABV, and artwork
Scenario: Override does not apply to a different keg
- WHEN
beer_overridescontains entries AND none of their keys equals the reportedkeg_product_idstate - THEN the card SHALL ignore every entry and resolve the beer by detection
- THEN the card SHALL NOT display any beer named by a non-matching entry
Scenario: Override for an unrecognised product ID
- WHEN the reported
keg_product_idmatches no catalog entry'skegIdANDbeer_overridescontains an entry for that ID - THEN the card SHALL display the beer named by that entry
- THEN the card SHALL NOT fall back to the integration-reported keg name
Scenario: No override applies when no keg is reported
- WHEN the
keg_product_idsensor reports no usable state ANDbeer_overridescontains entries - THEN the card SHALL enter the no-keg-detected state
- THEN the card SHALL NOT display any beer named by
beer_overrides
Scenario: Override entry naming an unknown beer
- WHEN a matching
beer_overridesentry names a beer present in neither the catalog norcustom_beers - THEN the card SHALL display that name against the generic color palette
- THEN the card SHALL NOT fall back to detection, since a matching override signals the user's intent for this keg
Requirement: Active override is visible
When the card displays a beer because of an override rather than detection, it SHALL make that visible, so a user can tell an override from a detection result without reading config.
Scenario: Override applied
- WHEN the card displays a beer resolved from a matching
beer_overridesentry - THEN the card SHALL render an indication that an override is in effect
Scenario: Override contradicts detection
- WHEN an override is applied AND detection would have resolved a different beer for the same keg
- THEN the indication SHALL identify the beer that detection resolved
- THEN the card SHALL NOT silently present the override as a detection result
Scenario: No override applied
- WHEN the card displays a beer resolved by detection with no matching override
- THEN the card SHALL NOT render an override indication