@liangjie559567/ultrapower 5.0.21 → 5.0.23

package/docs/reviews/ultrapower-standards/review_critic.md

@@ -0,0 +1,230 @@
+# Critic Review: ultrapower 全链路规范体系 PRD
+
+> **评审者**: The Critic
+> **评审日期**: 2026-02-26
+> **PRD 版本**: 0.1 (Draft)
+> **评分**: 4 / 10
+
+---
+
+## 总体判定
+
+**Reject** — 当前草稿存在多个严重阻碍，不具备进入实现阶段的条件。核心问题是：PRD 描述的是"规范文档"这一交付物，但对规范本身的内容几乎没有任何实质性定义，导致验收标准无法验证、实现者无从下手。
+
+---
+
+## 1. Security Audit（安全审计）
+
+### [HIGH] 状态文件路径遍历风险 — Fail
+
+PRD 第 3.1 节要求制定"状态文件读写规范"，但完全没有提及路径安全。
+
+实际代码中，`.omc/state/` 下的文件名由 `mode` 参数直接拼接（如 `{mode}-state.json`）。若 `mode` 值来自用户输入或 hook 注入，存在路径遍历攻击面：
+
+```
+mode = "../../.claude/settings"
+=> 写入路径: .omc/state/../../.claude/settings-state.json
+```
+
+PRD 未要求规范中包含输入校验或路径白名单策略。这是一个被完全忽视的安全边界。
+
+### [HIGH] Hook 命令注入面未定义信任边界 — Fail
+
+`hooks.json` 中所有 hook 均以 `async: false` 同步执行，且 matcher 为空字符串（匹配所有工具调用）。PRD 的 Hook 执行顺序规范中没有要求定义：
+
+- hook 脚本的执行权限边界
+- hook 输入数据的消毒（sanitization）策略
+- 恶意或损坏的 hook 脚本导致整个 Claude 会话阻塞的降级方案
+
+`bridge-normalize.ts` 中提到了"严格白名单过滤"，但 PRD 没有要求将此策略形式化为规范，也没有要求覆盖所有 hook 类型（当前仅覆盖 permission-request、setup、session-end 三类）。
+
+### [MEDIUM] 状态文件无加密，敏感上下文明文存储 — Conditional Fail
+
+`.omc/state/` 下的 `agent-replay-*.jsonl` 文件包含完整的 agent 对话历史，可能含有代码、密钥片段、用户指令等敏感信息。PRD 的"状态文件读写规范"仅关注并发锁，未要求规范中包含：
+
+- 敏感字段识别和脱敏策略
+- 文件权限设置（如 chmod 600）
+- 数据保留期限和清理策略
+
+---
+
+## 2. Edge Case Analysis（边缘场景分析）
+
+### [CRITICAL] Hook 失败的级联效应未定义
+
+PRD 的 Hook 执行顺序规范（P0-1）定义了正常时序，但完全没有覆盖以下场景：
+
+- `PreToolUse` hook 超时或崩溃 → Claude 是否继续执行工具调用？
+- `PostToolUse` hook 写状态文件失败 → 状态是否回滚？下次读取会得到什么？
+- `Stop` hook 执行中 Claude 进程被强制终止 → 临时状态文件是否泄漏？
+
+实际的 `hooks.json` 中没有超时配置，没有重试策略，没有 fallback。PRD 要求制定的规范如果不覆盖这些场景，规范本身就是不完整的。
+
+### [CRITICAL] 状态文件损坏场景完全缺失
+
+PRD 提到"状态文件并发读写冲突"是已知问题，但规范要求仅停留在"禁止并发写入"这一预防层面。没有要求定义：
+
+- 检测到损坏 JSON 时的恢复流程
+- 部分写入（写到一半进程崩溃）的检测和修复
+- 状态文件版本不兼容时的迁移路径
+
+当前 `.omc/state/` 下存在 `last-tool-error.json`，说明错误状态已经在被持久化，但没有对应的清理和恢复规范。
+
+### [HIGH] Agent 生命周期状态机的死状态
+
+PRD 图 4.2 定义的状态机存在逻辑漏洞：
+
+```
+RUNNING --> ERROR : 异常/超时
+ERROR --> SHUTDOWN : 错误处理完成
+```
+
+问题：如果"错误处理"本身也失败了，状态机卡在 `ERROR` 状态，没有强制退出路径。这是一个死状态（dead state）。此外：
+
+- `WAITING` 状态没有超时转换，agent 可以永久等待用户输入
+- `IDLE` 状态没有最大存活时间，资源永不释放
+- 没有定义 `ZOMBIE` 状态（进程已退出但状态文件未清理）
+
+### [HIGH] 并发写入"禁止"策略的执行机制缺失
+
+P0-2 要求"禁止并发写入同一状态文件"，但 PRD 没有说明这个禁止是如何被强制执行的：
+
+- 是文件系统锁（flock）？
+- 是应用层乐观锁（版本号 CAS）？
+- 是进程间信号量？
+
+在 Windows 平台（当前开发环境为 Windows 11）上，`flock` 语义与 Unix 不同，Node.js 的文件锁行为存在已知差异。PRD 完全没有提及跨平台兼容性。
+
+### [MEDIUM] Skill 决策树的歧义输入处理
+
+AC-02 要求新用户 5 分钟内选出正确 skill，但决策树（图 4.1）没有覆盖：
+
+- 用户输入同时匹配多个 skill 触发词时的优先级
+- 用户输入不匹配任何分支时的 fallback 路径
+- `autopilot` 和 `ultrapilot` 互斥规则在决策树中没有体现
+
+
+---
+
+## 3. Logical Consistency（逻辑一致性）
+
+### [CRITICAL] PRD 是"规范的规范"，但没有规范内容
+
+这是最根本的逻辑问题。PRD 的交付物是"规范文档"，但 PRD 本身只定义了规范文档的名称和存放路径，没有定义规范的实质内容。
+
+以 P0-2"状态文件读写规范"为例，PRD 只说"明确读写锁策略，禁止并发写入"，但没有回答：
+
+- 用什么锁机制？（文件锁 / 内存锁 / 数据库事务）
+- 锁的粒度是什么？（文件级 / 字段级）
+- 锁超时时间是多少？
+- 死锁检测和解除策略是什么？
+
+这意味着实现者拿到这份 PRD 后，仍然需要自行设计所有关键决策。PRD 没有减少任何歧义。
+
+### [HIGH] 验收标准 AC-01 与 AC-04 存在重叠且均不可验证
+
+AC-01："并发场景有明确处理指引" — 验证方法是"检查 P0 规范是否覆盖并行 agent 写同一状态文件的场景"。
+
+AC-04："三类 BUG 来源均有对应规范" — 验证方法是"逐一映射：运行时 BUG → P0"。
+
+两者都在验证"P0 规范是否存在"，而不是验证"P0 规范是否有效"。一份只写了"禁止并发写入"四个字的文档也能通过这两个 AC。这不是验收标准，是存在性检查。
+
+### [HIGH] AC-02 的测量方法不可重复执行
+
+"新用户 5 分钟内选出正确 skill，准确率 ≥ 80%"需要用户测试。但 PRD 没有定义：
+
+- "新用户"的定义（完全没用过 ultrapower？还是没用过 v5.x？）
+- "正确 skill"由谁判定？（存在主观性）
+- 3 个典型场景是哪 3 个？（不同场景难度差异极大）
+- 测试在什么环境下进行？（有无文档辅助？）
+
+这个 AC 在当前形式下无法被客观验证，也无法被重复执行。
+
+### [HIGH] P0 与 P2 存在实现顺序矛盾
+
+P0 要求制定"Hook 执行顺序规范"，P2 才要求制定"Hook 标准模板"。
+
+但实际上，如果没有标准模板，就无法判断现有 35 个 hook 是否符合规范；如果现有 hook 不符合规范，P0 的规范就是在描述一个不存在的理想状态。
+
+正确的顺序应该是：先审计现有实现 → 提炼规范 → 制定模板。PRD 跳过了"审计现有实现"这一步。
+
+### [MEDIUM] 非功能需求"向后兼容"与 P0 目标存在潜在冲突
+
+非功能需求要求"P0/P1 规范不得破坏现有 v5.0.x 用户的使用习惯"。
+
+但 P0 的目标是修复已知的并发 BUG（2026-02-12 Race Condition）。修复并发 BUG 通常意味着改变状态文件的读写行为，这可能改变现有用户依赖的时序。
+
+PRD 没有分析这两个目标之间的张力，也没有提供解决方案。
+
+### [MEDIUM] "三类 BUG 来源"与 MVP 范围的映射不完整
+
+背景章节定义了三类问题：运行时 BUG、使用混乱、贡献无序。但 P0 只覆盖了"运行时 BUG"中的三个子项，没有说明是否已穷举所有运行时 BUG 来源。
+
+实际上，从 hooks 目录结构来看，还存在以下未被 P0 覆盖的运行时风险：
+
+- `recovery` hook：崩溃恢复逻辑的规范缺失
+- `pre-compact` / `preemptive-compaction`：上下文压缩时序的规范缺失
+- `subagent-tracker`：子 agent 追踪状态的一致性规范缺失
+
+---
+
+## 4. 范围蔓延风险（Scope Creep Analysis）
+
+### [HIGH] P2 模板工作量被严重低估
+
+P2 要求制定 Skill、Agent、Hook 三类标准模板。但当前系统规模是：
+
+- 49 个 agent
+- 35 个 hook
+- 20+ 个 skill
+
+制定模板需要先对现有实现进行全面审计，提炼共性，识别差异，处理例外情况。这不是"写几个模板文件"的工作量，而是一次系统性的架构梳理。PRD 将其列为 P2（可选），但实际上它是 P0 规范能否落地的前提条件。
+
+### [MEDIUM] "贡献检查清单"隐含了 CI 工具链需求
+
+P2-10 要求"新增任何组件前必须通过的 checklist（含测试要求和版本兼容性验证）"。
+
+但如果 checklist 只是一份 Markdown 文档，没有自动化执行，它的实际效果接近于零（人工检查清单在工程实践中的遵守率极低）。
+
+PRD 在第 7 节明确将"自动化规范检查工具"和"规范合规性 CI 检查"列为 v2 延期项。这意味着 v1 的 checklist 是一份没有执行保障的文档，其价值存疑。
+
+---
+
+## 5. 缺失的关键内容
+
+以下内容在 PRD 中完全缺失，但对于一个规范体系 PRD 是必须的：
+
+| 缺失项 | 影响 |
+| --- | --- |
+| 规范的版本控制策略 | 规范本身如何演进？旧版规范如何废弃？ |
+| 规范冲突解决机制 | 当 P0 规范与 P1 规范产生矛盾时，谁优先？ |
+| 规范的强制执行机制 | 没有工具链保障的规范是建议，不是规范 |
+| 现有违规的处理策略 | 35 个 hook 中有多少不符合待制定的规范？如何处理？ |
+| 规范的受众定义 | 规范是给 AI agent 读的还是给人类开发者读的？两者格式要求完全不同 |
+| Windows 平台特殊处理 | 当前开发环境是 Windows 11，文件锁、路径分隔符等行为与 Unix 不同 |
+
+---
+
+## Conclusion（结论）
+
+**判定: Reject**
+
+### Major Blockers（严重阻碍）
+
+1. **PRD 没有定义规范内容，只定义了规范的名称** — 实现者无法从这份 PRD 推导出任何具体的规范条目。必须在 PRD 中至少给出每个规范文档的核心条目草稿。
+
+2. **状态文件安全边界完全缺失** — 路径遍历风险、敏感数据明文存储、hook 命令注入面均未被识别，规范体系不能在安全问题上留白。
+
+3. **验收标准不可验证** — AC-01 和 AC-04 是存在性检查而非质量检查；AC-02 缺乏可重复执行的测量方法。必须重写所有 AC，使其具备明确的通过/失败判定条件。
+
+4. **Agent 生命周期状态机存在死状态** — `ERROR` 状态没有强制退出路径，`WAITING` 状态没有超时，这是会在生产环境中触发的设计缺陷，不能进入实现。
+
+5. **跨平台兼容性（Windows）完全未考虑** — 文件锁策略在 Windows 上的行为与 Unix 不同，这是当前开发环境的直接风险，必须在 P0 规范中明确处理。
+
+### 修复建议（按优先级）
+
+1. 为每个 P0 规范条目补充至少 3 条具体规则草稿（不是描述，是可执行的规则）
+2. 重写 AC-01/AC-04 为可量化的质量指标（如：规范覆盖已知 BUG 列表中 N 个场景）
+3. 在 P0 中增加"安全边界"章节，覆盖路径校验和 hook 输入消毒
+4. 修复状态机死状态，为 `ERROR` 和 `WAITING` 增加超时强制转换
+5. 在非功能需求中增加 Windows 平台兼容性要求，并在 P0 锁策略中给出跨平台方案

