clawt 3.5.3 → 3.6.1

package/docs/cover-validate.md

@@ -1,94 +0,0 @@
-### 5.21 将验证分支修改覆盖回目标 Worktree
-
-**命令：**
-
-```bash
-clawt cover
-```
-
-> 无需指定分支名，自动从当前验证分支名（`clawt-validate-<branchName>`）中推导目标分支。
-
-**参数：**
-
-无额外参数。必须在验证分支上执行。
-
-**使用场景：**
-
-在 `validate` 验证过程中，用户可能会在主 worktree（验证分支上）对代码进行修改（如修复测试失败、调整逻辑等）。`cover` 命令用于将这些修改覆盖回目标 worktree，使目标 worktree 的代码与验证分支上的最新状态同步。
-
-**运行流程：**
-
-##### 步骤 1：前置校验
-
-1. **主 worktree 校验**（`requireMainWorktree`）
-2. **HEAD 校验**（`requireHead`）
-3. **项目级配置校验**（`requireProjectConfig`）
-4. **验证分支校验**：当前分支必须以 `clawt-validate-` 开头，否则报错退出
-
-##### 步骤 2：查找目标 worktree
-
-从验证分支名中提取目标分支名（去掉 `clawt-validate-` 前缀），然后在项目的 worktree 列表中精确匹配目标分支对应的 worktree。如果目标 worktree 不存在（可能已被移除），报错退出。
-
-##### 步骤 3：校验快照存在并读取
-
-校验目标分支的 validate 快照是否存在。如果快照不存在，提示用户先执行 `clawt validate -b <branch>` 创建快照。读取快照中的 tree hash（`snapshotTreeHash`），作为增量计算的基准。
-
-##### 步骤 3.5：工作区干净检查
-
-检测主 worktree（验证分支上）的工作区和暂存区是否干净（`isWorkingDirClean`）：
-
-- **不干净**（有修改）→ 正常继续，这是 cover 的典型使用场景
-- **干净**（无修改）→ 输出提示信息 `当前验证分支的工作区和暂存区没有任何修改，可能为误操作`，并通过 `confirmAction` 询问用户 `是否继续执行覆盖？`：
-  - 用户确认 → 继续执行
-  - 用户取消 → 直接返回，不执行后续步骤
-
-> 工作区干净时通常意味着用户没有在验证分支上做任何修改就执行了 cover，这大概率是误操作。增加确认提示可以避免不必要的覆盖操作。
-
-##### 步骤 4：计算增量 patch
-
-通过 `computeIncrementalPatch()` 计算验证分支上相对于快照的增量变更：
-
-1. 保存当前暂存区的 tree hash（`savedIndexTreeHash`），用于后续恢复
-2. `git add .` + `git write-tree` 获取当前工作区的完整 tree hash（`currentTreeHash`）
-3. 通过 `git read-tree` 恢复原始暂存区状态（无论成功失败都执行，在 `finally` 块中）
-4. 比较 `snapshotTreeHash` 与 `currentTreeHash`：
-   - **相同** → 无增量变更，输出提示后返回
-   - **不同** → 通过 `git diff-tree` 生成 patch
-
-##### 步骤 5：应用 patch 到目标 worktree
-
-将增量 patch 通过 `git apply --binary` 应用到目标 worktree 的工作区。如果 patch apply 失败，报错退出并提示用户检查目标 worktree 工作区状态。
-
-##### 步骤 6：更新快照
-
-将 `currentTreeHash` 写入快照的 `.tree` 文件，使后续再次 cover 时的基准正确。**只更新 `treeHash`，不更新 `headCommitHash` 和 `stagedTreeHash`**（保留 validate 时写入的原值）。
-
-##### 步骤 7：输出成功提示
-
-```
-✓ 已将验证分支上的修改覆盖到 worktree => <branchName>
-```
-
-**错误消息：**
-
-| 消息常量 | 触发条件 | 提示内容 |
-| -------- | -------- | -------- |
-| `COVER_VALIDATE_NOT_ON_VALIDATE_BRANCH` | 当前分支不是验证分支 | 提示先通过 `clawt validate` 切换到验证分支 |
-| `COVER_VALIDATE_TARGET_NOT_FOUND` | 目标 worktree 不存在 | 提示确认该 worktree 尚未被移除 |
-| `COVER_VALIDATE_NO_SNAPSHOT` | 无快照 | 提示先执行 `clawt validate -b <branch>` 创建快照 |
-| `COVER_VALIDATE_NO_CHANGES` | 无增量变更 | 提示无需覆盖 |
-| `COVER_VALIDATE_WORKING_DIR_CLEAN` | 工作区干净 | 提示可能为误操作，需确认是否继续 |
-| `COVER_VALIDATE_APPLY_FAILED` | patch 应用失败 | 提示检查目标 worktree 工作区状态后重试 |
-
-**实现要点：**
-
-- 命令注册名为 `cover`（非 `cover-validate`），用户通过 `clawt cover` 调用
-- 核心函数：`handleCoverValidate()`（`src/commands/cover-validate.ts`）
-- 辅助函数：
-  - `extractTargetBranchName()`：从验证分支名提取目标分支名
-  - `findTargetWorktreePath()`：查找目标 worktree 路径
-  - `computeIncrementalPatch()`：计算增量 patch
-- 消息常量：`COVER_VALIDATE_MESSAGES`（`src/constants/messages/cover-validate.ts`）
-- `writeSnapshot` 调用时只传 `treeHash`，利用其可选参数特性保留磁盘上的 `headCommitHash` 和 `stagedTreeHash` 原值
-
----

