dev-conventions/TODO.md

# К обсуждению

Черновик для следующего разговора: вопросы и варианты, а не принятые
решения.

## 1. Ссылка на `LANGUAGE.md` не переживает сборку

Все двенадцать конвенций во вводной прозе пишут «Форма записи —
`LANGUAGE.md`». Обвязка в репозиторий не едет (`conv` синхронизирует только
`conventions/`), поэтому в собранной копии эта ссылка указывает в никуда.

Это тот же класс дефекта, который вчера закрыло META-21 для ссылок между
темами: путь, верный в каноне, молча умирает при сборке. Разница в том, что
META-21 предлагает заменить путь на имя темы — а здесь заменять не на что,
целевого документа в репозитории просто нет.

Варианты, которые видно сейчас:

- **Убрать упоминание из тел конвенций.** Язык записи — забота того, кто
  пишет канон, а не того, кто читает конвенцию в своём репозитории. Читателю
  достаточно самого текста: модальные слова и «Почему» самоописательны.
  Дешевле всего, но копия теряет указание, по каким правилам её править.
- **Возить обвязку вместе с конвенциями.** Тогда `LANGUAGE.md` и, возможно,
  `GUIDE.md` появляются в `docs/conventions/` как ещё одни синхронизируемые
  файлы. Честно, но противоречит нынешнему разделению «канон — конвенции,
  корень — обвязка» и добавляет в репозиторий текст, который агенту при
  чтении конвенции не нужен.
- **Вкладывать короткую преамбулу в собранный файл.** Сборщик пишет в шапку
  три-четыре строки: что такое модальное слово, что «Почему» обязательно,
  где лежит полный документ. Самодостаточно и не тащит весь язык, но
  преамбула дублируется в каждом файле темы.

Сопутствующее: `GUIDE.md` в телах конвенций не упоминается ни разу —
проверено, так что вопрос только про `LANGUAGE.md`.

## 2. Тулинг: две разные задачи в одном `conv`

Сейчас в `conv` смешаны две категории работы, и они расходятся по всему —
по частоте запуска, по тому, кто запускает, и по тому, что считается
провалом.

**Целостность канона.** Префиксы уникальны и не переиспользованы, шапка
совпадает с реестром, номера без дыр вниз, у каждого правила модальность и
«Почему», ссылки разрешаются, чужой префикс не лезет в норму (META-20),
путей канона в тексте нет (META-21). Запускается в каноне, при каждой
правке, провал — это ошибка. Логика уже написана и много раз прогнана
руками, но живёт в скретчпаде, а не в репозитории.

**Установка в проект.** Манифест `.conventions.toml`, сборка файла темы из
секций (arch → языки → стеки → local), сохранение локальной секции при
пересборке, отчёт «канон ушёл вперёд», предупреждение о висячих ссылках на
неподписанные темы. Запускается в репозитории-потребителе, изредка, провал —
это чаще «посмотри глазами», чем «ошибка».

Что обсудить:

- Разделять ли на два исполняемых файла, или хватит подкоманд с честной
  границей внутри.
- Валидацию канона стоит ли отдать агенту скиллом вместо (или вдобавок к)
  скрипту: часть проверок формулируется как «прочитай и скажи, самодостаточна
  ли норма» — механически это не берётся, а агентом берётся.
- Куда в этой раскладке ложится запаркованное предупреждение о висячих
  ссылках: это установка, а не целостность, но список подписок ему нужен из
  манифеста.

## 3. Согласованная модель сборки нигде не записана

Самое срочное. Договорённости про плоскую раскладку живут только в
переписке, а репозиторий описывает прежнюю модель — и противоречит новой в
нескольких местах сразу.

Что решено, но не зафиксировано:

- копия плоская, файл на тему: `docs/conventions/config.md`, а не дерево
  `arch/` + `lang/`;
- файл темы собирается из секций `arch → языки → стеки → local` с
  машиночитаемыми маркерами `<!-- conv:section … -->` и `<!-- conv:local -->`;
- языки и стеки образуют разреженную матрицу; файл темы собирает её строку,
  многоязычная тема держит несколько языковых секций в одном файле;
