docs: review document for #323

Issue: #323
User-Visible: no

docs/reviews/CODE-REVIEW-323-r1.md

@@ -1,176 +1,157 @@
-# CODE-REVIEW — issue #323, заход r1
+# CODE-REVIEW — issue #323, заход r2
 
-**SHA материала:** `69facb991882b336a8e4122abf7733faec56d5ba` (после ребейза
-конвейером: `fec74ff3` → `69facb99`, поверх легло 1 коммит `dev`; предыдущего
-верхнего коммита в родословной ветки нет — это исходный ребейз перед первым
-циклом ревью, разбор полный).
+**Примечание о нумерации.** Заголовок задачи, переданный конвейером, указывал
+«заход r1 · блокирующих циклов 0 из 2». Это не соответствует фактическому
+состоянию: в дереве уже лежит закоммиченный `docs/reviews/CODE-REVIEW-323-r1.md`
+(коммит `3b915bd0`, класс C, трейлеры корректны), а в комментариях issue есть
+жёлтый вердикт `заход r1 · блокирующих циклов 1/2`, полученный на SHA `69facb99`,
+и последующий комментарий владельца «r1 → r2: M1 закрыта» на HEAD `fb8fdf47`.
+Текущий разбор — фактически **r2**, бюджет циклов до этого раунда равен **1/2**
+(лимит короткого трека — 2, §5.1). Документ ниже назван и оформлен как r2;
+если шаг публикации всё же соберёт имя `CODE-REVIEW-323-r1.md` из переданного
+заголовка, он затрёт настоящий r1 — заголовок задачи нужно поправить на стороне
+конвейера.
 
-**Трек:** `trivial` (§5.1). AC зафиксированы автором в теле issue при переводе
-в `S5-ready`:
-1. бейдж `HACS-Custom` → `HACS-Default` (README.md, README.ru.md);
-2. секция установки — вместо «⋮ → Custom repositories» обычный поиск «House
-   Plan» в HACS; my-кнопка, перезапуск, добавление интеграции и заметка про
-   Lovelace-ресурс сохраняются.
+**SHA материала:** `fb8fdf479c503992667c45294b28aede2d5056c3` (`git rev-parse HEAD`
+непосредственно перед подведением итогов).
 
-**Класс изменения:** C (документация), без кода — `src/**`,
-`custom_components/**/*.py` не тронуты.
+**Трек:** `trivial` (§5.1), лимит код-ревью — 2 цикла.
 
-## Скоуп диффа
+**Класс изменения:** C (документация). `src/**`, `custom_components/**/*.py` не
+тронуты ни в этом раунде, ни в r1.
+
+## Скоуп раунда — дельта r1 → r2
+
+Предыдущий вердикт (r1, SHA `69facb99`) — жёлтый, High: 0, Medium: 1 (M1,
+в скоупе). Дельта объявлена по `git diff 69facb99..fb8fdf47`:
 
 ```
-README.md       | 11 ++++++-----
-README.ru.md    | 12 +++++++-----
-docs/STATUS.md  |  2 +-
-docs/TESTING.md |  2 +-
-4 files changed, 15 insertions(+), 12 deletions(-)
+docs/USER-GUIDE.md                | 6 +++---
+docs/USER-GUIDE.ru.md              | 4 ++--
+docs/reviews/CODE-REVIEW-323-r1.md | 176 ++++++++++++++++++++++ (публикация r1 конвейером)
+3 files changed
 ```
 
-Два коммита, оба с трейлерами `Issue: #323` / `User-Visible: no`:
-- `343af61a` — README.md + README.ru.md: бейдж и секция установки;
-- `69facb99` — попутно найденные устаревшие места: строка HACS в
-  `docs/STATUS.md` (описывала очередь из 835 PR) и пункт установки в
-  `docs/TESTING.md` (начинался с custom repository).
+Один продуктивный коммит: `fb8fdf47` — «docs: both user guides install from
+the HACS default catalog too», трейлеры `Issue: #323` / `User-Visible: no`,
+сообщение коммита прямо ссылается на `CODE-REVIEW-323-r1 M1`. Второй файл в
+дельте (`docs/reviews/CODE-REVIEW-323-r1.md`) — собственный doc-коммит
+публикации `3b915bd0`, ожидаемый и не являющийся предметом ревью.
 
