# 16. Каталог вместо файла в `docs/` — отложено до переезда healthlog (2026-08-04) ## Что было Вопрос: разрешить документам в корне `docs/` быть не только файлом, но и каталогом — когда документ описывает несколько принципиальных решений или перерастает 400–500 строк. Паспорт остаётся файлом в любом случае: компактность и есть его функция. Механизм в каноне уже работает — `conventions/`, `research/`, `adr/` каталоги с обязательным `README.md`-индексом, — так что вопрос не «можно ли», а «от чего лечим». ## Решено **Р55. Порог в строках триггером не становится.** Замер по проектам: у порога ровно один документ — `healthlog/docs/architecture.md`, 1662 строки. В нём десять маркеров долга, а разделы — «Слои гранулярности» (211 строк), «Тренировки и прочие секции» (222), «Условный запрос», «Свёртка и размер ответа», «Форма ответа». Это **поведение**, чей нормативный дом `openspec/specs/`, где у проекта уже лежат пять capability. Остальные документы 108–438 строк, `jellybit` — 169. Порог сработал бы ровно там, где надо не разносить, а доводить переезд, и дал бы долгу постоянное жильё: разложить 1662 строки по файлам дешевле, чем вынести их в спеки, а после раскладки давление исчезнет и второй дом поведения останется навсегда. **Р56. Шов выноса — другой читатель или другой срок жизни, а не размер.** По этому критерию кандидатов два. `review.md` — сильнее прочих: у него уже записаны два раздела с разными сроками жизни, настройка конвейера стабильна и читается проходами, а журнал дефектов растёт неограниченно. `architecture.md` — по шву «окружение, деплой, наблюдатель», у которого отдельный читатель `ops`. А вот расщепление архитектуры **по принципиальным решениям отвергнуто**: у факта «почему решено так» дом `adr/`, и вынесенные разделы немедленно станут его вторым домом. **Р57. `security.md` и `passport.md` каталогом не становятся.** У `security.md` ценность именно в цельности: периметр первой строкой и «что вне модели» читаются враждебным проходом за один раз, а разнесённые — расходятся первыми. У `database.md` механизм заводить не под что: 241 и 211 строк. **Р58. Если вводить — точка входа остаётся одна.** `docs/architecture.md` упомянут в репозитории 66 раз: девять charter'ов, карта `project-facts.md`, `docs.py`, скелеты. Развилка «файл или каталог» размножится на девять «прочитай либо обойди». Поэтому форма жёсткая: каталог легален только при `<имя>/README.md`, и он **и есть** прежний документ — обзор целиком со ссылками на вынесенное, а не оглавление к нему. Каждый файл каталога обязан быть достижим ссылкой из `README.md`; это проверяется сегодняшним механизмом ссылок `docs.py` и ловит файл-сироту. Вынеся раздел, `README.md` на него **ссылается, а не пересказывает** — тот же приём, которым в архитектуре уже описаны компоненты со ссылкой на capability. **Р59. Решение отложено до конца переезда `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 "