需求派生树与收口真源

用途：解决「需求一开始只有 1、2、3，做到 A 时引出 1.1、1.2、1.3，推进 1.3 又引出 1.3.1、1.3.2……最后谁也说不清哪条为什么存在、哪些还没收口」。
把需求及其派生关系、处理与收口状态收进一份机器可校验的真源，其余视图全部是派生物。

典型触发：「记一下这个需求/待办」「这条需求为什么会有」「哪些还没做完/没收口」「需求又扩散了」「把待办和收口情况理一下」，或推进项目时你刚发现了一个新问题、新边界、新约束。

一、铁律（不遵守则系统立刻失去价值）

1. 所有写入只走 CLI。真源是 tree.json，由 todoctl 唯一管理。
   ⛔ 不要手改 tree.json，⛔ 更不要手改 TREE.md / ACTIVE.md / FOCUS.md / dashboard.html（它们是 render 的产物，会被覆盖）。出现「两个真源」是这套系统最大的威胁。
2. 身份与路径分离。节点身份是不可变 ID（R-0007），1.3.2 只是 render 算出来的位置编号。
   引用节点一律用 ID，不要用 1.3.2 —— 一旦插入/移动节点，编号会整体错位，所有历史引用同时失效。
3. 新增节点必须回答「为什么会有它」。--why 记录触发它的具体事实（在哪条需求、做什么动作时发现）。
   没有 why 的节点等于断掉追溯链，等于回到表格时代。
4. 收口必须附证据。close 强制要求至少一条 --evidence。
   没有证据的「已关闭」是假关闭，会直接污染真源。
5. done ≠ closed。done = 我改完了；closed = 已验证/已确认收口。两步分开，防止自己给自己盖章。
6. 报告成功 ≠ 真的生效。写入后必须回读校验（todoctl show <id> / check / render 产物 mtime）。
7. 不可撤销的语义变更先确认：drop（放弃）、带 --override-reason 的收口、--force 跳过前置检查 —— 这三类必须由用户本人明确同意后才执行。

二、真源与派生物

> 派生物会自动刷新：任何一次真源写入（add / start / close / focus …）成功后，只要该目录已存在 TREE.md，七个视图会被自动重新生成 —— 不需要你记得手动跑 render。
> 视图过期是「记录对不上」的老根源，所以它不由人负责。要临时关掉用 --no-render。
> 全新真源要先手动跑一次 render（那时还没有 TREE.md 可判断），之后才自动跟随。
> 渲染耗时与节点数近似线性：800 节点一次写入约 0.3 s，其中约 0.24 s 是 Python 进程启动本身 ——
> 也就是说规模基本不再是成本项。

存放位置（todoctl 自动判定，可用 --root 或 $TODOCTL_ROOT 覆盖）：

1. --root 显式指定
2. 环境变量 TODOCTL_ROOT
3. 当前目录已是真源：docs/requirements/ / .req-tree/requirements/ / requirements/ 下已有 tree.json
4. 兼容：旧版宿主专有路径 .workbuddy/requirements/ 下已有 tree.json（仅识别，不再新建）
5. 当前目录已预建：docs/requirements/ 或 .req-tree/requirements/（空目录即生效 —— 只限这两个本系统自建命名空间）
6. 检测到 git 仓库 → <仓库根>/docs/requirements/（推荐：与代码同版本，git log 即审计日志）
7. 未检测到 git 仓库 → <当前目录>/.req-tree/requirements/

> ⚠️ 第 3、5 条只认上列名字。裸 requirements/ 必须已经是真源（含 tree.json）才会被优先命中 ——
> 否则一个存放依赖清单的 requirements/ 目录会把真源劫持到仓库子目录里，静默产生第二棵树。
> init 会打印「根定位方式 / 当前目录 / 真源目录」三行，落点不在当前目录下时还会额外告警；请对照确认。
>
> 迁移兼容：真源若落在旧版路径 .workbuddy/requirements/，仍会被认出（第 4 条），
> 但 check 会主动提示你搬到 .req-tree/requirements/ 或 docs/requirements/ ——
> 搬的时候把 tree.json / journal.jsonl / baselines.json / snapshots/ 一起带走即可，不会丢数据。
>
> 本工具不绑定任何宿主：默认落点、启动脚本、文档里都没有写死的宿主私有目录。

