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

SPEC-REVIEW-405-r1

• Issue: https://github.com/Matysh/houseplan-card/issues/405
• ТЗ: docs/specs/405-dropped-promise-and-witness-floor.md
• SHA ТЗ: cd0c85b9ad5096d4772f99edc0354dea6a62f241
• Заход: r1 · блокирующих циклов израсходовано 0 из 4 (до этого раунда)
• Трек: полный (заявлен автором — две несвязанные поверхности, src/** и scripts/**; критерий small «одна поверхность» не выполняется — согласен)
• Вердикт: жёлтый

Скоуп ревью

Первый заход, дельты нет — разбор ТЗ целиком по §7.1: обязательные разделы, однозначность и доказуемость AC1…AC8, соответствие описанных технических фактов реальному коду (src/houseplan-editor-runtime.ts, src/houseplan-card.ts, src/editor-secondary.ts, demo/smoke_free_walls.mjs, scripts/docs-acceptance.mjs, test/docs-acceptance.test.mjs), а также продуктовая рамка по docs/SCOPE.md (задача инфраструктурная по духу — не про J1–J7, а про доказательность гейтов, что для класса B/тестовой инфраструктуры уместно и не требует отдельного продуктового обоснования; правка src/** делает задачу полным треком по §1, но не продуктовой в смысле пользовательского сценария — ТЗ прямо пишет «видимого поведения не меняет», что не противоречит скоупу, поскольку задача чинит доказательство существующего инварианта, а не добавляет функциональность).

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

Читкой кода, без исполнения (spec review, гейты не прогонялись — это код-ревью этап, здесь ему нечего проверять по §2.4). Для каждого технического утверждения ТЗ — сверка со строками файлов на HEAD (cd0c85b9):

• src/houseplan-editor-runtime.ts:3050-3150, 5282-5300 — таблица «Место» для M2 (_deletePhysicalSelection, _runEditorContext, _deleteDraftWhole);
• src/editor-secondary.ts:200-224 — runContext;
• src/houseplan-card.ts:3015-3022, 7845-7874 — вызывающие и параллельные обёртки _deletePhysicalSelection/_deleteDraftWhole/_deleteDraftSegment;
• demo/smoke_free_walls.mjs:1-30, 175-208 — стаб _confirmDanger и вызовы _deletePhysicalSelection;
• scripts/docs-acceptance.mjs:1-128 — docsWitnessFloor, docsAcceptancePlan, вычисление floor;
• test/docs-acceptance.test.mjs — существующие тесты AC7/AC8;
• scripts/golden-acceptance.mjs:1-200, demo/golden/accept.mjs:1-121, demo/golden/run.mjs:800-850 — сверка риска «изменение порога затрагивает golden»;
• scripts/mutation-gate.mjs — конвенция именования мутантов (id: 'kebab-case'), сверена с предложенными draft-delete-drops-the-promise и witness-floor-counts-survivors — согласуется.

Один факт проверен эмпирически (не просто чтением): предположение, что TypeScript пропустит функцию, аннотированную (): void, но фактически возвращающую Promise<void> изнутри, — проверено tsc на изолированном файле (см. находку M2-a ниже), потому что от этого зависела оценка серьёзности находки, а не только её наличие.

Issue #406 (куда ТЗ отправляет один Low-пункт) прочитан целиком через gh issue view 406 — сверка ссылки «#406 «д»».

Находки

M2-a (Medium, в скоупе) — таблица «Место» неполна: пропущена обёртка houseplan-card.ts:7856, и без неё правка не пройдёт tsc --noEmit

Файл: docs/specs/405-dropped-promise-and-witness-floor.md, раздел «(1) M2», таблица «Место» и абзац «Практически».

Что не так. Смок вызывает не houseplan-editor-runtime.ts, а window.__card — экземпляр класса houseplan-card.ts (demo/srv/demo.html:194 создаёт <houseplan-card>, demo/serve.mjs его же отдаёт в window.__card, smoke_free_walls.mjs:194,199 зовёт c._deletePhysicalSelection()). Реальная точка входа — обёртка src/houseplan-card.ts:7856:

private _deletePhysicalSelection = (): void => {
  return this._editorRuntimeOrThrow()._deletePhysicalSelection();
}

Таблица «Место» в ТЗ называет только editor-secondary.ts:221, houseplan-editor-runtime.ts:5290 и :3073 — эту строку не называет вовсе. «Практически» перечисляет три функции для правки (_deletePhysicalSelection в runtime, _runEditorContext, runContext) — тоже без неё.

Воспроизведено: изолированный tsc --strict --noEmit на паре функций, повторяющей форму houseplan-card.ts:7856 после того, как внутренний вызов меняет тип на Promise<void>, а внешняя обёртка остаётся (): void:

async function inner(): Promise<void> {}
const wrapper = (): void => {
  return inner();
};

error TS2322: Type 'Promise<void>' is not assignable to type 'void'.

Это не эстетика типов — это реальный отказ гейта npx tsc --noEmit, единственного среди трёх дешёвых гейтов, который правка данной задачи действительно затрагивает. Если исполнитель проверит только смок (JS, типов не видит) или отправит правку без прогона tsc, регресс поймает CI, но раунд код-ревью на это тратиться не должен.

Это не догадка о недостающем шаге, а видимый паттерн этого же файла. Строками ниже, houseplan-card.ts:7864 и :7868, у соседних методов (_deleteDraftWhole, _deleteDraftSegment) обёртки уже типизированы Promise<void>, зеркаля асинхронные методы runtime. Это подтверждает: в файле есть устоявшаяся конвенция «тип обёртки повторяет тип метода runtime», и _deletePhysicalSelection-обёртка на :7856 — единственная, которую эта задача обязана привести к тому же виду, а ТЗ её не называет.

Требуется: добавить src/houseplan-card.ts:7856 в таблицу «Место» и в перечень правок «Практически» — тип обёртки меняется на Promise<void> с return, как у _deleteDraftWhole/_deleteDraftSegment рядом.

Серьёзность — Medium, не High: контракт AC1–AC8 в остальном верен и достижим, дефект — не в контракте, а в полноте технической карты внутри уже названного в скоупе файла (src/houseplan-card.ts фигурирует в файлах задачи неявно — это тот же модуль, где объявлена обёртка _deleteDraftWhole, _deleteDraftSegment, уже упомянутых как соседний прецедент); дешёвый гейт tsc его поймает при обычной проверке, но ТЗ, которое ведёт прямиком к провалу первого же гейта, не «выполнимо без доработки» по мерке §2.4.

M4-b (Low) — ссылка «#406 «д»» на несуществующий пункт

Файл: docs/specs/405-dropped-promise-and-witness-floor.md, раздел «Скоуп / не-скоуп»:

затирание acceptance.declared при повторной приёмке (#406 «д») — соседняя строка того же файла, но другой контракт

Прочитан issue #406 целиком (gh issue view 406): в нём ровно четыре пункта, (а)–(г) — мёртвые ключи confirm.*, роль диалога, непокрытая HA-ветка подтверждения, снапшоты area. Пункта «(д)» нет. Оригинальный аудит-комментарий в теле #405 упоминает это как отдельный Low-пункт («Отдельно, из того же разбора (Low, чинить попутно): повторная приёмка неизменённого набора затирает acceptance.declared… scripts/docs-accept.mjs:142-150»), но нигде не заводит его как пункт «(д)» и не кладёт в #406.

Итог: Low-находка из исходного аудита сейчас не отслеживается ни одним issue — ссылка ТЗ на несуществующий пункт создаёт впечатление, что она где-то учтена, хотя это не так.

Решение ревьюера: не правится сейчас (сам дефект docs-accept.mjs:142-150 за пределами скоупа #405 — другая строка того же файла, другой контракт, как верно замечает автор) — но ссылка ложная и должна быть исправлена: либо пункт действительно добавляется в #406, либо ТЗ отправляет его в новый issue, либо ТЗ формулирует «Low, пока нигде не заведён» вместо несуществующей ссылки. Это правится в рамках текущего цикла возврата (Low, не отдельный лимит).

Медиум вне скоупа — заведён отдельным issue

Golden-эталоны подвержены тому же классу дефекта, что и M4 — #408

scripts/golden-acceptance.mjs:182-183 считает порог свидетелей от withBaseline.length — числа сцен со статусом не missing-baseline, то есть от того, что уцелело на диске, а не от размера известной матрицы (GOLDEN_SCENARIOS.length). Проверено чтением всей цепочки (demo/golden/run.mjs:836-839 ставит status: 'missing-baseline', когда файла эталона нет; goldenAcceptanceRefusal в scripts/golden-acceptance.mjs:59-93 требует, чтобы каждая такая сцена была объявлена через --expect-new — и не более; demo/golden/accept.mjs:64-72 вызывает goldenWitnessRefusal уже после этой проверки). Модельный разбор: git rm demo/golden/baselines/*.png

• объявление всех сцен --expect-new → каждая сцена легально проходит goldenAcceptanceRefusal → withBaseline.length === 0 → goldenWitnessFloor(0) === 0 → witnesses.length (0) < floor (0) ложно → отказа goldenWitnessRefusal нет. --reviewed не является независимой проверкой (булев CLI-флаг), так что рассуждение ТЗ #405 о том, что M4 недостаточно прикрыт --reviewed для docs-accept.mjs, симметрично относится и сюда.

ТЗ #405 обсуждает golden только в разделе «Риски» и только применительно к формуле (goldenWitnessFloor та же формула, что docsWitnessFloor, и должна остаться той же) — не к тому, что вызывающий код (withBaseline.length) подвержен той же уязвимости на входе, что чинит M4. Файл другой (scripts/golden-acceptance.mjs, не scripts/docs-acceptance.mjs), скоуп ТЗ его не называет — правка не входит в #405.

Issue заведён: #408, метки bug, P2, S1-new, infra, ссылка на #405.

Проверено и корректно

• Обязательные разделы §7.1 присутствуют все: сценарий, что человек увидит, проблема, скоуп/не-скоуп, контракт, UX, модель данных/миграция, i18n, AC1–AC8 с доказательством, план автотестов, риски, откат, release-артефакты.
• Продуктовых вопросов владельцу нет, догадок, выданных за факт, в контракте M2/M4 не найдено (кроме описанного выше пробела в таблице «Место» — это не догадка, а неполнота карты).
• Таблица «Место» для M2 (кроме отсутствующей строки houseplan-card.ts:7856) точно соответствует коду: runContext (editor-secondary.ts:221), _runEditorContext (houseplan-editor-runtime.ts:5290), _deletePhysicalSelection (:3073, ветка sel.kind === 'draft' действительно роняет промис через return), _deleteDraftWhole (:3119, действительно async, await _confirmDanger).
• Смок demo/smoke_free_walls.mjs:16 — стаб _confirmDanger = async () => true резолвится в том же микротаске, и :194,199 действительно не проверяет ожидание по-настоящему; воспроизведение из тела issue (макрозадача → два FAILED) правдоподобно и согласуется с кодом.
• scripts/docs-acceptance.mjs:44-46,107-108 — формула и место вычисления floor от withCommitted.length подтверждены; контраст «PNG на месте» vs «PNG удалены» из тела issue воспроизводим по чтению кода без исполнения.
• Предложенный контракт AC6 (floor от размера набора сценариев, не от наличия файлов) корректно сохраняет существующее поведение AC7 — проверено арифметически: docsWitnessFloor(ids.length) и текущее docsWitnessFloor(withCommitted.length) дают одно и то же значение во всех ветках существующих тестов test/docs-acceptance.test.mjs, включая «кадр без закоммиченной пары не может быть свидетелем» (floor остаётся 1 в обоих случаях — 3 или 1 округляются к одному порогу на этом наборе).
• «Не-скоуп» по _deleteDraftSegment — проверено: у него отдельный, корректно типизированный путь (houseplan-card.ts:7868 уже Promise<void>, зовётся напрямую из своей кнопки, не через _deletePhysicalSelection) — исключение обосновано верно, не прячет тот же дефект.
• Риск «изменение порога затрагивает golden» правильно определяет, что формулу трогать нельзя без зеркалирования — но не замечает независимый дефект на стороне вызова (см. #408).
• AC2 (отрицательный прогон обязателен) сформулирован по правилу «тест должен уметь падать» и предлагает конкретный механизм (scripts/mutation-gate.mjs, который в проекте уже используется по этому шаблону) — не декларация.
• Откат и release-артефакты соразмерны факту «видимого поведения нет» (User-Visible: no подтверждён отсутствием изменений в UX/i18n разделах).

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

• Гейты (tsc, npm test, npm run build, смоки, golden:verify, model-invariants) не прогонял — этап spec review, кода задачи ещё нет, прогонять нечего. Эмпирическая проверка ограничена одним изолированным TS-файлом вне репозитория, подтверждающим находку M2-a (см. выше), — это не прогон проектных гейтов.
• Не проверял scripts/mutation-gate.mjs на предмет того, заведутся ли предложенные мутанты технически без ошибок раннера — это вопрос реализации, а не ТЗ; на этапе спеки достаточно, что названный механизм существует и используется в проекте по тому же образцу.
• Не проверял golden test/golden-policy.test.mjs целиком — находка по #408 установлена чтением scripts/golden-acceptance.mjs и demo/golden/accept.mjs напрямую; тестовое покрытие этой ветки (принимает ли текущий набор тестов сценарий «все эталоны удалены») не сверял — это будет частью работы над #408, не #405.
• Не оценивал вне двух Medium/одного Low другие возможные дефекты в scripts/docs-accept.mjs целиком (не-docs-acceptance.mjs) — за пределами того, что уже упомянуто как «не-скоуп» самим ТЗ.

Итог

Один Medium в скоупе (M2-a) не даёт зелёный вердикт по §2.4 — ТЗ ведёт прямиком к отказу гейта tsc --noEmit, если исполнитель буквально следует таблице «Место». Плюс один Low (ложная ссылка на #406) для правки в этом же цикле. Medium вне скоупа заведён отдельным issue (#408), в задаче #405 не чинится.

Вердикт: жёлтый. Возврат автору: дополнить таблицу «Место» и раздел «Практически» строкой src/houseplan-card.ts:7856, поправить ссылку на #406.