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

# SPEC-REVIEW-385-r1

- Issue: https://github.com/Matysh/houseplan-card/issues/385
- Этап: ТЗ на ревью (PROCESS.md §2.4)
- Артефакт под ревью: `docs/specs/385-audit-lows.md`, ревизия 1 (2026-08-30),
  коммит `c28b2f2d` ("docs: specify #385 audit-lows batch")
- Заход: r1 · блокирующих циклов израсходовано 0 из 4 (до этого вердикта)
- Ревьюер получил issue и ТЗ без устных пояснений автора (§2.4)

## Скоуп

Четыре точечные правки из adversarial-аудита v1.69.0:

- (а) `houseplan-editor-runtime.ts` — клик по уже выбранному binding-кандидату
  безусловно сбрасывает `value_source`/`value_badge`;
- (б) `devices.ts` — `rewriteMarkerControlReferences` пишет фантомный ключ
  `value_source: undefined`;
- (в) `scripts/process-gate.mjs` — `releaseSourceViolationsOf` считается для
  каждого коммита диапазона, а не только для релизных;
- (г) `custom_components/houseplan/import_export.py` — асимметрия форматов
  обезвреживания внешних ссылок при экспорте (полями vs удалением ключа).

Полный трек обоснован корректно: аналитика (комментарий владельца от
2026-08-30) явно называет непройденный критерий §5 — «одна поверхность»
(четыре несвязанные поверхности: фронт-UI, фронт-модель, инфраструктурный
скрипт, бэкенд), со ссылкой на прецедент SPEC-REVIEW-376-r1 H1 / #369. Это
соответствует правилу AGENTS.md: «обычный трек» без названного критерия не
основание, а здесь критерий назван.

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

Первый заход — разбор полный, дельты нет. По каждому пункту (а)–(г) код прочитан
напрямую и сверен построчно с утверждениями ТЗ (без исполнения — кода фичи ещё
нет, это стадия спецификации):

- `src/houseplan-editor-runtime.ts:11961` (`_valueBadgeForBinding`),
  `:12252-12312` (радио-ветка `virtual` и клик по кандидату `cands.map`) —
  подтверждён безусловный сброс `valueSource: null, valueSourceTouched: true`
  в обоих местах, оба вызывают `_valueBadgeForBinding`, который также
  безусловно `valueBadgeTouched: true`. Утверждение (а) точное.
- `src/devices.ts:868-892` (`rewriteMarkerControlReferences`) — прослежена
  логика: для маркера без `value_source` переменная `valueSource` остаётся
  `undefined`, и если хотя бы `controls`/`value_badge` изменились, возвращаемый
  объект собирается через `{ ...marker, controls, value_badge: valueBadge,
  value_source: valueSource }` — ключ `value_source` явно проставляется со
  значением `undefined`. Утверждение (б) точное.
- `scripts/process-gate.mjs:108-155` (`makeCommit`, `parseRecords`) и
  `:650-670` (вызов из CLI) — подтверждено: `releaseSourceViolationsOf(sha,
  files)` в `parseRecords` вызывается для каждого коммита без проверки
  релизности; `isRelease` вычисляется отдельно внутри `makeCommit`. Утверждение
  «сегодня вызывается для каждого коммита» точное — но см. находку M1 ниже про
  точность описания самого предиката релизности.
- `custom_components/houseplan/import_export.py:504-519` — подтверждена
  асимметрия форматов (`badge["enabled"] = False; badge["source"] = None`
  против `marker.pop("value_source", None)`), оба пути инкрементируют
  `dropped_marker_links`. Утверждение (г) точное.
- `docs/specs/378-value-face-source.md:85` — подтверждена ссылка «при явной
  смене HA binding в диалоге старый `value_source` сбрасывается»: контракт (а)
  действительно возвращает поведение к букве спеки #378, а не изобретает новое.
- Существующие тесты сверены на предмет реалистичности плана автотестов:
  `test/devices.test.mjs:1900-1917` (`rewriteMarkerControlReferences`) —
  готовая база для AC3; `test/process-gate.test.mjs` (`parseRecords`,
  `isRelease`) — готовая база для AC4;
  `tests_backend/test_ha_import_export.py:1549-1589` (badge-only и
  value_source-only кейсы отдельно, но не оба сразу на одном маркере) —
  подтверждает, что AC5 — новый, не задвоенный сценарий.
- Гейты: код продукта не менялся (стадия — только ТЗ), поэтому typecheck/test/
  build не гоняю — исполнять нечего, это не пропуск, а неприменимость гейта на
  этой стадии. `node scripts/check-docs.mjs` не запускался — `src/**` не
  тронут (изменился только `docs/specs/385-audit-lows.md`, класс C).

