release-skill 0.1.1

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "release-skill",
+  "version": "0.1.1",
+  "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mzdbxqh/release-skill.git"
+  },
+  "homepage": "https://github.com/mzdbxqh/release-skill#readme",
+  "bugs": {
+    "url": "https://github.com/mzdbxqh/release-skill/issues"
+  },
+  "type": "module",
+  "bin": {
+    "release-skill": "./bin/release-skill.mjs"
+  },
+  "files": [
+    ".agents/",
+    ".claude-plugin/",
+    ".codex-plugin/",
+    "bin/",
+    "src/",
+    "skills/",
+    "skills-src/",
+    "adapters/",
+    "references/",
+    "schemas/",
+    "native/",
+    "!native/safe-write/build/",
+    "README.md",
+    "README.zh-CN.md",
+    "CHANGELOG.md",
+    "CODE_OF_CONDUCT.md",
+    "CONTRIBUTING.md",
+    "INSTALL.md",
+    "LICENSE",
+    "NOTICE",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "node --check src/**/*.mjs",
+    "test": "node --test test/*.test.mjs",
+    "test:no-dogfood": "node --test $(ls test/*.test.mjs | grep -v -E 'dogfood|artifacts-safe-fs-native-seam')",
+    "typecheck": "node --check src/**/*.mjs bin/*.mjs",
+    "sync:skills": "node scripts/sync-skills.mjs",
+    "sync:skills:check": "node scripts/sync-skills.mjs --check",
+    "build:adapters": "node scripts/build-adapters.mjs",
+    "build:adapters:check": "node scripts/build-adapters.mjs --check",
+    "native:build": "node-gyp rebuild --directory native/safe-write",
+    "native:build:test": "GYP_DEFINES='test_seam=1' node-gyp rebuild --directory native/safe-write",
+    "native:test": "npm run native:build:test && node --expose-gc --test test/artifacts-safe-fs-native-seam.test.mjs && npm run native:build && RELEASE_SKILL_NATIVE_DEV=1 node --test test/artifacts-safe-fs.test.mjs test/artifacts-transaction-native.test.mjs && node --input-type=module -e \"import {createRequire} from 'node:module';const a=createRequire(import.meta.url)('./native/safe-write/build/Release/safe_write.node');const k=Object.keys(a).sort();const e=['abortTemp','chmod','close','createTemp','fsync','mkdir','openDir','openRoot','readEntry','readFile','rename','rmdir','unlink'];if(k.length!==e.length||k.some((v,i)=>v!==e[i])){console.error('Production exports mismatch:',k);process.exit(1)}console.log('Production exports verified:',k.length,'functions')\""
+  },
+  "dependencies": {
+    "ajv": "8.20.0",
+    "ajv-formats": "3.0.1",
+    "libnpmpublish": "11.1.0",
+    "npm-registry-fetch": "18.0.2",
+    "yaml": "2.9.0"
+  },
+  "devDependencies": {
+    "node-gyp": "12.3.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "keywords": [
+    "release",
+    "publish",
+    "governance",
+    "skill",
+    "claude-code",
+    "codex"
+  ],
+  "license": "MIT"
+}

package/references/.render-manifest.json

@@ -0,0 +1,33 @@
+{
+  "source": "standards",
+  "files": {
+    "00-target-state.md": {
+      "digest": "d66f8c33b2df2bbcb235ce123f786c18c19b3a797197495793d9af566618099d",
+      "bytes": 6335
+    },
+    "01-state-machine.md": {
+      "digest": "4004aece5729059397ef5eeac554827afc16a468ae4c6180da12fdd29228ed95",
+      "bytes": 7770
+    },
+    "02-project-config.md": {
+      "digest": "6c8d6262e5fe9c034ad961b01b8fed684adb6272a7ce4c0e4dd87bfb061519ac",
+      "bytes": 7017
+    },
+    "03-readme-quality.md": {
+      "digest": "d74e41052592443ebbd450d0ace5f9b9b19c7a94db50f952b17c1c5a4c5dc230",
+      "bytes": 4977
+    },
+    "04-supply-chain.md": {
+      "digest": "c3ef50a4b27c049c118d8c51c0d35cfb2b0f5a35ccc2c9bfa7fda4018ead0a1c",
+      "bytes": 4682
+    },
+    "05-evidence-and-errors.md": {
+      "digest": "63987751b6d3a74f02033d4e23daa1f3c30d299827de9d8242b425887607b2ac",
+      "bytes": 6658
+    },
+    "06-adapter-contract.md": {
+      "digest": "f727bfbdcd2bd6f95edc144a4fd61732ecaac2a49ffda296dbf6923f14a0c2f1",
+      "bytes": 6890
+    }
+  }
+}

