docs: review document for #217

Issue: #217
User-Visible: no

docs/reviews/SPEC-REVIEW-217-r1.md

@@ -0,0 +1,130 @@
+# SPEC-REVIEW-217-r1
+
+- **Issue:** #217 — Text-маркер: внешняя обводка стала эллипсом вместо капсулы
+- **Артефакт ТЗ:** `docs/specs/217-text-shell-outline.md`
+- **Ветка/SHA:** `issue/217-text-shell-outline` @ `fe33dea`
+- **Трек:** обычный (не `small`)
+- **Цикл:** r1/4
+- **Вердикт:** зелёный · High: 0 · Medium: 0
+
+## Скоуп ревью
+
+Первый цикл — разбор полный. Проверялись: тело issue #217 и оба комментария
+(аналитика, хендофф автора ТЗ), `docs/specs/217-text-shell-outline.md`
+целиком, соответствие обязательным разделам §7.1 PROCESS.md, техническая
+достоверность диагноза причины по фактическому коду, согласованность с
+родительскими задачами #179 (нормативный дизайн-пакет) и #213 (контракты
+размеров/inset/hover, которые #217 обязуется не трогать).
+
+## Как проверялось
+
+- `docs/SCOPE.md`, `AGENTS.md`, `PROCESS.md` — прочитаны целиком, требования
+  §2.4/§7.1/§12 применены к ТЗ.
+- `docs/USER-GUIDE.ru.md` (разделы «Устройства», «Визуальные состояния
+  устройств») — сверена терминология («капсула», «shell», «полукруглые
+  торцы»).
+- `docs/STYLING-HOOKS.md`, `docs/LIVE-TEXT.md` — проверены как возможные
+  канонические документы подсистемы; ни один не описывает геометрию внешней
+  рамки Text-маркера напрямую, канон для неё — принятый спек #213
+  (`docs/specs/213-device-marker-geometry.md`), который ТЗ #217 и цитирует.
+- `docs/specs/213-device-marker-geometry.md` — сверены §9.1 (inset/anchor
+  контракт) и §11 (hover всей capsule), на которые #217 ссылается как на
+  неизменяемую базу.
+- `src/styles.ts` (строки 2040–2086), `src/device-face.ts` (строки 86–101) —
+  прочитаны, чтобы проверить точность «Подтверждённой причины» ТЗ по
+  фактическому коду, а не по пересказу автора.
+- `demo/srv/reference/device-icons/Light/Text Default.svg` — открыт и разобран
+  как SVG (outer `<path>` и внутренний `<rect rx="40">`), чтобы убедиться, что
+  stadium-контракт для внешней рамки действительно взят из нормативного
+  дизайн-пакета #179, а не додуман автором ТЗ.
+- Существование файлов, упомянутых в §11/§14 ТЗ, проверено по факту:
+  `test/device-marker-polish-contract.test.mjs`,
+  `demo/smoke_device_icon_design.mjs`, `demo/smoke_device_preview_parity.mjs`,
+  `demo/smoke_static_icon.mjs`, `scripts/check-docs.mjs`.
+- Прослежено, что `cardStyles` из `src/styles.ts` подключён во всех трёх
+  поверхностях (`houseplan-card.ts`, `space-card.ts`, `hp-device-preview.ts`),
+  что делает заявленный в ТЗ «shared device face without a second renderer»
+  технически достижимым для AC7 (surface/theme parity).
+
+Код не менялся и не проверялся на этапе реализации — на этапе `spec` его
+ещё нет (issue в `S4-spec-review`); все находки касаются только текста ТЗ и
+его соответствия существующему коду/дизайну.
+
+## Находки
+
+Нет находок High или Medium.
+
+**Low (снята с записью, не требует правки).** §2 ТЗ описывает форму словом
+«stadium» — англицизм дизайн-жаргона, которого нет в
+`docs/USER-GUIDE.ru.md`; там для того же объекта используется «капсула» /
+«внешняя капсула» (строки 563–564, 836). Раздел «что человек увидит» по
+§7.1 должен быть без терминов реализации, и «stadium» на грани этого
+требования. Решение ревьюера: не блокирует и не требует цикла, потому что
+(а) release note в §17 ТЗ и заголовок issue уже используют корректное
+русское «капсульная форма» — расхождение не попадёт ни в changelog, ни в
+UI; (б) «stadium» используется только как техническое уточнение геометрии
+внутри ТЗ, рядом с явным описанием «торцы — полуокружности, между ними
+прямой участок», которое самодостаточно и не требует термина. Автору
+предложено при следующей правке ТЗ (если он будет) заменить слово на
+«капсула», но это не является условием зелёного вердикта.
+
+## Проверка по существу (не только по форме)
+
+Дословно перепроверена «Подтверждённая причина» (§3 ТЗ) против кода:
+
+- `src/styles.ts:2049` — общий fallback `.device-shell-frame { border-radius:
+  9999px; }` подтверждён.
+- `src/styles.ts:2061-2062` — `.device-shell:not(.with-values)
+  .device-shell-frame { border-radius: 50%; }` подтверждён как источник
+  регрессии.
+- `src/device-face.ts:96-101` — класс `text-shell` присваивается по
+  `presentation.valueText != null`, класс `with-values` — по
+  `hasSections` (badge либо legacy-метрики), это два независимых условия.
+  Text-only маркер (только `valueText`, без badge/legacy) получает
+  `text-shell` без `with-values` и поэтому действительно попадает под
+  круглый override — диагноз ТЗ точен, а не «догадка, выданная за факт».
+- Комбинация `text-shell` + `with-values` (Text вместе с value-badge/legacy)
+  уже сегодня исключена из круглого override и не затронута регрессией; ТЗ
+  не утверждает обратного и не обязано отдельно оговаривать этот вариант.
+
+Референсный SVG (`Light/Text Default.svg`) прочитан как файл, не поверх
+слов автора: внешний `<path>` — сплошная stadium-обводка (два больших
+дуговых торца, соединённые прямыми верхней/нижней границами), внутренний
+`<rect rx="40" height="80">` — капсула с радиусом ровно в половину высоты.
+Нормативный источник действительно однозначно задаёт stadium и для внешней
+рамки, а не только для core — предположение №1 в §18 ТЗ подтверждено
+файлом, а не принято на веру.
+
+## Проверка обязательных разделов §7.1
+
+Все обязательные разделы присутствуют и содержательны: сценарий (§1) · что
+человек увидит до/после (§2) · проблема (§3) · нормативные источники и
+приоритет (§4) · scope/не-scope (§6/§7) · контракт поведения (§8) · UX (§9) ·
+данные/migration/i18n (§10) · архитектура (§11) · performance/security (§12) ·
+AC1…AC9, каждый с доказательством (§13) · план автотестов (§14) · риски (§15) ·
+откат (§16) · release-артефакты (§17). Продуктовые открытые вопросы
+отсутствуют, а неизбежное техническое предположение (какой CSS-механизм
+сузить: `9999px` vs height-derived) явно оставлено реализации в §18,
+пункт 2, и корректно помечено как «может быть изменено ревьюером».
+
+Каждый AC1–AC9 однозначен, имеет названный способ доказательства
+(`unit`/`browser smoke`/`golden`/«ревью кода»/`docs diff`) и проверяем не
+только предъявлением, но и потенциальным падением (AC2 явно требует
+documented mutant, AC4 — rect/inset assertions до/после).
+
+## Соответствие SCOPE.md
+
+Задача — исправление регрессии дизайн-системы #179, ранее принятой как
+Core user job J5/J1 (видимая точность отображения устройства на плане).
+Не расширяет продуктовый скоуп, не вводит новую функциональность, не
+затрагивает «Out of scope» раздел SCOPE.md.
+
+## Что не проверялось
+
+- Реальная browser-геометрия (rendering) не запускалась — на этапе `spec`
+  кода ещё нет; проверка ограничена статическим чтением текущего `src/`.
+- Golden/визуальные артефакты не создавались и не сравнивались — они
+  появятся в реализации и будут предметом code-review.
+- Не проверялась производительность — на этой стадии нет кода для профиля;
+  §12 ТЗ корректно ограничивает изменение CSS-only geometry без новых
+  layers/observers, что снимает необходимость профиля уже на этапе ТЗ.