clawt 2.5.0 → 2.6.0

package/.claude/agent-memory/docs-sync-updater/MEMORY.md

@@ -12,14 +12,6 @@
 - 配置项说明在 `5.7 默认配置文件` 章节的表格中
 - 更新模式：新增步骤时追加编号，配置项影响范围变化时更新说明列
 
-### CLAUDE.md
-- 面向 Claude Code 的项目架构指引，精简扼要
-- run 命令流程在 `核心流程（run 命令）` 章节，编号列表描述
-- resume 命令流程在独立的 `### resume 命令流程` 章节，编号列表 + 缩进列表描述匹配策略
-- merge 和 run 中断清理在 `validate + merge 工作流` 章节，一行式描述用箭头连接流程
-- utils 目录描述用括号内逗号分隔列举功能模块
-- 更新模式：编号列表追加步骤，箭头链追加阶段，括号内追加关键词
-
 ### README.md
 - 面向用户的使用文档
 - 每个命令一个 `###` 小节，含命令格式、参数表格、简要说明、示例
@@ -29,7 +21,7 @@
 ## 关键约定
 - `autoDeleteBranch` 配置项影响三处：remove 命令、merge 命令、run 中断清理
 - `confirmDestructiveOps` 配置项影响两处：reset 命令、validate --clean
-- merge 的清理确认在 merge 操作之前询问（避免交互中断），但清理在 merge 成功后执行
+- merge 的清理确认和清理操作均在 merge 成功后执行（避免 merge 冲突时提前询问用户造成困惑）
 - merge 成功后自动清理对应的 validate 快照（hasSnapshot + removeSnapshot）
 - merge 成功消息根据 `autoPullPush` 配置动态显示推送状态
 - run 的中断清理在所有子进程退出后执行
@@ -46,12 +38,11 @@
 
 ## 配置项同步检查点
 
-配置项变更时需在以下 5 处保持一致：
+配置项变更时需在以下 4 处保持一致：
 1. `src/constants/config.ts` — CONFIG_DEFINITIONS 对象（单一数据源，包含 defaultValue + description）
 2. `src/types/config.ts` — ClawtConfig 接口
 3. `docs/spec.md` — 5.7 默认配置文件章节（JSON 示例 + 配置项表格）
-4. `CLAUDE.md` — 关键约定段落中的配置描述
-5. `README.md` — 配置文件章节（JSON 示例 + 配置项表格）
+4. `README.md` — 配置文件章节（JSON 示例 + 配置项表格）
 
 ## 配置架构
 
@@ -65,7 +56,6 @@
 run 命令有两种模式（自 claudeCodeCommand 特性后）：
 - 不传 `--tasks`：交互式界面模式（单 worktree + `launchInteractiveClaude` + spawnSync）
 - 传 `--tasks`：并行任务模式（多 worktree + `executeClaudeTask` + spawnProcess）
-- CLAUDE.md 中的核心流程按模式分段描述
 
 ## 命令清单（10 个）
 
@@ -81,14 +71,17 @@ Notes:
 ## validate 快照机制
 
 - validate 命令支持首次/增量两种模式，通过 `hasSnapshot()` 判断
-- 快照路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree`（存储 git tree 对象 hash）
+- 快照由两个文件组成：`.tree`（git tree 对象 hash）和 `.head`（快照时主 worktree 的 HEAD commit hash）
+- 快照路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree` 和 `<branchName>.head`
 - 常量 `VALIDATE_SNAPSHOTS_DIR` 定义在 `src/constants/paths.ts`
 - validate 新增 `--clean` 选项（`ValidateOptions.clean?: boolean`）
-- 快照保存：`git add . → git write-tree → git restore --staged .`，将 tree hash 写入 `.tree` 文件
-- 增量模式核心：`git read-tree <旧 tree hash>` 将旧快照载入暂存区 + 新全量变更在工作目录 → `git diff` 可查看增量差异
-- tree 对象不依赖主分支 HEAD，无需一致性校验（旧方案需要 `.head` 文件校验 HEAD 一致性）
-- 增量 read-tree 失败时自动降级为全量模式（tree 对象可能被 git gc 回收）
-- git 层有 `gitWriteTree()`（返回 tree hash）和 `gitReadTree()`（载入暂存区）
+- 快照保存：`git add . → git write-tree → git rev-parse HEAD → git restore --staged .`，tree hash 写入 `.tree`，HEAD commit hash 写入 `.head`
+- 增量模式核心：检测 HEAD 是否变化决定策略
+  - HEAD 未变化：`git read-tree <旧 tree hash>` 直接载入暂存区
+  - HEAD 已变化：提取旧变更 patch（`git diff-tree` 旧 HEAD tree → 旧快照 tree），`git apply --cached` 重放到当前 HEAD 暂存区；有冲突则降级全量
+- 增量 read-tree / apply 失败时自动降级为全量模式
+- git 层工具函数：`gitWriteTree()`、`gitReadTree()`、`getCommitTreeHash()`、`gitDiffTree()`、`gitApplyCachedCheck()`
+- `readSnapshot()` 返回 `{ treeHash, headCommitHash }`，`writeSnapshot()` 接收 4 个参数（含 headCommitHash）
+- `removeSnapshot()` 同时清理 `.tree` 和 `.head` 文件
 - merge 成功后自动清理对应快照；merge 时主 worktree 脏 + 存在快照会输出警告提示
 - docs/spec.md 中 validate 章节（5.4）按 `--clean 模式`、`首次 validate`、`增量 validate` 三段描述
-- CLAUDE.md 中在 validate + merge 工作流章节用缩进列表描述两种模式

package/.claude/agents/docs-sync-updater.md

@@ -1,11 +1,11 @@
 ---
 name: docs-sync-updater
