From 79c2c2657cdee00ac49e9e7b524799f668f7e496 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 14 Jun 2026 16:12:46 +0300 Subject: [PATCH] =?UTF-8?q?docs(generator):=20=D1=83=D1=82=D0=BE=D1=87?= =?UTF-8?q?=D0=BD=D0=B5=D0=BD=D1=8B=20=D0=B7=D0=B0=D0=B4=D0=B0=D1=87=D0=B8?= =?UTF-8?q?=20=D0=BF=D0=BE=20=D0=BC=D0=BE=D0=B4=D0=B5=D0=BB=D1=8C=D0=BD?= =?UTF-8?q?=D0=BE=D0=BC=D1=83=20=D0=B2=D1=80=D0=B5=D0=BC=D0=B5=D0=BD=D0=B8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - ревью выявило слабые места в критериях приёмки модельного времени. - Что: - уточнены правила повторяемости, чистого прогона и review gate. - добавлены критерии для однородности визита через восстановление и T_end. - обновлён handoff с важными рисками для следующего агента. - Проверка: - git diff --check. --- .../PRD.md | 29 ++++++++++++++----- .../01-time-and-startup-history-contract.md | 11 +++++++ .../issues/02-model-time-to-clickhouse.md | 4 ++- .../issues/03-model-speed-and-day-factor.md | 5 +++- .../issues/04-state-v2-model-resume.md | 13 ++++++--- ...-startup-history-backfill-to-clickhouse.md | 9 ++++-- ...6-generated-history-as-analytics-source.md | 2 ++ ...rator-model-time-startup-history-issues.md | 11 +++++-- 8 files changed, 67 insertions(+), 17 deletions(-) diff --git a/.scratch/generator-model-time-startup-history/PRD.md b/.scratch/generator-model-time-startup-history/PRD.md index 95f38c5..971beab 100644 --- a/.scratch/generator-model-time-startup-history/PRD.md +++ b/.scratch/generator-model-time-startup-history/PRD.md @@ -19,12 +19,17 @@ Status: Draft - Каждый кодовый срез должен заканчиваться проверкой через ClickHouse, а не только локальными тестами генератора. -- Быстрый цикл внутри задачи идёт через `/tdd`: один поведенческий тест, - минимальная реализация, зелёная проверка. +- Кодовые AFK-задачи идут через `/tdd`: один поведенческий тест, минимальная + реализация, зелёная проверка. HITL- и документные задачи идут через + обсуждение и фиксацию решения, без искусственного теста. - Координатор не работает в `/goal` на всю цепочку. Один worker получает один issue, не коммитит и не реализует следующие задачи. - После реализации worker делает саморевью без правок. Координатор классифицирует находки и возвращает только обязательные исправления. +- В задачах 03 и 05 worker заранее даёт промежуточный статус, если статистический + прогон или стендовая проверка идут долго. +- Если исправление после review gate меняет дизайн, формат state, манифест или + схему проверки, результат исправления проходит повторный review gate. - Коммиты делает координатор после своих проверок и `git status --short`. - Ручная проверка дашбордов глазами выполняется только в конце всей цепочки. @@ -33,16 +38,21 @@ Status: Draft - `event_timestamp` — модельное время, а не настенные часы компьютера. - Операционные метки сервиса, история пачек, метрики здоровья и длительность тика остаются настенным временем, если отдельная задача не докажет обратное. -- При одинаковых `GEN_SEED`, `T0`, скорости и настройках поток повторяем. +- Контракт задачи 1 должен разделить, где повторяемость точная, а где + статистическая: промотка прошлого должна быть точной, живой режим зависит от + выбранного драйвера часов. - При ×K модельное время и событийный бюджет идут по модельной длительности тика, а не по реальной длительности сна процесса. +- Часовой пояс модельных часов явно задан в контракте; дневной коэффициент + считается по нему, а не по неявному локальному времени. - После сбоя точка возобновления считается из сохранённой связки модельного и настенного времени, а не простым `datetime.now()`. - Стартовая история — это события плюс слепок состояния плюс манифест, чтобы не смешать данные от разных `GEN_SEED`, `T0` и `T_end`. - На стыке `[T0, T_end]` и живого продолжения не должно быть дублей и дыр. - Повторная проверка на чистом стенде должна быть воспроизводимой: либо команда - явно чистит данные, либо процесс идемпотентен. + явно чистит ClickHouse, Kafka-топики данных и состояние генератора, либо + процесс идемпотентен. ## Задачи @@ -68,9 +78,11 @@ Status: Draft генерации: проверить форму данных, стык истории и живого продолжения, однородность визита до и после восстановления. -Для этих контрольных точек по возможности нужен reviewer другой родословной, а -не тот же worker: research показал, что сквозные свойства и форма распределений -хуже ловятся одной линией проверки. +Для review gate после задачи 3 reviewer другой родословной сильно желателен. +Для review gate после задачи 5 он обязателен: research показал, что форма +распределений и свойства на стыке двух путей хуже ловятся одной линией проверки. +Если такого reviewer-а нет, координатор останавливает цепочку и явно отдаёт +решение человеку. ## Финальная ручная приёмка @@ -78,3 +90,6 @@ Status: Draft генерации: видны история, возвраты, воронка и суточное «дыхание». Если текущих панелей не хватает для такого просмотра, создаётся отдельная задача на панель или runbook, а не расширяется эта цепочка задним числом. + +Миграция уроков по ADR-0006 сознательно отслеживается отдельно. Задача 6 должна +создать follow-up, если учебные материалы требуют нетривиальной переделки. diff --git a/.scratch/generator-model-time-startup-history/issues/01-time-and-startup-history-contract.md b/.scratch/generator-model-time-startup-history/issues/01-time-and-startup-history-contract.md index 642fe3d..dc7674b 100644 --- a/.scratch/generator-model-time-startup-history/issues/01-time-and-startup-history-contract.md +++ b/.scratch/generator-model-time-startup-history/issues/01-time-and-startup-history-contract.md @@ -21,15 +21,26 @@ Status: ready-for-human - [ ] Выбраны имена и формат настроек для `T0`, скорости ×K и режима промотки прошлого. +- [ ] Описан драйвер живых часов: модельное время идёт фиксированным шагом + `tick_seconds * K` или по измеренному настенному интервалу. Для каждого режима + записано, что именно считается повторяемым. +- [ ] Разделены уровни повторяемости: точная повторяемость промотки прошлого и + повторяемость живого режима по правилам выбранного драйвера часов. - [ ] Описано, как после сбоя вычисляется модельная точка возобновления при ×K: из сохранённой модельной метки, сохранённой настенной метки и скорости. +- [ ] Описано, что короткий и долгий простой считаются по модельному времени: + при большом ×K короткий настенный простой может стать долгим модельным. - [ ] Описан манифест стартовой истории: минимум `GEN_SEED`, `T0`, `T_end`, настройки генерации, версия state и контрольные числа. - [ ] Описана граница `T_end`: где заканчивается прошлое и с какой метки начинается живое продолжение, без дублей и дыр. - [ ] Разделены модельные метки событий и настенные операционные метки сервиса. +- [ ] Зафиксирован часовой пояс модельных часов для дневного коэффициента. - [ ] Решено, как координатор будет получать повторяемую ClickHouse-проверку: через очистку данных или идемпотентный прогон. +- [ ] Если выбран чистый прогон, перечислены поверхности сброса: таблицы + ClickHouse, Kafka-топики данных и состояние генератора (`generator_state` или + явный сброс состояния при старте). - [ ] Контракт записан в durable-документ: обновление `PRD.md`, короткий design note в `.scratch/generator-model-time-startup-history/` или уточнение спеки. Сам issue 01 только ссылается на источник истины. diff --git a/.scratch/generator-model-time-startup-history/issues/02-model-time-to-clickhouse.md b/.scratch/generator-model-time-startup-history/issues/02-model-time-to-clickhouse.md index ae031e9..0d684f0 100644 --- a/.scratch/generator-model-time-startup-history/issues/02-model-time-to-clickhouse.md +++ b/.scratch/generator-model-time-startup-history/issues/02-model-time-to-clickhouse.md @@ -19,7 +19,9 @@ Status: ready-for-agent - [ ] При фиксированных `GEN_SEED` и `T0` первый короткий прогон пишет события с модельными `event_timestamp`, начинающимися около `T0`. - [ ] Повторный чистый прогон с теми же настройками даёт те же контрольные - числа в ClickHouse. + числа в ClickHouse по правилу повторяемости из контракта задачи 1. +- [ ] Повторный чистый прогон явно сбрасывает или обходит старое состояние + генератора, чтобы сервис не продолжил прошлый запуск из `generator_state`. - [ ] Расчёт дневного коэффициента в этом срезе больше не зависит от реального часа запуска процесса. - [ ] Локальные тесты проверяют поведение через публичный интерфейс генератора diff --git a/.scratch/generator-model-time-startup-history/issues/03-model-speed-and-day-factor.md b/.scratch/generator-model-time-startup-history/issues/03-model-speed-and-day-factor.md index 6b56401..84a2c6a 100644 --- a/.scratch/generator-model-time-startup-history/issues/03-model-speed-and-day-factor.md +++ b/.scratch/generator-model-time-startup-history/issues/03-model-speed-and-day-factor.md @@ -25,9 +25,12 @@ Status: ready-for-agent - [ ] Событийный бюджет считается по модельной длительности тика, а не по реальному времени сна процесса. - [ ] Дневной коэффициент меняется при переходе модельного времени через - дневные/ночные часы, независимо от реального часа запуска. + дневные/ночные часы в зафиксированном часовом поясе, независимо от реального + часа запуска. - [ ] ClickHouse-проверка показывает повторяемые контрольные числа при тех же `GEN_SEED`, `T0`, скорости и настройках. +- [ ] Worker даёт промежуточный статус, если статистический прогон или стендовая + проверка занимает заметное время. - [ ] В `generator/README.md` или `docs/OPERATIONS.md` кратко описано, что ×K ускоряет именно модельное время стенда. diff --git a/.scratch/generator-model-time-startup-history/issues/04-state-v2-model-resume.md b/.scratch/generator-model-time-startup-history/issues/04-state-v2-model-resume.md index 57f618b..d7eb871 100644 --- a/.scratch/generator-model-time-startup-history/issues/04-state-v2-model-resume.md +++ b/.scratch/generator-model-time-startup-history/issues/04-state-v2-model-resume.md @@ -21,18 +21,23 @@ Status: ready-for-agent - [ ] State сохраняет достаточно данных, чтобы после сбоя вычислить модельную точку возобновления при ×K. -- [ ] Восстановление после короткого сбоя продолжает активные визиты и досылает - созревшие события с исходными модельными метками. -- [ ] Восстановление после долгого сбоя закрывает сильно просроченные активные - визиты без досылки остатка. +- [ ] Восстановление после короткого модельного сбоя продолжает активные визиты + и досылает созревшие события с исходными модельными метками. +- [ ] Восстановление после долгого модельного сбоя закрывает сильно просроченные + активные визиты без досылки остатка. - [ ] Восстановление из стартовой истории использует `T_end` как точку возобновления и не обрывает активные визиты из-за настенного простоя. +- [ ] Визит, переживший восстановление, остаётся однородным: события до и после + восстановления не меняют контекст визита и не создают второй путь генерации + внутри одного `click_id`. - [ ] Повреждённый или несовместимый state не валит сервис: генератор стартует с чистого листа и пишет предупреждение. - [ ] ClickHouse-проверка подтверждает, что на стыке восстановления нет дублей событий и нет разрыва `click_id` внутри продолжающегося визита. - [ ] После реализации выполнено саморевью worker-а и отдельное reviewer-ревью, потому что задача меняет state/serialization и сервисное восстановление. +- [ ] Если исправление после ревью меняет формат state или способ восстановления, + выполнен повторный reviewer-круг. ## Blocked by diff --git a/.scratch/generator-model-time-startup-history/issues/05-startup-history-backfill-to-clickhouse.md b/.scratch/generator-model-time-startup-history/issues/05-startup-history-backfill-to-clickhouse.md index 554c5f8..ec2eb8b 100644 --- a/.scratch/generator-model-time-startup-history/issues/05-startup-history-backfill-to-clickhouse.md +++ b/.scratch/generator-model-time-startup-history/issues/05-startup-history-backfill-to-clickhouse.md @@ -21,8 +21,9 @@ Status: ready-for-agent - [ ] Промотка прошлого создаёт события за `[T0, T_end]`, слепок состояния и манифест с контрольными данными. -- [ ] При одинаковых `GEN_SEED`, `T0`, `T_end` и настройках результат промотки - повторяем в пределах согласованных допусков. +- [ ] При одинаковых `GEN_SEED`, `T0`, `T_end` и настройках артефакт промотки + прошлого повторяем точно; проверки в ClickHouse следуют правилам допуска из + контракта задачи 1. - [ ] История загружается в ClickHouse штатной или явно описанной командой. - [ ] SQL-проверка показывает здоровую пирамиду: пользователей меньше, чем визитов, визитов меньше, чем событий. @@ -35,8 +36,12 @@ Status: ready-for-agent согласованном коридоре. - [ ] Живое продолжение после `T_end` не создаёт дублей на границе и не выглядит как независимый второй мир. +- [ ] Визиты, которые переходят через `T_end`, остаются однородными: контекст + визита не меняется на стыке стартовой истории и живого продолжения. - [ ] Подготовлены данные, команды и SQL-проверки, достаточные для внешнего review gate по распределениям и двум путям генерации из `PRD.md`. +- [ ] Worker даёт промежуточный статус, если промотка, загрузка в ClickHouse или + распределительные проверки занимают заметное время. ## Blocked by diff --git a/.scratch/generator-model-time-startup-history/issues/06-generated-history-as-analytics-source.md b/.scratch/generator-model-time-startup-history/issues/06-generated-history-as-analytics-source.md index fefb941..3cc43f0 100644 --- a/.scratch/generator-model-time-startup-history/issues/06-generated-history-as-analytics-source.md +++ b/.scratch/generator-model-time-startup-history/issues/06-generated-history-as-analytics-source.md @@ -38,6 +38,8 @@ STG→ODS→DDS→DM строится на ней, а Superset работает описывают архивный сид как основной источник аналитики. - [ ] Если уроки или дашборды требуют нетривиальной переделки, создан follow-up issue вместо расширения этой задачи. +- [ ] Если учебные материалы ещё описывают архивный сид как основной источник, + создан отдельный follow-up на миграцию уроков по ADR-0006. - [ ] Описан повторный чистый прогон: какие данные очищаются и какие команды выполняются, чтобы координатор мог надёжно перепроверить результат. diff --git a/.scratch/handoffs/2026-06-14-generator-model-time-startup-history-issues.md b/.scratch/handoffs/2026-06-14-generator-model-time-startup-history-issues.md index a844b09..0526477 100644 --- a/.scratch/handoffs/2026-06-14-generator-model-time-startup-history-issues.md +++ b/.scratch/handoffs/2026-06-14-generator-model-time-startup-history-issues.md @@ -28,8 +28,9 @@ - Координатор классифицирует находки и коммитит сам. - После задачи 3 нужен review gate по сквозному инварианту времени. - После задачи 5 нужен review gate по распределениям и двум путям генерации. -- Для этих review gate по возможности нужен reviewer другой родословной: это - следует из `docs/research/2026-06-11-subagent-coordinator-experiment.md`. +- Для review gate после задачи 5 нужен reviewer другой родословной; без него + координатор останавливает цепочку и отдаёт риск человеку. Это следует из + `docs/research/2026-06-11-subagent-coordinator-experiment.md`. ## Что важно не потерять @@ -37,8 +38,14 @@ в комментарии к issue. - При ×K восстановление после сбоя нельзя считать простым `datetime.now()`: нужна сохранённая связка модельного и настенного времени. +- Короткий или долгий простой считается по модельному времени, а не по настенным + минутам. +- Чистый прогон должен сбрасывать не только ClickHouse, но и Kafka-топики данных + и состояние генератора. - Стартовая история должна быть парным артефактом: события, слепок состояния и манифест. +- Живой и восстановленный пути не должны менять контекст внутри одного визита; + это известная слепая зона из research. - Задача 6 специально сужена до штатного пути стенда и документов запуска. Уроки, новые панели и улучшения дашбордов уходят в follow-up, если окажутся нетривиальными.