grace-multiagent-execute

执行包含多个 Agent 的 GRACE 开发计划，同时确保规划制品和共享上下文保持一致。

前置条件

• 必须存在包含模块契约和实现顺序的 docs/development-plan.xml
• 必须存在 docs/knowledge-graph.xml
• 应存在 docs/verification-plan.xml，其中包含模块本地验证命令和门禁预期
• 如果存在 docs/operational-packets.xml，请将其用作规范数据包和差异参考
• 如果缺少计划或知识图谱，请立即停止，并告知用户在分派大型批次之前自行运行 $grace-plan
• 如果缺少验证计划或其内容仍过于简略，请立即停止，并告知用户在分派大型批次之前自行运行 $grace-verification
• 仅当模块本地验证命令已经存在或能够明确定义时，才优先使用此技能

核心原则

并行处理模块实现，而非架构事实。

• 一名控制者负责共享制品：docs/development-plan.xml、docs/knowledge-graph.xml、docs/verification-plan.xml、阶段状态和执行队列
• Worker Agent 仅负责分配给自己的模块文件和模块本地测试
• 审查者在控制者合并知识图谱和计划更新之前验证模块输出
• 提速应依靠更完善的上下文打包、批量处理共享制品以及限定范围的审查，而不是让 Worker 自行编造架构
• 数据包应足够完善，确保 Worker 无需在执行批次期间重新解读目标
• 控制者的检查点比执行期间频繁介入更重要；应在批次之间修订数据包，而不是寄希望于 Worker 能从含糊的新提示中自行纠正

如果多个 Agent 编辑同一模块、同一共享 XML 文件或同一紧密耦合的部分，这就不属于多 Agent 执行批次。请改用 $grace-execute。

执行配置

除非用户另有要求，否则默认使用 balanced。

safe

• 分派前就拟定的执行批次征求批准
• 对每个模块输出进行契约审查和验证审查
• 每个批次后进行针对性知识图谱同步，并在每个阶段边界进行完整刷新
• 适用于模块新颖、风险较高或涉及不熟悉的集成界面的情况

balanced（默认）

• 在运行开始时解析一次计划和知识图谱
• 除非计划在运行期间发生变更，否则事先就执行安排征求一次批准
• 向 Worker 提供精简的执行数据包，而不是让每个 Worker 重新读取完整 XML 制品
• 由每个 Worker 执行模块本地验证，对每个模块进行限定范围的门禁审查，并按批次或阶段进行批量完整性检查
• 每个批次后进行针对性知识图谱同步；仅在阶段边界、怀疑存在偏差或最终收尾时进行完整刷新

fast

• 仅适用于代码库成熟、验证充分且架构稳定的情况
• 整个运行只征求一次批准；除非出现阻塞问题或计划变更
• 保持 Worker 数据包精简，仅要求精确执行范围所需的最低限度上下文
• 批次期间仅因关键的限定范围审查问题而阻塞，随后在阶段结束或最终收尾时批量进行深入完整性审计
• 仅在阶段完成或最终核对时进行完整刷新

每个模块仍必须使用一个全新的 Worker。不要通过跨模块复用 Worker 会话来优化此工作流。

流程

步骤 1：一次性构建执行波次

每次运行时读取一次 docs/development-plan.xml、docs/knowledge-graph.xml 和 docs/verification-plan.xml，然后构建控制器视图中的执行队列。

1. 解析待处理的 Phase-N 和 step-N 条目

2. 将步骤分组成可安全并行的波次

3. 只有满足以下条件，步骤才可安全并行：

   • 其所有依赖项均已完成
   • 与波次中的其他每个步骤具有不相交的写入范围
   • 不需要共同修改同一集成界面

4. 选择执行配置：safe、balanced 或 fast

