release-skill 0.1.1 → 0.1.4

package/skills/release-setup/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: release-setup
+description: "首次接入 release-skill：只读发现发布单元与个性化验证候选，机械提取提案，经人工确认 setupDigest 后仅首次创建配置"
+---
+
+# release-setup
+
+## 适用场景
+
+项目尚无 `.release-skill/project.yaml`，或用户要求初始化、接入、校准发布规则时使用。配置已存在时只审计并路由到 `release-assess`，不得重新生成。
+
+## 硬边界
+
+- 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
+- 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
+- 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
+- Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
+
+## 首次接入
+
+1. 检查入口：
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
+```
+
+2. 只读发现并机械提取提案。完整报告仅写入临时会话目录；不要设置 `trap EXIT`，确认前必须保留会话文件：
+
+```bash
+set -eu
+PROJECT=<项目绝对路径>
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+set +e
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --json > "$REPORT"
+SETUP_STATUS=$?
+set -e
+[ "$SETUP_STATUS" -eq 0 ] || [ "$SETUP_STATUS" -eq 2 ] || exit "$SETUP_STATUS"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+```
+
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+
+3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
+
+```bash
+set -eu
+SETUP_SESSION=<上一步打印的会话目录绝对路径>
+PROJECT=<上一步打印的项目绝对路径>
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+只向用户展示绑定摘要、配置差异和精确 `setupDigest`，取得一次明确确认。
+
+4. 确认后用原会话与已确认摘要首次创建。三个完整报告均重定向到文件，固定提取器成功后才清理会话目录：
+
+```bash
+set -eu
+SETUP_SESSION=<已确认会话目录的绝对路径>
+PROJECT=<已确认项目的绝对路径>
+CONFIRMED_SETUP_DIGEST=<用户确认的精确 setupDigest>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --answers "$ANSWERS" --write --confirm-setup "$CONFIRMED_SETUP_DIGEST" --json > "$CREATED_REPORT"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"){console.error("setup lifecycle verification failed");process.exit(2)}if(!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){console.error("assessment report invalid");process.exit(2)}const blocking=(a.gaps??[]).filter(g=>g.severity==="error").map(({code,scope,message})=>({code,scope,message}));process.stdout.write(JSON.stringify({created:{status:c.status,compactSummary:c.compactSummary},postSetup:{status:p.status,compactSummary:p.compactSummary},assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingGaps:blocking}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+## 故障路由
+
+- `NEEDS_INPUT`：审阅紧凑摘要；有冲突先修正权威事实并重跑。
+- `LOCAL_ONLY_DETECTED`：只能建立本地配置，由用户决定是否创建远端渠道。
+- `ALREADY_CONFIGURED` / `CONFIG_EXISTS`：不覆盖，转 `release-assess`。
+- `SETUP_DIGEST_MISMATCH`：事实或 answers 已变化，重新只读发现与确认。
+- `SAFE_WRITE_UNAVAILABLE`：保留只读报告，不启用普通路径写入兜底。
+
+## 完成标准
+
+完整报告未进入 Agent 上下文；跨 shell 只靠显式会话路径续接；无冲突提案由机器机械提取；写入仅创建一次且摘要精确匹配；创建后状态和 assess 只输出紧凑结果；人工文件保持原字节。

package/skills/release-verify/SKILL.md

@@ -28,18 +28,17 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 ## 正向执行路径
 
 1. 确认有 `--run` 路径（必需），且源 run 状态为 PUBLISHED
-2. 复用 `release-help` 已解析的 `CLI` 数组，运行 `"${CLI[@]}" verify --root <path> --plan <plan-path> --run <run-path> --json`
+2. 使用插件根相对路径运行 CLI；若存在 consumer gate 或 npm `smokeBin`，先逐项审阅并增加 `--acknowledge-gate-side-effects`
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
 4. 只有 `VERIFIED` 才是 happy end
 
 ## 确定性脚本调用
 
 ```bash
