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

# SPEC-REVIEW-291-r3

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

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

Третий заход. Предмет — дельта `git diff 23fb41d4..HEAD`, один содержательный
коммит плюс один инфраструктурный:

- `4f1ad6fe` «docs: review document for #291» — публикация в репозиторий уже
  вынесенного документа `docs/reviews/SPEC-REVIEW-291-r2.md`; на текст ТЗ не
  влияет;
- `4ec43ffd` «docs: define lattice report translations» — правка единственной
  Medium-находки r2 (M3: не названы i18n-ключи per-space отчёта) плюс, сверх
  требуемого, синхронизация примера CLI-вывода в AC3 с реальным форматом
  `latticeReport()` (была унаследованная Low-находка L1 из r1/r2).

`git diff origin/dev...HEAD --stat` — три файла документации (два review-документа
плюс сам ТЗ), класс C, кода нет. Полный разбор не требуется ни по признаку
ребейза (его не было), ни по смене контракта (AC1–AC6, AC8–AC12 и разделы 1–6,
8, 10, 11, 12 дельтой не тронуты — правка только в §7.1 (новая подсекция) и в
примере AC3), ни по объёму (дельта — 17 добавленных/1 удалённая строка в файле
ТЗ, точечно в месте, которое назвал r2).

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

1. Восстановлена цепочка раунда: комментарий-вердикт r2 (жёлтый, M3, документ
   `SPEC-REVIEW-291-r2.md`) → коммит `4ec43ffd`, закрывающий M3 → отсутствие
   нового вопроса владельцу (правка чисто техническая, что и требовал сам текст
   M3: «вопрос технический… снимается автором»).
2. `git show 4ec43ffd -- docs/specs/291-lattice-coordinate-write-barrier.md`
   построчно сопоставлен с текстом находки M3 из r2 (таблица «Закрытие раунда
   r2» ниже) и отдельно — с описанием L1 (AC3 CLI-пример).
