@mycodemap/mycodemap 1.9.0 → 2.0.0

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

@@ -1,11 +1,14 @@
 ---
 date: 2026-04-15
+updated: 2026-04-29
 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
 
+> **状态更新（2026-04-29）**：本文档原始包含 7 个想法，其中 #1（Diff-Aware Contract Enforcement）与 #3（Revive Git History Risk Scoring）已实现并归档至 `docs/archive/ideation/2026-04-15-executable-architecture-constitution-ideation-archive.md`。本文档保留剩余 5 项。
+
 ## 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.
@@ -28,31 +31,15 @@ focus: Pivot CodeMap to an "Executable Architecture Constitution" — making des
 
 ## 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
+### 1. 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
+**Status:** Partially Implemented (`better-sqlite3` added to `package.json`, but KùzuDB adapter not yet removed)
 
-### 4. Auto-Generate design.md from Existing Codebase
+### 2. 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.
@@ -60,7 +47,7 @@ focus: Pivot CodeMap to an "Executable Architecture Constitution" — making des
 **Complexity:** Medium
 **Status:** Unexplored
 
-### 5. Auto-Generate Architecture Remediation Patches
+### 3. 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.
@@ -68,7 +55,7 @@ focus: Pivot CodeMap to an "Executable Architecture Constitution" — making des
 **Complexity:** High
 **Status:** Unexplored
 
-### 6. Self-Healing Design Contract (Drift Approval)
+### 4. 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."
@@ -76,7 +63,7 @@ focus: Pivot CodeMap to an "Executable Architecture Constitution" — making des
 **Complexity:** Medium
 **Status:** Unexplored
 
-### 7. MCP `verify_contract` Tool
+### 5. 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.
@@ -100,3 +87,4 @@ focus: Pivot CodeMap to an "Executable Architecture Constitution" — making des
 ## Session Log
 
 - 2026-04-15: Initial ideation — ~40 candidates generated across 4 frames, 7 survived after adversarial filtering
+- 2026-04-29: #1 and #3 verified as fully implemented and archived

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

@@ -1,76 +1,36 @@
 ---
 date: 2026-04-20
+updated: 2026-04-29
 topic: mycodemap-init-enhancements
-focus: 把 mycodemap init 从“创建根目录配置文件”升级为“项目级 AI 助手基础设施初始化器”
+focus: 把 mycodemap init 从"创建根目录配置文件"升级为"项目级 AI 助手基础设施初始化器"
 mode: repo-grounded
 ---
 
 # Ideation: mycodemap init enhancements
 
+> **状态更新（2026-04-29）**：本文档原始包含 6 个想法，其中 #1–#5 已实现并归档至 `docs/archive/ideation/2026-04-20-mycodemap-init-enhancements-ideation-archive.md`。本文档仅保留未实现项 #6 及其相关上下文。
+
 ## 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 工作区”。
