close-feature

目的

在生命周期实现协调器关闭后使用此技能。接受与 /start-feature 相同的人工功能选择器。此技能会将已交付的代码转化为经过对账、验证且可审计的产品状态。将 <core-dir> 解析为已安装的 ../dstack-core 技能目录。

共享信任约定

执行此工作流前，请阅读并遵循 ../dstack-core/references/TRUST-AND-AUTHORITY.md。该约定对本工作流具有 规范效力。如果与此技能冲突，请遵循限制更严格的规则并报告冲突。

启动版本证据

在首次修改工作流之前，按照 ../dstack-core/references/SKILL-VERSION.md 中关于 close-feature 的说明操作。完成 只读功能解析后，捕获完整的单行输出，并将其追加到所选根目录的 Beads 备注中，然后再进行对账或交付修改。stale 结果会提示运行 npx skills update；unavailable 则记录未作新鲜度声明，且不会阻止离线工作。

交付权限：

• 调用授权对所选功能进行本地对账、验证、工作流提交以及 Beads 更新。
• 只有显式的 pr 模式授权创建拉取请求。只有显式的 merge 模式授权合并及合并后的工作树移除。ready 和无操作模式均不授权上述操作。
• 默认情况下，合并模式仅授权快进合并。只有当目标仓库的 AGENTS.md 明确说明接受合并提交时，才授权创建合并提交。
• 工作流绝不强制推送、删除远程分支、绕过钩子，或在确认合并前移除工作树。
• 关闭审查的子 Agent 仅可读。
• 合并模式授权对所选功能分子相关的仅追加 .beads/interactions.jsonl 行进行有限对账，并可处理通过仅含 discovered-from 或 parent-child 边的权威依赖关系谱系连接到该分子的、单独标识的工作，以及下文所述的两次仅包含交互记录的工作流提交。绝不授权丢弃、纳入或重写不相关的行或路径。

共享原生 Beads 权限

在进行任何交付修改前，请阅读 ../dstack-core/references/INTERACTION-BOUNDARY.md。原生关联工作树的 Beads 权限是共享的；bd -C 不是隔离边界。在 beads-workflow-lock.py 下运行连续的 Beads 对账和交付修改。在基础工作树中进行任何收尾 Beads 修改前，运行 reconcile-beads-interactions.py preflight；若失败，则只读检查外部行。租约繁忙、存在外部交互记录行或快照竞争，都会阻止交付。必须等受保护的合并后终结器通过后，才能关闭交付或根任务。

支持的操作

• pr：成功收尾后创建拉取请求。
• merge：成功收尾后合并并完成该功能。
• ready：将功能保留为就绪状态，不创建 PR 或合并。
• 无操作：完成收尾，然后请用户选择 pr、merge 或 ready。

执行

1. 激活并检查

运行 bd prime，然后以只读方式解析提供的功能选择器。获取其根 ID 后、执行任何声明、记录或其他变更之前，立即运行 <core-dir>/scripts/migrate-review-topology.py guard --root-id <feature-root>，并指定 --controller-topology-version 3。若标记版本较新或存在尚未迁移的旧评审类型，则必须停止；只有规范主工作树迁移器可以修改拓扑，旧审批不会转移。若未提供选择器，仅在当前活动分支为 feat/<slug> 时根据该分支推断。若当前分支不是功能分支，则停止并要求提供选择器，而不是关闭无关的待办工作：