> 公开版/脱敏镜像库场景：用 todoctl export 导出 —— 恒脱敏，没有「不脱敏」模式
> （一个以安全为目的的命令不该带危险开关；要完整副本直接读真源目录即可）。
> 它清空 why/notes，并把标了 internal 的节点连同整条子树剔除。
> ⚠ 唯一无法自动脱敏的是 title —— 每次导出都会提示「本次将导出 N 个节点，公开前请人工复核标题」。
>
> 更省事的一条路：如果你的公开版根本不需要待办树，直接把 docs/requirements/ 排除掉，
> 压根不用 export。export 只服务于「要公开、但要公开一个子集」这个场景。

三、怎么用、去哪看（入口索引）

完整的功能与入口索引见 references/entry-map.md —— 按「我想做 X → 打哪条命令 → 结果去哪看」组织，
含全部子命令与各自选项。这里只给最常用的骨架：

• 五个工作流（首次建真源 / 派生新需求 / 推进与收口 / 出视图与巡检 / 每周 rebalance）见 entry-map.md 第五节
• 触发时机与写入纪律见 references/discipline.md
• ⚠️ --force 与 --override-reason 是两个独立的确认，常被混用 —— --force 跳不过假收口检查。
  连同退出码约定，都在 entry-map.md 的「全局约定」里

四、会话恢复（跨次交接）

需求会记在树里，但「我上次做到哪一步」不会自动留在树里 —— 除非你留痕。这一节解决的就是「隔了一天/一周再回来，怎么接上」。

三个必须养成的动作

开工：todoctl resume             # 一条命令拿回现场
过程中：todoctl note R-0007 这次做到哪 发现了什么
收工：todoctl note R-0007 收尾 --next-step "明天先跑一遍 XX 用例"

note 是唯一能留住「过程」的手段。没有 note，下次 resume 只能告诉你「这条需求还在推进中」，却说不出卡在哪一句话上。

⚠️ note / add 的长文本只能走位置参数，没有 --file / stdin 通道 ⇒ 文本里的
反引号会被 shell 当命令替换吃掉（$ 同理），且不会报错、事后极难发现
（本机实测两次：R-0080 与 R-0088 的一批取证 note 里，代码片段整段消失）。
对策：① 文本里不要用反引号，标识符直接写、或用 「」；② 已经写坏了就补一条校正 note
（note 追加语义，不改历史）；③ 需要引用代码就描述位置（app/x.py:123）而非贴片段。

⚠️ 已收口的节点仍可 note —— 这是被鼓励的做法：收口后才发现的新证据/失效的旧断言，
用 note 补记而不是把节点 restore 重开。状态不受影响（实测 R-0059/0060/0061/0062/0087）。

交错推进（跳着做是常态，不是错误）

真实工作几乎不会按派生顺序走：在做 1.1.2、下一步该做 1.1.3，但你被拉去做 2.1、2.2，然后才回头做 1.1.3。
这本身没有数据风险（单人顺序操作，不会写坏真源）。风险在于三个「看不见」：

用法就两步：

todoctl update R-0007 --next R-0008 --next-step "先跑一遍用例"   # 声明计划下一步
todoctl bench                                                  # 随时看全手头

--next 是节点指针（可被校验、能算出绕行）；--next-step 是文字说明。两者可并存、互不替代。
跳过计划下一步不阻断 —— 绕行是正常决策，工具只负责让你「知道自己在绕」，不替你判断该不该绕。

resume 会给你什么

恢复锚点

resume 会把「现在」写成锚点（tree.json 的 last_resume），之后每次写入都会让 RESUME.md 里的变动清单累积。
所以：早上 resume 一次，明天打开时 RESUME.md 就是「昨天到今天发生了什么」。

• 锚点是秒级精度：与锚点同一秒内发生的改动不计入变动清单。真实使用间隔是分钟/小时级，无影响。
• 没设 focus 时，resume 会推断恢复目标（最近变动的 doing 节点）并标注「（推断）」，避免空手而归。

变动按需求线分流（防止跨需求交叉）

一天里你往往同时碰几条需求。如果 resume 把期间所有变动平铺出来，恢复现场就变成一锅粥，
提交时也说不清这个 commit 到底属于哪条线。

所以每条变更都带归属线（line = 该节点所属的最顶层根需求），恢复时自动分流：

关键点：旁支成果不会丢 —— 它已经在真源里了，只是不摆到当前现场。

提交时用 log 按线抽出叙述，commit message 就不会是一锅粥：

