补充临时 worktree 合并后的清理与验收收尾规则 #34

New Issue

2026-10-06T11:44:52+08:00

ila commented

2026-10-06 11:44:52 +08:00

基本信息

类型：单元任务（流程改进）
所属 Epic：无
所属 MVP / 版本：无
阶段：待验收

依赖与并行

前置工单：无
是否允许并行：是；只补充模板收尾规则，无未完成工单依赖。

子项目影响

仅影响的交付单元：DevHarness 文档与工作流模板。
是否跨子项目：否；不变更共享接口、产品代码或工具运行逻辑。

原始需求

来源：当前用户对话
提出时间：2026-10-06
需求摘要：下游项目使用 worktree 开发，合并到 main 后经常遗留目录。用户确认采用“创建者负责收尾、合并推送后按条件清理、与人工验收分开、保留时说明原因”的方案，并要求建单实施。

要解决什么

把临时 worktree 清理纳入日常任务收尾，避免开发目录长期遗留，又能保留仍用于验收、预览或其他任务的目录。

做什么 / 不做什么

做：更新 AGENTS.md 的 Git 与验证、完成和验收；先改 Development-Workflow 和 Local-Development-and-Verification Wiki，再导出对应镜像。
不做：不新增自动清理脚本、定时任务、强制 worktree 开发要求；不删除现有或其他项目的 worktree，不隐式删除分支或任务归档。

已确认方案

Agent 负责本任务创建的临时 worktree；任务交接时一并交接路径与收尾责任。
任务成果已合并到 main（或约定目标分支）并推送、必要验证通过后，核对准确路径、成果保留情况、本地文件和使用状态，符合条件即清理。
清理使用 git worktree remove，不自动使用 --force、递归删除或解锁绕过失败；git worktree prune 仅用于失效登记。
未提交/未跟踪/忽略文件中仍有需保留内容、其他 Agent 或服务仍在使用、锁定或验收依赖目录时保留，并记录原因与后续清理时机。
清理与工单验收独立：可在待验收前清理；用户验收前不得关闭工单。因验收保留的目录在验收结束、保留条件解除后清理。
最终证据写“worktree 已清理”或保留路径、原因和清理时机；直接实施项在结果报告中记录。
常规临时目录收尾属于已授权实施范围，无需每次重复确认；不扩展到其他任务目录或远端分支。

预计文件：AGENTS.md、docs/01-workflow.md、docs/04-local-development-and-verification.md。后两项仅由 Wiki 同步生成。

需求变化记录

无。

设计与原型

修改类型：非 UI
设计证据：当前对话已确认的 worktree 收尾流程，用户于 2026-10-06 授权实施。
无需 UI 原型；未要求本地 HTML 导出。

文档影响

更新 Development-Workflow、Local-Development-and-Verification。
无产品交付文档影响：仅开发工作流规则。
默认不创建或导出任务快照。

验收标准

明确本任务临时 worktree 的清理责任、触发时机和保留条件。
明确清理与工单人工验收独立，验收依赖解除后继续清理。
提供准确路径检查、git worktree remove 与结果检查的最小操作说明。
明确不自动 force、解锁、递归删除或删除其他任务目录与分支。
不因已合并就忽略本地独有文件或仍在使用的目录。
Wiki 已回读并同步镜像；严格检查、既有单元测试、镜像一致性与差异检查通过。
提交、推送、回写证据，保持待验收。

验证方式

python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/harness.py sync --check
git diff --check
人工核对已合并可清理、待验收无需目录、验收依赖目录、本地独有文件、其他任务使用、移除失败与 squash/rebase 合并的文档场景；不为文档增加逐字断言测试。

风险和回退

风险：把成果已合并误当作目录所有内容均可丢弃，或误删仍在使用的 worktree。
控制：仅处理本任务准确路径，确认本地需保留文件与使用状态，普通 remove 失败后保留并记录。
回退：在 Wiki 恢复本次新增条款前版本并同步镜像，回退本次 AGENTS.md 提交；本任务不涉及实际目录删除。

Gitea 交互

本会话未提供可调用的 Gitea MCP 工具，因此回退 Gitea API。凭据从本地安全配置注入当前进程，不输出或提交。

