@mycodemap/mycodemap 0.5.1 → 1.9.0

package/docs/brainstorms/999.1-mycodemap-init-enhancements-requirements.md

@@ -0,0 +1,166 @@
+---
+date: 2026-04-20
+topic: mycodemap-init-enhancements
+---
+
+# mycodemap init 增强：项目状态收敛器
+
+## Problem Frame
+
+当前 `mycodemap init` 命令仅在项目根目录创建一个 `mycodemap.config.json` 文件。随着 CodeMap 功能扩展，项目已经出现多类 AI 助手基础设施：`.mycodemap/` 工作区、日志目录、workflow 目录、git hooks、AI 护栏规则等。问题不只是“缺少初始化入口”，而是项目状态已经进入半迁移阶段：工具实际行为、文档承诺、配置路径和 `.mycodemap/` 产品心智不再完全一致。
+
+这导致：
+
+- 新用户不清楚 CodeMap 生成了哪些文件
+- git hooks 和 AI 规则需要手动复制和配置
+- 配置文件和输出目录的命名不一致（根目录 `mycodemap.config.json` vs `.mycodemap/` 目录）
+- 旧配置、旧目录、已有 hooks、已有 AI 上下文文件等状态被隐式处理，用户无法判断哪些已经完成、哪些需要手动处理
+- `init` 容易给出“初始化完成”的印象，但实际只完成了部分基础设施接入
+
+本需求将 `init` 命令升级为“项目状态收敛器”：先扫描当前仓库状态，识别 config / workspace / hooks / rules / first-run guide 的 drift，再向用户展示将要收敛的差异，最后执行选择的动作并产出可解释的 receipt。成功标准不再是“写出一个配置文件”，而是“用户和后续 AI/CLI 都能知道这个项目的 CodeMap 基础设施处于什么状态、做过什么、还缺什么”。
+
+## Requirements
+
+**状态扫描与收敛**
+
+- R1. `init` 启动时先扫描当前项目状态，包括 `.mycodemap/`、根目录旧配置、旧 `.codemap/`、hooks、rules、首次运行标记和需要人工接入的 AI 上下文文件
+- R2. `init` 将每个被扫描资产分类为明确状态：`missing`、`already-synced`、`migrated`、`installed`、`conflict`、`manual-action-needed` 或 `skipped`
+- R3. 交互式模式下，`init` 在写入文件前展示 reconciliation preview，说明将创建、迁移、覆盖、跳过或要求人工处理的项目
+- R4. `init` 执行后输出 human-readable receipt，并在 `.mycodemap/status/init-last.json` 写入 machine-readable receipt
+- R5. receipt 必须区分“已完成动作”和“仍需人工动作”，不得用单个“初始化完成”掩盖部分完成状态
+- R6. 重复运行 `init` 必须是幂等的：已同步资产显示 `already-synced`，漂移资产显示 `conflict` 或 `manual-action-needed`
+
+**Workspace 集中化**
+
+- R7. `init` 命令创建 `.mycodemap/` 目录作为所有 mycodemap tool-owned 资源的根目录
+- R8. 配置文件命名为 `.mycodemap/config.json`（不再使用根目录的 `mycodemap.config.json` 作为 canonical 配置）
+- R9. `.mycodemap/` 内部使用统一子目录结构：`logs/`、`workflow/`、`rules/`、`hooks/`、`storage/`、`status/`
+- R10. 若根目录已存在旧配置（`mycodemap.config.json` 或 `codemap.config.json`），自动复制内容到 `.mycodemap/config.json`，保留旧文件并在 receipt 中提示用户可删除
+- R11. 清理 `.codemap` → `.mycodemap` 的旧迁移提示，仅保留与本次 root config → `.mycodemap/config.json` 收敛有关的提示
+- R12. 如果旧 `.codemap/` 或旧 storage 路径仍存在，`init` 必须在 receipt 中显式标记为 drift，而不是静默忽略
+
+**Git Hooks 安装与同步**
+
+- R13. `init` 检测目标项目是否为 Git 仓库；若不是，workspace 和 rules 仍可收敛，hooks 状态标记为 `skipped` 或 `manual-action-needed`
+- R14. 若目标项目 `.git/hooks/` 已存在同名 hooks（pre-commit / commit-msg），检测内容差异并提示用户选择：保留、跳过、覆盖或 shim 合并
+- R15. shim 合并策略：`.git/hooks/pre-commit` 和 `commit-msg` 为轻量 shim 脚本，调用 `.mycodemap/hooks/` 下的完整 hooks 实现，保留用户已有的 hooks 逻辑
+- R16. `.mycodemap/hooks/` 下的 hooks 内容为 CodeMap 自身 `.githooks/` 下 hooks 的完整复制
+- R17. 每次运行 `mycodemap init` 时检查 hooks 同步状态（对比文件哈希），如有变化提示用户更新
+- R18. hooks 冲突检测基于文件内容哈希，而非仅文件名存在性
+- R19. hooks 的安装、跳过、冲突和人工处理结果必须写入 receipt
+
+**AI 护栏规则生成与同步**
+
+- R20. `init` 生成内置精简规则集到 `.mycodemap/rules/` 目录（通用型，不依赖项目类型）
+- R21. 规则文件按分类子目录组织：`.mycodemap/rules/commit/`、`.mycodemap/rules/test/`、`.mycodemap/rules/lint/` 等
+- R22. 规则注入通过 CLI 输出提示信息，引导用户手动在 `CLAUDE.md` 或 `AGENTS.md` 中添加引用，不自动修改用户文件
+- R23. CLI 输出必须包含可复制的引用片段，说明应把 `.mycodemap/rules/` 作为 tool-owned rules bundle 引入用户自己的 AI 上下文文件
+- R24. 每次运行 `mycodemap init` 时检查规则文件同步状态，如有变化提示用户更新并显示 diff 预览
+- R25. 规则文件内容参考 CodeMap 自身 `docs/rules/` 下的文档提炼生成
+- R26. 规则同步状态和仍需人工添加的引用动作必须写入 receipt
+
+**init 交互模式**
+
+- R27. 三个子功能（workspace 集中化、hooks 安装、rules 注入）以“一键选择”方式呈现，用户可以一次性勾选/取消要收敛的目标状态
+- R28. 提供 `--yes` 标志跳过交互，使用默认选择全部启用
+- R29. 提供 `--interactive` 标志显式进入交互模式（默认行为）
+- R30. init 流程输出采用“状态收敛器”风格：每项都有明确状态标记（✅ done / ⚠️ manual action / ❌ conflict / ⏭ skipped）
+
+**首次运行引导**
+
+- R31. 首次运行（无配置、无标记文件）时显示精简欢迎信息：init → generate → help
+- R32. 当用户实际运行 init 后，在 init 输出中根据 receipt 展示下一步，而不是固定展示同一套后续步骤
+- R33. 若 receipt 中存在 `manual-action-needed`，后续步骤必须优先展示人工动作（如向 `CLAUDE.md` / `AGENTS.md` 添加规则引用）
+
+**路径兼容性**
+
+- R34. `init` 将 `.mycodemap/config.json` 作为 desired canonical config，并把根目录旧配置视为迁移来源
+- R35. 本 phase 不要求修改非 `init` 命令的路径解析逻辑；如果 downstream 命令仍可能读取旧路径，`init` 必须在 receipt 中将 downstream config readiness 标记为 `manual-action-needed` 或 `conflict`
+- R36. 规划阶段必须验证最小路径变更边界，避免 `init` 创建的新 canonical config 被后续命令忽略
+
+**Git 集成**
+
+- R37. `init` 自动在目标项目的 `.gitignore` 中追加 `.mycodemap/logs/`，确保本地日志不进入版本控制
+- R38. 若 `.gitignore` 中已存在该条目，静默跳过，不重复追加
+- R39. `.gitignore` 的新增、跳过或冲突状态必须写入 receipt
+
+**资产台账与兼容引导**
+
+- R40. `.mycodemap/status/init-last.json` 必须按资产粒度记录最少必要事实：资产类型、ownership、origin、当前状态，以及用于重跑对账的 hash / version 线索；避免后续 rerun 只能依赖启发式猜测
+- R41. receipt 必须显式解释 canonical `.mycodemap/config.json` 与根目录旧配置、旧 storage 路径之间的关系，给出 forward guidance，而不是只报告“发现旧文件”
+- R42. 对于本 phase 内可逆的收敛动作（如配置迁移、hook shim 接入、`.gitignore` 追加），receipt 必须提供简短 rollback hint，帮助用户恢复到执行前的项目状态
+- R43. 本 phase 的 machine-readable receipt 兼作轻量 managed asset ledger，只保留会在 rerun / support / drift 检测中复用的事实，不引入新的独立状态数据库或额外 sync surface
+
+## Success Criteria
+
+- [ ] 全新项目运行 `mycodemap init` 后，终端输出 reconciliation preview 和执行后的 receipt
+- [ ] 全新项目运行 `mycodemap init` 后，`.mycodemap/` 目录包含完整的子目录结构（config.json、logs/、workflow/、rules/、hooks/、storage/）
+- [ ] 已有旧配置（根目录 `mycodemap.config.json`）的项目运行 init，旧配置自动迁移到新位置，旧文件保留但提示删除
+- [ ] 已有旧 `.codemap/` 或旧 storage 路径的项目运行 init，receipt 明确标记 drift 和下一步动作
+- [ ] 非 Git 项目运行 init，workspace / rules 可以完成收敛，hooks 被标记为 `skipped` 或 `manual-action-needed`
+- [ ] Git 项目运行 init，若已有 hooks，用户可选择覆盖/跳过/shim；shim 模式下用户原有 hooks 逻辑不被破坏
+- [ ] 规则文件成功生成到 `.mycodemap/rules/` 子目录，内容符合 CodeMap 自身规则文档的质量标准
+- [ ] `init` 不自动修改 `CLAUDE.md` / `AGENTS.md`，但输出可复制的规则引用片段
+- [ ] `.mycodemap/status/init-last.json` 包含 config、workspace、hooks、rules、gitignore、manual actions 的结构化状态
+- [ ] 重复运行 `mycodemap init` 时，receipt 能基于已记录的资产事实稳定地区分 `already-synced`、`conflict`、`manual-action-needed`
+- [ ] receipt 对已执行的可逆动作提供简短 rollback hint，用户无需阅读源码即可理解如何回退
+- [ ] `npm run check:all` 通过（类型检查 + 测试 + Lint）
+- [ ] init 输出风格与现有 CLI 保持一致（chalk 颜色 + emoji + 中文）
+
+## Scope Boundaries
+
+- 不为 AI 规则创建新的 CLI 子命令（如 `mycodemap sync-rules`）
+- 不修改非 mycodemap 相关的项目文件（如 package.json）
+- 不自动修改用户项目的 `CLAUDE.md` / `AGENTS.md`
+- 不支持非 Git 版本控制系统（如 Mercurial）
+- 不根据项目类型（npm/python/go 等）动态生成不同规则集
+- 不在本 phase 中承诺重写所有非 `init` 命令的配置读取路径；若必要，只允许规划阶段确认最小兼容改动
+- 不在本 phase 中新增 `.mycodemap/exports/` 或 `.mycodemap/assistants/` 目录；当前只要求生成可复制的接入片段
+- 不把 `.mycodemap/status/init-last.json` 扩展为通用状态数据库；仅记录 init 重跑与支持所需的最小事实
+
+## Key Decisions
+
+- **D-00** `init` 是项目状态收敛器：先扫描和解释现状，再执行选择的收敛动作
+- **D-01** 配置文件收到 `.mycodemap/config.json`：简化命名，放在命名空间目录下冲突概率低
+- **D-02** 自动迁移旧配置：零用户操作，复制后提示删除旧文件
+- **D-03** receipt 是成功输出的核心：所有完成、跳过、冲突和人工动作都必须显式呈现
+- **D-05** hooks 通过 `.git/hooks/` 接入：不修改 Git 全局配置，保持项目隔离
+- **D-16** shim 合并策略：轻量 shim 调用 `.mycodemap/hooks/` 的完整实现，不破坏用户已有逻辑
+- **D-17** 非 Git 项目不阻止 workspace / rules 收敛：hooks 以 `skipped` 或 `manual-action-needed` 呈现
+- **D-18** 自动追加 `.mycodemap/logs/` 到 `.gitignore`：防止本地日志污染版本控制
+- **D-19** 两步欢迎流程：未 init 时不展示无法执行的步骤，init 后根据 receipt 展示下一步
+- **D-20** 用户 AI 上下文文件属于 team-owned surface：工具只生成引用片段，不自动改写
+- **D-21** `init-last.json` 兼作轻量 managed asset ledger：记录 ownership / origin / hash / status 等会被 rerun 复用的事实，而不是额外引入独立 ledger 系统
+- **D-22** assistant compatibility pack 先收敛为 receipt 中的 copy-paste 片段：本 phase 不新增 `.mycodemap/exports/` / `.mycodemap/assistants/` 目录面
+- **D-23** 当前 phase 优先显式资产级 reconcile，而不是引入 `Minimal / Guardrails / Team Ready` 之类 profile 抽象，以免遮蔽 drift 与人工动作细节
+
+## Alternatives Considered
+
+- **独立 ledger / manifest 文件面**：有价值，但当前先吸收到 `.mycodemap/status/init-last.json`，避免过早引入第二套状态 surface
+- **assistant compatibility pack 目录化**：长期可能有价值，但当前用 receipt + copy-paste 片段即可满足“不自动改用户文件”的目标
+- **bootstrap profiles（Minimal / Guardrails / Team Ready）**：适合作为后续体验优化；本 phase 先保留资产级选择，确保状态透明优先于预设抽象
+
+## Dependencies / Assumptions
+
+- 目标项目已安装 mycodemap CLI（全局或本地）
+- CodeMap 自身 `.githooks/` 目录存在 `pre-commit` 和 `commit-msg` 作为内置 hooks 源
+- 用户使用支持环境变量或文件引用的 AI 工具（Claude Code、Cursor 等）来消费护栏规则
+- `.mycodemap/status/init-last.json` 是 init 自己的状态 contract，不是全局稳定 public API
+
+## Outstanding Questions
+
+### Resolve Before Planning
+
+_None — all product decisions resolved._
+
+### Deferred to Planning
+
+- [Needs research] 内置 hooks 源文件（`.githooks/pre-commit` 和 `.githooks/commit-msg`）在打包发布后的路径解析方式（相对于 CLI 安装位置）
+- [Technical] shim 脚本的具体实现方式（shell 脚本 vs Node.js 脚本），取决于 `.githooks/` 中现有 hooks 的实现方式
+- [Technical] 规则文件的 diff 预览实现方式（使用内置 diff 还是依赖外部工具）
+- [Technical] `--yes` 和 `--interactive` 选项的 CLI 注册方式（ commander.js 的选项配置）
+- [Technical] downstream 命令读取 `.mycodemap/config.json` 的最小兼容边界，避免本 phase 扩大到全 CLI 路径重构
+
+## Next Steps
+
+-> `/ce:plan` for structured implementation planning

