houseplan-card/docs/reviews/SPEC-REVIEW-510-r3.md

# SPEC-REVIEW-510-r3

- **Issue:** https://github.com/Matysh/houseplan-card/issues/510
- **ТЗ:** `docs/specs/510-mutants-on-candidate-and-review-waits-validate.md`
- **Этап:** spec (S4-spec-review) · заход r3 · блокирующих циклов израсходовано 2/4 до этого раунда
- **Материал:** ТЗ на HEAD рабочей копии (`3854fe72ac59b1e37a80b25faea0f8468356597a`), дельта против материала r2 (`5fc235c0e8de`)
- **Предыдущий раунд:** SPEC-REVIEW-510-r2, вердикт жёлтый, SHA материала `5fc235c0e8de`, High 0 · Medium 1 · Low 0

## Скоуп ревью

Разбор — по дельте (PROCESS.md §2.9/§2.10, issue #214): дельта локальна — правка того же ТЗ, той же ветки, без ребейза и без смены подсистемы, объём (3 предложения в одном разделе, `git diff --stat` — 4 вставки/4 удаления в одном файле) на порядок меньше исходной задачи. Но, как и в r2, дельта сама переписывает межшаговую проводку `process.yml` (§5.2) — контракт, по которому ветвятся все шаги ревью после `gate`. Поэтому разбор по дельте здесь не сводится к чтению трёх изменённых строк текста: нужно (1) закрыть находку r2 построчно, как и предписано форматом, и (2) проверить новую формулировку контракта против реального `process.yml` и существующих тестов — именно так r2 нашла свою находку не в новом тексте, а в столкновении нового текста со старым. Разделы, которых дельта не касается текстуально и чей контракт не меняется этой правкой (§1–§4, §5.1, §6, §7, §8 кроме связки со строкой 72, §9, §10.0, §10.1, §11, §12), не перепроверялись — унаследованы (см. ниже).

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

- `git diff 5fc235c0..3854fe72 -- docs/specs/510-mutants-on-candidate-and-review-waits-validate.md` — вся дельта, один хунк из 3 изменённых предложений в §5.2 (строки 69, 71, 72; строка 73 — только добавление «на этапе code», не меняющее её смысл).
- `git show 3854fe72` — сообщение коммита прочитано целиком, а не только дифф: «All step conditions now branch on `proceed` only (true = green or skipped, false = red/missing)» — это явная формулировка проектного решения, а не побочный эффект правки формулировок, и именно она проверялась.
- Находка r2 (единственная) сверена построчно с новым текстом (таблица ниже).
- Реальный `process.yml` (`grep -n "steps.reuse.outputs.reuse\|id: reuse\|id: gate\|Установить зависимости\|name: Review"`) — нынешние условия шагов «Установить зависимости», кэш/установка Chromium (пять мест) и шага `Review` (вызывающего модель) — везде `steps.rebase.outputs.conflict != 'true' && steps.reuse.outputs.reuse != 'true'`, не только `rebase.conflict != 'true'`, как упрощённо называет это ТЗ.
- `test/review-doc-guard.test.mjs:592-603` — существующий (не из этой задачи) тест «конвейер: зелёный вердикт применяется повторно без модели» жёстко требует `assert.match(reviewStep, /steps\.reuse\.outputs\.reuse != 'true'/, 'модель не вызывается при повторном применении')`. Этот тест в §11 ТЗ №510 назван как затрагиваемый файл, но ни разу не упомянут в §8 (плане тестов) как изменяемый или заменяемый.
- Перечитан весь фрагмент §5.2 целиком (строки 69–76), а не только изменённые предложения по отдельности — так же, как это делала r2 при поиске своей находки.

## Закрытие раунда r2

| Находка r2 | Чем закрыта | Где это видно |
|---|---|---|
| Medium 1 — три соседних предложения называли условие продолжения/возврата тремя разными именами (`result`/`proceed`), и буквальное `result != 'green'` для красного возврата (строка 71 r2) давало бы паразитный `S7→S6` на skip-ветке (spec/reuse) | **Частично.** Красный-возврат (строка 71) переписан на `steps.rebase.outputs.conflict != 'true' && steps.gate.outputs.proceed != 'true'` — на skip-ветке `proceed == 'true'`, шаг не срабатывает, паразитный возврат устранён. Формально устранена и текстовая нестыковка трёх формулировок: строка 69, строка 71 и строка 72 теперь одинаково используют `proceed`, а не смесь `result`/`proceed`. | `docs/specs/510-*.md:71` (красный-возврат — исправлено верно); `:69,72` (унификация терминов — сделана) |
| — та же находка, часть про строку 72 («все последующие шаги ревью») | **Не закрыта, закрыта неверно.** r2 явно предлагала для этой группы **оставить** `result == 'green'` буквально, потому что она (в отличие от красного-возврата) обязана оставаться заблокированной на skip-ветке — reuse обязан коротко замкнуть без реального ревью. r3 вместо этого заменила условие всей группы (`validated`, зависимости, Chromium, Claude, Review, публикация, решение, слияние, перестановка метки) на `proceed == 'true'`, а `proceed == 'true'` истинно и на skip-ветке (reuse) по определению той же строки 69 («`true` = green **или** skipped»). Это не formальность: см. находку ниже — это открывает шаг `Review` (вызов модели) и установку зависимостей/Chromium на reuse-ветке, где сейчас они не выполняются вовсе. | `docs/specs/510-*.md:72` (новая формулировка); противоречит реальному `process.yml` (условия шагов «Установить зависимости», кэш/установка Chromium, `Review`) и `test/review-doc-guard.test.mjs:596` |

Находка r2 закрыта только в своей «текстовой» части (три формулировки сведены к одному слову) — но одна из трёх сведена к неверному значению. Синтаксическая цель ревью r2 («одна переменная — одно условие») достигнута; содержательная («группа „продолжение ревью“ не должна срабатывать на skip-ветке») — нарушена этим же изменением.

## Находки

### Medium (в скоупе) — 1: унификация «всё через `proceed`» ломает reuse-fast-path (#499) — деплой-зависимости, Chromium и вызов модели получили бы условие, истинное и на ветке, где их сейчас не выполняют вовсе

**Файл:** `docs/specs/510-mutants-on-candidate-and-review-waits-validate.md`, §5.2, строки 69 и 72.

Строка 69 вводит абсолютное утверждение: «Единственная переменная, по которой ветвятся последующие шаги, — `proceed`». Строка 72 применяет это к группе «все последующие шаги ревью (`validated`, зависимости, Chromium, Claude, Review, публикация, решение, слияние, перестановка метки)» — их условие меняется на `steps.gate.outputs.proceed == 'true'` **вместо** нынешнего `steps.rebase.outputs.conflict != 'true'`.

Но нынешнее условие этих конкретных шагов в реальном `process.yml` — не `rebase.conflict != 'true'` в одиночку, а `steps.rebase.outputs.conflict != 'true' && steps.reuse.outputs.reuse != 'true'` (проверено чтением файла: «Установить зависимости», пять мест кэша/установки Chromium, шаг `Review`, вызывающий модель, — везде оба условия). ТЗ называет только первый конъюнкт как заменяемый и ни словом не упоминает второй — а коммит r3 («All step conditions now branch on `proceed` only») прямо формулирует замену как тотальную, не частичную.

Раз `proceed` по той же строке 69 истинен и на skip-ветке (`stage != code`, `reuse == true` или нет ветки — «`true` = green **или** skipped»), буквальная реализация строки 72 даёт: на reuse fast-path (`reuse == true`) условие `proceed == 'true'` истинно → шаги «Установить зависимости», кэш/установка Chromium и `Review` (вызов модели) **выполнятся**, хотя сегодня они не выполняются вовсе — в этом и была точка #499: «вердикт прошлого захода применяется повторно: модель не вызывается» (комментарий в `process.yml` перед шагом `reuse`). Конкретное воспроизведение: `test/review-doc-guard.test.mjs:592-603`, тест «конвейер: зелёный вердикт применяется повторно без модели», жёстко требует `steps.reuse.outputs.reuse != 'true'` именно в условии шага `Review` — при реализации §5.2 буквально по тексту r3 этот существующий тест либо ломается, либо реализация должна тихо отступить от буквального текста ТЗ и сохранить `&& steps.reuse.outputs.reuse != 'true'` вопреки заявленному «единственная переменная — `proceed`». Ни то, ни другое ТЗ не называет явно; `test/review-doc-guard.test.mjs` при этом перечислен в §11 как затрагиваемый файл, но конкретно эта проверка не упомянута в §8 ни как сохраняемая, ни как заменяемая.

Здесь же собственное противоречие внутри абзаца: строка 73 (не изменена по смыслу в этом раунде) описывает шаг `validated` как срабатывающий «при `proceed == 'true'` **на этапе code**» — то есть его поведение зависит не только от `proceed`, но и от `stage`, отдельной переменной. Заявление строки 69 «единственная переменная — `proceed`» опровергается уже следующим абзацем того же документа.

Воспроизведение (конкретный сценарий, не гипотетический): round задачи применяет reuse (зелёный вердикт прошлого захода переносится без вызова модели, ровно сценарий #437/#499, ради которого и заведён этот механизм) → `gate` пишет `proceed=true`, `result=skipped` (строка 69) → по буквальному тексту строки 72 шаг `Review` получает условие `proceed == 'true'` → модель вызывается повторно на том же дереве, за которое уже заплачен один заход, что и есть ровно тот перерасход, который #499 закрыл, только на новом месте.

**Чем закрывается в этом же ТЗ:** явно развести, как и предлагала r2, но с учётом факта, найденного в этом раунде — существующего `reuse` конъюнкта, о котором ТЗ не сказало ни слова:
- красный-возврат (строка 71) — `proceed != 'true'` (эта часть уже верна, менять не нужно);
- группа «продолжение ревью» (строка 72) — либо явно сохранить существующий `&& steps.reuse.outputs.reuse != 'true'` в дополнение к `proceed == 'true'` для тех конкретных шагов, что сегодня его несут (зависимости, Chromium, `Review`), либо (эквивалентно и проще для «одной переменной») зафиксировать, что `gate` пишет `proceed=false`, а не `true`, на reuse-ветке — но тогда нужно менять и красный-возврат (строка 71), который на этой ветке не должен сработать, то есть развести «reuse» как третье, отдельно поименованное значение, а не смешивать его с `skipped`-для-spec;
- строку 69 («Единственная переменная — `proceed`») — либо снять как неточную (строка 73 её же опровергает), либо явно ограничить область действия: «единственная переменная, добавляемая этим ТЗ» — не единственная вообще.
Правка — уточнение слов в тех же трёх местах плюс явное упоминание существующего `reuse`-конъюнкта, отдельный issue не заводится (Medium в скоупе, PROCESS.md §2.4).

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

- Красный-возврат (строка 71) исправлен верно и именно так, как предлагала r2: `proceed != 'true'` не срабатывает на skip-ветке — паразитный `S7 → S6` для spec/reuse-заходов устранён.
- Формальная (лексическая) нестыковка трёх формулировок из r2 устранена: строки 69/71/72 больше не называют одно и то же разными именами.
- Остальной текст §5.2 (порядок шага `gate` относительно `reuse`/«Конфликт с dev», алгоритм `validate-gate.mjs`, §5.1, §5.3) дельтой не тронут и остаётся тем, что уже проверено в r1/r2 построчно против кода.
- AC1, AC3, AC4, AC5, AC6 дельтой этого раунда не задеты по существу — унаследованы.

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

- `npx tsc --noEmit`, `npm test`, `npm run build`, `node scripts/check-docs.mjs` — не запускал: дельта r2→r3 — 4 вставки/4 удаления в одном `.md`-файле вне `src/**`/`scripts/**`/`test/**`, класс C (PROCESS.md §1), гейты неприменимы; то же самое было верно для r1 и r2, поведение не изменилось.
- Golden/смоки/perf/backend/инварианты модели — задача не трогает геометрию, рендер, состояние или бэкенд; не изменилось с r2.
- Права токена `HP_PROCESS_TOKEN`, риски §10.1 — не менялись дельтой, унаследованы из r1/r2.
- Реальная реализация `process.yml`/`validate-gate.mjs` — их нет, этап spec их не предполагает; находка выше проверена **чтением существующего** `process.yml` и существующего теста, не запуском.

## Унаследовано из r2

Без повторной проверки в этом раунде — дельта их не касается:

- Обязательные разделы §7.1 присутствуют и на своём месте — из SPEC-REVIEW-510-r1 (SHA `34bf81a1`) и подтверждено в SPEC-REVIEW-510-r2 (SHA `5fc235c0`).
- Скоуп/не-скоуп (§2/§3), включая границу с #479/#480/#499, и совместимость условия job `changed_mutants` (§4) с существующим механизмом `--changed` — из SPEC-REVIEW-510-r2, SHA `5fc235c0`; дельта этого раунда §4 не касается.
- Раздел §10.0 (UX/i18n/модель данных не затрагиваются) — из SPEC-REVIEW-510-r2, SHA `5fc235c0`; текст не менялся.
- Порядок шага `gate` относительно `material`/`reuse`/«Конфликт с dev» (§5.2, первое предложение) — сверен в r2 с реальными строками `process.yml` (414/430/445/485), дельтой r3 не тронут — из SPEC-REVIEW-510-r2, SHA `5fc235c0`.
- Алгоритм `scripts/validate-gate.mjs` (§5.1), включая закрытие Medium 2 из r1 («доказательство только при исполненных и зелёных job мутантов») — из SPEC-REVIEW-510-r1 (SHA `34bf81a1`) и SPEC-REVIEW-510-r2 (SHA `5fc235c0`), текст §5.1 дельтой r3 не тронут.
- §6 (слияние кандидата), §7 (правила хендоффа), §9 (откат), §10.1 (риски), §11 (затронутые файлы), §12 (предположения) — из SPEC-REVIEW-510-r1/r2, текст не менялся ни в r2, ни в r3.
- AC1, AC3, AC4, AC5, AC6 — из SPEC-REVIEW-510-r1/r2, способ доказательства не изменился.

## Вердикт

High: 0 · Medium (в скоупе): 1 · Low: 0.

Находка r2 закрыта только частично: красный-возврат исправлен верно, но формулировка «единственная переменная — `proceed`», применённая ко всей группе «продолжение ревью» (включая установку зависимостей, Chromium и вызов модели), конфликтует с реальным кодом `process.yml` (условия этих шагов сегодня требуют ещё и `steps.reuse.outputs.reuse != 'true'`) и с существующим тестом `test/review-doc-guard.test.mjs:596`, который жёстко фиксирует, что модель не вызывается на reuse-ветке (#499). Буквальная реализация текста r3 открывает ровно тот перерасход (повторный вызов модели на уже принятом дереве), ради устранения которого заведён #499. Это не гипотетика — сценарий воспроизведён по коду и существующему тесту, а не по документу самому по себе. Закрывается в этом же ТЗ уточнением трёх формулировок §5.2 с явным упоминанием `reuse`-конъюнкта.

**Вердикт: жёлтый.** Возврат в «ТЗ в работе» для уточнения §5.2 (строки 69, 72); далее — повторный цикл ревью по дельте (PROCESS.md §2.9/§2.10).

---

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

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

- Ветка: `issue/510-mutants-on-candidate-and-review-gate`, коммит `3854fe72ac59` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `45ab656b9462fc4f8a3a6f5eaad139d4b14d9f99`
  ```
  git log --all --format='%H %T' | grep 45ab656b9462
  ```
- ТЗ `docs/specs/510-mutants-on-candidate-and-review-waits-validate.md`, блоб `66bd41844726bd574d4fe59b506cd1f4389c34f8`
  ```
  git log --all --find-object=66bd41844726bd574d4fe59b506cd1f4389c34f8 -- docs/specs/510-mutants-on-candidate-and-review-waits-validate.md
  ```
- Вердикт конвейера: `yellow` · High 0