+- [证据] `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、冲突检测、可逆迁移，而不是静默覆盖。
+- [推论] 2024–2026 的主流 AI / dev tooling 明显收敛到"双层结构"：隐藏目录存放 tool-owned 资产，显式文件存放 team-owned / shared rules。
 - [推论] 最贴近市场共识的做法不是自动改用户上下文文件，而是生成 tool-owned bundle + 明确的人工接入片段。
 
 ## Ranked Ideas
 
-### 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:** Explored
-
-### 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:** Unexplored
-
-### 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:** Unexplored
-
-### 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:** Unexplored
-
-### 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:** Unexplored
-
-### 6. First-Run Concierge + Bootstrap Profiles
+### 1. First-Run Concierge + Bootstrap Profiles
 **Description:** [推论] 把 first-run guide 重写成状态驱动的 remediation concierge，并用少量 profile（如 Minimal / Guardrails / Team Ready）承载交互式一键选择。
 **Rationale:** [推论] 这是最低成本修复 mental model 的方法：既改善第一分钟体验，也避免 init 变成一长串低层开关。
 **Downsides:** [观点] profile 设计如果过粗，会掩盖复杂边界；如果过细，又会退化回问卷。
@@ -82,15 +42,10 @@ mode: repo-grounded
 
 | # | Idea | Reason Rejected |
 |---|------|-----------------|
-| 1 | `.mycodemap` as Agent Control Plane | [推论] 更像 framing，总体价值已被 #3 和 #5 吸收 |
-| 2 | `Manual Action Needed` as success | [推论] 是 #1 / #2 的成功语义，不值得独立成产品方向 |
-| 3 | `Project Safety Contracts` framing | [观点] 叙事强但产品增量弱，更适合后续命名或定位文案 |
-| 4 | `Customs Declaration Lanes` | [推论] 是 status receipt 的隐喻版本，重复度高 |
-| 5 | `Building Commissioning Sheet` | [推论] 与 Reconciler Dashboard / Drift-First 思路重复 |
-| 6 | `Board Game Setup Tray` | [推论] 是 Profiles 的隐喻版，没有新增结构价值 |
-| 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 |
+| 1 | `Project Safety Contracts` framing | [观点] 叙事强但产品增量弱，更适合后续命名或定位文案 |
+| 2 | `Board Game Setup Tray` | [推论] 是 Profiles 的隐喻版，没有新增结构价值 |
+
+## Session Log
+
+- 2026-04-20: 初始 ideation，6 个候选想法
+- 2026-04-29: #1–#5 已实现并归档；本文档收缩为仅保留未实现项 #6

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

@@ -1,5 +1,6 @@
 ---
 date: 2026-04-22
+updated: 2026-04-29
 topic: rules-entry-docs-optimization-consolidated
 focus: 融合两份 2026-04-22 ideation 的最佳部分，形成更强的 rules / AGENTS.md / CLAUDE.md 终稿提案
 mode: repo-grounded
@@ -10,17 +11,19 @@ sources:
 
 # Ideation: Consolidated rules / AGENTS.md / CLAUDE.md optimization
 
+> **状态更新（2026-04-29）**：本文档原始包含 6 个想法，其中 #1（One Constitution, Two Thin Adapters）已实现并归档至 `docs/archive/ideation/2026-04-22-rules-entry-docs-optimization-consolidated-ideation-archive.md`。本文档保留剩余 5 项。
+
 ## 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`。
+- [证据] 仓库自我定义已经很清楚：`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 不够清晰 + 入口过载 + 某些执行约束与真实自动化不一致”。
+- [证据] 文档已经主张"先路由、再按需下钻"和"按改动类型做最小验证"，但根 `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
 
@@ -32,88 +35,80 @@ sources:
 
 ### Synthesis
 
-- [推论] 文档一的强项是“战略方向正确、外部 grounding 充分、结构完整”，文档二的强项是“repo-specific 问题抓得具体、能直接落实施工项”。
-- [推论] 更强的终稿不应在两者之间二选一，而应采用“文档一的治理框架 + 文档二的具体问题卡片”。
+- [推论] 文档一的强项是"战略方向正确、外部 grounding 充分、结构完整"，文档二的强项是"repo-specific 问题抓得具体、能直接落实施工项"。
+- [推论] 更强的终稿不应在两者之间二选一，而应采用"文档一的治理框架 + 文档二的具体问题卡片"。
 
 ## Ranked Ideas
 
-### 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:** Explored
-
-### 2. Validation Router + No Ghost Commands
-**Description:** [推论] 把根 `CLAUDE.md` 中“修改后必须执行”改写为 1 屏验证决策树：按改动类型跳转到 `docs/rules/validation.md`；同时禁止在入口与规则文档中引用 `echo` stub 命令，所有写进 quick-start 的命令都必须是真实可运行命令。
-**Rationale:** [推论] 这是把 harness 的“最小必要验证”从口号变成真正可信的路由；它还顺手修掉最伤信任的“跑了命令但其实没验证”的问题。
+### 1. Validation Router + No Ghost Commands
+**Description:** [推论] 把根 `CLAUDE.md` 中"修改后必须执行"改写为 1 屏验证决策树：按改动类型跳转到 `docs/rules/validation.md`；同时禁止在入口与规则文档中引用 `echo` stub 命令，所有写进 quick-start 的命令都必须是真实可运行命令。
+**Rationale:** [推论] 这是把 harness 的"最小必要验证"从口号变成真正可信的路由；它还顺手修掉最伤信任的"跑了命令但其实没验证"的问题。
 **Repo-Specific Leverage:** [证据] `docs/rules/architecture-guardrails.md:29` 当前推荐 `npm run check:architecture`，但 `package.json:46` 仍是提示安装 dependency-cruiser 的 `echo`；`check:unused` 在 `package.json:48` 也是同类问题。
 **Downsides:** [观点] 若短期内不想落地真实检查，就必须先从入口与规则文档中移除这些命令，否则只会继续制造假安全感。
 **Confidence:** 96%
 **Complexity:** Medium
