@mycodemap/mycodemap 0.4.2 → 0.5.1

package/docs/eatdogfood-reports/2026-04-17-eatdogfood-agent-experience.md

@@ -0,0 +1,231 @@
+# CodeMap Eatdogfood 测试报告
+
+> 测试者身份：AI Agent（eatdogfood）  
+> 测试日期：2026-04-17  
+> 测试目标：用 CodeMap CLI 分析 CodeMap 自身，记录完整使用体验（尤其 Agent 视角）
+
+---
+
+## 1. 执行摘要
+
+本次测试以 AI Agent 的身份，完整体验了 CodeMap CLI 的**查询层**与**非查询层**能力。测试覆盖 10+ 命令，包含符号查询、依赖影响分析、代码地图生成、复杂度分析、循环依赖检测、CI 风险评估、设计契约验证/交接/漂移检测、工作流启动、Mermaid 导出等。
+
+**核心结论**：CodeMap 在"让 Agent 快速建立代码库心智模型"上表现优异，但部分命令在**参数一致性**和**零结果反馈**上仍有打磨空间。
+
+---
+
+## 2. 测试覆盖与结果
+
+### 2.1 查询与影响分析层
+
+| 命令 | 目标 | 结果 | Agent 评分 |
+|------|------|------|-----------|
+| `query -s "AnalyzeCommand"` | 查找符号定义 | 4 条精确结果，含 `kind`/`location`/`isExported` | ★★★★★ |
+| `deps -m "src/core/analyzer"` | 模块依赖关系 | 6 个依赖 + 6 个依赖者，带路径映射 | ★★★★★ |
+| `impact -f src/cli/commands/analyze.ts` | 文件变更影响面 | 33 个结果，自动区分 `source`/`test` | ★★★★★ |
+| `analyze -i read` | 高相关度文件摘要 | 人类友好，带 100%/95% 相关度 | ★★★★☆ |
+| `analyze -i link` | 架构关联映射 | 22 引用方/17 关联目标，`riskLevel: high` | ★★★★☆ |
+| `analyze -i show` | 模块导出摘要 | 导出 4 符号，依赖 17 模块 | ★★★★☆ |
+| `analyze -i find` | 关键词发现 | 对单文件路径 confidence 仅 0.04 | ★★☆☆☆ |
+| `history --symbol` | Git 历史与风险 | 返回 symbolId/moduleId/exactNameMatch | ★★★★★ |
+
+### 2.2 非查询层（生成、分析、工程、工作流）
+
+| 命令 | 目标 | 结果 | Agent 评分 |
+|------|------|------|-----------|
+| `generate -m fast` | 生成代码地图 | 242 模块/958 导出符号/62482 行，成功 | ★★★★★ |
+| `complexity src/cli/commands/analyze.ts` | 代码复杂度 | **指定文件后仍返回全量 79KB JSON** | ★★☆☆☆ |
+| `cycles` | 循环依赖检测 | `hasCycles: false`，架构健康 | ★★★★★ |
+| `ci assess-risk` | 变更风险评估 | score=0.05（low），threshold=0.50，通过 | ★★★★☆ |
+| `design validate` | 设计契约校验 | 有效 doc ✅，无效 doc ❌ 并列出缺失 section | ★★★★★ |
+| `design map` | 设计范围映射 | 无设计文档时 `blocked: true`，检测准确 | ★★★★★ |
+| `design handoff` | 生成交接包 | 生成 `.mycodemap/handoffs/` 含 touchedFiles/tests/risks | ★★★★★ |
+| `design verify` | 验证设计漂移 | 发现 5 处 drift，3 项待 review | ★★★★★ |
+| `check --contract ...` | 契约门禁检查 | `passed: true`，diff scope 从 1 扩展到 3 文件 | ★★★★☆ |
+| `export mermaid` | 导出依赖图 | 242 模块，7.1KB Mermaid 文件，成功 | ★★★★★ |
+| `workflow start` | 启动分析工作流 | 生成 workflow ID，推荐 `refactoring` 模板 | ★★★★☆ |
+
+---
+
+## 3. Agent 视角的使用体验（重点）
+
+### 3.1 Agent 的核心痛点：上下文是有限的，噪音是致命的
+
+作为 AI Agent，我在分析代码库时最大的约束不是计算能力，而是**上下文窗口**。当使用传统工具链（`grep` + `read`）分析 `src/cli/commands/analyze.ts` 的影响面时：
+
+- 3 次 Grep 返回约 **92 条文件引用**
+- 混入 `.planning/`、`.claude/`、`docs/archive/` 等 20+ 文档噪音
+- `src/orchestrator/result-fusion.ts` 被误抓——实际并未导入 `analyze.ts`，只是文本中出现了 "analyze"
+
+为了排除误报，我不得不**逐个 Read 文件验证**。这个过程消耗了大量 token，而且结果仍需要我手动去重、分类。
+
+而使用 `impact -f` 时：
+- **1 次调用**
+- **33 条精准结果**
+- **0 条文档噪音**
+- **自动标记 `source` / `test`**
+
+这不仅是"快"，而是从"猜测-验证"模式切换到了"直接获取答案"模式。
+
+### 3.2 哪些命令是 Agent 的"高信号工具"
+
+以下命令对 Agent 来说是**高 ROI**的，应优先集成到 Agent 工作流中：
+
+1. **`impact -f`** → 重构前的必备步骤。自动分类测试文件，让 Agent  instantly 知道"改完要跑哪些测试"。
+2. **`deps -m`** → 理解模块边界。比文本搜索 `import` 更准确，因为它基于解析后的依赖图。
+3. **`query -s`** → 符号导航。不仅找定义，还找重导出和关联函数，是 Agent 定位代码的 GPS。
+4. **`design validate` / `design map` / `design handoff`** → 设计驱动开发的三件套。Agent 可以在动手写代码前验证设计文档是否完整，生成交接包后按图施工。
+5. **`ci assess-risk`** → 在 Plan 阶段给变更打分。Agent 可以根据风险分数决定是否建议人类审查。
+6. **`generate`** → 建立项目基线。Agent 可以在任务开始时生成代码地图，后续所有查询都在这个基线上进行。
+
+### 3.3 哪些体验会打断 Agent 的自主性
+
+以下问题会迫使 Agent 从"自动执行"退回"试探-纠错"模式：
+
+#### 问题 A：`--json` 支持不统一
+
+```bash
+# 这些命令支持 --json ✅
+query -s, deps -m, impact -f, design validate, design map, design handoff, design verify, check, cycles
+
+# 这些命令不支持 --json ❌
+history --symbol, ci assess-risk, workflow start
+```
+
+对 Agent 来说，JSON 是**机器可解析的默认语言**。当某些命令不支持 `--json` 时，Agent 需要额外处理人类可读输出，增加解析失败的风险。
+
+#### 问题 B：`complexity` 指定文件仍返回全量
+
+我执行了：
+```bash
+node dist/cli/index.js complexity src/cli/commands/analyze.ts --json
+```
+
+但它返回了**所有 242 个文件**的复杂度数据（79KB）。对 Agent 来说，这意味着：
+- 大量无关信息挤占上下文
+- 需要自行过滤目标文件
+- 命令参数语义与行为不一致
+
+#### 问题 C：`check` / `ci assess-risk` 的静默通过
+
+当 `check` 检测到文件没有对应设计文档时，输出为空；`ci assess-risk` 输出纯文本但没有结构化分数字段。Agent 很难判断：
+- 这是"通过"还是"跳过"？
+- 状态码 0 是否代表一切正常？
+
+#### 问题 D：`analyze -i find` 对显式文件路径 confidence 过低
+
+```bash
+node dist/cli/index.js analyze -i find src/core/analyzer.ts --json
+# confidence: 0.04, results: []
+```
+
+当 Agent 已经精确指定了文件路径，工具却以低置信度返回空结果，这会让 Agent 怀疑自己的输入是否正确，从而触发不必要的 fallback 逻辑。
+
+### 3.4 Agent 最喜欢的设计细节
+
+1. **`impact` 的 `source` / `test` 分类**
+   这不是 UI 装饰，而是直接影响 Agent 决策的结构化信息。Agent 可以立刻生成测试计划："需要验证的测试文件：X, Y, Z"。
+
+2. **`design verify` 的 `driftCount` 和 `needsReviewCount`**
+   让 Agent 可以量化设计文档的"健康度"。`driftCount: 5` 意味着 Agent 应该优先提醒人类审查，而不是继续自动执行。
+
+3. **`check` 的 `scan_mode: diff` 和 scope 扩展警告**
+   ```json
+   { "code": "diff-scope-expanded", "message": "diff scope 从 1 个 changed file 扩展到 3 个 scanned file" }
+   ```
+   这让 Agent 理解契约检查的边界——它不是只看你改的那一行，而是会智能扩展到关联文件。
+
+4. **`history` 的 symbolId / moduleId**
+   虽然不支持 `--json`，但默认输出就是 JSON，而且带稳定的标识符。Agent 可以跟踪同一个符号在不同 commit 中的演变。
+
+---
+
+## 4. 对照实验：用 vs 不用 CodeMap
+
+**问题**：修改 `src/cli/commands/analyze.ts` 中的 `AnalyzeCommand`，会影响哪些文件？
+
+### 不用 CodeMap（传统路径）
+
+| 步骤 | 工具 | 结果 | 问题 |
+|------|------|------|------|
+| 1 | `grep "AnalyzeCommand"` | 18 个文件 | 混入了大量文档和历史文件 |
+| 2 | `grep "from.*analyze"` | 45 个文件 | 包含 `.claude/`、`.planning/` 噪音 |
+| 3 | `grep "import.*analyze"` | 29 个文件 | 仍有误报（如 `result-fusion.ts`） |
+| 4 | `Read` 验证 | 3+ 次 | 确认哪些是真依赖 |
+| 5 | 手动分类 | - | 测试文件和源码混在一起 |
+
+**总计**：6 次工具调用，~92 条引用（大量重复/噪音），需人工去重验证。
+
+### 用 CodeMap
+
+```bash
+node dist/cli/index.js impact -f src/cli/commands/analyze.ts --json
+```
+
+**结果**：1 次调用，33 条精准结果，0 噪音，自动分类 source/test。
+
+### 差距总结
+
+| 维度 | 不用 CodeMap | 用 CodeMap |
+|------|-------------|-----------|
+| 调用次数 | 6+ | **1** |
+| 结果量 | ~92 条 | **33 条** |
+| 噪音混入 | 20+ 文档/历史文件 | **0** |
+| 误报率 | 高（文本匹配） | **0** |
+| 测试/源码分类 | 手动 | **自动** |
+| Token 消耗 | 高 | **低** |
+
+---
+
+## 5. 发现的问题与改进建议
+
+### 5.1 高优先级（影响 Agent 自主性）
+
+| 问题 | 影响 | 建议 |
+|------|------|------|
+| `--json` 支持不统一 | Agent 需要为不同命令写不同解析器 | 所有命令统一支持 `--json`，或默认输出机器可读格式 |
+| `complexity` 指定文件仍返回全量 | 上下文爆炸 | 当提供文件参数时，只返回指定文件的复杂度 |
+| `check` / `ci assess-risk` 静默通过 | Agent 无法区分"通过"和"未执行" | 始终输出一条状态摘要，如 `status: passed` / `status: skipped` |
+| `analyze -i find` 对显式路径 confidence 过低 | Agent 会怀疑输入正确性 | 对绝对/相对文件路径提升 confidence 权重 |
+
+### 5.2 中优先级（体验优化）
+
+| 问题 | 影响 | 建议 |
+|------|------|------|
+| `generate` 默认输出到 `.mycodemap` | Agent 可能需要区分不同任务的结果 | 支持 `--task-id` 后缀或子目录 |
+| `workflow` 不支持 `--json` | 难以自动化驱动工作流 | 支持 `--json` 和 `--auto-proceed` |
+| RTK `Filters NOT applied` 警告 | 每次命令都出现，干扰输出 | 在 CI/Agent 模式下可静默 |
+
+---
+
+## 6. 结论
+
+### 对 Agent 来说，CodeMap 的价值是什么？
+
+CodeMap 把 AI Agent 从"**在代码海里钓鱼**"变成了"**直接拿到导航图**"。
+
+- **`impact`** 让 Agent 在改代码前就知道"会打翻哪些盘子"
+- **`design validate/handoff/verify`** 让 Agent 能参与设计驱动流程，而不是盲目写代码
+- **`ci assess-risk`** 让 Agent 具备风险意识，知道什么时候该停下来叫人类审查
+- **`generate` + `export`** 让 Agent 能把代码库结构转换成各种可消费格式
+
+### 当前的短板是什么？
+
+最大的短板不是功能缺失，而是**"Agent 接口的一致性"**。
+
+当 Agent 调用 10 个命令时，如果有 3 个不支持 `--json`、1 个忽略文件参数、2 个静默通过，Agent 的可靠性就会从"自动驾驶"降级为"辅助驾驶"。
+
+### 最终评分
+
+| 维度 | 评分 | 说明 |
+|------|------|------|
+| 查询精准度 | 9/10 | `query`/`deps`/`impact` 非常可靠 |
+| 非查询能力 | 8/10 | 生成/设计/CI/导出能力完整 |
+| Agent 友好度 | 6/10 | `--json` 不一致和部分命令 UX 影响自动化 |
+| 整体推荐度 | 8/10 | **值得作为 Agent 工具链的核心组件**，但需要修复接口一致性问题 |
+
+---
+
+**测试执行者**：Claude (AI Agent)  
+**测试对象**：CodeMap CLI v当前版本（基于 `main` 分支构建）  
+**报告生成时间**：2026-04-17

