D
Datarim
EN RU
Команда Maintenance

/dr-doctor

Миграция оперативных файлов на тонкую индексную схему

Обзор

/dr-doctor мигрирует устаревшие оперативные файлы Datarim на тонкую индексную схему. Описания задач выносятся из tasks.md, backlog.md и activeContext.md в отдельные файлы datarim/tasks/{TASK-ID}-task-description.md, а оперативные файлы остаются короткими списками указателей-однострочников.

Команда также упраздняет устаревшие progress.md и backlog-archive.md (оба отменены в серии v1.19). Отменённые задачи отправляются в documentation/archive/cancelled/; завершённые — в documentation/archive/{area}/.

Использование

# Dry-run (по умолчанию) — только отчёт о находках
/dr-doctor

# Применить миграцию
/dr-doctor --fix

# Применить миграцию в non-interactive окружении (CI / AI-сессия)
# — конфликты автоматически abort, без prompt
/dr-doctor --fix --no-prompt

# Quiet probe (только exit-код — для скриптов и self-heal контекста)
/dr-doctor --quiet

Что делает

  1. Проверяет datarim/ на несоответствующие записи (legacy ### TASK-ID: блоки, bold-id - **TASK-ID** ... строки, неканонические bullets, остаточный backlog-archive.md, остаточный progress.md).
  2. Выводит таблицу количества находок по категориям.
  3. При --fix выполняет 6-проходную миграцию:
    • Pass 1 — кэш описаний (вынос тел задач в отдельные description-файлы).
    • Pass 2 — перезапись оперативных файлов (tasks.md, backlog.md → thin one-liner index).
    • Pass 3 — мигратор rich-block activeContext.md (legacy paragraph form → строгое зеркало tasks.md § Active).
    • Pass 4 — миграция backlog-archive.md. Split по ## Cancelled / ## Completed; для каждой записи: cancelled → синтез documentation/archive/cancelled/archive-{ID}.md; completed → проверка existing documentation/archive/{area}/archive-{ID}.md или синтез в general/. Conflict resolution интерактивен по умолчанию; --no-prompt автоматически abort'ит конфликты (для CI / non-TTY).
    • Pass 5 — post-fix re-scan. Полный dry-run на мигрированном дереве должен выдать ноль находок; per-ID assertion проверяет, что каждый task ID из pre-fix backlog-archive.md.pre-v2.bak представлен в documentation/archive/. Несоответствие триггерит автоматический restore из pre-write tarball backup.
    • Pass 6 (TUNE-0085 v1.21.5, hardened TUNE-0088 v1.21.6) — миграция архивных секций оперативных файлов. Убирает ## Archived из tasks.md/backlog.md и ### Archived / ### Recently Archived / ## Последние завершённые из activeContext.md — секции, нарушающие канонический thin-index контракт («one section only», v1.19.1). Четыре формы bullet'ов auto-detected (S1 arrow-link, S2 status-paren, S4 mid-bold-context, S3 plain-bold); compound task IDs поддержаны (например DEV-1212-S8). Явный pointer → documentation/archive/{path}.md имеет приоритет над mapping prefix_to_area. Per bullet: verify canonical с {ID} literal → strip; отсутствует → defensive find по area subdirs (depth ≤ 3); если не найден, synthesise stub; collision → respect --conflict-policy. Headerless fallback: операционные файлы без archive-заголовка обрабатываются построчно; bullets с non-terminal статусом (in_progress, not_started, …) проходят как active content.
  4. Генерирует description-файлы с замкнутой 12-ключевой YAML-схемой (id, title, status, priority, complexity, type, project, started, parent, related, prd, plan).
  5. Идемпотентна — повторный запуск на compliant-дереве это no-op (exit 0).

Контракт безопасности данных

Каждый вызов --fix создаёт tarball-бэкап ${DATARIM_DOCTOR_BACKUP_DIR:-/tmp}/datarim-backup-{TS}.tgz (mode 0600) до любой записи. Строка summary при успехе печатает путь к бэкапу. Pass 4 дополнительно пишет per-file sidecar backlog-archive.md.pre-v2.bak, сохраняемый после миграции. Post-fix инвариант emitted_count >= parsed_count защищает от тихой потери данных; при нарушении doctor восстанавливает tarball и выходит с кодом 2.

Коды возврата

  • 0 — Compliant (или --fix успешен)
  • 1 — Несоответствующие находки (dry-run)
  • 2 — Ошибка миграции (--fix прерван; состояние сохранено благодаря атомарному переименованию файлов)
  • 3 — Параллельный запуск (lock занят)
  • 4 — Path traversal / нарушение безопасности в оперативных файлах
  • 64 — Ошибка использования

Интеграция Self-Heal

/dr-init Step 2.4 запускает datarim-doctor.sh --quiet при каждой инициализации, если datarim/ уже существует. На exit 1 с TTY выводит prompt «Run /dr-doctor --fix? [Y/n]» (default Y). Non-tty сессии печатают warning и продолжают.

pre-archive-check.sh проверяет каждую bullet-строку в tasks.md / backlog.md против канонического regex перед тем, как /dr-archive сможет продолжить. Обход: --no-schema-check только для in-flight миграции.

Схема

Канонический regex (single-line, anchored):

^- ([A-Z]{2,10}-[0-9]{4}) · (status) · P[0-3] · L[1-4] · (.{1,80}) → tasks/\1-task-description\.md$

Наборы статусов: tasks.md использует in_progress|blocked|not_started; backlog.md использует pending|blocked-pending|cancelled.

Позиция в пайплайне

Maintenance-команда, запускается по требованию или auto-suggested через /dr-init при non-compliant структуре.

Связанные

← Все возможности