houseplan-card/docs/AUDIT-FUNCTIONAL.md

# Audit — functional integrity & gaps

> Snapshot: **2026-08-05**, product **v1.58.0**.
> Cross-check of claimed surface (README / STATUS / SCOPE) against code and
> tests. Mission lens: SCOPE.md — *spatial at-a-glance + quick act*.

## 1. Mission fit

SCOPE personas:

| Persona | Primary mode | Fit |
|---|---|---|
| Home admin | Plan / Devices / Background editors | Strong — full geometry + marker tooling |
| Household members | View | Strong — tap toggles, room cards, glow/climate |
| Guests / kiosk | View + `kiosk: true` | Strong — editors blocked, swipe/cycle |

Jobs J1–J7 are marked **Closed** in SCOPE; J4 (onboarding) still **partial**
(floors-import exists; registry-driven room *suggestions* do not). That matches
code reality.

**Systematicity grade: high.** Features hang off a coherent model:

- spaces → rooms (polygons) → derived walls → openings
- markers bound to device/entity/virtual → layout points
- settings tiers: global → space → room → device
- View is the product; editors are admin-colored frames (UX-MODES)

Excess features (PDF manuals, virtual devices, LQI) are consciously **kept /
frozen** rather than deleted — unusual and correct for a shipping tool.

## 2. Claim ↔ code matrix

| Feature area | Claimed | Implemented | Tested | Notes |
|---|---|---|---|---|
| One HACS package (integration + card) | ✓ | ✓ | CI hacs/hassfest | Matches |
| GUI room markup (no SVG/YAML) | ✓ | ✓ | smokes + logic units | Matches |
| Doors/windows + lock invariant | ✓ | ✓ | smoke_lock_*, logic | CR-1 held |
| Islands / merge / split / open_to | ✓ | ✓ | units + smokes | Matches |
| Room resize | ✓ | `resize.ts` | units + smokes | Matches |
| Decor + backdrop transform | ✓ | ✓ (v1.58) | backdrop tests/smokes | Paper = room contours |
| Infinite / square canvas | ✓ | ✓ | canvas smokes | Matches CANVAS.md |
| Align-to-grid | ✓ | `align-grid.ts` | units | Matches |
| Auto devices by HA area | ✓ | `devices.ts` | units | Matches |
| Explicit hide-from-plan | ✓ | ✓ | smokes | FILTERING.md |
| Editable icon rules | ✓ | ✓ | — | Matches |
| Tap: info / more-info / toggle / run / cover | ✓ | ✓ | logic + smokes | Security model intact |
| Glow + door sectors | ✓ | ✓ | smokes | Island light block = known limit |
| Temp / LQI / light fills | ✓ | ✓ | units/smokes | Matches |
| Room cards + per-room settings | ✓ | ✓ | smokes | Matches |
| Kiosk | ✓ | ✓ | smokes | Matches |
| Vacuums + server trails | ✓ | `vacuum.ts` + `trails.py` | units + smokes | Display-only (intentional) |
| Sun / daynight / wedges | ✓ | `sun.ts` | units + smokes | Matches |
| `houseplan-space-card` | ✓ | ✓ | smokes | Matches |
| Signed content + SVG sandbox | ✓ | ✓ | HA tests + smokes | Matches |
| en/ru i18n | ✓ | ✓ | key-parity test | Matches |
| Floors-import wizard | ✓ | ✓ | — | Exists; suggestions gap below |
| Registry room suggestions | PRODUCT / J4 | **Partial / missing** | — | Gap |
| Music notes / TV ripples | UX backlog | **Absent** | — | Intentional not-planned |
| Furniture / wall CAD | competitor feature | **Absent** | — | Non-goal |
| Vacuum commands | user ask often | **Absent** | — | VACUUM.md non-goal |
| Cloud sync | — | **Absent** | — | Non-goal |

**Integrity conclusion:** marketed surface and shipped surface align unusually
well. The main integrity risks are **docs drift** (ARCHITECTURE/UX-MODES/PRODUCT)
and **auth UI↔API default mismatch** (see AUDIT-QUALITY), not phantom features.

## 3. Cross-cutting integrity themes

