clawt 3.6.0 → 3.6.2

package/docs/alias.md

@@ -1,114 +0,0 @@
-### 5.15 命令别名管理
-
-**命令：**
-
-```bash
-# 列出所有命令别名
-clawt alias
-clawt alias list
-
-# 设置命令别名
-clawt alias set <alias> <command>
-
-# 移除命令别名
-clawt alias remove <alias>
-```
-
-**子命令：**
-
-| 子命令 | 说明 |
-| ------ | ---- |
-| `clawt alias` / `clawt alias list` | 列出所有已配置的命令别名 |
-| `clawt alias set <alias> <command>` | 设置命令别名，将 `<alias>` 映射到 `<command>` |
-| `clawt alias remove <alias>` | 移除指定的命令别名 |
-
-**参数：**
-
-| 参数 | 必填 | 说明 |
-| ---- | ---- | ---- |
-| `<alias>` | 是（set / remove） | 别名名称 |
-| `<command>` | 是（set） | 目标内置命令名 |
-
-**约束规则：**
-
-1. **别名不能覆盖内置命令名**：别名不能与任何已注册的内置命令同名（动态检测，当前包括 `list`、`create`、`remove`、`run`、`resume`、`validate`、`cover`、`merge`、`config`、`sync`、`reset`、`status`、`alias`、`projects`、`completion`、`init`、`home`）。如果用户尝试设置与内置命令同名的别名，输出错误提示并返回
-2. **目标必须是内置命令**：别名的目标（`<command>`）必须是已注册的内置命令名。如果指定了不存在的目标命令，输出错误提示并返回
-3. **参数透传**：通过别名调用时，所有选项和参数会完全透传给目标命令，行为与直接调用目标命令完全一致
-
-**持久化：**
-
-别名配置存储在 `~/.clawt/config.json` 的 `aliases` 字段中（类型 `Record<string, string>`，默认 `{}`）。
-
-**运行流程：**
-
-#### `alias list`（默认）
-
-1. 读取配置文件中的 `aliases` 字段
-2. 如果没有配置任何别名，输出提示 `(无别名)`
-3. 如果有别名，逐行输出所有别名映射
-
-**输出格式：**
-
-```
-当前别名列表：
-────────────────────────────────────────
-
-  l → list
-  r → run
-  v → validate
-
-────────────────────────────────────────
-```
-
-#### `alias set <alias> <command>`
-
-1. **校验别名不与内置命令冲突**：检查 `<alias>` 是否为内置命令名，是则输出错误提示并返回
-2. **校验目标命令存在**：检查 `<command>` 是否为已注册的内置命令名，不是则输出错误提示并返回
-3. 将别名写入配置文件的 `aliases` 字段（如果别名已存在，覆盖旧值）
-4. 输出成功提示
-
-**输出格式：**
-
-```
-✓ 已设置别名: l → list
-```
-
-#### `alias remove <alias>`
-
-1. 读取配置文件中的 `aliases` 字段
-2. 检查指定的别名是否存在，不存在则输出错误提示并返回
-3. 从 `aliases` 中删除该别名并写入配置文件
-4. 输出成功提示
-
-**输出格式：**
-
-```
-✓ 已移除别名: l
-```
-
-**别名使用示例：**
-
-```bash
-# 设置别名
-clawt alias set l list
-clawt alias set r run
-clawt alias set v validate
-
-# 使用别名（等同于对应的完整命令）
-clawt l          # 等同于 clawt list
-clawt r task.md  # 等同于 clawt run task.md
-
-# 查看所有别名
-clawt alias list
-
-# 移除别名
-clawt alias remove l
-```
-
-**实现要点：**
-
-- 消息常量定义在 `src/constants/messages/alias.ts`（`ALIAS_MESSAGES`），包括列表为空提示、设置/移除成功、别名不存在、与内置命令冲突、目标命令不存在等消息
-- 别名应用逻辑位于 `src/utils/alias.ts` 的 `applyAliases` 函数：在主入口 `src/index.ts` 中，所有命令注册完成后调用，遍历配置中的 `aliases` 映射，通过 Commander.js 的 `.alias()` 方法为对应命令注册别名。如果目标命令不存在则跳过并输出 warn 级别日志
-- 内置命令冲突检测通过 `getRegisteredCommandNames(program)` 动态获取所有已注册命令名，而非硬编码命令列表
-
----

package/docs/completion.md

