tlc-implement

TLC Implement

冻结义务。释放构建。由未参与构建的人证明。

┌────────┐   ┌───────┐   ┌────────┐
│ CHECKS │ → │ BUILD │ → │ VERIFY │
└────────┘   └───────┘   └────────┘
 obligations   yours       always

编码 Agent 常见的失败，是某项要求从未成为有效义务，却仍然声称已完成。应对之道是设定一小组冻结的外部义务，并由非作者担任验证者，这样预算就能用在这里，而不是花在编排模型上。如何构建由你决定。

输入是经批准的 .specs/features/<feature>/plan.md，来自 tlc-plan——所谓经批准，是指其中包含 **Approved**: <date> - user: "<their words>" 这一行，这是 validate_checks.py 的要求——它就是完整的任务说明：你可能拿不到生成它的任何对话记录。对于大约不超过三个文件、且没有不可逆决策的小改动，无需计划：改为编写带有 ## Intent 段落的 checks.md。其他没有计划的大改动，或包含未解决 blocks 问题的计划，都应退回 tlc-plan。

规则

即使没有读取任何参考文件，这些规则也始终适用。每条规则都写在这里；参考文件会指回这里。

1. 每项检查都是一个可观察的主张，包含一个具体值，以及能够判定该主张的证明：一个由退出码决定结果的测试或命令；或者，对于捕获画面所呈现的状态，则是一张与捕获画面对照评判的图片（规则 9）。
2. 测试应断言检查所说的内容，而不是代码碰巧做了什么。不要通过阅读实现来编写测试。
3. 测试只随它所证明的主张一起更改，并与它所证明的代码在同一个提交中移除。为了让测试套件通过而更改测试，会掩盖测试原本要揭示的失败：检查有误时，应停下并询问。
4. validate_checks.py 通过后，检查即固定；如果 walk 或 Verifier 发现遗漏的义务，可以追加检查。在计划中，Landing、Surface 和存储的形态可以追加；路径和 Changes underneath 必须在更改它们的提交中保持真实。
5. Verifier 必须是全新的子 Agent，绝不能是作者；每项功能都必须运行一次，并与 screens 子 Agent 同时进行。check_proofs.py 负责判定机械部分——每项证明都已运行并在 HEAD 通过、构建、图片、walk、被杀死的变异；Verifier 则专注于判断：错误规则仍会通过的变异、无人提及的示例、比其判定标准更宽松的断言。只有当每项发现都通过提交解决，且 proofs.md 在 HEAD 为绿色时，工作才算完成。
6. 变异数量在 checks.md 中声明（Mutations:，默认值为 3），它决定 Verifier 要探测多少条规则，而不代表工作质量：无论 N 是多少，都必须保证代码质量、每项检查背后的测试，以及完整的 Coverage 关联。检查只是底线；检查未提及的边界情况或防护措施仍属于工作内容。
7. 完成门禁由脚本执行：validate_verification.py 退出码为 0。最终报告以它的最后一行开头；如果门禁未通过，必须先说明，不能留给读者自行发现。
8. 已获批准的计划授权进行本地编辑和本地提交。执行 git push、部署和更改生产数据，需要针对相应操作获得明确许可。
9. 捕获画面呈现的状态必须用一张图片证明。 作者要在浏览器窗口中达到该状态，并以捕获画面的尺寸保存 <capture>.running.png，将其放在捕获画面旁边——这里指像素尺寸除以缩放比例：窗口更宽会改变页面布局，之后再调整图片大小会掩盖这一点。任何人都不得重新打开应用来评判；应由 screens 子 Agent 评判该文件（verify-screens.md），如果图片中的文字看起来比捕获画面中的小，说明图片被调整过大小，必须重新截取。除 ## Differences from the source 列出的差异外，图片必须与捕获画面一致。不由捕获画面呈现的状态，以及功能未更改的现有屏幕，均须通过测试或 walk 证明，不需要图片或评判者。
10. 计划中引用为约束依据的捕获画面、画框或在线站点，只能由用户更改。若要移除、重命名或偏离其所呈现的内容，必须先征求用户意见，并将决定记录在 .specs/STATE.md 中，同时在计划的 ## Differences from the source 中列出，并注明 Confirmed: y - AD-NNN。
11. 文件记录运行状态；聊天内容在上下文压缩后不会保留。 用户在构建期间确认的事项，必须在用户确认的同一轮中写到 checks.md 的 **Settled mid-build:** 行。每个子 Agent 派出前，必须先写到 **Dispatched:** 行。上下文压缩后或在新会话中，应重新阅读此文件和当前阶段的参考文件，然后从文件记录处继续（memory.md）。

