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

SPEC-REVIEW-398-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/398
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Материал: docs/specs/398-sysmodules-guard-scope.md, коммит 69dd09a7 (тело issue #398 без изменений)
• Заход: r1 · блокирующих циклов израсходовано до этого вердикта: 0 из 4
• Комментариев в issue к моменту ревью: 0 (первый заход, полный разбор)

Скоуп проверки

Issue #398 просит расширить гвард test/backend-test-hygiene.test.mjs, который сегодня ловит запись стаба интеграции в sys.modules только по строковому литералу и поэтому не видит tests_backend/pure_imports.py:31 (sys.modules[name] = module, запись через переменную). Изменение полностью внутри класса B (test/**, tests_backend/**), не трогает src/** и custom_components/**/*.py, User-Visible: no. ТЗ оформлено полным треком — docs/specs/398-sysmodules-guard-scope.md, файл на месте, ссылка issue↔ТЗ двусторонняя.

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

1. Прочитаны docs/SCOPE.md, AGENTS.md, PROCESS.md целиком.
2. Прочитано тело issue #398 и лента меток (gh api .../timeline) — задача ушла S1-new → S3-spec → S4-spec-review без публичного комментария аналитики (см. «Наблюдения», п.2).
3. Прочитан ТЗ docs/specs/398-sysmodules-guard-scope.md целиком.
4. Сверены с реальным кодом все цитаты из ТЗ: test/backend-test-hygiene.test.mjs (регэксп на строке 39), tests_backend/pure_imports.py (строка 31), tests_backend/conftest.py (условная подмена под if not HAS_HA:), tests_backend/test_junction_limits.py (безусловный вызов load_pure с каноническим именем custom_components.houseplan.junction_limits), tests_backend/test_validation.py (собственный _load_pure, пишет в sys.modules под префиксом hp_pure.*, вне описанного скоупа гварда).
5. Канонические документы подсистем (SUN.md, LIGHT.md, CANVAS.md, WALL-THICKNESS.md, UX-MODES.md, CONFIG-COMPATIBILITY.md, TOUCH-SUPPORT.md) — не применимы, задача не меняет видимое поведение продукта.
6. docs/USER-GUIDE.ru.md — не применим, User-Visible: no, персона — разработчик, а не пользователь продукта.
7. Гейты кода не гонялись: на этапе ревью ТЗ продуктового/тестового кода ещё нет, есть только новый markdown-файл — typecheck/test/build к нему неприменимы.

Находки

Medium (в скоупе задачи) — AC3 разрешает «путь 2», AC4 делает его невозможным

docs/specs/398-sysmodules-guard-scope.md:73-84 называет два одинаково допустимых исхода для load_pure:

1. снимать регистрацию за собой после exec_module (самоочистка);
2. объявить pure_imports.py вторым легальным исключением рядом с conftest.py, с тестом, фиксирующим список ровно из двух файлов.

Текст явно оставляет выбор реализации: «Предпочтителен (1)… — но завтра станет прецедентом» (строка 83) описывает предпочтение, не запрет второго пути, и AC3 (строки 117-119) прямо предусматривает путь 2: «единственное исключение (либо два файла, если выбран путь 2 — тогда список зафиксирован тестом и его рост краснеет)».

Но AC4 (строки 120-122) требует: «После прогона всего tests_backend/ в sys.modules нет ключей custom_components* сверх тех, что положил conftest». Это не совместимо с путём 2 по конструкции: если pure_imports.py объявлен вторым легальным исключением и не убирает за собой запись, то после прогона tests_backend/ в sys.modules останутся ключи custom_components.houseplan.junction_limits, custom_components.houseplan.wall_segment_model, custom_components.houseplan.coordinate_canonicalization — ровно то, что issue проверил исполнением как текущее наблюдаемое поведение — и они не «положены conftest», а положены вторым разрешённым файлом. AC4 в буквальной формулировке тогда красный при полностью корректной, явно допустимой реализации.

Почему это находка ТЗ, а не мелочь для код-ревью. DoR требует «пронумерованные проверяемые критерии приёмки» — набор AC должен быть одновременно выполним. Сейчас AC3 и AC4 совместно выполнимы только при выборе пути (1); реализатор, прочитавший ТЗ и выбравший путь (2) как более простой (сам документ признаёт его допустимым и даже кладёт под него отдельный тест-пункт «план автотестов», п.4), гарантированно упрётся в красный AC4 при исполняемой проверке — и потратит цикл код-ревью на то, что было видно уже на этапе ТЗ.

Как править (для автора, не предписание): либо явно исключить путь 2 из допустимых исходов (тогда «выбор — за реализацией» в контракте лишний — есть только путь 1), либо переформулировать AC4 так, чтобы он допускал оба исхода: «…нет ключей custom_components* сверх положенных conftest.py и, если выбран путь 2, кроме предъявленных явным списком исключений в pure_imports.py».

Воспроизведение (не гипотеза — уже исполнено issue-автором и переподтверждено при разборе): cd tests_backend && python3 -c "import conftest, test_junction_limits, sys; print([k for k in sys.modules if k.startswith('custom_components')])" печатает три ключа junction_limits/wall_segment_model/coordinate_canonicalization сверх пустышек custom_components/custom_components.houseplan, поставленных conftest.py. При выборе пути 2 эти три ключа остаются легальными по AC3, но проваливают AC4 буквально.

Наблюдения (не блокируют, не находки к ТЗ)

1. Контракт vs риски о способе разбора. Раздел «Проблема и контракт» говорит «Форма проверки меняется с регулярного выражения на разбор синтаксиса Python» (что совпадает с просьбой issue: «разбор AST вместо регулярки»), а раздел «Риски» тут же ограничивает: «Полноценный парсер тянуть не нужно и нельзя: достаточно узкого разбора строк… с fail-closed на всё непонятое». Формулировки не запрещают друг друга буквально (узкий разбор конкретно конструкции присваивания — тоже «разбор синтаксиса», не обязательно generic-грамматика), но провисает связка: если ключевая гарантия ТЗ — «отказ на всё недоказуемое» — реализована самим fail-closed по умолчанию, то выбор между вызовом Python ast через subprocess (0 новых зависимостей, репозиторий и так тянет Python 3.13) и узким текстовым разбором в Node не влияет на корректность настолько, насколько намекает контраст формулировок. Технический вопрос — не продуктовый, решается автором/ревьюером по существу, не эскалируется владельцу; не блокирую, но рекомендую снять формулировочное противоречие в следующей редакции.
2. Маршрутизация issue мимо инфраструктурного пути. Диапазон правки — исключительно класс B (test/**, tests_backend/**), ни одного файла класса A. По AGENTS.md («Infrastructure-only work runs outside this flow… The test… is mechanical: not a single class A file») и PROCESS.md §1 такая задача идёт «без ТЗ, ревью ТЗ, код-ревью и без прохода по статусам». Лента меток issue (gh api .../timeline) показывает, что все переходы S1-new → S3-spec → S4-spec-review проставил лично владелец (Matysh) без публичного комментария аналитики S2 — то есть это не сбой автоматики, а его собственное решение вести задачу полным треком. Это не дефект ТЗ и не встаёт в оценку документа: владелец вправе выбрать больше строгости для третьего по счёту случая одного класса дефектов. Фиксирую как наблюдение для гигиены процесса, не как находку ревью.

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

• Оба обязательных продуктовых раздела на месте: «Сценарий» называет персону верно (разработчик, добавляющий backend-тест — не пользователь продукта по docs/SCOPE.md, что для чисто инфраструктурной задачи ожидаемо) и поверхность (backend test harness, tests_backend/); «Что человек увидит до и после» отвечает без терминов реализации.
• Все обязательные разделы §7.1 присутствуют: проблема, скоуп/не-скоуп, контракт, UX (Н/П), модель данных и миграция (Н/П), i18n (Н/П), AC1…AC6 с указанием доказательства, план автотестов, риски, откат, release-артефакты.
• Цитаты кода в ТЗ (регэксп test/backend-test-hygiene.test.mjs:39, запись pure_imports.py:31) дословно совпадают с текущим содержимым файлов — не придуманы задним числом.
• AC1, AC2, AC5, AC6 однозначны и проверяемы: у каждого назван способ доказательства (тест-контракт по форме записи, backend-прогон, мутант). AC2 корректно перечисляет конкретные проверяемые формы (f-строка, конкатенация, setdefault/update) вместо общего «и другие похожие».
• Скоуп/не-скоуп разграничены точно: tests_backend/conftest.py (контракт #394) и правило про sys.path (#393) явно исключены из скоупа этой задачи — граница, названная в issue #394, не ослабляется этим ТЗ.
• docs/SCOPE.md не нарушается: задача не претендует ни на одну строку Core user jobs, это ожидаемо для чисто инфраструктурного изменения, и ТЗ не делает вид, что решает продуктовую задачу.
• Риски названы по существу (разбор Python из Node, снятие регистрации ломает относительные импорты, скрытая зависимость от повторного импорта) со смягчениями, а не общими словами.
• Откат дешёвый и конкретный: «два коммита назад, продуктовый код не затронут» — соответствует факту (диапазон правки — исключительно class B).
• Ни одна догадка о поведении не выдана за факт: утверждения о текущем дефекте («переживает свой тест», перечень трёх модулей) сопровождаются пометкой «проверено исполнением» и совпадают с тем, что показал сам issue.

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

• Не гонял npx tsc --noEmit / npm test / npm run build — на этапе ревью ТЗ нет ни строки продуктового или тестового кода, есть только новый docs/specs/*.md; эти гейты неприменимы к чтению документа.
• Не проверял технической реализуемости «разбора синтаксиса Python из Node» экспериментом (не писал прототип) — вопрос вынесен в наблюдение 1 как формулировочный, а не как проверенный тупик.
• Не проверял tests_backend/test_validation.py построчно за пределами найденного вызова _load_pure/sys.modules[f"hp_pure...] — этого было достаточно, чтобы подтвердить корректность утверждения ТЗ «при необходимости» про этот файл (префикс hp_pure вне заявленного скоупа гварда custom_components*); полный разбор файла оставляю код-ревью, если реализация всё же тронет этот файл.

Вердикт

Жёлтый. Единственная блокирующая находка (Medium, в скоупе задачи) — несовместимость AC3 и AC4 для явно допущенного документом «пути 2»: описанный как разрешённый исход не может пройти собственный исполняемый критерий приёмки. Правится в тексте ТЗ этим же автором, без выхода за рамки текущей задачи.