From 548e7a8563d6ad523b0b715d08cd6bdda34948ad Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 10 Sep 2026 18:57:55 +0000 Subject: [PATCH] docs: review document for #521 Issue: #521 User-Visible: no --- docs/reviews/SPEC-REVIEW-521-r2.md | 202 +++++++++++++++++++++++++++++ 1 file changed, 202 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-521-r2.md diff --git a/docs/reviews/SPEC-REVIEW-521-r2.md b/docs/reviews/SPEC-REVIEW-521-r2.md new file mode 100644 index 00000000..d833ec9b --- /dev/null +++ b/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 → в задаче + +--- + + + +## Материал раунда + +- Ветка: `dev`, коммит `9592092b8eb9` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `01299fe4f0fe65c68b865d475932bf811e60d9ac` + ``` + git log --all --format='%H %T' | grep 01299fe4f0fe + ``` +- Тело issue: `ecdf5deb2acf08068eeb2f5e74e98a262d18f2011f4e26c672428abd72123093` +- Вердикт конвейера: `yellow` · High 0