release-skill 0.1.1

package/references/03-readme-quality.md

@@ -0,0 +1,136 @@
+# 03 -- README 质量
+
+本文档定义 README 作为发布硬门的质量标准。`README.md`（英文）和 `README.zh-CN.md`（中文）均须满足以下要求。设计原则见 `00-target-state.md` P-7。
+
+---
+
+## 1. 首屏四问
+
+README 首屏（不需要滚动即可看到的内容）必须让新用户回答以下四个问题：
+
+| 编号 | 问题 | 验收标准 |
+|---|---|---|
+| Q-1 | 这是什么？ | 一句话定位，不含内部术语和架构术语 |
+| Q-2 | 它适合谁、解决什么问题？ | 明确目标用户和问题域 |
+| Q-3 | 默认会不会执行 push、GitHub Release 或 npm publish？ | 明确的安全承诺，说明外部写操作默认关闭 |
+| Q-4 | 下一条最安全的可复制命令是什么？ | 可直接复制执行的命令，不依赖隐含前置条件 |
+
+---
+
+## 2. 正文结构
+
+正文按用户任务组织，不按源码目录组织。推荐顺序：
+
+1. 一句话定位和安全承诺（对应首屏四问）。
+2. 支持的发布拓扑与不支持范围。
+3. 五分钟安装和最小示例。
+4. `release-help`、`assess`、`prepare`、`publish`、`reconcile` 的渐进式流程。
+5. 配置最小样例。
+6. 失败场景与恢复入口。
+7. 安全、权限和供应链模型。
+8. 完整 reference、贡献和维护者入口。
+
+内部术语（如"发布单元""冻结计划""reconcile"）在首次出现时必须用用户语言解释。README 不得要求用户先理解父工程内部治理、状态机实现或 adapter 源码。
+
+---
+
+## 3. 三个黑盒角色
+
+建立三个黑盒用户场景用于验收。黑盒执行者不得读取源码、设计文档或测试 oracle。若执行者需要猜测命令、默认权限或产物位置，README 验收失败。
+
+### 3.1 首次使用者
+
+- **输入**：只读 README，干净环境。
+- **目标**：完成安装，发现 `release-help`，并对 fixture 执行只读 `assess`。
+- **验收**：无需猜测任何命令或路径即可完成。
+
+### 3.2 项目维护者
+
+- **输入**：只读 README，一个父工程 + 单插件项目。
+- **目标**：写出最小配置并完成 `prepare` dry-run。
+- **验收**：配置格式、字段含义和 dry-run 命令均可从 README 推导。
+
+### 3.3 安全审阅者
+
+- **输入**：只读 README。
+- **目标**：明确指出何时发生外部写操作、授权如何失效、部分发布如何恢复。
+- **验收**：安全模型、授权失效条件和恢复路径在 README 中有清晰说明。
+
+---
+
+## 4. 可执行命令
+
+### 4.1 提取与标注
+
+README 中的 shell 命令通过以下方式标注以便自动提取：
+
+```markdown
+<!-- release-skill:exec fixture=<id> -->
+```sh
+release-skill assess --root ./my-project
+```
+```
+
+### 4.2 执行规则
+
+- 标注命令在隔离 fixture 副本中执行，不修改原始项目。
+- 所有相对链接、标题锚点、文件路径和安装命令必须验证。
+- 示例输出中的关键字段通过 snapshot 或结构断言验证，避免展示已失效界面。
+
+### 4.3 命令新鲜度
+
+- 发布前在打包后的公开快照上重复执行 README 测试，防止父工程内通过、公开包中缺文件。
+- README 中公开 Skill 名称必须与实际插件清单和目录一致。
+
+---
+
+## 5. 中英文合同
+
+中英文 README 的以下四项标记必须保持一致；允许文字表达不同，不允许行为合同漂移：
+
+| 标记类别 | 说明 |
+|---|---|
+| `capability` | 支持的功能列表 |
+| `command` | 可执行命令及参数 |
+| `safety` | 安全承诺和写操作边界 |
+| `version` | 版本信息 |
+
+验证方法：比较机器可读的标记而非自然语言文本，报告每个语言中缺失的标记。
+
+---
+
+## 6. 打包后复测
+
+发布前必须在打包后的公开快照上重复执行 README 测试：
+
+1. 构建公开快照（见 `04-supply-chain.md`）。
+2. 在快照上提取并执行所有标注命令。
+3. 验证所有链接、锚点和文件路径。
+4. 验证 Skill 名称一致性。
+5. 验证中英文标记一致性。
+
+若打包后测试失败，发布计划不得进入 PREPARED 状态。
+
+---
+
+## 7. 人工审阅门
+
+自动化无法证明文字真正易懂，因此每个重要版本还需要一次独立 README 审阅。审阅至少检查以下内容：
+
+| 审阅项 | 要求 |
+|---|---|
+| 开篇方式 | 以用户问题开篇，不以项目历史或架构术语开篇 |
+| 最小路径 | 最小路径短且无隐含前置条件 |
+| 危险命令说明 | 每个危险命令在执行前说明影响 |
+| 失败提示 | 失败提示直接指向诊断或恢复步骤 |
+| 可操作性 | 不存在"功能清单很多，但用户不知道第一步做什么"的情况 |
+
+README 黑盒场景或人工审阅未通过时，发布计划不得进入 APPROVED 状态（见 `01-state-machine.md`）。
+
+---
+
+## 8. 跨标准引用
+
+- 安全承诺和供应链模型的详细要求见 `04-supply-chain.md`。
+- 错误码和证据格式见 `05-evidence-and-errors.md`。
+- 发布状态机中的状态转换见 `01-state-machine.md`。

