docs: review document for #521

Issue: #521
User-Visible: no

docs/reviews/SPEC-REVIEW-521-r2.md

@@ -0,0 +1,202 @@
+# SPEC-REVIEW — issue #521 — заход r2
+
+**Этап:** S4-spec-review (PROCESS.md §2.4) · **Трек:** полный (нарушен критерий
+§5 «нет влияния на производительность и на touch-контракт», названо самим
+автором в S2) · **Заход:** r2 (второй) · **Бюджет циклов:** 1/4 израсходовано
+до этого вердикта (r1 — жёлтый, потратил цикл 1; зелёный цикла не тратит, #227).
+
+## Скоуп ревью
+
+Материал — тело issue #521, раздел `## ТЗ`, в редакции после комментария
+автора «Исправление по ревью ТЗ r1 → заход r2» (2026-09-10T18:52:31Z). Автор
+заявляет дельту r1→r2 как «один абзац рамки и один пункт рисков» — правку
+единственной находки r1 (Medium: «Продуктовая рамка» ссылалась на несуществующее
+описание в `docs/USER-GUIDE.ru.md`). Тема ТЗ (регресс направляющих
+выравнивания во всех трёх живых жестах редактора) и весь контракт/AC/откат/
+release-артефакты не менялись.
+
+Разбор веду по §2.10: находка r1 проверяется на закрытие, AC/контракт
+наследуются без повторной проверки, поскольку дельта их не касается. Полный
+повторный разбор не требуется — дельта локальна (переписан один абзац одного
+раздела плюс добавлен один пункт риска), подсистема та же, контракт поведения
+не менялся.
+
+## Как проверялось
+
+- прочитано текущее тело issue #521 целиком (`gh issue view 521 --json body`)
+  и сверено с документом `docs/reviews/SPEC-REVIEW-521-r1.md` (вердикт,
+  находка, материал раунда);
+- прочитаны все четыре комментария issue в хронологическом порядке
+  (аналитика S2, «ТЗ готово — на ревью», вердикт r1, «Исправление по ревью ТЗ
+  r1 → заход r2»), чтобы отличить объявленную дельту от подтверждённой чтением;
+- заявление автора «Контракт, AC1–AC9, откат и release-артефакты не тронуты»
+  проверено не на слово: сопоставлены разделы «Контракт» (п.1–6), таблица
+  AC1–AC9 и разделы «Откат»/«Release-артефакты» текущего тела с их описанием
+  в документе r1 (конкретные ссылки на код, номера мутантов
+  `align-point-reads-frozen-snapshot`, `live-editor-devices-drops-align-guides`
+  и т.д., которые r1 разбирал построчно) — расхождений не найдено, дельта
+  подтверждается содержанием, а не только словами автора;
+- заново прочитан переписанный абзац «Продуктовой рамки» и новый пункт
+  «Долг документации» в «Рисках» — построчно, не по пересказу автора;
+  каждая ссылка и утверждение в них перепроверены независимо (см. «Находки»
+  и «Закрытие раунда r1»):
+  - `grep -n -i "выравнив\|направляющ\|якор\|align" docs/USER-GUIDE.ru.md` —
+    подтверждено, 0 совпадений на 2241 строку, ссылка на отсутствие описания
+    в руководстве в новой редакции верна;
+  - `_renderAlignGuides`, классы `.alignline`/`.aligndot`,
+    `demo/smoke_align_guides.mjs`, #400, `c0d61ca3` — все существуют и
+    соответствуют тому, что подтвердил r1 построчной сверкой с кодом на
+    `dev`; здесь не перепроверялись заново (наследуются, см. ниже), новых
+    ссылок на код в этом абзаце не добавлено;
+  - `AGENTS.md` (репозиторий) — существует, строки 21–23 действительно
+    формулируют «interface wording comes from there and is not invented»;
+    ссылка на него в новой редакции точна;
+  - `CLAUDE.md §4` — **проверено и не подтверждено**, см. находку ниже:
+    `find . -iname "CLAUDE.md"`, `git log --all --diff-filter=A --name-only`
+    и полнотекстовый `grep -rn "CLAUDE.md" --include="*.md" .` по всему
+    дереву репозитория (включая всю историю веток) — файла нет и никогда не
+    было, ни одна документация репозитория на него не ссылается;
+- этап spec: продуктовый код не менялся, гейты код-ревью (§8) здесь не
+  применяются — не запускались, как и в r1.
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+|---|---|---|
+| Medium: «Продуктовая рамка» утверждала, что восстанавливаемое поведение «описано в `docs/USER-GUIDE.ru.md» — полнотекстовый поиск даёт 0 совпадений, факт не подтверждён | Абзац переписан: источник поведения назван явно — код и тесты (`_renderAlignGuides`, `.alignline`/`.aligndot`, смок, #400, диагностика `c0d61ca3`); отсутствие описания в руководстве названо прямо и помечено как «долг документации», а не выдано за факт задокументированного поведения | Тело issue #521, `## ТЗ` → «Продуктовая рамка», абзац, начинающийся «Ничего нового не появляется. Восстанавливаемое поведение зафиксировано **в коде и тестах, а не в документации пользователя**…»; тот же факт продублирован новым пунктом «Долг документации» в разделе «Риски» |
+
+Находка закрыта по существу — старой ложной ссылки на `docs/USER-GUIDE.ru.md`
+как источник поведения в тексте больше нет, а сам факт (поведение
+задокументировано только в коде/тестах, не в пользовательском руководстве)
+подтверждается независимо. Но правка ввела новую ссылку того же типа —
+утверждение о существовании документа, которого нет (см. находку ниже):
+устранение находки r1 механически корректно, содержательно — нет, потому что
+на её месте появился новый экземпляр той же категории дефекта.
+
+## Унаследовано из r1
+
+Без повторной проверки в этом раунде приняты выводы `docs/reviews/SPEC-REVIEW-521-r1.md`
+(материал того раунда: `dev`, коммит `c50bc725c895`; тело issue —
+sha256 `bf26b17118240771206ed2a7f26f10c82783ea586679def63cbc17e538c38cfe`),
+поскольку дельта r2 их не задевает:
+
+- диагноз и причинность регресса (два независимых слома от `c0d61ca3`/#451) —
+  подтверждены r1 построчно по коду на `dev`;
+- контракт п.1–6 — технически осуществим, ссылки на `_renderAlignGuides()`,
+  `_livePos`, `scheduleHouseplanEditor`, `makeTransparent` точны;
+- таблица AC1–AC9 «AC · чем доказан · чем краснеет» — заполнена без пустых
+  ячеек, каждый пункт однозначен и называет способ доказательства и мутацию;
+  проверено r1, что ссылки на существующие мутанты/сценарии (#400, `noneInView`)
+  реальны, а не выдуманы;
+- откат — один revert, не касается данных/конфига/публичных контрактов;
+- release-артефакты — тексты обоих changelog названы дословно, `User-Visible: yes`;
+- перф и touch — риски названы явно, соответствуют требованию DoR при
+  нарушенном критерии `small`;
+- объём задачи (все три жеста в одной issue) — продуктовый вопрос уже задан
+  автором владельцу в установленной форме (что неясно · дефолт · приглашение
+  возразить), повторный запрос от ревьюера был бы дублированием.
+
+Технические разделы «Что не проверял» из r1 (не запускались гейты код-ревью;
+не оценивалась реализуемость подавления `.hp-editor-only-layer`; не
+оценивался бюджет тестового счётчика осевых циклов) остаются в силе тем же
+образом — это предмет код-ревью, а не этого раунда.
+
+## Находки
+
+### Medium — новая ссылка на несуществующий документ в том же абзаце, который правил находку r1
+
+**Файл:** тело issue #521, раздел `## ТЗ` → `### Продуктовая рамка` (правка
+r1→r2).
+
+**Формулировка.** Переписанный абзац заканчивается: «у поведения нет
+принятого владельцем названия в интерфейсной терминологии, а изобретать его
+в обход `docs/USER-GUIDE.ru.md` запрещено (`AGENTS.md`, CLAUDE.md §4)».
+Файла `CLAUDE.md` в репозитории нет — ни сейчас, ни когда-либо в истории:
+
+```
+find . -iname "CLAUDE.md"                              → пусто
+git log --all --diff-filter=A --name-only | grep -i "^CLAUDE.md$"  → пусто
+grep -rn "CLAUDE.md" --include="*.md" .                 → пусто (кроме этого ТЗ)
+```
+
+Ни один канонический документ проекта (`AGENTS.md`, `PROCESS.md`,
+`docs/SCOPE.md`) не упоминает `CLAUDE.md` и не ссылается на него как на
+источник правил. «§4» этого документа — ссылка на несуществующий раздел
+несуществующего файла.
+
+**Почему это находка, а не мелочь.** Это ровно тот же класс дефекта, что и
+закрытая находка r1: утверждение о существовании нормативного документа,
+поданное как факт без пометки «предположение», не подтверждаемое ничем в
+репозитории. Разница лишь в том, что здесь дефект попал в текст **той самой
+правки**, которая закрывала предыдущий экземпляр того же дефекта — то есть
+причина находки r1 (ссылка бралась «из привычки», по словам автора, без
+проверки) не устранена как практика, только конкретное ложное утверждение
+заменено на другое. `AGENTS.md` (единственный существующий из двух названных
+источников) действительно требует того же самого по существу — запрет
+изобретать интерфейсную терминологию в обход `docs/USER-GUIDE.ru.md` — поэтому
+нормативная опора у фразы есть, но она наполовину состоит из выдуманной
+ссылки.
+
+**Не блокирует контракт.** Как и в r1, AC1–AC9 не опираются на эту фразу: она
+живёт исключительно в продуктовой рамке, поясняющей, почему долг
+документации не закрывается в этой задаче. Технической правки контракта или
+AC не требует.
+
+**Чем закрывается.** Убрать `CLAUDE.md §4` из скобок, оставив `AGENTS.md`
+(единственная реально существующая и подходящая по содержанию ссылка), либо
+дать точную ссылку на реальный раздел, если автор имел в виду что-то другое.
+
+## Что проверено и признано корректным
+
+- **Дельта соответствует заявленной.** Сравнение текущего тела с описанием
+  находки r1 и с комментарием автора «Исправление по ревью ТЗ r1 → заход r2»
+  подтверждает: правка ограничена абзацем «Продуктовой рамки» и одним новым
+  пунктом «Долг документации» в «Рисках»; контракт, AC1–AC9, откат и
+  release-артефакты текстуально не менялись (сверено построчно, не на слово
+  автора).
+- **Факт отсутствия описания направляющих в `docs/USER-GUIDE.ru.md`** —
+  переподтверждён самостоятельным `grep`, не только цитатой из r1: 0
+  совпадений на `выравнив|направляющ|якор|align` в 2241 строке.
+- **Ссылка на `AGENTS.md` в новом абзаце** — точна: строки 21–23 файла
+  действительно формулируют требование не изобретать интерфейсную
+  терминологию в обход `docs/USER-GUIDE.ru.md`.
+- **Новый пункт «Долг документации» в «Рисках»** — не блокирует задачу,
+  корректно описывает открытый вопрос (терминологию называет владелец) и не
+  расширяет скоуп задачи.
+
+## Чего не проверял
+
+- Не перепроверял построчно код (`_renderAlignGuides`, `_alignPoint`,
+  `live-editor.ts`, `houseplan-editor-runtime.ts`) — дельта r2 его не
+  касается, вывод r1 наследуется (см. «Унаследовано из r1»).
+- Не запускал `tsc`/`test`/`build`/смоки — этап spec-review, продуктового
+  кода ещё нет, гейты §8 к этому этапу не относятся.
+- Не связывался с владельцем по вопросу объёма задачи (три жеста в одной
+  issue) — вопрос уже задан автором в установленной форме в r1, статус не
+  изменился.
+- Не проверял технические AC-детали, не задетые дельтой (счётчик осевых
+  циклов, бюджет `test/**`/`demo/**`) — они остаются предметом код-ревью, как
+  и было записано в r1.
+
+## Вердикт
+
+Единственная находка — Medium, в скоупе задачи (текстовая правка одной
+вставки в теле ТЗ, без изменения контракта/AC), High нет. По PROCESS.md
+§2.4/§2.10/§4 это жёлтый вердикт: автор правит ТЗ, фикс проходит следующий
+заход ревью по дельте.
+
+Вердикт: жёлтый · заход r2 · блокирующих циклов 2/4 · High: 0 · Medium: 1 → в задаче
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `dev`, коммит `9592092b8eb9` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `01299fe4f0fe65c68b865d475932bf811e60d9ac`
+  ```
+  git log --all --format='%H %T' | grep 01299fe4f0fe
+  ```
+- Тело issue: `ecdf5deb2acf08068eeb2f5e74e98a262d18f2011f4e26c672428abd72123093`
+- Вердикт конвейера: `yellow` · High 0