houseplan-card/docs/reviews/SPEC-REVIEW-406-r2.md

SPEC-REVIEW-406-r2

• Issue: #406
• ТЗ: docs/specs/406-beta2-polish.md, ветка issue/406-beta2-polish, ревизия 2, SHA 0d5b52d1 (HEAD ветки 44715dd0 добавляет поверх только docs/reviews/SPEC-REVIEW-406-r1.md, самого ТЗ не трогает)
• Этап: spec (PROCESS.md §2.4)
• Заход: r2 · блокирующих циклов израсходовано 1 из 4
• Вердикт: жёлтый

Почему разбор полный, а не по дельте

Владелец перебазировал ветку на origin/dev (b04387ce) между r1 и r2. SHA r1, названный в его собственном документе, — 8248f9e4 — на текущем дереве не существует (git cat-file -t 8248f9e4 → Not a valid object name): это не «SHA не назван», SHA назван корректно, но ребейз его переписал. Это ровно случай PROCESS.md §2.10: «ребейз на ушедший вперёд dev (после ребейза это другой код)» — разбор обязан быть полным. Дополнительное основание для полноты: ребейз протащил на ветку чужой коммит (8119c523, issue #409), который меняет ровно тот файл и ровно то место, которое контракт (д) описывает как открытый дефект — см. находку №1.

Скоуп

Без изменений от r1: пять независимых мелочей полного трека (i18n-мусор + гейт, роль hp-dialog/hp-confirm, смок HA-ветки, уборка снапшотов area, сохранение следа приёмки скриншотов).

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

Прочитан docs/SCOPE.md (раздел «Partially covered»: «Accessibility: … no ARIA labelling of the plan» — задача (б)/(в) законно попадает сюда), PROCESS.md §2.4/§2.9/§2.10/§7.1/§7.2, тело issue #406 и все комментарии (включая S2-разбор, ссылку на ТЗ, вердикт r1, ответ владельца на r1), docs/USER-GUIDE.ru.md (терминология подтверждения/разблокировки, строки 672-730, 824-963 — новых формулировок ТЗ не вводит).

Само ТЗ вычитано целиком построчно. Каждое фактическое утверждение перепроверено на текущем дереве (не на SHA r1 — его больше нет), а не принято на слово:

• src/i18n/en.json|ru.json|de.json|fr.json — подсчёт ключей и паритет (node -e подсчёт), точечная проверка литерального использования всех 13 заявленных мёртвых ключей и представителей заявленных динамических семейств (furn.cat_*, furn.sym_*, wall_model.reason.*, resize.disabled.*, junction.limit_*, decor.*, _help()/.aria);
• src/hp-dialog.ts, src/hp-confirm.ts, src/danger-confirm.ts, src/houseplan-card.ts (строки вокруг _lockAction) — роль диалога, устройство HpConfirmKind, место вызова warning-подтверждения;
• src/device-area-relocation.ts целиком — resolveDeviceAreaRelocations, applyAreaRelocationResolution, markerAreaSnapshotOf, git log файла (единственный коммит с #126, после рёбейза не менялся);
• scripts/docs-accept.mjs целиком, git log -p по нему — здесь нашлась находка №1;
• test/unified-wall-tool-source.test.mjs:32, demo/smoke_free_walls.mjs (ha-dialog-стаб), demo/smoke_esc_dialogs.mjs, demo/smoke_danger_confirm_ branches.mjs, demo/smoke_danger_confirmation.mjs — покрытие веток и прецедент стаба.

Гейты (tsc/test/build) не гонял: git diff --stat origin/dev...HEAD показывает только два doc-файла (docs/specs/406-beta2-polish.md, docs/reviews/SPEC-REVIEW-406-r1.md), продуктового кода на ветке ещё нет — то же основание, что в r1.

Закрытие раунда r1

Находка r1	Чем закрыта	Где видно
(а) Medium: инвентарь *.help.aria неверен (13 из 19 объявлены мёртвыми, а живы все 19)	Раздел «(а)» переписан: явно выделен абзац «Важное динамическое семейство, которое удалять нельзя» — все 19 *.help.aria признаны живыми через производную ${key}.aria от литерального _help('*.help'); список мёртвых сокращён до 13 (7 confirm.* + 6 прочих); правило внесено в AC3 явно, а не подразумевается в «прочих семействах»	docs/specs/406-beta2-polish.md:59-64,217-221. Перепроверено заново на текущем дереве (не наследовано): все 19 *.help.aria-ключей действительно имеют по одному литеральному _help('x.help')-потребителю, 13 заявленных мёртвых ключей — без потребителей ни в одном из 4 словарей
(б) Medium: AC6/AC7 не решают роль для HpConfirmKind.warning	Контракт (б) переписан: явная дихотомия снята, оба kind — destructive и warning — объявлены as alertdialog; warning назван явно как разблокировка двери с confirm.unlock_body; AC6 переформулирован на «оба вида»	docs/specs/406-beta2-polish.md:100-105,227-230. Перепроверено: houseplan-card.ts:13041-13049 — единственный warning-запрос, ссылка точна

Обе находки r1 закрыты по существу, не косметически. Полный повторный разбор (см. выше) вскрыл в разделе (б) отдельную, ранее не поднимавшуюся проблему феазибилити (находка №2) — она не переоткрывает находку r1, это независимый дефект того же раздела.

Унаследовано из r1

Формально пусто: ребейз на dev обесценил SHA r1, поэтому по правилу §2.10 разбор в этом раунде — полный, а не по дельте, и каждое утверждение ТЗ перепроверено заново на текущем дереве (см. «Как проверялось»), а не принято на основании документа r1. Структурная оценка §7.1 (все обязательные разделы присутствуют, продуктовых вопросов владельцу не вынесено, скоуп/не-скоуп корректны, docs/SCOPE.md подтверждает легитимность полного трека) не поменялась между r1 и r2 и не пересчитывалась заново построчно — в остальном результат r1 в этой части подтверждён независимым прочтением r2, а не переносится слепо.

Находки

[Medium, в скоупе] №1 — (д) контракт описывает уже исправленный дефект и расходится с тем, что реально попало в дерево ребейзом

Файл: docs/specs/406-beta2-polish.md, раздел «(д) Затирание следа приёмки» (строки 157-172) и AC12/AC13 (строки 246-251).

Что не так: ТЗ строит контракт (д) на утверждении «scripts/docs- accept.mjs:145 пишет declared: [...decision.replace]» безусловно, и приводит модельный прогон: «replace=[] → в манифест уйдёт acceptance.declared = []». На SHA r1 (8248f9e4) это было верно — сам дефект и являлся предметом п. (д). Но ветка с тех пор перебазирована на origin/dev, и в dev уже есть коммит 8119c523 («fix: the screenshot witness floor comes from the set, not from survivors», issue #409, попал в дерево этим самым ребейзом), который правит именно эту строку:

// scripts/docs-accept.mjs (текущее дерево)
const previous = JSON.parse(readFileSync(resolve(ROOT, 'docs/images/screenshots.json'), 'utf8'))
  .acceptance;
const accepted = {
  ...manifest,
  acceptance: decision.replace.length
    ? { declared: [...decision.replace], witnesses: decision.witnesses.length, floor: decision.floor, ... }
    : { ...(previous || {}), lastWriteWasFingerprintOnly: true },
};

Commit message коммита 8119c523 прямым текстом: «Попутно Low из #405: повторная приёмка неизменённого набора затирала acceptance.declared пустым списком … Прежний след сохраняется и помечается lastWriteWasFingerprintOnly.» — то есть ровно дефект (д), заведённый в #406 как самостоятельный пункт, уже был отмечен как Low в #405 и уже устранён в #409 до того, как ТЗ #406 дошло до ревизии 2 (ревизия 2 датирована 2026-09-01, тем же днём, что и коммит фикса, но после ребейза на dev, согласно комментарию владельца «Ветка перебазирована… ТЗ поднято до revision 2»).

Хуже того — исправление, которое реально попало в дерево, не совпадает с контрактом (д) в тексте ТЗ. ТЗ требует: «Свежие числа (witnesses, floor) обновляются, список declared … сохраняется» — то есть на пустом replace witnesses/floor должны пересчитываться заново. Фактически смёрженный код делает обратное: при replace.length === 0 он не пересчитывает witnesses/floor вовсе, а замораживает весь предыдущий acceptance-блок целиком ({...(previous || {})}) и лишь помечает его флагом lastWriteWasFingerprintOnly — что по своему обоснованию в коммите специально сигнализирует «эти числа не свежие, а старые от последней настоящей проверки».

Сценарий отказа: если реализация будет буквально следовать тексту ТЗ («свежие числа witnesses/floor обновляются»), она отменит уже смёрженное и обоснованное поведение lastWriteWasFingerprintOnly — то есть пункт (д) этой же задачи внесёт регресс в код, который #409 только что починил, и уберёт сигнал «эти цифры устарели», ради которого фикс и писался. Если же реализация просто оставит код как есть (ничего не делая, потому что контракт уже выполнен фактически), AC12/AC13 будут пройдены случайно, без теста на функцию main() (docs-accept.mjs) — единственный существующий тест, test/docs-accept.test.mjs, покрывает только verifyDocsCandidate, а не запись acceptance в main(); test/docs-acceptance.test.mjs покрывает только чистую функцию docsAcceptancePlan, тоже без записи файла. То есть заявленное AC12 «доказательство: тест на функции приёмки — replace: [] оставляет прежний список» ни разу не написано и по этой ревизии ТЗ не попадёт в план работы как отдельная задача, потому что автор считает пункт ещё непочиненным.

Ожидаемо: раздел (д) переписан с учётом текущего состояния дерева — либо признаётся, что дефект уже устранён коммитом 8119c523/#409 и пункт (д) сокращается до «добавить недостающий тест на запись main() в docs-accept.mjs, поведение не менять», либо, если владелец сознательно хочет другое поведение (witnesses/floor обновлять даже на пустом replace, отказавшись от lastWriteWasFingerprintOnly), это должно быть явно названо как осознанное расхождение с #409, а не как продолжение нарратива «дефект ещё жив».

[Medium, в скоупе] №2 — (б) контракт не называет механизм, которым HA-ветка hp-dialog получает alertdialog/aria-describedby, хотя рядом есть свидетельство, что «просто атрибут» не сработает

Файл: docs/specs/406-beta2-polish.md, раздел «(б)» (строки 107-115) и AC6 (строки 227-230).

Что не так: контракт формулирует требование как факт, а не как инженерную задачу: «Практически: hp-dialog получает семантический признак alert/обычный и id описания … Обе ветки — HA и запасная — объявляют роль и описание одинаково.» Это утверждение о поведении стороннего компонента ha-dialog, которого нет в этом репозитории (это компонент фронтенда Home Assistant, подключаемый в рантайме; локально существует только тестовый стаб, demo/smoke_free_walls.mjs:20-31, — фейковый HTMLElement с произвольным shadowRoot, написанный этим же проектом, а не поведение настоящего ha-dialog).

В том же файле, который цитирует контракт, уже есть прецедент именно этой проблемы: для связывания заголовка (aria-labelledby) HA-ветка не принимает обычный HTML-атрибут — она использует специальное свойство ha-dialog, .ariaLabelledBy (src/hp-dialog.ts:449, .ariaLabelledBy=${this._titleId}), тогда как запасная ветка использует обычный атрибут aria-labelledby=${this._titleId} (:462). Это разделение не случайно: ha-dialog рендерит собственную внутреннюю структуру в своём shadowRoot, и произвольный ARIA-атрибут, поставленный на внешний тег <ha-dialog>, необязательно долетает до реального узла диалога внутри — именно поэтому для заголовка потребовалось выделенное свойство, а не атрибут.

Контракт (б) не называет для alertdialog/aria-describedby никакого аналога .ariaLabelledBy — ни существующего свойства ha-dialog (в этом репозитории такого свойства нигде не встречается — grep -rn "ariaDescribedBy|ariaLive|type=.\{0,5\}alert" по src/*.ts пуст), ни явного признания, что такого свойства может не быть и нужно исследование на этапе реализации. При этом ни один существующий смок не проверяет роль/описание на HA-ветке вообще (demo/smoke_esc_dialogs.mjs:34 — только на запасной dialog; ни в одном файле demo/smoke_*.mjs нет getAttribute ('role') рядом с ha-dialog), то есть у проекта пока нет ни одного подтверждённого прецедента, что произвольный ARIA-признак на HA-ветке вообще долетает до реального диалога в настоящем Home Assistant — только локальный, полностью подконтрольный автору стаб.

Сценарий отказа: реализация ставит role="alertdialog" и aria-describedby атрибутами прямо на тег <ha-dialog>, локальный смок (тестирующий собственный же стаб) зеленеет по AC6/AC8, PR проходит ревью — а в реальном Home Assistant скринридер по-прежнему не объявляет alertdialog, потому что настоящий ha-dialog эти атрибуты на внешнем теге игнорирует так же, как проигнорировал бы aria-labelledby, если бы для него не завели .ariaLabelledBy. Ровно тот класс регрессии, который локальный тест из-за природы стаба не способен поймать.

Ожидаемо: контракт (б) явно называет способ донести alert-семантику/описание до реального ha-dialog (существующее свойство, если оно есть — тогда назвать его, как назван .ariaLabelledBy), либо явно помечает это как открытый технический вопрос реализации с планом проверки на реальной Home Assistant (не только на локальном стабе), а не формулирует как решённый факт «обе ветки объявляют одинаково».

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

• (а) Числа сходятся на текущем дереве независимо от r1: 1201 ключ во всех четырёх словарях (en/ru/de/fr), все 13 заявленных мёртвых ключей (7 confirm.* + marker.display_hint(_icon), history. delete_room, markup.delete, title.markup, history.partition_add) без единого литерального потребителя ни в одном из четырёх словарей; все 19 *.help.aria действительно производятся из литеральных _help('*.help') на строке houseplan-editor-runtime.ts:1194, номер строки точен. Заявленные динамические семейства AC3 (furn.cat_*, furn.sym_*, wall_model.reason.*, resize.disabled.*, junction.limit_*, decor.*) реально существуют как шаблонные литералы в houseplan-editor-runtime.ts/houseplan-card.ts. 52 = 13×4 верно. Коллизия с test/unified-wall-tool-source.test.mjs:32 подтверждена дословно на текущей строке.
• (б) дихотомия destructive/warning — подтверждена: ровно 7 мест kind: 'destructive' (все — удаления, houseplan-editor-runtime.ts и houseplan-onboarding-runtime.ts) и ровно одно kind: 'warning' (houseplan-card.ts:13041-13049, разблокировка, confirm.unlock_body). hp-confirm.ts на текущем дереве действительно не передаёт hp-dialog никакого alert-признака — контракт описывает реальный, ещё не закрытый разрыв, только механизм его закрытия для HA-ветки не назван (находка №2).
• (в) непокрытая HA-ветка — подтверждена без изменений от r1: smoke_free_walls.mjs — единственный файл с ha-dialog-стабом и глушит _confirmDanger; smoke_danger_confirmation.mjs/smoke_danger_ confirm_branches.mjs слова ha-dialog не содержат. Файл demo/smoke_ danger_confirm_branches.mjs действительно существует (создан #402, подтверждено содержимым) — план расширить именно его реалистичен.
• (г) утечка снапшота и порядок обрезки — файл device-area- relocation.ts не менялся с исходного коммита #126 (633cb20e, до ребейза), поэтому не задет им; перечитан целиком заново, а не наследован. resolveDeviceAreaRelocations действительно строит decisions только из цикла по options.devices (строка 155) — устройство, отсутствующее в этом списке целиком, не порождает decision и, соответственно, applyAreaRelocationResolution (строка 239) его запись не тронет никогда. Условие !options.authoritative (строка 142) — ранний return с пустым результатом, соответствует контракту «не трогать при неавторитетном реестре». .slice(0, MARKER_AREA_SNAPSHOT_LIMIT) (строка 68, MARKER_AREA_SNAPSHOT_LIMIT = 20_000, строка 9) читает по порядку вставки Object.entries — обрезка действительно режет самые свежие записи; разворот правила (AC11) реализуем без переписывания структуры. removeMarkerAreaSnapshots (строки 8326, 8448 houseplan-editor- runtime.ts) — номера строк точны.
• UX/терминология — docs/USER-GUIDE.ru.md уже описывает подтверждение разблокировки (строки 729-730) и удаления (672-673, 824-847) тем же языком, который использует ТЗ; новых терминов не введено. docs/SCOPE.md, раздел «Partially covered»: «Accessibility: … no ARIA labelling of the plan» — пункты (б)/(в) закрывают именно эту декларативно признанную продуктом брешь, скоуп легитимен.
• Скоуп/не-скоуп, отсутствие технических вопросов владельцу — как и в r1, границы очерчены явно, пересечения с #403/#405 разведены по разным контрактам одного файла; ни одного технического вопроса не вынесено владельцу.

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

• Гейты (tsc/test/build, check-docs.mjs) — не гонял: диапазон origin/dev...HEAD содержит только два .md-файла, продуктового кода ещё нет. То же основание, что в r1.
• Не пересчитывал вручную полный список «48 динамических семейств» и «1188 использовано / 13 не используется» по всем 1201 ключам — точечно перепроверил категории, названные в тексте (confirm.*, *.help.aria, единичные ключи, шесть заявленных семейств AC3); этого достаточно, чтобы подтвердить или опровергнуть числа в тексте, исчерпывающий пересчёт — задача самого гейта (AC1), а не ревью ТЗ.
• Не проверял (унаследовано из r1 без изменений, дельта его не касается): останется ли запись marker_area_snapshot живой, если устройство пропало из _devices, но по тому же id ещё существует маркер — открытый вопрос r1 остаётся открытым, контракт (г) не переформулирован в этой ревизии, граница AC9 та же, что и была.
• Не проверял поведение настоящего ha-dialog в реальной Home Assistant (нет доступа к его исходнику из этого репозитория) — отсюда и находка №2: это ровно то, что нельзя подтвердить чтением этого репозитория, и спецификация обязана либо назвать механизм, либо явно пометить как неисследованное.
• Не проверял scripts/mutation-gate.mjs на предмет технической реализуемости трёх заявленных мутантов — на этапе ТЗ это описание намерения, а не код.

Вердикт

Вердикт: жёлтый · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 2 → в задаче