docs(issues): оформлены задачи кросс-ревью генератора

- Зачем: - нужен готовый набор задач для закрытия находок кросс-линейного ревью. - Что: - добавлены issue 15-18 по границе миров, свежему стенду, проверкам и курсу. - обновлены навигация PRD и блокировка будущей доливки истории. - уточнены риски fallback, Superset sync и простоя daily-wave. - Проверка: - git diff --cached --check.
2026-07-05 01:00:39 +03:00
parent 1b1c37e3bf
commit 525bd8cabf
6 changed files with 226 additions and 5 deletions
@@ -90,9 +90,21 @@ Status: Implemented

 Дальнейшая задача вне текущей очереди:

- После фикса 09: `issues/13-...` (доливка истории от слепка; без приоритета,
-  `needs-triage` — доливка тиражирует стыки восстановления, дооформлять после
-  фикса).
+- `issues/13-...` — доливка истории от слепка; без приоритета,
+  `needs-triage`. После кросс-линейного ревью 2026-07-05 блокируется
+  задачами 15 и 17: доливка тиражирует стыки мира и должна опираться на
+  доверенную проверку фактической границы.
+
+Доработки по кросс-линейному ревью 2026-07-05:
+
+- `issues/15-world-boundary-after-cross-review.md` — граница миров после
+  обновления, сброса и консольных запусков.
+- `issues/16-fresh-stand-generator-control.md` — свежий стенд и Airflow-пульт
+  без неявных ручных шагов.
+- `issues/17-trusted-checks-startup-history-superset.md` — доверенные проверки
+  startup-history и Superset export.
+- `issues/18-course-clean-stand-startup-history.md` — курс на чистом стенде по
+  startup-history.

 ```mermaid
 flowchart LR
@@ -103,6 +115,11 @@ flowchart LR
    i14["14 быстрый профиль"] --> i08
    i09["09 фикс стыка"] --> i13["13 доливка"]
    i10["10 гео-карта"]
+    i15["15 граница миров"] --> i18["18 курс на чистом стенде"]
+    i16["16 свежий стенд"] --> i18
+    i17["17 доверенные проверки"] --> i18
+    i15 --> i13
+    i17 --> i13
 ```

 ## Контрольные точки
@@ -30,8 +30,18 @@ Status: needs-triage
  `09-seam-browser-fixture-not-preserved.md`: доливка создаёт новые стыки,
  тот же механизм восстановления.
 - [ ] Манифест после доливки отражает новый `T_end'`; антисмешивание работает.
+- [ ] До реализации доливки принято решение по fallback-ветке восстановления
+  визита: либо свойство донорского сида закреплено проверкой, либо длина визита
+  ограничена так, чтобы fallback не менял фактуру на стыке.

 ## Blocked by