## 基本信息 - 类型：单元任务（流程改进） - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：待验收 ## 依赖与并行 - 前置工单：无 - 是否允许并行：是；只补充模板收尾规则，无未完成工单依赖。 ## 子项目影响 - 仅影响的交付单元：DevHarness 文档与工作流模板。 - 是否跨子项目：否；不变更共享接口、产品代码或工具运行逻辑。 ## 原始需求 - 来源：当前用户对话 - 提出时间：2026-10-06 - 需求摘要：下游项目使用 worktree 开发，合并到 main 后经常遗留目录。用户确认采用“创建者负责收尾、合并推送后按条件清理、与人工验收分开、保留时说明原因”的方案，并要求建单实施。 ## 要解决什么把临时 worktree 清理纳入日常任务收尾，避免开发目录长期遗留，又能保留仍用于验收、预览或其他任务的目录。 ## 做什么 / 不做什么 - 做：更新 AGENTS.md 的 Git 与验证、完成和验收；先改 Development-Workflow 和 Local-Development-and-Verification Wiki，再导出对应镜像。 - 不做：不新增自动清理脚本、定时任务、强制 worktree 开发要求；不删除现有或其他项目的 worktree，不隐式删除分支或任务归档。 ## 已确认方案 1. Agent 负责本任务创建的临时 worktree；任务交接时一并交接路径与收尾责任。 2. 任务成果已合并到 main（或约定目标分支）并推送、必要验证通过后，核对准确路径、成果保留情况、本地文件和使用状态，符合条件即清理。 3. 清理使用 git worktree remove，不自动使用 --force、递归删除或解锁绕过失败；git worktree prune 仅用于失效登记。 4. 未提交/未跟踪/忽略文件中仍有需保留内容、其他 Agent 或服务仍在使用、锁定或验收依赖目录时保留，并记录原因与后续清理时机。 5. 清理与工单验收独立：可在待验收前清理；用户验收前不得关闭工单。因验收保留的目录在验收结束、保留条件解除后清理。 6. 最终证据写“worktree 已清理”或保留路径、原因和清理时机；直接实施项在结果报告中记录。 7. 常规临时目录收尾属于已授权实施范围，无需每次重复确认；不扩展到其他任务目录或远端分支。预计文件：AGENTS.md、docs/01-workflow.md、docs/04-local-development-and-verification.md。后两项仅由 Wiki 同步生成。 ## 需求变化记录无。 ## 设计与原型 - 修改类型：非 UI - 设计证据：当前对话已确认的 worktree 收尾流程，用户于 2026-10-06 授权实施。 - 无需 UI 原型；未要求本地 HTML 导出。 ## 文档影响 - [x] 更新 Development-Workflow、Local-Development-and-Verification。 - [x] 无产品交付文档影响：仅开发工作流规则。 - [x] 默认不创建或导出任务快照。 ## 验收标准 - [ ] 明确本任务临时 worktree 的清理责任、触发时机和保留条件。 - [ ] 明确清理与工单人工验收独立，验收依赖解除后继续清理。 - [ ] 提供准确路径检查、git worktree remove 与结果检查的最小操作说明。 - [ ] 明确不自动 force、解锁、递归删除或删除其他任务目录与分支。 - [ ] 不因已合并就忽略本地独有文件或仍在使用的目录。 - [ ] Wiki 已回读并同步镜像；严格检查、既有单元测试、镜像一致性与差异检查通过。 - [ ] 提交、推送、回写证据，保持待验收。 ## 验证方式 - python dev_scripts/harness.py check --strict - python -m unittest discover -s tests -v - python dev_scripts/harness.py sync --check - git diff --check - 人工核对已合并可清理、待验收无需目录、验收依赖目录、本地独有文件、其他任务使用、移除失败与 squash/rebase 合并的文档场景；不为文档增加逐字断言测试。 ## 风险和回退 - 风险：把成果已合并误当作目录所有内容均可丢弃，或误删仍在使用的 worktree。 - 控制：仅处理本任务准确路径，确认本地需保留文件与使用状态，普通 remove 失败后保留并记录。 - 回退：在 Wiki 恢复本次新增条款前版本并同步镜像，回退本次 AGENTS.md 提交；本任务不涉及实际目录删除。 ## Gitea 交互本会话未提供可调用的 Gitea MCP 工具，因此回退 Gitea API。凭据从本地安全配置注入当前进程，不输出或提交。

ila referenced this issue from a commit

2026-10-06 11:48:06 +08:00

