diff --git a/docs/reviews/SPEC-REVIEW-668-r2.md b/docs/reviews/SPEC-REVIEW-668-r2.md new file mode 100644 index 00000000..60819650 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-668-r2.md @@ -0,0 +1,136 @@ +# SPEC-REVIEW-668-r2 + +**Issue:** [#668](https://github.com/Matysh/houseplan-card/issues/668) — «EN user guide отстаёт от RU» (перевод/синхронизация `docs/USER-GUIDE.md` с `docs/USER-GUIDE.ru.md`, выделено из #667 п.8) +**Этап:** spec (`S4-spec-review`) · трек: полный (метки `P2`, `docs`, `S4-spec-review`; ни `small`, ни `trivial` не выставлены) +**Заход:** r2 · блокирующих циклов израсходовано 1 из 4 +**Материал:** тело issue #668, раздел `## ТЗ` (получено `gh issue view 668 --json body` на момент этого захода). Ветка `issue/668-user-guide`, HEAD `0d15200b39e1ed40c755540cdb442f9f05485044` — этот коммит добавляет только `docs/reviews/SPEC-REVIEW-668-r1.md`; `git diff origin/dev...HEAD --stat` кроме этого файла ничего не показывает, спек-стадия кода не касалась. +**Роль:** ревьюер ТЗ, независимая сессия, без контекста автора. + +## Скоуп проверки + +Дельта раунда — правка тела issue после жёлтого вердикта r1: комментарий автора +от `2026-09-27T08:44:07Z` («Замечание r1 исправлено: AC4 теперь явно разделяет +два доказательства, а план автотестов требует извлекать и сравнивать строки +версии EN/RU. Заодно зафиксировано, что реализация расширяет уже существующий +структурный гейт `check-docs`, а не создаёт независимый дублирующий контракт») +описывает точечную правку одной строки таблицы AC и одного пункта «Плана +автотестов». Дельта локальна: ни скоуп, ни остальные AC, ни контракт +документации не тронуты. По §2.10 разбор в r2 сокращён до дельты — единственной +находки r1 (Medium на AC4) — и повторной проверки того, что она не породила +новых противоречий; остальное наследуется из r1 без повторного прохода (раздел +ниже). + +## Как проверялось + +1. Получено текущее тело issue #668 (`gh issue view 668 --json body`) и полный + список комментариев (`gh issue view 668 --json comments`), включая вердикт + пайплайна r1 и последующий комментарий автора о правке. +2. Сверена таблица AC построчно с r1: изменилась только строка AC4; строки + AC1–AC3, AC5–AC7 побайтово совпадают с цитатами в + `docs/reviews/SPEC-REVIEW-668-r1.md`. +3. Раздел «План автотестов» сверен построчно: добавлен один пункт («Явно + тестировать извлечение строки `Current for` / `Актуально для` и красный + результат при разных версиях»); остальные четыре пункта не изменились. +4. Посчитан `sha256` нормализованного тела issue текущего раунда + (`scripts/review-doc-guard.mjs` → `issueBodyDigest`, нормализация CRLF/ + хвостовых пробелов — та же функция, что использует конвейер): + `aeef91d8b412d0d7dddc4e4c9179746e50a716ed6a80a3078c645cdd925fd5b2`. Он не + совпадает с якорем r1 (`6f92c0a35cb43dd19a414618b4d1f9c48394a8107b95c61bacbe7fbf03d8bef9` + — 64-символьный хеш, свёрнутая проверка подтверждает несовпадение), что + подтверждает: тело действительно правилось после r1, а не переиздано + без изменений. +5. Проверено, что ветка задачи не продвинулась дальше документа предыдущего + ревью: `git diff origin/dev...origin/issue/668-user-guide --stat` показывает + только добавление `docs/reviews/SPEC-REVIEW-668-r1.md`. DoR не нарушено + преждевременной реализацией; спек-ревью и дальше имеет дело только с + текстом issue. +6. Обязательные разделы §7.1 и их порядок повторно не пересчитывались построчно + (это не тронуто дельтой) — унаследовано из r1 с явной пометкой ниже. + +## Закрытие раунда r1 + +| Находка r1 | Чем закрыта | Где это видно | +|---|---|---| +| Medium — AC4 объединяла под одним методом два разных утверждения («unit» отсылало к тесту, которого не было в плане автотестов) | Таблица AC переписана: `AC4` теперь явно разносит методы — `unit: структурный гейт извлекает и сравнивает отметки версии` для равенства версии, `проверка diff подтверждает неизменность RU/продукта` для второго утверждения. План автотестов дополнен пунктом, прямо называющим тест на извлечение строк `Current for` / `Актуально для` и красный результат при их несовпадении — то есть тест, на который теперь ссылается «unit» в AC4, в документе назван и специфицирован (что именно он читает и когда краснеет). | Тело issue #668, таблица `### Acceptance criteria`, строка `AC4`; раздел `### План автотестов`, четвёртый пункт («Явно тестировать извлечение строки…»). Подтверждено также прямым комментарием автора `2026-09-27T08:44:07Z`. | +| Low (снято ревьюером r1, для протокола) — ТЗ не говорит, заменяет ли новый AC6-тест частичный `docs-section`-гейт `check-docs.mjs:172-185` или сосуществует с ним | Не требовало правки ТЗ (снято как заметка для код-ревью, не блокировало). Комментарий автора добавляет: «реализация расширяет уже существующий структурный гейт `check-docs`, а не создаёт независимый дублирующий контракт» — технический выбор объявлен, само ТЗ по-прежнему оставляет точную раскладку реализации на усмотрение автора, что и было приемлемо в r1. | Комментарий автора `2026-09-27T08:44:07Z`; формулировка Scope в теле issue («Точное выделение helper-модуля остаётся техническим решением реализации») не менялась. | + +Обе строки таблицы предыдущего раунда закрыты текстом, а не заявлением: правка +видна в самом теле issue, а не только декларируется в комментарии. + +## Унаследовано из r1 + +Без повторной проверки в r2, поскольку дельта их не касается — материал: +`docs/reviews/SPEC-REVIEW-668-r1.md`, тело issue на момент r1 (`sha256` +`6f92c0a35cb43dd19a414618b4d1f9c48394a8107b95c61bacbe7fbf03d8bef9`), ветка +`issue/668-user-guide` (дерево материала `1ccf52c4df9d7dfc33d3e5cbb63baf142eab53a2`): + +- Все обязательные разделы §7.1 присутствуют и идут в правильном порядке + (таблица «Обязательные разделы» в r1). +- Численная база ТЗ (57 vs 98 заголовков, 23 нумерованных раздела + памятка + безопасности, список отсутствующих тем) сверена с реальным `dev` построчно и + подтверждена, догадок, выданных за факт, не найдено. +- AC1 сверен с обоими файлами руководства дословно; AC6 — защитный AC, + метод доказательства и «чем краснеет» названы уже на этапе ТЗ (негативная + проба на временных фикстурах). +- Contract-раздел закрывает риски ссылок, i18n-сверки и протокол расхождения + RU с продуктом до того, как они стали открытыми вопросами. +- Не-scope корректно исключает переписывание RU, побуквенный перевод, новые + скриншоты/changelog. +- `User-Visible: no` соответствует правилу AGENTS.md для документационного + изменения, не прячет пользовательское изменение. +- Ветка создана от актуального `dev`; на момент r1 код/документ не были + тронуты — DoR не нарушалось. В r2 это утверждение проверено заново (см. «Как + проверялось», п.5) и подтверждено на новом SHA `0d15200b`. +- Открытых продуктовых вопросов к владельцу в ТЗ нет; две технические + развилки («принято предположительно») по-прежнему корректно помечены и не + эскалированы искусственно. + +## Что проверено и корректно (в этом раунде) + +- AC4 больше не смешивает под одной пометкой «unit» два разных утверждения: + теперь у равенства версии есть названный тест (извлечение и сравнение строк + `Current for` / `Актуально для`, красный результат при расхождении версий), + а у «RU/продукт не менялись» — метод «проверка diff», что для утверждения + такого рода (по сути повторение Non-scope) остаётся приемлемым способом + доказательства, не требующим отдельного автотеста. +- Правка не задела ни одну другую строку ТЗ: Scope, Non-scope, Contract, + модель данных/i18n, AC1–AC3 и AC5–AC7, риски, откат и release-артефакты + текстуально идентичны версии r1 — новых противоречий делта не вносит. +- Дельта учтена и в «Плане автотестов» (не только в таблице AC): формулировка + теста на строку версии присутствует именно там, где ревью r1 требовало её + найти, а не только в самой AC-таблице — расхождения между двумя разделами + того же ТЗ, которое было сутью находки r1, больше нет. +- Материал не продвинулся дальше документа r1 в код — спек-ревью по-прежнему + имеет дело только с текстом, преждевременной реализации нет. + +## Чего не проверял + +- Не пересчитывал заново заголовки RU/EN (`grep -n '^#'`) и не перечитывал + весь текст ТЗ построчно за пределами делты — дельта локальна и это сделано + в r1; см. раздел «Унаследовано из r1». +- Не запускал `npm test` / `npx tsc --noEmit` / `npm run build` / `npm run + gate:small` / `node scripts/check-docs.mjs` — на этапе ТЗ кода по-прежнему + нет (ветка несёт только предыдущий документ ревью), эти гейты неприменимы к + спек-ревью. +- Не оценивал качество будущего перевода/содержания разделов — их всё ещё не + существует; AC2/AC3 остаются предметом код-ревью по договорённости ТЗ. +- Не проверял `scripts/check-docs.mjs:172-185` повторно (номера строк, факт + частичного гейта) — это не менялось дельтой и было подтверждено в r1. + +## Вердикт + +Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0 → в задаче + +--- + + + +## Материал раунда + +- Ветка: `issue/668-user-guide`, коммит `0d15200b39e1` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `cc0afe245a53befaf9c5e823dde9409f2f9a1331` + ``` + git log --all --format='%H %T' | grep cc0afe245a53 + ``` +- Тело issue: `aeef91d8b412d0d7dddc4e4c9179746e50a716ed6a80a3078c645cdd925fd5b2` +- Вердикт конвейера: `green` · High 0