@mycodemap/mycodemap 0.5.1 → 1.9.0

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

@@ -78,6 +78,7 @@
 - 所有文件版本号必须完全一致
 - 必须符合语义化版本规范 (`x.x.x`)
 - 预发布版本可包含后缀 (`0.2.0-beta.1`)
+- 预发布版本发布到 npm 时必须显式传 dist-tag（例如 `0.2.0-beta.1 -> --tag beta`）
 
 **版本同步清单**:
 
@@ -158,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 命名规范**:
@@ -202,8 +210,8 @@ git push origin main --tags
      - Workflow Name: `publish.yml`
 
 2. **GitHub Secrets 检查**:
-   - [ ] **不应设置** `NPM_TOKEN` secret
-   - [ ] 如果需要 Token 方式，使用 `NPM_TOKEN` 并确保是 **Automation** 类型
+   - [ ] 默认可不设置 `NPM_TOKEN`，优先走 OIDC Trusted Publishing
+   - [ ] 如果需要 token fallback，使用 `NPM_TOKEN` 并确保是 **Automation** 类型
 
 3. **Workflow 权限配置**:
    ```yaml
@@ -214,9 +222,13 @@ git push origin main --tags
 
 4. **发布命令**:
    ```yaml
-   # 正确：使用 OIDC
+   # 正确：stable 版本发布到 latest
+   - name: Publish to NPM
+     run: npm publish --access public --tag latest
+
+   # 正确：prerelease 版本显式发布到 preid 对应 tag
    - name: Publish to NPM
-     run: npm publish --access public --provenance
+     run: npm publish --access public --tag beta
    
    # 错误：设置 NODE_AUTH_TOKEN 会干扰 OIDC
    # env:
@@ -285,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. 确保工作区干净
@@ -312,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 自动完成发布
 ```
 
 ---

package/docs/rules/release.md

@@ -0,0 +1,303 @@
+# 版本发布工作流程
+
+> 本文档定义 `/release` 命令的完整操作流程。
+> 它是 milestone closeout 与 npm 发布的统一编排入口，也是 `/release` 的单一权威文档。
+>
+> **适用对象**：执行发布的 AI 助手或人类操作者。
+> **前置阅读**：`docs/rules/pre-release-checklist.md`、`docs/rules/deployment.md`。
+
+> **Runtime adapters**：`.claude/skills/release/SKILL.md` 与 `.agents/skills/release/SKILL.md` 只允许作为运行时薄适配器存在。它们必须回指本文档，不能替代这里的单一权威流程。
+
+---
+
+## 核心原则
+
+1. **1:1 绑定**：每个 milestone 对应一个 npm release。
+2. **版本统一**：milestone 版本即 npm 版本（`vX.Y → X.Y.0`，例如 `v1.9 → 1.9.0`）。
+3. **二次确认**：在触发任何不可逆操作（版本 bump、tag 创建、远程推送）之前，必须等待用户显式确认。
+4. **Thin orchestrator**：`/release` 只做编排和确认门，实际工作委托给现有工具链（`$gsd-complete-milestone`、`scripts/release.sh`、`.github/workflows/publish.yml`）。
+
+---
+
+## 角色分级
+
+发布操作在 `AGENTS.md` 中定义为 **L3-禁止** 等级：
+
+- AI **不得**自主执行版本号变更、tag 创建、远程推送。
+- AI **可以**运行验证检查、准备方案、展示摘要、等待用户确认后执行。
+- 用户确认是**必需**的，不是可选的。
+- 本流程必须严格经过两道确认门；任何缺少显式确认的发布都视为无效。
+
+---
+
+## 触发条件
+
+运行 `/release v{X.Y}` 命令必须同时满足：
+
+1. 当前存在 **已完成且可 closeout** 的 milestone；如果 milestone 已归档，`/release` 只可在做版本发布补步骤时继续，不能跳过 readiness 检查。
+2. 用户显式提供了目标版本号（如 `/release v1.9`）。
+3. 当前工作区干净（无未提交修改）。
+4. 当前分支为 `main`（或仓库定义的发布分支）。
+5. 本地与远程都不存在冲突的目标 tag（例如 `v1.9.0`）。
+
+如果以上任一不满足，`/release` 应拒绝执行并说明原因。
+
+---
+
+## 工作流程
+
+```
+/release v{X.Y}
+  ↓
+① 验证触发条件
+② 检查 milestone readiness
+③ 运行 `$gsd-complete-milestone v{X.Y}`
+④ 【Confirmation Gate #1】展示归档摘要
+⑤ 计算并展示版本映射
+⑥ 【Confirmation Gate #2】展示发布摘要
+⑦ 委托机械发布 helper
+⑧ 验证 GitHub Actions 触发
+⑨ 完成报告
+```
+
+### 步骤详解
+
+#### ① 验证触发条件
+
+检查以下项目，任一失败则终止并报告：
+
+- [ ] 用户提供了明确的目标版本号（`v{X.Y}` 格式）
+- [ ] `git status --porcelain` 为空（工作区干净）
+- [ ] 当前分支为 `main`（或项目配置的 base branch）
+- [ ] milestone 已完成并具备 closeout/readiness 证据
+- [ ] 本地不存在目标 tag，远程也不存在同名发布 tag
+- [ ] `package.json` 当前版本已读出，可计算目标版本映射
+
+#### ② 检查 Milestone Readiness
+
+运行以下检查，收集状态信息用于后续确认门：
+
+```bash
+# 运行 readiness gate（hard / warn-only / fallback 三层语义）
+mycodemap readiness-gate
+
+# 或结构化输出
+mycodemap readiness-gate --json --structured
+
+# 检查开放工件
+node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" audit-open 2>/dev/null
+
+# 验证 roadmap 状态
+# (roadmap analyze 输出)
+```
+
+要求：
+- 所有 phase 有 `SUMMARY.md`
+- 所有 requirement 已勾选（或已记录为 deferred）
+- 无未解决的 blocker
+- readiness gate 无 `fallback` 状态（若存在 fallback，需人工判断后方可继续）
+
+如果有开放项目，展示给用户并要求选择：
+- [R] 解决 — 停止，修复后重新运行 `/release`
+- [A] 确认延期 — 记录到 `STATE.md` Deferred Items，继续
+- [C] 取消 — 退出
+
+#### ③ 运行 GSD Milestone Closeout
+
+委托给现有 GSD 工具链：
+
+```text
+$gsd-complete-milestone v{X.Y}
+```
+
+此步骤自动完成：
+- 归档 ROADMAP.md → `milestones/v{X.Y}-ROADMAP.md`
+- 归档 REQUIREMENTS.md → `milestones/v{X.Y}-REQUIREMENTS.md`
+- 更新 MILESTONES.md、PROJECT.md、STATE.md
+- 更新 RETROSPECTIVE.md
+- 创建安全 commit
+
+等待此步骤完全完成后，继续下一步。
+
+#### ④ 【Confirmation Gate #1】Milestone 归档摘要
+
+展示：
+
+```
+Milestone v{X.Y} [{Name}] 归档完成
+
+已归档：
+- milestones/v{X.Y}-ROADMAP.md
+- milestones/v{X.Y}-REQUIREMENTS.md
+- MILESTONES.md 已更新
+- PROJECT.md 已演进
+- STATE.md 已更新
+
+Phase 统计：{N} phases, {M} plans, {P} tasks
+关键交付：
+- {accomplishment 1}
+- {accomplishment 2}
+- ...
+```
+
+用户确认后继续（默认 N）。如果用户不确认，则流程停止，不进入任何发布准备步骤。
+
+#### ⑤ 计算并展示版本映射
+
+从 `package.json` 读取当前版本，计算新版本：
+
+```
+版本映射：
+- Milestone:    v{X.Y}
+- NPM 当前:     {current_version}
+- NPM 目标:     {X.Y}.0
+- 变更类型:     {major/minor/patch}
+
+⚠️ 警告：当前版本 {current_version} → {X.Y}.0 是 {major} 版本跳跃。
+   请确认这是预期行为。
+```
+
+当前仓库的已知映射示例：
+
+```
+v1.9 → 1.9.0
+0.5.2-beta.1 → 1.9.0
+```
+
+如果版本跳跃跨越 major 边界（0.x → 1.x 或 1.x → 2.x），额外高亮警告并要求操作者重新确认。
+
+#### ⑥ 【Confirmation Gate #2】发布摘要
+
+在触发任何不可逆操作之前，完整展示：
+
+```
+═══════════════════════════════════════════════════════
+  即将执行以下操作（不可撤销）：
+═══════════════════════════════════════════════════════
+
+1. 更新 package.json version: {current} → {X.Y}.0
+2. 创建 git commit: "[RELEASE] bump version to v{X.Y}.0"
+3. 创建 git tag: v{X.Y}.0
+4. 推送到远程 origin
+5. 触发 GitHub Actions: publish.yml
+   → 构建、测试、NPM 发布、GitHub Release
+
+确认后，以上操作将自动执行。
+
+确认发布 v{X.Y}.0? (y/N):
+```
+
+用户必须输入 `y` 或 `Y` 才继续。任何其他输入都终止流程。未经过此 gate，不得执行 `npm version`、git commit、git tag、`git push` 或任何会触发 `.github/workflows/publish.yml` 的动作。
+
+#### ⑦ 委托机械发布 helper
+
+用户确认后，`/release` 默认**委托**给现有机械 helper，而不是在 skill 里重写版本 bump / tag / push 逻辑：
+
+```bash
+rtk ./scripts/release.sh {X.Y}.0
+```
+
+委托边界如下：
+
+- `/release` 负责前置检查、milestone closeout、版本映射、major 跳跃高亮与 **Confirmation Gate #2**
+- `scripts/release.sh` 负责执行既有的 `npm run check:all`、版本写入、git commit、git tag、`git push`
+- `.github/workflows/publish.yml` 负责 tag push 后的构建、测试、NPM 发布与 GitHub Release
+
+> 说明：`scripts/release.sh` 当前自带交互确认；它只能作为 `/release` 已通过 **Confirmation Gate #2** 之后的机械 helper，不能替代 `/release` 的安全门。
+>
+> 说明：Phase 31 / Phase 32 / Phase 33 只定义和验证该流程，不会在当前 milestone 内真的执行这些命令。
+
+如需理解 helper 将触发的底层动作，可参考 `scripts/release.sh` 当前事实：它会写入 `package.json` / `package-lock.json` 版本、创建 `[RELEASE]` commit、创建 `v{X.Y}.0` tag，并推送分支与 tag 到远程。
+
+#### ⑧ 验证 GitHub Actions 触发
+
+推送后，验证 Actions 已触发：
+
+```bash
+# 给出 Actions 页面链接
+echo "GitHub Actions 发布状态:"
+echo "https://github.com/{owner}/{repo}/actions/workflows/publish.yml"
+```
+
+如需做**只读 follow-up observability**，统一使用独立命令：
+
+```bash
+mycodemap publish-status --tag v{X.Y}.0 --sha {headSha}
+mycodemap publish-status --tag v{X.Y}.0 --sha {headSha} --json --structured
+```
+
+约束：
+
+- `publish-status` 只读取 `.github/workflows/publish.yml` 的 snapshot truth
+- 它必须依赖 `--tag + --sha` 做精确匹配；无法精确确认时返回 `unavailable` / `ambiguous`
+- 它**不是**第二条发布路径；`/release` 仍是单一权威，`publish-status` 不得 rerun workflow、不得 dispatch、不得 publish、不得 push
+- 默认只做一次 snapshot；是否继续跟进由人类或上层 agent 自主决定
+
+可选：使用 `publish-status` 做非阻塞状态复核，但不要把它当成发布 authority 的一部分。
+
+#### ⑨ 完成报告
+
+```
+✅ Release v{X.Y}.0 已触发
+
+Milestone:     v{X.Y} — 已归档
+NPM 版本:      {X.Y}.0 — 已推送 tag
+GitHub Actions: 运行中
+
+查看状态:
+- Actions: https://github.com/{owner}/{repo}/actions
+- NPM:     https://www.npmjs.com/package/@mycodemap/mycodemap
+- Release: https://github.com/{owner}/{repo}/releases
+- Follow-up: `mycodemap publish-status --tag v{X.Y}.0 --sha {headSha}`
+```
+
+---
+
+## 错误处理与回滚
+
+### 中途失败
+
+如果在步骤 ③（GSD closeout）之前失败：无持久化副作用，直接终止。
+
+如果在步骤 ③ 完成后、步骤 ⑦ 之前失败：milestone 已归档，但 npm 未发布。可以修复问题后重新运行 `/release`（GSD closeout 部分会检测到已归档并跳过）。
+
+如果在步骤 ⑦ 中失败（如 push 被拒绝）：
+- 若 commit 已创建但 push 失败：修复远程冲突后手动推送。
+- 若 tag 已创建但 push 失败：手动 `git push origin v{X.Y}.0`。
+- 若 package.json 已修改但 commit 未创建：`git checkout package.json package-lock.json` 回滚。
+
+### 版本冲突
+
+如果本地或远程已存在 `v{X.Y}.0` tag：
+- 拒绝执行，报告冲突。
+- 建议用户检查是否重复运行 `/release`。
+
+如果 package.json 中版本已经是 `{X.Y}.0`：
+- 跳过版本 bump，只创建 tag 和推送。
+
+---
+
+## 禁止事项
+
+- **不得**在二次确认门之前执行任何 git 写操作（commit、tag、push）。
+- **不得**跳过 GSD milestone closeout 直接执行 `scripts/release.sh`。
+- **不得**在存在未解决 blocker 时继续发布（除非用户显式选择 [A] 确认延期）。
+- **不得**将 `NPM_TOKEN` 硬编码到任何脚本或文档中。
+- **不得**绕过 `docs:check:pre-release` 检查。
+- **不得**把 `/release` 文档写成第二套 closeout 或 publish 实现；它必须是 thin orchestrator。
+
+---
+
+## 文档同步触发条件
+
+以下变更会触发本文档需要更新：
+
+- GSD closeout 工作流变更（步骤或顺序变化）
+- `scripts/release.sh` 行为变更（参数、交互方式变化）
+- `.github/workflows/publish.yml` 触发条件变化
+- 版本映射规则变化
+- 确认门内容或格式变化
+
+---
+
+*版本: 1.0.0 | 最后更新: 2026-04-22*

package/docs/rules/testing.md

@@ -17,6 +17,7 @@
 | 类型 | 路径 |
 |------|------|
 | 常规测试 | `src/**/*.test.ts` |
+| Workflow E2E | `tests/e2e/**/*.test.ts` |
 | 集成测试 | `tests/` 目录（如存在单独集成测试编排） |
 | 基准测试 | `refer/benchmark-quality.test.ts` |
 
@@ -37,6 +38,21 @@ export default defineConfig({
 });
 ```
 