## Находки

### Medium (в скоупе задачи — чинится в этом ТЗ, без него вердикт был бы зелёным)

**M1. Контракт (в) описывает предикат `isRelease` неполно, что рискует
разойтись с AC4.**

`docs/specs/385-audit-lows.md`, раздел «Проблема / Контракты по пунктам», (в):
> потребляется она только стабильными релизными (`/^Release v\d/` без
> beta/candidate, :134)

Фактический код, `scripts/process-gate.mjs:133-135`:

```js
isRelease:
  (/^Release v\d/.test(subject) && !/-(beta|rc|alpha)\.|candidate/i.test(subject))
  || Boolean(one('Release')),
```

Это ИЛИ из двух условий, а в тексте назван только первый дизъюнкт. Второй —
«есть трейлер `Release:` вообще» — делает `isRelease: true` для ЛЮБОГО
коммита с этим трейлером, включая бета-коммиты приёмки golden-эталонов: по
`AGENTS.md` («A commit touching demo/golden/baselines/\*\* additionally
requires: `Release: v1.62.0-beta.9`») это штатная, частая категория.
Воспроизведение:

```
git show -s --format=%B 5f6ee65768788502ffb540c0df350d8f66fe7ce2
# Release: v1.69.0-beta.5           <- трейлер есть
# subject: "test: accept explicit value source golden"  <- НЕ матчит /^Release v\d/
sed -n '133,135p' scripts/process-gate.mjs
# isRelease = (…regex…) || Boolean(one('Release'))  → true для этого коммита
```

Почему это не «мелочь оформления»: AC4 требует «классификация релизности — та
же функция, что в гейте», и если реализатор напишет НОВУЮ функцию по описанию
из текста ТЗ (только первый дизъюнкт), а не буквально вынесет существующее
выражение целиком — гейт получит расхождение. Сценарий поломки: коммит,
легитимно несущий одновременно `Issue:`, `Release: vX.Y.Z-betaN`,
`Baseline-Reviewed:` И правки `src/**` (например, фикс + принятие эталона в
одном коммите — комбинация, которую `AGENTS.md` не запрещает). При суженном
предикате `parseRecords` для такого коммита НЕ вызовет
`releaseSourceViolationsOf`, оставив `releaseSourceViolations: null`; но
`c.isRelease` (вычисленный внутри `makeCommit` по полному, немодифицированному
выражению) останется `true`. В `evaluateCommit` (:196-203) сработает ветка
`!Array.isArray(c.releaseSourceViolations) → violations = sources`, то есть
ВСЕ тронутые `src/**`-файлы будут ошибочно засчитаны как «не-версионное
изменение продукта» — ложный отказ `pre-push`/CI на легитимном коммите.

AC4 сам по себе (юнит на идентичность/переиспользование предиката) должен бы
поймать такую реализацию при код-ревью, поэтому до продакшена дефект скорее
всего не дойдёт — но именно от того, что текст ТЗ читается раньше AC и
описывает предикат неточно, растёт риск, что реализатор напишет
«упрощённую», а не «вынесенную» версию, и код-ревью придётся ловить это
постфактум вместо того, чтобы ТЗ прямо предотвратило ошибку.

**Требуется на этом раунде:** заменить фразу «потребляется она только
стабильными релизными (`/^Release v\d/` без beta/candidate, :134)» на точную:
предикат — это ВСЁ булево выражение `isRelease` (оба дизъюнкта, включая
`Boolean(one('Release'))`), и контракт (в) требует буквально вынести именно
это выражение в общую функцию, а не переформулировать его по памяти.

## Low (правится или снимается решением ревьюера — не блокирует)

**L1. «План автотестов» ссылается на несуществующий тестовый паттерн.**
Текст: «паттерн существующих тестов `_valueBadgeForBinding`». Проверено:
`grep -rn "_valueBadgeForBinding" test/` — ноль совпадений; метод не
покрыт ни одним существующим тестом (используется только в
`src/houseplan-editor-runtime.ts` и `src/houseplan-card.ts`). Технический
вопрос (стратегия теста — домен автора, PROCESS §7.1), снимаю без возврата:
реализатору предстоит написать harness с нуля, а не переиспользовать образец.
Полезно поправить текст, но не блокирует переход в `S5-ready`.

**L2. DoR-примечание не называет явно влияние на производительность.**
PROCESS.md §2.5 требует пункт «влияние на производительность и бюджеты
названо (или явно «нет»)» отдельно от touch/миграции. Текущая строка
`DoR-примечания: миграция/compatibility — нет; touch — не влияет` эту графу
пропускает, хотя пункт (в) сам по себе — перф-правка гейта (снижает число
`git show` на нерелизных диапазонах). Достаточно одной строки в этом же
разделе; не блокирует, чиню на усмотрение автора.

