terminal-bench-loop

Terminal-Bench 循环

一项可重复的操作技能，用于通过 Paperclip 驱动单个 Terminal-Bench 问题，直到 smoke 测试通过；其中明确规定了 issue 拓扑、有限运行次数、以看板为门槛的产品修复，以及工作树连续性。

这项技能属于操作与诊断，而非工程。它会围绕 Terminal-Bench 循环协调 issue、产物和审批，但不授权更改代码——每项获准的产品修复都必须在看板确认后，作为单独的实现子 issue 落地。

规范执行模型：在开始循环或移动任何循环 issue 前，阅读 doc/execution-semantics.md。每个循环 issue 都必须处于该文档允许的状态：终态（done/cancelled）、明确正在进行（运行已启动 / 已排队唤醒）、明确等待中（in_review，且有参与者 / 交互 / 审批待处理），或明确处于恢复 / 阻塞状态（blocked，且有 blockedByIssueIds 和指定负责人）。

适用场景

当任务标题或正文符合以下任一条件时触发：

• “run Terminal-Bench in a loop”、“loop <task-name> through Paperclip”
• “drive Terminal-Bench fix-git”、“iterate on Terminal-Bench until it passes”
• “Terminal-Bench smoke loop”、“bench loop”、“smoke loop on <task-name>”
• 附有 Terminal-Bench 循环父 issue 的链接，并要求再迭代一次

如果用户交给你一个现有的顶层循环 issue，并要求进行下一轮迭代、诊断或重跑，也使用此技能。

不适用场景

• 任务是构建或更改 paperclip-bench 本身（Harbor 适配器、封装程序、遥测）。请在该仓库中使用常规工程流程。
• 任务是提交用于排名的基准测试结果。此技能有意生成 smoke / 不可比较的运行结果——完整测试套件或可比较的运行应升级交由 BenchmarkQualityManager 处理。
• 任务是常规的 Paperclip 产品 Bug，且并非由 Terminal-Bench 循环发现。请使用常规调查流程。
• 你未获准安装或分配公司技能，而请求者实际希望修改技能库。请将这一步交给有权限的技能库负责人。

必须遵守的三项不变量

每轮循环和每项拟议的产品修复都必须同时满足以下三项不变量。它们源自 /diagnose-why-work-stopped，且用户在活跃性相关工作中曾多次重申：

1. 工作持续推进。 每个循环 issue 都必须始终有明确的下一步行动负责人——Agent、看板、用户或指定的阻塞责任方。不得出现没有任何待处理事项的静默 in_review。
2. 只有真正的阻塞才会停止工作。 只有确实无法继续的情况才会导致停止（看板确认、QA、缺少凭证、预算用尽）。必须发现并妥善处理伪阻塞。
3. 避免无限循环。 迭代次数、实际耗时预算，以及应用产品修复前的看板门槛，共同确保循环有界。

如果拟议的迭代违反任何一项不变量，就放弃或重新设计。在循环 issue 中明确说明本轮如何满足每项不变量。

输入

在第 1 轮迭代前，将以下信息收集到顶层循环议题中。任何无法提供的输入都是阻塞项——注明解除阻塞的负责人并停止。

