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

# 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