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

SPEC-REVIEW-176-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/176
• ТЗ под ревью: тело issue #176 (лёгкий трек, файл docs/specs/ не создаётся — метка small подтверждена аналитиком и не оспорена владельцем)
• Роль: ревьюер ТЗ (не автор), этап S4-spec-review
• Трек: лёгкий (small), лимит циклов ревью ТЗ — 2 (§4 PROCESS.md)
• Цикл: r1/2

Скоуп ревью

ТЗ #176 удаляет мёртвый внутренний tool-state 'partition' из src/houseplan-card.ts (значение MarkupTool, MARKUP_TOOLS, метод _partitionClick, ~15 условных веток this._tool === 'partition') и три осиротевших i18n-ключа, оставленных после #173 (замена one-shot Partition единым Walls-инструментом). Persisted-модель независимых стен (space.partitions, PartitionCfg, kind: 'partition' у selection/opening host, весь UI работы с уже созданными стенами) не меняется. User-Visible: no; changelog не требуется.

Находка изначально заведена самим ревьюером кода на #173 (docs/reviews/CODE-REVIEW-173-r1.md, Medium-1) и подтверждена владельцем как issue — проверка «issue создан явным решением владельца» выполнена (первая запись в issue — команда владельца на вход в S2-analysis).

Не в скоупе ревью: продуктовый код не написан (issue в S4-spec-review; ветки issue/176-* в репозитории нет — проверено git branch -a), поэтому реализация, тесты и гейты — предмет будущего код-ревью (PROCESS.md §2.7).

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком (актуальная редакция, включая §2.4/§2.5/§5/§7.1/§8) и тело issue #176 со всеми комментариями (аналитика владельца, передача на ревью, отметка о сбое автоматического прогона).
2. Построчно сверены технические утверждения ТЗ с текущим dev (src/houseplan-card.ts, grep -in partition, полный список ~140 вхождений):
   • type MarkupTool = ... | 'partition' | ... — строка 516, подтверждено;
   • 'partition' в MARKUP_TOOLS — строка 547, подтверждено;
   • private _partitionClick(...) — строка 7143, реализует «два клика → одна перегородка» через _recordGeometry('history.partition_add', …); подтверждено;
   • диспетчер клика: if (this._tool === 'partition') { this._partitionClick(...); } — строка 6834-6835, единственная точка вызова метода — подтверждено, что _partitionClick не достижим никаким иным путём;
   • ветки this._tool === 'draw' || this._tool === 'partition' (лимиты, snap, hints, Undo/Escape, рендер превью) — найдены на строках 2241, 5362, 5429, 5450, 5487, 6364, 6601, 17202, 17923, 18039, 18041, 18091, 9597; одиночные this._tool === 'partition' — строки 2270, 2323, 6834, 9559, 9598, 11908 — количество и характер веток соответствуют заявленным в issue «порядка 15».
3. Проверена причина недостижимости this._tool === 'partition' — ключевое техническое утверждение issue, а не декларация:
   • normalizeMarkupTool (houseplan-card.ts:551-562) — единственное место, присваивающее this._tool из внешнего/сохранённого значения (this._tool = normalizeMarkupTool(vp.tool) при восстановлении warm viewport, строка 2656);
   • normalizeMarkupTool безусловно вызывает value = normalizeUnifiedWallTool(value) до проверки MARKUP_TOOLS.has(...) (строка 555);
   • normalizeUnifiedWallTool (src/wall-face-graph.ts:53-55): return value === 'partition' ? 'draw' : value; — литерал 'partition' маппится в 'draw' безусловно.
   • Других обработчиков, присваивающих this._tool = 'partition' из пользовательского ввода, не найдено (единственное текстовое совпадение — сравнения ===, не присваивания). Вывод issue «код недостижим, а не редко используем» подтверждён чтением, не декларацией автора.
