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

SPEC-REVIEW-376-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/376 — «Пачка Low из аудита beta.4: title:null в space-card, roomlabel в Background, персист цвета декора, iso-штрихи мебели, стейл-док, truthy light_pools (а–е)»
• Этап: ТЗ на ревью (PROCESS.md §2.4), лёгкий трек (метка small)
• ТЗ: тело issue, раздел «# ТЗ (лёгкий трек, редакция 1)», зафиксировано updatedAt: 2026-08-29T17:34:47Z
• Материал ревью: тело issue #376 (аналитика + ТЗ, один автор, без дальнейших комментариев на момент ревью) сверено с dev на 4eede5bc
• Заход: r1 · блокирующих циклов израсходовано 1 из 2 (лёгкий трек)

Скоуп ревью

Первый заход — предыдущего вердикта нет, разбор полный. Проверялось: соответствие docs/SCOPE.md; корректность выбора трека small по §5 PROCESS.md (все критерии обязаны выполняться одновременно); обязательный минимальный шаблон лёгкого трека («проблема · контракт · AC1…ACn с доказательством · откат»); однозначность и доказуемость каждого AC; отсутствие догадок, выданных за факт; сверка каждого фактического утверждения ТЗ о текущем коде с исходниками.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком (жизненный цикл §2, лимит циклов §4, критерии трека §5, артефакты §7, гейты §8).
2. Прочитано тело issue #376 полностью (аналитика §2.2 + ТЗ §1–§6), других комментариев на issue нет.
3. Прочитан docs/CONFIG-COMPATIBILITY.md целиком — сверить, что такое «новое compatibility-поле» в терминах именно этого проекта, и подобрать аналог для пункта (в).
4. Найден и прочитан прямой прецедент: issue #369 («Аудит после v1.69.0-beta.3 (V5) — семь Low-находок») — структурно идентичный кейс: пачка несвязанных Low-находок из точно такого же adversarial-аудита. SPEC-REVIEW-369-r1.md и -r2.md зафиксировали: «Этап: ТЗ на ревью, полный трек (владелец назвал критерий «одна поверхность» §5 как не выполненный — семь несвязанных поверхностей)» и результатом стал файл docs/specs/369-audit-lows.md, а не ТЗ в теле issue.
5. Найден и прочитан второй релевантный прецедент: SPEC-REVIEW-372-r1.md (родитель пункта (а) этого issue) — там тот же самый компакт-контракт title тоже потребовал полного трека («аналитика назвала критерий small, который задача не проходит — новый UX-контракт для title»).
6. Каждое фактическое утверждение ТЗ о текущем коде сверено с dev, не принято на слово:
   • src/space-card.ts:811-813 — title = this._config.title !== undefined ? this._config.title : sp?.title || ''; :821 compactTopFrame: this._config.title === ''; :870 ${title ? html\
     … — подтверждён факт «nullуже скрывает заголовок (falsy), но кадр остаётся симметричным» и чтоundefined` (отсутствие ключа) не задета правкой.
   • src/space-card.ts:290-291 — if (!this._config.light_pools) disposeGlowRuntime(...) (truthy-гейт) против рендер-гейта :842 lightPools: this._config.light_pools === true — подтверждён факт: light_pools: 1 не dispose'ит рантайм (!1 ложно) и переходит в ветку _resolveGlowBlend() (:291), при этом пулы не рендерятся (1 !== true). Расхождение реально существует и воспроизводится по описанному пути.
   • src/styles/plan.styles.ts:863-865 — .stage.mode-decor .devlayer, .stage.mode-decor .devlayer *, .stage.mode-decor .dev::before { pointer-events: none; }; строки 617-619 несут независимое правило .stage.markup .roomlabel { pointer-events: auto; } для другого режима (markup, не mode-decor). .roomlabel рендерится внутри .devlayer (src/houseplan-card.ts:11064 открывает .devlayer, :11962 — class="roomlabel …" рендерится в этом поддереве) — заявление «.devlayer * перебивает предыдущий auto для roomlabel в Background» подтверждено: для mode-decor специфичность конкурирующих правил равна (0,3,0), и позже объявленное правило (:863) побеждает по порядку источника. Не код-правка — доку добавлять корректно, код не трогается.
   • custom_components/houseplan/validation.py:1883 — vol.Optional( "settings", default=dict): vol.Schema({...}, extra=vol.ALLOW_EXTRA) — номер строки и факт «опциональный settings-объект с ALLOW_EXTRA» подтверждены; это снижает риск нового ключа (старый бэкенд/фронт не ломается на неизвестном поле), но само по себе не влияет на классификацию трека — см. находку H1.
   • src/houseplan-card.ts:984 — private _decorStyle: DecorStyle = { ...DEFAULT_DECOR_STYLE } — подтверждено, поле только in-memory, персиста нет.
   • src/furniture.ts:392-406 (furniturePlanScreenScale) и src/houseplan-card.ts:8084 (вызов) — подтверждена формула Math.min(viewportW/viewW, viewportH/viewH); src/houseplan-card.ts:10791 (class=${isoLayers?.structural ? 'iso-floor-scene' : nothing}) и :10830 (preserveAspectRatio="none") подтверждают наличие отдельной iso-трансформации, под которую эта формула не рассчитана.
   • docs/TESTING.md:1704 — строка «static room cards show the same data/base projection but no live pools» подтверждена дословно, без оговорки про light_pools/#374.
7. Проверено отсутствие незакрытых меток неопределённости в тексте («уточнить», TBD, голый вопросительный знак вне markdown-разметки) — не найдено.

Находки

H1 (High, блокирует) — трек small не проходит собственные критерии §5 одновременно; прямой прецедент #369 уже разрешил тот же вопрос иначе

Файл: тело issue #376 (раздел «8. Трек» аналитики + весь раздел «ТЗ»).

Критерии §5 PROCESS.md обязаны выполняться все одновременно; ни один не допускает исключения по «сумме несложных правок». Этот пакет нарушает как минимум два:

1. «Одна поверхность (один диалог, один модуль, один эндпоинт)». Сама аналитика перечисляет поверхности: space-card.ts (а, е), доки (б, д), houseplan-card.ts + houseplan-editor-runtime.ts + validation.py (в), отдельная iso-ветка houseplan-card.ts (г). Это минимум четыре разных модуля продуктового кода плюс документация — не «один модуль» ни по какому прочтению.
2. «Нет миграции конфига и новых compatibility-полей». Пункт (в) вводит новый персистентный ключ settings.decor_default_style — новую серверную схему (validation.py), новый путь чтения при инициализации и новый путь записи с expected_rev. Это ровно тот класс изменения, который docs/CONFIG-COMPATIBILITY.md каталогизирует как compatibility-поле (пусть и низкого риска благодаря ALLOW_EXTRA — см. «Как проверялось» п.6), а не разрешённое исключение для лёгкого трека.

Это не абстрактное толкование: у проекта есть прямой прецедент с той же формой задачи. Issue #369 — пачка из семи Low-находок ровно того же adversarial-аудита — была явно переведена на полный трек с формулировкой владельца «семь несвязанных поверхностей» (SPEC-REVIEW-369-r1.md, SPEC-REVIEW-369-r2.md), и результат лёг в docs/specs/369-audit-lows.md, а не в тело issue. #376 повторяет ту же форму (пачка Low из аудита, затрагивающая несвязанные модули) без единого слова о том, почему в этот раз критерий «одна поверхность» вдруг выполнен. Второй, более узкий прецедент — issue #372 (прямой родитель пункта (а) этого issue): та же самая пара «header/compact frame» для title уже один раз потребовала полного трека («новый UX-контракт для title»), хотя по объёму правки была проще, чем нынешний пакет из шести пунктов.

PROCESS.md §5, последний абзац: «Если по ходу выясняется, что критерий нарушен (появилась миграция, задело второй модуль) — метка small снимается, issue возвращается в S3-spec и получает нормальный файл ТЗ. Это не провал, это ранняя диагностика.» Это именно тот момент.

Почему High, а не Medium. Ошибка классификации меняет саму форму процесса вокруг задачи: бюджет ревью (2 цикла вместо 4), обязательность файла docs/specs/376-*.md, необходимость завести отдельный полный ТЗ хотя бы для (в). Это нельзя «починить тем же комментарием» без реструктуризации задачи — по определению не Medium-в-скоупе.

Продуктовые решения владельца не оспариваются. Оба решения 29.08 (title: null ≡ ''; «цвет декора персистится в серверный конфиг») остаются в силе — это ответы на продуктовые вопросы, они не про трек. Находка касается исключительно процессной классификации, которая по PROCESS.md решается аналитиком/ревьюером техническим порядком, не владельцем.

Рекомендация (одна из двух, автор выбирает):

• Выделить (в) в отдельный issue на полном треке (серверная схема + кросс-модульный путь записи — ровно профиль, для которого полный трек существует), оставить (а, б, г, д, е) на small — это уже гораздо ближе к «одному модулю» каждый по отдельности и без нового персистентного поля; либо
• Снять small со всего #376 по образцу #369, написать docs/specs/376-*.md с полными разделами §7.1.

M1 (Medium, в скоупе) — раздел «откат» отсутствует полностью

Файл: тело issue #376, весь раздел «# ТЗ».

Минимальный обязательный шаблон лёгкого трека (PROCESS.md §5): «проблема · контракт · AC1…ACn с доказательством · откат». В тексте нет ни одного предложения о том, как откатить любую из шести правок. Особенно заметно для (в): текст не говорит, что происходит с уже записанным settings.decor_default_style при откате коммита/фронтенда — хотя ответ уже виден из кода (extra=vol.ALLOW_EXTRA, «Как проверялось» п.6: старый бэкенд/фронт читает конфиг с незнакомым ключом без ошибки), в ТЗ это нигде не зафиксировано как часть контракта.

Чем чинится в этой же задаче: один абзац — «откат: правки (а, б, г, д, е) — обычный git revert, поведения не переживают перезапуск процесса. (в): неизвестный ключ decor_default_style безопасно игнорируется старым бэкендом/фронтом (ALLOW_EXTRA); откат кода не требует отдельной обратной миграции, задокументированный дефолт DEFAULT_DECOR_STYLE продолжает действовать.»

M2 (Medium, в скоупе) — пункты (б) и (д) заявлены в скоупе, но не имеют собственного AC

Файл: тело issue #376, раздел «## 2. AC» против раздела «## 1. Объём».

Раздел «Объём» явно называет (б) (предложение в USER-GUIDE(.ru) про Background-редактор) и (д) (оговорка в docs/TESTING.md:1704) как часть поставки. Раздел «AC» перечисляет AC-а, AC-в1…в3, AC-г, AC-е, AC-общ — ни одного пункта, который проверял бы именно текст (б) или (д). Без собственного AC код-ревьюеру нечем формально подтвердить, что эти два пункта скоупа выполнены так, как задумано (а не забыты или не сформулированы иначе).

Чем чинится в этой же задаче: два дополнительных пункта, например «AC-б: docs/USER-GUIDE.ru.md, раздел Редактора подложки, содержит предложение о неинтерактивности лейблов комнат в этом режиме — доказательство: ревью текста» и «AC-д: docs/TESTING.md:1704 содержит оговорку про light_pools/#374 — доказательство: ревью текста».

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

• Задача в скоупе docs/SCOPE.md — все шесть пунктов чинят существующее поведение уже принятых фич (#372, #362, #360, #361, #374), новых пользовательских job не открывают и не входят в «Out of scope».
• Продуктовых вопросов владельцу не осталось: оба места, где решение было нужно ((а) null≡''; (в) персист или нет), уже закрыты записанным решением владельца от 29.08 — текст ТЗ явно на них ссылается, а не переизобретает.
• Ни одно техническое утверждение ТЗ о текущем поведении кода не оказалось догадкой, выданной за факт — все семь проверенных пунктов (см. «Как проверялось» п.6) подтвердились дословно по номерам строк.
• Каждый отдельный AC (AC-а, AC-в1…в3, AC-г, AC-е, AC-общ) сформулирован как проверяемое утверждение с названным способом доказательства (unit/смок) и явной регресс-веткой там, где правка могла задеть соседнее поведение (AC-а: undefined и ' ' остаются нетронутыми; AC-г: существующий юнит #361 для 2D не должен ослабнуть).
• Раздел «Принятые предположения» корректно выносит технические, не наблюдаемые пользователем решения (формат ключа snake/camelCase, путь записи только из runtime-редактора) в явный блок вместо того, чтобы спрятать их в тексте контракта как решённые факты.
• i18n корректно отмечен как незадетый — ни один из шести пунктов не добавляет пользовательский текст в UI (только документацию).
• Риски (в), (а) названы конкретно вместе со снимающим их механизмом (дебаунс + expected_rev/#340; регресс-ветка AC-а), а не общими словами.

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

• Гейты код-ревью (typecheck/test/build/смоки/check-docs/ инварианты модели/pytest tests_backend) — не запускал: на стадии ТЗ продуктовый код не менялся, диффа против dev в этом issue нет, гейтам нечего было бы доказать. Ссылка на зелёный Validate 4eede5bc (https://github.com/Matysh/houseplan-card/actions/runs/33252620807) относится к текущему dev, не к материалу этого ТЗ.
• Точную будущую формулировку абзацев USER-GUIDE(.ru)/TESTING.md для (б, д) — контракт называет смысл и место, не финальный текст; это в пределах «принято предположительно», не находка (при условии, что M2 закрыт добавлением AC на сам факт правки).
• Реализуемость дебаунса «≥1 с» для записи (в) на практике — оценка риска по описанию, кода ещё нет.
• Согласованность нового бэкенд-ключа decor_default_style с полным реестром docs/CONFIG-COMPATIBILITY.md/scripts/config-field-registry.mjs за пределами вопроса классификации трека (H1) — это станет предметом код-ревью, если/когда (в) пойдёт в разработку.

Вердикт

Технически пакет описан аккуратно: каждое утверждение о текущем коде проверено построчно и подтвердилось, AC по большинству пунктов проверяемы и снабжены регресс-ветками, продуктовые решения владельца зафиксированы, а не додуманы. Но сама форма задачи — пачка из шести точечных находок adversarial-аудита поперёк как минимум четырёх модулей, одна из которых (в) добавляет новый персистентный серверный ключ с кросс-модульным путём записи, — не проходит собственные критерии лёгкого трека PROCESS.md §5 одновременно («одна поверхность», «нет новых compatibility-полей»), причём для задачи ровно такой же формы («пачка Low одного аудита») этот же проект уже принимал обратное решение на issue #369. Это блокирующая находка: она не про содержание AC, а про то, в каком процессе задачу вообще можно продолжать. Два Medium (отсутствующий раздел «откат», отсутствующие AC на пункты (б)/(д)) чинятся в этой же задаче без отдельного issue, независимо от исхода H1.

Вердикт: красный · заход r1 · блокирующих циклов 1/2 · High: 1 · Medium: 2 → в задаче