-description: "Use this agent when the user explicitly requests to synchronize documentation files (docs/spec.md, CLAUDE.md, README.md) based on recent code changes in the working area or staging area. This agent must NEVER be called proactively or automatically — it must only be invoked when the user explicitly asks for documentation synchronization.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"请同步更新文档\"\\n  assistant: \"好的，我来调用文档同步 agent 来根据当前代码变更更新相关文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 2:\\n  user: \"代码改完了，帮我把文档也更新一下\"\\n  assistant: \"收到，我现在使用文档同步 agent 来分析代码变更并更新 docs/spec.md、CLAUDE.md 和 README.md。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 3:\\n  user: \"update docs based on my changes\"\\n  assistant: \"好的，我来启动文档同步 agent，根据工作区和暂存区的变更同步更新文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Counter-example (DO NOT do this):\\n  user: \"我刚加了一个新命令\"\\n  assistant: (DO NOT proactively launch this agent. Wait for the user to explicitly request documentation updates.)"
+description: "Use this agent when the user explicitly requests to synchronize documentation files (docs/spec.md, README.md) based on recent code changes in the working area or staging area. This agent must NEVER be called proactively or automatically — it must only be invoked when the user explicitly asks for documentation synchronization.\\n\\nExamples:\\n\\n- Example 1:\\n  user: \"请同步更新文档\"\\n  assistant: \"好的，我来调用文档同步 agent 来根据当前代码变更更新相关文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 2:\\n  user: \"代码改完了，帮我把文档也更新一下\"\\n  assistant: \"收到，我现在使用文档同步 agent 来分析代码变更并更新 docs/spec.md 和 README.md。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Example 3:\\n  user: \"update docs based on my changes\"\\n  assistant: \"好的，我来启动文档同步 agent，根据工作区和暂存区的变更同步更新文档。\"\\n  <Use the Task tool to launch the docs-sync-updater agent>\\n\\n- Counter-example (DO NOT do this):\\n  user: \"我刚加了一个新命令\"\\n  assistant: (DO NOT proactively launch this agent. Wait for the user to explicitly request documentation updates.)"
 model: opus
 memory: project
 ---
 
-你是一位资深的技术文档工程师，精通代码变更分析与文档同步维护。你的核心职责是根据当前工作区（working directory）和暂存区（staging area）的代码修改，精准地同步更新项目中的三个关键文档：`docs/spec.md`、`CLAUDE.md` 和 `README.md`。
+你是一位资深的技术文档工程师，精通代码变更分析与文档同步维护。你的核心职责是根据当前工作区（working directory）和暂存区（staging area）的代码修改，精准地同步更新项目中的两个关键文档：`docs/spec.md` 和 `README.md`。
 
 ## 重要约束
 
@@ -33,15 +33,13 @@ memory: project
 ### 第二步：阅读现有文档
 
 1. 读取 `docs/spec.md` 的当前内容（如果存在）。
-2. 读取 `CLAUDE.md` 的当前内容。
-3. 读取 `README.md` 的当前内容（如果存在）。
-4. 理解每个文档的结构、风格和覆盖范围。
+2. 读取 `README.md` 的当前内容（如果存在）。
+3. 理解每个文档的结构、风格和覆盖范围。
 
 ### 第三步：确定需要更新的内容
 
 对每个文档，判断代码变更是否影响其内容：
 
-- **`CLAUDE.md`**：项目架构说明、命令列表、核心流程、目录层级、关键约定、构建命令等。当新增命令、修改架构、调整目录结构、修改构建流程时需要更新。
 - **`docs/spec.md`**：项目规格说明文档。当功能需求、技术规格、API 设计发生变化时需要更新。
 - **`README.md`**：用户面向的项目说明。当用户可见的功能、安装方式、使用方法、命令参数发生变化时需要更新。
 
@@ -83,7 +81,7 @@ memory: project
 - 如果工作区和暂存区都没有变更，检查最近的提交并告知用户当前没有未提交的变更，询问是否基于最近提交更新。
 - 如果某个文档文件不存在，告知用户并询问是否需要创建。
 - 如果变更内容过于复杂或不确定如何反映到文档中，列出你的理解并询问用户确认。
-- 如果变更只涉及代码重构而不改变功能，可能不需要更新面向用户的文档（README.md），但可能需要更新架构文档（CLAUDE.md）。
+- 如果变更只涉及代码重构而不改变功能，可能不需要更新面向用户的文档（README.md），但可能需要更新规格文档（docs/spec.md）。
 
 **Update your agent memory** as you discover documentation patterns, document structure conventions, terminology usage, and relationships between code modules and their documentation sections. This builds up institutional knowledge across conversations. Write concise notes about what you found and where.
 

package/README.md

@@ -117,7 +117,7 @@ clawt validate -b <branchName> [--clean]
 
 将目标 worktree 的变更通过 `git diff`（三点 diff）迁移到主 worktree，方便在主 worktree 中直接测试，无需重新安装依赖。同时检测未提交修改和已提交 commit，确保所有变更都能被捕获。
 
-支持增量模式：首次 validate 后会自动保存快照（通过 `git write-tree` 将变更存储为 git tree 对象），再次 validate 同一分支时会通过 `git read-tree` 将上次快照载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
+支持增量模式：首次 validate 后会自动保存快照（通过 `git write-tree` 将变更存储为 git tree 对象，并记录当前 HEAD commit hash），再次 validate 同一分支时会将上次快照载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 查看两次 validate 之间的增量差异。当主分支 HEAD 发生变化（如合并了其他分支）时，会自动将旧变更 patch 重放到当前 HEAD 暂存区上，避免 diff 混入 HEAD 变化的内容；若 patch 存在冲突则自动降级为全量模式。使用 `--clean` 可清理 validate 状态（重置主 worktree 并删除快照文件）。
 
 > **提示：** 如果 validate 时 patch apply 失败（目标分支与主分支差异过大），可先执行 `clawt sync -b <branchName>` 同步主分支后重试。
 

package/dist/index.js

@@ -368,9 +368,15 @@ function getDiffStat(worktreePath) {
   const output = execCommand("git diff --shortstat HEAD", { cwd: worktreePath });
   return parseShortStat(output);
 }
