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

# CODE-REVIEW-541-r1

Issue: #541 · «Один общий доказуемый CI-контракт для review/merge/release»
Трек: инфраструктурный (класс B/C, вход сразу на S7-code-review, решение владельца 13.09.2026)
Материал ревью: `0fd6977b47d6801b5bb8e6943188e3d7291f20b8` (рабочая копия уже на нём)
Заход: r1 · блокирующих циклов израсходовано 0 из 4

## Скоуп

Диапазон `origin/dev..HEAD`, 4 коммита, 17 файлов:

```
.github/workflows/validate.yml  |  93 +++
docs/DEVELOPMENT.md             |  15 +-
docs/STATUS.md                  |   2 +-
docs/TESTING.md                 |   6 +-
scripts/check-inputs.mjs        |   3 +-
scripts/ci-proof.mjs            | 339 +++ (новый)
scripts/merge-candidate.mjs     |  40 +-
scripts/mutation-gate.mjs       |  61 +-
scripts/release-gate.mjs        |  58 +-
scripts/release-prerelease.mjs  |  20 +-
scripts/validate-gate.mjs       |  41 +-
test/check-inputs.test.mjs      |  11 +-
test/ci-proof.test.mjs          | 190 +++ (новый)
test/merge-candidate.test.mjs   |  84 +-
test/release-gate.test.mjs      |  71 +-
test/validate-gate.test.mjs     |  31 +-
test/validate-workflow.test.mjs |  36 +
```

Все файлы — классы B (гейты/скрипты/workflow/тесты) и C (документация). Ни
одного файла класса A (`src/**`, `custom_components/**/*.py`) — задача
действительно инфраструктурная, полный флоу S1–S6 законно пропущен по §1.
Трейлеры всех четырёх коммитов: `Issue: #541` · `User-Visible: no` — верно для
чисто процессного изменения без пользовательского поведения.

Задача реализует единый машинно-проверяемый артефакт `ci-proof-<run>-<attempt>`
(`houseplan-ci-proof/v1`) и одну функцию состояний (`green/missing/pending/
cancelled/stale/failed`), которую разделяют review (`validate-gate.mjs`), merge
(`merge-candidate.mjs`) и release (`release-gate.mjs`/`release-prerelease.mjs`),
закрывая аудиторскую находку N2 §10: лёгкий зелёный dispatch мог заменить
старый красный full-прогон, а зелёный dispatch без исполненных mutant-job
проходил как доказательство для merge.

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

| Гейт | Статус | Примечание |
|---|---|---|
| `npx tsc --noEmit`, `npm test` (полный), `npm run build` + сверка бандла | не гонял повторно | Validate зелёный на точном SHA `0fd6977b`: https://github.com/Matysh/houseplan-card/actions/runs/34744556987 (подтверждено условием ревью — «дешёвые гейты на этом SHA уже подтверждены») |
| `node --test test/ci-proof.test.mjs test/merge-candidate.test.mjs test/release-gate.test.mjs test/validate-gate.test.mjs test/validate-workflow.test.mjs test/check-inputs.test.mjs` | **прогнал сам** | 75/75 green |
| `node scripts/process-gate.mjs` (офлайн, без `--issues`) | **прогнал сам** | «гейт пройден, предупреждений 0» |
| `node scripts/smoke-select.mjs --base origin/dev --head HEAD` | **прогнал сам** | «Исполняемого frontend-диффа нет» — браузерные смоки нечего выбирать, `src/**/*.ts` не тронут |
| `node scripts/check-docs.mjs` | не гонял | не применимо: diff не трогает `src/**` |
| `npm run golden:verify` | не гонял | не применимо: нет визуальных изменений |
| `node scripts/model-invariants.mjs` | не гонял | не применимо: геометрия/`layout`/толщины не затронуты |
| `python -m pytest tests_backend -q` | не гонял | не применимо: ни один `custom_components/**/*.py` не тронут |
| YAML-синтаксис `validate.yml` | **прогнал сам** | `python3 -c "import yaml; yaml.safe_load(open(...))"` — parses OK |
| Байтовая длина имён job (риск усечения GitHub Jobs API >100 UTF-8 байт, дважды ловился на этой же ветке) | **прогнал сам** | все резолвленные имена ≤112 байт максимум («Мутанты по диффу (1/6)…» = 94, «Доказательство выполненных проверок» = 68) — то же, что уже проверяет `test/validate-workflow.test.mjs` для `preflight` |
| `grep` job-графа `needs:` proof-job против списка реальных job id в workflow | **прогнал сам** | все 12 зависимостей существуют, ничего не рассинхронизировано |

