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

SPEC-REVIEW-43-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/43
• Ревьюер: Claude (роль «Ревьюер ТЗ», PROCESS.md §2.4)
• Материал: docs/specs/043-private-support-report.md, ревизия 2, на коммите 755fa4cf (ветка issue/43-help-feedback), плюс тело issue #43 и все 7 комментариев (аналитика 2026-08-14/2026-08-30, финальное UX-описание владельца 2026-09-01, повторная аналитика, Q1–Q5 и ответы владельца, хендофф автора «ТЗ полностью переработано»).
• Заход: r1 (первый разбор этого ТЗ, документ прежних раундов не существует — предыдущая ревизия ТЗ была отклонена самим автором в аналитике 2026-09-01, а не ревью, поэтому раздел «Унаследовано» не применяется).
• Трек: полный (аналитик явно назвал непройденные критерии small: больше одной поверхности, новый UX-контракт, новый внешний transport, privacy/security-контракт, обязательное влияние на touch-View) — лимит циклов ревью ТЗ 4, не 2.

Скоуп

ТЗ описывает новый диалог «Помощь и обратная связь» в шапке карточки: перенос блока «О карточке», языковая ссылка на USER-GUIDE, форму контакт/сообщение и opt-in обезличенный support-пакет с точной геометрией, который уходит через backend House Plan в отдельный project-controlled HTTPS-relay (новый deployable сервис support-relay/) в закрытый support-mailbox. Это первая ревизия, дошедшая до ревью; предыдущая (clipboard-only) была отозвана автором ещё в аналитике.

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

