@mycodemap/mycodemap 1.9.0 → 2.7.0

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

package/docs/ideation/2026-04-29-ux-install-agent-experience-ideation.md

@@ -0,0 +1,256 @@
+# Ideation: CodeMap User Experience, Installation/Configuration, and Human vs AI Agent Experience
+
+**Date:** 2026-04-29  
+**Focus:** User experience, installation and configuration experience, human vs AI agent experience  
+**Run ID:** 9e3b69d4496d7cc8  
+**Agents dispatched:** 9 (codebase scan + learnings + web research + 6 ideation frames)
+
+---
+
+## Grounding Summary
+
+### Codebase Context
+CodeMap is a TypeScript/Node.js ESM CLI tool generating structured code maps (`AI_MAP.md`, `codemap.json`) for AI/Agent consumption. Uses `commander`, `tree-sitter`, `better-sqlite3`, `hono`. Layered architecture with `src/cli-new/` coexisting alongside `src/cli/`, signaling migration in progress. Heavy AI-agent governance docs (`AGENTS.md`, `CLAUDE.md`, `.claude/`, `.kimi/`, `.agents/`).
+
+### Key Pain Points
+- **Native dependency install friction** (`better-sqlite3`, `tree-sitter` often fail without build tools) — #1 drop-off point
+- **Broken promises in `package.json`** (`check:architecture`, `check:unused` are no-ops)
+- **Dual CLI confusion** (`cli/` + `cli-new/`)
+- **MCP underpowered** (only 2 tools: `codemap_query`, `codemap_impact`)
+- **Agent interface inconsistency** (`--json` not uniform, silent failures, low confidence on explicit paths)
+- **Onboarding overload** — manual skill copying from `examples/`
+- **Agent dogfood rated 6/10** agent-friendly (2026-04-17)
+
+### Past Learnings
+- `init` redesigned as "project state reconciler" with `.mycodemap/` workspace (v1.7 shipped)
+- v0.5.1 install bug: `devDependencies` used at runtime caused global install crashes
+- CLI surface cleanup (v1.0): removed commands with explicit failure + migration messages
+- Three-layer readiness gate (`hard`/`warn-only`/`fallback`) from v1.11
+
+### External Context
+- CLI is beating MCP for coding agents in 2025-2026 due to token efficiency
+- Agent-native patterns: JSON-first, structured errors, predictable exit codes, field filtering, `--help-json`, progress on stderr
+- Prior art: `hubspot-cli` (dual entry point), `gdelt-cli` (machine-readable help), `discord-cli` (YAML structured output)
+- Snyk praised for smoothest onboarding (`snyk test` = seconds)
+- Research pain points: false positives up to 60%, lack of meaningful messages, configuration effort
+
+---
+
+## Raw Candidate Pool
+
+52 candidates generated across 6 ideation frames + 4 cross-cutting combinations. Full list preserved in checkpoint:
+`/tmp/compound-engineering/ce-ideate/9e3b69d4496d7cc8/raw-candidates.md`
+
+### Frame Summary
+| Frame | Count | Key Themes |
+|-------|-------|------------|
+| Pain and friction | 8 | Graceful degradation, presumptive onboarding, unified CLI, agent handshake, streaming MCP, confidence metadata, pre-install check, doctor |
+| Inversion/removal/automation | 8 | Zero-command install, config-as-cache, honest CLI, intent router, JSON-RPC daemon, auto-provisioned skills, failure-to-action, CLI-as-MCP gateway |
+| Assumption-breaking | 8 | Zero-install runtime, split human/agent interface, self-healing init, SDK mode, confidence-first output, progressive disclosure, git-native maps, declarative contract |
+| Leverage/compounding | 8 | WASM-first build, auto-reconciling state, interface contract architecture, zero-config preview, structured errors, skill ecosystem, agent-native mode, uncertainty budget |
+| Cross-domain analogy | 8 | Auto-mode installer, RPG onboarding, Netflix recommendations, language server daemon, tasting menu presets, accessibility profiles, pairing mode, confidence routing |
+| Constraint-flipping | 8 | 100ms install, self-teaching CLI, AI-first default, fingerprint config, unconfigurable tool, MCP-primary, concierge daemon, self-healing promise |
+
+---
+
+## Explicit Rejections (Why These Did Not Survive)
+
+### Rejected: Incremental / Already In Progress
+- **Unified CLI Surface with Subcommand Shadows** — Addresses real pain but is essentially "finish the cli-new migration," already in progress. Not an ideation breakthrough.
+- **Presumptive Onboarding / Config Proposed Not Asked** — Overlaps with existing v1.7 init reconciler design; less precise than Zero-Config Preview.
+- **Streaming MCP with Progress Tokens** — Good but naturally follows from CLI-as-MCP Gateway; not a standalone priority.
+
+### Rejected: Over-Engineered / Heavy Solutions to Simple Problems
+- **Agent Handshake Protocol** — Over-engineered for the actual problem: inconsistent `--json` and silent failures. A formal pre-command negotiation adds complexity; explicit flags/env vars are simpler.
+- **Smart Home "Pairing Mode" Auto-Negotiation** — Auto-detecting agent vs human is fragile (env vars, parent process names). Explicit `--agent` or `CODEMAP_MACHINE=1` is more reliable.
+- **Intent-Based Unified Router / Natural Language** — "Map my backend API surface" is cool but adds NLP complexity for marginal gain over good subcommand naming.
+
+### Rejected: Too Speculative / Missing Prerequisites
+- **100ms Install Mandate: Pure-JS Mode** — More extreme than WASM-first. Node 22+ `node:sqlite` is not universally available. Pure-JS tree-sitter grammar pack doesn't exist yet.
+- **The Embedded CodeMap / SDK Mode** — Powerful but scope explosion. If WASM-first happens, SDK mode becomes natural. Doing both simultaneously is too much.
+- **10x Budget: Agent Concierge Mode / Daemon + IDE Extension** — Visionary but the project already deferred viz/TUI/API (MVP3 PRD). A daemon is an architectural commitment for a future milestone.
+- **No Users, Only Agents: MCP as Primary Interface** — Inverts reality: the CLI exists and works. Making MCP primary would discard human UX investment.
+
+### Rejected: Provocative but Not Actionable
+- **Team of One: The Unconfigurable Tool** — Radical convention-over-configuration that would alienate power users and non-standard projects.
+- **Self-Correcting CLI Surface / Honest CLI** — "CLI audits itself on startup" is harder to implement and explain than a `doctor` command. Overlaps with #7 survivor.
+- **The Declarative Project Contract / codemap.yaml** — Overlaps with existing `.mycodemap/config.json` approach. YAML doesn't add enough value to justify migration.
+
+### Rejected: Framing Devices, Not Technical Directions
+- **Video Game Accessibility Profiles** — Good analogy but essentially combines "split interface" + "AI-first default" into a framing device.
+- **RPG "First Quest" Tutorial Onboarding** — UX polish framing of Zero-Config Preview. The tutorial aspect is surface, not architecture.
+- **Fine Dining "Tasting Menu" Presets** — Same as accessibility profiles; a UX framing of modes that already exist in other forms.
+- **Airport Customs "Green Lane / Red Lane"** — Clever analogy but confidence routing is already captured by Confidence-First Output.
+
+### Rejected: Overlap with Stronger Survivors
+- **Pre-Install Environment Contract Check** — Narrower than WASM-first; solves same problem less completely.
+- **The Self-Healing Init** — Covered by existing init reconciler + doctor command.
+- **Auto-Reconciling Project State** — Extension of existing v1.7 init reconciler; incremental, not breakthrough.
+- **Netflix "Because You Watched" Config Recommendations** — Incremental enhancement to init; not a distinct direction.
+- **Structured Error Recovery Protocol** — Overlaps heavily with Failure-to-Action Protocol.
+- **Configuration as a Cache, Not a Contract** — Interesting reframing but risks making configuration opaque and hard to debug.
+- **Agent-Native Streaming Protocol / JSON-RPC Daemon** — High complexity; daemon mode deferred per project scope.
+- **No Docs Allowed: The Self-Teaching CLI** — Framing device; interactive help is a feature, not a strategic direction.
+- **1M Users, Zero Support: Auto-Configured by Fingerprint** — Overlaps with Zero-Config Preview + existing init reconciler.
+
+---
+
+## Top Survivors (Ranked)
+
+### 1. Machine-Readable Interface Contract as Core Architecture
+**Source:** Leverage frame  
+**Idea:** Define the entire CLI surface as a formal schema (commands, args, flags, output shapes, error codes) in a single source-of-truth file. Generate the human CLI parser, the MCP server, `--help-json`, shell completions, and documentation from this schema. Never hand-write argument parsing or output formatting again.
+
+**Why it survived:**
+- **Highest leverage:** Every new command automatically gets full agent support, MCP exposure, and perfect consistency.
+- **Addresses root cause:** `--json` inconsistency, MCP underpoweredness, and agent-friendly 6/10 rating all stem from hand-maintained dual surfaces.
+- **Compounding:** As the CLI grows, the benefit multiplies. Adding one schema entry creates CLI flag, MCP tool, help text, and completion in one shot.
+- **Grounded:** Agent-native patterns from external research explicitly demand JSON-first, structured errors, and `--help-json`. This makes them free.
+
+**Risks:** Upfront schema design effort; migration of existing commands. Mitigation: incremental adoption, one command at a time.
+
+---
+
+### 2. WASM-First Build, Native-Opt-In Runtime
+**Source:** Leverage frame / Constraint-flip frame  
+**Idea:** Ship `tree-sitter` and `better-sqlite3` as WASM modules by default; detect and opportunistically upgrade to native binaries only when the environment supports it and the user opts in. `npm install codemap` works on every platform, every CI image, every fresh laptop with zero build tools.
+
+**Why it survived:**
+- **#1 pain point killer:** Native dependency install friction is the top drop-off point. This eliminates it entirely.
+- **Proven pattern:** esbuild's WASM fallback mode works in the same ecosystem. `web-tree-sitter` exists. Node 22 ships `node:sqlite` built-in.
+- **Platform coverage:** Reaches 100% of users instead of 70% who have build tools installed.
+- **Agent value:** Eliminates environment-dependent failures that break automated workflows.
+
+**Risks:** Performance regression for very large repos. Mitigation: native opt-in for performance-sensitive users; benchmark WASM vs native.
+
+---
+
+### 3. CLI-as-MCP Automatic Gateway
+**Source:** Inversion frame  
+**Idea:** Implement a generic `--mcp-stdio` adapter that dynamically exposes every CodeMap CLI subcommand as an MCP tool with auto-generated JSON schemas derived from TypeScript types (or the Interface Contract schema). Adding a new CLI command instantly creates a new MCP tool with zero extra work. The entire CLI surface becomes the MCP surface.
+
+**Why it survived:**
+- **Closes the integration gap:** MCP is currently underpowered (2 tools) while CLI has 20+ commands. Agents route around MCP to CLI because of this.
+- **Eliminates drift:** No more hand-maintained MCP server that lags behind CLI features.
+- **Depends on #1:** Best paired with Interface Contract architecture, but can start with TypeScript type reflection.
+- **High agent impact:** Transforms MCP from a second-class citizen into a first-class, complete interface.
+
+**Risks:** MCP schema generation must handle complex nested types. Mitigation: start with simple commands, iterate.
+
+---
+
+### 4. AI-First Default, Human-Pretty Optional
+**Source:** Constraint-flip frame / Assumption-breaking frame  
+**Idea:** Flip the output paradigm. All commands emit structured JSON/NDJSON on stdout by default. A `--human` flag (or auto-detected TTY) pipes through a built-in renderer for tables, spinners, and color. Progress goes to stderr as structured events. This makes the CLI natively composable for agents without special flags.
+
+**Why it survived:**
+- **Directly fixes agent inconsistency:** The current `--json` bolt-on is inconsistent across commands. Making structured output the default forces consistency.
+- **External evidence:** Research confirms CLI beats MCP for token efficiency when structured. This maximizes that advantage.
+- **Low implementation risk:** TTY detection is standard; renderers can be built incrementally.
+- **Composable:** `codemap analyze | jq '.findings[] | select(.severity=="high")'` works out of the box.
+
+**Risks:** Breaking change for existing human users who expect pretty output. Mitigation: major version bump; TTY auto-detection preserves current behavior for interactive use.
+
+---
+
+### 5. Zero-Config Preview / Progressive Commitment Model
+**Source:** Leverage frame / Cross-domain analogy  
+**Idea:** `npx codemap` with no config, no init, no flags performs a full analysis and emits a rich preview (top-level summary, detected project type, sample map). It then offers: "Looks good? Run `codemap --persist` to save configuration and generate full artifacts." No setup, no decisions, no config files until the user sees value.
+
+**Why it survived:**
+- **Snyk-inspired:** Snyk is praised for smoothest onboarding because `snyk test` demonstrates value in seconds.
+- **Low implementation cost:** Can be built on top of existing init reconciler and analysis pipeline.
+- **High conversion impact:** Removes the fear of side effects from trying the tool.
+- **Dual audience:** Humans see a preview and decide; agents can run `--persist` non-interactively.
+
+**Risks:** Preview must be fast (<5 seconds) or it backfires. Mitigation: default to shallow/symbolic scan for preview; deep analysis on demand.
+
+---
+
+### 6. Failure-to-Action Protocol
+**Source:** Inversion frame / Leverage frame  
+**Idea:** Every error returns a structured document containing: what was attempted, the root cause, a machine-readable remediation plan, and a confidence score. For native dep failures: auto-suggest `--wasm-fallback` or a prebuilt binary URL. For agents, errors include the exact next command to try. Errors become state transitions, not dead ends.
+
+**Why it survived:**
+- **Addresses silent failures:** The dogfood report explicitly found `analyze -i find` failing silently with near-empty JSON. This makes every failure explicit and actionable.
+- **Research-backed:** Studies cite "lack of meaningful messages" as a top pain point for code analysis tools.
+- **Agent self-healing:** Agents can attempt remediation without human intervention.
+- **Incremental:** Can be adopted command by command; doesn't require a big-bang rewrite.
+
+**Risks:** Remediation suggestions can be wrong, creating cascading failures. Mitigation: confidence scoring on suggestions; never auto-execute without `--apply-suggestion`.
+
+---
+
+### 7. codemap doctor as Continuous Health Monitor
+**Source:** Pain frame / Constraint-flip frame  
+**Idea:** A living diagnostics command that audits the entire CodeMap ecosystem: detects no-op scripts in `package.json` (`check:architecture`, `check:unused`), verifies native dep health, checks `.mycodemap/` workspace drift, validates CLI vs MCP version skew, and runs agent interface regression checks. Emits both human-readable reports and machine-readable diagnostics. Can run in CI as a health gate.
+
+**Why it survived:**
+- **Familiar pattern:** `npm doctor`, `brew doctor`, `flutter doctor` — users know what to expect.
+- **Addresses broken promises directly:** Surfaces the no-op scripts and other latent brokenness that erodes trust.
+- **CI-friendly:** Machine-readable output enables automated health checks in CI pipelines.
+- **Incremental:** Each diagnostic is a small addition; the command grows over time.
+
+**Risks:** Can become a dumping ground for random checks. Mitigation: categorize diagnostics (install, config, runtime, agent); require evidence tags for each check.
+
+---
+
+### 8. Auto-Provisioned Agent Skills / Self-Distributing Integration
+**Source:** Inversion frame  
+**Idea:** When CodeMap detects it is being invoked by an AI agent (via `KIMI_`, `CLAUDE_`, or `CODEX_` env vars), it automatically writes or updates the appropriate skill files into the agent's skill directory (`.claude/skills/codemap/`, `.kimi/skills/codemap/`). The tool maintains its own bindings, ensuring agents always use the latest integration layer.
+
+**Why it survived:**
+- **Directly solves onboarding overload:** "Manual skill copying from `examples/`" is explicitly cited as a pain point.
+- **Self-describing:** CodeMap knows its own CLI schema better than any human; it should generate its own agent integration.
+- **Version safety:** Skills stay in sync with the installed CodeMap version.
+- **Low cost if paired with #1 and #3:** If we have an interface contract and auto-generated MCP, skill generation is a thin layer on top.
+
+**Risks:** Overwriting user-customized skill files. Mitigation: write to `.mycodemap/skills/` and symlink/copy to agent dirs; never modify existing files without `--force`.
+
+---
+
+## Cross-Cutting Synthesis
+
+Three meta-patterns emerge from the survivors:
+
+### A. Self-Describing Universal API (#1 + #3 + #8)
+If the CLI surface is defined as a machine-readable contract, then:
+- The MCP server generates automatically (#3)
+- Agent skills generate automatically (#8)
+- `--help-json`, shell completions, and docs generate automatically (#1)
+- Every new CLI command is instantly agent-ready
+
+This is the **highest-compounding architectural bet** in the entire ideation set.
+
+### B. Zero-Friction Installation & Onboarding (#2 + #5)
+WASM-first eliminates install failures (#2). Zero-config preview eliminates configuration anxiety (#5). Together they create a "Snyk-class" onboarding where a new user goes from "heard about it" to "seeing value" in under 10 seconds with zero prerequisites.
+
+### C. Trust Architecture (#6 + #7 + confidence implications of #1)
+Failure-to-action protocol makes errors recoverable (#6). Doctor command continuously audits health (#7). Interface contract ensures output schemas are predictable (#1). Together they address the agent-friendly 6/10 rating by making the tool transparent, honest, and self-healing.
+
+---
+
+## Ideas by Dimension
+
+| Dimension | Top Idea |
+|-----------|----------|
+| **Workflow / DX** | Zero-Config Preview (#5) — demonstrates value before asking commitment |
+| **Reliability** | WASM-First Build (#2) — eliminates #1 source of install failures |
+| **Extensibility** | Interface Contract Architecture (#1) — every new feature is agent-ready by construction |
+| **Missing capabilities** | CLI-as-MCP Gateway (#3) — closes the 2-tool gap |
+| **Docs / Knowledge compounding** | Auto-Provisioned Skills (#8) — self-generating agent integration |
+| **Quality / Maintenance** | codemap doctor (#7) — continuous health monitoring |
+| **Agent experience** | AI-First Default (#4) — JSON-first, consistent, composable |
+| **Error handling** | Failure-to-Action Protocol (#6) — structured, recoverable errors |
+
+---
+
+## Next Steps Menu
+
+This ideation artifact identifies promising directions. The next step depends on what you want to do with these ideas:
+
+1. **Refine** — Deep-dive into one or more survivors, exploring edge cases, implementation approaches, and interdependencies.
+2. **Brainstorm** — Select one survivor and define it precisely enough for planning (requirements, boundaries, acceptance criteria). This hands off to `ce:brainstorm`.
+3. **Save and end** — Archive this ideation and return to it later when priorities shift.
+
+> **Routing note:** `ce:ideate` answers "What are the strongest ideas worth exploring?" `ce:brainstorm` answers "What exactly should one chosen idea mean?" `ce:plan` answers "How should it be built?" Do not skip to planning from ideation output.

package/docs/ideation/2026-05-02-subagent-environment-contract-injection-ideation.md

@@ -0,0 +1,183 @@
+---
+date: 2026-05-02
+topic: subagent-environment-contract-retrieval
+focus: Phase 58 subagent environment contract retrieval (revised v2)
+mode: repo-grounded
+run_id: b5a40dda
+---
+
+# Ideation: Subagent Environment Contract Retrieval
+
+> **修订说明（v2）**：经社区实践验证，平台提供的"注入"机制存在根本性缺陷。本 ideation 从"注入模式"调整为"检索模式"：不预编译 prompt snippet 塞给子代理，而是让子代理通过 CLI/MCP 自行查询项目规则。
+
+## Grounding Context
+
+### Codebase Context
+
+- [证据] Phase 58 的问题定义是：Claude Code 与 Codex CLI 都有子代理能力，但项目级环境契约不会可靠进入子代理，导致 `rtk` 包装、commit 格式、测试入口、CodeMap 检索优先级等规则丢失：`.planning/phases/58-subagent-environment-contract-injection/58-CONTEXT.md:29`。
+- [证据] **社区验证：平台注入机制不可靠**——Claude Code `SubagentStart` 的 `additionalContext` append 到 user context，会被上下文压缩丢弃（issue #23885）；`PreToolUse` 的 `updatedInput` 对 Agent tool 静默丢弃（issue #39814）；Codex `developer_instructions` 在 Windows 上不生效（#19399）、项目级自定义角色 `spawn_agent` 不认识（#14579）：详见 `.planning/phases/58-subagent-environment-contract-injection/58-CONTEXT.md` 调研修正声明。
+- [证据] Phase 58 scope 已锁定为环境契约发现、`.mycodemap/env-contract.json`、检索接口、平台适配配置示例、`mycodemap env-contract`、`init`、`doctor`、MCP 集成。`.mycodemap/prompt-snippets/` 已废弃：`.planning/phases/58-subagent-environment-contract-injection/58-CONTEXT.md:74`。
+- [证据] Phase 58 明确 out of scope：不替代平台 spawn/wait/close、不自动重写 `CLAUDE.md` / `AGENTS.md`、不做跨仓库委派、不生成 prompt snippets 进行注入：`.planning/phases/58-subagent-environment-contract-injection/58-CONTEXT.md:103`。
+- [证据] 设计已有 `ContractItem` 模型：`category`、`severity`、`content`、`metadata`、`sources.file/line/hash`：`.planning/phases/58-subagent-environment-contract-injection/58-DESIGN.md:64`。
+- [证据] 现有 role filter 已覆盖 `explore`、`plan`、`edit`、`worker`、`verify`、`default`：`.planning/phases/58-subagent-environment-contract-injection/58-DESIGN.md:109`。
+- [证据] CodeMap 已有可复用落点：`init` 的 plan/apply/receipt 架构：`src/cli/init/reconciler.ts:536`；`doctor` checker orchestrator：`src/cli/doctor/orchestrator.ts:10`；MCP 从 interface contract 自动注册 tools：`src/server/mcp/server.ts:78`。
+- [证据] `.githooks/commit-msg` 实际接受 uppercase tags：`BUGFIX FEATURE REFACTOR CONFIG DOCS DELETE`，并要求 `[TAG] scope: message`：`.githooks/commit-msg:7`、`.githooks/commit-msg:25`、`.githooks/commit-msg:34`。
+
+### Past Learnings
+
+- [证据] 既有 ideation 已把 `init` 定位为项目级 AI 助手基础设施初始化器，并强调不自动改写 `CLAUDE.md` / `AGENTS.md`：`docs/ideation/2026-04-20-mycodemap-init-enhancements-ideation.md:17`。
+- [证据] UX/agent experience ideation 已把机器可读接口契约、CLI-as-MCP、doctor、agent skills 自动分发列为高杠杆方向：`docs/ideation/2026-04-29-ux-install-agent-experience-ideation.md:100`。
+- [证据] dogfood 报告指出 agent 高风险点包括 `--json` 不一致、静默通过、低置信度空结果和噪音输出：`docs/eatdogfood-reports/2026-04-17-eatdogfood-agent-experience.md:85`。
+- [推论] Phase 58 最稳形态不是"把更多规则塞进 prompt"，也不是"编译成可审计 IR 后注入"，而是**"发现真实契约 -> 建立结构化索引 -> 提供统一检索接口 -> 让子代理自行查询"**。
+
+### External Context
+
+- [证据] OpenAI Codex 官方文档确认 Codex 支持 subagent workflows、自定义 agents、`.codex/agents/` TOML、`developer_instructions`、sandbox 继承与显式 spawn：https://developers.openai.com/codex/subagents
+- [证据] Claude Code 官方文档确认 project subagents 位于 `.claude/agents/`，subagent 有独立 context window、custom system prompt、tool access；subagent file body 成为 system prompt，且不会收到完整 Claude Code system prompt：https://docs.anthropic.com/en/docs/claude-code/sub-agents
+- [推论] 两个平台都提供了"平台级子代理运行时"，但**项目级契约注入机制存在已知缺陷**。CodeMap 作为项目层工具，应提供**检索能力**而非**注入能力**。
+
+### Risk Snapshot
+
+- [推论] 最大风险从"把错误规则注入子代理"变为"子代理不执行检索提示，导致不知道规则"。
+- [证据] 本轮 grounding 发现具体冲突风险：Phase 58 示例里出现 lowercase tags，但当前 hook 接受 uppercase tags；真实实现必须以 hook 或更权威来源为准。
+- [证据] CodeMap CLI 本轮对真实存在的 phase Markdown 文件执行 `analyze -i read` 返回"未找到文件"，已记录到 `.mycodemap/issues/codemap-issues.md`。
+
+## Ranked Ideas
+
+### 1. Env Contract Discovery + Retrieval Index
+
+**Description:** [推论] 把 env-contract 生成做成"发现+索引"流程。扫描仓库规则源（hooks、docs、configs），提取结构化契约项，输出 `.mycodemap/env-contract.json` 作为**检索索引**。子代理通过 `mycodemap env-contract --for <type> --json` 或 MCP `codemap_env_contract` 自行查询。
+
+**Rationale:** [推论] 这是 Phase 58 v2 的核心。不依赖平台注入机制，而是利用子代理自身的 Bash/MCP 工具能力。规则始终最新，跨平台一致，上下文占用极小（只有一条检索提示）。
+
+**Downsides:** [观点] 依赖子代理自觉执行检索提示；Explore/Plan 子代理动机强，Edit/Worker 可能直接开干。需通过简洁明确的提示和 agent type 适配来缓解。
+
+**Confidence:** 90%
+
+**Complexity:** Medium
+
+**Status:** Expanded to Phase 58 Design v2
+
+---
+
+### 2. Contract Consistency Checker (冲突检测降级)
+
+**Description:** [推论] 契约发现过程中检测多源冲突（如 hook 要求大写 tags，文档示例写小写）。输出 `conflicts[]` 到 `env-contract.json`，`mycodemap doctor` 报告冲突并给出 recommendation。不阻断生成，只 warn。
+
+**Rationale:** [推论] 旧设计中的"冲突优先编译器"过于厚重（quarantined 状态、阻断策略）。降级为一致性检查更轻量，也避免变成小型规则推理系统。冲突由使用者决定以谁为准。
+
+**Downsides:** [观点] 不自动解决冲突，需要人工判断。但自动解决冲突的权重分配本身就需要人工定义，warn-only 是务实的起点。
+
+**Confidence:** 88%
+
+**Complexity:** Low-Medium
+
+**Status:** Incorporated into Phase 58 Design v2
+
+---
+
+### 3. Platform Adapter Config Generator
+
+**Description:** [推论] `mycodemap env-contract --as-hook-config` 生成 Claude Code `SubagentStart` hook 配置；`mycodemap env-contract --as-codex-agent` 生成 Codex `developer_instructions` 检索提示模板。作为 `.mycodemap/assistants/` 下的 copy-paste 示例，不自动修改用户配置。
+
+**Rationale:** [推论] 降低用户接入门槛。用户不需要手写 hook JSON 或 TOML，只需 copy-paste 生成的示例到 `.claude/settings.json` 或 `.codex/agents/`。
+
+**Downsides:** [观点] Codex agent 配置存在已知 bug（#19399, #14579），生成的配置在部分平台可能不生效。需在文档中标注已知限制和备选方案。
+
+**Confidence:** 85%
+
+**Complexity:** Low
+
+**Status:** Incorporated into Phase 58 Design v2
+
+---
+
+### 4. Agent Readiness Doctor With Probe Matrix
+
+**Description:** [推论] 为每个 critical/high contract item 增加 probe 定义：来源 hash、抽取规则、验证命令、失败样例。`doctor` 新增 env-contract checker，报告 missing、stale、conflicting、MCP-tool-missing。
+
+**Rationale:** [推论] 这把"生成了契约"提升为"契约可被真实 CLI/subprocess 验证"，贴合仓库真实场景验证阈值，也复用现有 doctor 架构。
+
+**Downsides:** [观点] probe 初版应覆盖少数关键契约，如 commit、test、retrieval、output mode；不要一开始覆盖所有 docs/rules。
+
+**Confidence:** 84%
+
+**Complexity:** Medium
+
+**Status:** Unexplored
+
+---
+
+### 5. Context-Budgeted Contract Fetch
+
+**Description:** [推论] `mycodemap env-contract --for <role>` 和 MCP `codemap_env_contract` 支持按 agent type 过滤返回契约；无 MCP 环境使用 `.mycodemap/env-contract.json` 文件直接读取。
+
+**Rationale:** [推论] 子代理上下文有限，按类型过滤可减少返回数据量。MCP 强时动态拉取，MCP 不可用时仍能靠文件工作。
+
+**Downsides:** [观点] 这是检索模式的自然延伸，不是独立架构方向。
+
+**Confidence:** 82%
+
+**Complexity:** Low
+
+**Status:** Incorporated into Phase 58 Design v2
+
+---
+
+### 6. Failure-Mode-First Contract Items
+
+**Description:** [推论] 契约项不写成长手册，而是优先表达高频失败边界：不要裸 shell（本仓需 `rtk`）、不要错误 commit tag、不要用错误测试入口、低置信度空结果必须声明、机器输出必须保持 JSON/NDJSON 纯净。
+
+**Rationale:** [推论] 子代理查询结果需要快速消化，负面边界比完整规范更能减少实际事故，也能自然支持失败场景验证。
+
+**Downsides:** [观点] 如果只写禁止项，可能缺少正向示例；每个 critical item 至少应包含一个正确命令或正确格式。
+
+**Confidence:** 78%
+
+**Complexity:** Low-Medium
+
+**Status:** Unexplored
+
+---
+
+### 7. Subagent Preflight Receipt
+
+**Description:** [推论] 子代理执行任务前，通过检索获取契约并在输出中简短 ACK（如"已检索项目规则：使用 rtk 包装、commit 格式 [TAG] scope: message"）。父代理或验证脚本可观测到 ACK。
+
+**Rationale:** [推论] 让"检索成功"成为可观测事件。如果子代理输出中没有规则 ACK，说明它可能忽略了检索提示。
+
+**Downsides:** [观点] 不能要求所有子代理都复诵规则；ACK 应保持极短，主要用于验证与高风险任务。
+
+**Confidence:** 72%
+
+**Complexity:** Medium
+
+**Status:** Unexplored
+
+---
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|---|-----------------|
+| 1 | Conflict-First Env Contract Compiler (v1) | [推论] 旧设计假设"注入可靠"，但社区验证表明平台注入机制不可靠。"编译器+阻断"模型过于厚重，降级为"发现+索引+一致性检查"。 |
+| 2 | EnvContract IR And Adapter Compiler (prompt snippet lowering) | [推论] 旧设计包含生成 prompt snippets 并注入子代理。因注入路径不可靠，不再生成 `.mycodemap/prompt-snippets/`。适配层改为"检索指引生成"。 |
+| 3 | Role-scoped prompt packs / wristband / checklist | [推论] 是必要呈现形态，但已被检索模式覆盖。子代理通过查询获取适合自身的规则子集。 |
+| 4 | Source freshness hash check | [推论] 是 doctor/probe matrix 的组成部分，不够独立。 |
+| 5 | Init receipt with manual injection tasks | [推论] 已在 Phase 58 scope 和现有 init receipt 架构中，适合作为实现细节。 |
+| 6 | MCP env contract tool standalone gate | [推论] MCP 很重要，但 standalone 版本过度依赖 MCP；已并入检索接口设计。 |
+| 7 | Platform-specific snippet packs | [推论] 已被平台适配配置生成覆盖。 |
+| 8 | Contract as environment API | [推论] 是检索模式的核心原则，而非单独产品方向。 |
+| 9 | 10x-token dossier | [观点] 可作为 debug mode，但主路径需要最小必要契约。 |
+| 10 | Solo maintainer profile | [观点] 太窄，和 default profile 区别不够大。 |
+| 11 | Multi-team role lattice | [推论] 方向合理，但 scenario profiles 更简单、更适合 Phase 58。 |
+| 12 | No-platform bootstrap packet | [观点] 是边界原则，不是独立实施项。 |
+| 13 | Subagent context gap report | [推论] 适合作为 doctor/fetch 的报告视图。 |
+| 14 | JSON/NDJSON contract audit stream | [推论] 是检索接口必备输出属性，不是独立方向。 |
+
+## Session Log
+
+- 2026-05-02: 初始 ideation（v1）；假设"注入可靠"，提出冲突优先编译器、prompt snippet 生成等方案。
+- 2026-05-02: 社区验证：发现 Claude Code `additionalContext` 压缩丢弃、`updatedInput` 静默丢弃、Codex agent 配置 bug 等关键证据。
+- 2026-05-02: **修订为 v2**：从"注入模式"全面转向"检索模式"，废弃 prompt snippets 和冲突编译器，改为检索索引 + 一致性检查 + 平台适配配置生成。
+- 2026-05-02: Phase 58 Context 和 Design 文档已同步更新为 v2。