черновик «К обсуждению» закоммичен

- одиннадцать открытых вопросов по сборке, тулингу и разделению языка и
  набора конвенций: в переписке они теряются, а часть уже противоречит
  README, и это противоречие видно только рядом с текстом
- снята строка «Не коммитится» и поправлено то же утверждение в CLAUDE.md

.claude/settings.json

@@ -0,0 +1,5 @@
+{
+  "enabledPlugins": {
+    "av-dev-git@av-dev-skills": true
+  }
+}

CLAUDE.md

@@ -0,0 +1,119 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with
+code in this repository.
+
+Всё содержимое репозитория и общение по нему — на русском.
+
+## Что это
+
+Канон конвенций разработки для личных проектов. Сами конвенции лежат в
+`conventions/{arch,lang/<язык>,stack/<стек>}/`; обвязка канона (`README.md`,
+`LANGUAGE.md`, `GUIDE.md`, `prefixes.toml`, `conv`) живёт в корне и в
+репозитории-потребители не едет.
+
+Ниже — короткие инварианты с идентификаторами; детали и обоснования в
+`LANGUAGE.md` (форма записи) и `GUIDE.md` (процесс, префикс META).
+
+## Форма правила
+
+- Четыре обязательные части: `### <ПРЕФИКС>-<N>. Заголовок`, абзац
+  `**МОДАЛЬНОСТЬ.** норма`, абзац `**Почему.** …`. Правило без «Почему» не
+  принимается.
+- Норма — одна фраза; если в неё не влезает, это два правила.
+- Модальные слова: **ДОЛЖЕН**, **НЕ ДОЛЖЕН**, **СЛЕДУЕТ**, **НЕ СЛЕДУЕТ**,
+  **ДОПУСКАЕТСЯ**, плюс не-модальная отметка **МЕХАНИЗИРОВАНО**. Английские
+  ключевые слова (SHALL, MUST) не используются — они заняты OpenSpec.
+- Модальные слова не употребляются вне правил: ни в «Область действия», ни в
+  «Связано», ни в локальных регионах, ни во вводной прозе.
+- «Почему» отвечает на «что сломается, если сделать иначе», а не
+  пересказывает норму. «Потому что так принято» — не обоснование.
+- Правило, классифицирующее ситуации, пишется таблицей «ситуация → вердикт»;
+  строки нумеруются `KEYS-5.1`.
+- Модальность принадлежит правилу, а не файлу: `status:` в шапке отменён.
+
+## Идентификаторы и префиксы
+
+- Формат `<ПРЕФИКС>-<номер>`, нумерация сквозная внутри файла. Порядок правил
+  в файле — по читаемости: номер это идентификатор, а не позиция.
+- Идентификаторы не переиспользуются. Удалённое правило оставляет дыру, новое
+  берёт следующий свободный номер, а не первый освободившийся.
+- Новый файл конвенции — новый префикс: четыре заглавные латинские буквы,
+  уникальные по всему канону, выбираются под файл, а не выводятся по формуле.
+  Объявляется в шапке (`prefix: KEYS`) и регистрируется в `prefixes.toml`,
+  секция `[live]`, путём от корня репозитория.
+- Удаление или разделение файла: префикс уходит в `[retired]` с причиной и
+  датой, а не освобождается.
+- Перенос правила в другой файл — смысловое изменение: новый префикс и новый
+  номер. Переезд самого файла между осями идентификаторы не трогает.
+
+## Ссылки
+
+- META-20: норму можно исполнить, имея один этот файл. Ссылка на правило
+  чужой темы допустима в «Почему», в «Связано» и в разграничении области
+  действия — но не в самой норме. Нужен концепт соседней темы — коротко
+  повторить его здесь, соседа назвать в «Почему».
+- META-21: на соседнюю конвенцию ссылаются именем темы (конвенция
+  `logging`), на правило — идентификатором (`SLOG-27`), на другой слой своей
+  темы — словами «базовый слой». Пути файлов канона в тексте конвенции нет
+  (в обвязке — можно).
+
+## Что в каноне писать нельзя
+
+- META-4: в тексте конвенции нет утверждений о состоянии конкретного
+  репозитория; норма — в настоящем предписывающем времени.
+- META-5: расхождение кода с правилом — отступление, а не повод переписать
+  правило. Направление всегда конвенция → код; факт «в приложении уже иначе»
+  не является аргументом.
+- META-6: ДОЛЖЕН без механической проверки либо механизируется, либо
+  понижается в СЛЕДУЕТ. Правило, непроверяемое машиной в принципе (вкус
+  формулировки, суждение о ситуации), — СЛЕДУЕТ по построению.
+- META-10: блок «Почему» не удаляется никогда, в том числе после того, как
+  норма уехала в линтер.
+- META-1: один файл — ровно один повторяющийся выбор. META-2: конвенция
+  заводится, когда решение принимается третий раз.
+- Локальные регионы `<!-- local:имя --> … <!-- /local -->` в каноне остаются
+  пустыми: их содержимое принадлежит репозиторию-потребителю. Имя региона и
+  путь файла — API, переименование осиротит все копии.
+
+## Выбор оси
+
+Умирает при смене языка → `lang/<язык>/`. Умирает при смене инструмента,
+хранилища или транспорта → `stack/<стек>/`. Не умирает ни от того, ни от
+другого → `arch/`. Ось определяется природой правила, а не числом сегодняшних
+потребителей. `extends: arch/<файл>.md` в шапке — документация связи, а не
+механизм; слой только реализует и сужает базу, но не отменяет её.
+
+## Оформление файла
+
+Шапка `prefix:` (плюс `extends:`) → `# Тема` → вводная проза со строкой
+«Форма записи — `LANGUAGE.md`» → `## Область действия` (обязателен для
+трудноизменяемых слоёв — META-11) → правила → `## Связано` с пустым
+`<!-- local:связано -->`. Имя файла — kebab-case по теме. Проза переносится
+по ~76 колонок; таблицы и блоки кода не переносятся.
+
+## Ревью формы
+
+Список того, что подлежит проверке, — в `LANGUAGE.md`, раздел «Что стоит
+проверять машиной». Ни одна из проверок не реализована, поэтому при ревью их
+выполняют чтением.
+
+## Коммиты
+
+Русский, строчная буква, без точки в конце, прошедшее время или страдательный
+залог: «заведён реестр префиксов, правила канона перенумерованы». Изредка
+область через двоеточие (`guide:`, `errors:`). Тело — маркированный список на
+2–3 пункта с переносом по ~76 колонок; объясняет почему и цитирует
+идентификаторы правил. Conventional Commits не используются.
+
+## Состояние репозитория
+
+- Тестов, линтеров и CI нет. `conv` — python3 CLI на одной stdlib; запускают
+  его из корня репозитория-потребителя (`~/projects/private/dev-conventions/`
+  плюс `conv status`). `status` и `diff` всегда возвращают 0 — это отчёт, а не
+  проверка.
+- Ни один репозиторий-потребитель ещё не подключён: копий с шапкой `origin:`
+  в природе нет, все локальные регионы канона пусты.
+- `TODO.md` — площадка для обсуждения на будущее, а не принятые решения; при
+  работе над обвязкой его стоит прочесть, но истина о текущем устройстве —
+  `README.md`.

TODO.md

@@ -0,0 +1,240 @@
+# К обсуждению
+
+Черновик для следующего разговора: вопросы и варианты, а не принятые
+решения.
+
+## 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` в прозе «Оформления» даёт ложное
+  срабатывание.

conventions/arch/time.md

@@ -89,7 +89,7 @@ prefix: TIME
 меток без исключения, а каждый прямой вызов часов заводит ещё одно место,
 где их можно не соблюсти. Промах такого вызова проявляется не в коде, а в
 данных, и обнаруживается, когда испорченных записей уже накопилось.
-Соображение то же, что для идентификаторов (`arch/db-identifiers.md TIME-3`).
+Соображение то же, что для идентификаторов (KEYS-3).
 
 ### TIME-6. Дефолтов времени в схеме БД нет
 
@@ -100,7 +100,7 @@ prefix: TIME
 и в формате, который выбирала не единая точка (TIME-5). Без дефолта та же ошибка
 падает громко и чинится в момент написания, а не при разборе расхождения
 между временем в записи и временем в логе. Правило то же, что для
-идентификаторов (`arch/db-identifiers.md TIME-2`).
+идентификаторов (KEYS-2).
 
 ### TIME-7. Длительность — отдельная величина, а не пара меток