manifest.toml переименован в suite.toml

- родовое «манифест» заменено именем уровня: файл в наборе описывает сам набор, файл в проекте — подключённые конвенции, и каждый назван по тому, что описывает - по имени рядом лежащего манифеста определяется контекст: suite.toml — набор, .conventions.toml — проект; в TOOL.md решение зафиксировано, из открытых вопросов убрано
заведён TOOL.md — стартовая точка для convy
2026-07-26 17:06:29 +03:00 · 2026-07-26 17:00:00 +03:00
5 changed files with 198 additions and 74 deletions
@@ -9,7 +9,7 @@ code in this repository.
 Канон конвенций разработки для личных проектов. Сами конвенции лежат в
 `conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`,
-`LANGUAGE.md`, `GUIDE.md`, `READING.md`, `manifest.toml`, `conv`) живёт в
+`LANGUAGE.md`, `GUIDE.md`, `READING.md`, `suite.toml`, `conv`) живёт в
 корне. К потребителю из неё едет только `READING.md` — короткое описание языка
 для читателя копий.
@@ -76,7 +76,7 @@ code in this repository.
  латиницей, рекомендуется нижний kebab-case, годится любой идентификатор,
  пригодный для имени файла.
 - META-28: тема объявлена в шапке (`topic: time`) и стоит в манифесте набора
-  (`manifest.toml`, секция `[topics.live]`). Слои одной темы несут одно имя —
+  (`suite.toml`, секция `[topics.live]`). Слои одной темы несут одно имя —
  по нему собираются в один файл, как бы ни назывались их файлы; имя файла
  повторяет тему из удобства.
 - META-29: имя темы не переиспользуется, снятое уходит в `[topics.retired]`
