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

SPEC-REVIEW-398-r3

• Issue: https://github.com/Matysh/houseplan-card/issues/398
• Этап: ТЗ на ревью (PROCESS.md §2.4)
• Материал: docs/specs/398-sysmodules-guard-scope.md, коммит 9fde407e («#398 spec revision 3 per SPEC-REVIEW-398-r2»)
• Заход: r3 · блокирующих циклов израсходовано до этого вердикта: 2 из 4
• Предыдущий вердикт: docs/reviews/SPEC-REVIEW-398-r2.md, жёлтый, на коммите 480d202f (ревизия 2 ТЗ). SHA назван в самом документе r2 явно («Материал: …, коммит 480d202f»), детективная работа не требуется.

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

Дельта — git diff 480d202f..9fde407e -- docs/specs/398-sysmodules-guard-scope.md (27 добавленных / 7 удалённых строк, один файл). Правка не ребейзится на ушедший вперёд dev, не меняет продуктовый контракт (User-Visible: no, класс B сохранён), не задевает новую подсистему и по объёму меньше исходной задачи — полный повторный разбор не требуется. Дельта касается четырёх мест: (1) шапка «Ревизия», (2) новый абзац после раздела «Что делать с load_pure», (3) AC3 + новый AC8, (4) план автотестов (пп. 3–4 unit, мутанты). Разделы, которых дельта не коснулась (Сценарий, «Что человек увидит», Скоуп/не-скоуп, UX, модель данных, i18n, AC1/AC2/AC5/AC6, Риски, Откат, Release-артефакты), унаследованы из r2 — см. раздел ниже. Отдельно проверено, не задевает ли дельта совместность с AC, которые сама не редактировала (AC1/AC2 vs новый AC3/AC8) — это и есть предмет находки r2, разбор ниже.

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

Находка r2	Чем закрыта	Где это видно
Medium: устранение «пути 2» в ревизии 2 сделало AC1/AC2 (fail-closed отказ на sys.modules[<переменная>] = …) несовместимыми с AC3 (единственное исключение — только conftest.py) для tests_backend/pure_imports.py:31, оставленного в скоупе и обязанного по AC5 продолжать резолвить относительные импорты	Статический список исключений расширен до двух поимённых файлов; ключевое отличие от снятого «пути 2» — обязанность самоочистки (AC4) сохранена и продублирована отдельным AC8 с собственным мутантом, то есть исключение из AC1-проверки и обязанность очистки по AC4 разведены как два независимых требования, а не связаны в одно (именно эта связка и была ошибкой пути 2)	docs/specs/398-sysmodules-guard-scope.md:88-100 (новый абзац «Исключений в статическом гварде два, и это не возврат снятого пути») дословно повторяет вариант, предложенный ревьюером в r2 («Как править», см. docs/reviews/SPEC-REVIEW-398-r2.md), включая обоснование «там файл исключался ВМЕСТО очистки, здесь — при обязательной очистке»; AC3 (строки 133-135) теперь называет оба файла поимённо; новый AC8 (строки 136-139) требует восстановления в finally с отдельным мутантом pure-imports-stops-cleaning

Закрытие текстуально точное и логически корректное: авторская правка не просто переименовала проблему, а разнесла два ранее слитых требования (статический список «кому разрешено писать» и исполняемая проверка «осталось ли что-то после») по разным AC, что и было сутью замечания r2.

Каскадная правка, которую отдельно стоит отметить. Автор также обновил мутант sysmodules-guard-blind-to-variable: в ревизии 2 он ещё был сформулирован как «вернуть запись через переменную в pure_imports.py → гвард красный» — формулировка, оставшаяся неизменной с ревизии 1 и после правки r2 переставшая быть верной (раз pure_imports.py теперь легален по AC3, мутация на нём самом не могла бы покраснеть). В ревизии 3 текст исправлен на «добавить запись через переменную в файл ВНЕ списка исключений → гвард красный». Это не было прямо указано ревьюером, но вытекает из его находки — хороший признак того, что правка не точечная, а проверена на согласованность со смежными местами документа.

Новые находки (в этом раунде)

Blocking (High/Medium в скоупе) не найдено. Два наблюдения ниже — Low, не блокируют.

Low — план автотестов не называет явно позитивный контракт-тест для pure_imports.py как второго исключения

docs/specs/398-sysmodules-guard-scope.md:154-157, пункты плана автотестов:

3. `conftest.py` со своей условной подменой → зелено (AC3).
4. Попытка добавить третий файл в список исключений → красный (AC3).

AC3 вводит два поимённых исключения, но явный позитивный тест-пример назван только для одного (conftest.py); для tests_backend/pure_imports.py — файла, ради которого вся ревизия 3 и написана, — отдельного пункта «его собственная запись sys.modules[name] = module → зелено (AC3)» в плане нет. Это не логическое противоречие (как было в r1/r2): без него набор AC остаётся формально выполнимым, поскольку test/backend-test-hygiene.test.mjs сканирует реальные файлы tests_backend/*.py, включая сам pure_imports.py, и при каждом прогоне npm test наличие исключения будет неявно упражнено (если реализация ошибочно не распознает второе исключение, npm test покраснеет на реальном файле, а не только на синтетическом). Поэтому не поднимаю до Medium. Но именно эта строка кода — центр всей ревизии 3, и явный пункт плана снял бы зависимость от «неявного» покрытия реальным файлом.

Low — нумерация критериев приёмки нарушена: AC8 вставлен между AC3 и AC4, AC7 не существует

docs/specs/398-sysmodules-guard-scope.md:133-142: порядок в тексте — AC1, AC2, AC3, AC8, AC4, AC5, AC6. Ни в одной прежней ревизии (проверено: git show 69dd09a7:..., git show 480d202f:...) критерия AC7 не было — не удалён, а просто пропущен номер. Сути не меняет (каждый AC однозначен и пронумерован уникально, дублей нет), но для читателя, ищущего «AC7», это выглядит как потерянный критерий, а не как намеренный пропуск. Дешевле всего исправить переносом нового критерия в конец списка под следующим свободным номером (AC7) при следующей правке текста; заводить отдельный цикл ради этого нет оснований.

Унаследовано из r2

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

• Обязательные продуктовые разделы («Сценарий», «Что человек увидит до и после») и корректность персоны (разработчик, не пользователь продукта) — docs/reviews/SPEC-REVIEW-398-r2.md, раздел «Унаследовано из r1», на SHA 69dd09a7. Текст этих разделов не изменился ни в 480d202f, ни в 9fde407e (сверено: ни один hunk git diff 69dd09a7..9fde407e их не касается).
• Полнота обязательных разделов §7.1 (проблема, скоуп/не-скоуп, UX Н/П, модель данных и миграция Н/П, i18n Н/П, план автотестов, откат, release-артефакты) — там же. Структура документа не менялась в r3, только содержимое трёх блоков (проблема/контракт, AC3+AC8, план автотестов), разобранных выше.
• Соответствие docs/SCOPE.md: задача чисто инфраструктурная, не претендует на строку Core user jobs — docs/reviews/SPEC-REVIEW-398-r2.md, «Что проверено и корректно». Дельта r3 не меняет ни продуктовую рамку, ни User-Visible.
• Скоуп/не-скоуп (tests_backend/conftest.py вне скоупа, правило #393 вне скоупа) — не тронут дельтой r3, наследуется из r1/r2.
• AC1, AC2, AC5, AC6 — однозначны и проверяемы по отдельности — docs/reviews/SPEC-REVIEW-398-r1.md, «Что проверено и корректно», п.4, переподтверждено в r2. Текст этих критериев дельтой r3 не тронут (см. диф выше — правки только в AC3, новый AC8, план автотестов).
• Риски «разбор Python из Node», «снятие регистрации ломает относительные импорты», «соседи, подтянутые относительными импортами» — не изменены в r3 (диф 480d202f..9fde407e не затрагивает раздел «Риски»), проверены по существу в r1/r2.
• Откат и release-артефакты — не изменены дельтой r3, наследуются из r1/r2.
• Наблюдения r1 (напряжение формулировок «контракт vs риски» про способ разбора; маршрутизация issue мимо инфраструктурного пути) — не блокировали тогда, не затронуты дельтой r3, остаются наблюдениями.

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

• Закрытие находки r2 логически полное: две ранее слитые обязанности (статическое разрешение писать / исполняемая проверка отсутствия мусора) теперь заданы независимыми AC (AC3 и AC4/AC8), что и требовалось — сверено построчно по диффу.
• Каскадное обновление мутанта sysmodules-guard-blind-to-variable (описано выше) — проверено сопоставлением текста ревизии 2 и ревизии 3; без этой правки план автотестов противоречил бы новому AC3.
• Новый AC8 имеет самостоятельное, отличное от AC3 доказательство (мутант pure-imports-stops-cleaning, отдельно перечисленный в разделе «Мутант») — не голая декларация без способа проверки.
• Сверено с реальным кодом: tests_backend/pure_imports.py на текущий момент не содержит finally-восстановления и sys.modules[name] = module пишет безусловно (строки 27-29 файла) — ожидаемо, реализация ещё не начата, текст ТЗ описывает будущее состояние, а не выдаёт его за существующее.
• docs/SCOPE.md по-прежнему не нарушается — дельта r3 не расширяет заявленную поверхность.

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

• Не гонял npx tsc --noEmit / npm test / npm run build — на этапе ревью ТЗ нет продуктового или тестового кода помимо самого docs/specs/*.md; finally-очистка и AST-гвард ещё не реализованы, гейты неприменимы (то же основание, что в r1/r2).
• Не проверял выполнимость «разбор синтаксиса Python из Node» экспериментом — наблюдение 1 из r1 остаётся открытым, не переоценивалось в r3 (дельта его не касалась).
• Не проверял tests_backend/test_validation.py повторно — его _load_pure использует префикс hp_pure.*, не пересекающийся с custom_components*, подтверждено в r1 и не релевантно дельте r3.
• Не проверял, что произойдёт при переименовании одного из двух исключённых файлов (например, pure_imports.py → pure_imports_v2.py) — это вопрос реализации статического списка (по имени файла vs по содержимому), ТЗ его не обязано покрывать явно, а два Low-наблюдения выше достаточны для следующей правки текста, если автор сочтёт нужным.

Вердикт

Зелёный. Находка r2 закрыта корректно и по существу (не переименование проблемы, а разведение двух ранее слитых требований по разным AC), новых блокирующих несовместимостей правка не внесла. Два Low-наблюдения (нумерация AC8 вне последовательности; план автотестов не называет явный позитивный тест-пример для pure_imports.py как исключения) не блокируют и не образуют цикл — оставляю их автору на усмотрение при следующей правке текста, если таковая понадобится по другому поводу.