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

# SPEC-REVIEW-291-r2

- **Issue:** https://github.com/Matysh/houseplan-card/issues/291
- **Этап:** ТЗ на ревью (PROCESS.md §2.4)
- **Заход:** r2 · блокирующих циклов израсходовано 1 из 4 до этого вердикта
- **Артефакт ТЗ:** `docs/specs/291-lattice-coordinate-write-barrier.md`
- **Ветка:** `issue/291-lattice-coordinate-barrier`
- **SHA ревью r1:** `8b99df6e` (зафиксирован в `docs/reviews/SPEC-REVIEW-291-r1.md`,
  не был назван в тексте вердикта-комментария — отмечаю это как процессный
  пробел r1, не блокирующий: сам документ ревью SHA называет)
- **SHA этого ревью (r2):** `23fb41d4` = текущий `HEAD`, ветка не отстаёт от
  `origin/dev` (`git merge-base origin/dev HEAD` = `523190d8`, что равно tip
  `origin/dev` на момент проверки) — ребейза не было, полный разбор по §2.10
  не требуется, разбор по дельте.
- **Трек:** обычный (не `small`/`trivial`) — без изменений с r1.

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

Второй заход. Предмет — дельта `git diff 8b99df6e..HEAD`, два коммита:

- `5da14e08` «docs: add product context and rollback» — правка Medium-находок
  r1 (M1: продуктовые разделы §7.1; M2: разделы «Риски»/«Откат»);
- `23fb41d4` «docs: record optimize report decision» — фиксация ответа
  владельца на Q1 (степень детализации отчёта Optimize) в теле ТЗ.

Диапазон `git diff origin/dev...HEAD --stat` — по-прежнему только два файла
документации (`docs/reviews/SPEC-REVIEW-291-r1.md`,
`docs/specs/291-lattice-coordinate-write-barrier.md`), класс C. Кода нет,
поэтому полный разбор не требуется ни по признаку ребейза (его не было), ни по
признаку смены контракта (контракт AC1–AC6, AC8–AC12 и разделы 4–6, 8, 10
дельтой не тронуты), ни по объёму (дельта — 138 добавленных/переставленных
строк из ~400, точечно в тех двух местах, которые назвал r1, плюс перенумерация
заголовков).

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

1. Восстановлена история раунда из комментариев issue #291 (аналитика → ТЗ →
   вердикт r1 → уточняющий вопрос Q1 → правка M1/M2 → ответ владельца на Q1) и
   сверена с `git log` веткой: коммит `8b99df6e` — тот же SHA, что назвал
   комментарий «ТЗ готово» и на который ссылается сам `SPEC-REVIEW-291-r1.md`.
2. `git diff 8b99df6e..HEAD -- docs/specs/291-lattice-coordinate-write-barrier.md`
   построчно сопоставлен с находками M1/M2 из r1: подтверждено, что каждая
   исправлена по существу, а не переформулирована на словах (таблица ниже).