package/docs/exec-plans/completed/2026-04-17-eatdogfood-codemap-cli.md

@@ -0,0 +1,103 @@
+# 2026-04-17 eatdogfood：CodeMap CLI 项目内自试用记录
+
+## 1. 任务定义
+
+- [证据] **目标**：以真实使用者（eatdogfood）的身份，在当前仓库里直接使用项目自己的 CLI 做一次最小闭环试用，覆盖 `generate`、`query`、`analyze`、`deps`、`impact`，并记录体验、失败模式与后续建议。公开命令面与 AI/Agent 的推荐入口已在 `README.md:10`、`README.md:11`、`README.md:25`、`README.md:28`、`AI_GUIDE.md:47`、`AI_GUIDE.md:49`、`AI_GUIDE.md:51`、`AI_GUIDE.md:52`、`AI_GUIDE.md:54` 说明。
+- [证据] **限制条件**：当前仓库的默认配置只扫描 `src/**/*.ts`，排除 `dist/**`、`build/**`、测试文件，输出目录为 `.mycodemap`，因此本次 dogfood 以源码主干为主，不把构建产物视为正常分析对象。见 `mycodemap.config.json:3`、`mycodemap.config.json:4`、`mycodemap.config.json:7`、`mycodemap.config.json:8`、`mycodemap.config.json:9`、`mycodemap.config.json:10`、`mycodemap.config.json:12`。
+- [证据] **验收标准**：至少形成一次“生成 → 查询 → 阅读 → 依赖 → 影响”的真实操作链；至少记录一个失败场景；结果落到 `docs/exec-plans/` 以满足“目标、限制、DoD、风险、复盘”边界。目录职责见 `docs/exec-plans/README.md:3`、`docs/exec-plans/README.md:7`、`docs/exec-plans/README.md:8`、`docs/exec-plans/README.md:22`、`docs/exec-plans/README.md:23`、`docs/exec-plans/README.md:24`。
+- [证据] **依赖关系**：本仓库 `bin` 已指向 `dist/cli/index.js`，且 `build` 脚本为 `tsc`，说明可以直接基于已构建 CLI 运行体验测试。见 `package.json:15`、`package.json:16`、`package.json:17`、`package.json:29`、`package.json:30`。
+
+## 2. 操作过程
+
+### 2.1 入口确认
+
+- [证据] 先用 `node dist/cli/index.js --help` 确认当前公共命令，结果与 README/AI 指南一致：存在 `generate`、`query`、`deps`、`impact`、`analyze` 等入口；这与 `README.md:10`、`README.md:28`、`docs/ai-guide/COMMANDS.md:12`、`docs/ai-guide/COMMANDS.md:46`、`docs/ai-guide/COMMANDS.md:74`、`docs/ai-guide/COMMANDS.md:91` 一致。
+- [观点] 这一步体验是“入口比较完整，但用户需要自己决定该先用 `query` 还是 `analyze`”；对于第一次上手的人，命令多不一定是优势。
+
+### 2.2 生成代码地图
+
+- [证据] 执行命令：`rtk node dist/cli/index.js generate`
+- [证据] 实际输出显示：扫描 242 个文件、62482 行代码、242 个模块、958 个导出符号，并写出 `AI_MAP.md`、`codemap.json`、`dependency-graph.md` 与 `context/`。
+- [推论] 这一步与文档承诺基本一致：README 明确把 `generate` 作为第一步，并说明输出 `.mycodemap/AI_MAP.md`、`codemap.json`、`dependency-graph.md` 等文件，见 `README.md:58`、`README.md:59`、`README.md:61`、`README.md:62`、`README.md:66`、`README.md:67`；命令参考也把 `.mycodemap` 作为默认输出目录，见 `docs/ai-guide/COMMANDS.md:15`、`docs/ai-guide/COMMANDS.md:25`。
+- [观点] 这一步是本次体验里“最稳”的一环：执行路径短、反馈明确、产物可见，能快速建立信心。
+
+### 2.3 符号与模块查询
+
+- [证据] 执行命令：`node dist/cli/index.js query --search CodeMapServer --limit 5 --json --structured`
+- [证据] 返回 3 个结果：`src/server/CodeMapServer.ts` 模块、`CodeMapServer` 类导出、`src/server/index.ts` 里的 `CodeMapServer` 变量导出。
+- [证据] 执行命令：`node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured`
+- [证据] 返回 1 个结果：`src/interface/types/index.ts` 中导出的 `SourceLocation` 接口。
+- [推论] `query` 基本符合 AI 指南里“查定义/查相关代码”的定位：`query -s "XXX"` 用于找定义，`query -S "XXX"` 用于模糊检索，见 `AI_GUIDE.md:50`、`AI_GUIDE.md:54`、`docs/ai-guide/COMMANDS.md:49`、`docs/ai-guide/COMMANDS.md:52`、`docs/ai-guide/COMMANDS.md:65`、`docs/ai-guide/COMMANDS.md:66`。
+- [观点] 如果我是第一次接触项目的 agent，我会优先保留 `query`，因为它给我的“是否找到了东西”的反馈最直接。
+
+### 2.4 read / link / show
+
+- [证据] 执行命令：`node dist/cli/index.js analyze -i read -t src/server/CodeMapServer.ts --scope direct --include-git-history --json --structured`
+- [证据] 返回 `confidence.score = 0.8`、`level = high`、`results.length = 7`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i read -t src/interface/types/index.ts --scope direct --json --structured`
+- [证据] 返回 `confidence.score = 0.8`、`results.length = 8`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i link -t src/server --json --structured`
+- [证据] 返回 `confidence.score = 0.6`、`level = medium`、`resultCount = 2`。
+- [证据] 执行命令：`node dist/cli/index.js analyze -i show -t src/server --output-mode human`
+- [证据] 人类输出中直接给出 `src/server/CodeMapServer.ts:1`，并提示“导出 1 个符号，依赖 11 个模块，相关度 75.0%”。
+- [推论] `analyze` 的 `read/show` 路径能跑通，且与 README 中“`analyze` 支持 human/machine 模式”的承诺一致，见 `README.md:25`、`README.md:74`、`README.md:75`、`docs/ai-guide/COMMANDS.md:6`。
+- [观点] `show` 的人类输出有“开箱即看”的味道，比结构化 JSON 更像产品；但它的 discoverability 仍然依赖文档，不是 CLI 自解释。
+
+### 2.5 deps / impact
+
+- [证据] 执行命令：`node dist/cli/index.js deps -m src/server/CodeMapServer.ts --json --structured`
+- [证据] 返回结果显示：`src/server/CodeMapServer.ts` 直接依赖 11 个模块，前 5 个外部依赖是 `hono`、`@hono/node-server`、`hono/cors`、`hono/logger`、`hono/pretty-json`。
+- [证据] 执行命令：`node dist/cli/index.js impact -f src/server/CodeMapServer.ts --transitive --json --structured`
+- [证据] 返回结果显示：直接影响 6 个依赖方，统计字段中传递影响规模为 217。
+- [推论] 这与 AI 指南中“依赖看 `deps`、影响看 `impact -t -j`”的建议一致，见 `AI_GUIDE.md:51`、`AI_GUIDE.md:52`、`docs/ai-guide/COMMANDS.md:74`、`docs/ai-guide/COMMANDS.md:91`、`docs/ai-guide/COMMANDS.md:95`、`docs/ai-guide/COMMANDS.md:101`。
+- [观点] 这一步很像真实开发者决策前的“最后一跳”：如果我要改 `CodeMapServer`，这两个命令能快速告诉我“依赖谁”和“谁会被我炸到”。
+
+## 3. 失败预演与实际失败案例
+
+### 3.1 实际失败案例：`analyze -i find` 失准
+
+- [证据] 执行命令：`node dist/cli/index.js analyze -i find -k SourceLocation --json --structured`
+- [证据] 标准输出返回：`confidence.score = 0.04`、`level = low`、`resultCount = 0`。
+- [证据] 同一次执行的标准错误包含 `ast-grep scan 命令失败: SyntaxError`，错误内容直接打印了 TypeScript 语法（例如 `filePath: string`、`Promise<string>` 等），说明底层扫描器在解析 TS 文件时发生失败。
+- [证据] 对照组 1：`rtk grep 'SourceLocation' src tests docs --glob '!dist/**' --glob '!node_modules/**'` 能在 10 个文件里找到 37 处匹配。
+- [证据] 对照组 2：`node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured` 能稳定返回 `src/interface/types/index.ts` 中的 `SourceLocation`。
+- [推论] 这不是“仓库里没有该符号”，而是 `analyze find` 的实现/回退链有缺口：同一个关键词，基础文本检索与 `query` 都能命中，唯独 `analyze find` 在报扫描错误后给出空结果。
+- [观点] 这是本次 dogfood 最大的问题：它会让用户误以为“没有结果”，而不是“工具在部分路径上坏了”。
+
+### 3.2 风险模式
+
+- [推论] 风险模式 1：**静默降级**。命令虽然打印了 stderr，但仍然返回结构化空结果；如果调用方只读 stdout，就会把失败误判成“安全的 0 命中”。
+- [推论] 风险模式 2：**命令选择误导**。`AI_GUIDE.md:54` 把“查找与 XXX 相关的代码”推荐为 `query -S "XXX" -j`，这次反而证明它比 `analyze -i find` 更可靠；若未来文档把 find/promoted workflow 放在更前面，可能会扩大误导面。
+- [推论] 风险模式 3：**配置与实现不一致**。`mycodemap.config.json:7`、`mycodemap.config.json:8` 明确排除了 `dist/**`、`build/**`，但扫描错误里出现了对不兼容语法的解析失败，说明 analyze 链路可能没有完全复用 generate/query 那套“配置感知 + 忽略规则”。
+
+## 4. 心得和感受
+
+- [观点] **好感点**：`generate`、`query`、`deps`、`impact` 组合起来，已经足以支持“先建图、再定位、再评估改动范围”的真实工作流；对 agent 很实用。
+- [观点] **不满点**：`analyze` 想做统一入口，但当前可靠性不如专用命令；这让“统一入口”变成概念上更高级、实际体验上更脆弱。
+- [观点] **对立面质疑**：如果产品前提是“让 AI/Agent 通过统一结构化入口稳定拿到代码上下文”，那 `find` 返回空且不 hard fail 就已经触碰产品底线；这不是小瑕疵，而是信任问题。
+- [观点] **作为 eatdogfood 的主观感受**：我愿意继续用这个工具，但会形成一个保守习惯——先用 `generate + query`，把 `analyze find` 当成实验功能，而不是主路径。
+
+## 5. 结论与建议
+
+- [推论] **短期建议**：把 `query -S` 继续作为默认查找路径，对 `analyze -i find` 增加显式失败状态或 warning 升级，避免“空结果伪装成功”。
+- [推论] **中期建议**：检查 `analyze` 是否复用了与 `generate/query` 一致的 include/exclude 与 TypeScript 解析策略，优先消除“配置写了排除、实际扫描没排除”的偏差。
+- [推论] **长期建议**：让 `analyze` 只做 orchestration，不再偷偷切到不稳定的底层扫描器；或者至少在 JSON 结果里暴露 `partialFailure` 字段。
+
+## 6. 文档同步判断
+
+- [证据] 本次没有修改 CLI 契约、配置项、输出格式、架构边界，因此不触发 README / AI_GUIDE / COMMANDS / OUTPUT 的强制同步条件；触发条件定义见 `AGENTS.md:151`、`AGENTS.md:152`、`AGENTS.md:153`、`AGENTS.md:158`、`AGENTS.md:160`。
+- [证据] 本次新增的是执行复盘与缺陷记录，符合 `docs/exec-plans/` 与 `.codemap/issues/` 的用途，不属于产品文档失真修复。
+
+## 7. 本次使用的命令清单
+
+- [证据] `rtk node dist/cli/index.js generate`
+- [证据] `node dist/cli/index.js query --search CodeMapServer --limit 5 --json --structured`
+- [证据] `node dist/cli/index.js query --search SourceLocation --limit 10 --json --structured`
+- [证据] `node dist/cli/index.js analyze -i read -t src/server/CodeMapServer.ts --scope direct --include-git-history --json --structured`
+- [证据] `node dist/cli/index.js analyze -i read -t src/interface/types/index.ts --scope direct --json --structured`
+- [证据] `node dist/cli/index.js analyze -i link -t src/server --json --structured`
+- [证据] `node dist/cli/index.js analyze -i show -t src/server --output-mode human`
+- [证据] `node dist/cli/index.js deps -m src/server/CodeMapServer.ts --json --structured`
+- [证据] `node dist/cli/index.js impact -f src/server/CodeMapServer.ts --transitive --json --structured`
+- [证据] `node dist/cli/index.js analyze -i find -k SourceLocation --json --structured`
+- [证据] `rtk grep 'SourceLocation' src tests docs --glob '!dist/**' --glob '!node_modules/**'`

