@mycodemap/mycodemap 0.5.2-beta.1 → 1.9.0

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` 或等价人工确认流程之后触发。
+
 ## 禁止事项
 
 - 不得通过跳过测试或伪造产物完成发布。

package/docs/rules/engineering-with-codex-openai.md

@@ -25,7 +25,7 @@
 
 1. **T0-地图层**（始终提供）：架构说明、类型定义、关键约束文件
    - `AGENTS.md`（仓库级强约束）
-   - `CLAUDE.md`（执行手册）
+   - `CLAUDE.md`（入口路由）
    - `src/types/index.ts`（核心类型）
 
 2. **T1-任务相关层**（动态检索）：通过 CodeMap CLI 或文件路径匹配提供
@@ -64,13 +64,20 @@
   - 若涉及机器输出，`--json` 与 `--structured --json` 仍保持纯 JSON 契约。
 - 修改 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/OUTPUT.md`、`ARCHITECTURE.md` 这类入口文档时，必须明确区分“目标产品基线”和“当前 CLI 现实”，尤其是 `Server Layer` / `mycodemap server` 的命名边界。
 - 修改 `docs/product-specs/*` 现行规格时，必须同步 `docs/product-specs/README.md` 与 `scripts/validate-docs.js` 的高信号断言，避免规格正文和目录索引分叉；`docs/product-specs/DESIGN_CONTRACT_TEMPLATE.md` 也属于这一约束。
-- 若改动会影响 agent 执行手册、README 示例、测试事实或入口路由，先执行 `npm run docs:check`。
+- 若改动会影响入口路由、README 示例、测试事实或 AI / agent 的文档发现路径，先执行 `npm run docs:check`。
 - 若希望通过统一 CLI 护栏入口执行同一检查，使用 `node dist/cli/index.js ci check-docs-sync`；该命令会同时执行 docs guardrail 与 `sync-analyze-docs.js --check`。
 - 若改动涉及 repo-root contract 或 CI gate，确认 `.github/workflows/ci-gateway.yml` 中的 `node dist/cli/index.js check --contract mycodemap.design.md --against src` 仍保持 PR 显式 base / push full scan 语义。
 - `ci check-branch --allow` 支持 `*` 通配；在 CI / PR 环境中，分支识别会回退到 `GITHUB_HEAD_REF` / `GITHUB_REF_NAME`。
 - `generate`、`analyze` 与 `ci check-headers -d` 共享 `.gitignore` 感知文件发现模块；没有 `.gitignore` 时回退到统一默认 `exclude`。
 - 涉及发布边界时，再补 `npm run build` 与 `npm run validate-pack`；不要把本地临时产物当成发布事实。
 
+## 4.1 Validation quick truth
+
+- 文档/入口变更先跑 `npm run docs:check`。
+- 统一 docs/AI guardrail 入口：`node dist/cli/index.js ci check-docs-sync`（产品命令等价于 `mycodemap ci check-docs-sync`）。
+- repo-local rules 预检：`python3 scripts/validate-rules.py code --report-only` 只报告，不阻断。
+- CI / PR 超窗、fallback 或 false-positive 漂移时，`warn-only / fallback` 不是 hard gate success。
+
 ## 5. 当前项目的 CI 护栏
 
 - 本地护栏：
@@ -80,9 +87,9 @@
   - `.githooks/commit-msg` 只校验 `[TAG] scope: message` 格式；单次 commit 文件数量限制只保留在 `.githooks/pre-commit`。
 - 服务端护栏：
   - `.github/workflows/ci-gateway.yml` 包含固定命名的 `Rule validation backstop` step；即使本地使用 `git commit --no-verify` 绕过 hooks，CI 仍会运行 `python3 scripts/validate-rules.py code`，并仅在退出码 `1` 或 `4` 时 fail，`2/3` 只输出 warn-only / notice-only。
-  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run build`，并通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`（含 docs guardrail + analyze generated block）、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
+  - `.github/workflows/ci-gateway.yml` 会执行 `npm run docs:check`、`npm run typecheck`、`npm test`、`npm run test:e2e`、`npm run build`，并通过 `node dist/cli/index.js ci ...` 执行 `check-docs-sync`（含 docs guardrail + analyze generated block）、`check-commits`、`check-commit-size`、`check-headers`、`assess-risk`、`check-output-contract` 与 AI feed 同步检查。
   - `check-working-tree`、`check-branch`、`check-scripts` 作为共享发布前 gate checks，由本地 `ci` 命令提供，`ship` 的 CHECK 阶段直接复用它们。