3. Прочитан весь текущий файл ТЗ целиком (404 строки) — не только диф — чтобы
   поймать дефект, который правка по одному замечанию могла внести в
   нетронутую часть (регрессия §2.10, прецедент #102). Проверена сквозная
   нумерация разделов 1–15 после сдвига — последовательна, разрывов и повторов
   нет, внутренних ссылок на номера разделов в тексте (кроме заголовков) не
   найдено, значит перенумерация не оставила «висячих» ссылок.
4. Новый раздел 3 «Пользовательский контекст» и обновлённый раздел 7 сверены с
   `docs/USER-GUIDE.ru.md` (терминология интерфейса) — строки 1396–1420, 1444.
   Там же сверен факт, который был предметом M1: действующий (до #291) отчёт
   Optimize уже показывает один общий счётчик «шум координат» и отдельную
   строку сдвинутых элементов; per-space таблицы нет. Ключ `src/i18n/ru.json:817`
   (`gs.optimize_changes`) подтверждает то же самое буквально: один общий
   `{p}`, без разбивки по пространствам. Значит новое AC7 (per-space строки
   только для изменённых пространств) действительно вводит новый видимый
   текст, а не переописывает существующий — и именно это теперь оформлено как
   решение владельца (Q1), а не как факт от автора.
5. Сверены 10 сопоставимых ТЗ (090, 094, 150, 178, 179, 210, 211, 226, 252,
   279) на предмет конвенции разделов «i18n» и «Риски/Откат» — второй раз,
   целенаправленно на предмет i18n, поскольку сам факт наличия раздела не был
   предметом явной проверки в r1 (см. находку M3 ниже). Ближайший по смыслу
   документ — `docs/specs/252-optimize-orphan-layout-report.md` (тоже про
   Optimize report): у него нет отдельного заголовка «i18n», но каждая новая
   строка отчёта именует свой ключ инлайн (`gs.optimize_reference_warning`) и
   AC явно требуют «RU/EN i18n и unit matrices». Другой сопоставимый документ,
   `094-universal-state-toggle.md:645-663`, даёт образец полноты: список
   конкретных новых/меняющихся строк с RU/EN текстом.
6. Гейты кода не прогонялись — диф не содержит класса A/B (см. «Чего не
   проверял»).

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

| Находка r1 | Чем закрыта | Где видно |
|---|---|---|
| **M1** — нет продуктовых разделов §7.1 (персона/поверхность/момент, «до/после»); степень детализации Optimize-отчёта подана как факт, а не как предположение/вопрос | Добавлен раздел «3. Пользовательский контекст и результат» (персона — владелец дома с несколькими этажами, поверхность — Plan/Optimize, момент — обслуживающее действие и обычная запись; «до»/«после» одним абзацем каждое). Степень детализации отчёта переведена из факта автора в явный вопрос владельцу (Q1, комментарий 10:54:35) с default-вариантом и получила прямой ответ владельца (комментарий 11:40:47), зафиксированный как «Решения владельца» п.4 | `docs/specs/291-*.md` §3 (было добавлено в `5da14e08`); §2 п.4 и §7 (обновлены в `23fb41d4` по ответу владельца); issue-комментарии `5394220413` (вопрос) и `5394680424` (ответ) |
| **M2** — нет разделов «Риски» и «Откат», обязательных по DoR §2.5 и во всех 10 сопоставимых ТЗ | Добавлены разделы «11. Риски и меры» (5 пунктов риск→мера, привязанных к конкретным AC) и «12. Откат» (revert коммита, без миграции схемы, честная оговорка про уже канонизированные биты и Undo для явного Optimize) | `docs/specs/291-*.md` §11–§12, коммит `5da14e08` |
| **L1** (Low) — пример вывода CLI в AC3 (`noise: 0 (0.00%)`) не совпадает с реальным форматом `latticeReport()` | Не тронуто в этой дельте | `docs/specs/291-*.md`, раздел AC3 (текущий §9) — прежний текст без изменений |
| **L2** (Low) — тело issue называет задачу «Стадия 1 из ADR #282», хотя это Stage 0-продолжение, а не Stage 1 ADR | Не тронуто — тело issue #291 на момент этого ревью содержит ту же фразу | Тело issue #291, первый абзац |

M1 и M2 — единственные Medium из r1, обе закрыты по существу, не текстом
«исправлено». L1/L2 были явно необязательны к этому заходу (решение
ревьюера r1) и остаются открытыми ниже как унаследованные, не блокирующие.

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

### Medium (в скоупе задачи — чинится в текущем issue)

**M3. Раздел «i18n», обязательный по цепочке §7.1, отсутствует; новые строки
отчёта Optimize (per-space breakdown, строка максимального сдвига), введённые
именно этой дельтой через принятое решение по Q1, не имеют перечисленных
ключей en/ru.**

- **Файл:** `docs/specs/291-lattice-coordinate-write-barrier.md` — весь
  документ; ближе всего к месту дефекта разделы «7. Existing data и explicit
  Optimize report» и «13. Ожидаемые файлы».
- **Что не так:** `PROCESS.md` §7.1 перечисляет обязательные разделы ТЗ:
  «...модель данных и миграция · **i18n** · критерии приёмки...», а DoR-чеклист
  §2.5 требует «i18n: ключи en + ru перечислены» как отдельного пункта,
  без которого «статус не «Готово к разработке», как бы ни хотелось начать».
  В документе i18n встречается только как имя двух файлов в разделе 13
  (`src/i18n/en.json`, `src/i18n/ru.json`), без единого имени ключа и без
  текста строки.
  Это не было заметно до этой дельты: до ответа на Q1 отчёт был
  неспецифицирован (M1), и требовать ключи для неопределённого контента было
  бы рано. Теперь контент решён (§2 п.4, §7, AC7 этого документа), и именно
  дельта, закрывшая M1, обнажила этот пробел — проверка «дошла ли дельта» по
  §2.10 обязывает досмотреть его сейчас, а не отложить на код-ревью.
  Действующий ключ `gs.optimize_changes` (`src/i18n/ru.json:817`) — плоская
  строка формата `«...устранён шум координат: {p}; объединено отрезков...»`;
  для новых per-space строк и строки максимального сдвига неясно, расширяется
  ли этот же ключ параметрами, добавляется отдельный ключ на строку,
  добавляется отдельный ключ-шаблон на пространство с интерполяцией — три
  разных решения с разными последствиями для pluralisation и для существующего
  теста паритета i18n.
  Сопоставимые документы называют реальную практику: `docs/specs/252-optimize-orphan-layout-report.md`
  (тот же диалог Optimize) без отдельного заголовка «i18n», но с инлайн-именами
  ключей (`gs.optimize_reference_warning`) и явным AC на RU/EN unit matrices;
  `docs/specs/094-universal-state-toggle.md:645-663` — образец отдельного
  раздела с перечнем конкретных новых/меняющихся строк. В 291-м ни того, ни
  другого нет.
- **Сценарий, где это ломается:** разработчик на код-ревью добавляет новый
  ключ `gs.optimize_lattice_space` со своей pluralisation-схемой; ревьюер кода
  не может сверить её с ТЗ, потому что ТЗ не называло ни имени, ни структуры —
  решение принимается кодом, а не ТЗ, что прямо противоречит цели §7.1
  («размытое место не додумывается [в коде], а решается в ТЗ либо явно
  выносится предположением»).
- **Что сделать:** добавить короткий раздел (или подпункт к §7) с перечнем
  новых/меняющихся ключей en+ru — по образцу `094-*.md`: имя ключа, RU/EN текст
  или явное «расширяет `gs.optimize_changes` параметром `{spaces}`»; либо, если
  автор считает именование чисто техническим и несмотрящимся пользователю
  вопросом, добавить его явным пунктом в §15 «Принятые технические
  предположения» — но не оставлять полностью неупомянутым, как сейчас.

### Low (унаследованные, не блокируют, статус не изменился)

**L1** (из r1) — пример CLI-вывода в AC3 остаётся текстово рассинхронизирован
с `latticeReport()`. Не тронуто этой дельтой. Решение ревьюера прежнее: не
блокирует, правится заодно со следующей правкой документа.

**L2** (из r1) — тело issue #291 всё ещё называет задачу «Стадия 1 из ADR
#282»; расхождение с фактическим содержанием Stage 1 ADR (stable wall ids)
остаётся. Не относится к файлу ТЗ, не блокирует.

## Что проверено и признано корректным

- **M1 закрыта по существу, не по форме.** Раздел 3 отвечает на оба
  обязательных вопроса §7.1 (кто/где/когда встретит; что видно до/после), и,
  что важнее прежней находки, спорная деталь (степень детализации отчёта)
  перестала быть догадкой автора: она прошла через реальный вопрос владельцу
  с default-вариантом и получила его явное решение, зафиксированное текстом
  «Решения владельца» — это сильнее минимальной планки «пометить
  предположением», которую просил r1.
- **M2 закрыта содержательно.** Пять пунктов «риск → мера» в §11 адресуют
  именно те угрозы, которые делают риск 10/10 нетривиальным (широкий threshold,
  расхождение TS/Python округления, обход barrier, перф деградация, тихая
  очистка старого шума обычной записью) — каждый привязан к конкретному AC,
  не декларативен. §12 «Откат» честно называет то, что не откатывается
  автоматически (уже канонизированные биты), и почему это не считается
  потерей — это ровно тот уровень честности, которого не было в r1.
- **Перенумерация не внесла дефектов.** Прочитан весь документ целиком после
  сдвига разделов 3→15; последовательность 1–15 без разрывов и повторов,
  внутренних ссылок на устаревшие номера разделов не найдено.
- **Обновлённый §7/AC7 не противоречит уже принятому в r1 техническому
  контракту.** Формула распределения (total = Σ по изменённым пространствам,
  far отдельно, max shift отдельно от `moved/maxShiftCm`) не меняет ничего из
  §4–§6, §8–§9 (кроме самого AC7), которые дельта не трогала.
- **Новый текст §3/§7 не противоречит `docs/USER-GUIDE.ru.md`.** Формулировки
  про «отдельную строку шума» и «одну серверную отмену» описывают то же самое,
  что уже документировано как действующее поведение (строки 1396–1420,
  1444–1454) — ТЗ расширяет существующий контракт, а не изобретает его задним
  числом.
- **Ветка не отстаёт от `origin/dev`, ребейза не было** — `git merge-base
  origin/dev HEAD` совпадает с tip `origin/dev`; полный повторный разбор по
  §2.10 (случай ребейза) не требуется.

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

Принято без повторной проверки в этом раунде — документ
`docs/reviews/SPEC-REVIEW-291-r1.md`, SHA `8b99df6e`:

- Численный контракт §3.1–3.2 (ныне §4.1–4.2 после сдвига): `GRID_N=240`,
  `1e-4` threshold, формула deviation — сверены в r1 с реализованным
  `scripts/model-invariants.mjs`; дельта эти разделы не трогала.
- Разграничение `canonicalizeLatticeCoordinate`/`canonicalizeScalar` и
  совместимость с nine-decimal contract #224 — не изменено дельтой.
- Allow-list полей (§5, было §4) — сверен в r1 с `modelCoordinates()`
  (`scripts/model-invariants.mjs:316-358`); не изменено дельтой.
- Write barrier §6 (frontend/backend, source/AST guard) — не изменено
  дельтой.
- AC1–AC6, AC8–AC12 (было AC1-AC6, AC8-AC12) — текст не изменён дельтой,
  кроме AC7; численные диапазоны, мутанты, perf-бюджет приняты в r1.
- Scope/не-скоуп (§8, было §7) — не изменено дельтой.
- §15 п.1–5 (принятые технические предположения) — приняты в r1 как корректно
  технические, не подмена продуктового решения; дельта добавила только п.6
  (layout без named owner), рассмотренный в этом раунде отдельно (см. «Что
  проверено»).
- Трек/трейлеры (обычный трек, не `small`) — не изменено.

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

- Код — не существует и в этом раунде: `git diff origin/dev...HEAD --stat`
  показывает два файла документации, класс C. Гейты `typecheck`, `npm test`,
  `npm run build`, `check-docs.mjs`, `invariants`, смоки, perf — неприменимы,
  не прогонялись. Причина — отсутствие класса A/B в диффе, а не пропуск.
- Полный повторный разбор AC1–AC6, AC8–AC12 и разделов 4–6, 8, 10 — дельта их
  не касалась, приняты по наследству из r1 (раздел выше), а не перепроверены
  заново построчно.
- Существующие i18n-ключи вне `gs.optimize_changes` (тот, что напрямую сверен
  с M1/M3) — не проверял остальной `gs.optimize_*` блок построчно; выборочная
  проверка ограничена тем, что нужно для находок M1/M3.
- Не связывался с владельцем: находка M3 сформулирована с предложенным
  решением (либо перечислить ключи, либо явно вынести именование в §15) и
  снимается автором в следующей редакции, а не эскалацией — вопрос
  технический (именование/структура ключа), а не продуктовый по критерию
  §7.1.

## Итог

0 High, 1 Medium (M3, в скоупе — чинится в этом же issue коротким добавлением
раздела/пункта), 2 Low унаследованных (не блокируют, статус не менялся).
Обе Medium-находки r1 (M1, M2) закрыты по существу и подтверждены построчно, не
на слово автора. Технический контракт, принятый в r1, дельтой не нарушен.
Без High — жёлтый вердикт: документ возвращается автору на добавление
i18n-раздела/пункта; заход r3 расходует второй цикл из лимита 4.