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

- LANGUAGE.md: раздел «Идентификаторы» переписан под префиксы, в список
  машинных проверок добавлена сверка с реестром
- GUIDE.md перенумерован под префикс META, «номер правила» заменён на
  «идентификатор»
This commit is contained in:
av
2026-07-25 20:55:38 +03:00
parent dcdd92230b
commit 4a7cfca8f6
3 changed files with 96 additions and 60 deletions
+37 -21
View File
@@ -12,8 +12,8 @@
Не ради строгости. Три конкретные вещи, которые без адресуемых правил не
работают:
- **Механизация.** Регион `механизировано` должен говорить «правило R4
проверяет `archrules`», а не «`AUTOINCREMENT` в новых миграциях —
- **Механизация.** Регион `механизировано` должен говорить «правило
`MIGR-4` проверяет `archrules`», а не «`AUTOINCREMENT` в новых миграциях —
`archrules`»: во втором случае читатель сам догадывается, к какому
утверждению это относится, и догадывается по-разному.
- **Отступления.** «У нас не так» бесполезно, пока не сказано, что именно
@@ -28,7 +28,7 @@
## Единица — правило
```markdown
### R5. Разбор внешнего идентификатора на границе
### KEYS-5. Разбор внешнего идентификатора на границе
**ДОЛЖЕН.** Идентификатор, пришедший снаружи, проходит разбор до запроса
к базе.
@@ -38,8 +38,8 @@
существующую запись — отладка такого случая стоит дороже, чем сам разбор.
```
Четыре обязательные части: **номер**, **заголовок**, **модальность с
нормой**, **почему**. Норма — одна фраза; если в неё не влезает, это два
Четыре обязательные части: **идентификатор**, **заголовок**, **модальность
с нормой**, **почему**. Норма — одна фраза; если в неё не влезает, это два
правила.
## Правило без «почему» не принимается
@@ -79,7 +79,7 @@
Модальность живёт на **правиле**, а не на файле. Прежний файловый статус
(`status: рекомендуемая` / `обязательная` в шапке) отменён: он неизбежно
врал, потому что один файл смешивает жёсткие требования с советами. В шапке
остаются только `extends` и служебные ключи копии.
остаются только `prefix`, `extends` и служебные ключи копии.
Мы **не используем SHALL и прочие английские ключевые слова**. Они заняты
спецификациями (OpenSpec), и общий словарь стирал бы границу «конвенция —
@@ -87,13 +87,26 @@
## Идентификаторы
- Формат — `R<номер>`, сквозная нумерация внутри файла, начиная с `R1`.
- Строка таблицы, если на неё нужно ссылаться отдельно, — `R5.1`, `R5.2`.
- **Номера стабильны и не переиспользуются.** Удалённое правило оставляет
дыру в нумерации; занимать её новым правилом нельзя — иначе ссылка из
чужого репозитория начнёт указывать на другое утверждение.
- Глобальный адрес — путь файла плюс номер: `arch/db-identifiers.md R5`.
В пределах одного файла достаточно `R5`.
- Формат — `<ПРЕФИКС>-<номер>`: `KEYS-5`, `SLOG-27`. Префикс принадлежит
файлу, нумерация внутри файла сквозная и начинается с единицы.
- Строка таблицы, если на неё нужно ссылаться отдельно, — `KEYS-5.1`,
`KEYS-5.2`.
- **Идентификатор глобален.** Префикс уникален по всему канону, поэтому
путь файла в ссылке не нужен: `KEYS-5` адресует правило одинаково изнутри
файла, из соседней конвенции и из чужого репозитория. В собранной копии
слои разных осей лежат в одном документе, так что ссылка на базовый слой
из языкового вообще никуда не ведёт — правило рядом.
- **Идентификаторы стабильны и не переиспользуются.** Удалённое правило
оставляет дыру в нумерации; занимать её новым нельзя — иначе ссылка из
чужого репозитория начнёт указывать на другое утверждение. То же
относится к префиксам: выбывшие хранит `conventions/prefixes.toml`.
- Префикс **выбирается под файл, а не выводится по формуле**: он нужен,
чтобы по нему искать, а не чтобы его разбирать. Выводимый префикс вдобавок
привязал бы идентификатор к таксономии, которую канон перестраивает, и
упёрся бы в потолок из числа букв алфавита.
- Перенос правила в другой файл — смысловое изменение, а не переименование:
новый файл означает новый префикс и новую нумерацию. Переезд самого файла
между осями идентификаторы не трогает.
Порядок правил в файле выбирается по читаемости, не по номерам: номер — это
идентификатор, а не позиция.
@@ -105,7 +118,7 @@
чтобы оно не выглядело недописанным, место нормы занимает отметка:
```markdown
### R6. Дефолтов времени в схеме БД нет
### MIGR-6. Дефолтов времени в схеме БД нет
**МЕХАНИЗИРОВАНО.** Проверяется общим правилом линтера; формулировка
удалена, потому что дублировала работающую проверку.
@@ -113,7 +126,7 @@
**Почему.** Дефолт превращает забытую вставку в тихо работающий код…
```
- Номер и заголовок сохраняются: ссылки из репозиториев продолжают
- Идентификатор и заголовок сохраняются: ссылки из репозиториев продолжают
указывать на то же утверждение.
- «Почему» остаётся навсегда — линтер сообщает, что нарушено, но не
сообщает, зачем правило существует, и без обоснования нельзя понять,
@@ -175,11 +188,11 @@ AND тик фонового цикла упал по той же причине
```markdown
<!-- local:механизировано -->
R2, R4 — `internal/archrules` (проверяются в новых миграциях).
MIGR-2, MIGR-4 — `internal/archrules` (проверяются в новых миграциях).
<!-- /local -->
<!-- local:отступления -->
R6 — не соблюдается в легаси-таблицах `show_history`, `queue`: составные
MIGR-6 — не соблюдается в легаси-таблицах `show_history`, `queue`: составные
ключи там появились до конвенции, переписывание требует миграции данных.
<!-- /local -->
```
@@ -191,12 +204,15 @@ R6 — не соблюдается в легаси-таблицах `show_histor
Сейчас не реализовано; список — на будущее для `conv`:
- префикс в шапке файла совпадает с реестром, состоит из четырёх заглавных
латинских букв и не значится в списке выбывших;
- заголовки правил файла используют только его собственный префикс;
- номера уникальны внутри файла и не имеют пропусков вниз (новое правило
берёт следующий свободный, а не первый освободившийся);
- у каждого `### R<n>` есть модальное слово (или отметка МЕХАНИЗИРОВАНО) и
блок «Почему»;
- ссылки вида `R<n>` в локальных регионах копии указывают на правила,
которые в каноне ещё существуют;
- у каждого `### <ПРЕФИКС>-<n>` есть модальное слово (или отметка
МЕХАНИЗИРОВАНО) и блок «Почему»;
- ссылки вида `<ПРЕФИКС>-<n>` — хоть в тексте канона, хоть в локальных
регионах копии — указывают на правила, которые ещё существуют;
- модальные слова не встречаются вне правил.
## Порядок перевода