docs: review document for #748

Issue: #748
User-Visible: no

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-<sha12>.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-<sha12>` (имя документа без
+  префикса `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 <base> --head <head>` как отдельная команда не
+  запускался — его прогнал `gate:small` внутри себя с тем же результатом (ноль смоков).
+- Performance-профили — не названы в АС, не гонял.
+- Остальные упоминания «перед бетой» вне четырёх мест п.4 (PROCESS.md §5/§10.4/§11.7,
+  `ship-review.mjs`, `reviews-index.mjs`, `mutation-registry.mjs`) не предмет этой задачи
+  (см. «Как проверялось») — не перепроверял глубже само́й формулировки.
+
+---
+
+<!-- material-anchors: сгенерировано конвейером (#414) -->
+
+## Материал раунда
+
+- Ветка: `issue/748-canon-reconcile`, коммит `c099c4dda0a0` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
+- Дерево материала: `3f4ae17e493534020857650186910884fd1edb1b`
+  ```
+  git log --all --format='%H %T' | grep 3f4ae17e4935
+  ```
+- Тело issue: `f13eeaa6a21cf6847ca3050e8cdf314c293abd2796714243f1800f224b9e5000`
+- Вердикт конвейера: `green` · High 0 · маршрут `fix`
+<!-- hp:usage input_tokens=5175 output_tokens=19571 cache_creation_input_tokens=79647 cache_read_input_tokens=2626689 num_turns=41 -->