- Зачем:
- в docs/labs/ будет много заданий; номер ступени и номер задания в имени
делают папку оглавлением программы и избавляют от поиска по README (#230).
- Что:
- шесть ТЗ переименованы через git mv: 1-1…1-5 для ступени 1,
2-1-superset-chart.md для ступени 2; факультатив superset-dashboard.md
остался без номера.
- обновлены ссылки в docs/labs/README.md, 2-1-superset-chart.md,
docs/architecture/dds/session.md и пути в dags/homework_check.py.
- правило имен для docs/labs/ в AGENTS.md переписано под S-N-slug.
- Проверка:
- make lint; скрипт обхода относительных ссылок в docs/ и AGENTS.md —
битых нет.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- владелец при чтении PR #229 отметил образы в таблице программы
(«счет показывает проблему», «построить сторожей») и оборот
«запускается рукой».
- Что:
- ячейки «Чему учит» ступеней 3 и 5 переписаны как навыки, без образов.
- «запускается рукой» заменено на «запускается руками».
- Проверка:
- grep по «ё», «менти», словам-законам по docs/labs/*.md молчит.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- владелец при чтении забраковал прозу ТЗ ступени 1: образы вместо
утверждений, заголовки-метафоры, договоренности стенда поданы как
законы. Тикет #228.
- Что:
- пять ТЗ (задания 1–5) написаны заново по форме ТЗ ступени 2:
содержание, колонки, формулы, самопроверка и приемка сохранены.
- раздел README лаб «Общие правила ступени 1» переименован в «Как принято
на ступени 1» и переписан как выбор с доводом; точечно поправлены
«Самопроверка» и таблица ступени 1.
- Проверка:
- grep по «ё», «менти», формам «ты» и словам-законам по docs/labs/*.md
молчит (единственное «правило» — в нетронутом разделе «Уборка»).
- скрипт ссылок и якорей из #226 печатает пусто; git diff --check чист.
- сверка имен в обратных кавычках и чекбоксов старых и новых файлов —
без расхождений.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- README и путеводитель обращаются к читателю на «вы», а ТЗ в docs/labs/
были на «ты»; после пересборки индекса смесь стала заметна.
- Что:
- во всех восьми файлах docs/labs/ местоимения, глаголы и повелительное
наклонение переведены во второе лицо множественного числа.
- названия ступеней в таблице README оставлены как в спеке.
- Проверка:
- grep по формам «ты/твой», 'ё' и 'менти' по docs/labs/ молчит;
git diff --check чистый; ревью диффа свежей сессией.
- Зачем:
- программа лаб принята спекой, но индекс docs/labs/ показывал только
пять витрин и дашборд; ступень 2 не имела ТЗ (#226).
- Что:
- новое ТЗ docs/labs/superset-chart.md: один столбиковый график доли
отказов по устройствам поверх dm.session_overview_v, метрика в датасете.
- docs/labs/README.md: семь ступеней основной программы и пять разделов
факультативов; правила пяти витрин помечены как правила ступени 1.
- шапка docs/labs/superset-dashboard.md: факультатив раздела «Superset и BI».
- Проверка:
- grep 'ё' и 'менти' по трем файлам молчат; скрипт ссылок из тикета
печатает пусто; git diff --check чистый.
Closes#226
- Зачем:
- читатель карты видит ключи переноса данных, не переходя к карточкам узлов.
- Что:
- для 17 стрелок добавлено поле «Как соединяет», сверенное с SQL.
- раздел выведен в карточке стрелки и пересобрана карта.
- Проверка:
- uv run docs/handbook/architecture-map/render.py --check.
- make lint.
- make typecheck && make test в generator/.
Зачем: путеводитель рассказывает путь данных через слои словами, а карта
дает его увидеть и потрогать: у одного смысла в каждом слое свое имя и своя
поверхность, а переносят данные три разных механизма — матвью непрерывно,
даг пачкой, представление без копии. Постановка — тикет #222, форма —
резолюция #208 (один самодостаточный HTML, исходники рядом).
Что: docs/handbook/architecture-map.html — готовая карта; исходники в
docs/handbook/architecture-map/ (map.yaml — слои, узлы, стрелки, карточки;
template.html — разметка, стили, скрипт; render.py — сборка и --check;
README.md). Щелчок по узлу открывает карточку и подсвечивает путь, щелчок по
стрелке — кто и каким SQL переносит данные; переключатель потока приглушает
чужую часть карты. Ссылки карточек ведут в справочники и DDL на Gitea.
Путеводитель и глава о хранилище ведут на карту; make lint проверяет ruff
для сборщика и свежесть рендера; testing.md и AGENTS.md обновлены.
Проверка: uv run docs/handbook/architecture-map/render.py --check и
make lint зеленые; внешних запросов в HTML нет; ссылки и якоря карточек
сверены с Gitea; карта прощелкана в headless Chromium на ширинах
1280–1920: подсветка пути, фильтр, Esc, карточки узлов и стрелок.
Ревью: постановка — Opus; реализация — Codex (Sol), два слепых ревью Opus
(уместность и код), вычитка прозы Sol.
Зачем: владелец прочел главы и нашел неестественные фразы: дашборды
«спрашивают», даги «двигают ось», заказ «ездит в слепках», Superset —
«витрины глазами», объекты «приезжают из файлов». Читателю такие
образы надо расшифровывать, а урок в них не прячется.
Что: в четырех главах олицетворения заменены прямыми формулировками,
«позиция мира» и «шаговый даг» раскрыты через world_position и имена
дагов, паспорт мира описан по составу и назначению, окно слепка
заказов объяснено словами, режимы генератора и правило импорта
Superset сказаны прямо. Тире и стрелки оставлены: это домашний стиль.
Проверка: проверки тикета #220 на битые ссылки и запретные слова
пусты, строки прозы не длиннее 80 знаков, git diff --check чист.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Зачем: после главы о хранилище путеводитель обещал еще четыре главы, а
вместо них стояли заглушки «Пока главы нет…». Без них читатель не видит,
кто двигает мир и раскладывает данные по слоям, куда смотреть в Grafana,
как витрина становится графиком и откуда берутся данные.
Что: docs/handbook/airflow-dags.md, monitoring.md, superset.md,
generator.md — по скелетам тикета #220, форма — как у главы о хранилище.
Сквозная линия трех глав: ход мира на день D везет слепок заказов дня D−1,
поэтому выручка всегда на день позади кликстрима. README путеводителя
ведет заголовками в файлы глав, заглушки убраны; «Куда дальше» главы о
хранилище ведет прямо в главу об Airflow.
Проверка: три SELECT из глав прогнаны на живом стенде от analyst — трафик
получил сыгранный день, выручка только предыдущий, счетчики первых восьми
дней совпали с паспортом мира. Скрипт проверки ссылок и запретных слов из
тикета пуст. Постановка отревьюена Opus (18 находок внесены); главы прошли
саморевью Sol и два слепых ревью Opus — факты и проза (ai-text-lint плюс
оптика литературного русского): 25 находок внесены, 1 отклонена.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- первая глава путеводителя: без нее читатель попадает из README сразу
в справочники, минуя объяснение пути данных (тикет #218, карта #206).
- Что:
- добавлена docs/handbook/storage-layers.md: путь STG → ODS → DDS → DM,
правило чтения через _v, зона dic, таблица ключей соединения слоев
и два SELECT для самостоятельной пробы.
- в docs/handbook/README.md раздел «Будущие главы» стал «Главы»,
аннотация первой главы ведет в ее файл.
- Проверка:
- обе команды из раздела «Проверка» тикета #218 дают пустой вывод;
оба SELECT прогнаны на живом стенде от пользователя analyst.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Зачем: README был складом сведений, осевших там, где писались. По
раскладке резолюции #211 он становится лицом репозитория: промо-блок,
«куда я попал», типовые действия, ссылки. Слово «менти» уходит из README
и путеводителя, хвосты #212 и #214 закрываются.
Что: промо-цитата со ссылкой на план обучения и ментора; шапка с
нейтральной адресацией и одной фразой о составе и пути данных; «Быстрый
старт» сжат до двух команд по решению владельца — проверки остаются
роботам, в README одна ссылка на карту проверок; разделы «Адреса и
пароли», «Сдвинуть мир вперед», «Вернуть мир к началу», «Выключить или
сбросить целиком», «Подключиться из DBeaver»; «Документация» называет все
семь справочников вложенным списком. Умерли «Статус», «Что здесь будет»,
«Чем отличается от предшественника» и три заголовка-якоря. В world.md
снята устаревшая фраза о «даге этапа 5», stand.md и ADR 0007 ведут на
новый раздел «Адреса и пароли», в путеводителе снято слово «менти».
Проверка: скрипт ссылок пуст, grep «менти» по README и путеводителю пуст,
make config-test зеленый. Саморевью Sol 1/1; слепое ревью Opus — 0
блокеров, 2 minor, 3 nit, все закрыты; вычитка прозы ai-text-lint и
оптикой литературного русского — 15 находок, 9 внесены, 6 отклонены как
слова владельца и термины.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
- Зачем:
- справочники читает человек со стороны, а «пульт мира», «опись мира»,
«работник» и «сырьё» звучали шуткой или калькой времён разработки
(тикет #214, выбор владельца).
- Что:
- CONTEXT.md: статьи «Паспорт мира», «Даги модельного времени»,
«Шаговый даг», «Сырые данные», старые слова в строках «Избегать»;
пометки в ADR 0005, 0008, 0009 без переписывания решений.
- замены по README, справочникам, путеводителю, лабам, спекам,
комментариям дагов и SQL, тегу дага и панели Grafana; имена в коде
не тронуты.
- world.md и stand.md: 35 находок вычитки внесены, регистр выровнен.
- Проверка:
- make config-test; make lint в корне и в generator/; make test в
generator/ (437 passed); скрипт ссылок из #212 пуст; grep старых
слов вне ADR, research и CONTEXT.md пуст.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW
Зачем: ревью владельца по PR #213. Сверка конфигурации в stand.md
приехала из README одним абзацем на двадцать строк, а Superset был
приклеен к Airflow без пустой строки. Три места в world.md читались
калькой с английского.
Что: ледгер «Что проверено» разбит на записи по темам — ClickHouse,
Kafka, метрики и Grafana, Airflow, Superset. В world.md заголовок
«Как позвать генератор» стал «Как запустить генератор» (якоря в README
и generator/README.md обновлены), переписаны абзацы про значения по
умолчанию и про сокет Docker. Смысл не менялся. Словарь проекта
(«пульт мира», «опись мира», «работник», «сырье») не трогался: это
термины CONTEXT.md и ADR, их пересмотр — отдельная развилка.
Проверка: скрипт ссылок из тикета — пустой вывод; make config-test —
ЗЕЛЁНО; старый якорь «как-позвать-генератор» в репозитории не встречается.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW
Зачем: README служил складом для двух зон без своих справочников —
«службы и доступ» и «мир и его пульт». Раскладка принята резолюцией
#211: README остается лицом, устройство живет в docs/architecture/.
Что: новые docs/architecture/stand.md («Стенд: службы, доступ,
настройка», доводы — ADR 0001 и 0007) и docs/architecture/world.md
(«Мир и его пульт», доводы — ADR 0009 и 0013). Доводы смоука и
описания целей make слиты в testing.md без повторов: фраза о
check_containers_survived и абзац про config-test умерли как дубли.
На месте каждого переехавшего раздела README — абзац со ссылкой,
адреса и пароли интерфейсов остались. Путеводитель и README
генератора ссылаются на world.md вместо якорей README. Переехавший
текст не правился, только относительные ссылки.
Проверка: скрипт ссылок из тикета — пустой вывод; make config-test —
ЗЕЛЁНО; подиффовая сверка переехавших диапазонов с README@2588515 —
без расхождений (слепое ревью); в новой прозе нет «ё».
Closes#212
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014QBCtU38qSHg5DvgtnKXcW
- Зачем:
- менти негде было понять с первого экрана, что перед ним и куда идти;
тикет #209 карты #206 открывает учебную документацию стенда.
- Что:
- создан docs/handbook/README.md: тропа чтения и пять аннотированных
будущих глав с временными ссылками на справочники.
- шапка README.md переписана для менти: четыре действия и ссылки на
путеводитель и уроки; в разделе «Документация» добавлены handbook и labs.
- в AGENTS.md добавлено правило имен для docs/handbook/.
- Проверка:
- команда проверки ссылок из тикета #209 — пустой вывод;
- git diff: операторские разделы README не тронуты.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- раздел 9 отсылал к открытому тикету #203; решение принято, указатель
должен вести на итог, а не на вопрос.
- Что:
- фраза «докуда ведет карта #182» заменена итогом: карта закрыта приемкой
спеки, исполнение ведет карта #206.
- Проверка:
- вычитка раздела 9 файла docs/specs/2026-09-01-labs-program.md.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- термины спеки перейдут в задания, а «хребет», «ветки» и «точка
прицепа» с калькированными заголовками сюжетов смущали бы студентов.
- Что:
- хребет → основная программа, шаги → ступени, ветки → факультативы,
«точка прицепа» заменена формулой «открывается после ступени N»;
- заголовки разделов и сюжетов переписаны из позиции студента
(«Почему выручка не сходится», «Куда попадают битые строки»);
- переносы выровнены по ~80 колонок по всему файлу.
- Проверка:
- текст без учета пробелов не изменился на шаге переносов (SHA-256);
решения, состав и порядок программы не менялись.
- Зачем:
- тикет #202 карты #182: собрать из инвентаризации #201 программу лаб
целиком — состав, порядок, формы и судьбу идей-кандидатов.
- Что:
- создан docs/specs/2026-09-01-labs-program.md: хребет из семи
обязательных шагов и пять тематических разделов необязательных лаб;
- узаконены границы вычитания по потокам и поименные резолюции идей
#143, #145, #148, #149, #186, #187, #188;
- записаны отклоненные варианты оси прогрессии и границы спеки (#203).
- Проверка:
- вычитка владельцем (спека принята), слепое ревью фактов против
инвентаризации и доков — все находки закрыты.
- Зачем:
- спеке программы лаб (#202) нужен полный веер сюжетов вместо семи
случайно накопленных идей; резолюция тикета #201 карты #182.
- Что:
- заметка docs/research/2026-08-31-labs-inventory.md: 32 сюжета по
слоям STG, ODS, DDS, DM, BI и поперек слоев, три формы заданий,
разбор гипотезы «вычитание + DQ» с таблицей по потокам.
- Проверка:
- фактура (пути, имена таблиц, номера тикетов) сверена с репозиторием
при вычитке; кода изменение не касается.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Зачем: раздел 10 выносил все лабы v2 в отдельную работу учебного пути,
делая исключение только для домашек DM, — необязательная лаба Superset
из #197 формально в него не попадала.
Что: исключение расширено фразой про лабу «свой дашборд в Superset» с
меркой владельца: домашки DM и эта лаба продуманы до готовых ТЗ,
остальные лабы пока на уровне идей.
Проверка: вычитка; решение владельца репозитория из обсуждения #197.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Зачем: владеть хотя бы одним BI-инструментом на базовом уровне — полезный
навык дата-инженера, но стенд в первую очередь про ClickHouse, поэтому
лаба необязательная. Обещание «отдельная домашка после этапа 8» в доке DM
висело без адреса.
Что: ТЗ docs/labs/superset-dashboard.md — пять датасетов поверх публичных
представлений заданий 1-5, свой дашборд отдельно от стендового, проверка
глазами без homework_check; шестая строка и разведение «пяти заданий по
витринам» в docs/labs/README.md; абзац о сроке жизни объектов менти в
docs/architecture/superset.md; ссылка на лабу из доки DM; правило слага в
AGENTS.md расширено до «предмет задания».
Проверка: кода и DDL нет; слепое ревью текста (9 находок закрыто, 2
дополнительные с перепроверки) и финальная вычитка.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- этап 8 (#196): три сюжета спеки — выручка, сверка, посетители /
известные — должны приезжать в Superset при каждой инициализации
стенда, без ручной сборки в интерфейсе.
- Что:
- дерево infra/superset/import/ дополнено датасетами трех витрин dm,
тремя графиками и дашбордом «Бизнес-сюжеты»; uuid розданы рукой,
русские строки читаемы, metadata.yaml сокращен до версии формата.
- написан справочник docs/architecture/superset.md: устройство зоны,
дерево импорта, маршрут свежего экспорта, ловушки импорта.
- в docs/architecture/dm.md добавлена ссылка на справочник зоны.
- Проверка:
- docker compose run --rm superset-init — импорт начисто, затем три
графика отдают данные через API (54/48/10 строк).
- прогон рецепта «чистая установка» из справочника: сброс базы superset
в postgres-metadata, импорт, активы на месте.
- make lint и make check-services зеленые (7/7).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- семь мест обещали калибровку черновых долей «при пересборке
эталонного мира (этап 7)», а пересборки не будет (#192); числа
сверены замером и зафиксированы (#194, хвост этапа 7 — #9).
- Что:
- замер на каноническом мире (28 дней, без транспорта): все доли в
пределах ориентиров; пометки «черновое» сняты, наблюдаемые доли
вписаны в комментарии world.py, fate.md и запись «Что проверено»;
- потеря purchase: наблюдаемых 1,78% при броске 3% — вычеты штатные
(пары склейки, приоритет отмены), принято решением владельца;
ориентир класса B в мастер-спеке различает бросок и наблюдаемую долю;
- веса мира и опись не тронуты: правки world.py — только комментарии.
- Проверка:
- cd generator && make lint && make typecheck && make test (437 passed);
- git diff по data/world-inventory.json пуст; grep «черновое|калибровка»
по generator/src и docs/architecture/orders пуст.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- у дней 8-13 описи не нашлось читателя: обещание эталона в 14 дней
снято решением владельца 2026-08-30 (#192, этап 7 — #9).
- Что:
- резолюция перенесена в обе спеки, докстринг описи и словарь CONTEXT.md;
- добавлен тест: проигранный через CLI день совпадает с хешем описи;
- сняты замеры: пересборка описи 20,5 с, снимок 460,7 МБ, make test
176,5 с — записаны в карту проверок и таблицу бюджетов.
- Проверка:
- cd generator && make lint && make typecheck && make test (437 passed);
- git diff по data/world-inventory.json пуст.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- менти должен увидеть, как запоздавшая выгрузка меняет открытое окно, не подделывая аудит источника.
- Что:
- заказам назначена задержка D, D+1 или D+2 последним броском подпотока ORDERS.
- назначенный планом заказ приезжает сразу, а Woven передаёт эту гарантию именованным полем.
- обновлены документы, проверки границ механики и эталонные хеши слепков.
- Проверка:
- make lint, make typecheck и make test в generator: 436 тестов прошли.
- make config-test: конфигурация прошла проверку.
- world_live_day и следующий etl_pipeline перевели заказ 20260608-0001 из awaiting_order в match.
- Зачем:
- трекер стенда был полным, и правило «деньги — по бэкенду» держалось
на слове; классы B и D делают недосчет и пересчет трекера
наблюдаемыми (этап 6, #184).
- Что:
- подпоток BEACONS: точечная потеря purchase (~3%) и сюжетный дубль
(~2%) швом после _purchases, с гарантией моста идентичностей и
условием допуска дубля по паузе до следующего визита;
- опись считает пять классов по приоритету спеки; фильтр
classes_vs_inventory расширен, нулевой класс читается нулем;
- fate.md, seeds.md, dm.md и orders/README.md приведены к имени
BEACONS и строгому правилу допуска.
- Проверка:
- make lint, make typecheck, make test (433 passed) и make inventory
из generator/ — хеши слепков не изменились;
- на стенде: make smoke, make check-clickhouse, make check-services
зеленые; в dq_summary classes_vs_inventory и sessions_vs_reference
pass, витрина сверки показывает lost_event и duplicate_event.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
- Зачем:
- спека разрослась до 1058 строк, а журнал решений в разделе 9 читался
только целиком; агентам и людям нужен дешевый адресный заход к
основаниям решений генератора.
- Что:
- заведены ADR 0015 (пояс счетчика), 0016 (паспорт куки) и 0017 (номер
заказа); четыре адресные ссылки на «раздел 9» перешиты на них.
- раздел 9 пересобран в 11 тематических подразделов с датами и тикетами
у каждого решения и закрыт пометкой о заморозке; устаревшие
промежуточные замеры свернуты до указателей на актуальные.
- строка статуса в шапке отмечает закрытие спеки как документа этапа 2.
- Проверка:
- wc -l docs/specs/2026-08-01-generator.md (951, было 1058);
rg -n 'раздел[а-яё]* 9|разделы 8 и 9' docs -g '*.md' — 18 попаданий,
все классифицированы; разделы 1-8 нетронуты (сверка хешем).
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
ddadminandClaude Fable 5.1
ddmitry