-  - `.github/workflows/publish.yml` 会在发布前执行 `npm test` 与 `npm run build`。
+  - `.github/workflows/publish.yml` 会在发布前执行 `npm test`、`npm run test:e2e` 与 `npm run build`。
 - 禁止依赖 `git commit --no-verify` 作为解决方案；它只能跳过本地 hooks，不能绕过 CI 中的 `Rule validation backstop`。
 - 仓库协议仍然禁止通过 `--no-verify`、关闭 hook、放宽阈值、删除检查项来"修复"问题。
 
@@ -199,25 +206,57 @@ import type { IStorage } from '../interface/types/storage'; // 正确：只依
 
 | 你的改动 | 必须更新的文档 |
 |---------|--------------|
-| 新增/修改 CLI 命令或参数 | `CLAUDE.md`、`docs/rules/engineering-with-codex-openai.md` |
+| 新增/修改 CLI 命令或参数 | `AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、必要时同步 `CLAUDE.md` 路由 |
 | 新增/修改配置项或 Schema | `README.md`、`docs/SETUP_GUIDE.md`、`docs/AI_ASSISTANT_SETUP.md`、相关配置示例 |
 | 修改类型定义/公共接口 | 接口注释、`docs/rules/` 中相关文档 |
 | 修改 CI/CD 流程 | `docs/rules/validation.md`、`.github/workflows/` |
 | 修改 Git Hooks | `docs/rules/validation.md` |
 | 修改测试规则/覆盖率要求 | `docs/rules/testing.md` |
-| 修改架构分层或依赖规则 | `ARCHITECTURE.md`、`docs/rules/architecture-guardrails.md` |
+| 修改架构分层或依赖规则 | `ARCHITECTURE.md`、`docs/rules/architecture-guardrails.md`、必要时同步 `CLAUDE.md` / `AI_GUIDE.md` 导航 |
 | 新增代码质量红线 | `docs/rules/code-quality-redlines.md` |
-| 修改提交格式规范 | `AGENTS.md` |
+| 修改输出格式 / 机器契约 | `AI_GUIDE.md`、`docs/ai-guide/OUTPUT.md` |
+| 新增使用模式 / 工作流模式 | `AI_GUIDE.md`、`docs/ai-guide/PATTERNS.md` |
+| 修改提交格式规范或仓库级底线 | `AGENTS.md` |
 | 发现文档与代码不符 | 立即修复对应文档 |
 
 **原则**：若改动会影响其他开发者或 AI 的行为，就必须更新文档。
 
+### 10.3 任务初始化最小模板
+
+当入口路由把你导向本文件时，默认用下面这份最小模板启动任务；不要再把模板写回 `CLAUDE.md` 或 `.claude/CLAUDE.md`。
+
+```markdown
+## 任务分析
+- 目标：一句话说明要交付什么
+- 类型：新增 / 修复 / 重构 / 文档 / 其他
+- 等级：L0 / L1 / L2 / L3
+- 验收：最小可验证结果
+
+## 执行计划
+1. [Plan] 明确边界与影响范围 → verify: 最小相关检查
+2. [Build] 落地改动 → verify: 定点验证
+3. [Verify] 扩大验证 → verify: docs / typecheck / lint / test / build
+4. [Report] 说明变更、验证、风险、文档同步
+```
+
+### 10.4 AI 友好文档补充
+
+更新或创建面向 AI / agent 的文档时，至少满足以下约束：
+
+- 结构清晰：使用稳定标题层级，避免把多个主题混在一个巨段里。
+- 决策可路由：复杂流程优先提供表格、决策树或“场景 → 文档 / 命令”映射。
+- 示例可复制：命令块和 JSON / TypeScript 示例必须能直接复用，不写伪代码占位。
+- 契约可解析：机器输出变更时同步更新 `docs/ai-guide/OUTPUT.md`，必要时补 TypeScript 接口。
+- 模式可发现：新增典型工作流时同步更新 `docs/ai-guide/PATTERNS.md` 或 `PROMPTS.md`。
+- 错误可恢复：常见失败模式必须给出排查入口或恢复方式。
+- 链接可导航：入口文档负责指路，规则正文只在 authoritative docs 维护一次。
+
 ## 11. 参考来源
 
 - OpenAI Engineering: https://openai.com/engineering/codex/
 - Harness Engineering 方法论：`docs/references/tmp.md`
 - 仓库入口协议：`AGENTS.md`
-- 最小执行手册：`CLAUDE.md`
+- 入口路由：`CLAUDE.md`
 - 架构地图：`ARCHITECTURE.md`
 - 当前验证规则：`docs/rules/validation.md`
 - 当前发布规则：`docs/rules/deployment.md`

package/docs/rules/pre-release-checklist.md

@@ -159,24 +159,31 @@
 - [ ] 远程 tag 是否已推送
 - [ ] 当前分支是否为 main/master
 
-**发布流程**:
+**推荐发布入口**:
 
 ```bash
