D
Datarim
EN RU
Command Maintenance

/dr-doctor

Diagnose and migrate operational files to thin-index schema

Overview

/dr-doctor migrates legacy Datarim operational files to the thin-index schema. It externalises task descriptions from tasks.md, backlog.md, and activeContext.md into per-task files at datarim/tasks/{TASK-ID}-task-description.md, leaving the operational files as one-liner pointers.

The command also retires the legacy progress.md and backlog-archive.md files (both abolished in the v1.19 series). Cancelled tasks land in documentation/archive/cancelled/; completed tasks land in documentation/archive/{area}/.

Usage

# Dry-run (default) — report findings, no mutation
/dr-doctor

# Apply migration
/dr-doctor --fix

# Apply migration in non-interactive context (CI / AI session)
# — auto-aborts conflicts instead of prompting
/dr-doctor --fix --no-prompt

# Quiet probe (exit-code only — useful for scripts and self-heal contexts)
/dr-doctor --quiet

What It Does

  1. Probes datarim/ for non-compliant entries (legacy ### TASK-ID: blocks, bold-id - **TASK-ID** ... lines, non-canonical bullets, residual backlog-archive.md, residual progress.md).
  2. Reports a finding-count table per category.
  3. On --fix, runs a 6-pass migration:
    • Pass 1 — descriptions cache (extract task bodies into per-task description files).
    • Pass 2 — operational rewrite (tasks.md, backlog.md → thin one-liner index).
    • Pass 3 — activeContext.md rich-block migrator (legacy paragraph form → strict mirror of tasks.md § Active).
    • Pass 4 — backlog-archive.md migration. Splits by ## Cancelled / ## Completed; for each entry: cancelled → synthesise documentation/archive/cancelled/archive-{ID}.md; completed → verify existing documentation/archive/{area}/archive-{ID}.md or synthesise into general/. Conflict resolution is interactive by default; --no-prompt auto-aborts conflicts (CI/non-TTY safety).
    • Pass 5 — post-fix re-scan. Full dry-run on the migrated tree must report zero findings; per-ID assertion checks every task ID present in the pre-fix backlog-archive.md.pre-v2.bak is now represented in documentation/archive/. Mismatch triggers automatic restore from the pre-write tarball backup.
    • Pass 6 (TUNE-0085 v1.21.5, hardened TUNE-0088 v1.21.6) — operational-files archive section migration. Strips ## Archived from tasks.md/backlog.md and ### Archived / ### Recently Archived / ## Последние завершённые from activeContext.md — sections that violate the canonical thin-index contract («one section only», v1.19.1). Four bullet shapes auto-detected (S1 arrow-link, S2 status-paren, S4 mid-bold-context, S3 plain-bold); compound task IDs supported (e.g. DEV-1212-S8). Explicit → documentation/archive/{path}.md pointer wins over prefix_to_area mapping. Per bullet: verify canonical with {ID} literal → strip; missing → defensive find across area subdirs (depth ≤ 3); if not found, synthesise stub; collision → respect --conflict-policy. Headerless fallback: operational files without an archive header are processed line-by-line; bullets with non-terminal status (in_progress, not_started, …) pass through as active content.
  4. Generates description files with closed 12-key YAML frontmatter (id, title, status, priority, complexity, type, project, started, parent, related, prd, plan).
  5. Idempotent — re-running on a compliant tree is a silent no-op (exit 0).

Data-loss safety contract

Every --fix invocation creates a tarball backup at ${DATARIM_DOCTOR_BACKUP_DIR:-/tmp}/datarim-backup-{TS}.tgz (mode 0600) before any write. The summary line on success prints the backup path. Pass 4 additionally writes a per-file backlog-archive.md.pre-v2.bak sidecar that is preserved after migration. The post-fix invariant emitted_count >= parsed_count guards against silent data loss; on violation the doctor restores the tarball and exits 2.

Exit Codes

  • 0 — Compliant (or --fix succeeded)
  • 1 — Non-compliant findings (dry-run)
  • 2 — Migration error (--fix aborted; state preserved per atomic file rename)
  • 3 — Concurrent invocation (lock held)
  • 4 — Path traversal / security violation in operational files
  • 64 — Usage error

Self-Heal Integration

/dr-init Step 2.4 runs datarim-doctor.sh --quiet on every initialization when datarim/ already exists. On exit 1 with TTY, prompts «Run /dr-doctor --fix? [Y/n]» (default Y). Non-tty sessions print a warning and continue.

pre-archive-check.sh validates every bullet line in tasks.md / backlog.md against the canonical regex before /dr-archive may proceed. Escape: --no-schema-check for in-flight migration.

Schema Reference

Canonical 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$

Status sets: tasks.md uses in_progress|blocked|not_started; backlog.md uses pending|blocked-pending|cancelled.

Pipeline Position

Maintenance command, runs on demand or auto-suggested by /dr-init when structure is non-compliant.

Related

← All Features