houseplan-card/docs/reviews/SPEC-REVIEW-213-r1.md

SPEC-REVIEW-213-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/213
• Этап: ТЗ на ревью (S4-spec-review), PROCESS.md §2.4
• Артефакт под ревью: docs/specs/213-device-marker-geometry.md
• Трек: обычный (не small/trivial — подтверждено аналитикой в issue: сложность 7/10, несколько поверхностей, изменение принятого визуального контракта, влияние на touch-hover; наличие файла в docs/specs/ корректно).
• Ревьюер: Claude, ревью ТЗ (роль отделена от автора — Codex).

Вердикт

Зелёный. High: 0 · Medium: 0 · Low: 1 (снят с записью, см. ниже).

Скоуп ревью

Проверено: тело issue #213 и все три комментария (аналитика, occupancy, готовность ТЗ), ТЗ docs/specs/213-device-marker-geometry.md целиком (§1–23), обязательные разделы по PROCESS.md §7.1, соответствие docs/SCOPE.md (J1/J2/J7), docs/UX-MODES.md (pointer modality/hover ownership), docs/TOUCH-SUPPORT.md (hover — mouse-only, instance-local), docs/USER-GUIDE.ru.md (терминология LQI/hover/lock), а также фактическое состояние затронутого кода — не как источник вердикта по AC (это код-ревью), а чтобы отличить обоснованное техническое утверждение ТЗ от неотмеченной догадки.

Как проверялось

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md (процесс, классы изменений, лимит циклов, шаблон вердикта).
2. Прочитано тело issue #213 и все комментарии, включая явные решения владельца (6 пунктов) и итог аналитики («Продуктовые вопросы: отсутствуют. Владелец уже зафиксировал…»).
3. Прочитан весь файл docs/specs/213-device-marker-geometry.md.
4. Сверены количественные и технические утверждения ТЗ с фактическим кодом, чтобы отличить обоснованное решение от невыделенной догадки:
   • src/styles.ts:1886,2569 — подтверждён отдельный поздний --device-visual-factor: 0.9 в .dev и .vacpuck (§3, §8.1 ТЗ);
   • src/styles.ts:2039 — подтверждён текущий MDI viewport 0.5 × --dev-size (§8.2 ТЗ: переход на 0.55, что математически ровно +10%);
   • src/houseplan-card.ts:17814-17818, src/styles.ts:764-789 — подтверждён «старый компактный круг» oplock и зелёный #66d17a для locked вместо чёрного/белого пакета #179 (§3, §10 ТЗ);
   • src/logic.ts:8-11 (lqiColor, непрерывный HSL-градиент) и src/device-presentation.ts:46-56 (markerLqiColor, три дискретные категории) — подтверждено расхождение, которое ТЗ §12 предлагает устранить, возвращая маркер к формуле lqiColor();
   • src/device-pulse.ts:35-37 — подтверждено, что три цвета пакета #179 (#F0410C/#F0A00C/#1DC21D) остаются семантическими цветами pulse/alert независимо от маркерного LQI, как утверждает §12 ТЗ («остаются semantic colors других состояний»);
   • docs/specs/211-device-icons-visual-parity.md:159-164 — подтверждён источник «amber #F0A00C, owner override для Dark Unlock» и docs/specs/179-device-icons-redesign.md:487-501 — источник термина «No-Blur» (§10.1 ТЗ), то есть оба не являются изобретёнными фактами;
   • docs/specs/212-device-icons-polish.md:128,298,382 — подтверждён действующий контракт 44×44 CSS px, который ТЗ переносит как неизменяемый (§8.3, AC4);
   • docs/USER-GUIDE.ru.md:853,916 — подтверждено текущее пользовательское описание («три фиксированных диапазона» у маркера против «градиент» у заливки комнаты), что ТЗ явно планирует привести к единой формуле и обновить в release-артефактах (§21).
5. Проверена каждая из 13 AC на однозначность и наличие способа доказательства (unit/source, browser smoke, golden, review кода) — см. таблицу ниже.
6. Проверено, что предположения автора (не наблюдаемые пользователем детали) явно вынесены в §23 «Принятые технические предположения» отдельным блоком, а не растворены в тексте как факт.

Находки

Нет находок уровня High или Medium.

Low — оставлено с запиской (не блокирует)

L1. Не явно, распространяется ли рост MDI-viewport на +10% (§8.2) на внутренний глиф .vacpuck. .vacpuck ha-icon использует отдельное отношение puck-size × 0.68 (src/styles.ts:2598), которое ТЗ не упоминает явно ни в §8.2 (только «default, custom MDI и state-swapped glyph»), ни в списке «не входит в задачу» (§7). Формально vacuum puck упомянут в Scope (§6) только в контексте базового размера («base-size resolution… including vacuum puck»), а не MDI-глифа — то есть при внимательном чтении вопрос закрыт (владелец говорил «MDI-иконку внутри круга», имея в виду круглый Icon-маркер, а не puck), но явная фраза «размер MDI-глифа vacuum puck не меняется» сняла бы двойное толкование. Решение ревьюера: снимается без правки ТЗ — довод §6 vs §8.2 достаточен, доказательство того же рода уже требуется по AC2 («не клиппится на минимальном размере»), а расширение или нерасширение puck-glyph не меняет ни один AC и не расширяет/сужает скоуп. Автор кода может подтвердить любое из двух прочтений комментарием в реализации без нового продуктового решения.

