From 6befe4168f64251326cb059f0e47b61dce383daa Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Mon, 31 Aug 2026 01:23:19 +0000 Subject: [PATCH] docs: review document for #399 Issue: #399 User-Visible: no --- docs/reviews/SPEC-REVIEW-399-r1.md | 215 ++++++++++++++++++++++------- 1 file changed, 168 insertions(+), 47 deletions(-) diff --git a/docs/reviews/SPEC-REVIEW-399-r1.md b/docs/reviews/SPEC-REVIEW-399-r1.md index d6425269..c154afa0 100644 --- a/docs/reviews/SPEC-REVIEW-399-r1.md +++ b/docs/reviews/SPEC-REVIEW-399-r1.md @@ -1,73 +1,194 @@ -# SPEC-REVIEW-399-r1 +# SPEC-REVIEW-399-r2 - Issue: https://github.com/Matysh/houseplan-card/issues/399 - ТЗ: `docs/specs/399-backend-gate-honesty.md` -- Материал: SHA `a1d7e0da55322ff4309f139e22bc9a165b780f58` (ветка `issue/399-backend-gate-honesty`, единственный коммит поверх `dev`) -- Заход: r1 (первый), блокирующих циклов израсходовано 0/4 -- Трек: полный (issue не помечен `small`/`trivial`; спецификация сама называет причину — три несвязанные поверхности, что нарушает критерий «одна поверхность» §5) +- Материал: SHA `6d229c66f1e25460b6cc7efcbb67a88a723a3acb` (ветка + `issue/399-backend-gate-honesty`, ревизия 2 поверх `dev`) +- Заход: **r2**, не r1 — см. «Расхождение с заданием раунда» ниже +- Блокирующих циклов израсходовано: 1/4 (израсходован r1, жёлтый; зелёный + цикла не тратит, #227) +- Трек: полный (не изменился, наследуется из r1) - Вердикт: **жёлтый** -## Скоуп +## Расхождение с заданием раунда (нужно проговорить явно) -Три независимые правки бэкенд-гейта, все — класс B (`test/**`, `.github/workflows/**`, `pyproject.toml`, `tests_backend/requirements.txt`), продуктовый код (`src/**`, `custom_components/**/*.py`) не затронут: +Задание на этот прогон присвоило заходу номер r1 и указало +«блокирующих циклов израсходовано 0 из 4». Это не соответствует +фактическому состоянию: -1. пин `home-assistant-frontend` в `tests_backend/requirements.txt` не выведен из констрейнтов закреплённого `homeassistant`, а назначен вручную; -2. `[tool.ruff] include` в `pyproject.toml` шире, чем реально линтуемое в CI дерево; -3. `test/validate-workflow.test.mjs:216` пропускает файл без проверки, если в нём не нашлось ни имени пакета, ни пути к файлу пинов — то есть регресс к неверсионированной установке пройдёт гейт молча. +- `docs/reviews/SPEC-REVIEW-399-r1.md` уже существует в репозитории + (коммит `627a5359`) — это реальный, опубликованный документ ревью, а не + черновик; +- на issue #399 уже есть комментарий-вердикт `Вердикт: жёлтый · заход r1 · + блокирующих циклов 0/4 · High: 0 · Medium: 1 → в задаче`, оставленный + ревьюером; +- автор ответил на этот вердикт комментарием «Ревизия 2 — Medium закрыт» и + запушил `6d229c66 docs: #399 spec revision 2 per SPEC-REVIEW-399-r1`, + который редактирует ровно ту находку, которую назвал r1. -## Как проверялось +То есть цикл r1 реально состоялся и стоил бюджета (жёлтый, 1/4). Присвоение +этому прогону имени `r1` создало бы `docs/reviews/SPEC-REVIEW-399-r1.md` поверх +уже существующего документа — ровно тот сценарий, от которого предостерегает +инструкция «два документа с одинаковым номером затёрли бы друг друга». +Поэтому документ и вердикт этого прогона используют номер **r2**, полученный +из фактического состояния issue и репозитория, а не из присланного +заголовка задания. Далее применяется процедура §2.9/§2.10 для «не первого» +цикла: делта, закрытие r1, наследование. -- прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (полностью, включая §2.9/§2.10 про делту — не применимо: это r1, предыдущего раунда нет); -- прочитано тело issue #399 (комментариев нет); -- сверены все три технические претензии ТЗ с текущим состоянием репозитория построчно: - - `tests_backend/requirements.txt` — подтверждено: `home-assistant-frontend==20260826.1` (строка 29 в файле) соседствует с `homeassistant==2026.8.3`, комментарий рядом объясняет только выбор `phcc`/`homeassistant`, но не `home-assistant-frontend`; - - `pyproject.toml:5` — подтверждено: `include` содержит ровно три дерева, как написано в ТЗ; - - `.github/workflows/validate.yml:787-788` — подтверждено: шаг «Линт бэкенда» гоняет только `custom_components/houseplan`; - - `test/validate-workflow.test.mjs:210-222` — подтверждено дословно, включая номер строки 216 и точный текст условия `continue`; подтверждено также, что цикл проверки идёт по жёстко заданному списку `['validate.yml', 'mutation-gate.yml']`, а не по каталогу `.github/workflows/*.yml`; - - `git grep "pip install" .github/workflows/*.yml` — только `validate.yml` и `mutation-gate.yml` ставят зависимости через pip; остальные пять workflow (`announce`, `docs-screenshots`, `performance`, `process`, `publish-prerelease`, `release-zip`, `release`) не участвуют вовсе — сегодня список из двух файлов исчерпывающий; - - история `#392` (`a3dcee52`, `eb5aa2a0`, `56986748`) реальна и соответствует контексту, на который ссылается ТЗ; - - формат мутантов (`backend-pins-check-opts-out`, `lint-scope-drifts`) сверен с существующими записями `scripts/mutation-gate.mjs` — совпадает по структуре (`id`, kebab-case), не выдумка; - - сверен прецедент `docs/specs/398-sysmodules-guard-scope.md` — тот же формат «Сценарий: разработчик / Пользователь продукта — ничего» уже принят для инфраструктурных гейт-задач этого типа (прошёл ревью ТЗ ранее), так что в #399 это не дефект. -- внешний факт «`package_constraints.txt` тега `2026.8.3` требует `home-assistant-frontend==20260729.7`» (сердце находки M3) независимо перепроверить не удалось — в этой среде нет доступа к сети (`WebFetch` заблокирован отсутствием разрешения). Это ограничение разбора, а не довод против ТЗ: AC1 обязывает доказательство без сети (снимок в репозитории + комментарий с источником), так что сам контракт не зависит от того, смог ли ревьюер ТЗ сходить в интернет — сверка достоверности исходного числа ляжет на код-ревью, где оно будет видно построчно. +## Дельта, которая является предметом этого раунда -## Находки +`git diff a1d7e0da..6d229c66 -- docs/specs/399-backend-gate-honesty.md` +— ровно три хунка: -### Medium (в скоупе) — AC5 не фиксирует, какой набор файлов должен быть «отказом», а какой — «явно допустимым пропуском» +1. строка «Ревизия» в шапке (2, с указанием, что правка отвечает на + SPEC-REVIEW-399-r1); +2. абзац контракта в разделе «(3) Low «в»» — добавлено явное описание + «второй половины дыры» (жёстко заданный массив `['validate.yml', + 'mutation-gate.yml']`) и переформулирован контракт: перебор идёт по + **каталогу** `.github/workflows/*.yml`, для каждого файла ровно два + исхода (ставит зависимости бэкенда → пины; не ставит → доказывается явно, + не через отсутствие подстроки); +3. **AC5** переписан под тот же контракт: доказательство — тест на + синтетическом каталоге, где новый (третий) workflow ставит `pip install + pytest` без версий и обязан краснеть; плюс зафиксирован факт «сегодня в + репозитории девять workflow, установку python-зависимостей делают два». -**Файл**: `docs/specs/399-backend-gate-honesty.md`, AC5 (строки 125-128) и контракт п.(3) (строки 81-83). +Ничего за пределами этих трёх хунков не менялось: разделы про M3 (пин +фронтенда) и Low «а» (скоуп ruff), скоуп/не-скоуп, AC1–AC4/AC6, риски, +откат, release-артефакты — байт в байт те же, что видел r1. -**В чём разрыв**: контракт п.(3) сформулирован широко — «если workflow ставит зависимости бэкенда, он обязан делать это из файла пинов; если не ставит вовсе — это тоже утверждение, которое надо доказать, а не предположить». Это читается как требование накрыть **все** файлы `.github/workflows/*.yml`, а не только два, которые проверка сегодня перебирает (`for (const file of ['validate.yml', 'mutation-gate.yml'])` — жёстко заданный массив, не обход каталога). +## Закрытие раунда r1 -AC5 при этом требует лишь «перечисление файлов, которые проверка обходит, зафиксировано в самом тесте» — и это выполнимо двумя существенно разными способами: +| Находка r1 | Чем закрыта | Где видно | +|---|---|---| +| Medium: AC5 не фиксирует, перебор по каталогу `.github/workflows/*.yml` или по жёстко заданному списку из двух имён — обе версии формально проходят AC4/AC5, но только первая закрывает цель issue буквально | Контракт п.(3) и AC5 переписаны: явно требуется перебор **каталога**, а не списка; для каждого файла — либо пины, либо явное («не ставит») доказательство отсутствия установки, не через отсутствие подстроки; доказательство AC5 теперь называет синтетический каталог с **третьим** workflow, которого в старом списке из двух не было бы | `docs/specs/399-backend-gate-honesty.md:82-94` (контракт), `:136-144` (AC5), SHA `6d229c66` | -1. **слабая версия**: оставить перебор тем же жёстко заданным массивом из двух файлов, внутри него заменить implicit `continue` на explicit разрешённый список причин пропуска. Формально удовлетворяет AC4 (синтетический workflow без обеих зацепок краснеет) и AC5 (список пропускаемых случаев есть в тесте) — но семь остальных workflow-файлов (`announce.yml`, `docs-screenshots.yml`, `performance.yml`, `process.yml`, `publish-prerelease.yml`, `release-zip.yml`, `release.yml`) как не проверялись, так и не проверяются, и, что важнее, **новый** workflow с неверсионированной установкой (например, будущий бэкенд-джоб не в `validate.yml`) вообще никогда не попадёт в цикл — гейт не заметит его так же тихо, как заметил бы файл вне списка ещё до этой правки; -2. **сильная версия**: перебор строится по фактическому листингу `.github/workflows/*.yml`, и для каждого файла тест либо требует пины, либо явно и поимённо объявляет его исключённым (обоснованно — «не устанавливает питон-зависимости»). Это единственная версия, которая закрывает контракт п.(3) буквально, и единственная, которая не оставляет тот же класс слепого пятна, который и стал поводом для находки Low «в» в аудите. +Находка закрыта по существу: слабое прочтение (а) из r1 (список из двух +файлов, замена implicit `continue` на explicit skip-list **внутри тех же +двух**) текстом контракта теперь прямо исключено — новый p.(3) требует +перебора каталога, а не редактирования списка. Это единственная версия, +которую r1 признавал закрывающей issue буквально. -Обе версии проходят AC4/AC5 как написано. Ревью ТЗ обязано различать такие пары («однозначность каждого AC» — задание reviewer'а), а здесь автор реализации может на совершенно законных основаниях выбрать первую и заявить AC выполненными, хотя цель issue («отсутствие обеих зацепок — это отказ, а не пропуск», дословно из тела issue) для будущих файлов не достигается. +## Унаследовано из r1 (без повторной проверки) -**Почему не High**: это не свидетельство того, что задача не может быть выполнена — реализация в любом прочтении будет проходить свои тесты и не ломает ничего рабочего; вопрос ровно в том, какой из двух контрактов фиксируется. Технический вопрос («сканировать каталог или тот же список из двух») — не продуктовый, значит не выносится владельцу (§7.1); его решает автор при реализации, но AC должен явно называть, какой из двух исходов — и ссылаться на п.(3) как на прямое указание. Это Medium в скоупе текущей задачи (правит формулировку AC5, не открывает новый surface) — правится без нового issue (#202). +Со ссылкой на `docs/reviews/SPEC-REVIEW-399-r1.md`, SHA `a1d7e0da`: -**Как закрыть**: одна фраза в AC5 или отдельным пунктом контракта — тест перебирает **все** файлы `.github/workflows/*.yml` (а не фиксированный список из двух), и для каждого, что не входит в проверяемый набор, в самом тесте лежит явное объяснение почему (например, «не запускает Python»), а не молчаливое умолчание через отсутствие подстроки. Дёшево: строчка текста, реализацию не расширяет — `readdirSync` вместо литерала массива на один порядок сложнее не становится. +- §7.1: все обязательные разделы на месте (сценарий, что увидит человек, + проблема по пунктам, скоуп/не-скоуп, UX/данные/i18n — н/п обоснованно, + AC с доказательствами, план автотестов, риски, откат, release-артефакты) + — делта их не трогает, кроме плана автотестов (см. новую находку ниже). +- Классификация трека (полный, класс B, три несвязанные поверхности) — + делта не меняет ни поверхности, ни причину. +- Технические утверждения о разделах (1) M3 и (2) Low «а» — номера строк, + содержимое `tests_backend/requirements.txt:29`, `pyproject.toml:5`, + `.github/workflows/validate.yml:787-788` — делта их не касается, r1 их + построчно сверил. +- AC1, AC2, AC3, AC4, AC6 — текст не менялся этой ревизией, доказательства + оценены r1 как однозначные. +- Продуктовое обрамление и персоны SCOPE.md (задача инфраструктурная, + J-строка не затронута) — не изменилось. +- «Чего не проверял» из r1 (сеть для `package_constraints.txt`, объём + ruff-долга, аудит-документ вне репозитория) — остаётся в силе, делта + этих вопросов не касается. -## Что проверено и корректно +## Новая находка этого раунда -- Обязательные разделы §7.1 присутствуют все: сценарий, что человек увидит, проблема (по пунктам), скоуп/не-скоуп, контракт (по пунктам), UX (н/п — обоснованно), модель данных/миграция (н/п — обоснованно), i18n (нет новых строк — обоснованно), AC1–AC6 с указанием способа доказательства, план автотестов, риски, откат, release-артефакты. -- Продуктовое обрамление (`Сценарий` / `Что человек увидит`) совпадает по формату с уже принятым прецедентом (#398): «Пользователь продукта — ничего, разработчик — …» — корректно для чисто инфраструктурной задачи класса B, доменных персон `SCOPE.md` это не касается по существу вопроса. -- Классификация трека (полный, а не `small`) обоснована прямо в шапке ТЗ явным нарушенным критерием («три несвязанные поверхности») — соответствует требованию §2.2/§5 называть нарушенный критерий, а не полагаться на ощущение. -- Все технические утверждения о текущем состоянии кода (номера строк, содержимое `include`, содержимое workflow, логика `continue`) проверены построчным чтением файлов и совпадают дословно — никаких выданных за факт догадок не найдено. -- AC1–AC6 пронумерованы, для каждого указан способ доказательства (unit-тест либо явное «проверяется ревьюером» для AC3, что соответствует допустимому в DoR методу «ревью кода»). -- Риски названы по существу (объём ruff-долга при исходе (2), сетевая зависимость версии фронтенда, «ложное чувство завершённости») — не общие слова, а конкретные технические ловушки со смягчением. -- Откат — тривиальный revert, обосновано отсутствием продуктового кода в диффе. -- Не-скоуп корректно исключает соседние решения (#42 сужение линта как таковое, версии `homeassistant`/`phcc`, гвард `sys.modules` из #398) — предотвращает попутные правки за пределами трёх названных находок. -- «Одно число — один источник»: неприменимо, пользовательских чисел в диффе нет (весь дифф — CI-конфигурация и тесты). +### Medium (в скоупе) — «План автотестов» (п.4) не обновлён вслед за AC5 и описывает как раз ту слабую версию, которую контракт теперь запрещает + +**Файл**: `docs/specs/399-backend-gate-honesty.md:155` (раздел «План +автотестов», пункт 4 списка Unit-тестов). + +**Текст сейчас**: «Явный список обходимых файлов зафиксирован; добавление +нового файла в workflows без обновления списка краснеет (AC5).» + +**В чём разрыв**: это дословно формулировка **старой** (ревизия 1) версии +AC5 — «перечисление файлов, которые проверка обходит, зафиксировано в самом +тесте» — которую сам автор в этой же ревизии заменил на «перебор каталога, а +не фиксированного списка имён» (строка 137). Пункт 4 плана автотестов не +редактировался в этой ревизии (его нет в диффе), и он по-прежнему описывает +работу через **список**, который требуется вручную **обновлять** при +появлении нового файла — то есть ту самую конструкцию, о которой новый +контракт п.(3) говорит: «доказывается явно… а не выводится из отсутствия +подстроки [и не из членства в списке]». + +Смысловая разница не косметическая. Реализация, которая берёт «План +автотестов» как техническое задание для теста (а не прозу AC5 несколькими +абзацами выше), может на законных основаниях построить: `readdirSync` + +хардкод-массив «эти N файлов не ставят python-зависимостей» + фейл, если имя +нового файла не найдено ни в списке пиновых, ни в списке-исключений. Такая +реализация проходит буквальный текст п.4 («список… краснеет при отсутствии +файла в нём»), но именно она возвращает эксплуатационную нагрузку — +необходимость вручную поддерживать список — которую контракт п.(3) и +переписанный AC5 сознательно убрали («доказывается явно… а не выводится из +отсутствия подстроки»). Расхождение между двумя разделами одного и того же +ТЗ — тот же класс дыры, что и находка r1: AC/раздел проходятся двумя +существенно разными реализациями, только на этот раз конфликт не внутри +одного AC, а между «Критериями приёмки» и «Планом автотестов». + +Это не гипотетическая тонкость: п.4 — единственное место в документе, где +явно описано, ЧТО проверяет unit-тест для AC5, и оно противоречит только что +исправленному AC5 в этом же файле. + +**Почему не High**: реализация всё равно проходит написанные тесты в любом +из двух прочтений, продуктового кода нет, откат тривиален. Это вопрос +формулировки одного ТЗ-раздела, а не невозможности выполнить задачу. + +**Почему Medium, а не Low**: буквальный текст, на который будет смотреть +исполнитель при написании теста, указывает в сторону реализации, которую сам +документ (двумя разделами выше) явно отверг. Это создаёт тот же риск +«формально выполнено, но не решает то, из-за чего заведено», который r1 уже +один раз поймал в AC5 — здесь тот же риск переехал в соседний раздел +вследствие правки, а не был там с начала (в ревизии 1 AC5 и п.4 плана +автотестов формулировались одинаково слабо и не противоречили друг другу; +конфликт появился именно этой правкой). Правится в этой же задаче (#202 не +применяется — находка в скоупе). + +**Как закрыть**: одна строка. Например: «4. Синтетический каталог +`.github/workflows/*.yml`, где один из файлов не входит в набор +`validate.yml`/`mutation-gate.yml`, ставит `pip install pytest` без версий и +не имеет явного маркера «не устанавливает python-зависимости» — тест +краснеет; никакого списка имён для ручного обновления в реализации нет +(AC5).» Дёшево: правка одного предложения, план автотестов приводится в +соответствие с уже переписанным AC5. + +## Что проверено и корректно (в дополнение к унаследованному) + +- Новый факт в AC5 «в репозитории девять workflow, установку + python-зависимостей делают два» — перепроверен на текущем дереве: + `ls .github/workflows/*.yml` даёт ровно 9 файлов; `git grep -l "pip + install" .github/workflows/*.yml` даёт ровно `mutation-gate.yml` и + `validate.yml`. Число и состав совпадают дословно. +- Переписанный контракт п.(3) и AC5 внутренне непротиворечивы друг другу + (оба говорят про каталог, оба про «явное доказательство отсутствия + установки», оба про мутанта с третьим workflow) — конфликт только с планом + автотестов, описанным выше. +- Правка не меняет трек, скоуп/не-скоуп, риски и не переносит вопрос + владельцу — расширение контракта («перебор каталога») лежит внутри уже + согласованной цели issue («отсутствие обеих зацепок — отказ, а не + пропуск»), это техническое уточнение, а не продуктовое решение (§7.1: не + выносится владельцу). +- Заголовок «Ревизия 2» корректно ссылается на SPEC-REVIEW-399-r1 — + трассировка причины правки на месте. ## Чего не проверял -- Не проверял по сети фактическое содержимое `package_constraints.txt` тега `2026.8.3` репозитория `home-assistant/core` (претензия M3 из аудита) — инструмент веб-доступа в этой среде недоступен (запрос разрешения не подтверждён). Не блокирует вердикт: AC1 требует доказательства без сети, реализация и код-ревью проверят число построчно с открытым источником в комментарии. -- Не гонял `npm test` / `npx tsc --noEmit` / `npm run build` — это ревью ТЗ (документ, не код), гейты не относятся к этому этапу; они будут прогнаны на код-ревью после реализации. -- Не проверял сам аудит-документ `AUDIT-2026-08-31-v1700beta1.md` — файл не найден в репозитории (видимо, живёт вне репозитория, как и часть ревью до 1.62); тело issue содержит достаточный самостоятельный контекст, так что отсутствие исходника не мешает оценке ТЗ. -- Не проверял объём накопленного ruff-долга («порядка полусотни» находок при исходе (2)) — это оценка автора ТЗ для риска, не факт, требующий проверки на этом этапе; будет виден в CI при выборе исхода (2) на код-ревью. +- Сетевое содержимое `package_constraints.txt` тега `2026.8.3` + `home-assistant/core` (претензия M3) — как и в r1, недоступно в этой + среде; не блокирует, AC1 требует доказательства без сети, число будет + видно на код-ревью. +- Объём ruff-долга при исходе (2) для Low «а» — не факт, требующий проверки + на этом этапе; делта его не касается. +- `npm test`/`npx tsc --noEmit`/`npm run build` — это ревью документа + (ТЗ), а не кода; правка не трогает `src/**`/`custom_components/**`, гейты + кода к этому этапу не относятся и будут прогнаны на код-ревью. +- Аудит-документ `AUDIT-2026-08-31-v1700beta1.md` вне репозитория — как и + в r1, не найден локально, тело issue самодостаточно. ## Вердикт -Жёлтый: единственная блокирующая-по-скоупу находка — Medium, без High. Автор уточняет формулировку AC5 (какой набор workflow-файлов покрывает проверка и почему), проходит повторный цикл ревью ТЗ (лимит лёгкого трека здесь неприменим — трек полный, лимит 4, израсходовано 0/4). +Жёлтый: единственная блокирующая находка — Medium, без High. Прежняя +Medium-находка (AC5: список vs каталог) закрыта; ревизией 2 введена новая +Medium-находка того же семейства в соседнем разделе («План автотестов», +п.4). Автор приводит формулировку п.4 в соответствие с переписанным AC5 и +проходит ещё один заход ревью ТЗ (полный трек, лимит 4 цикла, израсходован +1/4 после r1; после этого раунда — 2/4).