-**Status:** Explored
+**Status:** Partially Implemented（根 `CLAUDE.md` 已改为纯路由，但 `package.json` 与 `docs/rules/architecture-guardrails.md` 中的 ghost commands 仍在）
 
-### 3. Behavior / Enforcement Split
+### 2. Behavior / Enforcement Split
 **Description:** [推论] 明确分层：`AGENTS.md` / `CLAUDE.md` 负责行为与路由；`.claude/settings*.json`、hooks、`scripts/validate-rules.py`、CI 负责确定性 enforcement；`docs/rules/*` 只解释何时触发、如何恢复、失败后果是什么。
-**Rationale:** [推论] 这既符合 Claude 官方“behavioral guidance vs technical enforcement”的划分，也与本仓库已有 `report-only` / `soft_gate` / `hard_gate` 设计天然一致。
-**Repo-Specific Leverage:** [证据] 根 `CLAUDE.md` 现在同时扮演“行为协议”“默认 gate 配置”“交付 checklist”三种角色：`CLAUDE.md:57`、`CLAUDE.md:61`、`CLAUDE.md:62`、`CLAUDE.md:63`、`CLAUDE.md:80`。
-**Downsides:** [观点] 需要重写措辞，让“默认路由/默认验证”与“真正 blocker”区分得非常清楚，否则用户会误会规则被放松。
+**Rationale:** [推论] 这既符合 Claude 官方"behavioral guidance vs technical enforcement"的划分，也与本仓库已有 `report-only` / `soft_gate` / `hard_gate` 设计天然一致。
+**Repo-Specific Leverage:** [证据] 根 `CLAUDE.md` 现在同时扮演"行为协议""默认 gate 配置""交付 checklist"三种角色：`CLAUDE.md:57`、`CLAUDE.md:61`、`CLAUDE.md:62`、`CLAUDE.md:63`、`CLAUDE.md:80`。
+**Downsides:** [观点] 需要重写措辞，让"默认路由/默认验证"与"真正 blocker"区分得非常清楚，否则用户会误会规则被放松。
 **Confidence:** 93%
 **Complexity:** Medium
-**Status:** Explored
+**Status:** Partially Implemented（行为路由已分离，但缺少 `scripts/validate-rules.py` 等专门 enforcement 工具，部分 enforcement 仍由 `validate-docs.js` 兼任）
 
-### 4. Path-Scoped Governance for a Transitional Repo
-**Description:** [推论] 根入口只维护“如何选规则”的导航，细节继续下沉到按路径加载的文档：Codex 依赖更近的 `AGENTS.md`，Claude 依赖 `.claude/rules/**` 的 `paths:`；同时在根入口显式声明“当前是迁移仓库，MVP3 层级优先，但历史目录仍可能存在”。
-**Rationale:** [推论] 这把文档二的“路由覆盖不足”问题与文档一的“progressive disclosure”主张合并起来：根文件不需要越来越长，但路径规则必须覆盖真实项目形态。
-**Repo-Specific Leverage:** [证据] 仓库已明确“过渡说明”和“入口文档应保持短小”：`AGENTS.md:324`、`AGENTS.md:327`、`AGENTS.md:329`；根 `CLAUDE.md` 当前路由表仍是高度 layer-centric：`CLAUDE.md:43` 到 `CLAUDE.md:55`。
-**Downsides:** [观点] 若没有命名约定和 archive discipline，路径化后会把问题从“根太长”转移成“子规则散落”。
+### 3. Path-Scoped Governance for a Transitional Repo
+**Description:** [推论] 根入口只维护"如何选规则"的导航，细节继续下沉到按路径加载的文档：Codex 依赖更近的 `AGENTS.md`，Claude 依赖 `.claude/rules/**` 的 `paths:`；同时在根入口显式声明"当前是迁移仓库，MVP3 层级优先，但历史目录仍可能存在"。
+**Rationale:** [推论] 这把文档二的"路由覆盖不足"问题与文档一的"progressive disclosure"主张合并起来：根文件不需要越来越长，但路径规则必须覆盖真实项目形态。
+**Repo-Specific Leverage:** [证据] 仓库已明确"过渡说明"和"入口文档应保持短小"：`AGENTS.md:324`、`AGENTS.md:327`、`AGENTS.md:329`；根 `CLAUDE.md` 当前路由表仍是高度 layer-centric：`CLAUDE.md:43` 到 `CLAUDE.md:55`。
+**Downsides:** [观点] 若没有命名约定和 archive discipline，路径化后会把问题从"根太长"转移成"子规则散落"。
 **Confidence:** 91%
 **Complexity:** Medium-High