package/references/00-target-state.md

@@ -0,0 +1,124 @@
+# 00 -- 目标状态
+
+本文档定义 release-skill 发布治理系统的目标拓扑、组件边界、设计原则和明确不做清单。所有规范性规则仅在此出现一次；关联领域的细节通过交叉引用指向对应标准。
+
+---
+
+## 1. 发布链路拓扑
+
+首版支持以下发布链路：
+
+```text
+父工程
+  -> 一个或多个公开 GitHub 子仓库
+  -> GitHub Release
+  -> 可选 npm publish
+  -> Claude Code / Codex 插件 marketplace 校验
+```
+
+PyPI、Cargo、Docker 等发布目标不在首版范围内，但 registry adapter 必须可以扩展。
+
+---
+
+## 2. 仓库架构与组件边界
+
+```text
+release-skill/
+├── standards/                 # 通用发布规范的唯一权威来源
+├── research/                  # 开源项目与本地项目调研证据
+├── schemas/                   # 项目配置、发布计划、执行证据 schema
+├── packages/release-skill/    # 可公开发布的插件子工程
+│   ├── skills/
+│   ├── scripts/
+│   ├── references/
+│   └── adapters/
+├── fixtures/                  # 不同成熟度项目和负向场景
+├── scripts/                   # 父工程渲染、泄漏审计、公开发布
+├── docs/                      # 设计、计划、评审和迁移报告
+└── public-release.json        # 本项目自身 dogfooding 配置
+```
+
+### 2.1 规范层
+
+`standards/` 是状态机（见 `01-state-machine.md`）、授权、配置（见 `02-project-config.md`）、版本、公开快照、文档质量（见 `03-readme-quality.md`）、供应链安全（见 `04-supply-chain.md`）、错误分类与恢复协议（见 `05-evidence-and-errors.md`）和 adapter 契约（见 `06-adapter-contract.md`）的唯一权威来源。
+
+公开插件需要的 reference 从该目录确定性渲染，禁止人工维护两个规范副本。
+
+### 2.2 确定性事务内核
+
+内核负责读取配置、归一化 profile、生成和校验发布计划、构建公开快照、运行验证门、查询远端状态、执行发布检查点并写入结构化证据。内核不得依赖 Agent 自由拼接 shell 命令。
+
+### 2.3 Skill 族
+
+首版至少提供以下公开 Skill：
+
+- `release-help`：用户可发现入口；完成依赖和环境检查、能力说明、最小示例、只读诊断、dry-run 和故障诊断引导。
+- `release-assess`：识别项目拓扑，评估公开文档、配置、供应链和发布流程距目标状态的差距。
+- `release-prepare`：补齐已授权的本地配置与文档，运行发布门并冻结发布计划，但不产生外部写操作。
+- `release-publish`：只读取已批准且未过期的发布计划，执行外部发布检查点。
+- `release-reconcile`：查询远端实际状态，处理部分成功、安全重试和发布后验证。
+
+入口 Skill 保持轻量，只编排确定性脚本和指向细分 Skill，不复制业务执行协议。默认不执行破坏性操作，写入前遵守用户授权并保护已有文件。
+
+### 2.4 Adapter 与 profile
+
+标准 adapter 包括：
+
+- Git 与公开 GitHub 子仓库
+- GitHub Release
+- npm registry
+- Claude Code plugin marketplace
+- Codex plugin manifest/marketplace
+
+首版 profile 包括：
+
+- `skill-plugin`
+- `npm-package`
+- `split-public-repos`
+- `hybrid-plugin-npm`
+
+profile 只提供默认配置，最终必须归一化为同一 schema（见 `02-project-config.md`），不能包含另一套发布流程。
+
+---
+
+## 3. 设计原则
+
+以下八条原则贯穿 release-skill 全部组件，各标准文档通过交叉引用遵守而不再重复全文。
+
+| 编号 | 原则 | 约束 |
+|---|---|---|
+| P-1 | 发布计划显式化 | 版本、发布单元、目标仓库、tag、包、验证命令和外部写操作必须进入可审阅、可冻结的发布计划（见 `01-state-machine.md` PREPARED 阶段）。 |
+| P-2 | 准备与发布分离 | 任何用户都可以安全运行只读诊断和 dry-run；外部写操作只接受绑定到冻结计划的明确授权（见 `01-state-machine.md` APPROVED 阶段、`06-adapter-contract.md` 授权门）。 |
+| P-3 | 确定性内核优先 | Agent 负责诊断、解释、生成计划和引导恢复；文件导出、hash、远端冲突检查、发布检查点和证据写入由脚本完成（见 `05-evidence-and-errors.md`）。 |
+| P-4 | 项目声明差异 | 通用流程不理解某个项目的业务规则，项目只声明发布单元、版本来源、命令 hooks 和增量安全要求（见 `02-project-config.md`）。 |
+| P-5 | 最小权限与可追溯性 | GitHub Actions 权限按 job 收紧；npm 优先 trusted publishing 和 provenance；第三方 Action 固定到 commit SHA（见 `04-supply-chain.md`）。 |
+| P-6 | 部分成功可恢复 | GitHub、Git 和 npm 无法构成原子事务，系统必须保留检查点并从实际远端状态继续，不得盲目回滚或从头重跑（见 `01-state-machine.md` PARTIAL 状态、`06-adapter-contract.md` 幂等重试）。 |
+| P-7 | README 是产品界面 | README 的可理解性、可操作性和命令新鲜度是发布硬门，不是"文件存在"检查（见 `03-readme-quality.md`）。 |
+| P-8 | 保护既有工作 | 不得 reset、clean、restore、checkout 或 stash 用户变更；跨项目评估默认只读。 |
+
+---
+
+## 4. 明确不做
+
+以下事项在 release-skill v1 中明确排除：
+
+1. 不在本轮修改四个参考项目（artifact-graph、agent-method-registry、loop-agent、flow-architect）的工作树。
+2. 不在本轮实际发布 GitHub/npm 资源。
+3. 不首版实现 PyPI、Cargo、Docker adapter。
+4. 不要求所有项目采用 Conventional Commits。
+5. 不让项目 hook 覆盖通用安全门（见 `02-project-config.md` overlay 限制、`04-supply-chain.md`）。
+6. 不把父工程私有路径、调研过程或本机绝对路径发布到公开插件。
+7. 配置及生成产物不得包含 `<project-root>/...` 等本机绝对路径。
+
+---
+
+## 5. 交叉引用索引
+
+| 领域 | 标准文档 |
+|---|---|
+| 状态与转换 | `01-state-machine.md` |
+| 配置 schema、hooks、profile、overlay、waiver | `02-project-config.md` |
+| README 质量门 | `03-readme-quality.md` |
+| 供应链安全 | `04-supply-chain.md` |
+| 错误码、证据格式、脱敏 | `05-evidence-and-errors.md` |
+| Adapter 接口与授权门 | `06-adapter-contract.md` |

