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

SPEC-REVIEW-397-r2

• Issue: https://github.com/Matysh/houseplan-card/issues/397
• ТЗ: docs/specs/397-device-position-echo.md (класс A, полный трек)
• Заход: r2 · блокирующих циклов израсходовано 1 из 4 (r1 — жёлтый, потратил цикл; этот раунд бюджет не тратит, см. вердикт)
• SHA r1: 83692e79 (найден в документе docs/reviews/SPEC-REVIEW-397-r1.md, раздел "Скоуп"; в комментарии-вердикте r1 SHA не назван — это находка формата, зафиксирована ниже, не блокирует)
• SHA этого раунда: 6edcde01

Скоуп раунда

Дельта — только docs/specs/397-device-position-echo.md:

git diff 83692e79..6edcde01 -- docs/specs/397-device-position-echo.md
 1 file changed, 23 insertions(+), 7 deletions(-)

(второй файл в общем диапазоне, docs/reviews/SPEC-REVIEW-397-r1.md, — публикация документа предыдущего раунда, не предмет ревью.)

Правка автора — точечный ответ на вердикт r1: один Medium (AC5б/AC7 без способа доказательства) и два Low (диапазон строк, отсутствие фразы "Доказательство" у AC3). Продуктовый код не тронут (src/** не в диффе) — ожидаемо для этапа "ТЗ на ревью". Дельта локальна: не ребейз, контракт поведения не меняется, новая подсистема не задета, объём дельты (23 строки) несопоставим с объёмом исходной задачи (174 строки). Разбор по дельте достаточен; полный повторный прогон не требуется.

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

Находка r1	Чем закрыта	Где видно
Medium: AC7 и вторая половина AC5 без способа доказательства	Добавлены пункты 7 (AC5б: удаление → честный reload → canUndo остаётся true) и 8 (AC7: запись «в полёте», сервер отвечает старой позицией → в _layout остаётся отправленная) в "План автотестов"; у AC5 и AC7 добавлена фраза "Доказательство: …" со ссылкой на эти пункты	docs/specs/397-device-position-echo.md:121–138 (AC), :157–160 (план)
Low-1: диапазон _persistDevicePlacement указан как :5226-5258, тело функции длиннее	Исправлено на :5226-5261	docs/specs/397-device-position-echo.md:28
Low-2: у AC3 нет явной фразы "Доказательство"	Добавлено "Доказательство: смок, пункт 5 плана — …"	docs/specs/397-device-position-echo.md:114–117

Все три закрытия проверены не на слово автора, а построчным чтением текущего src/houseplan-card.ts и src/device-position-history.ts на SHA 6edcde01 (продуктовый код с r1 не менялся, но заново прочитан, так как новые формулировки AC5/AC7 делают новые технические утверждения о его поведении — это предмет дельты, не наследуется):

• Диапазон функции. awk по файлу подтверждает: private async _persistDevicePlacement( начинается на :5226, закрывающая скобка метода — на :5261 (после this._persistLocalLayout(); }). Новый диапазон точен.
• AC5, обоснование раздельного доказательства. Ветка удаления (placement === null, pending = null, houseplan/layout/delete) подтверждена буквально на :5236-5242. applyDevicePlacement (src/device-position-history.ts:45-55) при placement === null действительно удаляет ключ (delete next[deviceId]), а не "заменяет значение" — рационале AC5 в ТЗ технически верно, не догадка.
• AC7, механизм "в полёте побеждает". _reloadLayoutOnly (:4904-4948) собирает mine из _sentPos (:4918), затем накладывает поверх ответа сервера (:4922-4926: for (const [id, pos] of mine) … merged[id] = pos) до сравнения отпечатков (:4927-4928). Формулировка AC7 и сценарий плана (пункт 8) описывают ровно этот код, не предположение.
• Смок для пунктов 7–8 ложится в тот же файл фикстуры (demo/smoke_device_position_history.mjs), что и пункты 4–6 — не пересекается с demo/smoke_layout_sync.mjs:87, который (по находке r1) проверяет только дренаж _sentPos, а не победу при слиянии; новый пункт закрывает именно тот пробел, который был назван.

Все три закрытия — не косметика, а корректные по содержанию правки: заявленное в тексте совпадает с тем, что делает код.

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

Без повторной проверки в этом раунде принято (документ docs/reviews/SPEC-REVIEW-397-r1.md, SHA 83692e79, дельта их не задевает):

• Обязательные разделы §7.1 присутствуют полностью, в правильном порядке; сценарий и "что человек увидит" отвечают на оба вопроса без терминов реализации; связь со SCOPE.md (J6, "Keep the plan true as the home evolves") — не изменились в дельте r2.
• Технический разбор B3 (некорректная запись в _layout, нежеканонический отпечаток) и M1 (подстроенная фикстура смока) — воспроизведены построчно в r1, дельта r2 текст находок не меняет (кроме номера строки, отдельно перепроверен выше).
• Граница скоупа: путь _savePos/_persistLayout (подписи комнат) багом не затронут — раздел "Скоуп / не-скоуп" не менялся.
• Цитата AC10 ТЗ #74 сверена с docs/specs/074-device-position-undo.md:254 — не менялась.
• Модель данных/миграция, i18n, откат, release-артефакты — разделы не затронуты дельтой.
• AC1, AC2, AC4, AC6 — однозначны, доказательство названо и прослеживается до плана автотестов; текст этих AC дельтой не менялся.
• Гейты npx tsc --noEmit, npm test (1654/1655, 1 известный skip), npm run build были зелёными на 83692e79; на 6edcde01 полный набор подтверждён Validate (см. ниже) — независимая проверка, не перенос старого результата.

Как проверялось в этом раунде

1. Найден вердикт r1 в комментариях issue (жёлтый, Medium в скоупе) и SHA ревью — из тела документа SPEC-REVIEW-397-r1.md (в самом комментарии-вердикте SHA не указан, см. находку формата ниже).
2. git diff 83692e79..6edcde01 -- docs/specs/397-device-position-echo.md — вся дельта прочитана целиком.
3. Каждое из трёх закрытий сверено с текущим кодом на 6edcde01 (см. таблицу выше) — не принято на слово.
4. Перечитаны обязательные разделы §7.1 в местах, которые правка не касалась, ровно настолько, чтобы убедиться в отсутствии противоречий между новым текстом AC5/AC7/AC3 и остальным документом (сценарий, скоуп, риски) — противоречий нет: раздел "Риски" уже (с r1) называл гонку с _sentPos и порядок записи как явные риски, новый AC7 их формализует, не противоречит.
5. Гейты: Validate на 6edcde01 зелёный (см. ссылку в задании на этот раунд) — npx tsc --noEmit, npm test, npm run build не перегонялись повторно, приняты по этой ссылке.

Находки

Low (формат, не блокирует) — SHA не назван в комментарии-вердикте r1

Комментарий-вердикт r1 в issue (2026-08-30T23:19:27Z) не содержит SHA, на котором получен результат — вопреки практике, которой сам документ ревью r1 следует (SHA ревью: 83692e79 в теле документа). SHA пришлось восстанавливать через документ, а не через комментарий. Не блокирует эту задачу (SHA найден и подтверждён), но стоит перенести в шаблон комментария-вердикта на будущее, чтобы не полагаться на то, что документ ревью всегда будет открыт вместе с комментарием.

Новых находок по содержанию ТЗ в дельте r2 нет: оба Low и один Medium из r1 закрыты корректно и по существу (см. таблицу выше), новых недоказанных утверждений или расхождений с кодом дельта не вносит.

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

• Все три пункта закрытия r1 (Medium AC5б/AC7, Low диапазон строк, Low фраза "Доказательство" у AC3) — не косметические переформулировки, а точные по содержанию правки, проверенные построчным чтением текущего исходника.
• Новые технические утверждения, добавленные дельтой (ветка удаления снимает ключ, а не заменяет значение; _sentPos побеждает при слиянии в _reloadLayoutOnly до сравнения отпечатков), верны и не являются непомеченными догадками.
• Новые пункты плана автотестов (7, 8) целятся в код, который дельта не трогала, но который граничит с фиксом B3 (тот же риск, что и в r1) — теперь у обеих веток есть названный, воспроизводимый способ доказательства.
• Документ внутренне непротиворечив: новый текст AC не противоречит разделам "Риски", "Скоуп/не-скоуп", "Модель данных".

Чего не проверял и почему

• npx tsc --noEmit, npm test, npm run build — не прогонял повторно: Validate на 6edcde01 зелёный (ссылка дана в задании на раунд), диф этого раунда не тронул код после последнего зелёного прогона.
• node scripts/check-docs.mjs — не прогонялся: диф не трогает src/**.
• npm run invariants -- --config … — не прогонялся: диф не меняет геометрию/layout/marker.space/open_spans.
• demo/smoke_*.mjs, scripts/smoke-select.mjs — не прогонялись: продуктовый код и демо-фикстуры не менялись ни в r1, ни в этой дельте (это по-прежнему этап ТЗ, реализации ещё нет).
• npm run golden:verify, python -m pytest tests_backend -q, performance-профили, bundle:sync/bundle:budget — не применимо: дельта документационная, ни рендер, ни custom_components/**/*.py, ни dist/** не затронуты.

Вердикт

Один Medium и два Low из r1 закрыты корректно, проверено построчно против кода на текущем SHA, новых High/Medium в дельте не найдено. Один Low (формат — SHA не назван в комментарии-вердикте r1) не блокирует и не в скоупе этой задачи.

Зелёный. ТЗ готово к DoR/S5-ready.