命令 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}/。

用法

# 试运行(默认)——报告发现项,不做变更
/dr-doctor

# 应用迁移
/dr-doctor --fix

# 在非交互环境中应用迁移(CI / AI 会话)
# —— 跳过冲突(保留条目)而非提示
/dr-doctor --fix --no-prompt

# 静默探测(仅退出码——适用于脚本和自愈场景)
/dr-doctor --quiet

功能说明

  1. 探测 datarim/ 中的不合规条目(旧版 ### TASK-ID: 块、粗体 ID 的 - **TASK-ID** ... 行、非规范项目符号、残留的 backlog-archive.md、残留的 progress.md)。
  2. 按类别报告发现项计数表。
  3. 在 --fix 时,执行 6 轮迁移:
    • 第 1 轮 —— 描述缓存(将任务正文提取到每任务描述文件)。
    • 第 2 轮 —— 运维文件重写(tasks.md、backlog.md → 单行薄索引)。
    • 第 3 轮 —— activeContext.md 富块迁移器(旧版段落形式 → 严格镜像 tasks.md § Active)。
    • 第 4 轮 —— backlog-archive.md 迁移。按 ## Cancelled / ## Completed 拆分;对每个条目:已取消 → 合成 documentation/archive/cancelled/archive-{ID}.md;已完成 → 验证现有 documentation/archive/{area}/archive-{ID}.md 或合成到 general/。冲突解决遵循 --conflict-policy=prompt|keep|overwrite|skip|abort(默认 prompt,非 TTY 下自动 skip);--no-prompt 是 skip 的 CI 别名。
    • 第 5 轮 —— 修复后重新扫描。对迁移后的树执行完整试运行必须报告零发现项;按 ID 断言检查修复前 backlog-archive.md.pre-v2.bak 中存在的每个任务 ID 现在都已体现在 documentation/archive/ 中。不匹配会触发从写入前 tarball 备份自动恢复。
    • 第 6 轮(<TASK-ID> v1.21.5,加固于 <TASK-ID> v1.21.6)—— 运维文件归档区段迁移。从 tasks.md/backlog.md 中剥离 ## Archived,从 activeContext.md 中剥离 ### Archived / ### Recently Archived / ## Последние завершённые —— 这些区段违反规范薄索引契约(«仅一个区段»,v1.19.1)。自动检测四种项目符号形态(S1 箭头链接、S2 状态括号、S4 中置粗体上下文、S3 纯粗体);支持复合任务 ID(例如 <TASK-ID>-S8)。显式 → documentation/archive/{path}.md 指针优先于 prefix_to_area 映射。对每个项目符号:用 {ID} 字面量验证规范性 → 剥离;缺失 → 在各区域子目录中防御性 find(深度 ≤ 3);若未找到,合成存根;冲突 → 遵循 --conflict-policy。无标题回退:没有归档标题的运维文件逐行处理;状态非终态(in_progress、not_started 等)的项目符号作为活动内容原样通过。
  4. 生成带有封闭 12 键 YAML frontmatter 的描述文件(id、title、status、priority、complexity、type、project、started、parent、related、prd、plan)。
  5. 迁移后运行两个正交轮次:backlog 终态条目清理(prune-backlog-terminal.sh —— 移除已有归档文档的已完成条目,暴露没有归档文档的条目)以及建议性 init 任务存在性检查(check-init-task-presence.sh --all,从不阻塞)。
  6. 幂等 —— 在合规的树上重新运行是静默无操作(退出码 0)。

数据丢失安全契约

每次 --fix 调用都会在任何写入之前于 ${DATARIM_DOCTOR_BACKUP_DIR:-/tmp}/datarim-backup-{TS}.tgz 创建 tarball 备份(模式 0600)。成功时的摘要行会打印备份路径。第 4 轮还会写入每文件 backlog-archive.md.pre-v2.bak 附属文件,迁移后保留。修复后不变量 emitted_count >= parsed_count 防止静默数据丢失;违反时 doctor 会恢复 tarball 并以退出码 2 退出。

退出码

  • 0 —— 合规(或 --fix 成功)
  • 1 —— 存在不合规发现项(试运行)
  • 2 —— 迁移错误(--fix 中止;状态按原子文件重命名保留)
  • 3 —— 并发调用(锁被持有)
  • 4 —— 运维文件中的路径遍历 / 安全违规
  • 64 —— 用法错误

自愈集成

当 datarim/ 已存在时,/dr-init 第 2.4 步在每次初始化时运行 datarim-doctor.sh --quiet。在 TTY 下退出码为 1 时,提示 «运行 /dr-doctor --fix?[Y/n]»(默认 Y)。非 TTY 会话打印警告并继续。

pre-archive-check.sh 在 /dr-archive 可以继续之前,根据规范正则验证 tasks.md / backlog.md 中的每个项目符号行。逃生通道:--no-schema-check 用于进行中的迁移。

文档迁移自愈(2.49.0+)

自 2.49.0 起,规范文档根目录为 documentation/(旧版 docs/ 名称已退役),且 /dr-optimize 漂移检测器会硬性翻转:仍使用 docs/ 的消费方仓库会被标记为漂移。因此仓库不仅被告知存在漂移 —— /dr-doctor 还提供可选的迁移轮次来修复它。

该轮次检测布局(旧版 docs/ → 提供迁移;docs/ 和 documentation/ 同时存在 → 人工审查,不自动修复;已迁移 → 干净无操作),然后执行 git mv + 四类 Diátaxis 拆分(已知文件映射到其类别;未知文件归入 how-to/ 并带审查标记)+ 锚定引用重写。它根据引用 linter 验证结果,若任何检查失败则回滚到迁移前的树 —— 幂等且回滚安全。

按设计,这是一个独立的同级执行器,而非运维文件 doctor 的 --scope:产品文档物理上位于框架状态目录之外,因此将内容迁移混入模式迁移会模糊框架有意保持的边界(§ 验证纪律)。

模式参考

规范正则(单行,锚定):

^- ([A-Z][A-Z0-9]{1,9}-[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。

流水线位置

维护命令,按需运行,或在结构不合规时由 /dr-init 自动建议。

相关

报告结果

在面向人员的更新或结果之前,应用 Human Outcome Reporting。说明用户可见的结果、原始条件、检查与证据,以及未决限制。阶段结果并不意味着整个任务已完成。保持精确协议和技术记录完整。若要在不继续工作的情况下再次解释,请使用 /dr-explain。