fix(git): 文档关闭后再清理工作树

2026-09-03 14:18:55 +08:00
parent 7026f249d0
commit 72a6f71dd0
5 changed files with 22 additions and 8 deletions
@@ -8,6 +8,11 @@

 ## [Unreleased]

+### Added
+
+- `knowledge:document-output` 增加 `register` 与 `close` 模式，使用 `workRoot/<task>/task.json` 记录任务状态、文件归属、可见性和关闭处置。
+- 增加“保留、沉淀、归档、删除、延后”五类关闭清单，以及共享文件逐项评审、断链检查和精确路径删除门禁。
+
 ### Planned

 - 建设 Skill 评测基线，支持固定场景、验收规则和更新前后回归比较。
@@ -24,6 +29,8 @@

 - `knowledge` 插件增加项目文档落盘配置能力；项目初始化写入 `documents.workRoot`、`documents.designRoot` 与 `documents.archiveRoot`，区分本地过程文档、共享设计和历史归档。
 - 需求、变更计划、技术设计与 Bug 分析 Skill 统一按项目文档配置选择任务目录；缺少配置时，过程文档回退到 `.craftkit/local/tasks/`，不再根据根目录说明文件推断落点。
+- 项目初始化增加文档生命周期默认策略；本地保留天数只用于提示，任务完成默认生成关闭预览，不自动删除文件。
+- 需求、计划、设计和分析 Skill 写入文档后登记本地任务记录；沉淀、交接、归档和 Worktree 清理按任务状态联动。

 ## [1.3.0] - 2026-08-31

@@ -88,7 +88,7 @@
 | S6 验证与自修复 | `test-backend`、`test-ui` | 分层验证记录、失败分类、修复结果 | 自动进入 S7 |
 | S7 代码审核 | `review-code`，按需叠加 `review-java`、`review-mybatis`、`review-frontend` | 审核报告、问题清单、未验证边界 | 自动修复明确问题后复审，进入 G4 |
 | S8 提交准备 | `commit-msg` | 精确文件范围、提交拆分与提交信息 | 进入审批门 G5 |
-| S9 本地提交与收尾 | Git 原生命令、`branch close` | 一个或多个本地提交、提交后状态、Worktree 清理结果 | 释放额外 Worktree 后输出最终交付报告 |
+| S9 本地提交与收尾 | Git 原生命令、`document-output close`、`branch close` | 本地提交、文档关闭清单、Worktree 清理结果 | 完成文档关闭门禁并释放额外 Worktree 后输出最终交付报告 |

 阶段不得仅凭名称跳过。确实不适用时，应记录“不适用”的证据和原因，再继续推进。

@@ -169,7 +169,7 @@
 6. 若项目上下文缺失，只在确有必要时提出 `init`；初始化写入仍遵守该 Skill 的确认步骤。
 7. 建立任务台账，至少记录任务编号、当前状态、输入、产物、审批记录、风险和下一动作。

-推荐将本次任务的本地运行状态保存到 `.craftkit/local/`；除非用户明确要求共享，不把运行状态写入可提交目录。
+推荐将本次任务的本地运行状态保存到 `documents.workRoot/<task>/task.json`；除非用户明确要求共享，不把运行状态写入可提交目录。任务记录至少登记状态、过程或共享产物、可见性、用途和关闭处置。

 ### S1：需求归集与落表

@@ -313,12 +313,14 @@ G5 批准后：
 4. 确认无敏感文件、缓存、本地配置和无关改动；
 5. 使用批准的提交信息创建本地提交；
 6. 验证提交哈希、提交内容、当前分支和提交后工作区状态；
-7. 如果本次使用独立 Worktree，确认开发、验证和本地交付已完成，检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
-8. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
-9. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
-10. 输出最终交付报告。
+7. 将任务状态更新为 `ready_to_close`，使用 `document-output close` 生成“保留、沉淀、归档、删除、延后”清单；默认只预览，删除只处理用户确认的精确文件；
+8. 执行已确认的知识沉淀和文档归档，校验目标及引用，再完成已授权清理；存在延后项时保持未关闭状态并说明原因；
+9. 如果本次使用独立 Worktree，确认文档任务已经 `closed`，再检查 Worktree 干净、无进行中的 Git 操作且 HEAD 已被本地分支引用；
+10. 展示准确清理路径、分支、HEAD 和 `git worktree remove` 命令，取得独立确认后使用 `branch close` 移除额外 Worktree；
+11. 验证 Worktree 目录和占用记录已移除、分支与提交仍存在、主工作区未变化；
+12. 输出最终交付报告。

-最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、未提交文件、未验证边界和后续建议。
+最终报告至少包含：需求与设计产物路径、分支、提交哈希、实现摘要、验证结果、审核结论、文档关闭状态、未提交文件、未验证边界和后续建议。

 ## 7. 阻塞与回退规则

@@ -439,6 +441,7 @@ G5 批准后：
 - 代码效果已通过 G4；
 - 提交范围与信息已通过 G5；
 - 本地提交已创建并核对内容；
+- 任务文档已生成关闭预览；已确认的沉淀、归档和删除均已验证，延后项已明确记录；
 - 使用独立 Worktree 时，其生命周期已经结束并安全移除；若用户明确要求保留现场，则任务状态应说明生命周期尚未结束及分支占用路径；
 - 未发生未经授权的 push、合并、发布、生产操作或历史改写。

@@ -1,6 +1,6 @@
 {
  "name": "git",
-  "version": "0.5.1",
+  "version": "0.5.2",
  "description": "安全、可复核的通用 Git 工作流。",
  "author": {
    "name": "CraftKit"
@@ -34,6 +34,8 @@ git worktree add -b "<branch>" "<absolute-worktree-path>" "<base>"
 - 当前 HEAD 已被预期本地分支引用；
 - 主仓库、worktree 路径、分支和 HEAD 均已准确确认。

+还要读取 `.craftkit/project.json` 的 `documents.workRoot`，检查该 Worktree 中与本分支任务对应的 `task.json` 和 ignored 文件。任务状态未到 `closed`、存在未登记的忽略文件或关闭清单尚未处理时，先执行 `knowledge:document-output close` 预览；用户要求保留现场时不得移除 Worktree。
+
 展示检查结果、移除后保留的分支和唯一清理命令，取得用户确认后执行：

 ```text
@@ -56,6 +56,8 @@ git log --first-parent --oneline -20
 - 当前 HEAD 已被预期本地分支引用；
 - 用户不再要求保留现场。

+同时读取 `.craftkit/project.json` 的 `documents.workRoot`，检查与预集成任务对应的 `task.json` 和 ignored 文件。任务状态未到 `closed`、存在未登记的忽略文件或关闭清单尚未处理时，标记为 `cleanup-blocked`，先执行 `knowledge:document-output close` 预览。
+
 用户要求保留现场时标记为 `delivery-ready`，明确说明生命周期尚未结束以及分支仍被该 worktree 占用。

 ## 清理门禁