5. 为每个波次中的每个模块准备精简的执行包，其中包含：

   • 模块 ID 和用途
   • 目标文件路径和精确的写入范围
   • 项目有定义时，从 docs/technology.xml 摘取的首选技术栈或工具
   • 从 docs/development-plan.xml 摘取的模块契约
   • 从 docs/knowledge-graph.xml 摘取的模块图条目
   • DEPENDS 中每个模块的依赖契约摘要
   • 从 docs/verification-plan.xml 摘取的验证内容，包括模块级命令、必需场景、必需日志标记和目标测试文件
   • 写入范围内仍可接受的假设或未解决的关联
   • 应立即停止工作器的停止条件或重新规划触发条件
   • 修复或审查循环的重试预算
   • 合并后将运行的波次级集成检查
   • 预期图变更字段：导入项、公共导出项、公共注解和 CrossLinks
   • 预期验证变更字段：测试文件、命令、标记和阶段后续说明

   如果存在 docs/operational-packets.xml，则按照规范的 ExecutionPacket、GraphDelta 和 VerificationDelta 模板构建执行包和变更提案。

向用户展示拟定的波次、所选配置和各执行包的范围。在 safe 配置下，每次派发前都要等待批准。在 balanced 和 fast 配置下，预先批准一次即可，除非计划发生变化。

步骤 2：分配所有权

派发前，明确界定所有权：

• 控制器：
  • 负责 docs/development-plan.xml
  • 负责 docs/knowledge-graph.xml
  • 负责 docs/verification-plan.xml
  • 负责波次执行包、阶段完成情况，以及涉及共享制品的提交
• 工作器 Agent：
  • 负责一个模块或一个明确界定的切片
  • 只能编辑该模块的源文件和模块级测试
  • 不得直接更改共享规划制品
• 审查 Agent：
  • 只读验证契约合规性、GRACE 标记、导入项、图变更准确性和验证证据

如果工作器发现需要新增缺失模块或依赖项，应停止该工作器，并在继续之前请用户修订计划。不得允许架构在未声明的情况下偏离。

第 3 步：每轮次派遣新的工作 Agent

对于每个已批准的轮次：

1. 为每个模块派遣一个新的工作 Agent
2. 每个工作 Agent 只能获得执行数据包及其写入范围内的文件
3. 要求工作 Agent：
   • 使用数据包中的模块契约和验证摘录生成或更新代码
   • 保留 MODULE_CONTRACT、MODULE_MAP、CHANGE_SUMMARY、函数契约和语义块
   • 在函数签名和文档字符串/注释上方放置 START_CONTRACT/END_CONTRACT
   • 仅添加或更新模块本地测试
     • 为关键分支保留或添加必需的稳定日志标记
     • 仅运行模块本地验证
     • 返回简短的检查点报告：保留的假设、运行的命令、捕获的证据，以及是否消耗了任何重试额度
     • 模块本地验证通过后提交工作，格式如下：

       grace(MODULE_ID): <描述所完成工作的祈使动词短语>
       
       <文件|函数|导出项> <名称>：<更改内容及原因>
       <文件|函数|导出项> <名称>：<更改内容及原因>
       

       每条提交说明都必须列出发生变更的具体文件、函数或导出项，并解释对每项所做的更改。禁止使用“强化 X”“添加 Y 证据”或“强制执行 Z”等笼统措辞。应优先采用具体描述，例如“在 loadPivvConfig 中捕获 ENOENT 并抛出 CONFIG_NOT_FOUND”“为 memory-store.reuseRecord 添加去重键冲突回归测试”或“防止写入阶段的转录内容发生部分刷新”。 让每个检查点提交聚焦于单一、连贯的更改，使提交历史读起来像一段叙事。
   • 返回结果数据包，其中包含变更的文件、验证证据、图谱差异提案、验证差异提案、提交哈希和任何集成假设

工作 Agent 的共享产物规则：

• 执行数据包可以包含用于实现的本地文件头详细信息
• 图谱和计划差异只能涵盖公共模块契约/接口变更，不得涵盖私有辅助代码的变动

第 4 步：以最小安全范围进行审查

每个工作 Agent 完成后：

1. 针对变更的文件和执行数据包进行范围限定的契约审查
2. 针对模块本地测试和验证证据进行范围限定的验证审查
3. 仅在以下情况下升级为完整的 $grace-reviewer 审计：
   • 怀疑存在跨模块偏差
   • 图谱差异与数据包或实际导入内容相矛盾
   • 验证差异与数据包或实际测试/日志标记相矛盾
   • 所选配置文件的验证力度不足
   • 到了阶段边界审计的时间
