From f399ad547b5f147afd637ba078d82ea919e36484 Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Wed, 2 Sep 2026 21:22:53 +0000 Subject: [PATCH] docs: review document for #425 Issue: #425 User-Visible: no --- docs/reviews/SPEC-REVIEW-425-r2.md | 198 +++++++++++++++++++++++++++++ 1 file changed, 198 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-425-r2.md diff --git a/docs/reviews/SPEC-REVIEW-425-r2.md b/docs/reviews/SPEC-REVIEW-425-r2.md new file mode 100644 index 00000000..2d1d7ee4 --- /dev/null +++ b/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` + +--- + + + +## Материал раунда + +- Ветка: `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 + ```