package/docs/create.md

@@ -1,101 +0,0 @@
-### 5.1 批量创建 Worktree（Worktree 对应分支）
-
-**命令：**
-
-```bash
-clawt create -b <branchName> [-n <count>]
-```
-
-**参数：**
-
-| 参数 | 必填 | 说明                                                  |
-| ---- | ---- | ----------------------------------------------------- |
-| `-b, --branch` | 是   | 分支名                                                |
-| `-n, --number` | 否   | 需要创建的 worktree 数量，默认 `1`                      |
-
-**运行流程：**
-
-通过 `runPreChecks(PRE_CHECK_CREATE)` 执行统一前置校验，包含以下检查项：
-
-1. **主 worktree 校验**（`requireMainWorktree`）(2.1)
-2. **HEAD 存在性校验**（`requireHead`）：确保仓库有至少一次 commit
-3. **确保在主工作分支上**（`ensureOnClawtMainWorkBranch`）：在创建 worktree 之前，确保当前处于配置的主工作分支（`clawtMainWorkBranch`）上。
-   - 如果当前分支**是** `clawtMainWorkBranch`，正常继续
-   - 如果当前在**验证分支**（`clawt-validate-` 前缀）上：
-     - 验证分支上的修改视为可丢弃的临时状态
-     - 如果工作区有未提交更改，自动执行 `git reset --hard HEAD && git clean -fd` 清理；若已干净则跳过清理
-     - 然后自动切换到主工作分支，继续创建流程
-   - 如果当前在**其他普通分支**上：
-     - 首先显示警告：`当前分支 <currentBranch> 与配置的主工作分支 <mainBranch> 不一致，如需更新请执行 clawt init`
-     - 然后通过 `confirmAction('是否继续执行？')` 让用户确认是否继续；用户拒绝则抛出"已取消操作"退出
-     - 用户确认后，如果工作区有未提交的更改，提供交互式选择（避免将修改意外带到主工作分支上）：
-       ```
-       ⚠ 当前分支有未提交的更改，请选择处理方式：
-
-       ❯ reset        - 丢弃所有更改 (git reset --hard HEAD && git clean -fd)
-         stash        - 暂存更改 (git add . && git stash)
-         exit         - 退出，手动处理
-       ```
-       - 选择 reset → 执行 `git reset --hard HEAD && git clean -fd`
-       - 选择 stash → 执行 `git add . && git stash push -m "clawt:auto-stash"`
-       - 选择 exit → 抛出错误"用户选择退出，请手动处理工作区更改后重试"
-       - 处理完成后再次校验工作区是否干净，不干净则报错"工作区仍然不干净，请手动处理"
-     - 执行 `git checkout <clawtMainWorkBranch>`，然后继续创建流程
-4. **主分支工作区干净校验**（`requireCleanWorkingDir`）：确保主工作分支的工作区和暂存区干净，存在未提交更改时报错"主 worktree 有未提交的更改，请先处理"
-5. **创建数量校验**：校验 `-n` 参数必须为正整数，否则报错 `无效的创建数量: "<value>"，请输入正整数`
-6. **分支名合法性校验与转换** (2.3)
-7. **分支名存在性校验** (2.4)
-   - 若 `n = 1`：校验 `branchName`
-   - 若 `n > 1`：校验 `branchName-1` 到 `branchName-n`
-   - 所有分支名在创建任何 worktree **之前**完成全部校验
-8. **批量创建 worktree + 验证分支**
-   - 若 `n = 1`：
-     ```bash
-     git worktree add -b <branchName> ~/.clawt/worktrees/<project>/<branchName>
-     git branch clawt-validate-<branchName>
-     ```
-   - 若 `n > 1`：
-     ```bash
-     git worktree add -b <branchName>-1 ~/.clawt/worktrees/<project>/<branchName>-1
-     git branch clawt-validate-<branchName>-1
-     git worktree add -b <branchName>-2 ~/.clawt/worktrees/<project>/<branchName>-2
-     git branch clawt-validate-<branchName>-2
-     ...
-     git worktree add -b <branchName>-n ~/.clawt/worktrees/<project>/<branchName>-n
-     git branch clawt-validate-<branchName>-n
-     ```
-9. **输出创建日志**
-
-**输出格式：**
-
-```
-✓ 已创建 3 个 worktree
-
-目录路径1：
-  ~/.clawt/worktrees/main-project/feature-scheme-1
-  分支名: feature-scheme-1
-  验证分支: clawt-validate-feature-scheme-1
-────────────────────────────────────────
-目录路径2：
-  ~/.clawt/worktrees/main-project/feature-scheme-2
-  分支名: feature-scheme-2
-  验证分支: clawt-validate-feature-scheme-2
-────────────────────────────────────────
-目录路径3：
-  ~/.clawt/worktrees/main-project/feature-scheme-3
-  分支名: feature-scheme-3
-  验证分支: clawt-validate-feature-scheme-3
-────────────────────────────────────────
-```
-
-**实现要点：**
-
-- 前置校验配置定义在 `src/constants/pre-checks.ts` 的 `PRE_CHECK_CREATE` 常量中
-- 分支名清理逻辑在 `src/utils/branch.ts` 的 `sanitizeBranchName` 中
-- 分支名生成逻辑在 `src/utils/branch.ts` 的 `generateBranchNames` 中
-- worktree 批量创建逻辑在 `src/utils/worktree.ts` 的 `createWorktrees` 中
-- 确保在主工作分支的逻辑在 `src/utils/validate-branch.ts` 的 `ensureOnMainWorkBranch` 中
-- 脏工作区交互处理逻辑在 `src/utils/validate-branch.ts` 的 `handleDirtyWorkingDir` 中
-- 相关消息常量定义在 `src/constants/messages/create.ts` 和 `src/constants/messages/common.ts` 中
-
----

