@liangjie559567/ultrapower 5.4.8 → 5.5.0

package/docs/reviews/draft_prd_pain_points/review_domain.md

@@ -0,0 +1,215 @@
+# Domain Expert Review: ultrapower 项目全面痛点修复计划
+
+**评审时间：** 2026-03-01
+**评审人角色：** Domain Expert（业务逻辑与行业标准专家）
+**评审对象：** Draft PRD — ultrapower 项目全面痛点修复计划
+**代码基线版本：** v5.4.8
+
+---
+
+## 整体评分：7 / 10
+
+PRD 体现了扎实的代码扫描能力，问题发现覆盖面广（118 项）。但部分安全严重度评级存在偏差：P0-3 被高估、P0-5 被低估；P1-9 的业务价值分析缺失导致优先级判断失准；测试补全（P2-8~10）的优先级相对行业标准偏低。总体修复逻辑符合现实，行业标准对齐尚可，但仍有若干领域缺陷需要修正。
+
+---
+
+## 肯定点
+
+1. **安全分层清晰。** P0 到 P3 的四级分层与 OWASP/CVSS 的严重度分级理念一致，有利于工程团队按优先级交付。
+
+2. **P0-1 路径遍历问题定位准确。** `getStatePath()` 在 state-manager 中接受外部传入的 `name` 参数并直接拼接路径，经代码核查确认未调用 `assertValidMode()`，漏洞属实。该修复符合项目自身 `docs/standards/runtime-protection.md` 的 P0 安全规则。
+
+3. **P0-7 daemon.ts 动态代码注入的发现有价值。** 将 `JSON.stringify(cfg)` 注入 Node.js `-e` 脚本字符串，当 `config` 中含有反引号、特殊字符或换行时确实可破坏语法，属于真实的代码注入向量，定级 P0 合理。
+
+4. **P1-11 kill/write 顺序颠倒是典型的 TOCTOU 问题。** 先写状态后 kill 进程，若 kill 失败状态已损坏，无法自愈。修复方向（先 kill 成功再写状态）符合事务性操作的行业最佳实践。
+
+5. **P1 Windows 兼容性问题识别系统化。** 覆盖了 shell 命令、路径分隔符、`/tmp` 依赖等常见跨平台陷阱，适配策略（`process.platform` 分支、`os.tmpdir()`、`path.relative()`）均为 Node.js 生态标准做法。
+
+---
+
+## 差异点 / 问题
+
+---
+
+### D-DE-01：P0-3（git push origin main）严重度高估，应降级为 P2
+
+- **严重度：** MEDIUM（评审意见，当前 PRD 定级 P0）
+- **描述：**
+
+  P0-3 的理由是"违反 CLAUDE.md 分支策略规范（默认分支为 dev，禁止直接推送 main）"。但从业务逻辑视角评估：
+
+  1. **触发路径受控。** `git push origin main` 位于 `scripts/release-steps.mjs` 的 `syncMarketplace()` 函数中。该脚本是 CI/GitHub Actions 的发布管道入口，并非任意开发者日常调用路径。攻击面极度受限。
+  2. **运行时已有 dry-run 保护。** 函数签名包含 `dryRun = false` 参数，所有调用点均支持 `--dry-run` 旁路，不会意外执行。
+  3. **与 P0-7（代码注入）的危害不可同日而语。** P0-7 可被任意具有 config 写权限的路径触发代码执行；P0-3 至多造成分支规范违反，不涉及权限提升、数据泄露或服务中断。
+
+  按 CVSS v3.1 维度：影响范围（Scope）=局部，保密性/完整性影响=低，利用难度=高（需 CI 触发）。综合评分约 3.1，应归 P2（流程规范问题）而非 P0（安全漏洞）。
+
+- **建议：** 将 P0-3 移至 P2 分组，标注"分支策略合规修复"。修复方式：删除 `git push origin main` 改走 PR 流程，或改为 `git push origin HEAD:dev`，并在 CI YAML 中加 branch protection check。
+
+---
+
+### D-DE-02：P0-4（--yolo 标志）风险评估需补充 Gemini CLI 行为语义
+
+- **严重度：** MEDIUM
+- **描述：**
+
+  PRD 将 `--yolo` 定级 P0，理由是"禁用所有安全确认，生产环境安全风险"。但需补充领域背景：
+
+  1. **`--yolo` 是 Gemini CLI 的非交互模式标志。** 其作用是跳过用户确认提示（类似 `--yes` / `--non-interactive`），使 CLI 在自动化管道中可无人值守运行，属于工具设计的标准用法。
+  2. **在 MCP 服务器上下文中，非交互模式是必要的。** ultrapower 将 Gemini CLI 作为子进程调用，进程标准输入不连接终端，若不传 `--yolo`，CLI 遇到确认提示会永久阻塞。
+  3. **真实风险在于"无法关闭"而非"标志本身"。** 若某些 Gemini CLI 版本的 `--yolo` 额外禁用了内容过滤或沙箱，硬编码确实不可接受。
+
+  因此风险核心是"缺乏可配置性以应对未来 CLI 行为变更"，而非当前的代码注入或权限提升。严重度介于 P0 与 P1 之间。
+
+- **建议：** 维持现有定级（P0 可接受），但修复描述应精确化：新增 `OMC_GEMINI_YOLO` 环境变量控制，并在文档中明确 `--yolo` 的语义边界。如 Gemini CLI 未来版本收紧此标志含义，需重新评估。
+
+---
+
+### D-DE-03：P0-5（prompt-injection 静默失败）严重度被低估
+
+- **严重度：** HIGH（当前 PRD 列为 P0 但描述轻描淡写，修复方案不足）
+- **描述：**
+
+  经代码核查（`src/mcp/prompt-injection.ts:93-97`），失败路径的现状是：
+
+  ```typescript
+  } catch (err) {
+    console.error('[prompt-injection] CRITICAL: Could not scan agents/ directory...');
+    _cachedRoles = [];
+  }
+  ```
+
+  实际代码已有 `console.error` 日志输出（非"静默"），但 PRD 描述为"无任何错误日志"——此描述与源码不符，存在事实偏差。
+
+  真正的业务风险是：`_cachedRoles = []` 导致 `VALID_AGENT_ROLES` 为空数组，下游 `resolveSystemPrompt` 中的角色验证全部失败，所有 agent_role 参数被拒绝，MCP 工具退化为无角色模式——这是功能性降级，不是安全漏洞。
+
+- **建议：**
+  1. 修正 PRD 中的事实描述（代码已有错误日志）。
+  2. 补充 fallback 硬编码列表（真实业务需求）。
+  3. 考虑从 P0 降级为 P1（功能稳定性问题，无安全向量）。
+
+---
+
+### D-DE-04：P0-6（daemon.ts Windows ESM import）已有部分缓解措施，评估需更新
+
+- **严重度：** MEDIUM
+- **描述：**
+
+  经代码核查（`daemon.ts:424`），现有代码：
+
+  ```typescript
+  const modulePath = __filename.replace(/\.ts$/, '.js');
+  const daemonScript = `import('${modulePath}')...`;
+  ```
+
+  PRD 描述"Windows 路径 `C:\Users\...` 插入 import() 字符串导致 ESM import 失败"属实。但补充背景：
+
+  1. **该代码路径在实际 Windows 生产环境中是否被激活？** `__filename` 来自 `fileURLToPath(import.meta.url)`，在 esbuild 打包后的 CJS bundle 中，`import.meta.url` 被替换为 `{}` 导致 ESM 路径不可用——实际上打包后的 daemon 可能走不同的代码路径。
+  2. **`createMinimalDaemonEnv()` 的白名单设计体现了良好的安全意识**，PRD 未予肯定，建议保留。
+
+- **建议：** 修复建议（`pathToFileURL(modulePath).href`）正确。但需在验收标准中补充"在打包产物上的 Windows E2E 测试"，而非仅在源码层验证。
+
+---
+
+### D-DE-05：P1-9（delegation-enforcer 未集成）业务价值评估缺失
+
+- **严重度：** HIGH（业务影响大，PRD 分析不足）
+- **描述：**
+
+  PRD 将 P1-9 仅描述为"功能死区——模块存在但未被调用"，缺乏业务影响量化分析。经代码阅读，`delegation-enforcer` 的核心功能是：
+
+  **当 Task/Agent 调用未显式指定 `model` 参数时，自动从 agent definitions 注入默认模型（haiku/sonnet/opus）。**
+
+  其业务影响链：
+
+  1. 若 enforcer 未集成，所有不带 `model` 参数的 Task 调用将使用 Claude Code 默认模型（通常为当前会话模型），而非 agent catalog 中定义的轻量模型（如 `explore` 应为 haiku）。
+  2. 直接后果：haiku 级任务被 sonnet/opus 执行，**每次 agent 调用成本放大 3-10x**，在高并行场景（ultrawork、team 模式）下成本损失尤为显著。
+  3. 二级后果：CLAUDE.md 中的 model_routing 规范（haiku/sonnet/opus 分级）形同虚设，用户基于分级的成本预期完全失效。
+
+  这是一个持续发生的业务损耗问题，而非一次性功能缺失。在 49 个 agents、并行编排场景下，其成本影响可能远超其他 P1 问题。
+
+- **建议：**
+  1. 将 P1-9 提升为 P0.5 或 P1 中最高优先级。
+  2. 补充验收标准：集成后需验证 `Task({subagent_type: "ultrapower:explore"})` 在无 model 参数时实际使用 haiku，通过 MCP 日志或 mock 验证，而非仅靠单元测试。
+  3. 修复方案需注意：`bridge.ts` 中的 `processPreToolUse()`（第 765 行）目前已调用 `processOrchestratorPreTool()`，但后者未调用 `delegation-enforcer`。集成点清晰，实现难度不高。
+
+---
+
+### D-DE-06：P2 测试补全优先级偏低，不符合行业最佳实践
+
+- **严重度：** MEDIUM
+- **描述：**
+
+  PRD 将 `atomic-write`、`version`、`hooks` 三个核心 lib 的测试覆盖补全列为 P2。但从行业标准视角：
+
+  1. **`atomic-write` 无测试是 P1 级风险，而非 P2。** 原子写入是 state-manager 的最底层安全保障，该函数无测试意味着 P0-1 修复后的路径遍历防护无法被回归测试覆盖，后续修改时随时可能引入回归。测试缺失本身是安全修复的质量保障缺口。
+  2. **行业标准（Jest、Vitest 生态惯例）：** 安全关键路径（路径遍历防护、原子写入）的单元测试覆盖是代码合并的必要条件（pre-merge gate），而非发布后的技术债。
+
+- **建议：** 将 `atomic-write` 和 `validateMode` 的测试覆盖提升至 P1，与其防护的 P0 安全问题同批交付。P2 中保留 hooks 集成测试补全（复杂度高，可延后）。
+
+---
+
+### D-DE-07：P0-2（LSP shell 注入）需补充实际利用路径分析
+
+- **严重度：** MEDIUM
+- **描述：**
+
+  PRD 描述 `execSync(\`${checkCommand} ${command}\`)` 存在 shell 注入，定级 P0 合理。但缺少利用路径分析：
+
+  1. **`command` 的来源是什么？** 若来自 LSP servers 的静态配置表（如 `['clangd', 'pyright', 'tsserver']`），则注入向量为空，实际风险为低。
+  2. 若 `command` 可接受用户配置输入（如 `~/.claude/settings.json` 中的自定义 LSP 服务器路径），则注入向量存在，P0 定级正确。
+
+  未看到源码中 `servers.ts:155-163` 的完整上下文（该文件未在本轮读取中覆盖），因此无法做最终判断。
+
+- **建议：** 修复建议（改用 `execFileSync('which', [command])`）无论输入来源如何均为更安全的做法，应执行。但 PRD 应补充"command 参数来源分析"，以准确评估利用难度，避免高估或低估风险。
+
+---
+
+### D-DE-08：`--yolo` 之外，Gemini CLI 集成缺少输入大小防护
+
+- **严重度：** LOW（PRD 遗漏项）
+- **描述：**
+
+  代码中已有 `MAX_FILE_SIZE = 5MB`、`MAX_STDOUT_BYTES = 10MB` 的限制，体现了良好的资源防护意识。但 PRD 未提及一个潜在问题：prompt 字符串（`fullPrompt`）本身没有大小上限检查，极大的 prompt 可能导致子进程 stdin 阻塞或 OOM。这是 MCP 工具服务器的常见稳定性风险。
+
+- **建议：** 在 P2/P3 中增加一条：对 `executeGemini` 和 `executeGeminiBackground` 的 `prompt` 参数添加大小上限（建议 4MB，与 MAX_FILE_SIZE 对齐），超出时返回明确错误。
+
+---
+
+## 行业标准对照
+
+| 关注点 | 行业最佳实践 | 本项目现状 | 评估 |
+|--------|------------|----------|------|
+| 路径遍历防护 | 使用白名单验证 + 统一入口 | validateMode 存在但 state-manager 未调用 | 部分合规，P0-1 修复后可达标 |
+| Shell 注入 | 始终使用 execFileSync + 参数数组 | execSync 字符串拼接仍存在 | 不合规，需修复 |
+| 动态代码生成 | 禁止将外部数据插入 eval/exec 字符串 | JSON.stringify 插入 `-e` 脚本 | 不合规，P0-7 修复方向正确 |
+| 跨平台兼容 | 使用 path.resolve/path.relative + os.tmpdir() | 多处硬编码 Unix 路径和 shell 语法 | 不合规，P1 修复覆盖主要问题 |
+| 原子写入 | 写临时文件 + rename 保证一致性 | atomicWriteJsonSync 已实现，但无测试 | 实现合规，测试缺失 |
+| 进程子系统 | 先操作后更新状态，失败不污染状态 | handleKillJob 顺序颠倒 | 不合规，P1-11 修复方向正确 |
+| 测试安全关键路径 | 安全函数100%分支覆盖作为合并门禁 | atomic-write、validateMode 无完整测试 | 不合规，优先级应提升 |
+| 资源上限 | MCP 服务器对所有输入设置上限 | 文件/stdout 有限制，prompt 无上限 | 部分合规 |
+
+---
+
+## 总体建议
+
+**结论：Modification Required（需修改后方可执行）**
+
+### 关键领域缺陷（Critical Domain Gaps）
+
+1. **P0-3 严重度高估**：`git push origin main` 是 CI 脚本中的流程规范违反，不是安全漏洞，应降级为 P2。将有限的 P0 修复资源集中于真实安全向量（P0-1、P0-7、P0-2）。
+
+2. **P1-9 业务价值严重低估**：delegation-enforcer 未集成导致 model routing 规范形同虚设，在高并行场景下持续产生 3-10x 成本放大效应。应作为 P1 最高优先级修复，并补充成本影响量化。
+
+3. **P0-5 事实描述不准确**：代码已有 `console.error` 日志，"静默失败"描述有误。真实风险是功能降级（角色验证失效），应修正描述并重新评估是否维持 P0 定级。
+
+4. **测试补全优先级偏低**：`atomic-write` 和 `validateMode` 的测试覆盖应与对应的 P0 安全修复同批交付，而非推迟至 P2 批次，否则安全修复缺乏回归保障。
+
+5. **P0-2 利用路径分析缺失**：需补充 LSP `command` 参数来源分析，以准确评估实际利用难度，避免决策层误判优先级。
+
+### 执行建议
+
+- **Batch 1（P0 真实安全漏洞）**：P0-1、P0-2、P0-6、P0-7，以及 atomic-write 测试覆盖
+- **Batch 2（P1 高影响功能修复）**：P1-9（delegation-enforcer 集成）优先于其他 P1；P1-11、P1-10
+- **Batch 3（P1 其余 + P0-3 降级处理）**：Windows 兼容性（P1-1~P1-4）、内存泄漏（P1-5~P1-7）、P2-3（P0-3 降级后放此）
+- **Batch 4（P2/P3）**：命名空间清洁、文档同步、代码质量

