From 134a7029b4951d059f8f170c3ac10c683ceda96b Mon Sep 17 00:00:00 2001 From: "claude[bot]" <209825114+claude[bot]@users.noreply.github.com> Date: Thu, 1 Oct 2026 14:31:17 +0000 Subject: [PATCH] docs: review document for #748 Issue: #748 User-Visible: no --- docs/reviews/CODE-REVIEW-748-r1.md | 144 +++++++++++++++++++++++++++++ 1 file changed, 144 insertions(+) create mode 100644 docs/reviews/CODE-REVIEW-748-r1.md diff --git a/docs/reviews/CODE-REVIEW-748-r1.md b/docs/reviews/CODE-REVIEW-748-r1.md new file mode 100644 index 00000000..2765693d --- /dev/null +++ b/docs/reviews/CODE-REVIEW-748-r1.md @@ -0,0 +1,144 @@ +# CODE-REVIEW #748 · заход r1 + +**Материал.** `origin/dev..HEAD`, один коммит `c099c4dda0a0b5be8aec99b31e24d3c41b951559` +(`fix(process): reconcile canon and hints with the pipeline after #707–#730 (#748)`). +Трейлеры: `Issue: #748`, `User-Visible: no` — верно, изменение процесса/документации, +продуктового поведения не касается. Трек: `show`. Validate на этом SHA зелёный +(https://github.com/Matysh/houseplan-card/actions/runs/36875387474) — `tsc --noEmit`, +`npm test`, `npm run build` повторно не гонялись, взяты с этой ссылки. + +## Скоуп + +Пять мелких расхождений канона/подсказок/кода, найденных при реализации #707–#730: + +1. подсказка `S3` в `scripts/task-packet.mjs` звала пушить ветку ТЗ, хотя с #517 ТЗ + живёт в теле issue и до `S5` ничего не пушится (§11.8); +2. правило 9 в `process-gate.mjs` («Gates: light») не соответствовало PROCESS.md §10.2, + где п.9 — нереализованный `release:prerelease`-чек; трейлер `Gates:` не писался и не + читался никогда; +3. §10.4 п.4 требовал heredoc в `run:`, тогда как #723/#730 и их тесты требуют обратного; +4. четыре места (`_process.yml`, `AUTHOR.md`, `REVIEWER.md`, `AGENTS.md`) называли только + пред-бета документ `SHIP-REVIEW-<тег>.md`, хотя с #727 ночь читает ship-код первой; +5. коммит ночной публикации ship-ревью нёс бета-текст и `Issue: #696` вместо своего. + +Плюс попутное исправление `docs/testing-notes/mutation-browser-guards.md`: счётчик +`200` — ориентир (#699), а не жёсткий потолок, таблица приведена к факту (205/200, +lifecycle 90). + +## Как проверялось + +- Прочитан полный диапазон `git diff origin/dev...HEAD` (14 файлов, +115/-33). +- Прочитано тело issue #748 (ТЗ, АС1–АС3, «Принято предположительно», «Кандидаты») и три + комментария (оценка, взятие в работу, «Сделано»). +- `PROCESS.md` §10.2 прочитан целиком (`1130–1234`) — сверена нумерация пунктов + (реализовано 1–8,10; «Не реализовано»: 9) с новым `RULES` в `process-gate.mjs`. +- Запущены юнит- и bash-тесты: `node --test test/process-gate.test.mjs + test/task-packet.test.mjs test/process-track.test.mjs test/ship-review.test.mjs` + (134/134 зелёных, включая bash-тест AC2 на настоящем git/bash). +- `npm run gate:small` — зелёный целиком (сборка+typecheck, no-new-any, + no-new-private-writes, smoke-select, юниты, bundle-policy, lint:unused); `smoke-select` + подтвердил: «исполняемого frontend-диффа нет — смоки этим диффом не выбираются». +- `node scripts/mutation-gate.mjs --check` — exit 0, `browser guards: 205/200` (WARN, не + FAIL) — подтверждает и новый код гейта, и правку `mutation-browser-guards.md`. +- **Доказательство «тест умеет падать» (AC1).** Временно откачены к `HEAD^` + (`d8e09cd1`) только продуктовые файлы `scripts/process-gate.mjs` и + `scripts/task-packet.mjs` (тесты и прочий код — текущие); прогон + `test/process-gate.test.mjs test/task-packet.test.mjs` дал 3 красных теста — ровно + три новых теста #748 AC1 (`#748 AC1: номера RULES…`, `#748 AC1: мёртвого трейлера…`, + `#748 AC1: подсказка S3…»`), остальные 71 зелёные. Файлы возвращены к `HEAD`, + рабочая копия чистая (`git status --short` пуст). +- AC2 доказан тем же прогоном: `test/publish-push-refusal.test.mjs` — реальный bash, + реальный git-сэндбокс, сверка сообщения коммита и состава файлов построчно. +- AC3 — разбор чтением: §10.4 п.4 переписан текстом, который требуют действующие тесты + (#723/#730/#727/#736, все выполнены выше); четыре места названы ночь + + `SHIP-REVIEW-<база>-dev-.md`; оставшиеся упоминания «перед бетой» вне этих + четырёх мест (`PROCESS.md` §5/§10.4/§11.7, `scripts/ship-review.mjs`, + `scripts/reviews-index.mjs`, `scripts/mutation-registry.mjs`) — не канон, а + заголовки/комментарии кода, описывающие именно бета-режим или историю, а не + утверждающие отсутствие ночи; ТЗ п.4 «Меняется» называет ровно эти четыре места, и + автор прямо раскрыл остальные в «Кандидаты» — не находка, корректно оставлено вне + скоупа. +- Проверено отсутствие осиротевших следов: `grep -rn "Gates: light\|RULES\[9\]\|'Gates'"` + по `scripts/`, `test/`, `docs/`, `PROCESS.md`, `AGENTS.md`, `.github/` — только в + тексте нового контрактного теста (ожидаемо). + +## Находки + +### Low — стала строка-комментарий в `process-gate.mjs:183` + +`scripts/process-gate.mjs:183`: `// --- проверки по одному коммиту: 1, 4, 5, 6, 9 ---` +прямо над `evaluateCommit`. Это и есть функция, из которой задача убрала обе проверки +«Gates: light» (правило 9) — но заголовок комментария правило 9 всё ещё перечисляет. +Поведения не меняет, тестом не проверяется, путаницы на практике не создаёт (правила +в `RULES` теперь не содержат ключ 9, и первое же чтение `RULES` это показывает) — +поэтому Low, а не Medium: это ровно тот класс несоответствия, который задача и была +призвана устранять, но дешёвая правка (убрать «, 9») была пропущена в этом же файле. +Снимается с записью: следующая правка этой функции может поправить заодно; блокировать +зелёный вердикт из-за одной цифры в комментарии несоразмерно объёму задачи (§8). + +## Что проверено и корректно + +- **AC1.** `rightsFor('S3-spec')` в `task-packet.mjs` даёт подсказку без «push ветки», + со `S4-spec-review` и ссылкой на §11.8 — текст совпадает с ТЗ дословно. + `RULES` в `process-gate.mjs` — ключи `{0,1,2,3,4,5,6,7,8,10}`, что равно реализованным + пунктам §10.2 (список п.1–8,10) минус «Не реализовано» (п.9); поле `gates` и обе + проверки трейлера `Gates: light` удалены из `makeCommit`/`evaluateCommit` целиком. + Новый тест `#748 AC1: номера RULES…` берёт пункты §10.2 из самого канона регулярным + разбором (`### 10.2` … `### 10.3`, срез по «Не реализовано») и действительно привязан + к тексту файла, а не к хардкоду — переименование пункта в PROCESS.md без синхронной + правки `RULES` этот тест уронит. +- **AC2.** Шаг «Опубликовать документ» `_ship-review.yml:329–372` ветвится по `MODE`: + `nightly` → заголовок `docs: nightly ship review <база>-dev-` (имя документа без + префикса `SHIP-REVIEW-` и расширения, через `${DOC##*/SHIP-REVIEW-}` и `${night%.md}`), + тело «Ночное пакетное ревью…», `Issue: #727`; иначе — бета-текст и `Issue: #696` + без изменений. Оба собираются `echo`-построчно в файл, heredoc не добавлен. Тест + `test/publish-push-refusal.test.mjs` (`#748 AC2`) гоняет это на настоящем bash+git + сэндбоксе и сверяет итоговое сообщение коммита в `dev` побайтово. +- **AC3.** PROCESS.md §10.4 п.4 переписан абзацем, который описывает фактический код + (построчный `echo` в файл для сообщений коммитов, текст из скрипта для комментариев/ + сводок, heredoc только в непеределанных старых шагах) и даёт вторую причину (текст из + кода проверяет тест, из YAML — нет). Четыре места (`_process.yml:1770/1774`, + `AUTHOR.md:248–250`, `REVIEWER.md:171–174`, `AGENTS.md:94–97`) теперь называют оба + документа ship-ревью. Машинные маркеры `hp:ship-merge`/`hp:ship-risk` не тронуты; + единственный оставшийся heredoc шага решения по вердикту + (`test/process-track.test.mjs:1001`) не убирался — это prior art, не предмет задачи. +- **Побочная правка `mutation-browser-guards.md`.** Таблица (4+4+26+45+36+90=205) точно + совпадает с выводом `mutation-gate.mjs --check` (`browser guards: 205/200`, WARN), а + формулировка «ориентир, не стена» совпадает с кодом гейта (`exit 0` при превышении). +- Коммит один, трейлеры `Issue: #748` и `User-Visible: no` на месте; changelog не тронут + и не должен быть — правка не видна пользователю продукта. +- Критерии §5 маршрута: сложность/риск низкие (пять точечных текстовых правок и снятие + мёртвой проверки), одна поверхность (конвейер ревью/процесса), миграции конфигов нет, + нового UX-контракта нет, производительности и touch не касается, ожидаемое поведение + уже зафиксировано в PROCESS.md/AGENTS.md и коде #517/#723/#727/#729/#730 — маршрут + `fix` подтверждён. + +## Чего не проверял + +- `npx tsc --noEmit`, `npm test`, `npm run build` отдельно не гонял — дешёвые гейты уже + подтверждены зелёным Validate на этом SHA (ссылка выше); `npm test` и сборку повторно + перегонял только точечно через `gate:small` (он их включает) для независимой проверки. +- Браузерные смоки, `golden:verify`, `python -m pytest`, `npm run invariants` — + не прогонял: диффа во frontend/рендере/геометрии/Python нет (`smoke-select` сам это + подтвердил: «исполняемого frontend-диффа нет»), в АС они не названы. +- `node scripts/smoke-select.mjs --base --head ` как отдельная команда не + запускался — его прогнал `gate:small` внутри себя с тем же результатом (ноль смоков). +- Performance-профили — не названы в АС, не гонял. +- Остальные упоминания «перед бетой» вне четырёх мест п.4 (PROCESS.md §5/§10.4/§11.7, + `ship-review.mjs`, `reviews-index.mjs`, `mutation-registry.mjs`) не предмет этой задачи + (см. «Как проверялось») — не перепроверял глубже само́й формулировки. + +--- + + + +## Материал раунда + +- Ветка: `issue/748-canon-reconcile`, коммит `c099c4dda0a0` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет. +- Дерево материала: `3f4ae17e493534020857650186910884fd1edb1b` + ``` + git log --all --format='%H %T' | grep 3f4ae17e4935 + ``` +- Тело issue: `f13eeaa6a21cf6847ca3050e8cdf314c293abd2796714243f1800f224b9e5000` +- Вердикт конвейера: `green` · High 0 · маршрут `fix` +