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)
- Pass 0 —
## Backlog区段拒绝:## Backlog中的顶级tasks.md标题是一个发现项;项目符号被手动移动到backlog.md。 - Pass 1 — 描述文件(构建缓存):遍历遗留的
### TASK-ID:标题;提取 status/priority/complexity/type/started/parent/related/prd/plan;写入带 frontmatter 的每任务文件。 - Pass 2 — 操作文件:将
tasks.md和backlog.md重写为按章节分组的单行索引。 - Pass 3 — activeContext.md:将遗留的
**Current Task:**形状转换为## Active Tasks列表(仅活动任务镜像,≤30 行);progress.md被删除。 - Pass 4 — backlog-archive 迁移:AWK 区段状态机 + 按 ID 分发将遗留的
backlog-archive.md拆分为documentation/archive/cancelled/(合成存根)和针对已完成条目的区域特定archive-{TASK-ID}.md(验证或合成到general/);--no-prompt标志用于 CI。 - Pass 5 — 修复后重新扫描:在
--fix之后以试运行模式组合现有扫描分发;断言修复后零发现项 + 保留.pre-v2.bak附属文件 + 幂等重跑(第二次--fix为空操作)。 - 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等)的项目符号作为活动内容通过。 - 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行格式门禁(失败时,用于解释不符合项)