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

SPEC-REVIEW-126-r2

• Issue: https://github.com/Matysh/houseplan-card/issues/126
• ТЗ: docs/specs/126-ha-area-marker-relocation.md
• Коммит материала: cfd9c0fd (git rev-parse HEAD перед подведением итогов; ветка issue/126-ha-area-marker-relocation)
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Заход: r2 · блокирующих циклов израсходовано 1 из 4
• Трек: полный (владелец явно закрыл small 2026-08-30)

SHA предыдущего раунда — примечание

Вердикт r1 назвал материал 8bc8ba66. Этого объекта в текущей истории репозитория нет (git cat-file -t 8bc8ba66 → fatal: Not a valid object name) — SHA был назван, но перестал существовать. Причина не в недобросовестности: комментарий автора в issue от 2026-08-31T05:40 прямо говорит «Ветка перебазирована на актуальный dev@4683a493cca25a4a527f2b96d3d11723aa9da74c», и git log -1 --format='%H %P' a3d343ca подтверждает — родитель коммита ТЗ теперь 4683a493 (коммит docs: review document for #400), а не старый dev@6bf39ee9, на который опирался 8bc8ba66. Это ребейз на ушедший вперёд dev (PROCESS.md §2.10/§7.2) — по правилу «после ребейза это другой код», разбор ниже полный, а не только по дельте текста.

Скоуп ревью

Диапазон материала — весь актуальный текст docs/specs/126-ha-area-marker-relocation.md на cfd9c0fd плюс проверка того, что ребейз (диапазон dev@6bf39ee9..dev@4683a493) не задевает ни одного факта, который ТЗ выдаёт за освоенный код. Продуктовый код по-прежнему не менялся — issue остаётся в S3-spec/до-DoR стадии, только текст спецификации.

Дельта с r1

git diff da8cb6fa..cfd9c0fd -- docs/specs/126-ha-area-marker-relocation.md (коммит cfd9c0fd, +17/−2) — правки по всем трём находкам r1 (M1, L1, L2). Дополнительно проверено, что ребейз a3d343ca/da8cb6fa/0d92712c/cfd9c0fd на dev@4683a493 не занёс изменений в подсистемы, о которых ТЗ делает фактические заявления:

git diff 6bf39ee9..4683a493 --stat -- src/devices.ts src/logic.ts \
  src/space-geometry.ts src/types.ts \
  custom_components/houseplan/validation.py custom_components/houseplan/websocket_api.py

→ пусто, ни один из этих файлов в диапазоне ребейза не тронут.

Ребейз действительно принёс продуктовый код, но только по #400 (полировка furniture-редактора): src/houseplan-card.ts — порядок отрисовки handle'ов selection box у мебели (HANDLE_PAINT_ORDER), и src/houseplan-editor-runtime.ts — исключение перетаскиваемого маркера устройства из align-candidates через _deviceDrag. Оба куска — про мебель/выравнивание в редакторе плана, не про маркеры устройств, Area или layout-запись, на которых стоит ТЗ #126. Ни один символ, который ТЗ #126 называет (_livePos, _defaultPositions, _syncNewDevices, diffNewDevices, markerPos, pointInPolygon, houseplan/layout/delete, explicit-override правило #317), в диапазоне ребейза не задет. Ребейз не инвалидирует ни один факт из «что проверено и признано корректным» r1.

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

Находка r1	Чем закрыта	Где это видно
M1 (Medium, в скоупе) — §9 ссылался на несуществующий budget known_devices	§9 переписан: вводится собственный лимит MAX_MARKER_AREA_SNAPSHOT = MAX_KNOWN_DEVICES = 20_000 entries плюс общий MAX_CONFIG_BYTES = 2 MiB; то же продублировано в §23	docs/specs/126-ha-area-marker-relocation.md:204-206, 479-480 (коммит cfd9c0fd). Число 20_000 не выдумано: custom_components/houseplan/validation.py:1092 реально объявляет MAX_KNOWN_DEVICES = 20000 и применяет его к known_devices/new_device_ids через vol.Length(max=MAX_KNOWN_DEVICES) (validation.py:1932-1933)
L1 (Low, снята с записью) — bindingKind:'entity' не отличает direct entity marker от composite light group	§8 получил абзац-дискриминатор: eligibility требует сохранённый marker с exact binding === entity:${bindingRef}, id-префикс — только defensive check; §23 повторяет это как явное техническое решение	docs/specs/126-ha-area-marker-relocation.md:176-180, 482-483. Поле marker.binding: string // 'device:<id>' | 'entity:<eid>' | 'virtual' реально существует (src/types.ts:121); light-группы markerless и получают синтетический id 'lg_'+eid (src/logic.ts:812, src/devices.ts:1175) — у них нет сохранённого marker.binding, так что дискриминатор из §8 действительно их отсекает, а не выдуман
L2 (Low, снята с записью) — нет явной строки о влиянии на производительность	В §19 добавлен абзац «Performance budget»: resolver гоняется только на authoritative rebuild, линейная сложность по markers+rooms, не вызывается из render, не пишет при unchanged input	docs/specs/126-ha-area-marker-relocation.md:433-435

Примечание не по делу закрытия, а по качеству r1: сама находка M1 была верной по существу (ТЗ действительно ссылалось на несуществующее название бюджета, не подкреплённое кодом), но обоснование r1 содержало неточность — r1 утверждал, что «явного per-field ограничения... в коде нет», хотя MAX_KNOWN_DEVICES = 20000 (validation.py:1092) существовал уже тогда и не менялся в диапазоне ребейза. Похоже, r1 грепал known_devices|new_device_ids в src/types.ts и MAX_CONFIG_BYTES в validation.py, но не искал сам MAX_KNOWN_DEVICES. Это не отменяет находку (несуществующее было именно то конкретное число/имя, которое ТЗ приписывало — и после правки текст ссылается на реальный, верно процитированный лимит), поэтому цикл не переоткрывается — только фиксирую для трассируемости.

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

Документ docs/reviews/SPEC-REVIEW-126-r1.md, SHA материала 8bc8ba66 (недоступен в текущей истории — см. раздел выше; содержательно эквивалентен a3d343ca+da8cb6fa до ребейза, что подтверждено отсутствием изменений в диапазоне ребейза по всем файлам, которые ТЗ цитирует). Принято без повторной построчной проверки в r2, так как текст этих разделов не менялся в дельте da8cb6fa..cfd9c0fd и ни один цитируемый в них символ не задет ребейзом:

• полнота обязательных разделов §7.1 (сценарий/персона, «что видно до и после» без терминов реализации, проблема/диагноз, скоуп/не-скоуп, контракт поведения, UX/touch/a11y, модель данных и миграция, i18n, AC1–AC12 со способом доказательства, план тестов, риски/откат, release-артефакты);
• соответствие J6 (docs/SCOPE.md);
• построчная сверка с кодом причины дефекта (_livePos() src/houseplan-card.ts:5174-5190, markerPos() src/space-geometry.ts:629-638, diffNewDevices() src/logic.ts:2092-2100);
• explicit-override правило #317 (src/devices.ts:1421-1424, resolveExplicitMarkerPlacement() src/devices.ts:1066-1086);
• реальность эндпойнта houseplan/layout/delete (custom_components/houseplan/websocket_api.py:1099-1106);
• переиспользование pointInPolygon() (src/logic.ts:431) для backfill;
• терминология по docs/USER-GUIDE.ru.md (метка «Новое», Find/поиск её не снимают);
• docs/specs/README.md обновлён корректно;
• владельцу не задано новых продуктовых вопросов.

Новая находка r2

Low — снимается с записью

L3. Строка 4 документа («Статус документа: актуализировано на dev@6bf39ee9...») устарела после ребейза на dev@4683a493.

Реальный родитель первого коммита ТЗ в текущей истории — 4683a493cca25a4a527f2b96d3d11723aa9da74c (git log -1 --format='%H %P' a3d343ca), а не 6bf39ee9, который документ называет своей базой. Само по себе не влияет на содержание ТЗ (диапазон ребейза не касается ни одной подсистемы, на которую опирается спецификация — см. раздел «Дельта с r1»), но неточная строка провенанса мешает следующему ревьюеру быстро проверить актуальность базы, как и в этом раунде пришлось восстанавливать факт ребейза из комментария issue, а не из самого документа. Снимается с записью: не блокирует; рекомендую поправить строку на актуальный dev@… при следующей правке ТЗ (или прямо при переводе в S5-ready), отдельного цикла ради этого не открываю.

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

Гейт	Команда	Результат
Typecheck	npx tsc --noEmit	green, без вывода
Unit-тесты	npm test	green: tests 1668, pass 1667, fail 0, skipped 1 (тот же известный environment-sensitive пропуск, не относится к дифу)
Build	npm run build	green, dist собран без ошибок
Сверка трёх копий бандла	npm run bundle:sync	green; после запуска git status --porcelain пуст — dist, custom_components/houseplan/frontend, demo/srv/assets уже были в синхроне (диф #126 не трогает src/**)
node scripts/check-docs.mjs	не запускал	диф #126 (da8cb6fa..cfd9c0fd) не трогает src/**; ребейз принёс изменения в src/houseplan-card.ts/src/houseplan-editor-runtime.ts, но это уже смёрженный и прошедший свой гейт код #400, не предмет этого ревью
npm run invariants / model invariants	не запускал	диф не трогает геометрию, layout, marker.space, open_spans — только текст ТЗ
Browser smoke (demo/smoke_*)	не запускал	продуктовый код не менялся ни этим дифом, ни ребейзом в затронутых #126 модулях
golden:verify, performance_smoke, pytest tests_backend	не запускал	визуальные/perf/backend поверхности не тронуты — диф docs-only

Зелёного Validate на SHA cfd9c0fd не найдено, поэтому дешёвые гейты прогнаны вручную повторно в этом раунде (код в дереве изменился из-за ребейза, хотя сам диф #126 — нет); все зелёные. Тяжёлые гейты не применимы по тем же основаниям, что и в r1.

Что проверено и признано корректным

• Все три находки r1 (M1/L1/L2) закрыты текстом, а не заявлением — см. таблицу «Закрытие раунда r1» с точными строками и перекрёстной проверкой по коду.
• Ребейз на dev@4683a493 не заносит правок ни в один файл/символ, на который опирается ТЗ #126 — проверено диапазонным git diff --stat по всем ключевым путям.
• AC1–AC12, разделы §5–§6 (скоуп/не-скоуп), §11–§14 (порядок записи, multi-client, race-guard) и §21 (риски/откат) не менялись в дельте и не задеты ребейзом — наследуются из r1 без повторной построчной проверки.
• Новый текст §9 корректно цитирует реальный код (MAX_KNOWN_DEVICES = 20000, validation.py:1092), а не изобретает число.
• Новый текст §8 корректно опирается на реально существующее поле marker.binding (src/types.ts:121) как дискриминатор, а не на недостаточный bindingKind.

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

• Не проверял выполнимость резолвера по коду — кода ещё нет, это спек-ревью.
• Не прогонял golden/performance/browser smoke/backend pytest — диф их не касается (см. таблицу гейтов).
• Не делал полного повторного построчного код-аудита разделов, унаследованных из r1 (§7.1-состав, J6, #29/#74/#317 контракты, endpoint layout/delete, point-in-polygon, терминология USER-GUIDE) — их текст не менялся в дельте, а ребейз не касается ни одного файла, на который они ссылаются; это явно зафиксировано в разделе «Унаследовано из r1».
• Не проверял вручную код #400 (мебель/handle paint order, align-candidates) — это чужой уже смёрженный на dev контракт вне предмета #126, тронут только ребейзом, не текстом ТЗ.

Вывод

High-находок нет. Все Medium/Low из r1 закрыты правкой на конкретных строках, подтверждённой кодом. Одна новая Low-находка (L3, устаревшая строка провенанса в шапке документа) снята с записью, не блокирует.

Вердикт: зелёный. ТЗ #126 готово к переводу в «Готово к разработке» (DoR §2.5): AC пронумерованы и доказуемы, миграция/compatibility, touch, i18n, performance и откат названы явно, открытых продуктовых вопросов нет.