docs: 补充临时 worktree 收尾规则 (#34)

ila commented

2026-10-06 11:48:40 +08:00

最终实施证据（待验收）

完成内容

AGENTS.md 的“Git 与验证”“完成和验收”明确临时 worktree 创建者的收尾责任、交接责任和清理时机。
成果已合并至 main 或约定目标分支并推送、必要验证通过后，核对本任务准确路径、合并证据、本地需保留内容和使用状态，符合条件即清理，无需重复授权。
使用 git worktree remove 并核对结果；失败或锁定时保留并记录，不自动 force、解锁、递归删除或扩展至其他任务目录、主工作树或分支。
worktree 清理与工单验收独立。在主分支验收时可以先清理；验收或预览依赖目录时记录路径、原因、责任人和清理时机，条件解除后继续清理。
Local-Development-and-Verification 增加检查未提交、未跟踪及忽略文件、核对 squash/rebase 合并结果、移除和结果确认的最小操作说明。
Development-Workflow 补充任务收尾与验收时保留目录的后续处理。
Claude Code 经现有 @AGENTS.md 导入获得相同规则，无需复制规则。

提交与文件

提交：dc68b2afbe43f633b9bc38266d7dcdd904751705，已推送 origin/main。
文件：AGENTS.md、docs/01-workflow.md、docs/04-local-development-and-verification.md。
本地 HEAD 与 origin/main 一致，工作区干净。
本任务未创建临时 worktree，无需执行目录清理。

验证

python dev_scripts/harness.py check --strict：通过。
python -m unittest discover -s tests -v：56/56 通过。
python dev_scripts/harness.py sync --check：15 个核心镜像一致。
git diff --check 及暂存差异检查：通过。
新增的两个 PowerShell 示例经语法解析通过；没有执行示例中的删除操作。
人工核对：已合并可清理、待验收无需目录、验收依赖目录、本地独有文件、其他任务使用、移除失败与 squash/rebase 合并均有对应说明。
本次为规则与文档修改，未新增脚本或逐字断言测试；未实际删除任何项目 worktree，未实测真实目录占用、子模块移除或数据恢复。
文档读取过程中一次 Select-Object 参数笔误已纠正，只读失败没有造成文件变化。

Wiki 证据与文档影响

Development-Workflow revision：1407294afe1100ab9fdbe69c60cf32718732d90e。
Local-Development-and-Verification revision：8348baeb75e77dcc0f8a6321e87bd3d60eb501a7。
线上写入后逐页回读正文并确认与预期一致，再通过 sync 生成本地镜像；没有直接编辑镜像。
Gitea API 回退原因已在工单正文记录。
未创建或导出任务快照；未扫描或清理其他项目历史遗留目录。

工单保持开启，阶段为待验收，等待用户明确验收。

## 最终实施证据（待验收） ### 完成内容 - AGENTS.md 的“Git 与验证”“完成和验收”明确临时 worktree 创建者的收尾责任、交接责任和清理时机。 - 成果已合并至 main 或约定目标分支并推送、必要验证通过后，核对本任务准确路径、合并证据、本地需保留内容和使用状态，符合条件即清理，无需重复授权。 - 使用 git worktree remove 并核对结果；失败或锁定时保留并记录，不自动 force、解锁、递归删除或扩展至其他任务目录、主工作树或分支。 - worktree 清理与工单验收独立。在主分支验收时可以先清理；验收或预览依赖目录时记录路径、原因、责任人和清理时机，条件解除后继续清理。 - Local-Development-and-Verification 增加检查未提交、未跟踪及忽略文件、核对 squash/rebase 合并结果、移除和结果确认的最小操作说明。 - Development-Workflow 补充任务收尾与验收时保留目录的后续处理。 - Claude Code 经现有 @AGENTS.md 导入获得相同规则，无需复制规则。 ### 提交与文件 - 提交：dc68b2afbe43f633b9bc38266d7dcdd904751705，已推送 origin/main。 - 文件：AGENTS.md、docs/01-workflow.md、docs/04-local-development-and-verification.md。 - 本地 HEAD 与 origin/main 一致，工作区干净。 - 本任务未创建临时 worktree，无需执行目录清理。 ### 验证 - python dev_scripts/harness.py check --strict：通过。 - python -m unittest discover -s tests -v：56/56 通过。 - python dev_scripts/harness.py sync --check：15 个核心镜像一致。 - git diff --check 及暂存差异检查：通过。 - 新增的两个 PowerShell 示例经语法解析通过；没有执行示例中的删除操作。 - 人工核对：已合并可清理、待验收无需目录、验收依赖目录、本地独有文件、其他任务使用、移除失败与 squash/rebase 合并均有对应说明。 - 本次为规则与文档修改，未新增脚本或逐字断言测试；未实际删除任何项目 worktree，未实测真实目录占用、子模块移除或数据恢复。 - 文档读取过程中一次 Select-Object 参数笔误已纠正，只读失败没有造成文件变化。 ### Wiki 证据与文档影响 - Development-Workflow revision：1407294afe1100ab9fdbe69c60cf32718732d90e。 - Local-Development-and-Verification revision：8348baeb75e77dcc0f8a6321e87bd3d60eb501a7。 - 线上写入后逐页回读正文并确认与预期一致，再通过 sync 生成本地镜像；没有直接编辑镜像。 - Gitea API 回退原因已在工单正文记录。 - 未创建或导出任务快照；未扫描或清理其他项目历史遗留目录。工单保持开启，阶段为待验收，等待用户明确验收。

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: OPC/dev_harness#34