4. Проверено, что тип MarkupTool и MARKUP_TOOLS не используются больше нигде в src/ (grep -rn "MarkupTool\|MARKUP_TOOLS" src/) — оба контейнера частные для houseplan-card.ts; удаление литерала не пробивает границу модуля.
5. Проверена граница «мёртвый код инструмента» vs «живая persisted-модель» построчно: kind: 'partition' в типах selection/drag/dialog (строки 1225, 1228, 1234, 1243, 7196, 7257, 7283, 7374, 7401, 7415, 7434, 7462, 7505, 11485, 12005, 17840, 17863, 17881, 17981), space.partitions/PartitionCfg, _partitionDeleteDialog/_confirmPartitionDelete, _partitionOpeningCuts/resolvePartitionOpeningCompat и весь модуль partition-openings.ts — ни один из них не завязан на this._tool, все работают с уже существующими объектами независимо от активного инструмента. Граница, которую ТЗ объявляет неприкосновенной (контракт п.3), реально проходит там, где заявлено.
6. Проверены i18n-ключи (src/i18n/en.json, src/i18n/ru.json): title.markup_partition, markup.hint_partition, physical.partition_size_title — все три существуют в обоих locale и (grep -rn по src/) используются только через this._tool === 'partition' (строки 9559, 9598) либо нигде не используются вне собственного определения (title.markup_partition) — подтверждено, что это ровно осиротевший набор, ни ключом больше, ни меньше. Ключи markup.partition, physical.partition_properties, history.partition_add, opening.host_partition, confirm.delete_partition_openings_*, opening.rebind_partition — заняты persisted-объектом и диалогами, ТЗ верно не включает их в список удаления.
7. Проверен test/golden-matrix.test.mjs:72: assert.equal(['draw', 'partition'].includes(scenario.planSnap.tool), true, …) — сейчас допускает оба значения. Проверены реальные сценарии demo/golden/matrix.mjs (planSnap: {...}, строки 73-80) — оба существующих planSnap-сценария уже используют tool: 'draw'; ни один golden-сценарий не задаёт 'partition'. Сужение assert до одного 'draw' не меняет ни одного изображения — заявление ТЗ «визуальные эталоны не меняются» подтверждено чтением фикстур, а не предположением.
8. Проверены названные в плане автотестов файлы: demo/smoke_free_walls.mjs (существует; строки 57-60, 177-181 напрямую ставят c._tool = 'partition' и зовут c._partitionClick(...) в обход публичного dispatch — ровно то приватное использование, которое ТЗ обязуется перевести на публичный flow), demo/smoke_plan_snap_overlay.mjs (существует; строка 185 card._tool = 'partition' перед _markupClick, что действительно проходит через диспетчер строки 6834-6835), и demo/smoke_unified_wall_tool.mjs (существует; не использует приватный tool-state — уже написан против публичного _tool = 'draw' + _keepClosedAsPartitions(), строка 128 — служит рабочим образцом того, как должны выглядеть переписанные сценарии).
9. Проверено существование паттерна «source-contract test», на который ссылается AC1 как способ доказательства: test/isometric-contract.test.mjs, open-passage-contract.test.mjs, optional-space-model-contract.test.mjs, release-contract.test.mjs и другие — это существующая практика репозитория (в т.ч. для внутренних инвариантов), а не изобретённый под это ТЗ механизм.
10. Проверено docs/USER-GUIDE.ru.md:343 — таблица инструментов Плана уже фиксирует «отдельного инструмента «Перегородка» нет» на пользовательском уровне; терминология ТЗ («persisted-объект остаётся «Перегородка», внутренний tool-token удаляется») не расходится и не переизобретает то, что задокументировано.
11. Проверено docs/TESTING.md:486-497 («Room markup editor») и docs/STATUS.md (grep -in partition — без совпадений) — ни один текущий пункт не описывает приватный _tool='partition'; изменение кода не требует правки формулировок этих файлов по существу, перечисление их в «Затрагиваемые поверхности» — корректная страховка на случай появления новых заметок в реализации, не декларация обязательной правки.
12. Проверено, что issue #176 не оспорил small: сложность/риск 3/10, одна поверхность (src/houseplan-card.ts + производные тесты/i18n), нет миграции, нового UX-контракта, влияния на perf/touch — все критерии §5 выполнены одновременно; trivial корректно не применён (тип tech-debt, не bug).
13. Проверено отсутствие ветки issue/176-* (git branch -a | grep 176 — пусто) и отсутствие более раннего docs/reviews/SPEC-REVIEW-176-*.md (ls docs/reviews | grep 176 — пусто) — это первый цикл, r1/2.

