@mycodemap/mycodemap 0.5.2-beta.1 → 1.9.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.9.0] - 2026-04-29 - Release Governance Unification
+
+### 🏛️ Governance
+
+- **release**: `/release v{X.Y}` 统一发布治理入口，绑定 milestone closeout 与 npm release 1:1
+- **release**: 引入双确认门（Confirmation Gate #1 / #2），发布操作升级为 L3 受控等级
+- **release**: `docs/rules/release.md` 成为单一权威发布流程文档
+- **release**: `.claude/skills/release/SKILL.md` 作为 thin orchestrator，委托 `scripts/release.sh` 与 `.github/workflows/publish.yml`
+
+### 📝 Documentation
+
+- **release**: 同步 `llms.txt`、`AI_GUIDE.md`、`AI_DISCOVERY.md`、`ai-document-index.yaml` 到 `v1.9.0`
+- **changelog**: 新增 v1.9.0 发布条目，记录 release governance unification milestone
+
 ## [0.5.2-beta.1] - 2026-04-19 - Trusted Publishing Verification
 
 ### 🛠️ Infrastructure

package/README.md

@@ -110,7 +110,7 @@ mycodemap design verify mycodemap.design.md --json
 | **[💬 docs/ai-guide/PROMPTS.md](docs/ai-guide/PROMPTS.md)** | 即用型提示词模板 |
 | **[🔧 docs/ai-guide/INTEGRATION.md](docs/ai-guide/INTEGRATION.md)** | 集成指南、错误处理 |
 | **[🛡️ AGENTS.md](AGENTS.md)** | 仓库级强约束、任务分级、代码红线 |
-| **[⚡ CLAUDE.md](CLAUDE.md)** | AI 执行手册、验收清单 |
+| **[⚡ CLAUDE.md](CLAUDE.md)** | AI 入口路由、下一步阅读导航 |
 | **[🤖 docs/AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)** | AI 助手配置指引 |
 | **[🛠️ docs/rules/engineering-with-codex-openai.md](docs/rules/engineering-with-codex-openai.md)** | 面向 agent 的工程约束 |
 
@@ -122,11 +122,12 @@ mycodemap design verify mycodemap.design.md --json
 
 ### `mycodemap init`
 
-初始化项目的 CodeMap 配置文件。
+初始化并收敛项目的 CodeMap workspace / config / hooks / rules 状态。
 
 ```bash
-mycodemap init          # 创建默认配置文件
-mycodemap init -y       # 使用默认配置直接创建
+mycodemap init               # 显示 reconciliation preview（默认不写入）
+mycodemap init --interactive # 显式显示 preview（等同默认行为）
+mycodemap init -y            # 使用默认选择直接写入
 
 # 别名：codemap init 也可以使用
 ```
@@ -134,8 +135,13 @@ mycodemap init -y       # 使用默认配置直接创建
 | 选项 | 说明 |
 |------|------|
 | `-y, --yes` | 使用默认配置 |
+| `--interactive` | 仅显示 reconciliation preview，不写入文件 |
 
-执行后会在项目根目录生成 `mycodemap.config.json` 配置文件。
+默认显示 reconciliation preview；使用 `mycodemap init -y` 或 `mycodemap init --yes` 才会真正写入。
+
+执行后会收敛 `.mycodemap/config.json`，并把 machine-readable receipt 写入 `.mycodemap/status/init-last.json`。
+
+`init` 还会同步 `.mycodemap/hooks/` 与 `.mycodemap/rules/`；但不会自动改写团队自有的 `CLAUDE.md` / `AGENTS.md`，只会在 receipt 中输出可复制片段。
 
 ### `mycodemap generate`
 
@@ -450,9 +456,16 @@ mycodemap ci check-output-contract
 
 > `ci assess-risk` 现在输出 `status/confidence/freshness/source` 与统一 risk level；若 Git history 不可用，会显式打印 `unavailable` / warning，并说明阈值未被应用。
 
+## 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。
+
 ## 配置说明
 
