docs: review document for #425

Issue: #425
User-Visible: no

docs/reviews/SPEC-REVIEW-425-r2.md

@@ -0,0 +1,198 @@
+# SPEC-REVIEW-425-r2
+
+- Issue: https://github.com/Matysh/houseplan-card/issues/425
+- ТЗ: `docs/specs/425-core-file-budget.md`, ветка `issue/425-core-file-budget`,
+  SHA `84b5f63cbb528e995cf1041e95e8678ce4f32f72` (класс C: `docs: address the
+  core budget spec review (#425)`, `Issue: #425` · `User-Visible: no`).
+- Заход: r2 · трек: полный · блокирующих циклов израсходовано 1 из 4.
+- Вердикт: **зелёный**.
+
+## Скоуп раунда
+
+Предыдущий раунд (r1, жёлтый) нашёл две находки Medium в скоупе и одну Low.
+Автор ответил правкой одного файла — `docs/specs/425-core-file-budget.md`
+(`4eae3398..84b5f63c`, +23/-5 строк) — и отдельным комментарием в issue,
+описывающим, что именно изменено. Контракт, AC1–AC3, AC5, скоуп/не-скоуп,
+риски, план автотестов вне AC4 дельта не задевает. Разбор этого раунда —
+по дельте (§2.10): дельта локальна (правка двух коротких разделов и одной
+строки доказательства, без ребейза, без смены контракта, без новой
+подсистемы), полный повторный разбор не требуется.
+
+## Дельта r1 → r2
+
+```
+git diff 4eae3398..84b5f63c -- docs/specs/425-core-file-budget.md
+```
+
+Три изменения:
+1. добавлены разделы `## Сценарий` и `## Что человек увидит до и после`
+   (после шапки, перед «Почему не проект, а ограничитель»);
+2. AC4 дополнен предложением «Доказательство: ревью кода — в тесте нет
+   чтения потолков из внешнего источника (файла, переменной окружения,
+   вычисления от текущего размера), и юнит на то, что функция принимает
+   потолки аргументом, а не добывает их сама.»;
+3. удалён второй (задублированный) раздел `## Откат` (был на строках 94–96
+   старой версии, идентичен первому).
+
+Ничего за пределами этих трёх правок не менялось: AC1–AC3, AC5, «Контракт»,
+«Скоуп / не-скоуп», «План автотестов» (кроме привязки AC4), «Риски»,
+«Release-артефакты» — байт в байт те же, что проверил r1.
+
+## Закрытие раунда r1
+
+| Находка r1 | Чем закрыта | Где это видно |
+|---|---|---|
+| Medium-1 — нет разделов «Сценарий» и «Что человек увидит до и после» (§7.1) | Оба раздела добавлены явным текстом, не отпиской «не применимо»: у задачи нет продуктового сценария, но описан инженерный аналог и явно назвал, что пользователь не увидит ничего | `docs/specs/425-core-file-budget.md:12-28` (`## Сценарий`, `## Что человек увидит до и после`) |
+| Medium-2 — AC4 не называет способ доказательства, план автотестов его не упоминает | К тексту AC4 добавлено предложение «Доказательство: ревью кода… и юнит на то, что функция принимает потолки аргументом» | `docs/specs/425-core-file-budget.md:63-67` |
+| Low-1 — раздел «Откат» задублирован | Второй экземпляр раздела удалён, остался один, перед release-артефактами | `docs/specs/425-core-file-budget.md:112-114`; второго `## Откат` в файле больше нет (`grep -n '^## Откат'` → одно совпадение) |
+
+Проверено чтением файла и `git diff`, а не заявлением автора в комментарии.
+
+## Как проверялось
+
+1. Вердикт и материал r1 найдены в комментариях issue #425
+   (`gh issue view 425 --json ...`, MCP `get_issue`/`get_issue_comments` не
+   выданы в этой сессии, как и в r1) и в блоке «Материал раунда» документа
+   `docs/reviews/SPEC-REVIEW-425-r1.md` (коммит `3df0f164`): SHA `4eae3398`,
+   дерево `d37bea6a940c33f8197d96b008432931ad7edb8f`, блоб ТЗ `213aaf2a…`.
+   SHA `4eae3398` резолвится напрямую в текущей истории — ребейза между
+   раундами не было, живые якоря не понадобились.
+2. `git diff 4eae3398..84b5f63c -- docs/specs/425-core-file-budget.md` —
+   единственный дифф раунда, разобран построчно (см. «Дельта r1 → r2» выше).
+3. Прочитан весь текущий файл `docs/specs/425-core-file-budget.md` (121
+   строка) целиком — не только изменённые фрагменты — чтобы убедиться, что
+   вставки не порвали структуру и не создали противоречий с соседними
+   разделами (например, что новый «Сценарий» не конфликтует с «UX, модель
+   данных, i18n» → «Не применимо»).
+4. Сверен список обязательных разделов §7.1 (PROCESS.md:505-507: сценарий ·
+   что человек увидит до и после · проблема · скоуп и не-скоуп · контракт
+   поведения · UX · модель данных и миграция · i18n · AC с доказательством ·
+   план автотестов · риски · откат · release-артефакты) с текущим
+   документом — все присутствуют; «UX / модель данных / i18n» объединены в
+   один раздел с общим «не применимо», это уже было в r1 и не менялось.
+5. `node scripts/process-gate.mjs` на `origin/dev..HEAD` (3 коммита) —
+   «гейт пройден, предупреждений 0», класс C, трейлеры `Issue: #425` /
+   `User-Visible: no` в последнем коммите корректны.
+6. `git diff origin/dev...HEAD --stat` — два файла, оба в `docs/`
+   (`SPEC-REVIEW-425-r1.md`, `425-core-file-budget.md`); `src/**` не
+   тронут, продуктового или тестового кода в диффе нет.
+
+## Находки
+
+Нет. Обе Medium-находки r1 закрыты по существу, Low закрыта. Новых находок
+в дельте не обнаружено — три правки точечные, не расширяют и не сужают
+контракт, не меняют AC1–AC3, AC5.
+
+## Что проверено и корректно (в дельте)
+
+- **Новый раздел «Сценарий»** отвечает на вопрос §7.1 прямо: явно называет
+  отсутствие продуктового сценария («Продуктового сценария у задачи нет —
+  она инженерная, и это сказано явно, а не подразумевается») и не
+  подменяет ответ формальной отпиской — описывает инженерный аналог сценария
+  (разработчик добавляет функцию → ядро растёт → счёт не ведётся), что
+  сильнее, чем предложенная r1 короткая формула «не применимо». Ни одного
+  продуктового утверждения, не подтверждённого документами, раздел не
+  содержит — все фразы описывают инженерный процесс, а не поведение UI.
+- **«Что человек увидит до и после»** согласуется с `Release-артефакты`
+  (`User-Visible: no`) и со `UX, модель данных, i18n` → «Не применимо»:
+  три места документа не противоречат друг другу насчёт отсутствия
+  видимых изменений.
+- **AC4 доказательство** переносимо в план код-ревью буквально: «в тесте
+  нет чтения потолков из внешнего источника» и «юнит на то, что функция
+  принимает потолки аргументом» — оба условия проверяемы по коду будущей
+  реализации без дополнительных допущений, ревьюер кода не должен будет
+  придумывать способ доказательства сам, как предупреждал r1.
+- **Дубль «Откат» устранён без побочных эффектов** — оставшийся раздел
+  (строки 112-114) идентичен по содержанию исходному, стоит на прежнем
+  месте относительно `Release-артефактов`, ничего не потеряно.
+- **Класс изменений и трейлеры коммита r2** — подтверждены
+  `process-gate.mjs` автоматически (см. «Как проверялось», п.5).
+
+## Унаследовано из r1
+
+Без повторной проверки в этом раунде приняты выводы r1
+(`docs/reviews/SPEC-REVIEW-425-r1.md`, коммит `3df0f164`, материал —
+SHA `4eae3398a6510ea19b403fd1ac33a5a3cc44881b`, дерево
+`d37bea6a940c33f8197d96b008432931ad7edb8f`) — дельта r1→r2 их не задевает:
+
+- **Замена #34** — ссылка живая, статус описан верно (r1 проверил по
+  `gh issue view`).
+- **Числа в таблице долга** (13658 / 14322 строк на `dev`) — сверены r1
+  напрямую с деревом, день в день; текст таблицы в дельте не менялся.
+- **AC1–AC3, AC5** — однозначны, каждый привязан к проверяемому условию и
+  явному способу доказательства (AC1 и AC2 — мутант/юнит, AC3 — тот же
+  юнит, AC5 — план автотестов, п.5); текст всех четырёх AC в дельте не
+  менялся, доказательство менялось только у AC4 и проверено заново в этом
+  раунде.
+- **План автотестов** на чистой функции `coreBudgetViolations` покрывает
+  все ветки контракта, включая обе границы люфта включительно — не менялся
+  (кроме отсутствовавшей ранее привязки AC4, которую план и не должен был
+  называть, так как способ доказательства AC4 — ревью кода, а не юнит по
+  этому плану).
+- **Мутант** (`core-budget-ignores-growth`) соответствует конвенции
+  `docs/TESTING.md` правило 4 — не менялся.
+- **Отсутствие похожего гейта и отсутствие пересечения с
+  `scripts/bundle-budget.mjs`** — проверено r1 по дереву репозитория, дельта
+  раздела «Скоуп / не-скоуп» не касалась.
+- **`docs/SCOPE.md` / Core user jobs** — задача инженерная (`User-Visible:
+  no`), не обязана закрывать строку J1–J7, конфликта нет; прецеденты
+  `scripts/bundle-budget.mjs` (#337/#367) и `scripts/mutation-gate.mjs`
+  (#85) в репозитории уже приняты. Раздел «Сценарий», добавленный в этом
+  раунде, этот вывод не меняет — он лишь формализует то же самое
+  утверждение об отсутствии пользовательской видимости.
+- **Открытых продуктовых вопросов владельцу нет** — задача целиком
+  техническая; новые разделы вопросов не порождают.
+- **`docs/USER-GUIDE.ru.md` и канонические документы подсистем** — не
+  относятся к задаче, видимое поведение не меняется.
+
+## Чего не проверял и почему
+
+- **Дешёвые гейты кода** (`npx tsc --noEmit`, `npm test`, `npm run build`,
+  сверка бандла) — не прогонял: `git diff origin/dev...HEAD --stat`
+  показывает только `docs/**`, продуктового или тестового кода в материале
+  раунда нет, прогонять их не на чем (как и в r1).
+- **`node scripts/check-docs.mjs`** — не запускал: диф не трогает `src/**`.
+- **Инварианты модели, мутационный гейт, golden, смоки, бэкенд-тесты,
+  perf-профили** — не запускал: код гейта ещё не написан (стадия ТЗ),
+  геометрия, рендер, `custom_components/**/*.py` и touch не затронуты.
+- **`docs/specs/README.md`** — как и в r1, не требую записи об #425/#34:
+  реестр по факту не поддерживается синхронно, это не критерий приёмки.
+- **Историчность чисел мотивационного раздела** (v1.58/v1.66.0) — не
+  перепроверял повторно: раздел «Почему не проект, а ограничитель» не
+  менялся в дельте, r1 уже пометил это как фон, не как AC.
+
+## Материал раунда
+
+- Ветка: `issue/425-core-file-budget`
+- SHA: `84b5f63cbb528e995cf1041e95e8678ce4f32f72`
+- Дерево: `8865e965a1b17c5152a297fccc176890778b0138`
+- ТЗ: `docs/specs/425-core-file-budget.md`, блоб
+  `0469a1eec26759469cf469c87136556935a1f629`
+- Предыдущий раунд: `docs/reviews/SPEC-REVIEW-425-r1.md` (коммит `3df0f164`),
+  материал r1 — SHA `4eae3398a6510ea19b403fd1ac33a5a3cc44881b`, дерево
+  `d37bea6a940c33f8197d96b008432931ad7edb8f`.
+
+## Вердикт
+
+Зелёный: обе находки Medium из r1 закрыты по существу и видны построчно в
+дельте, Low закрыта, новых находок нет. Дельта локальна, контракт и
+AC1–AC5 не изменены (кроме способа доказательства AC4, который теперь
+явный). Готово к разработке.
+
+`Вердикт: зелёный · заход r2 · блокирующих циклов 1/4 · High: 0 · Medium: 0 · Документ: docs/reviews/SPEC-REVIEW-425-r2.md`
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/425-core-file-budget`, коммит `84b5f63cbb52` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `8865e965a1b17c5152a297fccc176890778b0138`
+  ```
+  git log --all --format='%H %T' | grep 8865e965a1b1
+  ```
+- ТЗ `docs/specs/425-core-file-budget.md`, блоб `0469a1eec26759469cf469c87136556935a1f629`
+  ```
+  git log --all --find-object=0469a1eec26759469cf469c87136556935a1f629 -- docs/specs/425-core-file-budget.md
+  ```