package/docs/home.md

@@ -1,58 +0,0 @@
-### 5.20 切换回主工作分支
-
-**命令：**
-
-```bash
-clawt home
-```
-
-**参数：**
-
-无参数。
-
-**功能说明：**
-
-快速切换回项目的主工作分支。当用户在主 worktree 中处于验证分支或其他分支时，可通过 `clawt home` 一键切换回 `clawtMainWorkBranch` 所记录的主工作分支。
-
-**运行流程：**
-
-1. **前置校验**：调用 `runPreChecks` 执行统一前置校验：
-   - `requireMainWorktree`：校验当前目录是否在主 worktree 根目录 (2.1)
-   - `requireHead`：校验 HEAD 是否存在（仓库至少有一次 commit）
-   - `requireProjectConfig`：校验项目配置文件是否存在且合法
-   - `requireMainBranchExists`：校验配置中的主工作分支在 git 仓库中是否存在
-2. **获取分支信息**：
-   - 通过 `getMainWorkBranch()` 获取主工作分支名
-   - 通过 `getCurrentBranch()` 获取当前所在分支名
-3. **判断是否需要切换**：
-   - 当前分支 === 主工作分支 → 输出提示信息，无需切换
-   - 当前分支 !== 主工作分支 → 调用 `ensureOnMainWorkBranch()` 执行切换
-4. **输出结果**
-
-**输出格式：**
-
-```
-# 已在主工作分支上
-已在主工作分支 main 上，无需切换
-
-# 切换成功
-✓ 已从 clawt-validate-feat-login 切换到主工作分支 main
-```
-
-**消息常量：**
-
-定义在 `src/constants/messages/home.ts`：
-
-| 常量 | 说明 |
-| --- | --- |
-| `HOME_ALREADY_ON_MAIN(branch)` | 已在主工作分支上，无需切换 |
-| `HOME_SWITCH_SUCCESS(from, to)` | 切换成功提示，显示原分支和目标分支 |
-
-**实现要点：**
-
-- 命令注册函数 `registerHomeCommand` 位于 `src/commands/home.ts`
-- 前置校验通过 `runPreChecks` 统一调用，传入 `requireMainWorktree`、`requireHead`、`requireProjectConfig`、`requireMainBranchExists` 四项校验
-- 主逻辑依赖 `ensureOnMainWorkBranch`、`getCurrentBranch`、`getMainWorkBranch`、`guardMainWorkBranchExists` 等工具函数
-- `ensureOnMainWorkBranch()` 仅在需要切换时才调用（当前分支不等于主工作分支时）
-
----