package/references/01-state-machine.md

@@ -0,0 +1,155 @@
+# 01 -- 状态机
+
+本文档定义 release-skill 发布生命周期的全部状态、合法转换、禁止转换和异常处理规则。设计原则见 `00-target-state.md`。
+
+---
+
+## 1. 状态定义
+
+发布生命周期包含 7 个主状态和 3 个异常状态，共计 10 个状态。
+
+### 1.1 主状态
+
+| 状态 | 含义 | 进入条件 |
+|---|---|---|
+| **DISCOVERED** | 系统首次识别到一个可发布项目 | 通过配置文件发现或用户指定项目根目录 |
+| **ASSESSED** | 项目拓扑、配置、文档、供应链和发布流程已完成只读评估 | `assess` 命令成功退出 |
+| **PREPARED** | 发布门全部通过，发布计划已冻结写入磁盘 | `prepare` 命令成功退出，所有门均通过，计划 schema 验证通过 |
+| **APPROVED** | 人工审阅并批准了冻结的发布计划 | 批准记录绑定到发布计划 hash，且未过期 |
+| **PUBLISHING** | 外部写操作正在按检查点依次执行 | `publish` 命令读取已批准计划并开始执行 |
+| **PUBLISHED** | 所有发布检查点均已成功完成 | 最后一个检查点的 `observe` 验证通过 |
+| **VERIFIED** | 发布后验证全部通过 | `verify` 命令在全新环境中完成安装、调用、泄漏审计和远端一致性校验 |
+
+### 1.2 异常状态
+
+| 状态 | 含义 | 进入条件 |
+|---|---|---|
+| **NEEDS_INPUT** | 缺少会改变发布结果的用户选择或授权 | 配置中存在歧义、版本来源未确定或需要额外授权 |
+| **BLOCKED** | 认证、权限、验证门或外部服务阻止继续，且没有安全的本地替代路径 | 认证缺失（AUTH_MISSING）、远端服务不可达或权限不足 |
+| **PARTIAL** | 至少一个外部检查点已经成功，但发布单元尚未全部完成 | `publish` 在中途失败且已有检查点成功 |
+
+---
+
+## 2. 合法转换
+
+以下表格列出全部合法的状态转换。不在表中的转换均为禁止转换。
+
+| 源状态 | 目标状态 | 触发条件 |
+|---|---|---|
+| DISCOVERED | ASSESSED | `assess` 成功完成 |
+| DISCOVERED | NEEDS_INPUT | 发现歧义或缺失用户输入 |
+| ASSESSED | PREPARED | `prepare` 所有门通过且计划冻结 |
+| ASSESSED | NEEDS_INPUT | 评估发现需要用户输入 |
+| ASSESSED | BLOCKED | 认证缺失或外部服务阻止 |
+| PREPARED | APPROVED | 人工批准记录创建，且计划 hash、tree hash、目标版本和远端冲突状态均未变化 |
+| PREPARED | NEEDS_INPUT | 计划需要补充信息 |
+| APPROVED | PUBLISHING | `publish` 读取未过期批准并开始执行 |
+| APPROVED | PREPARED | 批准过期或计划变更导致批准失效，回退到重新准备 |
+| PUBLISHING | PUBLISHED | 所有检查点成功 |
+| PUBLISHING | PARTIAL | 至少一个检查点成功但后续失败 |
+| PUBLISHING | BLOCKED | 外部服务阻断且无法继续 |
+| PUBLISHED | VERIFIED | `verify` 全部通过 |
+| PUBLISHED | POST_PUBLISH_VERIFY_FAILED | 发布后验证失败（保留 PUBLISHED 事实但标记验证失败） |
+| NEEDS_INPUT | DISCOVERED | 用户提供输入后重新开始评估 |
+| NEEDS_INPUT | ASSESSED | 用户提供输入后恢复评估 |
+| BLOCKED | ASSESSED | 阻断因素解除后重新评估 |
+| BLOCKED | PUBLISHING | 阻断因素解除后从检查点恢复 |
+| PARTIAL | PUBLISHING | `reconcile` 从记录的检查点恢复执行 |
+| PARTIAL | VERIFIED | `reconcile` 补齐剩余步骤且 `verify` 通过 |
+| VERIFIED | DISCOVERED | 新版本周期开始 |
+
+### 2.1 自动转换规则
+
+以下转换在条件满足时自动触发，无需人工干预：
+
+- APPROVED -> PREPARED：当批准记录的计划 hash 与当前冻结计划不匹配时，批准自动失效。
+- APPROVED -> PREPARED：当 plan digest、Git tree hash、workspace digest、目标版本或已批准 action 列表变化时，批准自动失效。
+- PUBLISHING -> PARTIAL：当任一检查点成功后下一检查点失败时，自动计算 PARTIAL 状态。
+
+---
+
+## 3. 禁止转换
+
+以下转换在任何条件下均不允许：
+
+| 禁止转换 | 原因 |
+|---|---|
+| DISCOVERED -> PREPARED | 必须先完成评估 |
+| DISCOVERED -> APPROVED | 必须先评估再准备再批准 |
+| DISCOVERED -> PUBLISHING | 未评估未准备不能发布 |
+| ASSESSED -> APPROVED | 必须先通过 prepare 生成冻结计划 |
+| ASSESSED -> PUBLISHING | 必须先准备并获得批准 |
+| PREPARED -> PUBLISHING | 未获批准不能发布 |
+| PREPARED -> VERIFIED | 不能跳过发布直接验证 |
+| APPROVED -> VERIFIED | 不能跳过发布直接验证 |
+| APPROVED -> PUBLISHED | 不能跳过发布执行直接到已发布 |
+| PUBLISHING -> VERIFIED | 发布完成后必须先到 PUBLISHED |
+| PUBLISHING -> APPROVED | 发布进行中不能回退到批准 |
+| PUBLISHING -> PREPARED | 发布进行中不能回退到准备 |
+| PUBLISHED -> PUBLISHING | 已发布的不能重新发布同一计划 |
+| PUBLISHED -> APPROVED | 不能从已发布回退到批准 |
+| VERIFIED -> PUBLISHING | 已验证的不能重新发布 |
+| VERIFIED -> PUBLISHED | 已验证的不能回退到已发布 |
+| NEEDS_INPUT -> PUBLISHING | 缺少输入不能发布 |
+| BLOCKED -> PUBLISHING（非恢复路径） | 阻断状态只能通过 `reconcile` 恢复 |
+| PARTIAL -> VERIFIED（非 reconcile 路径） | 部分成功必须经过 `reconcile` 补齐 |
+
+---
+
+## 4. 异常处理
+
+### 4.1 NEEDS_INPUT 处理
+
+- 系统必须明确列出缺失的输入项、影响范围和可选方案。
+- NEEDS_INPUT 不能被静默转换为 VERIFIED。
+- 用户提供输入后，系统从 DISCOVERED 或 ASSESSED 重新开始。
+
+### 4.2 BLOCKED 处理
+
+- 系统必须记录阻断原因、相关错误码（见 `05-evidence-and-errors.md`）和建议的解除方式。
+- BLOCKED 不能被静默转换为 VERIFIED。
+- 阻断因素解除后，系统从 ASSESSED 重新评估或从 PUBLISHING 恢复。
+
+### 4.3 PARTIAL 处理
+
+- 系统必须保留至少一个已成功的外部检查点记录，不得丢失。
+- PARTIAL 状态在任何后续操作前必须被显式处理。
+- 恢复路径通过 `reconcile` 命令执行：查询远端实际状态，跳过已一致的步骤，仅重试安全且未完成的步骤。
+- 系统不得自动删除远端 tag、覆盖 GitHub Release、unpublish npm 包或从头重跑。
+- 远端状态与冻结计划不一致时（REMOTE_CONFLICT），停止并要求人工决策。
+
+### 4.4 批准失效
+
+批准记录绑定到发布计划 hash。以下任何变化均导致批准自动失效：
+
+- 发布计划内容变化（plan digest 不匹配）。
+- Git tree hash 变化。
+- 工作区 digest 变化。
+- 目标版本变化。
+- 已批准的 action 列表变化。
+
+远端冲突状态（如 tag 已存在、npm 版本冲突等）不在 approval 绑定字段中；它在 publish/reconcile 的 preflight 阶段阻断执行并要求人工决策。
+
+失效后系统回退到 PREPARED 状态，要求重新批准。
+
+### 4.5 发布检查点失败
+
+发布按以下检查点顺序执行（详见 `06-adapter-contract.md`）：
+
+1. 推送父工程版本提交（若配置管理该步骤）。
+2. 更新并推送公开子仓库快照。
+3. 创建并推送签名或可追溯 tag。
+4. 发布 npm 包。
+5. 创建 GitHub Release。
+6. 写入远端 URL、commit、tag、包版本、integrity 和执行结果。
+
+任一步失败都停止后续动作，保存检查点并进入 PARTIAL。已完成的检查点通过 `observe` 验证后在 `reconcile` 中幂等跳过。
+
+---
+
+## 5. 跨标准引用
+
+- 配置中的状态声明和 hook 参数约束见 `02-project-config.md`。
+- 错误码与证据格式见 `05-evidence-and-errors.md`。
+- Adapter 的 preflight/execute/observe/verify 接口和授权门见 `06-adapter-contract.md`。
+- 发布计划冻结和批准界面内容要求见本文档第 4.4 节和 `06-adapter-contract.md` 第 3 节。

