@mycodemap/mycodemap 1.9.0 → 2.0.0

package/docs/ai-guide/OUTPUT.md

@@ -28,6 +28,92 @@
 
 ---
 
+## Interface Contract Schema 输出结构
+
+> `mycodemap --schema` 输出整个 CLI 表面的单一真相源（single source of truth）。
+
+```typescript
+interface InterfaceContractSchema {
+  version: string;           // 契约版本号，如 "2.0.0"
+  commands: CommandSchema[]; // 所有 CLI 命令的定义
+  options: GlobalOptionSchema[]; // 全局选项定义
+  metadata: {
+    generatedAt: string;     // ISO 8601 时间戳
+    schemaVersion: string;   // schema 格式版本
+    totalCommands: number;
+    totalOptions: number;
+  };
+}
+
+interface CommandSchema {
+  name: string;              // 命令名，如 "query", "analyze", "doctor"
+  description: string;       // 命令描述
+  arguments: ArgumentSchema[];
+  options: OptionSchema[];
+  output: OutputSchema;      // 输出结构定义
+  examples: string[];
+}
+
+interface ArgumentSchema {
+  name: string;
+  required: boolean;
+  description: string;
+  type: "string" | "number" | "boolean" | "array";
+}
+
+interface OptionSchema {
+  name: string;
+  alias?: string;
+  type: "string" | "number" | "boolean" | "array";
+  description: string;
+  default?: unknown;
+  required: boolean;
+}
+
+interface OutputSchema {
+  format: "json" | "text" | "table";
+  schemaRef: string;         // 指向具体 TypeScript interface 的引用
+}
+```
+
+### 关键特性
+
+- **单一真相源**：此 schema 同时驱动以下四个输出：
+  1. CLI parser（命令行参数解析器）
+  2. MCP tool definitions（MCP 工具定义）
+  3. `--help-json`（机器可读帮助）
+  4. Shell completions（bash/zsh/fish 补全）
+- **变更即生效**：修改 schema 中的命令定义后，上述四个输出自动同步更新，无需手写维护
+- **MCP 网关依赖**：MCP server 通过读取此 schema 动态注册所有工具，见下文 MCP 章节
+
+### 示例
+
+```json
+{
+  "version": "2.0.0",
+  "commands": [
+    {
+      "name": "query",
+      "description": "查询符号、模块或依赖信息",
+      "arguments": [],
+      "options": [
+        { "name": "symbol", "alias": "s", "type": "string", "required": false },
+        { "name": "json", "alias": "j", "type": "boolean", "required": false }
+      ],
+      "output": { "format": "json", "schemaRef": "QueryOutput" }
+    }
+  ],
+  "metadata": {
+    "generatedAt": "2026-05-01T00:00:00.000Z",
+    "schemaVersion": "2.0.0",
+    "totalCommands": 20,
+    "totalOptions": 45
+  }
+}
+```
+
+---
+
 ## 文件发现契约
 
 ```typescript
@@ -128,9 +214,23 @@ interface CodeMap {
 
 ---
 
-## experimental MCP tool 输出结构
+## MCP Tool 输出结构 (CLI-as-MCP Automatic Gateway)
+
+> canonical MCP path 是 `generate --symbol-level → mcp install → host 启动 mcp start`。
+> **v2.0 重大变更**：所有 schema 定义的 CLI 命令自动暴露为 MCP tools，不再只有 2 个工具。
 
-> canonical MCP path 是 `generate --symbol-level → mcp install → host 启动 mcp start`。当前只暴露 `codemap_query` / `codemap_impact` 两个工具。
+### Gateway 模式
+
+CLI-as-MCP Automatic Gateway 的核心机制：
+
+1. **自动映射**：`Interface Contract Schema` 中定义的每个命令自动成为 MCP tool
+2. **动态注册**：向 schema 添加新命令 → 重启 MCP server → 新 tool 自动出现，无需手写 tool 定义
+3. **契约一致**：CLI 的输入/输出结构与对应的 MCP tool 完全同源，不存在漂移
+4. **工具定义自动生成**：MCP server 启动时从 schema 自动生成 `tool.name`、`tool.description`、`inputSchema`
+
+当前 schema 定义了 **20+ 个命令**，意味着 MCP host 可见 20+ 个 tools。以下 `McpQueryResult` 和 `McpImpactResult` 仅为其中两个示例。
+
+> 注意：tool 定义是自动生成的。如果你看到某个命令在 CLI 可用但在 MCP 不可见，检查该命令是否已注册到 `Interface Contract Schema`。
 
 ```typescript
 type McpToolStatus = "ok" | "not_found" | "ambiguous" | "unavailable";