-# 从 npm 全局安装
-"${CLI[@]}" verify --root <path> --plan <plan-path> --run <run-path> --json
-
-# 从源码运行
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 从插件根运行
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 计划含 consumer gate 或 smokeBin 时：
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --acknowledge-gate-side-effects --json
 ```
 
 ## 验证步骤
@@ -56,7 +55,7 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify -
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
-- 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），执行并验证输出
+- 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
 - 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
 
 ## 常见错误
@@ -68,3 +67,4 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify -
 | 远端状态不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
 | npm 安装失败 | POST_PUBLISH_VERIFY_FAILED | 停止 |
 | CLI 烟雾输出不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
+| consumer gate / smokeBin 未授权 | GATE_FAILED | 展示命令和副作用，人工确认后加 `--acknowledge-gate-side-effects` |

package/skills-src/release-assess/SKILL.md

@@ -23,16 +23,15 @@ description: Identify project topology and evaluate gaps in public documentation
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组：registry 已有受支持版本且 PATH 可用时为 `CLI=(release-skill)`；否则为 `CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")`
-2. 运行 `"${CLI[@]}" assess --root <path> --offline --json`
-3. 检查 exit code：0 = 成功，非 0 = 根据错误码处理
-4. 读取 JSON 报告中的 `status` 字段（`ASSESSED` / `NEEDS_INPUT` / `BLOCKED`）
-5. 若 `NEEDS_INPUT`，根据报告补充配置后重跑，使用最新输出作为唯一证据
+1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json`
+2. 检查 exit code：0 = 成功，非 0 = 根据错误码处理
+3. 读取 JSON 报告中的 `status` 字段（`ASSESSED` / `NEEDS_INPUT` / `BLOCKED`）
+4. 若 `NEEDS_INPUT`，根据报告补充配置后重跑，使用最新输出作为唯一证据
 
 ## 确定性脚本调用
 
 ```bash
-"${CLI[@]}" assess --root <path> --offline --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
 # 输出到文件: 加 --output <report-path>
 ```
 

package/skills-src/release-help/SKILL.md

@@ -12,34 +12,29 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；已有公开版本的生产闭环是显式的 `prepare --online --production → approve → publish → verify`
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
 
 **阶段通过规则**: `status` 与 `readiness.localPreparation.status` 只判断本地 help/assess/prepare；其充要条件是 `READY` 且 exit code 为 0。`missingRequired` 列出缺失的 Node/Git。生产发布必须另外读取 `readiness.productionPublish`：缺少 npm/gh 时为 `NOT_READY`，依赖存在时仍是 `AUTH_CHECK_REQUIRED`，因为 help 不访问网络、不验证认证。Agent 无权把本地就绪解释为生产就绪。
 
-**边界**: help 不修改文件系统、不执行外部写操作、不生成发布计划。优先探测 PATH 上的全局安装命令 `release-skill`，不可用时回退到源码路径。每个 unit 必须配置 `previousPublicBaseline`：首次发布且确认无前序版本用 none，已有版本用 bound + repo/ref/commit；none 不是绕过 publish 唯一性预检的开关。GitHub/npm、Claude/Codex marketplace 隔离安装、精确 npm 安装 smoke 与最终 VERIFIED 已通过真实 release-skill CLI + 本地 bare Git + fake gh/npm/Claude/Codex 的生产等价协议沙箱；另有隔离的已安装消费者 CLI 探针。测试未做 OS 级禁网，也未访问真实 marketplace；真实认证/API canary 尚未执行。
+**边界**: help 不修改文件系统、不执行外部写操作、不生成发布计划。优先探测 PATH 上的全局安装命令 `release-skill`，不可用时回退到源码路径。每个 unit 必须配置 `previousPublicBaseline`：首次发布且确认无前序版本用 none，已有版本用 bound + repo/ref/commit；none 不是绕过 publish 唯一性预检的开关。v0.1.1 已完成 GitHub/npm 真实生产发布、冻结 Git ref 的 Claude/Codex 消费者安装、精确 npm 安装 smoke 与最终 VERIFIED；生产等价本地协议套件继续覆盖 fake gh/npm/Claude/Codex 和本地 bare Git。测试未做 OS 级禁网，且一次成功发布不能证明其他项目的认证、权限、限流或最终一致性行为；每个项目的首次生产发布仍应作为受监控 canary。
 
 ## 正向执行路径
 
-1. 若 `npm view release-skill version` 已返回当前支持版本，探测 PATH 全局安装并运行 `release-skill help --json`
-2. registry 尚未发布当前版本或 PATH 不可用时，回退到源码路径：设置 `RELEASE_SKILL_HOME` 并运行 `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help --json`
-3. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
-4. 若环境就绪，运行 `release-assess` 识别项目拓扑
-5. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才路由到 `release-publish`
+1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json`
+2. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
+3. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
+4. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才路由到 `release-publish`
 
 ## 确定性脚本调用
 
 ```bash
-# 已确认 registry 存在当前版本后，从 npm 全局安装（推荐）
-release-skill help --json  # PATH 全局安装
-release-skill assess --root <path> --offline --json  # PATH 全局安装
-
-# 从源码 checkout 运行
-RELEASE_SKILL_HOME=/path/to/release-skill
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help --json
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" assess --root <path> --offline --json
+# 从插件根运行（自包含 bundle，无需 node_modules）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
 ```
 
 ## 故障路由