package/references/04-supply-chain.md

@@ -0,0 +1,147 @@
+# 04 -- 供应链安全
+
+本文档定义 release-skill 在 GitHub、npm 和插件 marketplace 发布中的安全要求，包括 provenance、签名、Action SHA 固定和最小权限模型。配置中的 hook 安全约束见 `02-project-config.md`，adapter 接口见 `06-adapter-contract.md`。
+
+---
+
+## 1. 最小权限原则
+
+### 1.1 GitHub Actions
+
+- 权限按 job 收紧，不使用仓库级默认宽权限。
+- 每个 job 仅声明其实际需要的 `permissions`。
+- 使用 `persist-credentials: false` 防止 token 留在 git 配置中。
+- 使用 GitHub App Token 或 Fine-grained PAT 替代 Classic PAT，实现精细权限控制。
+
+### 1.2 npm
+
+- 优先使用 Trusted Publishing（npm OIDC），不存储长期 npm token。
+- 若必须使用 token，限定 scope 为最小必要范围。
+- 使用 `npm publish --access public` 显式声明公开范围。
+
+### 1.3 插件 marketplace
+
+- 插件发布凭据限定为 marketplace 注册操作。
+- 不在 CI 环境中存储 Claude/Codex API 凭据。
+
+---
+
+## 2. Provenance 与签名
+
+### 2.1 npm Provenance
+
+- npm 包发布时必须携带 provenance 证明（`--provenance` 标志）。
+- Provenance 通过 OIDC token 由 CI 环境签名，证明包的构建来源和构建过程。
+- 发布后验证阶段（见 `01-state-machine.md` VERIFIED）检查 npm provenance 状态。
+
+### 2.2 Git Tag 签名
+
+- 发布 tag 优先使用 GPG 或 SSH 签名。
+- 若无法签名，tag 必须具备可追溯性：commit hash、创建时间、创建者身份记录在发布证据中。
+- 签名或可追溯性信息在批准界面展示。
+
+### 2.3 Commit 签名
+
+- 版本提交优先签名。
+- 签名状态记录在基线快照中。
+
+---
+
+## 3. 第三方 Action SHA 固定
+
+### 3.1 规则
+
+所有第三方 GitHub Action 必须固定到完整 commit SHA（40 字符），不接受分支名或语义版本标签。
+
+```yaml
+# 正确：固定到 SHA
+- uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11
+
+# 错误：使用标签
+- uses: actions/checkout@v4
+
+# 错误：使用分支
+- uses: actions/checkout@main
+```
+
+### 3.2 验证
+
+- 配置加载时检查所有 Action 引用格式。
+- 不符合 SHA 固定要求的 Action 引用返回 `CONFIG_INVALID` 错误码。
+
+---
+
+## 4. Secret 检测
+
+### 4.1 检测范围
+
+公开快照和发布产物中必须扫描以下内容：
+
+- 配置中声明的 `forbiddenContentPatterns`。
+- 通用 token 前缀：`ghp_`、`github_pat_`、`npm_`、`AKIA`。
+- 私钥标记：`BEGIN RSA PRIVATE KEY`、`BEGIN EC PRIVATE KEY`、`BEGIN OPENSSH PRIVATE KEY`。
+- 本机绝对路径：`<project-root>/` 前缀。
+- 内部目录名：`research/`、`standards/`、`runs/`、`docs/superpowers/`。
+
+### 4.2 检测行为
+
+- 检测到 secret 时返回 `SECRET_DETECTED` 错误码。
+- 错误信息中不记录 secret 的实际值，仅记录类型和位置。
+- 日志中不记录 token、认证头、npm 配置内容或未经脱敏的环境变量（见 `05-evidence-and-errors.md` 脱敏规则）。
+
+### 4.3 禁止路径
+
+以下路径不得出现在公开快照中：
+
+- 父工程专属目录：`standards/`、`research/`、`runs/`、`docs/superpowers/`。
+- 配置中声明的 `forbiddenPaths`。
+- 本机绝对路径。
+
+检测到禁止路径时返回 `PUBLIC_PATH_FORBIDDEN` 错误码。
+
+---
+
+## 5. 公开快照安全
+
+### 5.1 导出规则
+
+- 仅从 `git ls-files` 跟踪的文件中导出。
+- 显式声明的生成文件和 `package.json` 的 `files` 字段纳入导出范围。
+- 拒绝符号链接逃逸到源码根目录之外。
+- 拒绝大小写归一化后的重复目标路径。
+- 拒绝设备文件。
+
+### 5.2 构建物检查
+
+- `dist/` 目录中的文件与当前构建清单比对。
+- 构建清单不匹配的陈旧构建物返回 `STALE_BUILD_ARTIFACT` 错误码。
+
+---
+
+## 6. 策略与 Waiver
+
+### 6.1 安全策略
+
+项目通过 `policy` 字段声明安全要求（见 `02-project-config.md`）：
+
+- `requiredPublicFiles`：必须出现在公开快照中的文件列表。
+- `forbiddenPaths`：不得出现在公开快照中的路径列表。
+- `forbiddenContentPatterns`：不得出现在公开快照内容中的正则模式列表。
+
+### 6.2 不可豁免项
+
+以下安全要求不得通过 overlay 或 waiver 关闭（详见 `02-project-config.md` 第 5、6 节）：
+
+1. Secret 扫描。
+2. 发布计划摘要校验。
+3. 显式授权门。
+4. 发布后验证。
+
+---
+
+## 7. 跨标准引用
+
+- 配置 schema、hooks 和 overlay 限制见 `02-project-config.md`。
+- 错误码定义和脱敏规则见 `05-evidence-and-errors.md`。
+- Adapter 接口和外部写授权门见 `06-adapter-contract.md`。
+- 发布后验证阶段见 `01-state-machine.md` VERIFIED 状态。