package/references/02-project-config.md

@@ -0,0 +1,217 @@
+# 02 -- 项目配置
+
+本文档定义 `.release-skill/project.yaml` 的 schema 规范、hooks 参数约束、profile 归一化、overlay 限制和 waiver 边界。状态机见 `01-state-machine.md`，安全要求见 `04-supply-chain.md`，错误码见 `05-evidence-and-errors.md`。
+
+---
+
+## 1. 配置文件位置与格式
+
+项目使用 `.release-skill/project.yaml` 声明发布事实。
+
+- 格式：YAML 1.2，兼容 JSON。
+- 编码：UTF-8，无 BOM。
+- 不得包含 YAML alias（`*anchor`）或重复键。
+- 不得包含 `<project-root>/...` 等本机绝对路径。
+- 配置摘要（SHA-256）基于规范化 JSON 计算：递归排序对象键、保持数组顺序、序列化为 UTF-8 JSON。
+
+---
+
+## 2. 顶层 schema
+
+```yaml
+apiVersion: release-skill/v1
+kind: ReleaseProject
+
+project:
+  name: <string>            # 项目标识，必填
+  defaultBranch: <string>   # 默认分支，必填
+
+releaseUnits:               # 发布单元数组，至少 1 个
+  - id: <string>            # 唯一标识
+    source: <string>        # 源码相对路径（相对项目根目录）
+    publicRepo: <string>    # 公开仓库 owner/repo
+    version:
+      source: <string>      # 版本来源，如 "package.json"
+      tagTemplate: <string> # tag 模板，如 "artifact-graph-v{version}"
+    distributions:          # 分发渠道数组
+      - type: <string>      # "npm" | "claude-plugin" | "codex-plugin"
+        package: <string>   # npm 包名（type 为 npm 时必填）
+    publicFiles:            # 公开源码镜像的显式闭世界映射
+      - from: <string>      # 项目根相对路径
+        to: <string>        # 公开仓库中的发布单元相对路径
+        mode: preserve      # 保留源内容和可执行位
+    requiredPublicFiles:    # 本发布单元不可缺失的目标路径
+      - <string>
+    previousPublicBaseline: # 必填；每个 unit 独立声明
+      mode: none            # none | bound
+      # bound 时还必须提供 repo/ref/commit，可选 tree/manifestDigest
+
+hooks:                      # 可选，命令 hooks
+  docs: <hook>
+  build: <hook>
+  test: <hook>
+  typecheck: <hook>
+  lint: <hook>
+
+policy:                     # 可选，安全策略
+  forbiddenPaths: [<string>]
+  forbiddenContentPatterns: [<string>]
+```
+
+---
+
+## 3. 公开源码镜像与分发包
+
+`releaseUnits[].publicFiles` 定义 GitHub 公开源码镜像的显式、闭世界 allowlist。每个映射都必须可审阅；未列出的文件不会因为目录扫描、模板重生成或历史惯例而被自动加入。`releaseUnits[].requiredPublicFiles` 只约束同一发布单元，不能借用其他单元的目标路径。
+
+公开源码镜像与 distribution pack 是两条不同边界：前者决定公开仓库快照，后者由 npm `files`、插件 manifest 等渠道合同决定安装内容。发布前必须分别冻结、比较并验证两条边界；distribution pack 中的必需路径必须由该发布单元的公开映射覆盖。
+
+持续发布只复制已批准 mapping 指向的冻结源快照，不生成 README、slogan 或其他人工内容，也不以模板重新覆盖它们。人工修改一旦进入权威源，就作为下一轮迭代的输入保留。若公开目标仓库与冻结计划出现差异，系统停止写入并等待人工选择 merge、adopt 或 reject；不得静默采用任一侧，也不得从头生成文件。
+
+### 3.1 前序公开基线与人工权威源
+
+每个 `releaseUnits[]` 必须显式声明 `previousPublicBaseline`：
+
+- 确认从未发布过公开版本时使用 `mode: none`。它不是跳过冲突检查的开关；publish
+  仍会在任何 execute 前检查目标 branch、tag、GitHub Release 和 npm version 唯一性。
+- 已有公开版本时使用 `mode: bound`，并填写精确的 `repo`、不可变 `ref` 和
+  `commit`。生产 prepare 必须使用 `--online --production`，逐 unit 观察
+  ref→commit mapping；offline production 不得冻结未观察的 bound 基线。
+
+本地 human-owned 文件是下一轮发布内容的权威源；前序公开基线是冲突检测输入；
+冻结 snapshot 是本轮审批和发布的唯一字节来源。默认 Git observer 只调用
+`git ls-remote` 取得 ref→commit 映射，因此 commit 不一致时可提供 mapping diff，
+但没有下载远端文件，必须把 content diff 明确标记为 unavailable，不能声称已经比较内容。
+
+出现漂移时由人工选择：`merge`（合并双方修改）、`adopt`（采用远端修改）或
+`reject`（拒绝远端修改）。无论选择 merge 还是 adopt，决定采用的内容都必须先合并回
+human-owned 权威源，然后重新 prepare、审阅并 approve；后续环节只复制和冻结这些
+字节，不重新生成或覆盖 README、slogan 及其他人工修改。
+
+旧的 `policy.requiredPublicFiles` 已不支持。加载器必须返回 `CONFIG_INVALID`，并引导迁移到各自的 `releaseUnits[].requiredPublicFiles`。
+
+---
+
+## 4. Hooks 参数约束
+
+每个 hook 必须是对象，包含以下属性：
+
+| 属性 | 类型 | 必填 | 约束 |
+|---|---|---|---|
+| `command` | 字符串数组 | 是 | 至少 1 个元素；每个元素为字符串；第一个元素为可执行文件路径或名称；**不接受 shell 字符串** |
+| `cwd` | 字符串 | 否 | 相对路径，不得以 `/` 开头，不得包含 `..` |
+| `timeoutMs` | 整数 | 否 | 最小 1000，最大 7200000（2 小时） |
+| `envAllowlist` | 字符串数组 | 否 | 每个元素匹配 `^[A-Z_][A-Z0-9_]*$`；无重复元素 |
+
+hook 执行规则：
+
+- 使用 `execFile`，不使用 `exec` 或 `{ shell: true }`。
+- 通过 `realpath` 解析 cwd，拒绝逃逸到项目根目录之外。
+- 超时后杀死子进程，返回 `HOOK_TIMEOUT` 错误码。
+- 进程环境仅包含 `PATH`、平台必需进程变量和 allowlist 中声明的变量。
+
+示例：
+
+```yaml
+hooks:
+  test:
+    command: [pnpm, test]
+    cwd: .
+    timeoutMs: 300000
+    envAllowlist: [CI]
+```
+
+---
+
+## 5. Profile（规划中）
+
+> **当前状态：** Profile 尚未实现，`project.yaml` 不支持 `profile` 字段。
+> 以下为设计规划，不可写入当前配置文件。
+
+profile 是预设的默认配置模板，提供常见发布拓扑的开箱配置。
+
+### 5.1 首版 profile 列表
+
+| profile | 适用场景 |
+|---|---|
+| `skill-plugin` | 纯 Claude/Codex 插件发布 |
+| `npm-package` | 纯 npm 包发布 |
+| `split-public-repos` | 父工程 + 多公开子仓库 |
+| `hybrid-plugin-npm` | 插件与 npm 包混合发布 |
+
+### 5.2 归一化规则
+
+- profile 只提供默认配置值。
+- 最终必须归一化为同一 schema，不能包含另一套发布流程。
+- 项目显式声明的字段覆盖 profile 默认值。
+- 归一化后的配置摘要必须稳定：相同的项目声明和 profile 组合产生相同的摘要。
+
+---
+
+## 6. Overlay 限制（规划中）
+
+> **当前状态：** Overlay 尚未实现，`project.yaml` 不支持 `overlay` 字段。
+> 以下为设计规划，不可写入当前配置文件。
+
+项目 overlay 可以收紧通用规则（增加更严格的要求），但不能：
+
+- 关闭 secret 扫描。
+- 关闭发布计划摘要校验。
+- 关闭显式授权门。
+- 关闭发布后验证。
+- 使 hook 接受 shell 字符串。
+- 使用本机绝对路径。
+
+违反上述限制的 overlay 在配置加载时拒绝，返回 `CONFIG_INVALID` 错误码。
+
+---
+
+## 7. Waiver 边界（规划中）
+
+> **当前状态：** Waiver 尚未实现，`project.yaml` 不支持 `waiver` 字段。
+> 以下为设计规划，不可写入当前配置文件。
+
+当需要绕过某项安全门时，必须使用 waiver 机制：
+
+### 7.1 Waiver 必填字段
+
+| 字段 | 说明 |
+|---|---|
+| `rule` | 被豁免的规则标识 |
+| `reason` | 豁免理由，不得为空 |
+| `responsible` | 责任人，不得为空 |
+| `expiresAt` | 失效日期，不得为空，不得晚于 30 天 |
+
+### 7.2 展示要求
+
+- Waiver 在批准界面必须显著展示。
+- 过期的 waiver 自动失效，对应的规则恢复强制执行。
+- Waiver 不适用于以下不可豁免项：secret 扫描、计划摘要校验、显式授权、发布后验证。
+
+---
+
+## 8. 配置验证
+
+配置加载时执行以下验证：
+
+1. YAML 语法正确，无 alias 和重复键。
+2. `apiVersion` 为 `release-skill/v1`。
+3. `kind` 为 `ReleaseProject`。
+4. `project.name` 非空。
+5. `releaseUnits` 至少包含 1 个元素。
+6. 每个 `releaseUnit.id` 全局唯一。
+7. 每个 `releaseUnit.source` 路径在项目中存在。
+8. 所有 hook 的 `command` 为数组且第一个元素非空。
+9. 所有 hook 的 `cwd` 不包含绝对路径前缀和 `..`。
+10. 所有路径字段不包含 `<project-root>/` 前缀。
+
+验证失败返回 `CONFIG_INVALID` 错误码，附带具体失败原因。
+
+---
+
+## 9. 跨标准引用
+
+- 状态机中的状态定义和转换规则见 `01-state-machine.md`。
+- 供应链安全中的最小权限和 Action 固定要求见 `04-supply-chain.md`。
+- 错误码定义见 `05-evidence-and-errors.md`。
+- Adapter 接口见 `06-adapter-contract.md`。