• 源议题。 提出该循环请求的 Paperclip 议题。循环父议题需链接回此议题。
• Terminal-Bench 任务名称。 单任务标识符（例如 terminal-bench/fix-git）。多任务套件不在此技能范围内。
• 迭代预算。 循环必须停止且不再继续修复前的最大迭代次数（通常为 3–5 次）。还要记录每轮迭代的最长耗时。
• Paperclip App 工作树议题。 Paperclip App 项目中负责实现的议题，其执行工作区拥有隔离的工作树。第 1 轮迭代创建此议题；后续迭代通过 inheritExecutionWorkspaceFromIssueId 或等效方式复用它。
• 基准测试命令。 确切的 paperclip-bench 调用，包括绑定到待测 Paperclip App 工作树的 PAPERCLIPAI_CMD（或等效绑定）。在循环议题中原样记录。
• 派发运行器配置。 使冒烟测试实际启动 Paperclip 心跳所需的 Harbor/Paperclip 运行器派发配置。对于当前 Harbor 封装器，原样记录 PAPERCLIP_HARBOR_RUNNER_CONFIG JSON（或等效配置文件），以保留以下内容：assignee、heartbeat_strategy、agent_adapter / agent_adapters、在有意需要本地凭据时使用的 reuse_host_home，以及停止预算。一个只创建未分配给任何人、状态为 todo 的 BEN-1，且没有启用心跳的 Agent 的 Harbor 命令，属于测试框架/设置失败，而非有效的产品诊断。
• 最新产物根目录。 paperclip-bench 写入运行产物（清单、results.jsonl、Harbor 原始作业文件夹、脱敏遥测数据）的文件系统或存储路径。每轮迭代追加内容；不覆盖任何内容。
• 审批政策。 在实现前必须接受拟议产品修复的人（默认：董事会通过 request_confirmation；若已委派则由 CTO 负责；绝不能由循环驱动程序单独决定）。

在顶层循环议题中记录每项输入（在描述中或专用的 inputs 文档中）。如果循环进行期间任何输入发生变化，请注明变更内容及其生效的迭代轮次。

议题拓扑

循环必须以树形结构表示，不能只写在评论中：

• 顶层循环议题。 长期存在。保存输入、迭代计数器、当前状态、指向每个迭代子议题的链接，以及产品规则历史。迭代运行期间保持 in_progress；仅当类型化等待方直接位于循环父议题上时才设为 in_review（执行策略参与方、request_confirmation / ask_user_questions / suggest_tasks 交互、审批或具名人工负责人）；当子议题是阻塞工作时设为 blocked，并填写 blockedByIssueIds（持有修复提案 request_confirmation 的迭代子议题，或实现、QA、CTO 审查子议题）；通过时设为 done；董事会否决或预算耗尽时设为 cancelled。
• 迭代子议题。 每轮迭代一个。每个子议题都包含：有界运行议题（冒烟测试）、诊断议题（应用 /diagnose-why-work-stopped）、带有 request_confirmation 交互的修复提案文档，以及——仅在提案获接受后——实现、QA、CTO 审查和重新运行子议题。迭代子议题依赖于前序议题，以便执行器按顺序唤醒它们。
• Paperclip App 实现议题。 第 1 轮迭代创建一个全新的 Paperclip App 子议题，其项目政策会生成隔离的工作树。之后每轮迭代的实现/重新运行子议题都通过 inheritExecutionWorkspaceFromIssueId 引用同一执行工作区，以便在同一工作树中修改和测试。

使用 blockedByIssueIds 配置依赖关系，绝不要用“被 X 阻塞”之类的文字描述。当依赖的子议题变为 done 时，执行器会自动唤醒下一个子议题。

流程

0. 阅读当前执行约定

在打开或推进循环之前，先阅读 doc/execution-semantics.md。在分类循环问题状态时，沿用该文档中的术语：live path / waiting path / recovery path；post-run disposition；bounded continuation；productivity review；pause-hold；watchdog。不要自行发明新状态。

1. 打开或复用顶层循环问题

• 如果已提供现有循环问题，请阅读其中的内容：输入、迭代计数器、上次迭代的停止原因、当前 Paperclip App 工作树指针、最新基准测试命令。
• 如果不存在循环问题，请在 Paperclip App 项目（或源问题指向的项目）下创建一个。标题：Terminal-Bench loop: <task-name>。描述需记录上述输入、迭代预算以及源问题的链接。
• 验证工作树指针仍然有效。如果记录的执行工作区已被丢弃（工作树已清理、项目已更改），则循环受阻——指出解除阻塞的负责人（CodexCoder 或 Paperclip App 所有者），然后停止。

2. 打开迭代子问题

• 在循环问题上递增迭代计数器。
• 创建标题为 Iteration N: <task-name> 的迭代子问题。其描述应重述输入并引用循环父问题。如果存在上一次迭代的终态子问题，则将其设为阻塞项，以免执行者同时启动两个迭代。
• 如果递增后的迭代计数器将超出预算，则不要创建子问题。将循环问题移至 cancelled（预算耗尽）；如果需要用户决定是否延长预算，则移至 in_review。