package/docs/init.md

@@ -1,81 +0,0 @@
-### 5.19 初始化项目级配置
-
-**命令：**
-
-```bash
-# 设置主工作分支（使用当前分支）
-clawt init
-
-# 设置主工作分支（指定分支名）
-clawt init -b <branchName>
-
-# 查看当前项目的 init 配置
-clawt init show
-```
-
-**参数：**
-
-| 参数/子命令 | 必填 | 说明 |
-| --- | --- | --- |
-| `-b` | 否 | 指定主工作分支名。不传则使用当前分支 |
-| `show` | 否 | 交互式查看和修改项目配置 |
-
-**功能说明：**
-
-初始化项目级配置，将指定分支记录为该项目的主工作分支（`clawtMainWorkBranch`）。该配置用于 `create` / `run` 时检测当前分支是否为主工作分支，并在偏离时提醒用户。`init show` 子命令提供交互式面板，可查看和修改所有项目配置项（如 `validateRunCommand`）。项目级配置的完整说明见 [project-config.md](./project-config.md)。
-
-**运行流程（设置模式）：**
-
-1. **主 worktree 校验** (2.1)
-2. **加载现有配置**：尝试读取 `~/.clawt/projects/<projectName>/config.json`（可能为 `null`）
-3. **确定主工作分支名**：
-   - 传了 `-b` → 使用指定的分支名
-   - 未传 `-b` → 先验证 HEAD 存在，再使用当前分支名（`git rev-parse --abbrev-ref HEAD`）
-4. **合并并写入项目级配置**：将 `clawtMainWorkBranch` 合并到现有配置并写入 `~/.clawt/projects/<projectName>/config.json`
-   - 配置文件不存在 → 创建新配置
-   - 配置文件已存在 → 合并现有配置，仅更新 `clawtMainWorkBranch` 字段（保留其他配置项不变）
-5. **输出成功提示**：
-   - 已有配置 → `✓ 已将主工作分支从 <旧分支> 更新为 <新分支>`
-   - 无已有配置 → `✓ 项目初始化成功，主工作分支设置为: <分支名>`
-
-**运行流程（show 模式）：**
-
-1. **主 worktree 校验** (2.1)
-2. **项目配置校验**（`requireProjectConfig`）：读取 `~/.clawt/projects/<projectName>/config.json`
-   - 配置不存在 → 抛出错误 `项目尚未初始化，请先执行 clawt init 设置主工作分支`
-   - 配置缺少 `clawtMainWorkBranch` 字段 → 抛出错误 `项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支`
-   - 配置存在且合法 → 进入交互式面板
-3. **交互式配置编辑**：调用 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），基于 `PROJECT_CONFIG_DEFINITIONS` 构建配置项列表（详见 [project-config.md](./project-config.md)）
-   - 列出所有项目配置项，显示名称、当前值和描述
-   - 用户选择配置项后，根据值类型自动选择输入方式（与全局配置的交互式编辑逻辑一致）
-4. **持久化修改**：将修改后的值合并到当前配置并写入配置文件
-5. **输出成功提示**：`✓ 项目配置 <key> 已设置为 <value>`
-
-**输出格式：**
-
-```
-# 首次初始化
-✓ 项目初始化成功，主工作分支设置为: main
-
-# 更新已有配置
-✓ 已将主工作分支从 develop 更新为 main
-
-# show 交互式修改成功
-✓ 项目配置 validateRunCommand 已设置为 npm test
-
-# show 未初始化（抛出错误）
-项目尚未初始化，请先执行 clawt init 设置主工作分支
-
-# show 配置缺少主工作分支字段（抛出错误）
-项目配置缺少主工作分支信息，请重新执行 clawt init 设置主工作分支
-```
-
-**重复执行：** 支持重复执行，后一次会合并到现有配置中更新 `clawtMainWorkBranch`，不影响其他配置项。
-
-**实现要点：**
-
-- `init show` 子命令从 JSON 展示改为交互式面板，调用 `interactiveConfigEditor`（`src/utils/config-strategy.ts`）实现通用交互式配置编辑
-- 配置项定义来自 `PROJECT_CONFIG_DEFINITIONS`（`src/constants/project-config.ts`），详见 [项目级配置文档](./project-config.md)
-- 消息常量：`MESSAGES.INIT_SELECT_PROMPT`（选择配置项提示语）、`MESSAGES.INIT_SET_SUCCESS`（修改成功提示），定义在 `src/constants/messages/init.ts`
-
----