Гейты (typecheck/test/build) не прогонялись — на этапе ревью ТЗ продуктового кода нет; прогон гейтов не относится к этому этапу (PROCESS.md §2.7/§8).

Обязательные разделы (§7.1 PROCESS.md, лёгкий трек — тело issue)

Раздел	Есть	Комментарий
Сценарий (персона/поверхность/момент)	N/A, обоснованно	задача не создаёт наблюдаемого изменения продукта (User-Visible: no, контракт п.6); §7.1 формулирует эти два раздела как продуктовые именно для отделения «работы» от «изменения продукта» — здесь по существу нет стороны-наблюдателя, это подтверждено чтением кода (см. п.3), а не заявлено голословно
Что человек увидит до/после	N/A, обоснованно	то же: «до» и «после» с точки зрения пользователя идентичны — задача про внутреннюю модель, не про интерфейс
Проблема	✅	подтверждена чтением houseplan-card.ts и wall-face-graph.ts (см. «Как проверялось» п.2-3), а не декларацией автора
Контракт (скоуп/не-скоуп внутри пунктов 1-3)	✅	граница мёртвый-код/persisted-модель проверена построчно (п.5) и проходит ровно там, где заявлено
Модель данных и миграция	✅	«persisted-модель не меняется» — подтверждено (п.5); миграции нет, потому что нет изменения хранимой схемы
i18n	✅	ровно три ключа, ни больше ни меньше — подтверждено построчной сверкой (п.6)
AC1…ACn с доказательством	✅	3 штуки, у каждого назван реалистичный и проверяемый способ доказательства (typecheck+source-contract test / unit+targeted smokes / locale unit+build diff+golden:verify)
План автотестов	✅	ссылается на реально существующие файлы (п.7-8), включая точную строку смока, которая сейчас использует приватный API и должна быть переписана
Риски	частично	явного раздела «Риски» нет, но риск («будущий контрибьютор вернёт мёртвую ветку по аналогии») назван в теле issue и закрывается самим фактом удаления кода — для лёгкого трека §5 отдельного раздела «Риски» не требует (шаблон: проблема · контракт · AC · откат)
Откат	✅	один revert, без миграции данных — обоснованно, так как persisted-схема не тронута
Release-артефакты	✅	явно и корректно: User-Visible: no → changelog не требуется; три bundle snapshot синхронизируются по стандартному процессу сборки

Раздел «Принятые предположения» присутствует и корректно отделяет то, что уже прочно установлено чтением кода (partition в persisted-типах — не мёртвый код; legacy-нормализатор остаётся намеренно), от того, что не является продуктовым вопросом вовсе (нет UI, нет changelog) — ни одно утверждение раздела не выдаёт техническую догадку за факт.

Находки

Отсутствуют. Ниже — то, что специально проверено на предмет типичных для этого класса дефектов (пропущенный call site, недосказанная граница скоупа, домысленное поведение) и не подтвердилось.

• Домыслы вместо решения не найдены. Единственное потенциально спорное техническое утверждение — «код недостижим, а не редко используем» — не принято на веру, а прослежено до кода нормализации (normalizeUnifiedWallTool, «Как проверялось» п.3): это не догадка автора, а проверяемый факт.
• Скоуп i18n не занижен и не завышен. Отдельно проверено, что среди трёх удаляемых ключей есть physical.partition_size_title, которого не было в исходной находке код-ревью #173 (там названы только title.markup_partition и markup.hint_partition) — авторская аналитика нашла его самостоятельно и подтвердила чтением (this._tool === 'partition' ? 'physical.partition_size_title', строка 9559); ключ действительно используется только приватным tool-state и нигде в persisted-UI.
• Golden-эталоны не сузятся ошибочно. Проверено, что сужение test/golden-matrix.test.mjs:72 до одного 'draw' не затрагивает ни один реальный сценарий demo/golden/matrix.mjs — оба planSnap-сценария уже на 'draw'.

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