- выбор описывается манифестом `.conventions.toml` в корне
  репозитория-потребителя; путь к канону там **не** хранится;
- направление строго одностороннее: канон → код. Правка канона делается
  руками в каноне, потом пересборка;
- локальные префиксы правил репозитория объявляются в манифесте и не
  пересекаются с реестром канона.

Что этому прямо противоречит в репозитории сейчас:

- `README.md` → «Раскладка в репозитории» показывает зеркальное дерево
  `docs/conventions/arch/db-identifiers.md`;
- `README.md` → «Команды» и «Контракт с агентом» описывают `conv push` и
  `conv push --new` как штатный путь; при односторонней модели транспорт
  назад исчезает, остаётся только детект «копия правлена вне локальной
  секции»;
- `conv` содержит `cmd_push` со всей обвязкой (`--new`, `--force`).

## 4. Именованные регионы → одна локальная секция

Решено заменить регионы `<!-- local:имя -->` на одну локальную секцию в
конце собранного файла: отступление ссылается на идентификатор правила
(`DIRS-5`), а не стоит рядом с ним. Это то, что делает
сравнение копии с каноном одним хешем и выкидывает из `conv` перенос
регионов по именам.

Сделать перенос ещё предстоит: в каноне сейчас **31 регион в 12 файлах**.

```
7  связано        7  отступления     7  механизировано
1  эталон / эталоны / словарь / секреты / секретные-поля
1  проверки / поля / модель-владельца / маппинг / границы
```

Отдельно решить, что делать с `связано`: сейчас это репо-специфичная часть
раздела «Связано» (META-17), и при единой локальной секции она переезжает
туда же — надо проверить, что META-17 после этого не противоречит сам себе.

## 5. Пары слоёв и темы без базы

Отложено сознательно, но список стоит держать перед глазами:

- `SLOG` объявляет `extends: arch/time.md` — расширение **чужой** темы.
  Сборщик темы `logging` на это наткнётся: базового слоя с темой `logging`
  нет, а `arch/time.md` он тянуть не должен. Чинится переводом в обычную
  ссылку «связано».
- Темы без арх-слоя: `db-schema`, `errors`, `web-ui`. Собираются в файл с
  одной секцией — само по себе не ломается, но это и есть тот невыделенный
  арх-слой из известного долга.
- Имена тем в паре не совпадают: `arch/db-identifiers.md` против
  `lang/go/db-schema.md`. При сборке по имени темы это две разные темы —
  проверить, что так и задумано.
- В `lang/go/db-schema.md` сидит целый пласт `stack/sqlite/` (типы колонок),
  тоже из известного долга README.

## 6. Подключение к репозиториям

Ничего ещё не подключено. Кандидаты — jellybit и pet-project-server.
Понадобится: заполнить локальные секции тем, что сейчас в этих репозиториях
записано по факту; обёртка в раннере (`inv conventions` / `task conventions`,
единый интерфейс команд у трёх ansible-репозиториев); строка в `AGENTS.md`
каждого потребителя про то, что файлы в `docs/conventions/` — копии.

Открытый кусок с прошлого раза: **как копия ссылается на канон, не ломая
самодостаточность**. Абсолютный путь `~/projects/private/dev-conventions`
в закоммиченном файле не годится — репозиторий перестаёт быть
самодостаточным и получает хардкод путей. Пересекается с вопросом 1.

## 7. Не переизобретено ли это

Проверить перед тем, как вкладываться в тулинг. Ближайшие кандидаты, куда
смотреть:

- **copier / cruft** — шаблон проекта с последующим `update`: ровно та же
  задача «стянуть обновление апстрима, не затерев локальные правки», с
  ответом через три-way merge вместо наших регионов. Стоит понять, почему у
  них merge, а у нас исключение из сравнения.
- **vendir** — вендоринг чужого содержимого с лок-файлом; ближе к нашей
  модели «канон это лавка».
- **Vale** — линтер прозы с правилами в файлах: значительная часть проверок
  целостности канона (модальные слова вне правил, запрещённые формулировки)
  выражается его языком.