@@ -13,7 +13,7 @@
 | [LANGUAGE.md](LANGUAGE.md) | язык записи правил: идентификаторы, модальность, обоснование |
 | [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления |
 | [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю |
-| [manifest.toml](manifest.toml) | манифест набора: язык, темы, префиксы правил |
+| [suite.toml](suite.toml) | манифест набора: язык, темы, префиксы правил |
 | `conv` | сборка копий |
 К потребителю едет содержимое `conventions/` и один файл обвязки —
@@ -103,7 +103,7 @@ prefix: KEYS
 документ, как бы ни назывались их файлы. Имя файла повторяет тему из
 удобства, но истина — в шапке.
-Темы перечислены в манифесте набора — [`manifest.toml`](manifest.toml),
+Темы перечислены в манифесте набора — [`suite.toml`](suite.toml),
 секция `[topics.live]`: имя и однострочное описание. Имя темы не
 переиспользуется по той же причине, что и префикс: оно живёт в чужих
 репозиториях — в шапке `origin:` каждой копии, в подписке манифеста, в тексте
@@ -229,7 +229,7 @@ MIGR-6 не соблюдается в `show_history`, `queue`: составны
 | Файл | Где лежит | Что описывает |
 |---|---|---|
-| `manifest.toml` | в наборе | сам набор: темы и префиксы правил |
+| `suite.toml` | в наборе | сам набор: язык, темы, префиксы правил |
 | `.conventions.toml` | в проекте | подключение: откуда копии, какие темы, язык, стек |
 Манифест набора — единственное место, где перечислены оба идентификатора
@@ -2,9 +2,12 @@
 Черновик для следующего разговора: вопросы и варианты, а не принятые
 решения. Закрытый вопрос отсюда удаляется — принятое решение живёт в
-`README.md`, `GUIDE.md` или `LANGUAGE.md`, а не в этом файле.
+`README.md`, `GUIDE.md`, `LANGUAGE.md` или `TOOL.md`, а не в этом файле.
-Две секции: сначала язык и подход, потом канон с тулингом.
+Вопросы про инструмент здесь не живут — они собраны в `TOOL.md`, раздел
 «Открытые вопросы».
 Две секции: сначала язык и подход, потом сам набор и подключение.
 # Язык и подход
@@ -64,50 +67,9 @@ API, а норму при этом нельзя поправить, не зад
 сущность и ещё одна синхронизация; при одном наборе лечение выходит хуже
 болезни.
-# Канон, тулинг, подключение
+# Канон и подключение
-## 4. Тулинг: две разные задачи в одном `conv`
+## 4. Пары слоёв и темы без базы
 Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
 по частоте запуска, по тому, кто запускает, и по тому, что считается
 провалом.
 **Целостность канона.** Префиксы уникальны и не переиспользованы, шапка
 совпадает с манифестом, у каждого правила модальность и блок ПОЧЕМУ, ссылки
 разрешаются, префикс чужой темы не лезет в норму (META-20), путей канона в
 тексте нет (META-21), строка о версии языка на месте. Запускается в каноне,
 при каждой правке, провал — это ошибка. Логика уже написана и много раз
 прогнана руками, но живёт в скретчпаде, а не в репозитории.
 **Установка в проект.** Манифест `.conventions.toml`, сборка файла темы из
 слоёв (`arch` → язык → стек), сохранение при пересборке всего, что ниже
 маркера, `READING.md` рядом с копиями, предупреждение о висячих ссылках на
 неподписанные темы. Запускается
 в репозитории-потребителе, изредка, провал — это чаще «посмотри глазами»,
 чем «ошибка». Отчёта «канон ушёл вперёд» здесь нет: его делает `git diff`
 после пересборки.
 Что обсудить:
 - Разделять ли на два исполняемых файла, или хватит подкоманд с честной
  границей внутри.
 - Валидацию канона стоит ли отдать агенту скиллом вместо (или вдобавок к)
  скрипту: часть проверок формулируется как «прочитай и скажи, самодостаточна
  ли норма» — механически это не берётся, а агентом берётся.
 - Куда в этой раскладке ложится запаркованное предупреждение о висячих
  ссылках: это установка, а не целостность, но список подписок ему нужен из
  манифеста.
 Список проверок теперь реализуем целиком: граница правила определена,
 нумерация сплошная, снятое правило остаётся заглушкой — данных со стороны
 языка проверке хватает.
 Перед тем как переписывать, стоит посмотреть на два готовых прототипа:
 дистрибуцию пакетов Vale (`.vale.ini` → `vale sync` → `styles/`) как образец
 манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
 хочу» и «что получил».
 ## 5. Пары слоёв и темы без базы
 Отложено сознательно, но список стоит держать перед глазами:
@@ -128,7 +90,7 @@ API, а норму при этом нельзя поправить, не зад
 - Вынос арх-ядра из `errors` и `logging` закроет две хрупкие ссылки из
  `web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
-## 6. Подключение к репозиториям
+## 5. Подключение к репозиториям
 Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
 Понадобится: заполнить локальную часть копий тем, что сейчас в этих
@@ -136,20 +98,3 @@ API, а норму при этом нельзя поправить, не зад
 `task conventions`, единый интерфейс команд у трёх ansible-репозиториев);
 строка в `AGENTS.md` каждого потребителя про то, что файлы в
 `docs/conventions/` — копии.
 ## 7. Тулинг на Go, живущий независимо
 Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
 одном репозитории и правятся одним движением. Мысль: вынести в отдельный
 Go-бинарь со своим релизным циклом, ставить через `eget` (механизм уже есть
 в pet-project-server).
 Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
 инструмент «заодно» с правкой конвенции, работает против **любого** канона и
 любого потребителя — что прямо требуется вопросом 3, — и снимает питон из
 зависимостей репозиториев-потребителей.
 Порядок обратный ожидаемому: пока вопрос 3 не сделан, инструмент всё равно
 работает против одного конкретного канона, и независимый релизный цикл ему
 нечего обслуживать. Сначала 3, потом 7. Разделение из вопроса 4 при этом
 дешевле заложить сразу, чем отпиливать потом.
@@ -0,0 +1,177 @@
 # Инструмент: convy
 Стартовая точка для разработки. Здесь — принятые решения об инструменте и
 открытые вопросы к нему; модель, которую он реализует, описана в
 [README.md](README.md), а форма правил — в [LANGUAGE.md](LANGUAGE.md). При
 расхождении истина там, а не здесь.
 ## Что это
 `convy` — CLI для управления конвенциями: собирает копии в проектах и
 проверяет целостность набора. Пишется на Go, живёт в отдельном репозитории,
 ставится готовым бинарём.
 Имя выбрано за то, что держит корень предметной области и звучит как маленький
 помощник, а уменьшительное `-y` обещает малость — что правда: инструмент
 копирует файлы, собирает тему из слоёв и проверяет форму, не более. Рядом
 существует английское слово `convey`, отличающееся одной буквой и подходящее
 по смыслу, — опечатку в текстах стоит проверять отдельно.
 Отдельный репозиторий нужен по двум причинам. Инструмент и данные в одном
 репозитории правятся одним движением, и это мешает: лежащий отдельно бинарь
 физически не даёт починить инструмент «заодно» с правкой конвенции. Вторая —
 независимый бинарь работает против любого набора и любого проекта, а не против
 одного конкретного канона.
 ## Термины
 | Уровень | Английский | Русский | Что там лежит |
 |---|---|---|---|
 | набор | `suite` | набор | `conventions/`, манифест набора, обвязка |
 | проект | `project` | проект | `docs/conventions/`, манифест подключения, копии |
 `package`, `bundle`, `library` не берём: они тащат багаж менеджеров
 зависимостей — версии, разрешение, лок, — которого в модели нет. `set` не
 годится в CLI: в позиции подкоманды читается глаголом.
 «Канон» — имя этого конкретного набора, а не термин уровня; в общих
 формулировках употребляется «набор». «Потребитель» — слово про роль
 репозитория, а не про уровень.
 Манифесты названы по тому, что описывают, а не по уровню ради симметрии:
 `suite.toml` в наборе — идентичность набора, `.conventions.toml` в проекте —
 подключённые конвенции. Точка в проекте отделяет служебное от содержимого
 проекта; в наборе файл правится при каждой новой теме, и прятать его незачем.
 Отсюда же бесплатное определение контекста: по имени рядом видно, где ты.
 ## Раскладка команд
 Глубина команды отражает частоту и адресата. Проектные команды выполняются в
 каждом репозитории и часто; ведение набора — в одном репозитории и редко.
 ```
 convy add <тема>    подписаться и собрать
 convy pull          пересобрать подписанное
 convy list          что подключено и что можно взять
 convy check         проверить форму того, что здесь
 convy suite check   целостность набора: префиксы, темы, ссылки, форма
 convy suite new     новая тема: шапка, префикс, запись в манифест
 ```
 Граница проходит не по «проектное против наборного», а по «частое и
 повсеместное» против «только у автора». Поэтому `check` остаётся наверху:
 форма правила одна и та же, локальные правила проекта на `X`-префиксах
 написаны по ней же, и проверять их у себя нужно без подкоманды. Под `suite`
 уходит то, что в проекте не имеет смысла.
 Три следствия для реализации:
 - **контекст определяется и отказ говорится явно.** `.conventions.toml` рядом
  — проект, `suite.toml` — набор. Проектная команда, набранная в наборе, не
  делает ничего наугад: она отказывает и подсказывает наборный аналог;
 - **помощь группируется заголовками** «В проекте» и «В наборе»: в плоском
  списке уровни не видны;
 - **синонимов нет.** `convy project pull` рядом с `convy pull` не заводим: два
  способа сказать одно — то, от чего модель избавлялась в остальных местах.
 В проектах вызов идёт через обёртку раннера (`inv conventions -- pull`,
 `task conventions -- pull`), которая пробрасывает аргументы. Обёртка уже
 называет предмет, поэтому короткая проектная команда здесь тоже выигрывает.
 ## Две задачи, которые нельзя смешивать
 Они расходятся по частоте, по адресату и по тому, что считается провалом.
 **Целостность набора.** Префиксы уникальны и не переиспользованы, шапка
 совпадает с манифестом, тема объявлена и зарегистрирована, у каждого правила
 модальность с нормой и обоснование либо заглушка, нумерация сплошная, ссылки
 разрешаются, путей набора в тексте конвенции нет, строка о версии языка на
 месте. Запускается в наборе при каждой правке; провал — ошибка.
 **Установка в проект.** Манифест подключения, сборка файла темы из слоёв,
 сохранение локальной части, `READING.md` рядом с копиями. Запускается в
 проекте изредка; провал чаще означает «посмотри глазами», чем «ошибка».
 Отчёта «набор ушёл вперёд» нет: его делает `git diff` после пересборки.
 ## Что делает установка
 Подробности — в README, раздел «Копия в репозитории». Коротко, что важно для
 реализации:
 - копия плоская, **один файл на тему**; слои идут секциями в порядке
  `arch` → язык → стек, выбор слоёв — по `lang` и `stack` из манифеста
  подключения;
 - шапка копии — только `origin:` с именем темы; отпечатков и дат нет;
 - всё ниже маркера `<!-- conv:local -->` переживает пересборку, всё выше
  перезаписывается; маркер ставит сборщик;
 - `README.md` в директории принадлежит проекту и не трогается; `READING.md`
  принадлежит набору и перезаписывается целиком;
 - транспорта обратно нет: ни `push`, ни отчёта о расхождении, ни лок-файла.
 ## Что делает проверка
 Список проверок — в `LANGUAGE.md`, раздел «Что стоит проверять машиной». Он
 уже разделён на три части, и это деление прямо ложится в код:
 - **форма правила** — разбором текста, в любом файле, который язык
  употребляет: конвенции и `GUIDE.md`;
 - **распространение** — разбором текста, только в файлах конвенций: тема в
  шапке, префикс чужой темы в норме, пути набора, `X` у локальных правил;
 - **чтением** — то, что машине не даётся: взаимоисключительность строк
  таблицы, покрытие области действия, самодостаточность нормы, обоснование
  отвечает на «что сломается», примеры не расширяют норму.
 Третья часть — не работа `convy`. Её выполняет агент, и по ней стоит завести
 скилл, а не пытаться выразить регуляркой.
 ## Независимость от набора
 Инструмент не зашивает правила языка в код: версия и документы объявлены в
 манифесте набора, секция `[language]`. Пока версия одна, это выглядит
 избыточным — но именно здесь разница между «инструмент для этого канона» и
 «инструмент для любого набора».
 Отсюда же: никаких упоминаний конкретных тем, префиксов и путей в коде.
 ## Чего инструмент не делает
 - не сливает трёхсторонне и не разрешает конфликты: правка выше маркера
  теряется, и это заявленное поведение;
 - не ведёт лок-файл: копии закоммичены, автоматического обновления нет,
  ответ на «что было в прошлый раз» даёт git;
 - не хранит список подписчиков: подписка — свойство проекта;
 - не переносит правки из проекта в набор: это ручная и редкая операция.
 ## Открытые вопросы
 - **Один бинарь или два.** Пока — один с подкомандой `suite`. Разделение
  дешевле заложить сразу, чем отпиливать потом: если задачи разъедутся, у них
  уже будут разные точки входа.
 - **Установка.** `eget` умеет GitHub-релизы, а git у меня свой
  (`git.vakhrushev.me`) — проверить, тянет ли `eget` релизы Gitea, иначе
  остаётся прямой URL или `go install`.
 - **TOML.** В stdlib парсера нет, значит одна внешняя зависимость
  (`BurntSushi/toml` или `pelletier/go-toml`). Выбрать и больше зависимостей
  не заводить.
 - **Предупреждение о висячих ссылках** на неподписанные темы: это установка,
  а не целостность, но список подписок ему нужен из манифеста подключения.
 - **Проверка на `convey`** в текстах — вместе с остальными проверками формы
  или отдельной мелочью.
 - **Прототипы, на которые стоит посмотреть** до того, как писать: дистрибуция
  пакетов Vale (`.vale.ini` → `vale sync` → `styles/`) как образец манифеста и
  `vendir.yml` — как пример границы между «чего хочу» и «что получил».
 ## Состояние
 `convy` не начат. В наборе лежит `conv` — питоновский скрипт под прежнюю
 модель копий: зеркальное дерево, именованные регионы, `origin_hash`, команды
 `status`, `diff`, `push`. Он не истина ни в чём: модель описана в README,
 проверки — в `LANGUAGE.md`.
 Логика проверок целостности написана и много раз прогнана руками, но живёт в
 скретчпадах сессий, а не в репозитории. При старте разработки её стоит
 перенести первой — это готовая спецификация в виде кода.
 Переименование `conv` → `convy` в обвязке (`README.md`, `CLAUDE.md`) делается
 одним заходом, когда инструмент будет готов.
@@ -1,11 +1,13 @@
-# Манифест набора конвенций.
+# suite.toml — манифест набора конвенций.
 #
-# Манифестов в модели два, и они отвечают на разные вопросы:
+# Манифестов в модели два, и каждый назван по тому, что описывает:
 #
-#   - этот, в наборе, описывает сам набор: какие в нём темы и какие префиксы
+#   - `suite.toml` здесь, в наборе, — сам набор: язык записи, темы, занятые
-#     правил заняты;
+#     префиксы правил;
-#   - `.conventions.toml` в репозитории-потребителе описывает подключение:
+#   - `.conventions.toml` в проекте — подключение: откуда взяты копии, какие
-#     откуда взяты копии, какие темы выбраны, какие язык и стек.
+#     темы выбраны, какие язык и стек.
 #
 # По тому, какой из двух лежит рядом, видно, где ты находишься.
 #
 # Оба идентификатора набора — тема и префикс — живут здесь, потому что
 # правила у них общие: объявляются в шапке файла, сверяются с манифестом,