@mycodemap/mycodemap 0.4.2 → 0.5.0

package/docs/archive/test_scenario_3_impact_analysis_report.md

@@ -0,0 +1,520 @@
+# 测试场景3：影响范围分析对比测试报告
+
+## 测试概述
+
+**测试目标**: 对比 CodeMap `impact` 命令与手动 `grep` 分析文件变更影响范围的差异
+
+**测试时间**: 2025年3月2日  
+**测试目录**: `/data/codemap`  
+**CodeMap版本**: 本地构建版本
+
+---
+
+## 测试用例 1: src/core/analyzer.ts 影响分析
+
+### 测试目的
+分析核心分析器文件的变更影响范围，对比 CodeMap 的依赖图分析与手动 grep 文本搜索的差异。
+
+### CodeMap 执行 (直接依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts
+```
+
+**执行时间**: 0.539s (real)
+
+**输出**:
+```
+📍 影响分析
+──────────────────────────────────────────────────
+
+目标文件:
+   src/core/analyzer.ts
+   导出: analyze
+
+⬇️  直接依赖该文件的模块 (13):
+   • src/orchestrator/ai-feed-generator.ts
+   • src/orchestrator/result-fusion.ts
+   • src/watcher/watch-worker.ts
+   • src/core/__tests__/analyzer.test.ts
+   • src/cli/__tests__/generate.test.ts
+   • src/cli/commands/ci.ts
+   • src/cli/commands/generate.ts
+   • src/cli/commands/watch-foreground.ts
+   • src/orchestrator/__tests__/ai-feed-generator.test.ts
+   • src/orchestrator/__tests__/git-analyzer.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+   • src/plugins/__tests__/complexity-analyzer.test.ts
+   • src/cli/commands/__tests__/watch-foreground.test.ts
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 13 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/core/analyzer.ts --transitive
+```
+
+**执行时间**: 0.698s (real)
+
+**输出**:
+```
+直接依赖该文件的模块 (13):
+   [同上]
+
+🌐 传递依赖 (66):
+       └─► src/cli/index.ts [距离: 3]
+         └─► src/ai/claude.ts [距离: 4]
+         └─► src/ai/codex.ts [距离: 4]
+         ... 还有 46 个
+
+直接影响: 13 个模块
+传递影响: 66 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "analyzer|Analyzer" src/ | head -20
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/__tests__/generate.test.ts
+src/cli/commands/__tests__/generate.test.ts
+src/cli/commands/__tests__/watch-foreground.test.ts
+src/plugins/built-in/complexity-analyzer.ts
+src/cli/commands/watch-foreground.ts
+src/core/__tests__/analyzer.test.ts
+src/cli/commands/ci.ts
+src/core/analyzer.ts
+src/cli/commands/generate.ts
+src/plugins/__tests__/complexity-analyzer.test.ts
+src/plugins/index.ts
+src/plugins/plugin-loader.ts
+src/index.ts
+src/orchestrator/ai-feed-generator.ts
+src/orchestrator/index.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/__tests__/git-analyzer.test.ts
+src/orchestrator/__tests__/ai-feed-generator.test.ts
+```
+
+**匹配文件总数**: 22 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.54s | 0.70s | 0.01s | Grep 更快 (54-70x) |
+| **直接依赖数** | 13 | 13 | 22 | Grep 包含大量误报 |
+| **传递依赖数** | 未显示 | 66 | N/A | CodeMap 独有功能 |
+| **依赖深度** | ❌ | ✅ (显示距离) | ❌ | CodeMap 传递模式优势 |
+| **风险评估** | ✅ 极高风险 | ✅ 极高风险 | ❌ | CodeMap 独有功能 |
+| **导出信息** | ✅ | ✅ | ❌ | CodeMap 独有功能 |
+| **误报率** | 低 | 低 | 高 (40%) | CodeMap 更准确 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖"**:
+```
+src/cli/commands/__tests__/generate.test.ts  (不包含 analyzer 导入)
+src/core/analyzer.ts                          (文件自身)
+src/index.ts                                  ✅ 应该被检测！
+src/orchestrator/git-analyzer.ts              (独立模块，非依赖)
+src/orchestrator/index.ts                     (通过 git-analyzer 导入)
+src/plugins/built-in/complexity-analyzer.ts   (独立模块)
+src/plugins/index.ts                          (通过 complexity-analyzer 导入)
+src/plugins/plugin-loader.ts                  (通过 complexity-analyzer 导入)
+```
+
+**关键发现**: 
+- `src/index.ts` 确实导出了 `analyze` 函数 (`export { analyze } from './core/analyzer.js'`)，但 CodeMap 未检测到这是 analyzer.ts 的依赖
+- Grep 找到的 22 个文件中，约 9 个是误报（文件名含 analyzer 但实际不依赖 core/analyzer.ts）
+- CodeMap 的 13 个直接依赖都是准确的导入关系
+
+---
+
+## 测试用例 2: src/types/index.ts 影响分析
+
+### 测试目的
+分析类型定义文件的变更影响，类型文件通常有大量依赖关系。
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/types/index.ts --transitive
+```
+
+**执行时间**: 0.858s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/types/index.ts
+   导出: SymbolKind, SourceLocation, DecoratorInfo, ... (38 个类型)
+
+⬇️  直接依赖该文件的模块 (38):
+   • src/ai/claude.ts
+   • src/ai/codex.ts
+   • src/ai/provider.ts
+   • src/ai/subagent-caller.ts
+   • src/core/analyzer.ts
+   • src/core/global-index.ts
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/generator/ai-overview.ts
+   • src/generator/context.ts
+   • ... (共38个)
+
+🌐 传递依赖 (41):
+     └─► src/ai/factory.ts [距离: 2]
+     └─► src/ai/index.ts [距离: 2]
+             └─► src/cli/index.ts [距离: 6]
+             └─► ...
+
+⚠️  风险评估:
+   🔴 极高风险 - 该文件是核心依赖，修改将影响大量模块
+   直接影响: 38 个模块
+   传递影响: 41 个额外模块
+```
+
+### 传统工具执行
+
+```bash
+rg -l "from.*types/index|from.*types" src/
+```
+
+**执行时间**: 0.009s (real)
+
+**输出**:
+```
+src/watcher/watch-worker.ts
+src/cli/commands/complexity.ts
+src/cli/commands/analyze.ts
+src/cli/commands/watch-foreground.ts
+src/cli/commands/impact.ts
+src/cli/commands/cycles.ts
+src/cli/commands/ci.ts
+src/cli/commands/generate.ts
+src/cli/commands/deps.ts
+src/cli/commands/workflow.ts
+src/cli/commands/query.ts
+src/worker/index.ts
+src/ai/claude.ts
+src/ai/subagent-caller.ts
+src/ai/provider.ts
+src/ai/codex.ts
+src/ai/index.ts
+... (共66个文件)
+```
+
+**匹配文件总数**: 66 个
+
+### 对比分析
+
+| 维度 | CodeMap | Grep | 结论 |
+|------|---------|------|------|
+| **执行时间** | 0.86s | 0.009s | Grep 快 95x |
+| **匹配文件数** | 38 | 66 | 差异 28 个文件 |
+| **误报/漏报** | 可能遗漏 | 包含非 types/index.ts 导入 | 各有优劣 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的 "依赖" (28 个)**:
+```
+src/ai/index.ts
+src/cli/commands/analyze.ts
+src/cli/commands/ci.ts
+src/cli/commands/workflow.ts
+src/index.ts
+src/orchestrator/adapters/ast-grep-adapter.ts
+src/orchestrator/adapters/base-adapter.ts
+src/orchestrator/adapters/codemap-adapter.ts
+src/orchestrator/confidence.ts
+src/orchestrator/git-analyzer.ts
+src/orchestrator/index.ts
+src/orchestrator/integration/pipeline.test.ts
+src/orchestrator/intent-router.ts
+src/orchestrator/result-fusion.ts
+src/orchestrator/tool-orchestrator.ts
+src/orchestrator/workflow/phase-checkpoint.ts
+src/orchestrator/workflow/types.ts
+src/orchestrator/workflow/workflow-context.ts
+src/orchestrator/workflow/workflow-orchestrator.ts
+... (共28个)
+```
+
+**原因分析**:
+这些文件通过 `src/orchestrator/types.ts` 间接使用类型，而非直接从 `src/types/index.ts` 导入。例如:
+```typescript
+// src/orchestrator/result-fusion.ts
+import type { UnifiedResult, HeatScore } from './types.js';  // 不是 types/index.js
+```
+
+而 `src/orchestrator/types.ts` 自身又从 `src/types/index.ts` 导入，形成间接依赖。
+
+**结论**: 
+- CodeMap 准确识别**直接**依赖 (38个)
+- Grep 捕获了**间接**依赖模式，但也包含了一些误报 (通过 `orchestrator/types` 而非 `types/index`)
+- CodeMap 传递依赖模式 (41个) 补充了间接依赖，总计 79 个影响模块
+
+---
+
+## 测试用例 3: src/cache/lru-cache.ts 影响分析
+
+### 测试目的
+分析具体工具类文件的变更影响，评估叶节点文件的依赖分析。
+
+### CodeMap 执行
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts
+```
+
+**执行时间**: 0.800s (real)
+
+**输出**:
+```
+📍 影响分析
+
+目标文件:
+   src/cache/lru-cache.ts
+   导出: LRUCache, LRUCacheWithTTL
+
+⬇️  直接依赖该文件的模块 (4):
+   • src/cache/index.ts
+   • src/cache/parse-cache.ts
+   • src/cache/__tests__/lru-cache.test.ts
+   • src/parser/implementations/tree-sitter-parser.ts
+
+⚠️  风险评估:
+   ⚠️  高风险 - 该文件被多个模块依赖，修改需谨慎
+   直接影响: 4 个模块
+```
+
+### CodeMap 执行 (传递依赖)
+
+```bash
+npx codemap impact -f src/cache/lru-cache.ts --transitive
+```
+
+**传递依赖**: 76 个模块
+
+### 传统工具执行
+
+```bash
+rg -l "lru-cache|LRUCache" src/
+```
+
+**执行时间**: 0.010s (real)
+
+**输出**:
+```
+src/cache/__tests__/lru-cache.test.ts
+src/cache/parse-cache.ts
+src/cache/lru-cache.ts
+src/cache/index.ts
+src/orchestrator/test-linker.ts
+```
+
+**匹配文件总数**: 5 个
+
+### 对比分析
+
+| 维度 | CodeMap Direct | CodeMap Transitive | Grep | 结论 |
+|------|----------------|-------------------|------|------|
+| **执行时间** | 0.80s | ~1.0s | 0.01s | Grep 快 80-100x |
+| **直接依赖数** | 4 | 4 | 5 | Grep 多1个 |
+| **传递依赖数** | 未显示 | 76 | N/A | CodeMap 独有功能 |
+| **风险评估** | ✅ 高风险 | ✅ 高风险 | ❌ | CodeMap 独有 |
+
+### 差异分析
+
+**Grep 找到但 CodeMap 未找到的**:
+```
+src/orchestrator/test-linker.ts  (仅作为字符串示例提及，无实际导入)
+```
+
+这是一个**误报**: `test-linker.ts` 只是在注释中提到 `lru-cache.test.ts` 作为示例:
+```typescript
+* lru-cache.test.ts → lru-cache.ts
+```
+
+CodeMap 正确地识别了这一点，没有将其列为依赖。
+
+---
+
+## 综合对比分析
+
+### 1. 直接依赖识别
+
+| 测试文件 | CodeMap 直接依赖 | Grep 匹配数 | CodeMap 准确率 | Grep 准确率 |
+|---------|-----------------|------------|----------------|-------------|
+| analyzer.ts | 13 | 22 | 100% | ~41% |
+| types/index.ts | 38 | 66 | 100% | ~58% |
+| lru-cache.ts | 4 | 5 | 100% | ~80% |
+
+**结论**: CodeMap 在直接依赖识别上具有**更高的准确性**，几乎没有误报。
+
+### 2. 传递依赖识别
+
+| 测试文件 | CodeMap 传递依赖 | 手动分析可行性 | 优势 |
+|---------|-----------------|---------------|------|
+| analyzer.ts | 66 | 困难 | 揭示深层影响 |
+| types/index.ts | 41 | 困难 | 跨层级追踪 |
+| lru-cache.ts | 76 | 几乎不可能 | 揭示广泛影响 |
+
+**结论**: CodeMap 的传递依赖分析是**独有功能**，手动几乎无法完成同等分析。
+
+### 3. 风险评估准确性
+
+CodeMap 风险评估分级:
+- 🔴 极高风险: > 20 个直接依赖 (如 types/index.ts: 38个)
+- ⚠️ 高风险: 5-20 个直接依赖
+- ⚠️ 中风险: 1-4 个直接依赖 (如 cycles.ts: 2个)
+- 🟢 低风险: 0 个依赖
+
+**验证**:
+- `src/types/index.ts` (38依赖) → 🔴 极高风险 ✅ 合理
+- `src/cache/lru-cache.ts` (4依赖) → ⚠️ 高风险 ✅ 合理 (虽数量不多但核心功能)
+- `src/cli/commands/cycles.ts` (2依赖) → ⚠️ 中风险 ✅ 合理
+
+### 4. 输出格式实用性
+
+**CodeMap 优势**:
+- 可视化依赖树结构
+- 显示每个依赖的导出内容
+- 距离标记 (传递依赖)
+- 风险等级评估
+- 统计汇总
+
+**Grep 优势**:
+- 简单列表，易于脚本处理
+- 可与其他 Unix 工具链组合
+
+### 5. 性能对比
+
+| 工具 | 平均执行时间 | 相对速度 |
+|------|-------------|---------|
+| CodeMap (direct) | ~0.6s | 1x |
+| CodeMap (transitive) | ~0.8s | 0.75x |
+| ripgrep | ~0.01s | 60-80x |
+
+---
+
+## 发现的问题
+
+### 问题 1: 遗漏 re-export 依赖
+**严重性**: 🔴 高
+
+**描述**: CodeMap 未能检测到通过 re-export 模式依赖的文件。
+
+**示例**: `src/index.ts` 包含:
+```typescript
+export { analyze } from './core/analyzer.js';
+```
+
+但 CodeMap 未将 `src/index.ts` 列为 `analyzer.ts` 的依赖。
+
+**影响**: 修改 analyzer.ts 可能影响所有通过主入口导入的下游用户。
+
+### 问题 2: 对 "高/极高风险" 阈值定义不明确
+**严重性**: 🟡 中
+
+**描述**: 
+- `types/index.ts` (38依赖) → 🔴 极高风险
+- `analyzer.ts` (13依赖) → 🔴 极高风险
+- `lru-cache.ts` (4依赖) → ⚠️ 高风险
+
+阈值跳跃较大，13和38都被归为"极高"，但4就是"高"，缺少中间等级。
+
+### 问题 3: 执行时间较长
+**严重性**: 🟡 中
+
+**描述**: CodeMap 比 ripgrep 慢 60-80 倍。对于大型代码库或频繁查询场景，这可能成为瓶颈。
+
+**建议**: 
+- 提供缓存机制
+- 增量更新依赖图
+- 添加 `--fast` 模式使用简化分析
+
+### 问题 4: 输出格式缺乏机器可读性
+**严重性**: 🟢 低
+
+**描述**: 输出主要是人类可读格式，没有 JSON/YAML 输出选项，不利于脚本集成。
+
+---
+
+## 改进建议
+
+### 1. 增强 re-export 检测
+```typescript
+// 检测以下模式:
+export { foo } from './module';
+export * from './module';
+export { default } from './module';
+```
+
+### 2. 细化风险等级
+```
+🟢 低风险: 0-2 依赖
+🟡 中风险: 3-10 依赖  
+🟠 高风险: 11-25 依赖
+🔴 极高风险: 26+ 依赖
+```
+
+### 3. 添加性能优化选项
+```bash
+npx codemap impact -f file.ts --cached        # 使用缓存
+npx codemap impact -f file.ts --depth 2       # 限制传递深度
+npx codemap impact -f file.ts --json          # 机器可读输出
+```
+
+### 4. 提供 diff 模式
+```bash
+npx codemap impact --compare branch1 branch2  # 对比分支影响
+```
+
+---
+
+## 总结
+
+| 评估维度 | 评分 | 说明 |
+|---------|------|------|
+| 准确性 | ⭐⭐⭐⭐⭐ | 几乎无直接依赖误报 |
+| 完整性 | ⭐⭐⭐⭐ | 遗漏 re-export，其他良好 |
+| 传递分析 | ⭐⭐⭐⭐⭐ | 独有功能，非常有价值 |
+| 风险评估 | ⭐⭐⭐⭐ | 分级合理但阈值可细化 |
+| 性能 | ⭐⭐⭐ | 比 grep 慢，但可接受 |
+| 实用性 | ⭐⭐⭐⭐⭐ | 可视化输出，信息丰富 |
+
+### 最终结论
+
+**CodeMap impact 命令**在影响范围分析上**显著优于**传统 grep 方法:
+
+1. **准确性**: 几乎零误报，而 grep 有 20-60% 的误报率
+2. **传递依赖**: 提供手动几乎无法完成的深层依赖分析
+3. **风险评估**: 量化风险等级，辅助决策
+4. **可视化**: 树形结构直观展示依赖关系
+
+**适用场景**:
+- ✅ 发布前影响评估
+- ✅ 重构前依赖分析  
+- ✅ 代码审查辅助
+- ✅ 架构决策支持
+
+**不适用场景**:
+- ❌ 需要极快速响应的实时监控
+- ❌ 纯文本处理的自动化脚本
+
+**总体推荐**: ⭐⭐⭐⭐⭐ (5/5) - 对于需要准确影响分析的场景强烈推荐使用