package/docs/list.md

@@ -1,73 +0,0 @@
-### 5.8 获取当前项目所有 Worktree
-
-**命令：**
-
-```bash
-clawt list [--json]
-```
-
-**参数：**
-
-| 参数     | 必填 | 说明                                     |
-| -------- | ---- | ---------------------------------------- |
-| `--json` | 否   | 以 JSON 格式输出（仅包含 path 和 branch） |
-
-**运行流程：**
-
-1. **主 worktree 校验** (2.1)
-2. **获取项目名** (2.2)
-3. 获取项目的所有 worktree 列表（扫描 `~/.clawt/worktrees/<project>/` 目录，与 `git worktree list` 交叉验证）
-4. 根据 `--json` 选项决定输出格式：
-   - 指定 `--json` → 以 JSON 格式输出（仅包含 path 和 branch）
-   - 未指定 → 以文本格式输出（包含变更状态信息）
-
-**文本输出格式（默认）：**
-
-每个 worktree 会显示路径、分支名和变更状态。每个 worktree 条目下方额外显示一行状态信息（提交数、变更行数、未提交修改），各条目之间以空行分隔。如果某个 worktree 处于空闲状态（0 个提交、无变更、无未提交修改），其路径会以橙色高亮显示，方便用户快速识别可能需要清理或还未开始工作的 worktree。
-
-```
-当前项目: main-project
-
-  ~/.clawt/worktrees/main-project/feature-scheme-1   [feature-scheme-1]
-    3 个提交   +120 -30   (未提交修改)
-
-  ~/.clawt/worktrees/main-project/feature-scheme-2   [feature-scheme-2]
-    1 个提交   +45 -10
-
-  ~/.clawt/worktrees/main-project/feature-scheme-3   [feature-scheme-3]    ← 橙色路径（空闲）
-    0 个提交   无变更
-
-  ~/.clawt/worktrees/main-project/bugfix-login   [bugfix-login]
-    2 个提交   +80 -25
-
-共 4 个 worktree
-```
-
-如果没有 worktree：
-
-```
-当前项目: main-project
-
-  (无 worktree)
-```
-
-**JSON 输出格式（`--json`）：**
-
-```json
-{
-  "project": "main-project",
-  "total": 4,
-  "worktrees": [
-    {
-      "path": "~/.clawt/worktrees/main-project/feature-scheme-1",
-      "branch": "feature-scheme-1"
-    },
-    {
-      "path": "~/.clawt/worktrees/main-project/feature-scheme-2",
-      "branch": "feature-scheme-2"
-    }
-  ]
-}
-```
-
----

