dsh-superpower 6.3.0

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,322 @@
+---
+name: test-driven-development
+description: "实现新功能或修复缺陷时，编写实现代码前先写测试的测试驱动开发完整指南与流程约束规范"
+---
+
+# 测试驱动开发（TDD）
+
+## 概述
+
+先写测试。观察它失败。再写最少的代码让它通过。
+
+**核心原则：** 如果你没有亲眼看到测试失败，你就无法确定它是否真的测对了东西。
+
+**违反规则的字面要求，就是违背规则的精神。**
+
+## 何时使用
+
+**始终使用：**
+- 新功能
+- 缺陷修复
+- 重构
+- 行为变更
+
+**例外情况（需征得协作人同意）：**
+- 一次性原型
+- 生成的代码
+- 配置文件
+
+想着“就这一次跳过 TDD”？打住，这就是在自我合理化。
+
+## 铁律
+
+```
+NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
+```
+
+没有先写出一个失败的测试，就不写任何生产代码。
+
+在测试之前写了代码？删掉，重来。
+
+**没有例外：**
+- 不要留着当“参考”
+- 不要在写测试时“改造”它
+- 不要去看它
+- 删除就是删除
+
+完全基于测试重新实现，没有例外。
+
+## 红-绿-重构
+
+```dot
+digraph tdd_cycle {
+    rankdir=LR;
+    red [label="红色阶段\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    verify_red [label="验证是否\n按预期失败", shape=diamond];
+    green [label="绿色阶段\n最小化实现", shape=box, style=filled, fillcolor="#ccffcc"];
+    verify_green [label="验证是否通过\n全部通过", shape=diamond];
+    refactor [label="重构阶段\n清理优化", shape=box, style=filled, fillcolor="#ccccff"];
+    next [label="下一项", shape=ellipse];
+
+    red -> verify_red;
+    verify_red -> green [label="是"];
+    verify_red -> red [label="失败原因\n错误"];
+    green -> verify_green;
+    verify_green -> refactor [label="是"];
+    verify_green -> green [label="否"];
+    refactor -> verify_green [label="保持\n通过"];
+    verify_green -> next;
+    next -> red;
+}
+```
+
+### 红色阶段 - 编写失败的测试
+
+写一个最小化的测试，展示应该发生什么。
+
+<Good>
+```typescript
+test('retries failed operations 3 times', async () => {
+  let attempts = 0;
+  const operation = () => {
+    attempts++;
+    if (attempts < 3) throw new Error('fail');
+    return 'success';
+  };
+
+  const result = await retryOperation(operation);
+
+  expect(result).toBe('success');
+  expect(attempts).toBe(3);
+});
+```
+命名清晰、测试真实行为、只测一件事
+</Good>
+
+<Bad>
+```typescript
+test('retry works', async () => {
+  const mock = jest.fn()
+    .mockRejectedValueOnce(new Error())
+    .mockRejectedValueOnce(new Error())
+    .mockResolvedValueOnce('success');
+  await retryOperation(mock);
+  expect(mock).toHaveBeenCalledTimes(3);
+});
+```
+命名模糊、测的是 mock 而非真实代码
+</Bad>
+
+**要求：**
+- 一次只测一个行为
+- 命名清晰
+- 使用真实代码（除非不得不 mock）
+
+### 验证红色阶段 - 观察失败
+
+**强制要求，切勿跳过。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试失败（而非报错）
+- 失败信息符合预期
+- 失败原因是功能缺失导致（而非拼写错误）
+
+**测试通过了？** 说明你在测试已有的行为，请修正测试。
+
+**测试报错了？** 修复错误，直到它以正确的方式失败为止。
+
+### 绿色阶段 - 最小化实现
+
+编写刚好能让测试通过的最简代码。
+
+<Good>
+```typescript
+async function retryOperation<T>(fn: () => Promise<T>): Promise<T> {
+  for (let i = 0; i < 3; i++) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (i === 2) throw e;
+    }
+  }
+  throw new Error('unreachable');
+}
+```
+刚好够通过
+</Good>
+
+<Bad>
+```typescript
+async function retryOperation<T>(
+  fn: () => Promise<T>,
+  options?: {
+    maxRetries?: number;
+    backoff?: 'linear' | 'exponential';
+    onRetry?: (attempt: number) => void;
+  }
+): Promise<T> {
+  // YAGNI
+}
+```
+过度设计
+</Bad>
+
+不要添加测试未要求的功能，不要顺手重构其他代码，也不要做超出测试范围的“优化”。
+
+### 验证绿色阶段 - 观察通过
+
+**强制要求。**
+
+```bash
+npm test path/to/test.test.ts
+```
+
+确认：
+- 测试通过
+- 其他测试仍全部通过
+- 输出干净（无错误、无警告）
+
+**测试失败？** 修代码，而不是改测试。
+
+**其他测试失败？** 立即修复。
+
+### 重构阶段 - 清理优化
+
+仅在变绿之后：
+- 消除重复
+- 改进命名
+- 抽取辅助函数
+
+保持测试持续通过，不要新增行为。
+
+### 重复
+
+为下一个功能编写下一个失败的测试。
+
+## 好的测试
+
+| 质量 | 好的示例 | 差的示例 |
+|---------|------|-----|
+| **最小化** | 只测一件事，名称里出现“和”就拆分 | `test('validates email and domain and whitespace')` |
+| **清晰** | 名称描述行为 | `test('test1')` |
+| **体现意图** | 展示期望的 API 用法 | 掩盖代码应有的行为 |
+
+在编写或修改任何测试时，请阅读 [writing-good-tests.md](writing-good-tests.md) 中让测试保持诚实的规则：
+- 在编写测试前，先说清楚什么样的生产代码变更会让它失败
+- 只对真实行为做断言，绝不对 mock 的行为做断言
+- 仅用于测试的代码放在测试工具中，不要放进生产类
+- 只有在理解依赖的副作用后，才去 mock 它
+
+## 常见的自我合理化
+
+| 借口 | 实际情况 |
+|--------|---------|
+| "太简单了，不用测" | 简单的代码也会出错，写个测试只要 30 秒。 |
+| "先实现，之后再补测试" | 后补的测试会立刻通过——这什么也证明不了。它们可能测错了东西、测的是实现而非行为，或遗漏了你忘记的边界情况。你从未看过它失败，也就从未证明它能捕获缺陷。测试先行才会迫使失败发生。 |
+| "后补测试也能达到同样的目标（重精神不重形式）" | 后补测试回答的是“这段代码做了什么？”；先行测试回答的是“这段代码应该做什么？”。后补的测试受你已写代码的影响——你只会验证自己记得的场景，而非本应发现的场景。没有经过失败验证的覆盖率毫无说服力。 |
+| "已经手动测过了" | 手动测试是随意的：没有覆盖记录、代码变更后无法重复执行、压力下容易遗漏场景。“我试的时候是好的”不等于全面。自动化测试每次都以同样的方式运行。 |
+| "删掉花了 X 小时的代码太浪费了" | 沉没成本谬误——时间已经花掉了，无法挽回。真正的选择是：用 TDD 重写（高可信度） vs. 保留现有代码再后补测试（低可信度、很可能有缺陷）。保留不可信的代码才是浪费。 |
+| "留着当参考，先写测试" | 你会忍不住去适配它，这本质还是后补测试。删除就是删除。 |
+| "需要先探索一下" | 可以，先探索，探索完扔掉，再从 TDD 开始。 |
+| "测试很难写 = 设计不清晰" | 听测试的，难测就意味着难用。 |
+| "TDD 会拖慢我" | TDD 才是务实的路径：在提交前捕获缺陷、防止回归、让你无惧重构。所谓“务实”的捷径只会把调试推到线上——更慢，而非更快。 |
+| "手动测试更快" | 手动测试无法证明边界情况，每次变更你都要重新测一遍。 |
+| "现有代码本来就没测试" | 你正在改进它，给现有代码补上测试。 |
+
+## 危险信号 - 立即停下并重来
+
+- 先写代码，后写测试
+- 在实现之后才补测试
+- 测试立刻通过
+- 无法解释测试为何失败
+- 测试“稍后”再补
+- 为“就这一次”找合理化理由
+- “我已经手动测过了”
+- “后补测试也能达到同样目的”
+- “重在精神，不在形式”
+- “留着当参考”或“在现有代码上改一改”
+- “已经花了 X 小时，删掉太浪费”
+- “TDD 太教条，我这是务实”
+- “这次情况特殊，因为……”
+
+**出现以上任何一种，意味着：删掉代码，用 TDD 重来。**
+
+## 示例：缺陷修复
+
+**缺陷：** 空邮箱被接受
+
+**红色阶段**
+```typescript
+test('rejects empty email', async () => {
+  const result = await submitForm({ email: '' });
+  expect(result.error).toBe('Email required');
+});
+```
+
+**验证红色阶段**
+```bash
+$ npm test
+FAIL: expected 'Email required', got undefined
+```
+
+**绿色阶段**
+```typescript
+function submitForm(data: FormData) {
+  if (!data.email?.trim()) {
+    return { error: 'Email required' };
+  }
+  // ...
+}
+```
+
+**验证绿色阶段**
+```bash
+$ npm test
+PASS
+```
+
+**重构阶段**
+如有需要，为多个字段抽取统一的校验逻辑。
+
+## 验证清单
+
+标记完成前请逐项检查：
+
+- [ ] 每个新增的函数/方法都有对应的测试
+- [ ] 已亲眼看到每个测试在实现前失败
+- [ ] 每个测试都以预期的原因失败（功能缺失，而非拼写错误）
+- [ ] 仅编写了刚好让测试通过的最简代码
+- [ ] 所有测试均已通过
+- [ ] 输出干净（无错误、无警告）
+- [ ] 测试使用真实代码（仅在不得已时使用 mock）
+- [ ] 已覆盖边界情况和错误路径
+
+无法全部勾选？你跳过了 TDD，请重来。
+
+## 遇到阻塞时
+
+| 问题 | 解决方案 |
+|---------|----------|
+| 不知道怎么测 | 写出你期望的 API，先写断言，找协作人讨论。 |
+| 测试太复杂 | 设计太复杂，简化接口。 |
+| 必须 mock 所有东西 | 代码耦合过重，使用依赖注入。 |
+| 测试准备工作过于庞大 | 抽取辅助函数，依然复杂？简化设计。 |
+
+## 调试集成
+
+发现缺陷？先写一个能复现它的失败测试，再走 TDD 循环。测试既能证明修复有效，也能防止回归。
+
+绝不在没有测试的情况下修复缺陷。
+
+## 最终规则
+
+```
+生产代码 → 已存在对应测试且该测试曾先失败
+否则 → 就不是 TDD
+```
+
+未经协作人许可，没有例外。

