язык: короткое описание для читателя копии едет в репозиторий

- заведён READING.md: словарь со значениями, форма правила и её граница,
  ссылки, локальная часть — без разделов о ведении набора и без META-ссылок,
  примеры на X-префиксах
- сборщик кладёт его в docs/conventions/ и перезаписывает целиком; в манифест
  набора добавлена секция [language] с версией и двумя документами
- META-30: правка словаря или состава частей правила доходит до READING.md,
  иначе потребитель толкует ДОПУСКАЕТСЯ по прежней версии
This commit is contained in:
av
2026-07-26 15:51:54 +03:00
parent 67d51db212
commit 170c06c1da
7 changed files with 205 additions and 39 deletions
+34 -7
View File
@@ -12,13 +12,15 @@
| `README.md` | устройство канона, оси, сборка копий, жизненный цикл |
| [LANGUAGE.md](LANGUAGE.md) | язык записи правил: идентификаторы, модальность, обоснование |
| [GUIDE.md](GUIDE.md) | как ведут конвенции: когда заводить, механизация, отступления |
| [manifest.toml](manifest.toml) | манифест набора: темы и префиксы правил |
| [READING.md](READING.md) | как читать конвенцию: то, что едет к потребителю |
| [manifest.toml](manifest.toml) | манифест набора: язык, темы, префиксы правил |
| `conv` | сборка копий |
Обвязка живёт только в каноне и в репозитории не оказывается — в копию едет
лишь содержимое `conventions/`. Самодостаточность копии это не нарушает:
конвенция называет язык записи одной строкой с номером версии и не ссылается
на путь (`LANGUAGE.md`, раздел «Ссылка на язык из конвенции»).
К потребителю едет содержимое `conventions/` и один файл обвязки —
`READING.md`; остальная обвязка остаётся в каноне. Самодостаточность копии это
не нарушает: конвенция называет язык записи одной
строкой с номером версии и не ссылается на путь (`LANGUAGE.md`, раздел «Ссылка
на язык из конвенции»).
Правило то же, что у ролей: **деплоится и читается только то, что лежит в
git репозитория**. Канон никем не подключается на лету.
@@ -151,6 +153,7 @@ extends: arch/db-identifiers.md
```
docs/conventions/
README.md собственный, не собирается
READING.md как читать конвенцию — приезжает из канона
time.md arch/time.md + lang/go/time.md
db-identifiers.md arch/db-identifiers.md + lang/go/db-identifiers.md
app-directories.md arch/… + stack/ansible/…
@@ -159,6 +162,10 @@ docs/conventions/
Так конвенция остаётся самодостаточным документом: тот, кто проверяет по ней
код — человек или агент, — читает один файл и не собирает тему из трёх мест.
Имена в директории делятся на три вида: `README.md` принадлежит репозиторию и
сборщик его не трогает, `READING.md` принадлежит канону и перезаписывается
целиком, остальные файлы — копии тем с шапкой `origin:` и локальной частью.
**Шапка копии** ставится при сборке и в каноне не хранится:
```yaml
@@ -198,6 +205,24 @@ MIGR-6 не соблюдается в `show_history`, `queue`: составны
репозитория. Файл, оставивший шапку, при следующем обновлении потеряет
всё, что выше маркера.
## Язык записи едет вместе с копиями
Конвенция называет язык одной строкой с номером версии и без пути — строка
работает и сама по себе. Но семантика заглавных слов живёт в описании языка, а
описание в репозиторий-потребитель раньше не попадало: агент, читающий копию,
принимал ДОПУСКАЕТСЯ за бытовое «можно» и терял ровно то, ради чего слово
введено.
Поэтому в `docs/conventions/` сборщик кладёт `READING.md` — короткое описание
для читателя правил: словарь со значениями, правило заглавных, из чего состоит
правило и где его граница, как ссылаться, что живёт ниже маркера. Полное
[LANGUAGE.md](LANGUAGE.md) остаётся в каноне: три его раздела адресованы
автору набора и ссылаются на правила `GUIDE.md`, которых у потребителя нет.
Два документа — один словарь, и это единственное место, где возможен дрейф.
Правка ключевых слов или состава частей правила обязана дойти до `READING.md`
(META-30), а сверить их дёшево: таблицы либо совпадают, либо нет.
## Два манифеста
Манифестов в модели два, и они отвечают на разные вопросы:
@@ -251,6 +276,7 @@ topics = ["time", "config", "db-identifiers"]
conv list # какие темы есть в каноне
conv add time # добавить тему в манифест и собрать файл
conv pull # пересобрать всё, что перечислено в манифесте
# (и обновить READING.md рядом с копиями)
```
Отчёт о том, что изменилось, отдельной командой не выдаётся: после `pull`
@@ -288,6 +314,7 @@ conv pull # пересобрать всё, что переч
Модель выше — согласованная, а не реализованная. `conv` пока собран под
прежнюю: зеркальное дерево копий вместо плоского, именованные регионы
`<!-- local:имя -->` вместо одного маркера, `origin_hash` в шапке и команды
`status`, `diff`, `push`. Сами конвенции уже приведены к новой модели —
именованных регионов в каноне нет. Ни один репозиторий-потребитель не
`status`, `diff`, `push`; `READING.md` рядом с копиями он тоже пока не
кладёт. Сами конвенции уже приведены к новой модели — именованных регионов в
каноне нет. Ни один репозиторий-потребитель не
подключён, поэтому переход никого не ломает.