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

# CODE-REVIEW-573-r1

**Issue:** #573 — Release proof: переиспользовать проверки product tree после
baseline-only commit без второго полного Validate
**Трек:** infrastructure (класс B/tests/process, класса A нет)
**Материал:** `47f36e571c723ee163bb10dc44a31582b5e9e5fc` (единственный коммит на
`issue/573-release-proof-reuse`, база `origin/dev` = `06bf9b69`)
**Заход:** r1 · блокирующих циклов израсходовано (до этого раунда) 0 из 4

## Скоуп

Proof Validate до этой задачи называл только `tree` кандидата. Приёмка
эталонов (`ad4000f9` на beta.3) меняла его целиком, хотя продукт не менялся —
второй Validate честно перегонял smoke/perf/6 шардов мутантов, которые уже
были доказаны первым прогоном. Причина: `source-fingerprint.mjs` называет
корпус строкой-каталогом `demo/golden`, а замыкание входов раскрывало эту
строку во все текстовые файлы под каталогом, включая
`demo/golden/baselines/baselines-index.json` — индекс эталонов утекал во
входы smoke/perf/browser-guard мутантов.

Правка вводит:
1. `BASELINE_OVERLAY` в `check-inputs.mjs` — раскрытие каталога по строке
   больше не выдаёт overlay эталонов; явный корень (`golden`) и явная ссылка
   на файл — как были.
2. Составное evidence в proof (`ci-proof.mjs`): `product.tree` (ls-tree без
   overlay), `baselines.{tree,manifestSha256,reviewedRun}`, `keys` (content-
   ключи пяти реюзных job, включая исполненные).
3. `evaluateCiProof({expected, reviewedRun})` — потребитель на checkout
   кандидата сверяет evidence, а не верит ему; `release-gate.mjs`/
   `release-prerelease.mjs` считают `expected` только когда `HEAD == sha`.

Класса A нет, `User-Visible: no` корректен, трейлеры (`Issue: #573`,
`User-Visible: no`) на месте.

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