@@ -51,10 +46,11 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" assess -
 | pnpm 未安装 | 不影响本地准备；仅出现在 recommendations 中 |
 | npm/gh 未安装 | 本地准备仍可就绪，但 `readiness.productionPublish.status` 为 `NOT_READY` |
 | npm/gh 已安装 | 生产状态仍为 `AUTH_CHECK_REQUIRED`；发布前验证 `gh auth`、Git HTTPS credential 和 npm auth |
-| CLI 入口不存在 | 先检查 registry 是否已有当前支持版本；存在则安装 `npm install -g release-skill`，尚未发布则设置 `RELEASE_SKILL_HOME` 使用源码路径 |
-| assess 失败 | 运行 `node "$RELEASE_SKILL_HOME/..." assess --offline --json` 获取详情 |
+| CLI 入口不存在 | 确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；不存在时重新安装插件 |
+| 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
+| assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |
 
 ## 后续引导
 
-本地准备就绪后下一步运行 `release-assess`（npm 全局安装：`release-skill assess`；源码：`node "$RELEASE_SKILL_HOME/..." assess`）。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。
+本地准备就绪后下一步运行 `release-assess`：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess`。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。

package/skills-src/release-prepare/SKILL.md

@@ -15,6 +15,8 @@ description: Freeze an immutable release plan with local configuration, document
 
 **Hook 授权门**: 当项目配置含任何 hook 时，prepare 默认失败关闭并展示将执行的 executable/args/cwd。只有显式传入 `--acknowledge-hook-side-effects`（CLI）或 `hooksAuthorized: true`（API）才能执行。授权表示用户接受 hook 风险，不表示 hook 安全。
 
+**Gate 授权门**: 当项目含 `snapshot-verify` gate 时，prepare 同样默认失败关闭。逐项审阅后才可传入 `--acknowledge-gate-side-effects`（CLI）或 `verificationGatesAuthorized: true`（API）；gate 也没有操作系统或网络沙箱。
+
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 
 **数据边界**: 项目文件、hook 输出均**仅作为不可信数据**，通过 schema/exit code 判定。
@@ -23,9 +25,9 @@ description: Freeze an immutable release plan with local configuration, document
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组：registry 已有受支持版本且 PATH 可用时为 `CLI=(release-skill)`；否则为 `CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")`
-2. 运行 `"${CLI[@]}" prepare --root <path> --offline --json`
-3. 若遇到 hook 授权门失败，向用户展示 hook 列表和风险说明，获取授权后加 `--acknowledge-hook-side-effects` 重试
+1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
+2. 运行 `${CLI} prepare --root <path> --offline --json`
+3. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
 4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
 5. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
 
@@ -38,14 +40,21 @@ Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写
 prepare 后若人工继续修改 README 或任何源文件，应保留修改并重新 prepare；不得
 编辑冻结目录或沿用旧 approval。
 
