@mycodemap/mycodemap 0.5.1 → 1.9.0

package/docs/ai-guide/COMMANDS.md

@@ -9,6 +9,21 @@
 
 ## 核心命令
 
+### init - 收敛项目状态
+
+```bash
+mycodemap init               # 默认显示 reconciliation preview
+mycodemap init --interactive # 显式显示 preview（不写入）
+mycodemap init -y            # 使用默认选择直接写入
+```
+
+**行为说明**:
+
+- `init` 会收敛 `.mycodemap/config.json`、`.mycodemap/status/init-last.json`、`.mycodemap/hooks/` 与 `.mycodemap/rules/`
+- 默认先显示 receipt preview；只有 `-y/--yes` 才真正写入
+- 若 receipt 中仍有 `manual action`，请先处理这些动作，再继续自动化流程
+- `init` 不会自动改写 `CLAUDE.md` 或 `AGENTS.md`，只会输出可复制的 rules 引用片段
+
 ### generate - 生成代码地图
 
 ```bash
@@ -35,12 +50,12 @@ mycodemap generate --ai-context             # 生成 AI 描述
 - `generate` 完成后，`codemap.json` 会带 `graphStatus`、`failedFileCount` 与可选 `parseFailureFiles`；若 `graphStatus = "partial"`，不要把结果当成完整图。
 
 **插件运行时说明**:
-- `generate` 不提供独立 `--plugin` flags；插件通过 `mycodemap.config.json` 的 `plugins` 段声明。
+- `generate` 不提供独立 `--plugin` flags；插件通过 `.mycodemap/config.json` 的 `plugins` 段声明。
 - 只有显式存在 `plugins` 段时，`generate` 才会加载插件并运行 analyze / generate hooks。
 - `AI_MAP.md` 会增加 `Plugin Summary`，`codemap.json` 会增加 `pluginReport`，stdout 会输出插件诊断摘要。
 
 **图存储运行时说明**:
-- `generate` 会读取 `mycodemap.config.json.storage`，并把 CodeGraph 写入所选后端。
+- `generate` 会读取 `.mycodemap/config.json` 的 `storage` 段，并把 CodeGraph 写入所选后端。
 - `storage.type` 支持 `filesystem`、`sqlite`、`memory`、`auto`；默认是 `filesystem`。
 - 旧的 `neo4j` / `kuzudb` 配置会直接报迁移错误；显式选择 `sqlite` 但运行时缺少 `better-sqlite3` 或 Node.js `<20` 时也会直接报错，不会静默 fallback 到 `filesystem`。
 - `storage.type = "auto"` 当前优先走 `sqlite`；只有 SQLite 不可用时才 warning 后回退 `filesystem`。
@@ -521,7 +536,7 @@ mycodemap export mermaid                     # Mermaid 语法
 mycodemap export json -o ./output.json       # 指定输出
 ```
 
-- `export json|graphml|dot` 会从 `mycodemap.config.json.storage` 指定的后端读取 CodeGraph。
+- `export json|graphml|dot` 会从 `.mycodemap/config.json` 的 `storage` 段指定后端读取 CodeGraph。
 - `export mermaid` 仍直接读取 `.mycodemap/codemap.json`，这是当前保留的文件出口，不代表 graph backend 未接入主路径。
 - 图存储后端收口不等于重新开放公共 `mycodemap server` 产品面；`Server Layer` 仍是内部层。
 
@@ -563,6 +578,45 @@ mycodemap ship --yes                       # 置信度 60-75 时自动确认
 
 ---
 
+### publish-status - 发布后的只读 snapshot 复核
+
+> `publish-status` 是 `ship` / `/release` 之后的 follow-up observability surface；它不触发发布、不重跑 workflow，也不猜“最新一条 run”。
+
+```bash
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --json
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --json --structured
+mycodemap publish-status --tag v1.9.0 --sha abcdef123456 --workflow-file publish.yml
+```
+
+| 选项 | 说明 | 默认值 |
+|------|------|--------|
+| `--tag <tag>` | 发布 tag，必须精确提供 | - |
+| `--sha <sha>` | 发布 commit SHA，必须精确提供 | - |
+| `--workflow-file <file>` | GitHub Actions workflow 文件名 | `publish.yml` |
+| `--json` | 输出 machine-readable JSON | `false` |
+| `--structured` | 去掉自然语言 `content`，需配合 `--json` 使用 | `false` |
+
+**状态语义:**
+- `success`：找到唯一精确匹配 run，且 workflow 成功
+- `failure`：找到唯一精确匹配 run，且 workflow 明确失败
+- `pending`：还没观察到精确匹配 run，或 run 仍在执行中
+- `ambiguous`：出现多个同时匹配 `tag + sha` 的 runs；不会猜哪一个才是“最新”
+- `unavailable`：repo slug、GitHub API、权限或最终 truth 无法精确确认
+
+**输出契约:**
+- 默认输出终端摘要
+- `--json` 输出 machine-readable payload，并保留 `content`
+- `--json --structured` 移除自然语言字段，仅保留结构化 truth
+- payload 至少包含 `status`、`workflowUrl`、`releaseUrl`、`runId`、`failedJobs`、`reason`、`details`
+
+**边界:**
+- 只做一次 snapshot read，不内置轮询
+- 只读；不会 rerun workflow、dispatch workflow、`npm publish`、`git push`
+- 它不会替代 `ship` 或 `/release`，发布 authority 仍在 `docs/rules/release.md`
+
+---
+
 ## 全局选项
 
 所有命令支持：