package/skills/test-driven-development/writing-good-tests.md

@@ -0,0 +1,145 @@
+# 编写高质量测试
+
+**何时加载本文档：** 编写或修改测试、添加 Mock，或为测试添加清理/辅助方法时。
+
+## 概述
+
+测试的存在是为了捕获特定的缺陷。以下两条原则贯穿始终：
+
+```
+1. 每个测试都要明确它能捕获什么缺陷
+2. 每个测试都要验证真实对象
+```
+
+严格的 TDD 能自然地满足这两点：先写测试并观察其在真实代码上失败，就已经证明了它具备失败能力；只有当真实依赖被证明缓慢或涉及外部系统时，才引入 Mock。
+
+## 原则一：明确测试要捕获的缺陷
+
+在编写测试体之前，先回答：**什么样的生产代码变更应该让这个测试失败——而这个变更是缺陷还是有意决策？** 只有当测试能够捕获错误分支、缺失的副作用、错误参数、边界情况或被破坏的契约时，它才有存在的价值。
+
+**独立推导期望值。** 使用字面量和人工校验的固件；表格驱动测试中 `want` 使用字面量是首选形式。由被测代码（或其辅助函数）计算出的期望值，无论代码做什么都能通过：
+
+```typescript
+// ❌ Mirror assertion: the same builder computes both sides — always true
+const expected = buildSearchQuery({ tag: 'urgent' });
+expect(buildSearchQuery({ tag: 'urgent' })).toBe(expected);
+
+// ✅ Hand-derived literal
+expect(buildSearchQuery({ tag: 'urgent' })).toBe('tag:"urgent"');
+```
+
+**不要写变更探测器。** 如果只有有意决策才能让测试失败——如常量的取值、文案措辞、内部结构——那么它只会在重构时触发，却在真正的缺陷面前保持沉默。应该测试依赖于该决策的行为：不要写 `expect(MAX_RETRIES).toBe(5)`，而要验证“失败调用会被重试 5 次，第 6 次绝不会发起”。
+
+**测行为，而非文本。** 断言脚本、技能或配置包含某一行，只能证明源码就是源码本身。应在受控输入下运行脚本，并断言其输出、副作用或退出码。面向 Agent 的指令性文档，应通过消费方 Agent 的行为来测试（superpowers:writing-skills）；面向人的 prose 则完全不需要测试。
+
+**测你的代码，而非框架。** 测试你的代码在其边界上做出的契约——你注册的路由、你发出的查询、你生成的负载。上游的实现机制应由其维护者来测试（典型反例：断言你的路由会调用已注册的处理器——那是框架的测试，不是你的）。当上游行为确实出乎意料时，针对该假设写一个窄范围的特征测试（characterization test）并明确命名假设。同样边界也适用于你的内部代码：构造函数、getter、常量和简单透传，只有在它们承担校验、归一化、默认值、推导、约束或副作用时才值得测试——否则应断言首个依赖于它们的、消费者可见的结果。
+
+### 门禁检查
+
+```
+编写测试体之前：
+  明确什么样的生产代码变更会让该测试失败。
+
+  无法命名              → 围绕可观测行为重新设计
+  “源码文本变了”        → 运行产物并断言其效果
+  只有有意决策会失败    → 这是变更探测器；改为测试
+                          依赖于该决策的行为
+
+  确认期望值未使用被测代码推导。
+  如果复用了被测代码的逻辑或辅助函数：
+    替换为字面量或人工校验的固件
+```
+
+## 原则二：使用真实对象
+
+**Mock 本身不值得断言。** 对 Mock 的断言，只在 Mock 存在时通过、不存在时失败——它对组件本身一无所言。应断言真实组件的行为；如果你发现自己在检查 Mock，那就去掉 Mock 或删掉该断言。
+
+```typescript
+// ✅ Real behavior
+expect(screen.getByRole('navigation')).toBeInTheDocument();
+
+// ❌ Mock existence
+expect(screen.getByTestId('sidebar-mock')).toBeInTheDocument();
+```
+
+**你的搭档的提醒：**“我们在测试 Mock 的行为吗？”
+
+**在正确的层级 Mock。** 在替换真实方法前，先了解它的所有副作用；只 Mock 缓慢或外部的操作，保留测试所依赖的部分为真实实现。不确定时，先让测试跑在真实实现上，观察究竟需要发生什么。
+
+```typescript
+// ❌ The mock swallows the config write that duplicate detection reads
+vi.mock('ToolCatalog', () => ({
+  discoverAndCacheTools: vi.fn().mockResolvedValue(undefined)
+}));
+
+// ✅ Mock only the slow server startup; the config write stays real
+vi.mock('MCPServerManager');
+```
+
+**让替身足够具体。** 当参数、调用次数或顺序属于契约的一部分时，就要断言它们——一个接受任意参数的假对象什么也验证不了。为每个分支（成功、失败、畸形输入）提供独立的固件或 spy，这样错误的分支就无法满足期望。
+
+**完整镜像真实数据。** 按真实存在的完整结构来 Mock——包含所有已文档化的字段——而不仅仅是你测试中读取的字段。部分 Mock 会在下游代码读取缺失字段时静默失败：测试通过，而集成已损坏。
+
+**生产类只承载生产方法。** 仅测试需要的清理逻辑应放在测试工具中，绝不要以 `destroy()` 的形式出现在生产类上。自问：这个方法是否只被测试调用？这个类是否拥有该资源的生命周期？答案有误 → 放到测试工具里。
+
+**复杂 Mock 不如真实组件。** 当 Mock 的搭建超过测试逻辑本身、Mock 缺少真实组件拥有的方法、或测试因 Mock 变更而崩溃时，改用基于真实组件的集成测试。**你的搭档的提问：**“这里真的需要用 Mock 吗？”
+
+### 门禁检查
+
+```
+添加 Mock 或测试辅助方法之前：
+  列出真实方法的所有副作用；测试所依赖的保持真实——
+  只在更底层的缓慢/外部层级进行 Mock。
+
+  Mock 的响应需完整镜像真实结构。
+
+  仅被测试调用的方法归属于测试工具，而非生产代码。
+
+  正要对 Mock 本身做断言？
+    去掉 Mock 或删掉该断言。
+```
+
+## 测试与实现一同交付
+
+TDD 循环——失败的测试、最小实现、重构——才是“完成”的定义。只交付行为所需的测试，且仅交付这些：平凡代码和面向人的 prose 不需要测试，为满足流程而写的测试会带来永久的维护成本。
+
+## 变异检查
+
+完成前，在脑中对生产代码做变异；对每一种现实的变异，至少应有一个测试会失败：
+
+- 错误的常量或参数
+- 错误的分支处理
+- 缺失的状态变更或副作用
+- 空返回或默认返回
+- 对 zero、空、nil、未授权或畸形输入缺失校验
+
+没有任何测试能捕获的变异，意味着该行为未受保护——或测试本身是同义反复。
+
+## 速查表
+
+| 当你…… | 应该…… |
+|-------------|-----|
+| 写任何测试 | 明确它要捕获的缺陷——是缺陷，而非决策 |
+| 构造期望值 | 手工推导；绝不要用被测代码来计算 |
+| 测试脚本或文档 | 运行它 / 对其消费者做压力测试；不要 grep 文本 |
+| 想测试依赖 | 测试你的边界契约，而非对方已文档化的实现机制 |
+| 想对 Mock 元素做断言 | 测试真实组件，或去掉 Mock |
+| 准备 Mock 方法 | 了解其副作用；在缓慢/外部层级 Mock |
+| 构造 Mock 响应 | 完整镜像真实结构 |
+| 需要仅测试使用的清理逻辑 | 放到测试工具中 |
+| Mock 搭建急剧膨胀 | 改用基于真实组件的集成测试 |
+| 完成测试文件 | 执行变异检查 |
+
+## 警示信号
+
+- 准备与断言共享同一对象，必然相等
+- 测试只能通过 panic、崩溃或缺失选择器而失败
+- 测试在每次有意变更时都失败，却从不在意外破坏时失败
+- 期望值隐藏在循环、构造器或辅助函数之后
+- 测试 grep 源码文本，或断言已移除的符号保持移除
+- 即使只剩下框架，该测试依然“有意义”
+- 测试仅为覆盖率而存在，未检查任何副作用或结果
+- 断言检查 `*-mock` 测试 ID，或在移除 Mock 后失败
+- 某个方法只被测试文件调用
+- Mock 搭建超过测试的一半，或你无法解释为何需要 Mock
+- “为了保险”而 Mock