1. docs/SCOPE.md, AGENTS.md, PROCESS.md (целиком, включая §1, §2.3–2.10, §4, §7.1–7.2) — прочитаны до разбора ТЗ.
2. Issue #43: тело + все 7 комментариев через gh issue view --json (mcp__github__* были недоступны без разрешения) — восстановлена полная цепочка решений владельца (финальное UX-описание → Q1–Q5 → ответы).
3. Построчное чтение docs/specs/043-private-support-report.md (646 строк) против §7.1 обязательных разделов, продуктовых вопросов из issue и docs/TOUCH-SUPPORT.md.
4. Сверка утверждений §3 («подтверждённое текущее состояние») с реальным кодом: src/houseplan-card.ts (кнопка General Settings, _norm && _canEdit, порядок zoom→settings, ленивый import('./houseplan-editor-runtime')), src/houseplan-editor-runtime.ts (блок «О карточке», gs.about_* ключи), custom_components/houseplan/{websocket_api,import_export}.py (create_export), repairs.py (broken_plan_<spaceId>), src/i18n/{ru,en,de,fr}.json (RU/EN/DE/FR уже существуют).
5. Сверка i18n-подписи и терминологии («О карточке», «Общие настройки», GitHub/Telegram-ссылки) с docs/USER-GUIDE.ru.md и src/i18n/ru.json — расхождений не найдено.
6. docs/CONFIG-COMPATIBILITY.md — подтверждено, что фича не трогает схему config/layout (ТЗ §10 корректно).
7. docs/TOUCH-SUPPORT.md — сверка UX/§11 с контрактом «View dialogs and safe device actions: Fully supported» и правилом обязательной пометки Touch editor: ….
8. docs/specs/README.md — обязательный раздел release-артефактов и двусторонняя ссылка issue↔ТЗ (строка 106) присутствуют.
9. scripts/process-gate.mjs прочитан целиком по функции classify() и условиям fail(1, …)/fail(8...), чтобы проверить, как гейт классифицирует новый путь support-relay/**, которого ТЗ вводит впервые.

Гейты

Гейт	Результат
npx tsc --noEmit	зелёный, 6.2 с
node scripts/process-gate.mjs	«гейт пройден, предупреждений 0» (офлайн, диапазон origin/dev..HEAD, 1 коммит)
npm test, npm run build, check-docs.mjs, смоки, model-invariants, pytest tests_backend	не прогонялись — диф коммита 755fa4cf строго класса C: docs/specs/043-private-support-report.md + docs/specs/README.md (git show --stat HEAD), src/**/custom_components/** не тронуты. Эти гейты бессмысленны для чисто документного диффа на этапе ТЗ; check-docs.mjs условен на изменения src/**, которых нет

Трейлеры коммита 755fa4cf: Issue: #43, User-Visible: no — корректны для docs-only правки.

Находки

Medium (в скоупе задачи) — support-relay/** не попадает ни в один класс изменений

Файл: docs/specs/043-private-support-report.md, §9.1 (строки 404–416) и §18 (строки 606–617).

Суть: ТЗ явно вводит новый top-level каталог support-relay/ — «separately deployable service, excluded from the HACS artifact» — и явно кладёт «минимальный deployable relay» в объём #43 (§5.1). Ни AGENTS.md (таблица «Change classes»), ни PROCESS.md §1 не знают такого пути: класс A ограничен src/** и custom_components/houseplan/**/*.py, класс B — конкретным списком (test/**, tests_backend/**, demo/**, scripts/**, .github/**, …), класс C — документацией. support-relay/** не match-ится ни одним regex.

Я прочитал scripts/process-gate.mjs::classify() (строки 93–99): путь, не попавший ни в CLASS_D/A/B/C, получает '?'. Строка 255–256 превращает это только в предупреждение (warn(0, …)), а не в отказ. Требование трейлера Issue: #NN (правило 1, строка 232) и проверка статуса issue через --issues (правило 8, строки 310/392/510) применяются только когда c.classes.has('A') || c.classes.has('B') — то есть коммит, который трогает только support-relay/**, эти проверки не запускает вовсе.

Сценарий отказа: после старта реализации коммит вида feat: relay rate limiting с diff только внутри support-relay/ пройдёт process-gate.mjs (и локальный pre-push) без единого трейлера Issue:, без метки issue в S5-ready/S6-in-progress/S7-code-review, без ссылки на ТЗ — то есть ровно то, что правило №1 AGENTS.md объявляет запрещённым («Изменение продуктового кода без issue запрещено»). Для обычного продукта это было бы досадной дырой в тулинге; здесь эта дыра открыта ровно в подсистеме, которая пересылает точную геометрию дома и контакт пользователя на внешний сервер — там же, где PROCESS.md требует наибольшей строгости.

Почему это находка ТЗ, а не готового кода: §18 «Documentation and release artifacts» перечисляет docs/USER-GUIDE, docs/ARCHITECTURE.md, docs/SUPPORT-PRIVACY.md, docs/TESTING.md, relay README — но не упоминает обновление таблицы классов в AGENTS.md/PROCESS.md §1. Без явного решения в ТЗ реализация имеет прямой путь создать неклассифицированный каталог и получить только warning вместо gate.

Почему это не продуктовый вопрос владельцу: это техническое решение (файловая раскладка / расширение таблицы классов), которое, по §7.1 PROCESS.md, агенты решают и фиксируют сами («Всё, чего пользователь не наблюдает, агенты решают сами… раскладка файлов»). Автору достаточно добавить в ТЗ (например, в §9.1 или §18) одно из двух решений:

• либо явно расширить класс A (или завести отдельный подкласс) на support-relay/** в AGENTS.md/PROCESS.md §1 тем же коммитом, где каталог появляется, и включить эту правку в release-артефакты §18;
• либо разместить relay-код внутри уже классифицированного пути (например, под scripts/support-relay/ — класс B, или отдельно обсудить с владельцем вынос в отдельный репозиторий, если секреты не должны жить в этом дереве вообще).

Оставляю выбор автору — важно, чтобы решение было явно записано в ТЗ, а не осталось implicit-пробелом, который заметят только когда реальный коммит пройдёт гейт с одним warning.

Low (снимается с записью) — отсутствует явная пометка Touch editor: …

Файл: docs/specs/043-private-support-report.md, §11 (строки 461–476).

docs/TOUCH-SUPPORT.md требует: «New editor feature specifications … must state one of: Touch editor: supported; Touch editor: best effort / intentionally degraded; Touch editor: not exposed.» Диалог Help/Feedback доступен не только в View, но и во всех трёх редакторах (Plan/Devices/ Backdrop, §6.1), поэтому формально подпадает под это правило. §11 подробно и корректно описывает touch/a11y-контракт (44×44 px цель, 320 px раскладка, aria-live, фокус-менеджмент) — по содержанию это ровно Touch editor: supported, просто без канонической фразы, по которой обычно грепают такие декларации.

Снимаю как Low без возврата на цикл: содержательно контракт уже сильнее, чем «fully supported» из таблицы TOUCH-SUPPORT.md для View-диалогов, а сам диалог — не операция редактирования геометрии, а сквозной UI-элемент шапки. Автору имеет смысл добавить одну строку «Touch editor: supported» в §11 при следующей правке ТЗ ради единообразия аудита, но это не блокирует переход в S5-ready.

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

• Обязательные разделы §7.1 — все на месте: сценарий (§1, персона Home admin из SCOPE.md, поверхность View+все редакторы), что человек увидит до/после (§2, одной фразой, без терминов реализации), проблема (§3), скоуп и не-скоуп (§5.1/5.2), контракт поведения (§4, §6–9), UX (§6, §11), модель данных и миграция (§10 — миграции нет, обоснованно: пакет строится на чтении, не меняет schema), i18n (§12), AC1…AC17 с доказательством (§13), план автотестов (§14), риски (§16), откат (§19), release-артефакты (§18).
• Продуктовые вопросы правильно классифицированы и закрыты владельцем. Q1–Q5 в issue — все действительно продуктовые (куда уходят данные, что считается «бэкапом», что видно в preview, кто видит кнопку, есть ли контакт для ответа) — ни один не технический вопрос, вынесенный по ошибке. Ответы владельца дословно перенесены в §4/§6/§7/§9 ТЗ без искажений (сверено построчно): точная геометрия — да (Q2), preview точных байтов — да (Q3), только can_write, без kiosk (Q4), необязательный контакт вне support-пакета (Q5), HTTPS-relay через backend (Q1).
• Технические предположения промаркированы. §20 «Принятые технические предположения» явно называет неочевидные архитектурные решения (email-relay вместо issue, package-local sequential псевдонимы вместо стабильного хэша, in-memory кеш preview, 30/24-часовые сроки хранения) как «assumed, change freely» — это именно то, что требует PROCESS.md §7.1, и защищает от «догадки, выданной за факт».
• Утверждения о текущем состоянии (§3) проверены по коду, а не приняты на веру. Каждое из пяти технических утверждений подтвердилось построчно (см. «Как проверялось» п.4) — расхождений с реальным деревом не найдено.
• AC однозначны и снабжены методом доказательства. Все 17 AC в таблице §13 имеют явную колонку Evidence с конкретным методом (browser smoke, DOM/i18n unit, backend test, adversarial security test, fake-clock test, performance benchmark) — ни одного «проверить вручную» или недоказуемого критерия не найдено.
• «Одно число — один источник» уже спроектировано в контракт, а не оставлено на волю реализации. §6.4/§7.1/§8.1/AC5/AC10 и явный пункт mutation-gate «preview bytes are regenerated on submit → exact-byte test red» (§14.4) требуют, чтобы preview, download и отправленные байты были одним и тем же кешированным объектом с TTL-токеном, а не тремя независимыми вычислениями — ровно тот инвариант, который трижды ловил регрессии в проекте (#234, #233).
• Privacy allowlist/exclusion списки (§7.2/7.3) внутренне непротиворечивы: каждый пункт «включено» имеет зеркальный запрет в «исключено» там, где это применимо (имена/ids/URL/бинарники/undo-backup/HA state исключены явно; точная геометрия включена явно и осознанно как продуктовое решение, а не побочный эффект).
• i18n-контракт (RU/EN/DE/FR) соответствует уже существующим локалям проекта (src/i18n/{ru,en,de,fr}.json существуют) — фича не расширяет список поддерживаемых языков произвольно.
• Cross-links. Issue #43 ↔ ТЗ ↔ docs/specs/README.md — ссылки в обе стороны на месте.
• DoR-зависимости (§17) корректно вынесены как внешние операционные факты (деплой relay, mailbox, staging), а не спрятаны как «предположения»: ТЗ прямо говорит, что при их отсутствии после зелёного ревью issue должен получить S5-ready + blocked, а не мёртвую кнопку — это соответствует PROCESS.md §2.9 и §7.1 «риски перечислены».

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

• Полные npm test/npm run build/browser-смоки/model-invariants/ pytest tests_backend — не прогонялись: диф чисто документный (класс C), ни один из этих гейтов не имеет предмета для проверки на этом коммите. Они станут обязательны на этапе код-ревью, когда появится реализация.
• Реальная развёртываемость relay, содержимое support-relay/, secrets- handling — предмета для проверки ещё нет (кода нет), это заявленная DoR-зависимость §17, а не то, что должно быть в ТЗ.
• Golden/скриншоты, performance-профили — не относятся к докс-only диффу этого раунда.
• Соответствие ещё не написанных docs/SUPPORT-PRIVACY.md, docs/ARCHITECTURE.md-правок — эти документы появятся вместе с кодом (§18), не на этапе ТЗ.

Вывод

ТЗ методологически одно из самых тщательных, что проходили через этот процесс: 17 однозначных AC с доказательствами, явное разделение продуктовых решений владельца и технических допущений, встроенная защита от «одно число — два источника» и от privacy-регрессий через adversarial-фикстуру. Единственная блокирующая (по бюджету цикла) находка — не продуктовая, а процессная: новый top-level каталог support-relay/ создаёт слепую зону в автоматическом гейте process-gate.mjs, причём именно для той части системы, где цена незамеченного нарушения правила «код только через issue» выше всего. Это Medium-находка в скоупе задачи (сам каталог заводит #43), правится одной явной строкой в ТЗ — второй раунд не должен требовать нового расследования.