-通过 `mycodemap init` 生成的 `mycodemap.config.json` 配置文件支持以下选项：
+通过 `mycodemap init` 收敛的 canonical 配置文件是 `.mycodemap/config.json`（根目录 `mycodemap.config.json` / `codemap.config.json` 只作为 legacy migration source）。
 
 ```jsonc
 {
@@ -487,7 +500,7 @@ mycodemap ci check-output-contract
   // 图存储后端配置
   "storage": {
     "type": "filesystem",
-    "outputPath": ".codemap/storage"
+    "outputPath": ".mycodemap/storage"
   },
 
   // 插件加载配置
@@ -507,8 +520,8 @@ mycodemap ci check-output-contract
 | `output` | `string` | 输出目录路径 | `".mycodemap"` |
 | `watch` | `boolean` | 监听模式预留配置 | `false` |
 | `storage.type` | `"filesystem" \| "sqlite" \| "memory" \| "auto"` | 图存储后端类型 | `"filesystem"` |
-| `storage.outputPath` | `string` | 文件系统存储目录 | `".codemap/storage"` |
-| `storage.databasePath` | `string` | SQLite 数据目录（相对项目根目录） | `".codemap/governance.sqlite"` |
+| `storage.outputPath` | `string` | 文件系统存储目录 | `".mycodemap/storage"` |
+| `storage.databasePath` | `string` | SQLite 数据目录（相对项目根目录，建议放在 `.mycodemap/` 下） | `".mycodemap/governance.sqlite"` |
 | `storage.autoThresholds` | `object` | `auto` 后端选择阈值 | - |
 | `plugins.builtInPlugins` | `boolean` | 是否启用内置插件 | `true` |
 | `plugins.pluginDir` | `string` | 额外插件目录 | - |
@@ -521,7 +534,7 @@ mycodemap ci check-output-contract
 {
   "storage": {
     "type": "sqlite",
-    "databasePath": ".codemap/governance.sqlite"
+    "databasePath": ".mycodemap/governance.sqlite"
   }
 }
 ```
@@ -701,6 +714,67 @@ cp examples/codex/codemap-agent.md .agents/skills/codemap/SKILL.md
 
 详细配置请参考 [AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)，设计与规则入口请先看 [docs/README.md](docs/README.md)。
 
+### CodeMap Skill 使用指南
+
+CodeMap Skill 是一个预置的 AI 技能文件，让 Claude Code 等支持 Skill 机制的 AI 助手自动获得 CodeMap 的全部分析能力。当用户提到"分析代码结构"、"查找依赖"、"影响范围"、"代码地图"等意图时，AI 会自动加载该技能并调用 CodeMap CLI。
+
+#### 工作原理
+
+```
+用户提问 → AI 识别意图 → 加载 CodeMap Skill → 调用 CLI 命令 → 返回结构化结果
+```
+
+Skill 文件由两部分组成：
+
+| 文件 | 作用 |
+|------|------|
+| `.claude/skills/codemap/SKILL.md` | 主技能文件：触发条件、场景-命令映射、任务示例、错误处理 |
+| `.claude/skills/codemap/references/commands.md` | 完整命令参考：所有命令的选项、参数和用法 |
+
+#### 安装
+
+Skill 文件已内置在本仓库中，无需额外安装。对于其他项目，复制即可：
+
+```bash
+# 复制到目标项目的 .claude/skills/ 目录
+cp -r .claude/skills/codemap /path/to/target-project/.claude/skills/
+```
+
+#### 典型使用场景
+
+在 Claude Code 对话中直接用自然语言触发，无需手动输入命令：
+
+| 用户意图 | AI 自动执行的命令 |
+|----------|-------------------|
+| "这个项目有哪些模块？" | `mycodemap query -m "src/..."` 或查看 `AI_MAP.md` |
+| "IntentRouter 在哪里定义的？" | `mycodemap query -s "IntentRouter"` |
+| "修改这个文件会影响什么？" | `mycodemap impact -f <path> --transitive` |
+| "项目有循环依赖吗？" | `mycodemap cycles` |
+| "这个模块的复杂度如何？" | `mycodemap complexity -f <path> --detail` |
+| "帮我检查提交格式" | `mycodemap ci check-commits` |
+| "验证设计契约" | `mycodemap design validate` |
+
+#### CLI 调用方式
+
+标准用户通过全局安装的 `mycodemap` 调用；CodeMap 本体仓库的开发者使用 `node dist/cli/index.js`：
+
+```bash
+# 用户模式（全局安装后）
+mycodemap query -s "SymbolName"
+mycodemap impact -f src/file.ts
+
+# 开发者模式（CodeMap 本体仓库内，需先 npm run build）
+node dist/cli/index.js query -s "SymbolName"
+```
+
+#### 自定义与扩展
+
+- **修改触发条件**：编辑 `SKILL.md` 头部的 `description` 字段，调整 AI 何时自动加载此技能
+- **添加新命令**：在 `references/commands.md` 中补充新命令文档
+- **添加新场景**：在 `SKILL.md` 的 "任务场景" 部分追加新的使用模式
+
+详细配置请参考 [AI_ASSISTANT_SETUP.md](docs/AI_ASSISTANT_SETUP.md)，设计与规则入口请先看 [docs/README.md](docs/README.md)。
+
 ## 新增 CLI 命令
 
 ### `mycodemap design`

