From 1f432245dbfe89f7a067dec644057d42c9c2d5de Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Tue, 8 Sep 2026 20:38:03 +0000 Subject: [PATCH] docs: review document for #492 Issue: #492 User-Visible: no --- docs/reviews/SPEC-REVIEW-492-r1.md | 223 +++++++++++++++++++++++++++++ 1 file changed, 223 insertions(+) create mode 100644 docs/reviews/SPEC-REVIEW-492-r1.md diff --git a/docs/reviews/SPEC-REVIEW-492-r1.md b/docs/reviews/SPEC-REVIEW-492-r1.md new file mode 100644 index 00000000..f1f1eadb --- /dev/null +++ b/docs/reviews/SPEC-REVIEW-492-r1.md @@ -0,0 +1,223 @@ +# SPEC-REVIEW-492-r1 + +Issue: #492 «CI: проверять точный кандидат интеграции и полный набор зависимостей selection/reuse» +Этап: ТЗ на ревью (PROCESS.md §2.4). Трек: полный (не `small`) — ТЗ живёт в +`docs/specs/492-exact-candidate-and-input-manifest.md`. +Заход: r1 · блокирующих циклов израсходовано 0 из 4. + +## Скоуп + +Предмет ревью — файл `docs/specs/492-exact-candidate-and-input-manifest.md` +(174 строки) и обновление `docs/specs/README.md`, оба из коммита `941c7cff` +на ветке `issue/492-exact-candidate-and-input-manifest`. Материал не менялся +между заходами (r1, предыдущих раундов не было — единственный комментарий в +issue — аналитика S2, не вердикт ревью). + +Класс задачи по AGENTS.md: issue заявлен `infra`/`P1`/`tech-debt`, ни одного +файла класса A ни в ТЗ, ни в перечне «Затронутых файлов» (§12 ТЗ). По +механическому признаку AGENTS.md такая задача могла бы идти вне S-флоу вовсе; +автор явно называет это в комментарии S2 и ведёт задачу по меткам ради +ревью конвейером, ссылаясь на прецедент того же рода — #472, #475, #481 +(все — gate-инфраструктура, все проверены: #472 и #481 закрыты через полный +S1…S8, #475 — `small`, полный S1…S8 тоже пройден, класс файлов везде B/C/D). +Прецедент подтверждён напрямую (`gh issue view`), это корректная и уже +устоявшаяся практика репозитория, а не самовольное расширение флоу. Первый +вопрос «какую строку Core user jobs закрывает задача» здесь неприменим по +предмету: `docs/SCOPE.md` описывает продуктовые обязательства перед тремя +персонами, а #492 правит собственный процесс проверки (`PROCESS.md`, +`.github/workflows/**`), у которого пользователя-персоны в смысле SCOPE.md +нет — сценарий и адресаты корректно названы в §1.1 ТЗ как «автор задачи, +ревьюер, обслуживающий чат, владелец, читающий статусы». + +## Как проверялось + +- Прочитаны целиком `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (весь файл, + включая §1–§10.4: классы файлов, лёгкий/полный трек, лимит циклов §4, + обязательные разделы ТЗ §7.1, шаблоны вердиктов §7.2, гейты §8). +- Прочитано тело issue #492 и единственный комментарий (аналитика владельца, + S2), где подтверждены источники аудита по SHA. +- **Каждое фактическое техническое утверждение §1 ТЗ проверено чтением кода на + цитируемом SHA `ea6061e9`, а не принято на слово:** + - п.1 (слияние): `.github/workflows/process.yml` на `ea6061e9` — шаг «Слить + ветку в dev» действительно делает `git rebase origin/dev`, затем сразу + `git push … HEAD:dev` без какой-либо проверки нового дерева между ребейзом + и push; шаг «dev ушёл вперёд» только комментирует, не блокирует (строки + ~917–969 файла на этом SHA). Подтверждено. + - п.2 (реюз бэкенда): `scripts/gate-reuse.mjs` на `ea6061e9` — + `HARNESS.backend.roots` = `['tests_backend', 'custom_components', + 'pytest.ini', 'scripts/backend-coverage-baseline.txt', 'pyproject.toml']` + — не включает `scripts/support-relay/**`, `scripts/sh3d-convert/**`, + `scripts/config-schema.json`, `scripts/dump-config-schema.py`; при этом + `reuseKey` подмешивает `sourceFingerprint(root)` (полный `src/**`) во + **все** job без исключения, включая `backend`. `scripts/classify-changes.mjs` + на том же SHA: регэксп `backend` содержит `scripts/support-relay/`, но не + `pyproject.toml` и не `scripts/sh3d-convert/`. Оба утверждения — и «relay + классифицируется как backend, но не входит в ключ реюза», и «pyproject/ + sh3d-convert не классифицируются вовсе» — подтверждены буквально. + - п.4 (мутанты): `scripts/backend-test-guard.mjs` на `ea6061e9` — третий + аргумент (`testFile`) действительно опционален с дефолтом + `tests_backend/test_ha_import_export.py`; `grep` по `mutation-gate.mjs` + даёт 35 использований этого гарда, что согласуется с «10 из 35 без + третьего аргумента» (точное число 10 не пересчитывалось построчно — + порядок величины и факт существования дефолта подтверждены, этого + достаточно для проверки формулировки проблемы на этапе ТЗ). + - Ни одно техническое утверждение раздела «Проблема» не оказалось догадкой, + выданной за факт — все проверяемые пункты подтвердились чтением + процитированного SHA. +- Сверены оба направления связи issue ↔ ТЗ: issue #492 не содержит прямой + ссылки на файл ТЗ в теле (обычно это делает владелец/автор отдельной правкой + либо ссылка остаётся в `docs/specs/README.md` — она на месте), сам файл ТЗ + ссылается на issue первой строкой; `docs/specs/README.md` содержит строку + `#492` → `492-exact-candidate-and-input-manifest.md`. Связь двусторонняя по + факту (README + текст ТЗ), проверено чтением диффа коммита `941c7cff`. +- Проверено соответствие обязательных разделов §7.1 PROCESS.md: сценарий + (§1.1), что человек увидит до/после (§1.2), проблема (§1), скоуп/не-скоуп + (§2/§3), контракт поведения (§4–§8), UX/модель данных/i18n (§10.1, явное + «не затрагиваются» — корректно для infra), критерии приёмки (§10, AC1–AC10), + риски (§10.2), откат (§9), release-артефакты (§11) — все присутствуют. + Отдельного раздела «план автотестов» под таким заголовком нет, но по + содержанию план распределён по §8 (пять групп отрицательных тестов с + конкретными представителями и файлами) и §12 (перечень новых/правимых + `test/*.test.mjs`) — это не пропуск, а другая раскладка того же + содержания; не самостоятельная находка. +- Проверена внутренняя согласуемость: таблица категорий манифеста (§5.1) + сверена построчно со списком представителей §8.1 — каждая категория + (`source`/`tests`/`fixtures`/`config`/`toolchain`/`protocol`) имеет хотя бы + один представитель в негативных тестах, кроме `tests` (уже покрыта + существующим корнем `tests_backend` в текущем `HARNESS`, поэтому не входит + в список **новых** гарантий). Список из «шести мутантов на протокол» в §13 + и §8.5 совпадает поимённо (6 пунктов). +- По каждому AC1–AC10 отдельно проверено, к какому пункту §8 (или §7) он + привязан как доказательство — см. находку ниже, единственный разрыв на + AC6. +- Дешёвые гейты не прогонялись отдельно: Validate на `941c7cff` зелёный + (ссылка дана в постановке задачи), а класс изменений — только `docs/**` + (класса C), код не менялся. `typecheck`/`test`/`build`/`check-docs` + нерелевантны этапу ТЗ и этому диффу. + +## Находки + +### Medium (в скоупе задачи) — AC6 не называет способ доказательства + +**Файл:** `docs/specs/492-exact-candidate-and-input-manifest.md`, AC6 (раздел +10) и §5.3. + +AC6 формулирует защитное утверждение: «`backend` не зависит от `src/**` — +включено последним коммитом после AC4–AC5». Это ровно тот тип критерия, +для которого PROCESS.md §2.5 требует явно назвать способ доказательства +(`unit`/`backend`/`smoke`/`golden`/«ревью кода»), а последующее код-ревью +(§2.7) потребует таблицу «AC · чем доказан · чем краснеет» — но в +доступном виде оно уже должно быть заложено на этапе ТЗ, как это сделано +для AC1–AC5, AC7–AC9 через §8.1–§8.5. + +Для AC1–AC5 и AC7–AC10 каждое утверждение имеет прямую привязку к +конкретному пункту §8 (представитель, отрицательный тест или таблица +случаев). Для AC6 такой привязки нет: §8.1 перечисляет представителей всех +шести проверок (`frontend` через `src/**` там не фигурирует ни разу как +объект отрицательного теста), а §5.3 лишь описывает механизм («ключ = хеш +`inputsOf(job)`, `sourceFingerprint` уходит») без утверждения, что где-то +проверяется обратное: что правка файла из `src/**` **не** меняет ключ +`backend` после финального коммита. + +**Сценарий отказа:** реализация выполняет AC1–AC5, AC7–AC10 с тестами, но +финальный коммит AC6 сводится к удалению строки `source: +sourceFingerprint(root)` из вычисления ключа `backend` без теста. Регресс +(кто-то по невнимательности вернёт эту строку в будущей правке +`check-inputs.mjs`, или `inputsOf('backend')` по ошибке продолжит включать +`src/**` через общий `source`-манифест) не поймает ни один автотест — +ровно то поведение, которое всё ТЗ ставит целью исключить («Зелёный вердикт +обязан означать, что именно этот код проверен»), окажется непроверенным +для собственного шестого критерия. + +**Почему это Medium, а не High:** AC6 не блокирует остальные девять +критериев и не делает ТЗ невыполнимым — пробел локален и дёшево чинится: +одна строка в §8.1 (представитель — файл `src/**`, например +`src/houseplan-card.ts`; ожидание — ключ `backend` **не** меняется, ключ +`frontend`/`smoke` меняется) плюс одноимённый пункт в перечне тестов §12 +(`test/gate-reuse.test.mjs`). Находка в скоупе задачи (сам AC6 уже в §10) — +чинится в этом же ТЗ, отдельный issue не заводится. + +## Что проверено и корректно + +- Все пять пунктов раздела «Проблема» (§1) фактически подтверждены чтением + кода на процитированном SHA `ea6061e9` — ни одно не оказалось домыслом + (детали — выше, «Как проверялось»). +- Скоуп/не-скоуп (§2/§3) чётко разграничивают протокол проверки от + содержания самих проверок и от продуктового кода; при обнаружении + продуктового дефекта явно предписан отдельный issue — соответствует + правилу «Medium вне скоупа = новый issue» на будущее код-ревью. +- §4 (точный кандидат) корректно устраняет реальный, только что + подтверждённый чтением дефект — push без проверки между ребейзом и push; + алгоритм п.1–7 покрывает все ветвления (dev не двигался / двигался с + равным patch-id / двигался с другим patch-id / Validate красный / lease + отклонён / попытки исчерпаны), и каждое ветвление имеет счётчик выхода в + статус (`S6`/`S7`/`S8`) без зависания. +- §6 (замыкание входов гарда) адресует ровно найденный технический дефект + (10 из 35 гардов без третьего аргумента, `trail-resume-test-guard.mjs` + скрывает пути тестов) явно объявляемым `GUARD_INPUTS` и статическим + замыканием импортов — реализуемо без исполнения кода на этапе отбора. + Точечность выбора по стороне патча внутри `src/**` явно вынесена в + не-скоуп (§3, §6.4) — не оставлена недосказанной. +- §7 (ночной прогон) — минимальная точечная правка, устраняющая + единственный названный дефект (успех в момент постановки в очередь). +- §9 (откат) корректен для infra-задачи без продуктового кода: revert + коммитов, отдельно назван риск устаревания старых маркеров реюза (один + лишний полный прогон, не сбой). +- Раздел «Принятые предположения» (§13) содержит только технические решения + (эквивалентность Validate на ветке проверке дерева; PAT остаётся PAT; + порядок реализации) и явно помечен как «принято предположительно, + поменять свободно» — соответствует PROCESS.md §7.1: продуктовых вопросов + к владельцу нет и не должно быть, поскольку задача не имеет + пользовательской поверхности в смысле `docs/SCOPE.md`. +- AC1–AC5, AC7–AC10 однозначны и проверяемы, каждый имеет прямую привязку к + конкретному отрицательному тесту или таблице случаев в §8. +- Формат ТЗ и связь issue ↔ ТЗ ↔ README соблюдены; трек (полный, не + `small`) выбран верно — задача касается четырёх поверхностей протокола + CI одновременно, что явно нарушает критерий «одна поверхность» лёгкого + трека (сам ТЗ называет это прямо: «Трек: полный … без файлов класса A»). + +## Чего не проверял + +- Реализацию по существу — на этом этапе её нет, в diff'е только + `docs/specs/**` и `docs/specs/README.md` (оба класса C). Код-ревью + впереди. +- Точный подсчёт «10 из 35» гардов без третьего аргумента (§1 п.4) — вручную + не пересчитывал каждое из 35 вхождений `backend-test-guard.mjs` в + `mutation-gate.mjs`; подтверждён факт существования дефолтного значения и + порядок величины через `grep -c`, этого достаточно для проверки + формулировки проблемы, но не является независимым пересчётом точного + числа. +- Достижимость таймингов §10.2 (5–8 мин ожидания Validate внутри ревью-job, + лимит 45 мин, «десятки минут в 3 шардах» для расширенного отбора + мутантов) — это оценки автора на будущее, эксплуатационная проверка + относится к пост-мержу/код-ревью, не к ТЗ. +- Тяжёлые гейты (`golden`, `smoke`, `performance_smoke`, backend pytest) — + не прогонялись: diff класса C, изменений в `src/**`/`custom_components/**` + нет, гейты нерелевантны этапу и типу изменений. +- Прецеденты #472/#475/#481 проверены только по метаданным issue + (`gh issue view`: заголовок, метки, состояние) и списку файлов + `docs/reviews/` — содержимое их спек-документов построчно не сверялось с + #492, кроме одного (`SPEC-REVIEW-481-r1.md`), прочитанного как образец + формата и калибровки серьёзности находок для infra-специфики. + +## Вердикт + +Жёлтый. High: 0, Medium: 1 (в скоупе задачи — чинится в этом же ТЗ, отдельный +issue не заводится). Пробел дешёвый: одна строка в §8.1 плюс один тестовый +файл в §12. + +--- + + + +## Материал раунда + +- Ветка: `issue/492-exact-candidate-and-input-manifest`, коммит `941c7cff7a1b` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `b9b9b1a2171c2cafd5f24cf83b1d6c5baa2fbb6b` + ``` + git log --all --format='%H %T' | grep b9b9b1a2171c + ``` +- ТЗ `docs/specs/492-exact-candidate-and-input-manifest.md`, блоб `2fcaeb946e984a30e0188a15ebed904eb3d31b7d` + ``` + git log --all --find-object=2fcaeb946e984a30e0188a15ebed904eb3d31b7d -- docs/specs/492-exact-candidate-and-input-manifest.md + ```