### 3.1 Coordinate & geometry story — coherent after evolution

Legacy fixed pixel canvas → normalized square → infinite canvas with bounds.
Migrations + `geometry/repair` + dual-store `geom_pending` show the team treats
coordinate changes as product-critical (correct). Frontend `space-geometry.ts`
and backend `validation.py` intentionally mirror limits (±5000) — two sources of
truth, but tested.

### 3.2 Security story — mostly coherent

| Surface | Policy | Coherent? |
|---|---|---|
| Lock / alarm from plan icon | Never actuate | Yes — tested |
| Lock via door-card button | Explicit labeled control | Yes — SCOPE CR-1 |
| SVG plans | Sandbox CSP + signing | Yes |
| Config/layout writes | `may_write` | **Split** with UI admin gate |
| `run` tap | automation/script/scene only + optional confirm | Yes |

### 3.3 Multi-client story — mostly coherent

Config writes: CAS + write chain. Layout point updates: rev bumps but **no**
conflict surface — fine for one editor, weak for two tablets dragging at once.

### 3.4 Filtering story — cleaned up

Old hardcoded “dacha DNA” filters → editable icon rules + explicit hide flags
(v1.51). Documented in FILTERING.md. Good systematic cleanup.

## 4. Gaps (build only with intent)

### In-mission polish (SCOPE already lists most)

| Gap | Persona impact | Notes |
|---|---|---|
| Registry-driven room suggestions | Admin first-run | J4 partial; biggest *product* unlock left |
| Touch ergonomics of editors | Admin on tablet | Partial |
| Value-display richness | Household | Partial |
| a11y beyond `prefers-reduced-motion` | All | Keyboard/ARIA weak |
| Plan-level security glance (“N open / all locked”) | Household / kiosk | SCOPE known gap |
| Person / presence in rooms | Household | SCOPE known gap; presence ripples exist at marker level |
| Threshold colouring for room metrics | Household | SCOPE known gap |
| README / screenshot lag vs redesign | Adoption | Distribution, not function |

### Engineering gaps that feel like product bugs

| Gap | Why it matters |
|---|---|
| Default `admin_only=False` while UI hides editors from non-admins | Non-admin can still mutate via raw WS — surprise vs household persona |
| Opening-measure magnet placement flake under pinned Chromium | One smoke red; pixel-precision path |
| Demo.html needs hass nudge / F5 for icons | Harness quirk; confuses manual demo in a raw browser |

### Explicit non-gaps (do not “fix” by building these)

- 3D / glb
- Furniture / wall drawing (easy-floorplan territory)
- Vacuum start/zone commands
- History graphs, cameras, energy
- Cloud collaboration
- Becoming a general dashboard framework

## 5. Systematicity scorecard

| Question | Answer |
|---|---|
| Is there one mental model? | Yes — spaces/rooms/markers/settings tiers |
| Do modes prevent tool leakage? | Mostly — UX-MODES + kiosk hard-block; View is default |
| Are overrides predictable? | Yes — more specific settings win |
| Do security rules have a single owner? | Tap: `resolveTapAction`. Write: `may_write` (UI duplicate — debt) |
| Are frozen excesses documented? | Yes — SCOPE excess audit |
| Is the roadmap still pointing at the mission? | Phase 8–10 are quality/distribution; Phase 9 leftovers are registry/docs — aligned |

**Grade: A− for functional systematicity.** The product feels designed, not
accreted — with the structural exception of the Lit shell size (quality debt,
not a feature-model debt).

## 6. Suggested integrity checks for future agents

Before merging a feature:

1. Does it serve J1–J7 or a SCOPE “known gap”? If neither → reject or rewrite.
2. Does it introduce a second policy for taps, writes, or file deletion? → fold
   into `resolveTapAction` / `may_write` / collection rules.
3. Does it need a migration? → dual-store / repair path, not silent reshape.
4. Is it tested at the right layer? Pure math → `npm test` / pytest; pointer UX
   → smoke with `check`/`finish`; never a smoke that always exits 0.
5. Dual CHANGELOG + STATUS/ARCHITECTURE/TESTING updates in the **same** commit.