package/dist/cli/commands/init.d.ts

@@ -1,4 +1,9 @@
-export declare function initCommand(_options: {
+import { type InitReceipt } from '../init/reconciler.js';
+export interface InitCommandOptions {
     yes?: boolean;
-}): Promise<void>;
+    interactive?: boolean;
+    cwd?: string;
+}
+export declare function executeInitCommand(options: InitCommandOptions): Promise<InitReceipt>;
+export declare function initCommand(options: InitCommandOptions): Promise<void>;
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAWA,wBAAsB,WAAW,CAAC,QAAQ,EAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAE,iBAmC5D"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAIA,OAAO,EAAmD,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAG1G,MAAM,WAAW,kBAAkB;IACjC,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAUD,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC,CAgB1F;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CAE5E"}

package/dist/cli/commands/init.js

@@ -1,41 +1,29 @@
 // [META] since:2026-03 | owner:cli-team | stable:true
 // [WHY] Initialize CodeMap configuration for new projects
 import chalk from 'chalk';
-import fs from 'fs/promises';
-import path from 'path';
-import { createDefaultCodemapConfigFile } from '../config-loader.js';
-const NEW_CONFIG_NAME = 'mycodemap.config.json';
-const LEGACY_CONFIG_NAME = 'codemap.config.json';
-export async function initCommand(_options) {
-    console.log(chalk.blue('🚀 初始化 CodeMap...'));
-    const newConfigPath = path.join(process.cwd(), NEW_CONFIG_NAME);
-    const legacyConfigPath = path.join(process.cwd(), LEGACY_CONFIG_NAME);
-    // 优先检查新配置
-    try {
-        await fs.access(newConfigPath);
-        console.log(chalk.yellow(`⚠️  配置文件已存在 (${NEW_CONFIG_NAME})`));
-        return;
-    }
-    catch {
-        // 新配置不存在，继续
-    }
-    // 兼容旧配置：如果存在旧配置，迁移到新配置
-    try {
-        await fs.access(legacyConfigPath);
-        console.log(chalk.yellow(`⚠️  发现旧配置文件 ${LEGACY_CONFIG_NAME}，已迁移到 ${NEW_CONFIG_NAME}`));
-        const legacyContent = await fs.readFile(legacyConfigPath, 'utf-8');
-        await fs.writeFile(newConfigPath, legacyContent);
-        console.log(chalk.green(`✅ 迁移完成！配置文件: ${NEW_CONFIG_NAME}`));
-        return;
+import { applyInitPlan, createInitPlan, writeInitReceipt } from '../init/reconciler.js';
+import { renderInitPreview, renderInitReceipt } from '../init/receipt.js';
+function resolveInitMode(options) {
+    if (options.yes) {
+        return 'apply';
     }
-    catch {
-        // 旧配置也不存在，创建新配置
+    return 'preview';
+}
+export async function executeInitCommand(options) {
+    const rootDir = options.cwd ?? process.cwd();
+    const mode = resolveInitMode(options);
+    const plan = createInitPlan(rootDir, mode);
+    console.log(chalk.blue('🚀 初始化 CodeMap...'));
+    if (mode === 'preview') {
+        renderInitPreview(plan.receipt);
+        return plan.receipt;
     }
-    // 创建默认配置
-    const defaultConfig = createDefaultCodemapConfigFile();
-    await fs.writeFile(newConfigPath, JSON.stringify(defaultConfig, null, 2));
-    console.log(chalk.green('✅ 初始化完成！'));
-    console.log(chalk.gray(`配置文件已创建: ${NEW_CONFIG_NAME}`));
-    console.log(chalk.gray('运行 "mycodemap generate" 或 "codemap generate" 生成代码地图'));
+    const receipt = await applyInitPlan(plan);
+    await writeInitReceipt(receipt);
+    renderInitReceipt(receipt);
+    return receipt;
+}
+export async function initCommand(options) {
+    await executeInitCommand(options);
 }
 //# sourceMappingURL=init.js.map

package/dist/cli/commands/init.js.map

@@ -1 +1 @@
-{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,0DAA0D;AAE1D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,8BAA8B,EAAE,MAAM,qBAAqB,CAAC;AAErE,MAAM,eAAe,GAAG,uBAAuB,CAAC;AAChD,MAAM,kBAAkB,GAAG,qBAAqB,CAAC;AAEjD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAA2B;IAC3D,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE7C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,eAAe,CAAC,CAAC;IAChE,MAAM,gBAAgB,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,kBAAkB,CAAC,CAAC;IAEtE,UAAU;IACV,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;QAC/B,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,gBAAgB,eAAe,GAAG,CAAC,CAAC,CAAC;QAC9D,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,YAAY;IACd,CAAC;IAED,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,eAAe,kBAAkB,SAAS,eAAe,EAAE,CAAC,CAAC,CAAC;QACvF,MAAM,aAAa,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC,CAAC;QACnE,MAAM,EAAE,CAAC,SAAS,CAAC,aAAa,EAAE,aAAa,CAAC,CAAC;QACjD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,gBAAgB,eAAe,EAAE,CAAC,CAAC,CAAC;QAC5D,OAAO;IACT,CAAC;IAAC,MAAM,CAAC;QACP,gBAAgB;IAClB,CAAC;IAED,SAAS;IACT,MAAM,aAAa,GAAG,8BAA8B,EAAE,CAAC;IAEvD,MAAM,EAAE,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,CAAC,SAAS,CAAC,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAE1E,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC;IACrC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,YAAY,eAAe,EAAE,CAAC,CAAC,CAAC;IACvD,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,qDAAqD,CAAC,CAAC,CAAC;AACjF,CAAC"}
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,0DAA0D;AAE1D,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,cAAc,EAAE,gBAAgB,EAAoB,MAAM,uBAAuB,CAAC;AAC1G,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAQ1E,SAAS,eAAe,CAAC,OAA2B;IAClD,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,OAA2B;IAClE,MAAM,OAAO,GAAG,OAAO,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;IAC7C,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACtC,MAAM,IAAI,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAE3C,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAE7C,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACvB,iBAAiB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,CAAC;IAC1C,MAAM,gBAAgB,CAAC,OAAO,CAAC,CAAC;IAChC,iBAAiB,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAA2B;IAC3D,MAAM,kBAAkB,CAAC,OAAO,CAAC,CAAC;AACpC,CAAC"}

package/dist/cli/commands/publish-status.d.ts

@@ -0,0 +1,31 @@
+/**
+ * [META] since:2026-04-23 | owner:cli-team | stable:false
+ * [WHY] Expose read-only publish workflow snapshot truth as a standalone follow-up command for humans and agents
+ */
+import { Command } from 'commander';
+import { type MonitorStatus } from './ship/monitor.js';
+export interface PublishStatusCommandOptions {
+    tag: string;
+    sha: string;
+    workflowFile?: string;
+    json?: boolean;
+    structured?: boolean;
+}
+export interface PublishStatusCommandResult {
+    success: boolean;
+    status: Exclude<MonitorStatus, 'timeout'>;
+    workflowUrl?: string;
+    releaseUrl?: string;
+    runId?: number;
+    failedJobs: string[];
+    reason?: string;
+    details?: string;
+    matchedRunCount?: number;
+    content?: string;
+}
+export declare function renderPublishStatusResult(result: PublishStatusCommandResult): string;
+export declare function executePublishStatusCommand(options: PublishStatusCommandOptions): Promise<PublishStatusCommandResult>;
+export declare function handlePublishStatusCommand(options: PublishStatusCommandOptions): Promise<void>;
+export declare function createPublishStatusCommand(): Command;
+export declare const publishStatusCommand: Command;
+//# sourceMappingURL=publish-status.d.ts.map

package/dist/cli/commands/publish-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-status.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/publish-status.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,WAAW,2BAA2B;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AA0CD,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,0BAA0B,GAAG,MAAM,CAkCpF;AAED,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,0BAA0B,CAAC,CAQrC;AAED,wBAAsB,0BAA0B,CAC9C,OAAO,EAAE,2BAA2B,GACnC,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CASpD;AAED,eAAO,MAAM,oBAAoB,SAA+B,CAAC"}

package/dist/cli/commands/publish-status.js

@@ -0,0 +1,101 @@
+/**
+ * [META] since:2026-04-23 | owner:cli-team | stable:false
+ * [WHY] Expose read-only publish workflow snapshot truth as a standalone follow-up command for humans and agents
+ */
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { snapshotPublishStatus, } from './ship/monitor.js';
+function toCommandResult(result, structured) {
+    const base = {
+        success: result.success,
+        status: result.status === 'timeout' ? 'unavailable' : result.status,
+        workflowUrl: result.workflowUrl,
+        releaseUrl: result.releaseUrl,
+        runId: result.runId,
+        failedJobs: result.failedJobs ?? [],
+        reason: result.reason,
+        details: result.details ?? result.error,
+        matchedRunCount: result.matchedRunCount,
+    };
+    if (structured) {
+        return base;
+    }
+    return {
+        ...base,
+        content: renderPublishStatusResult(base),
+    };
+}
+function formatStatusLabel(status) {
+    switch (status) {
+        case 'success':
+            return chalk.green('success');
+        case 'failure':
+            return chalk.red('failure');
+        case 'pending':
+            return chalk.yellow('pending');
+        case 'ambiguous':
+            return chalk.yellow('ambiguous');
+        case 'unavailable':
+            return chalk.yellow('unavailable');
+        default:
+            return chalk.yellow(status);
+    }
+}
+export function renderPublishStatusResult(result) {
+    const lines = [
+        `Publish 状态: ${formatStatusLabel(result.status)}`,
+    ];
+    if (result.runId) {
+        lines.push(`Run ID: ${result.runId}`);
+    }
+    if (result.reason) {
+        lines.push(`Reason: ${result.reason}`);
+    }
+    if (result.details) {
+        lines.push(`Details: ${result.details}`);
+    }
+    if (result.failedJobs.length > 0) {
+        lines.push(`Failed Jobs: ${result.failedJobs.join(', ')}`);
+    }
+    if (result.matchedRunCount && result.matchedRunCount > 1) {
+        lines.push(`Matched Runs: ${result.matchedRunCount}`);
+    }
+    if (result.workflowUrl) {
+        lines.push(`Workflow: ${result.workflowUrl}`);
+    }
+    if (result.releaseUrl) {
+        lines.push(`Release: ${result.releaseUrl}`);
+    }
+    return lines.join('\n');
+}
+export async function executePublishStatusCommand(options) {
+    const snapshot = await snapshotPublishStatus({
+        tagName: options.tag,
+        headSha: options.sha,
+        workflowFile: options.workflowFile,
+    });
+    return toCommandResult(snapshot, options.structured === true);
+}
+export async function handlePublishStatusCommand(options) {
+    if (options.structured && !options.json) {
+        throw new Error('--structured 需要配合 --json 使用');
+    }
+    const result = await executePublishStatusCommand(options);
+    if (!options.json) {
+        console.log(renderPublishStatusResult(result));
+        return;
+    }
+    console.log(JSON.stringify(result, null, 2));
+}
+export function createPublishStatusCommand() {
+    return new Command('publish-status')
+        .description('查询 publish workflow 的只读 snapshot 状态（默认人类可读输出）')
+        .requiredOption('--tag <tag>', '发布 tag（精确匹配）')
+        .requiredOption('--sha <sha>', '发布 commit SHA（精确匹配）')
+        .option('--workflow-file <file>', 'GitHub Actions workflow 文件名', 'publish.yml')
+        .option('--json', 'JSON 格式输出')
+        .option('--structured', '输出完全结构化的 JSON（不包含自然语言字符串，需要配合 --json 使用）')
+        .action(handlePublishStatusCommand);
+}
+export const publishStatusCommand = createPublishStatusCommand();
+//# sourceMappingURL=publish-status.js.map

package/dist/cli/commands/publish-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-status.js","sourceRoot":"","sources":["../../../src/cli/commands/publish-status.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/readiness-gate.d.ts

@@ -0,0 +1,25 @@
+/**
+ * [META] since:2026-04-29 | owner:cli-team | stable:false
+ * [WHY]  standalone readiness gate command that runs all release quality checks with three-layer gate semantics
+ */
+import { Command } from 'commander';
+import { type CheckOutput } from './ship/checker.js';
+export interface ReadinessGateOptions {
+    dryRun?: boolean;
+    verbose?: boolean;
+    json?: boolean;
+    structured?: boolean;
+}
+export interface ReadinessGateResult {
+    success: boolean;
+    blocked: boolean;
+    blockReason?: string;
+    checkOutput: CheckOutput;
+    version?: string;
+    versionType?: string;
+}
+export declare function runReadinessGate(options?: ReadinessGateOptions): Promise<ReadinessGateResult>;
+export declare function handleReadinessGateCommand(options: ReadinessGateOptions): Promise<void>;
+export declare function createReadinessGateCommand(): Command;
+export declare const readinessGateCommand: Command;
+//# sourceMappingURL=readiness-gate.d.ts.map

package/dist/cli/commands/readiness-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readiness-gate.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/readiness-gate.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAA2D,KAAK,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE9G,MAAM,WAAW,oBAAoB;IACnC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAuFD,wBAAsB,gBAAgB,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6EvG;AAED,wBAAsB,0BAA0B,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsB7F;AAED,wBAAgB,0BAA0B,IAAI,OAAO,CAQpD;AAED,eAAO,MAAM,oBAAoB,SAA+B,CAAC"}

package/dist/cli/commands/readiness-gate.js

@@ -0,0 +1,197 @@
+/**
+ * [META] since:2026-04-29 | owner:cli-team | stable:false
+ * [WHY]  standalone readiness gate command that runs all release quality checks with three-layer gate semantics
+ */
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { analyzeCommits } from './ship/analyzer.js';
+import { calculateVersion } from './ship/versioner.js';
+import { runQualityChecks, shouldBlockRelease } from './ship/checker.js';
+function renderGateResult(result) {
+    const lines = [];
+    const { checkOutput, version, versionType } = result;
+    lines.push(chalk.bold('Readiness Gate 结果'));
+    lines.push('');
+    if (version) {
+        lines.push(`目标版本: v${version} (${versionType})`);
+        lines.push('');
+    }
+    // Hard gates
+    lines.push(chalk.bold('Hard Gates:'));
+    for (const [name, item] of checkOutput.results) {
+        if (item.gateMode !== 'hard')
+            continue;
+        const icon = item.result.status === 'passed' ? chalk.green('✓') : item.result.status === 'failed' ? chalk.red('✗') : chalk.yellow('⏸');
+        const label = name.replace(/([A-Z])/g, ' $1').toLowerCase();
+        lines.push(`  ${icon} ${label}`);
+        if (item.result.message) {
+            lines.push(`     ${chalk.gray(item.result.message)}`);
+        }
+    }
+    lines.push('');
+    // Warn-only gates
+    lines.push(chalk.bold('Warn-only Gates:'));
+    for (const [name, item] of checkOutput.results) {
+        if (item.gateMode === 'hard')
+            continue;
+        const icon = item.result.status === 'passed' ? chalk.green('✓') : item.result.status === 'failed' ? chalk.yellow('!') : chalk.yellow('⏸');
+        const label = name.replace(/([A-Z])/g, ' $1').toLowerCase();
+        lines.push(`  ${icon} ${label}`);
+        if (item.result.message) {
+            lines.push(`     ${chalk.gray(item.result.message)}`);
+        }
+    }
+    lines.push('');
+    // Summary
+    const hardPassed = Array.from(checkOutput.results.values())
+        .filter(item => item.gateMode === 'hard')
+        .every(item => item.result.status === 'passed');
+    const hasFallback = checkOutput.hasFallback;
+    if (hasFallback) {
+        lines.push(chalk.yellow('⏸️  判定: FALLBACK — 部分检查信号不可用，需要人工判断'));
+    }
+    else if (!hardPassed) {
+        lines.push(chalk.red('❌ 判定: BLOCKED — hard gate 未通过'));
+    }
+    else if (checkOutput.confidence.decision === 'block') {
+        lines.push(chalk.red('❌ 判定: BLOCKED — 置信度过低'));
+    }
+    else if (checkOutput.confidence.decision === 'confirm') {
+        lines.push(chalk.yellow('⚠️  判定: CONFIRM — 置信度中等，建议人工确认'));
+    }
+    else {
+        lines.push(chalk.green('✅ 判定: PASSED — 所有 gate 通过'));
+    }
+    lines.push(`置信度: ${checkOutput.confidence.score}/100`);
+    return lines.join('\n');
+}
+function toStructuredResult(result) {
+    const { checkOutput, version, versionType } = result;
+    const gates = {};
+    for (const [name, item] of checkOutput.results) {
+        gates[name] = {
+            gateMode: item.gateMode,
+            status: item.result.status,
+            message: item.result.message,
+            details: item.result.details,
+        };
+    }
+    return {
+        success: result.success,
+        blocked: result.blocked,
+        blockReason: result.blockReason,
+        version,
+        versionType,
+        confidence: checkOutput.confidence,
+        gates,
+    };
+}
+export async function runReadinessGate(options = {}) {
+    // Step 1: Analyze
+    let analyzeResult;
+    try {
+        analyzeResult = await analyzeCommits();
+    }
+    catch {
+        return {
+            success: false,
+            blocked: true,
+            blockReason: '变更分析失败',
+            checkOutput: {
+                results: new Map(),
+                allHardPassed: false,
+                hasFallback: true,
+                confidence: { score: 0, decision: 'block', reasons: ['无法分析 commits'], breakdown: { base: 0, bonuses: [], penalties: [] } }
+            }
+        };
+    }
+    // Step 2: Version
+    let versionResult;
+    try {
+        versionResult = await calculateVersion(analyzeResult);
+    }
+    catch {
+        return {
+            success: false,
+            blocked: true,
+            blockReason: '版本计算失败',
+            checkOutput: {
+                results: new Map(),
+                allHardPassed: false,
+                hasFallback: true,
+                confidence: { score: 0, decision: 'block', reasons: ['无法计算版本'], breakdown: { base: 0, bonuses: [], penalties: [] } }
+            }
+        };
+    }
+    if (!versionResult.shouldRelease || versionResult.versionType === 'none') {
+        return {
+            success: true,
+            blocked: false,
+            checkOutput: {
+                results: new Map(),
+                allHardPassed: true,
+                hasFallback: false,
+                confidence: { score: 100, decision: 'auto', reasons: ['无可发布变更'], breakdown: { base: 100, bonuses: [], penalties: [] } }
+            },
+            version: versionResult.suggestedVersion,
+            versionType: versionResult.versionType,
+        };
+    }
+    // Step 3: Gate checks
+    const checkOutput = await runQualityChecks(analyzeResult, versionResult);
+    const blocked = shouldBlockRelease(checkOutput);
+    let blockReason;
+    if (blocked) {
+        if (checkOutput.hasFallback) {
+            blockReason = '存在 fallback 状态，需要人工判断';
+        }
+        else if (!checkOutput.allHardPassed) {
+            blockReason = 'hard gate 未通过';
+        }
+        else if (checkOutput.confidence.decision === 'block') {
+            blockReason = '置信度过低';
+        }
+        else {
+            blockReason = '发布检查未通过';
+        }
+    }
+    return {
+        success: !blocked,
+        blocked,
+        blockReason,
+        checkOutput,
+        version: versionResult.suggestedVersion,
+        versionType: versionResult.versionType,
+    };
+}
+export async function handleReadinessGateCommand(options) {
+    if (options.structured && !options.json) {
+        throw new Error('--structured 需要配合 --json 使用');
+    }
+    const result = await runReadinessGate(options);
+    if (options.json) {
+        const output = options.structured
+            ? toStructuredResult(result)
+            : {
+                ...result,
+                checkOutput: {
+                    ...result.checkOutput,
+                    results: Object.fromEntries(result.checkOutput.results),
+                },
+            };
+        console.log(JSON.stringify(output, null, 2));
+        return;
+    }
+    console.log(renderGateResult(result));
+}
+export function createReadinessGateCommand() {
+    return new Command('readiness-gate')
+        .description('运行发布 readiness gate 检查（hard / warn-only / fallback 三层语义）')
+        .option('--dry-run', '仅分析，不发布')
+        .option('--verbose', '显示详细输出')
+        .option('--json', 'JSON 格式输出')
+        .option('--structured', '输出完全结构化的 JSON（不包含自然语言字符串，需要配合 --json 使用）')
+        .action(handleReadinessGateCommand);
+}
+export const readinessGateCommand = createReadinessGateCommand();
+//# sourceMappingURL=readiness-gate.js.map