3. Прочитан весь текущий файл ТЗ целиком (422 строки), не только диф — та же
   дисциплина, что в r2, ради регрессии §2.10 (прецедент #102). Нумерация
   разделов 1–15 с подсекцией 7.1 последовательна, разрывов и повторов нет,
   внутренних ссылок на номера разделов, кроме заголовков, не найдено.
4. Новые ключи `gs.optimize_lattice_summary` / `gs.optimize_lattice_space`
   сверены построчно: (а) с текущими `src/i18n/en.json`/`ru.json` — оба имени
   отсутствуют, коллизии с уже существующими ключами (`gs.optimize_changes`,
   `gs.optimize_glow_migration` и соседние `gs.optimize_detail_*`) нет; (б) с
   §7 самого ТЗ — placeholders `{n}`/`{far}`/`{cm}` совпадают по смыслу с
   `latticeCoordinatesCanonicalized`/`latticeCoordinatesFar`/«maximum shift»;
   (в) с owner-решением §2 п.4 — компактный summary (два числа: canonicalized +
   max shift) буквально совпадает с двумя placeholders `gs.optimize_lattice_summary`,
   не больше и не меньше.
5. Прочитан существующий код отчёта Optimize (`src/align-grid.ts:56-200`,
   `src/houseplan-card.ts:15250-15270, 16337-16420`), которого диф не касается,
   чтобы понять, на какую реальную практику ложится новое решение M3, и не
   противоречит ли заявление «не требующими отдельной pluralisation» из §7.1
   действующей конвенции. Найдено: существующий `gs.optimize_changes` и соседние
   ключи (`count.devices`, `space.delete_blocked`, `import.start`) уже сплошь
   используют числовой placeholder без грамматической плюрализации — заявление
   в §7.1 не голословно, оно описывает реальную практику файла.
6. Найден и прочитан прецедент округления «физического сдвига» —
   `src/houseplan-card.ts:15259-15264`: `Math.ceil(maxShiftCm * 10) / 10`,
   документированная политика «round up, so the promise can never be smaller
   than the deed» для *обычного* grid-align. Это релевантно новому `{cm}` из
   §7.1 — см. находку L3 ниже.
7. Пример AC3 (`docs/specs/291-*.md:246-249`) сверен буквально с
   `scripts/model-invariants.mjs:518-525` (`latticeReport()`), включая пробелы
   и хвост «— ближе 0.0001 шага, но не точно»; `NOISE_STEPS = 1e-4`
   (`model-invariants.mjs:308`) подтверждает буквальное «0.0001».
8. Сверены 10 сопоставимых ТЗ на предмет формата раздела i18n (та же выборка,
   что в r2, целенаправленно на предмет структуры таблицы «ключ → EN → RU») —
   `094-universal-state-toggle.md:645-663` остаётся образцом; новый §7.1
   структурирован тем же способом (таблица ключ/EN/RU плюс условия показа).
9. Гейты кода не прогонялись — диф не содержит класса A/B (см. «Чего не
   проверял»).

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

| Находка r2 | Чем закрыта | Где видно |
|---|---|---|
| **M3** — раздел/пункт i18n отсутствовал; новые строки per-space отчёта (принятые по Q1) не имели перечисленных ключей en/ru | Добавлена подсекция «7.1 i18n-контракт отчёта»: таблица с двумя ключами (`gs.optimize_lattice_summary`, `gs.optimize_lattice_space`), их EN/RU текстом, условиями показа (`n > 0`; только затронутые пространства) и явным решением не расширять `gs.optimize_changes` | `docs/specs/291-*.md` §7.1, коммит `4ec43ffd` |
| **L1** (из r1, унаследована в r2 как открытая) — пример CLI-вывода в AC3 не совпадал с форматом `latticeReport()` | Пример переписан на реальный формат: `  шум у узла          0 (0.00%)  — ближе 0.0001 шага, но не точно`, буквально совпадает с шаблонной строкой функции и значением `NOISE_STEPS` | `docs/specs/291-*.md` §9 AC3, коммит `4ec43ffd`; сверено с `scripts/model-invariants.mjs:518-525,308` |
| **L2** (из r1) — тело issue #291 называет задачу «Стадия 1 из ADR #282» | Не тронуто в этой дельте | Тело issue #291, первый абзац — без изменений на момент этого ревью |

M3 — единственная Medium из r2, закрыта по существу (конкретные ключи, EN/RU
текст, условия показа, явное разграничение от существующего ключа), а не
переформулирована на словах. L1 закрыта тем же коммитом сверх required
объёма — не входила в предмет обязательной правки M3, но исправлена заодно;
отмечаю как факт, не как невыполненное требование.

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

### Low

**L3. Точность (число знаков/округление) нового placeholder `{cm}` в
`gs.optimize_lattice_summary` не названа, и очевидный кандидат на переиспользование
— существующая политика округления «вверх до 0.1 см» — даёт малоинформативное
число именно для той величины, ради которой она вводится.**

- **Файл:** `docs/specs/291-lattice-coordinate-write-barrier.md` §7.1 (новая
  подсекция этой дельты).
- **Что не так:** тело issue #291 само приводит порядок величины canonicalization
  shift — «максимальный сдвиг при канонизации 3,3·10⁻⁷ render units — три
  десятитысячных пикселя», и именно на этом основана owner-формулировка
  «продуктового риска нет». В кодовой базе уже есть готовый, документированный
  прецедент округления «максимального сдвига» для *обычного* grid-align:
  `src/houseplan-card.ts:15264` — `Math.ceil(r.report.maxShiftCm * 10) / 10`,
  с явным комментарием «round up, so the promise can never be smaller than the
  deed». Если автор реализации по аналогии применит эту же политику к новому
  `{cm}` (естественный шаг: имя переменной и физический смысл — оба «maximum
  shift в см» — совпадают), результат для реальных величин порядка `10⁻⁷` см
  будет **всегда** `0.1`, независимо от истинного значения: округление вверх
  превращает любое ненулевое, но исчезающе малое число в фиксированную
  «единицу видимости». Это не противоречит «round up» инварианту (число не
  меньше факта), но обесценивает саму причину, по которой в §7/AC7 эта
  величина выделена отдельной строкой, а не влита в `moved/maxShiftCm`: она
  должна явно читаться как микроскопическая, а не выглядеть как сопоставимая
  с реальным видимым перемещением grid-align (тот же порядок «0.1 см»). CLI-путь
  того же измерения решает эту задачу иначе — `latticeReport()` использует
  `toExponential(2)` для `worstNoise.steps` (`model-invariants.mjs:531-532`), то
  есть в проекте уже есть работающий прецедент представления субпиксельных
  величин без искажающего округления, но §7.1 к нему не апеллирует и вообще не
  упоминает точность.
- **Сценарий, где это заметно:** пользователь открывает Optimize после первой
  барьерной записи, видит строку «максимальный сдвиг: 0.1 см», не отличимую по
  виду от строки grid-align с реальным перемещением на миллиметр — и не может
  понять из текста, что фактическая величина в миллион раз меньше, хотя именно
  эта разница и была причиной, по которой владелец не увидел здесь риска.
- **Почему Low, не Medium:** сама цифра «0.1 см» не искажает решение
  Confirm/Cancel (величина в любом случае мала и находится в рамках owner-декларации
  «риска нет»), не блокирует ни один AC (AC7 не требует конкретной точности, только
  «не занижается») и не меняет контракт поведения — это вопрос читаемости числа,
  не корректности. Симметрично с прежней калибровкой этого документа: L1 в r1/r2
  был находкой того же класса (несовпадение текстового примера с форматом) и
  получил Low, а не Medium.
- **Что сделать:** в §7.1 или §15 одной строкой зафиксировать точность/формат
  `{cm}` (например: «round up до значимой цифры, не до фиксированного знака»,
  либо явно «использовать `toExponential`/иной формат, отличный от
  `Math.ceil(x·10)/10` grid-align»), либо явно принять текущее округление как
  сознательный выбор с оговоркой о его информативности. Правится заодно со
  следующей правкой документа; не блокирует эту.

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

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

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

- **M3 закрыта по существу.** Таблица §7.1 называет оба ключа, их EN/RU текст
  и условия показа, разграничивает новый счётчик от `gs.optimize_changes` —
  ровно то, чего требовал §7.1 PROCESS.md («размытое место не додумывается [в
  коде]»). Формат таблицы соответствует образцу `094-*.md`, на который
  ссылался сам текст находки.
- **Заявление «не требующими отдельной pluralisation» не голословно** — сверено
  с действующей практикой файла (`gs.optimize_changes` и соседние ключи,
  п.5 «Как проверялось»); все они используют числовой placeholder без
  грамматических форм.
- **Новые ключи не коллидируют с существующими** и не переопределяют
  `gs.optimize_changes` — проверено прямым grep по обоим i18n-файлам и по
  `src/houseplan-card.ts`.
- **AC3-пример теперь буквально совпадает с реализацией.** Построчная сверка с
  `latticeReport()` и `NOISE_STEPS`, включая пробелы перед «—».
- **Перенумерация/вставка §7.1 не внесла дефектов.** Документ прочитан целиком
  (422 строки); последовательность 1–15 с подсекцией 7.1 без разрывов,
  повторов и висячих ссылок на номера разделов.
- **Технический контракт §4–§6, §8, §9 (кроме текста AC3-примера), §10–§12 не
  затронут этой дельтой** и не противоречит новому §7.1: разделение
  «canonicalized noise shift» и «moved/maxShiftCm обычного grid alignment»,
  принятое в §7/AC7 ранее, буквально отражено двумя разными i18n-ключами, а
  не смешано в один.
- **Ветка не отстаёт от `origin/dev`, ребейза не было** — `git merge-base
  origin/dev HEAD` совпадает с tip `origin/dev`; полный повторный разбор по
  §2.10 не требуется.

## Унаследовано из r2 (и, через него, из r1)

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

- Численный контракт §4.1–4.2: `GRID_N = 240`, `1e-4` threshold, формула
  deviation — сверены в r1 с реализованным `scripts/model-invariants.mjs`;
  дельта r3 этих разделов не трогала (кроме буквы примера в AC3, сверенной
  заново в этом раунде).
- Разграничение `canonicalizeLatticeCoordinate`/`canonicalizeScalar` и
  совместимость с nine-decimal contract #224 (§4.2) — не изменено.
- Allow-list полей (§5) — сверен в r1 с `modelCoordinates()`
  (`scripts/model-invariants.mjs:316-358`); не изменено.
- Write barrier §6 (frontend/backend, source/AST guard) — не изменено.
- AC1–AC6, AC7 (кроме i18n-подсекции и примера AC3), AC8–AC12 — текст не
  изменён дельтой r3; численные диапазоны, мутанты, perf-бюджет приняты в r1,
  продуктовые разделы §2–3 приняты в r2.
- Разделы «Риски» (§11) и «Откат» (§12) — приняты в r2 (M2), не изменены.
- Scope/не-скоуп (§8) — не изменено.
- §15 п.1–6 (принятые технические предположения) — приняты в r1/r2 как
  корректно технические; дельта r3 их не касалась.
- Трек/трейлеры (обычный трек, не `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 целиком и разделов 1–6, 8, 10–12 —
  дельта их не касалась текстуально (кроме буквы примера AC3, который сверен),
  приняты по наследству из r1/r2 (раздел выше), а не перепроверены заново
  построчно.
- Существующий i18n-блок `gs.optimize_*` за пределами ключей, релевантных
  M3/L3 (`gs.optimize_changes` и его непосредственные соседи) — не проверял
  построчно весь блок; выборка ограничена тем, что нужно для этих находок.
- Не связывался с владельцем: находка этого раунда (L3) сформулирована как
  Low с предложенным решением и не требует продуктового решения (персона,
  поверхность и объём изменений не затронуты — это вопрос точности отображения
  числа, технический по критерию §7.1).

## Итог

0 High, 0 Medium, 2 Low (L2 унаследована и не тронута; L3 — новая находка этого
раунда, оба не блокируют). Единственная Medium-находка r2 (M3) закрыта по
существу и подтверждена построчно, не на слово автора; попутно закрыта и
унаследованная Low-находка r1 (L1), хотя это не требовалось для перехода в
зелёный. Технический контракт, принятый в r1/r2, дельтой не нарушен.

Без High и без Medium — **зелёный вердикт**. Зелёный вердикт не расходует
бюджет §4 (#227): счётчик остаётся 2 из 4.