superpowers-zh 1.7.3 → 1.7.5

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "superpowers-zh",
       "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 22 款工具",
-      "version": "1.7.3",
+      "version": "1.7.5",
       "source": "./",
       "author": {
         "name": "jnMetaCode",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "superpowers-zh",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Claude Code / Hermes Agent / Cursor / Claw Code / Qoder 等 22 款工具",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "description": "AI 编程超能力中文增强版：头脑风暴、subagent 驱动开发、规划、TDD、调试、代码审查、收尾工作流，附 4 个中文 skills 沉淀。",
   "author": {
     "name": "jnMetaCode",

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "superpowers-zh",
   "displayName": "Superpowers 中文版",
   "description": "AI 编程超能力中文增强版：20 个 skills（14 翻译 + 4 中国原创 + 2 上游历史保留），支持 Cursor / Claude Code / Hermes Agent / Claw Code / Qoder 等 22 款工具",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "author": {
     "name": "jnMetaCode",
     "url": "https://github.com/jnMetaCode"

package/README.md

@@ -16,7 +16,10 @@ Chinese community edition of [superpowers](https://github.com/obra/superpowers)
 >
 > 🌍 Also available in [English](https://aiolaola.com/en?utm_source=github&utm_campaign=superpowers) · [日本語](https://aiolaola.com/ja?utm_source=github&utm_campaign=superpowers) · [Español](https://aiolaola.com/es?utm_source=github&utm_campaign=superpowers) · [한국어](https://aiolaola.com/ko?utm_source=github&utm_campaign=superpowers) · [繁體中文](https://aiolaola.com/zh-Hant?utm_source=github&utm_campaign=superpowers)
 
-> 🆕 **v1.7.3 更新亮点**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> 🆕 **v1.7.5 更新亮点**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> - 🐛 **两个 worktree / Gemini 的真问题** —— 修掉 worktree 清理静默空转；更正「Gemini 不支持子智能体」的错误说法（原说法会让 3 个 skill 在 Gemini CLI 上瘸腿）
+> - 🔄 **测试参考重构** —— `testing-anti-patterns` → `writing-good-tests`：从 5 个反模式清单改为两条原则 + 变异检查
+> - 🔄 **SDD 同步上游 v6.2.0** —— plan 作用域工作区（一份过期账本再也不会让控制者跳过整段任务）+ 五轮上限的唤回式修复循环与熔断裁定
 > - 🪟 **Windows bootstrap 修复** —— SessionStart hook 改经 Git Bash 分发（同步上游），hook 不加载 skill 就是死重
 > - 🧩 新增 **Cline** 与 **Kilo Code** 两款 VS Code 扩展（工具数 20 → 22）—— 按 rules 常驻开销做了专门设计，索引仅 4.5 KB
 > - 🔧 检测落空时会扫 PATH 给出**可直接复制的 `--tool` 命令**，不再只报「未检测到」

package/README.zh-Hant.md

@@ -16,7 +16,10 @@ Chinese community edition of [superpowers](https://github.com/obra/superpowers)
 
 > 📖 **免費配套學習** → [從零學會 AI 編程](https://aiolaola.com/?utm_source=github&utm_campaign=superpowers)：180 節免費實操課 + 《AI 編程實戰三卷書》線上閱讀 + 實戰社群 · superpowers 裝好後配上方法論效率翻倍 · 永久免費
 
-> 🆕 **v1.7.3 更新亮點**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> 🆕 **v1.7.5 更新亮點**（[完整 Release Notes →](RELEASE-NOTES.zh.md)）
+> - 🐛 **兩個 worktree / Gemini 的真問題** —— 修掉 worktree 清理靜默空轉；更正「Gemini 不支援子智能體」的錯誤說法（原說法會讓 3 個 skill 在 Gemini CLI 上瘸腿）
+> - 🔄 **測試參考重構** —— `testing-anti-patterns` → `writing-good-tests`：從 5 個反模式清單改為兩條原則 + 變異檢查
+> - 🔄 **SDD 同步上游 v6.2.0** —— plan 作用域工作區（一份過期帳本再也不會讓控制者跳過整段任務）+ 五輪上限的喚回式修復循環與熔斷裁定
 > - 🪟 **Windows bootstrap 修復** —— SessionStart hook 改經 Git Bash 分發（同步上游），hook 不載入 skill 就是死重
 > - 🧩 新增 **Cline** 與 **Kilo Code** 兩款 VS Code 外掛（工具數 20 → 22）—— 針對 rules 常駐開銷做了專門設計，索引僅 4.5 KB
 > - 🔧 偵測落空時會掃 PATH 給出**可直接複製的 `--tool` 命令**，不再只報「未偵測到」

package/RELEASE-NOTES.zh.md

@@ -6,6 +6,118 @@
 
 ---
 
+## v1.7.5 (2026-08-07)
+
+对齐上游 v6.2.0 的 **B 块 + D 块**（[#19](https://github.com/jnMetaCode/superpowers-zh/issues/19)）。
+
+### 🐛 worktree 清理静默空转（真 bug，我们与上游同样存在）
+
+`finishing-a-development-branch` 的步骤 6 在步骤 5 已经 `cd` 到主仓库根之后，才用 `git rev-parse --show-toplevel` 重算 `WORKTREE_PATH` —— 于是拿到主根路径，`.worktrees/` 溯源判断**永远匹配不上**，清理静默空转，随后分支删除还会因为 worktree 仍挂着而失败。上游记录说测试对象不得不偏离 skill 原文才能跑通。
+
+修法：步骤 2 趁还在工作区内就捕获，步骤 6 消费该值并加显式警告说明为何不能重算；去掉步骤 6 冗余的 `MAIN_ROOT` 推导与 `cd`；选项 2 补上菜单已声称的分离 HEAD 推送变体。
+
+**已实际复现验证**（临时仓库 + `.worktrees/feature`）：旧逻辑算得 `main` → 溯源未命中 → 清理空转；新逻辑捕获到 `main/.worktrees/feature` → 命中 → `worktree remove` 与 `branch -D` 均成功。
+
+### 🐛 我们把 Gemini 的子智能体支持写错了
+
+`gemini-tools.md` 原文称 Gemini CLI 没有 Task 等价物、依赖子智能体的 skill「退化为 `executing-plans` 单会话执行」。**这是错的** —— Gemini CLI 通过 `invoke_agent`（`agent_name: "generalist"`，也可用 `@generalist` 聊天语法）支持子智能体，且支持同一响应内多调用并行分派。
+
+这个错误会让 Gemini CLI 用户的 `subagent-driven-development` / `dispatching-parallel-agents` / `requesting-code-review` 全部瘸腿。按上游重写（33 → 62 行），补齐指令文件层级加载、`~/.gemini/skills` 与 `~/.agents/skills` 优先级、模板填写、并行分派，以及此前缺失的 20 个工具名。已全仓扫描确认无别处重复该说法。
+
+### 🔄 `testing-anti-patterns.md` → `writing-good-tests.md`
+
+上游把 299 行的反模式枚举重写为 198 行的**两条原则**：
+
+- **原则 1「点名它要抓的破坏」** —— 写测试体前先答"什么生产改动会让它失败，那是 bug 还是决定"。含镜像断言、变更探测器、测行为不测文本、测你的代码不测框架
+- **原则 2「跑真东西」** —— mock 不配拥有断言、在正确层级 mock、替身要具体、完整镜像真实数据、生产类只承载生产方法
+- 新增**变异检查**：收尾前在脑中变异生产代码，每种现实变异都应至少让一个测试失败
+- 触发条件放宽到「编写或修改**任何**测试时」
+
+TDD SKILL.md 同步：删掉「为什么顺序很重要」整节长散文（论点折进合理化借口表，5 行扩写）、删掉末尾已失效的「测试反模式」一节。
+
+### 🔧 audit 结构漂移度量修正（此前一直在虚报欠账）
+
+`audit.sh` 用 `grep -cE '^#{1,4} '` 数标题，但这会把 ``` 围栏内的 shell 注释（`# 运行测试`）当成 markdown 标题 —— 多几行 bash 注释就能凭空造出「结构漂移」。
+
+用正确口径（awk 逐行跟踪围栏）重算 14 个 skill，3 条告警里 **2 条是假阳性**：
+
+| skill | 旧口径 | 新口径 |
+|---|---|---|
+| `executing-plans` | 9/16 **WARN** | 9/11 pass |
+| `finishing-a-development-branch` | 21/31 **WARN** | 14/17 pass |
+| `using-git-worktrees` | 21/28 WARN | 14/21 **WARN（真漂移）** |
+
+双向验证：给 `brainstorming` 加 5 个真标题会触发告警，加 5 行围栏内 shell 注释不触发。
+
+### ✅ 验证
+
+- 两个新/改文件章节均与上游一一对应；`writing-good-tests.md` 指标精确一致（12 bold 要点 / 11 行表格 / 11 条危险信号 / 14 项代码记号）
+- **行为 eval 8 个判断场景：8/8 全对**。附带一个有价值的对照：agent 拿不到 `writing-good-tests.md`、只能退回 SKILL.md 四条摘要时得分 6/8 —— 错的恰好是只存在于参考文件里的两条规则（部分 mock 静默失败、琐碎转发 getter 不配有测试）。说明参考文件承载着摘要覆盖不到的承重规则。
+- `scripts/audit.sh` **152 pass / 1 warn / 0 fail**（原 150/3）、`scripts/verify-release.sh` **82 pass / 0 fail**
+
+---
+
+## v1.7.4 (2026-08-07)
+
+### 🔄 SDD 同步上游 v6.2.0：plan 作用域工作区 + 基于唤回的修复循环（#19 A 块）
+
+对齐上游 `subagent-driven-development` 的 6 个 commit。这是 [#19](https://github.com/jnMetaCode/superpowers-zh/issues/19) 拆分后的 A 块 —— 注意 v1.7.1 刚对齐过 SDD，本次是那之后的**新增量**。
+
+**为什么脚本与文档必须整块一起改：** 我们的 SKILL.md 里写的是旧签名 `review-package BASE HEAD`。脚本换成 plan 作用域签名后若不同步改文档，agent 会照旧签名调用直接吃 usage 错误 —— 比不同步更糟。
+
+**plan 作用域工作区（结构性修复）**
+
+原先所有计划共用 `.superpowers/sdd/` 一个目录，一份过期账本被误读成当前进度会让控制者**跳过整段任务序列**（上游称之为观察到的最昂贵失败）。现在每个计划一个 `.superpowers/sdd/<计划文件名>/`，从结构上消除误读。账本新增身份行 `# SDD ledger — plan: <路径>`。
+
+- `sdd-workspace` / `review-package` 在我们这边与上游 v6.1.1 字节一致（从未汉化），直接取上游版
+- `task-brief` 只手工应用上游那两处改动，**保留 fork 适配**（awk 同时匹配 `Task N` 与 `任务 N`，因为本仓库 writing-plans 产出中文标题）
+
+**SKILL.md 全面重写（平铺 14 节 → 生命周期结构）**
+
+- **修复循环**：一轮 = 一次修复分派 + 一次定向复审，每任务上限五轮。第 1-3 轮**唤回原实现者**（context 完整），第 4-5 轮换全新实现者 + 高一档模型
+- **熔断**：第 5 轮仍有未解决发现则停止分派，逐条裁定 —— 搁置（附裁定）或在承重项上 BLOCKED。只在上限处裁定，提早裁定等于换名字的预先定性
+- Minor 发现与「计划要求的」发现两条路在循环外
+- 新增「常见的合理化借口」表取代原「红线」清单
+- 新增 `re-review-prompt.md`（106 行全文翻译）
+
+### 🧹 清除 v1.7.1 遗留的生成产物
+
+三个 SDD 文件末尾都残留着 `</content>` —— v1.7.1 那次重写（PR #108, `d7885ca`）留下的，上游没有。这些文件会整体进 agent 的 prompt，属于污染。已全部清除并全仓扫描确认无同类残留。
+
+### ✅ 验证（含行为 eval）
+
+**结构性核对**
+- 章节结构与上游 14 节一一对应；`superpowers:` 引用集与上游完全一致
+- 26 项关键技术记号（脚本签名、账本行格式、四种状态、`ADDRESSED`/`NOT ADDRESSED`、数值门槛）逐一确认存在，无漏译
+- 两个 dot 图节点/边数与上游精确一致（6/6 与 23/28），且**无幽灵节点、无孤立节点** —— 手工翻译 dot 标签最易在边里写错，会静默产生幽灵节点
+
+**脚本实测**（临时 git 仓库）
+- 两个计划各得独立目录；往 A 计划写 ledger 后 B 计划目录仍为空（关键回归）
+- `.gitignore` 落在 `.superpowers/sdd/` 层且 `git status` 干净
+- 中文「任务 2」与英文「Task 3」经新路径均抽取成功
+- `review-package` 旧签名正确报 usage 错误
+
+**行为 eval —— 新机制 7 个场景全对**
+
+考察译文是否真的传达了新规则（第 2 轮该唤回还是换新、第 4 轮模型档位、第 5 轮能否再开一轮、承重发现该搁置还是停下、Minor 走哪条路、遇到别的计划的账本怎么办、控制者能否自己修）：**7/7 正确**，连「运行环境无法唤回时才改派全新实现者」这个细节都答出。
+
+**集成 eval —— 真实 agent 的准备阶段**
+
+用 `tests/subagent-driven-dev/go-fractals` 脚手架跑真实执行的准备阶段，验证 agent 是否按**新签名**调脚本（旧习惯可能让它省掉 `PLAN_FILE`）：
+
+- ✔ 实际调用 `sdd-workspace plan.md`，带上了 PLAN_FILE 参数
+- ✔ 同时检查了 plan 作用域账本**和**旧扁平路径的游离账本
+- ✔ 账本第一行为正确的身份行
+- ✔ 工作区落在 `.superpowers/sdd/plan/`，未在旧扁平路径写账本
+- ✔ 起飞前冲突扫描产出 5 条**打包成一次**的提问（而非逐条打断）
+- ✔ 建了 10 条待办，并按指令在分派实现者前停下
+
+**回归**：`scripts/audit.sh` 150 pass / 0 fail、`scripts/verify-release.sh` 82 pass / 0 fail。SDD 已从 audit 的上游漂移警告里消失（结构层级现已对齐）。
+
+> audit PASS 由 153 降至 150，是上游有意删除 Integration 一节（原列 `executing-plans` / `test-driven-development` / `writing-plans` 三个引用）导致 Category 4b 少 3 项引用检查，非静默跳过。
+
+---
+
 ## v1.7.3 (2026-08-07)
 
 ### 🐛 同步上游两处纯代码修复（对齐 v6.1.1 → v6.2.0 时挑出）

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
   "description": "AI 编程超能力中文版 — TDD、调试、代码审查等经过实战验证的工作方法论",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "contextFileName": "GEMINI.md"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "superpowers-zh",
-  "version": "1.7.3",
+  "version": "1.7.5",
   "engines": {
     "node": ">=20.0.0"
   },

package/skills/finishing-a-development-branch/SKILL.md

@@ -50,6 +50,9 @@ npm test / cargo test / pytest / go test ./...
 ```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)
+# 现在就捕获 —— 此刻还在工作区里面。步骤 5 会切换目录，
+# 而清理（步骤 6）需要这个值
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
 ```
 
 这决定了展示哪种菜单、以及清理方式：
@@ -129,6 +132,8 @@ git branch -d <feature-branch>
 ```bash
 # 推送分支
 git push -u origin <feature-branch>
+# 从分离 HEAD 出发时，在远端指定新分支名：
+# git push origin HEAD:refs/heads/<new-branch>
 
 # 创建 PR
 gh pr create --title "<title>" --body "$(cat <<'EOF'
@@ -179,21 +184,15 @@ git branch -D <feature-branch>
 
 ### 步骤 6：清理工作区
 
-**只对选项 1 和 4 执行。** 选项 2 和 3 始终保留 worktree。
+**只对选项 1 和 4 执行。** 选项 2 和 3 始终保留 worktree。两个调用方都已经切到主仓库根目录了 —— 移除 worktree 必须从 worktree 外面执行 —— 因此这里使用**步骤 2 里捕获的** `GIT_DIR` / `GIT_COMMON` / `WORKTREE_PATH`，也就是那次目录切换之前的值。
 
-```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)
-WORKTREE_PATH=$(git rev-parse --show-toplevel)
-```
+> ⚠️ **不要在这里重新计算这些值。** 此刻 `git rev-parse --show-toplevel` 返回的是主仓库根目录，不是 worktree 路径 —— 溯源判断会永远匹配不上，清理会静默空转，随后分支删除还会因为 worktree 仍挂着而失败。
 
 **如果 `GIT_DIR == GIT_COMMON`：** 普通仓库，无 worktree 可清理。结束。
 
-**如果 worktree 路径在 `.worktrees/` 或 `worktrees/` 之下：** 这是 Superpowers 创建的 worktree —— 我们负责清理。
+**如果 `WORKTREE_PATH` 在 `.worktrees/` 或 `worktrees/` 之下：** 这是 Superpowers 创建的 worktree —— 我们负责清理。
 
 ```bash
-MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
-cd "$MAIN_ROOT"
 git worktree remove "$WORKTREE_PATH"
 git worktree prune  # 自愈：清理任何过期的注册记录
 ```