[🛠] Operations Automation #4: 少改文档也能避免状态过期的结构

✨ GPT-5.6 Sol 的总结

记录我如何放弃把状态变更复制到多份文档的做法，改用可变状态的单一owner、按条件更新的downstream文档与phase checkpoint，重新整理文档保鲜流程。

文档更新得越多，当前状态反而越分裂

长时间任务经过上下文压缩或转交到其他session后，曾出现过把旧文档里写的下一项工作误认为当前状态的情况。为了避免这个问题，我有一段时间会在状态变化时，把所有看起来相关的文档都更新一遍。

我在README、文档router、需求文档、当前方向文档、Runbook和TODO中，反复写入相同的完成事实与下一项工作。当时觉得，只要没有漏掉任何文档就会更安全。

但从把一次状态变更写进六处的那一刻起，就必须一直让这六处保持完全一致。有些文档还停留在部署前，另一些却写着真机验证已经结束。大量更新文档不但没有阻止状态过期，反而制造出了新的过期状态。

每完成一次小验证，就要修改多份文档，甚至留下一个commit。Git history因此也被切得很碎。相比实现究竟在哪里结束，文案被同步了多少次反而更加显眼。

可变状态只交给一份文档负责

问题不在于文档数量，而在于多份文档共同拥有同一个事实。因此，我先为每一种事实指定了唯一的owner。

发生变化的事实	owner	修改其他文档的条件
当前Runtime、blocker、phase、下一项工作	canonical current-state snapshot	不复制到其他文档
稳定的产品决策、禁止的绕行方案、活跃Goal	current-direction文档	仅当产品决策或Goal本身发生变化时
行为、数据、权限、acceptance	requirements或contract	仅当用户或系统的行为契约发生变化时
运营流程、gate、rollback、recovery	Runbook	仅当运营人员应遵循的流程发生变化时
文档关系、产品阶段、执行入口	README或router	仅当导航路径或产品关系发生变化时
详细命令、日志、worker验证	report、artifact、Git evidence	aggregate文档只保留结论和证据链接

关键在于区分“相关”与“拥有”。部署结束并不意味着需要修改需求文档。如果部署过程中运营rollback流程发生变化，就修改Runbook；如果行为契约也随之改变，才在那时修改requirements。

README和router也不再追着当前revision、设备状态或下一项工作变化。这些文档只负责稳定地指出应该去哪里阅读、从哪里执行。

将即时更新与durable checkpoint分开

单一owner并不意味着把文档更新拖到phase结束。出现新证据，或Runtime状态、blocker、优先级、下一项工作发生变化时，我会在继续实现之前立即更新canonical current-state snapshot。这样即使任务中途被压缩或转交，下一个session也能从一个地方恢复真实状态。

相反，commit不会在状态每变一行时就创建。只有到了可以独立review并重新开始的边界，才会再检查一次current-state并建立checkpoint。

• 实现完成时
• 部署与事后验证完成时
• 得到真机或用户入口E2E结果，或者blocker已经确认时
• 因interruption或handoff需要移交工作时

即时更新是为了保证resume安全，phase checkpoint则是为了review和回滚一组变更。把两者当成同一条规则处理，才导致micro-event commit不断增加。

没有commit权限的任务更简单。不能只因为review结束，就创建COMMITTED或CLOSED状态。应保持集成候选处于freeze状态，在真正的checkpoint出现之前，不把它记录成durable的完成状态。

worker验证留在report中，不再塞进aggregate文档

并行工作中，每个worker都会留下执行过的命令、检查结果、重叠的hunk和剩余限制。如果再把这些内容贴进root TODO、README和需求文档，只会增加coordinator必须阅读的文档数量。

worker级别的详细证据保存在immutable report和Git diff中，current-state只记录集成后的结论、当前影响和证据路径。coordinator会逐一review report，但不会把一个report当作一个commit。同一phase中的多个report，在集成验证完成后可以共享一个checkpoint。

这样一来，aggregate文档变短了，详细验证也没有消失。下一个session先阅读当前状态，只有需要判断依据时，才沿链接查看report和Git evidence。

resume顺序违背了owner规则

整理完规则后，我重新检查整个流程，发现了一个意外的基本矛盾：启动流程要求先读README，再读todo.md。

一边在README里写着不要复制可变状态，实际的resume流程却先读router，再读current-state。如果router里残留了过期的状态描述，从第一次判断起就可能走错方向。

因此我调整了启动顺序。首先在canonical current-state中查看当前Runtime、blocker、phase和下一项工作。然后再从README与文档router中确认repository边界并找到所需的leaf文档。稳定的产品决策从current-direction读取，实际行为契约则从requirements读取。

只添加一张文档owner表还不够。无论是人还是Agent，实际阅读顺序都必须遵循owner关系。

当前应用范围与剩余限制

这套结构已经反映到共用工作规则、Operations Automation的文档routing、变更文档化manifest和并行coordination protocol中。skill validator、文档同步检查和diff检查都已通过。不过，当前变更仍只存在于local working tree中，尚未commit或部署。

我也没有回头重写所有既有文档。历史记录和详细report保持原样，只有active文档中的current-state事实发生冲突时，才会缩减为对owner的引用。相比旧文档仍然存在，更优先的是不再把它当作当前工作的authority来读取。

现在判断文档是否保持最新，不再看修改了多少处。而是看经过压缩或handoff之后，是否只读一个地方就能准确掌握当前阶段与下一项工作，以及需要详细依据时能否重新追溯证据。