todoctl log                                           # 全部变更，按线分组
todoctl log --line R-0031                             # 只要 OCR 这条线（可给该线上任意节点）
todoctl log --since "2026-09-22 09:00" --commit-msg   # 上次提交以来，直接出草稿

journal.jsonl 是追加式变更日志（只增不改），也是 log 的唯一依据。它是真源的一部分，要一起提交、不要手改；也不要进脱敏导出。

与其他机制的分工

⚠️ RESUME.md 与 FOCUS.md 不进脱敏导出（含内部进度轨迹与工作现场）。

五、封板、回滚与并发保护

封板（baseline）—— 把散在各线的成果合成一个可交付时点

交错推进一段时间后，你需要一个「到此为止」的时点：此刻各条线分别走到哪、哪几件正在进行。

todoctl baseline --name "v0.3 首版" --note "首版功能齐了"

它做三件事：

1. 冻结一份不可变快照（节点规模、各线进度、当时正在进行的项）写入 baselines.json；此后无论怎么改，历史基线都不变
2. 打印相对上一基线的差异（节点 / 已收口 / 未收口 / 进行中 / 阻塞的增减 + 各线进度变化）
3. 刷新 BASELINE.md

• 真源有错时拒绝封板 —— 基线必须是干净的时点
• 比对用 todoctl baseline --diff（不带值 = 与上一个比）
• ⚠️ --diff 输出的右侧 ID 不是基线：它形如 对比：`B-甲` → `B-乙`，其中 B-乙 是打印时刻现算的临时标签，代表「当前实时状态」，
  不会被写进 baselines.json / BASELINE.md，--list 里也查不到。「看到两个 ID 但只查到 1 条基线」是正常现象，不是记录丢失。
  想比对两个真实基线，必须显式给 --diff <B-xxx>。

回滚（restore）—— 没有 git 也能退回上一步

每次写入前都会自动留档到 snapshots/：last.json（上一版）、prev.json（上上版）、按天一份（保留 30 天）。

todoctl restore --list                    # 先看有什么
todoctl restore --last --yes              # 退回上一次写入之前
todoctl restore --date 2026-09-22 --yes   # 退回该日首写之前

• 必须显式 --yes：回滚是不可逆操作；未加 --yes 只会打印「将要发生什么」然后返回 2
• 执行前会把当前状态另存为 pre-restore-<时间>.json —— 所以回滚本身也可逆
• 回滚会自动抬高 ID 水位（扫 journal 与 baselines 里出现过的最大 ID），保证「ID 永不复用」这条不变量不被回滚破坏

> 分工：整体回退用快照，逐字段追溯用 journal 的 before/after（todoctl log）。

并发保护（tree.lock）—— 只防「同时写」

同机多开进程同时写会静默丢数据（读-改-写的后写覆盖先写）。写入命令会先取 <root>/tree.lock 的非阻塞字节锁：

⚠️ 这把锁只防「同时写」，不限制「并行推进多条需求」。交错推进一直是允许的、也是常态。

六、强校验清单（check 会阻断的错误）

不阻断但必须看的告警：
W1 深度超限、W2 同父未收口过多、W3 推进中依赖未收口、
W4 open/blocked/done 长期未更新（> 14 天）、
W5 doing 搁置（> 7 天未动）、W6 计划中的下一步尚未开工（正在绕行）、
W7 祖先已收口/已放弃但它仍在 doing/done（--force 放行 start 后的兜底告警）、
W8 计划中的下一步已终结（closed/dropped） —— 该计划已失效，需更新或清除 --next。

> W6 与 W8 的区别：W6 是「绕行」（下一步还没开始，你还能回来）；W8 是「计划失效」
> （指向的节点已经收口/放弃，原计划不再成立）。bench 上分别是 ↷绕行中 与 ⌫计划已失效。

> W4 与 W5 互斥：doing 只出 W5，其余状态只出 W4，不会重复告警。

start / unblock 的两道前置门（除了需要 done_when）：
① depends_on 未收口 → 拒；② 祖先已 closed/dropped → 拒。
两者都可用 --force 显式放行（疏而有痕：放行后 W3/W7 会持续提示，而不是静默）。
在已收口的祖先下开工，等于正在制造一个假收口 —— 这是 E12 在时间轴上的前置版本。

七、常见错误

八、细节页

工具本体：scripts/todoctl.py（零第三方依赖，仅标准库）。三个入口完全等价，都只从 PATH 找 Python、
不含任何写死的安装路径（换机器、换平台、换用户都不用改）：