package/docs/ideation/2026-04-15-executable-architecture-constitution-ideation.md

@@ -0,0 +1,102 @@
+---
+date: 2026-04-15
+topic: executable-architecture-constitution
+focus: Pivot CodeMap to an "Executable Architecture Constitution" — making design.md a diff-aware, git-history-risk-weighted, CI-enforceable gate
+---
+
+# Ideation: Executable Architecture Constitution
+
+## Codebase Context
+
+**Project**: CodeMap — TypeScript CLI tool that generates structured code context for AI/Agents (dependency graphs, symbol maps, etc.). Currently pivoting from "AI code map tool" to "Executable Architecture Constitution" — an architecture contract governance engine.
+
+**Key Assets**:
+- MVP3 6-layer architecture is enforced (Interface → Infrastructure → Domain → Server → CLI)
+- `design validate/map/handoff/verify` commands already exist with full JSON output contracts
+- `docs/backlog.md` contains a v0.6 product重塑提案 to pivot to "architecture contract validation & guardrail system"
+- Historical CI gateway exists (`codemap ci check-commits`, `check-headers`, `assess-risk`) but some are archived
+- Git risk analyzer was designed and archived (GRAVITY/HEAT/IMPACT scoring formula exists in `src/orchestrator/workflow/git-analyzer.ts` but is dormant)
+- Storage is currently KùzuDB; proposal suggests migrating to `better-sqlite3` + in-memory directed graph
+- Tree-sitter parser exists for TS/Go/Python
+- Current `design verify` only checks handoff drift; it does NOT scan actual `src/` code against architecture rules
+
+**Pain Points**:
+- `src/core/` and `src/parser/` migration debt
+- Multiple temp output dirs
+- Docs-sync pressure
+- No diff-aware incremental validation exists yet
+
+## Ranked Ideas
+
+### 1. Diff-Aware Contract Enforcement
+**Description:** Upgrade `mycodemap verify` into a true contract enforcer that scans `src/` code. By default, only validate files touched by `git diff` and their dependency chains. Return non-zero exit codes when `layer_direction`, `forbidden_imports`, or `module_public_api_only` rules are violated.
+**Rationale:** This is the core product soul of the pivot. Today `design verify` only checks handoff drift and never touches source code — creating a dangerous false sense of security for users.
+**Downsides:** Bridging design.md's text constraints with tree-sitter symbol extraction requires careful engineering for the first rule.
+**Confidence:** 90%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 2. SQLite + In-Memory Graph Storage Migration
+**Description:** Remove the KùzuDB adapter and replace it with `better-sqlite3` for persisting symbol relationships, plus a lightweight in-memory directed graph (Map/Set adjacency list) loaded at startup. The same storage layer should handle code graphs, git blame history, and contract metadata.
+**Rationale:** KùzuDB installation failures are the top onboarding friction. SQLite's single-file nature turns CodeMap into a version-controllable CLI tool rather than a system requiring database ops.
+**Downsides:** Must validate startup time and memory footprint against large codebases (target: <1s for 10K files, <200MB RAM).
+**Confidence:** 85%
+**Complexity:** Medium-High
+**Status:** Unexplored
+
+### 3. Revive Git History Risk Scoring (GRAVITY/HEAT/IMPACT)
+**Description:** Harden the existing but dormant `calculateRiskScore` in `src/orchestrator/workflow/git-analyzer.ts` and rewire the GRAVITY/HEAT/IMPACT three-dimensional model into `verify` and `impact` outputs.
+**Rationale:** Competitors cannot replicate the causal narrative of "who changed this block, what regressions this dependency chain caused before." The formula is already designed — it just needs to be wired up.
+**Downsides:** Requires high-quality historical data (rollbacks, incident correlations); young codebases may have weak signal.
+**Confidence:** 80%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 4. Auto-Generate design.md from Existing Codebase
+**Description:** Instead of asking humans to write `design.md` from scratch, use the existing tree-sitter parser to scan `src/` for module boundaries and public APIs, then generate a baseline contract. Users only review and lock it.
+**Rationale:** Eliminates the root cause of "docs vs code divergence." If contract generation cost approaches zero, maintenance cost collapses too.
+**Downsides:** Auto-generated rules may be too permissive or capture too many implementation details; needs smart UX to "lock" which rules matter.
+**Confidence:** 75%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 5. Auto-Generate Architecture Remediation Patches
+**Description:** When `verify` finds a module boundary violation, don't just report it — generate a concrete refactoring patch (e.g., "move this import down to the adapter layer").
+**Rationale:** In the AI era, "errors without fixes" is a half-measure. This was also highlighted in Codex's second opinion as a core element of the coolest version.
+**Downsides:** Requires semantic understanding beyond import graphs; fully automated fixes risk introducing bugs.
+**Confidence:** 65%
+**Complexity:** High
+**Status:** Unexplored
+
+### 6. Self-Healing Design Contract (Drift Approval)
+**Description:** Allow `design.md` to evolve with the code through an approval workflow. When drift is detected, provide `codemap design evolve --approve` to snapshot current code boundaries back into the contract as the new baseline.
+**Rationale:** Architecture decay is an organizational norm. If contracts forever forbid drift, they get abandoned. A reviewable, approvable evolution mechanism is the only way they survive long-term.
+**Downsides:** Requires strict versioning and multi-level approval, otherwise it becomes a channel for "legitimizing tech debt."
+**Confidence:** 70%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 7. MCP `verify_contract` Tool
+**Description:** Wrap the `design verify` JSON output contract as an MCP Server tool for Claude Code / Cursor to call before every code modification.
+**Rationale:** Minimal engineering investment for maximum ecosystem leverage. Transforms CodeMap from "a CLI developers remember to run" into "infrastructure AI calls by default."
+**Downsides:** The MCP ecosystem is still early; interface standardization may shift.
+**Confidence:** 85%
+**Complexity:** Low
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | Zero-config CI Gateway | Too narrow; essentially a packaging simplification of existing `ci` subcommands, not a strategic improvement |
+| 2 | Auto-sync docs guardrail | High engineering complexity for low leverage; contributes marginally to the pivot's core value |
+| 3 | Architecture-as-Test-Suite | Functionally duplicates #1 with a different shape (Vitest vs CLI); drifts from CodeMap's CLI-native identity |
+| 4 | GitHub Action as the only interface | Radical but too costly; conflicts with existing CLI investment and user base |
+| 5 | Risk-weighted soft gate | Historically explored; soft thresholds rarely change developer behavior in practice |
+| 6 | Commit message as architecture signal | Over-relies on LLM inference; high cost and unpredictable signal quality |
+| 7 | TypeScript-only deep constitution | Strategic but would discard existing Go/Python parser work; unclear cost/benefit |
+| 8 | One-shot removal of core/parser debt | A refactoring task, not a product improvement idea |
+
+## Session Log
+
+- 2026-04-15: Initial ideation — ~40 candidates generated across 4 frames, 7 survived after adversarial filtering