Проверено и корректно

• Обязательные разделы §7.1 присутствуют: сценарий/персона (§1), что человек увидит до/после (§2), проблема (§3), scope/не-scope (§6-7), контракт поведения (§8-12), UX/a11y/touch (§13), данные/миграция/i18n (§14), архитектурный контракт (§15), edge cases (§16), AC1-13 с доказательством (§17), план автотестов (§18), риски (§19), откат (§20), release-артефакты (§21).
• Каждый AC однозначен и несёт способ доказательства — AC1 (size) unit+browser matrix+reference; AC2 (glyph) source+smoke+reference; AC3 (concentric) DOM+pixel-centroid smoke, red-before-fix; AC4 (anchor/parity) unit+smoke; AC5/AC6 (opening lock/security) visual matrix+существующие lock smokes; AC7/AC8 (hover/action boundary) real PointerEvent smoke; AC9/AC10 (LQI color/only-color) pure tests + existing room fill regression; AC11 (compat) serialization unit + review; AC12 (perf) source review + pre-beta smoke; AC13 (release artifacts) docs diff + check-docs.
• Технические утверждения не являются непроверенными догадками. Каждое количественное расхождение, которое ТЗ приводит как «подтверждённая причина» (0.9-фактор, MDI 0.5, зелёный oplock.locked, три дискретных цвета LQI против непрерывного lqiColor()), прямо соответствует текущему коду — не изобретено и не оставлено голым утверждением.
• Технические предположения корректно отделены от продуктовых решений. §23 содержит 7 пунктов, помеченных «принято предположительно, ревьюер может оспорить», и все семь — действительно ненаблюдаемые пользователем детали (footprint замка, unknown-asset, hover-vs-action границы, band/color separation, база нормализации, калибровка pixel-threshold, выбор layout-подхода), а не скрытые продуктовые решения.
• Отсутствие открытого продуктового вопроса обосновано, а не замалчивается. Комментарий аналитики прямо указывает, что все шесть решений уже зафиксированы владельцем в теле issue до начала ТЗ — это единственный легитимный случай нулевого вопроса на сложной задаче (решение уже принято раньше, а не пропущено).
• Совместимость и откат. §14 верно квалифицирует отсутствие миграции/новых полей (только фактический размер/цвет меняются, схема и сериализация — нет); §20 даёт однокоммитный откат без миграции данных. Соответствует docs/CONFIG-COMPATIBILITY.md (нет новых compatibility-полей, ничего материализуется при Open→Save).
• Touch/UX-контракт согласован с канонами. §11/§13 корректно переносят инвариант docs/TOUCH-SUPPORT.md/docs/UX-MODES.md: hover instance-local, только настоящая мышь, touch/pen мгновенно снимает, compatibility-мышь не восстанавливает без нового реального ввода; редактор устройств — best effort, View/kiosk — блокирующий.
• Lock invariant не затронут. §10.2 сохраняет docs/SCOPE.md «Лок инвариант»: клик по значку замка только открывает карточку, unlock/lock — только явной кнопкой с подтверждением; AC6 отдельно доказывает это существующими lock-smokes.
• Трассируемость. Issue ↔ ТЗ ссылки в обе стороны на месте; трек и файл ТЗ выбраны верно (обычный трек, не small).

Чего не проверял

• Не проверялся реальный код реализации — на этом этапе (S4-spec-review) кода ещё нет, продуктовый код не менялся.
• Не прогонялись гейты/тесты/смоки — этап ТЗ этого не требует; гейты относятся к код-ревью (PROCESS.md §2.7, §8).
• Не проверялась точность списанных в §23 числовых threshold'ов («один layout quantum», «0.5 физического пикселя») с точки зрения реальной калибровки — это по определению откладывается на failing-before-fix/mutant доказательство в реализации (сам ТЗ явно это признаёт в §23 п.6), а не на утверждение, которое можно проверить чтением ТЗ.
• Отсутствие строки #213 (и #212) в таблице docs/specs/README.md не рассматривалось как находка: колонка/таблица помечена в PROCESS.md §7.3 как известный расходящийся артефакт на списание, не входит в обязательный DoR-чеклист §2.5, и тот же пробел уже есть у #212 — не регрессия, внесённая этим ТЗ.

Итог

ТЗ #213 добросовестно переводит шесть решений владельца в проверяемый контракт, корректно отделяет продуктовые решения от технических предположений, и все количественные утверждения о текущем поведении подтверждаются чтением актуального кода, а не являются непроверенными догадками. Единственная находка — Low, снята с запиской, не требует правки ТЗ. Задача готова перейти в S5-ready.