技能 Maintenance

Datarim Doctor

薄索引操作文件的模式规范:规范正则表达式、YAML frontmatter 契约、8 遍迁移语义(Pass 0–7,包括归档区段强制)、数据丢失安全契约。由 /dr-doctor 和 /dr-init 自愈按需加载。

概述

Datarim Doctor 是定义薄索引契约的运行时知识模块。操作文件(tasks.md、backlog.md、activeContext.md)携带每个任务一行的指针;任务描述位于 datarim/tasks/{TASK-ID}-task-description.md 的每任务文件中,带有封闭的 YAML frontmatter。progress.md 和 activeContext.md § Последние завершённые 滚动日志已被废除——完成历史仅存在于 documentation/archive/ 和 git log 中。

为何使用薄索引

操作文件是索引,而非内容。每一行回答四个问题:哪个任务、什么状态、描述在哪里。没有散文、没有需求、没有计划内容存在于 tasks.md / backlog.md 中。

  • 有界上下文——代理读取 1 KB 索引而非 100 KB 单体文件。
  • 每个任务单一事实来源——描述、验收标准、约束在一个文件中。
  • 可 grep 的状态——行格式可机器解析;状态变更是 1 行差异。
  • 幂等迁移——/dr-doctor 可运行任意次数而不产生漂移。

规范行正则表达式

^- ([A-Z][A-Z0-9]{1,9}-[0-9]{4}) · (STATUS) · P[0-3] · L[1-4] · (.+) → tasks/\1-(task-description|init-task)\.md$

此活动索引正则表达式(ONELINER_RE)适用于 tasks.md 和 activeContext.md;确切常量位于 scripts/lib/schema-regex.sh。状态集:

  • tasks.md / activeContext.md:规范写入器发出 in_progress | blocked | not_started(正则表达式也接受 pending | blocked-pending | cancelled 以兼容迁移);指针是必需的,且必须携带相同的任务 ID。
  • backlog.md:其自身的 BACKLOG_ITEM_RE——pending | blocked-pending | cancelled | superseded | absorbed | deferred 加上活动状态、优先级 P0–P4 以及单行内联描述;指针是可选的。

分隔符:·(U+00B7 中间点)。箭头:→(U+2192)。frontmatter 中的标题:≤ 80 字符,单行;包含 → 的标题必须重命名。

描述文件契约

每个任务在 datarim/tasks/{TASK-ID}-task-description.md 都有一个描述文件,带有封闭的 12 键 YAML frontmatter:

---
id: <TASK-ID>                 # ^[A-Z][A-Z0-9]{1,9}-[0-9]{4}$
title: <string>               # ≤ 80 chars
status: <enum>
priority: <enum>              # P0|P1|P2|P3
complexity: <enum>            # L1|L2|L3|L4
type: <string>                # framework|infra|content|...
project: <string>             # Datarim|Arcanada|...
started: <date>               # YYYY-MM-DD
parent: <TASK-ID|null>
related: <list[TASK-ID]>
prd: <relpath|null>
plan: <relpath|null>
---

正文:5 个规范章节(概述 / 验收标准 / 约束 / 范围外 / 相关),上限 250 行。可选的 ## Implementation Notes 和 ## Decisions。