4. 如果发现问题：
   • 让同一个工作 Agent 返回并修复问题
   • 限制修复循环；如果数据包未定义预算，默认每个工作 Agent 最多进行 2 轮审查
   • 除非需要升级审查，否则仅重新运行受影响的审查
5. 只有获批的模块输出才能进入控制器集成

第 5 步：控制器集成与批量图谱同步

轮次中的所有模块获批后：

1. 集成已接受的模块输出
2. 将图谱差异提案统一集中应用一次，更新 docs/knowledge-graph.xml
3. 将验证差异提案统一集中应用一次，更新 docs/verification-plan.xml
4. 每轮更新一次 docs/development-plan.xml 的步骤状态
5. 针对变更的模块和触及的依赖面运行定向 $grace-refresh
6. 如果定向刷新报告了更广泛的偏差，则在下一轮之前升级为完整刷新
7. 如果本轮发现自动化检查力度不足或缺失，则停止运行并告知用户：继续之前，请自行运行 $grace-verification
8. 如果本轮对数据包结构、执行策略或验证深度造成实质性改变，则在派遣下一轮之前运行 grace lint --profile autonomous --path <project-root>

步骤 6：按级别验证

在仍能确保正确性的前提下，选择尽可能小的级别运行验证。

• 工作者级别：模块本地类型检查、Lint、单元测试和确定性的本地断言
• 波次级别：仅对该波次涉及的合并界面进行集成检查
• 阶段级别：完整测试套件、完整完整性审计，以及最终的图谱与验证对账，然后再将阶段标记为完成

除非风险状况有此要求，否则每个模块成功后都不要运行全仓库测试和全仓库图谱扫描。

步骤 7：控制器提交共享产物并汇报

每个波次结束后，控制器仅提交发生变化的共享产物：

• 根据波次结果更新 docs/knowledge-graph.xml、docs/verification-plan.xml 和 docs/development-plan.xml
• 按以下格式提交：

  grace(meta): sync <artifacts updated> after wave N
  
  <module-id>: <what changed in the graph/plan/verification for this module>
  <module-id>: <what changed in the graph/plan/verification for this module>
  

  只列出共享产物条目确实发生变化的模块，并说明更新内容（例如：“M-CONFIG：标记 step-1 已完成，将公共导出添加到图谱中”）。没有变化的模块不列出。

工作者已在步骤 3 中按模块完成实现提交。控制器仅提交共享规划产物。

每个波次结束后，汇报：

=== WAVE COMPLETE ===
Wave: N
Profile: safe / balanced / fast
Modules: M-xxx, M-yyy
Approved: count/count
Graph sync: targeted passed / targeted fixed / escalated to full refresh
Verification: module-local passed / wave checks passed / follow-up required
Remaining waves: count

调度规则

• 每次运行仅解析一次共享 XML 产物，除非计划发生变化
• 优先使用控制器构建的执行数据包，而不是让工作者反复读取原始 XML
• 仅在独立模块之间并行处理，绝不跨越未知耦合关系
• 不要让工作者自行设计新架构
• 不要让工作者并行编辑相同的共享 XML 产物
• 不要跨模块重复使用工作者会话；保持工作者会话全新，并精简数据包
• 为每位工作者指定确切的文件所有权和成功标准
• 验证通过后，工作者必须提交其实现；不要等待控制器
• 控制器只提交共享产物（图谱、计划、验证），不提交实现文件
• 活跃波次期间，优先进行定向刷新和范围审查
• 将完整审查员审计和完整刷新扫描留到阶段边界、怀疑存在偏移或发生严重故障时进行
• 如果验证不足，就放慢速度并切换到 safe，不要假装 fast 是安全的

不适用情况

• 只剩一个模块
• 步骤紧密耦合且共享相同文件
• 计划仍在频繁变更
• 团队尚未定义可靠的模块本地验证流程

当依赖风险高于并行带来的收益时，请使用 $grace-execute 进行顺序执行。