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 → в задаче

---

Материал раунда

• Ветка: dev, коммит 9592092b8eb9 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 01299fe4f0fe65c68b865d475932bf811e60d9ac

  git log --all --format='%H %T' | grep 01299fe4f0fe
  

• Тело issue: ecdf5deb2acf08068eeb2f5e74e98a262d18f2011f4e26c672428abd72123093
• Вердикт конвейера: yellow · High 0