3. 运行有界冒烟测试

• 基准测试命令必须使用被测的 Paperclip App 工作树。将 PAPERCLIPAI_CMD（或等效的命令绑定）设为该工作树内的 CLI 入口点。切勿让冒烟测试针对操作员当前检出的 Paperclip 运行。
• 同一命令块必须包含运行器分发配置，使基准测试问题可执行。对于当前 Harbor 封装器，导出 PAPERCLIP_HARBOR_RUNNER_CONFIG，其中包含预期指派对象、心跳策略、Agent 适配器、凭据／主目录模式以及停止预算。如果省略分发配置，不要将单独的 uvx harbor run ... 视为标准冒烟测试；应将其记录为测试框架／设置遗漏，并使用记录的配置重新运行。
• 使用墙钟时间和 Paperclip 的运行预算控制限制运行时长。如果冒烟测试将超出每次迭代上限，则终止运行并记录截断原因。
• 在迭代子问题或专门的 run 文档中记录：
  • Paperclip 运行 ID 和心跳运行 ID
  • 基准测试运行 ID、清单、results.jsonl 行、Harbor 原始作业文件夹
  • 使用的分发配置（PAPERCLIP_HARBOR_RUNNER_CONFIG 或等效配置），包括指派对象和适配器类型
  • 测试框架报告的准确停止原因（通过、测试框架失败、验证器失败、超时、Agent 放弃、基础设施错误）
  • Paperclip 遥测导出时启用心跳和观察到心跳的 Agent 数量
  • 失败分类类别（任务／模型、Paperclip 产品、测试框架／设置、验证器／基础设施、安全、未明确）
  • 最新制品根目录下的制品路径
• 将迭代标记为 冒烟测试／不可比较。可比较运行不在此技能范围内。

4. 诊断确切的停止点

将 /diagnose-why-work-stopped 模式应用于本次迭代的运行，仅限于此循环 — 不要引入无关的取证模板。具体来说：

• 逐个检查 Paperclip App 工作树下由冒烟测试生成的 Paperclip 问题树节点，找出导致进度停止的确切 (issue, status) 组合。引用证据：运行 ID、评论时间戳、状态转换。
• 将该子树中每个未取得进展的问题归类为确实需要人工／董事会介入、可由 Agent 处理但当前未被分派或已涵盖。
• 说明故障属于任务／模型、Paperclip 产品、测试框架／设置、验证器／基础设施、安全问题，还是尚不明确。明确指出哪些证据属于推断（例如，跨公司的 API 边界阻止直接读取）。
• 如果故障是 Paperclip 产品缺陷，将修复方案表述为一条通用产品规则，并依据上述三个不变量进行检查。如果这条规则会阻止近期一次成功的运行，则缩小规则的适用范围。

将诊断记录为迭代子项上的 diagnosis 文档。暂不提出代码方案。

5. 决定下一步

根据诊断结果，迭代必须且只能以以下一种终止状态结束：

• 通过。 冒烟测试验证器报告通过。推动迭代子项和循环父项进入 QA／CTO 审查流程（步骤 8）。
• 已提出产品修复方案。 已识别 Paperclip 产品缺陷。在迭代子项上编写 plan 文档，提出修复方案，然后进入步骤 6。
• 非产品故障，重试。 故障属于测试框架／设置、基础设施或模型不稳定，迭代预算尚未用尽，且循环驱动程序认为无需更改代码即可重跑并获得有效信息（例如，基础设施暂时故障）。在迭代子项上记录理由，然后进入步骤 7，不执行实现步骤。
• 确实存在阻塞项。 已明确的外部阻塞项（凭据、配额、第三方服务中断、安全审查）。将循环问题移至 blocked，将 blockedByIssueIds 设置为阻塞项问题（必要时创建该问题），并注明负责解除阻塞的负责人。停止。
• 预算用尽或董事会叫停。 迭代预算已用尽，或董事会已拒绝下一项修复方案。将循环问题移至 cancelled，并添加评论，总结运行历史和停止原因。