• Соответствие docs/SCOPE.md: задача не создаёт нового Core user job и не расширяет ни один из них напрямую — это ожидаемо для tech-debt. Косвенная связь с J4/J6 (поддержание единственного тестируемого пути Plan editor, без альтернативного нетестируемого API) не притянута: старый _partitionClick действительно обходит crash-safe/finish/limit-контракт, установленный #173 для «unified Walls chain» (J6 — «keep the plan true as the home evolves»).
• Легитимность лёгкого трека: сложность 3/10, одна поверхность, нет миграции/нового UX-контракта/влияния на perf или touch — критерии §5 выполнены все одновременно; аналитик верно не предложил trivial (тип tech-debt, критерий §5.1 требует bug).
• Продуктовых вопросов действительно нет. Единственный класс вопросов, который вообще уместен на этом этапе — объём видимого изменения — здесь вырожден: видимого изменения нет вовсе (User-Visible: no), и это не недосмотр автора, а прямое следствие того, что удаляется недостижимый код. Технические решения (source-contract test, перевод смоков на публичный flow) корректно оставлены на усмотрение разработчика записью в разделе «Принятые предположения», как и предписывает §7.1 PROCESS.md.
• Граница мёртвый-код / persisted-модель проведена точно и без пропусков — построчная проверка (см. «Как проверялось» п.5) не нашла ни одного места, где persisted kind: 'partition' зависел бы от this._tool, и ни одного места, где this._tool === 'partition' относился бы к чему-то, кроме активного инструмента разметки.
• Ссылки на существующие файлы не выдуманы — все три названных в плане автотестов смока (smoke_free_walls.mjs, smoke_plan_snap_overlay.mjs, smoke_unified_wall_tool.mjs) существуют, и первые два действительно используют приватный _tool = 'partition'/_partitionClick способом, который ТЗ обязуется устранить — заявление в AC2 не голословно.
• Обратная совместимость не сужается. Legacy warm-viewport токен 'partition' продолжает нормализоваться в 'draw' уже существующим кодом (normalizeUnifiedWallTool), который ТЗ явно не трогает и защищает unit-тестом (контракт п.2) — соответствует docs/CONFIG-COMPATIBILITY.md в части «не сужать уже принятый вход», хотя формально warm viewport — page-memory, а не persisted storage schema, которую документ описывает напрямую.
• Откат тривиален и корректен — один revert без миграции данных, поскольку persisted-схема не меняется ни в одной части.

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

• Реализацию — её нет: issue в S4-spec-review, ветки issue/176-* не существует (git branch -a пуст по этому номеру) — проверено.
• Гейты typecheck/test/build/browser smoke/golden — не относятся к этапу ревью ТЗ; предмет будущего код-ревью (PROCESS.md §2.7/§8).
• python -m pytest tests_backend — backend (custom_components/**/*.py) не упомянут ни в issue, ни в затронутых файлах, и не содержит partition как tool-state (только независимая от frontend-инструмента persisted-схема, если вообще есть — не проверялась специально, так как ТЗ прямо заявляет «Backend … не меняется», а весь код-путь — frontend-only MarkupTool).
• Точный будущий текст source-contract теста и точный способ переписать smoke_free_walls.mjs/smoke_plan_snap_overlay.mjs на публичный draw/finish flow — это техническое решение реализации (§7.1: «всё, чего пользователь не наблюдает, агенты решают сами»), а не предмет ревью ТЗ.
• Реальный визуальный результат npm run golden:verify — CSS/геометрия не меняются по заявлению ТЗ и по чтению фикстур (см. «Как проверялось» п.7), но фактический прогон гейта относится к реализации/пре-релизу, не к этому этапу.
• Точность числовых оценок аналитики (ценность 1/10, сложность 3/10, P3) по существу — поле владельца (PROCESS.md §2.2), не предмет ревью ТЗ.

Вердикт

Зелёный. High: 0, Medium: 0, Low: 0. ТЗ описывает точно очерченную, доказанную чтением кода (не декларированную) границу между мёртвым tool-state и живой persisted-моделью независимых стен; все технические утверждения (недостижимость this._tool === 'partition', точный список осиротевших i18n-ключей, безопасность сужения golden-matrix assert) проверены построчно и подтвердились. Продуктовых вопросов нет обоснованно — задача не создаёt наблюдаемого изменения, а не умалчивает о нём. AC однозначны и снабжены доказуемыми способами проверки.

Вердикт: зелёный · цикл r1/2 · High: 0 · Medium: 0 → нет · Документ: docs/reviews/SPEC-REVIEW-176-r1.md