@liangjie559567/ultrapower 5.0.21 → 5.0.23

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

@@ -0,0 +1,142 @@
+# Tech Feasibility Review: ultrapower 全链路规范体系
+
+**评审日期**: 2026-02-26
+**评审人**: Tech Lead
+**PRD 版本**: Draft v1
+**项目版本**: ultrapower v5.0.21
+
+---
+
+## 1. Architecture Impact (架构影响)
+
+- Schema Changes: No（纯文档工程，不涉及数据模型变更）
+- API Changes: No（不修改任何运行时接口）
+- Runtime Impact: No（仅新增 docs/ 文件，修改 README.md 和 CLAUDE.md）
+- Build Pipeline Impact: No（无需修改 tsconfig.json、vitest.config.ts）
+
+**关键发现**：本 PRD 的 Impact Scope 定义为"纯文档工程"，但存在一个隐性架构影响被忽略——CLAUDE.md 的修改会直接影响所有 agent 的运行时行为（CLAUDE.md 在每次会话启动时被注入为系统上下文）。这不是普通文档修改，属于**运行时配置变更**，需要单独的回归测试策略。
+
+---
+
+## 2. Risk Assessment (风险评估)
+
+- Complexity Score (1-10): **3**
+- POC Required: No
+- Regression Risk: Medium（CLAUDE.md 修改影响 agent 行为）
+- Consistency Risk: High（规范文档与现有代码实现存在潜在不一致）
+
+### 风险明细
+
+**R1 - 规范与实现不一致（High）**
+代码库中已存在大量隐式规范（如 `bridge-normalize.ts` 中的 hook 字段白名单、`mode-registry/index.ts` 中的状态文件路径约定）。若文档规范与现有实现描述不符，会造成贡献者困惑。必须以代码为准反向提取规范，而非凭空撰写。
+
+**R2 - CLAUDE.md 修改的运行时副作用（Medium）**
+CLAUDE.md 在每次 Claude Code 会话启动时被注入。对其修改（如新增 Axiom 门禁规则、调整路由表）会立即影响所有 agent 的决策逻辑，无法通过单元测试覆盖，只能通过集成测试验证。PRD 未提及此风险。
+
+**R3 - Impact Scope 遗漏（Medium）**
+见第 3 节详述。
+
+**R4 - 并发写入规范的可执行性（Low）**
+PRD P0 提到"禁止并发写入同一状态文件"，但 `mode-registry/index.ts` 中已有 `STALE_MARKER_THRESHOLD` 机制处理崩溃场景，并未使用文件锁。规范文档需要明确：这是"应该"还是"必须"，以及违反时的降级策略。
+
+---
+
+---
+
+## 3. Impact Scope 完整性分析
+
+### PRD 已列出文件（合理）
+
+| 文件 | 评估 |
+|------|------|
+| `docs/standards/runtime-protection.md` | 合理，对应 P0 Hook/状态规范 |
+| `docs/standards/user-guide.md` | 合理，对应 P1 决策树/路由规范 |
+| `docs/standards/contribution-guide.md` | 合理，对应 P2 贡献检查清单 |
+| `docs/standards/templates/skill-template.md` | 合理，对应 P2 模板 |
+| `docs/standards/templates/agent-template.md` | 合理，对应 P2 模板 |
+| `docs/standards/templates/hook-template.md` | 合理，对应 P2 模板 |
+| `README.md` | 合理，需更新指向新规范 |
+| `CLAUDE.md` | 高风险，见 R2 |
+
+### 遗漏文件（建议补充）
+
+**遗漏 1 - `docs/standards/state-machine.md`（P0 级别）**
+`src/hooks/mode-registry/index.ts` 中定义了完整的状态机（autopilot/ultrapilot/swarm/pipeline/team/ralph/ultrawork/ultraqa），包含状态转换规则、stale marker 阈值（1小时）、互斥模式检测。这是运行时保护规范的核心，必须有独立文档。
+
+**遗漏 2 - `docs/standards/hook-execution-order.md`（P0 级别）**
+PRD 提到"Hook执行顺序规范"，但未在 Impact Scope 中列出对应文件。`hooks/` 目录下存在 `session-start.sh`、`run-hook.cmd`，`src/hooks/` 下有 `bridge.ts`、`bridge-normalize.ts`、`guards/`、`keyword-detector/` 等多个 hook 类型。执行顺序规范应独立成文，而非合并进 `runtime-protection.md`。
+
+**遗漏 3 - `docs/standards/agent-lifecycle.md`（P0 级别）**
+PRD P0 包含"Agent生命周期规范"，但 Impact Scope 中没有对应文件。`src/agents/definitions.ts` 中已有 AgentConfig 类型定义，生命周期规范（创建/路由/执行/销毁）需要独立文档。
+
+**遗漏 4 - `docs/standards/anti-patterns.md`（P1 级别）**
+PRD P1 包含"常见反模式清单"，但 Impact Scope 中未列出对应文件。建议独立成文，而非合并进 `user-guide.md`，便于后续维护和搜索。
+
+**遗漏 5 - `docs/standards/README.md`（P2 级别）**
+新增 `docs/standards/` 目录后，需要一个索引文件说明各规范文档的用途和阅读顺序，否则贡献者无法快速定位。
+
+---
+
+## 4. Implementation Plan (大致实现计划)
+
+### 阶段一：规范提取（3-4天）
+
+从现有代码反向提取规范，确保文档与实现一致：
+
+- 从 `src/hooks/bridge-normalize.ts` 提取 Hook 字段白名单规范
+- 从 `src/hooks/mode-registry/index.ts` 提取状态机转换规则和 stale marker 阈值
+- 从 `src/agents/definitions.ts` 提取 Agent 生命周期规范
+- 从 `src/hooks/guards/pre-tool.ts`、`post-tool.ts` 提取 Hook 执行顺序
+
+撰写文件：`runtime-protection.md`、`hook-execution-order.md`、`state-machine.md`、`agent-lifecycle.md`
+
+### 阶段二：规范扩展（2-3天）
+
+- 撰写 `user-guide.md`（Skill 调用决策树 + Agent 路由规范）
+- 撰写 `anti-patterns.md`（常见反模式清单）
+- 撰写 `contribution-guide.md`（贡献检查清单）
+- 撰写 3 个模板文件（skill/agent/hook）
+- 撰写 `docs/standards/README.md`（目录索引）
+
+### 阶段三：集成与验证（1天）
+
+- 更新 `README.md` 指向新规范
+- 审慎修改 `CLAUDE.md`（仅追加，不删除现有规则）
+- 人工验证：用新模板创建一个 demo skill，确认模板可用
+
+---
+
+## 5. 技术债务预规划
+
+**TD-1：规范与代码的同步机制（中期）**
+当前无机制保证文档规范与代码实现同步。建议在 CI 中加入检查，验证 `mode-registry/index.ts` 中的状态文件路径是否与 `state-machine.md` 描述一致。否则规范文档会随版本迭代快速过时。
+
+**TD-2：CLAUDE.md 版本管理（短期）**
+CLAUDE.md 目前通过 `<!-- OMC:VERSION:5.0.21 -->` 标记版本，但没有 changelog。修改前需建立变更记录机制，避免 agent 行为回归无法追溯。
+
+**TD-3：模板的可测试性（中期）**
+P2 的 skill/agent/hook 模板目前只是 Markdown 文档。建议后续将模板转为可执行的脚手架脚本，降低贡献者使用门槛，同时可通过 CI 验证模板生成的文件是否符合规范。
+
+**TD-4：并发写入保护的实现层缺失（短期）**
+P0 规范"禁止并发写入同一状态文件"目前仅靠约定，`mode-registry` 使用同步 `writeFileSync`，在 Team 模式多 worker 场景存在竞态条件。规范文档应明确推荐原子写入（write-to-temp + rename）模式，并在 `src/lib/` 中提供工具函数，确保规范与实现同步落地。
+
+---
+
+## Conclusion (结论)
+
+- **结论**: Pass（条件通过）
+- **Estimated Effort**: 6-8 天（1 名工程师）
+- **综合评分**: 7/10
+
+**通过理由**：技术可行性高，纯文档工程，无运行时风险，团队具备完整技术栈。
+
+**通过条件**：
+1. Impact Scope 补充遗漏的 5 个文件（`state-machine.md`、`hook-execution-order.md`、`agent-lifecycle.md`、`anti-patterns.md`、`docs/standards/README.md`）
+2. CLAUDE.md 修改需单独制定回归验证方案
+3. 规范内容必须从现有代码反向提取，禁止凭空撰写
+4. TD-4（并发写入原子性）建议在本次迭代中一并解决，避免规范与实现脱节
+
+**扣分项（-3分）**：
+- Impact Scope 遗漏 5 个关键文件（-1.5）
+- 未识别 CLAUDE.md 的运行时影响（-1）
+- 未规划规范与代码的同步机制（-0.5）

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