@@ -266,6 +366,199 @@ interface CodemapImpactInput {
 
 ---
 
+## doctor 命令输出结构
+
+### JSON 输出 (`--json`)
+
+```typescript
+type DoctorCheckStatus = "pass" | "warn" | "fail" | "skip";
+type DoctorCategory = "install" | "config" | "runtime" | "agent";
+
+interface DoctorCheck {
+  name: string;
+  status: DoctorCheckStatus;
+  message: string;
+  remediation?: string;
+  details?: Record<string, unknown>;
+}
+
+interface DoctorCategoryResult {
+  category: DoctorCategory;
+  summary: {
+    pass: number;
+    warn: number;
+    fail: number;
+    skip: number;
+  };
+  checks: DoctorCheck[];
+}
+
+interface DoctorOutput {
+  overall: "healthy" | "degraded" | "critical";
+  categories: DoctorCategoryResult[];
+  // Failure-to-Action Protocol 字段
+  rootCause?: string;           // 若 overall != healthy，给出根因
+  remediationPlan?: string[];   // 按优先级排列的修复步骤
+  confidence: "high" | "medium" | "low";  // 诊断置信度
+  nextCommand?: string;         // 建议执行的下一步 CLI 命令
+}
+```
+
+### Failure-to-Action Protocol
+
+当诊断发现问题时，`doctor` 不仅返回状态，还返回可执行的修复指引：
+
+| 字段 | 含义 | 示例 |
+|------|------|------|
+| `rootCause` | 问题的根本原因 | `"SQLite binding 缺失，导致 storage backend 无法初始化"` |
+| `remediationPlan` | 按优先级排列的修复步骤 | `["npm install better-sqlite3", "mycodemap generate --symbol-level"]` |
+| `confidence` | 诊断置信度 | `"high"` — 对根因判断有把握 |
+| `nextCommand` | 建议执行的下一步命令 | `"mycodemap generate --symbol-level"` |
+
+### 示例
+
+```json
+{
+  "overall": "degraded",
+  "categories": [
+    {
+      "category": "install",
+      "summary": { "pass": 2, "warn": 0, "fail": 0, "skip": 0 },
+      "checks": [
+        { "name": "node_version", "status": "pass", "message": "Node.js >= 20" },
+        { "name": "npm_packages", "status": "pass", "message": "所有依赖已安装" }
+      ]
+    },
+    {
+      "category": "config",
+      "summary": { "pass": 1, "warn": 1, "fail": 0, "skip": 0 },
+      "checks": [
+        { "name": "config_file", "status": "pass", "message": "mycodemap.config.json 存在" },
+        { "name": "storage_type", "status": "warn", "message": "storage.type 未显式设置，使用 auto", "remediation": "建议显式设置为 sqlite 或 filesystem" }
+      ]
+    },
+    {
+      "category": "runtime",
+      "summary": { "pass": 1, "warn": 0, "fail": 1, "skip": 0 },
+      "checks": [
+        { "name": "graph_exists", "status": "fail", "message": "symbol-level 图不存在", "remediation": "运行 mycodemap generate --symbol-level" },
+        { "name": "sqlite_available", "status": "pass", "message": "better-sqlite3 可用" }
+      ]
+    },
+    {
+      "category": "agent",
+      "summary": { "pass": 1, "warn": 0, "fail": 0, "skip": 1 },
+      "checks": [
+        { "name": "mcp_server", "status": "pass", "message": "MCP server 可启动" },
+        { "name": "shell_completions", "status": "skip", "message": "未检测 shell 环境" }
+      ]
+    }
+  ],
+  "rootCause": "symbol-level 图缺失，MCP tools 无法提供完整语义查询",
+  "remediationPlan": [
+    "mycodemap generate --symbol-level",
+    "mycodemap mcp install",
+    "重启 MCP host"
+  ],
+  "confidence": "high",
+  "nextCommand": "mycodemap generate --symbol-level"
+}
+```
+
+---
+
+## benchmark 命令输出结构
+
+### JSON 输出 (`--json`)
+
+```typescript
+interface BenchmarkTiming {
+  mean: number;      // 平均耗时 (ms)
+  median: number;    // 中位数 (ms)
+  p95: number;       // 95 分位 (ms)
+  p99: number;       // 99 分位 (ms)
+  stdDev: number;    // 标准差
+  samples: number;   // 采样次数
+}
+
+interface BenchmarkComparison {
+  command: string;
+  wasm: BenchmarkTiming;
+  native: BenchmarkTiming;
+  speedup: number;   // native / wasm，>1 表示 native 更快
+  fallback: {
+    used: boolean;   // 是否发生了 WASM → Native fallback
+    reason?: string; // fallback 原因，如 "wasm_unavailable", "timeout", "memory_limit"
+  };
+}
+
+interface BenchmarkOutput {
+  overall: {
+    totalCommands: number;
+    fallbackCount: number;
+    averageSpeedup: number;
+  };
+  comparisons: BenchmarkComparison[];
+  system: {
+    nodeVersion: string;
+    platform: string;
+    arch: string;
+    memoryMb: number;
+  };
+}
+```
+
+### WASM vs Native 对比语义
+
+| 字段 | 含义 |
+|------|------|
+| `speedup` | Native 相对于 WASM 的加速比。`1.0` 表示无差异，`>1` 表示 Native 更快，`<1` 表示 WASM 更快（罕见） |
+| `fallback.used` | 是否因 WASM 不可用/超时/内存限制而回退到 Native 实现 |
+| `fallback.reason` | fallback 触发原因，用于诊断 WASM 路径的问题 |
+
+### 示例
+
+```json
+{
+  "overall": {
+    "totalCommands": 5,
+    "fallbackCount": 1,
+    "averageSpeedup": 2.3
+  },
+  "comparisons": [
+    {
+      "command": "generate",
+      "wasm": { "mean": 1200, "median": 1150, "p95": 1800, "p99": 2100, "stdDev": 200, "samples": 10 },
+      "native": { "mean": 500, "median": 480, "p95": 720, "p99": 850, "stdDev": 90, "samples": 10 },
+      "speedup": 2.4,
+      "fallback": { "used": false }
+    },
+    {
+      "command": "query",
+      "wasm": { "mean": 80, "median": 75, "p95": 120, "p99": 150, "stdDev": 15, "samples": 10 },
+      "native": { "mean": 35, "median": 32, "p95": 55, "p99": 70, "stdDev": 8, "samples": 10 },
+      "speedup": 2.29,
+      "fallback": { "used": false }
+    },
+    {
+      "command": "analyze",
+      "wasm": { "mean": 0, "median": 0, "p95": 0, "p99": 0, "stdDev": 0, "samples": 0 },
+      "native": { "mean": 600, "median": 580, "p95": 900, "p99": 1100, "stdDev": 120, "samples": 10 },
+      "speedup": 0,
+      "fallback": { "used": true, "reason": "wasm_unavailable: analyze 命令尚未提供 WASM 实现" }
+    }
+  ],
+  "system": {
+    "nodeVersion": "v22.14.0",
+    "platform": "linux",
+    "arch": "x64",
+    "memoryMb": 32768
+  }
+}
+```
+
+---
+
 ## query 命令输出结构
 
 ### JSON 输出 (-j)

package/docs/ai-guide/PROMPTS.md

@@ -429,10 +429,10 @@
 
 ## 模板 9: ship 发布验证
 
-**适用场景**: 需要验证 `codemap ship` 是否会通过 tag push 触发 GitHub Actions，而不是本地直接发布
+**适用场景**: 需要验证 `mycodemap ship` 是否会通过 tag push 触发 GitHub Actions，而不是本地直接发布
 
 ```markdown
-我需要验证 `codemap ship` 的自动发布链路是否完整。
+我需要验证 `mycodemap ship` 的自动发布链路是否完整。
 
 请执行以下步骤：
 

package/docs/ai-guide/QUICKSTART.md

@@ -2,7 +2,7 @@
 
 > AI/Agent 使用 CodeMap 的快速入门和决策指南
 >
-> CodeMap 是一个 AI-first 代码地图工具：AI/Agent 是主要消费者，代码分析是首屏产品面。
+> CodeMap 是 AI-Native 优先、人类友好的代码架构治理基础设施：AI/Agent 是主要消费者，代码分析是首屏产品面。
 
 ---
 
@@ -88,6 +88,13 @@ cat .mycodemap/AI_MAP.md
 | "需要重构建议" | `cycles` + `complexity` | `analyze -i read -t "src/" --json` | 机器可读优先 |
 | "查找循环依赖" | `cycles` | - | 文本 |
 | "有哪些测试文件" | `query -S ".test.ts"` | - | 文本 |
+| "诊断 CodeMap 环境健康" | `codemap doctor --json` | `mycodemap doctor` | 机器可读优先 |
+| "查看 CLI 接口契约" | `codemap --schema \| jq '.'` | `mycodemap --schema` | 机器可读优先 |
+| "对比 WASM/Native 性能" | `codemap benchmark --json` | `mycodemap benchmark --wasm` / `--native` | 机器可读优先 |
+| "验证设计契约" | `codemap design validate mycodemap.design.md --json` | - | 机器可读优先 |
+| "映射设计范围到代码" | `codemap design map mycodemap.design.md --json` | - | 机器可读优先 |
+| "生成 handoff 包" | `codemap design handoff mycodemap.design.md --json` | - | 机器可读优先 |
+| "验证交付 checklist" | `codemap design verify mycodemap.design.md --json` | - | 机器可读优先 |
 
 ---
 
@@ -128,6 +135,26 @@ cat .mycodemap/AI_MAP.md
 | 结果导出 | `export` | 导出 JSON / GraphML / Mermaid |
 | CI 门禁 | `ci` | 代码质量检查 |
 | 工作流编排（analysis-only） | `workflow` | 复杂分析任务管理 |
+| 环境健康诊断 | `doctor` | 检测 ghost 命令、native 依赖、workspace drift、agent 连通性 |
+| 性能对比 | `benchmark` | WASM vs Native 性能对比 |
+| 接口契约 | `--schema` | 输出完整 Interface Contract Schema JSON |
+| 设计契约工作流 | `design` | validate / map / handoff / verify 设计契约 |
+
+---
+
+## v2.0 新命令速查
+
+| 命令 | 用途 | 示例 |
+|------|------|------|
+| `doctor` | 环境健康诊断 | `mycodemap doctor --json` |
+| `benchmark` | WASM/Native 性能对比 | `mycodemap benchmark --json` |
+| `--schema` | 接口契约输出 | `mycodemap --schema \| jq '.'` |
+| `design validate` | 验证设计契约 | `mycodemap design validate mycodemap.design.md --json` |
+| `design map` | 映射设计范围到代码 | `mycodemap design map mycodemap.design.md --json` |
+| `design handoff` | 生成 handoff 包 | `mycodemap design handoff mycodemap.design.md --json` |
+| `design verify` | 验证交付 checklist | `mycodemap design verify mycodemap.design.md --json` |
+
+> v2.0 milestone: **agent-native-foundation**。AI-First Default Output: JSON/NDJSON 默认；`--human` 或 TTY 自动检测切换为人类可读。
 
 ---
 

package/docs/ai-guide/README.md

@@ -2,7 +2,7 @@
 
 > 专为 AI/Agent 设计的 CodeMap 使用指南。
 >
-> CodeMap 是一个 AI-first 代码地图工具；AI/Agent 是主要消费者。  
+> CodeMap 是 AI-Native 优先、人类友好的代码架构治理基础设施；AI/Agent 是主要消费者。  
 > 入口层优先聚焦 `generate`、`query`、`deps`、`impact`、`complexity`、`export`、`ci` 等核心分析能力。  
 > `workflow` 是当前公开的 analysis-only 工作流能力，`ship` 仍是公开的过渡能力；`server`、`watch`、`report`、`logs` 已从 public CLI 移除，并在调用时给出迁移提示。
 
@@ -26,7 +26,7 @@
 | 原则 | 说明 |
 |------|------|
 | AI-first 入口 | 优先从 `AI_GUIDE.md`、`QUICKSTART.md`、`OUTPUT.md` 建立对产品和契约的理解 |
-| 机器可读优先 | 当前 CLI 过渡现实下，大多数命令仍用 `--json` 暴露机器可读结果 |
+| 机器可读优先 | v2.0 AI-First Default Output：JSON/NDJSON 默认；`--human` 或 TTY 自动检测切换为人类可读 |
 | 人类可读显式入口 | `analyze` 当前支持 `--output-mode human`；其余命令按现有文本输出使用 |
 | 边界优先 | `Server Layer` 是内部架构层，不等于公共 `mycodemap server` 命令 |
 

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

@@ -0,0 +1,70 @@
+---
+date: 2026-04-15
+archived: 2026-04-29
+source: docs/ideation/2026-04-15-executable-architecture-constitution-ideation.md
+reason: 以下想法已在 2026-04-15 至 2026-04-29 期间实现并合并至主分支
+---
+
+# Ideation Archive: Executable Architecture Constitution (Implemented)
+
+> 本归档包含原 ideation 文档中已实现的 2 项核心想法（#1 Diff-Aware Contract Enforcement、#3 Revive Git History Risk Scoring）。
+> 剩余项（#2 SQLite Migration、#4–#7）保留在源文档中。
+
+## 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
+
+## 已实现的想法
+
+### 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:** Implemented
+
+**Implementation References:**
+- `src/cli/contract-diff-scope.ts` — diff scope resolution (`--base`, `--changed-files`)
+- `src/cli/contract-checker.ts` — rule execution (`layer_direction`, `forbidden_imports`, `module_public_api_only`)
+- `src/cli/commands/check.ts` — CLI entry, `process.exitCode = 1` on blocking violations
+- `src/cli/design-contract-loader.ts` — contract rule parsing and validation
+- Tests: `src/cli/commands/__tests__/check-diff-aware.test.ts`, `src/cli/__tests__/contract-checker.test.ts`, `src/cli/__tests__/design-contract-loader.test.ts`
+
+### 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:** Implemented
+
+**Implementation References:**
+- `src/orchestrator/history-risk-service.ts` — canonical `GitHistoryService` with GRAVITY/HEAT/IMPACT scoring
+- `src/orchestrator/workflow/git-analyzer.ts` — `calculateRiskScore` and `FileHeat` primitives
+- `src/cli/contract-checker.ts` — integrates `GitHistoryService` into `runContractCheck`
+- `src/cli/commands/check.ts` — renders `History Risk` in CLI output
+- Tests: `src/orchestrator/__tests__/history-risk-service.test.ts`, `src/orchestrator/__tests__/git-analyzer.test.ts`
+
+## Session Log
+
+- 2026-04-15: Initial ideation — ~40 candidates generated across 4 frames, 7 survived after adversarial filtering
+- 2026-04-15: Began implementation of diff-aware contract enforcement (`contract-diff-scope.ts`, `contract-checker.ts`)
+- 2026-04-15: Revived and hardened GRAVITY/HEAT/IMPACT scoring into `history-risk-service.ts`
+- 2026-04-29: Verified #1 and #3 fully implemented; archived to this document

package/docs/archive/ideation/2026-04-20-mycodemap-init-enhancements-ideation-archive.md

@@ -0,0 +1,109 @@
+---
+date: 2026-04-20
+archived: 2026-04-29
+source: docs/ideation/2026-04-20-mycodemap-init-enhancements-ideation.md
+reason: 以下想法已在 2026-04-21 至 2026-04-29 期间实现并合并至主分支
+---
+
+# Ideation Archive: mycodemap init enhancements (Implemented)
+
+> 本归档包含原 ideation 文档中已实现的 5 项核心想法。
+> 剩余未实现项（#6 First-Run Concierge + Bootstrap Profiles）保留在源文档中。
+
+## Grounding Context (原文)
+
+### Codebase Context
+
+- [证据] 当前 `src/cli/commands/init.ts` 主要只处理根目录 `mycodemap.config.json` / `codemap.config.json` 的存在检查、旧配置迁移和默认配置写入。
+- [证据] `src/cli/paths.ts` 仍以根目录配置文件作为发现入口，而 `src/cli/config-loader.ts` 的默认 `output` 已转向 `.mycodemap`，但默认 `storage.outputPath` 仍是 `.codemap/storage`。
+- [证据] `src/cli/first-run-guide.ts` 已把 marker 放进 `.mycodemap/`，但欢迎语仍把 init 叙述成"初始化配置"而不是"初始化 AI 工作区"。
+- [证据] 仓库已经拥有可复用的 `.githooks/`、规则校验脚本、first-run guide、chalk + emoji + 中文 CLI 风格。
+
+### Past Learnings
+
+- [推论] 当前最大的产品问题不是"功能不存在"，而是"看起来成功但其实只做了一部分"。
+- [推论] 半迁移状态应该被显式解释、对账和修复，而不是继续依赖隐式 fallback。
+- [证据] 本 phase 已锁定：不自动修改用户 `CLAUDE.md` / `AGENTS.md`，并要求在 `.mycodemap/` 中集中化 config、rules、workflow、logs 等资产。
+
+### External Context
+
+- [推论] 2024–2026 的主流 AI / dev tooling 明显收敛到"双层结构"：隐藏目录存放 tool-owned 资产，显式文件存放 team-owned / shared rules。
+- [推论] hooks 安装的成熟心智是 ownership、冲突检测、可逆迁移，而不是静默覆盖。
+- [推论] 最贴近市场共识的做法不是自动改用户上下文文件，而是生成 tool-owned bundle + 明确的人工接入片段。
+
+## 已实现的想法
+
+### 1. Init Reconciler Dashboard ✅
+**Description:** [推论] 让 `mycodemap init` 先扫描 config / workspace / hooks / rules / first-run 状态，再展示统一状态表并执行勾选后的 reconcile，而不是一上来创建文件。
+**Rationale:** [推论] 这是最强的主心智重写：它同时吸收了"状态透明""半迁移修复""不新增 sync surface"三条信号，并把 init 从 file-creator 提升为 repo-state reconciler。
+**Downsides:** [观点] 需要先定义稳定的状态模型和 CLI 展示格式，否则实现容易碎片化。
+**Confidence:** 93%
+**Complexity:** Medium
+**Status:** Implemented in `src/cli/init/reconciler.ts`, `src/cli/init/receipt.ts`
+
+### 2. Bootstrap Receipt + Managed Asset Ledger ✅
+**Description:** [推论] 每次 init 产出 receipt，并在 `.mycodemap/` 持久化 ledger / manifest，记录配置、hooks、rules、exports、marker 的 ownership、origin、hash、版本、rollback hint 和当前状态。
+**Rationale:** [推论] 这是把"看起来成功但其实没做完"变贵的最直接手段，也为后续 rerun、support、sync、future commands 提供统一事实源。
+**Downsides:** [观点] 若 schema 设计过重，容易提前抽象；需要克制到"只记录会复用的事实"。
+**Confidence:** 90%
+**Complexity:** Medium
+**Status:** Implemented in `src/cli/init/reconciler.ts` (`InitReceipt`, `InitAsset`, `writeInitReceipt`)
+
+### 3. Drift-First Compatibility Bridge ✅
+**Description:** [推论] 把根配置、旧 `.codemap/storage`、旧路径 fallback、旧文档心智全部视为显式 drift；init 负责解释旧世界和新 canonical `.mycodemap/config.json` 的关系，并提供 forward / rollback 指引。
+**Rationale:** [推论] 这是最直击当下 repo 痛点的方向：它不是再加一个功能，而是修复"根配置 vs `.mycodemap` 工作区"的双中心叙事。
+**Downsides:** [观点] 需要同时碰实现、文档和路径叙事；若边界定义不清，会继续扩大兼容负担。
+**Confidence:** 91%
+**Complexity:** Medium
+**Status:** Implemented in `src/cli/init/reconciler.ts` (`buildLegacyRootConfigAssets`, `buildLegacyOutputAsset`, `buildLegacyStorageAsset`)
+
+### 4. Ownership-Preserving Hook Contract ✅
+**Description:** [推论] 把 hooks 从"复制文件"升级为 ownership negotiation：优先用 shim / adapter 指向 `.mycodemap/hooks/` 下的 canonical assets，显式处理 adopt / preserve / manual / conflict / rollback。
+**Rationale:** [推论] hooks 是最高杠杆也最高敏感的边界；这个方向兼顾强能力、可逆性和团队信任，且与外部成熟模式一致。
+**Downsides:** [观点] Git 环境差异和已有团队 hooks 形态很多，边缘案例会拖高实现复杂度。
+**Confidence:** 86%
+**Complexity:** Medium-High
+**Status:** Implemented in `src/cli/init/hooks.ts` (`createHookPlan`, `shimAsset`, `payloadAsset`)
+
+### 5. Rules Link Mode + Assistant Compatibility Pack ✅
+**Description:** [推论] 在 `.mycodemap/rules/`、`.mycodemap/exports/`、`.mycodemap/assistants/` 中生成可引用的 rules bundle、copy-paste include blocks、per-tool stubs 和文档片段，而不是自动改 `CLAUDE.md` / `AGENTS.md`。
+**Rationale:** [推论] 这条路最贴近行业共识：隐藏目录归工具，显式上下文归团队；同时把多工具接入和文档同步成本一起压低。
+**Downsides:** [观点] 用户仍需手动完成最后一步粘贴；若提示文案不够强，可能有人觉得"不够自动化"。
+**Confidence:** 88%
+**Complexity:** Medium
+**Status:** Implemented in `src/cli/init/rules.ts`, `src/cli/init/rule-templates.ts`
+
+## Rejection Summary (已归档)
+
+以下被拒绝的想法因已被上述实现吸收或替代而一并归档：
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | `.mycodemap` as Agent Control Plane | [推论] 更像 framing，总体价值已被 #3 和 #5 吸收 |
+| 2 | `Manual Action Needed` as success | [推论] 是 #1 / #2 的成功语义，不值得独立成产品方向 |
+| 4 | `Customs Declaration Lanes` | [推论] 是 status receipt 的隐喻版本，重复度高 |
+| 5 | `Building Commissioning Sheet` | [推论] 与 Reconciler Dashboard / Drift-First 思路重复 |
+| 7 | `Canonical Locator Map` | [观点] 更像 #2 / #3 的内部机制，而非顶层 ideation winner |
+| 8 | `Migration Journal + Undo Receipts` | [推论] 很有价值，但已折叠进 #2 的 ledger 方案 |
+| 9 | `Capability Matrix for Downstream Commands` | [推论] 值得做，但依赖 #2 的事实层先成立 |
+| 10 | `Portable Hook Adapter Contract` | [推论] 作为 hook 方向的底层机制已吸收到 #4 |
+| 11 | `Doc Snippet Registry` | [推论] 已并入 #5 的 compatibility pack |
+| 12 | `Recovery Partition + Bootloader` | [观点] 类比很强，但太偏实现隐喻，顶层价值已并入 #4 |
+
+## Implementation References
+
+- `src/cli/commands/init.ts` — 命令入口
+- `src/cli/init/reconciler.ts` — 状态扫描、计划生成、receipt 结构
+- `src/cli/init/receipt.ts` — 终端预览与 receipt 渲染
+- `src/cli/init/hooks.ts` — ownership-preserving hook shim
+- `src/cli/init/rules.ts` — rules bundle 生成与 AI context snippet
+- `src/cli/init/rule-templates.ts` — 内置通用规则模板
+- `src/cli/commands/__tests__/init-command.test.ts` — 命令级集成测试
+- `src/cli/commands/__tests__/init-hooks.test.ts` — hooks 收敛测试
+- `src/cli/commands/__tests__/init-rules.test.ts` — rules 收敛测试
+
+## Session Log
+
+- 2026-04-20: 初始 ideation，6 个候选想法
+- 2026-04-21: 开始实现 #1-#5，引入 `reconciler.ts`、`receipt.ts`、`hooks.ts`、`rules.ts`
+- 2026-04-29: 验证 #1-#5 全部实现完成，归档至本文档

package/docs/archive/ideation/2026-04-22-rules-entry-docs-optimization-consolidated-ideation-archive.md

@@ -0,0 +1,54 @@
+---
+date: 2026-04-22
+archived: 2026-04-29
+source: docs/ideation/2026-04-22-rules-entry-docs-optimization-consolidated-ideation.md
+reason: 以下想法已在 2026-04-22 至 2026-04-29 期间实现并合并至主分支
+---
+
+# Ideation Archive: Consolidated rules / AGENTS.md / CLAUDE.md optimization (Implemented)
+
+> 本归档包含原 ideation 文档中已完全实现的 1 项核心想法（#1 One Constitution, Two Thin Adapters）。
+> 剩余项（#2–#6）保留在源文档中。
+
+## Grounding Context (原文)
+
+### Codebase Context
+
+- [证据] 仓库自我定义已经很清楚：`AGENTS.md` 应是"强约束 + 路由"，`CLAUDE.md` 应是"启动清单、检索顺序、最小操作手册"；而且入口文档应该保持短小：`AGENTS.md:3`、`AGENTS.md:14`、`AGENTS.md:15`、`AGENTS.md:329`。
+- [证据] 但当前根 `CLAUDE.md` 同时承载了 post-edit 默认验证、路径路由、rule-system 默认值、CLI dogfood、交付清单，已经超过"薄入口"定位：`CLAUDE.md:25`、`CLAUDE.md:43`、`CLAUDE.md:57`、`CLAUDE.md:65`、`CLAUDE.md:80`。
+- [证据] `.claude/CLAUDE.md` 又额外定义了任务开始前/结束后清单、TDD 流程、禁止行为、commit 策略和 `npm run check:all`，与根 `CLAUDE.md` 形成双入口：`.claude/CLAUDE.md:1`、`.claude/CLAUDE.md:7`、`.claude/CLAUDE.md:33`、`.claude/CLAUDE.md:51`。
+- [证据] 文档已经主张"先路由、再按需下钻"和"按改动类型做最小验证"，但根 `CLAUDE.md` 仍保留一套统一 post-edit 命令与固定 checklist，存在叙事冲突：`docs/rules/README.md:19`、`docs/rules/validation.md:5`、`docs/rules/validation.md:29`、`docs/rules/validation.md:31`、`CLAUDE.md:25`。
+- [证据] 当前部分验证命令存在"文档真、脚本假"的信任问题：`docs/rules/architecture-guardrails.md` 把 `npm run check:architecture` 列为快速验证，但 `package.json` 中它仍是 `echo` stub；`check:unused` 也是同样情况：`docs/rules/architecture-guardrails.md:24`、`docs/rules/architecture-guardrails.md:29`、`package.json:45`、`package.json:46`、`package.json:48`。
+- [证据] 仓库处于过渡态，文档体系与执行面并存新旧结构；历史归档仍在，少量指南仍在根层，官方要求"以实际存在的文件为准"：`AGENTS.md:324`、`AGENTS.md:327`、`AGENTS.md:329`。
+- [推论] 因此当前核心问题不是"规则数量不足"，而是"shared truth source 不够清晰 + 入口过载 + 某些执行约束与真实自动化不一致"。
+
+### External Context
+
+- [证据] OpenAI Codex 官方 `AGENTS.md` 指南强调：写长期稳定、项目特有、可快速扫读的指令；复杂说明应拆到配套 markdown，而不是把一切都塞进根入口。来源：https://developers.openai.com/codex/guides/agents-md
+- [证据] OpenAI Codex best practices 还强调：应通过 retrospective 把重复失败模式沉淀为更专门的技能或流程，而不是继续膨胀通用指令文件。来源：https://developers.openai.com/codex/learn/best-practices
+- [证据] Claude Code 官方 memory 文档建议共享 memory 维持在约 200 行以内；需要更长时，应拆文件并用 `@path` 导入，同时支持在 `CLAUDE.md` 中导入 `AGENTS.md` 与用 `.claude/rules/` 的 `paths:` 做路径作用域加载。来源：https://code.claude.com/docs/en/memory
+- [证据] Claude Code 官方 best practices / hooks 文档强调：`CLAUDE.md` 更适合行为指导，hooks 与 settings 更适合确定性 enforcement；长会话和超长上下文会拖垮效果。来源：https://code.claude.com/docs/en/best-practices 、https://docs.anthropic.com/en/docs/claude-code/hooks
+- [证据] 2026 社区与研究信号都在同一方向上收敛：instruction 文件过长、过泛、缺少可执行细节时会显著掉质；保留最小必要要求比堆叠规则更有效。来源：https://dev.to/reporails/the-state-of-ai-instruction-quality-35mn 、https://arxiv.org/abs/2602.11988
+
+## 已实现的想法
+
+### 1. One Constitution, Two Thin Adapters ✅
+**Description:** [推论] 以 `AGENTS.md` 作为唯一共享治理宪法，专门承载风险分级、证据协议、改动边界、truth-source map、文档职责层次；把根 `CLAUDE.md` 收缩成 Claude/Codex 共用入口路由；把 `.claude/CLAUDE.md` 收缩成 Claude 专属 adapter，优先通过 `@AGENTS.md` 与 `@CLAUDE.md` 引入，而不是重复抄写规则。
+**Rationale:** [推论] 这同时解决了"根入口过载"和"双 CLAUDE.md"问题，也最符合 Codex 原生 `AGENTS.md` 与 Claude 官方 import / memory 模型。
+**Repo-Specific Leverage:** [证据] 当前双入口问题真实存在：根 `CLAUDE.md:25` 到 `CLAUDE.md:88` 已是一整套执行面，`.claude/CLAUDE.md:7` 到 `.claude/CLAUDE.md:39` 又重复定义任务前后动作。
+**Downsides:** [观点] 需要一次性定义清楚三者边界，否则很容易演变成"三份薄文档互相引用但仍然漂移"。
+**Confidence:** 97%
+**Complexity:** Medium
+**Status:** Implemented
+
+**Implementation References:**
+- `AGENTS.md` — 仓库级宪法，首句明确定义 `AGENTS.md = constitution / CLAUDE.md = router / .claude/CLAUDE.md = Claude adapter`
+- `CLAUDE.md` — 54 行纯入口路由，只回答"谁定权、下一步去哪读、规则变更时该改哪份文档"
+- `.claude/CLAUDE.md` — 29 行纯 adapter，不维护第二套规则
+- `scripts/validate-docs.js:96-253` — `validateEntryDocGovernance`，自动审计三份文档的边界合规性
+
+## Session Log
+
+- [证据] 2026-04-22：对比 `docs/archive/ideation/2026-04-22-harness-rules-entry-docs-optimization-ideation.md` 与 `docs/archive/ideation/2026-04-22-rules-claude-agents-optimization-ideation.md`，确认前者更强在治理框架与外部 grounding，后者更强在 repo-specific 问题识别。
+- [证据] 2026-04-22：补充校验根 `CLAUDE.md`、`.claude/CLAUDE.md`、`package.json`、`docs/rules/architecture-guardrails.md`，把"双入口""ghost commands""迁移仓库"三个具体问题收敛进统一提案。
+- 2026-04-29：验证 #1 完全实现；归档至本文档