package/docs/reviews/ultrapower-full-bugfix-plan/review_product.md

@@ -0,0 +1,135 @@
+# Product Strategy Review: ultrapower 全面痛点修复计划
+
+> 评审人: Product Director (axiom-product-director)
+> 评审日期: 2026-03-01
+> PRD 版本: Draft (118 问题，4 批次修复)
+> 产品版本基线: v5.4.8
+
+---
+
+## 整体评分：6 / 10
+
+**评分理由**：PRD 在技术识别层面做得扎实（问题分类清晰、P0 安全标注准确），但在产品战略层面存在三个根本性缺陷：缺乏用户影响量化、批次计划与发布节奏脱钩、验收标准停留在工程层面而非用户体验层面。这是一份偏工程视角的 Bug 修复计划，尚未达到可指导产品决策的 PRD 标准。
+
+---
+
+## 肯定点
+
+### 1. P0 安全问题识别准确
+
+将路径遍历（state-manager）、Shell 注入（LSP）、代码注入（daemon ESM）列为最高优先级，符合"信任边界优先"的产品安全原则。这 7 项 P0 安全问题一旦被利用，可能导致用户系统级损害，产品口碑不可逆受损，优先修复是正确决策。
+
+### 2. Windows 平台单独分层合理
+
+明确将 Windows 兼容性问题单列为 P1，与用户主运行环境（Windows 11）的实际情况一致。结合项目历史（2026-02-27 Windows hook 路径修复会话、$USERPROFILE 修复）可知这是持续性痛点，专项分层有必要。
+
+### 3. 分批策略体现了优先级意识
+
+4 个批次的整体方向（安全 -> 功能 -> 规范 -> 质量）逻辑清晰，符合"先稳定、后完善"的发布逻辑，避免了将代码质量整理与安全修复混在同一批次增加回归风险。
+
+---
+
+## 差异点 / 问题
+
+### D-PD-01: 用户影响维度完全缺失
+
+- 严重度: HIGH
+- 描述: PRD 列出了 118 项技术问题，但没有一项标注了"受影响用户规模"或"触发频率"。以 P1 内存泄漏（Python REPL Map、LSP timer）为例，这些问题仅在长时间会话中才会显现，实际触发用户比例可能很低；而 P2 中的 session-recovery 占位功能，却可能影响所有遭遇 Claude Code 崩溃的用户。当前优先级排序完全由技术严重度驱动，缺乏用户价值维度的校准。
+- 建议: 为每个优先级组补充"影响用户估计"（高/中/低频触发）和"用户可感知程度"（是否导致用户可见错误），作为优先级最终排序的第二权重。至少对 31 项 HIGH 问题进行用户影响评分。
+
+---
+
+### D-PD-02: PRD 背景描述存在重大遗漏
+
+- 严重度: HIGH
+- 描述: PRD 背景部分仅用一段话描述问题全景，完全没有提及项目当前真实状态。从 active_context.md 和 reflection_log.md 可知，项目已经经历了多轮紧急修复（v5.4.1 plugin.json 验证、v5.4.5 二次注入、v5.4.6 npm-cache 死锁），这些修复均源于生产环境的真实用户报错。这意味着"产品当前稳定性欠佳"这一背景是已知事实，但 PRD 没有将这个语境显式化，导致读者无法判断修复计划的紧迫性来自历史积压还是新发现的问题。
+- 建议: 在背景部分增加"当前产品健康状态"小节，说明：(1) 近 3 个月生产环境紧急修复次数（至少 5 次）；(2) 用户报告的核心痛点（plugin 安装失败、hook 路径错误）；(3) 技术债务积累的历史原因（快速迭代期遗留）。这样才能让 PRD 的紧迫性论证站得住脚。
+
+---
+
+### D-PD-03: "23项"与"31项"HIGH 严重度数据不一致
+
+- 严重度: HIGH
+- 描述: PRD 目标部分写道"消除 HIGH 严重度安全与稳定性 Bug（共 23 项实际统计为 31 项）"，这句话暗示了两个相互矛盾的数字，且没有解释差异来源。这对于需要向团队或外部利益相关方传达修复范围的产品文档而言，是严重的可信度问题——读者无法确认哪个数字是权威数字，也无法判断是否存在"被低估的修复工作量"。
+- 建议: 在 PRD 正式化之前必须厘清两个数字的来源：23 项是最初估计、31 项是精确统计，还是存在口径差异（例如 23 项是安全类、31 项含稳定性）。选择唯一权威数字，并在脚注说明统计口径。
+
+---
+
+### D-PD-04: Batch 1 与 Batch 2 存在未声明的技术依赖
+
+- 严重度: MEDIUM
+- 描述: P0 安全修复（Batch 1）中包含 state-manager 路径遍历防护（要求 `assertValidMode()` 接口）；而 P1 Windows 修复（Batch 2）中的 subagent-tracker 路径和 pre-tool 路径问题，很可能需要复用同一批路径处理工具函数。PRD 将两者拆入不同批次，但未说明跨批次的接口契约：Batch 2 能否独立于 Batch 1 的路径工具函数实现？如果不能，批次边界就存在隐性依赖，可能导致 Batch 2 开发时需要等待或重构 Batch 1 的输出。
+- 建议: 在分批计划中增加"批次间接口契约"小节，明确 Batch 1 输出哪些可复用的工具函数/类型定义，供 Batch 2 直接引用。可参考项目现有实践（Sub-PRD T-01 中循环依赖防护注释的做法）。
+
+---
+
+### D-PD-05: 验收标准停留在工程层面，缺乏用户验收维度
+
+- 严重度: MEDIUM
+- 描述: 当前验收标准（零回归、安全门禁、Windows 验证、测试新增、命名空间清洁、文档同步）全部是工程验收指标，没有用户体验层面的验收。以 P1 功能缺失（session-recovery 占位、job-management 阻塞）为例，即使代码修复通过了测试，用户是否能感知到体验改善？改善的幅度是否达到预期？这些在当前标准中无法被验证。
+- 建议: 为每个批次增加"用户可感知验收"维度，例如：Batch 2 完成后，在 Windows 环境执行核心工作流（auto-update、ax-export）的端到端成功率应达到 100%（对比 Batch 2 前的失败率基线）。
+
+---
+
+### D-PD-06: P2 命名空间迁移（superpowers -> ultrapower）的业务风险未评估
+
+- 严重度: MEDIUM
+- 描述: PRD 将 9 个文件的命名空间迁移（superpowers: -> ultrapower:）列为 P2。但从产品角度看，这不仅是代码整洁问题：如果用户当前的 CLAUDE.md、settings.json、或个人工作流脚本中使用了 `superpowers:` 前缀调用命令，命名空间修复后这些调用是否会静默失效？PRD 没有评估向后兼容性风险，也没有说明是否存在兼容层（例如 alias 机制）来保护现有用户。
+- 建议: 在 P2 命名空间修复前，明确两点：(1) 目前是否存在用户可调用的 `superpowers:` 命令（通过 skills/commands 目录确认）；(2) 如果存在，是否需要保留兼容 alias 至下一个大版本（参考 CLAUDE.md 中的废弃别名机制）。将这两点作为 P2 的前置调查任务。
+
+---
+
+### D-PD-07: 与 Q1/Q2 路线图的对齐关系缺失
+
+- 严重度: MEDIUM
+- 描述: PRD 没有说明这个修复计划与产品大版本路线图的关系。从项目历史看，ultrapower 处于高速迭代阶段（2 周内连续发布 v5.4.1 到 v5.4.8），这 118 个问题是否会与正在进行的新功能开发（例如 Nexus v2、deepinit 271 个 AGENTS.md）形成冲突？修复计划是独立于功能开发还是并行进行？如果并行，代码冲突和测试稳定性风险如何管理？
+- 建议: 增加"路线图对齐"小节，明确说明：(1) 4 个批次的预计发布版本号（如 Batch 1 对应 v5.5.0 patch，Batch 2 对应 v5.5.1 等）；(2) 是否有功能冻结期来保障修复质量；(3) 与正在进行的功能开发的冲突管理策略。
+
+---
+
+### D-PD-08: delegation-enforcer 未集成的业务影响未阐明
+
+- 严重度: LOW
+- 描述: PRD 将 "delegation-enforcer 未集成" 列为 P1 功能缺失，但没有解释其业务影响：delegation-enforcer 负责什么约束？不集成的情况下，用户或系统会出现什么可见的异常行为？如果这个组件是 OMC 核心编排逻辑的一部分，其缺失可能导致某些委派场景静默失效，影响用户对 multi-agent 工作流的信任。
+- 建议: 在 PRD 中补充对 delegation-enforcer 未集成的用户可见影响描述（哪些场景会因此产生错误行为或降级行为），以支持 P1 优先级的合理性论证。
+
+---
+
+### D-PD-09: 测试覆盖补全的范围不够明确
+
+- 严重度: LOW
+- 描述: PRD 提到"补全测试覆盖空白（atomic-write, version, hooks）"，但"空白"的定义模糊。从项目历史看，当前测试数量从 4663 增长到 4698，增量不大。118 个问题修复后，预期新增多少测试用例？当前覆盖率基线是多少？目标覆盖率是多少？没有这些数据，"测试新增"这一验收标准无法被量化验证。
+- 建议: 在验收标准中为测试补全设定可量化目标，例如："Batch 3 完成后，atomic-write、version、hooks 三个模块的单元测试行覆盖率均不低于 80%"，并提供当前基线数据。
+
+---
+
+## 总体建议
+
+### 立即修复（进入执行前必须解决）
+
+1. 解决 HIGH 问题数量不一致（D-PD-03）：在 ax-review 流程进入 ax-decompose 之前，必须确认 PRD 中 31 项 HIGH 问题的完整清单，不能带模糊数字进入开发阶段。
+
+2. 补充用户影响评分（D-PD-01）：为 31 项 HIGH 问题中每一项标注"用户可见性"（1=内部逻辑不可见，2=间接影响，3=用户直接报错），作为细粒度排序依据。
+
+### 进入 Batch 1 前的调查任务（Low-cost，1-2小时）
+
+3. 确认 superpowers: 命名空间的用户暴露面（D-PD-06）：grep skills/commands 目录，确认是否有用户可调用的 superpowers: 命令，决定是否需要兼容 alias。
+
+4. 补充 delegation-enforcer 的用户可见影响描述（D-PD-08）：可通过代码搜索确认其调用链，不需要新调查。
+
+### 发布策略建议
+
+当前产品在 2 周内经历 5 次紧急修复（v5.4.1 到 v5.4.8），这本身是一个信号：紧急响应速度很快，但系统性防御不足。建议将此次 4 批次修复计划与版本号策略绑定：
+
+- Batch 1（P0 安全）-> v5.5.0（minor 版本，明确传递"安全加固"信号）
+- Batch 2（P1 Windows+功能）-> v5.5.1
+- Batch 3（P2 命名空间+文档）-> v5.5.2
+- Batch 4（P3 代码质量）-> v5.5.3 或合并至下一个 minor
+
+每个批次在独立分支上开发，通过 CI Gate 后合并到 dev，避免批次间的代码污染。这也与项目现有的 PR 工作流保持一致。
+
+### 最终结论
+
+- **优先级**: P1 - Should Have（当前版本）
+- **条件**: 必须在执行前解决 D-PD-01（用户影响评分）和 D-PD-03（HIGH 问题数量一致性）
+- **备注**: 这是一个技术上正确但产品战略论证尚不充分的修复计划。最大风险不在于修复本身，而在于 118 个问题对应的"用户可感知价值"没有被量化——执行完之后，团队无法有证据地向用户或利益相关方说明"产品变好了多少"。建议在 ax-decompose 阶段将用户影响评分纳入每个 Sub-PRD 的验收标准。

