@liangjie559567/ultrapower 7.6.0 → 7.7.1

package/docs/reviews/bugs-pain-points-audit/tech-debt-v7.6.0-code-review.md

@@ -0,0 +1,328 @@
+# Technical Debt Fixes v7.6.0 - Code Review Report
+
+**Review Date**: 2026-03-16
+**Commit Range**: 4f413d6d..066ff55c
+**Reviewer**: Senior Code Reviewer (Opus 4.6)
+**Scope**: 56 files, 1035 insertions, 215 deletions
+
+---
+
+## Executive Summary
+
+**Recommendation**: ⚠️ **REQUEST CHANGES**
+
+The commit range under review (4f413d6d..066ff55c) contains **only documentation changes** for TD-2. The actual code implementations for TD-1, TD-3, and TD-4 were completed in **earlier commits** (55be0ceb, 0b759af7, and pre-existing). The verification report claims all fixes are complete, but this review identifies critical issues.
+
+**Files Reviewed**: 56 (34 documentation files, 21 test event files, 1 verification report)
+
+---
+
+## Critical Findings
+
+### CRITICAL-1: Misleading Verification Report
+
+**File**: `docs/reports/tech-debt-verification-2026-03-16.md`
+**Severity**: CRITICAL
+**Issue**: The verification report claims TD-4 was fixed in the reviewed commit range, but the actual fix was implemented much earlier (likely in v7.1.1 or earlier security hardening commits).
+
+**Evidence**:
+- Report claims: "TD-4: 已完成，代码库中已正确使用原子写入"
+- Actual: `src/hooks/subagent-tracker/index.ts:427` already uses `atomicWriteJsonSyncWithRetry`
+- No TD-4 implementation commit found in range 4f413d6d..066ff55c
+
+**Impact**: Creates false audit trail, misleading for future maintenance
+
+**Recommendation**: Update verification report to clarify that TD-4 was already implemented in earlier commits, not as part of this technical debt sprint.
+
+---
+
+## Issues by Technical Debt Item
+
+### TD-1: Test Timeout Configurations ✅ VERIFIED (Earlier Commit)
+
+**Status**: Implemented correctly in commit 55be0ceb (outside review range)
+
+**Files Modified**:
+- `src/features/__tests__/mcp-integration.test.ts:10`
+- `src/features/mcp-autodiscovery/__tests__/performance.test.ts:8`
+
+**Implementation Quality**: ✅ GOOD
+```typescript
+beforeAll(async () => {
+  contextManager = new UnifiedContextManager();
+  await contextManager.initialize();
+}, 30000); // Explicit 30s timeout
+```
+
+**Verification**:
+- ✅ Timeout parameter correctly added to beforeAll hooks
+- ✅ Value appropriate (30000ms for initialization)
+- ✅ Consistent across both test files
+- ✅ Follows Vitest API correctly
+
+**Issues**: None
+
+---
+
+### TD-2: LSP Documentation Migration ⚠️ INCOMPLETE
+
+**Status**: Partially implemented in commits b06f8c59 and 7ebfcfea
+
+**Files Modified**: 34 documentation files (437 line changes)
+
+**Implementation Quality**: ⚠️ NEEDS IMPROVEMENT
+
+#### HIGH-1: Inconsistent Tool Name Format
+
+**Files**: Multiple documentation files
+**Line**: Various
+**Issue**: Documentation shows tool names as `mcp__plugin_ultrapower_t__lsp_*` which creates confusion.
+
+**Example from docs/REFERENCE.md:820**:
+```markdown
+| `ultrapower:lsp_hover` | `mcp__plugin_ultrapower_t__lsp_hover` |
+```
+
+**Problem**: The MCP tool name contains a colon in the middle: `...t__ultrapower:lsp_hover`
+
+**Expected**: Either:
+1. `mcp__plugin_ultrapower_t__lsp_hover` (if keeping old naming)
+2. Document that the actual MCP name uses underscores: `mcp__plugin_ultrapower_t__ultrapower_lsp_hover`
+
+**Impact**: Users will get tool not found errors if they copy-paste these names
+
+**Recommendation**: Verify actual MCP tool registration names in `src/tools/lsp-tools.ts` and ensure documentation matches exactly.
+
+---
+
+#### MEDIUM-1: Incomplete Migration in Code Examples
+
+**File**: `docs/mcp/performance.md:61-64`
+**Issue**: Code examples use invalid syntax with colons in object property access
+
+```typescript
+// Current (INVALID JavaScript):
+const [hover, refs, symbols] = await Promise.all([
+  mcp__plugin_ultrapower_t__lsp_hover({ file, line, character }),
+  //                                   ^ SyntaxError: Unexpected token ':'
+```
+
+**Expected**:
+```typescript
+const [hover, refs, symbols] = await Promise.all([
+  mcp__plugin_ultrapower_t__['ultrapower:lsp_hover']({ file, line, character }),
+  // OR if the actual tool name uses underscores:
+  mcp__plugin_ultrapower_t__ultrapower_lsp_hover({ file, line, character }),
+]);
+```
+
+**Impact**: Code examples will not run, causing user confusion
+
+**Recommendation**: Fix all code examples to use valid JavaScript syntax.
+
+---
+
+#### MEDIUM-2: Missing Verification Step
+
+**File**: Plan specified grep verification, but no evidence it was run
+**Issue**: Plan step 3 says: `grep -r "ultrapower:lsp_diagnostics" docs/`
+
+**Problem**: This grep would find the NEW naming (which is correct), but the plan description says "Expected: No matches" which is backwards logic.
+
+**Recommendation**: Clarify verification steps and provide evidence that old naming (`lsp_*` without prefix) no longer exists in documentation.
+
+---
+
+### TD-3: Windows Compatibility Tests ✅ VERIFIED (Earlier Commit)
+
+**Status**: Implemented correctly in commit 0b759af7 (outside review range)
+
+**Files Created**:
+- `tests/platform/windows-atomic-write.test.ts` (30 lines)
+- `docs/standards/runtime-protection.md` (7 lines added)
+
+**Implementation Quality**: ✅ GOOD
+
+**Code Review**:
+```typescript
+describe.skipIf(process.platform !== 'win32')('Windows atomic write', () => {
+  // ✅ Correct platform detection
+  // ✅ Proper cleanup in afterEach
+  // ✅ Tests actual atomic write behavior
+
+  it('should handle locked files gracefully', () => {
+    atomicWriteJsonSyncWithRetry(testPath, data);
+    expect(existsSync(testPath)).toBe(true);
+    // ✅ Verifies file was written
+    // ✅ Verifies content integrity
+  });
+});
+```
+
+**Strengths**:
+- ✅ Uses `skipIf` for platform detection (correct Vitest API)
+- ✅ Proper cleanup with `afterEach` and `testFiles` tracking
+- ✅ Tests the actual atomic write function
+- ✅ Documentation updated with platform notes
+
+**Issues**: None
+
+---
+
+### TD-4: Atomic Write Protection ⚠️ MISLEADING CLAIM
+
+**Status**: Already implemented (pre-existing, not in this sprint)
+
+**Files**: `src/hooks/subagent-tracker/index.ts:427`
+
+**Implementation Quality**: ✅ GOOD (but not part of this review)
+
+**Current State**:
+```typescript
+// Line 12: Import present
+import { atomicWriteJsonSyncWithRetry } from "../../lib/atomic-write.js";
+
+// Line 427: Correct usage
+atomicWriteJsonSyncWithRetry(statePath, state);
+```
+
+**Issue**: The verification report claims this was fixed as part of TD-4, but:
+- No commit in range 4f413d6d..066ff55c modifies `subagent-tracker/index.ts`
+- The atomic write was likely implemented during v7.1.1 security hardening
+- Commit fc63ee7d (feat(security): implement hook system security hardening) predates this sprint
+
+**Recommendation**: Update verification report to acknowledge TD-4 was already complete, not newly implemented.
+
+---
+
+## Security Review
+
+### No Security Issues Found
+
+All changes in this commit range are documentation-only (TD-2). The code changes (TD-1, TD-3, TD-4) were in earlier commits and have been reviewed separately.
+
+---
+
+## Performance Review
+
+### No Performance Impact
+
+Documentation changes have no runtime performance impact.
+
+---
+
+## Best Practices Review
+
+### LOW-1: Commit Range Mismatch
+
+**Issue**: The verification report references commit range 4f413d6d..066ff55c, but the actual implementation commits (55be0ceb, 0b759af7, b06f8c59, 7ebfcfea) are outside or partially outside this range.
+
+**Impact**: Confusing audit trail for future reviews
+
+**Recommendation**: Either:
+1. Expand commit range to include all implementation commits
+2. Clarify that verification covers earlier commits, not just the specified range
+
+---
+
+### LOW-2: Test Event Files in Review
+
+**Files**: 21 files in `.omc/nexus/events/`
+**Issue**: Test event JSON files are included in the commit range, adding noise to the review
+
+**Recommendation**: Consider `.gitignore` for test event files or use separate commits for test artifacts.
+
+---
+
+## Documentation Quality
+
+### MEDIUM-3: Inconsistent Terminology
+
+**Files**: Multiple documentation files
+**Issue**: Mixed use of "LSP tools", "LSP tool naming", "ultrapower:lsp_*" without clear definition
+
+**Recommendation**: Add a glossary section explaining:
+- What "ultrapower:" prefix means
+- Why the migration is happening
+- How to identify old vs new naming
+
+---
+
+## Summary Statistics
+
+| Category | Count |
+|----------|-------|
+| **Files Reviewed** | 56 |
+| **Code Files** | 0 (all in earlier commits) |
+| **Documentation Files** | 34 |
+| **Test Files** | 0 (created in earlier commit) |
+| **Test Event Files** | 21 |
+| **Critical Issues** | 1 |
+| **High Issues** | 1 |
+| **Medium Issues** | 3 |
+| **Low Issues** | 2 |
+
+---
+
+## Issues by Severity
+
+### CRITICAL (1)
+- **CRITICAL-1**: Misleading verification report claims TD-4 was fixed in this sprint
+
+### HIGH (1)
+- **HIGH-1**: Invalid MCP tool names in documentation (contains colons)
+
+### MEDIUM (3)
+- **MEDIUM-1**: Code examples use invalid JavaScript syntax
+- **MEDIUM-2**: Missing verification evidence for old naming removal
+- **MEDIUM-3**: Inconsistent terminology across documentation
+
+### LOW (2)
+- **LOW-1**: Commit range mismatch in verification report
+- **LOW-2**: Test event files add noise to review
+
+---
+
+## Approval Recommendation
+
+⚠️ **REQUEST CHANGES**
+
+### Must Fix Before Approval:
+1. **CRITICAL-1**: Update verification report to clarify TD-4 was pre-existing
+2. **HIGH-1**: Fix MCP tool names in documentation (remove colons or use bracket notation)
+3. **MEDIUM-1**: Fix all code examples to use valid JavaScript syntax
+
+### Should Fix (Recommended):
+4. **MEDIUM-2**: Provide evidence that old LSP naming is removed from docs
+5. **MEDIUM-3**: Add terminology glossary for LSP tool naming
+
+### Nice to Have:
+6. **LOW-1**: Clarify commit range scope in verification report
+7. **LOW-2**: Consider gitignoring test event files
+
+---
+
+## Positive Observations
+
+1. ✅ TD-1 implementation is clean and correct (commit 55be0ceb)
+2. ✅ TD-3 Windows test has proper platform detection and cleanup (commit 0b759af7)
+3. ✅ TD-4 atomic write protection is correctly implemented (pre-existing)
+4. ✅ CHANGELOG deprecation notice is clear (commit b06f8c59)
+5. ✅ Documentation migration is comprehensive (437 line changes)
+6. ✅ Commit messages follow conventional commits format
+
+---
+
+## Next Steps
+
+1. Fix HIGH-1 and MEDIUM-1 by verifying actual MCP tool registration names
+2. Update verification report to correct TD-4 timeline
+3. Run verification: `grep -rn "mcp__plugin_ultrapower_t__lsp_" docs/` to find old naming
+4. Fix code examples to use valid syntax
+5. Re-run full test suite to ensure no regressions
+6. Update this review with fixes and re-submit for approval
+
+---
+
+**Review Completed**: 2026-03-16T20:10:05Z
+**Reviewer**: Senior Code Reviewer (Claude Opus 4.6)