package/docs/exec-plans/README.md

@@ -14,6 +14,9 @@
 - `completed/` 当前包含：
   - `2026-03-03-deps-path-extension-fix.md`
   - `2026-03-03-post-task-plan.md`
+  - `2026-04-17-eatdogfood-codemap-cli.md`
+  - `2026-04-19-prerelease-trusted-publishing-fix.md`
+  - `harness-engineering-rollout.md`
 - `tech-debt/` 当前包含：
   - `2026-03-15-lint-guardrail-gap.md`
 

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

@@ -0,0 +1,96 @@
+---
+date: 2026-04-20
+topic: mycodemap-init-enhancements
+focus: 把 mycodemap init 从“创建根目录配置文件”升级为“项目级 AI 助手基础设施初始化器”
+mode: repo-grounded
+---
+
+# Ideation: mycodemap init enhancements
+
+## 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 + 明确的人工接入片段。
+
+## 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
+**Description:** [推论] 把 first-run guide 重写成状态驱动的 remediation concierge，并用少量 profile（如 Minimal / Guardrails / Team Ready）承载交互式一键选择。
+**Rationale:** [推论] 这是最低成本修复 mental model 的方法：既改善第一分钟体验，也避免 init 变成一长串低层开关。
+**Downsides:** [观点] profile 设计如果过粗，会掩盖复杂边界；如果过细，又会退化回问卷。
+**Confidence:** 84%
+**Complexity:** Low-Medium
+**Status:** Unexplored
+
+## Rejection Summary
+
+| # | 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 |

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

