docs: complete issue 421 product framing

Issue: #421
User-Visible: no
This commit is contained in:
Sergey Matyunin
2026-09-02 20:04:10 +03:00
parent 7f9b919888
commit fac1f8840e
+41
View File
@@ -6,6 +6,28 @@
- Связанные контракты: #43 (support preview), #404/#407 (browser error
guard), #401/#409 (приёмка документационных скриншотов), #85 (mutation gate)
## Сценарий
Разработчик меняет lifecycle support-preview, browser error guard или CLI
приёмки скриншотов и запускает объявленную для этого контракта проверку. Сейчас
она может остаться зелёной после удаления защищающего механизма, поэтому
ревьюер получает ложное доказательство и регрессия может попасть в релиз.
После этой задачи тот же намеренный дефект воспроизводится адресным мутантом
либо контролируемым red proof. Гейт обязан покраснеть до merge; исправная версия
проходит тот же тест зелёной.
## Что человек увидит до и после
**До:** видимого дефекта в текущей версии нет, но три зелёные проверки не
гарантируют заявленное поведение. Будущая регрессия может незаметно вернуть
пригодность заменённого support-токена, пропустить browser exception или стереть
историю приёмки документационных кадров.
**После:** UI и штатные сценарии выглядят ровно так же. Пользователь получает
косвенный результат: эти три класса регрессий блокируются проверками до выпуска,
а не обнаруживаются после него.
## Цель
Сделать три существующих утверждения доказательными: тест или гейт обязан
@@ -62,6 +84,13 @@ round-trip в `reportPageErrors()`. Удаление этого `await` оста
уже закреплено в `AGENTS.md` и `PROCESS.md`;
- полный аудит всех тестов проекта за пределами трёх названных швов.
## UX
Новых экранов, сообщений, настроек и действий нет. Help & feedback сохраняет
действующие ответы и срок жизни preview; browser smokes и docs acceptance CLI
остаются инструментами разработки. Desktop, touch, kiosk, keyboard, focus и
ARIA не затронуты.
## Контракт
### 1. Replacement, discard и TTL preview-токена
@@ -154,6 +183,18 @@ Production modules `custom_components/houseplan/websocket_api.py` и
текущее поведение. Если тест выявит реальный дефект поведения, реализация
останавливается и найденный продуктовый scope оформляется отдельно.
## Модель данных и миграция
Persisted config/layout, support-package schema, WebSocket payloads и runtime
records preview не меняются; миграция и compatibility-поля не нужны.
Тестируемая функция `docs-accept.mjs` перестраивает тот же manifest, который CLI
пишет сейчас. Формат `docs/images/screenshots.json` не расширяется: при реальной
замене пикселей создаётся уже существующий acceptance trace, а при
fingerprint-only refresh переносятся его прежние поля и добавляется уже
действующий `lastWriteWasFingerprintOnly`. Старые manifests без `acceptance`
остаются допустимыми.
## i18n, compatibility, touch и security
- новых строк и изменений словарей нет;