package/docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md

@@ -0,0 +1,79 @@
+# Design Contract Template
+
+把下面模板复制到仓库根目录并保存为 `mycodemap.design.md`。
+
+> 目标不是写长篇 PRD，而是把 AI 后续执行需要的**目标、限制、验收标准、显式非目标**写成可验证输入。
+
+## Required Sections
+
+| Section | Required | 作用 |
+|---------|----------|------|
+| `## Goal` | Yes | 定义这次要达成的结果 |
+| `## Constraints` | Yes | 约束技术/产品/时间/兼容性边界 |
+| `## Acceptance Criteria` | Yes | 写成可以验证的结果，而不是模糊愿景 |
+| `## Non-Goals` | Yes | 明确这次不做什么，防止 AI scope drift |
+| `## Context` | No | 补充背景、现状、依赖关系 |
+| `## Open Questions` | No | 记录需要人类决策的问题 |
+| `## Notes` | No | 其他实现前必须知道的信息 |
+
+## Authoring Rules
+
+- 使用清晰 section heading，不要把多个主题揉进同一段。
+- `Acceptance Criteria` 尽量写成可检查的 bullet。
+- `Non-Goals` 不能为空；它是防止越界实现的第一道护栏。
+- 如果某个关键决策尚未确定，写进 `Open Questions`，不要让 AI 自行猜测。
+
+## Copy-Paste Template
+
+```markdown
+# Design Contract: <feature name>
+
+## Goal
+- 这个 feature 最终要解决什么问题？
+- 用户或团队为什么需要它？
+
+## Constraints
+- 必须兼容的现有命令、接口或目录边界
+- 不允许改动的模块 / 风险限制 / 时间限制
+
+## Acceptance Criteria
+- [ ] 可验证结果 1
+- [ ] 可验证结果 2
+- [ ] 可验证结果 3
+
+## Non-Goals
+- 这次明确不做什么
+- 哪些相关问题留到后续 phase
+
+## Context
+- 当前实现现状
+- 相关文件 / 模块 / 文档
+
+## Open Questions
+- 需要人类确认的问题 1
+
+## Notes
+- 其他补充信息
+```
+
+## Minimal Example
+
+```markdown
+# Design Contract: Add design validate command
+
+## Goal
+- 为 human-authored design contract 提供正式的 CLI validate 入口
+
+## Constraints
+- 不扩写 analyze intent
+- 不恢复 workflow 的 commit / ci phases
+
+## Acceptance Criteria
+- [ ] `mycodemap design validate mycodemap.design.md --json` 返回机器可读结果
+- [ ] 缺失 `Acceptance Criteria` section 时返回 blocker diagnostics
+- [ ] README 和 AI docs 能发现该入口
+
+## Non-Goals
+- 不做 design-to-code mapping
+- 不生成 handoff package
+```