package/references/05-evidence-and-errors.md

@@ -0,0 +1,164 @@
+# 05 -- 证据与错误
+
+本文档定义 release-skill 的 9 类稳定错误码、JSON/JSONL 事件格式、脱敏规则和证据目录结构。状态机见 `01-state-machine.md`，配置约束见 `02-project-config.md`。
+
+---
+
+## 1. 稳定错误码
+
+以下 9 个错误码覆盖 release-skill 全部可恢复和不可恢复错误场景。错误码在所有版本间保持稳定，不得重命名或删除。
+
+| 错误码 | 含义 | 触发场景 | 典型恢复 |
+|---|---|---|---|
+| `CONFIG_INVALID` | 配置文件格式或内容不合法 | YAML 语法错误、schema 校验失败、路径逃逸、hook 不合规 | 修正配置文件后重新运行 |
+| `BASELINE_CHANGED` | 发布计划冻结后 Git tree 发生变化 | 有文件被修改、新增或删除导致 tree hash 不匹配 | 重新运行 `prepare` 冻结新基线 |
+| `DIRTY_SCOPE_CONFLICT` | 工作目录存在未提交变更且可能影响发布范围 | dirty 文件与发布单元的源码路径重叠 | 提交或暂存变更后重试 |
+| `GATE_FAILED` | 发布门（构建、测试、lint、文档验证等）未通过 | hook 返回非零退出码 | 修复失败项后重新运行 `prepare` |
+| `AUTH_MISSING` | 缺少必要的认证凭据或权限 | GitHub token 未配置、npm 登录缺失、marketplace 凭据不足 | 配置凭据后重试 |
+| `REMOTE_CONFLICT` | 远端资源状态与冻结计划不一致 | tag 已存在但指向不同 commit、npm 版本已发布、Release 已存在且内容不同 | 人工检查远端状态并决定处理方式 |
+| `HOOK_TIMEOUT` | 项目 hook 执行超时 | hook 运行时间超过 `timeoutMs` 配置 | 增加超时值或优化 hook 执行效率 |
+| `PARTIAL_RELEASE` | 发布部分成功 | 至少一个外部检查点成功但后续检查点失败 | 使用 `reconcile` 从检查点恢复 |
+| `POST_PUBLISH_VERIFY_FAILED` | 发布后验证未通过 | 安装测试失败、泄漏审计未通过、provenance 验证失败 | 检查失败原因，可能需要人工干预 |
+
+---
+
+## 2. JSON/JSONL 事件格式
+
+### 2.1 事件结构
+
+每次执行产生 JSONL 格式的事件流，每个事件为一行 JSON 对象。
+
+```json
+{
+  "schemaVersion": 1,
+  "runId": "<uuid>",
+  "sequence": 1,
+  "timestamp": "2026-07-15T12:00:00.000Z",
+  "command": "prepare",
+  "phase": "baseline",
+  "status": "started",
+  "error": null
+}
+```
+
+### 2.2 必填字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `schemaVersion` | 整数 | 事件格式版本，当前为 1 |
+| `runId` | 字符串 | 本次执行的唯一标识（UUID） |
+| `sequence` | 整数 | 事件在本次执行中的序号，从 1 开始递增 |
+| `timestamp` | 字符串 | ISO 8601 格式的 UTC 时间 |
+| `command` | 字符串 | 触发命令名（assess、prepare、publish、reconcile、verify） |
+| `phase` | 字符串 | 当前执行阶段标识 |
+| `status` | 字符串 | 状态值：`started`、`succeeded`、`failed`、`skipped` |
+
+### 2.3 可选字段
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `error` | 对象或 null | 失败时包含错误详情：`{ "code": "<ERROR_CODE>", "message": "<中文摘要>" }` |
+| `duration` | 整数 | 阶段耗时（毫秒） |
+| `details` | 对象 | 阶段特定的补充信息 |
+
+### 2.4 摘要输出
+
+每次执行结束时产生一个面向用户的中文摘要，包含：
+
+- 执行的命令和最终状态。
+- 每个阶段的执行结果。
+- 失败的错误码和建议恢复方式。
+- 关键产物路径（发布计划、证据目录、批准记录）。
+
+---
+
+## 3. 命令记录
+
+每个 hook 和外部命令的执行记录包含以下信息：
+
+| 字段 | 说明 |
+|---|---|
+| `command` | 命令和参数数组 |
+| `cwd` | 执行目录（相对路径） |
+| `startedAt` | 开始时间（ISO 8601） |
+| `finishedAt` | 结束时间（ISO 8601） |
+| `exitCode` | 退出码 |
+| `stdout` | 标准输出引用（脱敏后存储，见第 4 节） |
+| `stderr` | 标准错误引用（脱敏后存储，见第 4 节） |
+
+---
+
+## 4. 脱敏规则
+
+### 4.1 日志脱敏
+
+日志不得记录以下内容：
+
+- token、认证头、npm 配置内容。
+- 未经脱敏的环境变量值。
+- 私钥内容。
+
+### 4.2 输出脱敏
+
+命令输出中的敏感信息按以下规则脱敏：
+
+| 模式 | 脱敏方式 |
+|---|---|
+| 键名匹配 `/token\|secret\|password\|authorization\|cookie/i` | 值替换为 `<REDACTED>` |
+| 值以 `ghp_` 开头 | 替换为 `<REDACTED_GITHUB_TOKEN>` |
+| 值以 `github_pat_` 开头 | 替换为 `<REDACTED_GITHUB_PAT>` |
+| 值以 `npm_` 开头 | 替换为 `<REDACTED_NPM_TOKEN>` |
+| 值以 `AKIA` 开头 | 替换为 `<REDACTED_AWS_KEY>` |
+| 匹配私钥头尾标记 | 整段替换为 `<REDACTED_PRIVATE_KEY>` |
+
+### 4.3 错误信息脱敏
+
+错误信息中不记录 secret 的实际值。错误码和错误消息仅描述错误类型和位置，不包含敏感数据。`SECRET_DETECTED` 错误的报告中仅记录 secret 的类型（如"GitHub PAT"）和文件路径，不记录实际值。
+
+---
+
+## 5. 证据目录结构
+
+每次执行产生一个证据目录，位于 `.release-skill/runs/<runId>/`。
+
+```text
+.runs/<runId>/
+├── events.jsonl              # JSONL 事件流
+├── summary.json              # 执行摘要
+├── commands/                 # 命令执行记录
+│   ├── 001-build.json
+│   ├── 002-test.json
+│   └── ...
+├── plan/                     # 发布计划相关
+│   ├── release-plan.json     # 冻结的发布计划
+│   └── plan-digest.txt       # 计划摘要
+├── baseline/                 # 基线快照
+│   ├── baseline.json         # Git HEAD、tree hash、dirty 文件
+│   └── snapshot-manifest.json
+├── approval/                 # 批准记录（存在时）
+│   └── approval-record.json
+└── verify/                   # 验证结果（存在时）
+    └── verify-report.json
+```
+
+### 5.1 文件保留
+
+- 证据目录在执行完成后不得被自动删除。
+- `events.jsonl` 为追加写入，不得在执行过程中被截断。
+- `summary.json` 在执行结束时原子写入。
+- 命令记录在每个命令完成后立即写入。
+
+### 5.2 引用与存储
+
+- 大型输出（如 stdout/stderr 完整内容）存储在 `commands/` 下的独立文件中。
+- 事件和摘要中通过相对路径引用命令记录文件。
+- 存储的输出内容经过第 4 节脱敏规则处理。
+
+---
+
+## 6. 跨标准引用
+
+- 状态机中的异常状态和恢复规则见 `01-state-machine.md`。
+- 配置中的 hook 约束和验证规则见 `02-project-config.md`。
+- 供应链安全中的 secret 检测范围见 `04-supply-chain.md`。
+- Adapter 接口和检查点记录见 `06-adapter-contract.md`。