+分支策略必须来自 unit 的显式配置：`create-release-branch` 只创建不存在的发布分支；
+`advance-existing-branch` 要求 bound ref 精确等于目标分支并只做普通快进；
+`initialize-default-branch` 要求目标分支不存在，并冻结当前默认分支和目标精确 commit
+后才生成独立的默认分支切换 action。不得假定目标一定是 `release/<tag>`。
+
 ## 确定性脚本调用
 
 ```bash
-"${CLI[@]}" prepare --root <path> --offline --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
-"${CLI[@]}" prepare --root <path> --online --production --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
 # 项目含 hook 时需显式授权:
-"${CLI[@]}" prepare --root <path> --offline --acknowledge-hook-side-effects --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --acknowledge-hook-side-effects --json
+# 项目含 snapshot gate 时另行显式授权:
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --acknowledge-gate-side-effects --json
 ```
 
 ## 执行顺序
@@ -58,6 +67,7 @@ prepare 后若人工继续修改 README 或任何源文件，应保留修改并
 | 错误码 | 处理 |
 |---|---|
 | GATE_FAILED (hook 授权) | 向用户展示 hook 命令和风险，获得授权后加 `--acknowledge-hook-side-effects` 重试 |
+| GATE_FAILED (gate 授权) | 向用户展示 snapshot gate 命令和风险，获得授权后加 `--acknowledge-gate-side-effects` 重试 |
 | GATE_FAILED (bound + offline) | 改用 `--online --production`，不得把 unobserved-offline plan 交给 publish |
 | GATE_FAILED (前序基线漂移) | 先取得并比较实际远端内容；人工选择 merge/adopt/reject。merge/adopt 都必须把接受内容落回 human-owned 权威源，并把 `previousPublicBaseline` 更新为接受状态的精确 repo/ref/commit 后重新 online production prepare；reject 停止调查，禁止改 `mode: none` 绕过 |
 | GATE_FAILED (其他) | 修复门失败原因后重试；以 CLI exit code 为准 |

package/skills-src/release-publish/SKILL.md

@@ -18,7 +18,8 @@ description: 从已批准且摘要确认的生产计划发布冻结 Git branch/t
 
 只发布 `prepare --production` 封存的 Git object 和 npm tarball，不从活动工作区重新
 打包，不生成或覆盖 README。远端 branch/tag/Release/npm version 已存在、查询不确定、
-认证失败或摘要漂移时，在全局预检阶段停止并交给人工。禁止 force、删除和自动回滚。
+认证失败或摘要漂移时，在全局预检阶段停止并交给人工。禁止覆盖、删除和自动回滚；
+新建 ref 的 create-only CAS（`--force-with-lease=<ref>:`）只断言目标不存在，不授权覆盖。
 
 ## 授权门
 
@@ -30,15 +31,14 @@ description: 从已批准且摘要确认的生产计划发布冻结 Git branch/t
 ## 确定性执行
 
 ```bash
-"${CLI[@]}" publish --root <path> --plan <plan-path> \
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" publish --root <path> --plan <plan-path> \
   --approval <approval-path> --confirm-production <planDigest> --json
 ```
 
-`CLI` 必须复用 `release-help` 已解析的入口：registry 已有受支持版本且 PATH 可用时
-为 `CLI=(release-skill)`；否则为源码 checkout 的 node 数组。
-
-执行顺序：全局只读预检 → `release/<tag>` 公开分支 → tag → npm tarball →
+执行顺序：全局只读预检 → 配置的公开分支（按三种 `branchStrategy` 执行）→ 必要时
+单独切换默认分支 → tag → npm tarball →
 GitHub Release → Claude/Codex marketplace 隔离安装。每步 execute 后立即 observe；
+默认分支 action 同时绑定名称和目标精确 commit；末尾再次核对分支/默认分支一致性。
 失败停止后续动作并记录 PARTIAL。PUBLISHED 后运行 verify 复核全新消费者安装。
 
 ## 故障路由
@@ -47,7 +47,7 @@ GitHub Release → Claude/Codex marketplace 隔离安装。每步 execute 后立
 |---|---|
 | `BASELINE_CHANGED` | 保留人工修改，重新 prepare、审阅和 approve；不要覆盖修改。 |
 | 摘要/制品不匹配 | 停止；重新 prepare，不修补冻结目录。 |