package/docs/product-specs/README.md

@@ -11,8 +11,9 @@
 - `MVP3-ARCHITECTURE-COMPARISON.md`：把历史设计目标与 `v1.3` 已落地基线并列，防止把愿景误写成现实。
 - `MVP3-ARCHITECTURE-REDESIGN-PRD.md`：记录当前产品边界、Deferred 范围与用户价值。
 - `MVP3-ARCHITECTURE-REDESIGN-TECH-PRD.md`：记录当前技术基线、目录现实、护栏与迁移语义。
+- `DESIGN_CONTRACT_TEMPLATE.md`：当前 human-authored design contract 的 canonical 模板，供 `mycodemap.design.md` 复制使用。
 
-> 以上 3 份规格目前都属于“已交付基线同步版”，不是新的待实施 roadmap。
+> 前 3 份规格属于“已交付基线同步版”；`DESIGN_CONTRACT_TEMPLATE.md` 是当前有效输入契约模板，不是新的待实施 roadmap。
 
 ## 应放内容
 

package/docs/rules/engineering-with-codex-openai.md

@@ -44,13 +44,17 @@
 
 - 仓库内调试与验证优先使用 `node dist/cli/index.js <command>`，因为当前真实 CLI 入口是 `dist/cli/index.js`。
 - 需求澄清、影响分析、引用定位优先走 `query`、`analyze`、`deps`、`impact`，不要直接全仓漫游。