- `09-seam-browser-fixture-not-preserved.md` — доливка тиражирует стыки
-  восстановления; сначала починить фактуру на стыке, иначе дефект размножится.
+- `15-world-boundary-after-cross-review.md` — доливка продолжает мир от слепка;
+  сначала нужен закрытый инвариант «старый state и консольные пути не создают
+  второй мир».
+- `17-trusted-checks-startup-history-superset.md` — доливка создаёт новые
+  стыки; сначала нужна доверенная проверка фактической границы по манифесту.
+
+Исторический контекст: `09-seam-browser-fixture-not-preserved.md` закрыла
+фактуру визита на стыке восстановления, но кросс-линейное ревью 2026-07-05
+нашло более широкие риски вокруг границы мира и проверки стыка.
@@ -0,0 +1,46 @@
+Status: ready-for-agent
+
+# Граница миров после кросс-ревью
+
+## Parent
+
+`.scratch/generator-model-time-startup-history/PRD.md`
+
+## What to build
+
+Закрыть семейство находок кросс-линейного ревью про «смешение миров»: после
+обновления кода, сброса стенда или консольного запуска старое состояние и старый
+live-генератор не должны тихо писать события в новый мир данных.
+
+Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`,
+разделы `Issue 12/14` и `Issue 09`.
+
+Связанные старые issue: `09-seam-browser-fixture-not-preserved.md`,
+`12-generator-control-dag.md`, частично `14-fast-teaching-profile.md`.
+
+## Acceptance criteria
+
+- [ ] Известная старая версия state при `GEN_STATE_RESET=false` даёт громкий
+  отказ с понятным сообщением, а не тихий чистый старт поверх существующей
+  истории.
+- [ ] Сброс и остановка стенда убирают ручной live-генератор из compose-профиля;
+  он не переживает `down`/`clean` и не воскресает после перезагрузки хоста.
+- [ ] Консольные пути backfill/import/continue используют ту же идею
+  предпроверки чистого стенда, что Airflow-пульт, но реализованы способом,
+  пригодным для запуска с хоста.
+- [ ] Документация объясняет миграционный случай: почему старый state может
+  теперь дать громкий отказ и что делать оператору или менти.
+- [ ] Есть проверка, которая доказывает каждый из трёх путей смешения миров:
+  старая версия state, compose-профиль live-генератора, консольный запуск на
+  грязном стенде.
+
+## Blocked by
+
+Нет — можно начинать сразу.
+
+## Notes
+
+- Рекомендуемый режим `coordinator-loop`: гейт. Worker `high`, ревью задачи
+  `high`, ревью кода `high`.
+- Не чинить здесь ложнозелёные проверки и курс целиком: это отдельные задачи
+  17 и 18. Здесь только граница миров и доказательства именно этой границы.
@@ -0,0 +1,50 @@
+Status: ready-for-agent
+
+# Свежий стенд и Airflow-пульт без догадок
+
+## Parent
+
+`.scratch/generator-model-time-startup-history/PRD.md`
+
+## What to build
+
+Сделать так, чтобы человек на свежем клоне мог пройти быстрый старт до
+`generator_control` без неявных шагов, сырых ошибок и зависаний Airflow.
+
+Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`,
+разделы `Issue 12/14` и `Issue 08`.
+
+Связанные старые issue: `12-generator-control-dag.md`,
+`14-fast-teaching-profile.md`.
+
+## Acceptance criteria
+
+- [ ] Quick start и курс явно называют `uv` и остальные обязательные
+  пререквизиты до первой команды, которая их требует.
+- [ ] Быстрый старт на чистом стенде подготавливает DDL до проверок генератора;
+  отсутствие таблиц не падает сырым `UNKNOWN_TABLE`.
+- [ ] После обновления репозитория Airflow получает новые зависимости и DAG-и
+  без ручных догадок: через пересборку, явную команду или ясно описанный шаг.
+- [ ] `generator_control` не висит навсегда, если зависимый `etl_pipeline`
+  стоит на паузе: оператор получает понятный отказ или инструкцию до запуска
+  долгого ожидания.
+- [ ] Решение по Airflow API, проверенное через Context7 для текущей версии,
+  зафиксировано в коде или документации кратко и рядом с местом выбора.
+- [ ] Runbook предупреждает, что долгий простой `daily-wave` на скорости 60
+  создаёт большую дыру в модельном времени, и советует reset или повторный
+  импорт стартовой истории.
+
+## Blocked by
+
+- `.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md`
+
+## Notes
+
+- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`, ревью
+  кода `high`. Если правка уйдёт в устройство DAG-зависимостей шире
+  предпроверки паузы, эскалировать до гейта.
+- Формальная зависимость от 15 нужна из-за общего участка предпроверки чистого
+  стенда: свежий стенд должен опираться на уже выбранный способ отказа и
+  диагностики грязного мира.
+- Не включать сюда учебные тексты уроков 00/01/05, кроме пререквизитов и
+  quick start: основной проход курса закрывает задача 18.
@@ -0,0 +1,48 @@
+Status: ready-for-agent
+
+# Проверки startup-history и Superset без ложного зелёного
+
+## Parent
+
+`.scratch/generator-model-time-startup-history/PRD.md`
+
+## What to build
+
+Сделать проверки доверенными: зелёный результат должен означать, что проверен
+фактический стык стартовой истории и живого продолжения, а Superset export
+соответствует ожидаемому контракту чарта.
+
+Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`,
+разделы `Issue 09`, `Issue 10` и `Issue 08`.
+
+Связанные старые issue: `09-seam-browser-fixture-not-preserved.md`,
+`10-dashboard-geo-map-readability.md`, частично `14-fast-teaching-profile.md`.
+
+## Acceptance criteria
+
+- [ ] Проверка startup-history берёт границу стыка из манифеста фактического
+  прогона, а не из значения окружения по умолчанию.
+- [ ] ODS-часть проверки не проходит на пустом ODS: отсутствие строк считается
+  ошибкой проверки, а не успешным результатом.
+- [ ] Профиль запуска доходит до проверки: сценарий с `daily-wave` проверяет
+  именно мир `daily-wave`, а не диапазон `ci`.
+- [ ] Ожидание live-строк доказывает, что живое продолжение реально успело
+  записать данные; короткое ожидание не должно превращать проверку стыка в
+  пропущенную проверку.
+- [ ] Тест Superset сравнивает полный существенный контракт `params` между
+  конфигурацией и export, а не только небольшой набор полей.
+- [ ] Сортировка top countries задана явно по числу событий, чтобы порядок не
+  зависел от случайной формы ответа после pivot.
+- [ ] Повторная синхронизация Superset не удаляет одноимённые чарты вне целевого
+  источника данных или dashboard; деструктивность sync задокументирована.
+
+## Blocked by
+
+Нет — можно начинать сразу.
+
+## Notes
+
+- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`,
+  ревью кода `high`.
+- Не смешивать с правками курса: задача 18 должна пользоваться уже доверенными
+  проверками, но текст уроков не является частью этой задачи.
@@ -0,0 +1,50 @@
+Status: ready-for-agent
+
+# Курс проходит по startup-history на чистом стенде
+
+## Parent
+
+`.scratch/generator-model-time-startup-history/PRD.md`
+
+## What to build
+
+Довести учебный путь до воспроизводимого прохода на чистом стенде: уроки должны
+работать с `startup-history`, не опираться на архивный сид и не обещать live-поток
+там, где он больше не запускается по умолчанию.
+
+Источник: `.scratch/handoffs/20260705-0002-cross-review-generator-chain.md`,
+раздел `Issue 08`.
+
+Связанные старые issue: `08-migrate-course-from-archive-seed.md`, частично
+`12-generator-control-dag.md` и `14-fast-teaching-profile.md`.
+
+## Acceptance criteria
+
+- [ ] Упражнение урока 01 с добавлением `kafka_msg_ts` воспроизводимо на стенде:
+  повторная заливка данных не сбрасывает схему, которую только что изменил
+  менти.
+- [ ] Урок 00 объясняет служебные топики генератора настолько, чтобы список
+  топиков не выглядел как набор неожиданных артефактов.
+- [ ] Уроки 00 и 05 не противоречат друг другу в описании видимости consumer lag;
+  утверждение проверено на текущем стенде.
+- [ ] Урок мониторинга согласован с no-live default: либо явно запускает live,
+  либо не обещает, что алерт отсутствия сообщений будет тихим на здоровом
+  стенде без live.
+- [ ] Операционная документация не ведёт учебный путь первым делом к архивному
+  `make data`; startup-history остаётся основным источником аналитики.
+- [ ] Проход уроков 00, 01 и 05 на чистом стенде проверен командно или вынесен
+  в явный HITL-пункт с точной инструкцией, что должен подтвердить человек.
+
+## Blocked by
+
+- `.scratch/generator-model-time-startup-history/issues/15-world-boundary-after-cross-review.md`
+- `.scratch/generator-model-time-startup-history/issues/16-fresh-stand-generator-control.md`
+- `.scratch/generator-model-time-startup-history/issues/17-trusted-checks-startup-history-superset.md`
+
+## Notes
+
+- Рекомендуемый режим `coordinator-loop`: обычный issue, worker `medium`, ревью
+  кода и документов `high`.
+- Если по ходу окажется, что упражнение 01 требует нового поддержанного режима
+  перезаливки, не прятать это в тексте урока: оформить как явное решение и
+  покрыть проверкой.