branch=$(git branch --show-current)
feature_selector=${branch#feat/}  # only when branch matches feat/*
uv run <core-dir>/scripts/resolve-feature.py "<feature-selector>" --json
bd show <resolved-root-id> --json

Beads 操作使用返回的根 ID；工作树、报告和交付命令使用其规范 <slug> 引用。根据根元数据解析 docs_reconcile_id、validation_id、review_implementation_integrity_id、review_delivery_integrity_id 和 delivery_id。仅在元数据缺失时，才查询完整的 molecule 或子项列表以进行修复。激活并验证 feat/<slug>。在判断文档是否准确之前，检查提交、实现、测试和已更改文件。

只有在所有生命周期 ID 均已解析、活动工作树为 feat/<slug>、实现协调器已关闭，且没有未关闭的 migration:reconciliation 任务阻碍收尾后，才能继续。在记录启动版本或执行其他收尾阶段的 Beads 变更之前，解析规范的基础工作树并运行共享交互预检。若预检失败，不作任何变更地检查追加的行，然后停止，并保持交付项和根项未关闭：

uv run <core-dir>/scripts/reconcile-beads-interactions.py preflight \
  --worktree <base-worktree> --root-id <root-id>

2. 协调文档

认领文档协调步骤。将已交付行为与以下内容进行比较：

• 功能的 design.md；
• Documentation Impact 中列出的每个确切页面；
• 实现更改的每个面向读者的页面；
• 相关架构和参考页面；
• docs/src/planned-features.md；
• docs/src/features/index.md；
• docs/src/SUMMARY.md。

创建或更新：

docs/src/features/<slug>/index.md

使用 docs/src/features/_template/index.md。记录必须独立完整；可以链接到 design.md，但不得嵌入 design.md 或旧版 tasks.md。确保设计已登记在 SUMMARY.md 中功能设计标记之间，然后将已实现的记录添加到 SUMMARY.md 和 features/index.md 中已实现功能标记之间。

在协调 bead 中记录已交付行为、有意更改、已纠正的偏差、延期工作、文档路径、提交和证据。

3. 验证

认领验证步骤。将每项必需检查归类为 passed、failed、unavailable、waived 或 not-applicable。根据设计中的验证策略、每个子项的 validation_command、已更改路径的归属、生成内容与文档的一致性，以及后续修复导致失效的检查，构建受影响的功能检查集。运行该检查集；若文档有更改，还要运行 uv run --no-project python scripts/check-docs.py。不要自动运行整个代码库的测试套件；只有设计、代码库交付政策或用户的明确要求有此规定时，才运行该套件。记录确切命令、结果、跳过的检查、限制、经过测试的提交和受影响路径。复用未更改的重点任务证据／遥测，但仅当其记录的源边界适用时，才将结果视为有效。后续的关闭评审修复仅会使受影响的结果失效；必须在批准前重新运行这些检查。所需证据完整且仍然有效之前，不得关闭验证。除非用户明确豁免了确切的检查，否则 unavailable 仍会阻止继续。验证豁免须记录命令、原因、受影响的提交、用户接受该决定的记录以及剩余风险；它不会豁免评审发现的问题。

4. 派生两项直接关闭分配，然后运行两项评审

Beads 是工作流清单。直接从 Beads 和面向读者的文件中读取功能根目录、文档和验证问题、实施协调者、待关闭的审查问题、已实施记录、路线图／导航、当前发现以及专项检查证据。不要创建数据包、收集器、共享上下文或第二份持久化任务清单。

从权威功能工作树中固定一个不可变的 Git 源边界：review_boundary_id、reviewed_commit、reviewed_diff_base、reviewed_diff_digest 和变更路径。在启动前，持久化两个关闭状态及其所属的 review_issue_id、源边界、声明的路径／领域／需求 ID，以及 initial_active。缺失或过期的验证证据会阻止审查。

通过 PI-REVIEWER-ROSTER.md 将 implementation-integrity 解析为 dstack-implementation-reviewer，将 delivery-integrity 解析为 dstack-delivery-integrity-reviewer。名称缺失或不可用时，应在可选的项目本地同步后明确失败；不得静默替换角色。

从所属的 Beads 问题、设计／文档、专项验证和固定的 Git 边界中，推导出两份相互独立的临时任务。实施任务应声明代码和测试路径，并涵盖代码行为是否正确、质量与简洁性、安全性和可维护性。交付任务应声明文档、验证、Beads、已实施记录、路线图／导航、交付声明和偏差路径，并且仅涵盖交付完整性；它应整合此前的交付和偏差证据，但不审查代码。

同时启动恰好两名全新的审查者。每名审查者只接收自己的任务和一个固定的只读工作树；每名审查者都应直接读取指定证据，并在不扩大范围的前提下报告缺失证据。

在每个所属的待关闭审查 Bead 上，使用 ../dstack-core/references/REVIEW-STATE.md 中可执行的审查状态，以及 ../dstack-core/references/REVIEW-FINDINGS.md 中当前未关闭的发现台账。创建确切的审查者集合 ["implementation-integrity", "delivery-integrity"]，并在启动前持久化 initial_active。每份初始报告可以暂时批准、记录发现／决策，或标记为不完整；不得表示最终批准。将任务计数、可用时的耗时／上下文遥测，以及终止状态持久化为运行证据，而非验收证据。

只有当两个角色都批准，且不存在任何发现、决策或失效项时，初始批准才能通过可执行的聚合流程关闭。修复问题、回答决策或协调重叠内容后，只重新运行受影响的检查，并在使同级批准失效前，提供一份完整的聚合源边界协调结果。之后，恢复同一审查者进行唯一一次可用的验证轮次。同一审查边界不得进行第三轮。出现重大／受保护的验证发现或验证后的重叠问题时，应标记为 redesign_required；不得针对该边界再次启动审查。超时／不可用时，保留部分证据，且最多允许进行一次明确的同轮基础设施替换，绝不自动重试。替换者接收相同的源边界、未关闭的发现、解决方案和审查后的差异；若替换者也失败，则停止。 redesign_required 停止状态要求在再次审查前，提交一个设计／文档／验证边界。使用 review-state.py transition，事件设为 redesign，提供新的 review_boundary_id，以及所有更新后的已审查源边界 字段和声明；这会消耗唯一一次重新设计替换机会，并将新边界重置为 initial_active。不要重复使用旧批准，也不要根据历史证据推断已获批准。只有对于明确属于非实质性、且不涉及安全性、正确性、验证、无障碍或数据丢失防护的问题，才可申请豁免，并且必须提供用户确切接受的范围和理由。受保护的问题无论严重程度如何，均不可豁免。仅当汇总的 can_close 为 true 时，才关闭两项关闭审查；随后只有在其证据仍为最新时，才关闭验证和文档对账。

5. 提交对账

运行 git status --short；识别预先存在或超出范围的更改，并将其排除在提交之外。提交最终代码、测试、文档和审计记录更改。在提交消息中包含功能根 ID。在 Beads 中记录提交 SHA 和审查结果。当交付步骤成为下一个就绪事项时，即可完成收尾。

6. 完成收尾交互边界

在请求或执行交付操作之前，完成文档对账、验证和收尾审查期间发出的所有 Beads 交互。在仓库范围的 beads-workflow-lock.py 租约下，仅将所选谱系的行复制到功能分支，提交仅包含交互记录的审计提交，然后恢复基础副本：

uv run <core-dir>/scripts/reconcile-beads-interactions.py prepare \
  --base-worktree <base-worktree> --feature-worktree <feature-worktree> --root-id <root-id>
git -C <feature-worktree> add .beads/interactions.jsonl
cat > /tmp/dstack-close-interactions-message <<'EOF'
chore(beads): record <slug> close-out state

Beads: <root-id>
EOF
git -C <feature-worktree> commit -F /tmp/dstack-close-interactions-message
uv run <core-dir>/scripts/reconcile-beads-interactions.py finalize \
  --base-worktree <base-worktree> --feature-worktree <feature-worktree> --root-id <root-id>

仅当基础交互导出干净，且没有任何收尾 Beads 修改生成记录行时，才跳过此边界。如果 prepare 或检查器报告存在外来行，则停止，不要恢复，也不要关闭交付／根事项。用户选择 pr、merge 或 ready 之前，基础副本必须保持干净；后续交付操作必须重新获取租约并再次检查。

7. 选择交付操作

如果未提供操作，请只提出一个问题：

create PR
merge
leave ready with no delivery action

ready

添加 delivery:ready，记录对账提交，并保持交付／根事项处于打开状态。

pr

使用 gh pr create 创建拉取请求，记录其 URL，添加 delivery:pr-open，并在确认合并前保持根事项处于打开状态。

merge

读取目标仓库的 AGENTS.md 合并策略。通过 git worktree list --porcelain 找出检出 <base-branch> 的工作树；不要假定当前目录就是基础工作树。验证其分支。要求工作树干净，不得暂存、删除或纳入无关更改；但有一项范围明确的例外：原生 Beads 可能已在基础工作树中为所选功能分子追加了受跟踪的交互记录。

首次交付变更前，要求规范基础工作树处于干净状态。此预检必须在关闭交付或功能根任务之前运行：

uv run <core-dir>/scripts/reconcile-beads-interactions.py preflight \
  --worktree <base-worktree> --root-id <root-id>

如果失败，则在不做更改的情况下检查，并保持交付和根任务处于打开状态：

uv run <core-dir>/scripts/reconcile-beads-interactions.py inspect \
  --worktree <base-worktree> --root-id <root-id>

如果基础工作树仅因 .beads/interactions.jsonl 中追加了记录而处于脏状态，且这些记录的 issue_id 是所选根 ID、其点号分隔的后代，或通过本地 Beads discovered-from 或 parent-child 依赖路径关联回该分子的单独标识工作项，则在还原基础工作树副本前，先在功能分支上保留这些记录。仅有 related 和 blocks 边不能证明这种关联：

uv run <core-dir>/scripts/reconcile-beads-interactions.py prepare \
  --base-worktree <base-worktree> --feature-worktree <feature-worktree> --root-id <root-id>
git -C <feature-worktree> add .beads/interactions.jsonl
cat > /tmp/dstack-close-interactions-message <<'EOF'
chore(beads): record <slug> close-out state

Beads: <root-id>
EOF
git -C <feature-worktree> commit -F /tmp/dstack-close-interactions-message
uv run <core-dir>/scripts/reconcile-beads-interactions.py finalize \
  --base-worktree <base-worktree> --feature-worktree <feature-worktree> --root-id <root-id>

在 prepare 之后，不得再进行其他合并前 Beads 更改；若发生了此类更改，则重新运行 prepare，修改仅包含交互记录的提交，并重新运行 finalize。该辅助工具会拒绝已暂存的更改、非追加式编辑、格式错误或重复的记录、无关的 issue ID、任何其他脏路径，以及未在功能分支上逐字节提交每条记录就进行还原的操作。如果它拒绝当前状态，则停止，不得还原任何内容。其他所有基础工作树脏状态仍会阻止操作。

随后要求两个工作树都处于干净状态并执行合并：

test -z "$(git -C <feature-worktree> status --porcelain)"
test -z "$(git -C <base-worktree> status --porcelain)"
git -C <base-worktree> branch --show-current  # must equal <base-branch>
git -C <base-worktree> merge --ff-only feat/<slug>
git -C <base-worktree> merge-base --is-ancestor feat/<slug> <base-branch>

如果基础工作树缺失、因其他原因处于脏状态，或位于其他分支，则在合并前停止。如果 --ff-only 失败，则说明功能分支必须更新或变基；绝不要退而采用合并提交。只有 AGENTS.md 中明确规定的仓库策略才能将此默认行为替换为合并提交流程。用户仅选择 merge 并不代表授权创建合并提交。

确认合并后，记录实际交付目标，但不要关闭交付或根任务，也不要移除任何一个工作树：

merge_sha=$(git -C <base-worktree> rev-parse <base-branch>)

必须执行的合并后收尾步骤

只有此收尾步骤通过后，合并才算完成。在合并后的基础工作树中：

1. 更新 docs/src/features/<slug>/index.md，写入 Status: delivered 和 Merge commit: <merge_sha>（注明是快进还是合并提交），并记录实际的拉取请求或 not created。
2. 核对记录中 Documentation Updated 部分列出的所有路径、功能更改的所有面向读者的页面、docs/src/planned-features.md、docs/src/features/index.md 和 docs/src/SUMMARY.md。移除声称合并或交付仍在等待中的过时内容；不要让交付完整性审查者去发现这种可通过机械方式检测出的偏差。
3. 针对记录和所有核对过的面向读者的路径运行语义交付验证器：

uv run <core-dir>/scripts/verify-delivery-state.py \
  --base-worktree <base-worktree> --base-branch <base-branch> \
  --record docs/src/features/<slug>/index.md --merge-sha <merge_sha> \
  --path <reader-facing-path> --path <another-reader-facing-path>

验证器必须确认记录的合并 SHA 是基础分支的祖先、记录标记为已交付且包含该 SHA，并且提供的路径中都没有声称交付仍在等待或尚未合并的过时内容。然后重新运行 uv run --no-project python scripts/check-docs.py，以及受收尾步骤影响的所有格式化程序、代码检查工具、构建、测试和功能专属检查。绝不可将合并前的验证结果用于这些编辑。

仅暂存收尾步骤涉及的路径，在合并后的基础分支上提交，并在 Beads 中记录两个 SHA：

git -C <base-worktree> add docs/src/features/<slug>/index.md <reader-facing-paths> \
  docs/src/planned-features.md docs/src/features/index.md docs/src/SUMMARY.md
cat > /tmp/dstack-post-merge-finalizer-message <<'EOF'
docs(<scope>): reconcile <slug> delivery state

Beads: <root-id>
EOF
git -C <base-worktree> commit -F /tmp/dstack-post-merge-finalizer-message
finalizer_sha=$(git -C <base-worktree> rev-parse HEAD)
# The guarded delivery finalizer records both SHAs in the Beads close reason.

如果验证器、文档检查、收尾提交或受保护的 Beads 关闭操作失败，则报告 blocked by post-merge reconciliation，并保留两个工作树。不要关闭交付项或根项，也不要声称已完成。

仅当收尾步骤通过后，才使用受保护的交付收尾程序关闭交付项和功能根项。它会在仓库范围的租约下重新检查合并和收尾步骤的证据，以及基础分支边界是否干净。不要直接使用 bd close 命令关闭交付项或根项。该保护程序会在 Beads 关闭原因中记录 Post-merge delivery SHA: <merge-sha>; finalizer commit: <finalizer-sha>：

uv run <core-dir>/scripts/finalize-feature-delivery.py \
  --base-worktree <base-worktree> --base-branch <base-branch> \
  --record docs/src/features/<slug>/index.md --merge-sha <merge-sha> \
  --finalizer-sha <finalizer-sha> \
  --path <reader-facing-path> --path <another-reader-facing-path> \
  --delivery-id <delivery-id> --root-id <root-id>

这些最终的 Beads 修改可能会在现已合并的基础工作树中追加新的所选功能交互记录行。验证并仅提交这些证据：

uv run <core-dir>/scripts/reconcile-beads-interactions.py verify-post-merge \
  --base-worktree <base-worktree> --root-id <root-id>
git -C <base-worktree> add .beads/interactions.jsonl
cat > /tmp/dstack-delivery-interactions-message <<'EOF'
chore(beads): record <slug> delivery

Beads: <root-id>
EOF
git -C <base-worktree> commit -F /tmp/dstack-delivery-interactions-message

如果工作树仍然干净，则跳过此合并后提交。任何交互提交之后、清理之前，都要重新运行验证器。任何拒绝或新增的脏路径都会阻止清理，必须保留以供明确核对。验证导航和已实现的记录，然后移除功能工作树。如果 dstack.activeFeature 仍等于此功能，则在确认交付后清除该仓库本地设置。除非另有授权，否则绝不要推送或删除远程分支。

返回以下一种就绪状态：ready for delivery、ready after reconciliation fixes、blocked by implementation/docs mismatch 或 blocked by incomplete validation，并提供规范的功能引用和人类可读名称、根 ID、文档、证据、审查、提交、操作和 Beads 变更。