fable-execute

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Fable Execute

Implement one accepted change without turning a bounded card into an unreviewable wandering session.

实现一项已确认的变更，同时避免将范围有界的工作卡变成无法审查的漫无目的执行会话。

Mission

使命

Execution owns implementation, not architecture discovery. The agent should make the smallest coherent change that satisfies the accepted card, keep invariants visible, validate immediately, and stop when new facts invalidate the plan.

"Minimal" means minimal behaviorally complete diff, not necessarily the fewest changed lines.

执行阶段负责实现，而不是架构探索。Agent 应进行满足已确认工作卡的最小连贯变更，让不变量保持清晰可见，立即验证，并在新事实使计划失效时停止。

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

Activate When

适用条件

scope and acceptance are explicit;
load-bearing architecture/external facts are settled;
the card can be implemented without inventing a new public contract;
the task is a bounded static/config/docs change where TDD adds no meaningful proof;
a TDD Skill has already established RED and implementation is ready.

范围和验收标准明确；
关键架构/外部事实已经确定；
无需创造新的 public contract 即可实现工作卡；
任务是有界的静态代码、配置或文档变更，TDD 不会提供有意义的证明；
TDD Skill 已经建立 RED，并且可以进入实现阶段。

Do Not Activate When

不适用条件

a behavior change still needs a valid RED (
```
fable-tdd
```
);
implementation reveals a new architecture decision (
```
fable-plan
```
);
a repeated failure needs diagnosis (
```
fable-recover
```
);
the task is to independently verify or review an existing diff (
```
fable-verify
```
/
```
fable-review
```
).

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

Change Classification

变更分类

Before editing, classify the card:

Change	Execution concern
Local behavior	preserve surrounding contract
Config/manifest	precedence, generated source, packaging
Public API/CLI	compatibility and caller impact
Data/persistence	transaction/migration invariant
Generated output	edit source/generator, regenerate once
Dependency wiring	lifecycle/cleanup/error propagation
Repair after TDD	satisfy RED without widening behavior
Repair after review	fix only grounded finding + affected proof

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

变更	执行关注点
本地行为	保持周边 contract 不变
配置/manifest	优先级、生成源、打包
Public API/CLI	兼容性和调用方影响
数据/持久化	事务/迁移不变量
生成产物	修改源文件/生成器，只重新生成一次
依赖装配	生命周期、清理、错误传播
TDD 后修复	满足 RED，同时不扩大行为范围
评审后修复	仅修复有明确依据的发现及受影响的证明

Protocol

协议

Stage 1 — Re-read the card against current workspace

阶段 1 — 根据当前工作区重新核对工作卡

Confirm:

objective;
owned scope;
prohibited scope;
dependencies/assumptions;
acceptance evidence;
current git/workspace state.

If the workspace changed since planning in a way that invalidates assumptions, stop and replan rather than force the old card through.

确认：

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

如果工作区在规划后发生了变化，并导致原有假设失效，应停止并重新规划，而不是强行推进旧工作卡。

Stage 2 — Inspect before mutation

阶段 2 — 修改前进行检查

Read the exact target code and its immediate contracts/callers/tests. Avoid broad rediscovery, but do not edit from stale memory.

Identify invariants that must stay true during the change.

读取准确的目标代码及其直接相关的 contract、调用方和测试。避免大范围重新探索，但也不要凭过时记忆直接编辑。

确定变更过程中必须始终成立的不变量。

Stage 3 — Choose the smallest coherent mutation

阶段 3 — 选择最小连贯变更

Prefer:

existing repository patterns;
source-of-truth over generated output;
local compatibility over speculative abstractions;
reversible changes when uncertainty remains;
one behavior change at a time.

优先采用：

仓库中已有的模式；
修改 source-of-truth，而非生成产物；
局部兼容，而非推测性抽象；
在仍存在不确定性时采用可逆变更；
每次只处理一项行为变更。

Stage 4 — Mutate and record impact