- **RFC 2119 / 8174** — канонический источник модальных слов; наш словарь
  фактически его перевод, полезно сверить границы значений.
- **EARS** — шаблоны требований (ubiquitous / event-driven / state-driven);
  соседняя формализация того же, что мы решили таблицами.
- **Наборы правил для агентов** — `AGENTS.md`, cursor rules, скиллы: задачу
  «раздать читаемые агентом договорённости по репозиториям» сейчас решают
  несколько продуктов, и там уже могли устояться форматы.

## 8. Мультиязычность ключевых слов

Модальные слова сейчас русские, и это осознанно: разный словарь держит
границу «конвенция — не спецификация» бесплатно. Вопрос — нужен ли
английский набор параллельно.

За: канон может однажды понадобиться на английском; агенты натренированы на
MUST/SHOULD плотнее, чем на ДОЛЖЕН/СЛЕДУЕТ. Против: два набора — это два
способа записать одно, и проверка «модальные слова не встречаются вне
правил» усложняется вдвое.

Если делать, то таблица ключевых слов должна принадлежать **описанию
языка**, а не каждой конвенции — то есть вопрос завязан на следующий.

## 9. Описание языка отдельно от набора конвенций

`LANGUAGE.md` и `GUIDE.md` описывают, **как** пишутся конвенции;
`conventions/` — **один конкретный** набор. Сейчас они склеены в одном
репозитории, и из одного описания нельзя собрать второй набор (рабочий,
доменный, чужой).

Что это даёт, если разнести:

- канон объявляет, какой версии языка следует, а тулинг валидирует набор
  **против объявленного описания**, а не против зашитых в код правил;
- таблица модальных слов (вопрос 8) живёт в описании и одна на все наборы;
- вопрос 1 (`LANGUAGE.md` не переживает сборку) меняет форму: собранный файл
  ссылается не на путь, а на язык с версией.

Цена — ещё одна сущность и ещё одна синхронизация. Проверить, не выйдет ли
лечение хуже болезни при одном пользователе.

## 10. Тулинг на Go, живущий независимо

Сейчас `conv` — питоновский скрипт внутри канона, то есть тулинг и данные в
одном репозитории и правятся одним движением. Мысль: вынести в отдельный
Go-бинарь со своим релизным циклом, ставить через `eget` (механизм уже есть
в pet-project-server).

Что за этим стоит помимо вкуса: независимый бинарь физически не даёт править
инструмент «заодно» с правкой конвенции, работает против **любого** канона и
любого потребителя — что прямо требуется вопросом 9, — и снимает питон из
зависимостей репозиториев-потребителей.

Связано с вопросом 2: если тулинг всё равно переписывается, разделение
«целостность канона / установка в проект» дешевле заложить сразу, чем
отпиливать потом.

## 11. Ссылки на родительский слой своей темы

Из `lang/` и `stack/` ссылаться на идентификаторы своего же арх-слоя
безопасно: при сборке они оказываются секциями одного файла, и ссылка
никуда не ведёт — правило рядом. Ограничение META-20 писалось именно про
**чужую тему**, так что формально это уже разрешено.

Но стоит проговорить явно, потому что сейчас читается уже как запрет:

- в `LANGUAGE.md` проверка сформулирована как «**чужой префикс** не
  встречается в абзаце с модальностью» — по букве это ловит и `GTIM` →
  `TIME-3`, то есть ложно срабатывает на ровно том случае, который
  разрешён. Должно быть «префикс **чужой темы**»;
- обсудить, не добавить ли в META-20 явную строку **ДОПУСКАЕТСЯ** про
  родительский слой: правило, которое читают как более строгое, чем оно
  есть, заставляет авторов дублировать текст без нужды.

## Из вчерашнего, не закрыто

- Вынос арх-ядра из `errors` и `logging`: закроет две хрупкие ссылки из
  `web-ui` (стек) в go-слой — единственные ссылки стек → язык в каноне.
- `conv check` должен уметь отличать ссылку на удалённое правило от
  упоминания дыры: сейчас `META-16` в прозе «Оформления» даёт ложное
  срабатывание.