-**Status:** Explored
+**Status:** Unexplored（不存在 `.claude/rules/` 目录，无 `paths:` 配置）
 
-### 5. Live Rulebook + Archive Demotion
-**Description:** [推论] 明确标注 live governance surface：只认 `AGENTS.md`、根 `CLAUDE.md`、`.claude/CLAUDE.md`、`docs/rules/README.md` 与活跃规则文档；历史 rollout、模板母本、迁移提案要统一降级为 reference/archive，并在文件头写明“不可作为当前执行真相”。
+### 4. Live Rulebook + Archive Demotion
+**Description:** [推论] 明确标注 live governance surface：只认 `AGENTS.md`、根 `CLAUDE.md`、`.claude/CLAUDE.md`、`docs/rules/README.md` 与活跃规则文档；历史 rollout、模板母本、迁移提案要统一降级为 reference/archive，并在文件头写明"不可作为当前执行真相"。
 **Rationale:** [推论] 对 agent 来说，最贵的不是少一条规则，而是不知道哪份文档才是现在真的生效。
-**Repo-Specific Leverage:** [证据] 仓库已承认“历史归档仍保留、少量操作指南仍在根层、执行时以实际存在文件为准”：`AGENTS.md:327`。
+**Repo-Specific Leverage:** [证据] 仓库已承认"历史归档仍保留、少量操作指南仍在根层、执行时以实际存在文件为准"：`AGENTS.md:327`。
 **Downsides:** [观点] 这是文档身份治理，不是炫目的功能增强；但如果不做，后续所有瘦身都会被旧文档重新污染。
 **Confidence:** 92%
 **Complexity:** Low-Medium
-**Status:** Explored
+**Status:** Partially Implemented（`docs/archive/` 目录存在，但并非所有历史文档都被显式标注"不可作为当前执行真相"；`docs/ideation/` 中仍有未归档的历史文档）
 
-### 6. Governance Self-Audit + Generated Shared Tables
-**Description:** [推论] 把“规则重复”和“规则自身腐烂”合并成一个治理能力：高频重复表格（如代码红线、职责映射、验证入口）应由单一结构化源生成；并定期审计链接、命令存在性、路径路由覆盖和 live/reference 身份是否一致。
-**Rationale:** [推论] 文档二抓住了 repo 的真实维护痛点，而文档一提供了更高层的约束原则；把两者合并后，能防止“今天瘦身，明天重新 drift”。
+### 5. Governance Self-Audit + Generated Shared Tables
+**Description:** [推论] 把"规则重复"和"规则自身腐烂"合并成一个治理能力：高频重复表格（如代码红线、职责映射、验证入口）应由单一结构化源生成；并定期审计链接、命令存在性、路径路由覆盖和 live/reference 身份是否一致。
+**Rationale:** [推论] 文档二抓住了 repo 的真实维护痛点，而文档一提供了更高层的约束原则；把两者合并后，能防止"今天瘦身，明天重新 drift"。
 **Repo-Specific Leverage:** [证据] 当前重复与漂移已在多处出现：`AGENTS.md:127`、`docs/rules/engineering-with-codex-openai.md:89`；而命令存在性问题已被 `package.json:46`、`package.json:48` 证明。