@@ -0,0 +1,119 @@
+---
+date: 2026-04-22
+topic: rules-entry-docs-optimization-consolidated
+focus: 融合两份 2026-04-22 ideation 的最佳部分，形成更强的 rules / AGENTS.md / CLAUDE.md 终稿提案
+mode: repo-grounded
+sources:
+  - 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
+---
+
+# Ideation: Consolidated rules / AGENTS.md / CLAUDE.md optimization
+
+## 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
+
+### Synthesis
+
+- [推论] 文档一的强项是“战略方向正确、外部 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 的“最小必要验证”从口号变成真正可信的路由；它还顺手修掉最伤信任的“跑了命令但其实没验证”的问题。
+**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
+
+### 3. 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”区分得非常清楚，否则用户会误会规则被放松。
+**Confidence:** 93%
+**Complexity:** Medium
+**Status:** Explored
+
+### 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，路径化后会把问题从“根太长”转移成“子规则散落”。
+**Confidence:** 91%
+**Complexity:** Medium-High
+**Status:** Explored
+
+### 5. 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`。
+**Downsides:** [观点] 这是文档身份治理，不是炫目的功能增强；但如果不做，后续所有瘦身都会被旧文档重新污染。
+**Confidence:** 92%
+**Complexity:** Low-Medium
+**Status:** Explored
+
+### 6. 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:** [观点] 这已经逼近“小型文档治理系统”了；若一次做太大，容易反向过度工程化。
+**Confidence:** 88%
+**Complexity:** Medium
+**Status:** Explored
+
+## 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 知道去哪读、何时验证、谁在阻断”，不负责承载全部细节、全部命令、全部历史。**
+
+## Rejection Summary
+
+| # | Idea | Reason Rejected |
+|---|------|-----------------|
+| 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”的根问题。 |
+
+## 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。

