From 154c662a0bac03b4561094b088767e331e556e88 Mon Sep 17 00:00:00 2001 From: Sergey Matyunin Date: Mon, 17 Aug 2026 11:55:38 +0300 Subject: [PATCH] docs: address issue 166 spec review Issue: #166 User-Visible: no --- docs/specs/166-sun-north-rotation.md | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/docs/specs/166-sun-north-rotation.md b/docs/specs/166-sun-north-rotation.md index 22766437..20b2f8e3 100644 --- a/docs/specs/166-sun-north-rotation.md +++ b/docs/specs/166-sun-north-rotation.md @@ -1,6 +1,6 @@ # Issue #166 — солнечные лучи зеркально учитывают направление севера -Статус: **ТЗ на ревью** +Статус: **ТЗ принято, готово к реализации** Дата: 2026-08-16 Тип: `bug` · приоритет: `P1` · user value: 8/10 · complexity: 4/10 · risk: 6/10 @@ -127,6 +127,11 @@ awayFromSun = -toSun нормализация угла. `sunDirOnPlan()` продолжает возвращать единичный вектор к Солнцу в координатах холста. +Архитектурный инвариант для текущих и будущих потребителей, включая +SUN-CONTRAST: направление Солнца на плане берётся только из +`planSunAngle()`. Ни render-слой, ни contrast-логика не вводят вторую формулу, +зеркальное преобразование или дополнительную поправку знака. + Знак меняется только в композиции двух систем координат. Нельзя одновременно инвертировать `toSun`, нормали окон или `awayFromSun`: это дало бы локально правильный тест, но снова перепутало бы освещённую сторону либо направление @@ -238,9 +243,10 @@ fade/rim, editor gating и независимый four-phase background прох ### AC-06 — визуальная регрессия больше не маскируется -В golden matrix есть хотя бы одна детерминированная сцена с ненулевым +В `GOLDEN_SCENARIOS` есть хотя бы одна детерминированная сцена с ненулевым `north_deg` и асимметричным сочетанием азимута/окон, где ошибочный знак выбрал -бы другую сторону плана. +бы другую сторону плана. Добавление либо семантическое изменение этой сцены +сопровождается повышением `GOLDEN_MATRIX_VERSION`. **Доказательство:** обновлённый manifest/diff golden; ручное принятие только изменённой ожидаемой сцены. @@ -284,6 +290,21 @@ smoke/golden перед бетой, без новых security exceptions. Полный HA harness на Windows не является каноном из-за `fcntl`; его обязательное доказательство остаётся в Linux CI. +### Мутационный гейт + +Перед передачей реализации на код-ревью автор вручную применяет каждый мутант, +запускает указанный узкий тест и фиксирует, что тест красный; после возврата +рабочей реализации тот же тест должен быть зелёным. + +| Мутант | Обязательное доказательство | +|---|---| +| Вернуть в `planSunAngle()` вычитание `azimuth - northDeg` | Табличный unit AC-01 падает хотя бы на контрольных сочетаниях `90° + 90°` и wrap через 360° | +| Оставить сложение углов, но инвертировать `toSun` вместо исправления требуемой семантики вектора | Таблица углов AC-01 остаётся зелёной, а направленный unit AC-03 выбора нижнего окна при `north_deg=90`, `azimuth=90` падает | +| Вернуть `north_deg: 0` в новой golden-сцене | Структурный тест golden matrix падает, потому что обязательная запись в `GOLDEN_SCENARIOS` больше не содержит ненулевой ориентации, а `GOLDEN_MATRIX_VERSION` не соответствует сценарию | + +Гейт не считается доказанным только визуальным diff: для каждого мутанта нужен +исполняемый тест с заранее определённой причиной падения. + ## 12. Риски и защита от регрессии 1. **Повторная инверсия не того вектора.** Защита: отдельно тестировать