docs: review document for #628

Issue: #628 User-Visible: no
2026-09-29 03:09:36 +00:00 · 2026-09-25 10:13:17 +00:00
parent 774b7c7e04
commit f86bc34dd5
2 changed files with 173 additions and 0 deletions
@@ -0,0 +1,172 @@
+# CODE-REVIEW-628-r1
+
+Issue: #628 · Материал раунда: `66b2b576aee86e905a620722d7dd7acf3a71ee57` (HEAD,
+рабочая копия на нём) · диапазон `origin/dev..HEAD`.
+
+## Скоуп
+
+Инфраструктурная задача без ТЗ (трек «infrastructure-only», AGENTS.md):
+владелец выбрал вариант 1 из четырёх, предложенных в теле issue — разовый
+`git gc --prune=now` клона на Windows-машине владельца, замер до/после,
+фиксация решения в `docs/DEVELOPMENT.md`. LFS, единая копия бандла в git и
+перезапись истории явно отклонены владельцем (комментарии от 2026-09-24 и
+2026-09-25).
+
+AC из тела issue:
+- **AC1** — решение владельца зафиксировано в `docs/DEVELOPMENT.md`.
+- **AC2** — прирост пака за следующий месяц ≤ 20 MiB, тот же `count-objects`.
+
+Диапазон `origin/dev..HEAD` — ровно один коммит:
+
+```
+66b2b576 docs: record repository GC baseline
+```
+
+Диф — ровно один файл, `docs/DEVELOPMENT.md`, +27/-0. Не класс A: код
+(`src/**`, `custom_components/**/*.py`, манифесты, i18n) не тронут — задача
+законно вошла в конвейер напрямую на `S7-code-review`, минуя `S1`…`S6`.
+Трейлеры коммита: `Issue: #628`, `User-Visible: no` — верно для документации,
+не меняющей продукт; правка обоих CHANGELOG не требуется и не сделана.
+
+## Как проверялось
+
+- Прочитаны тело issue #628 и все 4 комментария (вопросы владельца с
+  умолчаниями от 2026-09-24, ответ «вариант 1» от 2026-09-25, взятие в работу,
+  итоговый отчёт с фактическими командами и числами).
+- `git log --oneline origin/dev..HEAD` и `git diff origin/dev...HEAD` —
+  материал раунда подтверждён, дифф прочитан целиком (27 строк, приведён
+  выше).
+- Арифметика внесённых чисел пересчитана вручную:
+  - до GC: 749.84 (loose) + 334.55 (packs) = **1084.39 MiB** — совпадает с
+    текстом «fell from 1,084.39 MiB»;
+  - после GC: 0 (loose) + 467.63 (packs) = **467.63 MiB** — совпадает;
+  - разница: 1084.39 − 467.63 = **616.76 MiB** — совпадает с текстом;
+  - принятая верхняя граница AC2: 467.63 + 20 (порог AC2) = **487.63 MiB** —
+    совпадает с текстом.
+  Все четыре числа в документе внутренне согласованы, источник порога — AC2
+  из тела issue, дублирования с конфликтующим значением нигде не найдено
+  (`grep -rn "size-pack|count-objects|git gc" docs/` — единственное упоминание
+  во всём `docs/**`, само `docs/DEVELOPMENT.md`).
+- `node scripts/check-docs.mjs --screenshots=warn` — прогнал сам (диф не
+  трогает `src/**`, гейт не обязателен, но дешёвый): `Documentation checks
+  passed (7 files, 12 external links)`, есть неотносящееся к диффу
+  предупреждение про устаревший fingerprint скриншотов на `dev` — то же самое,
+  что автор указал в issue-комментарии.
+- Проверена структура заголовков всего файла (`grep -n '^#' docs/DEVELOPMENT.md`)
+  и прочитан контекст вставки (строки ~93–236) целиком, чтобы понять, в какую
+  секцию попал новый раздел и что было до/после него.
+
+## Находки
+
+### Medium (в скоупе задачи, чинится в этом же раунде)
+
+**Новый раздел разрывает существующую секцию «Local Windows workstation» и
+меняет владельца подсекции «File-sync pitfalls».**
+
+- Файл: `docs/DEVELOPMENT.md`
+- Строки диффа: вставка после строки 167 (`git config core.untrackedCache
+  true` + закрывающий ``` ```), перед исходной строкой 168
+  (`### ⚠️ File-sync pitfalls (critical)`).
+- Воспроизведение: до диффа секция `## Local Windows workstation` (начинается
+  на исходной строке 93) заканчивалась абзацем про `git config
+  core.fsmonitor/core.untrackedCache` и затем без разрыва переходила в свою
+  подсекцию `### ⚠️ File-sync pitfalls (critical)` — про ненадёжность
+  сетевого mount при редактировании и сборке на Windows, тема, не связанная
+  ни с #628, ни с `git gc`. Новый уровень-2 заголовок `## Local repository
+  maintenance (#628)` вставлен ровно между ними. Формально уровни заголовков
+  не нарушены (`##` на своём месте), но логически подсекция `###
+  File-sync pitfalls` теперь читается как часть раздела о разовом `git gc`, а
+  не как часть раздела про настройку Windows-рабочей станции, которому она
+  принадлежит по смыслу и куда попала бы любая навигация по дереву
+  заголовков (TOC-скрипты, IDE outline, `grep -n '^#'`). Читатель, ищущий
+  «почему нельзя редактировать файлы через сетевой mount», найдёт этот пункт
+  под заголовком про garbage collection репозитория — вводит в заблуждение
+  ровно там, где документ единственная страховка (эта же папка отмечена как
+  «⚠️ critical»).
+- Почему это не Low: единственная продукция этой задачи — текст документа;
+  структурная ошибка в нём — дефект в самой поставке, а не косметика. Задача
+  дешёво чинится перестановкой блока (переместить новый `##`-раздел после
+  `### File-sync pitfalls` и перед `## Tests`, либо перед `## Local Windows
+  workstation`), без изменения содержания.
+- Чем доказано: проверено чтением (`git diff`, `grep -n '^#'`,
+  прочитан весь диапазон строк 93–236 до и после точки вставки) — не
+  исполнением, для документации исполнения не требуется.
+
+Других находок нет.
+
+## Что проверено и корректно
+
+- **AC1** — решение владельца зафиксировано текстом, который совпадает с
+  тем, что владелец выбрал в комментариях (вариант 1 из «Варианты» issue-тела;
+  явные исключения LFS/удаление `dist/**`/перезапись истории воспроизводят
+  умолчания-отказы владельца по вопросам 2–4 из первого комментария).
+  Проверено чтением issue + диффа.
+- **AC2** — документ не может «закрыть» этот AC сейчас (проверка назначена на
+  2026-10-25 и позже), но правильно фиксирует измеримый критерий: базовая
+  величина 467.63 MiB, порог ≤20 MiB из AC2, принятая верхняя граница 487.63
+  MiB, и явная команда для будущего замера (`git gc --prune=now`, `git
+  count-objects -vH`, сравнение `size-pack`). Это ровно то, что можно
+  зафиксировать в рамках этой задачи; сам будущий замер — не предмет этого
+  ревью.
+- Арифметика всех четырёх чисел в новом разделе пересчитана и подтверждена
+  (см. «Как проверялось»).
+- Трейлеры коммита корректны: `Issue: #628`, `User-Visible: no`; ни один
+  changelog не тронут — и не должен быть, изменение не видно пользователю
+  продукта.
+- Дифф не касается `src/**`, `custom_components/**/*.py`, манифестов, i18n,
+  `test/**`, `scripts/**`, геометрии — ни один защитный AC, ни один
+  автотестируемый контракт этой задачей не затронут; таблица «AC · чем
+  доказан · чем краснеет» не требуется, потому что в задаче нет защитного AC
+  (валидации/гарда/лимита/отказа/инварианта) — оба AC описательные
+  (зафиксировать решение / измерить рост).
+- Однократность действия (не повторяющийся `git gc` в CI, не CRON) —
+  подтверждена и текстом раздела, и тем, что диф не трогает
+  `.github/workflows/**` и `scripts/**`.
+- Единственность источника чисел: `size-pack`/`count-objects`/`git gc`
+  встречаются в `docs/**` только в этом новом разделе — нет второго места, где
+  та же величина продублирована с другим значением.
+
+## Чего не проверял и почему
+
+- **`npx tsc --noEmit`, `npm test`, `npm run build` (сверка бандла)** — не
+  перегонял: диф не содержит кода, только `docs/DEVELOPMENT.md`; кроме того
+  Validate на этом же SHA `66b2b576` уже зелёный
+  (https://github.com/Matysh/houseplan-card/actions/runs/36121805309),
+  что покрывает эти дешёвые гейты.
+- **Смоки, golden, `pytest tests_backend`, инварианты модели,
+  performance-профили** — не прогонял: диф не касается рендера, геометрии,
+  Python-кода интеграции или производительности; ни один из них не назван в
+  AC1/AC2. `node scripts/smoke-select.mjs` не запускал по той же причине —
+  диф не в `src/**`/`demo/**`, смок-выбор не применим к markdown-only диффу.
+- **Сам замер AC2 (`git gc` + `count-objects` на 2026-10-25 или позже)** — не
+  мой предмет: это будущая проверка, которую документ только готовит; в этом
+  раунде оценивается полнота и корректность подготовки, не результат.
+- **Повторный запуск владельческого `git gc --prune=now` на Windows-клоне** —
+  не выполнял и не мог: у ревьюера нет доступа к машине владельца, а числа до/
+  после в issue-комментарии — отчёт владельца о собственном действии, не
+  проверяемый из песочницы; я перепроверил только внутреннюю арифметику
+  перенесённых в документ чисел (см. выше), не первичный факт их измерения.
+- **Разбор навигации doc-tooling (TOC-генераторы, `scripts/check-docs.mjs`
+  на предмет заголовков)** — `check-docs.mjs` прогнан и зелёный, но он не
+  проверяет семантическую принадлежность подсекций — эта проверка сделана
+  мной вручную построением дерева заголовков, а не инструментом.
+
+## Вердикт
+
+Жёлтый: единственная Medium-находка — в скоупе задачи (тот же файл, та же
+правка) и без High-находок, поэтому по правилам возвращается автору в этом же
+issue, без отдельного issue.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/628-repository-gc`, коммит `66b2b576aee8` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `4aabbb2ce19d8605d15a9a6d17dc999366f3bf9b`
+  ```
+  git log --all --format='%H %T' | grep 4aabbb2ce19d
+  ```
+- Тело issue: `9b54257641bbb6e8f0276842401740d958c3593af319626ccc1c8a88e0e6c671`
+- Вердикт конвейера: `yellow` · High 0
@@ -41,6 +41,7 @@
 | #629 | [SPEC-REVIEW-629-r1.md](SPEC-REVIEW-629-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | — | — |
 | #629 | [CODE-REVIEW-629-r1.md](CODE-REVIEW-629-r1.md) | code · r1 | 🟢 зелёный | 0 | 0 | — | — |
 | #629 | [CODE-REVIEW-629-r2.md](CODE-REVIEW-629-r2.md) | code · r2 | 🟢 зелёный | 0 | 0 | — | — |
+| #628 | [CODE-REVIEW-628-r1.md](CODE-REVIEW-628-r1.md) | code · r1 | 🟡 жёлтый | 0 | 1 | Новый раздел разрывает существующую секцию «Local Windows workstation» и меняет владель… | `docs/DEVELOPMENT.md` |
 | #627 | [SPEC-REVIEW-627-r1.md](SPEC-REVIEW-627-r1.md) | spec · r1 | 🟢 зелёный | 0 | 0 | избыточное (не противоречивое) условие в AC2; влияние на touch не названо явным пунктом | `docs/TOUCH-SUPPORT.md` |
 | #627 | [CODE-REVIEW-627-r1.md](CODE-REVIEW-627-r1.md) | code · r1 | 🟡 жёлтый | 0 | 1 | demo/smoke_danger_confirmation.mjs не переведён на ожидание составного гейта; диалог оп… | `demo/smoke_danger_confirmation.mjs` `src/houseplan-card.ts` `de.ts` `smoke_danger_confirm_branches.mjs` |
 | #627 | [CODE-REVIEW-627-r2.md](CODE-REVIEW-627-r2.md) | code · r2 | 🟢 зелёный | 0 | 0 | — | — |