阶段 4 — 进行变更并记录影响

Track:

files/surfaces changed;
new/changed contract;
generated artifacts affected;
acceptance command required after this mutation.

If an edit crosses card boundaries, pause and explain why before continuing.

跟踪：

已变更的文件/界面；
新增或变更的 contract；
受影响的生成产物；
本次变更后需要运行的验收命令。

如果某项编辑越过工作卡边界，应暂停并在继续前说明原因。

Stage 5 — Immediate acceptance check

阶段 5 — 即时验收检查

Run the narrowest meaningful acceptance evidence as soon as the coherent mutation exists.

A command exit code alone is insufficient if it does not exercise the changed behavior.

一旦形成连贯变更，立即运行范围最窄且有意义的验收证据。

如果命令没有实际触发变更后的行为，仅凭退出码不足以证明通过。

Stage 6 — Classify failure before another edit

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

On failure ask:

expected RED from ongoing TDD?
typo/compile issue introduced by current edit?
incorrect implementation hypothesis?
stale/build/config/harness problem?
hidden dependency/architecture change?

Only make another mutation if the failure provides new information that justifies it.

失败时询问：

是否是正在进行的 TDD 所预期的 RED？
当前编辑是否引入了拼写或编译问题？
实现假设是否错误？
是否存在构建过期、配置错误或 harness 问题？
是否存在隐藏依赖或架构变更？

只有当失败提供了能够证明后续修改合理的新信息时，才继续进行变更。

Stage 7 — Clean the diff

阶段 7 — 清理 diff

Before handoff:

remove debug output/dead experiments;
inspect accidental formatting or generated noise;
verify no unrelated file changed;
regenerate deterministic outputs from source when required;
preserve user-owned concurrent changes.

交付前：

移除调试输出和无用试验；
检查意外的格式改动或生成噪声；
验证没有无关文件被改动；
如有需要，从源文件重新生成确定性输出；
保留用户正在进行的并发更改。

Stage 8 — Handoff for independent verification

阶段 8 — 移交独立验证

Send

fable-verify

card objective;
diff/touched surfaces;
acceptance command/result;
invariants considered;
generated/config impacts;
residual risk and unverified surfaces.

向

fable-verify

提供：

工作卡目标；
diff/涉及界面；
验收命令和结果；
已考虑的不变量；
生成产物/配置影响；
残余风险和未验证界面。

Decision Rules

决策规则

New load-bearing unknown → stop and route to discover/research/plan.
New architecture/public contract decision →
```
fable-plan
```
; do not hide it as implementation detail.
Behavior change with no valid regression test where one is feasible →
```
fable-tdd
```
.
Generated file requested → locate generator/source and mutate source; regenerate output afterward.
Existing user/unrelated changes in target file → preserve them and make the smallest contextual edit; do not reset/overwrite wholesale.
Acceptance fails for a clearly introduced syntax/type error → repair directly, rerun, and keep scope bounded.
Similar implementation hypothesis fails repeatedly →
```
fable-recover
```
; arbitrary "try again" loops are forbidden.
Acceptance command passes but does not exercise the changed path → do not claim card completion; strengthen acceptance or hand off with that gap explicit.

出现新的关键未知项 → 停止，并转入 discover/research/plan。
出现新的架构/public contract 决策 →
```
fable-plan
```
；不要将其隐藏为实现细节。
对于行为变更，若存在可行的回归测试却没有有效的回归测试 →
```
fable-tdd
```
。
请求修改生成文件时 → 找到生成器/源文件并修改源文件；随后重新生成输出。
目标文件中存在用户已有的更改或无关更改时 → 保留这些更改并进行最小化的上下文编辑；不要整体重置或覆盖文件。
验收因当前变更明确引入的语法/类型错误而失败时 → 直接修复、重新运行，并保持范围有界。
类似的实现假设反复失败时 →
```
fable-recover
```
；禁止盲目“再试一次”的循环。
验收命令通过但没有实际执行变更路径时 → 不要宣称工作卡已完成；应加强验收，或明确说明证据缺口后移交。

