execute-common

Execute 系列控制器方案

build-in-waves、build-by-story 和 build-inline 共享的控制器步骤与运行时状态的统一归处。任务分派与审查见本文件旁的 task-lifecycle.md。当该技能的 Setup 或 After-last 要求时加载。此方案已注册，因此 npx skills add 会将其与 Execute 系列一并复制。

会话预检

在执行任何分派、任何 isolate-workspace / git worktree add，以及进行任何首次生产代码编辑之前，先回答三个问题：

1. 问题跟踪器同步。 首先打开 docs/agents/issue-tracker.md。如果其中指定了跟踪器，请阅读本文件旁边的 tracker-sync.md 并严格遵循：操作员指定的工单必须在任何分派之前在此认领。曾有一次为 #23 构建 haiku 时没有打开该文件，因此工单从未被认领，其 PR 也未关闭。没有文件，或未指定跟踪器 → 工单集为空，继续（未配置是正常情况，不是失败）。

2. 目录占用状态。 读取 requirements.md 中的 Status:，以及匹配的 docs/specs/INDEX.md 行。若 INDEX 缺失 → 说明一次，并建议使用 /configure-repo；只要 requirements.md 存在，仍要写入该文件。 land-branch / realign-spec 负责 Implemented；cut-release 负责 Shipped。每次启动都要执行，包括压缩后恢复时。

   目录状态为 `Approved` 时，不得执行 ISOLATE-WORKSPACE，也不得编辑生产代码。 用户要求先隔离、跳过文档流程或不提交目录文件，都不能覆盖此步骤。

   状态	操作
   Approved	在当前检出中，将两个文件都写为 In-progress，然后继续。
   In-progress	已被占用。不要重复写入。继续。
   Draft	停止——规范尚未获批。
   Implemented / Shipped	保持不变。这不是启动标记。

   隔离之前，提交当前检出中该功能尚未提交的规范文件（requirements.md、design.md、tasks.md、INDEX 行）——如果状态为 Approved，占用状态写入也应包含在该提交中。工作树从 HEAD 创建，因此未提交的规范文档会留在原处，新工作树和其他会话都看不到。isolate-workspace 仍不得提交 .gitignore——占用状态属于此步骤，不属于该技能。

3. 工作区 / 分支。 如果尚未创建隔离工作区：是在工作树中隔离，还是在当前分支上实现？未经请求，不要创建工作树。隔离 → 必需的子技能：使用 isolate-workspace。如果当前分支是 main/master，则实现前需要另行明确征得同意；“不使用工作树”不等于同意修改 main/master。

完成条件：跟踪器选择（或空工单集）已明确，占用状态为 In-progress（或明确因 Draft/Implemented/Shipped 而停止），当前检出中没有该功能尚未提交的规范文件，且工作区选择已明确。

想法	实际情况
“会话预检只检查跟踪器和工作区”	占用状态是问题 2；工作区是问题 3。只有包含 In-progress 才算完成。
“他们禁止的是在 main 上提交文档”	其他会话会读取当前检出中的 INDEX。隔离必须在写入启动标记之后进行。
“从工作树 / 功能分支就能看出占用状态”	在当前检出中运行的会话仍会读到 Approved。INDEX 才是占用状态信号。
“之后 land-branch 会将状态改成 Implemented”	Implemented 表示收尾。In-progress 是启动标记，必须在创建工作树之前写入。
“等到合并时再让 INDEX 保持 Approved 也没关系”	其他会话无法看到此 CODE 正在执行。任务 1 之前就要写入标记。
“不用工作树——那就跳过文档流程”	不选择隔离并不意味着可以跳过占用状态更新。
“已经是 In-progress——立即隔离”	先读取 Status；跳过写入，不要跳过检查。恢复时仍要在隔离前读取 Status。
“用户禁止提交文档 / 要求先隔离——这可以覆盖占用状态更新”	占用状态不可豁免。只有当前检出读到 In-progress 后才能隔离。
“规范文件已经在磁盘上——工作树也能看到”	git worktree add 会复制 HEAD。未提交的 requirements.md / 三件套文件会留在原处。

运行时绑定和租约预检

首次派发前（内联路线：首次生产性编辑前）， 请阅读本文件旁的 runtime-binding.md 并严格遵循其中的要求。该文件定义 .skills/<CODE>/execution-session.json 架构（schema_version、harness、 provider、model、resume/fork/worktree support、cache_control、token_telemetry、 pricing_policy、effective_concurrency、rotations）、四种租约轮换触发条件、 pricing-policy 回退规则，以及并发降级规则。

完成条件：派发前已存在运行时快照，所有不可用的能力均已明确说明，并已记录首次生效的并发/租约决策。

台账检查

阅读本文件旁的 ledger-check.md 并严格遵循其中的要求：.skills/ 保持 仅本地可用，从 .skills/<CODE>/progress.md 恢复，记录任务门槛所依据的 lint 基线，并且 Verified: 栏由 prove-claim 填写。

完成条件：已明确下一个任务/单元，并已记录 Lint baseline:。