6. 产品修复前请求董事会确认

当本轮迭代以提议产品修复结束时：

• 更新本轮迭代子任务的 plan 文档，写明提议的契约、三项不变量检查、受影响的 Paperclip 界面，以及分阶段子任务（实现、QA、CTO 审查、重新运行）——但不要创建这些子任务。
• 在本轮迭代子任务（即拥有 plan 文档的同一问题）上发起 request_confirmation 交互，并将其关联到最新的计划修订。幂等键：confirmation:{iterationIssueId}:plan:{revisionId}。将 continuationPolicy 设为 wake_assignee。
• 将本轮迭代子任务移至 in_review。类型化等待项——request_confirmation 交互——直接挂在该子任务上，因此其 in_review 状态合理。评论中链接计划文档并说明待确认事项。
• 将循环父任务移至 blocked，设置 blockedByIssueIds: [iterationChildId]，并在评论中指明负责解除阻塞的董事会（或审批策略指定的其他审批人）。此处不要将循环父任务移至 in_review：类型化等待项挂在本轮迭代子任务上，而非父任务上，因此父任务的等待路径是子任务阻塞。这符合拓扑规则：只有当类型化等待项直接挂在循环父任务上时，循环父任务才处于 in_review。
• 等待接受。如果董事会发布了会更改计划的替代评论，请修订文档，然后在本轮迭代子任务上针对新修订发起新的确认；先前的确认随即失效。循环父任务的 blockedByIssueIds 已指向本轮迭代子任务，因此无需更改。
• 如果被拒绝，请按照预算或董事会停止规则结束循环；不要悄悄重试同一提案。
• 如果被接受，请创建实现、QA、CTO 审查和重新运行子任务，并按顺序设置 blockedByIssueIds；同时更新循环父任务的 blockedByIssueIds，使其指向新的门控子任务（通常是实现子任务），让父任务继续因实际的下游工作而处于 blocked。实现子任务必须继承 Paperclip App 的执行工作区（将 inheritExecutionWorkspaceFromIssueId 指向拥有工作树的问题），确保修复落在 smoke 测试所使用的同一隔离工作树中。

7. 在同一工作树中重新运行

实现和 QA 完成后（或在非产品故障且需要重试的情况下立即），重新运行子任务会使用相同的 paperclip-bench 调用，并继续将 PAPERCLIPAI_CMD 固定到受测的 Paperclip App 工作树。

• 重新运行必须使用修复实际落入的同一工作树。如果两轮迭代之间重置了工作区，则循环无效——在循环问题上创建一个阻塞项并停止。
• 完成后，重新运行子任务将成为下一轮迭代的运行记录。如果 smoke 测试现在通过，请跳至第 8 步。否则，返回第 4 步并创建新的本轮迭代子任务（受迭代预算限制）。

8. 通过：QA、CTO 审核并关闭

冒烟测试通过后：

• 如果 QA 和 CTO 审核尚未位于依赖链中，则创建对应的子任务（CTO 审核依赖于 QA，因此依赖链会按顺序启动）。将循环父任务移至 blocked，并将 blockedByIssueIds 设置为 QA / CTO 审核链，同时发布评论，指出 QA 和 CTO 是解除阻塞的负责人，并链接到子任务。循环父任务应保持 blocked，而非 in_review，因为有类型的等待者位于子任务上，而非父任务上。
• 如果希望循环父任务在此阶段本身处于 in_review（例如，某位看板用户已明确自愿推动审核），则应直接在父任务上设置有类型的等待者——执行策略参与者、request_confirmation / ask_user_questions / suggest_tasks 交互、审批或指定的人类负责人——而不能只依赖子任务链。不要让父任务处于 in_review，同时又让 QA / CTO 子任务充当阻塞项；本技能正是为了避免这种含糊的审核状态而存在。
• QA 验证制品（清单、results.jsonl、Harbor 原始作业、脱敏遥测数据），并验证基于同一工作树的重新运行是否可复现。
• CTO 审核循环期间落地的任何产品修复的技术范围。
• QA 和 CTO 接受后，以看板级摘要评论关闭循环问题：任务名称、迭代次数、停止原因（通过）、工作树指针、最终制品根目录链接，以及已接受的产品修复列表（每项都附上其实现问题 ID）。