package/docs/ai-guide/INTEGRATION.md

@@ -216,4 +216,4 @@ npm ls better-sqlite3
 - 命令参考：`docs/ai-guide/COMMANDS.md`
 - 输出契约：`docs/ai-guide/OUTPUT.md`
 - 主索引：`AI_GUIDE.md`
-- 执行手册：`CLAUDE.md`
+- 入口路由：`CLAUDE.md`

package/docs/ai-guide/PATTERNS.md

@@ -271,14 +271,14 @@ node dist/cli/index.js check --contract mycodemap.design.md --against src --base
 **执行步骤**:
 
 ```bash
-# Step 1: 编辑配置文件
-cat mycodemap.config.json
+# Step 1: 编辑 canonical 配置文件
+cat .mycodemap/config.json
 
 # Step 2: 选择后端
 # {
 #   "storage": {
 #     "type": "sqlite",
-#     "databasePath": ".codemap/governance.sqlite"
+#     "databasePath": ".mycodemap/governance.sqlite"
 #   }
 # }
 

package/docs/ai-guide/QUICKSTART.md

@@ -9,16 +9,25 @@
 ## 快速开始
 
 ```bash
-# Step 1: 生成代码地图（必须在其他命令之前执行）
+# Step 0: 若项目还没初始化，先预览 init 收敛结果
+node dist/cli/index.js init --interactive
+
+# Step 1: 确认 receipt 后执行 init（只在需要写入时）
+node dist/cli/index.js init --yes
+
+# Step 2: 生成代码地图（必须在其他命令之前执行）
 node dist/cli/index.js generate
 
-# Step 2: 阅读生成的 AI_MAP.md 获取项目概览（若显式配置了 plugins，也要看 Plugin Summary）
+# Step 3: 阅读生成的 AI_MAP.md 获取项目概览（若显式配置了 plugins，也要看 Plugin Summary）
 # stdout 还会显示当前写入的 `MVP3 Storage (...)`
 cat .mycodemap/AI_MAP.md
 