-**Downsides:** [观点] 这已经逼近“小型文档治理系统”了；若一次做太大，容易反向过度工程化。
+**Downsides:** [观点] 这已经逼近"小型文档治理系统"了；若一次做太大，容易反向过度工程化。
 **Confidence:** 88%
 **Complexity:** Medium
-**Status:** Explored
+**Status:** Partially Implemented（`scripts/validate-docs.js` 已实现入口文档自动化审计，但无"从单一结构化源生成重复表格"的机制，也无定期审计 package.json stub 命令的能力）
 
 ## Recommended Final Direction
 
-- [观点] **首选主轴**：`#1 One Constitution, Two Thin Adapters`
-  这是最强的结构性修复，因为它同时吸收了双入口治理、single source of truth、Claude/Codex 双工具共存三类问题。
-- [观点] **第二优先级**：`#2 Validation Router + No Ghost Commands`
-  这是最强的信任修复，因为它能最快把“文档说一套、命令做一套”的错位消掉。
-- [观点] **第三优先级**：`#3 Behavior / Enforcement Split`
-  这是最强的长期维护修复，因为它能防止入口文件再次被确定性流程污染。
-- [推论] 若只允许保留一个总原则，应是：**根入口只负责“让 agent 知道去哪读、何时验证、谁在阻断”，不负责承载全部细节、全部命令、全部历史。**
+- [观点] **当前首选主轴**：`#2 Validation Router + No Ghost Commands`
+  在 #1 已完成后，这是最强的信任修复：把"文档说一套、命令做一套"的错位消掉。
+- [观点] **第二优先级**：`#3 Behavior / Enforcement Split`
+  这是最强的长期维护修复，防止入口文件再次被确定性流程污染。
+- [观点] **第三优先级**：`#4 Path-Scoped Governance`
+  把路由从根文件进一步下沉到路径作用域，是 progressive disclosure 的下一步。
+- [推论] 若只允许保留一个总原则，应是：**根入口只负责"让 agent 知道去哪读、何时验证、谁在阻断"，不负责承载全部细节、全部命令、全部历史。**
 
 ## Rejection Summary
 
 | # | Idea | Reason Rejected |
 |---|------|-----------------|
-| 1 | `Universal Mega Entry File` | [推论] 与 Codex / Claude 官方“短入口 + 路由 + 作用域加载”方向完全相反。 |
+| 1 | `Universal Mega Entry File` | [推论] 与 Codex / Claude 官方"短入口 + 路由 + 作用域加载"方向完全相反。 |
 | 2 | `Per-Tool Twin Rulebooks` | [推论] 会把多 agent 共享规则重新复制成两套真相，长期必漂移。 |
 | 3 | `Everything as Structured YAML First` | [观点] 对重复表格很有价值，但若把全部治理文档都数据化，会过早走向工具化治理。 |
 | 4 | `Only Fix Ghost Commands` | [推论] 只能修补信任问题，不能解决入口过载与 shared truth source 不清晰。 |
 | 5 | `Only Merge the Two CLAUDE Files` | [推论] 不触及 `AGENTS.md` / `docs/rules/*` 的职责划分，仍会留下多真相竞争。 |
-| 6 | `Archive Nothing, Just Add More Cross Links` | [观点] 交叉链接能缓解迷路，不能解决“哪份文档是 live contract”的根问题。 |
+| 6 | `Archive Nothing, Just Add More Cross Links` | [观点] 交叉链接能缓解迷路，不能解决"哪份文档是 live contract"的根问题。 |
 
 ## 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-22：最终终稿选择“保留文档一的骨架，吸收文档二最具体的实施抓手”，而不是继续保留两份并行 ideation。
+- [证据] 2026-04-22：补充校验根 `CLAUDE.md`、`.claude/CLAUDE.md`、`package.json`、`docs/rules/architecture-guardrails.md`，把"双入口""ghost commands""迁移仓库"三个具体问题收敛进统一提案。
+- [推论] 2026-04-22：最终终稿选择"保留文档一的骨架，吸收文档二最具体的实施抓手"，而不是继续保留两份并行 ideation。
+- 2026-04-29：验证 #1 完全实现并归档；更新剩余项状态为 Partially Implemented / Unexplored