@@ -0,0 +1,110 @@
+# UX Review: ultrapower 全链路规范体系 PRD
+
+> 评审人：UX Director
+> 评审日期：2026-02-26
+> PRD 版本：Draft v1
+> 产品版本：ultrapower v5.0.21
+
+---
+
+## 1. Flow Analysis (流程分析)
+
+### 用户旅程识别
+
+本 PRD 涉及三类核心用户，其旅程差异显著：
+
+| 用户类型 | 核心目标 | 当前 PRD 覆盖 |
+|---------|---------|-------------|
+| 新用户（首次使用） | 5 分钟内选出正确 skill | AC-02 有提及，但路径未设计 |
+| 日常使用者 | 快速决策、避免反模式 | P1 有规划，细节缺失 |
+| 贡献者 | 新增 skill/agent/hook | P2 有规划，模板未定义 |
+
+### 流程问题逐项分析
+
+**Step 1 - 用户入口（发现阶段）**
+- 问题：PRD 未定义用户从哪里"进入"规范体系。是 README？是 CLAUDE.md？是 AGENTS.md？
+- 建议：明确规范体系的单一入口文档，避免用户在 49 个 agents + 70 个 skills 的海洋中迷失。
+
+**Step 2 - 决策树（选择 skill 阶段）**
+- 问题：P1 提到"Skill 调用决策树"，但 PRD 未描述决策树的维度和深度。用户面对 70 个 skills，需要几步才能收敛到正确选择？
+- 建议：决策树不超过 3 层，每层不超过 5 个分支。第一层应基于用户意图（"我想做什么"），而非系统分类（"这是什么类型的 skill"）。
+
+**Step 3 - 执行阶段（使用 skill）**
+- 问题：PRD 未涉及执行中的用户反馈机制。用户如何知道 skill 正在运行？如何知道出错了？
+- 建议：补充"执行状态可见性"规范，定义进度提示、错误提示的标准格式。
+
+**Step 4 - 错误恢复（出错后）**
+- 问题：AC-04 提到"三类 BUG 来源均有对应规范"，但未说明用户视角的错误恢复路径。
+- 建议：合并 Step 3 & 4，设计"错误 -> 诊断 -> 恢复"的标准流程，而非仅列出 BUG 来源。
+
+---
+
+## 2. UI/Visual Feedback (视觉反馈)
+
+### 决策树组件
+
+- 当前状态：仅在 MVP 范围中提及"Skill 调用决策树"，无任何结构定义。
+- 改进点：需要定义决策树的呈现形式。纯文本 Markdown 表格？流程图？交互式命令行提示？
+- 建议：对于 CLI 工具，决策树应以"意图关键词 -> skill 名称"的对照表形式呈现，配合示例命令。
+
+### 反模式清单组件
+
+- 当前状态：P1 列出"常见反模式清单"，但未定义格式。
+- 改进点：反模式清单如果只是文字列表，用户不会在出错时主动查阅。
+- 建议：每条反模式应包含：错误现象描述 + 根因 + 正确做法 + 示例对比（Bad vs Good）。
+
+### 状态文件规范组件（P0）
+
+- 当前状态：P0 包含"状态文件读写规范"，但未说明用户如何感知状态。
+- 改进点：状态文件是内部机制，但用户需要知道"系统现在在做什么"。
+- 建议：规范中应包含面向用户的状态可见性标准，不仅仅是技术读写规范。
+
+### 贡献检查清单组件（P2）
+
+- 当前状态：P2 提到"贡献检查清单"，格式未定义。
+- 改进点：检查清单如果条目过多，贡献者会跳过。
+- 建议：检查清单分为"必须项"（5 条以内）和"建议项"，必须项用醒目标记区分。
+
+---
+
+## 3. Usability Score (1-10)
+
+**综合评分：5 / 10**
+
+### 评分依据
+
+| 维度 | 得分 | 理由 |
+|------|------|------|
+| 效率（Efficiency） | 4/10 | AC-02"5 分钟选出正确 skill"是好目标，但 PRD 未提供实现路径。70 个 skills 无导航，5 分钟目标难以达成。 |
+| 清晰度（Clarity） | 5/10 | P0/P1/P2 分层清晰，但每层内部的用户交互点模糊。"规范"和"用户体验"之间的桥梁缺失。 |
+| 学习曲线（Learning Curve） | 5/10 | 有 Axiom 工作流路由表作为参考，但规范体系本身的入门路径未设计。新用户仍需阅读大量文档才能上手。 |
+| 视觉层级（Visual Hierarchy） | 6/10 | P0/P1/P2 优先级分层合理，但在实际文档中如何体现优先级差异未说明。 |
+| 系统反馈（Feedback） | 4/10 | 执行状态、错误提示、成功确认的规范完全缺失。这是最大的 UX 盲区。 |
+
+---
+
+## Conclusion (结论)
+
+**评审结论：Optimizable（可优化）**
+
+PRD 的优先级分层（P0/P1/P2）和验收标准（AC-01 至 AC-04）框架合理，显示出清晰的系统思维。但从用户体验角度，当前草稿更像是"技术规范目录"而非"用户体验规范"。
+
+### Top 3 亟待改进
+
+**1. 补充用户旅程地图（最高优先级）**
+PRD 缺少对三类用户（新用户、日常用户、贡献者）的完整旅程描述。AC-02"5 分钟目标"没有对应的旅程设计支撑，无法验收。建议在 PRD 中增加"用户旅程"章节，为每类用户定义：入口 -> 决策点 -> 执行 -> 反馈 -> 退出的完整路径。
+
+**2. 定义系统反馈标准（高优先级）**
+当前 PRD 完全未涉及执行中的用户反馈机制（进度、成功、错误）。对于一个编排 49 个 agents 的系统，用户在等待期间的感知体验至关重要。建议新增 AC-05：所有 skill 执行均有标准化的状态提示格式。
+
+**3. 决策树需要原型设计（中优先级）**
+"Skill 调用决策树"是 AC-02 的核心交付物，但 PRD 未定义其结构、深度和呈现形式。建议在 PRD 中附上决策树的草图或伪代码，明确：第一层分支维度是什么、最多几层、叶节点如何映射到具体 skill 名称。
+
+### 遗漏的用户痛点
+
+以下痛点在当前 PRD 中未被覆盖：
+
+- **并发冲突的用户感知**：AC-01 提到并发场景处理，但用户如何感知冲突、如何手动干预未定义。
+- **规范版本升级的迁移体验**：当规范体系从 v1 升级时，已有用户如何知道哪些内容变了？
+- **错误信息的可读性**：三类 BUG 来源有规范，但错误信息本身是否对用户友好未纳入范围。
+- **规范文档的可搜索性**：70 个 skills 的规范如果分散在多个文件，用户无法快速定位。需要统一的索引或搜索入口。

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

