- Зачем:
- handoff должен отражать, что уже в трекере, а что осталось завести.
- Что:
- список «не забыть» сокращён: #1 и #2 созданы, остались лабы и
инкрементальный ETL.
- Проверка:
- gh issue list — два открытых issue.
- Зачем:
- full_refresh на каждый world_next_day пересчитывает весь мир —
с ростом мира это следующее узкое место после счётчиков manifest.
- Что:
- в список issues «не забыть» добавлен инкрементальный ETL со ссылкой
на legacy-план plans/incremental-etl-v2.md.
- Проверка:
- вычитка handoff.
- Зачем:
- следующая сессия должна стартовать от актуальной точки.
- Что:
- раздел «Что дальше» переписан: спека и контракт трекера сделаны,
остались issues и конвейер задач.
- Проверка:
- вычитка handoff.
- Зачем:
- три обещания спеки расходились с фактами кода и замеров HITL.
- Что:
- в путь менти возвращён шаг make superset-init; критерий «терминал
только make up» поправлен честно.
- критерий стоимости world_next_day сужен до генерации+manifest:
ETL full_refresh растёт с миром — явно вынесен в «чего не делаем».
- проверка профиля ×1 уточнена: runtime-seam уже на daily-wave,
проверять надо дефолты launch.py и автотесты.
- Проверка:
- сверка с scripts/run_generated_history_runtime_check.sh, Makefile
и замерами HITL (ETL 30 с на 110k событий).
- Зачем:
- находки ручного HITL 2026-07-19 требовали проектного решения: путь
менти через backfill медленный, бедный и путаный; нужна база import
эталонного мира и две ветки роста.
- Что:
- спека docs/specs/2026-07-19-mentee-path-redesign.md: целевая модель
(import + next-day + continue), эталонный 3-дневный мир в git (xz),
переименование пульта в world_init с дефолтом import, отдельный
world_next_day, инкрементальные счётчики manifest, один учебный
профиль; форма работ — 4 дочерних issue.
- CONTEXT.md: термины «мир (стенда)», «эталонный мир», «три режима
менти».
- .scratch/hitl-findings.md восстановлен из среза 0e312b3 как рабочий
материал фичи (до разбора в issues).
- Проверка:
- вычитка против hitl-findings и решений обсуждения 2026-07-19.
- Зачем:
- пилот нативного трекера на фиче mentee-path: спека в git как
источник истины, тонкий корневой issue, дочерние issues-постановки.
- Что:
- docs/agents/issue-tracker.md переписан с локального markdown на
GitHub Issues (gh CLI, правило тонкого корневого issue, архив
старых задач — в истории git, срез 0e312b3).
- triage-метки стали настоящими метками GitHub (созданы в репозитории),
AGENTS.md обновлён.
- Проверка:
- gh label list — пять канонических меток на месте.
- Зачем:
- после слияния feature/data-generator одноразовые материалы .scratch
(задачи 01-21, PRD, журналы, старые handoff'ы) больше не нужны:
долговечное живёт в docs/, история — в git (срез 0e312b3).
- Что:
- удалено всё содержимое .scratch (50 файлов).
- добавлен handoff 20260719-2229-mentee-path-start.md: направление
редизайна пути менти (4 задачи) и пилот GitHub Issues.
- Проверка:
- git show --stat; в .scratch остался только новый handoff.
- Зачем:
- перед слиянием в main документация должна совпадать с кодом:
ARCHITECTURE.md и REPO_MAP.md не знали про операцию next-day,
каталог generator/ и семь новых скриптов.
- Что:
- в ARCHITECTURE.md операция next-day добавлена в описание DAG
generator_control (три места).
- в REPO_MAP.md добавлены раздел Generator и семь скриптов
стартовой истории; описание generator_control дополнено.
- Проверка:
- make lint — зелёный; сверка списков с airflow/dags и scripts/.
- Зачем:
- форма Trigger DAG требовала заполнить все поля: канонический запуск
«выбрать профиль, остальное пусто» через UI был невозможен (находка F1
ручного HITL); артефакты backfill (data/*.json, 49 МБ) рисковали
попасть в коммит.
- Что:
- пять необязательных Param переведены на Param(None, type=["null",
"string"]) — идиома необязательного поля, проверено по Context7
(Airflow 2.10.5); все места чтения уже None-безопасны (or "").
- контрактный тест дополнен: у необязательных Param есть "null" в type,
у operation/profile — нет.
- .gitignore: правило data/*.json (сиды data/*.jsonl остаются под git);
задача 21 закрыта в .scratch.
- Проверка:
- make test (205 + 31 passed) и make lint — зелёные.
- Зачем:
- долг ручной HITL-проверки пути менти переносился пятый handoff подряд;
проверка вскрыла набор находок и наметила редизайн пути менти.
- Что:
- добавлены находки HITL (F1-F9) с рамочной моделью трёх режимов менти:
import-база, ветки next-day и continue, под каждую — свой урок/лаба.
- зафиксированы решения: 3-дневный артефакт на daily-wave, сжатие xz,
один учебный профиль, беспараметрный next-day, инкрементальные счётчики.
- добавлен handoff по ADR-0003 с планом раскладки находок в постановки.
- Проверка:
- чтение .scratch/generator-model-time-startup-history/hitl-findings.md
и .scratch/handoffs/20260719-2144-hitl-mentee-path-redesign.md.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
- Зачем:
- передать контекст новой сессии: конвейер задачи 13 завершён, следующие
шаги — задача про расписание, HITL-проверка пути менти, уроки плейбука.
- Что:
- добавлен handoff 20260712-2359 (итоги конвейера, состояние стенда,
план и отклонения процесса).
- убран отработанный handoff 20260712-2015 (одноразовый по ADR-0003).
- Проверка:
- вычитка handoff'а; ссылки на задачу 13 и коммиты f5dee26/540989d.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- режим кормления стенда порциями: менти триггерит «следующий день»,
видит полный цикл DWH за один шаг (задача 13, вариант 2 — генерация
от слепка T_end).
- Что:
- новый ограниченный режим next-day: восстановление мира из state,
генерация ровно [T_end, T_end+24h), публикация данные -> state ->
манифест (манифест — точка фиксации, автоотката нет).
- операция next-day в DAG generator_control: своя предпроверка границы
вместо clean-guard, идемпотентность через параметр expected_t_end.
- цепочка границ — накопительное поле boundaries в манифесте, старый
формат читается как [T0, T_end]; импорт не изменён.
- новая проверка цепочки (make generated-history-chain-check): непарные
счётчики и однородность по каждой границе, явный статус нулевого
стыка, хвост за границей по всем четырём топикам, литералы в UTC
с микросекундами.
- документация OPERATIONS.md: глагол, предпроверка, восстановление
после сбоя, ограничение retention; в задаче 13 — решения двух слепых
ревью постановки и кода с аргументами отклонений.
- Проверка:
- make test: 204 теста генератора + 31 контракт корня, зелёные.
- make generated-history-chain-check: зелёный, 2 внутренние границы,
непарные счётчики нулевые; учебный цикл: DM 322 -> 10026 -> 19196
за два next-day подряд.
- make generated-history-runtime-check (регрессия задачи 20): зелёный.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- два слепых ревью постановки (Codex и Claude) вернули CHANGES_REQUIRED:
guard чистого стенда противоречил доливке, не были заданы механизм
идемпотентности, точка фиксации, формат цепочки границ и проверки.
- Что:
- добавлен раздел «Решения по ревью постановки»: next-day как новый
ограниченный режим, день = [T_end, T_end+24h), предпроверка границы,
параметр expected_t_end, манифест как точка фиксации, поле boundaries,
батчевый режим проверки цепочки, расписание вынесено в отдельную задачу.
- критерии приёмки финализированы (были черновыми), добавлен раздел
«Границы (что не трогать)», исправлены ссылки на строки кода.
- Проверка:
- вычитка задачи; факты сверены обоими ревьюерами по коду ветки
(индексы находок — в обменном каталоге сессии).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- зафиксировать состояние для продолжения в новой сессии (ADR-0003).
- Что:
- handoff: итог конвейера по задаче 20, разблокированная задача 13,
план рефлексии по расходу контекста в subagent-playbook.
- Проверка:
- чтение handoff: ссылки на задачу и коммиты корректны, дерево чистое.
- Зачем:
- адверсарное ревью показало: генератор не обрабатывает SIGTERM
(python — PID 1, docker compose stop ведёт к SIGKILL посреди batch),
а вариант «ждать записи generator_batch_history» гонку не закрывает.
- Что:
- направление фикса: минимальный SIGTERM-хендлер с дозаписью batch,
альтернативы отклонены с доводами, bounded live mode вне скоупа.
- критерии дополнены: красный сценарий обязан ловиться, стабильность
обосновывается структурно, запрещены вероятностные смягчения.
- в диагноз внесены механизм обрыва и различие device/geo vs location.
- Проверка:
- чтение постановки: все находки ревью закрыты решением или доводом.
- Зачем:
- диагноз задачи 20 снял страх швов (генератор на стыке не ломает),
и пользователь выбрал вариант реализации next-day;
- сессия завершается - нужен handoff для продолжения.
- Что:
- задача 13: выбран вариант 2 (генерация следующего дня от слепка),
вариант нарезки артефакта отклонён с обоснованием; статус
ready-for-agent, blocked by задача 20;
- handoff сессии в .scratch/handoffs/ - итоги проверки пути менти,
состояние трекера, план (фикс 20 -> задача 13 -> HITL).
- Проверка:
- чтение задачи 13 и handoff; git status чистый после коммита.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- Codex-диагноз нашёл корень нестабильности runtime-гейта: гонка
остановки live-генератора, batch публикуется по топикам без
атомарности, seam-SQL маскирует непарные строки под смену фактуры;
- попутно закрыт второй открытый вопрос задачи 13 - запасная ветка
рождения визита уже хранит донора (фикс задачи 09).
- Что:
- задача 20: диагноз с судьбой трёх гипотез, направление фикса
(управляемая остановка live + precheck непарных строк), статус
ready-for-agent;
- задача 13: вопрос про fallback-ветку закрыт, статус ready-for-human
(осталось решение по развилке реализации).
- Проверка:
- утверждение про донора перепроверено по generation.py:194-209;
эмпирика диагноза - в логах прогонов, пути в задаче 20.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- плейбук оркестрации опирается на репо-локальных субагентов для
глубоких рассуждений и шумной механики; в этом репозитории их
ещё не было.
- Что:
- созданы .claude/agents/deep-reasoner.md (Opus, high) и
.claude/agents/fast-worker.md (Sonnet) по референсу скилла
claude-subagent-playbook;
- .gitignore: локальное содержимое .claude/ скрыто, agents/
коммитятся.
- Проверка:
- git status не показывает .claude/settings.local.json;
субагенты видны в новой сессии Claude Code.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- ревью пути менти 2026-07-07 нашло четыре места, где документация
сбивает новичка: скрытый шаг с паузой etl_pipeline, два рецепта
первого запуска без связки, неверное число дашбордов и пустые
панели Airflow на backfill-only пути.
- Что:
- README: добавлен шаг «снимите паузу с etl_pipeline» перед backfill
и пометка, что generated-history-analytics — тот же путь одной
командой;
- курс: README курса связывает оба рецепта первого запуска, урок 05
называет четыре дашборда (включая Generator Overview) и объясняет,
почему панели Airflow пусты до запуска etl_pipeline.
- Проверка:
- чтение задетых разделов; имена дашбордов сверены с provisioning
Grafana в ходе ревью.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- рамка задачи 13 пересмотрена: ценность доливки — кормление стенда
дневными батчами (урок и имитация жизни), а не удлинение истории;
- прогон пути менти 2026-07-07 показал, что runtime-гейт стыка
backfill->live нестабилен — красный/зелёный через раз.
- Что:
- задача 13 переписана под глагол next-day в generator_control:
сценарии, развилка реализации (срез артефакта против доливки от
слепка), закрыт вопрос про импорт частями (сейчас всё или ничего);
- добавлена задача 20 про нестабильную runtime-проверку стыка с
эмпирикой двух прогонов и гипотезами для диагноза.
- Проверка:
- два прогона make generated-history-runtime-check (красный 8/19,
затем зелёный) — зафиксированы в задаче 20.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- коммит-гейт не запускал корневые контрактные тесты, а часть подтверждённых обходов могла снова смешать разные миры генератора.
- Что:
- добавлены цели make test, make lint и contract-test с тихим pytest-выводом через Docker.
- закрыты обходы через generator-reset, неизвестную версию state и fail-open проверку DM-витрин.
- усилены поведенческие контракты CHECK_LIVE_SEAM, профиля manifest и pause-check etl_pipeline; обновлены документы и issue 19.
- Проверка:
- make test; make lint; git diff --check.
- Зачем:
- coordinator-loop требует handoff для внешнего кросс-линейного ревью.
- Что:
- добавлена записка с индексом изменений, ревью и открытыми рисками.
- журнал фиксирует завершение финального review и handoff.
- Проверка:
- staged-состав содержит только handoff и журнал.
- Зачем:
- backfill-only сценарии не должны советовать проверку, которая требует live seam.
- Что:
- для backfill/import-only путей указан CHECK_LIVE_SEAM=0.
- live-проверка вынесена в generated-history-runtime-check или явно описанный live-путь.
- журнал дополнен финальным review и rerun.
- Проверка:
- финальный chain review rerun APPROVED; git diff --check.
- Зачем:
- коммит-гейт coordinator-loop требует единых быстрых команд проверки.
- Что:
- добавлен issue 19 для make test и make lint.
- PRD обновлён после закрытия задач 15-18.
- журнал фиксирует follow-up перед финальным review.
- Проверка:
- staged-состав содержит только PRD, журнал и issue 19.
- Зачем:
- coordinator-loop отделяет рабочие изменения от статусов и журнала.
- Что:
- задача 18 переведена в done с закрытыми критериями.
- журнал дополнен ревью, проверками чистого маршрута и коммитом.
- Проверка:
- staged-состав содержит только issue 18 и журнал.
- Зачем:
- курс должен проходить на чистом стенде без архивного сида и скрытых шагов.
- Что:
- уроки 00, 01 и 05 согласованы с генераторными топиками, no-live default и consumer lag.
- упражнение с kafka_msg_ts переведено на повторную заливку без сброса схемы.
- учебный путь в операционной документации ведёт через startup-history.
- Проверка:
- make generated-history-analytics; make up; doc rg checks; git diff --check.
- Зачем:
- coordinator-loop отделяет рабочий срез от статусов и журнала.
- Что:
- задача 17 переведена в done с закрытыми критериями.
- журнал дополнен ревью, bounded runtime gate и коммитом.
- Проверка:
- staged-состав содержит только issue 17 и журнал.
- Зачем:
- зелёный результат проверок должен означать фактический стык и точный контракт дашборда.
- Что:
- проверка startup-history читает manifest, требует live seam и непустой ODS.
- добавлен быстрый runtime gate для daily-wave и live-продолжения.
- Superset sync ограничен целевым dashboard и сверяет существенные params.
- Проверка:
- docker target tests; make generator-test; make generated-history-runtime-check.
- Зачем:
- coordinator-loop отделяет рабочие изменения от статусов и журнала.
- Что:
- задача 16 переведена в done с закрытыми критериями.
- журнал дополнен ревью, стендовым gate и коммитами.
- Проверка:
- staged-состав содержит только issue 16 и журнал.
- Зачем:
- свежий стенд должен доходить до generator_control без скрытых ручных шагов и зависаний.
- Что:
- quick start явно готовит DDL и откладывает Superset init до готового DM.
- generator_control проверяет паузу etl_pipeline до мутирующих шагов.
- make up пересобирает Airflow и поднимает базовый набор сервисов.
- Проверка:
- make generator-test; docker compose config --quiet; make clean; make up; make ddl.
- Зачем:
- coordinator-loop требует отделять рабочий срез от статусов и журнала.
- Что:
- задача 15 переведена в done с закрытыми критериями.
- журнал дополнен происхождением ревью и коммит-гейтом.
- Проверка:
- git status --short и staged-состав перед коммитом.
- Зачем:
- старый state и ручной live-генератор могли тихо писать события в новый мир данных.
- Что:
- добавлена общая проверка чистого стенда для Airflow и host-путей.
- защищены backfill, import, continue и clean-start сценарии live-generator.
- описан миграционный отказ старого state.
- Проверка:
- make generator-test; docker compose config --quiet; py_compile; bash -n.
- Зачем:
- формат даты в имени handoff-файла приведён в соответствие с фактическим шаблоном, который использует скилл.
- Что:
- изменён шаблон имени с `.scratch/handoffs/YYYY-MM-DD-<slug>.md` на `.scratch/handoffs/YYYYMMDD-HHMM-<slug>.md` в AGENTS.md.
- Проверка:
- открыть AGENTS.md и убедиться, что указан актуальный формат.
- Зачем:
- зафиксировать результат кросс-прохода другой родословной по
c672ed0..ec815ce для передачи в багфикс-цепочку.
- Что:
- отчёт: 1 critical, 5 high, 10 medium, 4 low; четыре сквозных семейства
(смешение миров, стенд без live, ложнозелёные проверки, чистый клон).
- маршрутизация находок и предложение порядка багфикс-цепочки.
- Проверка:
- находки доказаны исполнением: мутационные тесты, compose-эксперимент,
зонды на сиде, Context7 по Airflow 2.10.5.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- следующий шаг handoff — независимый ревью диапазона c672ed0..HEAD;
результат нужно зафиксировать для продолжения в новой сессии.
- Что:
- добавлен раздел «Независимый ревью-проход» (свежий взгляд, без субагентов):
вердикт, прогнанные тесты 172+5, находки по задачам, косметические мелочи.
- обновлены «Открытые риски» и «Следующий шаг»: остаётся HITL-приёмка и
решение по задаче 13.
- Проверка:
- git show --stat HEAD; ревью-раздел читается в handoff.
- Зачем:
- финальный review должен видеть согласованные PRD, issue, курс, Superset и архитектурные документы.
- Что:
- обновлены PRD, чекбоксы закрытых issue и журнал coordinator-loop.
- синхронизированы архитектура, карта репозитория, CONTEXT и курс со startup-history-путём.
- убраны старые маркеры Superset-геокарты после перехода на Top Countries.
- Проверка:
- rg-проверки финального review по PRD, issue и Superset-маркерам.
- git diff --cached --check.
- Зачем:
- нужно зафиксировать состояние трекера после рабочего коммита issue 08.
- Что:
- задача 08 переведена в done.
- журнал coordinator-loop дополнен ревью-гейтом и коммит-гейтом.
- Проверка:
- git diff --cached --check.
- Зачем:
- учебный путь должен идти через генерацию и штатный пайплайн, а не через архивный сид.
- Что:
- обновлены уроки 00-06 и стандарт урока под startup-history/backfill.
- объяснено, что data/*.jsonl остаются кладовкой значений генератора.
- тест-план переведён на новый штатный запуск и HITL-приёмку.
- Проверка:
- rg -n \"make clean/up/ddl/data/transform|make data|kafka_load|LIMIT=|2022-11-28|26 из 50\" docs/course docs/TEST_PLAN.md.
- git diff --cached --check.
- Зачем:
- нужно зафиксировать состояние трекера после рабочего коммита issue 10.
- Что:
- задача 10 переведена в done.
- журнал coordinator-loop дополнен ревью-гейтом и коммит-гейтом.
- Проверка:
- git diff --cached --check.
- Зачем:
- гео-блок дашборда должен показывать понятную метрику, единицы и сравнение стран.
- Что:
- legacy world_map заменён на столбцы Top Countries by Events с tooltip и легендой.
- синхронизирован экспорт дашборда и добавлены контрактные тесты.
- обновлены документы и урок Superset по новому гео-блоку.
- Проверка:
- uv run --with pytest pytest tests/test_superset_dashboard_config.py.
- uv run python -m py_compile superset/create_dashboard.py tests/test_superset_dashboard_config.py.
- jq empty superset/dashboards/ecommerce_analytics.zip.json.
- Зачем:
- нужно зафиксировать состояние трекера после рабочего коммита issue 09.
- Что:
- задача 09 переведена в done.
- журнал coordinator-loop дополнен двумя кругами гейтового ревью и коммит-гейтом.
- Проверка:
- git diff --cached --check.
- Зачем:
- визит после восстановления не должен менять браузер и источники перехода внутри одного click_id.
- Что:
- добавлен base_click_id в state v3 для восстановления донора фактуры.
- исправлено восстановление timestamp offset без потери микросекунд.
- расширены тесты и стыковая проверка browser/source и device/os/geo.
- Проверка:
- uv run --with-requirements generator/requirements.txt pytest generator/tests -q.
- bash -n scripts/check_generated_analytics.sh.
- git diff --cached --check.
- Зачем:
- нужно зафиксировать состояние трекера после рабочего коммита issue 14.
- Что:
- задача 14 переведена в done.
- журнал coordinator-loop дополнен ревью-гейтом и коммит-гейтом.
- Проверка:
- git diff --cached --check.
- Зачем:
- суточная волна должна быть видна на занятии за минуты, а не за сутки работы стенда.
- Что:
- профиль daily-wave переведён на speed 60 при тике 1 секунда.
- приглушены подробные live-логи успешного тика без изменения сохранения state.
- обновлены тесты, спека и инструкции запуска быстрого профиля.
- Проверка:
- make generator-test.
- git diff --cached --check.
- Зачем:
- нужно зафиксировать состояние трекера после рабочего коммита issue 12.
- Что:
- задача 12 переведена в done.
- журнал coordinator-loop дополнен ревью-гейтом и коммит-гейтом.
- Проверка:
- git diff --cached --check.
- Зачем:
- нужен основной ручной интерфейс стенда для backfill/import/check без консольной матрицы переменных.
- Что:
- добавлен DAG generator_control с параметрами Airflow, ветвлением операций и ожиданием ETL.
- вынесена общая логика запуска и предпроверок генератора для Airflow.
- обновлены compose-настройки, зависимости, тесты и документация по пульту.
- Проверка:
- uv run --with pytest --with-requirements generator/requirements.txt pytest generator/tests -q.
- docker compose config --quiet.
- Зачем:
- подготовить цепочку 12 -> 14 -> 09 -> 10 -> 08 к передаче в coordinator-loop:
задаче 12 не хватало решений после 07 и 11, задача 14 родилась из обсуждения
учебного UX (суточная волна вживую).
- Что:
- issue 12 (DAG-пульт): решения 2026-07-04 — без Docker-доступа из Airflow,
операции как Python-код генератора в тасках, генератор без автостарта,
границы пульта, предпроверки чистоты (топики + STG), ожидание ETL перед
check; учтены находки адверсарного ревью и ревью Codex.
- issue 14 (новая): профиль daily-wave переводится на speed=60 при тике 1 с —
модельный час за настенную минуту без изменения фактуры мира.
- issue 08: мягкие зависимости от 14 и 09 (артефакт курса рождается после
них), режим ревью; PRD: задача 14 в списке и графе, 12 помечена дооформленной.
- Проверка:
- вычитка: статусы задач ready-for-agent, порядок в PRD и Blocked by
согласованы; mermaid-граф рендерится.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- нужно зафиксировать итог coordinator-loop и обновить порядок оставшихся задач.
- Что:
- PRD обновлен после завершения issue 07 и 11.
- журнал дополнен финальным review и диагностикой nested reviewer tools.
- Проверка:
- git diff --cached --check.
- Зачем:
- узкое место — время человека на ручную приёмку: без DAG-пульта проверять
миграцию курса пришлось бы через консоль.
- Что:
- PRD, раздел «Задачи»: номер файла объявлен идентификатором (не порядком),
порядок задан ветками и mermaid-графом; основная цепочка 07 -> 11 -> 12,
миграция курса 08 — последней.
- issue 08: добавлена мягкая зависимость от 12 (приёмка уроков через пульт).
- handoff триажа: раздел «Следующий шаг» обновлён под новый порядок.
- Проверка:
- mermaid-диаграмма проверена валидатором Mermaid; статусы задач не менялись.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- закрыть последний шаг триажа: без Acceptance criteria и способа приёмки
задачи нельзя передавать Codex на исполнение.
- Что:
- issue 09: причина уточнена по коду (расходится источник фактуры — донор
против seed_click_id, а не индекс), зафиксировано решение хранить донора
в state, критерии расширены полями location (referer, utm) по итогам ревью.
- issue 10: приёмка по скриншотам playwright-cli с определением «читаемо»,
поправлена длительность пересборки (6 часов по умолчанию, не 2 суток),
отмечено, что legacy world_map, похоже, не умеет легенду и tooltip.
- handoff триажа дополнен сдвигами в понимании и итогом тройного ревью.
- Проверка:
- утверждения по коду сверены с generation.py, runtime.py, state.py и
sql/ddl/dds/30_dds.sql двумя независимыми ревью-агентами.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- продолжение работы планируется в новой сессии; нужен одноразовый
handoff по ADR-0003 с решениями дня и точкой входа.
- Что:
- записан handoff: рабочая форма Claude/Codex, решения по целеполаганию
и бэклогу, очередь задач, следующий шаг — дооформить 09 и 10 до
ready-for-agent, затем передача Codex.
- Проверка:
- просмотр .scratch/handoffs/2026-07-04-generator-backlog-triage.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- в конвенции набора скиллов нет состояния «сделано» (в GitHub это
закрытие issue), из-за чего закрытые задачи помечались случайными
ролями триажа (ready-for-human на сделанных 01-06).
- Что:
- в issue-tracker.md добавлено: завершённая задача — Status: done,
состояние жизненного цикла трекера, а не роль триажа;
triage-labels.md с пятью ролями не тронут.
- Проверка:
- просмотр docs/agents/issue-tracker.md, раздел «Соглашения».
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- follow-up задачи после ревью 2026-06-14 лежали без триажа; решения по
артефакту, громкому отказу и интерфейсу приняты 2026-07-04 и должны
попасть в задачи до передачи исполнителю.
- Что:
- задачи 07 (миграция курса) и 08 (артефакт) поменяны местами — номера
отражают порядок; ссылки обновлены.
- 07 (артефакт + runbook) дооформлен: импорт строго через Kafka (напрямую
в ClickHouse не пишет), громкий отказ при несовместимом state с правкой
спеки, граница runbook «использование, не устройство»; ready-for-agent.
- 08 дооформлен: устройство генератора вне пути менти, реальный объём
(make data во всех уроках 00-05), демо вне скоупа; ready-for-agent.
- новые задачи: 11 глаголы/длительность/профили (после 07, до 12),
12 Airflow-DAG как пульт (приоритет поднят), 13 доливка (после 09).
- задачи 01-06 переведены в done (стояли ошибочные ready-for-human);
PRD фичи дополнен списком задач 7-13 с порядком и зависимостями.
- Проверка:
- head -1 .scratch/generator-model-time-startup-history/issues/*.md;
grep по старым именам файлов ничего не находит вне handoff.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- целеполагание было размазано по обсуждениям: место стенда в менторской
программе и иерархия целей нигде не были записаны, а демо-употребление
стенда устарело (выросло в отдельный проект).
- Что:
- PRD курса §1: место стенда в треке ClickHouse (теория и лабы вне репо,
здесь — интеграции), иерархия целей курс -> стенд -> генератор;
схема потока обновлена на генератор как источник.
- PRD §7: закрыта развилка про урок о генераторе (урока не будет,
генератор — скрытая инфраструктура), добавлена открытая развилка про
кластерную конфигурацию.
- удалены DEMO_CHEATSHEET_5MIN.md и DEMO_SCRIPT_10_15MIN.md; ссылок на них
в репозитории не осталось.
- Проверка:
- grep -rn "DEMO_CHEATSHEET\|DEMO_SCRIPT" --include="*.md" . — только
исторический handoff.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- после coordinator-loop нужно независимое ревью результатов модельного
времени и стартовой истории; пропущенный внешний review gate после задачи 5
закрыт другой родословной.
- Что:
- добавлен verification-handoff: что проверено независимо, дефект стыка
(issue 09) и открытые пробелы (×K, crash recovery, коридоры мат-спеки,
воспроизводимость, review gate задачи 3).
- заведены issues 08 (портативный артефакт + runbook + идеи интерфейса),
09 (баг браузерной фактуры на стыке), 10 (читаемость гео-карты).
- в docs/course/PRD.md §7 — открытый вопрос «генератор как скрытая
инфраструктура vs отдельный урок».
- Проверка:
- git show --stat HEAD
- чтение .scratch/handoffs/2026-06-14-generator-model-time-verification-review.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- авторитетная версия должна жить у навыка (dotfiles), рядом с handoff-побратимом; здесь — чтобы не плодить расходящиеся копии.
- Что:
- полное содержимое заменено коротким указателем на dotfiles-версию.
- Проверка:
- открыть .scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- сохранить выводы сессии проектирования, пока свежие; без записи они теряются при компактизации и в новой сессии.
- Что:
- добавлен handoff с диагностикой двух «пожаров» — контекста координатора и токенов — по логам прогона Codex.
- зафиксированы prior art (obra:superpowers), два принятых правила, кандидаты-фиксы и открытые вопросы.
- Проверка:
- открыть .scratch/handoffs/2026-06-14-coordinator-loop-context-economy.md
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- чистый стенд должен строить аналитику из генерации, а не из архивного JSONL-сида.
- Что:
- добавлены команды generated-history-analytics и generated-history-check.
- обновлены README, operations и Superset-документы под путь generator backfill -> DM -> Superset.
- создан follow-up на миграцию учебных материалов с архивного сида.
- Проверка:
- make generated-history-analytics.
- make generated-history-check.
- reviewer gate issue 06 пройден без блокирующих находок.
- Зачем:
- стенду нужна повторяемая история с живым продолжением от модельной границы без дублей и разрыва визитов.
- Что:
- добавлен backfill-режим с `GEN_MODEL_T_END`, manifest и state на `T_end`.
- live-запуск восстанавливается из manifest без настенной дельты и проверяет совместимость state.
- добавлены SQL-проверки формы данных, повторяемости и стыка backfill с live.
- Проверка:
- make generator-test.
- два чистых ClickHouse-прогона backfill дали одинаковые manifest checksums и digest.
- reviewer gate issue 05 пройден после исправлений state/manifest.
- Зачем:
- рестарт генератора должен продолжать поток от модельной точки без дублей и смешивания state разных настроек.
- Что:
- state v2 хранит модельную и настенную метки, скорость, timezone, T0 и seed.
- live-восстановление считает модельную точку по настенной дельте и проверяет совместимость config.
- добавлен путь восстановления от T_end и тесты короткого и долгого простоя.
- Проверка:
- make generator-test.
- ClickHouse-сценарии короткого и долгого восстановления state.
- reviewer gate issue 04 пройден после исправления совместимости state.
- Зачем:
- ускоренный стенд должен проходить больше модельного времени и давать соответствующий событийный бюджет.
- Что:
- расчёт интенсивности переведён на модельную длительность тика.
- добавлена устойчивая выборка бюджета при больших λ.
- усилены тесты ×K, дневного коэффициента и независимости от настенного часа.
- Проверка:
- make generator-test.
- review gate после issue 03 пройден после исправления underflow Poisson.
- Зачем:
- генератор должен писать события от модельной точки T0 и проверяться повторяемо в ClickHouse.
- Что:
- добавлены настройки модельного времени и передача модельной точки в live-тик.
- дневной коэффициент считается по модельному времени и часовому поясу.
- обновлены проверки, compose, документация и статус issue 02.
- Проверка:
- make generator-test.
- два чистых ClickHouse-прогона с GEN_STATE_RESET=true дали одинаковые контрольные числа.
- Зачем:
- нужно закрепить принятое человеком HITL-решение до кодовых задач 02-06.
- Что:
- добавлен рабочий контракт настроек, хода часов, state, манифеста и ClickHouse-проверки.
- выбран один живой ход часов через фиксированный модельный шаг без отдельной матрицы драйверов.
- уточнена граница стартовой истории как [T0, T_end) и закрыт чек-лист issue 01.
- Проверка:
- git diff --cached --check.
- Зачем:
- ревью выявило слабые места в критериях приёмки модельного времени.
- Что:
- уточнены правила повторяемости, чистого прогона и review gate.
- добавлены критерии для однородности визита через восстановление и T_end.
- обновлён handoff с важными рисками для следующего агента.
- Проверка:
- git diff --check.
- Зачем:
- нужен рабочий план для реализации модельного времени и стартовой истории.
- Что:
- добавлен parent PRD с инвариантами, зависимостями и review gate.
- добавлены шесть локальных issue для последовательной работы.
- добавлен handoff для продолжения в новой сессии.
- Проверка:
- git diff --check.
- Зачем:
- ADR-0006 сделал генерацию единственным источником аналитики, а статический
сид — архивным; глоссарий и спеки это ещё не отражали.
- Что:
- CONTEXT.md: «статический сид» переименован в «архивный статический сид»
(короткое имя сохранено), описан как временная кладовка значений с целью
полного вывода; «стартовая история» получила синонимы «стартовый сид» и
«новый сид»; раздел «Слои данных» отмечает переход аналитики на генерацию.
- мат-спека: разделы «Персистентность через рестарты» и «Воспроизводимость»
помечены как переописанные в спеке модельного времени (ссылкой, без повтора).
- спека модельного времени: синоним «стартовый сид» добавлен в определение и
в заметку о влиянии на документацию.
- Проверка:
- git diff: термины и перекрёстные ссылки читаются непротиворечиво; ADR не
правились (статус «архивный» не переносится в документы до ADR-0006).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- сохранить контекст сессии для продолжения работы в новой сессии.
- Что:
- добавлен handoff: что сделано и закоммичено, контекст вне артефактов, очередь шагов, ограничения.
- Проверка:
- чтение .scratch/handoffs/2026-06-14-adr0006-source-flip-and-model-time-spec.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- кириллица занимает примерно в 1,5–2 раза больше токенов; рассуждения можно вести экономнее.
- Что:
- добавлено правило: внутренние рассуждения и промежуточные пометки — на английском.
- русский остаётся для ответов пользователю, документов, комментариев в коде и сообщений коммитов.
- Проверка:
- чтение AGENTS.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- генератор даёт здоровую пирамиду, и стенду нужен единый источник аналитики вместо вырожденного статического сида.
- Что:
- добавлен ADR-0006: генерация — единственный источник аналитики, статический сид становится архивным (кладовка значений до синтеза фактуры).
- добавлена спека модельного времени: точка отсчёта, заливка прошлого, стартовая история, сохранение состояния, воспроизводимость и проверка в два шага.
- в ADR-0004 и ADR-0005 добавлены указатели вперёд на ADR-0006 и спеку.
- Проверка:
- чтение документов; перекрёстные ссылки между ADR-0004/0005/0006 и спекой согласованы.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- закрыть отложенный заход эксперимента: внешнее ревью результата
автономной петли моделью другой родословной (дизайн-линия, не Кодекс).
- Что:
- добавлена секция об итогах ревью: прогноз по находке A не оправдался,
петля её поймала (try→fresh + регрессионный тест в коммите 640050e).
- зафиксировано, что внешний взгляд добавил сквозные находки (расхождение
живого/восстановленного путей, форма распределения длины визита).
- уточнена гипотеза о пользе reviewer-а другой родословной.
- Проверка:
- git show --stat HEAD; чтение docs/research/2026-06-11-subagent-coordinator-experiment.md.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Зачем:
- генератор не влит и неочевидно почему; при возврате к нему легко
переоткрывать заново вывод, что click_id на событие ломает семантику визита.
- Что:
- добавлен KNOWN_ISSUES.md: модель интенсивности ок, модель сущностей неверна,
план перехода на иерархию пользователь -> сессия -> событие.
- в шапку README.md добавлено предупреждение со ссылкой на KNOWN_ISSUES.md.
- Проверка:
- прочитать generator/KNOWN_ISSUES.md и сверить с generate_batch() в generator.py.
- Зачем:
- нужно зафиксировать архитектуру перехода от full refresh к инкрементальной загрузке
- план служит референсом для реализации и code review
- Что:
- добавлен plans/incremental-etl-v2.md с полным описанием:
* архитектура watermark (event_ts + lookback 5min)
* DDL для meta.etl_watermarks_history с TTL 30 дней
* SQL шаблоны для всех слоев (ODS, DDS, DM)
* структура DAG с параллельной загрузкой ODS
* функции get_watermark и save_watermark
* алерты Grafana для late arrivals
* демонстрация late arrivals через комментарии и логи
* сценарии тестирования
* оценка трудозатрат (15-16 часов)
- Проверка:
- файл создан: plans/incremental-etl-v2.md
- структура соответствует принятой архитектуре
- все параметры согласованы (TTL, lookback, параллельность)
- Зачем:
- нужна визуализация метрик generator в реальном времени
- Prometheus job уже настроен, не хватает Grafana dashboard
- Что:
- добавлен provisioning-файл dashboards/generator-overview.json
- 6 разделов: Overview, Events by Topic, Errors, Tick Statistics, Status, Info
- Overview: Total Events/min (все 4 топика), Tick Duration (p50/p99)
- Events by Topic: bar chart Events per Hour, Events Rate, Total Events
- Errors: Total Errors, Error Rate, Errors by Topic (с 'or on() vector(0)')
- Tick Statistics: Duration Distribution, Hour Factor (text), Tick Interval (text)
- Status: Generator Status (threshold 120s), Generator Health (heartbeat), Time Since Last Tick
- Info: команды и предупреждения о хардкоде GEN_TICK_SECONDS=5s
- исправлены панели ошибок с 'or on() vector(0)' для корректного отображения 0
- заменен heatmap на bar chart для стабильности
- добавлены пояснения про Events/min = сумма 4 связанных топиков
- Hour Factor синхронизирован с кодом генератора (00-05/09-18)
- Generator Health: переименовано из State Management с value mappings
- обновлены docs/OPERATIONS.md и generator/README.md
- удален устаревший plans/generator-monitoring-plan.md
- Проверка:
- дашборд открывается на http://localhost:3000/d/generator-overview
- все панели отображают данные корректно (протестировано через Playwright)
- ошибки показывают 0 вместо No data
- Events/min корректно отображает сумму всех 4 топиков (~800-1000/min)
- Зачем:
- упростить и сделать безопаснее сериализацию состояния генератора
- повысить устойчивость старта при временной недоступности Kafka
- Что:
- заменена сериализация rng state на JSON-safe формат без pickle/base64
- добавлено восстановление tuple-структуры rng state после json
- добавлен общий retry с exponential backoff для ensure_topics
- обновлена документация по continuity и ограничениям после рестарта
- расширены тесты state-сценариев и retry-логики
- Проверка:
- make generator-test
- 50 passed
- Зачем:
- генератор должен продолжать работу с места остановки после падения/рестарта
- нужно сохранять continuity тиков и состояние RNG для воспроизводимости
- Что:
- добавлен GeneratorState dataclass (tick, rng_state, last_batch_id, timestamp)
- добавлен KafkaStateManager для работы с compact topic generator_state
- топик создаётся с cleanup.policy=compact (хранится только последнее значение)
- интеграция в GeneratorService: восстановление при старте, сохранение после тика
- новые env: GEN_STATE_ENABLED (по умолчанию true), GEN_STATE_RESET (по умолчанию false)
- добавлены тесты test_state.py
- обновлена документация README.md
- Проверка:
- make generator-test (45 тестов проходят)
- docker compose restart generator - продолжает с сохранённого tick
- GEN_STATE_RESET=true - начинает с tick=1
- Изолированы ошибки history-канала: best-effort с логированием, не валят тик
- Добавлено явное создание топика generator_batch_history при старте
- Добавлена защита от пустого словаря (ValueError при загрузке)
- Обновлена документация о структуре тестов
- Исправлены тесты на пустой словарь
Ревью: изоляция ошибок history, явное создание топика, защита от пустых данных
- Удалён класс InMemoryBatchHistory и вся fallback-логика
- Упрощён KafkaBatchHistory: убраны _initialized, get_stats(), обработка ошибок
- Обновлена документация (generator/README.md, docs/OPERATIONS.md)
- Упрощены тесты, удалены тесты для удалённого функционала
- Код стал честнее: без Kafka генератор падает при старте
Ревьюер: Prometheus даёт достаточно visibility, fallback избыточен
- Зачем:
- ревью rev5: ClickHouse-интеграция была проблемной (порт 9000 native vs HTTP,
неработающий fallback, отсутствие DDL для базы meta)
- архитектурно чище: генератор остаётся pure Kafka producer,
история доступна для аналитики через стандартный ingestion
- Что:
- удален ClickHouseBatchHistory, clickhouse-connect зависимость
- добавлен KafkaBatchHistory с записью в топик generator_batch_history
- добавлен BatchRecord.to_dict() для JSON-сериализации
- добавлен рабочий fallback: Kafka → InMemory при недоступности
- удален pytest-asyncio (не использовался)
- добавлены тесты test_kafka_history.py (15 тестов) и test_service.py (6 тестов)
- обновлена документация: топик вместо таблицы ClickHouse
- Проверка:
- make generator-test: 44/44 тестов пройдено
- docker-compose валиден, генератор не зависит от clickhouse
- Зачем:
- были только standalone скрипты без системы запуска
- нужна стандартная система тестирования для CI/CD
- Что:
- добавлен pytest и pytest-asyncio в requirements.txt
- создана директория tests/ с conftest.py (fixtures)
- разделены тесты по модулям: test_config, test_generation, test_history
- добавлены команды в Makefile: generator-test, generator-test-build, generator-test-cov
- удалены устаревшие test_local.py и test_comprehensive.py
- обновлена документация в README.md
- Проверка:
- make generator-test — 23/23 тестов пройдено
- Зачем:
- нужен постоянный поток данных для демонстрации работы стека
- текущий batch-загрузчик не позволяет показать streaming-сценарии
- Что:
- добавлен сервис generator с режимом steady (Poisson-интенсивность)
- генератор публикует в 4 топика: browser/location/device/geo_events
- сохраняются связи event_id и click_id между событиями
- сборка через uv для скорости и компактности образа
- добавлены команды generator-* в Makefile
- комплексные тесты: валидация, статистика, формат сообщений
- Проверка:
- `docker run --rm -v $(pwd)/..:/workspace -w /workspace/generator generator:test python test_comprehensive.py` — 8/8 тестов
- `make generator-up` — 3 тика без ошибок, отправлено 2904 сообщения
- Зачем:
- зафиксировать решение об observability генератора на уровне MVP-плана
- Что:
- добавлены требования по /metrics, scrape_config и target generator:9109
- добавлен env-параметр GEN_METRICS_PORT
- обновлены шаг внедрения и критерии успеха
- Проверка:
- проверен diff только для plans/generator_demo_stream_plan.md
- Зачем:
- убрать рассинхрон между кратким ТЗ, архитектурой и планом генератора
- Что:
- сокращен docs/DE-task.md до формата краткого ТЗ проекта
- обновлены docs/ARCHITECTURE.md и README.md: bootstrap через kafka_load и steady-stream через generator-service
- обновлен plans/generator_demo_stream_plan.md: режим steady-stream и тик-публикация
- Проверка:
- просмотрен git diff по измененным файлам
- в коммит включены только мои документационные изменения
- Зачем:
- зафиксировать реалистичный MVP без переусложнения
- Что:
- оставлен один режим steady для автономного генератора
- добавлена минимальная статистическая модель потока на базе Poisson
- уточнены минимальные метрики, история batch и короткий roadmap внедрения
- Проверка:
- проверен diff и итоговое содержимое plans/generator_demo_stream_plan.md
- Зачем:
- фича готова: продвинутый курс (уроки 0–6), редизайн Superset, гейт целостности
DDS, мониторинг и выверенные по коду профильные доки. Codex работу завершил.
- Что:
- --no-ff merge ветки docs/advanced-clickstream-course.
- артефакты .scratch/ (handoff'ы, аудит) намеренно исключены из дерева main.
- Проверка:
- git ls-tree -r HEAD не содержит .scratch; git show --summary HEAD — два родителя.
- Зачем:
- следующей сессии нужна точка опоры: что сделано, какой канон у слоёв и какие
хвосты остались вне скоупа.
- Что:
- добавлен .scratch/handoffs/2026-06-06-docs-accuracy-done.md.
- зафиксированы рамка путей (Airflow — основной, scripts/make — запасной),
канон по урокам 2–3 и открытые хвосты (лицензия, непроверенные уроки 0,1,4–6).
- Проверка:
- git show --stat HEAD; ссылки на findings.md и коммит 92e9c4b актуальны.
ddadmin
