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

SPEC-REVIEW-42-r2

• Issue: #42 «[HP-ENG-01] измеряемое инженерное качество backend»
• Этап: ТЗ на ревью (PROCESS.md §2.4), полный трек (метки: P2, tests, tech-debt, S4-spec-review; small отсутствует)
• Артефакт ТЗ: docs/specs/042-backend-engineering-quality.md, ревизия 3 (коммит 0ed83c36, docs-only, класс C)
• Заход: r2 · блокирующих циклов израсходовано 1/4 (перед этим раундом)
• Предыдущий раунд: r1, вердикт жёлтый, найдено на коммите ревизии 2 582d673a (документ docs/reviews/SPEC-REVIEW-42-r1.md, зафиксирован в дереве коммитом e270bd71)

Скоуп проверки (дельта)

Между раундами в историю dev попал один посторонний коммит 50851dc3 (ci: classify against the last proven-green ancestor, issue #387) — он не относится к #42, файла ТЗ не трогает, из разбора исключён.

Сам раунд r2 — это ровно один коммит автора, 0ed83c36 (docs: #42 spec revision 3 per SPEC-REVIEW-42-r1): 32 добавлено / 10 удалено, единственный файл docs/specs/042-backend-engineering-quality.md. Диф не трогает src/** и custom_components/**/*.py — код-гейты (typecheck/test/build/check-docs/смоки/pytest tests_backend) к этому раунду неприменимы по той же причине, что и в r1 (PROCESS.md §2.4 vs §2.7). Правка — точечный ответ на M1/M2 из r1: переписан блок 5 «WS error contract» и добавлен раздел «i18n»; больше ничего в файле не менялось (строка ревизии в заголовке — техническая).

Полный повторный разбор ТЗ не требовался: правка локальна, контракт поведения не меняется, новая подсистема не затронута, объём дельты (один абзац + новый короткий раздел) кратно меньше исходной задачи. Инвариантов модели, i18n-паритета файлов, смоков — гейты не относятся к этому дифу, т.к. геометрия/UI-код не изменились.

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

• Построчный дифф git diff 582d673a..0ed83c36 -- docs/specs/042-*.md, сверка против текста находок M1 и M2 из docs/reviews/SPEC-REVIEW-42-r1.md (читал полностью).
• Перечитан весь текущий файл ТЗ целиком (203 строки) — не только изменённый блок 5, чтобы поймать несогласованность между новым текстом блока 5 и разделом «Критерии приёмки», который дифф НЕ трогал.
• Проверено присутствие обязательных разделов §7.1 в актуальной версии файла (список секций постранично).

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

Находка r1	Чем закрыта	Где видно
M1 — AC5 не покрывает коды, эмитируемые не литералом в send_error(...) (err.code-классы OpeningPassageError/PartitionOpeningHostError/PartitionOpeningJambMarginError/WallModelClientOutdatedError, JunctionLimitError, MarkerControlError)	Частично. Раздел «5. WS error contract» переписан: введён ERROR_CODE_FAMILIES, оба пути эмиссии (литералы send_error и err.code-классы) перечислены явно с методом извлечения (regex по class-attr, f-строка по списку rules, префиксные семейства) — ровно вариант (а) из рекомендации r1. Но сама формулировка AC5 в разделе «Критерии приёмки» (docs/specs/042-*.md:148-149) и её мутант в «Плане автотестов» (:162, «удалить код из ERROR_CODES → красный AC5») остались текстом ревизии 2 — тем самым, который M1 назвал недостаточным («скан исходника: каждый литерал send_error(...)-кода»). Правка не долетела с блока 5 до самого критерия приёмки. Разбираю как новую находку r2 ниже.	docs/specs/042-backend-engineering-quality.md:83-99 (закрыто) против :148-149,162 (не закрыто)
M2 — раздел «i18n» отсутствует; не зафиксировано, новый ключ или переиспользование err.code	Полностью. Добавлен раздел «## i18n» (:123-129): новых ключей нет, переиспользуются существующие err.unknown/err.code (4 локали), плюс явное решение по порядку проверок в _errText — code-first — вынесено в блок 5 (:106-110, помечено «M2 r1»).	docs/specs/042-backend-engineering-quality.md:106-110,123-129
Low — разделы «UX» и «Модель данных и миграция» не оформлены отдельными заголовками §7.1	Не тронуто. В r1 уже снято с записью («не блокирует, консолидировать при следующей правке, отдельного цикла не требует») — повторно не поднимаю, автор правку не делал и не обязан был.	без изменений, см. «Унаследовано»

Находки

Medium 1 (в скоупе) — AC5 и её мутант не синхронизированы с исправленным блоком 5; критерий приёмки снова недоказателен

Файл: docs/specs/042-backend-engineering-quality.md

Что не так. Раздел 5 (:83-99) теперь корректно требует от контракт-теста покрывать оба пути эмиссии кода (литералы send_error + перечисленные err.code-источники/семейства). Но:

• AC5 (:148-149) буквально повторяет старую формулировку: «ERROR_CODES ⊇ все коды send_error (скан исходника); каждый код имеет en-ключ backup.error.<code>» — ни слова про ERROR_CODE_FAMILIES, про перечисленные классы-источники err.code, про требование «family-ключ ИЛИ задокументированный fallback». Как единственный формально «критерий приёмки», именно этот текст, а не проза блока 5, будет тем, с чем код-ревьюер на этапе code сверяет реализацию;
• мутант AC5 в «Плане автотестов» (:162) — «удалить код из ERROR_CODES → красный AC5» — проверяет только фиксированный список, не проверяет, что скан действительно достаёт err.code-семейства. Реализация «в лоб» под букву AC5 (наивный скан литералов send_error(...)) снова даст зелёный тест, который ничего не доказывает для invalid_passage_fields и invalid_partition_opening_jamb_margin — то есть воспроизводит именно тот сценарий, который M1 описывал как дефект.

Почему это находка именно r2, а не «M1 не закрыта». Текст блока 5 переписан правильно и по существу отвечает на M1; пропуск — в том, что правка не была протянута до самого критерия приёмки и его мутанта, а именно они образуют доказательную часть ТЗ (PROCESS.md §7.1: «критерии приёмки AC1…ACn с указанием доказательства»). Автор в комментарии к ревизии 3 заявляет «AC5/блок 5 покрывают ОБА пути эмиссии» — по факту диффа это верно только для блока 5.

Как чинится в скоупе: переформулировать AC5, например: «ERROR_CODES ⊇ все коды-литералы send_error(...); ERROR_CODE_FAMILIES ⊇ все коды из перечисленных err.code-источников (OpeningPassageError, PartitionOpeningHostError, PartitionOpeningJambMarginError, WallModelClientOutdatedError, JunctionLimitError, MarkerControlError); каждый код/семейство имеет либо backup.error.<code>, либо задокументированный fallback; появление кода/класса вне обоих списков → красный» — и добавить к мутанту м1 вторую ветку («убрать класс-источник из перечня err.code → красный AC5»), либо явно сослаться на текст блока 5 как на нормативный (тогда AC5 короче, но должен явно писать «см. §5» вместо повторения устаревшей формулировки).

Технический вопрос (какой именно текст AC), не продуктовый — решаю сам, не выношу владельцу.

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

Без повторной проверки в r2 принято на основании docs/reviews/SPEC-REVIEW-42-r1.md (документ ревью r1, найден на дереве коммитом e270bd71; измерения и выводы получены на SHA 582d673a):

• независимая перепроверка числовых фактов ТЗ (ruff 333/291/17/13/6/2/2, quality_scale.yaml — ровно 4 todo, отсутствие Troubleshooting в USER-GUIDE.ru.md, 26 ключей backup.error.*, дубль pip-строки в mutation-gate.yml:67) — дельта r2 этих фактов не касается, они не переизмерялись повторно;
• продуктовые разделы «Сценарий» и «Что человек увидит до и после» — на месте, продуктовые, без терминов реализации (дельта их не трогала); ценностная оценка задачи (3/10 пользователю, 9/10 разработке) принята владельцем в комментариях issue ранее, не переоткрываю;
• «Скоуп/не-скоуп», «Контракт поведения», AC1–AC4, AC7 — однозначны, способ доказательства назван у каждого, тест умеет упасть (дельта r2 их текст не меняла);
• AC6 — проверен ПОВТОРНО в этом раунде (см. ниже), т.к. дельта его касается через M2/блок 5;
• риски, откат, release-артефакты, принятые предположения — не изменялись дельтой, приняты как в r1;
• Low-находка про заголовки «UX»/«Модель данных и миграция» — статус не меняется: снята с записью в r1, автор консолидацию не делал и не был обязан её делать в этом раунде.

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

• M2 закрыта полностью — раздел «i18n» присутствует, решение явное (переиспользование err.unknown/err.code, никаких новых ключей), согласуется с фактом, перепроверенным в r1 (ключи уже переведены на 4 языка); порядок «code-first» в _errText зафиксирован текстом в блоке 5 (:106-110) — ровно то, что просила находка M2;
• AC6 (:150-152) остаётся однозначным и согласован с новым текстом блока 5: «JSON-message двух кодов парсится в structured details; старый regex-формат по-прежнему принимается; неизвестный код → локализованный fallback, английский message не попадает в DOM» — этого достаточно для проверки code-first фикса без необходимости упоминать порядок явно в самом AC (порядок — деталь реализации, наблюдаемый результат AC6 не меняется);
• блок 5 (:83-99) — единственный содержательно переписанный фрагмент — сам по себе не содержит новых пробелов: оба пути эмиссии названы, метод извлечения кода для каждого класса описан конкретно (regex по code = "...", список rules П1–П4, префиксы value_badge_/ value_source_), критерий «family-ключ ИЛИ документированный fallback» однозначен, «код/класс вне списков → красный» закрывает вопрос полноты перечня на будущее;
• трейлеры коммита 0ed83c36 — Issue: #42, User-Visible: no — корректны (видимого поведения этот коммит не меняет, он правит только текст ТЗ).

Чего не проверял и почему

• код-гейты (typecheck/test/build/check-docs/model-invariants/ браузерные смоки/pytest tests_backend) — диф раунда состоит из одного файла docs/specs/042-*.md, src/** и custom_components/**/*.py не тронуты; прогон на неизменном коде не даёт сигнала по существу ТЗ и не входит в предмет ревью ТЗ (PROCESS.md §2.4 vs §2.7);
• повторный замер ruff/coverage/quality_scale.yaml — факты не менялись этим раундом, перепроверены в r1 и наследуются без повторного прогона;
• содержимое коммита 50851dc3 (ci: classify against the last proven-green ancestor) — прочитан только git show --stat для подтверждения, что он не относится к #42; по существу не ревьюился, т.к. принадлежит issue #387.

Итог

M2 закрыта полностью. M1 закрыта только в прозе блока 5 — критерий приёмки AC5 и его мутант остались текстом ревизии 2, который сам M1 назвал недоказательным. Возврат — по одной находке Medium в скоупе, чинится правкой того же файла (переформулировать AC5 и добавить вторую ветку мутанта либо явно сослаться на блок 5), без нового цикла владельца и без пересмотра архитектуры.