package/docs/lesson-learn/2026-04-19-prerelease-trusted-publishing-fix.md

@@ -0,0 +1,119 @@
+# 预发布自动发布故障修复记录
+
+> 日期：2026-04-19  
+> 状态：已修复  
+> 范围：npm Trusted Publishing / GitHub Actions 发布链路 / 发布前版本校验
+
+## 问题摘要
+
+- [证据] `v0.5.2-beta.0` 首次真实自动发布失败，失败 run 为 `24632519866`。
+- [证据] 失败并不是 npm Trusted Publisher 配置缺失，而是发布链路中有两个代码层问题：
+  1. `scripts/pre-release-check.js:112` 的 YAML 版本提取正则不支持 prerelease 版本；
+  2. `.github/workflows/publish.yml:124` 在发布 prerelease 版本时没有显式传 `npm publish --tag <preid>`。
+- [证据] 修复后，`v0.5.2-beta.1` 的真实自动发布成功，成功 run 为 `24632744587`。
+- [证据] 发布完成后，npm dist-tag 状态为：
+  - `latest -> 0.5.1`
+  - `beta -> 0.5.2-beta.1`
+
+## 现象
+
+### 现象 1：发布前检查误判版本不一致
+
+- [证据] `package.json`、`llms.txt`、`AI_GUIDE.md`、`AI_DISCOVERY.md` 都是 `0.5.2-beta.0`。
+- [证据] 但 `scripts/pre-release-check.js` 把 `ai-document-index.yaml` 的版本解析成了 `0.5.2`，导致 prerelease 版本无法被完整识别。
+- [推论] 这会让发布前检查在 beta/rc 版本上产生错误噪音，阻断或误导发布判断。
+
+### 现象 2：GitHub Actions 在 npm publish 阶段失败
+
+- [证据] `v0.5.2-beta.0` 的发布 run `24632519866` 在 `Publish to NPM` 步骤失败。
+- [证据] 关键报错是：`You must specify a tag using --tag when publishing a prerelease version.`
+- [推论] 这说明 Trusted Publishing 本身已经工作，问题不在 npm 仓库授权，而在 workflow 对 prerelease 版本没有传 dist-tag。
+
+## 根因分析
+
+### 根因 1：YAML prerelease 解析规则过窄
+
+- [证据] `scripts/pre-release-check.js:114` 之前只匹配 `x.y.z`，不匹配 `x.y.z-beta.0` 这类版本。
+- [证据] 修复提交：`73cf296 [BUGFIX] release: support prerelease YAML version checks`
+- [推论] 只要版本同步文件里存在 prerelease，旧逻辑都会把它截断，导致版本一致性检查不可靠。
+
+### 根因 2：npm@11 对 prerelease 发布要求显式 dist-tag
+
+- [证据] `.github/workflows/publish.yml:83` 现在新增 `Determine npm dist-tag` 步骤，从版本号推导 npm tag。
+- [证据] `.github/workflows/publish.yml:128` 现在会在 OIDC 与 `NPM_TOKEN` fallback 两条路径上统一传 `--tag "$DIST_TAG"`。
+- [证据] 修复提交：`93a1a7a [BUGFIX] release: publish prereleases with dist-tags`
+- [推论] 升级到 `npm@11.5.1` 以后，prerelease 发布必须显式指定 `--tag beta` / `--tag rc` 等，否则 registry 会拒绝发布。
+
+## 修复方案
+
+### 修复 1：放宽 prerelease 版本匹配
+
+- [证据] 在 `scripts/pre-release-check.js:112` 附近，把 YAML 版本提取规则改为支持 `(\d+\.\d+\.\d+(?:-[\w.]+)?)`。
+- [结果] `npm run docs:check:pre-release` 现在可以正确识别 `0.5.2-beta.1`。
+
+### 修复 2：在 workflow 中显式推导并传递 npm dist-tag
+
+- [证据] 在 `.github/workflows/publish.yml:83` 新增 `Determine npm dist-tag`：
+  - 稳定版默认 `latest`
+  - prerelease 从 preid 推导，例如 `beta`、`rc`
+- [证据] 在 `.github/workflows/publish.yml:124` 的发布步骤中：
+  - OIDC 路径使用 `npx npm@11.5.1 publish --tag "$DIST_TAG"`
+  - Token fallback 路径使用 `npx npm@11.5.1 publish --tag "$DIST_TAG" --provenance`
+- [结果] `v0.5.2-beta.1` 成功发布到 npm 的 `beta` dist-tag。
+
+### 修复 3：同步发布说明与验证规则
+
+- [证据] 文档已同步到以下位置：
+  - `docs/PUBLISHING.md`
+  - `docs/rules/validation.md`
+  - `docs/rules/pre-release-checklist.md`
+- [推论] 这一步是为了把“prerelease 必须显式传 dist-tag”的真实约束写回文档，避免下次再次按旧认知排障。
+
+## 处理过程
+
+1. [证据] 先完成 `0.5.2-beta.0` 版本准备并推送 tag，触发首次真实发布。
+2. [证据] 发现本地 `docs:check:pre-release` 被 YAML prerelease 解析问题阻断。
+3. [证据] 修复 `scripts/pre-release-check.js` 后，本地预检查、测试、构建、打包验证全部通过。
+4. [证据] 首次远端 run `24632519866` 仍在 `Publish to NPM` 失败，暴露 `npm publish --tag` 缺失问题。
+5. [证据] 修复 workflow 和文档后，准备 `0.5.2-beta.1` 并重新推送。
+6. [证据] 第二次远端 run `24632744587` 成功完成 `Publish to NPM`、`Generate Release Notes`、`Create GitHub Release`。
+
+## 验证结果
+
+### 本地验证
+
+- [证据] `npm run docs:check:pre-release` 通过
+- [证据] `npm test` 通过，`916/916` 测试通过
+- [证据] `npm run build` 通过
+- [证据] `npm run validate-pack` 通过
+
+### 远端验证
+
+- [证据] GitHub Actions 成功 run：`24632744587`
+- [证据] GitHub Release 已创建：`v0.5.2-beta.1`
+- [证据] npm registry 已更新 `beta` dist-tag 到 `0.5.2-beta.1`
+
+## 相关提交
+
+- [证据] `73cf296 [BUGFIX] release: support prerelease YAML version checks`
+- [证据] `93a1a7a [BUGFIX] release: publish prereleases with dist-tags`
+- [证据] `0d7e8c0 [CONFIG] release: prepare v0.5.2-beta.1`
+
+## 残留事项
+
+- [证据] workflow 仍有非阻断告警：
+  - `actions/create-release@v1` 使用 Node 20，将来需要升级
+  - `set-output` 已废弃，后续应替换为环境文件方式
+  - 存在一个 `git exit code 128` 注解噪音，但不影响发布成功
+- [观点] 这些问题不影响当前发布结果，但建议作为下一轮 release-infra 清理项集中处理。
+
+## 下次发布的最小检查清单
+
+- [证据] 若版本是 prerelease，确认版本号包含 preid，例如 `0.5.2-beta.2`
+- [证据] 先运行 `npm run docs:check:pre-release`
+- [证据] 再运行 `npm test`、`npm run build`、`npm run validate-pack`
+- [证据] 推送匹配版本的 tag，观察 `Publish to NPM` workflow
+- [证据] 发布后检查：
+  - `npm view @mycodemap/mycodemap version dist-tags --json`
+  - `gh release view v<version>`
+