package/docs/reviews/ultrapower-standards/review_domain.md

@@ -0,0 +1,243 @@
+# Domain Expert Review: ultrapower 全链路规范体系
+
+> 评审人：Domain Expert (领域专家)
+> 评审日期：2026-02-26
+> PRD 版本：Draft v1
+> 项目版本：ultrapower v5.0.21
+> 评审依据：基于实际源码分析（src/hooks/、src/agents/、src/lib/）
+
+---
+
+## 总体评分：6 / 10
+
+PRD 方向正确，但对实际运行时行为的描述存在多处与代码不符的情况，且遗漏了若干已在代码中存在的关键复杂性。规范若基于这份 PRD 编写，将产生"规范与实现不一致"的新问题。
+
+---
+
+## 1. Logic Validation (逻辑验证)
+
+### 1.1 Hook 执行顺序规范
+
+**状态：Adjustment Needed（需要调整）**
+
+PRD 将 Hook 分为 PreToolUse / PostToolUse / Stop 三类，但实际代码中的 Hook 类型远不止三类。
+
+根据 `src/hooks/bridge.ts` 中的 `HookType` 定义，实际存在以下类型：
+
+```typescript
+type HookType =
+  | "keyword-detector"      // UserPromptSubmit 阶段
+  | "stop-continuation"     // Stop 阶段（已简化为软执行）
+  | "ralph"                 // Stop 阶段（ralph 循环）
+  | "persistent-mode"       // Stop 阶段（统一持久化模式）
+  | "session-start"
+  | "session-end"
+  | "pre-tool-use"
+  | "post-tool-use"
+  | "autopilot"
+  | "subagent-start"        // SubagentStart 事件
+  | "subagent-stop"         // SubagentStop 事件
+  | "pre-compact"
+  | "setup-init"
+  | "setup-maintenance"
+  | "permission-request"
+```
+
+PRD 的三分类遗漏了：SubagentStart/Stop、PreCompact、PermissionRequest、SessionEnd 等关键 hook 类型。这些 hook 在实际运行时承担了重要职责（agent 生命周期追踪、权限自动审批、压缩前状态保存）。
+
+**关键发现**：Stop 阶段实际上有三个独立 hook 竞争处理权，优先级为：
+`Ralph > Ultrawork > Todo-Continuation`（见 `src/hooks/persistent-mode/index.ts` 第 11 行注释）。这个优先级规则是规范中必须明确的核心内容，PRD 完全未提及。
+
+### 1.2 状态文件读写规范（并发保护）
+
+**状态：Partially Pass（部分通过）**
+
+PRD 提到"并发保护"，实际代码中已有实现，但实现细节比 PRD 描述的更复杂，规范需要准确反映这些细节。
+
+已实现的并发保护机制（`src/lib/atomic-write.ts`）：
+- 使用 `temp file + atomic rename` 模式（`wx` 标志确保独占创建）
+- 写入前 `fsync` 确保数据落盘
+- rename 后尝试目录级 `fsync`（Windows 上可能失败，代码已处理）
+- 同步版本（`atomicWriteJsonSync`）和异步版本（`atomicWriteJson`）均已实现
+
+**已知问题的根因**（Race Condition，2026-02-12）：
+subagent-tracker 的并发写入问题实际上已有专门的缓解机制（`src/hooks/subagent-tracker/index.ts`）：
+- `pendingWrites` Map 实现写入防抖（100ms debounce）
+- `flushInProgress` Set 防止重复并发 flush
+- `mergeTrackerStates` 函数实现确定性状态合并（Math.max 计数器 + 时间戳仲裁）
+
+但规范中需要明确：**这套机制只保护 subagent-tracking.json，其他状态文件（team-state.json、ralph-state.json 等）使用的是 atomicWriteJsonSync，没有 debounce 层**。这是一个不一致性，规范应该统一说明各类状态文件的保护级别差异。
+
+### 1.3 Agent 生命周期规范
+
+**状态：Adjustment Needed（需要调整）**
+
+PRD 描述的 `spawn → shutdown` 状态机过于简化。实际代码中 agent 生命周期有以下状态：
+
+```
+running → completed | failed
+```
+
+但 `SubagentStopInput` 接口中有一个重要注释（`src/hooks/subagent-tracker/index.ts` 第 102 行）：
+
+```typescript
+/** @deprecated The SDK does not provide a success field. Use inferred status instead. */
+success?: boolean;
+```
+
+这意味着：**Claude Code SDK 不提供 agent 是否成功完成的直接信号**，当前实现依赖推断（inferred status）。规范必须明确这个限制，否则基于规范的实现者会假设可以直接读取成功/失败状态。
+
+**遗漏的边界情况**：
+1. Agent 超时（stale threshold = 5分钟，`STALE_THRESHOLD_MS = 5 * 60 * 1000`）
+2. Agent 孤儿状态（父 session 结束但 agent 仍在运行）
+3. Agent 成本超限（`COST_LIMIT_USD = 1.0`）触发的强制终止
+4. 死锁检测（`DEADLOCK_CHECK_THRESHOLD = 3`）
+
+这四种边界情况在代码中均有处理逻辑，但 PRD 的生命周期规范完全未覆盖。
+
+### 1.4 Team Pipeline 状态机
+
+**状态：Pass（通过，但需补充）**
+
+Team Pipeline 的状态转换在代码中有严格的 ALLOWED 矩阵（`src/hooks/team-pipeline/transitions.ts`）：
+
+```typescript
+const ALLOWED: Record<TeamPipelinePhase, TeamPipelinePhase[]> = {
+  'team-plan': ['team-prd'],
+  'team-prd': ['team-exec'],
+  'team-exec': ['team-verify'],
+  'team-verify': ['team-fix', 'complete', 'failed'],
+  'team-fix': ['team-exec', 'team-verify', 'complete', 'failed'],
+  complete: [],
+  failed: [],
+  cancelled: ['team-plan', 'team-exec'],  // 恢复路径
+};
+```
+
+PRD 的 CLAUDE.md 描述与此基本一致，但遗漏了一个关键约束：`team-exec` 阶段进入需要 `plan_path` 或 `prd_path` artifact 存在，`team-verify` 阶段进入需要 `tasks_completed >= tasks_total`。这些前置条件是规范的核心内容。
+
+---
+
+## 2. Industry Standard Check (标准合规)
+
+### 2.1 并发控制模式
+
+**状态：Compliant（符合）**
+
+`atomic rename` 模式是文件系统并发控制的行业标准做法（参考 SQLite WAL、Redis AOF 等）。代码实现符合最佳实践：独占创建临时文件 → fsync → rename。
+
+**但存在一个 Windows 特定问题**：Windows 上 `fs.rename` 使用 `MoveFileExW with MOVEFILE_REPLACE_EXISTING`，在目标文件被其他进程持有时会失败（不同于 POSIX 的原子替换语义）。代码注释中提到了这一点，但规范应该明确说明 Windows 平台的行为差异。
+
+### 2.2 Hook 架构模式
+
+**状态：Non-standard（非标准，但合理）**
+
+PRD 描述的 Hook 系统是 ultrapower 特有的架构，不对应任何通用行业标准。这本身没有问题，但规范需要清晰定义：
+
+- Hook 的输入/输出契约（`HookInput` / `HookOutput` 接口）
+- Hook 的执行超时保证（当前代码未见明确超时限制）
+- Hook 失败时的降级行为（当前实现：大多数 hook 失败时返回 `{ continue: true }`，即静默降级）
+
+**静默降级是一个重要的领域决策**，规范应该明确这是设计选择而非疏漏，并说明其理由（hook 不应阻塞用户工作流）。
+
+### 2.3 Agent 路由决策
+
+**状态：Adjustment Needed（需要调整）**
+
+PRD 的 P1 提到"Skill 调用决策树（skill vs agent vs MCP 三者选择）"，但实际代码中还存在第四个选择路径：**直接处理（orchestrator 自身处理，不委派）**。
+
+`src/hooks/omc-orchestrator/index.ts` 中的 enforcement 机制正是为了防止 orchestrator 绕过委派直接修改文件。规范的决策树必须包含这个维度，否则会产生"什么时候 orchestrator 可以直接处理"的歧义。
+
+---
+
+## 3. Value Proposition (价值主张)
+
+### 3.1 框架维护者
+
+**收益分析**：P0 规范（Hook 执行顺序、状态文件读写）直接降低维护成本。当前代码中存在多处"同一问题的不同解法"（例如：subagent-tracker 有 debounce 层，而 team-state 没有），规范化后可以统一实现模式，减少未来的 race condition 类 bug。
+
+**风险**：如果规范基于 PRD 的不完整描述编写，可能固化错误的理解，反而增加维护成本。
+
+### 3.2 框架使用者（终端用户）
+
+**收益分析**：P1 规范（Skill 调用决策树）是用户最直接的痛点。当前 70 个 skills 的选择对新用户来说是认知负担。决策树如果设计得当，可以将"选择正确 skill"的时间从分钟级降到秒级。
+
+**关键缺口**：PRD 没有说明决策树的呈现形式。是 CLAUDE.md 中的文字描述？还是交互式 `/help` 命令？还是 HUD 中的实时提示？不同呈现形式的用户价值差异巨大。
+
+### 3.3 框架贡献者
+
+**收益分析**：P2 规范（标准模板 + 检查清单）降低贡献门槛。当前 agents/ 目录下的 .md 文件格式不统一（部分有 YAML frontmatter，部分没有），模板化后可以提升一致性。
+
+---
+
+## 4. 关键领域缺陷（Critical Domain Gaps）
+
+### Gap 1：Hook 类型分类不完整（高优先级）
+
+PRD 的三分类（PreToolUse/PostToolUse/Stop）遗漏了 SubagentStart/Stop、PreCompact、PermissionRequest、SessionEnd 等 8 个 hook 类型。规范若基于此编写，将产生覆盖盲区。
+
+**建议**：以 `src/hooks/bridge.ts` 中的 `HookType` 定义为权威来源，规范必须覆盖所有 15 个 hook 类型。
+
+### Gap 2：Stop Hook 优先级规则未定义（高优先级）
+
+Stop 阶段有三个 hook 竞争（Ralph > Ultrawork > Todo-Continuation），这个优先级规则是运行时行为的核心，但 PRD 完全未提及。
+
+**建议**：在 Hook 执行顺序规范中明确 Stop 阶段的优先级链，并说明每个 hook 的触发条件和退出条件。
+
+### Gap 3：SDK 限制未纳入规范（中优先级）
+
+Claude Code SDK 不提供 agent 成功/失败的直接信号（`success` 字段已废弃），当前实现依赖推断。规范必须明确这个平台限制，否则基于规范的实现者会产生错误假设。
+
+**建议**：在 Agent 生命周期规范中增加"平台限制"章节，说明哪些状态是 SDK 直接提供的，哪些是推断的。
+
+### Gap 4：Windows 平台原子写入语义差异（中优先级）
+
+Windows 上 `rename` 不是真正的原子操作（目标文件被持有时会失败），这与 POSIX 语义不同。当前代码有注释说明，但规范应该将此作为已知平台差异明确记录。
+
+**建议**：在状态文件读写规范中增加"平台差异"章节，说明 Windows 和 POSIX 的行为差异及其影响。
+
+### Gap 5：Agent 边界情况覆盖不足（中优先级）
+
+超时、孤儿、成本超限、死锁四种边界情况在代码中均有处理，但 PRD 的生命周期规范未覆盖。
+
+**建议**：Agent 生命周期规范应包含完整的异常状态处理矩阵，对应 `src/hooks/subagent-tracker/index.ts` 中的 `AgentIntervention` 类型定义。
+
+### Gap 6：Orchestrator 直接处理路径缺失（低优先级）
+
+决策树缺少"orchestrator 直接处理"这个选项，导致规范不完整。
+
+**建议**：在 Skill 调用决策树中增加第四个分支：直接处理（适用于简单澄清、快速状态检查等场景），并明确其适用边界。
+
+---
+
+## Conclusion (结论)
+
+**Modification Required（需要修改后才能进入实现阶段）**
+
+### 评分明细
+
+| 维度 | 得分 | 说明 |
+|------|------|------|
+| 技术规范完整性 | 5/10 | Hook 类型分类不完整，遗漏 8 个类型 |
+| Hook 时序设计准确性 | 6/10 | Stop 阶段优先级规则缺失，是核心遗漏 |
+| 状态文件并发保护方案 | 7/10 | 原子写入方案可行，但各状态文件保护级别不一致未说明 |
+| Agent 生命周期覆盖 | 5/10 | 遗漏 4 种边界情况，SDK 限制未说明 |
+| 领域特定遗漏 | 6/10 | Windows 平台差异、orchestrator 直接处理路径未覆盖 |
+| **综合** | **6/10** | |
+
+### 必须修复的问题（进入实现前）
+
+1. 以 `src/hooks/bridge.ts` 的 `HookType` 为权威来源，补全 Hook 类型分类（15 个类型，而非 3 个）
+2. 明确 Stop 阶段的 hook 优先级链：Ralph > Ultrawork > Todo-Continuation
+3. 在 Agent 生命周期规范中说明 SDK 不提供 `success` 字段的平台限制
+4. 补充 Agent 边界情况矩阵（超时/孤儿/成本超限/死锁）
+
+### 建议修复的问题（可在迭代中处理）
+
+5. 说明各状态文件的并发保护级别差异（subagent-tracker 有 debounce，其他没有）
+6. 在决策树中增加"orchestrator 直接处理"分支
+7. 记录 Windows 平台的 rename 语义差异
+
+### 与 Product Review 的交叉验证
+
+Product Review（评分 7/10）指出"P1 的 ROI 实际高于 P0"，从领域视角看这个判断是正确的。但需要补充：P0 的 Hook 执行顺序规范如果不准确，会直接导致 P1 的决策树建立在错误的基础上。两者需要同步推进，而非 P1 优先于 P0。

