след сверки: ключ переехал в секцию docs, конфиг больше не отвергается

Ключ [healthcheck] last, заведённый вчера темой 78, роняли оба скрипта
плагина: верхний уровень .av-dev.toml стережёт TOP_KEYS в shared/config.py,
и неизвестный ключ там — отказ кодом 3. Первый же прогон сверки сделал бы
нерабочими canon check/adopt/upgrade, весь task-track и гейт проекта.

След живёт теперь ключом healthcheck_last в секции [docs] — по смыслу
(настройки проверок документов) и по цене (правка одной константы DOCS_KEYS
в docs.py, общий читатель не тронут). Воспроизведено до и после: docs.py и
tasks.py конфиг с ключом принимают.

Корень был не в описке, а в ложном обещании канона «неизвестный ключ docs.py
игнорирует» — оно старше темы 78, и на него опёрлись, не открыв скрипт.
Обещание снято, на его месте правило: новый ключ заводится правкой константы
скрипта-владельца, и только потом попадает в канон.

Журнал — тема 79.
This commit is contained in:
av
2026-08-23 19:35:17 +03:00
parent a4bc9191e7
commit 8145b378b2
6 changed files with 105 additions and 15 deletions
+24 -7
View File
@@ -555,12 +555,10 @@ version = 1 # версия раскладки
[docs]
migrations = "internal/store/migrations" # если БД есть
healthcheck_last = "a1b2c3d" # сверка документов: коммит прошлого прогона
[tasks]
dir = "tasks" # каталог задач от корня репозитория
[healthcheck]
last = "a1b2c3d" # сверка документов: коммит прошлого прогона
```
`version` — версия раскладки, под которую проект приведён, целым числом:
@@ -571,13 +569,18 @@ last = "a1b2c3d" # сверка документов: ко
делает сверку с `database.md`. `[tasks]` — где лежит каталог задач и как названы
его части; состав ключей описывает скилл `task-track`.
`[healthcheck] last` — коммит, на котором в последний раз проходила сверка
`[docs] healthcheck_last` — коммит, на котором в последний раз проходила сверка
документов; ставит его сам `av-dev:doc-healthcheck` последним шагом прогона, а
читает `av-dev:doc-sync`, чтобы сосчитать задачи, сделанные с тех пор. **Ключ
необязательный и в скелете его нет намеренно**: у нового проекта сверок не было,
и пустое значение врало бы про это меньше, чем отсутствие ключа, только на вид.
Отсутствие читается однозначно — «не сверялись ни разу».
Секции он достался по смыслу: `[docs]` — настройки проверок документов, а сверка
документов и есть такая проверка. Своя секция верхнего уровня стоила бы правки
общего читателя `shared/config.py` и сделала бы файл, объявленный «версией и
настройками», хранилищем состояния.
**Формат TOML взят ради комментариев.** Файл лежит в репозитории проекта, и
человек, открывший его через полгода, обязан прочитать в нём, что означает
число. JSON комментариев не знает, и объяснение приходилось держать в другом
@@ -592,6 +595,20 @@ last = "a1b2c3d" # сверка документов: ко
читаются: два дома для одной версии расходятся молча. Увидев их, `docs.py` и
`tasks.py` говорят «прежняя раскладка» и зовут `upgrade` — версия 1 журнала.
Ключей будет больше по мере роста проверок; неизвестный ключ `docs.py`
игнорирует, отсутствующий — считает «проверка неприменима» и говорит об этом
строкой, а не молчит.
Ключей будет больше по мере роста проверок, но **заводятся они только вместе с
правкой скрипта**: неизвестный ключ — не безмолвный пропуск, а **отказ кодом
3**. Верхний уровень стережёт `shared/config.py` (`TOP_KEYS`), секцию `[docs]`
`docs.py` (`DOCS_KEYS`), секцию `[tasks]``tasks.py`. Довод у отказа
проверяемый: ключ, положенный не в ту секцию, при молчаливом пропуске не значит
ничего — проверка объявляет себя неприменимой, отчёт выходит зелёным, и на месте
настройки оказывается тишина.
**Здесь это правило однажды соврало, и цена была немедленной.** Абзац обещал, что
неизвестный ключ игнорируется; по этому обещанию скилл сверки завёл себе секцию
`[healthcheck]` верхнего уровня — и первый же её прогон сделал бы нерабочими
`docs.py`, `tasks.py` и гейт проекта, который их зовёт. Отсюда и порядок: **новый
ключ заводится правкой константы в скрипте-владельце, и только потом появляется
здесь**.
**Отсутствующий** ключ — другое дело: он значит «проверка неприменима», и скрипт
говорит об этом строкой, а не молчит.