package/docs/reviews/ultrapower-pain-points/review_critic.md

@@ -0,0 +1,181 @@
+# Critic Review: ultrapower 项目全面痛点修复计划 Draft PRD
+
+**评审时间：** 2026-03-01
+**评审人：** The Critic（安全漏洞 / 边缘情况 / 逻辑一致性审核）
+**被评审文件：** `.omc/axiom/draft_prd_pain_points.md`
+**代码基版本：** v5.4.8（branch: main）
+
+---
+
+## 整体评分：3 / 10
+
+PRD 识别出了真实存在的问题，但在数字自洽性、修复方案可行性、关键安全遗漏和实施可行性四个维度上存在严重缺陷。以当前状态不可直接进入实施阶段。
+
+---
+
+## 肯定点
+
+1. **问题识别覆盖面广**：10 个模块全量扫描，118 个问题的分类框架是有价值的起点。
+2. **P0-3 确认属实**：`scripts/release-steps.mjs:84` 的 `git push origin main` 确实存在，违反 CLAUDE.md 分支策略，是真实的规则违反。
+3. **P0-6 确认属实**：daemon.ts Windows 路径 ESM import 失败问题已在代码中确认（第424行 `__filename.replace`，在 Windows 路径下确实存在问题）。
+4. **P2 命名空间问题属实**：经代码确认，`commands/` 下3个文件和 `skills/` 下多个文件确实存在 `superpowers:` 旧命名空间引用。
+5. **P1-8 占位实现属实**：`src/hooks/recovery/session-recovery.ts:184-189` 确认存在占位注释并返回 `true`。
+
+---
+
+## 差异点 / 问题
+
+### D-CR-01：顶层目标数字自相矛盾（内部一致性崩溃）
+- **严重度：** HIGH
+- **描述：** PRD 第一节"背景与目标"明确写"消除 HIGH 严重度安全与稳定性 Bug（共 **23 项**）"，但第二节问题汇总表中 HIGH 列合计为 **31 项**（7+5+4+7+1+1+2+4=31）。这两个数字出现在同一份文档的相邻章节，差值 8 项，不存在解释性脚注。这暴露出 PRD 由多个片段拼合而成，未经整体一致性校验。任何依赖该数字进行工作量估算或进度追踪的下游 agent / 人员都会得到错误基线。
+- **建议：** 在 PRD 定稿前，必须选择一个数字并对齐全文所有引用。优先使用表格统计值（31）并修正目标描述。
+
+---
+
+### D-CR-02：P0-1 修复方案的类型不匹配——assertValidMode 与 state-manager 的语义冲突
+- **严重度：** HIGH
+- **描述：** PRD 声称修复方案是"在 `getStatePath()` 入口添加 `assertValidMode(name)` 调用"。经代码核实：
+  - `assertValidMode()` 的白名单（`validateMode.ts:18-27`）仅包含 8 个值：`autopilot, ultrapilot, team, pipeline, ralph, ultrawork, ultraqa, swarm`。
+  - 但 `state-manager` 的调用者并不只传入这 8 个模式名。实际代码中存在大量合法的非模式 state name，例如：`LEGACY_LOCATIONS` 的键包含 `boulder, hud-state, prd, ralph-verification` 等；MCP 工具中还会传入会话 ID、analytics 等任意 name。
+  - 如果直接在 `getStatePath()` 加入 `assertValidMode()`，将导致所有非模式 state 操作（analytics、daemon state、boulder state 等）在运行时抛出异常，造成比修复前更严重的功能破坏。
+  - 正确做法应该是区分"模式 state 路径"和"通用 state 路径"，只对前者做白名单校验；或者为 MCP tool 暴露的 `state_read/write` 接口单独加校验层。
+- **建议：** 修复方案必须重新设计。不能在 `getStatePath()` 全局添加 `assertValidMode()`，而应在上层调用链中对来自外部输入的 `mode` 参数做校验，保留内部调用的灵活性。
+
+---
+
+### D-CR-03：P0-4 的"修复"会直接导致 Gemini CLI 挂起
+- **严重度：** HIGH
+- **描述：** PRD 声称通过 `OMC_GEMINI_YOLO=false` 环境变量使 `--yolo` 可配置，以解决"生产环境安全风险"。但代码现实是：
+  - Gemini CLI 的 `--yolo` 标志是"跳过所有交互式确认"的必需参数。在无终端（non-interactive）、无 TTY 的 CI 和 hook 执行环境下，去掉 `--yolo` 后 Gemini CLI 会停在确认提示处等待用户输入，导致进程永久阻塞。
+  - 这意味着默认禁用 `--yolo` 会把所有 Gemini MCP 调用变成死锁。PRD 把一个影响运行时可用性的决策降级为"可配置项"，但没有说明默认值，也没有说明 CI 环境如何处理。
+  - 安全风险（`--yolo` 禁用确认）和可用性风险（无 `--yolo` 导致阻塞）在 PRD 中被当作单一维度处理，实则是两个相互对立的约束。
+- **建议：** 此问题需要在 PRD 中明确说明：默认值必须保持 `--yolo=true` 以保证非交互环境可用；同时应通过限制 Gemini 执行的命令范围（scope 白名单）而非禁用 `--yolo` 来控制安全风险。修复方向写反了。
+
+---
+
+### D-CR-04：P0-7 的"修复方案"会破坏现有 daemon 架构
+- **严重度：** HIGH
+- **描述：** PRD 建议"通过 stdin / 环境变量传递 config"来取代 `JSON.stringify` 插入代码字符串。但 daemon 的当前架构是：
+  - `spawn('node', ['-e', daemonScript])` 使用 `-e` 执行内联脚本（第435行）。
+  - `stdio: 'ignore'` 已明确设置（第437行），即子进程的 stdin/stdout/stderr 全部关闭。
+  - 修改为 stdin 传递意味着必须将 `stdio` 从 `'ignore'` 改为 `['pipe', 'ignore', 'ignore']`，但这会影响 `child.unref()` 的行为——保持 stdin pipe 开启会阻止父进程在部分 Node.js 版本中正常退出，破坏"fire and forget"的 daemon 设计意图。
+  - PRD 没有说明如何处理这个架构性矛盾。"通过环境变量"是更可行的替代，但 config 中可能含路径等大型字符串，环境变量有长度限制（Windows 上约 32KB）。
+- **建议：** 必须在 PRD 中明确选择一种方案并分析副作用：(A) 使用临时文件传递 config（写入后由子进程读取，需要清理逻辑）；(B) 保留 JSON.stringify 但对 config 字段做严格转义校验（更小改动）。不能只写"通过 stdin"就结束。
+
+---
+
+### D-CR-05：P0-2 的修复方案被实际代码否定——问题已部分存在但形式不同
+- **严重度：** MEDIUM
+- **描述：** PRD 声称 `execSync(\`${checkCommand} ${command}\`)` 存在 shell 注入风险，建议改为 `execFileSync('which', [command])`。经代码核实（`src/tools/lsp/servers.ts:157-158`）：
+  - 实际代码已经做了平台分支：`const checkCommand = process.platform === 'win32' ? 'where' : 'which'`。
+  - 但 `command` 变量的来源和是否经过校验仍未在 PRD 中说明。如果 `command` 来自 LSP server 配置文件（用户可控），才是真实注入风险；如果来自内部硬编码列表，风险可忽略。
+  - PRD 省略了这个关键的"威胁来源"分析，使得修复的必要性和紧迫性无法被独立验证。
+- **建议：** 必须补充 `command` 变量的数据流分析（从哪里来，是否用户可控），才能正确评估此问题的严重度。
+
+---
+
+### D-CR-06：P1-9 delegation-enforcer"功能死区"的真实原因被模糊化
+- **严重度：** MEDIUM
+- **描述：** PRD 描述 delegation-enforcer 是"功能死区"，建议"在 `bridge.ts` 的 `processHook` 中实际集成"。经代码核实：
+  - `src/features/delegation-enforcer.ts` 确实存在完整的 `enforceModel()` 实现。
+  - `src/__tests__/delegation-enforcer-integration.test.ts:13` 的注释明确说明原因："these tests are SKIPPED because the delegation enforcer is not yet wired into the hooks bridge"。
+  - 但 `bridge.ts` 中完全没有任何 `import` 或调用 `delegation-enforcer` 的痕迹（已通过 grep 确认零匹配）。
+  - PRD 把这个问题归类为 P1（中等）是否合理？`enforceModel` 的作用是确保每个 Task 调用都有正确的 model 参数。如果 enforcer 从未被调用，那么所有 Task 调用中 model 参数的自动注入功能都是死代码，这可能是一个影响整个多 Agent 编排核心功能的 P0 问题，而非 P1。
+- **建议：** 重新评估此问题严重度。同时 PRD 需要说明：集成 enforcer 到 `processHook` 的性能影响（每次 hook 调用都会执行 enforcer），以及是否应该只在 `pre-tool-use` 中对 Task 类型调用执行。
+
+---
+
+### D-CR-07：Batch 1 任务数量与覆盖项目数严重不匹配
+- **严重度：** HIGH
+- **描述：** PRD 第十一节："Batch 1（P0 安全 + 稳定性）- 估计 **2 个任务**"，但覆盖范围是 P0-1 至 P0-7（7项）加 P1-6/P1-7（2项），共 **9 个独立修复点**，横跨 4 个不同文件（`state-manager/index.ts`, `lsp/servers.ts`, `release-steps.mjs`, `gemini-core.ts`, `daemon.ts`, `lsp/client.ts`）。"2 个任务"严重低估了工作量。这不是措辞问题，而是会导致 executor agent 在 2 个任务预算内试图完成 9 项修复，进而走捷径或遗漏验证。同样的问题存在于 Batch 2（"3个任务"覆盖 9 项修复）和 Batch 3（"2个任务"覆盖 10 项修复）。
+- **建议：** 按照 1 个任务最多覆盖 2-3 个相关修复的原则重新拆分。Batch 1 至少需要 4 个任务。
+
+---
+
+### D-CR-08：验收标准"4698+ 测试全部通过"是不可验证的幻数
+- **严重度：** MEDIUM
+- **描述：** PRD 第十二节声明"npm test 中 4698+ 测试全部通过"。经代码核实：
+  - 项目中存在 210 个 `.test.ts` 文件（已通过 `find` 确认）。
+  - 但实际测试用例总数需要运行 `npm test` 才能确认，PRD 中的"4698"数字来源不明，可能是某次历史运行的结果，当前版本可能已变化。
+  - 更关键的问题是：此验收标准对新增修复没有增量要求。验收标准只说"不新增失败"，但没有要求 P0 修复必须有对应的回归测试覆盖。一个修复了但没有测试保护的安全补丁，在下次重构时可能被无意撤销。
+- **建议：** 删除具体数字"4698"，改为"当前测试基线数量（执行 `npm test` 获取）全部通过，且每个 P0 修复必须新增至少 1 个回归测试用例"。
+
+---
+
+### D-CR-09：严重安全问题遗漏——bridge-normalize.ts 快速路径绕过安全校验
+- **严重度：** HIGH（应为 P0，PRD 中未出现）
+- **描述：** 经代码核实，`src/hooks/bridge-normalize.ts:117-130` 的快速路径（fast path）逻辑存在安全风险：
+  - `isAlreadyCamelCase()` 函数判断：只要输入对象包含 `sessionId`、`toolName`、`directory` 中任意一个键，且没有下划线键，就直接跳过 Zod 验证，以原始对象直接返回。
+  - 这意味着攻击者可以构造一个包含 `sessionId: "anything"` 的恶意输入，同时附加任意未知字段，完全绕过 Zod schema 验证（包括 `KNOWN_FIELDS` 白名单过滤）。
+  - 快速路径的返回值中确实只选取了已知字段（第152-168行），但返回对象包含 `...rest` 展开（需要进一步确认），或者下游代码直接操作原始 `toolInput` 时，未知字段可能泄漏。
+  - CLAUDE.md 的安全规范明确要求"所有 hook 输入经 bridge-normalize.ts 白名单过滤"，但快速路径实际上跳过了这个保证。
+- **建议：** 此问题应升级为 P0。快速路径必须对敏感 hook 类型（`SENSITIVE_HOOKS`）禁用，或者快速路径的输出也必须经过字段白名单过滤。
+
+---
+
+### D-CR-10：严重安全问题遗漏——Atomics.wait 在主线程使用
+- **严重度：** HIGH（应为 P0，PRD 中未出现）
+- **描述：** 经代码核实，`src/hooks/subagent-tracker/index.ts:164-170` 和 `src/notifications/session-registry.ts:100` 中存在 `Atomics.wait()` 调用：
+  ```
+  Atomics.wait(view, 0, 0, ms);
+  ```
+  - `Atomics.wait()` 在 Node.js 主线程（非 Worker）中调用时，会抛出 `TypeError: Cannot use Atomics.wait() on the main thread`，导致整个 hook bridge 崩溃。
+  - 这取决于这些函数是否在 Worker 上下文中调用。但 hook bridge 的执行模型是单进程 Node.js，没有 Worker 线程的证据。如果确实在主线程调用，这是一个会导致 hook 系统完全失效的崩溃性 bug。
+  - PRD 的 4 个并行 Explore Agent 扫描中没有任何人发现这个问题，说明扫描质量存疑。
+- **建议：** 此问题应立即升级为 P0 并验证实际执行上下文。如果在主线程，必须替换为 `setTimeout` 基于的异步等待。
+
+---
+
+### D-CR-11：P1-8 路径错误——PRD 指向不存在的文件路径
+- **严重度：** MEDIUM
+- **描述：** PRD P1-8 声称问题位于 `src/features/session-recovery/session-recovery.ts:183-189`。但经文件系统核实，实际文件路径是 `src/hooks/recovery/session-recovery.ts`（`src/features/session-recovery/` 目录根本不存在）。PRD 中的路径是错误的。虽然问题本身属实（占位实现已确认），但错误的路径会导致 executor agent 找不到文件。这类路径错误可能在所有 118 个问题中普遍存在，因为 PRD 没有说明路径是如何获取和验证的。
+- **建议：** 所有"位置"字段必须通过 `find` 或 grep 实际验证后才能写入 PRD。
+
+---
+
+### D-CR-12：P0-3 修复方案不完整——删除 git push 后发布流程断裂
+- **严重度：** MEDIUM
+- **描述：** PRD 对 P0-3 的修复是"删除此行或改为走 PR 流程"。但 `release-steps.mjs` 是一个自动化发布脚本，`git push origin main` 是其中一个必要步骤。删除该行后：
+  - 版本 tag 推送到哪里？
+  - `main` 分支如何保持与发布版本同步？
+  - CLAUDE.md 规范要求"所有 PR 以 dev 为目标"，但这不意味着 `main` 永远不能有新提交——发布流程通常是 `dev -> main` 的合并。
+  - PRD 没有提供完整的替代发布流程，只是删除一行并说"走 PR 流程"，但自动化脚本如何创建 PR？
+- **建议：** 修复方案应重写为：将 `git push origin main` 替换为 `git push origin dev && gh pr create --base main --head dev --title "Release vX.X.X"`，或者明确说明人工步骤。不能简单删除。
+
+---
+
+### D-CR-13：验收标准"Windows 真实验证"没有可执行的 CI 方案
+- **严重度：** MEDIUM
+- **描述：** PRD 第十二节第3条："P1-1/P1-2/P1-3 在 Windows 11 真实环境验证"。但：
+  - 没有说明如何在 CI 中执行（GitHub Actions `windows-latest` runner？本地手动？）。
+  - 没有说明验证通过的具体标准（什么命令，什么输出算成功）。
+  - "真实验证"作为验收标准如果没有自动化，就只能依赖人工，这在快速迭代中极易被跳过。
+- **建议：** 验收标准必须包含具体的 CI 配置（如在 `.github/workflows/` 中添加 Windows runner）或具体的手动测试步骤（具体命令、期望输出）。
+
+---
+
+## 总体建议
+
+**结论：Reject（拒绝）**
+
+**严重阻碍（Major Blockers）：**
+
+1. **D-CR-01**：文档内部数字矛盾（23 vs 31 HIGH项），基线数字必须统一后才能进入实施。
+2. **D-CR-02**：P0-1 修复方案（assertValidMode 全局注入）会导致运行时功能性崩溃，比原有安全漏洞危害更大，必须重新设计。
+3. **D-CR-03**：P0-4 修复方向错误（禁用 --yolo 导致 Gemini 阻塞），会把 MCP Gemini 功能变为死锁。
+4. **D-CR-04**：P0-7 修复方案（stdin 传递 config）与 daemon 现有架构冲突（stdio: 'ignore'），需重新选择方案。
+5. **D-CR-07**：Batch 1 估计"2个任务"覆盖9项修复，工作量估算失真会导致实施质量下降。
+6. **D-CR-09**：bridge-normalize.ts 快速路径安全绕过未进入 P0，是比 PRD 已列出问题更严重的安全漏洞。
+7. **D-CR-10**：Atomics.wait 主线程问题未出现在 PRD 中，可能导致 hook 系统崩溃性失效。
+
+**必要的修订步骤：**
+
+- 统一全文数字（HIGH 项统一为 31）。
+- P0-1 修复方案改为：仅在 MCP tool 暴露的外部接口层（`state_read`/`state_write` tool handler）添加 mode 白名单校验，不修改 `getStatePath()` 函数签名。
+- P0-4 修复方案改为：维持 `--yolo` 默认开启，改为通过命令白名单限制 Gemini 可执行的操作范围。
+- P0-7 修复方案改为：使用临时文件传递 config，或对 JSON.stringify 输出进行反斜杠和引号的字符级转义校验。
+- 新增 P0-NEW-1：bridge-normalize.ts 快速路径对敏感 hook 禁用 fast path。
+- 新增 P0-NEW-2：验证并修复 Atomics.wait 主线程调用问题。
+- 修正所有文件路径引用（至少 P1-8 路径错误已确认）。
+- 重新估算分批任务数量，Batch 1 拆分为至少 4 个任务。
+- 验收标准补充：每个 P0 修复要求对应回归测试；Windows 验证要求具体 CI 配置或手动测试命令。