package/skills/using-git-worktrees/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: using-git-worktrees
+description: "适用于需与当前工作区隔离的功能开发或执行实现计划前，通过原生工具优先、git worktree 兜底的方式确保独立工作区就绪"
+---
+
+# 使用 Git Worktree
+
+## 概述
+
+确保所有工作都在独立工作区中进行。优先使用平台原生的 worktree 工具，仅在无原生工具可用时再回退到手动 git worktree。
+
+**核心原则：** 先检测是否已处于隔离环境，再使用原生工具，最后回退到 git。不要与 harness 对抗。
+
+**开始时声明：** “我正在使用 using-git-worktrees 技能来创建独立工作区。”
+
+## 步骤 0：检测现有隔离状态
+
+**在创建任何内容之前，先检查是否已处于独立工作区中。**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+BRANCH=$(git branch --show-current)
+```
+
+**子模块防护：** `GIT_DIR != GIT_COMMON` 在 git 子模块中同样为真。在判定“已处于 worktree”之前，需先确认是否处于子模块中：
+
+```bash
+# 若返回路径，则处于子模块而非 worktree——按常规仓库处理
+git rev-parse --show-superproject-working-tree 2>/dev/null
+```
+
+**若 `GIT_DIR != GIT_COMMON`（且不在子模块中）：** 说明已处于关联 worktree 中。跳至步骤 2（项目初始化），不要再创建新的 worktree。
+
+按分支状态报告：
+- 处于分支上：“已在独立工作区 `<path>`，分支为 `<name>`。”
+- 游离 HEAD：“已在独立工作区 `<path>`（游离 HEAD，外部托管），结束时需创建分支。”
+
+**若 `GIT_DIR == GIT_COMMON`（或处于子模块中）：** 说明处于常规仓库检出状态。
+
+用户是否已在指令中表明 worktree 偏好？若无，请在创建 worktree 前征得同意：
+
+> “是否需要我为你创建一个独立 worktree？它可以保护当前分支不受改动影响。”
+
+若已存在明确偏好则直接遵循，无需询问。若用户拒绝，则在原地工作并跳至步骤 2。
+
+## 步骤 1：创建独立工作区
+
+**你有两种机制，请按以下顺序尝试。**
+
+### 1a. 原生 Worktree 工具（优先）
+
+用户已请求独立工作区（步骤 0 已获同意）。你是否已有创建 worktree 的方式？可能是名为 `EnterWorktree`、`WorktreeCreate`、`/worktree` 命令或 `--worktree` 参数的工具。如果有，请直接使用并跳至步骤 2。
+
+原生工具会自动处理目录选址、分支创建和清理。使用 `git worktree add` 而绕过原生工具会产生 harness 无法感知和管理的幽灵状态。
+
+仅在无原生 worktree 工具可用时，才进入步骤 1b。
+
+### 1b. Git Worktree 兜底方案
+
+**仅在步骤 1a 不适用时使用**——即你没有可用的原生 worktree 工具时，才手动通过 git 创建 worktree。
+
+#### 目录选择
+
+按以下优先级选择目录，用户的显式偏好始终优先于已观测到的文件系统状态。
+
+1. **检查指令中是否已声明 worktree 目录偏好。** 如用户已指定，直接使用，无需询问。
+
+2. **检查是否存在项目本地的 worktree 目录：**
+   ```bash
+   ls -d .worktrees 2>/dev/null     # 优先（隐藏目录）
+   ls -d worktrees 2>/dev/null      # 备选
+   ```
+   如存在则直接使用；若两者都存在，以 `.worktrees` 为准。
+
+3. **若无其他指引**，默认为项目根目录下的 `.worktrees/`。
+
+#### 安全性校验（仅针对项目本地目录）
+
+**创建 worktree 前必须确认目录已被忽略：**
+
+```bash
+git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
+```
+
+**若未被忽略：** 加入 .gitignore 并提交该改动后再继续。
+
+**为何关键：** 防止将 worktree 内容误提交到仓库。
+
+#### 创建 Worktree
+
+```bash
+# 根据所选位置确定路径
+path="$LOCATION/$BRANCH_NAME"
+
+git worktree add "$path" -b "$BRANCH_NAME"
+cd "$path"
+```
+
+**沙盒兜底：** 若 `git worktree add` 因权限错误（沙盒拒绝）失败，请告知用户沙盒已阻止 worktree 创建，改为在当前目录继续工作，并在原地完成初始化与基线测试。
+
+## 步骤 2：项目初始化
+
+自动检测并执行对应的初始化：
+
+```bash
+# Node.js
+if [ -f package.json ]; then npm install; fi
+
+# Rust
+if [ -f Cargo.toml ]; then cargo build; fi
+
+# Python
+if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+if [ -f pyproject.toml ]; then poetry install; fi
+
+# Go
+if [ -f go.mod ]; then go mod download; fi
+```
+
+## 步骤 3：验证干净基线
+
+运行测试以确保工作区初始状态干净：
+
+```bash
+# 使用项目对应的命令
+npm test / cargo test / pytest / go test ./...
+```
+
+**若测试失败：** 报告失败情况，询问是否继续或先行排查。
+
+**若测试通过：** 报告就绪。
+
+### 报告
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## 快速参考
+
+| 场景 | 操作 |
+|-----------|--------|
+| 已处于关联 worktree | 跳过创建（步骤 0） |
+| 处于子模块中 | 视为常规仓库（步骤 0 防护） |
+| 存在原生 worktree 工具 | 使用原生工具（步骤 1a） |
+| 无原生工具 | 使用 Git worktree 兜底（步骤 1b） |
+| `.worktrees/` 已存在 | 使用它（校验是否已忽略） |
+| `worktrees/` 已存在 | 使用它（校验是否已忽略） |
+| 两者都存在 | 使用 `.worktrees/` |
+| 两者都不存在 | 先检查指令文件，再默认使用 `.worktrees/` |
+| 目录未被忽略 | 加入 .gitignore 并提交 |
+| 创建时权限错误 | 沙盒兜底，原地工作 |
+| 基线测试失败 | 报告失败并询问 |
+| 无 package.json/Cargo.toml | 跳过依赖安装 |
+
+## 常见托词
+
+| 托词 | 实际情况 |
+|--------|---------|
+| “我显然不在 worktree 里，没必要检查” | 执行步骤 0。harness 创建的隔离和子模块都会让肉眼判断失误，用检测命令才能确定。 |
+| “`git worktree add` 比到处找原生工具更快” | 原生工具（如 `EnterWorktree`）负责选址、分支和清理。绕过它是头号错误——会产生 harness 无法感知和管理的幽灵状态。 |
+| “worktree 目录肯定已经被忽略了” | 请执行 `git check-ignore`。未被忽略的 worktree 目录会把整个工作树提交进仓库。 |
+| “随便起个目录名都行” | 显式指令优先于已存在的项目本地目录，项目本地目录优先于 `.worktrees/` 默认值。 |
+| “工作区是全新的，基线测试可以等等再跑” | 脏基线会让后续所有失败变得无法定位。现在就跑测试；是否带病继续由你的协作人决定。 |