### Защитные AC — таблица «чем краснеет»

Все три — новый защитный код в `scripts/ci-proof.mjs`, чистые юниты. Мутировал руками (patch → прогон → откат), дополнительно у трёх из них есть штатные witness в `scripts/mutation-gate.mjs`, которые я тоже прогнал по отдельности (`node scripts/mutation-gate.mjs --id=<id>`).

| AC (issue #541) | Чем доказан | Чем краснеет |
|---|---|---|
| Rebase/смена run attempt не переносит старое доказательство новому кандидату (проверка `proof.run.attempt !== expected.attempt`) | `node --test test/ci-proof.test.mjs` (тест «SHA, tree, run attempt, event… cannot drift») | Снял только часть условия про `attempt` (`\|\| false && proof.run?.attempt !== expected.attempt`) — тест покраснел (1 fail из 8). Восстановлено, `git status` чист |
| Лёгкий зелёный run не проходит как full для release (`policy?.full && !asBool(proof.request?.full)`) | `node scripts/mutation-gate.mjs --id=release-proof-accepts-light-run` (witness: `test/ci-proof.test.mjs` + `test/release-gate.test.mjs`) | «release-proof-accepts-light-run: тест покраснел, как обязан» |
| Зелёный dispatch без реально доказанных mutant-job не проходит review/merge (`policy?.mutants && !asBool(proof.request?.mutants)`) | Ручная мутация той же строки | 1 fail в `test/validate-gate.test.mjs` («a green foreign dispatch whose mutant jobs were skipped is ignored»). Отдельного witness в `mutation-gate.mjs` для этой строки нет, но существующий unit-тест (унаследован от #510) реально её защищает |
| Reuse без независимо проверенной зелёной source-job не принимается (`!source \|\| … \|\| !executedCheckIsGreen(id, source.jobs)`) | `node scripts/mutation-gate.mjs --id=ci-proof-trusts-reuse-without-source-job` | «тест покраснел, как обязан» |
| Merge не принимает success-conclusion без proof-артефакта (`!proof` → `missing`, не `green`) | `node scripts/mutation-gate.mjs --id=merge-trusts-success-without-proof` | «тест покраснел, как обязан» |
| Красный dispatch / отменённый dispatch не проходят review (унаследованные из #510 проверки, переехавшие в `ci-proof.mjs`) | `node scripts/mutation-gate.mjs --id=review-starts-on-red-validate` и `--id=review-returns-task-on-cancelled-dispatch` | оба «тест покраснел, как обязан» |

Все шесть прогонов мутации выполнил лично, рабочее дерево после каждого чистое
(`git status --short` пусто).

## Разбор по AC issue (раздел «Приёмка»)

1. **«Full red → light green не разрешает release; настоящий full green после старого red разрешает»** — `test/release-gate.test.mjs`: «release skips a newer light proof but does not let it hide an older full failure» и «a later complete full proof refreshes an older red release candidate», оба green. Прочитано и логику `classifyValidateProofs`/`selectCiProofVerdict` — идут от новейшего run к старому, пропуская `cancelled`/`stale`, первый решительный статус — вердикт.
2. **«Dispatch без реально доказанных mutant jobs не разрешает merge»** — `test/ci-proof.test.mjs` («green dispatch without six executed mutant jobs proves neither review nor merge») и `test/merge-candidate.test.mjs` («real merge waiter never accepts a successful dispatch without its proof artifact») — оба green; независимая проверка `executedCheckIsGreen` берёт реальный список job из GitHub API, а не то, что заявляет сам proof.
3. **«Законное content-addressed reuse принимается только с полными доказательствами»** — тест «reuse needs a content key, marker source SHA/run and the successful source job» проверяет три угла: пустой `reuseRuns` → failed, испорченный `key` → failed, но легитимный reuse на источник с посторонним красным job (сам overall run красный, но конкретная job зелёная) — принимается (это явно документированное поведение, не дыра: content-addressed единица — job, а не run).
4. **«Rebase/run attempt не переносят чужие доказательства»** — см. таблицу выше.
5. **«Тесты сравнивают consumers на одной матрице fixtures»** — `test/ci-proof.test.mjs`, тест «one state machine gives review, merge and release the same terminal semantics» гоняет один и тот же fixture через `Object.values(CI_PROOF_POLICIES)` (review/merge/release), не только regex по YAML (тот отдельно проверяет только структуру workflow, `test/validate-workflow.test.mjs`).

Отдельно проверил переход документации: `docs/TESTING.md`/`docs/DEVELOPMENT.md` меняют формулировку «prereleases need the fast exact-SHA Validate only» → «every release, including a prerelease, needs the full exact-SHA Validate proof». Это выглядело как расширение объёма гейта на бету, но чтением `scripts/classify-changes.mjs:heavyGatesRequested` подтвердил: коммит с трейлером `Release:` уже до этой задачи (#479) безусловно требовал `heavy=true` — новая формулировка лишь чинит устаревший текст под фактическую автоматизацию и закрывает ровно ту дыру, которую описывает аудит (release-скрипт раньше принимал любой `success`, не разбирая light/full). Прогонов CI это не удорожает.

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

- `buildCiProof`/`evaluateCiProof` — единая точка входа для review/merge/release, консистентна по всем полям (candidate.sha/tree, run.id/attempt/event, requiredChecks/executedChecks/reusedChecks).
- Job-правила (`JOB_RULES`) независимо перепроверяют состав и `conclusion` реальных job (не верят самозаявлению proof), включая фиксированное число мутантных шардов (6) и smoke-шардов (3), совпадающее с `matrix.shard` в workflow.
- `readCiProofArtifact` — самодельный ZIP-ридер, покрыт unit-тестом на сконструированном архиве (store + deflate).
- `parseReuseMarker` — fail closed при отсутствии SHA/run/attempt.
- Workflow YAML валиден, граф `needs` финальной job `proof` совпадает с реальными job id, `if: always()` обеспечивает публикацию доказательства и на красном прогоне.
- Трейлеры коммитов, ветка `issue/541-ci-proof`, отсутствие изменений класса A — соответствуют инфраструктурному треку §1.
- Хендофф-история в issue честно фиксирует найденные и исправленные на живом GitHub Actions дефекты (усечение имени job, YAML flow-mapping с выражением) и результаты трёх реальных прогонов workflow, включая наблюдение `stale` для light/non-full runs.

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

- Полный `npm run gate:small`/`npm test` не повторял целиком — заявленный зелёный Validate на точном материале (`0fd6977b`) уже покрывает typecheck/test/build по условию ревью; повторно прогнал только новые/изменённые целевые файлы тестов.
- `npm run golden:verify`, `check-docs.mjs`, `model-invariants.mjs`, `pytest tests_backend` — не применимы к диффу (нет `src/**`, геометрии или Python).
- Не воспроизводил реальный workflow_dispatch на GitHub (это уже сделано автором трижды на этой ветке, со ссылками на прогоны в хендоффе); проверил логику и тесты, которые эти прогоны обвязывают.
- Не проверял отдельно `scripts/gate-reuse.mjs`/ключи реюза как таковые (не менялись в этом диффе, кроме одной записи в `check-inputs.mjs`, покрытой `test/check-inputs.test.mjs`).

## Находки

**High: 0. Medium: 0.**

- **Low (не блокирует, оставляю на усмотрение автора/следующей задачи).** `scripts/validate-gate.mjs::provesMutants` и `realOps.jobs` больше не вызываются из продовой логики `validateGate` — решение о доказанности mutant-job теперь принимает `evaluateCiProof`/`JOB_RULES` в `ci-proof.mjs`. Функция и её тесты (`test/validate-gate.test.mjs:66-70`) остаются рабочими и содержательными сами по себе, но как часть решающего пути они мертвы; риск нулевой (защита не ослаблена, просто задвоена), снимаю без цикла — не переписываю продуктовый код сам, вопрос ревьюеру не задаётся, это техническая деталь автора.

## Вердикт

Все AC issue #541 доказаны автотестами, которые я лично прогнал и для критичных защит — лично сломал мутацией и увидел красный. High/Medium находок нет; единственная Low-находка — не более чем указание на будущий cleanup, не блокирует.

**Вердикт: зелёный · заход r1 · блокирующих циклов 0/4 · High: 0 · Medium: 0**

---

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

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

- Ветка: `issue/541-ci-proof`, коммит `0fd6977b47d6` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `1b1886c210926f1aa43a0db47a979c25472384bd`
  ```
  git log --all --format='%H %T' | grep 1b1886c21092
  ```
- Тело issue: `b34ab665a4f9ae621b08dcb3854faec5c4e7fdb1b8e0c3c4e1b5b62ab3eef116`
- Вердикт конвейера: `green` · High 0