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

CODE-REVIEW — issue #547 — заход r1

Материал: origin/dev...HEAD, вершина 6c6f53491f72357f97e06ce40e5ace87a61a1cde (рабочая копия уже на нём; git fetch/checkout на другой SHA не делались). Заход: r1 (первый), блокирующих циклов израсходовано 0/4. Коммит: один, fix(release): bind beta bookkeeping to candidate (#547), трейлеры Issue: #547 / User-Visible: no.

Скоуп

Инфраструктурная задача (метка infra, ускоренный вход в S7-code-review, PROCESS.md §1). Продуктовый код (src/**, custom_components/**/*.py) не затронут — только класс B (scripts/**, .github/workflows/**, test/**) и класс C (docs/**, AGENTS.md, PROCESS.md) в одном коммите, что и требуется для DoD. User-Visible: no корректен — изменений в CHANGELOG нет и не нужно.

Дефект по аудиту (#547 из body issue): close-merged в publish-prerelease.yml фиксировал SHA кандидата до gate/build, но после публикации выбирал живую очередь S8-merged --author Matysh без проверки попадания в этот кандидат. Сценарий A → B → publish(A) мог закрыть B как выпущенную в A; фильтр по автору отдельно исключал принятые внешние issue. Задача: детерминированный manifest (RELEASE-MEMBERSHIP.json), привязанный к тегу и точному SHA, доказательство Issue: #NN в Git-диапазоне кандидата, общий idempotent bookkeeping для workflow и локального паблишера.

Как проверялось

Ревью раунда — первый, деления на дельту не было: разбирался весь диф origin/dev...HEAD (14 файлов, +722/−118).

1. Прочитан docs/SCOPE.md — изменение не продуктовое (нет пользовательского поведения), поэтому проверка через Core user jobs не применяется; это гейт релизного процесса, соответствующая инфраструктурная категория подтверждена меткой infra и решением владельца в первом комментарии issue.
2. Прочитаны AGENTS.md/PROCESS.md (текущая версия, включая правки этого диффа) — трейлеры, классы файлов, ускоренный вход инфры сошлись.
3. Прочитано тело issue #547 и все три комментария (взятие в работу, реализация, ребейз). Все четыре AC из issue сверены с кодом построчно (см. ниже).
4. Прочитан весь новый код: scripts/release-membership.mjs (207 строк), scripts/release-bookkeeping.mjs (102 строки), правки scripts/release-prerelease.mjs, scripts/release-assets.mjs и .github/workflows/publish-prerelease.yml целиком — построчно, не по диффу, чтобы увидеть итоговую последовательность шагов gate → publish → close-merged.
5. Прочитаны обновления docs/ARCHITECTURE.md, docs/DEVELOPMENT.md — сверены с фактическим кодом на расхождения (не найдено).

Прогнанные гейты

• Дешёвый гейт этого SHA уже зелёный: Validate https://github.com/Matysh/houseplan-card/actions/runs/34745685188 — проверено напрямую (gh run view 34745685188): conclusion=success, headSha=6c6f53491f72357f97e06ce40e5ace87a61a1cde — совпадает с материалом ревью. tsc --noEmit, npm test, npm run build повторно не гонялись — основание §8/условие промпта соблюдено.
• node --test test/release-membership.test.mjs test/release-bookkeeping.test.mjs test/release-assets.test.mjs test/release-contract.test.mjs — прогнано вручную поверх зелёного Validate ради прямой проверки новых тестов: 20/20 зелёных.
• Дисциплина «тест должен уметь падать» проверена на обоих новых мутантах из scripts/mutation-gate.mjs (prerelease-membership-keeps-unproven-s8, prerelease-bookkeeping-duplicates-release-comment): патч применён вручную, соответствующий тест падает (1/3 fail и 1/4 fail соответственно), файл возвращён, git status чист.
• node scripts/smoke-select.mjs --base origin/dev --head HEAD → «Исполняемого frontend-диффа нет … Browser-smoke не выбираются». Смоки не гонялись — выбирать нечего, diff не касается src/**.
• node scripts/check-docs.mjs — не гонялся: diff не касается src/**, отпечаток скриншотов не мог устареть от этой правки.
• npm run golden:verify, python -m pytest tests_backend, инварианты модели (npm run invariants), перформанс-профили — не гонялись: нет рендера, геометрии, custom_components/**/*.py или названных в AC перф-путей в этом диффе.

Проверка AC (issue #547)

1. «В сценарии A → B → publish A задача B остаётся открытой; release- комментарий относится только к действительно включённой работе» — доказано чтением + тестом. buildReleaseMembership принимает список issue («живая S8 очередь» как подсказка) и оставляет в manifest только те номера, для которых найден коммит с трейлером Issue: #NN в git-диапазоне previous-tag..candidate (scripts/release-membership.mjs:592-609, readCandidateHistory). B, слитая после кандидата A, не входит в этот диапазон и остаётся в unmatched → не попадает в manifest → не участвует в finishManifestIssues. Тест test/release-membership.test.mjs:1179-1193 («S8 is only a hint») прогоняет ровно этот сценарий: issue 11 просится, но не доказана — unmatched: [11].
2. «Принятая в процесс внешняя issue учитывается наравне с владельческой» — фильтр --author Matysh убран из gh issue list в close-merged (подтверждено чтением workflow — фильтра в файле больше нет — и тестом test/release-contract.test.mjs:1155 !workflow.includes('--author Matysh')). manifest.issues не содержит поля автора вовсе; доказательство одно и то же для любого issue (тест «accepted external issues use the exact same proof and no author field»).
3. «Повтор после сбоя каждого шага comment/labels/close безопасен и не дублирует релиз» — finishManifestIssues перечитывает состояние issue ops.load до и после операций, action по каждому шагу вычисляется от актуального состояния (planIssueBookkeeping), маркер <!-- houseplan-release:<tag> --> в теле комментария предотвращает повторный комментарий. Интеграционный тест test/release-bookkeeping.test.mjs:1031-1094 бросает ошибку ровно на шаге removeLabel/close и проверяет, что повторный вызов не дублирует комментарий и не трогает не связанную с manifest issue #11. На уровне workflow — close-merged больше не условен по newly_published (было if: needs.publish.outputs.newly_published == 'true', снято), поэтому ретрай уже опубликованного релиза всё равно доводит bookkeeping до конца (проверено чтением job + тестом !closeJob.includes('newly_published')). Локальный паблишер (release-prerelease.mjs:540-565) при повторном запуске против уже публичного релиза берёт manifest из уже опубликованного файла (verifyRemoteAssetContents → publishedMembership), а не пересчитывает заново — это не даёт разъехаться manifest между попытками.
4. «Нельзя закрыть issue только по текущей S8 без доказанного попадания в релиз» — buildReleaseMembership по умолчанию (allowUnmatched: false) бросает исключение на недоказанный номер; workflow вызывает create с --allow-unmatched (не ошибка, а тихое исключение из manifest — то же самое AC1), а локальный паблишер вызывает без этого флага, то есть на явно переданный оператором --issues= без доказательства — падает (scripts/release-prerelease.mjs:500-502, buildReleaseMembership без allowUnmatched). close-merged/release-bookkeeping.mjs вообще не читают gh issue list — !closeJob.includes('gh issue list') подтверждено и тестом, и чтением workflow.

Дополнительно проверено чтением (не только по AC)

• Пиннинг кандидата при ушедшем вперёд dev. Шаг «Pin the dev candidate or the existing annotated tag» (publish-prerelease.yml:35-64): если аннотиро- ванный тег уже существует, SHA берётся из него (git checkout --detach), иначе требуется точное совпадение с origin/dev tip, как раньше. Это и есть механизм, который делает сценарий A→B→publish(A) вообще возможным воспроизвести при ретрае — раньше скрипт требовал точного совпадения с текущим tip dev, что ломало ретрай, если dev успел уйти вперёд.
• Согласованность SHA256SUMS/паспорта с новым файлом. PASSPORTED_ASSETS добавлен как отдельный список (installables + membership), INSTALLABLE_ASSETS не тронут — сохранена обратная совместимость с любым другим потребителем (sumsOfDirectory(dir, names = INSTALLABLE_ASSETS) — дефолт прежний). Проверено тестом test/release-assets.test.mjs (обновлён, зелёный).
• release.yml (стабильный релиз) не тронут и не содержит своей логики закрытия issue — bookkeeping только у беты, дублирования путей нет (grep подтвердил отсутствие close-merged/S8-merged в release.yml).
• Права workflow: issues: read добавлен на уровне файла (нужен для gh issue list/gh issue view в job gate), actions: read добавлен в close-merged (нужен для actions/download-artifact). Оба использования соответствуют добавленным шагам, лишних прав не замечено.
• readCandidateHistory ищет ближайший любой (в том числе бета) тег через git describe --match=v*, а не обязательно последний стабильный. Проверено, что это не создаёт риска повторного комментария/закрытия по уже выпущенным issue: buildReleaseMembership рассматривает только явно переданные номера (--issues=/открытая S8-очередь), а уже закрытые в предыдущей бете issue не в статусе open и потому не запрашиваются заново (workflow фильтрует --state open). Диапазон истории используется только как доказательство, а не как источник новых кандидатов, так что более широкий диапазон расширяет допустимое доказательство, а не список закрываемых issue.

Находки

Нет. High/Medium в скоупе или вне скоупа не обнаружено.

Чего не проверял

• Реальный прогон workflow publish-prerelease.yml на GitHub Actions (ручной workflow_dispatch) — не выполнялся, оценка по чтению кода + unit/integration тестам + контрактным assertion-тестам, читающим сам файл workflow. Ручного тестирования в цикле нет (см. вводные к этапу), поэтому это осознанный предел разбора, а не пропуск.
• Поведение GitHub API на предмет eventual consistency между gh issue close и последующим gh issue view в finishManifestIssues (двойная проверка состояния после операций) — теоретический риск ложного падения при лаге реплики GitHub не проверяем локально; юнит-тесты используют синхронный fake ops и не могут вскрыть такой лаг. Не поднимаю как находку: нет свидетельств, что это когда-либо проявлялось, и старый код делал аналогичные последовательные gh-вызовы без верификации вовсе.
• npm run typecheck, полный npm test, npm run build — не перегонялись повторно, доверие к зелёному Validate этого точного SHA (см. «Прогнанные гейты»).

---

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

• Ветка: issue/547-release-membership, коммит 6c6f53491f72 — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
• Дерево материала: ff3fc598bd9ce498a00df3dceb1af1b235c8916a

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

• Тело issue: 6a94820d247d611868ebc4188e2ce2ebc2c67c3ea3f8757fdb6b7cd1c94b814d
• Вердикт конвейера: green · High 0