-## Как проверялось
+Дельта локальна: правка ограничена ровно теми двумя файлами, что назвала
+находка M1, ничего за пределами её формулировки не задето. Ребейза на ушедший
+вперёд `dev` не было (родословная `fb8fdf47` — прямое продолжение `69facb99`),
+контракт поведения не менялся, новая подсистема не задета, объём дельты
+(10 строк в двух markdown-файлах) многократно меньше исходной задачи. Полный
+разбор не требуется — работает сокращение по §2.10.
 
-### AC — по коду (docs), проверено чтением
+## Закрытие раунда r1
 
-- **AC1 (бейдж).** `README.md:3` и `README.ru.md:3` — `HACS-Custom` →
-  `HACS-Default`, URL и alt-текст остались консистентны с прежним статичным
-  shields.io-бейджем (не live-бейдж, разница только в тексте/подписи).
-  Выполнено.
-- **AC2 (секция установки).** `README.md:88-95`, `README.ru.md:91-99` —
-  шаги «⋮ → Custom repositories» / «добавьте URL» убраны, заменены на
-  «найдите House Plan в поиске HACS и установите»; my-кнопка
-  (`my.home-assistant.io/.../hacs_repository`), шаг перезапуска, шаг «Add
-  integration → House Plan» и абзац про ручную регистрацию Lovelace-ресурса
-  (`resources: /houseplan_files/houseplan-card.js`) сохранены дословно.
-  Выполнено. Проверено чтением, не исполнением (docs-only, поведения карточки
-  правка не касается).
+| Находка r1 | Чем закрыта | Где видно |
+|---|---|---|
+| **M1** — `docs/USER-GUIDE.md` (82-83) и `docs/USER-GUIDE.ru.md` (82) учили добавлять custom-репозиторий вручную, противореча исправленному README | Шаг 1 в обоих файлах переписан: поиск «House Plan» в HACS, явная фраза «no custom repository needed» / «пользовательский репозиторий добавлять не нужно» — по образцу формулировки README | `docs/USER-GUIDE.md:82-83` (diff `69facb99..fb8fdf47`, коммит `fb8fdf47`); `docs/USER-GUIDE.ru.md:82` (тот же коммит). Проверено чтением: `sed -n '75,90p' docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` после правки, сверено построчно с формулировкой `README.md:88-91` / `README.ru.md:91-95` — смысл идентичен (входит в default-каталог, custom repository не нужен), терминология «основной каталог HACS» совпадает между RU-README и RU-USER-GUIDE |
 
-`hacs.json.name` = `"House Plan (card + storage)"` — поиск по подстроке
-«House Plan» в HACS находит запись; формулировка в README не вводит
-пользователя в заблуждение.
+Дополнительно перепроверено grep'ом по всему трекаемому дереву (не только
+`.md`, без исключений кроме CHANGELOG/reviews/specs, чтобы не полагаться
+на грепы r1 без проверки): `git grep -rniE "custom.{0,25}repositor|HACS-Custom|пользовательск\S*\s+репозитор|custom.{0,15}Integration.{0,15}repositor"`
+находит только четыре ожидаемых строки — по одной новой формулировке в каждом
+из четырёх файлов (README.md, README.ru.md, USER-GUIDE.md, USER-GUIDE.ru.md).
+Ни устаревших упоминаний, ни расхождений в `custom_components/**`, `src/**`
+или где-либо ещё не осталось. M1 закрыта полностью, новых мест с тем же
+дефектом дельта не оставила.
 