-# 方式1: 使用发布脚本（推荐）
-./scripts/release.sh patch   # patch/minor/major
-
-# 方式2: 手动发布
-# 1. 更新版本号
-npm version patch  # 自动创建 tag
+# milestone-bound release 的推荐方式只有 `/release vX.Y`
+/release v1.9
+
+# `/release` 会负责:
+# 1. 检查 milestone readiness / 工作区 / 分支 / tag 冲突
+# 2. 运行 milestone closeout 或确认已归档状态
+# 3. 展示 Confirmation Gate #1 与 #2
+# 4. 在最终确认后委托机械 helper
+```
 
-# 2. 推送 tag
-git push origin main --tags
+**手动例外（仅限人工受控且已完成等价 closeout + 双确认门）**:
 
-# 3. GitHub Actions 自动完成:
-#    - 构建项目
-#    - 运行测试
-#    - 发布到 NPM (通过 OIDC)
-#    - 创建 GitHub Release
+```bash
+# 只有在完成与 `/release` 等价的 closeout / Gate #1 / Gate #2 后
+# 才允许调用机械 helper
+rtk ./scripts/release.sh 1.9.0
+
+# tag push 后由 GitHub Actions 自动完成:
+# - 构建项目
+# - 运行测试
+# - 发布到 NPM (通过 OIDC)
+# - 创建 GitHub Release
 ```
 
 **Tag 命名规范**:
@@ -290,25 +297,22 @@ npm run docs:check:pre-release 2>&1 | less
 
 ### 发布前准备
 
-**推荐方式: 使用发布脚本（一键完成）**
+**推荐方式: 使用 `/release vX.Y` 统一编排**
 
 ```bash
-# 使用发布脚本（自动处理版本、tag、推送）
-./scripts/release.sh patch    # patch 版本 (0.2.0 -> 0.2.1)
-./scripts/release.sh minor    # minor 版本 (0.2.0 -> 0.3.0)
-./scripts/release.sh major    # major 版本 (0.2.0 -> 1.0.0)
-./scripts/release.sh 0.3.0    # 指定具体版本
-
-# 脚本会自动:
-# 1. 运行 npm run check:all
-# 2. 更新 package.json 版本
-# 3. 创建 git commit
-# 4. 创建 git tag
-# 5. 推送到远程仓库
-# 6. 触发 GitHub Actions 发布 (OIDC)
+# milestone-bound release 的统一入口
+/release v1.9
+
+# `/release` 会负责:
+# 1. 检查 milestone readiness / 工作区 / 分支 / tag 冲突
+# 2. 运行 milestone closeout 或确认已归档状态
+# 3. 展示 Confirmation Gate #1 与 #2
+# 4. 在最终确认后委托 `rtk ./scripts/release.sh 1.9.0`
 ```
 
-**手动方式（需要更多控制时）**
+`scripts/release.sh` 是 Gate #2 之后的机械 helper，不是绕过 `/release` 的主入口。
+
+**手动方式（仅限人工受控的例外流）**
 
 ```bash
 # 1. 确保工作区干净
@@ -317,17 +321,24 @@ git status
 # 2. 运行发布前检查
 npm run docs:check:pre-release
 
-# 3. 构建和测试
+# 3. 完成 milestone readiness 与双确认门
+#    - Confirmation Gate #1: closeout 摘要确认
+#    - Confirmation Gate #2: 版本 bump / tag / push 前最终确认
+
+# 4. 构建和测试
 npm run check:all
 
-# 4. 更新版本号（会自动创建 tag）
+# 5. 仅在确认后调用机械 helper
+rtk ./scripts/release.sh 1.9.0
+
+# 6. 或者手动更新版本号（会自动创建 tag）
 npm version patch|minor|major
 
-# 5. 推送代码和 tag
+# 7. 推送代码和 tag
 git push origin main
 git push origin --tags
 
-# 6. GitHub Actions 自动完成发布
+# 8. GitHub Actions 自动完成发布
 ```
 
 ---