配置

项目在 AGENTS.md 或等效文件中声明该值；checks.md 会将数量复制到 Mutations: 行。

## tlc-implement

mutations: 3

部分	运行方式	无法捕获的问题
check_proofs.py（始终运行）	每个运行器在 HEAD 上对每项证明运行一次；每项检查与其筛选器所选的测试相匹配；检查 Build: 命令、图片和演练流程，并注入变异	因错误原因而通过的测试
验证器（始终运行）	在规则所在位置注入 N 个变异、两个无人指定的示例、比其判定标准更宽松的断言，以及与约束性截图相矛盾的检查（verify.md）	未经过变异探测的规则
屏幕子 Agent（判定标准引用了截图时）	将每张截图与作者的图片进行核对，逐行标记为 same 或 differs，并注明 HEAD（verify-screens.md）	间距、颜色和字重；截图中无法显示的细节；截图未展示的画面

截图不进行变异测试；应将 N 用在错误实现代价最高的地方。如果该功能的 N 看起来太低，请用一行说明，并让用户提高数值。

产物

.specs/
├── STATE.md                    # decisions log (AD-NNN)
├── LESSONS.md                  # rendered by scripts/lessons.py - do not hand-edit
├── lessons.json                # machine-owned
└── features/<feature>/
    ├── plan.md                 # from tlc-plan; read, and kept true
    ├── checks.md               # claims + proofs, the coverage join, swept, handoff
    ├── captures/               # binding source files, and the author's <capture>.running.png
    ├── screens.md              # the screens sub-agent's inventory and verdict, per picture
    ├── proofs.md               # written by check_proofs.py: every proof and mutation at HEAD
    ├── mutations.json          # the Verifier's mutations, re-run after the fix
    └── verification.md         # the Verifier's findings, each closed by a commit

阶段

阶段	产出	参考
检查	带有证明的声明、逐项关联的所有集合，以及已检查的九个维度	checks.md
构建	检查中的测试、代码、提交，以及已演练并保存的画面	build.md
验证	规则 5	verify.md、verify-screens.md

决策、续接和经验：memory.md。

脚本

将 <skill-dir> 解析为包含此 SKILL.md 的目录，然后运行 python3 <skill-dir>/scripts/<name>.py。如果 cwd 不是项目根目录，请传入 --root。非零 退出码表示停止并修复。运行脚本，而不是阅读脚本：其消息会说明需要更改什么。

时机	命令
开始构建之前	validate_checks.py <feature>——它也要求计划中有 **Approved**: 行
每次提交之前	check_commit.py --message "<msg>"
派发验证器之前，以及修复之后	check_proofs.py <feature> [--mutations <mutations.json>]
宣布完成之前	validate_verification.py <feature>
编写检查之前，以及门禁通过之后	lessons.py ...
编辑验证器或模板之后	selftest.py

selftest.py 会针对每条门禁规则各变异一次 scripts/fixtures/ 中的固定测试数据，并要求每个变异都被检测出来；这些固定测试数据也是一组通过检查的产物示例。

要求

需要	用途	缺少时
Python 3.8+（仅使用标准库）	每个脚本	门禁无法运行；阶段仍然适用
git	mutate.py 和 check_proofs.py（HEAD、干净的工作树）	不执行变异和 HEAD 检查：请在报告中说明
子 Agent	验证器和屏幕子 Agent	在新会话中运行其文件并写入 self-verified；门禁会发出警告
能读取图片的模型	屏幕子 Agent	将图片和截图交给用户
Agent 可操作的浏览器	保存 <capture>.running.png 和演练流程	将步骤交给用户

测试运行器：check_proofs.py 会将 bun、vitest、jest、pytest 和 go test 各自归为一次运行 （scripts/runners.py）；其他命令各自单独运行，并根据其退出码判定。

输出

生成产物；不要叙述阶段过程。先给出结论，并明确陈述决策。 章节标题保留英文；正文遵循项目惯例；标识符一律不翻译。