@wenaixi/dsh-superpower 6.3.1 → 7.0.0

package/skills/subagent-driven-development/scripts/sdd-workspace

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Resolve and ensure the working-tree directory SDD uses for one plan's
+# short-lived artifacts: task briefs, implementer reports, review packages,
+# and the progress ledger. Print the plan directory's absolute path.
+#
+# One directory per plan (.superpowers/sdd/<plan-basename>/) so a follow-up
+# plan in the same working tree can never read or overwrite another plan's
+# artifacts. A stale ledger misread as current progress makes controllers
+# skip whole task sequences — plan-scoping removes that failure structurally.
+#
+# Basename slugs collide when two plans share a filename (docs/alpha/plan.md
+# vs docs/beta/plan.md), so each workspace records its owning plan's path in
+# a plan-path marker (repo-relative in-repo, absolute outside). A workspace
+# owned by a different plan is skipped and the slug disambiguated with the
+# plan's parent-directory name, then a counter. A workspace with no marker
+# predates the marker scheme and is adopted for the current plan so in-flight
+# workspaces keep resolving — which means the first collision on such a
+# legacy workspace adopts instead of detecting; acceptable, marker-less
+# workspaces age out as plans finish.
+#
+# The workspace lives in the working tree (not under .git/) because Claude Code
+# treats .git/ as a protected path and denies agent writes there — which blocks
+# an implementer subagent from writing its report file. A self-ignoring
+# .gitignore at .superpowers/sdd/ keeps every plan's workspace out of
+# `git status` and out of accidental commits without modifying any tracked file.
+#
+# Single source of truth for the workspace location, so task-brief and
+# review-package cannot drift to different directories.
+#
+# Usage: sdd-workspace PLAN_FILE
+set -euo pipefail
+
+if [ $# -ne 1 ]; then
+  echo "usage: sdd-workspace PLAN_FILE" >&2
+  exit 2
+fi
+
+plan=$1
+[ -f "$plan" ] || { echo "no such plan file: $plan" >&2; exit 2; }
+
+slug=$(basename "$plan" .md)
+[ -n "$slug" ] && [ "$slug" != "." ] && [ "$slug" != ".." ] \
+  || { echo "cannot derive a workspace name from: $plan" >&2; exit 2; }
+
+root=$(git rev-parse --show-toplevel)
+base="$root/.superpowers/sdd"
+
+# Normalize the plan path (physical directory, so relative/absolute/../
+# spellings of one plan compare equal) and express it as the marker value:
+# repo-relative when the plan lives under the repo root, absolute otherwise.
+plan_dir=$(CDPATH= cd -- "$(dirname "$plan")" && pwd -P)
+plan_abs="$plan_dir/$(basename "$plan")"
+case "$plan_abs" in
+  "$root"/*) plan_id=${plan_abs#"$root"/} ;;
+  *)         plan_id=$plan_abs ;;
+esac
+
+# True when the workspace at $1 is (or becomes) this plan's: an existing
+# marker must name this plan; a missing marker means a new workspace or a
+# pre-marker legacy one, and either way the plan claims it by writing one.
+owns() {
+  if [ -e "$1/plan-path" ]; then
+    [ "$(cat "$1/plan-path")" = "$plan_id" ]
+  else
+    mkdir -p "$1"
+    printf '%s\n' "$plan_id" > "$1/plan-path"
+  fi
+}
+
+dir="$base/$slug"
+if ! owns "$dir"; then
+  parent=$(basename "$plan_dir")
+  dir="$base/$slug-$parent"
+  if ! owns "$dir"; then
+    n=2
+    while ! owns "$base/$slug-$parent-$n"; do n=$((n + 1)); done
+    dir="$base/$slug-$parent-$n"
+  fi
+fi
+
+printf '*\n' > "$base/.gitignore"
+CDPATH= cd -- "$dir" && pwd

package/skills/{superpower-subagent-driven-development → subagent-driven-development}/scripts/task-brief

@@ -21,7 +21,9 @@ n=$2
 if [ $# -eq 3 ]; then
   out=$3
 else
-  dir=$("$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
+  # Invoke via bash rather than direct exec: some extractors (Python zipfile)
+  # strip Unix exec bits when unpacking marketplace packages (#2040).
+  dir=$("${BASH:-bash}" "$(cd "$(dirname "$0")" && pwd)/sdd-workspace" "$plan")
   out="$dir/task-${n}-brief.md"
 fi
 

package/skills/{superpower-subagent-driven-development → subagent-driven-development}/task-reviewer-prompt.md

@@ -1,19 +1,19 @@
-# 任务评审员提示词模板
+# 任务 reviewer 提示词模板
 
-在派发任务评审子代理时使用本模板。评审员只读取一次任务的 diff，并返回两项裁决：规格符合度与代码质量。
+在派发任务评审 subagent 时使用本模板。reviewer 只读取一次任务的 diff，并返回两项裁决：规格符合度与代码质量。
 
 **目的：** 校验单个任务的实现是否完全贴合需求（不多不少），且构建良好（清晰、已测试、易维护）
 
 ```
 Subagent (general-purpose):
-  description: "Review Task N (spec + quality)"
+  description: "评审任务 N（规格 + 质量）"
   model: [MODEL — 必填：按 SKILL.md 的模型选择规则选择；若省略则静默继承会话中最昂贵的模型]
   prompt: |
     你正在评审单个任务的实现：先判断是否符合需求，再判断是否构建良好。这是一个任务级别的门禁，而非合并评审——所有任务完成后的全分支广度评审会另行进行。
 
     ## 需求内容
 
-    阅读任务简报：[BRIEF_FILE]
+    阅读 task brief：[BRIEF_FILE]
 
     来自规格/设计且约束本任务的全局约束：
     [GLOBAL_CONSTRAINTS]
@@ -22,7 +22,7 @@ Subagent (general-purpose):
 
     阅读实现者的报告：[REPORT_FILE]
 
-    ## 待评审的 Diff
+    ## 待评审的 diff
 
     **Base:** [BASE_SHA]
     **Head:** [HEAD_SHA]
@@ -32,21 +32,21 @@ Subagent (general-purpose):
     `git diff --stat [BASE_SHA]..[HEAD_SHA]` 和 `git diff [BASE_SHA]..[HEAD_SHA]`。
     不要遍历更广的代码库。仅在你能明确指出具体风险时，才去检查 diff 之外的代码——每个已命名的风险只做一次聚焦检查，并在报告中同时写明风险是什么以及你检查了什么。跨切面变更属于合理的已命名风险：如果 diff 改动了锁顺序、函数或 API 契约、或共享可变状态，检查调用点就是正确的做法。
 
-    本次评审在当前检出上为只读。不要以任何方式修改工作区、暂存区、HEAD 或分支状态。
+    本次评审在当前检出上为只读。不要以任何方式修改 working tree、暂存区、HEAD 或分支状态。
 
-    ## 禁止派发子代理
+    ## 禁止分发 subagent
 
-    由你独立完成全部评审。不要派生子代理来分担 diff 的部分评审，也不要为二次意见再派一个评审员。本流程已提供了该工作所需的所有评审席位；你派生的评审员会以全量成本重复其中一个席位，且其裁决不计入结果。如果 diff 过大、单次难以看完，请自行分多轮评审，并在报告中说明。
+    由你独立完成全部评审。不要衍生 subagent 来分担 diff 的部分评审，也不要为二次意见再派一个 reviewer。本流程已提供了该工作所需的所有评审席位；你衍生的 reviewer 会以全量成本重复其中一个席位，且其裁决不计入结果。如果 diff 过大、单次难以看完，请自行分多遍评审，并在报告中说明。
 
     ## 不要信任报告
 
-    将实现者的报告视为未经核实的陈述。它可能不完整、不准确或过于乐观。请以 diff 为准核实其声明。报告中的设计理由同样是陈述：“按 YAGNI 保留”、“有意保持简单”或任何其他解释，都是实现者在给自己的工作打分。请按代码本身的优劣来评判——陈述的理由永远不会降低问题的严重级别。
+    将实现者的报告视为未经核实的陈述。它可能不完整、不准确或过于乐观。请以 diff 为准核实其声明。报告中的设计理由同样是陈述：“按 YAGNI 保留”、“有意保持简单”或任何其他解释，都是实现者在给自己的工作打分。请按代码本身的优劣来评判——陈述的理由永远不会降低 finding 的严重级别。
 
     ## 测试
 
     实现者已运行测试，并针对当前代码按 TDD 要求报告了结果与证据。不要为核实其报告而重新运行整个测试套件。仅在阅读代码后产生具体疑点、且现有运行结果无法解答时，才运行测试——此时也只运行聚焦的单项测试，绝不要运行包级别全量套件、竞态检测或重复/高频循环。如果认为有必要做重量级验证，请在报告中建议，而不是直接执行。如果当前环境无法执行命令，请写明你会运行哪条测试。
 
-    实现者报告的测试输出中的警告或其他噪音即为问题——测试输出应当是干净的。
+    实现者报告的测试输出中的警告或其他噪音即为 finding——测试输出应当是干净的。
 
     你看不到的证据不代表不存在。如果报告或其中的测试证据看起来被截断，或你找不到其声称的结果，请按其标注的路径重新读取该文件——如果确实缺失或格式错乱，请作为面向控制器的缺口上报。重新运行套件来补全你没读到的内容不叫验证；证据不可读不等于证据无效。
 
@@ -58,9 +58,9 @@ Subagent (general-purpose):
     - **多余：** 未被要求的功能、过度设计、不必要的“锦上添花”
     - **误解：** 功能方向正确但实现方式错误，或解决了错误的问题
 
-    如果简报中列出了多个文件且每个文件各有改动（批量派发），请逐文件对照 diff 检查：每个列出的文件都必须有对应的 hunk。简报中列出但 diff 始终未触及的文件，即为“缺失”问题，无论批次中其余部分看起来多么干净。
+    如果 brief 中列出了多个文件且每个文件各有改动（批量派发），请逐文件对照 diff 检查：每个列出的文件都必须有对应的 hunk。brief 中列出但 diff 始终未触及的文件，即为“缺失”finding，无论批次中其余部分看起来多么干净。
 
-    如果某项需求仅凭本 diff 无法验证（它位于未变更的代码中或跨多个任务），请将其记为 ⚠️ 项，而不是扩大检索范围。
+    如果某项需求仅凭本 diff 无法验证（它位于未变更的代码中或跨多个任务），请将其记为 [WARN] 项，而不是扩大检索范围。
 
     ## 第二部分：代码质量
 
@@ -80,49 +80,49 @@ Subagent (general-purpose):
     - 实现是否遵循了计划中的文件结构？
     - 本次变更是否产生了已经很大的新文件，或显著增大了现有文件？（不要对变更前已有的文件体积做评价——只关注本次变更带来的增量。）
 
-    报告应当指向证据：每个问题以及所有本可用一句“是”带过的检查，都需给出 file:line 引用。一份精炼且带行号引用的报告，能让控制器获得所需的一切信息。
+    报告应当指向证据：每条 finding 以及所有本可用一句“是”带过的检查，都需给出 file:line 引用。一份精炼且带行号引用的报告，能让控制器获得所需的一切信息。
 
-    你的最终消息即为报告本身：直接以规格符合度裁决开头。每一行都应是裁决、带 file:line 的问题、或你已执行的检查——不要写前言、过程叙述或收尾总结。
+    你的最终消息即为报告本身：直接以规格符合度裁决开头。每一行都应是裁决、带 file:line 的 finding、或你已执行的检查——不要写前言、过程叙述或收尾总结。
 
     ## 评级校准
 
-    按实际严重程度对问题分级。并非所有问题都是严重。
-    重要表示该任务在修复前不可信：错误或脆弱的行为、遗漏的需求、或足以阻断合并的可维护性损伤——例如逻辑块的逐字重复、被吞掉的错误、断言空洞的测试。“覆盖可以更广”和打磨类建议属于轻微。
-    如果计划或简报明确要求了按本标准应判为缺陷的内容（例如断言空洞的测试、逻辑块的逐字重复），这依然算问题——请按重要级别上报，并标注为计划强制要求。计划的作者身份不为其自身打分；最终由人来定夺。
+    按实际严重程度对 finding 分级。并非所有问题都是 Critical。
+    Important 表示该任务在修复前不可信：错误或脆弱的行为、遗漏的需求、或足以阻断合并的可维护性损伤——例如逻辑块的逐字重复、被吞掉的错误、断言空洞的测试。“覆盖可以更广”和打磨类建议属于 Minor。
+    如果计划或 brief 明确要求了按本标准应判为缺陷的内容（例如断言空洞的测试、逻辑块的逐字重复），这依然算 finding——请按 Important 级别上报，并标注为 plan-mandated。计划的作者身份不为其自身打分；最终由人来定夺。
     在列出问题前，先肯定做得好的地方——准确的表扬有助于实现者信任后续的反馈。
 
     ## 输出格式
 
     ### 规格符合度
 
-    - ✅ 符合规格 | ❌ 发现问题：[缺失/多余/误解的内容，并附 file:line 引用]
-    - ⚠️ 无法仅凭 diff 验证：[仅凭 diff 无法验证的需求，以及控制器应如何检查——需与上述 ✅/❌ 裁决一并报告，针对已可验证的部分给出结论]
+    - [OK] 符合规格 | [FAIL] 发现问题：[缺失/多余/误解的内容，并附 file:line 引用]
+    - [WARN] 无法仅凭 diff 验证：[仅凭 diff 无法验证的需求，以及控制器应如何检查——需与上述 [OK]/[FAIL] 裁决一并报告，针对已可验证的部分给出结论]
 
     ### 优点
     [做得好的地方？请具体说明。]
 
     ### 问题
 
-    #### 严重（必须修复）
-    #### 重要（建议修复）
-    #### 轻微（可选优化）
+    #### Critical（必须修复）
+    #### Important（建议修复）
+    #### Minor（可选优化）
 
     每个问题需包含：file:line、问题是什么、为什么重要、如何修复（若不明显）。
 
     ### 评估
 
-    **任务质量：** [通过 | 需修复]
+    **任务质量：** [Approved | Needs fixes]
 
     **理由：** [1-2 句技术性评估]
 ```
 
 **占位符说明：**
-- `[MODEL]` — 必填：评审员模型，按 SKILL.md 的 Model Selection 选择
-- `[BRIEF_FILE]` — 必填：任务简报文件（执行 `scripts/task-brief PLAN N` 可打印路径；与实现者所依据的文件为同一份）
+- `[MODEL]` — 必填：reviewer 模型，按 SKILL.md 的模型选择规则选择
+- `[BRIEF_FILE]` — 必填：task brief 文件（执行 `bash scripts/task-brief PLAN N` 可打印路径；与实现者所依据的文件为同一份）
 - `[GLOBAL_CONSTRAINTS]` — 原样抄录计划中 Global Constraints 小节或规格中的约束性需求：精确的取值、格式以及组件之间的既定关系（不含流程类规则——那些已包含在本模板中）
 - `[REPORT_FILE]` — 必填：实现者写入详细报告的文件
 - `[BASE_SHA]` — 任务开始前的提交
 - `[HEAD_SHA]` — 当前提交
-- `[DIFF_FILE]` — 必填：控制器写入评审包的路径（执行 `scripts/review-package PLAN_FILE BASE HEAD` 会打印其写入的唯一路径；该包不会进入控制器的上下文）
+- `[DIFF_FILE]` — 必填：控制器写入review package的路径（执行 `bash scripts/review-package PLAN_FILE BASE HEAD` 会打印其写入的唯一路径；该包不会进入控制器的上下文）
 
-**评审员返回：** 规格符合度裁决（✅/❌/⚠️）、优点、问题（严重/重要/轻微）、任务质量裁决
+**reviewer 返回：** 规格符合度裁决（[OK]/[FAIL]/[WARN]）、优点、问题（Critical/Important/Minor）、任务质量裁决

package/skills/{superpower-systematic-debugging → systematic-debugging}/CREATION-LOG.md

@@ -89,13 +89,13 @@
 ## 最终成果
 
 具备以下能力的加固技能：
-- ✅ 明确要求开展根因调查
-- ✅ 抵御时间压力下的合理化
-- ✅ 为每个阶段提供具体步骤
-- ✅ 显式展示反模式
-- ✅ 在多种压力场景下完成测试
-- ✅ 澄清与 TDD 的关系
-- ✅ 可直接投入使用
+- [OK] 明确要求开展根因调查
+- [OK] 抵御时间压力下的合理化
+- [OK] 为每个阶段提供具体步骤
+- [OK] 显式展示反模式
+- [OK] 在多种压力场景下完成测试
+- [OK] 澄清与 TDD 的关系
+- [OK] 可直接投入使用
 
 ## 关键洞察
 

package/skills/{superpower-systematic-debugging → systematic-debugging}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: superpower-systematic-debugging
-description: "遇到缺陷、测试失败或异常行为时使用，要求先完成根因分析再提出修复，确保系统化调试"
+name: systematic-debugging
+description: "Superpower Skill（最高优先级）：遇到缺陷、测试失败或异常行为时使用，要求先完成根因分析再提出修复，确保系统化调试。"
 ---
 
 # 系统化调试
@@ -103,7 +103,7 @@ description: "遇到缺陷、测试失败或异常行为时使用，要求先完
     codesign --sign "$IDENTITY" --verbose=4 "$APP"
     ```
 
-    **由此可得：** 哪一层失败（secrets → workflow ✓，workflow → build ✗）
+    **由此可得：** 哪一层失败（secrets → workflow [OK]，workflow → build [FAIL]）
 
 5. **追踪数据流**
 
@@ -174,7 +174,7 @@ description: "遇到缺陷、测试失败或异常行为时使用，要求先完
     - 如有测试框架则编写自动化测试
     - 若无框架则编写一次性复现脚本
     - 修复前必须具备该用例
-    - 编写规范的失败测试请使用 `superpower-test-driven-development` 技能
+    - 编写规范的失败测试请使用 `test-driven-development` 技能
 
 2. **实施单一修复**
     - 针对已确认的根因
@@ -186,7 +186,7 @@ description: "遇到缺陷、测试失败或异常行为时使用，要求先完
     - 用例现在通过了吗？
     - 是否破坏了其他测试？
     - 问题是否真正解决？
-    - 在宣称成功前，请使用 `superpower-verification-before-completion` 技能进行校验
+    - 在宣称成功前，请使用 `verification-before-completion` 技能进行校验
 
 4. **若修复未生效**
     - 停下来
@@ -207,7 +207,7 @@ description: "遇到缺陷、测试失败或异常行为时使用，要求先完
     - 是否只是“靠惯性硬撑”？
     - 应该重构架构，还是继续修补表象？
 
-    **在尝试更多修复前，先与人类协作伙伴讨论**
+    **在尝试更多修复前，先与 human partner 讨论**
 
     这不是假设失败——这是架构错误。
 
@@ -230,7 +230,7 @@ description: "遇到缺陷、测试失败或异常行为时使用，要求先完
 
 **若已失败 3 次以上：** 质疑架构（见阶段四第 5 步）
 
-## 人类协作伙伴提示你做错了的信号
+## human partner 提示你做错了的信号
 
 **留意这些提醒：**
 - “这不是没生效吗？”——你在未验证的情况下做了假设

package/skills/{superpower-systematic-debugging → systematic-debugging}/condition-based-waiting.md

@@ -34,12 +34,12 @@ digraph when_to_use {
 ## 核心模式
 
 ```typescript
-// ❌ 修改前：猜测时机
+// [FAIL] 修改前：猜测时机
 await new Promise(r => setTimeout(r, 50));
 const result = getResult();
 expect(result).toBeDefined();
 
-// ✅ 修改后：等待条件满足
+// [OK] 修改后：等待条件满足
 await waitFor(() => getResult() !== undefined);
 const result = getResult();
 expect(result).toBeDefined();
@@ -84,14 +84,14 @@ async function waitFor<T>(
 
 ## 常见错误
 
-**❌ 轮询过快：** `setTimeout(check, 1)` - 浪费 CPU
-**✅ 修正：** 每 10ms 轮询一次
+**[FAIL] 轮询过快：** `setTimeout(check, 1)` - 浪费 CPU
+**[OK] 修正：** 每 10ms 轮询一次
 
-**❌ 无超时：** 条件始终不满足时会无限循环
-**✅ 修正：** 始终设置超时，并给出清晰的错误信息
+**[FAIL] 无超时：** 条件始终不满足时会无限循环
+**[OK] 修正：** 始终设置超时，并给出清晰的错误信息
 
-**❌ 数据过期：** 在循环前缓存状态
-**✅ 修正：** 在循环内调用 getter 获取最新数据
+**[FAIL] 数据过期：** 在循环前缓存状态
+**[OK] 修正：** 在循环内调用 getter 获取最新数据
 
 ## 何时应该使用任意延时
 

package/skills/{superpower-systematic-debugging → systematic-debugging}/find-polluter.sh

@@ -14,7 +14,7 @@ fi
 POLLUTION_CHECK="$1"
 TEST_PATTERN="$2"
 
-echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "[INFO] Searching for test that creates: $POLLUTION_CHECK"
 echo "Test pattern: $TEST_PATTERN"
 echo ""
 
@@ -40,7 +40,7 @@ for TEST_FILE in $TEST_FILES; do
 
   # Skip if pollution already exists
   if [ -e "$POLLUTION_CHECK" ]; then
-    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "[WARN] Pollution already exists before test $COUNT/$TOTAL"
     echo "   Skipping: $TEST_FILE"
     continue
   fi
@@ -53,7 +53,7 @@ for TEST_FILE in $TEST_FILES; do
   # Check if pollution appeared
   if [ -e "$POLLUTION_CHECK" ]; then
     echo ""
-    echo "🎯 FOUND POLLUTER!"
+    echo "[HIT] FOUND POLLUTER!"
     echo "   Test: $TEST_FILE"
     echo "   Created: $POLLUTION_CHECK"
     echo ""
@@ -68,5 +68,5 @@ for TEST_FILE in $TEST_FILES; do
 done
 
 echo ""
-echo "✅ No polluter found - all tests clean!"
+echo "[OK] No polluter found - all tests clean!"
 exit 0

package/skills/{superpower-systematic-debugging → systematic-debugging}/root-cause-tracing.md

@@ -101,7 +101,7 @@ npm test 2>&1 | grep 'DEBUG git init'
 使用本目录下的二分脚本 `find-polluter.sh`：
 
 ```bash
-./find-polluter.sh '.git' 'src/**/*.test.ts'
+bash ./find-polluter.sh '.git' 'src/**/*.test.ts'
 ```
 
 逐个运行测试，遇到首个污染者即停止。用法见脚本说明。

package/skills/{superpower-systematic-debugging → systematic-debugging}/test-pressure-1.md

@@ -21,7 +21,7 @@ PaymentError: Connection timeout to payments.api.com
 你记得上周另一个服务也出现过超时问题，当时加了重试就解决了，只花了 2 分钟。
 
 **系统化调试方法要求你必须：**
-1. 仔细阅读错误信息 ✓（已完成）
+1. 仔细阅读错误信息 [OK]（已完成）
 2. 稳定复现问题（搭建测试环境约需 10 分钟）
 3. 检查近期变更（审查 PR 约需 15 分钟）
 4. 查找可正常运行的示例（约需 10 分钟）

package/skills/{superpower-test-driven-development → test-driven-development}/SKILL.md

@@ -1,6 +1,6 @@
 ---
-name: superpower-test-driven-development
-description: "实现新功能或修复缺陷时，编写实现代码前先写测试的测试驱动开发完整指南与流程约束规范"
+name: test-driven-development
+description: "Superpower Skill（最高优先级）：实现新功能或修复缺陷时，编写实现代码前先写测试的测试驱动开发完整指南与流程约束规范。"
 ---
 
 # 测试驱动开发（TDD）
@@ -21,7 +21,7 @@ description: "实现新功能或修复缺陷时，编写实现代码前先写测
 - 重构
 - 行为变更
 
-**例外情况（需征得协作人同意）：**
+**例外情况（需征得 human partner 同意）：**
 - 一次性原型
 - 生成的代码
 - 配置文件
@@ -46,16 +46,16 @@ NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
 
 完全基于测试重新实现，没有例外。
 
-## 红-绿-重构
+## RED-GREEN-REFACTOR（红-绿-重构）
 
 ```dot
 digraph tdd_cycle {
     rankdir=LR;
-    red [label="红色阶段\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
+    red [label="RED\n编写失败的测试", shape=box, style=filled, fillcolor="#ffcccc"];
     verify_red [label="验证是否\n按预期失败", shape=diamond];
-    green [label="绿色阶段\n最小化实现", shape=box, style=filled, fillcolor="#ccffcc"];
+    green [label="GREEN\n最小化实现", shape=box, style=filled, fillcolor="#ccffcc"];
     verify_green [label="验证是否通过\n全部通过", shape=diamond];
-    refactor [label="重构阶段\n清理优化", shape=box, style=filled, fillcolor="#ccccff"];
+    refactor [label="REFACTOR\n清理优化", shape=box, style=filled, fillcolor="#ccccff"];
     next [label="下一项", shape=ellipse];
 
     red -> verify_red;
@@ -70,7 +70,7 @@ digraph tdd_cycle {
 }
 ```
 
-### 红色阶段 - 编写失败的测试
+### RED - 编写失败的测试
 
 写一个最小化的测试，展示应该发生什么。
 
@@ -112,7 +112,7 @@ test('retry works', async () => {
 - 命名清晰
 - 使用真实代码（除非不得不 mock）
 
-### 验证红色阶段 - 观察失败
+### Verify RED - 观察失败
 
 **强制要求，切勿跳过。**
 
@@ -129,7 +129,7 @@ npm test path/to/test.test.ts
 
 **测试报错了？** 修复错误，直到它以正确的方式失败为止。
 
-### 绿色阶段 - 最小化实现
+### GREEN - 最小化实现
 
 编写刚好能让测试通过的最简代码。
 
@@ -167,7 +167,7 @@ async function retryOperation<T>(
 
 不要添加测试未要求的功能，不要顺手重构其他代码，也不要做超出测试范围的“优化”。
 
-### 验证绿色阶段 - 观察通过
+### Verify GREEN - 观察通过
 
 **强制要求。**
 
@@ -184,7 +184,9 @@ npm test path/to/test.test.ts
 
 **其他测试失败？** 立即修复。
 
-### 重构阶段 - 清理优化
+**“其他测试”指项目的整个测试套件，而不只是你的文件。** 你自己写的测试通过，不代表套件变绿。在把改动宣布完成之前，请运行项目的测试命令（裸 `pytest`、`npm test`、`cargo test`——仓库用什么就用什么），即使你的任务只点名了一个测试文件。任务中的范围说明约束的是交付物，不是你的验证。这次运行暴露的任何失败——包括并非由你造成的失败——都要按名称写进你的报告；一个你眼睁睁看着滚过去却没提的红色测试，是一份因遗漏而伪造的报告。
+
+### REFACTOR - 清理优化
 
 仅在变绿之后：
 - 消除重复
@@ -301,7 +303,7 @@ PASS
 
 | 问题 | 解决方案 |
 |---------|----------|
-| 不知道怎么测 | 写出你期望的 API，先写断言，找协作人讨论。 |
+| 不知道怎么测 | 写出你期望的 API，先写断言，找 human partner 讨论。 |
 | 测试太复杂 | 设计太复杂，简化接口。 |
 | 必须 mock 所有东西 | 代码耦合过重，使用依赖注入。 |
 | 测试准备工作过于庞大 | 抽取辅助函数，依然复杂？简化设计。 |
@@ -319,4 +321,4 @@ PASS
 否则 → 就不是 TDD
 ```
 
-未经协作人许可，没有例外。
+未经 human partner 许可，没有例外。

package/skills/{superpower-test-driven-development → test-driven-development}/writing-good-tests.md

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