package/docs/reviews/ultrapower-standards/review_product.md

@@ -0,0 +1,102 @@
+# Product Strategy Review: ultrapower 全链路规范体系
+
+> 评审人：Product Director
+> 评审日期：2026-02-26
+> PRD 版本：Draft v1
+> 项目版本：ultrapower v5.0.21
+
+---
+
+## 总体评分：7 / 10
+
+战略方向正确，规范体系是框架成熟化的必经之路。但 MVP 边界模糊、指标可验证性存疑、部分优先级排序需要调整。
+
+---
+
+## 1. Strategic Fit (战略匹配: High)
+
+- Alignment: ultrapower 已迭代至 v5.0.21，拥有 49 个 agents、70 个 skills、35 个 hooks，系统复杂度已到达"规范真空"临界点。从 CHANGELOG 可见，v5.0.9~v5.0.14 的主要工作都是修复文档不一致、数量对不上、缓存嵌套等"规范缺失"导致的问题。这份 PRD 的战略时机是对的——不是超前，而是已经有点滞后。
+
+- Differentiation: 规范体系本身不是差异化来源，但它是差异化能力（多 agent 编排）能被用户稳定使用的前提。没有规范，用户无法信任框架，贡献者无法安全扩展。
+
+- Roadmap Fit: 与 Q1/Q2 目标高度契合。框架已从"能用"阶段进入"可靠用"阶段，规范体系是这个跃迁的基础设施。
+
+---
+
+## 2. Prioritization Matrix (优先级矩阵)
+
+| 维度 | P0 运行时防护 | P1 用户使用规范 | P2 开发贡献规范 |
+|------|-------------|--------------|--------------|
+| Impact | 5 | 4 | 3 |
+| Effort | 3 | 2 | 2 |
+| Score | 1.67 | 2.00 | 1.50 |
+
+**关键发现：P1 的 ROI 实际高于 P0。**
+
+P0（Hook执行顺序、状态文件读写、Agent生命周期）是内部运行时规范，主要受益者是框架维护者。P1（Skill调用决策树、Agent路由规范）直接影响用户每次使用体验，且 ultrapower 的核心用户痛点恰恰是"不知道该用哪个 skill/agent"。
+
+建议调整：P1 的 Skill 调用决策树应与 P0 并行推进，而非排在其后。
+
+---
+
+## 3. Success Metrics (成功指标评估)
+
+| 指标 | 可量化性 | 问题 |
+|------|---------|------|
+| 并发场景覆盖率 100% | 中 | "并发场景"边界未定义，谁来认定"覆盖"？ |
+| 新用户选出正确 skill ≤ 5分钟 | 高 | 需要用户测试数据，当前无基线，无法验证改善 |
+| 新增 skill 检查清单覆盖 100% | 高 | 可通过 CI 门禁自动验证，这是最强的指标 |
+| 三类 BUG 来源全覆盖 | 低 | "三类 BUG 来源"未在 PRD 中定义，指标悬空 |
+
+**最强指标**：新增 skill 检查清单 100% 覆盖——可自动化验证，建议作为 Primary KPI。
+
+**最弱指标**：三类 BUG 来源全覆盖——需要先定义这三类是什么，否则无法验证。
+
+- Primary KPI: 新增 skill/agent/hook 的检查清单覆盖率（目标 100%，可 CI 验证）
+- Secondary KPI: 用户首次选出正确 skill 的时间（需建立基线测量）
+
+---
+
+## 4. 战略遗漏分析
+
+### 遗漏 1：规范的"执行机制"缺失（高优先级）
+PRD 定义了规范内容，但没有说明规范如何被执行。文档规范如果没有 CI 门禁或 lint 规则支撑，会退化为"参考文档"而非"约束机制"。建议明确：哪些规范通过自动化工具强制执行，哪些依赖人工审查。
+
+### 遗漏 2：规范的版本化策略缺失（中优先级）
+ultrapower 迭代速度快（v5.0.9 到 v5.0.21 在短期内完成），规范文档如何随版本演进？没有版本化策略，规范会很快过时，反而增加混乱。
+
+### 遗漏 3：现有反模式的来源分析缺失（中优先级）
+PRD 提到"三类 BUG 来源有对应规范"，但没有基于真实 issue/bug 数据来定义这三类。从 CHANGELOG 看，实际高频问题是：缓存嵌套、文档数量不一致、plugin 发布失败。规范应从真实痛点反推，而非自上而下设计。
+
+### 遗漏 4：用户分层缺失（低优先级）
+P1 和 P2 面向不同用户群（终端用户 vs 贡献者），但 PRD 没有区分这两类用户的使用场景和需求差异，导致规范设计可能混淆受众。
+
+---
+
+## 5. MVP 范围评估
+
+**当前 MVP 范围：偏大。**
+
+三个优先级（P0/P1/P2）同时在 MVP 中，实际上是三个独立的产品交付物。真正的 MVP 应该是：
+
+**建议 MVP（最小可验证版本）：**
+- Skill 调用决策树（P1）——直接解决用户最高频痛点
+- 新增 skill 标准模板 + 检查清单（P2 子集）——可立即通过 CI 验证，形成闭环
+
+P0 的运行时规范（Hook执行顺序、状态文件读写）更适合作为内部技术文档，不需要作为用户可见的产品功能交付。
+
+---
+
+## Conclusion (结论)
+
+**P1 - Should Have**（当前定级，建议调整部分范围后升为 P0）
+
+**核心建议：**
+
+1. 将 Skill 调用决策树从 P1 提升，与 P0 并行交付——这是用户最直接的痛点。
+2. 缩小 MVP 范围：先交付"决策树 + 检查清单"，用 CI 验证覆盖率，形成可量化的第一个里程碑。
+3. 补充规范执行机制：明确哪些规范通过自动化强制，哪些通过 review 流程保障。
+4. 定义"三类 BUG 来源"：从 CHANGELOG 和 issue 历史中归纳，而非假设。
+5. 加入规范版本化策略：与 npm 版本号绑定，确保规范不会滞后于代码。
+
+**战略背景备注：** ultrapower 正处于从"个人工具"向"可信赖框架"演进的关键节点。规范体系是这个演进的基础设施投资，战略价值明确。但投资回报的前提是规范能被执行，而非仅被记录。