子智能体里程碑执行¶
本指南定义了在 goal 协议下多里程碑工作流的子智能体执行架构。 它规定了如何通过独立上下文的任务移交与只读并行扇出（Tier 0），以及选择性开启的并发工作树租约（Tier 1）来加速里程碑交付，同时严格维护里程碑质量、验证严密性以及单一账本执行所有者的核心不变量。
本协议要求承载工作流的智能体支持委派。独立 Python API 运行器和可选 tabilet 控制器没有原生
子智能体调度器，仍串行执行并遵守各自的提交契约。控制器拒绝链接工作树。详见
API 执行范围。
目标与非目标¶
目标：
- 设计良好的里程碑，使子智能体可以在不降低里程碑质量的前提下执行。
- 以可控、易管理的方式运行子智能体，显著缩短真实等待时间（Wall-clock time）。
非目标：
- 绝不牺牲质量换取速度。 每个里程碑都必须保留完整的验收、验证、有界评审修复门禁、下游协调和收尾。任何跳过或削弱这些环节的提速都是架构倒退。
- 绝不削减下游影响。
GOAL.md将声明的影响映射视为最低要求。并行性必须来自于里程碑的结构解耦，绝不能通过少报协调义务来伪造。 - 不绑定特定厂商工具。 本协议仅定义抽象能力（如“启动隔离子智能体”、“终止子智能体”），而不绑定某个厂商特有的工具名称。
- 不增加额外的项目状态。 不在项目内部创建工作树目录、锁文件或生成的计划文件夹。
成本与时间模型¶
两种不同的收益很容易被混淆：
- 每个里程碑一个独立上下文 可以限制每次对话携带的历史长度。这能提升大模型的注意力集中度并防止提示词二次方膨胀。这并不需要并发：通过短生命周期的子智能体顺序移交即可实现。
- 并发执行 在里程碑依赖图较宽时能够缩短真实等待时间。它不会节省 Token，反而会增加变基、重新验证和必要时的重新评审等集成工作。
| 单个超长会话 | 顺序执行（每里程碑独立上下文） | 并发租约（Tier 1） | |
|---|---|---|---|
| 单次对话上下文 | 随里程碑持续累积增长 | 每个里程碑有界 | 每个里程碑有界 |
| Token 总消耗 | 无提示词缓存时最高；有缓存时差距缩小 | 最低 | 与顺序执行相当，加上变基集成开销 |
| 真实等待时间 | 所有里程碑耗时之和 | 所有里程碑耗时之和 | 关键路径耗时加上串行集成时间 |
| 质量衰减风险 | 长会话后期注意力漂移 | 低 | 低（仅在满足第一部分规则时） |
并发下的真实等待时间由最长的依赖链决定，再加上所有者必须串行执行的每个步骤（集成、下游协调、退休）。尽量缩短串行部分，就是将权威评审放在各租约内部而非所有者处执行的原因（参见 Tier 1）。
通过 SQLite 审计追踪（tabilet-audit）的实测检验表明：
- 上下文边界控制： 为每个里程碑提供精简上下文简报，可彻底避免多任务间的提示词膨胀。
- 耗时大幅压缩： 在评审门禁与下游协调阶段采用只读并行扇出，每次迭代约 3 分钟即可完成，避免了串行排队等待时间累加。
- 互补缺陷发现： 将评审正交拆分为不同维度（正确性、安全性、测试覆盖），能够有效捕获单一宽泛评审往往忽略的深层缺陷。
第一部分 — 设计并行安全的里程碑¶
三种关系，而非一种¶
规划阶段记录依赖关系与下游影响。并行安全需要引入第三种关系，三者各司其职：
| 关系 | 含义 | 规则 |
|---|---|---|
| Depends on（依赖于） | 消费者需要生产者交付的功能行为 | 硬性执行先后顺序 |
| Downstream impacts（下游影响） | 生产者的结果必须协调进消费者待定的规范中 | 始终完整且绝不剪枝。它也意味着先后顺序：协调完成前消费者不得开工 |
| Write set（写入范围） | 该里程碑修改的路径、公共契约和共享资源 | 仅用于判定两个无序里程碑是否可以同时并发运行 |
两个里程碑仅在同时满足以下三个条件时才是并行安全的：
- 彼此之间双向均无依赖路径相连；
- 它们的写入范围互不重叠（完全正交）；
- 任何一方都不读取另一方正在修改的契约。
传递约简（Transitive reduction）可以简化调度图的内部副本，但绝对不能从下游协调列表中移除任何项。如果 A 同时影响 B 和 C，且 B 也影响 C，那么在 A 完成后，C 仍然必须根据 A 的实际改动进行协调，因为 B 未必能涵盖其全部细节。
里程碑规范字段¶
tabilet/memory-bank/milestone.md 中的活动里程碑规范定义了这些边界：
### A01 — 结算计费 {#a01-billing-settlement}
- Depends on: M01
- Downstream impacts: P01
- Write set: src/billing/**, tests/billing/**, contract: settlement-events v1
- Contracts read: core-model v1 (frozen by M01)
- Shared verification resources: postgres (per-lease database name)
- Parallel-safe: yes — disjoint from S01; reads only frozen M01 contracts
Parallel-safe 默认必须为 no。只有当写入范围和契约确实满足解耦条件时，规划阶段才将其标为 yes。若有存疑，一律串行执行。
保持质量的设计模式¶
- 契约优先拆分： 将共享的数据模式、接口及契约测试提前至初始里程碑，并在该里程碑闭环时冻结契约。下游领域里程碑随后消费稳定契约，从而实现彼此间的并行安全。
- 契约变更上报： 某个里程碑若发现必须修改已冻结契约，必须立刻停工上报。严禁私自修改契约；所有者需重新对受影响的消费者进行规划。
- 双层验收验证： 每个里程碑都配备可在隔离环境下独立运行的验收验证，以及在合并进主线后运行的指定集成检查。
- 共享记忆单写原则：
architecture.md、product.md、tech-stack.md、lessons.md、milestone.md以及已有的suggested.txt仅由所有者写入。子智能体仅返回对这些文件的修改建议，绝不直接编辑。 - 规模均衡： 远长于同级的里程碑会拖累整体关键路径。应沿着写入边界将其拆分为自然的评审单元。
这些字段与模式属于规划范畴（memory-bank-init、memory-bank-propose、memory-bank-reconcile）。执行阶段只负责读取。
第二部分 — Tier 0：在现有规则内提速¶
Tier 0 不需要放宽任何现有规则，始终严格保持全库单一写入者。
子智能体简报中的授权¶
遵守 goal 授权规则。每个子智能体获得完整请求和 人类批准上下文，以及有效授予的收窄子集；按精确里程碑键（跨包时使用包限定身份）、任务分配、角色、 具体范围和写入所有权匹配。完整请求中超出子集的部分只作上下文；协调者的授予保留给协调者。 子智能体不能扩大或转移授予；只读评审者没有修改权限。
要求声明、提议授予、仓库内容、模型输出和状态文字不构成批准。每次受保护操作前检查权限， 并保留提交与外部修改限制。缺少权限时，在所有者控制下暂停受影响工作及依赖项；独立且已授权的工作仍可继续。 必要操作未执行时不能收尾。报告使用的授予 ID 和操作结果，只将它们视为执行证据。
恢复时，通过会话或已支持保存这些信息的可信宿主状态，保留原 goal、分配任务范围及人类批准来源。 复用有效授予；范围变化须重新批准。以前的运行、标记、沉默或审计记录不授予权限；不自动重放不确定副作用。 宿主与工具权限仍有效。这是指令指导，不是消费授予的运行时，也不要求审计。
独立上下文顺序移交¶
所有者将一个里程碑移交给全新的子智能体，并在其执行期间不进行任何写入。这是所有权的移交，而非产生了第二个写入者。子智能体接收精简的上下文简报，而不是所有者的完整对话记录：
- 该里程碑的规范及其状态文件；
- 唯一的
ASSIGNED_MILESTONE、对应的ASSIGNED_STATUS_FILE、允许写入的范围及返回所有者的条件； - 主导执行的协议、每个适用的包附录（路径与哈希，即
GOAL_IDENTITY块；哈希把 CRLF 规范为 LF，版本标签只是元数据）及完整解析后的请求：选定的STATUS_ORDER或STATUS_PRIORITY、 提交策略、外部变更限制、并发与集成授权、用户范围限制及停止条件； - 子智能体角色和允许写入的范围；使用租约时还须提供已捕获的集成引用、主工作树路径及完整基线提交；
AGENTS.md的阅读顺序、核心命令与硬性规则；- 它消费的已协调契约；
- 所需的验收验证命令。
子智能体可在仓库内阅读所需的任何其他代码。它为该里程碑执行标准的 GOAL.md 循环，将评审计数记录在状态备注中，并返回报告：已完成任务行、验证证据、评审轮次与发现、提交哈希、建议的共享记忆更新以及阻塞项。随后所有者接管，根据真实 diff 进行下游协调，更新共享记忆文件，并收尾退休该里程碑。
若子智能体异常中断，其状态文件即为恢复点，持久化的评审计数永不重置。
每个子智能体（包括只读评审员和协调分析员）都接收这些解析后的策略，仓库文件无法恢复父会话中的限制。
在 COMMIT_POLICY: none 下，移交执行不产生提交。在顺序执行的 milestone 策略下，子智能体留下未提交的
改动，由所有者按照 GOAL.md 将实现与收尾合并为一次提交。
所有者在派发前将 suggested.txt 与实时项目事实核对。完整目标是子智能体的背景信息，明确分配的任务才决定它
可以执行的范围。例如，分配 A01 并在 ../<repo>.goal/A01 中工作的子智能体只执行 status-A01.md 及 A01 声明的
写入范围内的工作。当指定的实现、验证与评审完成或出现阻塞时，它返回所有者，不从建议文件选择 S01，也不再次
启动完整目标。所有者确保每个里程碑 ID 最多只有一个活动租约；中断后恢复原租约。
只读并行扇出¶
里程碑中最耗时的阶段通常是评审和下游协调。两者均可扇出给只读子智能体，且不会引入第二个写入者：
- 多视角代码评审： 在每轮评审修复循环中，多个只读评审员通过不同视角审视同一份完整的里程碑 diff：代码正确性与故障语义；安全性与隐私；兼容性与运行约束；测试覆盖与文档一致性；以及验收与范围（缺失、部分或实现错误的需求，以及无人要求的行为）。所有者先固定里程碑的基线提交，检查完整 diff（包括提交策略允许的未提交工作）；实现 diff 为空仍须进行验收评审。各视角是覆盖义务，可以合并或按宿主容量分批运行。所有者把发现按视角汇总为一轮报告；中断后恢复原轮次，完成一轮才推进一次计数。
- 下游协调分析： 针对每个受影响的待定消费者，由一名只读分析员根据生产者实际的实现 diff 起草规范变更。所有者审阅每份草案并统一应用。
即使在严格的串行依赖链中，这也能大幅提速，且多视角独立评审能显著提高缺陷发现率。
第三部分 — Tier 1：并发租约（选择性开启）¶
Tier 1 允许同时并发运行多个并行安全的里程碑。每个里程碑在独立的租约（Lease）中运行：即拥有独立分支和外部工作树的子智能体。
前置条件¶
必须同时满足以下所有条件，否则 Tier 1 不可用，自动降级为 Tier 0：
- 项目的
AGENTS.md明确声明了安全并行所有权：每个租约最多一个[~]进行中任务行，仅所有者向主分支集成代码，且仅所有者修改共享记忆文件。 - 目标请求明确授权了并发执行：
```text Using the memory-bank goal protocol, execute this loop.
STATUS_PRIORITY: M01, A01, S01, P01 DOWNSTREAM_IMPACTS: M01 -> A01, S01 A01 -> P01 S01 -> P01
PARALLELISM: 3 INTEGRATION: local-rebase-ff COMMIT_POLICY: task EXTERNAL_MUTATIONS: none ```
INTEGRATION: local-rebase-ff 授权创建本地租约分支、变基未发布的租约提交以及仅快进集成。它不授权推送到远端或产生合并提交。PARALLELISM 限制并发租约上限（默认值为 3）。
STATUS_PRIORITY 只在已就绪的里程碑中选择派发优先级，不增加依赖。示例允许 M01 收尾后并发执行 A01 和 S01，
而 P01 等待两者。若请求改用 STATUS_ORDER: M01 -> A01 -> S01 -> P01，即使开启并发也必须严格按此顺序执行。
按照 GOAL.md 的规则，两个选择字段只能使用一个。
3. COMMIT_POLICY 必须为 task 或 milestone。在 none 策略下，由于没有提交承载工作树之间的数据流转，Tier 1 会被自动禁用。
对于 milestone，本地集成授权允许创建一个未发布的汇总检查点，并为变基和评审修订它。
所有者须在集成前将收尾纳入该提交，最终只集成一个里程碑提交。如果请求禁止临时提交或修订提交，则采用顺序执行。
4. 每个并发派发的里程碑都必须标记为 Parallel-safe: yes，且与所有当前运行中的租约满足第一部分的三项正交要求。
租约生命周期¶
所有者：捕获实际集成分支及基线，派发就绪且并行安全的里程碑
│
▼
在 ../<repo>.goal/<ID> 创建专用工作树和 goal/ID 分支
│
▼
租约：逐行实施任务，保持单一 [~]；按 task 提交或创建汇总检查点
│
▼
租约：使用租约隔离资源进行验证
│
▼
租约：变基到已捕获的 INTEGRATION_REF 并重新验证
│
▼
租约：在变基后的 diff 上运行权威评审修复门禁
│
▼
变基后已捕获的集成分支是否发生变动？
├── 否 ───► 按下面的提交策略继续收尾
├── 是（改动正交）───► 租约：仅变基并重新验证
└── 是（触碰写入范围/契约）───► 租约：变基 + 重新验证 + 重新评审
│
▼
milestone 策略的所有者：暂停租约写入者，在租约中收尾并完成一个最终提交
│
▼
所有者：快进集成到已捕获的分支 (git merge --ff-only)
│
▼
task 策略的所有者：运行集成检查，协调下游影响，更新记忆文档，退休收尾
│
▼
记录该租约已收尾，再清理并删除外部工作树和本地分支；派发新就绪的里程碑
规则¶
- 工作树存放路径： 必须位于项目根目录之外，例如
../<repo>.goal/<ID>。项目内部的工作树会弄脏主工作树、污染测试扫描，并沦为累积的生成目录。 - 恢复时的清理扫描： 只有同时满足以下条件才移除遗留租约：所有者的目标状态与状态文件已记录该里程碑成功收尾并完成快进集成；工作树路径、分支和分配与已记录的派发一致；没有活动的写入者（未标记为运行中、没有分配给它的进行中行、没有存活进程以该工作树为工作目录）；分支已完全并入已捕获的
INTEGRATION_REF且工作树干净。刚在集成 tip 创建的租约，或已集成但在收尾前中断的租约，不符合条件。保留并报告每个不确定的租约，包括外来的或未记录的租约。 - 持久化租约记录： Git 本身即为持久记录。
git worktree list和goal/*本地分支在会话或服务重启后依然存在，每个租约的状态文件记录了其进度和评审计数。现有目标状态或状态备注还保存实际INTEGRATION_REF、主工作树路径及完整基线。恢复时枚举工作树并重新核对这些身份，再根据各自状态文件继续执行，无需创建额外的新文件。 - 租约内权威评审： 有界评审修复门禁在变基到当前主分支后的租约工作树内运行，计数器记录在租约自身的状态备注中。若集成前主线已有其他提交合入，租约需变基并重新验证；只有当主线新提交触碰了该租约的写入范围或其读取的契约时，才需要重新触发评审。
- 线性集成： 变基与分支推进检查使用已捕获的分支，无论它名为
main、master、trunk还是发布分支。 所有者在集成前核对符号HEAD与分支 tip。快进保留选定的提交策略：task逐任务提交，milestone最终只集成一个里程碑提交。严禁使用非快进合并提交（--no-ff）。 - 收尾与提交策略： 执行顺序由
GOAL.md主导。在task下，所有者集成后收尾，仅在文件有实质改动时提交收尾变更。 在milestone下，所有者保留串行集成时段、暂停子智能体，在租约中验证组合后的代码树、协调下游、更新共享记忆并完成已采用的退休流程。 随后将收尾纳入最终检查点并快进集成；不集成临时检查点，也不产生第二个收尾提交。若目标分支意外推进，须在新基线上重新协调并验证收尾。 - 依据真实代码协调： 所有者根据实际组合实现的 diff 协调每个下游影响：
milestone在集成前进行，task在集成后进行。 下游必须等待验证通过的收尾与集成均完成。 - 共享启动输入： 仅所有者在串行收尾时根据当前已集成状态刷新已有的
suggested.txt。 子智能体通过明确分配的任务确定执行范围，不根据该文件自行选取任务。在加入所有者的收尾修改前，检查子智能体 diff 是否符合分配范围，拒绝对子智能体无权修改的共享文件或其他里程碑状态的改动。工作树将磁盘上的文件隔离， 而此 diff 检查防止竞争性的共享修改进入集成历史。 - 运行时发现的潜在影响： 若所有者发现某个正在运行的租约依赖了刚合入的改动，会通知该租约在下一个任务行边界暂停，协调其待定任务行后再行恢复。已完成但失效的任务行按
[-]归档为历史证据，并指定其继任者。 - 故障隔离： 任务阻塞、第 10 轮评审失败或集成冲突只会停止该特定租约。其工作树和分支会被保留以供排查，其下游依赖不会被调度，而独立的同级租约继续不受影响地执行。
- 资源隔离： 每个租约使用独立的端口、数据库名称和缓存。需要排他性资源的里程碑仅串行化其验证步骤，而不串行化代码实现。
被否决的方案¶
| 方案 | 被否决的原因 |
|---|---|
| 使用合并提交（Merge commits）集成租约 | 违反已授权的快进集成及线性提交历史 |
| 减少声明的影响以换取并行度 | 剥夺了真实的规范协调义务；GOAL.md 将声明的影响映射视为最低要求 |
| 对影响列表进行传递约简（Transitive reduction） | 会跳过消费者根据原始生产者实际变更直接进行的协调工作 |
| 在项目内部创建工作树目录 | 污染工作区，导致 API 运行器报错，干扰测试发现并产生冗余文件 |
| 仅依靠自由文本总结进行协调 | GOAL.md 明确要求根据“真实存在的代码实现”进行协调 |
| 仅在隔离环境中评审，集成后再评审一次 | 产生两套无统一计数属主的门禁；且隔离评审无法发现集成冲突 |
| 从任务行推断写入范围 | 任务行不会可靠地列出文件路径；写入范围必须显式声明 |
| 使用环境变量传递并发度 | 目标输入字段能确保授权完整记录在启动任务的请求本身中 |
模型策略与租约证据保留¶
可选的 MODEL_POLICY 将普通工作、协调与修复交给 DEFAULT，
将每轮整个里程碑评审交给新的只读 WHOLE_MILESTONE_REVIEW 智能体。
每份简报都携带完整解析策略、主导请求、批准背景、缩小后的有效授权、明确任务、固定基线、此前发现与持久化轮次。
评审员没有修改权限，只有所有者汇总报告并写状态账本。模型、强度或新智能体能力不可用时暂停受影响工作；省略策略时沿用宿主设置。
A/B/C 三部分分别说明规划边界与执行选择，并不是模型策略的三个层级。
普通收尾清理和恢复清理都须检查被忽略的文件，以及跟踪和未跟踪的变更。
Git 即使没有 --force 也能删除含有被引用但已忽略证据的干净工作树。
冻结退役记录前，将必需的资格、引用及恢复证据保留到获准的持久位置，核对内容哈希并更新可维护引用，确认删除租约后仍可访问。
不得为了清理而改写冻结记录。保留、所有权或引用不确定时保留工作树；仅删除已确认可丢弃的产物。
原有收尾、集成、所有权、无活动写入者、分支已合入、工作树干净及禁止强制删除等条件仍全部适用。