# 项目发布策略

## 策略优先级

按以下顺序确定规则，并在来源冲突时停止说明，不要静默覆盖：

1. 用户本次请求中明确给出的目标和授权范围。
2. 项目 `AGENTS.md`、`CLAUDE.md`、发布文档和可选的 `.release-policy.yaml`。
3. 构建脚本、包清单、CI 工作流和历史发布使用的实际入口。
4. 代码托管平台当前的默认分支、保护规则、检查和允许的合并方式。
5. 本 Skill 的默认值。

用户请求若与项目硬规则或平台保护冲突，展示冲突并请求处理方式。不要借用户的一句
“直接发布”绕过仓库声明的检查或保护。

开始流程时记录 base commit，并读取该提交对应的项目策略。本次发布分支对策略文件的
修改不应改变正在执行的流程；新策略从下一次发布开始生效。

项目策略不能授予外部写权限。即使配置声明创建 Forge Release 或删除远端分支，也必须
由用户本次请求明确授权相应动作。

## 可选配置

项目反复出现同一种歧义时，用户可以要求创建 `.release-policy.yaml`。从
`templates/release-policy.template.yaml` 复制后，只保留项目真正需要固定的字段。

配置只保存可提交的项目策略：

- `schema`：配置结构版本，当前为 `1`。
- `base_branch`：发布 PR/MR 的目标分支。
- `branch_pattern`：版本分支格式，支持无展示前缀的规范 `{version}`。
- `version.scheme`：`semver` 或项目已经使用的其他方案。
- `version.sources`：构建和运行实际读取的权威版本文件。
- `tag_pattern`：release tag 格式，支持无展示前缀的规范 `{version}`。
- `merge_method`：`squash`、`merge` 或 `rebase`。
- `forge_release`：项目是否建议在 tag 后创建 Forge Release；它不授予创建权限。
- `tag_signing`：`off`、`optional` 或 `required`。
- `delete_remote_branch`：发布完成后是否建议清理远端源分支；它只是计划偏好，不是删除
  权限或自动执行指令，仍需用户在本次请求中明确授权。

不要在配置中保存 token、账号、私钥路径、个人工作目录或一次性发布状态。不要加入任意
shell 命令字段；本地验证继续从项目文档、CI 和构建入口发现。

读取配置后校验字段集合、类型和枚举值，遇到未知字段时停止。`branch_pattern` 和
`tag_pattern` 展开后分别用 Git branch/tag ref 规则校验；不要把配置值拼进 shell 字符串。
`version.sources` 中每一项必须是仓库相对路径，拒绝绝对路径和 `..`。规范化并解析
symlink 后，目标必须仍在当前 worktree 内；权威来源通常还应由 Git 跟踪。

先按版本方案把用户输入规范化。默认 SemVer 接受 `1.6.0` 或作为用户输入的 `v1.6.0`，
但内部 `{version}` 固定为 `1.6.0`；版本文件写入规范值，branch/tag pattern 分别负责添加
展示前缀。自定义版本方案按项目文档定义规范值，不能从 pattern 猜测后重复添加前缀。

## 无配置时的发现顺序

1. 从 remote HEAD 和平台信息确定默认 base，不能确定时询问。
2. 从项目文档、CI 和构建入口找版本文件及更新方式。
3. 从已有分支和已合并 PR/MR 识别命名与合并方式。
4. 从稳定 tag 识别前缀和版本方案，只把 tag 当作交叉验证。
5. 无项目约定时使用 `release/v<version>`、SemVer、`v<version>` annotated tag 和
   squash merge；默认不创建 Forge Release，不删除远端分支。

## 每次执行的计划快照

在第一次写操作前列出以下事实：

- base 分支和远端 commit。
- 当前版本、目标版本、版本来源和升级依据。
- worktree 路径与分支名。
- PR/MR 托管平台和合并方式。
- tag 与 Forge Release 计划。
- 用户授权的最远阶段和清理范围。

任何事实在执行中改变时刷新计划。改变会影响已授权的远端写目标时，再次获得确认。