houseplan-card/docs/reviews/SPEC-REVIEW-481-r2.md

# SPEC-REVIEW-481-r2

Issue: #481 «changed_mutants: журнал пойманных свидетелей вместо суда по диапазону»
Этап: ТЗ на ревью (PROCESS.md §2.4). Трек: `small` — ТЗ в теле issue, файл
`docs/specs/481-*.md` не создан (проверено: `ls docs/specs/ | grep -i 481` — пусто).
Заход: r2 · блокирующих циклов израсходовано 1 из 2 (r1 был жёлтым и потратил цикл;
зелёный вердикт цикла не образует, #227).

## Скоуп

Предмет ревью — тело issue #481 на текущий момент, целиком, но разбор — по дельте
между r1 и r2 (PROCESS.md §2.10): полностью переразобраны только два места, которых
касалась правка автора; остальное (AC1–AC5, AC7, ссылки, оценка, список файлов)
унаследовано из r1 без повторной проверки по существу, с точечной сверкой фактов,
которые дёшево перепроверить (см. «Унаследовано из r1»).

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

1. Найден вердикт r1 — комментарий в issue (жёлтый, High: 0, Medium: 2) и документ
   `docs/reviews/SPEC-REVIEW-481-r1.md` (коммит `2f65a184`, `git show 2f65a184:docs/reviews/SPEC-REVIEW-481-r1.md`).
   Блок «Материал раунда» в конце r1-документа несёт **пустой SHA ветки** («Ветка: dev,
   коммит `` — ... Якоря снять не удалось: ветки задачи нет, материал читался по dev»).
   По PROCESS.md §2.10 это прямо названо нормальным случаем, а не находкой: «если SHA не
   резолвится — это не находка, а обычное дело»; находкой было бы только SHA, мёртвое уже
   на момент публикации — здесь SHA просто не указано, а не указано неверно. Дельту
   поэтому объявляю не по коду, а по тексту: r1-документ дословно цитирует то, что было
   в теле issue на момент r1 (формулировки находок 1 и 2 ниже), и комментарий автора
   после r1 прямо перечисляет, что изменено. Оба источника сверены с текущим телом
   issue построчно.
2. Дельта = добавленный `### 6. Откат` внутри «Решение» + переписанная колонка
   «Доказательство» строки AC6 в таблице критериев. Больше правок в теле issue между
   r1 и r2 нет (сверено построчно с текстом, процитированным в r1-документе и с
   комментарием автора).
3. По каждой из двух Medium-находок r1 — сверено дословное совпадение предложенного
   в r1 исправления с тем, что появилось в issue (см. таблицу ниже).
4. AC1–AC5, AC7 дельта не затрагивает — не переразбирались по существу. Дёшево
   сверено: файл `docs/specs/` по-прежнему отсутствует; названные в AC7 идентификаторы
   свидетелей (`ledger-records-escaped`, `ledger-version-sensitive`,
   `ledger-written-at-end-only`) и тесты `#481 AC1`…`#481 AC5` по-прежнему существуют в
   коде ветки (`grep` по `scripts/mutation-gate.mjs`, `test/mutation-gate.test.mjs`,
   `test/validate-workflow.test.mjs`) — спецификация не разошлась с уже существующей
   реализацией на ветке задачи. Это не код-ревью (реализация по существу не
   оценивалась), а та же перекрёстная сверка реализуемости, что делал r1.
5. Числа в комментарии автора после r1 (132/134 отобрано, 132 пропущено, 113/113 без
   изменения отпечатка) — не доказательство (AC6 явно это оговаривает), поэтому не
   перепроверялись побитово; но сами исторические SHA, на которые они ссылаются,
   проверены на существование и соответствие описанию: `052549fa` — «test: accept
   golden baselines after #471 and #476», `f2e38e48` — «build: prepare v1.73.0-beta.2
   candidate», `5d281171` — «ci: shard changed mutants before release», `04f4cd10` —
   «docs: refresh screenshot source fingerprint». Все существуют, ни один не выдуман,
   описание соответствует содержимому коммитов.
6. Гейты (typecheck/test/build) не гонялись — по прецеденту r1 и по существу этапа:
   материал spec-review — текст ТЗ, а не диапазон кода; их прогон принадлежит
   код-ревью (§2.7).

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

| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| Medium 1: отсутствует обязательный раздел «откат» (шаблон §5) | Добавлен `### 6. Откат` внутри «Решение», текст почти дословно повторяет формулировку, предложенную r1 («ревёрт коммита… `readLedger` трактует отсутствующий, битый или чужой по схеме файл как пустой журнал… старое поведение восстанавливается без ручных действий») | Тело issue #481, раздел «Решение» → «### 6. Откат» |
| Medium 2: AC6 доказывается способом вне таксономии §2.5 («замер при реализации, числа в issue» — запрещено правилом 18) | Колонка «Доказательство» строки AC6 переписана на «ревью кода (иллюстративные числа — комментарий автора в issue, не доказательство)» — выбран путь (b) из двух предложенных r1; критерий AC6 сформулирован как структурное утверждение, проверяемое чтением кода (отбор по диффу не изменён, сужение только через `splitByLedger`, версия-инвариантность — следствие AC1), а не как конкретное число мутантов | Тело issue #481, таблица «Критерии приёмки», строка AC6 |
| Low 3: влияние на perf/touch не названо явно словом «нет» (снято r1 без правки, с запиской) | Закрыто попутно тем же новым разделом: «Влияние на perf/touch/UX — нет: затронуты только скрипты, workflow и тесты» | Тело issue #481, конец «### 6. Откат» |

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

Документ: `docs/reviews/SPEC-REVIEW-481-r1.md` (коммит `2f65a184`; материал раунда —
`dev` на момент r1, SHA ветки в документе не резолвлен — по §2.10 это нормальный
случай, не находка).

Принято без повторной проверки по существу:
- AC1–AC5 и AC7 однозначны, проверяемы, попадают в разрешённую таксономию доказательств
  (unit / контрактный тест воркфлоу / отрицательные прогоны свидетелей); на ветке
  задачи для них есть реальные автотесты, различающие правильное и сломанное поведение.
- Ссылки на #475, #480, #472, #388 точны и соответствуют описанию автора.
- Технические факты не домысел: `guardFiles()` экспортирована, `visualFingerprint` и
  нормализация версии существуют в `scripts/source-fingerprint.mjs`, структура
  `MUTANT_DEFINITIONS` соответствует описанию.
- Раздел «Что не меняется» корректно ограничивает скоуп (полный прогон, `--check`,
  `--id` журнал не читают).
- `actions/cache/save … if: always()` — осознанное обоснованное отступление от
  соседнего success-only паттерна `performance_smoke`.
- Трек `small` обоснован: критерии §5 выполняются одновременно; файла
  `docs/specs/481-*.md` нет.
- «Затронутые файлы» — верно, всё класса B/C, ни одного класса A; подтверждено
  дополнительно и в этом раунде: `git diff --stat` с момента r1-документа (коммит
  `2f65a184`) по текущий HEAD `2c50e736` трогает ровно перечисленные файлы
  (`scripts/mutation-gate.mjs`, `scripts/source-fingerprint.mjs`,
  `.github/workflows/validate.yml`, `test/mutation-gate.test.mjs`,
  `test/validate-workflow.test.mjs`, `docs/TESTING.md`) плюс служебный
  `docs/images/screenshots.json` (отпечаток скриншотов, механика докс-гейта, не
  продуктовый файл) — класс A по-прежнему не задет.

## Находки нового раунда

Нет. High: 0, Medium: 0.

## Что проверено и корректно (в этом раунде)

- Текст нового раздела «Откат» точно соответствует поведению `readLedger`,
  независимо подтверждённому ещё в r1 чтением кода ветки: отсутствующий, битый или
  несовпадающий по схеме файл трактуется как пустой журнал.
- AC6 больше не привязан к нефальсифицируемому числу и не требует ручного «замера»:
  формулировка проверяема чтением кода, а поле доказательства явно в разрешённой
  таксономии §2.5 и не нарушает правило 18 (числа помечены как иллюстрация, не
  доказательство).
- Названные в комментарии автора исторические SHA (`052549fa`, `f2e38e48`,
  `5d281171`, `04f4cd10`) существуют и соответствуют описанным событиям (релизный
  кандидат, шардирование, докс-коммит) — иллюстрация не построена на выдуманных
  ссылках, хотя сама она и не является доказательством AC6.
- Открытых продуктовых вопросов в тексте нет; догадок, выданных за решённое
  поведение, не найдено — как в дельте, так и в унаследованной части (перепроверено
  r1, не оспаривается).

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

- Гейты (`tsc --noEmit`, `npm test`, `npm run build`) не гонялись: на этапе
  spec-review материал — текст ТЗ, а не диапазон кода; тот же выбор сделал r1 для
  этой же задачи по той же причине. `node scripts/check-docs.mjs` не запускался по
  той же причине — этот этап не проверяет состояние `src/**`.
- Не пересчитывал побитово иллюстративные числа из комментария автора (132 из 134
  отобранных пропущено по журналу; 113 из 113 без изменения отпечатка на бампе
  версии) — они явно помечены как не-доказательство, реальный прогон на историческом
  диапазоне и фиксация команды/результата — задача код-ревью (вариант (b) из
  находки r1 №2 прямо поручает это код-ревьюеру).
- Не переоценивал по существу реализацию на ветке `issue/481-mutation-ledger` —
  это предмет код-ревью (§2.7), не этого этапа; использовал код только как
  перекрёстную проверку (не домысел ли текст ТЗ), как и в r1.

## Вердикт

Зелёный. High: 0, Medium: 0. Обе Medium-находки r1 закрыты текстом issue дословно
по предложенным вариантам исправления, Low закрыт попутно. Статус — «Готово к
разработке».

---
Материал раунда: тело issue #481 на момент r2; предыдущий документ —
`docs/reviews/SPEC-REVIEW-481-r1.md` (коммит `2f65a184`); HEAD ветки на момент
этого разбора — `2c50e736` (detached, `origin/issue/481-mutation-ledger`).

---

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

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

- Ветка: `issue/481-mutation-ledger`, коммит `2c50e7367100` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `3d4c141fe31c1bad1f12948956a3246c678eec0c`
  ```
  git log --all --format='%H %T' | grep 3d4c141fe31c
  ```