@@ -0,0 +1,85 @@
+# 评审摘要: ultrapower 全链路规范体系
+
+> 聚合日期：2026-02-26
+> 聚合人：axiom-review-aggregator（首席 PM）
+> 草稿版本：Draft v0.1
+> 输出：docs/prd/ultrapower-standards-rough.md
+
+---
+
+## 1. 关键决策
+
+| 冲突 | 仲裁角色 | 决策结果 |
+|------|---------|---------|
+| PRD 只定义规范名称，无实质内容 | Critic（安全/质量，最高优先级） | Rough PRD 必须为每个 P0 规范条目提供至少 3 条可执行规则草稿，不得仅列文件名 |
+| 状态文件路径遍历风险未处理 | Critic（安全边界不可协商） | 新增"安全边界"章节，要求 mode 参数白名单校验，禁止路径拼接 |
+| Agent 状态机存在死状态（ERROR 无强制退出） | Critic + Tech（技术可行性） | 状态机增加 ERROR 超时强制转换（30s）、WAITING 超时（5min）、ZOMBIE 清理状态 |
+| Hook 类型分类：PRD 写 3 类，实际代码有 15 类 | Domain（领域知识，逻辑正确性） | 以 bridge.ts 的 HookType 为权威来源，规范覆盖全部 15 个 hook 类型 |
+| Stop 阶段优先级规则缺失 | Domain（领域知识） | 明确 Stop 阶段优先级链：Ralph > Ultrawork > Todo-Continuation |
+| P1 Skill 决策树 ROI 高于 P0，应并行 | Product（战略对齐） | Skill 决策树与 P0 并行交付，不再排在 P0 之后 |
+| Impact Scope 遗漏 5 个文件 | Tech（技术可行性，硬性约束） | 补充 state-machine.md、hook-execution-order.md、agent-lifecycle.md、anti-patterns.md、standards/README.md |
+| 验收标准 AC-01/AC-04 是存在性检查而非质量检查 | Critic（质量不可协商） | 重写全部 AC，改为可量化的质量指标 |
+| 决策树无原型设计 | UX（用户体验优化） | PRD 中附决策树伪代码原型，定义 3 层结构和第一层分支维度 |
+| Windows 平台文件锁语义未处理 | Critic + Tech（安全 + 技术约束） | 非功能需求增加 Windows 平台兼容性要求，P0 锁策略给出跨平台方案 |
+| 规范无执行机制（无 CI 门禁） | Product（战略对齐） | 明确哪些规范通过自动化强制（CI），哪些通过 review 流程保障；CI 门禁列为 v1 必交付项 |
+| 跳过"审计现有实现"直接写规范 | Critic（根本性质量问题） | 新增 P0 前置任务：审计现有 35 个 hook 和 49 个 agent 实现，规范从代码反向提取 |
+
+---
+
+## 2. 范围变更
+
+### 移除
+
+- 原 P0/P1/P2 同时作为 MVP 的三层结构（范围过大）
+- 原 AC-01"并发场景有明确处理指引"（存在性检查，替换为可量化版本）
+- 原 AC-04"三类 BUG 来源均有对应规范"（与 AC-01 重叠，替换为质量指标）
+- 原状态机图（存在死状态，已重新设计）
+- 原 Hook 三分类（PreToolUse/PostToolUse/Stop）（与代码不符，已替换）
+
+### 新增
+
+- P0 前置任务：现有实现审计（35 个 hook + 49 个 agent）
+- 安全边界章节：路径遍历防护、hook 输入消毒、状态文件权限
+- 完整 Agent 状态机：含 ZOMBIE 状态、ERROR 超时、WAITING 超时、成本超限、死锁检测
+- 15 类 HookType 完整分类（来自 bridge.ts）
+- Stop 阶段优先级链规则
+- SDK 平台限制说明（success 字段已废弃）
+- Agent 边界情况矩阵（超时/孤儿/成本超限/死锁）
+- Windows 平台差异说明（rename 语义、文件锁）
+- 规范执行机制（CI 门禁策略）
+- 规范版本化策略（与 npm 版本号绑定）
+- 用户旅程地图（三类用户：新用户/日常用户/贡献者）
+- 系统反馈标准（进度/成功/错误提示格式）
+- Skill 决策树原型（3 层结构，第一层基于用户意图）
+- Impact Scope 补充 5 个遗漏文件
+- 新增 AC-05（系统反馈标准化）、AC-06（规范执行机制）
+
+### 优先级调整
+
+- Skill 调用决策树：从 P1 提升，与 P0 并行交付
+- 贡献检查清单：从 P2 提升为 P1 子集（CI 可验证，形成闭环）
+- 自动化规范检查工具：从"v2 延期"调整为"v1 CI 门禁"（无执行机制的规范无价值）
+
+---
+
+## 3. 放弃项（经仲裁明确不纳入）
+
+| 放弃项 | 放弃理由 |
+|--------|---------|
+| 英文版规范文档 | 当前用户群以中文为主，v2 延期 |
+| 视频教程/交互式引导 | 超出文档范围，v2 延期 |
+| 规范覆盖率度量仪表盘 | 超出 v1 范围 |
+| 历史 BUG 的规范回溯标注 | 工作量过大，v2 延期 |
+| 模板转为可执行脚手架脚本 | 技术债务 TD-3，v2 处理 |
+
+---
+
+## 4. 仲裁层级应用记录
+
+本次仲裁共触发 12 个冲突点，按优先级层级处理如下：
+
+- 安全（Critic）覆盖其他所有意见：路径遍历、hook 注入、状态文件权限 — 3 项
+- 技术可行性（Tech）作为硬性约束：Impact Scope 补充、Windows 兼容性、原子写入工具函数 — 3 项
+- 战略对齐（Product）调整优先级：Skill 决策树并行、CI 门禁列为 v1、MVP 范围收窄 — 3 项
+- 逻辑正确性（Domain）修正技术描述：15 类 HookType、Stop 优先级链、SDK 限制 — 3 项
+- 用户体验（UX）补充设计细节：决策树原型、用户旅程、系统反馈标准 — 纳入但不覆盖上层决策