9. 停止规则

出现以下任一情况时，循环必须停止，并在循环问题上明确记录状态：

• 通过。 冒烟验证器报告通过，且 QA 和 CTO 接受（第 8 步）。循环问题 → done。
• 看板拒绝。 看板拒绝某项修复提案，且未要求修改。循环问题 → cancelled。评论中应指出被拒绝的提案及原因。
• 达到迭代预算。 迭代计数达到预算，但仍未通过。循环问题 → cancelled（如果需要由用户决定是否延长预算，则设为 in_review）。绝不能悄然开始第 N+1 次迭代。
• 明确指出实际阻塞项。 外部阻塞项（凭据、配额、基础设施、安全、缺失技能）无法由循环负责人解决。循环问题 → blocked，并将 blockedByIssueIds 指向阻塞问题，同时注明负责解除阻塞的人。

循环绝不能只以一条文字评论结束。每次停止都必须伴随状态转换，并明确指定下一步行动负责人。

工作树规则

循环不得测试当前心跳碰巧使用的 Paperclip 检出目录。它必须测试应用所提修复的同一个隔离式 Paperclip App 工作树。

• 首次迭代会创建 Paperclip App 实现子任务；该项目的 git-worktree 策略会生成一个全新的工作树。
• 循环问题应记录拥有该工作树的问题 ID 和工作区路径（或工作区 ID）。
• 后续每个实现、QA 和重新运行子任务都应将 inheritExecutionWorkspaceFromIssueId 设置为拥有该工作树的问题 ID，以确保循环后续的所有工作共用一个工作区。
• 基准测试命令始终会将 PAPERCLIPAI_CMD（或等效的命令绑定）设置为该工作树中的 CLI 入口点，并附带记录的派发运行器配置（PAPERCLIP_HARBOR_RUNNER_CONFIG 或等效项），以便分配基准测试问题并启动心跳。循环问题中存储的基准测试命令是唯一可信来源——如果心跳需要在不同的 shell 中运行冒烟测试，它必须逐字复制记录的命令块，而不能只复制 Harbor 调用行。
• 如果工作区被清理，或工作树路径不再有效，则循环无效，直至重建。将循环标记为 blocked，并注明负责解除阻塞的人（通常是 CodexCoder 或 Paperclip App 负责人）。

活跃性规则

每个循环问题在每次心跳结束时，都必须处于以下状态之一：

• 终态： done 或 cancelled。不再采取后续操作。
• 明确处于活动状态： in_progress，且有正在运行的任务、即将触发的排队唤醒，或有正在执行的子问题。
• 明确处于等待状态： in_review，且有明确类型的等待对象——执行策略参与者、request_confirmation / ask_user_questions / suggest_tasks 交互、审批，或指定的人类负责人。
• 明确处于恢复 / 阻塞状态： blocked，且已设置 blockedByIssueIds，指向真实的阻塞问题；此外还需添加评论，写明负责解除阻塞的人及所需操作。

如果循环问题在退出时不符合上述任何一种状态，则心跳尚未完成。退出前修正状态。

注意事项