package/docs/shared/agent-tiers.md

@@ -116,18 +116,18 @@ Task(subagent_type="ultrapower:explore",
 
 | 工具 | 类别 | 用途 | 是否分配给 Agent？ |
 | ------ | ---------- | --------- | --------------------- |
-| `lsp_hover` | LSP | 获取代码位置的类型信息和文档 | 否（orchestrator 直接使用） |
-| `lsp_goto_definition` | LSP | 跳转到符号定义处 | 否（orchestrator 直接使用） |
-| `lsp_find_references` | LSP | 查找符号在代码库中的所有用法 | 是（仅 `explore`） |
-| `lsp_document_symbols` | LSP | 获取文件中所有符号的概览 | 是 |
-| `lsp_workspace_symbols` | LSP | 按名称在工作区中搜索符号 | 是 |
-| `lsp_diagnostics` | LSP | 获取文件的错误、警告和提示 | 是 |
-| `lsp_diagnostics_directory` | LSP | 项目级类型检查（tsc --noEmit 或 LSP） | 是 |
-| `lsp_prepare_rename` | LSP | 检查符号是否可以重命名 | 否（orchestrator 直接使用） |
-| `lsp_rename` | LSP | 在整个项目中重命名符号 | 否（orchestrator 直接使用） |
-| `lsp_code_actions` | LSP | 获取可用的重构和快速修复 | 否（orchestrator 直接使用） |
-| `lsp_code_action_resolve` | LSP | 获取代码操作的完整编辑详情 | 否（orchestrator 直接使用） |
-| `lsp_servers` | LSP | 列出可用的语言服务器及安装状态 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_hover` | LSP | 获取代码位置的类型信息和文档 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_goto_definition` | LSP | 跳转到符号定义处 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_find_references` | LSP | 查找符号在代码库中的所有用法 | 是（仅 `explore`） |
+| `ultrapower:lsp_document_symbols` | LSP | 获取文件中所有符号的概览 | 是 |
+| `ultrapower:lsp_workspace_symbols` | LSP | 按名称在工作区中搜索符号 | 是 |
+| `ultrapower:lsp_diagnostics` | LSP | 获取文件的错误、警告和提示 | 是 |
+| `ultrapower:lsp_diagnostics_directory` | LSP | 项目级类型检查（tsc --noEmit 或 LSP） | 是 |
+| `ultrapower:lsp_prepare_rename` | LSP | 检查符号是否可以重命名 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_rename` | LSP | 在整个项目中重命名符号 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_code_actions` | LSP | 获取可用的重构和快速修复 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_code_action_resolve` | LSP | 获取代码操作的完整编辑详情 | 否（orchestrator 直接使用） |
+| `ultrapower:lsp_servers` | LSP | 列出可用的语言服务器及安装状态 | 否（orchestrator 直接使用） |
 | `ast_grep_search` | AST | 基于 AST 的模式化结构代码搜索 | 是 |
 | `ast_grep_replace` | AST | 基于模式的结构化代码转换 | 是 |
 | `python_repl` | Data | 用于数据分析和计算的持久化 Python REPL | 是 |
@@ -154,30 +154,30 @@ Task(subagent_type="ultrapower:explore",
 
 | 工具 | 直接使用时机 |
 | ------ | --------------------- |
-| `lsp_hover` | 对话中快速查询类型 |
-| `lsp_goto_definition` | 分析过程中导航到符号定义 |
-| `lsp_prepare_rename` | 在决定方案前检查重命名可行性 |
-| `lsp_rename` | 安全重命名操作（返回编辑预览，不自动应用） |
-| `lsp_code_actions` | 发现可用的重构操作 |
-| `lsp_code_action_resolve` | 获取特定代码操作的详情 |
-| `lsp_servers` | 检查语言服务器可用性 |
+| `ultrapower:lsp_hover` | 对话中快速查询类型 |
+| `ultrapower:lsp_goto_definition` | 分析过程中导航到符号定义 |
+| `ultrapower:lsp_prepare_rename` | 在决定方案前检查重命名可行性 |
+| `ultrapower:lsp_rename` | 安全重命名操作（返回编辑预览，不自动应用） |
+| `ultrapower:lsp_code_actions` | 发现可用的重构操作 |
+| `ultrapower:lsp_code_action_resolve` | 获取特定代码操作的详情 |
+| `ultrapower:lsp_servers` | 检查语言服务器可用性 |
 
 对于需要实现的复杂重命名或重构任务，委派给 `executor`（使用 `model="opus"`），它可以使用 `ast_grep_replace` 进行结构化转换。
 
 ### 工具选择指南
 
-* **需要文件符号概览或工作区搜索？** 通过 `explore` 使用 `lsp_document_symbols`/`lsp_workspace_symbols`
+* **需要文件符号概览或工作区搜索？** 通过 `explore` 使用 `ultrapower:lsp_document_symbols`/`ultrapower:lsp_workspace_symbols`
 
-* **需要查找符号的所有用法？** 通过 `explore` 使用 `lsp_find_references`
+* **需要查找符号的所有用法？** 通过 `explore` 使用 `ultrapower:lsp_find_references`
 
 * **需要结构化代码模式？**（如"查找所有匹配 X 形状的函数"）通过 `explore`、`architect` 或 `code-reviewer` 使用 `ast_grep_search`
 
 * **需要结构化代码转换？** 通过 `executor`（使用 `model="opus"`）使用 `ast_grep_replace`
 
-* **需要全项目类型检查？** 通过 `architect`、`executor` 或 `build-fixer` 使用 `lsp_diagnostics_directory`
+* **需要全项目类型检查？** 通过 `architect`、`executor` 或 `build-fixer` 使用 `ultrapower:lsp_diagnostics_directory`
 
-* **需要单文件错误检查？** 通过多个 agent 使用 `lsp_diagnostics`（参见矩阵）
+* **需要单文件错误检查？** 通过多个 agent 使用 `ultrapower:lsp_diagnostics`（参见矩阵）
 
 * **需要数据分析/计算？** 通过 `scientist` 使用 `python_repl`
 
-* **需要快速类型信息或定义查询？** 直接使用 `lsp_hover`/`lsp_goto_definition`（orchestrator 直接工具）
+* **需要快速类型信息或定义查询？** 直接使用 `ultrapower:lsp_hover`/`ultrapower:lsp_goto_definition`（orchestrator 直接工具）

package/docs/shared/features.md

@@ -59,7 +59,7 @@
 
 ## 目录诊断工具
 
-通过 `lsp_diagnostics_directory` 工具进行项目级类型检查。
+通过 `ultrapower:lsp_diagnostics_directory` 工具进行项目级类型检查。
 
 **策略：**
 

package/docs/shared/verification-tiers.md

@@ -6,7 +6,7 @@
 
 | 层级 | 标准 | Agent | 模型 | 所需证据 |
 | ------ | ---------- | ------- | ------- | ------------------- |
-| **LIGHT** | <5 个文件，<100 行，完整测试覆盖 | architect-low | haiku | lsp_diagnostics 无错误 |
+| **LIGHT** | <5 个文件，<100 行，完整测试覆盖 | architect-low | haiku | ultrapower:lsp_diagnostics 无错误 |
 | **STANDARD** | 默认（非 LIGHT 或 THOROUGH） | architect-medium | sonnet | diagnostics + 构建通过 |
 | **THOROUGH** | >20 个文件，或架构/安全变更 | architect | opus | 完整审查 + 所有测试 |
 
@@ -94,7 +94,7 @@ ELSE:
 | 声明 | 所需证据 |
 | ------- | ------------------- |
 | "已修复" | 显示现在通过的测试 |
-| "已实现" | lsp_diagnostics 无错误 + 构建通过 |
+| "已实现" | ultrapower:lsp_diagnostics 无错误 + 构建通过 |
 | "已重构" | 所有测试仍然通过 |
 | "已调试" | 定位到 file:line 的根本原因 |
 

package/docs/standards/README.md

@@ -5,7 +5,7 @@
 > **最后更新**: 2026-03-02
 > **真理之源**: `docs/standards/audit-report.md`
 
-ultrapower v7.6.0 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
+ultrapower v7.7.1 具备 49 个 agents、70 个 skills、35 个 hooks 的完整体系。本规范体系从现有代码反向提取，覆盖运行时防护、Hook 执行顺序、状态机、Agent 生命周期、用户使用指南和贡献规范，使 ultrapower 从"能用"升级为"可靠、易用、可扩展"。
 
 ---
 

package/docs/standards/runtime-protection.md

@@ -308,6 +308,13 @@ try {
 
 * 所有涉及文件操作的代码必须考虑 Windows 平台行为差异
 
+* 使用 `maxRetries` 参数在 `atomicWriteJsonSyncWithRetry` 中提高鲁棒性
+
+**测试覆盖**：
+
+* Windows 平台兼容性测试：`tests/platform/windows-atomic-write.test.ts`
+* 测试在非 Windows 平台自动跳过（`skipIf(process.platform !== 'win32')`）
+
 #### 2.3.1 Windows 命令注入防护（SEC-H02）
 
 **来源**: v5.5.18 P0 修复 (2026-03-05)

package/docs/troubleshooting.md

@@ -468,7 +468,7 @@ find .omc/checkpoints -type f -mtime +1 -delete
 
 # 在 Claude Code 中运行
 
-/lsp_servers
+/ultrapower:lsp_servers
 
 # 重启 LSP 服务器
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liangjie559567/ultrapower",
-  "version": "7.6.0",
+  "version": "7.7.1",
   "description": "Disciplined multi-agent orchestration: workflow enforcement + parallel execution",
   "type": "module",
   "main": "dist/index.js",