-| 远端对象已存在 | 人工判断版本或远端状态；不得 force 或覆盖。 |
+| 远端对象已存在 | 人工判断版本或远端状态；不得覆盖。create-only CAS 也必须失败关闭。 |
 | 认证/网络/未知查询错误 | 失败关闭，修复环境后基于同一证据判断是否 reconcile。 |
 | `PARTIAL` | 检查 `release-run.json`，不重跑整套发布、不删除成功对象。 |
 

package/skills-src/release-reconcile/SKILL.md

@@ -29,8 +29,8 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组，并确认有 `--run` 路径（必需），且源 run 状态为 `PARTIAL`
-2. 运行 `"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --json`
+1. 使用插件根相对路径运行 CLI，确认有 `--run` 路径（必需），且源 run 状态为 `PARTIAL`
+2. 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --json`
 3. 检查 exit code 和结构化状态：`PUBLISHED`（恢复完成，待 verify）/ `PARTIAL`（需重试）/ `BLOCKED`（需人工决策）
 4. 若 PARTIAL 且需重试，加 `--approval`；生产计划还必须加 `--confirm-production <planDigest>`
 
@@ -38,16 +38,16 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ```bash
 # reconcile
-"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --json
 # verify
-"${CLI[@]}" verify --root <path> --plan <plan-path> --run <reconcile-run-path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <reconcile-run-path> --json
 # 重试（需 --approval）