决策轨迹 — 可观测条件

当用户要求提供决策轨迹/展示工作过程，或任务需无人值守地运行一夜/ 多天，或 effective_concurrency > 1 且存在多个未完成单元时 → 阅读 本文件旁的 decision-trail.md 并严格遵循其中的要求；否则在关闭备注中写入 skip: no decision-trail predicate。

待办事项 — 门槛

在任何派发或任务 1 开始前，先在可见列表中列出待办事项——使用 harness 的待办/任务列表工具（如有），否则将清单写入回复，并在每个任务边界 重述：每个任务对应一个待办事项，并且 添加一个终止待办事项 Close branch（即下方的关闭序列——现在创建， 而不是之后创建）。只有在已知某项润色条件成立时（用户预先提出要求），才添加 Polish Diff 待办事项。否则，如果在关闭序列第 3 步时满足润色条件， 则在该步骤创建 Polish Diff 待办事项。

完成条件：列表与计划一致，并且包含 Close branch 待办事项。

Close 流程

完成最后一项任务（waves / inline）或最后一个解锁单元（story）后：

1. 审查整个分支。 必需子技能：使用 inspect-change，并将 base 设为 git merge-base <branch-base> HEAD——绝不能使用分支中途的 sha。 <branch-base> 为 main，或当工单堆叠在某个阻塞工单之上时使用该阻塞工单的分支（deliver-issues）：堆叠工单若对照 main 进行审查， 就会重新审查其阻塞工单的 diff，并将该 diff 中的文件计入润色范围。 提供 Minor 项台账。使用最高级别的模型。
2. 一个修复者处理完整的问题清单 → 重新审查。绝不能为每个问题分别安排一个修复者。Inline 路径：你在 test-first 下担任修复者。
3. 润色 Diff——可观察条件。 根据下文评估润色判定条件。若任一条款为真 → 必需子技能：在验收前对整个分支的 diff 使用 polish-diff；若 Polish Diff todo 尚不存在，现在就创建；只有在该技能运行后才能将其标记为完成。若没有任何条款为真 → 跳过；在 Close branch 备注中写入 skip: no polish predicate。EOD、演示压力、“inspect 很干净”以及“改动小到感觉可有可无”都不是判定条件。
4. 验收。 必需子技能：使用 validate-feature。若有失败 → 执行 root-cause，然后将通过的检查提升为描述领域行为的已提交测试（仅文档主干——测试文件无需包含需求 ID 标签）。
5. 关闭凭证。 加载 close-receipt.md 并遵循其生成流程。只有在最后一次修改之后，且仅基于与该 HEAD 绑定的证据，才能签发。只有在证据缺失或过期时才重新运行生成器。
6. 完成。 必需子技能：使用 land-branch。

只有在步骤 1–6 均已执行，或按其判定条件跳过后，才能将 Close branch todo 标记为完成。

想法	实际情况
“任务 todo 全部已完成——Close 可以稍后再做”	Close branch todo 仍未完成；必须运行完整流程后才能 land
“Inspect 没问题／分支很小——跳过润色”	Inspect 干净和“感觉改动很小”都不是判定条件。统计文件数；检查公共 API；查看 inspect 遗留项
“EOD／演示——跳过 40 个文件分支的润色”	时间压力不是判定条件。文件数才是
“始终运行润色，这样就不会忘记”	对一个三文件的拼写错误安排四个清理 Agent，正是设置此条件机制要避免的成本。跳过时必须写明，绝不能不作记录

Close 流程判定条件

润色——以下任一条件成立时为真：用户要求润色、清理或整理；inspect-change 的 Standards 遗留项中包含一项重要级别或更高、且不改变行为的发现（复用、死代码、不必要的复杂性、浪费 I/O）；git diff --name-only $(git merge-base <branch-base> HEAD) HEAD 列出超过 15 个文件；该分支新增了公共 API 或导出接口。

危险信号——绝不可

• 跳过 tracker-sync、occupancy 或 workspace preflight
• 当目录 Status 仍为 Approved 时隔离或编辑生产文件
• 仅在本次会话创建的 worktree 中写入 In-progress
• 重新盖章已处于 In-progress 状态的行
• 当此 checkout 仍有未提交的规范／需求改动时进行隔离
• 配置缺失或用户拒绝时，擅自创建 tracker 或工单集
• 未经明确同意就在 main/master 上开始实现
• 未经询问就创建 worktree，或将“当前分支”视为对 main/master 的同意
• 在 todo 列表创建之前派发第一个任务（任务和 Close branch 都要包含）
• 无记录地跳过润色（未写入 skip: no polish predicate）
• 无记录地跳过决策轨迹（未写入跳过说明／必需行）
• 将 EOD、演示或“inspect 很干净”视为润色判定条件
• 在 Close branch todo 仍未完成时进入 land-branch
• 写入不完整的凭证，或将其绑定到最后一次修改之前的证据
• 将检查提升为“带 ID 标签的测试”——ID 应保留在文档中