заведён TOOL.md — стартовая точка для convy

- имя, термины suite/project, раскладка команд: проектные наверху, ведение
  набора под подкомандой suite, check остаётся общим
- собрано в одном месте то, что инструмент делает и чего не делает: сборка
  копии, три группы проверок, независимость от конкретного набора, отказ от
  слияния, лока и обратного транспорта
- два тулинговых вопроса вынесены из TODO в раздел «Открытые вопросы»;
  вопросы про инструмент там больше не живут
This commit is contained in:
av
2026-07-26 17:00:00 +03:00
parent c96566d4b4
commit e8fdc98557
2 changed files with 182 additions and 63 deletions
+8 -63
View File
@@ -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`
Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
по частоте запуска, по тому, кто запускает, и по тому, что считается
провалом.
**Целостность канона.** Префиксы уникальны и не переиспользованы, шапка
совпадает с манифестом, у каждого правила модальность и блок ПОЧЕМУ, ссылки
разрешаются, префикс чужой темы не лезет в норму (META-20), путей канона в
тексте нет (META-21), строка о версии языка на месте. Запускается в каноне,
при каждой правке, провал — это ошибка. Логика уже написана и много раз
прогнана руками, но живёт в скретчпаде, а не в репозитории.
**Установка в проект.** Манифест `.conventions.toml`, сборка файла темы из
слоёв (`arch` → язык → стек), сохранение при пересборке всего, что ниже
маркера, `READING.md` рядом с копиями, предупреждение о висячих ссылках на
неподписанные темы. Запускается
в репозитории-потребителе, изредка, провал — это чаще «посмотри глазами»,
чем «ошибка». Отчёта «канон ушёл вперёд» здесь нет: его делает `git diff`
после пересборки.
Что обсудить:
- Разделять ли на два исполняемых файла, или хватит подкоманд с честной
границей внутри.
- Валидацию канона стоит ли отдать агенту скиллом вместо (или вдобавок к)
скрипту: часть проверок формулируется как «прочитай и скажи, самодостаточна
ли норма» — механически это не берётся, а агентом берётся.
- Куда в этой раскладке ложится запаркованное предупреждение о висячих
ссылках: это установка, а не целостность, но список подписок ему нужен из
манифеста.
Список проверок теперь реализуем целиком: граница правила определена,
нумерация сплошная, снятое правило остаётся заглушкой — данных со стороны
языка проверке хватает.
Перед тем как переписывать, стоит посмотреть на два готовых прототипа:
дистрибуцию пакетов Vale (`.vale.ini``vale sync``styles/`) как образец
манифеста и `vendir.yml` — как пример того, где проходит граница между «чего
хочу» и «что получил».
## 5. Пары слоёв и темы без базы
## 4. Пары слоёв и темы без базы
Отложено сознательно, но список стоит держать перед глазами:
@@ -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 при этом
дешевле заложить сразу, чем отпиливать потом.