-"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --approval <approval-path> --confirm-production <planDigest> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --approval <approval-path> --confirm-production <planDigest> --json
 ```
 
 ## 幂等跳过逻辑
 
-对每个 action: observe 远端状态 → 完全一致则跳过 → 不存在且在 approval 范围内则重试 → 不一致则 REMOTE_CONFLICT 错误停止。
+对每个 action: observe 远端状态 → 完全一致则跳过 → 不存在且在 approval 范围内则重试 → 不一致则 REMOTE_CONFLICT 错误停止。`advance-existing-branch` 额外区分“冻结旧 commit”（可重试）、“计划新 commit”（已推进）和第三方 commit（冲突）；不得把自己已成功的推进误判为前序基线漂移。
 
 ## 故障路由
 

package/skills-src/release-setup/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: release-setup
+description: "首次接入 release-skill：只读发现发布单元与个性化验证候选，机械提取提案，经人工确认 setupDigest 后仅首次创建配置"
+---
+
+# release-setup
+
+## 适用场景
+
+项目尚无 `.release-skill/project.yaml`，或用户要求初始化、接入、校准发布规则时使用。配置已存在时只审计并路由到 `release-assess`，不得重新生成。
+
+## 硬边界
+
+- 默认只读。README、slogan、CHANGELOG、业务脚本和已有配置均为人工权威内容，不得重写或覆盖。
+- 发现脚本不等于选择或授权。间接脚本以 `SIDE_EFFECTS_UNPROVEN` 排除；项目特有 hook/gate 只能人工增量注册。
+- 仓库、公开文件等证据冲突时停止自动提案，交给人工修正权威事实后重新发现。
+- 写入只允许 create-once（仅创建一次），必须同时提供 answers 与精确 `setupDigest`；无安全原生写入能力时失败关闭。
+- Agent 的多次 shell 调用彼此独立；只能用首轮打印的会话目录绝对路径续接，不得假设变量仍存在。
+
+## 首次接入
+
+1. 检查入口：
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
+```
+
+2. 只读发现并机械提取提案。完整报告仅写入临时会话目录；不要设置 `trap EXIT`，确认前必须保留会话文件：
+
+```bash
+set -eu
+PROJECT=<项目绝对路径>
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+set +e
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --json > "$REPORT"
+SETUP_STATUS=$?
+set -e
+[ "$SETUP_STATUS" -eq 0 ] || [ "$SETUP_STATUS" -eq 2 ] || exit "$SETUP_STATUS"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary){console.error("compactSummary missing");process.exit(2)}process.stdout.write(JSON.stringify(r.compactSummary,null,2)+"\n")' "$REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if((r.proposalConflicts??[]).length){console.error("proposal conflicts require human resolution");process.exit(2)}if(!r.recommendedAnswers){console.error("recommendedAnswers missing");process.exit(2)}fs.writeFileSync(process.argv[2],JSON.stringify(r.recommendedAnswers,null,2)+"\n",{flag:"wx",mode:0o600})' "$REPORT" "$ANSWERS"
+```
+
+若 `proposalConflicts` 非空，暂停，让用户修正仓库/映射权威事实，删除本会话目录后从第 2 步重跑，不得猜测选边。无冲突时可人工增量编辑 `answers.json`：hook 写入 `recommendedAnswers.projectConfig.hooks` 对应的 `projectConfig.hooks`；gate 写入 `verificationGates`，并把同一 id 加入 `selectedGateIds`。人工文件保持 `mode: preserve`，跨单元共享源使用 `sourceScope: workspace`。
+
+3. 使用上一步打印的两个绝对字面量重新赋值，运行绑定 dry-run；任何人工编辑后都必须重跑本步：
+
+```bash
+set -eu
+SETUP_SESSION=<上一步打印的会话目录绝对路径>
+PROJECT=<上一步打印的项目绝对路径>
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --answers "$ANSWERS" --json > "$BOUND_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.compactSummary||!r.setupDigest){console.error("bound setup report incomplete");process.exit(2)}process.stdout.write(JSON.stringify({compactSummary:r.compactSummary,setupDigest:r.setupDigest},null,2)+"\n")' "$BOUND_REPORT"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+```
+
+只向用户展示绑定摘要、配置差异和精确 `setupDigest`，取得一次明确确认。
+
+4. 确认后用原会话与已确认摘要首次创建。三个完整报告均重定向到文件，固定提取器成功后才清理会话目录：
+
+```bash
+set -eu
+SETUP_SESSION=<已确认会话目录的绝对路径>
+PROJECT=<已确认项目的绝对路径>
+CONFIRMED_SETUP_DIGEST=<用户确认的精确 setupDigest>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --answers "$ANSWERS" --write --confirm-setup "$CONFIRMED_SETUP_DIGEST" --json > "$CREATED_REPORT"
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root "$PROJECT" --offline --json > "$ASSESS_REPORT"
+ASSESS_EXIT=$?
+set -e
+[ "$ASSESS_EXIT" -eq 0 ] || [ "$ASSESS_EXIT" -eq 1 ] || exit "$ASSESS_EXIT"
+node -e 'const fs=require("node:fs");const [c,p,a]=process.argv.slice(1).map(x=>JSON.parse(fs.readFileSync(x,"utf8")));if(c.status!=="CONFIG_CREATED"||p.status!=="ALREADY_CONFIGURED"){console.error("setup lifecycle verification failed");process.exit(2)}if(!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){console.error("assessment report invalid");process.exit(2)}const blocking=(a.gaps??[]).filter(g=>g.severity==="error").map(({code,scope,message})=>({code,scope,message}));process.stdout.write(JSON.stringify({created:{status:c.status,compactSummary:c.compactSummary},postSetup:{status:p.status,compactSummary:p.compactSummary},assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingGaps:blocking}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+## 故障路由
+
+- `NEEDS_INPUT`：审阅紧凑摘要；有冲突先修正权威事实并重跑。
+- `LOCAL_ONLY_DETECTED`：只能建立本地配置，由用户决定是否创建远端渠道。
+- `ALREADY_CONFIGURED` / `CONFIG_EXISTS`：不覆盖，转 `release-assess`。
+- `SETUP_DIGEST_MISMATCH`：事实或 answers 已变化，重新只读发现与确认。
+- `SAFE_WRITE_UNAVAILABLE`：保留只读报告，不启用普通路径写入兜底。
+
+## 完成标准
+
+完整报告未进入 Agent 上下文；跨 shell 只靠显式会话路径续接；无冲突提案由机器机械提取；写入仅创建一次且摘要精确匹配；创建后状态和 assess 只输出紧凑结果；人工文件保持原字节。

package/skills-src/release-verify/SKILL.md

@@ -28,18 +28,17 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 ## 正向执行路径
 
 1. 确认有 `--run` 路径（必需），且源 run 状态为 PUBLISHED
-2. 复用 `release-help` 已解析的 `CLI` 数组，运行 `"${CLI[@]}" verify --root <path> --plan <plan-path> --run <run-path> --json`
+2. 使用插件根相对路径运行 CLI；若存在 consumer gate 或 npm `smokeBin`，先逐项审阅并增加 `--acknowledge-gate-side-effects`
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
 4. 只有 `VERIFIED` 才是 happy end
 
 ## 确定性脚本调用
 
 ```bash
