fable-execute

Fable Execute

实现一项已接受的变更，避免将范围明确的卡片变成无法审查、漫无边际的会话。

使命

执行阶段负责实现，而非探索架构。Agent 应做出满足已接受卡片的最小完整变更，让不变量清晰可见，立即验证，并在新事实推翻计划时停止。

“最小”指行为完整的最小差异，不一定是改动行数最少。

适用时机

• 范围和验收标准明确；
• 关键架构和外部事实已确定；
• 无需另行设计新的公共契约即可实现该卡片；
• 任务是范围明确的静态、配置或文档变更，TDD 无法提供有意义的证明；
• TDD Skill 已完成 RED 阶段，现可开始实现。

不适用时机

• 行为变更仍需要有效的 RED（fable-tdd）；
• 实现过程中发现新的架构决策（fable-plan）；
• 需要诊断反复出现的失败（fable-recover）；
• 任务是独立验证或审查现有差异（fable-verify/fable-review）。

变更分类

编辑前，先对卡片进行分类：

变更	执行关注点
局部行为	保持周边契约
配置/清单	优先级、生成源、打包
公共 API/CLI	兼容性和调用方影响
数据/持久化	事务/迁移不变量
生成的输出	编辑源文件/生成器，只重新生成一次
依赖接线	生命周期/清理/错误传播
TDD 后修复	满足 RED，不扩大行为范围
审查后修复	只修复有依据的问题及受影响的验证

协议

阶段 1 — 根据当前工作区重新审阅卡片

确认：

• 目标；
• 负责范围；
• 禁止涉及的范围；
• 依赖项/假设；
• 验收证据；
• 当前 Git/工作区状态。

如果自规划后工作区发生变化，导致假设失效，应停止并重新规划，而不是强行按旧卡片执行。

阶段 2 — 修改前先检查

阅读确切的目标代码及其直接相关的契约、调用方和测试。避免大范围重新探索，但不要依据过时记忆编辑。

确定变更过程中必须保持成立的不变量。

阶段 3 — 选择最小完整的修改

优先选择：

• 仓库中已有的模式；
• 真实源文件，而非生成的输出；
• 局部兼容性，而非推测性的抽象；
• 不确定性尚存时可逆的变更；
• 一次只改动一种行为。

阶段 4 — 修改并记录影响

跟踪：

• 变更的文件/界面；
• 新增或变更的契约；
• 受影响的生成产物；
• 本次修改后必须运行的验收命令。

如果修改超出卡片范围，应暂停并在继续前说明原因。

阶段 5 — 立即进行验收检查

完整修改形成后，尽快运行范围最小且有意义的验收检查。

命令退出码本身并不足够；如果命令没有覆盖变更的行为，就不能算作验收证据。

阶段 6 — 再次编辑前先分类失败

失败时，询问：

• 这是正在进行的 TDD 中预期的 RED 吗？
• 是否是当前编辑引入的拼写或编译问题？
• 实现假设是否有误？
• 是否是过时的构建、配置或测试框架问题？
• 是否存在隐藏依赖或架构变更？

只有在失败提供了足以证明修改合理的新信息时，才进行下一次修改。

阶段 7 — 清理差异

交接前：

• 删除调试输出和无用的试验代码；
• 检查意外的格式改动或生成噪声；
• 确认没有无关文件被修改；
• 必要时从源文件重新生成确定性输出；
• 保留用户同时进行的更改。

阶段 8 — 交接以供独立验证

发送给 fable-verify：

• 卡片目标；
• 差异/改动界面；
• 验收命令/结果；
• 已考虑的不变量；
• 生成内容/配置影响；
• 剩余风险和未经验证的界面。

决策规则

• 出现新的关键未知事项 → 停止并转交发现／调研／规划。
• 出现新的架构／公共契约决策 → 使用 fable-plan；不要将其隐藏为实现细节。
• 行为发生变化，且在可行的情况下没有有效回归测试 → 使用 fable-tdd。
• 要求提供生成文件 → 找到生成器／源文件并修改源文件；之后重新生成输出。
• 目标文件中已有用户修改／无关改动 → 保留这些改动，并结合上下文做最小修改；不要整体重置／覆盖。
• 验收因明显由本次引入的语法／类型错误而失败 → 直接修复，重新运行，并控制范围。
• 类似的实现假设反复失败 → 使用 fable-recover；禁止随意“再试一次”的循环。
• 验收命令通过，但未覆盖变更路径 → 不要声称卡片已完成；应加强验收，或明确说明该缺口后移交。

不变量

• 卡片范围不得在未说明的情况下扩大。
• 保留用户改动／无关改动。
• 在适用时，修改事实来源，而非派生输出。
• 每次有意义的修改都会使先前的验证结果失效。
• 除非正确性所必需，否则修复时不得捎带无关清理。
• 验收证据必须与变更行为相对应。

失败分类

本地实现缺陷

当前编辑直接导致语法／类型／断言失败。在卡片范围内修复。

假设失败

代码有效，但行为仍然不正确。修正假设；类似失败反复出现时，转交恢复处理。

隐藏依赖

正确行为需要卡片已接受范围之外的组件／契约。停止并重新规划范围。

测试框架／产物不匹配

命令运行了过时的构建、错误的环境、错误的分支或生成产物。当这导致因果证据不明确时，转交恢复处理。

验收不足

检查通过，但没有覆盖变更。完成前加强验证。

并行工作冲突

目标包含不属于此卡片的有效改动。保留这些改动、缩小编辑范围，或协调所有权；绝不可为图方便而覆盖。

反模式

• “既然顺手”就进行重构；
• 直接编辑生成文件；
• 执行开始后进行大范围搜索／架构调整；
• 只改表面语法并重复尝试相同补丁；
• 为了小修复而替换整个经过用户修改的文件；
• 行为未受验证时，将构建通过当作功能证明；
• 添加卡片未要求的抽象／可配置性；
• 将架构决策隐藏在实现中。

执行任务包

Card:
Owned scope:
Files/surfaces changed:
Behavior/contract delta:
Acceptance command/result:
Invariants checked:
Generated/config impacts:
Unexpected facts:
Residual risk:
Recommended verify scope:

完成标准

满足以下条件时，执行即告完成：

• 已在明确范围内实现所接受的行为；
• 直接验收证据通过，或已明确移交任何验证缺口；
• 差异中没有意外／无关改动；
• 没有将新的架构决策暗中带入实现；
• 验证专员已获得准确说明，了解哪些内容已变更，以及还有哪些内容需要证伪。

渐进式资源

• 深入了解范围控制指南：references/bounded-mutation-and-failure-classification.md
• 现有范围控制参考：references/mutation-containment.md
• 示例：examples/bounded-card-execution.md