8 遍迁移算法(Pass 0–7)

  1. Pass 0 — ## Backlog 区段拒绝:## Backlog 中的顶级 tasks.md 标题是一个发现项;项目符号被手动移动到 backlog.md。
  2. Pass 1 — 描述文件(构建缓存):遍历遗留的 ### TASK-ID: 标题;提取 status/priority/complexity/type/started/parent/related/prd/plan;写入带 frontmatter 的每任务文件。
  3. Pass 2 — 操作文件:将 tasks.md 和 backlog.md 重写为按章节分组的单行索引。
  4. Pass 3 — activeContext.md:将遗留的 **Current Task:** 形状转换为 ## Active Tasks 列表(仅活动任务镜像,≤30 行);progress.md 被删除。
  5. Pass 4 — backlog-archive 迁移:AWK 区段状态机 + 按 ID 分发将遗留的 backlog-archive.md 拆分为 documentation/archive/cancelled/(合成存根)和针对已完成条目的区域特定 archive-{TASK-ID}.md(验证或合成到 general/);--no-prompt 标志用于 CI。
  6. Pass 5 — 修复后重新扫描:在 --fix 之后以试运行模式组合现有扫描分发;断言修复后零发现项 + 保留 .pre-v2.bak 附属文件 + 幂等重跑(第二次 --fix 为空操作)。
  7. Pass 6 — 操作文件归档区段迁移(<TASK-ID> v1.21.5,加固于 <TASK-ID> v1.21.6):从 ## Archived/tasks.md 剥离 backlog.md,从 ### Archived 剥离 ### Recently Archived/## Последние завершённые/activeContext.md——这些区段违反规范薄索引契约(«仅一个区段»,v1.19.1)。自动检测四种项目符号形状(S1 箭头链接、S2 状态括号、S4 中间粗体上下文、S3 纯粗体)。支持复合任务 ID(例如 <TASK-ID>-S8、<TASK-ID>-FOLLOWUP-lock-ownership-doc)。项目符号正文中显式的 → documentation/archive/{path}.md 指针优先于硬编码的 prefix_to_area 映射。每个项目符号:在解析路径验证规范归档 → 剥离;缺失 → 跨区域子目录防御性 find(深度 ≤ 3)——若找到且包含 ID 字面量,则带警告剥离;否则合成存根;冲突 → 遵循 --conflict-policy。无标题回退:没有归档标题的操作文件逐行处理;具有显式非终止状态(in_progress、not_started、blocked 等)的项目符号作为活动内容通过。
  8. Pass 7 — HTML 注释归档备注(验证后剥离):单行 <!-- {ID} {verb} {date} → documentation/archive/…md --> 注释仅在引用的归档文件存在时被剥离;否则保留并给出警告。

幂等性守卫:如果不存在 ### TASK-ID: 标题、没有遗留的 backlog-archive.md,且所有项目符号行匹配规范正则表达式,则立即退出 0。用于 /dr-init 自愈的廉价探测。

数据丢失安全契约

围绕 --fix 模式的纵深防御(<TASK-ID>):

  • 写入前 tarball 备份——在任何变更之前,将 umask 077 的 tarball 写入 ${DATARIM_DOCTOR_BACKUP_DIR:-/tmp}/datarim-backup-{TS}.tgz。路径在成功摘要中显示。
  • 附属副本——Pass 4 变更的每个遗留文件还会在树内获得一个 .pre-v2.bak 附属文件(操作员可见)。
  • 不变量——EMITTED_COUNT >= PARSED_COUNT。Doctor 在重写前后计数任务条目。违反触发 restore_backup_and_die():移除变更状态,tar -xzf 将 tarball 解压回原位,退出 2。
  • 固定运行时——doctor 从项目固定的 .datarim-runtime/ 副本运行,其清单记录源修订和内容摘要。运行时编辑不修改框架源;更改通过源仓库和显式更新进行。

自愈入口点

  • /dr-doctor(始终)
  • /dr-init 自愈——探测 datarim-doctor.sh --quiet;在不符合时提供 /dr-doctor --fix。
  • /dr-archive 归档前门禁——pre-archive-check.sh 验证行格式;仅在迁移进行中时使用 --no-schema-check 绕过。

边缘情况

  • Bash 3.2(macOS 默认)——工具使用两遍 grep+awk 解析器,而非 NUL 分隔读取。
  • 标题包含 → 字符——转义或拒绝(正则表达式不允许)。操作员必须重命名。
  • 并发调用——在 flock 上使用 $DATARIM_ROOT/.dr-doctor.lock。第二个实例退出 3。
  • 路径遍历——通过 scripts/lib/canonicalise.sh 进行词法规范化(无 I/O)。工具退出 4。

加载方

  • /dr-doctor(始终)
  • /dr-init 自愈步骤(当探测返回退出码 1 时)
  • /dr-archive 行格式门禁(失败时,用于解释不符合项)