houseplan-card/docs/reviews/CODE-REVIEW-628-r1.md

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.

---

Материал раунда

• Ветка: issue/628-repository-gc, коммит 66b2b576aee8 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: 4aabbb2ce19d8605d15a9a6d17dc999366f3bf9b

  git log --all --format='%H %T' | grep 4aabbb2ce19d
  

• Тело issue: 9b54257641bbb6e8f0276842401740d958c3593af319626ccc1c8a88e0e6c671
• Вердикт конвейера: yellow · High 0