Дешёвые гейты (`typecheck`, `npm test`, `npm run build`, `check-docs`) на этом
SHA уже подтверждены зелёным Validate (run 35262504454, https://github.com/Matysh/houseplan-card/actions/runs/35262504454) —
не перегонял.

Сам прогнал (диф не трогает `src/**`, геометрию, рендер — полные наборы не
нужны):

| Гейт | Команда | Результат |
|---|---|---|
| Выбор смоков | `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | «Исполняемого frontend-диффа нет … Browser-smoke этим диффом не выбираются» — смоки не нужны, диф не трогает `src/**` |
| Покрытие входов | `node scripts/check-inputs.mjs --coverage` | чисто, 0 неизвестных |
| Заявленное поведение фикса | `node scripts/check-inputs.mjs --check=smoke --why=demo/golden/baselines/baselines-index.json` | «не вход smoke» — воспроизвёл ключевую заявку автора вживую |
| Целевые unit-тесты задачи | `node --test --test-name-pattern="#573" test/check-inputs.test.mjs test/gate-reuse.test.mjs test/mutation-gate.test.mjs test/ci-proof.test.mjs test/release-gate.test.mjs` | 11/11 pass |
| «Тест умеет падать» для AC1/защиты overlay | вручную откатил фильтр `!isBaselineOverlay(f)` в `check-inputs.mjs`, перегнал те же 4 файла | все 4 упали (например `mutation-gate.test.mjs`: отпечаток свидетеля со смок-гардом изменился — ожидаемое поведение до фикса), затем восстановил файл, `git diff` чист |
| Инварианты геометрии | — | не нужны: диф не трогает рёбра/толщину/`layout` |
| golden/pytest/perf | — | не нужны: диф не трогает рендер и `custom_components/**/*.py` |

Не прогонял: `npx tsc --noEmit`, `npm test` (полный), `npm run build`,
`node scripts/check-docs.mjs` целиком — покрыты зелёным Validate на этом SHA.

## AC → доказательство → чем краснеет

| # (из тела issue) | Доказан | Чем краснеет |
|---|---|---|
| 1. beta.3-воспроизведение: baseline-only commit reuses green, golden перегоняется, final proof green | `test/ci-proof.test.mjs` `#573 AC1`; `test/gate-reuse.test.mjs` `#573` (синтетика C→B); реальная пара `e5fe4364→ad4000f9` в комментарии автора | мутант `baseline-overlay-leaks-into-every-key` (проверено лично, см. таблицу выше — 4/4 теста падают на откате фильтра) |
| 2. source+baseline вместе → соответствующие job исполняются | `test/gate-reuse.test.mjs` `#573` (правка `src/card.ts` вместе с эталонами меняет ключи smoke/golden/perf) | тот же мутант (ключи перестают различать источники) |
| 3. красный smoke/mutant/perf не прячется зелёной golden | `test/ci-proof.test.mjs` `#573 AC3` | контракт #541 (`reuse-*` мутанты, не менялся в этой задаче) |
| 4. подмена ключа/tree/индекса/reviewed-run → fail-closed | `test/ci-proof.test.mjs` `#573 AC4`; `test/release-gate.test.mjs` `#573` | мутанты `proof-trusts-evidence-it-could-verify`, `reused-marker-key-unchecked-against-candidate`, `product-tree-identity-counts-baselines` — прочитаны, патчи соответствуют текущим строкам кода (проверено чтением, не переисполнял мутацию вручную — они уже отчитаны Validate как «поймано 1 из 1») |
| 5. один terminal contract для release/merge/review | частично доказан — см. находку Medium ниже: реальный вызов `evaluateCiProof` из `merge-candidate.mjs`/`validate-gate.mjs` с настоящим `reviewedRun`-объектом не покрыт тестом, а поведение фактически новое | — |
| 6. замер wall time | оценка автора по факту длительностей job прогона `ad4000f9` (не тест, честно оформлено как оценка, issue не требовал автотеста) | н/п |

## Находки

### Medium (в скоупе — правится в этой же задаче)

**`evaluateCiProof` меняет поведение merge/review-потребителей без теста и
вопреки утверждению автора, что оно не меняется.**

- **Файл:** `scripts/ci-proof.mjs`, блок `evaluateCiProof` (строки 297–311),
  фактически задействован через `scripts/merge-candidate.mjs` (line ~164) и
  `scripts/validate-gate.mjs` (line ~77) — оба используют
  `loadGithubProofContext`, которая теперь возвращает `reviewedRun`.
- **Суть:** блок проверки `Baseline-Reviewed` run (существует/завершён/не
  отменён/принадлежит `validate.yml`) срабатывает всегда, когда
  `proof.evidence.baselines.reviewedRun` объявлен — независимо от того,
  передан ли `expected`/`policy.full`. Он не привязан к release: любой
  консьюмер (`merge`, `review`), которому `loadGithubProofContext` вернула
  реальный (не `undefined`) `reviewedRun`, получает новую fail-closed
  проверку.
- **Это не гипотетика.** Ровно такой коммит — исполнитель принимает эталоны
  той же веткой, что и правку, с трейлером `Baseline-Reviewed:` на верхушке —
  уже стандартная практика этого репозитория: `9bf41ec3` (`#584`,
  непосредственно предыдущая задача, слитая перед этой) сделан именно так и
  прошёл текущий S7/merge. После этой задачи такой коммит на верхушке ветки
  заставит `merge-candidate.mjs` и `validate-gate.mjs` (тот самый гейт, что
  прямо сейчас ждёт Validate для код-ревью!) дополнительно зависеть от
  доступности GitHub API для СТАРОГО run'а, названного трейлером, — сбой
  этого запроса (см. `catch { reviewedRun = null; }` в
  `loadGithubProofContext`) закрывает merge/review `failed`, хотя раньше они
  этот run вообще не проверяли.
- **Воспроизвёл лично:**
  ```js
  evaluateCiProof({ run, proof /* proof.evidence.baselines.reviewedRun: 999 */,
    jobs, candidate, policy: CI_PROOF_POLICIES.merge, reviewedRun: null })
  // → { status: 'failed', note: 'Baseline-Reviewed run 999 is missing, cancelled or not a Validate run' }
  ```
  притом что `expected` не передавался вовсе — то есть это не «сверка
  ожиданий release-потребителя», а самостоятельная новая проверка, которая
  молча зацепила merge/review.
- **Не покрыто тестами:** единственный тест с `policy: CI_PROOF_POLICIES.merge`
  (`test/ci-proof.test.mjs:266`) явно передаёт `reviewedRun: undefined`,
  обходя именно этот путь. Ни в `test/merge-candidate.test.mjs`, ни в
  `test/validate-gate.test.mjs` нет ни одного упоминания `reviewedRun` —
  реальный вызов через `loadGithubProofContext` не проверен ни разу.
- **Расходится с хендоффом:** автор пишет «Review/merge-потребители
  получают тот же evaluate без ожиданий — их семантика не меняется». Это
  верно только для сверки `expected` (product tree/keys/overlay); проверка
  `reviewedRun` — новая для этих потребителей и от `expected` не зависит.
- **Почему Medium, не High:** направление отказа безопасное (fail-closed, не
  скрывает дефект), и для ЭТОЙ задачи не проявляется (у `47f36e57` нет
  `Baseline-Reviewed`). Риск — будущая спурная поломка merge/review на
  легитимном сценарии (баг-фикс + приёмка эталонов одной веткой), без единого
  теста, который поймал бы регресс в любую сторону.
- **Предлагаемое устранение (на выбор автора):** либо ограничить проверку
  `reviewedRun` тем же условием, что и `expected` (реально нужна только
  release-потребителю, который заявлен как единственный, кто про это
  спрашивает), либо добавить тест на `merge`/`review` policy с настоящим
  объектом `reviewedRun` (успех и отказ) и явно принять новое поведение,
  поправив формулировку в хендоффе.

## Что проверено и корректно

- `BASELINE_OVERLAY`/`isBaselineOverlay`/`closure` — воспроизвёл вживую и
  мутацией; overlay больше не течёт через раскрытие каталога, явная ссылка на
  файл (`test/golden-index.test.mjs`-подобный сценарий) остаётся входом.
- `CHECKS.golden.roots` содержит `demo/golden/**` явным корнем — golden
  по-прежнему видит overlay напрямую, не через закрытие; заявка «golden не
  теряет эталоны» подтверждена чтением.
- `productTreeId`/`baselineReviewedRun` — детерминированные чистые функции,
  тесты покрывают приёмку эталонов (дерево не меняется) и правку исходника
  (дерево меняется), throws на пустом дереве и на трейлере без run id.
- `buildCiProof` пишет `key` для исполненной реюзной job и отвергает чужой
  ключ маркера реюза — проверено тестом и логикой (симметрично записи и
  сверке).
- `candidateExpectations` считает evidence только когда `HEAD == sha`, иначе
  явный notice «проверяю по GitHub» — корректно ограничивает применимость
  локального сравнения только собственным checkout'ом.
- Golden-гарды мутации (`golden-lamp-out-of-reach`,
  `golden-filled-tunnel-removed`) — проверил чтением: оба в `--mode=capture`
  по семантическим ассертам, `demo/golden/policy.mjs` запрещает verify по
  одной сцене, так что потеря overlay в их отпечатке не открывает дыру.
- Документация (`DEVELOPMENT.md`, `TESTING.md`, `STATUS.md`) описывает именно
  то поведение, что в коде — сверил построчно.
- `reviewedRun`-проверка НЕ проверяет `conclusion === 'success'`, только
  «не cancelled» — согласуется с самим сценарием beta.3, где просматриваемый
  run был красным по golden; намеренно, не дефект.

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

- Полный `npm test`/`npm run typecheck`/`npm run build` — покрыты зелёным
  Validate на этом SHA, не перегонял.
- `check-docs.mjs` целиком — то же самое, плюс диф не трогает `src/**`.
- Реальный прогон Validate с настоящим `NEEDS_JSON`/`reuse.outputs` (job
  `proof` в CI) — верю логике и юнит-тестам, живой YAML не выполнял.
- Мутанты `proof-trusts-evidence-it-could-verify`,
  `reused-marker-key-unchecked-against-candidate`,
  `product-tree-identity-counts-baselines` — сверил патчи с текущим кодом
  построчно (совпадают), но не переисполнял их вручную (в отличие от
  `baseline-overlay-leaks-into-every-key`, который проверил лично);
  полагаюсь на отчёт Validate «поймано 1 из 1».

## Итог

Ядро задачи (overlay не течёт в ключи smoke/perf/мутантов, golden видит
overlay явным корнем, release-потребитель сверяет evidence и fail-closed на
подмену) реализовано корректно и доказано тестами, которые я лично убедился,
что умеют падать. Один Medium-дефект в скоупе: новая fail-closed проверка
`Baseline-Reviewed` run зацепила merge/review-потребителей незаметно для
автора и без единого теста на этом пути, при уже существующем в репозитории
прецеденте (`#584`), который его бы затронул. High-находок нет.

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

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

- Ветка: `issue/573-release-proof-reuse`, коммит `47f36e571c72` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `aca987ffcc31c3656ec79fea04db2890c9f2242a`
  ```
  git log --all --format='%H %T' | grep aca987ffcc31
  ```
- Тело issue: `5ab99e532f34bdfa488c9143f2c1c1361b826159e0707a56ce70a640e8ca4fff`
- Вердикт конвейера: `yellow` · High 0