Единый корень документации: docs/ становится documentation/ в 2.49.0

Datarim 2.49.0 делает одно структурное изменение — и проводит его последовательно везде: корень документации переименован из docs/ в documentation/. Это ломающее изменение канона, поэтому стоит объяснить, почему переименование папки заслужило bump минорной версии и правило жёсткого перехода.

Проблема: две папки, два смысла, отложенное столкновение

У проекта Datarim фактически было две поверхности документации, которые жили под разными именами и никогда не сводились вместе:

• docs/ — собственная продуктовая документация фреймворка: getting-started, справочник команд и скилов, разъяснительные материалы.
• documentation/ — база знаний потребителя: архив задач, мандаты, инфраструктурные заметки — закоммиченная история проекта, который использует Datarim.

Два корня, два контракта, нет общего словаря. Каждый новый проект должен был усвоить, что «docs» означает одно внутри фреймворка, а его собственная долгосрочная документация уходит совсем в другое место. Drift-детектор видел, что у проекта есть папка docs/, но не имел мнения о её отношении к documentation/. Этот раскол был маленьким налогом, который платил каждый репозиторий — постоянно.

Решение: переименовать и слить под одним корнем

Вместо двух имён 2.49.0 делает documentation/ единым каноническим корнем документации для всей экосистемы. Продуктовые документы фреймворка переезжают внутрь него, разложенные по четырём категориям Diátaxis:

• documentation/tutorials/ — обучающие пошаговые материалы (getting-started, use-cases)
• documentation/how-to/ — рецепты под задачу (процесс релиза, верификация, журнал эволюции)
• documentation/reference/ — справочники (команды, скилы, CLI, контракт валидатора)
• documentation/explanation/ — фоновые разъяснения (pipeline, consilium, spec-traceability)

Существующая база знаний потребителя не двигается — её архив задач остаётся в documentation/archive/. Переименованные продуктовые документы просто становятся соседями рядом с ним. Чтобы два контракта снова не столкнулись, теперь зарезервированы четыре имени: категорией Diátaxis нельзя назвать archive, evolution, release-audit или ephemeral. Один корень, чёткое разделение, без пересечений.

История git сохраняется целиком — каждый файл переезжает через git mv, так что git log --follow по-прежнему видит коммиты до переименования.

Жёсткий переход — но никогда упрёк без решения

Стратегия совместимости — чистый разрыв: drift-детектор теперь считает репозиторий, всё ещё сидящий на старом docs/, дрейфом. Жёсткий переход честен только тогда, когда то, что он помечает, реально можно починить — помечать проблему без пути починки значит просто ворчать. Поэтому 2.49.0 приносит лекарство в том же релизе.

/dr-doctor получает opt-in проход самопочинки для миграции документации. Наведите его на репозиторий потребителя, всё ещё на docs/ — и он выполнит ту же миграцию, что фреймворк сделал сам себе:

• Определит раскладку — старый docs/, частично мигрированное состояние или уже мигрированный репозиторий (тогда это чистый no-op).
• Мигрирует через git mv + раскладку Diátaxis (известные файлы попадают в свою категорию; неизвестные — в how-to/ с пометкой на ревью) + якорную перезапись ссылок.
• Проверит результат линтером ссылок — и если хоть одна проверка падает, откатит к точному дореформенному дереву из бэкап-тарбола.

Он идемпотентен (запустите дважды — второй запуск ничего не делает) и безопасен при откате (упавшая проверка никогда не оставит вас наполовину мигрированным). Намеренно это отдельный сосед-инструмент, а не новый режим, прикрученный к доктору операционных файлов — продуктовые документы физически лежат вне служебного каталога состояния фреймворка, и смешение миграции контента с миграцией схемы размыло бы границу, которую фреймворк держит сознательно.

Как мигрировать ваш репозиторий

Если ваш проект всё ещё использует docs/, обновление — это одна opt-in команда:

• Запустите /dr-doctor; он сообщит о старом docs/ как о доступной миграции.
• Примите миграцию; доктор перенесёт документы в documentation/ с раскладкой Diátaxis и перепишет ссылки.
• Если проверка после миграции падает, дерево восстанавливается автоматически — ничего не остаётся наполовину сделанным.

Новые проекты, развёрнутые через /dr-init, уже стартуют с documentation/. Там делать нечего.

Почему это важно

Изменение маленькое в диффе и большое в ясности. Единый корень документации означает, что есть ровно один ответ на вопрос «куда положить этот документ?» — продуктовые документы по категории Diátaxis, история проекта под archive/, и то и другое под documentation/. Drift-детектор, скаффолд, мандаты и доктор теперь указывают в одно и то же место. Полную запись смотрите в changelog.