package/docs/log.md

@@ -1,67 +0,0 @@
-### 5.9 日志系统
-
-**日志目录：** `~/.clawt/logs/`
-
-**日志文件命名：** `clawt-YYYY-MM-DD.log`（按日期滚动）
-
-**日志级别：**
-
-| 级别    | 说明               | 使用场景                               |
-| ------- | ------------------ | -------------------------------------- |
-| `debug` | 调试信息           | Git 命令执行详情、变量值等               |
-| `info`  | 一般信息           | 操作开始/完成、创建/移除 worktree 等     |
-| `warn`  | 警告信息           | 分支名被转换、非致命异常等              |
-| `error` | 错误信息           | 命令执行失败、校验不通过等               |
-
-**实现方案：** 使用 `winston` + `winston-daily-rotate-file` 库。
-
-**日志格式：**
-
-```
-[2025-02-06 14:30:22] [INFO ] 创建 worktree: ~/.clawt/worktrees/main-project/feature-scheme-1
-[2025-02-06 14:30:22] [DEBUG] 执行命令: git worktree add -b feature-scheme-1 ~/.clawt/worktrees/main-project/feature-scheme-1
-[2025-02-06 14:30:23] [WARN ] 分支名已转换: feature/a.b → feature-a-b
-[2025-02-06 14:30:25] [ERROR] 分支 feature-scheme-1 已存在，无法创建
-```
-
-**保留策略：**
-
-- 日志文件保留 30 天
-- 单个日志文件最大 10MB
-
-#### `--debug` 控制台调试输出
-
-通过全局选项 `--debug` 可将调试日志实时输出到终端，方便排查问题。
-
-**实现机制：**
-
-- 在 Commander.js 的 `preAction` 钩子中检测 `--debug` 选项，按需调用 `enableConsoleTransport()` 函数
-- `enableConsoleTransport()` 动态向 winston 实例添加 `Console` transport（level 为 `debug`），该函数幂等，多次调用不会重复添加 transport
-- 相关常量定义在 `src/constants/logger.ts`：
-  - `DEBUG_TIMESTAMP_FORMAT`：时间戳格式（`HH:mm:ss.SSS`，精简，不含日期）
-
-**控制台日志格式：**
-
-```
-HH:mm:ss.SSS LEVEL 消息内容
-```
-
-**日志级别颜色映射：**
-
-| 级别    | 颜色   |
-| ------- | ------ |
-| `error` | 红色   |
-| `warn`  | 黄色   |
-| `info`  | 青色   |
-| `debug` | 灰色   |
-
-**使用示例：**
-
-```bash
-clawt run -b feature-login --debug
-clawt validate -b feature-scheme --debug
-```
-
-> **注意：** `--debug` 选项不影响文件日志（file transport），文件日志始终按原有策略写入。控制台输出仅在传入 `--debug` 时启用。
-
----

package/docs/merge.md

