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

# SPEC-REVIEW-363-r1

Issue: #363 · Этап: spec (PROCESS.md §2.4) · Трек: `small` (лёгкий) · Заход r1 ·
блокирующих циклов израсходовано 0 из 2 (лимит лёгкого трека — 2, §5)

## Скоуп

ТЗ в теле issue #363: возврат кнопки «Добавить» в основной тулбар Device
editor рядом с «Устройства» — короткий путь к уже существующему диалогу
нового устройства (`_openMarkerDialog()` без аргумента), убранной в `cab8d128`
(#29) вместе с каталогом «Устройства». Каталог не трогается. Класс изменения —
A (`src/houseplan-editor-runtime.ts`, три словаря `src/i18n/*.json`) плюс C
(`docs/USER-GUIDE*.md`, оба changelog). Метка `small` подтверждена в
аналитике владельца (S2): сложность 2/10, одна поверхность, миграций нет,
нового UX-контракта нет (контракт — тот же, что до #29).

## Важное обстоятельство состояния (проверить перед чтением остального)

В issue уже есть более ранняя попытка этого же захода: комментарий от
`claude` (2026-08-29T09:16:10Z, жёлтый вердикт, `Заход r1 · блокирующих
циклов 1/2 · High: 0 · Medium: 1`) и закоммиченный на `dev`
`docs/reviews/SPEC-REVIEW-363-r1.md` (коммит `9d6d6eb9`, тот же SHA, что и
текущий HEAD). Тот документ нашёл **M1**: раздел «Release-артефакты» не
называл обязательный прогон workflow «Скриншоты документации» и
`docs:accept --reviewed`, из-за чего `docs`-job в CI Validate стал бы
красным по расхождению `sourceFingerprint`, даже если ни один PNG не
изменился (сценарий #230/#234).

Задача даёт этому заходу метаданные `Заход r1 · 0 из 2` — то есть с точки
зрения конвейера предыдущая попытка цикл не потратила: судя по всему, тот
прогон не дошёл до финального структурированного ответа (без него, по
инструкции конвейера, метка не переставляется), поэтому официально не
засчитан, а issue не уходил в `S3-spec`. Тем не менее тело issue уже
переписано в «ТЗ · revision 2» и текстуально закрывает M1 (см. ниже) — то
есть автор (владелец, пишущий ТЗ прямо в issue на лёгком треке) увидел
незасчитанный комментарий и поправил текст до этого захода. Я не доверяю
этому на слово и ниже перепроверяю сам, что revision 2 действительно
закрывает M1 и что остальные утверждения черновика остаются верными на
текущем дереве. Раздела «Унаследовано из r<N-1>» не завожу — по счётчику
конвейера это первый действительный заход, и я перепроверил всё заново, а
не по дельте.

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

Ничего не принято на слово из текста ТЗ или прежнего черновика — каждое
утверждение перепроверено чтением дерева на `HEAD=9d6d6eb9`:

1. **M1 закрыт.** AC7 сейчас: «...полный артефакт принимается через `npm run
   docs:accept -- --reviewed --from=<artifact>`, а обновлённый
   `docs/images/screenshots.json` коммитится... Все PNG канонического набора
   (сейчас 10) ожидаются пиксельно неизменными». Раздел «Release-артефакты»
   дублирует то же требование и явно называет workflow «Скриншоты
   документации» обязательной «даже если видимая композиция кадров не
   меняется». Проверил, что названные команда и workflow существуют:
   `.github/workflows/docs-screenshots.yml` (шаг публикует
   `docs/images/screenshots.json` артефактом), `package.json:16` —
   `"docs:accept": "node scripts/docs-accept.mjs"`. Прежний черновик просил
   именно это, только называл «9 PNG» — сейчас в дереве
   `demo/docs/screenshots.mjs` действительно **10** сценариев (проверил
   `grep -n "id:" demo/docs/screenshots.mjs` и `docs/images/screenshots.json
   → scenarios.length`), то есть текущее ТЗ точнее черновика, а не расходится
   с деревом задним числом.
2. **`_openMarkerDialog()` жив, контракт не меняется.**
   `src/houseplan-editor-runtime.ts:7628` `public _openMarkerDialog(d?:
   DevItem)`; вызов без аргумента — путь диалога нового устройства. Кнопка
   «Устройства» вызывает другой метод, `_openDeviceInbox()`
   (`houseplan-editor-runtime.ts:11545`), а «Добавить виртуальное устройство»
   внутри каталога вызывает тот же `_openMarkerDialog()` без аргумента
   (`houseplan-editor-runtime.ts:11578`, `openVirtual`). Значит новая кнопка
   получает ровно тот же путь, что уже используется каталогом для того же
   исхода — вторая, независимая проверка того, что AC2 просит воспроизводимую,
   а не новую логику.
3. **i18n-таблица побайтово совпадает с состоянием до `cab8d128`.**
   `git show cab8d128^:src/i18n/en.json` и `...ru.json` дают ровно
   `"devbar.add": "Add"` / `"Добавить"` и `"title.add_device": "Add a device
   to the plan"` / `"Добавить устройство на план"` — совпадает посимвольно с
   таблицей ТЗ. Оба ключа сейчас отсутствуют во всех трёх словарях
   (`grep -n "devbar.add\|title.add_device" src/i18n/{en,ru,de}.json` — пусто),
   значит работа по их возврату реальна, а не фиктивна.
4. **Немецкий текст — согласованное предположение, не догадка.** `de.json`
   уже использует `"device_inbox.add": "Hinzufügen"` для того же действия и
   паттерн «существительное + hinzufügen» для похожих подписей
   (`"title.add_space": "Bereich hinzufügen"`). Предложенные `"Hinzufügen"` /
   `"Gerät zum Plan hinzufügen"` этому соответствуют. Помечено в ТЗ как
   принятое предположение, которое ревьюер вправе оспорить — не оспариваю.
5. **Паритет словарей ловит забытую локаль.** `test/i18n.test.mjs:109-112`:
   `assert.deepEqual(Object.keys(dictionary).sort(), enKeys)` для каждого
   языка реестра. Пропуск любого из 6 значений (2 ключа × 3 локали) красит
   `npm test`. AC4 доказуемо этим тестом, и тест умеет падать (сейчас ключей
   нет ни в одном словаре — не найти это на голом дереве, если ключ забыт,
   тест обязан споткнуться).
6. **Место вставки и порядок.** Текущий `_renderDevicesBar()`
   (`houseplan-editor-runtime.ts:11541-11553`) начинается с кнопки
   `device_inbox.button` («Устройства»), затем `devbar.rules` («Правила
   иконок»). До #29 первой кнопкой была «Добавить»
   (`git show cab8d128^:src/houseplan-card.ts` — фрагмент, приведённый в теле
   issue, подтверждён отдельно). Вставка новой кнопки перед «Устройства»
   восстанавливает этот порядок; номера строк в S2-аналитике (`:11491`)
   немного разошлись с текущими из-за более поздних коммитов — не находка,
   метод и разметка на месте.
7. **Каталог и его «Добавить виртуальное устройство» не задеты.**
   `_renderDeviceInbox()` / `openVirtual()` вне диапазона правок ТЗ.
   `demo/smoke_device_inbox.mjs` существует, его заголовок прямо ссылается на
   #29 («one lifecycle catalog replaces the separate Add / hidden-device
   paths») — подходящий существующий регресс-щуп для AC3.
8. **RU/EN руководство действительно потеряло строку.**
   `docs/USER-GUIDE.ru.md:775-786` — таблица «Редактор устройств» содержит
   «Устройства» и «Добавить виртуальное устройство», строки про «Добавить»
   нет. `docs/USER-GUIDE.md:519-529` — список без пункта «Add». Оба файла
   названы в «Затронутых файлах».
9. **Golden-сцены разведены верно.** `demo/golden/matrix.mjs:381` —
   `geometry-devices-editor-dark`: `mode: 'devices'`, **без** ключа `dialog` —
   тулбар виден целиком, третья кнопка попадёт в кадр. `device-inbox-*`
   (строки 383-390) все три несут `dialog: 'device-inbox'` — модальный
   каталог перекрывает тулбар, эти кадры не должны измениться.
   `--expect-change=geometry-devices-editor-dark` в AC8 — точная и
   единственная нужная пометка.
10. **UX-MODES.md / TOUCH-SUPPORT.md** — персистентный инструмент в основном
    тулбаре, `barclose` остаётся в правом торце (`editbar-end`, не тронут);
    новых touch-целей и жестов не вводится. Конфликта с «редакторы
    desktop-first, touch — best effort» нет.
11. **Обязательные разделы §7.1** — сценарий+результат, скоуп/не-скоуп,
    контракт поведения и UX, данные/совместимость (модель не меняется),
    i18n, AC1-AC8 с доказательством каждого, план тестов и мутанты, риски и
    откат, release-артефакты — все присутствуют в теле issue.
12. **Продуктовые вопросы, которые могли уйти владельцу как технические** —
    не найдены: три «принятых предположения» (CSS-классы/wrap, отсутствие
    отдельного disabled-state, немецкий перевод) — все технические/оформ-
    ительские, ни одно не требует продуктового решения.

## Гейты этого захода

Материал — только текст issue, продуктового кода по #363 в дереве ещё нет
(`git log --all --oneline | grep 363` и `git branch -a | grep 363` не находят
ветки/коммитов задачи, кроме случайных числовых совпадений `3633a3db`
(#159), `9d6d6eb9`/это же ревью). Прогонять `typecheck`/`test`/`build`/
`check-docs` не над чем — это ревью текста (§2.4), а не кода (§2.7); их место
в коде-ревью после реализации. Отдельно перечитал и вручную проверил
исполняемость `test/i18n.test.mjs` (пункт 5) и существование
`demo/smoke_device_inbox.mjs`, `.github/workflows/docs-screenshots.yml`,
`scripts/docs-accept.mjs` чтением, не запуском — их сегодняшнее содержимое,
а не будущее поведение, было предметом проверки.

## Находки

Нет. M1 предыдущего (незасчитанного) захода закрыт текстом ТЗ (см. пункт 1
выше) и проверен по дереву, а не на слово. Догадок, выданных за решение, не
найдено. Технических вопросов, которые следовало решить самому вместо
эскалации владельцу, не найдено — их и не было.

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

- Обработчик `_openMarkerDialog()` и его контракт (пункт 2).
- Побайтовое совпадение i18n-таблицы с состоянием до `cab8d128` и паритет-тест
  (пункты 3, 5).
- Согласованность предложенного немецкого текста с действующим словарём
  (пункт 4).
- Место вставки и восстановленный порядок кнопок (пункт 6).
- Независимость каталога и его «Добавить виртуальное устройство» (пункт 7).
- Пропуск строки тулбара в RU/EN руководстве (пункт 8).
- Разведение golden-сцен `geometry-devices-editor-dark` vs `device-inbox-*`
  (пункт 9).
- Отсутствие конфликта с UX-MODES.md / TOUCH-SUPPORT.md (пункт 10).
- Полнота обязательных разделов ТЗ §7.1 и отсутствие невынесенных
  продуктовых вопросов (пункты 11-12).
- Закрытие M1 предыдущего захода текстом revision 2 (пункт 1).

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

- Реализацию — её ещё нет; код-ревью (§2.7) проверит diff, а не текст ТЗ.
- Фактический прогон `typecheck`/`test`/`build`/`check-docs`/golden — не
  применимо к этому заходу, материала для прогона (diff) не существует.
- Browser-смоки и golden-захват — то же самое, нечего запускать.
- Реальный CI-прогон workflow «Скриншоты документации» — оценивалась только
  корректность его упоминания в ТЗ, а не его будущее исполнение.

## Вердикт

Зелёный. High: 0, Medium: 0. ТЗ полно, однозначно, каждый AC привязан к
способу доказательства, единственная находка предыдущей (незасчитанной)
попытки закрыта текстом и подтверждена чтением дерева. Трек `small`
подтверждён повторно.