package/docs/rules/README.md

@@ -1,6 +1,8 @@
 # `docs/rules/` 速查索引
 
 > 只保留会直接影响 agent / 人类开发行为的规则。每份文档都应短、可执行、可 grep。
+>
+> 入口角色约束：`AGENTS.md` 定权，根 `CLAUDE.md` 只负责把你路由到这里或其他 live docs；规则正文仍以本目录各文件为准。
 
 ## 先读哪份文档
 
@@ -11,7 +13,8 @@
 | 改测试、fixture、测试文件布局 | `testing.md` | `npm test` |
 | 改 hooks、CI、验证顺序、repo-local guardrail | `validation.md` | `npm run docs:check` / `python3 scripts/validate-rules.py code --report-only` |
 | 改 agent 执行协议、CLI/CI 工程护栏 | `engineering-with-codex-openai.md` | `node dist/cli/index.js ci check-docs-sync` |
-| 改发布/打包流程 | `deployment.md` | `npm run build` / `npm run validate-pack` |
+| 改 `/release workflow`、milestone 绑定、确认门 | `release.md` | `npm run docs:check:pre-release` |
+| 改发布/打包 mechanics | `deployment.md` | `npm run build` / `npm run validate-pack` |
 | 改发布前 checklist / 版本同步 | `pre-release-checklist.md` | `npm run docs:check:pre-release` |
 
 ## 使用规则

package/docs/rules/deployment.md

@@ -17,6 +17,13 @@
 - 库入口：`dist/index.js`
 - `prepublishOnly` 已要求构建并测试
 
+## Milestone-bound releases
+
+- 每个 milestone 对应一个 npm release，不再把 milestone closeout 与 npm 发布视为两套彼此无关的流程。
+- 版本映射规则是 `vX.Y → X.Y.0`；例如 `v1.9 → 1.9.0`。
+- 统一入口是 `/release`，它负责串起 readiness 检查、milestone closeout、版本映射、确认门和现有发布工具链。
+- 不得绕过 GSD milestone closeout 直接执行发布；`scripts/release.sh` 与 `.github/workflows/publish.yml` 只在 `/release` 或等价人工确认流程之后触发。
+
 ## 禁止事项
 
 - 不得通过跳过测试或伪造产物完成发布。