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

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, что снимает необходимость профиля уже на этапе ТЗ.