@@ -1,137 +0,0 @@
-### 5.6 合并验证过的分支
-
-**命令：**
-
-```bash
-# 指定分支名（支持模糊匹配）
-clawt merge -b <branchName> [-m <commitMessage>]
-
-# 不指定分支名（列出所有分支供选择）
-clawt merge [-m <commitMessage>]
-```
-
-**参数：**
-
-| 参数 | 必填 | 说明                                                                     |
-| ---- | ---- | ------------------------------------------------------------------------ |
-| `-b` | 否   | 要合并的分支名（支持模糊匹配，不传则列出所有分支供选择）                   |
-| `-m` | 否   | 提交信息（目标 worktree 工作区有修改时必填）                               |
-
-**运行流程：**
-
-1. **主 worktree 校验** (2.1)
-2. **确保在主工作分支上**（`ensureOnMainWorkBranch`）：确保当前处于主工作分支上。如果在验证分支上，清理工作区后切回；如果在其他分支上，检查工作区是否干净，不干净则交互处理（reset/stash/exit），然后切回主工作分支。
-3. **解析目标 worktree**：根据 `-b` 参数解析目标 worktree，匹配策略如下：
-   - **未传 `-b` 参数**：
-     - 获取当前项目所有 worktree
-     - 无可用 worktree → 报错退出
-     - 仅 1 个 worktree → 直接使用，无需选择
-     - 多个 worktree → 通过交互式列表（Enquirer.Select）让用户选择
-   - **传了 `-b` 参数**：
-     1. **精确匹配优先**：在 worktree 列表中查找分支名完全相同的 worktree，找到则直接使用
-     2. **模糊匹配**（子串匹配，大小写不敏感）：
-        - 唯一匹配 → 直接使用
-        - 多个匹配 → 通过交互式列表让用户从匹配结果中选择
-     3. **无匹配** → 报错退出，并列出所有可用分支名
-4. **主 worktree 状态检测**
-   - 执行 `git status --porcelain`
-   - 如果有更改：
-     - 如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree`），额外输出警告 `主 worktree 可能存在 validate 残留状态，可先执行 clawt validate -b <branchName> --clean 清理`
-     - 提示 `主 worktree 有未提交的更改，请先处理`，退出
-   - 无更改 → 继续
-5. **Squash 检测与执行（auto-save 临时提交压缩）**
-   - 通过 `git log HEAD..<branchName> --format=%s` 检查目标分支是否存在以 `AUTO_SAVE_COMMIT_MESSAGE`（`chore: auto-save before sync`）为前缀的 commit
-   - **不存在** → 跳过，进入步骤 6
-   - **存在** → 提示用户是否将所有提交压缩为一个：
-     ```
-     检测到 sync 产生的临时提交，是否将所有提交压缩为一个？
-       压缩后变更将保留在目标worktree的暂存区，需要重新提交（可使用 Claude Code Cli或其他工具生成提交信息）
-     ```
-   - **用户选择不压缩** → 跳过，进入步骤 6
-   - **用户选择压缩** →
-     1. 获取主分支名（从项目级配置 `clawtMainWorkBranch` 获取）
-     2. 计算分叉点：`git merge-base <mainBranch> <branchName>`
-     3. 在目标 worktree 中执行 `git reset --soft <merge-base>`，将所有 commit 撤销到暂存区
-     4. 如果用户提供了 `-m` → 直接在目标 worktree 执行 `git commit -m '<commitMessage>'`，输出成功提示，继续步骤 6
-     5. 如果用户未提供 `-m` → 提示用户前往目标 worktree 自行提交后重新执行 `clawt merge`：
-        ```
-        ✓ 已将所有提交压缩到暂存区
-          请在目标 worktree 中提交后重新执行 merge：
-          cd <worktreePath>
-          提交完成后执行：clawt merge -b <branch>
-        ```
-        **退出流程**
-6. **根据目标 worktree 状态决定是否需要提交**
-   - 检测目标 worktree 工作区是否干净（`git status --porcelain`）
-   - **工作区有未提交修改**：
-     - 如果用户未提供 `-m`，提示 `<worktreePath> 有未提交的修改，请通过 -m 参数提供提交信息`（其中 `<worktreePath>` 为目标 worktree 的完整路径），退出
-     - 提供了 `-m` → 执行提交：
-       ```bash
-       cd ~/.clawt/worktrees/<project>/<branchName>
-       git add .
-       git commit -m '<commitMessage>'
-       ```
-   - **工作区干净**：
-     - 检查目标分支相对于主分支是否有本地提交（`git log HEAD..<branchName> --oneline`）
-     - 有本地提交 → 跳过提交步骤，直接进入合并
-     - 无本地提交 → 提示 `目标 worktree 没有任何可合并的变更（工作区干净且无本地提交）`，退出
-7. **回到主 worktree 进行合并**
-   ```bash
-   cd <主 worktree 路径>
-   git merge <branchName>
-   ```
-8. **冲突检测**（双层机制）
-   - **try-catch 层**：`git merge` 抛出异常时，先检查是否有冲突，有冲突则报错退出，否则重新抛出原始异常
-   - **二次确认层**：即使 merge 未抛异常，也再次检查是否有合并冲突
-   - **有冲突** → 提示 `合并存在冲突，请手动处理：\n  解决冲突后执行 git add . && git merge --continue`，退出
-   - **无冲突** → 继续
-9. **推送（受 `autoPullPush` 配置控制）**
-   - `autoPullPush` 为 `false` → 输出提示 `已跳过自动 pull/push，请手动执行 git pull && git push`
-   - `autoPullPush` 为 `true` → 执行 `git pull` + `git push`：
-     - `git pull` 失败且有冲突 → 输出警告 `自动 pull 时发生冲突，merge 已完成但远程同步失败`，退出（不再 push）
-     - `git pull` 失败且无冲突 → 抛出错误
-     - `git push` 失败 → 输出警告 `自动 push 失败，merge 和 pull 已完成\n  请手动执行 git push`，退出
-10. **输出成功提示**
-
-```
-# 提供了 -m 且已推送时
-✓ 分支 feature-scheme-1 已成功合并到当前分支
-  提交信息: <commitMessage>
-  已推送到远程仓库
-
-# 提供了 -m 但未推送时
-✓ 分支 feature-scheme-1 已成功合并到当前分支
-  提交信息: <commitMessage>
-
-# 未提供 -m 且已推送时
-✓ 分支 feature-scheme-1 已成功合并到当前分支
-  已推送到远程仓库
-
-# 未提供 -m 且未推送时
-✓ 分支 feature-scheme-1 已成功合并到当前分支
-```
-
-11. **merge 成功后确认并清理 worktree 和分支（可选）**
-   - 如果配置文件中 `autoDeleteBranch` 为 `true`，自动执行清理
-   - 否则交互式询问用户是否清理
-   - 用户确认后，依次执行：
-     ```bash
-     # 移除 worktree
-     git worktree remove -f <worktree路径>
-     # 删除本地分支
-     git branch -D <branchName>
-     # 同步删除验证分支
-     git branch -D clawt-validate-<branchName>
-     # 修剪 worktree 引用
-     git worktree prune
-     # 如果项目 worktree 目录为空，则清理空目录
-     ```
-   - 输出清理成功提示：`✓ 已清理 worktree 和分支: <branchName>`
-   - 验证分支的删除时机与目标分支保持一致（见 [2.5 验证分支生命周期](#25-验证分支)）：用户确认清理 → 同步删除验证分支；用户拒绝清理 → 验证分支也保留
-
-12. **清理 validate 快照**
-    - merge 成功后，如果存在该分支的 validate 快照（`~/.clawt/validate-snapshots/<project>/<branchName>.tree` 和 `<branchName>.head`），自动删除这些快照文件（merge 成功后快照已无意义）
-
-> **注意：** 清理确认和清理操作均在 merge 成功后执行。只有 merge 成功才会询问用户是否清理 worktree 和分支，避免 merge 冲突时用户被提前询问造成困惑。
-
----