houseplan-card/docs/reviews/SPEC-REVIEW-454-r1.md

# SPEC-REVIEW — issue #454 · заход r1

- Issue: https://github.com/Matysh/houseplan-card/issues/454
- Этап: ТЗ на ревью (PROCESS.md §2.4), заход r1, блокирующих циклов израсходовано 0 из 4 (лимит полный, `small`/`trivial` не стоят)
- Материал: `docs/specs/454-review-round-counter.md` на коммите `ebcf1223` (комментарий «ТЗ готово», ветка `issue/454-review-round-counter`)
- Ревьюер: свежая сессия, без контекста написания ТЗ

## Скоуп

Issue описывает дефект в `guard`-джобе `.github/workflows/process.yml`: счёт
`attempt`/`spent` идёт по regex над телом комментария-вердикта, и вердикт без
явной подстроки `SPEC-REVIEW`/`CODE-REVIEW` в тексте выпадает из подсчёта
навсегда — что уже привело к перезаписи `docs/reviews/SPEC-REVIEW-449-r1.md` и
к занижению бюджета циклов. ТЗ предлагает считать оба числа по опубликованным
файлам `docs/reviews/${marker}-${NUM}-r*.md` на ветке задачи (`attempt` — от
максимального номера файла плюс один, не от их количества), со страховкой
«максимум из счёта по файлам и счёта по комментариям» на случай отказа шага
публикации.

Класс изменения — B (инфраструктура): трогаются только
`.github/workflows/process.yml` и `scripts/review-doc-guard.mjs` /
`test/review-doc-guard.test.mjs`. Ни одного файла класса A нет, то есть по
механическому признаку AGENTS.md/PROCESS.md §1 задача могла бы идти вне флоу
вовсе (без ТЗ и его ревью). Автор в комментарии `S2-analysis` (2026-09-04)
сознательно выбрал полный трек, назвав причину — правка меняет механизм,
который управляет всеми остальными задачами, и ошибка в нём стоит дороже
обычной инфраструктурной правки. Это решение владельца/автора по существу
задачи, а не нарушение процесса, и не является предметом этого ревью.

`docs/SCOPE.md` к этой задаче неприменим по смыслу: правка не служит ни одному
Core user job — это внутренний инструмент конвейера ревью, не продуктовая
функция. Отмечаю это, а не пропускаю проверку молча.

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

- Прочитаны `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` (целиком, включая §2.10,
  §4, §7.1, §8, §10–12).
- Прочитано тело issue #454 и оба комментария (`S2-analysis` владельца,
  «ТЗ готово» автора).
- Прочитан `docs/specs/454-review-round-counter.md` целиком.
- Сверены факты ТЗ с текущим кодом на `dev` (`git show origin/dev:...`):
  - `.github/workflows/process.yml` — блок `guard`/`decide` (строки ~60–164),
    построение имени документа `doc="docs/reviews/${marker}-${NUM}-r${CYCLE}.md"`
    (строки 661, 803), шаг резолва ветки задачи (строки ~211–225);
  - `scripts/review-doc-guard.mjs` — весь файл: существующие три режима CLI
    (`--allow=`/stdin, `--anchor=`, `--doc=`) и их назначение (allowlist пути
    публикации, дозапись якорей материала, проверка осиротевших SHA);
  - реальный формат строки вердикта в опубликованном документе
    (`docs/reviews/CODE-REVIEW-450-r1.md` на `dev`) — подтверждено, что строка
    `Вердикт:` встречается ровно один раз и в конце документа, заголовок
    `## Вердикт` подстроку `Вердикт:` не даёт.
- Прослежена арифметика контракта (§1–§3 ТЗ) вручную на реальной хронологии
  #449 из комментария владельца (таблица времени/вердиктов/наличия маркера) —
  см. находку M1 ниже.

Код не читался как продукт (ветки реализации ещё нет — этап `S4-spec-review`,
`scripts/review-doc-guard.mjs` и `process.yml` на ветке задачи ещё не изменены
относительно `dev`). Это ревью ТЗ, не код-ревью.

## Находки

### M1 (Medium, в скоупе) — AC2 не доказуем тем способом, который сам называет

**Формулировка AC2:** «Вердикт без маркера в теле больше не занижает ни
`attempt`, ни `spent`: сценарий #449 (r1 без маркера, r2 с маркером) даёт
`attempt=3`, `spent=2»`, доказательство — «unit на фикстуре реальных данных
#449». План тестирования уточняет: «фикстура «как на #449» строится из
реальных заголовков документов и строк вердиктов».