@@ -1,55 +0,0 @@
-### 5.16 `clawt completion` 命令
-
-为终端环境（bash/zsh）生成并安装 `clawt` 的命令、选项及参数的自动补全脚本。
-
-#### 语法
-```bash
-clawt completion bash
-clawt completion zsh
-clawt completion install
-```
-
-#### 子命令说明
-
-| 子命令    | 说明                                                                                |
-| --------- | ----------------------------------------------------------------------------------- |
-| `bash`    | 输出适用于 bash 的补全脚本（用户可重定向到 `~/.bashrc`）                                |
-| `zsh`     | 输出适用于 zsh 的补全脚本（用户可重定向到 `~/.zshrc`）                                  |
-| `install` | 自动检测当前 shell 类型，将补全脚本追加到对应的配置文件中                                  |
-
-#### `install` 子命令流程
-
-1. 通过 `process.env.SHELL` 检测当前 shell 类型
-2. 根据 shell 类型确定目标配置文件：
-   - zsh → `~/.zshrc`（追加 `source <(clawt completion zsh)`）
-   - bash → `~/.bashrc`（追加 `eval "$(clawt completion bash)"`）
-3. 检查目标文件中是否已包含 `clawt completion`，已存在则跳过并提示
-4. 追加成功后提示用户重启终端或 source 配置文件
-5. 未知 shell 类型时输出警告，提示手动配置
-
-#### 动态补全特性
-
-补全脚本通过内部子命令 `_complete` 实现动态补全，不对外公开。补全引擎基于 Commander.js 的命令树结构遍历，支持以下场景：
-
-| 场景                         | 补全行为                                                   |
-| ---------------------------- | ---------------------------------------------------------- |
-| `-b` / `--branch` 参数之后   | 动态列出当前项目所有 worktree 分支名（通过 `getProjectWorktrees`） |
-| `-f` / `--file` 参数之后     | 动态列出匹配的文件和子目录（不限制文件类型，支持子目录递归浏览）    |
-| `config set` / `config get` 之后 | 动态列出所有配置项键名（从 `CONFIG_DEFINITIONS` 获取）         |
-| 输入以 `-` 开头              | 列出当前命令层级的可用选项（short/long）                       |
-| 其他情况                     | 列出当前命令层级的可用子命令及别名；若输入为空，同时列出可用选项    |
-
-**文件路径补全细节：**
-- 支持子目录递归浏览（如 `tasks/` 后继续 Tab 可深入子目录）
-- 目录候选项以 `/` 结尾，补全时不自动追加空格
-- 不限制文件类型，列出所有非隐藏文件
-- 跳过隐藏文件和目录（以 `.` 开头）
-
-#### 实现说明
-
-- 补全命令注册函数：`registerCompletionCommand()`（在 `src/commands/completion.ts`）
-- 消息常量：`COMPLETION_MESSAGES`（在 `src/constants/messages/completion.ts`）
-- 核心函数：`generateCompletions()` 解析当前输入上下文并输出候选项，`completeFilePath()` 处理文件路径补全，`tryCompleteSpecialArg()` 处理特殊参数（分支名、文件路径、配置键）的动态补全，`completeFromCommandTree()` 基于命令树遍历生成子命令和选项候选项
-- shell 脚本生成：`getBashScript()`、`getZshScript()` 分别生成对应 shell 的补全脚本
-
----

package/docs/config-file.md

@@ -1,45 +0,0 @@
-### 5.7 默认配置文件
-
-**路径：** `~/.clawt/config.json`
-
-**生成时机：** 全局安装后自动生成（通过 `postinstall` 脚本）。
-
-**升级策略：** 配置文件已存在时，执行增量合并而非简单跳过：
-
-- **新版本新增的配置项** → 使用默认值补充到用户配置中
-- **用户已有的配置项** → 保留用户的值，不覆盖
-- **新版本已移除的配置项** → 从用户配置中删除
-
-仅在合并后配置发生变化时才写入文件。配置文件损坏或无法解析时，视为不存在，重新生成默认配置。
-
-**默认内容：**
-
-```json
-{
-  "autoDeleteBranch": false,
-  "claudeCodeCommand": "claude",
-  "autoPullPush": false,
-  "confirmDestructiveOps": true,
-  "maxConcurrency": 0,
-  "terminalApp": "auto",
-  "resumeInPlace": false,
-  "aliases": {},
-  "autoUpdate": true
-}
-```
-
-**配置项说明：**
-
-| 配置项             | 类型      | 默认值    | 说明                                               |
-| ------------------ | --------- | --------- | -------------------------------------------------- |
-| `autoDeleteBranch` | `boolean` | `false`   | 移除 worktree 时是否自动删除对应本地分支（无需每次确认）；merge 成功后是否自动清理 worktree 和分支；run 任务被中断（Ctrl+C）后是否自动清理本次创建的 worktree 和分支 |
-| `claudeCodeCommand` | `string` | `"claude"` | Claude Code CLI 启动指令，用于 `clawt run` 不传 `--tasks` 时和 `clawt resume` 在 worktree 中打开交互式界面 |
-| `autoPullPush` | `boolean` | `false` | merge 成功后是否自动执行 git pull 和 git push |
-| `confirmDestructiveOps` | `boolean` | `true` | 执行破坏性操作（reset、validate --clean）前是否提示确认 |
-| `maxConcurrency` | `number` | `0` | run 命令默认最大并发数，`0` 表示不限制 |
-| `terminalApp` | `string` | `"auto"` | 批量 resume 使用的终端应用：`auto`（自动检测）、`iterm2`、`terminal`（macOS） |
-| `resumeInPlace` | `boolean` | `false` | resume 单选时是否在当前终端就地打开，`false` 则通过 `terminalApp` 在新 Tab 中打开 |
-| `aliases` | `Record<string, string>` | `{}` | 命令别名映射，键为别名，值为目标内置命令名 |
-| `autoUpdate` | `boolean` | `true` | 是否启用自动更新检查（每 24 小时通过 npm registry 检查一次新版本） |
-
----