package/references/06-adapter-contract.md

@@ -0,0 +1,178 @@
+# 06 -- Adapter 契约
+
+本文档定义 release-skill adapter 的接口规范、外部写授权门和幂等重试机制。状态机见 `01-state-machine.md`，安全要求见 `04-supply-chain.md`，错误码见 `05-evidence-and-errors.md`。
+
+---
+
+## 1. Adapter 接口
+
+每个 adapter 必须实现以下四个方法。所有 adapter 遵循同一接口契约，由 adapter registry 统一调度。
+
+### 1.1 preflight(action, context)
+
+- **职责**：在执行外部写操作前检查远端状态，确认操作可安全执行。
+- **时机**：在 `publish` 命令执行每个检查点之前调用。
+- **输入**：`action` 描述待执行的外部操作，`context` 包含冻结计划、批准记录和授权标志。
+- **输出**：结构化观察结果，包含远端当前状态和是否可安全执行。
+- **失败处理**：preflight 失败时不执行后续操作，返回 `REMOTE_CONFLICT` 或 `AUTH_MISSING`。
+
+### 1.2 execute(action, context)
+
+- **职责**：执行外部写操作。
+- **前置条件**：`context.externalWritesAuthorized === true`，即批准记录有效且未过期。
+- **输入**：`action` 描述待执行的外部操作，`context` 包含冻结计划和授权信息。
+- **输出**：结构化执行结果，包含远端资源标识（commit hash、tag、包版本等）。
+- **安全约束**：若授权标志为 false，execute 必须拒绝执行并返回 `AUTH_MISSING`。
+
+### 1.3 observe(action, context)
+
+- **职责**：查询远端实际状态，与冻结计划对比。
+- **时机**：在 `reconcile` 和 `verify` 阶段调用，也用于 `execute` 后的即时验证。
+- **输入**：`action` 描述已计划的外部操作，`context` 包含冻结计划。
+- **输出**：远端实际状态和与计划的一致性判断。
+- **一致性判断**：
+  - `CONSISTENT`：远端状态与计划完全匹配。
+  - `MISSING`：远端资源尚未创建。
+  - `CONFLICTING`：远端资源存在但与计划不匹配。
+
+### 1.4 verify(action, context)
+
+- **职责**：对外部写操作的结果进行深度验证。
+- **时机**：在 `verify` 阶段调用。
+- **输入**：`action` 描述已执行的外部操作，`context` 包含冻结计划和执行记录。
+- **输出**：验证结果，包括 integrity、provenance、签名状态等。
+- **验证范围**：
+  - Git tag 指向正确的 commit。
+  - GitHub Release 内容与计划一致。
+  - npm 包的 integrity 和 provenance 有效。
+  - 插件清单可被 marketplace 发现。
+  - 公开仓库通过泄漏审计。
+
+---
+
+## 2. 标准 Adapter 列表
+
+### 2.1 Git/GitHub Adapter
+
+| 操作 | 方法 | 说明 |
+|---|---|---|
+| 推送版本提交 | execute | 推送已批准的父工程版本提交 |
+| 推送子仓库快照 | execute | 更新并推送公开子仓库快照 |
+| 创建签名 tag | execute | 创建并推送签名或可追溯 tag |
+| 创建 GitHub Release | execute | 基于冻结计划创建 Release |
+| 查询 tag 状态 | observe | 检查 tag 是否存在及指向 |
+| 查询 Release 状态 | observe | 检查 Release 是否存在及内容 |
+| 验证 tag 指向 | verify | 确认 tag 指向正确的 commit |
+
+工具：`git` CLI 和 `gh` CLI，使用 `execFile` 参数数组调用。
+
+### 2.2 npm Adapter
+
+| 操作 | 方法 | 说明 |
+|---|---|---|
+| 发布 npm 包 | execute | 使用 `npm publish --provenance --access public` |
+| 查询版本状态 | observe | 使用 `npm view` 检查版本是否存在 |
+| 验证 integrity | verify | 验证包的 integrity hash 和 provenance 状态 |
+
+工具：`npm` CLI，使用 `execFile` 参数数组调用。
+
+### 2.3 插件 Marketplace Adapter
+
+| 操作 | 方法 | 说明 |
+|---|---|---|
+| 注册插件 | execute | 在 marketplace 注册插件清单 |
+| 查询插件状态 | observe | 检查插件是否可被发现 |
+| 验证安装性 | verify | 在全新环境中安装并验证插件可调用 |
+
+支持目标：Claude Code plugin marketplace、Codex plugin manifest/marketplace。
+
+---
+
+## 3. 外部写授权门
+
+### 3.1 授权要求
+
+所有 adapter 的 `execute` 方法必须在以下条件全部满足时才能执行外部写操作：
+
+1. 发布计划已冻结且 schema 验证通过。
+2. 发布计划摘要与批准记录中的摘要匹配。
+3. 批准记录存在且未超过 24 小时有效期。
+4. Git tree hash 与批准记录中的匹配。
+5. 目标版本与批准记录中的匹配。
+6. 远端无冲突状态（preflight 通过）。
+7. `context.externalWritesAuthorized === true`。
+
+任一条件不满足时，execute 返回对应错误码（`AUTH_MISSING`、`BASELINE_CHANGED`、`REMOTE_CONFLICT` 等）并拒绝执行。
+
+### 3.2 批准记录结构
+
+```json
+{
+  "planDigest": "<sha256>",
+  "baseline": {
+    "gitTreeHash": "<sha256>"
+  },
+  "targetVersion": "1.0.0",
+  "approvedActions": ["push-snapshot", "create-tag", "npm-publish", "github-release"],
+  "actor": "maintainer",
+  "approvedAt": "2026-07-15T12:00:00.000Z",
+  "expiresAt": "2026-07-16T12:00:00.000Z"
+}
+```
+
+- `approvedActions` 不得包含通配符。
+- `expiresAt` 不得晚于 `approvedAt` + 24 小时。
+
+---
+
+## 4. 幂等重试
+
+### 4.1 幂等规则
+
+- `reconcile` 阶段首先通过 `observe` 查询所有计划操作的远端状态。
+- 状态为 `CONSISTENT` 的操作幂等跳过，不重新执行。
+- 状态为 `MISSING` 的操作安全重试。
+- 状态为 `CONFLICTING` 的操作停止并返回 `REMOTE_CONFLICT`，要求人工决策。
+
+### 4.2 重试安全约束
+
+- 系统不得自动删除远端 tag。
+- 系统不得覆盖已存在的 GitHub Release。
+- 系统不得 unpublish npm 包。
+- 系统不得从头重跑已完成的发布。
+- 重试仅限于安全且未完成的步骤。
+
+### 4.3 检查点记录
+
+每个外部操作的执行结果作为检查点写入证据目录（见 `05-evidence-and-errors.md`）。检查点包含：
+
+- 操作标识和类型。
+- 执行前的 `observe` 结果。
+- 执行结果（成功/失败/跳过）。
+- 执行后的 `observe` 验证结果。
+- 远端资源标识（commit、tag、版本、URL）。
+
+---
+
+## 5. 发布 Saga 执行流程
+
+`publish` 命令按以下顺序执行：
+
+1. 重新验证发布计划 schema。
+2. 重新验证发布计划摘要。
+3. 检查批准记录是否过期。
+4. 检查 Git tree hash 是否变化。
+5. 执行远程 preflight。
+6. 按批准的操作列表顺序执行每个检查点。
+7. 每个检查点：preflight -> execute -> observe -> 记录。
+8. 任一检查点失败时停止后续动作，计算 PARTIAL（若已有成功检查点）。
+9. 所有检查点成功后进入 PUBLISHED 状态。
+
+---
+
+## 6. 跨标准引用
+
+- 状态机中的 PUBLISHING、PARTIAL、PUBLISHED 和 VERIFIED 状态见 `01-state-machine.md`。
+- 配置中的 hook 和安全策略见 `02-project-config.md`。
+- 供应链安全中的 provenance、签名和最小权限见 `04-supply-chain.md`。
+- 证据目录结构和事件格式见 `05-evidence-and-errors.md`。

