diff --git a/DECISIONS.md b/DECISIONS.md index 40820a2..e0f0fb9 100644 --- a/DECISIONS.md +++ b/DECISIONS.md @@ -1080,3 +1080,75 @@ HTML-комментарии, невидимые в отрендеренном ma проверок репозитория: **ошибка в блоке не видна при чтении** — текст правдоподобен, дифф разумен, падает только рендер. Расхождение с прозой скрипт не ловит и не притворяется, что ловит: это работа правила 63. + +## 16. Каталог вместо файла в `docs/` — отложено до переезда healthlog (2026-08-04) + +### Что было + +Вопрос: разрешить документам в корне `docs/` быть не только файлом, но и +каталогом — когда документ описывает несколько принципиальных решений или +перерастает 400–500 строк. Паспорт остаётся файлом в любом случае: компактность +и есть его функция. + +Механизм в каноне уже работает — `conventions/`, `research/`, `adr/` каталоги с +обязательным `README.md`-индексом, — так что вопрос не «можно ли», а «от чего +лечим». + +### Решено + +**CCC. Порог в строках триггером не становится.** Замер по проектам: у порога +ровно один документ — `healthlog/docs/architecture.md`, 1662 строки. В нём +десять маркеров долга, а разделы — «Слои гранулярности» (211 строк), «Тренировки +и прочие секции» (222), «Условный запрос», «Свёртка и размер ответа», «Форма +ответа». Это **поведение**, чей нормативный дом `openspec/specs/`, где у проекта +уже лежат пять capability. Остальные документы 108–438 строк, `jellybit` — 169. +Порог сработал бы ровно там, где надо не разносить, а доводить переезд, и дал бы +долгу постоянное жильё: разложить 1662 строки по файлам дешевле, чем вынести их +в спеки, а после раскладки давление исчезнет и второй дом поведения останется +навсегда. + +**DDD. Шов выноса — другой читатель или другой срок жизни, а не размер.** По +этому критерию кандидатов два. `review.md` — сильнее прочих: у него уже записаны +два раздела с разными сроками жизни, настройка конвейера стабильна и читается +проходами, а журнал дефектов растёт неограниченно. `architecture.md` — по шву +«окружение, деплой, наблюдатель», у которого отдельный читатель `ops`. А вот +расщепление архитектуры **по принципиальным решениям отвергнуто**: у факта +«почему решено так» дом `adr/`, и вынесенные разделы немедленно станут его +вторым домом. + +**EEE. `security.md` и `passport.md` каталогом не становятся.** У `security.md` +ценность именно в цельности: периметр первой строкой и «что вне модели» читаются +враждебным проходом за один раз, а разнесённые — расходятся первыми. У +`database.md` механизм заводить не под что: 241 и 211 строк. + +**FFF. Если вводить — точка входа остаётся одна.** `docs/architecture.md` +упомянут в репозитории 66 раз: девять charter'ов, карта `project-facts.md`, +`docs.py`, скелеты. Развилка «файл или каталог» размножится на девять «прочитай +либо обойди». Поэтому форма жёсткая: каталог легален только при +`<имя>/README.md`, и он **и есть** прежний документ — обзор целиком со ссылками +на вынесенное, а не оглавление к нему. Каждый файл каталога обязан быть достижим +ссылкой из `README.md`; это проверяется сегодняшним механизмом ссылок `docs.py` +и ловит файл-сироту. Вынеся раздел, `README.md` на него **ссылается, а не +пересказывает** — тот же приём, которым в архитектуре уже описаны компоненты со +ссылкой на capability. + +**GGG. Решение отложено до конца переезда `healthlog` (шаг 2 TODO).** Порядок: +довести поведение в спеки, замерить остаток. Жмёт после этого — вводить каноном +версии 3, и сразу для `review.md` и `architecture.md`, а не для всех документов +корня скопом. + +### Что из этого следует + +65. **Цена изменения — версия канона, а не правка одного файла.** Обратной + совместимости у канона нет, поэтому в счёт входят: `docs.py` (`check_stray` с + его `ALLOWED_FILES`/`ALLOWED_DIRS`, `check_required` — обязательный путь + становится развилкой, `check_capabilities` — сегодня читает ровно один файл), + `skeletons.md`, `project-facts.md`, девять charter'ов, запись в + `changelog.md` канона и ветка `upgrade` в скилле `canon`. +66. **Раздутый документ канона — сначала подозреваемый, потом кандидат на + вынос.** Диагностика перед раскладкой — счёт маркеров долга + (`grep -c "