package/docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md

@@ -0,0 +1,126 @@
+# 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 自行猜测。
+
+## Frontmatter Rules
+
+把可执行规则写在文件开头的 YAML frontmatter 中。当前 Phase 25 只支持三种规则：
+
+- `layer_direction`
+- `forbidden_imports`
+- `module_public_api_only`
+
+```yaml
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+  - type: forbidden_imports
+    name: "parser 禁止直接引用 fs"
+    module: "src/infrastructure/parser/**"
+    forbidden:
+      - fs
+      - path
+    severity: warn
+  - type: module_public_api_only
+    name: "domain 模块对外仅暴露 index.ts"
+    module: "src/domain/**"
+    public_api: "index.ts"
+    severity: error
+---
+```
+
+## Copy-Paste Template
+
+```markdown
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+---
+# Design Contract: <feature name>
+
+## Goal
+- 这个 feature 最终要解决什么问题？
+- 用户或团队为什么需要它？
+
+## Constraints
+- 必须兼容的现有命令、接口或目录边界
+- 不允许改动的模块 / 风险限制 / 时间限制
+
+## Acceptance Criteria
+- [ ] 可验证结果 1
+- [ ] 可验证结果 2
+- [ ] 可验证结果 3
+
+## Non-Goals
+- 这次明确不做什么
+- 哪些相关问题留到后续 phase
+
+## Context
+- 当前实现现状
+- 相关文件 / 模块 / 文档
+
+## Open Questions
+- 需要人类确认的问题 1
+
+## Notes
+- 其他补充信息
+```
+
+## Minimal Example
+
+```markdown
+---
+rules:
+  - type: layer_direction
+    name: "core 不可依赖 cli"
+    from: "src/core/**"
+    to: "src/cli/**"
+    severity: error
+---
+# 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/MVP3-ARCHITECTURE-COMPARISON.md

@@ -22,7 +22,7 @@
 |------|--------|----------------|
 | CLI | 多个命令直接碰核心实现 | 公共 CLI 收口为分析优先的命令面，命名边界清晰 |
 | Server Layer | 设计概念模糊，易与公共 `server` 命令混淆 | `src/server/` 保留为**内部架构层**；公共 `server` 命令已移除 |
-| Storage | 以文件输出为中心，图存储路径不稳定 | `filesystem` / `memory` / `kuzudb` / `auto` 为正式 surface；`neo4j` 已退出正式支持 |
+| Storage | 以文件输出为中心，图存储路径不稳定 | `filesystem` / `memory` / `sqlite` / `auto` 为正式 surface；`neo4j` 与 `kuzudb` 已退出正式支持 |
 | Parser | 以 TypeScript 逻辑为主，扩展能力弱 | `ParserRegistry` + `TypeScript/JavaScript`、`Go`、`Python` 三类已落地实现 |
 | Workflow | 设计上曾试图扩到更多工程阶段 | 当前公开能力仅保留 analysis-only：`find → read → link → show` |
 | Docs / CI | 文档与实现容易漂移 | `docs:check` + `ci check-docs-sync` + CI gateway 固定当前契约 |
@@ -68,7 +68,7 @@ Domain Layer (`src/domain/`)
   └─ 面向业务模型，不直接暴露 CLI 细节
 
 Infrastructure Layer (`src/infrastructure/`)
-  ├─ storage: FileSystem / Memory / KùzuDB
+  ├─ storage: FileSystem / SQLite / Memory
   ├─ parser: TypeScript(JS) / Go / Python
   └─ repositories / shared graph helpers
 
@@ -80,7 +80,7 @@ Interface Layer (`src/interface/`)
 ### 当前架构要点
 
 - `Server Layer` 是内部架构层，不等于公共 `mycodemap server`
-- 图存储正式产品面已收敛为 Kùzu-only 主线，不再把 `neo4j` 当成受支持 backend
+- 图存储正式产品面已收敛为 `filesystem` / `sqlite` / `memory` / `auto`；旧 `neo4j` / `kuzudb` 配置只保留迁移诊断
 - `workflow` 是公开能力，但仅编排分析阶段，不再混入实现/提交/CI 阶段
 
 ---
@@ -103,7 +103,7 @@ await fs.writeFile(path.join(outputDir, 'AI_MAP.md'), markdown);
 ### After：存储契约已稳定，但产品面已收敛
 
 ```typescript