-- 修改 `analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+- 修改 `design`、`analyze`、`query`、`ci`、`workflow` 等高影响命令时，至少验证：
+  - `node dist/cli/index.js design validate mycodemap.design.md --json` 的成功/失败路径符合文档；
+  - `node dist/cli/index.js design map mycodemap.design.md --json` 的 success/blocker 路径、`candidates` / `unknowns` / `diagnostics` 与文档一致；
+  - `node dist/cli/index.js design handoff mycodemap.design.md --json` 的 `readyForExecution` / `approvals` / `assumptions` / `openQuestions` 与文档一致；
+  - `node dist/cli/index.js design verify mycodemap.design.md --json` 的 `checklist` / `drift` / `diagnostics` / `readyForExecution` 与文档一致，并保持 review-needed / blocker 分离语义；
   - `node dist/cli/index.js analyze --help` 与文档示例一致；
   - `find` / `read` / `link` / `show` 中受影响的 public intent 可以在当前仓库运行；
   - 若文档保留 legacy alias 说明，真实输出仍会返回 `warnings[]`；
   - 若涉及机器输出，`--json` 与 `--structured --json` 仍保持纯 JSON 契约。
 - 修改 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/OUTPUT.md`、`ARCHITECTURE.md` 这类入口文档时，必须明确区分“目标产品基线”和“当前 CLI 现实”，尤其是 `Server Layer` / `mycodemap server` 的命名边界。