+```typescript
+// vitest.e2e.config.ts
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['tests/e2e/**/*.test.ts'],
+    exclude: ['node_modules', 'dist', 'refer/**/*.test.ts'],
+    testTimeout: 10000,
+    hookTimeout: 10000,
+    pool: 'threads'
+  }
+});
+```
+
 ## 测试要求
 
 - 所有新功能必须附带测试
@@ -59,6 +75,9 @@ export default defineConfig({
 npm test
 npx vitest run
 
+# 运行 workflow E2E 护栏
+npm run test:e2e
+
 # 运行特定测试文件
 npx vitest run src/orchestrator/__tests__/confidence.test.ts
 

package/docs/rules/validation.md

@@ -10,7 +10,14 @@
 | 改 repo-local 规则控制脚本或 hook 路由 | `python3 scripts/validate-rules.py code --report-only` | 先看 contract，不先硬阻断 |
 | 改 CLI 文档入口或统一 guardrail | `node dist/cli/index.js ci check-docs-sync` | 同时验证 docs guardrail 与 analyze generated block |
 | 改实现代码 | `npm run typecheck` → `npm run lint` → `npm test` | 从最小相关验证扩到基础回归 |
-| 改发布/打包边界 | `npm run build` → `npm run validate-pack` | 确认 shipped artifact 仍成立 |
+| 改发布/打包边界 | `npm run docs:check:pre-release` → `npm run build` → `npm run validate-pack` | 先锁版本/发布契约，再确认 shipped artifact 仍成立 |
+
+## 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。
 
 ## Repo-local rule validator
 
@@ -39,18 +46,19 @@
 | 1 | `npm run docs:check` | 文档护栏 |
 | 2 | `npm run typecheck` | 类型检查 |
 | 3 | `npm run lint` | lint |
-| 4 | `npm test` | 单元测试 |
-| 5 | `npm run build` | 构建验证 |
-| 6 | `node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10` | 设计 contract 校准；`changed files <= 10` 才可能进入 hard gate |
-| 7 | `node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github` | PR 注解与 contract gate |
-| 8 | `node dist/cli/index.js ci check-docs-sync` | 统一 docs/AI guardrail |
-| 9 | `node dist/cli/index.js ci assess-risk --threshold=0.7` | 风险评估 |
+| 4 | `npm test` | 默认 `src/**/*.test.ts` 回归 |
+| 5 | `npm run test:e2e` | `tests/e2e/**/*.test.ts` workflow E2E 护栏 |
+| 6 | `npm run build` | 构建验证 |
+| 7 | `node scripts/calibrate-contract-gate.mjs --max-changed-files 10 --max-false-positive-rate 0.10` | 设计 contract 校准；`changed files <= 10` 才可能进入 hard gate |
+| 8 | `node dist/cli/index.js check --contract mycodemap.design.md --against src --base origin/main --annotation-format github` | PR 注解与 contract gate |
+| 9 | `node dist/cli/index.js ci check-docs-sync` | 统一 docs/AI guardrail |
+| 10 | `node dist/cli/index.js ci assess-risk --threshold=0.7` | 风险评估 |
 
 > PR 超窗、`diff-scope-fallback` 或 `false-positive rate >10%` 时，workflow 必须明确标为 `warn-only / fallback`。
 
 ## 需要特别补跑的场景
 
-- 若改动涉及 `mycodemap.config.json.storage` 或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
+- 若改动涉及 `.mycodemap/config.json` 的 `storage` 段或图数据库适配器，至少补跑对应 storage adapter 定点测试，并确认 `README.md`、`AI_GUIDE.md`、`docs/ai-guide/COMMANDS.md`、`docs/SETUP_GUIDE.md`、`mycodemap.config.schema.json` 与 guardrail 脚本同步。
 - 若改动涉及 `check` / `ci assess-risk` / `history` / `analyze --include-git-history` 的统一 risk truth，至少补跑 `node dist/cli/index.js history --symbol createCheckCommand`、`node scripts/report-high-risk-files.mjs --top 3`、`npm run build`。
 - 若改动涉及产品定位、输出契约、共享文件发现规则或 `Server Layer` / `mycodemap server` 边界，确认 README、AI 文档、架构文档和 guardrail 脚本使用同一套措辞。
 
@@ -73,6 +81,7 @@
 | 失败模式 | 先看哪里 | 恢复方式 |
 |---|---|---|
 | `schema / README / AI 文档没同步` | `npm run docs:check` | 先修文档真相，再重跑 |
+| prerelease 发布卡在 npm publish | `.github/workflows/publish.yml` / `package.json version` | 确认 prerelease 版本显式传了 `--tag <preid>`；例如 `0.5.2-beta.1` 必须走 `--tag beta` |
 | 文档继续把历史设计写成当前现实 | `npm run docs:check` | 把 shipped baseline 与 future intent 分开 |
 | 旧的 `neo4j` / `kuzudb` 配置已经不受支持，但文档还把它写成正式 backend | `README.md` / `AI_GUIDE.md` / schema | 改回 `filesystem` / `sqlite` / `memory` / `auto` 真实 contract |
 | `storage.type="sqlite"` 运行时不满足要求 | Node.js `>=20`、`better-sqlite3`、`STORAGE_BACKEND_MIGRATED`、`SQLITE_NOT_AVAILABLE` | 修运行时或改配置，不要静默 fallback |
@@ -95,6 +104,7 @@ node scripts/report-high-risk-files.mjs --top 3
 npm run typecheck
 npm run lint
 npm test
+npm run test:e2e
 npm run build
 npm run validate-pack
 ```

package/mycodemap.config.schema.json

@@ -53,7 +53,7 @@
         },
         "outputPath": {
           "type": "string",
-          "default": ".codemap/storage",
+          "default": ".mycodemap/storage",
           "description": "Filesystem storage directory"
         },
         "databasePath": {