clawt 3.10.3 → 3.10.5

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/clawt.svg)](https://www.npmjs.com/package/clawt) [![GitHub](https://img.shields.io/badge/GHub-afk101%2Fclawt-blue)](https://github.com/afk101/clawt)
 
-**[English](./README.md)** | [中文](./README.zh-CN.md)
+**[English](./README.md)** | [中文](https://github.com/afk101/clawt/blob/main/README.zh-CN.md)
 
 Run multiple Claude Code Agent tasks in parallel based on Git Worktree — all agents' code changes are fully isolated from each other.
 
@@ -19,7 +19,7 @@ Claude Code can independently complete feature development, bug fixes, and refac
 
 This is how most developers use Claude Code today — **serial execution**:
 
-![Serial timeline](./docs/images/serial-timeline.png)
+![Serial timeline](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/serial-timeline.png)
 
 **3 tasks total ≈ 49.5 min.** The biggest problem: **while Claude is working on task A, B, C — you're just waiting.**
 
@@ -33,7 +33,7 @@ The core idea is simple:
 
 Same 3 tasks, with Clawt:
 
-![Parallel timeline](./docs/images/parallel-timeline.png)
+![Parallel timeline](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/parallel-timeline.png)
 
 **3 tasks total ≈ 26.5 min (parallel execution, sequential review)**
 
@@ -60,11 +60,11 @@ Git Worktree is a native Git mechanism (`git worktree add`) that creates multipl
 
 > **Human's job: think about requirements, write prompts, review code(Optional). AI's job: write code. Git Worktree is the isolation layer between them.**
 
-![Architecture](./docs/images/architecture.png)
+![Architecture](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/architecture.png)
 
 > **Clawt does not modify, replace, or wrap Claude Code itself. It only manages "where" and "how many" Claude Code instances run — at a higher level.**
 
-![Layer architecture](./docs/images/layer-architecture.png)
+![Layer architecture](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/layer-architecture.png)
 
 Everything you use inside each worktree is vanilla Claude Code — same interaction, same commands, same `CLAUDE.md`, same MCP config. Any Claude Code update automatically benefits Clawt with zero adaptation needed.
 
@@ -118,7 +118,7 @@ clawt status -i
 | `q` | Quit panel | — |
 
 Example:
-![Status panel](./docs/images/status-panel-en.png)
+![Status panel](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/status-panel-en.png)
 > All operations can also be executed via standalone commands — see "Command Reference" below.
 
 ## Command Reference

package/README.zh-CN.md

@@ -19,7 +19,7 @@ Claude Code 可以独立完成需求开发、Bug 修复、代码重构等任务
 
 这是大多数开发者使用 Claude Code 的现状——**串行执行**：
 
-![串行模式时间轴](./docs/images/serial-timeline.png)
+![串行模式时间轴](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/serial-timeline.png)
 
 **3 个任务总耗时 ≈ 49.5 分钟**。最大的问题是：**Claude 在执行任务的时候，你完全在干等。**
 
@@ -33,7 +33,7 @@ Claude Code 可以独立完成需求开发、Bug 修复、代码重构等任务
 
 同样的 3 个任务，使用 Clawt 后：
 
-![并行模式时间轴](./docs/images/parallel-timeline.png)
+![并行模式时间轴](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/parallel-timeline.png)
 
 **3 个任务总耗时 ≈ 26.5 分钟（并行执行，串行验证）**
 
@@ -62,11 +62,11 @@ Git Worktree 是 Git 原生支持的机制（`git worktree add`），它允许
 
 > **人做的事情：思考需求、写 Prompt、审查代码（可选）。AI 做的事情：写代码。用 Git Worktree 作为两者之间的隔离层。**
 
-![架构图](./docs/images/architecture.png)
+![架构图](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/architecture.png)
 
 > **Clawt 不修改、不替换、不包装 Claude Code 本身。它只是在更高一层管理"在哪里"以及"同时启动多少个" Claude Code。**
 
-![分层架构](./docs/images/layer-architecture.png)
+![分层架构](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/layer-architecture.png)
 
 你在每个 Worktree 里使用的，就是原汁原味的 Claude Code——同样的交互方式、同样的命令、同样的 CLAUDE.md、同样的 MCP 配置。Claude Code 的任何更新，Clawt 自动受益，无需适配。
 
@@ -120,7 +120,7 @@ clawt status -i
 | `q` | 退出面板 | — |
 
 示例：
-![状态面板](./docs/images/status-panel-zh.png)
+![状态面板](https://raw.githubusercontent.com/afk101/clawt/main/docs/images/status-panel-zh.png)
 > 所有操作也可通过独立命令执行，详见下方「命令一览」。
 
 ## 命令一览

package/dist/index.js

@@ -819,6 +819,33 @@ var VALIDATE_MESSAGES_I18N = {
     "zh-CN": (branch) => `\u53D8\u66F4\u8FC1\u79FB\u5931\u8D25\uFF1A\u76EE\u6807\u5206\u652F\u4E0E\u4E3B\u5206\u652F\u5DEE\u5F02\u8FC7\u5927
   \u8BF7\u5148\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...(${files.length} files total)` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `Ignored files left in main worktree are blocking patch apply:
+${displayed}${more}
+
+Please clean up manually and retry:
+${cmds}`;
+    },
+    "zh-CN": (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...\uFF08\u5171 ${files.length} \u4E2A\u6587\u4EF6\uFF09` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `\u68C0\u6D4B\u5230\u88AB .gitignore \u5FFD\u7565\u7684\u6587\u4EF6\u6B8B\u7559\u5728\u4E3B worktree \u4E2D\uFF0C\u5BFC\u81F4\u53D8\u66F4\u65E0\u6CD5\u5E94\u7528\uFF1A
+${displayed}${more}
+
+\u8BF7\u624B\u52A8\u6E05\u7406\u540E\u91CD\u8BD5\uFF1A
+${cmds}`;
+    }
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: "No worktrees available, please create one with clawt run or clawt create first",
@@ -2817,6 +2844,19 @@ function gitMergeContinue(cwd) {
 function buildAutoSaveCommitMessage(mainBranch, branch) {
   return `${AUTO_SAVE_COMMIT_MESSAGE_PREFIX} ${mainBranch} into ${branch}`;
 }
+function gitCheckIgnored(paths, cwd) {
+  if (paths.length === 0) return [];
+  try {
+    const output = execFileSync2("git", ["check-ignore", "--", ...paths], {
+      cwd,
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    });
+    return output.trim().split("\n").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
 
 // src/utils/git-branch.ts
 function checkBranchExists(branchName, cwd) {
@@ -5093,6 +5133,17 @@ async function executeRunCommand(command, mainWorktreePath) {
 }
 
 // src/utils/validate-core.ts
+import { existsSync as existsSync10 } from "fs";
+import { join as join10 } from "path";
+function buildCleanCommands(files) {
+  const dirs = /* @__PURE__ */ new Set();
+  for (const file of files) {
+    const lastSlash = file.lastIndexOf("/");
+    const dir = lastSlash > 0 ? file.substring(0, lastSlash) : ".";
+    dirs.add(dir);
+  }
+  return Array.from(dirs).map((dir) => `git clean -fdx ${dir}/`);
+}
 function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName, hasUncommitted) {
   let didTempCommit = false;
   try {
@@ -5101,6 +5152,13 @@ function migrateChangesViaPatch(targetWorktreePath, mainWorktreePath, branchName
       gitCommit("clawt:temp-commit-for-validate", targetWorktreePath);
       didTempCommit = true;
     }
+    const ignoredFiles = detectIgnoredFilesInPatch(branchName, mainWorktreePath);
+    if (ignoredFiles.length > 0) {
+      const cleanCommands = buildCleanCommands(ignoredFiles);
+      logger.warn(`\u68C0\u6D4B\u5230 ${ignoredFiles.length} \u4E2A\u88AB\u5FFD\u7565\u7684\u6B8B\u7559\u6587\u4EF6\u51B2\u7A81`);
+      printWarning(MESSAGES.VALIDATE_IGNORED_FILES_CONFLICT(ignoredFiles, cleanCommands));
+      return { success: false };
+    }
     const patch = gitDiffBinaryAgainstBranch(branchName, mainWorktreePath);
     if (patch.length > 0) {
       try {
@@ -5175,6 +5233,16 @@ function switchToValidateBranch(branchName, mainWorktreePath) {
   }
   return validateBranchName;
 }
+function detectIgnoredFilesInPatch(branchName, mainWorktreePath) {
+  try {
+    const output = execCommand(`git diff --name-only HEAD...${branchName}`, { cwd: mainWorktreePath });
+    const patchFiles = output.split("\n").filter(Boolean);
+    if (patchFiles.length === 0) return [];
+    return gitCheckIgnored(patchFiles, mainWorktreePath).filter((file) => existsSync10(join10(mainWorktreePath, file)));
+  } catch {
+    return [];
+  }
+}
 
 // src/utils/interactive-panel.ts
 import { createInterface as createInterface2 } from "readline";
@@ -5967,9 +6035,9 @@ async function handleMergeConflict(currentBranch, incomingBranch, cwd, autoFlag)
 }
 
 // src/hooks/post-create.ts
-import { existsSync as existsSync10, accessSync, chmodSync, constants as fsConstants } from "fs";
+import { existsSync as existsSync11, accessSync, chmodSync, constants as fsConstants } from "fs";
 import { spawn as spawn2 } from "child_process";
-import { join as join10 } from "path";
+import { join as join11 } from "path";
 var POST_CREATE_SCRIPT_RELATIVE_PATH = ".clawt/postCreate.sh";
 function isExecutable(filePath) {
   try {
@@ -6001,8 +6069,8 @@ function resolvePostCreateHook() {
     }
   }
   const mainWorktreePath = getMainWorktreePath();
-  const scriptPath = join10(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
-  if (existsSync10(scriptPath)) {
+  const scriptPath = join11(mainWorktreePath, POST_CREATE_SCRIPT_RELATIVE_PATH);
+  if (existsSync11(scriptPath)) {
     if (!isExecutable(scriptPath)) {
       autoFixExecutablePermission(scriptPath);
     }
@@ -7263,8 +7331,8 @@ function registerAliasCommand(program2) {
 }
 
 // src/commands/projects.ts
-import { existsSync as existsSync11, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
-import { join as join11 } from "path";
+import { existsSync as existsSync12, readdirSync as readdirSync6, statSync as statSync4 } from "fs";
+import { join as join12 } from "path";
 import chalk13 from "chalk";
 function registerProjectsCommand(program2) {
   program2.command("projects [name]").description(getCurrentLanguage() === "en" ? "Show worktree overview across projects, or view details for a specific project" : "\u5C55\u793A\u6240\u6709\u9879\u76EE\u7684 worktree \u6982\u89C8\uFF0C\u6216\u67E5\u770B\u6307\u5B9A\u9879\u76EE\u7684 worktree \u8BE6\u60C5").option("--json", getCurrentLanguage() === "en" ? "Output in JSON format" : "\u4EE5 JSON \u683C\u5F0F\u8F93\u51FA").action((name, options) => {
@@ -7288,8 +7356,8 @@ function handleProjectsOverview(json) {
   printProjectsOverviewAsText(result);
 }
 function handleProjectDetail(name, json) {
-  const projectDir = join11(WORKTREES_DIR, name);
-  if (!existsSync11(projectDir)) {
+  const projectDir = join12(WORKTREES_DIR, name);
+  if (!existsSync12(projectDir)) {
     printError(MESSAGES.PROJECTS_NOT_FOUND(name));
     process.exit(1);
   }
@@ -7302,7 +7370,7 @@ function handleProjectDetail(name, json) {
   printProjectDetailAsText(result);
 }
 function collectProjectsOverview() {
-  if (!existsSync11(WORKTREES_DIR)) {
+  if (!existsSync12(WORKTREES_DIR)) {
     return { projects: [], totalProjects: 0, totalDiskUsage: 0 };
   }
   const entries = readdirSync6(WORKTREES_DIR, { withFileTypes: true });
@@ -7311,7 +7379,7 @@ function collectProjectsOverview() {
     if (!entry.isDirectory()) {
       continue;
     }
-    const projectDir = join11(WORKTREES_DIR, entry.name);
+    const projectDir = join12(WORKTREES_DIR, entry.name);
     const overview = collectSingleProjectOverview(entry.name, projectDir);
     projects.push(overview);
   }
@@ -7328,7 +7396,7 @@ function collectSingleProjectOverview(name, projectDir) {
   const worktreeDirs = subEntries.filter((e) => e.isDirectory());
   const worktreeCount = worktreeDirs.length;
   const diskUsage = calculateDirSize(projectDir);
-  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join11(projectDir, e.name)));
+  const lastActiveTime = resolveProjectLastActiveTime(projectDir, worktreeDirs.map((e) => join12(projectDir, e.name)));
   return {
     name,
     worktreeCount,
@@ -7343,7 +7411,7 @@ function collectProjectDetail(name, projectDir) {
     if (!entry.isDirectory()) {
       continue;
     }
-    const wtPath = join11(projectDir, entry.name);
+    const wtPath = join12(projectDir, entry.name);
     const detail = collectSingleWorktreeDetail(entry.name, wtPath);
     worktrees.push(detail);
   }
@@ -7443,7 +7511,7 @@ function printWorktreeDetailItem(wt) {
 }
 
 // src/commands/completion.ts
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync13 } from "fs";
+import { readFileSync as readFileSync6, writeFileSync as writeFileSync5, existsSync as existsSync14 } from "fs";
 import { resolve as resolve3 } from "path";
 import { homedir as homedir2 } from "os";
 
@@ -7494,14 +7562,14 @@ compdef _clawt_completion clawt
 }
 
 // src/utils/completion-engine.ts
-import { existsSync as existsSync12, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
-import { join as join12, dirname, basename as basename2 } from "path";
+import { existsSync as existsSync13, readdirSync as readdirSync7, statSync as statSync5 } from "fs";
+import { join as join13, dirname, basename as basename2 } from "path";
 function completeFilePath(partial) {
   const cwd = process.cwd();
   const hasDir = partial.includes("/");
-  const searchDir = hasDir ? join12(cwd, dirname(partial)) : cwd;
+  const searchDir = hasDir ? join13(cwd, dirname(partial)) : cwd;
   const prefix = hasDir ? basename2(partial) : partial;
-  if (!existsSync12(searchDir)) {
+  if (!existsSync13(searchDir)) {
     return [];
   }
   const entries = readdirSync7(searchDir);
@@ -7510,7 +7578,7 @@ function completeFilePath(partial) {
   for (const entry of entries) {
     if (!entry.startsWith(prefix)) continue;
     if (entry.startsWith(".")) continue;
-    const fullPath = join12(searchDir, entry);
+    const fullPath = join13(searchDir, entry);
     try {
       const stat = statSync5(fullPath);
       if (stat.isDirectory()) {
@@ -7599,7 +7667,7 @@ function generateCompletions(program2, args) {
 
 // src/commands/completion.ts
 function appendToFile(filePath, content) {
-  if (existsSync13(filePath)) {
+  if (existsSync14(filePath)) {
     const current = readFileSync6(filePath, "utf-8");
     if (current.includes("clawt completion")) {
       printInfo(MESSAGES.COMPLETION_INSTALL_EXISTS + ": " + filePath);
@@ -7739,19 +7807,19 @@ async function handleHome() {
 }
 
 // src/commands/tasks.ts
-import { resolve as resolve4, dirname as dirname2, join as join13 } from "path";
-import { existsSync as existsSync14, writeFileSync as writeFileSync6 } from "fs";
+import { resolve as resolve4, dirname as dirname2, join as join14 } from "path";
+import { existsSync as existsSync15, writeFileSync as writeFileSync6 } from "fs";
 function registerTasksCommand(program2) {
   const taskCmd = program2.command("tasks").description(getCurrentLanguage() === "en" ? "Task file management" : "\u4EFB\u52A1\u6587\u4EF6\u7BA1\u7406");
   taskCmd.command("init").description(getCurrentLanguage() === "en" ? "Generate task template file" : "\u751F\u6210\u4EFB\u52A1\u6A21\u677F\u6587\u4EF6").argument("[path]", getCurrentLanguage() === "en" ? "Output file path" : "\u8F93\u51FA\u6587\u4EF6\u8DEF\u5F84").action(async (path2) => {
-    const filePath = path2 ?? join13(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
+    const filePath = path2 ?? join14(TASK_TEMPLATE_OUTPUT_DIR, generateTaskFilename(TASK_TEMPLATE_FILENAME_PREFIX));
     await handleTasksInit(filePath);
   });
 }
 async function handleTasksInit(filePath) {
   const absolutePath = resolve4(filePath);
   logger.info(`tasks init \u547D\u4EE4\u6267\u884C\uFF0C\u76EE\u6807\u6587\u4EF6: ${absolutePath}`);
-  if (existsSync14(absolutePath)) {
+  if (existsSync15(absolutePath)) {
     throw new ClawtError(MESSAGES.TASK_INIT_FILE_EXISTS(filePath));
   }
   ensureDir(dirname2(absolutePath));

package/dist/postinstall.js

@@ -726,6 +726,33 @@ var VALIDATE_MESSAGES_I18N = {
     "zh-CN": (branch) => `\u53D8\u66F4\u8FC1\u79FB\u5931\u8D25\uFF1A\u76EE\u6807\u5206\u652F\u4E0E\u4E3B\u5206\u652F\u5DEE\u5F02\u8FC7\u5927
   \u8BF7\u5148\u6267\u884C clawt sync -b ${branch} \u540C\u6B65\u4E3B\u5206\u652F\u540E\u91CD\u8BD5`
   },
+  /** validate 检测到被 .gitignore 忽略的残留文件冲突 */
+  VALIDATE_IGNORED_FILES_CONFLICT: {
+    en: (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...(${files.length} files total)` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `Ignored files left in main worktree are blocking patch apply:
+${displayed}${more}
+
+Please clean up manually and retry:
+${cmds}`;
+    },
+    "zh-CN": (files, cleanCommands) => {
+      const maxDisplay = 10;
+      const displayed = files.slice(0, maxDisplay).map((f) => `  - ${f}`).join("\n");
+      const more = files.length > maxDisplay ? `
+  ...\uFF08\u5171 ${files.length} \u4E2A\u6587\u4EF6\uFF09` : "";
+      const cmds = cleanCommands.map((c) => `  ${c}`).join("\n");
+      return `\u68C0\u6D4B\u5230\u88AB .gitignore \u5FFD\u7565\u7684\u6587\u4EF6\u6B8B\u7559\u5728\u4E3B worktree \u4E2D\uFF0C\u5BFC\u81F4\u53D8\u66F4\u65E0\u6CD5\u5E94\u7528\uFF1A
+${displayed}${more}
+
+\u8BF7\u624B\u52A8\u6E05\u7406\u540E\u91CD\u8BD5\uFF1A
+${cmds}`;
+    }
+  },
   /** validate 无可用 worktree */
   VALIDATE_NO_WORKTREES: {
     en: "No worktrees available, please create one with clawt run or clawt create first",

package/docs/superpowers/findings/2026-06-01-sync-validate-diverged-findings.md

@@ -0,0 +1,203 @@
+# sync 后 validate 仍然失败 — 调查记录
+
+**日期：** 2026-06-01
+
+---
+
+## 现象描述
+
+用户在交互式面板（`clawt status`）中对目标分支执行 validate，patch apply 失败，提示：
+
+```
+⚠ Change migration failed: target branch has diverged too far from main
+  Please run clawt sync -b <target-branch> first, then retry
+```
+
+用户选择自动 sync（或手动执行 `clawt sync -b <target-branch>`），sync 成功：
+
+```
+✓ Synced latest code from <main-branch> to <target-branch>
+Validation branch clawt-validate-<target-branch> has been rebuilt
+```
+
+但再次执行 validate 时，仍然报同样的错误。
+
+---
+
+## 调查过程
+
+### 第一步：确认分支状态
+
+- 主工作分支：HEAD 指向最新 commit
+- 验证分支：与主分支 HEAD 一致（sync 后已重建）
+- 目标分支：包含多次 merge commit，已合并主分支最新代码
+
+**结论：** sync 已成功，验证分支已正确重建，分支状态本身没有问题。
+
+### 第二步：模拟 patch apply
+
+执行三点 diff 并尝试 apply：
+
+```bash
+git diff clawt-validate-<target-branch>...<target-branch> --binary | git apply --check -
+```
+
+输出：
+
+```
+错误：<ignored-dir>/findings/some-findings.md：已经存在于工作区中
+错误：<ignored-dir>/plans/some-plan.md：已经存在于工作区中
+...（共 N 个文件）
+```
+
+**关键发现：** patch 失败的原因不是分支差异过大，而是目标分支中跟踪的某些文件在主 worktree 工作目录中已经物理存在。
+
+### 第三步：追溯文件来源
+
+检查主 worktree 工作目录：
+
+```bash
+ls <ignored-dir>/findings/
+# some-findings.md  ← 物理存在
+# ...（共多个文件）
+```
+
+检查 `git status`：
+
+```
+无文件要提交，干净的工作区
+```
+
+**为什么这些文件物理存在但 git status 不显示？**
+
+检查 `.gitignore`：
+
+```bash
+cat .gitignore | grep <ignored-dir>
+# <ignored-dir>/   ← 被忽略！
+```
+
+**结论：** 该目录在主分支的 `.gitignore` 中，这些文件是**被忽略的未跟踪文件**，`git status` 不会显示它们。
+
+### 第四步：追溯文件如何进入主 worktree
+
+这些文件是由**之前的 validate 操作**创建的：
+
+1. validate 通过 `git diff HEAD...branch --binary | git apply -` 将目标分支的变更（包括被忽略目录下的文件）应用到主 worktree 工作目录
+2. 目标分支跟踪了这些文件（尽管 `.gitignore` 中有该目录，但 AI Agent 在 worktree 中用 `git add -f` 强制添加了它们）
+3. validate 完成后，这些文件作为**未跟踪文件**留在主 worktree 工作目录中
+
+### 第五步：追溯为什么清理无效
+
+validate 的清理逻辑（`handleIncrementalValidate` 步骤 2 和 `handleDirtyWorkingDir` 的 reset 选项）使用：
+
+```bash
+git reset --hard    # 只影响已跟踪文件
+git clean -fd       # 删除未跟踪文件，但**不删除被忽略的文件**
+```
+
+`git clean -fd` 的行为：
+- 删除未跟踪且未被忽略的文件 ✓
+- **跳过**在 `.gitignore` 中的文件 ✗
+
+要删除被忽略的文件，需要 `git clean -fdx`（`-x` 表示包括被忽略的文件）。
+
+### 第六步：确认 sync 为什么不解决问题
+
+`executeSyncForBranch` 的操作：
+1. 检查目标 worktree 未提交变更 → 自动 commit
+2. 在目标 worktree 中 `git merge <main-branch>`
+3. 重建验证分支
+
+**sync 完全不清理主 worktree 的工作目录**，因此那些被忽略的残留文件仍然存在。
+
+---
+
+## 根本原因
+
+**完整因果链：**
+
+```
+上游 commit 将某目录加入 .gitignore 并从 git 跟踪中移除
+    ↓
+目标分支仍然跟踪着自己新增的文件（AI Agent 用 git add -f 强制提交）
+    ↓
+validate 通过 patch apply 将这些文件创建到主 worktree 工作目录
+    ↓
+validate 结束后的清理（git clean -fd）无法删除这些文件（因为在 .gitignore 中）
+    ↓
+文件作为"被忽略的未跟踪文件"永久残留在主 worktree
+    ↓
+下次 validate 的 patch apply 试图创建同名文件 → "已经存在于工作区中" → 失败
+    ↓
+auto-sync 不清理主 worktree 工作目录 → 问题持续存在（死循环）
+```
+
+**核心矛盾：**
+
+- 被忽略目录在主分支 `.gitignore` 中 → `git clean -fd` 不删除
+- 被忽略目录在目标分支被跟踪 → patch 包含这些文件 → apply 时与物理存在的文件冲突
+
+---
+
+## 影响范围
+
+此 bug 在以下条件同时满足时触发：
+
+1. 目标分支跟踪了某些在 `.gitignore` 中的文件（通常是 AI Agent 用 `git add -f` 强制添加）
+2. 主分支的 `.gitignore` 包含对应路径
+3. 至少执行过一次 validate（使文件通过 patch 进入主 worktree）
+4. 后续再次执行 validate（patch apply 因文件已存在而失败）
+
+---
+
+## 技术决策记录
+
+| 假设 | 验证结果 |
+|------|----------|
+| 分支确实 diverged（差异过大） | ❌ 排除：三点 diff 正常，merge-base 正确 |
+| 验证分支未正确重建 | ❌ 排除：验证分支与主分支 HEAD 一致 |
+| sync 未成功执行 | ❌ 排除：sync 成功，目标分支已合并主分支 |
+| patch 内容与主分支冲突 | ❌ 排除：不是内容冲突，是文件已存在 |
+| **被忽略文件残留导致 patch apply 失败** | ✅ 确认：`git apply --check` 明确报 "已经存在于工作区中" |
+
+---
+
+## Brainstorming 决策（2026-06-01）
+
+### 方案评估
+
+| 方案 | 安全性 | 便利性 | 误删风险 | 代码复杂度 |
+|------|--------|--------|----------|------------|
+| A：检测 + 提示用户手动清理 | 高 | 低 | 无 | 低 |
+| B：检测 + 自动清理后继续 | 中 | 高 | 有 | 略高 |
+
+### 最终决策
+
+**选择方案 A（检测 + 提示用户手动清理）**
+
+理由：
+1. 这类冲突本质上是项目 `.gitignore` 配置与分支跟踪状态不一致导致的，属于需要用户知情的项目级决策
+2. 不应该由工具静默处理，用户需要知道哪些文件被清理了
+3. 实现简单，风险为零
+
+### 实现方案
+
+1. 新增 `gitCheckIgnored(paths, cwd)` — 批量检测文件是否被 `.gitignore` 忽略
+2. 新增 `detectIgnoredFilesInPatch(branchName, mainWorktreePath)` — 检测 patch 中的幽灵文件
+3. 修改 `migrateChangesViaPatch` — apply 前调用检测函数，有冲突则输出提示并返回失败
+4. 新增消息常量 `VALIDATE_IGNORED_FILES_CONFLICT`（双语）
+
+### 提示格式
+
+```
+⚠ 检测到被 .gitignore 忽略的文件残留在主 worktree 中，导致变更无法应用：
+  - <ignored-dir>/findings/some-findings.md
+  - <ignored-dir>/plans/some-plan.md
+  ...（共 N 个文件）
+
+请手动清理后重试：
+  git clean -fdx <ignored-dir>/
+```
+
+清理命令按冲突文件的直接父目录去重生成。