-# Step 3: 根据任务选择命令...
+# Step 4: 根据任务选择命令...
 ```
 
+- `init` 的 receipt 会把 `done`、`manual action`、`conflict`、`skipped` 分开显示
+- 如果 receipt 提示需要手动把 `.mycodemap/rules/` 片段加入 `CLAUDE.md` / `AGENTS.md`，请先处理该动作
+
 ---
 
 ## 输出契约速查
@@ -69,7 +78,7 @@ cat .mycodemap/AI_MAP.md
 |---------|---------|---------|---------|
 | "项目结构是什么" | `generate` + 读 `AI_MAP.md` | `analyze -i show -t "src/" --json` | 文本 |
 | "插件是否真的加载成功" | `generate` + 读 `AI_MAP.md` 的 `Plugin Summary` | 解析 `.mycodemap/codemap.json` 的 `pluginReport` | 机器可读优先 |
-| "需要切换/排查图存储后端" | 编辑 `mycodemap.config.json.storage` 后运行 `generate` | `export json` 验证是否能从同一 backend 读回 | 文本 + 机器可读 |
+| "需要切换/排查图存储后端" | 编辑 `.mycodemap/config.json` 的 `storage` 段后运行 `generate` | `export json` 验证是否能从同一 backend 读回 | 文本 + 机器可读 |
 | "XXX 在哪里定义" | `query -s "XXX"` | `query -S "XXX"` | 文本 |
 | "修改 XXX 会影响什么" | `impact -f "XXX" -t -j` | `analyze -i read -t "XXX" --scope transitive --json` | 机器可读优先 |
 | "XXX 模块依赖什么" | `deps -m "XXX" -j` | `analyze -i link -t "XXX" --json` | 机器可读优先 |

package/docs/ai-guide/README.md

@@ -55,13 +55,13 @@
 
 | 文档 | 行数 | 核心内容 |
 |------|------|---------|
-| QUICKSTART.md | ~120 | 决策树、场景映射 |
-| COMMANDS.md | ~350 | 核心分析命令 + 移除命令迁移说明 |
-| OUTPUT.md | ~320 | 目标契约、当前 CLI 现实与 JSON 结构 |
-| PATTERNS.md | ~290 | 核心分析模式 + 过渡 workflow 说明 |
-| PROMPTS.md | ~300 | 8个提示词模板 |
-| INTEGRATION.md | ~420 | MCP、Skill、错误处理 |
-| **总计** | **~1800** | **完整 AI 使用指南** |
+| QUICKSTART.md | 130 | 决策树、场景映射 |
+| COMMANDS.md | 574 | 核心分析命令 + 移除命令迁移说明 |
+| OUTPUT.md | 1546 | 目标契约、当前 CLI 现实与 JSON 结构 |
+| PATTERNS.md | 498 | 核心分析模式 + 过渡 workflow 说明 |
+| PROMPTS.md | 463 | 9个提示词模板 |
+| INTEGRATION.md | 219 | MCP、Skill、错误处理 |
+| **总计** | **3430** | **完整 AI 使用指南** |
 
 ---
 

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

@@ -0,0 +1,102 @@
+---
+date: 2026-04-22
+topic: harness-rules-entry-docs-optimization
+focus: 基于 harness mode 优点与 2026-04 最新 Codex / Claude Code 官方 + 社区实践，重构 rules、AGENTS.md、CLAUDE.md 的职责与加载方式
+mode: repo-grounded
+---
+
+# Ideation: Harness-aligned rules and entry docs optimization
+
+## Grounding Context
+
+### Codebase Context
+
+- [证据] 仓库已经明确把入口文档定义为“强约束 + 路由”，并把 `AGENTS.md` 定义为仓库级强约束、把 `CLAUDE.md` 定义为启动清单与最小操作手册：`AGENTS.md:3`、`AGENTS.md:14`、`AGENTS.md:15`。
+- [证据] `CLAUDE.md` 仍同时承载固定 post-edit 命令、rule-system 默认值与交付清单，已经不只是“入口路由”：`CLAUDE.md:25`、`CLAUDE.md:41`、`CLAUDE.md:59`、`CLAUDE.md:63`、`CLAUDE.md:83`。
+- [证据] `docs/rules/README.md` 已主张“先路由、再按需下钻”，`docs/rules/validation.md` 已主张“按改动类型做最小验证”，与根入口中的“统一大礼包命令”存在张力：`docs/rules/README.md:19`、`docs/rules/validation.md:5`、`docs/rules/validation.md:29`、`docs/rules/validation.md:31`。
+- [证据] 任务分级、可信度自评、代码红线等核心治理内容已在多处重复陈述，truth source 不单一：`AGENTS.md:43`、`AGENTS.md:100`、`AGENTS.md:127`、`docs/rules/engineering-with-codex-openai.md:15`、`docs/rules/engineering-with-codex-openai.md:89`、`docs/rules/engineering-with-codex-openai.md:193`。
+- [推论] 当前问题更像“入口过载 + 多真相竞争”，而不是“规则还不够多”；优化重点应是职责重划与加载路径重写，而不是继续往根文件里加内容。
+
+### External Context
+
+- [证据] OpenAI Codex 官方 `AGENTS.md` 指南强调：指令文件要长期有效、优先写项目特有信息、复杂说明要拆到配套 markdown，并且“保持可快速扫读”；同时建议通过回顾重复错误，把稳定流程沉淀成更专门的技能而不是不断膨胀入口文件。来源：https://developers.openai.com/codex/guides/agents-md 与 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 强调：上下文窗口很快会塞满，长会话性能会下降；应把通用或高频操作下沉为子目录 `CLAUDE.md`、hooks、命令或技能，而不是让根文件继续变长；hooks 适合确定性动作，`CLAUDE.md` 更适合行为指导。来源：https://code.claude.com/docs/en/best-practices 与 https://docs.anthropic.com/en/docs/claude-code/hooks 。
+- [证据] 2026-04-21 的社区语料分析（RepoRails）统计了 28,721 个 coding-agent 项目，发现 instruction 文件只有 27.2% 的原子陈述是真正可执行指令，89.9% 缺少具体构造；同时 37% 的项目已是多 agent 配置，最常见组合之一就是 Claude + Codex。来源：https://dev.to/reporails/the-state-of-ai-instruction-quality-35mn 。
+- [证据] 2026-02-12 的论文《Do AGENTS.md Files Help LLM-Based Code Generation Agents?》指出：上下文文件并非总是提升效果，过量要求会拉低成功率并增加 token 消耗；作者建议只保留执行任务所需的最小要求。来源：https://arxiv.org/abs/2602.11988 。
+- [证据] 高信号社区实践也在收敛到“基础记忆 + hooks/settings + skills/agents/rules 分层”而不是单一超级入口文件。一个近期公开示例把 `CLAUDE.md`、settings、hooks、agents、skills、`rules/` 分成独立治理面。来源：https://github.com/ChrisWiles/claude-code-showcase 。
+
+### Past Learnings
+
+- [推论] 本仓库已经具备 harness 友好的关键机制：`route_by_edit_path`、`soft_gate` / `hard_gate`、场景化验证矩阵、短入口路线图；真正缺的是“谁是 live truth source”的清晰边界，而不是新机制本身：`CLAUDE.md:61`、`CLAUDE.md:62`、`CLAUDE.md:63`、`docs/rules/validation.md:10`、`docs/rules/validation.md:21`。
+- [推论] 因为仓库已经同时面向 Claude 与 Codex，任何继续复制规则到多份入口文件的做法，都会与外部多-agent 收敛趋势正面冲突。
+
+## Ranked Ideas
+
+### 1. One Constitution, Two Adapters
+**Description:** [推论] 把 `AGENTS.md` 收缩为唯一共享“治理宪法”：只保留风险分级、证据协议、改动边界、truth-source map、文档职责分层；把 `CLAUDE.md` 收缩为 Claude 适配层，只保留 `@AGENTS.md`、Claude 专属能力边界、检索顺序、最小入口 checklist。
+**Rationale:** [推论] 这条路最直接利用了 Codex 原生 `AGENTS.md` 与 Claude 官方“`CLAUDE.md` 可导入 `AGENTS.md`”的交集；它把双 agent 共识收敛成一份 shared constitution，再用极薄 adapter 承载每个 harness 的差异。
+**Downsides:** [观点] 初次重写需要明确“什么必须共享、什么必须保留为 Claude/Codex delta”，否则容易把 adapter 又写胖。
+**Confidence:** 96%
+**Complexity:** Medium
+**Status:** Explored
+
+### 2. Validation Decision Tree, Not Post-Edit Bundle
+**Description:** [推论] 把 `CLAUDE.md` 里的“修改后必须执行”改成 1 屏决策树：先判断改动类型，再跳到 `docs/rules/validation.md` 的最小验证矩阵；根文件只保留“如何选路径”，不再内嵌固定大礼包命令。
+**Rationale:** [推论] 这最贴合 harness mode 的优势：让 agent 在当前改动上做最小充分验证，而不是默认加载一整套命令；也能把 `CLAUDE.md:25` 与 `docs/rules/validation.md:5` 的冲突消掉。
+**Downsides:** [观点] 决策树如果写得太抽象，用户会失去“一眼能 copy”的即时性；需要在短小与可执行之间拿捏。
+**Confidence:** 94%
+**Complexity:** Medium
+**Status:** Explored
+
+### 3. Behavior / Enforcement Split
+**Description:** [推论] 明确宣布：`AGENTS.md` / `CLAUDE.md` 只负责行为协议与路由；`.claude/settings*.json`、hooks、`scripts/validate-rules.py`、CI 才负责确定性 enforcement；`docs/rules/*` 解释何时、为何、怎样触发这些护栏。
+**Rationale:** [推论] 这同时对齐了 Claude 官方“technical enforcement 用 settings，behavioral guidance 用 `CLAUDE.md`”与本仓库已有 soft/hard gate 设计；一旦边界清晰，入口文件自然会瘦下来。
+**Downsides:** [观点] 需要重写若干表述，把“必须执行”改成“默认路由 / 真正阻断点”，否则读者会误会要求被削弱。
+**Confidence:** 92%
+**Complexity:** Medium
+**Status:** Explored
+
+### 4. Path-Scoped Governance Packs
+**Description:** [推论] 把高细节治理内容继续下沉到按路径加载的文件：Codex 用更近的 `AGENTS.md`，Claude 用 `.claude/rules/**` 的 `paths:`；根入口只保留“何时去哪个包里读”。
+**Rationale:** [推论] 这是把 progressive disclosure 真正落地成结构，而不是口号。Claude 官方已经给出路径规则机制，Codex 也原生按目录查找 `AGENTS.md`；本仓库正好同时受益。
+**Downsides:** [观点] 如果没有严格的命名和归档规则，治理文件数量会增加，反而形成“散落的小真相”。
+**Confidence:** 90%
+**Complexity:** Medium-High
+**Status:** Unexplored
+
+### 5. Live Rulebook / Archive Demotion
+**Description:** [推论] 显式定义 live governance surface：只认 `AGENTS.md`、`CLAUDE.md`、`docs/rules/README.md` 与活跃 `docs/rules/*`；已完成 rollout、模板参考、历史提案全部改成 reference/archive 身份，并在文件头标出“不可作为当前执行真相”。
+**Rationale:** [推论] 这会直接消灭当前最伤 harness 的问题之一——第二真相来源。对于 agent 来说，“哪些文件是历史，哪些文件能执行”比多一条规则更重要。
+**Downsides:** [观点] 文档本身的“身份治理”不性感，短期收益不如入口重写直观；但如果不做，后续任何瘦身都可能再次被旧文档反污染。
+**Confidence:** 91%
+**Complexity:** Low-Medium
+**Status:** Explored
+
+### 6. Retrospective-Driven Rule Admission
+**Description:** [推论] 新规则只允许通过三种入口进入根治理文档：重复性错误、人工 review 反复发现、或 deterministic hook 仍覆盖不了的高风险缺口；其余内容默认进入 scoped rules、skill、prompt template 或参考文档。
+**Rationale:** [推论] 这直接吸收了 Codex 官方“把重复流程沉淀为技能”的建议，以及社区/论文对“说明文件一旦膨胀就掉质”的共同结论；它能防止这次瘦身后再反弹。
+**Downsides:** [观点] 这是治理纪律，不是一次性重构；需要 owner 持续执行，否则很容易回到“先塞进根文件再说”。
+**Confidence:** 89%
+**Complexity:** Low
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | `Root 200-Line Budget` | [推论] 很好的 guardrail，但它更适合作为 #1 / #4 的验收指标，而不是顶层方向。 |
+| 2 | `Command Cookbook Extraction` | [推论] 本质上是 #2 的实现动作，不值得单列为产品级 ideation winner。 |
+| 3 | `Assistant Compatibility Matrix` | [观点] 更像 #1 的附属表格，用于落地 shared constitution，而不是单独战略。 |
+| 4 | `Current-vs-Target Architecture Banner` | [推论] 价值很高，但更像 #4 / #5 的具体机制；单独成项会让 ideation 过碎。 |
+| 5 | `Rule Delta Log / Governance Changelog` | [推论] 是 #5 的配套治理件，不是独立顶层方向。 |
+| 6 | `Deterministic Guardrail Ledger` | [推论] 核心价值已被 #3 吸收；单列会重复“behavior vs enforcement”主轴。 |
+| 7 | `Skill-First Escape Hatch` | [观点] 是 #6 的优先级规则，不是独立结构重写。 |
+| 8 | `Per-Tool Twin Rulebooks` | [推论] 与 Claude 官方 `@AGENTS.md` 导入机制和多-agent single-source 方向相冲突，会扩大漂移面。 |
+| 9 | `Universal Mega Entry File` | [推论] 与 Codex / Claude 官方“短入口 + 分层导入 + 作用域加载”全部背离，是反 harness 方案。 |
+
+## Session Log
+
+- [证据] 2026-04-22：交叉阅读本仓库 `AGENTS.md`、`CLAUDE.md`、`docs/rules/README.md`、`docs/rules/validation.md`、`docs/rules/engineering-with-codex-openai.md`，确认当前痛点是“入口过载 + 多真相竞争”。
+- [证据] 2026-04-22：补充 OpenAI Codex 官方 `AGENTS.md` / best practices、Claude Code 官方 memory / best practices / hooks，以及 2026 社区语料分析与论文证据。
+- [推论] 2026-04-22：最终收敛结论不是“再加更多规则”，而是“重建 single source of truth、把 deterministic enforcement 与行为指导拆开、让作用域加载真正生效”。

package/docs/archive/ideation/2026-04-22-rules-claude-agents-optimization-ideation.md

@@ -0,0 +1,107 @@
+---
+date: 2026-04-22
+topic: rules-claude-agents-optimization
+focus: 基于 harness 模式优点优化 rules、CLAUDE.md 和 AGENTS.md
+---
+
+# Ideation: Rules / CLAUDE.md / AGENTS.md 优化
+
+## Codebase Context
+
+**项目形状**：TypeScript CLI 工具（`@mycodemap/mycodemap`），为 AI 辅助开发提供代码地图与结构化上下文。采用 MVP3 五层架构，构建输出到 `dist/`，CLI 入口为 `dist/cli/index.js`。
+
+**关键痛点**：
+1. **规则重复**：代码红线在 3 处出现（code-quality-redlines.md、AGENTS.md 7.1、engineering-with-codex-openai.md §6），阈值相同但格式不同步
+2. **路径路由缺失**：CLAUDE.md 路由表仅覆盖 5 个 src/ 子目录，遗漏 worker/、cache/、watcher/、plugins/ 等活跃目录
+3. **幽灵命令**：`check:architecture` 和 `check:unused` 是 echo stub，但文档当作真实命令引用
+4. **交付清单无 enforcement**：CLAUDE.md 要求"失败场景+可信度自评"，但无自动化检查点
+5. **双 CLAUDE.md**：根目录与 `.claude/` 各有一份，内容重叠且部分矛盾
+6. **无解决方案归档**：`docs/solutions/` 不存在，知识随会话结束蒸发
+7. **规则自身无审计**：链接失效、命令更名、路径迁移无自动检测
+
+## Ranked Ideas
+
+### 1. 规则去重即活契约 (Single-Source-of-Truth Rules)
+**Description:** 将分散在 3 份文档中的代码红线合并为单一结构化数据源（YAML/JSON），通过生成脚本自动渲染所有 markdown 表格。规则变更时，一次编辑、全处同步。
+**Rationale:** 当前同一规则在 3 处出现，格式不同（AGENTS.md 无"阻断标准"列，engineering-with-codex-openai.md 有"阻断标准"列，code-quality-redlines.md 有"失败后果"列），已存在漂移证据。单一数据源消除同步负担，让规则系统自身可维护。
+**Downsides:** 需要编写和维护生成脚本；迁移期间需人工比对确保无遗漏；新同事需要学习"编辑源文件而非 markdown"的工作流。
+**Confidence:** 90%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 2. CLAUDE.md 路径路由自动补全
+**Description:** 补全路径路由表缺失的 `src/worker/`、`src/cache/`、`src/watcher/`、`src/plugins/` 映射。同时添加 CI 检查：若新增 `src/*/` 目录而无路由条目，构建失败。
+**Rationale:** 当前 14 个 src/ 子目录中仅 5 个有路由映射。AI 助手触碰未映射目录时要么防御性读取全部规则（烧 token），要么在无知觉中违反约束。自动化检查防止路由表永远滞后于代码现实。
+**Downsides:** 目录归属可能存在争议（如 worker/ 应映射到 architecture-guardrails.md 还是 testing.md）；遗留目录 orchestrator/、core/ 需明确策略。
+**Confidence:** 95%
+**Complexity:** Low
+**Status:** Unexplored
+
+### 3. 替换 Echo Stub 为真实检查
+**Description:** `npm run check:architecture` 和 `check:unused` 当前是 echo 占位符，但 architecture-guardrails.md 将其列为"快速验证"步骤。dependency-cruiser 已在 dependencies 中，应配置真实规则并启用。
+**Rationale:** "幽灵命令"摧毁信任——操作者运行后获得虚假安全感。这是 harness rollout doc 中标记为"已配置"但实际不可用的项目。修复后架构护栏真正生效，每次提交自动验证分层依赖。
+**Downsides:** dependency-cruiser 规则配置需要校准（false positive 可能很多）；可能暴露现有违规需批量清理；knip 仍需安装。
+**Confidence:** 85%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 4. 可信度自评结构化输出
+**Description:** 当前可信度自评（AGENTS.md 5.1）是纯散文，写后即弃。定义轻量 schema（YAML frontmatter 或 JSON），AI 在任务完成时输出结构化数据，收集为 per-task 日志。
+**Rationale:** 从"荣誉系统"转变为可分析数据集。长期可识别：哪些风险标记最常被忽略、哪些"确定信息"后来被证伪、哪些任务类型的自评最不可靠。数据驱动的可信度校准比直觉更可靠。
+**Downsides:** 需要定义和迭代 schema；历史数据无法回溯；存储和索引结构化日志需要基础设施。
+**Confidence:** 80%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 5. 双 CLAUDE.md 职责澄清/合并
+**Description:** 根目录 `CLAUDE.md`（自称为"入口路由"）与 `.claude/CLAUDE.md`（自称为"项目特定指令"）内容重叠且部分矛盾（如交付清单项目不同、TDD 要求表述不同）。需明确职责分割或合并为单一入口。
+**Rationale:** 每次新会话都要在脑中协调两份"主文档"，决策疲劳真实存在。根目录 CLAUDE.md 说"只做入口路由"却包含路由表、规则默认值、dogfood 命令、交付清单——它实际上在做 `.claude/CLAUDE.md` 的事。
+**Downsides:** 合并可能丢失 Claude Code 自动读取 `.claude/CLAUDE.md` 的便利性；分割需要精心设计边界，否则会变成"三份文档"问题。
+**Confidence:** 85%
+**Complexity:** Low
+**Status:** Unexplored
+
+### 6. 解决方案归档 (Post-Task Diff as Institutional Memory)
+**Description:** 每次 L1+ 任务完成后，将 diff、计划、验证命令、结果捕获为结构化记录存入 `docs/solutions/`。按问题类型、受影响模块、解决模式索引。
+**Rationale:** 当前知识随会话结束而蒸发。`docs/exec-plans/completed/` 有计划记录但无解决方案记录。"我们上次如何解决跨层导入违规？""那个 YAML 正则 prerelease 坑是什么来着？"无法回答。
+**Downsides:** 需要建立记录格式和索引约定；维护负担随时间增长；可能变成垃圾堆（需要定期清理）。
+**Confidence:** 75%
+**Complexity:** Medium
+**Status:** Unexplored
+
+### 7. 规则系统自我审计
+**Description:** 系统定期自动审计自身健康：检查 AGENTS.md / CLAUDE.md 中所有链接是否有效、引用的命令是否存在、路径路由是否覆盖实际目录、每条规则是否有对应自动化检测。生成"规则健康报告"。
+**Rationale:** 规则自身也会腐烂——链接失效（如 AGENTS.md §6 引用 `analyze` 命令参数可能已变化）、命令更名、路径迁移、阈值过时。当前是"被动修复"模式，发现问题才修复。主动审计防止规则系统悄悄失效。
+**Downsides:** 审计规则本身也需要维护；可能产生误报（如某些链接故意指向外部资源）；需要决定审计频率和触发条件。
+**Confidence:** 70%
+**Complexity:** Medium
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 1 | 单文件真相源（YAML 替换 AGENTS.md + CLAUDE.md + ARCHITECTURE.md） | 过于激进，会破坏现有工作流；#1 已覆盖规则去重痛点 |
+| 2 | 规则数据库（SQLite/JSON） | 过度工程化，500 行规则不需要数据库查询能力 |
+| 3 | 路径路由自动推导 | 有趣但复杂；静态补全 + CI 检查（#2）更务实 |
+| 4 | Harness 可执行化（TypeScript 模块） | 工程量大；当前核心痛点是同步而非可执行性 |
+| 5 | Harness MCP Server | 同 #4，范围过大，不适合当前阶段 |
+| 6 | Harness 即测试框架 | 同 #4，当前阶段不适用 |
+| 7 | 文档漂移自动检测修复 | 价值高但实现复杂，需解析 markdown 中代码片段 |
+| 8 | 自收缩文档系统 | "零引用"不等于"无价值"，误伤风险高 |
+| 9 | 活架构（自动生成 ARCHITECTURE.md） | 设计决策和迁移计划无法从代码自动生成 |
+| 10 | TODO-DEBT 激活 | 问题真实但范围小，当前优先级不高 |
+| 11 | 自动可信度回填（基于执行轨迹） | 太复杂，需大量基础设施；#4 更务实 |
+| 12 | 自动验证交付（git post-commit） | 被 #4 部分覆盖，实现复杂 |
+| 13 | 验证命令依赖图（DAG） | `check:all` 硬编码问题不严重 |
+| 14 | Agent 性能遥测 | 数据驱动好，但当前更紧迫的是修复规则系统 |
+| 15 | 规则变更金丝雀流水线 | 高杠杆但复杂，适合未来考虑 |
+| 16 | Context Injection API | 太抽象，项目已有 CodeMap CLI |
+| 17 | 类型化文档（TypeScript 接口生成 md） | 与 #1 类似但更局限 |
+| 18 | 自动任务分级 | L0-L3 主观判断难完全自动化 |
+| 19 | 自我修复验证（ESLint auto-fix 扩展） | ESLint --fix 已存在，增量价值有限 |
+| 20 | 失败场景注册表 | 范围较小，当前优先级不高 |
+
+## Session Log
+
+- 2026-04-22: Initial ideation — 40 raw candidates generated across 4 frames (user pain, inversion/automation, assumption-breaking, leverage), 7 survivors after adversarial filtering

package/docs/brainstorms/2026-04-22-rules-entry-docs-phase1-structure-consolidation-requirements.md

@@ -0,0 +1,110 @@
+---
+date: 2026-04
+topic: rules-entry-docs-phase1-structure-consolidation
+---
+
+# Rules 入口文档一期结构收敛
+
+## Problem Frame
+
+当前仓库存在三层入口文档面：`AGENTS.md`、根 `CLAUDE.md`、`.claude/CLAUDE.md`。它们在治理规则、执行流程、验证要求和交付约束上存在交叠，导致 agent 和人类贡献者难以快速判断：
+
+- 哪份文档才是权威来源
+- 哪份文档只是入口路由
+- 被移出的内容应该落到哪里维护
+
+本期要解决的问题不是“规则不够多”，而是“入口面职责不清、共享真相源不清、入口文档容易再次膨胀”。第一阶段因此聚焦**结构收敛**：先把三层入口文档的角色和内容归宿切清，再把后续信任修复、自审机制、历史文档治理等议题留给后续阶段。
+
+| 文档 | 一期目标角色 | 允许内容 | 必须移出 |
+|---|---|---|---|
+| `AGENTS.md` | 严格宪法 | 风险分级、证据协议、文档职责、改动边界、交付底线 | 操作清单、工具专属适配、长命令列表 |
+| `CLAUDE.md` | 纯路由页 | 加载顺序、去哪读下一份文档、去哪找验证规则 | 策略正文、命令清单、默认值、dogfood、交付 checklist |
+| `.claude/CLAUDE.md` | 超薄 adapter | 仅 Claude 专属导入/适配差异 | 通用执行规则、TDD/commit/验证政策、第二套手册 |
+
+## Requirements
+
+**权威模型**
+
+- R1. `AGENTS.md` 必须成为仓库级治理主题的唯一权威来源，覆盖风险分级、证据协议、文档职责分层、改动边界与交付底线。
+- R2. 根 `CLAUDE.md` 必须收缩为纯路由页，只负责告诉 agent 去哪里读，不再作为独立规则面存在。
+- R3. `.claude/CLAUDE.md` 必须收缩为 Claude 专属 adapter，只保留 Claude 需要的导入或装配差异。
+- R4. 每一条规范性要求必须只有一个权威文件；其他入口文档只允许链接或导入，不允许复述为第二套规则面。
+- R5. 本阶段采用零重复原则：入口文档之间不保留提醒式摘要、简化 checklist 或重复政策条目。
+
+**内容归宿**
+
+- R6. 本阶段从 `AGENTS.md`、`CLAUDE.md`、`.claude/CLAUDE.md` 中移出的内容，必须在同一轮迁移到现有文档归宿，不允许留下悬空 `TODO` 作为规范性承接。
+- R7. 本阶段只复用现有文档体系承接迁移内容，例如 `docs/rules/*.md`、`AI_GUIDE.md`、`ARCHITECTURE.md`，不新增中间治理文档。
+- R8. 验证顺序、验证命令、gate 说明等操作性内容，必须归入现有验证或工程规则文档，不再停留在三份入口文档中。
+- R9. 工具发现、命令速查、dogfood、使用提示等内容，必须归入现有 AI 指南或其他既有归宿，不再停留在三份入口文档中。
+- R10. `AGENTS.md` 不得承接从两份 `CLAUDE` 文档移出的操作性细节；宪法层必须保持窄而稳定。
+- R11. 本阶段交付物必须明确给出“被移出内容 → 新归宿文件”的映射，保证后续维护者知道去哪里编辑。
+
+**路由与可发现性**
+
+- R12. 重构完成后，无论从 `AGENTS.md`、根 `CLAUDE.md` 还是 `.claude/CLAUDE.md` 开始，贡献者都应能快速回答三个问题：哪份是权威、下一步去哪读、规则变更时该改哪一份。
+- R13. 收敛后的入口面必须同时保持对 Codex 风格 `AGENTS.md` 读取和 Claude 专属 adapter 加载方式的可发现性。
+- R14. 路由面必须保持简洁，表达导航关系而不是重新长成第二本执行手册。
+
+**阶段范围控制**
+
+- R15. 第一阶段只解决结构角色澄清与内容迁移，不要求同时完成治理自审、自动生成表格或文档防漂移系统。
+- R16. 第一阶段不新增治理中间层、生成式文档系统或新的规则承接机制。
+- R17. 第一阶段不要求重写所有规则本身；只在消除重复、明确权威和修正归宿所必需时调整措辞。
+- R18. 第一阶段不以“完全修复 ghost commands / 验证信任 / archive 身份治理”为成功前提，除非这些问题会阻断结构迁移本身。
+
+## Success Criteria
+
+- [ ] `AGENTS.md` 只保留宪法级内容，不再承载操作清单或工具专属执行细节
+- [ ] 根 `CLAUDE.md` 变为纯路由页，不再内嵌命令清单、默认值、dogfood 或交付 checklist
+- [ ] `.claude/CLAUDE.md` 只保留 Claude 专属 adapter 内容，不再重复通用执行政策
+- [ ] 三份入口文档之间不存在重复的规范性要求
+- [ ] 每一类从入口文档移出的内容都有明确且现成的目标文档承接
+- [ ] 本阶段未引入新的中间治理文档
+- [ ] 维护者能从任一入口文档快速定位权威文件与下一步阅读路径
+
+## Scope Boundaries
+
+- 不在本阶段新增新的治理承接文档
+- 不在本阶段引入文档生成器、自审框架或重复检测自动化
+- 不在本阶段重写全部规则正文，只做必要的归宿与措辞收敛
+- 不把 ghost commands、验证可信度或 archive/live 身份治理作为本阶段主目标
+- 不把 `.claude/CLAUDE.md` 扩展为第二套 Claude 独立规则手册
+
+## Key Decisions
+
+- **D1** `AGENTS.md` 定位为严格宪法：仓库级规范只在这里定权
+- **D2** 根 `CLAUDE.md` 定位为纯路由页：负责导航，不负责再定义规则
+- **D3** `.claude/CLAUDE.md` 定位为超薄 adapter：只保留 Claude 专属差异
+- **D4** 零重复是硬约束：入口文档之间不保留摘要式复述
+- **D5** 所有被移出内容必须同轮迁移，且只允许迁移到现有文档体系
+- **D6** 第一阶段是结构收敛，不是一次性解决全部治理问题
+
+## Alternatives Considered
+
+- **根 `CLAUDE.md` 继续保留轻量执行面**：被否决，因为会继续让路由页承担规则职责
+- **`.claude/CLAUDE.md` 保留完整 Claude 手册**：被否决，因为会继续制造第二套权威入口
+- **`AGENTS.md` 承接更多执行框架或 checklist**：被否决，因为会让宪法层重新膨胀成超级入口
+
+## Dependencies / Assumptions
+
+- 现有 `docs/rules/*.md`、`AI_GUIDE.md`、`ARCHITECTURE.md` 会继续作为 live 文档面存在
+- Claude 侧可以通过 adapter/import 方式消费共享规则，而不必复制整套规则正文
+- 后续规划阶段可以逐项确认“旧 section → 新文件”的精确映射与改写顺序
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+_None — 本阶段的产品级结构决策已收敛。_
+
+### Deferred to Planning
+
+- [Technical] 根 `CLAUDE.md` 最终采用什么路由表现形式最清晰：路径表、场景表、还是最小导航清单
+- [Technical] `.claude/CLAUDE.md` 采用何种最小导入/引用写法，既满足 Claude 使用，又不形成第二套文本面
+- [Technical] 现有入口文档中的每个 section 应如何一对一映射到现有目标文档
+- [Technical] 为保证迁移后仍可发现，是否需要同步微调 `docs/rules/README.md` 或 `AI_GUIDE.md` 的导航表达
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning