From 3529cd84256eee2ecf97472b61cb416e62a44366 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Thu, 13 Aug 2026 12:43:09 +0300 Subject: [PATCH] =?UTF-8?q?=D1=83=D0=B4=D0=B0=D0=BB=D0=B5=D0=BD=D1=8B=20TO?= =?UTF-8?q?DO.md,=20REMAINING.md=20=D0=B8=20HISTORY.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - указатель в README сведён к журналу решений; из decisions/README.md убрана строка про остатки, из addresses.py — HISTORY.md в перечне журналов; - упоминания этих файлов внутри журнала оставлены как есть: он описывает прошлые состояния и задним числом не переписывается. --- HISTORY.md | 85 -------------------------- README.md | 4 +- REMAINING.md | 140 ------------------------------------------- TODO.md | 135 ----------------------------------------- decisions/README.md | 2 - scripts/addresses.py | 1 - 6 files changed, 1 insertion(+), 366 deletions(-) delete mode 100644 HISTORY.md delete mode 100644 REMAINING.md delete mode 100644 TODO.md diff --git a/HISTORY.md b/HISTORY.md deleted file mode 100644 index 4c42a7d..0000000 --- a/HISTORY.md +++ /dev/null @@ -1,85 +0,0 @@ -# Как процесс дошёл до текущей формы - -Сжатие черновика `AGENTIC-TASKS.md` (497 строк), лежавшего незакоммиченным в -корне healthlog. Правила процесса из него переехали в плагины и здесь **не -повторяются** — второй дом для тех же правил ровно то, против чего документ и -был написан. Остаётся то, чего в плагинах нет и быть не должно: **что отвергнуто -и почему, и числа первого замера**. - -Решения текущего круга разбора — [журнал решений](decisions/README.md). - -## Что отвергнуто и почему - -### Scrum целиком - -Терминология близка — спринт, груминг, определение готовности, ретроспектива, — -и она удобна: не нужно изобретать слова. Но добрая половина Scrum существует ради -синхронизации людей, которых здесь нет: исполнителей двое, человек и агент. - -**Не взято:** тайм-бокс (спринт ограничен объёмом, а не временем), velocity и -оценки в очках, ежедневный стендап (стендап — это и есть диалог), планирование -отдельно от груминга (владелец беклога один), роль скрам-мастера. - -**Взято:** цель спринта, заморозка набора, определение готовности, груминг — -каждое потому, что снимает решение, которое иначе принимается заново каждый раз. -**Ретроспектива взята содержанием, но не отдельным ритуалом**: она шаг той же -сессии. Отдельная встреча ради трёх вопросов — плата ритуалом без выгоды. - -### Приоритеты у задач - -Заменены целью. Ни секциями, ни списком: «что делать дальше» отвечает набор -спринта, а между спринтами порядок не нужен никому — брать задачи вне спринта -запрещает заморозка. Отсюда нет ни «повысить», ни «встать раньше»: вместо -повышения — смена цели или включение в набор. - -### Секция «блокеры» в беклоге - -Блокер — **состояние** (спринт не может продолжаться ни одной задачей), а не -полка: он живёт ровно до ответа человека, и записи в такой секции не успевают -жить. Основание измерено: **два «блокера» из двух ничего не блокировали** — в -обоих файлах записано «что заблокировано: ничего». Отсюда разделение вопроса и -блокера. - -### Запись о сделанной задаче - -У сделанной задачи записи не остаётся: файл и строка удаляются. Ей хватает -коммита и документации; вторая запись была бы вторым домом для того же факта. -Вопрос «что было в спринте N» отвечается даром — `SPRINT.md` лежит под git. - -## Числа первого замера - -Одна сессия, шесть закрытых задач. **Выборка нетипичная, статус — первый -замер.** Приведены не как константы, а чтобы следующий замер было с чем -сравнить. - -- **Беклог вырос с 29 до 38**: заведено 15, закрыто 6 (две родились и умерли - внутри сессии). Прирост **2,5 задачи на одну закрытую** — ревью и - эксплуатационные проходы производят работу быстрее, чем мы её потребляем. -- **Одна из шести задач была внеплановой** — дозакрытие находок, вставленное в - ход работы, потому что дефект затирал маршрут тренировки необратимо, а - пересборка журнала повторяла то же поражение. Отсюда класс «необратимый - ущерб» как единственное, что врывается в замороженный спринт: правило не - придумано, оно уже применялось. -- **15 часов на шесть задач**: пять заняли от 1 ч 16 мин до 2 ч 14 мин (медиана - ≈ 1 ч 55 мин), шестая — 5 ч 42 мин в два захода. Мерилось **до** сужения - конвейера ревью; замер устарел и подлежит повторению. -- **Шесть задач за сессию** — предел одного контекста, а не спринта. Спринт - сессией не ограничен, перенос числа условен. - -Умолчание «5–8 задач в спринте» выведено отсюда и остаётся **ориентиром, а не -законом**. Пересматривается на разборе прошедшего спринта — шаг 2 сессии, и ничей -другой. - -## Что из черновика было не решено и решено позже - -| Вопрос черновика | Где решён | -| --- | --- | -| название процесса | решение Z: имени нет, процесс это `av-dev` | -| «Ближайшая цель» прозой в `docs/plan.md` как второй дом цели спринта | решение E: `plan.md` растворяется в `PLAN.md` целей | - -## Судьба самого черновика - -Документ описывал процесс, а процесс живёт в плагинах этого репозитория, не в -healthlog. Содержимое разошлось: правила — в `av-dev-pm:tasks` и -`av-dev-pm:session`, обоснования и числа — сюда. Оригинал в git не коммитился и -удаляется при переезде healthlog на канон. diff --git a/README.md b/README.md index 7694f22..6f2e289 100644 --- a/README.md +++ b/README.md @@ -3,9 +3,7 @@ Личный маркетплейс плагинов для разработки. Процесс имени не имеет — он и есть `av-dev`. -Что решено и почему — [журнал решений](decisions/README.md). Что осталось сделать — -[TODO.md](TODO.md) и [REMAINING.md](REMAINING.md). Как процесс дошёл до текущей -формы — [HISTORY.md](HISTORY.md). +Что решено и почему — [журнал решений](decisions/README.md). ## Плагины diff --git a/REMAINING.md b/REMAINING.md deleted file mode 100644 index 6f8e98d..0000000 --- a/REMAINING.md +++ /dev/null @@ -1,140 +0,0 @@ -# Остатки, открытые вопросы и принятые пределы - -Состояние пересобирается по ходу работы; счётчика тем и коммитов здесь нет -намеренно — он протухает молча, а двигать его некому. Что и когда решено — -[журнал решений](decisions/README.md), записи датированы. - -План работ — [TODO.md](TODO.md). Решения с причинами — [decisions/](decisions/README.md). -Здесь то, что **не** является работой из плана: незакрытые риски, честно принятые -пределы и вопросы, у которых пока нет ответа. - -## Главный незакрытый риск - -**Калибровка не сделана, а уставы проходов с тех пор переписывались не раз.** - -Правки шли волнами: вынос в плагин (предмет проверки заменён ссылкой на раздел -брифа), переход на пути документов канона, две правки по находкам ревью, граф -порядка, ступень `wide`, пересмотр триггеров ступени. -`references/calibration.md` требует при каждой такой правке замерить, помогла ли -она, — **ни одного замера не было**. Числа правок здесь нет намеренно: счётчик -пришлось бы двигать вручную, и он уже однажды отстал. - -**Неизмеренные изменения копятся** в том самом месте, где присваивается -severity. Пробы готовы и синтетических не нужно — четыре реальные находки -прошедшей сессии healthlog: - -- скелет из `null` затирает маршрут тренировки молча и необратимо; -- откат бинаря поверх новой схемы стартует без единого слова; -- канонизация внутри транзакции — 768 МиБ пика, 5.019 с удержания блокировки; -- `-1 >= -1` читается как «журнал разобран целиком». - -Ожидаемый исход известен и его стоит проверить первым: метод переносится, а -**severity деградирует**. Третья находка без слота под представление данных и -настройки хранилища превращалась из `critical` с прогнанным оракулом в условное -наблюдение. Ровно ради этого случая канон развёл числа (`docs/research/`) и -настройки (`docs/database.md`) по разным домам и **обязал проход их сшивать** — -но работает ли обязанность, не проверено. Оркестратор реагирует на severity, -поэтому цена — не «не найдём», а **«найдём и не починим»**. - -Сама работа — [TODO.md](TODO.md), раздел «Калибровка»; здесь только цена: замер -стоит перед переездом jellybit и блокирует его (решение 39), а ожидаемый исход -уже назван выше. - -**«Главный» здесь про цену, а не про очередь.** Первой идёт адаптация healthlog -(TODO, раздел «Живые проекты»): без неё нет проекта под каноном, на котором -работают остальные скиллы. Калибровка блокирует один шаг — переезд jellybit, — а -не всё подряд. - -## Что ещё не сделано - -Список работ — в [TODO.md](TODO.md). Здесь только то, что стоит держать в голове -отдельно: - -- **Ни один скилл не прогонялся на живом проекте.** `docs.py` прогнан на - healthlog и jellybit в режиме `check` и находит осмысленный дрейф; `init`, - `canon adopt`, `canon upgrade`, скиллы `docs`, `openspec` и `resolve` не - исполнялись ни разу. `openspec.py`, раскол плагинов и оба чекпоинта `resolve` - проверены только на фикстурах и на установке каждого плагина в одиночку. -- **Проектные копии в healthlog и jellybit.** Два `.claude/skills/` и одиннадцать - `.claude/agents/` старого поколения — их надо снести при установке. - **Совпадение имён при этом больше не грозит:** скиллы jellybit названы - `task-pipeline`, `review-pipeline`, `task-batch`, а плагин теперь даёт - `resolve`, `review`, `openspec` — ни одно имя не пересекается. Риск снят - переименованием, а не устранён по существу: заведись у проекта свой `review`, - Claude Code держал бы обе пары, и короткое имя увело бы в копию молча. - -## Открытые вопросы - -**`doc-consistency` не различает «про нас» и «про то, что мы производим».** -Первый прогон на самом dev-skills предъявил репозиторию правило из -`av-dev-git/skills/commit/SKILL.md` — а это продукт, уезжающий в чужие проекты, -а не правило, которому подчиняется маркетплейс. На проекте под каноном такой -путаницы нет (там документы описывают сам проект), поэтому в устав это пока не -дописано: сперва посмотреть, встретится ли класс ещё раз. - -**Как проверять, что канон не разошёлся с проектами после `upgrade`.** `canon -check` сверяет версию, но не то, что миграционные записи journal'а применены -верно. Проект может нести `"canon": 2` и не иметь того, что версия 2 требовала. -Ответ выбран: шагом 6 `upgrade` зовутся оба судьи документов — проверка не -механическая, но других у существа записей нет. Останется открытым, пока не -прогнано на живом проекте: неизвестно, ловят ли они недоделанную миграцию или -только её последствия. - -**Не выродились ли «границы покрытия» в шаблон.** Строка «что смотрели и чего не -смотрели» обязательна в докладе `check`, `adopt`, интейка, штурма и всех пяти -агентов канона и задач (`doc-consistency`, `doc-code-drift`, `doc-wording`, -`task-form`, `task-wording`) — девять мест, и проверить её исполнение некому: -приёмщик и исполнитель одно лицо (`task-groom/SKILL.md`, «Стимулы»). Выродившаяся -строка **хуже отсутствия**: доклад выглядит проверенным. - -Приём не правится: это гипотеза об износе, а не находка, и менять работающее по -догадке дороже. **Наблюдение к первой обкатке на живом проекте:** если в трёх -докладах подряд границы покрытия совпали дословно или называют не то, чего -проверка действительно не касалась, — приём выродился, и вот тогда решать. - -**Форма ADR при пересмотре решения.** Парный статус («старая запись получает -`заменено на`») судит агент `doc-consistency` — правило 6 его устава. Охват был -открытым вопросом, пока агент звался пачкой, отобранной работой; переезд вызова -в `av-dev:doc-healthcheck` с пачкой «весь канон» его снял. Остаётся зазор до -ближайшего прогона `healthcheck` и отсутствие механической проверки — то есть -пересмотр, сделанный сегодня, судится тогда, когда позовут сверку, а не в момент -правки. - -## Известные пределы — приняты, чинить не планируется - -**Транзакций на несколько файлов нет.** POSIX её не даёт без журнала. Окно сжато -до цепочки `rename` без ввода-вывода, а всё, что в окне может разъехаться, -сделано производным и восстанавливается `check --fix` без потерь. - -**Оракул в критериях приёмки проверяется эвристикой.** Число пунктов проверяется -жёстко, наличие оракула — по слову, и это **только замечание**. В тексте прямо -сказано, что проверено меньше, чем требуется. - -**Recall прохода по конвенциям равен качеству конвенций проекта.** Своего списка -у него нет: критерий берётся из `docs/conventions/`. На проекте с тонкими -конвенциями проход почти пуст, и charter это признаёт вслух. - -**Доменного словаря в каноне нет.** Проходы получают факты, но не термины; -словарь строится каждый раз заново из спек и архитектуры. Цена не измерена. - -**Смысловые дубли ловит только агент.** `docs.py` видит раскладку, но не то, что -раздел `docs/architecture.md` описывает поведение, уже записанное capability -`recognition`. -Граница объявляется вслух в каждом отчёте — это единственная защита от -«соблюдено» на проекте с тремя лишними файлами. - -**Приёмщик и исполнитель совпали, и опор стало меньше.** Граница «пайплайн не -закрывает задачу» снята сознательно (решение P); защиты держатся текстом, а не -механикой. Реальных опор было три, осталось две: сохранённый отчёт триажа и -`reopen` (индексы под git показывают закрытие, потому что оно коммитится -отдельным коммитом учёта). Третья — приёмка шагом сессии — ушла вместе со -спринтами: у неё больше **нет момента**, и происходит она только тогда, когда -что-то бросилось в глаза на груминге. Это записано в самих скиллах, а не -спрятано. - -**Копия правила в шаблонах проекта.** `adr/README.md` и `review.md` уезжают в -репозиторий и обязаны там что-то говорить, поэтому правило канона в них -копируется намеренно. Расхождение копии с домом ловит `scripts/copies.py` — -но только у **помеченной** копии, и только внутри маркетплейса. Остаётся на -человеке двое: пометить копию и завести запись в журнал версий, когда правка -уже уехала в проект. diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 1dcf720..0000000 --- a/TODO.md +++ /dev/null @@ -1,135 +0,0 @@ -# Что осталось сделать - -**Здесь только работы и их порядок.** Чего здесь нет намеренно: - -- **риски, открытые вопросы и принятые пределы** — [REMAINING.md](REMAINING.md); -- **почему решено так** — [журнал решений](decisions/README.md), записи - датированы; -- **шаги повышения проекта с версии канона на версию** — журнал версий - ([changelog.md](av-dev/skills/doc-canon/references/changelog.md)). Пересказ их - сюда был бы вторым домом, и прежний план на этом уже разъезжался: он повторял - записи версий 3, 4 и 5 построчно, и половина повторов протухла молча. - -Сделанное отсюда **удаляется, а не помечается галочкой**. След остаётся в -коммитах и в журнале решений; список из двух сотен `[x]` перестают читать целиком, -и живые пункты в нём теряются — прежний план умер именно так. - -## Где мы сейчас - -Плагина два: `av-dev` — весь процесс девятью скиллами (`doc-*` — документы, -`task-*` — учёт работ, `code-*` — работа по задачам), и `av-dev-git` — -сообщения коммитов. Прежние три (`av-dev-docs`, `av-dev-tasks`, `av-dev-code`) -слились 13 августа 2026, -[тема 64](decisions/64-three-plugins-merged.md) журнала решений. Общее, что нужно нескольким скиллам, -живёт домом в `av-dev/shared/`. - -Раскладка — **версия 1**, одна на документы и на каталог задач, в -`.av-dev.toml` в корне проекта. Живые проекты стоят на каноне 2–3 и на плагине -`av-dev-pm`, которого больше нет: им идти сперва по закрытому журналу канона до -14, потом по записи 1 действующего. - -Бумажная часть закрыта аудитом четырёх плагинов и четырьмя пропусками правок -([тема 59](decisions/59-four-subagent-audit.md) журнала решений). Всё, что ниже, проверяется **только на живом коде**. - -## 1. Живые проекты — вернуть в рабочее состояние - -Блокирует всё остальное: под текущим каноном не стоит ни один проект, и ни один -скилл, кроме `docs.py check`, не исполнялся на живом коде ни разу -(см. REMAINING, «Что ещё не сделано»). - -### healthlog — первым - -- [ ] переустановить плагины: снять `av-dev-pm` и `av-dev-pipeline`, поставить - `av-dev` и `av-dev-git`. Прежние имена мертвы, и `plugin update` их не - переименует — только снять и поставить. `marketplace update`, затем `plugin update` — одного шага мало - (README, «Обновление») -- [ ] удалить проектные копии: `.claude/skills/healthlog-{task,review}-pipeline` - и девять `.claude/agents/healthlog-review-*.md`. Они прошлого поколения и - после переезда указывают на документы, которых уже не будет -- [ ] `av-dev:doc-canon` в режиме `adopt` — он приведёт проект к раскладке 1 - сразу, картой и с подтверждением. Файл-в-файл здесь не расписан: раскладку - знает скилл, и второй перечень разошёлся бы с ним -- [ ] каталог задач — в `tasks/` корня (канон 11), не в `docs/tasks/`, без - `SPRINT.md` (канон 12); версия и настройки — в `.av-dev.toml` корня, там - же секция `[tasks]`. Скилл задач зовётся из `adopt` сам -- [ ] гейт проекта: три шага вместо одного — `docs.py check`, `tasks.py check - --dir tasks`, `openspec.py check`. **Второй и третий раньше не были - нужны:** согласованность задач тянул за собой `docs.py`, форму `config.yaml` - он же. Теперь оба молчат, и без своих шагов дрейф перестанет ловиться -- [ ] разобрать урожай `doc-consistency` и `doc-code-drift` порциями — правило - единственного дома на живом проекте не проверял никто - -### jellybit — после калибровки - -Порядок не произволен: замер (раздел 3) блокирует переезд jellybit, и только его. - -- [ ] то же, что у healthlog: плагины, проектные копии, `adopt`, каталог задач, - гейт -- [ ] проектные копии здесь опаснее: скиллы названы `task-pipeline`, - `review-pipeline` — **ровно как в плагине**, и короткое имя - может увести в устаревшую копию молча (REMAINING) - -## 2. Учёт работ без спринтов — что осталось - -Сделано: спринт снят со скрипта и текстов, приоритет стал порядком строк в -беклоге, гейт готовности переехал в `tasks.py ready`, `session` стал скиллом -`groom`, запись 12 в журнал версий канона написана. - -- [ ] прогнать груминг на живом беклоге — на фикстуре проверялись команды, а не - сам разбор. Наблюдение к первому прогону: **не выродился ли шаг 4 в - «оставить как есть»** — признак тот, что доклад не называет ни одного - движения с доводом - -## 3. Калибровка — блокирует переезд jellybit - -- [ ] замер на четырёх находках healthlog: скелет из `null`, откат бинаря, - канонизация в транзакции, `-1 >= -1`. Цена и ожидаемый исход — REMAINING, - «Главный незакрытый риск» - -## 4. Конвейер: что осталось после `resolve` - -Сам скилл написан (`av-dev:code-resolve`, три сценария — разведка, решение и -обслуживание; чекпоинт есть у первых двух, у обслуживания планового стопа нет), -`task-batch` удалён. Осталось то, что на бумаге не проверяется: - -- [ ] прогнать сценарий разведки на живой задаче: он написан целиком на бумаге и - не исполнялся ни разу. Самое неизвестное — выбор сценария на входе (не - уедет ли всё в решение, потому что «способ вроде понятен») и объём того, - что разведка пишет в документы -- [ ] прогнать сценарий обслуживания на живой задаче `chore`. Неизвестных три: - **держится ли связка признаков** (не уедет ли в обслуживание то, что меняет - поведение, и наоборот — не заведут ли пустой change по привычке); **работает - ли ревью без change** — конвейер написан вокруг него, и прогон с - фиксированным планом не запускался ни разу; **есть ли чем сверить состав - гейта** — на живых проектах семантика гейта в `CLAUDE.md` может не называть - шагов поимённо, и тогда сверка вырождается в цвет -- [ ] перемерить скилл `review` тем же вопросом, что и проект целиком: - сколько из его стадий реально смотрятся глазами. Тысяча строк, и весь - автоматический участок между чекпоинтами держится на них -- [ ] чекпоинт «объяснение» собирается из `proposal.md` и `design.md`, а - требования к их форме уехали в `openspec/config.yaml` (`rules.proposal`, - `rules.design`). **На живом проекте это ни разу не работало:** неизвестно, - хватает ли двух артефактов, чтобы объяснение не пришлось дописывать руками - -## 5. Мелочь, оставленная аудитом сознательно - -Одной пачкой, когда будет повод открыть эти файлы, — не раньше: - -- [ ] «чекпоинт» несёт третий смысл — точка наблюдаемости в коде - (`finding-contract.md`, `promote.md`). Слово занято дважды по своему же - правилу, но домены разные, и переименование здесь может выйти дороже - путаницы -- [ ] закрытый словарь `shared/language.md` не содержит ни «конвейера», ни - «чекпоинта», ни «груминга» — трёх рабочих терминов репозитория. Список - объявлен закрытым, и пополнять его на ходу нельзя -- [ ] `move <слаг>` без флагов теперь легален и значит «в конец своей секции» — - осмысленная операция, но в прозе не описана нигде -- [ ] `reopen` печатает «позиция это приоритет» и для целей роадмапа, где секции - очередью не являются - -## 6. Обкатка - -- [ ] один-два цикла healthlog на новом процессе. Наблюдения к первой обкатке - два: не выродились ли «границы покрытия» в шаблон (REMAINING, «Открытые - вопросы») и **не превратился ли чекпоинт в ритуал одобрения** — признак - тот же, дословно повторяющийся текст и согласие без единой правки diff --git a/decisions/README.md b/decisions/README.md index 5c6c0ad..10bead1 100644 --- a/decisions/README.md +++ b/decisions/README.md @@ -13,8 +13,6 @@ числом не переписывается. Отсюда и разнобой формы — ранние темы держат решения под заголовком «Решено», поздние ведут их прозой. -Незакрытые остатки прошлого захода — [REMAINING.md](../REMAINING.md). - ## Требования, зафиксированные по ходу Не решения — вход, который обязан быть удовлетворён и разбирается в названной diff --git a/scripts/addresses.py b/scripts/addresses.py index 48cb6e7..82c111e 100644 --- a/scripts/addresses.py +++ b/scripts/addresses.py @@ -60,7 +60,6 @@ JOURNALS = { "av-dev/skills/doc-canon/references/changelog-tasks-before-merge.md": "журнал версий формата задач до слияния", "decisions/": "журнал решений", - "HISTORY.md": "журнал работ", "NOTES.md": "рабочие заметки", }