From 4386eb3e1cd3aa760d9132608a294bb48f142751 Mon Sep 17 00:00:00 2001 From: Anton Vakhrushev Date: Fri, 7 Aug 2026 08:57:09 +0300 Subject: [PATCH] =?UTF-8?q?=D1=88=D0=BE=D0=B2=20=D0=BC=D0=B5=D0=B6=D0=B4?= =?UTF-8?q?=D1=83=20=D0=BF=D0=BB=D0=B0=D0=B3=D0=B8=D0=BD=D0=B0=D0=BC=D0=B8?= =?UTF-8?q?:=20=D0=BA=D0=B0=D0=BD=D0=BE=D0=BD=20=D0=BF=D0=B5=D1=80=D0=B5?= =?UTF-8?q?=D1=81=D1=82=D0=B0=D0=BB=20=D0=BD=D0=B0=D0=B7=D1=8B=D0=B2=D0=B0?= =?UTF-8?q?=D1=82=D1=8C=20=D0=B8=D0=BC=D0=B5=D0=BD=D0=B0=20=D0=BF=D1=80?= =?UTF-8?q?=D0=BE=D1=85=D0=BE=D0=B4=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit av-dev-pm и av-dev-pipeline раздельны: канон работает без конвейера, конвейер без канона — поразрядно деградируя и называя это строкой. Но канон в шести местах называл конвейер поимённо, и одно из них — вывод docs.py пользователю: «свои темы проекта: … — их разбирает review-basics». Такая строка чинится не правкой файла, а недоумением на чужом проекте. Правило записано в canon.md, чтобы не отрастало заново. Общий словарь — имена тем и имена ступеней, и только они: ими проект настраивает ревью, вопросами по темам и триггерами профиля. Имён проходов канон не называет нигде. Направление несимметрично, и это верно: конвейер называет документы канона поимённо, потому что он их читатель, а обратной ссылки быть не может — документ живёт дольше, чем раскладка проходов. Что вычищено: имя review-basics в canon.md, в changelog версии 5 и в выводе docs.py; «её берёт basics» из таблицы ролей; описательные адресации того же класса — «архитектурный проход судит», «враждебный проход выдумает». Худшей была строка в skeletons.md «там идут враждебный, эксплуатационный и архитектурный проходы»: утверждение о составе ступени, живущее на стороне, которая о составе не знает. Строка таблицы «эксплуатационный проход ревью» стала «тема ревью operations» — заодно совпала со словарём, к которому tasks/SKILL.md отсылает как к единому дому. Отдельно — пример, нарушавший собственное правило. Объяснение, почему вопросы адресуются темам, звучало «вопрос, адресованный ops, перестал задаваться в тот день, когда ops уехал в верхнюю ступень»: правило про нестабильность имён, проиллюстрированное именем. Стало «адресованный проходу» и переживёт переименование. Починена и висячая ссылка: project-facts.md отсылал к таблице «Кто читает» в каноне, которой там нет — она была убрана правкой, вводившей темы, и по новому правилу её и не должно быть. Списка читателей не ведёт никто: читателя назначает план прогона. Тема 38 в DECISIONS.md, следствия 143-144. Co-Authored-By: Claude Opus 5 (1M context) --- DECISIONS.md | 35 +++++++++++++++++++ .../references/project-facts.md | 14 +++++--- av-dev-pm/agents/doc-consistency.md | 2 +- av-dev-pm/skills/canon/references/canon.md | 23 +++++++----- .../skills/canon/references/changelog.md | 6 ++-- .../skills/canon/references/skeletons.md | 12 +++---- av-dev-pm/skills/canon/scripts/docs.py | 4 +-- av-dev-pm/skills/init/SKILL.md | 2 +- av-dev-pm/skills/tasks/SKILL.md | 2 +- 9 files changed, 74 insertions(+), 26 deletions(-) diff --git a/DECISIONS.md b/DECISIONS.md index 9162f3e..8a2ff6b 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -2626,3 +2626,38 @@ JJJ): у профиля обязан быть один правильный от 142. **Слово, уже значащее что-то в предметной области проекта, нельзя брать именем роли конвейера.** «Гейт» принадлежит проекту раньше, чем ревью, и спор за него ревью проигрывает. + +## 38. Шов между плагинами: канон не называет имён проходов (2026-08-07) + +Замечено при сведении тем документации с ревьюверами: `av-dev-pm` в шести местах +называл конвейер поимённо — от прозы канона до **вывода `docs.py` пользователю** +(«свои темы проекта: … — их разбирает `review-basics`»). Плагины при этом +раздельные: `av-dev-pm` работает без конвейера, `av-dev-pipeline` — без канона, +поразрядно деградируя. + +**АДААА. Общий словарь — имена тем и имена ступеней, и только они.** Ими проект +настраивает ревью: вопросы по темам и триггеры профиля. Имён проходов канон не +называет нигде. Направление зависимости при этом несимметрично и это верно: +**конвейер называет документы канона поимённо, потому что он их читатель**, а +обратной ссылки быть не может — документ живёт дольше, чем раскладка проходов. + +Заодно вычищены описательные адресации того же класса: «архитектурный проход +судит», «враждебный проход выдумает», «там идут враждебный, эксплуатационный и +архитектурный проходы». Последняя — худшая из них: это утверждение о **составе +ступени**, живущее на стороне, которая о составе не знает. + +**АДААБ. Пример в правиле не должен нарушать само правило.** Объяснение, почему +вопросы адресуются темам, звучало так: «вопрос, адресованный `ops`, перестал +задаваться в тот день, когда `ops` уехал в верхнюю ступень». Правило про +нестабильность имён, иллюстрированное именем. Стало «адресованный проходу» — и +работает даже после того, как проход переименуют. + +### Что из этого следует + +143. **Ссылка из вывода скрипта дороже ссылки из прозы.** Устаревшую строку в + документе чинит тот, кто её читает; устаревшее имя в сообщении `docs.py` + доезжает до чужого проекта и там объясняется недоумением. +144. **Список, который никто не ведёт, честнее списка, который ведут двое.** + Читателей документа не перечисляет ни одна сторона — читатель назначается + планом прогона. Прежняя ссылка на «таблицу читателей» пережила саму таблицу + и обещала то, чего нет, — с той самой правки, которая таблицу и убрала. diff --git a/av-dev-pipeline/skills/review-pipeline/references/project-facts.md b/av-dev-pipeline/skills/review-pipeline/references/project-facts.md index e3e3647..f9c938a 100644 --- a/av-dev-pipeline/skills/review-pipeline/references/project-facts.md +++ b/av-dev-pipeline/skills/review-pipeline/references/project-facts.md @@ -81,10 +81,16 @@ список и **не сливает в одну строку**: разные пробелы чинятся разным — периметр пишется руками за десять минут, а числа требуют замера. -**Кто какой документ читает — не здесь.** Полный список читателей ведёт канон -(`Skill av-dev-pm:canon`, его `references/canon.md`, таблица «Кто читает»); ниже — -только **последствие** отсутствия, и оно называет самое дорогое, а не всех -пострадавших. Два списка читателей уже однажды разошлись; второго раза не надо. +**Кто какой документ читает — из документа не выводится, а назначается планом.** +Документ питает тему (это записано на стороне канона, таблица «Роли документов и +темы ревью»), а тему на этом прогоне закрывает тот, кого назвал разметчик; вся +раскладка «тема → проход → глубина» — в `SKILL.md` этого скилла и больше нигде. +**Списка читателей не ведёт никто, и это не пробел.** Он жил бы на стороне +канона, а документ живёт дольше, чем раскладка проходов: список разошёлся бы с +конвейером молча и при этом выглядел актуальным. Однажды уже разошёлся. + +Ниже — только **последствие** отсутствия дома, и оно называет самое дорогое, а не +всех пострадавших. | Нет дома | Что деградирует | | --- | --- | diff --git a/av-dev-pm/agents/doc-consistency.md b/av-dev-pm/agents/doc-consistency.md index 1432f08..be4888a 100644 --- a/av-dev-pm/agents/doc-consistency.md +++ b/av-dev-pm/agents/doc-consistency.md @@ -113,7 +113,7 @@ color: yellow `adr/README.md`; - **замена парная**: новая запись пересматривает прежнее решение — у старой обязан быть статус «заменено на». Односторонняя замена оставляет две - активные записи об одном, и `architecture` прочитает ту, что нашёл первой. + активные записи об одном, и читатель прочитает ту, что нашёл первой. 7. **Пустое названо пустым, а не заглушено.** Незаполненный документ канона держит **одну честную информативную строку**: «внешних зависимостей нет — diff --git a/av-dev-pm/skills/canon/references/canon.md b/av-dev-pm/skills/canon/references/canon.md index fc589de..1d4ff4e 100644 --- a/av-dev-pm/skills/canon/references/canon.md +++ b/av-dev-pm/skills/canon/references/canon.md @@ -34,7 +34,7 @@ | --- | --- | --- | | `ROADMAP.md`, секция `Сопровождение` | план | **работы**, которые собираемся делать: цели и их задачи | | `architecture.md`, раздел «Эксплуатация» | состояние | **как устроено сейчас**: где работает, что рядом, кто перезапускает | -| эксплуатационный проход ревью | оптика | **чем проверяем**: «это упало через неделю на проде» | +| тема ревью `operations` | оптика | **чем проверяем**: «это упало через неделю на проде» | Слово **«поддержка» не употребляется вовсе** — в нём слышится помощь пользователю, а это другая работа. @@ -80,10 +80,10 @@ openspec/ `ADR-ГГГГ-ММ-ДД-slug.md`. **Список тем открытый, и это не послабление, а механизм.** Всё, что проект -кладёт в `docs/`, становится темой ревью: конвейер разбирает её проходом -`review-basics`, у которого именной оптики нет и который для того и заведён. -Завёл `docs/accessibility.md` — появилась тема `accessibility`, и она попадает в -план каждого прогона. Не темы ровно две: `docs/tasks/` (его ведёт скилл `tasks`) +кладёт в `docs/`, становится темой ревью: у конвейера есть приёмник для темы, к +которой нет именной оптики, и заведён он ровно за этим. Завёл +`docs/accessibility.md` — появилась тема `accessibility`, и она попадает в план +каждого прогона. Не темы ровно две: `docs/tasks/` (его ведёт скилл `tasks`) и `docs/review.*` — это настройка самого конвейера, слой над темами. Отсюда следствие, ради которого правило и заведено: **`docs/` — это конфигурация @@ -121,6 +121,13 @@ kebab-case.** Причина не эстетическая: имя файла с прогона и меняется вместе с конвейером, а документ живёт дольше. Раскладку «тема → проход → глубина» держит скилл `av-dev-pipeline:review-pipeline`. +**Общего словаря у канона с конвейером ровно два вида имён: имена тем и имена +ступеней.** Ими проект и настраивает ревью — вопросами по темам и триггерами +профиля. **Имён проходов канон не называет нигде**, включая вывод `docs.py`: +проход переименовывается и переезжает между ступенями, и канон, назвавший его, в +этот день соврёт молча. Обратное направление законно — конвейер называет +документы канона поимённо, потому что он их читатель. + | Документ | Вопрос | Тема ревью | | --- | --- | --- | | `CLAUDE.md`, `AGENTS.md` | что нельзя нарушать, чем краснеет гейт | `autotests`; инварианты — сквозные, во все темы | @@ -133,7 +140,7 @@ kebab-case.** Причина не эстетическая: имя файла с | `adr.*` | почему решено именно так | `architecture` | | `openspec/specs/` | что система делает — нормативно | `requirements` | | `review.*` | как настроен конвейер и что уже проскакивало | **не тема**: слой над всеми | -| *свой документ проекта* | что проект счёл нужным проверять | **своя тема**, её берёт `basics` | +| *свой документ проекта* | что проект счёл нужным проверять | **своя тема**, именем документа | ### `passport.md` @@ -185,7 +192,7 @@ kebab-case.** Причина не эстетическая: имя файла с **Периметр первой строкой.** «Сервис открыт наружу» и «контур доверенный, публичного интернета здесь нет, не выдумывай его» — противоположные постановки -под одним заголовком, и враждебный проход между ними сам не выберет. Контур ещё +под одним заголовком, и разбор темы `security` между ними сам не выберет. Контур ещё не развёрнут — назови **оба** периметра, целевой и сегодняшний, и скажи прямо, против какого строятся находки. @@ -250,7 +257,7 @@ kebab-case.** Причина не эстетическая: имя файла с всегда неверны, каждая со строкой «почему здесь это не дефект»; - **Вопросы по темам** — в форме `<тема>: <вопрос> (<провенанс>)`. **Не по именам проходов**: проход уезжает между ступенями, а тема остаётся, и вопрос, - адресованный `ops`, перестал бы задаваться молча в тот день, когда `ops` уехал + адресованный проходу, перестал бы задаваться молча в тот день, когда тот уехал в верхнюю ступень. Задаёт вопрос тот, кто закрывает тему на этом прогоне; - **Триггеры профиля** — проектная конкретизация правила выбора профиля ревью: что в этом проекте считается **крупным или незнакомым** изменением (поднимает diff --git a/av-dev-pm/skills/canon/references/changelog.md b/av-dev-pm/skills/canon/references/changelog.md index 3446b20..9929b10 100644 --- a/av-dev-pm/skills/canon/references/changelog.md +++ b/av-dev-pm/skills/canon/references/changelog.md @@ -29,8 +29,8 @@ upgrade` идёт по записям снизу вверх от версии п каталогами, остальные — файлами, и обосновать это было нечем. Обе формы сразу — ошибка: два дома для одного факта расходятся молча. 2. **Список тем открытый.** Всё, что проект кладёт в `docs/`, становится темой - ревью и попадает в план каждого прогона; разбирает такие темы проход - `review-basics`, у которого именной оптики нет и который для того и заведён. + ревью и попадает в план каждого прогона; именной оптики у такой темы нет, её + разбирает общий проход конвейера, заведённый ровно за этим. Прежде `docs.py` называл незнакомый файл «вне канона» — теперь называет своей темой проекта и перечисляет их в отчёте. Не темы ровно две: `docs/tasks/` и `docs/review.*`. @@ -42,7 +42,7 @@ upgrade` идёт по записям снизу вверх от версии п - в `docs/review.*`: **«Вопросы к проходам» → «Вопросы по темам»**, форма `<тема>: <вопрос> (<провенанс>)`. Причина не косметическая: вопрос, - адресованный `ops`, перестал задаваться молча в тот день, когда `ops` уехал в + адресованный проходу, перестал задаваться молча в тот день, когда тот уехал в верхнюю ступень ревью. Тема переезд прохода переживает, имя прохода — нет; - там же **«Недоступно проверке» — по темам**, оба подраздела. diff --git a/av-dev-pm/skills/canon/references/skeletons.md b/av-dev-pm/skills/canon/references/skeletons.md index d4da3b0..e591d6f 100644 --- a/av-dev-pm/skills/canon/references/skeletons.md +++ b/av-dev-pm/skills/canon/references/skeletons.md @@ -46,7 +46,7 @@ ## Что целью не является -Граница домена. По ней архитектурный проход судит, не перенесено ли понятие +Граница домена. По ней в теме `architecture` судят, не перенесено ли понятие через границу. ## Типовые сценарии @@ -144,8 +144,8 @@ ## Что вне модели -Перечислить явно. Пустой пункт означает, что враждебный проход выдумает угрозу -сам, и находка никогда не будет исправлена. +Перечислить явно. Пустой пункт означает, что в теме `security` угрозу выдумают +за тебя, и находка никогда не будет исправлена. ``` ## `docs/conventions/README.md` @@ -283,8 +283,8 @@ к обязательным. **Адресуй теме, а не имени прохода.** Проходы переезжают между ступенями и -упраздняются; вопрос, адресованный `ops`, перестанет задаваться в тот день, когда -`ops` уедет в верхнюю ступень, — и заметить это будет нечем. Тема переезд +упраздняются; вопрос, адресованный проходу, перестанет задаваться в тот день, +когда тот уедет в верхнюю ступень, — и заметить это будет нечем. Тема переезд переживает. Темы ядра: `requirements`, `autotests`, `conventions`, `architecture`, @@ -297,7 +297,7 @@ узлами или capability. **Крупное или незнакомое здесь** — поднимает прогон до `wide`, верхней ступени: -там идут враждебный, эксплуатационный и архитектурный проходы, и там же +там `security`, `operations` и `architecture` проверяют запуском, и там же единственные замеры. Ступень рассчитана на **5–10% задач**; если сюда попадает каждая третья, список написан слишком широко. diff --git a/av-dev-pm/skills/canon/scripts/docs.py b/av-dev-pm/skills/canon/scripts/docs.py index 735afe9..34dfc29 100644 --- a/av-dev-pm/skills/canon/scripts/docs.py +++ b/av-dev-pm/skills/canon/scripts/docs.py @@ -359,8 +359,8 @@ def check_stray(root: Path, rep: Report) -> None: own.append(theme) if own: rep.note( - f"свои темы проекта: {', '.join(own)} — их разбирает review-basics," - f" именного прохода у них нет" + f"свои темы проекта: {', '.join(own)} — именной оптики у них нет," + f" их разбирает общий проход конвейера" ) diff --git a/av-dev-pm/skills/init/SKILL.md b/av-dev-pm/skills/init/SKILL.md index 7ea846e..0c74799 100644 --- a/av-dev-pm/skills/init/SKILL.md +++ b/av-dev-pm/skills/init/SKILL.md @@ -39,7 +39,7 @@ description: "Завести новый проект — сессия вопро 1. **Цель и потребители.** Ради чего это; кто пользуется — список закрытый, и он определяет, что считать нужным, а что интересным. 2. **Чем это НЕ является и мера успеха.** Граница домена — критерий, по - которому архитектурный проход потом судит о переносе понятия. Мера — по чему + которому потом судят в теме `architecture` о переносе понятия. Мера — по чему поймём, что удалось. 3. **Периметр и недоверенный вход.** Открыт наружу или контур доверенный; что приходит извне и каким каналом; что чувствительнее чего. Контур ещё не diff --git a/av-dev-pm/skills/tasks/SKILL.md b/av-dev-pm/skills/tasks/SKILL.md index 2433a23..d2bfe85 100644 --- a/av-dev-pm/skills/tasks/SKILL.md +++ b/av-dev-pm/skills/tasks/SKILL.md @@ -207,7 +207,7 @@ stateDiagram-v2 **Сопровождение и эксплуатация — целое и часть**, а не синонимы, и та же тема живёт ещё в двух местах канона: разделе «Эксплуатация» в `architecture.md` и -эксплуатационном проходе ревью. Словарь у всех трёх общий и живёт одним домом — +теме ревью `operations`. Словарь у всех трёх общий и живёт одним домом — [canon.md](../canon/references/canon.md), раздел «Сопровождение и эксплуатация». Пересказывать его здесь нельзя: три перечня «чем держат проект» уже разъезжались на «метриках и логах» против «мониторинга».