**Проблема.** Реальная история #449 (таблица в комментарии `S2-analysis`
владельца) даёт для spec-этапа ровно три вердикта:

| Время | Вердикт | Маркер в теле |
|---|---|---|
| 14:46 | жёлтый, «заход r1» | нет |
| 14:56 | жёлтый, «заход r2» | да |
| 15:17 | зелёный, «заход r3» | да |

Из-за бага документ `SPEC-REVIEW-449-r1.md` физически перезаписан: под этим
именем сейчас лежит содержимое **второго** раунда (жёлтый), а третий раунд
лежит под именем `-r2.md` (зелёный). Оригинальное содержимое первого раунда
(тоже жёлтое) сохранилось только в старом git-блобе `1ce62613`, вне рабочего
дерева — и его восстановление ТЗ прямо выносит в «не-скоуп» («восстановление
затёртого документа… отдельная ручная операция владельца, к механизму не
относится»).

Если строить фикстуру **буквально** из реальных, то есть сейчас существующих
на ветке файлов (`-r1.md` = жёлтый, `-r2.md` = зелёный) и применить контракт
§1–§3 ТЗ:

- `attemptFromFiles = max(1, 2) + 1 = 3` — совпадает с AC2;
- `spentFromFiles` = число файлов с блокирующим вердиктом = **1**
  (`-r1.md` жёлтый; `-r2.md` зелёный не считается) — **не совпадает** с
  заявленным `spent=2`;
- страховка `spentFromComments` (правило контракта §3, не изменяется) даёт то
  же самое: `of_stage` по маркеру = [комментарий 14:56, комментарий 15:17],
  `blocking` = только 14:56 (жёлтый) = **1**. `max(1, 1) = 1`.

Иными словами: подлинность «жёлтый» первого раунда физически утрачена вместе
с его файлом, и ни счёт по файлам, ни счёт по комментариям (комментарий 14:46
не несёт маркера — это и есть исходный баг) не могут её восстановить. Это не
ошибка алгоритма — это прямое следствие того, что данные уже потеряны, и сам
же документ признаёт это в «не-скоупе». Но тогда посчитанное по **реальным**
данным #449 значение — `spent=1`, а не `2`, как утверждает AC2.

Число `spent=2` достижимо только на **реконструированной** фикстуре: два
отдельных, никогда не перезаписывавшихся файла (`-r1.md` и `-r2.md`), оба с
вердиктом «жёлтый» — то есть на данных, которые не являются «реальными данными
#449» в буквальном смысле, а представляют, как выглядела бы история #449,
если бы коллизии имён не произошло. План тестирования не говорит, какое из
двух прочтений имеется в виду, а расхождение материально: разработчик,
построивший фикстуру по первому (буквальному) прочтению, получит
подтверждённый унит-тестом `spent=1` и не будет знать, ошибка это в реализации
или в самом AC — до следующего раунда ревью.

**Как воспроизвести рассуждение:** взять реальные три вердикта и два реальных
файла #449 (перечислены выше), применить формулы контракта §1–§3 ТЗ вручную —
результат `attempt=3, spent=1`, а не `attempt=3, spent=2`.