-export type StorageType = 'filesystem' | 'kuzudb' | 'memory';
+export type StorageType = 'filesystem' | 'sqlite' | 'memory';
 
 export interface StorageConfig {
   type: StorageType | 'auto';
@@ -118,10 +118,11 @@ export interface StorageConfig {
 
 当前事实：
 
-- **正式支持**：`filesystem`、`memory`、`kuzudb`、`auto`
-- **不再正式支持**：`neo4j`
-- **迁移语义**：旧 `neo4j` 配置会返回显式错误，不会静默 fallback
-- **`auto` 现状**：配置面存在，但当前仍保守落到 `filesystem`；阈值字段是契约，不代表已完成智能切换
+- **正式支持**：`filesystem`、`memory`、`sqlite`、`auto`
+- **不再正式支持**：`neo4j`、`kuzudb`
+- **迁移语义**：旧 `neo4j` / `kuzudb` 配置会返回显式错误，不会静默 fallback
+- **`auto` 现状**：配置面存在，当前优先选择 `sqlite`；仅当 SQLite 运行时不可用时 warning 后回退 `filesystem`
+- **SQLite runtime**：显式 `sqlite` 需要 `better-sqlite3` + Node.js `>=20`；否则返回 `SQLITE_NOT_AVAILABLE`
 
 ---
 
@@ -209,7 +210,7 @@ mycodemap ci check-docs-sync
 | 能力 | 当前状态 |
 |------|----------|
 | `neo4j` 正式支持 | 已移除出正式产品面 |
-| 更丰富的自动后端切换启发式 | 仍 deferred；`auto` 当前保守落到 `filesystem` |
+| 更丰富的自动后端切换启发式 | 仍 deferred；`auto` 当前优先选择 `sqlite`，仅在 SQLite 不可用时回退 `filesystem` |
 | Java / Rust / C/C++ 等更多 parser 实现 | 接口预留，未作为当前 shipped reality |
 | `viz` / `tui` / CLI 可视化套件 | 未作为当前 public CLI 基线交付 |
 | 公共 HTTP API / `mycodemap server` 产品面 | 未开放；`Server Layer` 仍是 internal-only |
@@ -221,7 +222,7 @@ mycodemap ci check-docs-sync
 `MVP3` 的核心价值已经从“理想化设计图”收口成了当前可验证的产品基线：
 
 - 5 层架构已在目录结构与职责边界上落地
-- 存储面已稳定为 Kùzu-only 主线
+- 存储面已稳定为 `filesystem` / `sqlite` / `memory` / `auto` 四态 surface
 - 解析器已具备可扩展注册机制，并落地 3 类实现
 - 公共 CLI 已回到分析优先的可维护命令面
 - 文档、测试与 CI 已能共同约束这些边界