From cc9387163edd652edfb17a52cd1b554fd776dd5b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Fri, 4 Sep 2026 16:29:12 +0000 Subject: [PATCH] docs: review document for #454 Issue: #454 User-Visible: no --- docs/reviews/SPEC-REVIEW-454-r2.md | 161 +++++++++++++++++++++++++++++ 1 file changed, 161 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-454-r2.md diff --git a/docs/reviews/SPEC-REVIEW-454-r2.md b/docs/reviews/SPEC-REVIEW-454-r2.md new file mode 100644 index 00000000..638d1926 --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-454-r2.md @@ -0,0 +1,161 @@ +# SPEC-REVIEW — issue #454 · заход r2 + +- Issue: https://github.com/Matysh/houseplan-card/issues/454 +- Этап: ТЗ на ревью (PROCESS.md §2.4), заход r2, блокирующих циклов израсходовано 1 из 4 +- Материал: `docs/specs/454-review-round-counter.md` на коммите `f3e60578` (комментарий автора «Замечание r1 (M1) исправлено, ТЗ обновлено: `f3e60578`», ветка `issue/454-review-round-counter`) +- Предыдущий раунд: r1, жёлтый, документ `docs/reviews/SPEC-REVIEW-454-r1.md`, материал `ebcf1223` +- Ревьюер: свежая сессия, без контекста написания ТЗ и r1 + +## Скоуп разбора + +Разбор по дельте (PROCESS.md §2.9/§2.10). Дельта — один коммит `f3e60578`, +`git diff ebcf1223..f3e60578 -- docs/specs/454-review-round-counter.md`: +32 строки в одном файле, три места: + +1. одна строка таблицы «Факты по #449» (маркер в теле код-вердикта 16:01); +2. абзац под таблицей, объясняющий эту строку, плюс следствие в «не-скоупе» + про необратимую потерю `spent` первого спек-раунда #449; +3. переформулировка **AC2** + новый **AC2b** + синхронный абзац в «Плане + тестирования». + +Ребейза не было (родитель дельты — тот же `ebcf1223`, на котором получен r1). +Контракт поведения (§1–§5 ТЗ), скоуп/не-скоуп по составу, карта реализации, +риски, release-артефакты — не тронуты дельтой, разбираю их по r1, без +повторной проверки. Задета только доказательная база одного AC и одна +фактическая иллюстрация в разделе «Подтверждённая проблема» — сокращённый +разбор оправдан, дельта локальна. + +## Как проверялось + +Правки не вношу — только читаю и перепроверяю исполнением/рассуждением на +реальных данных. + +- Прочитан диф `git diff ebcf1223..f3e60578` целиком (не только резюме автора). +- Independently (не со слов автора) снят фактический снимок #449 на сегодня: + - `gh issue view 449 --repo Matysh/houseplan-card --json comments` — все + комментарии-вердикты с их точным текстом; + - `git show origin/dev:docs/reviews/SPEC-REVIEW-449-r1.md` / + `…-r2.md` / `CODE-REVIEW-449-r1.md` / `…-r2.md` — содержимое и + собственная итоговая строка вердикта каждого файла; + - `git show :docs/reviews/SPEC-REVIEW-449-r1.md` на трёх исторических + блобах (`1ce62613`, `070c276e`, `b39f99b3`), названных автором, чтобы + подтвердить, что `-r1.md` физически содержит тело второго раунда, а + `-r2.md` — третьего. +- По этим данным вручную пересчитаны обе формулы контракта §1–§3 ТЗ для + фикстур AC2 и AC2b (см. «Закрытие раунда r1» ниже) — не поверил заявлению + автора на слово, получил числа заново из первичных данных. +- Прочитан весь остаток документа (шапка, скоуп/не-скоуп, контракт, + крайние случаи, AC1–AC9, карта реализации, риски, release-артефакты, + принятые предположения) на предмет того, не сломала ли дельта что-то, + что дельта не должна была трогать — не сломала. + +Гейты (`tsc`/`test`/`build`/`check-docs`/`invariants`/смоки/`golden`) не +гонял: класс изменения — документация ТЗ, реализации на ветке нет +(`scripts/review-doc-guard.mjs`, `test/review-doc-guard.test.mjs` на ветке +задачи отсутствуют), это унаследовано из r1 и дельтой не задето. + +## Закрытие раунда r1 + +| Находка r1 | Чем закрыта | Где это видно | +|---|---|---| +| **M1** (Medium, в скоупе): AC2 требовала `attempt=3, spent=2` на фикстуре «реальные данные #449», но буквальный пересчёт по реальным файлам/комментариям даёт `spent=1` — план тестирования не указывал, какое из двух прочтений (буквальное или реконструкция) имеется в виду | AC2 переписан на буквальный слепок (`attempt=3, spent=1`), добавлен отдельный AC2b на реконструкцию («история, прожитая с исправлением», `attempt=4, spent=2`); «План тестирования» называет обе фикстуры по имени и раздельно; в «не-скоупе» явно зафиксировано, что `spent=1` на сегодняшних данных — правильный ответ, а не недосчёт | `docs/specs/454-review-round-counter.md:96‑111,174‑194` (коммит `f3e60578`). Перепроверено мной независимо: `SPEC-REVIEW-449-r1.md` на `origin/dev` содержит тело раунда 2 (собственная финальная строка — «жёлтый вердикт... возвращается автору»), `…-r2.md` — тело раунда 3 (финал — «зелёный вердикт... бюджет циклов не тратит»); `attemptFromFiles=max(1,2)+1=3`, `spentFromFiles=1` (только `-r1.md` блокирующий); `spentFromComments`: из трёх комментариев маркер несут два (14:56, 15:17), из них блокирующий один (14:56) → `1`. `max(1,1)=1`. Совпадает с новой формулировкой AC2 | +| L1 (Low, была снята с записью в r1, без обязательства правки) — нет разделов «UX»/«i18n»; r1 предлагал добавить строки-заглушки «заодно», если раунд правит документ | Не добавлено — но это была необязательная опция («было бы уместно… не отдельным циклом»), не требование; L1 уже была закрыта самим r1 без возврата автору | Текущий текст ТЗ: шапка по-прежнему содержит только `Touch editor: not exposed`, строк «UX:»/«i18n:» нет — не регрессия, а неиспользованная опция | +| L2 (Low, к сведению, не в счёт вердикта) — cohesion `review-doc-guard.mjs` | Не поднималась к правке в r1 и не поднимается сейчас — technical, оставлена автору кода | Карта реализации не изменилась дельтой | + +## Унаследовано из r1 + +Без повторной проверки принимаю из `docs/reviews/SPEC-REVIEW-454-r1.md` +(материал `ebcf1223`) — дельта этих мест не касается: + +- **Контракт §1** (источник истины — файлы, `max+1`, а не количество) и его + проверка на крайних случаях (дыра в нумерации, пустое множество файлов). +- **Контракт §2** (строка вердикта, `жёлт`/`красн` без учёта регистра) — + совпадает с существующим `process.yml:100`. +- **Контракт §3** (страховка максимумом) — `max(a,b)` не может дать + перерасчёт при данном построении источников. +- **AC1, AC3–AC7** — формулировки однозначны, способ доказательства достижим; + AC4/AC5/AC7 согласованы с уже действующими инвариантами #227/#89. +- **AC8, AC9** — синхронизация `process.yml` main/dev через существующий шаг + Validate; логика в тестируемом модуле, а не в inline-shell. +- **Не-скоуп** (ручная правка задним числом комментария #449, восстановление + `SPEC-REVIEW-449-r1.md`, обязательный гейт «назови файл») — исключения + корректны и не додуманы. +- **Ограничение «`process.yml` идентичен в main и dev»**, **план отката**, + **release-артефакты** (`User-Visible: no`, класс B, трейлеры). +- Технические наблюдения L1/L2 (не блокируют, см. таблицу выше). + +## Что проверено и корректно (дельта) + +- **AC2 (новая формулировка).** Число `attempt=3, spent=1` подтверждено + независимым пересчётом по первичным данным (см. «Как проверялось» и + таблицу закрытия) — не осталось расхождения, из-за которого r1 вернул ТЗ. + Фикстура названа однозначно («буквальный слепок сегодняшнего состояния + ветки»), способ доказательства не изменился (unit). +- **AC2b (новый).** Формула контракта §1/§3, применённая к трём + независимым файлам (`r1` жёлтый, `r2` жёлтый, `r3` зелёный), даёт + `attemptFromFiles=max(1,2,3)+1=4`, `spentFromFiles=2` (r1, r2 блокирующие, + r3 нет) — совпадает с заявленным `attempt=4, spent=2`. Формулировка не + оставляет второго прочтения: явно названа «реконструкция», а не факт. +- **Правка в «Подтверждённая проблема» про код-вердикт 16:01.** Автор + дополнительно (сверх M1) исправил собственную фактическую ошибку: красный + код-вердикт 16:01 содержит подстроку `CODE-REVIEW` в свободном тексте + («путь соберёт шаг публикации, `CODE-REVIEW-449-r1`»), а не отсутствует, + как было написано раньше. Проверено дословно по тексту комментария + (`gh issue view 449 --json comments`, комментарий `2026-09-04T16:01:28Z`, + последний абзац) — подстрока действительно там. Утверждение «guard видит… + один код-вердикт из одного (`attempt=2`, верно)» было точным на момент + написания дельты (единственный код-вердикт на #449 в тот момент — этот + красный). Это иллюстрация в разделе с фактажом, не часть контракта или + AC — её точность на дальнейшее развитие живого issue #449 не влияет на + доказательность AC2/AC2b, которые используют замороженную (unit-)фикстуру, + а не пересчёт по живому issue при каждом прогоне теста. +- **Внутренняя согласованность документа после правки.** Прочитан документ + целиком: старое утверждение «дефект повторится на первом же возврате #449 + в S7-code-review» удалено (заменено на факт про 16:01), нигде в остальном + тексте (скоуп, контракт, карта реализации, риски) на него больше нет + ссылок — висячих противоречий не осталось. + +## Чего не проверял + +- Не гонял гейты (`tsc`/`test`/`build`/`check-docs`/`invariants`/смоки/ + `golden`/`pytest`) — класс изменения документация, кода на ветке нет; + унаследовано из r1, дельта тоже только в `.md`. +- Не проверял `gh api`/`git ls-remote` на предмет реальной способности + перечислить файлы `docs/reviews/` на произвольной ветке без checkout — + унаследовано из r1 как «техническая деталь реализации, не продуктовое + ограничение», дельта эту часть контракта (§4 ТЗ) не трогает. +- Не проверял дальнейшую судьбу код-этапа #449 после комментария 16:01: на + момент этого ревью на issue #449 уже существует второй код-вердикт + (зелёный, `2026-09-04T16:22:58Z`, опубликован как + `docs/reviews/CODE-REVIEW-449-r2.md` без коллизии имени — комментарий сам + явно называет свой документ). Это не расходится с текстом ТЗ (иллюстрация + фиксирует факт на момент авторской правки, а не обещание, что живой issue + #449 остановится) и не требует правки ТЗ — привожу для полноты, не как + находку. +- Не проверял отдельно раздел «Карта реализации»/«Риски» повторно — дельта + их не касается, инвариант «унаследовано из r1» покрывает их. + +## Итог + +Находка предыдущего раунда (M1) закрыта и перепроверена исполнением по +первичным данным, а не со слов автора: `spent=1` для буквальной фикстуры и +`spent=2` для реконструкции — оба числа независимо пересчитаны и совпадают с +новыми AC2/AC2b. Новых High или Medium дельта не создала. Остаток контракта +не тронут и наследуется из r1 без повторной проверки. Вердикт — зелёный, +бюджет цикла не тратится. + +--- + + + +## Материал раунда + +- Ветка: `issue/454-review-round-counter`, коммит `f3e60578d443` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `983c66cca25d56b4a147e535608bce8f2261ad05` + ``` + git log --all --format='%H %T' | grep 983c66cca25d + ``` +- ТЗ `docs/specs/454-review-round-counter.md`, блоб `b5af292101a495e4699d839397e837a3a2467c85` + ``` + git log --all --find-object=b5af292101a495e4699d839397e837a3a2467c85 -- docs/specs/454-review-round-counter.md + ```