package/docs/standards/README.md

@@ -0,0 +1,85 @@
+# ultrapower 全链路规范体系
+
+> **ultrapower-version**: 5.0.22
+> **状态**: 正式发布
+> **最后更新**: 2026-02-26
+> **真理之源**: `docs/standards/audit-report.md`
+
+ultrapower v5.0.22 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
+
+---
+
+## 快速导航
+
+| 我是... | 从这里开始 |
+|---------|-----------|
+| **新用户**（首次使用） | [用户使用指南](./user-guide.md) — 5 分钟内选出正确 skill |
+| **日常使用者**（遇到问题） | [反模式清单](./anti-patterns.md) — 10 条常见错误及修复方案 |
+| **框架贡献者** | [贡献规范](./contribution-guide.md) — 统一模板和检查清单 |
+| **框架维护者** | [运行时防护规范](./runtime-protection.md) — 并发保护和安全边界 |
+
+---
+
+## 规范文档索引
+
+### P0 — 运行时防护（必须遵守）
+
+| 文件 | 说明 | 状态 |
+|------|------|------|
+| [runtime-protection.md](./runtime-protection.md) | Hook 输入防护 + 状态文件读写规范（含安全边界） | ✅ |
+| [hook-execution-order.md](./hook-execution-order.md) | 全部 15 类 HookType 枚举、路由规则、执行顺序与优先级 | ✅ |
+| [state-machine.md](./state-machine.md) | Agent 完整状态机（含 TIMEOUT/ZOMBIE 死状态）+ Team Pipeline 转换矩阵 | ✅ |
+| [agent-lifecycle.md](./agent-lifecycle.md) | Agent 边界情况矩阵（超时/孤儿/成本超限/死锁）+ SDK 限制说明 | ✅ |
+
+### P0-并行 — 用户使用规范
+
+| 文件 | 说明 | 状态 |
+|------|------|------|
+| [user-guide.md](./user-guide.md) | Skill 决策树（3 层，5 个意图分支）+ Agent 路由指南 | ✅ |
+
+### P1 — 使用与贡献规范
+
+| 文件 | 说明 | 状态 |
+|------|------|------|
+| [anti-patterns.md](./anti-patterns.md) | 10 条反模式清单（Bad vs Good 格式，根因可追溯） | ✅ |
+| [contribution-guide.md](./contribution-guide.md) | 贡献者旅程 + 5 条必须项检查清单 + CI 门禁说明 | ✅ |
+
+### P2 — 模板与集成
+
+| 文件 | 说明 | 状态 |
+|------|------|------|
+| [templates/skill-template.md](./templates/skill-template.md) | Skill 标准模板（触发词、约束、输出格式、测试用例） | ✅ |
+| [templates/agent-template.md](./templates/agent-template.md) | Agent 标准模板（角色定义、工具权限、输入输出契约） | ✅ |
+| [templates/hook-template.md](./templates/hook-template.md) | Hook 标准模板（HookType 声明、必需字段、失败降级策略） | ✅ |
+
+### 审计报告（真理之源）
+
+| 文件 | 说明 |
+|------|------|
+| [audit-report.md](./audit-report.md) | T-01a/T-01b 现有实现审计报告 — 所有规范的真理之源，记录 9 个 PRD 与代码的差异点 |
+
+---
+
+## 安全边界（不可协商）
+
+以下三条安全规则优先级最高，任何实现不得违反：
+
+1. **路径遍历防护**：`mode` 参数必须通过 `validateMode()` 白名单校验，禁止直接拼接到文件路径。合法值：`autopilot`、`ultrapilot`、`team`、`pipeline`、`ralph`、`ultrawork`、`ultraqa`、`swarm`（共 8 个）。
+2. **Hook 输入消毒**：所有 hook 输入必须经过 `bridge-normalize.ts` 白名单过滤。敏感 hook（`permission-request`、`setup-init`、`setup-maintenance`、`session-end`）的未知字段必须被丢弃。
+3. **状态文件权限**：`agent-replay-*.jsonl` 等敏感文件权限必须为 `0o600`，且不得提交到 git（`.omc/` 已在 `.gitignore` 中）。
+
+---
+
+## 规范版本化
+
+- 规范文档在文件头部声明 `ultrapower-version: x.y.z`
+- 每次 minor 版本升级（如 v5.0.x → v5.1.0）必须更新规范 changelog
+- 废弃的规范条目标记 `@deprecated`，保留 2 个 minor 版本后删除
+
+---
+
+## 相关入口
+
+- 项目根 README：`../../README.md`
+- 编排指令：`../CLAUDE.md`
+- 任务清单：`../tasks/ultrapower-standards/manifest.md`