# Handoff: fixes after generator cross-line review

Дата: 2026-07-05 22:12.
Жанр: handoff по ADR-0003 после coordinator-loop 15 -> 16 -> 17 -> 18.

## Что закрыто

- 15: граница миров после обновления, clean/reset и host-запусков.
  Коммиты: `080d5ae`, `108053b`.
- 16: свежий стенд и `generator_control` без неявных ручных шагов.
  Коммиты: `27947ce`, `9804d0b`.
- 17: доверенные проверки startup-history и Superset.
  Коммиты: `00c97eb`, `6731349`.
- 18: курс 00/01/05 проходит по startup-history на чистом стенде.
  Коммиты: `77e4fb6`, `6d64f39`.
- Follow-up 19: отдельная задача на единые `make test` и `make lint`.
  Коммит: `2778eae`.
- Финальный review fix: документация больше не советует обычный
  `make generated-history-check` после backfill-only пути.
  Коммит: `8e1c733`.
- Issue 19 закрыта после внешнего Claude review: единые `make test` и
  `make lint`, подключение корневых контрактных тестов и усиление проверок
  startup-history.
  Коммит: `9b0b063`.

## Ключевые стыки реализации

- `generator/src/clickstream_generator/stand_clean.py` — общий guard чистого
  стенда для Airflow и host-путей.
- `scripts/assert_stand_clean.sh` — host-проверка перед backfill/import/continue.
- `airflow/dags/generator_control_dag.py` — pause-check `etl_pipeline` до
  мутирующих веток.
- `scripts/check_generated_analytics.sh` — manifest boundary, fail-closed
  live seam, непустой ODS и fail-closed проверка DM-витрин.
- `scripts/run_generated_history_runtime_check.sh` — bounded runtime gate для
  daily-wave + live seam.
- `scripts/run_generator.sh` — `reset` теперь проходит clean-stand guard до
  запуска live-генератора.
- `Makefile` — `make test`, `make lint`, `contract-test`; обычный pytest-вывод
  тихий, подробность можно включить через `PYTEST_ARGS`.
- `generator/src/clickstream_generator/state.py` — любая версия state не `3.0`
  даёт громкий `UnsupportedStateVersionError`; `from_dict_safe` больше не
  глотает ошибку старой/неизвестной версии.
- `generator/src/clickstream_generator/airflow_control.py` —
  `target_dag_trigger_error()` покрывает три ветки pause-check без импорта
  Airflow.
- `superset/create_dashboard.py` — sync ограничен чартами целевого dashboard.
- `docs/course/lessons/00_kafka_intro.md`,
  `docs/course/lessons/01_kafka_to_clickhouse.md`,
  `docs/course/lessons/05_monitoring.md` — курс согласован с startup-history,
  no-live default и consumer lag.

## Проверки

- Issue 15: `make generator-test`, `docker compose config --quiet`,
  `py_compile`, `bash -n`.
- Issue 16: `make generator-test`, `docker compose config --quiet`,
  `py_compile`, `make clean`, `make up`, `make ddl`.
- Issue 17: Docker target tests, `make generator-test`, `py_compile`,
  `bash -n`, `make generated-history-runtime-check`.
- Issue 18: doc `rg`, `git diff --check`,
  `make generated-history-analytics`, `make up`.
- Issue 19 / commit `9b0b063`: `make contract-test` — 16 passed;
  `make generator-test` — 190 passed; `make lint` — passed; `make test` —
  190 generator tests, 16 contract tests, `docker compose config --quiet`.
- Финальный chain review `Gibbs`: initial `CHANGES_REQUESTED`, narrow rerun
  `APPROVED`.

## Происхождение ревью

- 15: gate; task reviewer `Ptolemy` high, code reviewer `Linnaeus` high;
  оба rerun `APPROVED`.
- 16: code reviewer `Laplace` high; primary review found paused-DAG order bug,
  later reruns `APPROVED`.
- 17: code reviewer `Bacon` high; found Superset ownership and live-seam
  defaults; bounded runtime gate rerun `APPROVED`.
- 18: docs/code reviewer `Hume` high; found Prometheus scrape-count drift;
  rerun `APPROVED`.
- Финал: chain reviewer `Gibbs` xhigh; found docs drift around
  `generated-history-check`; rerun `APPROVED`.
- После `9b0b063`: внешний Claude review подтвердил закрытие всех девяти
  находок и дал `APPROVED`. Reviewer не перезапускал Docker-проверки сам, но
  сверил код, тесты и документы; фактические прогоны были выполнены
  координатором.

## Отклонения процесса

- Локальный `uv run ... pytest` у координатора падал до pytest из-за
  `snap-confine` / `cap_dac_override`. Для координаторского gate целевые тесты
  запускались через Docker-образ `generator:test`. Это вынесено в issue 19.
- Первичный runtime gate issue 17 через полный `daily-wave` был остановлен:
  прогон был активным, но слишком долгим для коммит-гейта. После этого добавлен
  bounded `make generated-history-runtime-check`.
- Несколько стендовых проверок чистили Docker volumes. Это ожидаемо для issue
  16-18 и зафиксировано в журнале.

## Что вручную проверить дальше

- Чистый ручной путь через Airflow UI: `make up`, `make ddl` или `ddl_init`,
  `airflow dags unpause etl_pipeline`, затем `generator_control` backfill.
- Backfill-only путь: `make generated-history-analytics`, затем
  `CHECK_LIVE_SEAM=0 make generated-history-check`.
- Стык backfill/live: `make generated-history-runtime-check`.
- Superset: после готового DM открыть dashboard и сверить, что чарты созданы и
  `Top Countries by Events` читается.
- Kafka UI: в уроке 00 должны быть понятны четыре data-топика и служебные
  `generator_state`, `generator_startup_history_manifest`,
  `generator_batch_history`.

## Suggested skills

- `triage` — если продолжать issue 13: он всё ещё `needs-triage`.
- `brainstorm-with-docs` — если перед issue 13 нужно заново согласовать
  модель доливки истории от слепка.
- `coordinator-loop` — только после перевода issue 13 в `ready-for-agent`.
- `code-review` — для внешнего прохода по коммитам после ручной проверки.

## Открытые риски

- Ручная HITL-проверка после `9b0b063` ещё не выполнена пользователем.
- Issue 13 остаётся `needs-triage`: доливка истории от слепка должна опираться
  на закрытые инварианты 15 и 17.