Команда /dr-doctor — структурная диагностика файлов Datarim
Как /dr-doctor диагностирует и восстанавливает операционные файлы Datarim: миграция устаревших блочных задач в однострочную схему, вынос описаний и удаление устаревшего progress.md.
Операционные файлы Datarim имеют каноническую структуру. Когда задачи накапливаются месяцами, структура дрейфует: блочные заголовки смешиваются с однострочными записями, описания занимают место внутри tasks.md, а устаревший progress.md остаётся от предыдущей версии схемы. /dr-doctor исправляет всё это.
Команда идемпотентна. Запуск на полностью соответствующем проекте не производит никаких изменений. Запуск на устаревшем дереве мигрирует каждый несоответствующий файл, а затем проверяет результат — второй проход всегда возвращает нулевые находки.
Когда запускать
Три ситуации требуют /dr-doctor. Самая частая — ручной запуск: tasks.md или backlog.md разросся или содержит записи в смешанных форматах. Вторая — автоматическая: шаг 0.6 /dr-init запускает проверку соответствия структуры и перенаправляет сюда при ненулевом коде возврата. Третья — после обновления до Datarim v1.19.0 и выше: первый запуск выполняет миграцию схемы.
Проверка перед архивированием в /dr-archive также проверяет соответствие, поэтому незачищенное дерево остановит закрытие задачи до прохождения этой команды.
Сначала проверка, затем применение
По умолчанию — режим проверки без изменений. Команда выводит таблицу из четырёх строк: устаревшие блочные заголовки, устаревшие записи с жирным ID, несоответствующие строки-буллеты и наличие progress.md. Если все счётчики равны нулю — команда завершается молча. При наличии находок — запрашивает подтверждение перед любыми изменениями.
Флаг --fix применяет миграцию. Внутри scripts/datarim-doctor.sh захватывает блокировку файла, записывает атомарно по одному файлу и прерывается с сохранением состояния при любой ошибке. После миграции второй сухой прогон подтверждает нулевые находки.
Что меняется на диске
Каждая устаревшая блочная запись задачи в tasks.md или backlog.md превращается в одну строку. Текст, который был внутри блока, переходит в новый файл: datarim/tasks/{TASK-ID}-task-description.md с YAML-шапкой и секциями тела. Если существует progress.md — последние завершённые записи переносятся в activeContext.md, сам файл удаляется. Ничто за пределами datarim/ не затрагивается.
После миграции в режиме рекомендации запускается проверка наличия init-задач — выводится список задач без связанного init-task-файла, отсортированный по возрасту, но никогда не блокирующий саму миграцию.
Коды возврата и восстановление
Код 0 означает соответствие или успешную миграцию. Код 1 — наличие находок в режиме проверки. Код 2 — миграция прервана, состояние сохранено, отдельные файлы можно откатить через git restore. Код 3 — блокировка захвачена параллельным запуском, нужно подождать и повторить. Код 4 — сработала защита от path-traversal, нужно проверить проблемную запись вручную.
Общая картина фреймворка — в посте что такое Datarim. О том, как компоненты фреймворка остаются в порядке, рассказывает /dr-optimize.