package/docs/config.md

@@ -1,93 +0,0 @@
-### 5.10 交互式查看和修改全局配置
-
-**命令：**
-
-```bash
-# 交互式修改配置（等同于 config set 无参数）
-clawt config
-
-# 修改配置项（无参数进入交互式，有参数直接设置）
-clawt config set [key] [value]
-
-# 获取单个配置项的值
-clawt config get <key>
-
-# 将配置恢复为默认值
-clawt config reset
-```
-
-#### 交互式修改配置（`config` / `config set`）
-
-直接执行 `clawt config` 或 `clawt config set`（不带参数）进入交互式配置修改模式。
-
-**运行流程：**
-
-1. 读取全局配置文件 `~/.clawt/config.json`
-2. 列出所有配置项供用户选择（`Enquirer.Select`），每项显示：
-   - 配置项名称
-   - 当前值（布尔值绿色/黄色，字符串和数字青色）
-   - 配置项描述（暗淡色 dim）
-   - 对象类型配置项（如 `aliases`）标灰不可选，提示用户通过专用命令管理
-3. 用户选择某个配置项后，根据值类型自动选择提示策略：
-   - **boolean 类型** → `Select`（true / false）
-   - **number 类型** → `Input`（带数字校验）
-   - **string 类型 + 有 `allowedValues`** → `Select`（枚举列表）
-   - **string 类型 + 无 `allowedValues`** → `Input`（自由输入）
-4. 将修改后的配置持久化到配置文件
-5. 输出成功提示：`✓ <key> 已设置为 <value>`
-
-#### 直接设置配置项（`config set <key> <value>`）
-
-当带参数执行 `clawt config set <key> <value>` 时，直接修改指定配置项。
-
-**参数：**
-
-| 参数 | 必填 | 说明 |
-| ---- | ---- | ---- |
-| `key` | 否 | 配置项名称（不传则进入交互式模式） |
-| `value` | 否 | 配置值（传了 `key` 时必填） |
-
-**运行流程：**
-
-1. 校验 `key` 是否为有效的配置项名称（基于 `DEFAULT_CONFIG` 的键列表），无效则输出错误及可用配置项列表
-2. 校验 `value` 是否缺失，缺失则提示：`缺少配置值，用法: clawt config set <key> <value>`
-3. 根据目标配置项的类型解析并校验值：
-   - **boolean** → 仅接受 `true` 或 `false`
-   - **number** → `Number()` 解析，`NaN` 报错
-   - **string + 有 `allowedValues`** → 校验值是否在枚举列表中
-   - **string + 无 `allowedValues`** → 无额外校验
-4. 加载配置、修改目标项、持久化
-5. 输出成功提示：`✓ <key> 已设置为 <value>`
-
-#### 获取单个配置项（`config get <key>`）
-
-**参数：**
-
-| 参数 | 必填 | 说明 |
-| ---- | ---- | ---- |
-| `key` | 是 | 配置项名称 |
-
-**运行流程：**
-
-1. 校验 `key` 是否为有效的配置项名称，无效则输出错误及可用配置项列表
-2. 读取配置文件，获取目标配置项的值
-3. 输出：`<key> = <value>`
-
-#### 恢复默认配置（`config reset`）
-
-**运行流程：**
-
-1. 始终提示确认（显示即将执行的操作和后果：当前配置将被覆盖为默认值），不受 `confirmDestructiveOps` 配置控制。用户取消则退出
-2. 将默认配置写入 `~/.clawt/config.json`（覆盖现有配置文件）
-3. 输出成功提示：`✓ 配置已恢复为默认值`
-
-**实现要点：**
-
-- 配置项类型定义：`ConfigItemDefinition` 新增可选字段 `allowedValues`（`readonly string[]`），仅对 string 类型有效，用于枚举值校验和交互式 Select 提示
-- 值解析与提示策略：`src/utils/config-strategy.ts` 中的 `parseConfigValue()`（CLI 字符串解析）和 `promptConfigValue()`（交互式提示），基于类型和 `allowedValues` 自动分发
-- 交互式配置编辑：`handleInteractiveConfigSet` 调用通用的 `interactiveConfigEditor`（`src/utils/config-strategy.ts`），传入 `CONFIG_DEFINITIONS` 和 `disabledKeys`（对象类型配置项禁用映射），不再在 config 命令中直接构建选择列表和调用 `promptConfigValue`
-- `saveConfig(config)`：`src/utils/config.ts` 中的通用配置写入函数，将完整配置对象持久化到文件
-- `formatConfigValue(value)`：支持 boolean（绿色/黄色）和 string/number（青色）的格式化显示。`undefined` / `null` 值显示为暗淡色的 `(未设置)`
-- 对象类型配置项（如 `aliases`）的显示逻辑在 `interactiveConfigEditor` 的列表构建中处理：通过 `JSON.stringify` 以暗淡色显示值，并标记为不可选（disabled），提示用户通过 `clawt alias` 命令管理
-
----

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`
-
----