-### Гейты — прогнаны
+## Унаследовано из r1
+
+Без повторной проверки в этом раунде, ссылка — `docs/reviews/CODE-REVIEW-323-r1.md`
+на SHA `69facb99`:
+
+- **AC1** (бейдж `HACS-Custom` → `HACS-Default` в README.md/README.ru.md) —
+  дельта r1→r2 не трогает README, доказательство r1 не устарело.
+- **AC2** (секция установки README — поиск вместо custom repository, my-кнопка/
+  restart/add integration/YAML-ресурс сохранены) — та же причина, README не в
+  дельте.
+- Правки `docs/STATUS.md` и `docs/TESTING.md` (коммит `69facb99`) — вне дельты
+  этого раунда, признаны корректными в r1.
+- Трейлеры `Issue: #323` / `User-Visible: no` на коммитах r1 (`343af61a`,
+  `69facb99`) — проверены в r1, не переоценивались повторно.
+- Обоснование непрогона `check-docs.mjs`, инвариантов геометрии, смоков,
+  `golden:verify`, backend-тестов и perf-профилей для диффа README/STATUS/TESTING
+  (docs-only, `src/**` и геометрия не задеты) — рассуждение переносится и на
+  делту r2, поскольку она тоже чисто текстовая и тоже не касается `src/**`.
+- Пункт «чего не проверял» из r1 (живой поиск в HACS UI, докс-скриншоты,
+  отсутствие типа `bug` на трек `trivial`) — сохраняет силу, дельта этого
+  раунда на эти пункты не влияет.
+
+## Гейты этого раунда
+
+Дешёвые гейты прогнаны заново на `fb8fdf47`, как требует §2.10 (код/дерево
+изменились с r1, а стоят гейты минуты):
 
 | Гейт | Команда | Результат |
 |---|---|---|
-| Typecheck | `npx tsc --noEmit` | зелёный, без вывода |
+| Typecheck | `npx tsc --noEmit` | зелёный, без вывода, exit 0 |
+| Build | `npm run build` | зелёный, `dist/houseplan-card.js` собран за 11.9s |
+| Синхронность копий бандла | `git status --short dist/ custom_components/houseplan/frontend/ demo/srv/assets/` + `cmp dist/houseplan-card.js custom_components/houseplan/frontend/houseplan-card.js` | пусто / идентичны — класс D не менялся |
 | Unit-тесты | `npm test` | зелёный: 1358 объявлено, 1357 pass, 1 skipped, 0 fail |
-| Build | `npm run build` | зелёный, `dist/houseplan-card.js` собран за 9.3s |
-| Синхронность трёх копий бандла | `git status --short` после build | пусто — `dist/`, `custom_components/houseplan/frontend/`, `demo/srv/assets/` не тронуты и не разошлись (класс D не менялся, дифф его и не затрагивал) |
 
-Три гейта прогнаны, потому что они всегда дешёвые и прогоняются в каждом
-раунде независимо от объёма диффа — их результат актуален именно для
-`69facb99`, не унаследован.
+Не прогонялись, причина не изменилась относительно r1 (дельта тоже docs-only,
+не касается `src/**`, геометрии, рендера, backend):
 
-### Гейты — не прогонялись, и почему
+- `node scripts/check-docs.mjs` — дельта не трогает `src/**`, отпечаток
+  скриншотов не мог устареть от правки в двух markdown-файлах руководства.
+- `npm run invariants -- --config …` — geometry/`layout`/толщина стен/
+  `marker.space`/`open_spans` не задеты ни разу за оба раунда.
+- Браузерные смоки (`demo/smoke_*.mjs`) — изменённые символы это markdown-текст
+  `docs/USER-GUIDE*.md`, не код/тест; `smoke-select.mjs` не запускал по той же
+  причине, что и в r1 (инструмент ищет связи по изменённым символам кода/тестов,
+  а не по тексту руководств вне `demo/`).
+- `npm run golden:verify` — рендер, геометрия, стили не менялись.
+- `python -m pytest tests_backend -q` — `custom_components/**/*.py` не тронут.
+- Perf-профили — не названы в AC, не задеты.
 