+function gitApplyCachedFromStdin(patchContent, cwd) {
+  execCommandWithInput("git", ["apply", "--cached"], { input: patchContent, cwd });
+}
 function getCurrentBranch(cwd) {
   return execCommand("git rev-parse --abbrev-ref HEAD", { cwd });
 }
+function getHeadCommitHash(cwd) {
+  return execCommand("git rev-parse HEAD", { cwd });
+}
 function gitDiffBinaryAgainstBranch(branchName, cwd) {
   logger.debug(`\u6267\u884C\u547D\u4EE4: git diff HEAD...${branchName} --binary${cwd ? ` (cwd: ${cwd})` : ""}`);
   return execSync2(`git diff HEAD...${branchName} --binary`, {
@@ -405,6 +411,24 @@ function gitWriteTree(cwd) {
 function gitReadTree(treeHash, cwd) {
   execCommand(`git read-tree ${treeHash}`, { cwd });
 }
+function getCommitTreeHash(commitHash, cwd) {
+  return execCommand(`git rev-parse ${commitHash}^{tree}`, { cwd });
+}
+function gitDiffTree(baseTreeHash, targetTreeHash, cwd) {
+  logger.debug(`\u6267\u884C\u547D\u4EE4: git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}${cwd ? ` (cwd: ${cwd})` : ""}`);
+  return execSync2(`git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}`, {
+    cwd,
+    stdio: ["pipe", "pipe", "pipe"]
+  });
+}
+function gitApplyCachedCheck(patchContent, cwd) {
+  try {
+    execCommandWithInput("git", ["apply", "--cached", "--check"], { input: patchContent, cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 // src/utils/formatter.ts
 import chalk from "chalk";
@@ -667,27 +691,40 @@ import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync
 function getSnapshotPath(projectName, branchName) {
   return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
 }
+function getSnapshotHeadPath(projectName, branchName) {
+  return join3(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+}
 function hasSnapshot(projectName, branchName) {
   return existsSync5(getSnapshotPath(projectName, branchName));
 }
-function readSnapshotTreeHash(projectName, branchName) {
+function readSnapshot(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   logger.debug(`\u8BFB\u53D6 validate \u5FEB\u7167: ${snapshotPath}`);
-  return readFileSync2(snapshotPath, "utf-8").trim();
+  const treeHash = existsSync5(snapshotPath) ? readFileSync2(snapshotPath, "utf-8").trim() : "";
+  const headCommitHash = existsSync5(headPath) ? readFileSync2(headPath, "utf-8").trim() : "";
+  return { treeHash, headCommitHash };
 }
-function writeSnapshot(projectName, branchName, treeHash) {
+function writeSnapshot(projectName, branchName, treeHash, headCommitHash) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   const snapshotDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   writeFileSync2(snapshotPath, treeHash, "utf-8");
-  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}`);
+  writeFileSync2(headPath, headCommitHash, "utf-8");
+  logger.info(`\u5DF2\u4FDD\u5B58 validate \u5FEB\u7167: ${snapshotPath}, ${headPath}`);
 }
 function removeSnapshot(projectName, branchName) {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   if (existsSync5(snapshotPath)) {
     unlinkSync(snapshotPath);
     logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${snapshotPath}`);
   }
+  if (existsSync5(headPath)) {
+    unlinkSync(headPath);
+    logger.info(`\u5DF2\u5220\u9664 validate \u5FEB\u7167: ${headPath}`);
+  }
 }
 function removeProjectSnapshots(projectName) {
   const projectDir = join3(VALIDATE_SNAPSHOTS_DIR, projectName);
@@ -1158,7 +1195,8 @@ function saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName) {
   gitAddAll(mainWorktreePath);
   const treeHash = gitWriteTree(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash);
+  const headCommitHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
   return treeHash;
 }
 async function handleValidateClean(options) {
@@ -1189,7 +1227,7 @@ function handleFirstValidate(targetWorktreePath, mainWorktreePath, projectName,
   printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
 }
 function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, projectName, branchName, hasUncommitted) {
-  const oldTreeHash = readSnapshotTreeHash(projectName, branchName);
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
   if (!isWorkingDirClean(mainWorktreePath)) {
     gitResetHard(mainWorktreePath);
     gitCleanForce(mainWorktreePath);
@@ -1197,7 +1235,21 @@ function handleIncrementalValidate(targetWorktreePath, mainWorktreePath, project
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
   try {
-    gitReadTree(oldTreeHash, mainWorktreePath);
+    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
+    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
+      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
+      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
+      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
+        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
+      } else if (oldChangePatch.length > 0) {
+        logger.warn("\u65E7\u53D8\u66F4 patch \u4E0E\u5F53\u524D HEAD \u51B2\u7A81\uFF0C\u964D\u7EA7\u4E3A\u5168\u91CF\u6A21\u5F0F");
+        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+        printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+        return;
+      }
+    } else {
+      gitReadTree(oldTreeHash, mainWorktreePath);
+    }
   } catch (error) {
     logger.warn(`\u589E\u91CF read-tree \u5931\u8D25: ${error}`);
     printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
@@ -1274,7 +1326,7 @@ async function shouldCleanupAfterMerge(branchName) {
     printInfo(`\u5DF2\u914D\u7F6E\u81EA\u52A8\u5220\u9664\uFF0Cmerge \u6210\u529F\u540E\u5C06\u81EA\u52A8\u6E05\u7406 worktree \u548C\u5206\u652F: ${branchName}`);
     return true;
   }
-  return confirmAction(`merge \u6210\u529F\u540E\u662F\u5426\u5220\u9664\u5BF9\u5E94\u7684 worktree \u548C\u5206\u652F (${branchName})\uFF1F`);
+  return confirmAction(`\u662F\u5426\u5220\u9664\u5BF9\u5E94\u7684 worktree \u548C\u5206\u652F (${branchName})\uFF1F`);
 }
 function cleanupWorktreeAndBranch(worktreePath, branchName) {
   cleanupWorktrees([{ path: worktreePath, branch: branchName }]);
@@ -1300,7 +1352,6 @@ async function handleMerge(options) {
   if (shouldExit) {
     return;
   }
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   const targetClean = isWorkingDirClean(targetWorktreePath);
   if (!targetClean) {
     if (!options.message) {
@@ -1336,6 +1387,7 @@ async function handleMerge(options) {
   } else {
     printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch, autoPullPush));
   }
+  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }

package/docs/spec.md

@@ -143,6 +143,7 @@ git show-ref --verify refs/heads/<branchName> 2>/dev/null
 ├── validate-snapshots/                  # validate 快照目录
 │   └── <project-name>/                  # 以项目名分组
 │       ├── <branchName>.tree            # 每个分支一个 tree hash 快照文件（存储 git tree 对象的 hash）
+│       ├── <branchName>.head            # 每个分支一个 HEAD commit hash 快照文件（存储快照时主 worktree 的 HEAD commit hash）
 │       └── ...
 └── worktrees/                           # 所有 worktree 的统一存放目录
     └── <project-name>/                  # 以项目名分组
@@ -363,7 +364,7 @@ Git worktree 不会包含 `node_modules`、`.venv` 等依赖文件，每次安
 
 **快照机制：**
 
-validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`）。当再次执行 validate 时，通过 `git read-tree` 将上次快照的 tree 对象载入暂存区、最新变更保留在工作目录，用户可通过 `git diff` 直接查看两次 validate 之间的增量差异。由于 tree 对象存储在 git 对象库中，不依赖主分支 HEAD，无需一致性校验。
+validate 命令引入了**快照（snapshot）机制**来支持增量对比。每次 validate 执行成功后，会将当前全量变更通过 `git write-tree` 保存为 git tree 对象，并将 tree hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），同时将主 worktree 的 HEAD commit hash 记录到文件（`~/.clawt/validate-snapshots/<project>/<branchName>.head`），用于增量 validate 时对齐基准。当再次执行 validate 时，如果主分支 HEAD 未变化，通过 `git read-tree` 将上次快照的 tree 对象载入暂存区；如果主分支 HEAD 已变化（如合并了其他分支），则将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容。最终用户可通过 `git diff` 查看两次 validate 之间的增量差异。
 
 **运行流程：**
 
@@ -444,11 +445,12 @@ git restore --staged .
 
 ##### 步骤 4：保存快照为 git tree 对象
 
-将主 worktree 工作目录的全量变更保存为 git tree 对象：
+将主 worktree 工作目录的全量变更保存为 git tree 对象，同时记录当前 HEAD commit hash：
 
 ```bash
 git add .
 git write-tree  # → 返回 tree hash，写入 ~/.clawt/validate-snapshots/<project>/<branchName>.tree
+git rev-parse HEAD  # → 返回 HEAD commit hash，写入 ~/.clawt/validate-snapshots/<project>/<branchName>.head
 git restore --staged .
 ```
 
@@ -465,9 +467,9 @@ git restore --staged .
 
 当 `~/.clawt/validate-snapshots/<project>/<branchName>.tree` 存在时，自动进入增量模式：
 
-##### 步骤 1：读取旧 tree hash
+##### 步骤 1：读取旧快照
 
-在清空主 worktree 之前，读取上次保存的快照 tree hash。
+在清空主 worktree 之前，读取上次保存的快照 tree hash 及当时的 HEAD commit hash。
 
 ##### 步骤 2：确保主 worktree 干净
 
@@ -479,9 +481,15 @@ git restore --staged .
 
 ##### 步骤 4：保存最新快照为 git tree 对象
 
-将最新全量变更保存为新的 tree 对象（覆盖旧快照，流程同首次 validate 的步骤 4）。
+将最新全量变更保存为新的 tree 对象（覆盖旧快照），同时记录当前 HEAD commit hash（流程同首次 validate 的步骤 4）。
 
-##### 步骤 5：将旧 tree 对象载入暂存区
+##### 步骤 5：将旧变更状态载入暂存区
+
+根据主分支 HEAD 是否发生变化，选择不同的策略将旧变更载入暂存区：
+
+**情况 A：HEAD 未变化（或旧版快照无 HEAD 信息）**
+
+直接通过 `git read-tree` 将旧 tree 对象载入暂存区：
 
 ```bash
 git read-tree <旧 tree hash>
@@ -490,6 +498,28 @@ git read-tree <旧 tree hash>
 - **读取成功** → 结果：暂存区=上次快照，工作目录=最新全量变更（用户可通过 `git diff` 查看增量差异）
 - **读取失败**（tree 对象可能被 git gc 回收）→ 降级为全量模式，暂存区保持为空，等同于首次 validate 的结果
 
+**情况 B：HEAD 发生了变化（如主分支合并了其他分支）**
+
+此时旧 tree 对象基于旧 HEAD，直接 read-tree 会导致 diff 混入 HEAD 变化的内容。需要将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上：
+
+```bash
+# 获取旧 HEAD 对应的 tree hash
+git rev-parse <旧 HEAD commit hash>^{tree}  # → 旧 HEAD tree hash
+
+# 提取旧变更 patch（旧 HEAD tree → 旧快照 tree 的差异）
+git diff-tree -p --binary <旧 HEAD tree hash> <旧快照 tree hash>
+
+# 检测 patch 能否无冲突地应用到暂存区
+git apply --cached --check < patch
+
+# 无冲突：apply --cached 到当前 HEAD 暂存区
+git apply --cached < patch
+```
+
+- **patch 为空**（旧变更为空）→ 暂存区保持干净
+- **无冲突** → apply --cached 到当前 HEAD 暂存区，结果与情况 A 一致
+- **有冲突** → 降级为全量模式（暂存区保持为空），等同于首次 validate 的结果
+
 ##### 步骤 6：输出成功提示
 
 ```
@@ -654,7 +684,7 @@ clawt merge -b <branchName> [-m <commitMessage>]
 ✓ 分支 feature-scheme-1 已成功合并到当前分支
 ```
 
-9. **merge 成功后清理 worktree 和分支（可选）**
+9. **merge 成功后确认并清理 worktree 和分支（可选）**
    - 如果配置文件中 `autoDeleteBranch` 为 `true`，自动执行清理
    - 否则交互式询问用户是否清理
    - 用户确认后，依次执行：
@@ -670,9 +700,9 @@ clawt merge -b <branchName> [-m <commitMessage>]
    - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
 
 10. **清理 validate 快照**
-    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），自动删除该快照文件（merge 成功后快照已无意义）
+    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree` 和 `<branchName>.head`），自动删除这些快照文件（merge 成功后快照已无意义）
 
-> **注意：** 清理确认在 merge 操作之前询问（避免 merge 成功后因交互中断而遗留未清理的 worktree），但清理操作在 merge 成功后才执行。
+> **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。
 
 ---
 
@@ -936,7 +966,7 @@ clawt sync -b <branchName>
        clawt validate -b <branch> 验证变更
      ```
    - **无冲突** → 继续
-7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 文件），自动删除（代码基础已变化，旧快照无效）
+7. **清除 validate 快照**：合并成功后，如果该分支存在 validate 快照（`.tree` 和 `.head` 文件），自动删除（代码基础已变化，旧快照无效）
 8. **输出成功提示**：
    ```
    ✓ 已将 <mainBranch> 的最新代码同步到 <branchName>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawt",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "本地并行执行多个Claude Code Agent任务，融合 Git Worktree 与 Claude Code CLI 的命令行工具",
   "type": "module",
   "main": "dist/index.js",

package/src/commands/merge.ts

@@ -105,7 +105,7 @@ async function shouldCleanupAfterMerge(branchName: string): Promise<boolean> {
     printInfo(`已配置自动删除，merge 成功后将自动清理 worktree 和分支: ${branchName}`);
     return true;
   }
-  return confirmAction(`merge 成功后是否删除对应的 worktree 和分支 (${branchName})？`);
+  return confirmAction(`是否删除对应的 worktree 和分支 (${branchName})？`);
 }
 
 /**
@@ -153,9 +153,6 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     return;
   }
 
-  // merge 前确认是否清理 worktree 和分支
-  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
-
   // 步骤 4：根据目标 worktree 状态决定是否需要提交
   const targetClean = isWorkingDirClean(targetWorktreePath);
 
@@ -206,7 +203,8 @@ async function handleMerge(options: MergeOptions): Promise<void> {
     printSuccess(MESSAGES.MERGE_SUCCESS_NO_MESSAGE(options.branch, autoPullPush));
   }
 
-  // 步骤 9：merge 成功后清理 worktree 和分支
+  // 步骤 9：merge 成功后确认并清理 worktree 和分支
+  const shouldCleanup = await shouldCleanupAfterMerge(options.branch);
   if (shouldCleanup) {
     cleanupWorktreeAndBranch(targetWorktreePath, options.branch);
   }

package/src/commands/validate.ts

@@ -21,12 +21,17 @@ import {
   gitCleanForce,
   gitDiffBinaryAgainstBranch,
   gitApplyFromStdin,
+  gitApplyCachedFromStdin,
   gitResetSoft,
   gitWriteTree,
   gitReadTree,
+  getHeadCommitHash,
+  getCommitTreeHash,
+  gitDiffTree,
+  gitApplyCachedCheck,
   hasLocalCommits,
   hasSnapshot,
-  readSnapshotTreeHash,
+  readSnapshot,
   writeSnapshot,
   removeSnapshot,
   confirmDestructiveAction,
@@ -148,6 +153,7 @@ function migrateChangesViaPatch(targetWorktreePath: string, mainWorktreePath: st
 /**
  * 保存当前主 worktree 工作目录变更为 git tree 对象快照
  * 操作序列：git add . → git write-tree → git restore --staged .
+ * 同时保存当前 HEAD commit hash，用于增量 validate 时对齐基准
  * @param {string} mainWorktreePath - 主 worktree 路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
@@ -157,7 +163,8 @@ function saveCurrentSnapshotTree(mainWorktreePath: string, projectName: string,
   gitAddAll(mainWorktreePath);
   const treeHash = gitWriteTree(mainWorktreePath);
   gitRestoreStaged(mainWorktreePath);
-  writeSnapshot(projectName, branchName, treeHash);
+  const headCommitHash = getHeadCommitHash(mainWorktreePath);
+  writeSnapshot(projectName, branchName, treeHash, headCommitHash);
   return treeHash;
 }
 
@@ -225,8 +232,8 @@ function handleFirstValidate(targetWorktreePath: string, mainWorktreePath: strin
  * @param {boolean} hasUncommitted - 目标 worktree 是否有未提交修改
  */
 function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath: string, projectName: string, branchName: string, hasUncommitted: boolean): void {
-  // 步骤 1：读取旧 tree hash（在清空前读取）
-  const oldTreeHash = readSnapshotTreeHash(projectName, branchName);
+  // 步骤 1：读取旧快照（tree hash + 当时的 HEAD commit hash）
+  const { treeHash: oldTreeHash, headCommitHash: oldHeadCommitHash } = readSnapshot(projectName, branchName);
 
   // 步骤 2：确保主 worktree 干净（调用方已通过 handleDirtyMainWorktree 处理）
   // 这里做兜底清理，防止 handleDirtyMainWorktree 之后仍有残留
@@ -238,12 +245,35 @@ function handleIncrementalValidate(targetWorktreePath: string, mainWorktreePath:
   // 步骤 3：通过 patch 从目标分支获取最新全量变更
   migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted);
 
-  // 步骤 4：保存最新快照为 git tree 对象
+  // 步骤 4：保存最新快照为 git tree 对象（同时记录当前 HEAD）
   saveCurrentSnapshotTree(mainWorktreePath, projectName, branchName);
 
-  // 步骤 5：将旧 tree 对象载入暂存区（恢复上次快照状态）
+  // 步骤 5：将旧变更状态载入暂存区
   try {
-    gitReadTree(oldTreeHash, mainWorktreePath);
+    const currentHeadCommitHash = getHeadCommitHash(mainWorktreePath);
+
+    if (oldHeadCommitHash && oldHeadCommitHash !== currentHeadCommitHash) {
+      // HEAD 发生了变化（如主分支合并了其他分支）：
+      // 将旧变更 patch（旧 tree 相对于旧 HEAD 的差异）重放到当前 HEAD 暂存区上，
+      // 避免新旧 tree 基准不同导致 diff 混入 HEAD 变化的内容
+      const oldHeadTreeHash = getCommitTreeHash(oldHeadCommitHash, mainWorktreePath);
+      const oldChangePatch = gitDiffTree(oldHeadTreeHash, oldTreeHash, mainWorktreePath);
+
+      if (oldChangePatch.length > 0 && gitApplyCachedCheck(oldChangePatch, mainWorktreePath)) {
+        // 无冲突：apply --cached 到当前 HEAD 暂存区
+        gitApplyCachedFromStdin(oldChangePatch, mainWorktreePath);
+      } else if (oldChangePatch.length > 0) {
+        // 有冲突：降级为全量模式（暂存区保持为空）
+        logger.warn('旧变更 patch 与当前 HEAD 冲突，降级为全量模式');
+        printWarning(MESSAGES.INCREMENTAL_VALIDATE_FALLBACK);
+        printSuccess(MESSAGES.VALIDATE_SUCCESS(branchName));
+        return;
+      }
+      // oldChangePatch 为空表示旧变更为空，暂存区保持干净即可
+    } else {
+      // HEAD 未变化（或旧版快照无 HEAD 信息）：直接 read-tree 旧快照
+      gitReadTree(oldTreeHash, mainWorktreePath);
+    }
   } catch (error) {
     // 旧 tree 对象无法读取（可能被 git gc 回收），降级为全量模式
     logger.warn(`增量 read-tree 失败: ${error}`);

package/src/utils/git.ts

@@ -425,3 +425,43 @@ export function gitWriteTree(cwd?: string): string {
 export function gitReadTree(treeHash: string, cwd?: string): void {
   execCommand(`git read-tree ${treeHash}`, { cwd });
 }
+
+/**
+ * 获取指定 commit 对应的 tree 对象 hash
+ * @param {string} commitHash - commit hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {string} tree 对象的 hash
+ */
+export function getCommitTreeHash(commitHash: string, cwd?: string): string {
+  return execCommand(`git rev-parse ${commitHash}^{tree}`, { cwd });
+}
+
+/**
+ * 获取两个 tree 对象之间的 diff（patch 格式，含二进制）
+ * @param {string} baseTreeHash - 基准 tree hash
+ * @param {string} targetTreeHash - 目标 tree hash
+ * @param {string} [cwd] - 工作目录
+ * @returns {Buffer} diff patch 内容
+ */
+export function gitDiffTree(baseTreeHash: string, targetTreeHash: string, cwd?: string): Buffer {
+  logger.debug(`执行命令: git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}${cwd ? ` (cwd: ${cwd})` : ''}`);
+  return execSync(`git diff-tree -p --binary ${baseTreeHash} ${targetTreeHash}`, {
+    cwd,
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * 检测 patch 能否无冲突地应用到暂存区（干运行，不实际修改）
+ * @param {Buffer} patchContent - patch 内容（Buffer 格式）
+ * @param {string} [cwd] - 工作目录
+ * @returns {boolean} patch 能否成功应用
+ */
+export function gitApplyCachedCheck(patchContent: Buffer, cwd?: string): boolean {
+  try {
+    execCommandWithInput('git', ['apply', '--cached', '--check'], { input: patchContent, cwd });
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/index.ts

@@ -40,6 +40,9 @@ export {
   gitResetSoftTo,
   gitWriteTree,
   gitReadTree,
+  getCommitTreeHash,
+  gitDiffTree,
+  gitApplyCachedCheck,
 } from './git.js';
 export { sanitizeBranchName, generateBranchNames, validateBranchesNotExist } from './branch.js';
 export { validateMainWorktree, validateGitInstalled, validateClaudeCodeInstalled } from './validation.js';
@@ -49,4 +52,4 @@ export { printSuccess, printError, printWarning, printInfo, printSeparator, prin
 export { ensureDir, removeEmptyDir } from './fs.js';
 export { multilineInput } from './prompt.js';
 export { launchInteractiveClaude } from './claude.js';
-export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';
+export { getSnapshotPath, hasSnapshot, readSnapshotTreeHash, readSnapshot, writeSnapshot, removeSnapshot, removeProjectSnapshots } from './validate-snapshot.js';

package/src/utils/validate-snapshot.ts

@@ -5,7 +5,7 @@ import { ensureDir } from './fs.js';
 import { logger } from '../logger/index.js';
 
 /**
- * 获取指定项目和分支的 validate 快照文件路径
+ * 获取指定项目和分支的 validate 快照 tree 文件路径
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
  * @returns {string} tree hash 文件的绝对路径
@@ -14,6 +14,16 @@ export function getSnapshotPath(projectName: string, branchName: string): string
   return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.tree`);
 }
 
+/**
+ * 获取指定项目和分支的 validate 快照 head 文件路径
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {string} head commit hash 文件的绝对路径
+ */
+function getSnapshotHeadPath(projectName: string, branchName: string): string {
+  return join(VALIDATE_SNAPSHOTS_DIR, projectName, `${branchName}.head`);
+}
+
 /**
  * 判断指定项目和分支是否存在 validate 快照
  * @param {string} projectName - 项目名
@@ -31,36 +41,61 @@ export function hasSnapshot(projectName: string, branchName: string): boolean {
  * @returns {string} tree 对象的 hash
  */
 export function readSnapshotTreeHash(projectName: string, branchName: string): string {
+  return readSnapshot(projectName, branchName).treeHash;
+}
+
+/**
+ * 读取指定项目和分支的 validate 快照（tree hash + HEAD commit hash）
+ * tree hash 从 .tree 文件读取，HEAD commit hash 从 .head 文件读取
+ * @param {string} projectName - 项目名
+ * @param {string} branchName - 分支名
+ * @returns {{ treeHash: string; headCommitHash: string }} 快照数据
+ */
+export function readSnapshot(projectName: string, branchName: string): { treeHash: string; headCommitHash: string } {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   logger.debug(`读取 validate 快照: ${snapshotPath}`);
-  return readFileSync(snapshotPath, 'utf-8').trim();
+
+  const treeHash = existsSync(snapshotPath) ? readFileSync(snapshotPath, 'utf-8').trim() : '';
+  const headCommitHash = existsSync(headPath) ? readFileSync(headPath, 'utf-8').trim() : '';
+
+  return { treeHash, headCommitHash };
 }
 
 /**
  * 写入 validate 快照内容（自动创建目录）
+ * tree hash 写入 .tree 文件，HEAD commit hash 写入 .head 文件
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
  * @param {string} treeHash - git tree 对象的 hash
+ * @param {string} headCommitHash - 快照时主 worktree 的 HEAD commit hash
  */
-export function writeSnapshot(projectName: string, branchName: string, treeHash: string): void {
+export function writeSnapshot(projectName: string, branchName: string, treeHash: string, headCommitHash: string): void {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   const snapshotDir = join(VALIDATE_SNAPSHOTS_DIR, projectName);
   ensureDir(snapshotDir);
   writeFileSync(snapshotPath, treeHash, 'utf-8');
-  logger.info(`已保存 validate 快照: ${snapshotPath}`);
+  writeFileSync(headPath, headCommitHash, 'utf-8');
+  logger.info(`已保存 validate 快照: ${snapshotPath}, ${headPath}`);
 }
 
 /**
- * 删除指定项目和分支的 validate 快照
+ * 删除指定项目和分支的 validate 快照（.tree + .head）
  * @param {string} projectName - 项目名
  * @param {string} branchName - 分支名
  */
 export function removeSnapshot(projectName: string, branchName: string): void {
   const snapshotPath = getSnapshotPath(projectName, branchName);
+  const headPath = getSnapshotHeadPath(projectName, branchName);
   if (existsSync(snapshotPath)) {
     unlinkSync(snapshotPath);
     logger.info(`已删除 validate 快照: ${snapshotPath}`);
   }
+  if (existsSync(headPath)) {
+    unlinkSync(headPath);
+    logger.info(`已删除 validate 快照: ${headPath}`);
+  }
 }
 
 /**

package/CLAUDE.md

@@ -1,105 +0,0 @@
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## 项目概述
-
-Clawt 是一个 CLI 工具，融合 Git Worktree 与 Claude Code CLI，支持在本地并行执行多个 Claude Code Agent 任务。核心思路：为每个任务创建独立的 git worktree，在各自隔离的环境中并行调用 `claude -p` 执行任务，互不干扰。
-
-## 构建与开发
-
-```bash
-npm run build     # 使用 tsup 构建到 dist/
-npm run dev       # tsup --watch 模式
-npm i -g .        # 本地全局安装进行测试
-```
-
-构建工具为 tsup，入口 `src/index.ts`，输出 ESM 格式，target node18。构建产物在 `dist/index.js` 带有 shebang 头。另有 `scripts/postinstall.ts` 作为独立入口构建（npm 安装后初始化 `~/.clawt/` 目录）。
-
-本项目无测试框架和 lint 工具。
-
-## 架构
-
-### 命令注册模式
-
-每个命令为独立文件 `src/commands/<name>.ts`，导出 `registerXxxCommand(program)` 函数，在 `src/index.ts` 中统一注册到 Commander。命令内部逻辑封装在对应的 `handleXxx` 函数中。
-
-十个命令：`create`、`run`、`resume`、`list`、`remove`、`validate`、`merge`、`config`、`sync`、`reset`。
-
-### 核心流程（run 命令）
-
-run 命令有两种模式：
-
-**模式一：不传 `--tasks`（交互式界面模式）**
-
-1. `validateMainWorktree()` 确认在主 worktree 根目录
-2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
-3. 检测分支是否已存在（`checkBranchExists()`），已存在则提示使用 `clawt resume -b <branch>` 恢复会话
-4. `createWorktrees()` 创建单个 worktree
-5. `launchInteractiveClaude()` 通过 `spawnSync` + `inherit stdio` 在 worktree 中直接启动 Claude Code 交互式界面（启动命令由配置项 `claudeCodeCommand` 指定，默认 `claude`）
-
-**模式二：传 `--tasks`（并行任务模式）**
-
-1. `validateMainWorktree()` 确认在主 worktree 根目录
-2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
-3. `createWorktrees()` 批量创建 git worktree（串行）
-4. `executeClaudeTask()` 通过 `spawnProcess` 并行调用 `claude -p <task> --output-format json --permission-mode bypassPermissions`
-5. 每个任务完成时实时输出通知，全部完成后输出汇总
-6. SIGINT（Ctrl+C）中断处理：`killAllChildProcesses()` 终止所有子进程 → 等待退出 → `handleInterruptCleanup()` 根据 `autoDeleteBranch` 配置自动或交互式清理 worktree 和分支
-
-### resume 命令流程
-
-1. `validateMainWorktree()` 确认在主 worktree 根目录
-2. `validateClaudeCodeInstalled()` 确认 claude CLI 可用
-3. `resolveTargetWorktree()` 解析目标 worktree（`-b` 可选）：
-   - 未传 `-b`：仅 1 个 worktree 直接使用，多个通过 `promptSelectBranch()`（Enquirer.Select）交互选择
-   - 传了 `-b`：`findExactMatch()` 精确匹配 → `findFuzzyMatches()` 子串模糊匹配（大小写不敏感，唯一直接使用，多个交互选择） → 无匹配报错并列出可用分支
-4. `launchInteractiveClaude()` 在目标 worktree 中启动 Claude Code 交互式界面
-
-### validate + merge 工作流
-
-- `validate`：将目标分支的全量变更（已提交 + 未提交）通过 `git diff HEAD...branch --binary` 的 patch 方式迁移到主 worktree，便于在主 worktree 中测试。支持两种模式：
-  - **首次 validate**（无历史快照）：patch 迁移全量变更 → 通过 `git write-tree` 保存快照为 git tree 对象 → 结果：暂存区=空，工作目录=全量变更
-  - **增量 validate**（存在历史快照）：读取旧 tree hash → 确保主 worktree 干净 → patch 迁移最新变更 → 保存新 tree 对象快照 → `git read-tree` 将旧 tree 载入暂存区 → 结果：暂存区=上次快照，工作目录=最新变更（可通过 `git diff` 查看增量差异）
-  - `--clean` 选项：根据 `confirmDestructiveOps` 配置提示确认 → 重置主 worktree + 删除对应快照文件
-  - 快照存储路径：`~/.clawt/validate-snapshots/<projectName>/<branchName>.tree`（存储 git tree 对象 hash）
-  - tree 对象不依赖主分支 HEAD，无需一致性校验
-  - 变更检测：同时检测目标 worktree 的未提交修改和已提交 commit，两者均无则提示无需验证
-  - 未提交修改处理：有未提交修改时先做临时 commit，diff 完成后通过 `git reset --soft` 撤销恢复原状
-- `merge`：检测目标 worktree 状态（有修改则需 `-m` 提交，已提交则跳过，无变更则报错）→ **squash 检测**（检查目标分支是否存在 `AUTO_SAVE_COMMIT_MESSAGE` 前缀的 auto-save commit，如有则提示用户是否压缩所有提交：用户确认后通过 `gitMergeBase` 计算分叉点、`gitResetSoftTo` 将所有 commit reset 到暂存区；有 `-m` 则直接提交继续流程，无 `-m` 则提示用户自行提交后退出）→ 合并到主 worktree → 根据 `autoPullPush` 配置决定是否 pull + push（成功消息动态显示推送状态）→ 可选清理 worktree 和分支（受 `autoDeleteBranch` 配置或交互式确认控制）→ 清理对应的 validate 快照
-- `run` 中断清理：Ctrl+C 终止所有子进程后，根据 `autoDeleteBranch` 配置自动清理或交互式确认清理本次创建的 worktree 和分支
-
-### sync 命令流程
-
-1. `validateMainWorktree()` 确认在主 worktree 根目录
-2. 检查目标 worktree 是否存在
-3. 获取主分支名（`getCurrentBranch()`，不硬编码 main/master）
-4. 如果目标 worktree 有未提交变更，自动 `git add . && git commit` 保存
-5. 在目标 worktree 中执行 `git merge <mainBranch>` 合并主分支
-6. 冲突处理：有冲突时提示用户手动解决，无冲突则输出成功
-7. 合并成功后清除该分支的 validate 快照（代码基础已变化，旧快照无效）
-
-### reset 命令流程
-
-1. `validateMainWorktree()` 确认在主 worktree 根目录
-2. 检测主 worktree 工作区和暂存区是否干净（`isWorkingDirClean()`）
-3. 不干净 → 根据 `confirmDestructiveOps` 配置决定是否通过 `confirmDestructiveAction()` 提示确认 → `gitResetHard()` + `gitCleanForce()` 重置工作区和暂存区（保留 validate 快照）
-4. 已干净 → 提示无需重置
-
-### 目录层级
-
-- `src/commands/` — 各命令的注册与处理逻辑
-- `src/utils/` — 工具函数（git 操作（含三点 diff、分支合并、冲突检测、merge-base 计算、commit message 检测、soft reset 到指定 commit、write-tree/read-tree、分支存在性检测等）、shell 执行与子进程管理、分支名处理、worktree 管理与批量清理、配置、格式化输出与破坏性操作确认、交互式输入、Claude Code 交互式启动、validate 快照管理（基于 git tree 对象））
-- `src/constants/` — 常量定义（路径、退出码、消息模板、分支规则、配置默认值、终端控制序列、validate 快照目录、sync 相关消息、git 常量（如 `AUTO_SAVE_COMMIT_MESSAGE`）、squash 相关消息、reset 相关消息、remove 相关消息、破坏性操作确认消息）
-- `src/types/` — TypeScript 类型定义
-- `src/errors/` — 自定义 `ClawtError` 错误类（携带退出码）
-- `src/logger/` — winston 日志（按日期滚动，写入 `~/.clawt/logs/`）
-
-### 关键约定
-
-- 所有命令执行前都会调用 `validateMainWorktree()` 确保在主 worktree 根目录（`git rev-parse --git-common-dir === ".git"`）
-- Worktree 统一存放在 `~/.clawt/worktrees/<projectName>/` 下
-- 全局配置文件 `~/.clawt/config.json`，postinstall 时自动创建/合并，包含 `autoDeleteBranch`（是否自动删除分支）、`claudeCodeCommand`（Claude Code CLI 启动指令，用于 `run` 和 `resume` 的交互式界面）、`autoPullPush`（merge 后是否自动 pull/push）、`confirmDestructiveOps`（破坏性操作前是否提示确认，影响 `reset` 和 `validate --clean`）四个配置项。配置项以 `CONFIG_DEFINITIONS` 为单一数据源，`DEFAULT_CONFIG` 和 `CONFIG_DESCRIPTIONS` 均从中派生
-- shell 命令执行有同步（`execCommand` → `execSync`）、异步（`spawnProcess` → `spawn`）和同步带 stdin（`execCommandWithInput` → `execFileSync`）三种方式
-- 项目为纯 ESM（`"type": "module"`），模块导入需带 `.js` 后缀
-- 分支名特殊字符会被 `sanitizeBranchName()` 自动清理