package/schemas/.render-manifest.json

@@ -0,0 +1,37 @@
+{
+  "source": "schemas",
+  "files": {
+    "approval-record.schema.json": {
+      "digest": "38df0f095cc4b5be650a04513f8ea10cef5a6c3d0780ab38b0c5ee559d6ac7a5",
+      "bytes": 2611
+    },
+    "artifact-lock.schema.json": {
+      "digest": "6a5f4c826540b849571f173118bcbd778dfaceb4133034036ae565c3e9e353e5",
+      "bytes": 2729
+    },
+    "artifact-plan.schema.json": {
+      "digest": "f2166b1ec48a99135c0d55e5bacf8d74ed80d0b8cb46837819e295fa310979df",
+      "bytes": 1546
+    },
+    "artifact-policy.schema.json": {
+      "digest": "fa28b3856f2ed48b666458120c9b9d84d42c9ebfbec13bc866e8d71ecef6dea7",
+      "bytes": 2117
+    },
+    "evidence-event.schema.json": {
+      "digest": "b7e14522a5aba818cab191545f23d2323be0e4c80566e9d3e4da576103a00490",
+      "bytes": 2390
+    },
+    "release-plan.schema.json": {
+      "digest": "3647a554d7f8b1041078301b4de06c9aade0e1083ba8f6492cf4d3a825ea40ef",
+      "bytes": 4084
+    },
+    "release-project.schema.json": {
+      "digest": "6ae488bbad12563323892cc65f236a0ca3443aa6c0f4a17d69095a5c1af2574e",
+      "bytes": 6218
+    },
+    "release-run.schema.json": {
+      "digest": "eeb16507f0d852ed1c53b0fbeeeda0ab1c15abea63554d6f4c127f75ca1dc673",
+      "bytes": 4037
+    }
+  }
+}