-- `node scripts/check-docs.mjs` — не нужен: диплом не трогает `src/**`,
-  отпечаток скриншотов не может устареть от правки в README/STATUS/TESTING.
-- `npm run invariants -- --config …` — геометрия, `layout`, толщина стен,
-  `marker.space`, `open_spans` диффом не затронуты.
-- Браузерные смоки (`demo/smoke_*.mjs`) — диплом не меняет ни одной
-  видимой в карточке строки или поведения; `node scripts/smoke-select.mjs`
-  не запускал, т.к. измененные символы — это markdown-текст README/STATUS/
-  TESTING, а не код/тесты, по которым инструмент ищет связи. Смоки
-  рендерят `demo/srv/demo.html`, README/STATUS/TESTING в это дерево не
-  попадают.
-- `npm run golden:verify` — рендер, геометрия и стили не менялись.
-- `python -m pytest tests_backend -q` — `custom_components/**/*.py` не
-  тронут.
-- Perf-профили — не названы в AC, geometry/perf-пути не задеты.
+«Одно число — один источник»: дельта не вводит и не меняет пользовательских
+числовых величин; текстовая формулировка «в основном каталоге HACS, custom
+repository не нужен» теперь идентична между README и USER-GUIDE на обоих
+языках (см. таблицу закрытия M1 выше) — именно то расхождение, которое r1
+поймал как Medium, теперь устранено единообразно.
 
-## Находки
+## Находки этого раунда
 
-### Medium — В СКОУПЕ задачи
+Нет. High: 0, Medium: 0, Low: 0. Дельта — точечный фикс, ничего нового не
+внесла и не задела соседнее поведение.
 
-**M1. `docs/USER-GUIDE.md` и `docs/USER-GUIDE.ru.md` не обновлены и
-противоречат исправленному README.**
+## Проверено и корректно
 
-Обе версии полного руководства (на которое README ссылается как на «Full
-user guide» / «Полное руководство», и куда RU-README прямо отправляет за
-«пошаговыми сценариями») в разделе «HACS» / «Установка через HACS»
-по‑прежнему учат добавлять репозиторий вручную:
+- M1 закрыта: оба полных руководства (EN/RU) больше не учат ручному добавлению
+  custom-репозитория и текстуально согласованы с README.
+- Расширенный grep (не только `.md`, без предположения, что r1 нашёл всё)
+  подтверждает отсутствие других мест с тем же устаревшим паттерном.
+- Коммит `fb8fdf47` несёт корректные трейлеры (`Issue: #323`,
+  `User-Visible: no`); `User-Visible: no` обоснован — поведение карточки/
+  интеграции не меняется, только текст документации, changelog-файлы не
+  тронуты (согласуется).
+- Класс D (`dist/**`, `custom_components/houseplan/frontend/**`,
+  `demo/golden/baselines/**`) не менялся ни в дельте, ни ранее.
+- Doc-коммит публикации r1 (`3b915bd0`) корректно трейлерован и не является
+  предметом ревью — ожидаемый служебный коммит конвейера.
 
-```
-docs/USER-GUIDE.md:82-83
-1. Add `https://github.com/Matysh/houseplan-card` to HACS as a custom
-   **Integration** repository.
+## Чего не проверял
 