-- 修改 `docs/product-specs/*` 现行规格时，必须同步 `docs/product-specs/README.md` 与 `scripts/validate-docs.js` 的高信号断言，避免规格正文和目录索引分叉。
+- 修改 `docs/product-specs/*` 现行规格时，必须同步 `docs/product-specs/README.md` 与 `scripts/validate-docs.js` 的高信号断言，避免规格正文和目录索引分叉；`docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md` 也属于这一约束。
 - 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
 - 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`；该命令会同时执行 docs guardrail 与 `sync-analyze-docs.js --check`。
 - `ci check-branch --allow` 支持 `*` 通配；在 CI / PR 环境中，分支识别会回退到 `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`。

package/docs/rules/validation.md

@@ -5,12 +5,13 @@
 1. 先验证与你改动最相关的命令、测试或模块。
 2. 若改动影响 agent 路由、CLI 示例、规则文档或测试事实，先执行 `npm run docs:check`。
 3. 若改动同时影响 CLI 护栏入口，再补 `node dist/cli/index.js ci check-docs-sync`；该命令会串联 docs guardrail 与 analyze generated block 校验。
-4. 若改动涉及 `analyze` canonical 示例、选项表或 `AI_GUIDE.md` 速查模板，优先用 `node scripts/sync-analyze-docs.js --check` 直接定位 generated block 漂移。
-5. 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
-6. 若改动涉及 `docs/product-specs/*` 的现行规格，确认 `docs/product-specs/README.md`、相关规格文档与 `scripts/validate-docs.js` 同步；当前 docs guardrail 会显式校验 MVP3 三份架构规格的 shipped baseline 表述。
-7. 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
-8. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
-9. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
+4. 若改动涉及 `design validate` / `design map` / `design handoff` / `design verify` 链路，确认 README、AI 文档、`docs/rules/*` 与 `scripts/validate-docs.js` 同步到同一条链：`design validate → design map → design handoff → design verify`，并显式区分 review-needed 与 blocker 退出语义。
+5. 若改动涉及 `analyze` canonical 示例、选项表或 `AI_GUIDE.md` 速查模板，优先用 `node scripts/sync-analyze-docs.js --check` 直接定位 generated block 漂移。
+6. 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
+7. 若改动涉及 `docs/product-specs/*` 的现行规格，确认 `docs/product-specs/README.md`、相关规格文档与 `scripts/validate-docs.js` 同步；当前 docs guardrail 会显式校验 MVP3 三份架构规格的 shipped baseline 表述。
+8. 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
+9. 再扩大到 `npm run typecheck`、`npm run lint`、`npm test`。
+10. 涉及发布或打包时，再执行 `npm run build` 与 `npm run validate-pack`。
 
 ## CI Gateway 验证流程
 
@@ -39,6 +40,7 @@ CI Gateway 已集成以下自动检查（按执行顺序）：
 - 手改 `README.md`、`docs/ai-guide/COMMANDS.md` 或 `AI_GUIDE.md` 的 `analyze` canonical 代码块 / 选项表 / 速查模板，却没同步 generated block → `node scripts/sync-analyze-docs.js --check` 失败。
 - 文档声称扫描类命令会尊重 `.gitignore`，但实现仍保留手写跳过规则 → `analyze` 与 `check-headers -d` 的文件集合漂移。
 - 把 `workflow` 重新扩回非分析阶段，却没同步 README / AI 命令文档 / guardrail 脚本 → `npm run docs:check` 失败。
+- 文档把 `design verify` 写成新的 workflow phase，或把 review-needed 路径写成 blocker failure → design docs 与命令退出语义漂移。
 - `docs/product-specs/README.md` 仍写“当前活跃产品规格暂为空”，但目录里已经有现行规格 → 目录索引与规格正文自相矛盾。
 - MVP3 规格文档继续把历史设计愿景写成当前现实（例如把 `neo4j`、14 种语言或公共 `server` 产品面写回去）→ `npm run docs:check` 失败。
 - `config-loader` 已支持 `storage`，但 schema / README / AI 文档没同步 → 用户能写配置，编辑器和 guardrail 却仍把它当非法字段。
@@ -50,6 +52,7 @@ CI Gateway 已集成以下自动检查（按执行顺序）：
 npm run docs:check
 node scripts/sync-analyze-docs.js --check
 node dist/cli/index.js ci check-docs-sync
+node dist/cli/index.js design verify mycodemap.design.md --json
 node dist/cli/index.js ci check-working-tree
 node dist/cli/index.js ci check-branch
 SHIP_IN_CI=1 node dist/cli/index.js ci check-scripts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mycodemap/mycodemap",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "TypeScript 代码地图工具 - 为 AI 辅助开发提供结构化上下文",
   "repository": {
     "type": "git",