• 对操作人员的 Paperclip 检出目录运行 smoke。 worktree 规则的核心在于，基准测试针对修复实际落入的 worktree。启动运行前，务必设置 PAPERCLIPAI_CMD 并验证路径。
• 遗漏调度配置。 Harbor 运行如果省略 PAPERCLIP_HARBOR_RUNNER_CONFIG（或等效配置），可能会启动 Paperclip 并创建 BEN-1，但该问题仍未分配，且没有启用心跳的 Agent。这不代表 Terminal-Bench 产品信号。保留并重新运行完整命令块，包括受理人和适配器配置。
• 审批前编码。 在委员会确认接受本次迭代的 plan 文档之前，不得创建实现子问题。诊断阶段不得推送代码。
• 跳过近期工作的调查。 提出 Paperclip 产品规则时，先检查过去几天在相关活跃性 / 执行领域已发布的内容。与上周已接受的契约相矛盾的规则会导致返工。
• 把 in_review 当作已完成。 如果循环问题或迭代子问题处于 in_review，却没有参与者、交互、审批或人类负责人，这代表停止而非进展。应将其视为活跃性违规并转交处理。
• 迭代 N+1 未经明确批准。 达到迭代预算后，除非在循环问题上明确记录了预算扩展，否则绝不启动下一次迭代。
• 可比运行偏移。 此技能只生成 smoke 运行。如果提问者想提交可比基准测试，请转交给 BenchmarkQualityManager 和 BenchmarkForensics——不要把 smoke 重新标记为可比运行。
• 递归恢复。 恢复自身恢复问题的搁置工作，是典型的无限循环。如果诊断在 smoke 的子树中发现此问题，请拒绝继续深入，并转交至 /diagnose-why-work-stopped，以修复产品规则。
• 修改技能库。 此技能绝不会在循环迭代中安装、编辑或分配公司技能。技能库变更应通过单独的问题交给获授权的技能库负责人处理。
• 隐藏链路。 不得静默删除或隐藏失败的迭代子问题、撤回的提案或被拒绝的确认。审计记录是循环的依据。

Verification checklist (before exiting a heartbeat that touched the loop)

• 所有输入均已记录在顶层循环 issue 上，包括确切的基准测试命令、PAPERCLIPAI_CMD 绑定和调度运行器配置。
• 迭代计数器已更新且未超出预算。
• Paperclip App 工作树指针仍可解析，且该迭代的运行、实现和重跑子项共用该工作区。
• 已捕获冒烟测试运行的运行 ID、清单、results.jsonl、Harbor 原始作业文件夹和停止原因。
• Paperclip 遥测显示基准测试 issue 已分配，且心跳已启用或已观察到；或者该迭代被明确归类为无调度的测试框架／设置问题。
• 诊断遵循 /diagnose-why-work-stopped 模式，对每个未取得进展的 issue 进行分类，并检查三个不变量。
• 未经批准的修复提案没有实现子项；如果已提出修复提案，则针对最新计划版本有一个待处理的 request_confirmation。
• 每个循环和迭代 issue 均处于终止状态、明确标记为进行中、明确标记为等待，或处于已命名的阻塞状态。
• 如果循环在本次心跳期间停止，停止原因必须是通过、看板拒绝、预算耗尽或已命名的实际阻塞因素之一。
• 本次心跳期间未修改任何公司技能库。

确定性冒烟测试

安装或更改技能后，在将其用于实时 Terminal-Bench 循环之前，运行此冒烟测试：

pnpm smoke:terminal-bench-loop-skill

该命令使用 PAPERCLIP_API_URL、PAPERCLIP_API_KEY 和 PAPERCLIP_COMPANY_ID 中当前的 Paperclip API 令牌和公司。当设置了 PAPERCLIP_TASK_ID 时，它会将冒烟测试 issue 挂接到该源 issue 下，并继承其项目／目标上下文。默认情况下，验证后会取消短期冒烟测试 issue；传入 -- --keep 可保留已验证的 blocked 循环父项、in_review 迭代子项和待处理确认，以供手动检查。

此冒烟测试具有确定性，且有意不用于比较。它不会启动 Terminal-Bench、Harbor、Agent 模型或提供方运行时。它只验证控制平面的结构：

• 本地 .agents/skills/terminal-bench-loop/SKILL.md 包含循环约定中的术语；
• 可以创建顶层循环 issue，并将其更新为阻塞状态；
• 可以在循环父项下创建迭代子项 issue；
• 模拟的基准测试产物路径已记录在 run 文档中；
• diagnosis 文档指出了确切的停止点和下一步行动负责人；
• 已创建 request_confirmation 交互，且迭代子项处于 in_review，并具有明确类型的等待路径，而非默默等待审核。