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

SPEC-REVIEW-57-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/57
• ТЗ под ревью: docs/specs/057-color-opacity-picker.md (коммит b8d2613a18f53f0d1bae9e02d9966496d49ad22d, ветка issue/57-color-opacity-picker)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: обычный (метки issue: P3, polish, tech-debt, S4-spec-review — метки small/trivial нет), файл в docs/specs/ создан корректно, а не ТЗ в теле issue.
• Цикл: r1/4

Скоуп ревью

Проверялось соответствие ТЗ:

• docs/SCOPE.md — легитимность задачи как editor usability polish, а не расширение продукта за пределы job'ов;
• PROCESS.md §2.4, §2.5 (DoR), §7.1 (обязательные разделы), §3/§12 (в т.ч. «догадка вместо решения», Medium → отдельный issue);
• AGENTS.md — классы файлов, ветка, трейлеры коммита ТЗ;
• docs/TOUCH-SUPPORT.md — контракт editors (best effort) и требование явной метки Touch editor: … для новых editor-фич;
• полному тексту issue #57 и всем трём комментариям (аналитика с Q1 и предложенным default, решение владельца по Q1, финальный хендофф автора);
• фактическому состоянию src/hp-color-opacity.ts и src/floating-surface-controller.ts — на предмет того, что технические утверждения ТЗ о существующей инфраструктуре (#68) не выдуманы;
• фактическим call sites hp-color-opacity и связанных цветовых настроек в src/houseplan-card.ts — на предмет полноты списка «Existing call sites» (§12/§16 ТЗ) относительно текста issue («decor, room colors, ripple»).

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

1. Прочитан весь тред issue #57 (gh issue view 57 --json body,comments): исходное описание (research task → recommendation → swap behind hp-color-opacity API, явно называет три категории call sites: "decor, room colors, ripple"), аналитика 2026-08-14 (ценность 4/10, сложность 4/10, риск 5/10, P3, обычный трек, один продуктовый вопрос Q1 с default), решение владельца 2026-08-15 по Q1 («убрать вложенность: один клик — одна поверхность с цветом и прозрачностью вместе, без второго системного dialog»), финальный комментарий автора со ссылкой на коммит и файл ТЗ. Вопрос задан корректно — единственный, продуктовый, с default; ни одного технического вопроса владельцу не эскалировано.
2. Сверены обязательные разделы ТЗ (§7.1 PROCESS.md) построчно — таблица ниже.
3. Прочитан текущий src/hp-color-opacity.ts целиком: подтверждено, что проблема из §3 ТЗ реальна — _pickerTemplate() (строка 347) рендерит <input type="color"> внутри popover-поверхности, то есть первый клик открывает House Plan popover, а сам цвет по-прежнему делегирован системному <input type=color> без alpha. Формулировка проблемы не голословна.
4. Прочитан src/floating-surface-controller.ts и registerOverlay в src/hp-dialog.ts:365 — оба реальны, используются уже сегодня в hp-color-opacity.ts. Ссылки ТЗ §7/§9/§10 на «общий floating-surface/ overlay lifecycle из #68» и «exclusive transient surface, конкурирующая с hp-help» подтверждены существующим кодом и терминологией docs/specs/068-help-affordance.md:50 («одна exclusive transient- поверхность на диалог, hp-help и hp-color-opacity используют один контракт»), а не изобретены заново.
5. Проверены заявленные в §12 ТЗ «Existing call sites» построчным поиском <hp-color-opacity в src/houseplan-card.ts: найдены decor color/fill (строки 9152, 9167, 9325, 9395, 9442), marker Glow override (17917, showOpacity=false подтверждён на 17918), room/space custom fill (18365, 18549). Список ТЗ для этих сайтов точен.
6. Тем же поиском по всему файлу найдена «третья» линия цветовых контролов, которая не проходит через hp-color-opacity вовсе: _renderColorRow() (houseplan-card.ts:13477-13487) — рендерит голый <input type="color"> рядом с отдельным <input type="range">, без единого swatch/popover. Используется 11 раз в диалоге "Общие настройки" (gs.*): light_on/off/none (14003-14005), temp_cold/ok/hot (14007-14009), lqi_low/high (14011-14012), glow_base/glow_light (14014-14015), wall_fill (14028) — тот же класс проблемы («второй клик по цвету — системный picker без прозрачности», здесь даже без единого swatch), но не упомянуто ни в §12 (call sites), ни в §16 (затронутые поверхности), ни в §5 (не входит в задачу) ТЗ.
7. Отдельно проверено значение слова «ripple» из текста issue: marker activity color (rippleColor, houseplan-card.ts:18087-18090, тип ripple_color в types.ts:1442) — тоже голый <input type="color"> без hp-color-opacity и без alpha. Это ровно та категория, которую issue называет по имени («decor, room colors, ripple») — и она отсутствует в §12 ТЗ, который вместо неё называет «marker Glow override» (уже мигрировавший на hp-color-opacity компонент, не требующий работы). См. Medium-1 ниже.
8. Проверено наличие требуемой docs/TOUCH-SUPPORT.md буквальной декларации Touch editor: … — отсутствует; см. Low-1.
9. Проверены трейлеры и class-принадлежность: git show b8d2613 --stat показывает только docs/specs/057-color-opacity-picker.md и docs/specs/README.md (класс C, ни одного файла класса A — правило №1 AGENTS.md соблюдено, продуктовый код не тронут на этапе ТЗ). Коммит несёт Issue: #57 и User-Visible: no — корректно для документа класса C. docs/specs/README.md обновлён тем же коммитом, ссылка issue↔ТЗ в обе стороны на месте.
10. Проверено существование release-артефактов, которые §18 ТЗ обещает обновить: docs/TESTING.md, docs/CHANGELOG.md, docs/CHANGELOG.ru.md, docs/USER-GUIDE.ru.md — все существуют, ссылки не на несуществующие файлы.
11. Проверены i18n-конвенции: явные ключи не перечислены буквально (только человеко-читаемые названия controls в §13), но такой же уровень детализации принят в прошедшем ревью docs/specs/068-help-affordance.md (тоже описывает механизм именования, а не конкретные строки) — не считаю это дефектом при спек-ревью, конкретные ключи — свободное техническое решение реализации.

Обязательные разделы (§7.1 PROCESS.md)

Раздел	Есть	Комментарий
Сценарий (персона/поверхность/момент)	✅	§1 — home admin, editor-диалоги, момент клика по образцу цвета
Что человек увидит до/после	✅	§2, одна фраза до/после, без глубоких implementation-терминов
Проблема (с подтверждённой причиной)	✅	§3, подтверждена чтением hp-color-opacity.ts (см. «Как проверялось» п.3)
Скоуп / не-скоуп	⚠️	§4/§5 — полны для перечисленного, но не покрывают все call sites из текста issue, см. Medium-1
Контракт поведения	✅	§7 (interaction contract), §8 (значения/преобразования)
Модель данных и миграция	✅	§12 — API/schema неизменны, обоснованно (presentation-only компонент)
UX, i18n, accessibility, touch	✅	§9-11, §13; touch — см. Low-1 (нет буквальной метки)
AC1…ACn с доказательством	✅	§14, 9 штук, у каждого назван способ доказательства (unit/smoke/golden/build artifact)
План автотестов	✅	§15, unit/smoke/golden/performance по отдельности
Риски	✅	§17, таблица риск/мера, 5 строк
Откат	✅	§17 — public API и данные неизменны, откат = revert реализации
Release-артефакты	✅	§18, конкретные существующие документы, оба changelog в одном User-Visible: yes коммите

Присутствует и явный блок «Принятые технические предположения» (§19) — разделение продуктового/технического, которого требует §7.1: 5 пунктов, всё базовая реализация/API-неизменность, не user-facing решения.

Находки

Medium-1 — ТЗ молча сужает названные в issue call sites: «ripple» пропущен, параллельная семья «Общие настройки» не упомянута вовсе

Файл: docs/specs/057-color-opacity-picker.md:179-181 (§12, «Existing call sites»), :253-259 (§16, «Затронутые поверхности»), :46-54 (§5, «Не входит в задачу») против src/houseplan-card.ts:13477-13487 (_renderColorRow), :14003-14028 (11 вызовов), :18087-18090 (rippleColor).

Issue #57 явно перечисляет три категории call sites, которые должны обновиться «at once»: «decor, room colors, ripple». ТЗ §12 вместо этого называет «decor stroke/fill/text/furniture, room/space custom fill и marker Glow override» — «ripple» нигде не упомянут, ни в scope, ни в §5 «Не входит в задачу» как явно отложенный пункт. Проверка кодом подтверждает: marker ripple_color (houseplan-card.ts:18089, «Marker: activity color» в диалоге) — это голый <input type="color">, вообще не использующий hp-color-opacity, то есть требующий такой же работы, как и остальные call sites, но не включённый в контракт, AC или тестовый план.

Дополнительно обнаружена целая параллельная реализация того же паттерна: _renderColorRow() (houseplan-card.ts:13477-13487) рендерит <input type="color"> рядом с отдельным <input type="range"> — тот же класс проблемы, который issue описывает как причину задачи («второй клик по цвету — системный picker без прозрачности»), только даже без единого swatch. Она используется 11 раз в диалоге "Общие настройки" для light_on/off/none, temp_cold/ok/hot, lqi_low/high, glow_base/glow_light, wall_fill — именно тех состояний, вокруг которых построены J1/J5/J7 SCOPE.md (живая заливка комнат по свету/температуре/LQI). Она не упомянута ТЗ вовсе — ни как included, ни как explicitly excluded.

Воспроизведение: после реализации ТЗ как написано, пользователь по-прежнему встретит исходную проблему (второй клик по цвету открывает системный picker, прозрачность теряется/недоступна одновременно) на: (1) marker "activity color" (инструмент разметки, диалог устройства, display: icon_ripple) — явно названный issue как «ripple»; (2) любом из 11 полей диалога "Общие настройки". То есть заявленная в issue ценность «all call sites... upgrade at once» достигается лишь частично, и в самом ТЗ этот пробел не зафиксирован как осознанное решение — то есть выглядит как полное покрытие, не будучи им.

Это не делает текущий контракт невыполнимым или непроверяемым — AC1-9 самодостаточны и проверяемы для того набора call sites, который ТЗ действительно перечисляет. Поэтому уровень Medium, а не High: реализация по этому ТЗ работает и не содержит логической ошибки, дефект — в неполноте заявленного покрытия и в тишине вокруг этой неполноты.

Решение ревьюера: Medium, заведён отдельным issue #180 со ссылкой на #57, метки tech-debt/P3/S1-new. Не блокирует S5-ready. Рекомендация автору — на выбор: (а) явно перечислить ripple в §12/§16 и включить в объём этого issue, раз он и так использует тот же компонент с showOpacity=false по образцу Glow (стоимость мала, паттерн уже есть); либо (б) добавить одну строку в §5 «Не входит в задачу», явно называющую ripple и "Общие настройки" state-color rows отложенными в #180 — чтобы ТЗ не выглядело полным покрытием, будучи им лишь частично. Выбор (а)/(б) — не продуктовый вопрос сам по себе (объём этого конкретного issue уже решён владельцем неявно: он не разбирал этот список построчно), поэтому это может решить сам автор технически; если он предпочтёт спросить владельца — это корректный продуктовый вопрос («входит ли ripple в объём #57») с default (б).

Low-1 — нет буквальной декларации Touch editor: … по docs/TOUCH-SUPPORT.md

Файл: docs/specs/057-color-opacity-picker.md:124-137 (§9)

docs/TOUCH-SUPPORT.md, раздел «Documentation rule», требует, чтобы новая спецификация editor-фичи явно указывала одно из: Touch editor: supported / best effort / intentionally degraded / not exposed. §9 ТЗ подробно описывает, что сам picker получает «явную touch-поддержку» (pointer capture, multi-touch safety, 40×40 touch targets), но не содержит буквальной строки формата Touch editor: …. Тот же класс замечания последовательно фиксировался как Low в прошлых спек-ревью этого репозитория (SPEC-REVIEW-89-r1, SPEC-REVIEW-122-r1, SPEC-REVIEW-141-r1, SPEC-REVIEW-146-r1), включая прецедент docs/specs/068-help-affordance.md:10 («Touch editor: поддерживается для самого affordance» — компонент, получающий явную touch-гарантию поверх общего best-effort правила редакторов, ровно как здесь).

Решение ревьюера: Low, не блокирует. Рекомендация — добавить одну строку вида «Touch editor: supported (сам picker; остальные операции родительских редакторов остаются best effort по docs/TOUCH-SUPPORT.md)» рядом с §9. Оставляю на усмотрение автора; фиксирую здесь как условие «низкое либо правится, либо снимается с записью» (§3.8 PROCESS.md) — снимаю без правки, так как содержательно требование уже выполнено прозой, отсутствует только буквальный формат метки.

Что проверено и корректно

• Соответствие docs/SCOPE.md: задача — editor usability polish, не создаёт нового продуктового job'а и не расширяется на профессиональный графический редактор (владелец явно закрыл этот вопрос в аналитике: «в scope как editor usability, но без необходимости создавать профессиональный графический редактор»); эксплуатирует существующие J1/J4/ J5/J6/J7 через editor usability, не создавая нового.
• Легитимность полного трека: issue не помечен small/trivial, файл ТЗ в docs/specs/ создан по правилу (не в теле issue) — соответствует сложности 4/10 и множеству поверхностей (decor/room/space/marker).
• Продуктовый вопрос закрыт по процессу: единственный вопрос Q1 («насколько сложным должен быть picker») задан батчем с default, blocked был выставлен и снят владельцем при ответе; технических вопросов владельцу не эскалировано.
• Главное решение владельца воспроизведено точно: §7 ТЗ («один клик — одна поверхность, где сразу доступны цвет и прозрачность, без вложенного системного picker») дословно соответствует формулировке владельца в комментарии от 2026-08-15.
• Технический диагноз §3 не голословен — подтверждён прямым чтением src/hp-color-opacity.ts (см. «Как проверялось» п.3): текущий компонент действительно делегирует цвет <input type=color> внутри своего popover.
• Инфраструктурные ссылки на #68 (FloatingSurfaceController, registerOverlay, «exclusive transient surface») реальны и точны — подтверждены существующим кодом floating-surface-controller.ts и hp-dialog.ts:365, а не изобретены.
• Перечисленные (не все, см. Medium-1) существующие call sites точны — все указанные в §12 использования <hp-color-opacity> найдены построчно в houseplan-card.ts с совпадающей семантикой (showOpacity=false для Glow подтверждён).
• API/compatibility (§12) корректно не расширяет config/storage schema — оправданно: изменяется только внутренняя реализация presentation-only компонента, внешний контракт (color, opacity, событие) не меняется.
• Bundle-budget (§6, §14 AC8) сформулирован как измеримый критерий с точным способом доказательства (exact production build artifact, raw+gzip), включает условный путь для vendored-альтернативы с теми же ограничениями — не оставляет технический выбор недоказуемым.
• AC1-AC9 однозначны и снабжены допустимым по §2.5 PROCESS.md способом доказательства (unit/smoke/golden/review), ни один не оставлен неопределённым.
• Release-артефакты (§18) ссылаются на существующие файлы документации, оба changelog в одном User-Visible: yes коммите — соответствует правилу 11 PROCESS.md.
• Трассируемость: docs/specs/README.md обновлён тем же коммитом (раздел «P3», ссылка на ТЗ); коммит b8d2613 несёт Issue: #57, User-Visible: no, класс C — корректно для документа ТЗ. git show --stat не содержит ни одного файла класса A — правило №1 AGENTS.md соблюдено.
• «Принятые технические предположения» (§19) корректно отделяют свободные для автора реализации решения от продуктового контракта — соответствует требуемой в §7.1 PROCESS.md структуре.

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

• Не прогонял никаких гейтов (typecheck/test/build/golden/смоки) — на этапе ТЗ продуктовый код не существует, гейты неприменимы; существование упомянутых механизмов (FloatingSurfaceController, registerOverlay, demo/golden, docs/TESTING.md) проверено чтением файловой системы, а не исполнением.
• Не проверял реализуемость конкретной геометрии saturation/value field, round-trip toleranse ≤1 RGB channel или точный алгоритм hue-memory для achromatic цвета как кода — по тексту ТЗ (§19) это явно свободное техническое решение автора кода, подлежащее доказательству тестами на реализации/код-ревью, а не предмет ревью ТЗ.
• Не проверял точность числовых оценок аналитики (ценность 4/10, сложность 4/10, риск 5/10, P3) по существу — это поле владельца (PROCESS.md §2.2), уже принятое явным решением до написания ТЗ.
• Не проверял весь src/houseplan-card.ts построчно на предмет иных, ещё не найденных мест с голым <input type=color> за пределами уже идентифицированных _renderColorRow/ripple_color/bg_color — поиск был ограничен паттернами hp-color-opacity, input type=.?color.? и _renderColorRow через grep, не исчерпывающим построчным чтением всего файла (~18500 строк). bg_color (фон, без alpha) сознательно не включён в Medium-1: у него нет отдельного opacity-компонента, то есть не тот класс проблемы, который описывает issue.
• Не проверял, действительно ли docs/USER-GUIDE.ru.md требует конкретной правки текста прямо сейчас (спека верно откладывает точную формулировку в release-артефакты §18, реализация ещё не начата).

Вердикт

Зелёный. High: 0, Medium: 1 (заведён отдельным issue #180, не блокирует), Low: 1 (косметика, снята с записью в этом документе, не требует правки перед S5-ready). ТЗ корректно и проверяемо решает то, что само заявляет как скоуп: устраняет вложенный system picker для decor/room/space/Glow call sites, техническая база (#68) подтверждена чтением кода, продуктовый вопрос владельца закрыт по процессу. Единственный содержательный пробел — молчаливое сужение относительно явно названного в issue call site «ripple» и не упомянутой параллельной семьи «Общие настройки» — не делает написанный контракт невыполнимым, поэтому не блокирует, но обязан быть решён отдельно (issue #180) до того, как задача #57 будет считаться полным ответом на исходный запрос.