-docs/USER-GUIDE.ru.md:82
-1. В HACS добавьте `https://github.com/Matysh/houseplan-card` как
-   пользовательский репозиторий категории **Integration**.
-```
-
-**Воспроизведение:** пользователь читает README → видит «House Plan is in
-the HACS default catalog — no custom repository needed», переходит по
-ссылке «Full user guide» за подробностями → получает противоположную и
-устаревшую инструкцию (добавить custom repository вручную) в том же самом
-разделе «HACS». Это ровно та проблема, которую issue #323 ставит целью
-убрать («лишние шаги, которых больше не требуется»), просто в соседнем
-файле того же класса C.
-
-Автор этой же ветки уже расширял скоуп за пределы «только README»: коммит
-`69facb99` правит `docs/STATUS.md` и `docs/TESTING.md` как «попутно
-найденные устаревшие места» — тот же тип дефекта (стале-упоминание
-custom-repository потока), тот же класс C. USER-GUIDE — тот же случай,
-не пойманный при том же самом sweep (вероятная причина: непрямое
-совпадение по тексту — «custom **Integration** repository» с жирным между
-словами в EN и строчная «пользовательский» без грепаемого «HACS-Custom» в
-RU, — оба ускользают от точного grep по фразе «custom repository»).
-
-Без этой правки задача не решает заявленный сценарий полностью: у
-пользователя остаётся действующий (и более заметный, т.к. это «полное
-руководство») путь к устаревшей инструкции.
-
-**Что делать:** привести шаг 1 в обоих `docs/USER-GUIDE*.md` к тому же
-виду, что и в README (поиск в HACS вместо добавления custom-repository), в
-рамках этого же issue — Medium в скоупе, отдельный issue не заводится
-(#202).
-
-Других мест с той же формулировкой не нашлось (проверено
-`grep -rniE "custom.{0,20}repositor|HACS-Custom|пользовательск\S*\s+репозитор"
---include="*.md" .`, исключая CHANGELOG и `node_modules`; `docs/DEVELOPMENT.md`,
-`CONTRIBUTING.md` чисты).
-
-### Проверено и корректно
-
-- Бейдж и секция установки в обоих README согласованы между собой (EN/RU),
-  порядок шагов и сохранённые фрагменты (my-кнопка, restart, add
-  integration, YAML-ресурс) идентичны прежним, кроме заменённого шага.
-- `docs/STATUS.md` HACS-строка и `docs/TESTING.md` install-чеклист приведены
-  в соответствие факту (`hacs/default#9004` merged 2026-08-25) без потери
-  информации (post-merge checklist сохранён).
-- Трейлеры `Issue: #323` / `User-Visible: no` на обоих коммитах корректны:
-  продукт (карточка/интеграция) не меняется, значит changelog не требуется.
-- `docs/CHANGELOG.md` / `docs/CHANGELOG.ru.md` не тронуты — согласуется с
-  `User-Visible: no`.
-- Диплом не трогает `dist/**`, `custom_components/houseplan/frontend/**`,
-  `demo/golden/baselines/**` (класс D) — верно для чисто текстовой правки.
-- «Одно число — один источник»: числовых пользовательских величин дифф не
-  вводит и не меняет, правило не применимо к этому диффу за вычетом M1,
-  которое устройство ровно того же типа дефекта, но текстовое, а не
-  числовое.
-
-### Чего не проверял (и осознанно)
-
-- Живой поиск «House Plan» в HACS UI — недоступен в окружении ревьюера (нет
-  запущенного HA/HACS-инстанса); утверждение принято по ссылке на
-  `hacs/default#9004` (merged, зафиксировано владельцем в чате 2026-08-27,
-  процитировано в теле issue) и по `hacs.json.name`.
-- Скриншоты/докс-фингерпринт — не проверялись, т.к. `src/**` не тронут и
-  `check-docs.mjs` не применим (см. таблицу гейтов выше).
-- Отсутствие меты типа (`bug`/`feature`/`tech-debt`) на issue #323 при
-  наличии `trivial` — замечено (§5.1 требует тип `bug` в списке критериев
-  короткого трека), но это принятое владельцем в `S2-analysis` решение
-  (владелец лично перевёл в `S5-ready` и взял в работу), не предмет
-  код-ревью и не блокирует; не выношу отдельной находкой.
+- Живой поиск «House Plan» в интерфейсе HACS — недоступен в окружении
+  ревьюера; унаследовано из r1 без повторной попытки.
+- Докс-скриншоты/фингерпринт — не проверялись, `src/**` не тронут, `check-docs.mjs`
+  не применим ни в r1, ни в r2.
+- Отсутствие меты типа (`bug`/`feature`/`tech-debt`) на issue при наличии
+  `trivial` — уже отмечено и принято в r1 как решение владельца, не предмет
+  этого раунда.
 
 ## Вердикт
 
-High: 0. Medium: 1, в скоупе задачи (M1) — чинится в этом же issue.
-Полный набор AC доказан, но задача не закрывает сценарий целиком, пока
-второй документ с теми же инструкциями противоречит первому — поэтому
-вердикт жёлтый, а не зелёный, несмотря на 0 High.
+High: 0. Medium: 0. M1 из r1 закрыта полностью и без побочных находок. Все
+AC (унаследованные из r1, дельта их не задевает) доказаны; дополнительная
+находка r1, из-за которой стоял жёлтый, устранена — задача теперь решает
+заявленный сценарий целиком: и README, и полное руководство на обоих языках
+согласованно говорят «House Plan уже в default-каталоге HACS, custom
+repository не нужен».
+
+Вердикт: зелёный.