Invariants

不变量

Card scope does not expand silently.
User/unrelated changes are preserved.
Source-of-truth is edited instead of derived output when applicable.
Every meaningful mutation makes prior verification stale.
No unrelated cleanup is bundled into a repair unless required for correctness.
Acceptance evidence corresponds to the changed behavior.

工作卡范围不会静默扩大。
用户已有的更改和无关更改得到保留。
适用时，修改 source-of-truth，而不是派生输出。
每次有意义的变更都会使先前的验证结果失效。
除非正确性所必需，否则修复中不得夹带无关清理。
验收证据与变更后的行为相对应。

Failure Taxonomy

失败分类

Local implementation defect

本地实现缺陷

Current edit causes a direct syntax/type/assertion failure. Fix within card.

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

Hypothesis failure

假设失败

Code is valid but behavior remains wrong. Revise hypothesis; repeated similar failures route to recovery.

代码有效，但行为仍然错误。修正假设；如果类似失败反复出现，则转入 recovery。

Hidden dependency

隐藏依赖

Correct behavior requires a component/contract outside the accepted card. Stop and replan scope.

正确行为需要已确认工作卡之外的组件或 contract。停止并重新规划范围。

Harness/artifact mismatch

Harness/产物不匹配

Commands execute stale build, wrong env, wrong branch, or generated artifact. Route to recovery when this obscures causal evidence.

命令运行的是陈旧构建、错误环境、错误分支或生成产物。当这会掩盖因果证据时，转入 recovery。

Acceptance weakness

验收不足

Check passes without exercising the change. Strengthen proof before completion.

检查通过，但未实际触发变更。完成前应加强证明。

Concurrent-work conflict

并发工作冲突

Target contains legitimate changes not owned by this card. Preserve them, narrow edit, or coordinate ownership; never overwrite for convenience.

目标中包含不属于该工作卡的有效更改。保留这些更改、缩小编辑范围或协调所有权；绝不能为图方便而将其覆盖。

Anti-Patterns

反模式

"while I'm here" refactors;
editing generated files directly;
broad search/architecture work after execution starts;
retrying the same patch with superficial syntax changes;
replacing an entire user-modified file for a small fix;
accepting a build pass as functional proof when behavior is not exercised;
adding abstraction/configurability not required by the card;
hiding an architecture decision inside implementation.

“顺手”重构；
直接编辑生成文件；
执行开始后开展大范围搜索或架构工作；
仅做表面语法修改，却反复重试同一补丁；
因小修复而整体替换用户修改过的文件；
未实际触发行为时，将构建通过视为功能证明；
添加工作卡并不要求的抽象或可配置能力；
将架构决策隐藏在实现中。

Execution Packet

执行包

text

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

text

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

Completion Criteria

完成标准

Execution completes when:

the accepted behavior is implemented within explicit scope;
immediate acceptance evidence is green or any proof gap is explicitly handed off;
diff contains no accidental/unrelated mutation;
new architecture decisions have not been smuggled into implementation;
the verification specialist has a precise map of what changed and what remains to falsify.

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

已确认的行为在明确范围内得到实现；
即时验收证据通过，或任何证明缺口都被明确移交；
diff 中没有意外或无关的变更；
没有将新的架构决策偷偷混入实现；
验证专员获得了一份精确映射，说明改了什么，以及还有哪些内容需要被证伪。

Progressive Resources

渐进式资源

Deep containment guide:

references/bounded-mutation-and-failure-classification.md

Existing containment reference:
```
references/mutation-containment.md
```
Example:
```
examples/bounded-card-execution.md
```

深度范围收敛指南：

references/bounded-mutation-and-failure-classification.md

现有范围收敛参考：
```
references/mutation-containment.md
```
示例：
```
examples/bounded-card-execution.md
```