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

# SPEC-REVIEW-398-r2

- Issue: https://github.com/Matysh/houseplan-card/issues/398
- Этап: ТЗ на ревью (PROCESS.md §2.4)
- Материал: `docs/specs/398-sysmodules-guard-scope.md`, коммит `480d202f`
  («#398 spec revision 2 per SPEC-REVIEW-398-r1»)
- Заход: r2 · блокирующих циклов израсходовано до этого вердикта: 1 из 4
- Предыдущий вердикт: `docs/reviews/SPEC-REVIEW-398-r1.md`, жёлтый, на коммите
  `69dd09a7` (ревизия 1 ТЗ). SHA в вердикте r1 не назван явно текстом — найден
  сопоставлением: `git show a4b686a7 --stat` (коммит с самим документом r1)
  датирован позже `69dd09a7` и раньше `480d202f`, а «Материал» в r1 называет
  файл без ревизии — правки после которой ещё не было, то есть r1 читал ровно
  содержимое `69dd09a7`.

## Разбор по дельте (PROCESS.md §2.9, #214)

Дельта — `git diff 69dd09a7..480d202f -- docs/specs/398-sysmodules-guard-scope.md`
(28 добавленных / 22 удалённых строк). Правка не переезжает на другую подсистему,
не меняет продуктовый контракт (задача остаётся `User-Visible: no`, класс B) и по
объёму меньше исходной задачи — полный повторный разбор не требуется. Проверены
только: (а) закрытие находки r1 по цитате нового текста и (б) те AC, чьё
доказательство дельта задевает — это AC3, AC4 и, как показано ниже, обнаружилось,
что дельта задевает ещё и совместимость AC1/AC2 с AC3 через код `pure_imports.py`,
явно оставленный «в скоупе» правки. Разделы, которых дельта не касалась (Сценарий,
UX, i18n, AC5, AC6, откат, release-артефакты), унаследованы из r1 — см. раздел
ниже.

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

| Находка r1 | Чем закрыта | Где это видно |
|---|---|---|
| Medium: AC3 явно допускал «путь 2» (объявить `pure_imports.py` вторым легальным исключением), а AC4 требовал отсутствия лишних ключей после прогона — путь 2 конструктивно не мог пройти AC4 | «Путь 2» полностью удалён из текста; раздел «Что делать с `load_pure`» переписан как «один путь: снимать за собой», с явной ссылкой на находку ревьюера | `docs/specs/398-sysmodules-guard-scope.md:71-87` («Ревизия 1 допускала второй исход… вариант снят»); AC3 (строки 120-121) больше не содержит альтернативы «либо два файла»; план автотестов, п.4 (строка 139) убрал условность «если выбран путь 2» |

Текстовое закрытие корректно и однозначно: альтернативный путь убран, а не
спрятан («не рекомендуется», «как правило» и т.п. отсутствуют — использована
формулировка «вариант снят»).

## Новая находка r2

### Medium (в скоупе задачи) — устранение «пути 2» открывает новый конфликт: AC1/AC2 не совместимы с AC3 для `tests_backend/pure_imports.py`, оставленного «в скоупе»

Ревизия 2 фиксирует ровно одно исключение из-под гварда —
`tests_backend/conftest.py` (строка 87: «Единственное исключение остаётся одно»;
AC3, строки 120-121: «остаётся единственным исключением»; план автотестов,
п.4, строка 139: «попытка добавить **второй** файл в список исключений →
красный» — то есть механизм исключения зафиксирован именно как список файлов
мощности 1, а не как распознавание безопасного паттерна «запись + восстановление»).

Одновременно раздел «Скоуп/не-скоуп» (строка 91) оставляет
`tests_backend/pure_imports.py` в скоупе как файл, который правка изменяет (а не
удаляет), и требует (через «Что делать с `load_pure`», строки 78-87, и AC5,
строки 125-127), чтобы после правки `load_pure` продолжал резолвить
относительные импорты для существующих вызовов — в частности,
`tests_backend/test_junction_limits.py:28-30`, который передаёт канонический
литерал `"custom_components.houseplan.junction_limits"` в качестве аргумента:

```python
sys.modules[name] = module  # tests_backend/pure_imports.py:31
```

Это ровно образец, который AC1 называет напрямую: «Файл, записывающий
`sys.modules[<переменная>] = …`, где переменная может содержать имя пакета
интеграции, отклоняется гвардом» (строки 112-114). Значение `name` внутри
`pure_imports.py` — параметр функции, из текста самого файла статически не
определимо, что оно не начинается с `custom_components`; собственный
fail-closed принцип ТЗ («значение ключа может быть неизвестно статически —
тогда гвард обязан отказывать», строки 67-69) требует отклонить именно этот
файл. Проверка в `test/backend-test-hygiene.test.mjs` статическая, идёт
файл-за-файлом без исполнения (комментарий в коде, строки 11-14: «Проверка
статическая — по исходникам, без запуска») — она не может увидеть, что
`load_pure` восстанавливает `sys.modules` после `exec_module`; восстановление
— рантайм-факт, а гвард текст не исполняет.

Итог: `pure_imports.py`, оставленный в скоупе и обязанный по AC5 продолжать
работать для `test_junction_limits.py`, **структурно не может** одновременно (а)
не быть исключением (по AC3, ровно один файл-исключение — `conftest.py`) и (б)
избежать отклонения по AC1 (поскольку пишет в `sys.modules` по переменной,
которая в вызовах из скоупа действительно принимает значения вида
`custom_components.houseplan.*`). Здесь нет обходного варианта на уровне формы
записи: регистрация модуля в `sys.modules` под точным каноническим именем —
обязательное условие резолва относительных импортов в Python
(`importlib.util.module_from_spec` + `exec_module`), других способов сделать
`from .wall_segment_model import …` рабочим для этого файла ТЗ не описывает и
предложить не может без изменения самого механизма загрузки.

**Почему это находка ТЗ, а не код-ревью.** Это тот же класс дефекта, что и
закрытая находка r1: набор AC совместно невыполним для сценария, который сам
документ называет обязательным (пункт «в скоупе» + AC5). Разработчик,
реализующий ТЗ буквально — упрощённая по AC1/AC2 регулярка/AST-проверка плюс
очистка `sys.modules` в `load_pure` — получит перманентно красный
`test/backend-test-hygiene.test.mjs` на собственном `pure_imports.py`, то есть
красный `npm test` сразу после реализации, и упрётся в противоречие, которое
было видно уже на этапе чтения ТЗ.

**Как править (для автора, не предписание).** Разрешить `pure_imports.py`
вторым явным исключением в AC3 (список из двух конкретных, поимённо
зафиксированных файлов — `conftest.py` и `pure_imports.py`, рост списка сверх
этого по-прежнему красный) — это НЕ реинкарнация снятого «пути 2»: там
исключение освобождало от очистки и потому ломало AC4; здесь очистка (уже
специфицированная в ревизии 2 как «снимать всё, что появилось под префиксом
`custom_components` за время `exec_module`») остаётся обязательной сама по
себе и закрывает AC4 независимо от статуса файла в списке исключений
статического гварда. Иными словами: исключение из AC1-проверки (статический
факт «этому файлу разрешено писать») и обязанность очистки по AC4
(рантайм-факт «после прогона лишнего не осталось») — два независимых
требования, и revision 2 верно оставила второе, но по инерции убрала и первое,
хотя первое было не источником проблемы. Альтернатива — доказать в тексте, что
`name` в `pure_imports.py` статически ограничен паттерном, не совпадающим с
`custom_components*` (не просматривается, как это сделать без потери гибкости
вызова с каноническим именем).

**Воспроизведение** (разбор по коду, не исполнено как эксперимент — гварда,
описанного ТЗ, ещё не существует в коде): применить контракт AC1 к
`tests_backend/pure_imports.py:31` буквально даёт «отклонить», а вызов из
`tests_backend/test_junction_limits.py:28` требует, чтобы файл продолжал
работать. Оба требования одновременно предъявлены этой же ревизией ТЗ (AC1 +
скоуп + AC5).

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

Без повторной проверки в этом раунде — дельта не касалась этих участков текста
и они не входят в цепочку доказательства новой находки:

- Обязательные продуктовые разделы («Сценарий», «Что человек увидит до и
  после») и корректность персоны — `docs/reviews/SPEC-REVIEW-398-r1.md`,
  раздел «Что проверено и корректно», п.1, на SHA `69dd09a7` (текст этих
  разделов дельтой не тронут).
  Как проверить самостоятельно, что раздел не менялся: сравнить
  `git diff 69dd09a7..480d202f -- docs/specs/398-sysmodules-guard-scope.md`
  — «Сценарий» и «Что человек увидит» отсутствуют среди затронутых hunks.
- Полнота обязательных разделов §7.1 (проблема, скоуп/не-скоуп, UX Н/П, модель
  данных и миграция Н/П, i18n Н/П, план автотестов, откат, release-артефакты)
  — там же, п.2. Структура не менялась, менялось только содержимое трёх блоков
  (проблема/контракт, AC3, план автотестов п.4), уже разобранных выше.
- Соответствие `docs/SCOPE.md`: задача не претендует на строку Core user jobs,
  чисто инфраструктурная — там же, п.5. Не переоценивалось: дельта не меняет
  ни продуктовую рамку, ни `User-Visible`.
- AC2, AC5, AC6 — однозначны и проверяемы каждый по отдельности — там же, п.4
  (частично; см. ниже уточнение по AC1). Текст этих критериев дельтой не
  тронут (см. диф выше — правки только в AC3 и в тексте перед AC-блоком).
  Уточнение к унаследованному: r1 также назвал AC1 «однозначным» — это верно
  в изоляции (формулировка ясна), но r1 не проверял совместность AC1 с AC3 и
  скоупом; это ровно то, что находка r2 закрывает как пробел прошлого раунда,
  а не противоречие ему.
- Риски «разбор Python из Node» и «скрытая зависимость от повторного импорта»
  — назывались по существу уже в r1, текст не менялся (третий риск, «снятие
  регистрации ломает относительные импорты», получил только уточнение
  «замер: модуль полностью рабочий после очистки» — редакционное, не меняет
  сути) — там же, п.6. Новый риск ревизии 2 («соседи, подтянутые
  относительными импортами») проверен заново в этом раунде, см. «Что
  проверено и корректно» ниже.
- Откат и release-артефакты — не изменены дельтой, наследуются из п.7-8 того
  же документа.
- Наблюдение 1 (напряжение формулировок «контракт vs риски» про способ
  разбора) и наблюдение 2 (маршрутизация issue мимо инфраструктурного пути) —
  не блокировали в r1 и не затронуты дельтой; остаются наблюдениями, не
  находками.

## Что проверено и корректно (в этом раунде)

- Закрытие находки r1 текстуально полное: «путь 2» не просто ослаблен
  формулировкой, а вычеркнут вместе со всеми его следами в AC3 и плане
  автотестов (сверено построчно по диффу выше).
- Новый риск «Соседи, подтянутые относительными импортами» (строки 163-167)
  назван конкретно, с перечислением реальных имён модулей
  (`wall_segment_model`, `coordinate_canonicalization`) и с механизмом
  смягчения (диф по префиксу вокруг `exec_module`, а не снятие одного имени) —
  проверено сопоставлением с фактическим поведением, описанным в разделе
  «Проблема и контракт» (те же три модуля названы там как реально
  оставшиеся после `import test_junction_limits`).
- `docs/SCOPE.md` по-прежнему не нарушается: правка не расширяет заявленную
  поверхность, остаётся полностью инфраструктурной.

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

- Не гонял `npx tsc --noEmit` / `npm test` / `npm run build` — на этапе ревью
  ТЗ нет продуктового или тестового кода, есть только правка `docs/specs/*.md`;
  эти гейты неприменимы. (То же основание, что и в r1.)
- Не проверял эксперимента «разбор синтаксиса Python из Node» — вопрос остаётся
  открытым наблюдением из r1, не заново поднятым в этом раунде.
- Не перечитывал `tests_backend/test_validation.py` целиком повторно — его
  собственный `_load_pure` использует префикс `hp_pure.*`, статически не
  совпадающий с `custom_components*` (литеральная часть f-строки/конкатенации
  проверяема по AC2), и это уже подтверждено в r1; для новой находки этот файл
  не релевантен, она про `pure_imports.py`.
- Не проверял, можно ли реализовать распознавание паттерна «запись сразу с
  последующим восстановлением» как альтернативу пофайловому списку исключений
  — это один из вариантов правки, adресованных автору, а не факт, который
  нужно доказывать ревьюеру; сам документ фиксирует именно файловый список
  (AC3 + план автотестов п.4), и находка оценивает именно этот, явно выбранный
  автором механизм.

## Вердикт

Жёлтый. Единственная блокирующая находка (Medium, в скоупе задачи) — устраняя
находку r1 удалением «пути 2», ревизия 2 разорвала совместность AC1/AC2 (гвард
обязан отклонить запись `pure_imports.py:31` по правилу fail-closed) и AC3
(единственное разрешённое исключение — только `conftest.py`) при том, что
`pure_imports.py` явно оставлен в скоупе и обязан по AC5 продолжать работать
для `test_junction_limits.py`. Правится в тексте ТЗ тем же автором, без выхода
за рамки текущей задачи — вероятный минимальный фикс: вернуть
`pure_imports.py` в список статических исключений (не путать со снятым «путём
2» — обязанность очистки `sys.modules` по AC4 остаётся в силе независимо от
статуса файла в списке исключений гварда).