**Что нужно поправить.** Явно указать в AC2/плане тестирования одно из двух:
(a) фикстура — два независимых, не перезаписанных документа с вердиктом
«жёлтый» у обоих (тогда `spent=2` доказуемо, но это не «реальные данные
#449», а реконструкция «как должно было быть»); либо (b) фикстура — буквально
текущее состояние ветки #449, и тогда ожидаемое значение — `attempt=3,
spent=1`, а способность корректно посчитать «сколько удаётся восстановить»
(не «сколько было на самом деле») — это и есть то, что стоит проверять и
описывать. Второй вариант честнее: он проверяет ровно то, что новый механизм
физически способен дать при уже случившейся потере данных, не обещая
невозможного.

Из скоупа задачи (спецификация того же issue #454), без High-находок —
жёлтый вердикт с возвратом автору.

### L1 (Low, снимается с записью) — нет явных разделов «UX» и «i18n»

`PROCESS.md` §7.1 перечисляет обязательные разделы ТЗ, включая «UX» и «i18n»
отдельными пунктами. В документе нет ни одного из них как самостоятельного
раздела (headers): «UX» частично закрыт строкой в шапке `Touch editor: not
exposed — задача не касается интерфейса вовсе», «i18n» не упомянут вовсе ни
разу.

Не блокирует и не создаёт риска: задача не трогает ни одного файла с
интерфейсом или строками (`src/**`, `i18n/*.json`), это прямо следует из
раздела «Класс изменения» и списка задеваемых файлов, и вывод «i18n/UX не
затронуты» очевиден по содержанию, а не додуман. Снимаю находку с записью, а
не требую правки: добавление двух формальных строк-заглушек «UX: нет» / «i18n:
нет» было бы ритуалом без содержания. Если следующий раунд правит документ по
M1, было бы уместно добавить эти строки заодно (не отдельным циклом).

### L2 (Low, к сведению, не в счёт вердикта) — cohesion `review-doc-guard.mjs`

`scripts/review-doc-guard.mjs` сейчас узко специализирован — заголовок модуля
прямо говорит «публикация ревью-документа не имеет права трогать ничего, кроме
него» (проверка путей пуша, дозапись и проверка якорей материала). ТЗ
добавляет туда четвёртую, содержательно не связанную обязанность — счёт
`attempt`/`spent` для `guard`-джоба, который отрабатывает **до** публикации и
даже до самого ревью. Технический вопрос именования/расположения модуля —
это то, что PROCESS.md §7.1 явно отдаёт автору («где стоит гвард… агенты
решают сами»), поэтому не поднимаю его до статуса находки, требующей правки, а
оставляю как наблюдение: отдельный файл (например
`scripts/review-round-counter.mjs`) сделал бы границу ответственности яснее и
не расширял бы область, которую уже покрывает существующее название и
докстринг. Автор/ревьюер кода вправе оспорить это на следующем этапе без
возврата сюда.

## Что проверено и корректно

- **Контракт §1 (источник истины — файлы, `max+1`, а не количество).**
  Проверено рассуждением на реальных данных #449 и на таблице крайних случаев
  «Ошибки и крайние случаи»: дыра в нумерации (`r1`, `r3`) корректно даёт
  `attempt=4`, поведение при пустом множестве файлов (`attempt=1, spent=0`)
  совпадает с сегодняшним умолчанием `attempt=1` в `process.yml:93`.
- **Контракт §2 (строка вердикта, `жёлт`/`красн` без учёта регистра).**
  Совпадает с существующим правилом `process.yml:100` («blocking» через тот
  же regex `(жёлт|красн)`, `i`), не меняет то, что уже работает верно для
  идентификации блокирующих вердиктов внутри одного документа — подтверждено
  на реальном файле `CODE-REVIEW-450-r1.md` (единственное вхождение строки
  `Вердикт:` — финальная, помеченная как искомая).
- **Контракт §3 (страховка максимумом).** Само правило корректно устраняет
  риск «перерасчёта», которого боялся автор исходного механизма
  (`process.yml:88-93`): максимум из двух счётов не может дать значение выше
  фактического числа опубликованных документов/вердиктов ни при каком их
  сочетании — арифметически `max(a,b) ≤ true`, только если оба источника не
  завышают, что для обоих верно по построению (ни файлы, ни комментарии не
  порождают лишних записей).
- **AC1, AC3–AC7.** Формулировки однозначны, способ доказательства (unit,
  частично + мутант) указан и достижим — не нашёл ни одного нереализуемого
  условия среди них при том же рассуждении, что для M1 (AC4/AC5/AC7
  дополнительно совпадают с уже работающими сегодня инвариантами #227/#89,
  которые контракт §5 явно объявляет неизменными).
- **Не-скоуп.** Явно и корректно исключает правку задним числом чужого
  комментария и восстановление утраченного `SPEC-REVIEW-449-r1.md` —
  соответствует «владелец решает вручную», не додумано автором.
- **Ограничение «`process.yml` идентичен в `main` и `dev`»** учтено в разделе
  «Карта реализации» (п. 5) и в разделе рисков; соответствует существующему
  шагу Validate, который эту идентичность проверяет — не проверял сам шаг
  Validate заново, доверяю его существованию по цитате в ТЗ (совпадает с тем,
  что описывает `PROCESS.md`/комментарий автора при `S2-analysis`).
- **Откат.** План (один коммит-ревёрт `process.yml` плюс зеркало в `main`,
  скрипт и тесты безвредны сами по себе) реалистичен и не требует миграции
  данных — подтверждаю чтением, без исполнения (откатывать нечего, кода ещё
  нет).
- **Release-артефакты.** `User-Visible: no`, трейлеры корректны для класса B;
  условие обновления `PROCESS.md` («если он описывает нынешний механизм
  подсчёта по комментариям») сверено с текстом `PROCESS.md` — документ
  обсуждает разделение `attempt`/`spent` концептуально (§4, §2.10), но не
  описывает реализацию «regex по телу комментария», поэтому условие, скорее
  всего, не сработает; это корректно оставлено условным, а не заявлено фактом.

## Чего не проверял

- Само существование и содержимое `scripts/review-doc-guard.mjs` /
  `test/review-doc-guard.test.mjs` **на ветке задачи** — на момент этого
  ревью ветка `issue/454-review-round-counter` содержит только
  `docs/specs/454-review-round-counter.md` (по коммиту `ebcf1223`, «ТЗ
  готово»), реализации ещё нет — это ожидаемо для этапа `S4-spec-review`, не
  пропуск.
- Гейты (`typecheck`/`test`/`build`) не гонял: класс изменения — документация
  ТЗ, кода нет вовсе, гонять нечего. `check-docs`/`golden`/смоки/`invariants`
  неприменимы — diff не касается `src/**`, геометрии, визуала или бэкенда.
- Не проверял исполнением, действительно ли `gh api`/`git ls-remote` способны
  без `actions/checkout` перечислить файлы `docs/reviews/` на произвольной
  ветке из `guard`-джоба (контракт §4 ТЗ) — формально это описано в «Карте
  реализации» как `gh api`, что технически осуществимо (REST `contents`
  эндпоинт не требует локального дерева), но сам вызов не выполнял; это
  техническая деталь реализации, а не продуктовое ограничение, и её вправе
  уточнить автор на этапе кода.
- Не проверял, как именно единственный существующий на сегодня файл
  `docs/reviews/CODE-REVIEW-449-r1.md` (единственный опубликованный документ
  на код-этапе #449) поведёт себя под новым алгоритмом — не требовалось для
  находки M1, которая полностью доказывается на spec-этапе; арифметика
  code-этапа (`attempt=2, spent=1`, что совпадает с ожиданием автора в
  комментарии `S2-analysis`) проверена мысленно и расхождений не показала.

## Итог

Один Medium в скоупе (M1: AC2 недоказуем буквальным прочтением собственной
формулировки — конкретное числовое расхождение показано выше), High —
ноль. Остальные девять AC однозначны и доказуемы описанным способом. Low
L1 снимается с записью, L2 — наблюдение вне вердикта. Вердикт — жёлтый,
возврат автору на уточнение AC2 (одна строка/абзац, не переписывание ТЗ).

---

## Материал раунда

- Ветка: `issue/454-review-round-counter`, ТЗ прочитано на коммите `ebcf1223`
  (тот же SHA, что указан автором в комментарии «ТЗ готово»).
- Сверка с базовым состоянием — `origin/dev` на момент ревью (см. «Как
  проверялось»): `.github/workflows/process.yml`, `scripts/review-doc-guard.mjs`,
  `docs/reviews/CODE-REVIEW-450-r1.md`.
- Воспроизвести факты о #449, использованные в M1:
  ```
  gh issue view 449 --repo Matysh/houseplan-card --json comments
  gh issue view 454 --repo Matysh/houseplan-card --json body,comments
  git show origin/dev:.github/workflows/process.yml
  git show origin/dev:scripts/review-doc-guard.mjs
  git show origin/issue/454-review-round-counter:docs/specs/454-review-round-counter.md
  ```

---

<!-- material-anchors: сгенерировано конвейером (#414) -->

## Материал раунда

- Ветка: `issue/454-review-round-counter`, коммит `ebcf12233af7` — ребейз его осиротит, и это нормально: ниже якоря, которые ребейз не меняет.
- Дерево материала: `e7a2554603963e6da4f3aa44b30502dc852a43f1`
  ```
  git log --all --format='%H %T' | grep e7a255460396
  ```
- ТЗ `docs/specs/454-review-round-counter.md`, блоб `730f7f3964e2269e7f867bedfde50290afe9a1a9`
  ```
  git log --all --find-object=730f7f3964e2269e7f867bedfde50290afe9a1a9 -- docs/specs/454-review-round-counter.md
  ```