**L3. Формулировка «(б)–(г) — «мелкие уточнения»» в Release-артефактах
двусмысленна.** Раздел UX того же документа прямо говорит: «Пункты (б)–(г)
видимого поведения не меняют» — по конвенции `AGENTS.md` это кандидаты на
`User-Visible: no`, для которых правка changelog не требуется вовсе. Фраза
«мелкие уточнения» читается как обещание отдельных строк в пользовательском
changelog для невидимых правок, что противоречит соседнему же разделу.
Не блокирует (это описание коммит-стратегии, домен автора), но стоит явно
решить: одна строка про (а) в едином коммите (если а–г идут одним коммитом
`User-Visible: yes`), либо явное «(б)–(г) отдельными `User-Visible: no`
коммитами без changelog».

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

- Все четыре описания дефектов (а)–(г) в разделе «Проблема / Контракты»
  сверены построчно с текущим кодом и точны (см. «Как проверялось»).
- Обязательные разделы §7.1 присутствуют: сценарий, что человек увидит до/после,
  проблема+контракт, скоуп/не-скоуп, UX, модель данных/миграция, i18n, AC1–AC6
  с указанием способа доказательства, план автотестов, риски, откат,
  release-артефакты.
- Ни одно утверждение о поведении не выдано за факт без опоры: контракт (а)
  прямо ссылается на букву спеки #378 §1.6 и это подтверждено чтением
  `docs/specs/378-value-face-source.md:85`; контракт (г) явно и осознанно
  выбирает НЕ менять формат хранения («Формат хранения менять нельзя — это
  ломало бы round-trip»), с обоснованием, а не как невысказанное
  предположение.
- Открытых продуктовых вопросов нет — и это оправдано: (а) не вводит новый UX,
  а восстанавливает уже описанное поведение #378 §1.6; (б)–(г) не видны
  пользователю вообще. Ни один вопрос из вынесенных в тело ТЗ не относится к
  «что человек видит/делает» — правильно, что автор не эскалировал ничего
  владельцу.
- AC1–AC6 пронумерованы, у каждого указан способ доказательства
  (unit/smoke/pytest), формулировки однозначны (например, AC3 буквально даёт
  проверяемое выражение `'value_source' in marker === false`), для AC1/AC4
  описаны и позитивная, и регрессная ветки — тест «умеет упасть» показан
  явно через раздел «Мутанты».
- AC5 — не задвоенный сценарий: существующие pytest-тесты покрывают
  badge-only (`test_issue_90...`) и value_source-only (`test_issue_378...`)
  по отдельности, но не комбинацию на одном маркере — подтверждено `grep`.
- Откат простой и честный (`git revert`, нет флагов/миграций/персистентных
  данных) — соответствует малому риску задачи.
- i18n корректно помечен как незадетый — ни один пункт не добавляет строк
  интерфейса (проверено — п.(а) в UX-разделе прямо говорит «Новых строк нет»,
  и ни один из четырёх контрактов не описывает новый текст).

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

- Код продукта не существует на этой стадии (спека, не реализация) — гейты
  `typecheck`/`test`/`build`/`check-docs`/`invariants`/смоки/`golden:verify`
  неприменимы и не запускались; это нормально для этапа ТЗ, а не пропуск.
- Не проверял, действительно ли `_boolInput`/остальной рендер диалога маркера
  не имеет ТРЕТЬЕГО пути выбора binding помимо названных :12260 и :12308 —
  сам автор в разделе «Риски» просит ревьюера перепроверить `grep`'ом; я
  прогнал `grep -n "_valueBadgeForBinding" src/houseplan-editor-runtime.ts` и
  получил ровно два вызова внутри шаблона (:12260, :12308) плюс определение
  (:11961) — третьего пути нет. Это подтверждает риск закрытым, но не гарантирует
  отсутствие иного, не через `_valueBadgeForBinding`, места записи
  `value_source`/`value_badge` — за пределами grep по одному имени я не искал.
- Не оценивал сравнительную стоимость 2×`git show` на коммит в (в) в реальных
  цифрах (сколько коммитов в типичном диапазоне) — контракт и AC4 не требуют
  числового бюджета, только факта отсутствия лишних вызовов, этого достаточно
  для проверки.

## Вердикт

Жёлтый: одна находка Medium в скоупе задачи (M1), High нет. Возврат автору на
правку текста ТЗ (раздел «Проблема / Контракты», пункт в) — код не пишется,
правки текстовые. После правки — повторный заход по дельте (PROCESS.md §2.10):
достаточно перечитать изменённый абзац (в) и подтвердить, что предикат назван
полностью и AC4 остаётся согласован.