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

SPEC-REVIEW-291-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/291
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Заход: r1 · блокирующих циклов израсходовано 0 из 4
• Артефакт ТЗ: docs/specs/291-lattice-coordinate-write-barrier.md
• Ветка: issue/291-lattice-coordinate-barrier
• SHA на момент ревью: 8b99df6e (docs-only коммит, единственный впереди origin/dev)
• Трек: обычный (не small/trivial) — верно: миграция-подобная операция, frontend+backend boundary, сложность/риск 10/10 по собственной оценке автора

Скоуп ревью

Это первая редакция ТЗ. Разбор полный: раздела «Унаследовано из r0» не существует, дельта-обзор (§2.10 PROCESS.md) относится только к r2+.

Прочитано перед оценкой: docs/SCOPE.md, AGENTS.md, PROCESS.md (полностью, включая §2.4, §2.5, §2.9, §2.10, §7.1, §7.2), тело issue #291 и оба комментария, docs/adr/282-wall-geometry-representation.md, docs/CONFIG-COMPATIBILITY.md (§«Canonical geometry on write #224»), docs/WALL-THICKNESS.md (модель wallKey), docs/USER-GUIDE.ru.md §19 «Обслуживание планов», действующий код scripts/model-invariants.mjs (latticeProfile, latticeReport, флаг --lattice), test/model-invariants.test.mjs (существующие пины шума на real-plan-*.json), i18n-ключи gs.optimize_* в src/i18n/ru.json, и структура десяти сопоставимых ТЗ в docs/specs/ (090, 094, 150, 178, 179, 210, 211, 226, 252, 279) для проверки конвенции разделов «Риски»/«Откат».

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

Ревью документное (этап spec, кода еще нет — единственный коммит в ветке касается только docs/specs/291-*.md). Гейты кода (typecheck/test/build) на этом этапе неприменимы: класса A/B изменений в диффе нет.

Проверено по существу, а не на слух:

1. Численный контракт (§3.1–3.2 ТЗ) — свёрен с реализованным scripts/model-invariants.mjs: GRID_N = 240, NOISE_STEPS = 1e-4, формула latticeDeviation совпадают буква в букву с §3.1 ТЗ. Значит цифры в ТЗ не выдуманы, а взяты из уже принятого измерительного кода Stage 0 (#283).
2. Существующая девяти-decimal граница #224 — прочитана в docs/CONFIG-COMPATIBILITY.md, сверена с §3.2 ТЗ («canonicalizeScalar сохраняет nine-decimal contract»): согласуется, ТЗ не переизобретает эту часть.
3. Модель wallKey и её текущая частичная защита от #258 (max(pitch·10⁻⁶, 10⁻⁹) при вычислении key) — прочитана в docs/WALL-THICKNESS.md. ТЗ говорит о #258 в прошедшем времени («перебрасывали») — не противоречит: локальный фикс в wallKey не убирает источник шума как класс, ТЗ формулирует именно устранение класса.
4. Существующие тесты test/model-invariants.test.mjs:349-394 уже пинят noise >= 100 на обеих real-plan-*.json и checkWallKeys(...).length === 0 на них же — совпадает с AC3/AC6 ТЗ буквально, эти AC не гадание, а описание уже наблюдаемого свойства существующих фикстур.
5. --lattice флаг и JSON-вывод (profile.noise, profile.byKind, …) в scripts/model-invariants.mjs уже существуют — AC3 не требует придумывать новый CLI с нуля, инструмент есть.
6. i18n: сверено текущее содержимое gs.optimize_changes в src/i18n/ru.json (строка 817) с требованием AC7 «per-space breakdown {spaceId, canonicalized, far}» — текущий ключ — это один общий счётчик («устранён шум координат: {p}»), не таблица по пространствам. Значит AC7 действительно вводит новый видимый текст, а не просто меняет число за существующей строкой.
7. Конвенция остальных ТЗ: grep по docs/specs/*.md на «Риски»/«Откат»/ «Rollback» — во всех проверяемых десяти документах (090, 094, 150, 178, 179, 210, 211, 226, 252, 279) есть отдельный раздел. В 291-*.md — нет ни одного упоминания risk-таблицы или отдельного «Откат».
8. Термин «future layout owner» (§4, §10 ТЗ) — не изобретён на месте: тот же термин («Future owner») использован как строка risk-таблицы в docs/specs/252-optimize-orphan-layout-report.md:327. Признано корректным переносом термина, не догадкой.

Полные автотесты/смоки/perf-бенчмарки не прогонялись и не должны: на этапе spec-review нет кода для их прогона (диф — один файл docs/specs/291-*.md).

Находки

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

M1. Отсутствуют обе обязательные продуктовые секции §7.1, и новый видимый UI предъявлен как решённый факт, а не помечен предположением.

• Файл: docs/specs/291-lattice-coordinate-write-barrier.md, разделы 1 и 6 (и весь документ — ни разу не упомянуты персона, поверхность или момент встречи).
• Что не так: §7.1 PROCESS.md требует первыми двумя разделами: «какая персона (docs/SCOPE.md), на какой поверхности, в какой момент это встретит» и «что человек увидит, одной фразой, без терминов реализации», и явно объясняет, почему это первые разделы: «ТЗ, которое не может ответить на эти два вопроса, описывает работу, а не изменение продукта». Раздел 1 этого ТЗ («Сценарий и измеренная причина») — целиком технический: процент шума, формула, причина. Ни слова про Home admin, Plan editor или момент нажатия «Оптимизировать планы». Это не формальность: изменение реально видимо. gs.optimize_changes (src/i18n/ru.json:817) сегодня — один общий счётчик «устранён шум координат: {p}». AC7 требует per-space breakdown {spaceId, canonicalized, far} и отдельную строку для layout без пространства — это новый текст в диалоге Optimize, который увидит Home admin. Ни один owner-decision из #284 (процитированных в самом issue) не говорит о степени детализации отчёта — только о том, что far-координаты не трогаются и перечисляются. Решение «показать разбивку по пространствам, а не только total» — собственное решение автора ТЗ, поданное как AC, а не как предположение, которое ревьюер может оспорить (§7.1: «Догадка, записанная как факт, — худший вид дефекта»).
• Сценарий, где это ломается: реализация делает per-space таблицу; owner, открыв бету, ожидал (по аналогии с текущим единственным counter'ом) простой общий счётчик и считает новую таблицу лишней/шумной UI-детализацией admin-only диалога — расхождение обнаруживается после код-ревью, а не на этапе ТЗ, где чинить дешевле.
• Что сделать: добавить два продуктовых раздела по шаблону §7.1 (персона — Home admin; поверхность — Plan editor → «Общие настройки → Оптимизировать планы»; момент — открытие предпросмотра Optimize; одна фраза «что видит до/после» — например: «раньше отчёт показывал один общий счётчик очищенного шума, теперь — разбивку по пространствам»); одним предложением явно связать степень детализации отчёта с §12 «принято предположительно, поменять свободно» либо получить продуктовое подтверждение у владельца одним вопросом с default-вариантом (§7.1 формат вопроса).

M2. Нет разделов «Риски» и «Откат», обязательных по DoR (§2.5) и присутствующих в каждом сопоставимом ТЗ проекта.

• Файл: docs/specs/291-lattice-coordinate-write-barrier.md — весь документ.
• Что не так: DoR-чеклист §2.5 PROCESS.md требует перед переводом в «Готово к разработке»: «влияние на производительность... названо» (выполнено, §AC11) — но также «риски перечислены» и «откат: как выключить или вернуть назад» отдельным пунктом. В этом ТЗ ни одного из двух нет как структурированного раздела. Сравнение: docs/specs/252-optimize-orphan-layout-report.md §12 содержит таблицу «Риск | Мера» и явную строку «Rollback — revert implementation-коммита. Persisted format не меняется...»; docs/specs/279-near-orthogonal-junction.md §5 — «Главный риск... его закрывают...»; docs/specs/226-entity-parent-dedup.md §18 — «Откат и риски» как отдельный заголовок. Во всех 10 проверенных ТЗ раздел есть; в 291-м — нет.
• Почему это не формальность именно здесь: AC5 требует, чтобы barrier был непроходим — ни один frontend outbound writer и ни один backend Store.async_save config/layout путь не может обойти его. Это означает, что ошибка в самой boundary-функции (например, из-за неверной granularity округления или ложного срабатывания source/AST guard'а на легитимном новом writer'е) блокирует все сохранения плана сразу на обоих стеках. Собственная оценка риска в ТЗ и issue — 10/10. Для изменения такого класса не сказано ни слова о том, как отличить misfire барьера от обычного дефекта в проде, и как откатиться (просто ревертнуть коммит? отключить Labs-флагом? — не решено ни так, ни так).
• Что сделать: добавить раздел «Риски и откат»: минимум — таблица «риск | мера» (ложный noise-match у легитимной near-node authored geometry; guard блокирует легитимный новый writer; boundary даёт разные canonical bits на fe/be при расхождении версий) и явное «откат — revert implementation-коммита, PLAN_MODEL_VERSION не повышается, обратная миграция не нужна» (или иной вариант, если авторское решение отличается).

Low (замечание, не блокирует; фиксируется или снимается с записью)

L1. AC3 иллюстрирует вывод CLI текстом, который не совпадает с реальным форматом инструмента.

• Файл: docs/specs/291-lattice-coordinate-write-barrier.md, AC3 (раздел 8).
• ТЗ приводит:

  npm run invariants -- --config <candidate> --lattice
  noise: 0 (0.00%)
  

  Фактический вывод latticeReport() (scripts/model-invariants.mjs:520-541, уже реализован) — русский текст " шум у узла 0 (0.00%)", а не noise: 0 (0.00%). С флагом --json было бы profile.noise === 0. Разночтение косметическое и не меняет проверяемость критерия (число ноль — то же самое), но при буквальном сравнении вывода на код-ревью может создать ложное сомнение «инструмент не совпадает с ТЗ».
• Решение ревьюера: не блокирует; правится либо заменой примера на profile.noise === 0 (JSON-режим), либо точной русской строкой, при следующей правке документа по другому замечанию. Отдельного возврата ради этого не требуется.

L2. Issue #291 называет себя «Стадия 1 из ADR #282», хотя реальная Stage 1 ADR #282 — это «stored identity» (stable wall ids), которую сам этот же ТЗ явно выносит в «Не входит».

• Это находка по телу issue, не по файлу ТЗ (сам файл docs/specs/291-*.md термин «Stage 1» не использует и корректно перечисляет integer storage schema, stable wall ids в §7 «Не входит»). Расхождение — только в первой фразе issue-body: «Выделено из исследования #284 ... Стадия 1 из ADR #282, без смены схемы хранения». По ADR (docs/adr/282-wall-geometry-representation.md, раздел «Stage 1 — stored identity»), Stage 1 — это именно stable id для стен, а не lattice-canonicalization; последнее ближе к развитию Stage 0 (измерение → устранение измеренного явления), но не совпадает ни с одной явно пронумерованной стадией ADR.
• Почему стоит внимания: будущий читатель, ищущий прогресс по ADR #282 в issue-трекере, увидит «Stage 1 сделан» по номеру #291 и решит, что stable wall ids уже есть — хотя это не так и явно не входит в скоуп.
• Решение ревьюера: не блокирует ТЗ (файл спеки не содержит ошибки), но стоит поправить формулировку в issue (комментарием или правкой шапки) — например, «расширение Stage 0 ADR #282» вместо «Стадия 1». Оставляю как Low-замечание автору issue, не как находку к самому документу ТЗ.

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

• Численные константы и формулы (GRID_N=240, 1e-4 порог, Math.round) совпадают с уже реализованным и слитым кодом Stage 0 — не выдумка.
• Разграничение canonicalizeLatticeCoordinate / canonicalizeScalar (§3.2) корректно не пересекается с существующим #224 nine-decimal contract и не вводит рекурсивную канонизацию произвольных чисел — прямое соответствие требованию docs/CONFIG-COMPATIBILITY.md «No recursive "round every number" migration is allowed».
• Allow-list полей (§4) — по каждому пункту сверено с реально существующими полями модели (room.poly, walls[].a/b, partitions[].a/b, wall_columns[].center, open_spans[].a/b, layout x/y) — совпадает с полями, которые уже обходит modelCoordinates() в scripts/model-invariants.mjs:316-358. Все объекты allow-list реальны, не придуманы.
• AC1/AC2/AC10 (идемпотентность, shared fixture parity, мутанты) — проверяемые, с точным диапазоном (4801 узлов, k=-2400..2400) и конкретным списком обязательных мутантов; никаких «проверим на глаз».
• AC5 (source/AST guard, непроходимый barrier) — не спекуляция: в репозитории уже есть прецедент такого класса гейта (scripts/backend-test-guard.mjs), подход реализуем.
• AC6 — сформулирован как уже наблюдаемое свойство существующих фикстур (test/model-invariants.test.mjs:349-394 уже пинит noise >= 100 и checkWallKeys === 0 на raw real-plan файлах) — ТЗ не требует нового инварианта, а фиксирует то, что уже проверяется, плюс явное «raw byte/hash-equivalent после теста».
• §12 «Принятые технические предположения» — правильно оформлен как явный блок допущений (место, где агенты решают несмотрящиеся пользователю детали сами), и по содержанию все 5 пунктов действительно технические (Store-механика, версия схемы, диагональные координаты, touch-контракт), а не подмена продуктового решения.
• Скоуп/не-скоуп (§7) корректно исключает дорогую часть ADR (integer schema, stable ids, planar graph) и визуально несвязанные P1-баги (#288–290, #278 union algorithm) — совпадает с собственным анализом owner в issue-теле («барьер не лечит то, что болит сейчас»).
• Trailers/track: tech-debt/P1, обычный трек — корректно, задача не подходит под small (миграция-подобная операция, две поверхности — frontend+backend, широкая точка записи).

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

• Собственно код: на этом этапе (S4-spec-review) продуктового кода в ветке нет — единственный коммит 8b99df6e касается только docs/specs/291-lattice-coordinate-write-barrier.md. Гейты typecheck, npm test, npm run build, check-docs.mjs, invariants, смоки, perf-бенчмарк — неприменимы к этому диффу и не прогонялись; они станут предметом код-ревью после реализации.
  • Причина, а не пропуск: диапазон git diff origin/dev...HEAD --stat — ровно один файл документации, класс C, без class A/B изменений.
• Не проверял, действительно ли перечень «Ожидаемые файлы» (§10 ТЗ) полон — список файлов на этапе спеки индикативен, а не контракт; это будет видно на код-ревью по фактическому диффу.
• Не связывался с владельцем и не задавал продуктовых вопросов напрямую: вопрос о степени детализации Optimize-отчёта (M1) сформулирован как находка с предложенным решением по умолчанию (следовать текущей однострочной конвенции gs.optimize_changes, если автор явно не считает таблицу по пространствам необходимой) — снимается автором в следующей редакции ТЗ, а не эскалацией к владельцу, если умещается в пятиминутное предположение с default-вариантом; при разногласии автор/ревьюер решают вопрос вердиктом следующего цикла (§7.1), не владельцем.

Итог

0 High, 2 Medium (в скоупе — обе чинятся в этом же issue текстовыми правками ТЗ, не переработкой технического контракта), 1 Low (не блокирует, правится заодно), плюс отдельное Low-замечание к формулировке issue-body (не к файлу ТЗ). Технический контракт (AC1–AC12, численные константы, allow-list, барьер, мутанты) хорошо обоснован и явно проверен по существующему коду — без High. Без High это жёлтый вердикт: документ возвращается автору на правку двух отсутствующих разделов, повторный заход re1 расходует один цикл из лимита 4.