-# 从 npm 全局安装
-"${CLI[@]}" verify --root <path> --plan <plan-path> --run <run-path> --json
-
-# 从源码运行
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 从插件根运行
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 计划含 consumer gate 或 smokeBin 时：
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --acknowledge-gate-side-effects --json
 ```
 
 ## 验证步骤
@@ -56,7 +55,7 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify -
 - 在 `os.tmpdir()` 创建隔离目录
 - 执行 `npm install <package>@<version>` 带安全标志
 - 验证安装的 `package.json` name 和 version 精确匹配
-- 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），执行并验证输出
+- 若配置了 `smokeBin`：验证 bin 路径安全（无逃逸、无 symlink），从精确安装根、隔离 HOME 和最小环境执行并验证输出；这会运行已安装代码，必须显式授权
 - 若未配置 `smokeBin`：仅安装 + name/version 检查即通过
 
 ## 常见错误
@@ -68,3 +67,4 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" verify -
 | 远端状态不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
 | npm 安装失败 | POST_PUBLISH_VERIFY_FAILED | 停止 |
 | CLI 烟雾输出不匹配 | POST_PUBLISH_VERIFY_FAILED | 停止 |
+| consumer gate / smokeBin 未授权 | GATE_FAILED | 展示命令和副作用，人工确认后加 `--acknowledge-gate-side-effects` |

package/src/adapters/contract.mjs

@@ -57,6 +57,9 @@ export const ActionType = Object.freeze({
   // consumer marketplace install (production)
   CLAUDE_MARKETPLACE_INSTALL: 'claude-marketplace-install',
   CODEX_MARKETPLACE_INSTALL: 'codex-marketplace-install',
+
+  // default branch management
+  SET_DEFAULT_BRANCH: 'set-default-branch',
 });
 
 /**

package/src/adapters/git-github.mjs

@@ -25,7 +25,7 @@ async function run(command, args, options = {}) {
 
 function isNotFound(error) {
   const text = `${error?.stdout ?? ''}\n${error?.stderr ?? ''}\n${error?.message ?? ''}`;
-  return /(?:HTTP\s+404|\bstatus(?: code)?\s*[:=]?\s*404\b)/i.test(text);
+  return /(?:HTTP\s+404|\bstatus(?: code)?\s*[:=]?\s*404\b|(?:^|\n)\s*release not found\s*(?:\n|$))/i.test(text);
 }
 
 function ghRepo(action) {
@@ -62,11 +62,40 @@ async function readRemoteTag(action, remoteUrl, exec) {
   return stdout.trim().split(/\s+/)[0] ?? '';
 }
 
+function validateDefaultBranchAction(action) {
+  if (!action.repo || !action.oldBranch || !action.newBranch || !action.expectedNewBranchCommit) {
+    throw new Error('set-default-branch requires repo, oldBranch, newBranch, and expectedNewBranchCommit');
+  }
+  validateOid(action.expectedNewBranchCommit);
+  githubRepositoryUrl(action.repo, action.githubHost);
+  for (const [label, branch] of [['oldBranch', action.oldBranch], ['newBranch', action.newBranch]]) {
+    if (
+      typeof branch !== 'string' || branch.length === 0 || branch.startsWith('/') ||
+      branch.endsWith('/') || branch.includes('..') || branch.includes('\\') || /[\s~^:?*[\]]/.test(branch)
+    ) {
+      throw new Error(`${label} is not a safe Git branch name`);
+    }
+  }
+  if (action.oldBranch === action.newBranch) {
+    throw new Error('set-default-branch oldBranch and newBranch must differ');
+  }
+}
+
+async function readRemoteBranchCommit(action, exec) {
+  const remoteUrl = githubRepositoryUrl(action.repo, action.githubHost);
+  const { stdout } = await exec(
+    'git',
+    ['ls-remote', '--heads', remoteUrl, `refs/heads/${action.newBranch}`],
+    { shell: false },
+  );
+  return stdout.trim().split(/\s+/)[0] ?? '';
+}
+
 export function createGitGithubAdapter(deps = {}) {
   const exec = deps.exec ?? run;
   return Object.freeze({
     name: NAME,
-    actionTypes: Object.freeze([ActionType.GIT_PUSH, ActionType.GIT_TAG, ActionType.GITHUB_RELEASE]),
+    actionTypes: Object.freeze([ActionType.GIT_PUSH, ActionType.GIT_TAG, ActionType.GITHUB_RELEASE, ActionType.SET_DEFAULT_BRANCH]),
 
     async preflight(action, context) {
       try {
@@ -104,6 +133,27 @@ export function createGitGithubAdapter(deps = {}) {
             if (err.message?.includes('already exists')) throw err;
             if (!isNotFound(err)) throw new Error(`cannot determine GitHub Release uniqueness: ${err.message}`);
           }
+        } else if (action.actionType === ActionType.SET_DEFAULT_BRANCH) {
+          validateDefaultBranchAction(action);
+          await exec('gh', ['auth', 'status'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
+          const { stdout: current } = await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.default_branch'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
+          if (current.trim() !== action.oldBranch) {
+            throw new Error(`default branch drift: expected ${action.oldBranch} but observed ${current.trim()}`);
+          }
+          const newBranchCommit = await readRemoteBranchCommit(action, exec);
+          if (newBranchCommit && newBranchCommit !== action.expectedNewBranchCommit) {
+            throw new Error(
+              `new default branch commit drift: expected ${action.expectedNewBranchCommit} but observed ${newBranchCommit}`,
+            );
+          }
         } else {
           throw new Error(`unsupported action type: ${action.actionType}`);
         }
@@ -149,6 +199,27 @@ export function createGitGithubAdapter(deps = {}) {
             '--title', action.name ?? `Release ${action.tag}`,
             '--notes', action.notes ?? `Release ${action.tag}`,
           ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+        } else if (action.actionType === ActionType.SET_DEFAULT_BRANCH) {
+          validateDefaultBranchAction(action);
+          const { stdout: current } = await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.default_branch'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
+          if (current.trim() !== action.oldBranch) {
+            throw new Error(`default branch drift immediately before update: expected ${action.oldBranch} but observed ${current.trim()}`);
+          }
+          const newBranchCommit = await readRemoteBranchCommit(action, exec);
+          if (newBranchCommit !== action.expectedNewBranchCommit) {
+            throw new Error(
+              `new default branch commit drift immediately before update: expected ${action.expectedNewBranchCommit} but observed ${newBranchCommit || 'missing'}`,
+            );
+          }
+          await exec('gh', ['api', `repos/${action.repo}`, '-X', 'PATCH', '-f', `default_branch=${action.newBranch}`], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
         } else {
           throw new Error(`unsupported action type: ${action.actionType}`);
         }
@@ -183,6 +254,17 @@ export function createGitGithubAdapter(deps = {}) {
             { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } },
           );
           observation = { tag: release.tagName, commit: commitResult.stdout.trim(), releaseUrl: release.url };
+        } else if (action.actionType === ActionType.SET_DEFAULT_BRANCH) {
+          validateDefaultBranchAction(action);
+          const { stdout: current } = await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.default_branch'], {
+            cwd: context.root,
+            shell: false,
+            env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+          });
+          observation = {
+            defaultBranch: current.trim(),
+            newBranchCommit: await readRemoteBranchCommit(action, exec),
+          };
         } else {
           throw new Error(`unsupported action type: ${action.actionType}`);
         }