release-skill 0.1.1 → 0.1.3

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # release-skill
 
-[English](README.md)
+[English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
@@ -9,23 +9,21 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 最后一步重新生成 README、重新打包活动工作区或覆盖人工内容。
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** `assess`、离线 `prepare`，以及冻结 Git branch/tag、GitHub
-> Release、npm tarball、Claude/Codex 插件市场消费者安装验证已通过生产等价协议沙箱：
-> 测试运行真实 release-skill CLI 和冻结制品，Git 目标是本地 bare remote，`gh`、
-> `npm`、Claude、Codex 是协议级 fake；另有隔离的本地探针调用已安装的
-> Claude/Codex CLI，但没有访问真实 marketplace 或生产 API。这些测试没有提供
-> OS 级网络隔离。我们尚未替你执行真实生产 canary；
-> 第一次真实发布仍应作为受监控 canary。真实 API、认证、权限、限流和最终一致性
-> 不属于该沙箱证明范围。`prepare --online` 观察前序公开基线（bound 模式），
-> 漂移或不可观察时失败关闭；远端唯一性检查延后到 `publish` 全局预检完成。
+> **当前边界：** v0.1.1 已完成 GitHub 与 npm 的真实生产发布，并从冻结 Git ref
+> 完成精确 npm 安装及 Claude/Codex 消费者安装验证。同一工作流还通过了本地
+> 生产等价协议套件：测试运行真实 release-skill CLI 和冻结制品，Git 目标是本地
+> bare remote，`gh`、`npm`、Claude、Codex 使用协议级 fake。该套件没有提供 OS 级
+> 网络隔离，也不能证明其他项目的认证、权限、限流和最终一致性行为与本次发布相同；
+> 每个项目的第一次生产发布仍应作为受监控 canary。`prepare --online` 观察 bound
+> 前序公开基线，漂移或不可观察时失败关闭；远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **v0.1.1 发布候选：** 在 `npm view release-skill version` 返回 `0.1.1` 前，
-> 使用下方源码 checkout 命令，不要假设 npm 命令已经存在。
+> **v0.1.1 已完成真实生产发布与验证。** npm 安装的 CLI 是受支持的用户入口；
+> 源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
-> - npm 已发布：`release-skill help`
-> - 当前发布候选：`node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help`
+> - npm 安装：`npm install -g release-skill` → `release-skill help`
+> - 源码 checkout：`node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help`
 
 <!-- release-skill:maturity:v0.1-boundary -->
 <!-- release-skill:maturity:boundary -->
@@ -60,11 +58,7 @@ release-skill 不重新生成、也不回写项目源文件。`prepare` 从当
 - Git 2.30+
 - 至少已有一个提交的目标 Git 仓库
 
-> **v0.1.1 发布候选：** 生产发布完成前，npm registry 可能返回 404，本轮审阅
-> 请使用下方源码 checkout。只有当 `npm view release-skill version` 返回 `0.1.1`
-> 后，npm 安装的 CLI 才是受支持的用户入口；源码 checkout 仅作为开发回退。
-
-**从 npm 安装（v0.1.1 发布后受支持）：**
+**从 npm 安装（推荐）：**
 
 ```bash
 npm install -g release-skill
@@ -82,7 +76,7 @@ npx release-skill help
 release-skill help
 ```
 
-**开发安装（从源码 checkout）：**
+**开发安装（贡献者回退，从源码 checkout）：**
 
 设置源码路径并安装依赖：
 
@@ -94,8 +88,6 @@ npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
 
 然后通过 `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs"` 调用 CLI。
 
-在目标项目创建 `.release-skill/project.yaml`：
-
 先保护本地运行数据，避免把计划、审批和冻结制品提交进仓库：
 
 ```gitignore
@@ -103,7 +95,135 @@ npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
 !.release-skill/project.yaml
 ```
 
-然后创建配置；npm 的可见性必须显式选择，不能依赖工具猜测：
+### 首次接入：先发现，再由人工定稿
+
+项目尚无配置时，先运行只读 setup。它会扫描包、插件清单、Git remote、旧版
+`public-release.json` 和质量脚本，列出发布单元、tag、分支、前序公开基线及验证
+gate 候选，但不会读取 README 正文作为指令，也不会自动选择或执行脚本：
+
+```bash
+release-skill setup --root /absolute/path/to/my-project --json
+```
+
+`NEEDS_INPUT` 和 `LOCAL_ONLY_DETECTED` 会按设计返回退出码 2：它们表示仍需人工决策，
+不是内部崩溃。自动化应读取 JSON 的 `status`，不要把 setup 的所有非零退出码都当作
+工具故障。
+
+审阅候选后，人工创建 answers JSON，其中 `projectConfig` 是完整配置，
+`selectedGateIds` 与其中 `verificationGates[].id` 必须精确一致；不需要个性化 gate
+时显式使用空数组。带 answers 再 dry-run 一次，确认它绑定的新 `setupDigest`，最后
+才允许首次创建配置：
+
+```json
+{
+  "projectConfig": {
+    "apiVersion": "release-skill/v1",
+    "kind": "ReleaseProject",
+    "project": { "name": "my-project", "defaultBranch": "main" },
+    "releaseUnits": [{
+      "id": "my-project",
+      "source": ".",
+      "publicRepo": "owner/my-project",
+      "version": { "source": "package.json", "tagTemplate": "v{version}" },
+      "distributions": [{
+        "type": "npm",
+        "package": "my-project",
+        "access": "public",
+        "provenance": false,
+        "tag": "latest",
+        "registry": "https://registry.npmjs.org",
+        "publisher": "my-npm-username"
+      }],
+      "publicFiles": [
+        { "from": "README.md", "to": "README.md", "mode": "preserve" },
+        { "from": "package.json", "to": "package.json", "mode": "preserve" }
+      ],
+      "requiredPublicFiles": ["README.md", "package.json"],
+      "previousPublicBaseline": { "mode": "none" },
+      "production": {
+        "branchTemplate": "release/{tag}",
+        "branchStrategy": "create-release-branch"
+      }
+    }]
+  },
+  "selectedGateIds": []
+}
+```
+
+这是完整的 schema 形状，不是项目事实的权威答案。仓库、渠道、基线与公开文件
+都必须替换为本项目经审阅的事实；只有确认不存在任何历史公开版本时才可使用
+`mode: none`。
+
+如果要选择一个 dry-run 已报告的 gate，保留同一份完整 `projectConfig`，在其中增加
+顶层 `verificationGates`，并让外层 `selectedGateIds` 完全一致。例如 dry-run 已
+报告 `my-project-script-test` 时：
+
+```json
+{
+  "projectConfig": {
+    "apiVersion": "release-skill/v1",
+    "kind": "ReleaseProject",
+    "project": { "name": "my-project", "defaultBranch": "main" },
+    "releaseUnits": [{
+      "id": "my-project",
+      "source": ".",
+      "publicRepo": "owner/my-project",
+      "version": { "source": "package.json", "tagTemplate": "v{version}" },
+      "distributions": [{
+        "type": "npm",
+        "package": "my-project",
+        "access": "public",
+        "provenance": false,
+        "tag": "latest",
+        "registry": "https://registry.npmjs.org",
+        "publisher": "my-npm-username"
+      }],
+      "publicFiles": [
+        { "from": "package.json", "to": "package.json", "mode": "preserve" }
+      ],
+      "requiredPublicFiles": ["package.json"],
+      "previousPublicBaseline": { "mode": "none" },
+      "production": {
+        "branchTemplate": "release/{tag}",
+        "branchStrategy": "create-release-branch"
+      }
+    }],
+    "verificationGates": [{
+      "id": "my-project-script-test",
+      "phase": "snapshot-verify",
+      "scope": { "unit": "my-project" },
+      "command": ["node", "-e", "const p=require('./package.json');if(!p.name)process.exit(1)"],
+      "cwd": ".",
+      "timeoutMs": 30000,
+      "envAllowlist": []
+    }]
+  },
+  "selectedGateIds": ["my-project-script-test"]
+}
+```
+
+id 必须复制自当前 `gateCandidates`，不得自创。示例命令只依赖公开快照中的
+`package.json`。如果改用项目脚本，该脚本及其全部依赖必须包含在 `publicFiles` 中；
+snapshot gate 看不到父工作空间的测试、开发依赖或 `node_modules`，除非它们本来就是
+显式公开内容。
+
+```bash
+release-skill setup --root /absolute/path/to/my-project \
+  --answers /absolute/path/to/setup-answers.json --json
+release-skill setup --root /absolute/path/to/my-project \
+  --answers /absolute/path/to/setup-answers.json \
+  --write --confirm-setup <setupDigest> --json
+```
+
+setup 只会原子创建不存在的 `.release-skill/project.yaml`。v0.1.3 的 create-once
+写入使用随包提供、带摘要登记的 `darwin-arm64` 原生预构建；
+不支持的平台会以 `SAFE_WRITE_UNAVAILABLE` 失败关闭，不会退回存在路径竞态的写法。
+已有配置返回 `ALREADY_CONFIGURED`/`CONFIG_EXISTS`，后续由人工增量编辑；README、slogan、
+CHANGELOG 和业务脚本不会被生成或覆盖。没有远端渠道时会返回
+`LOCAL_ONLY_DETECTED`，表示生产渠道仍需人工建立或明确放弃。
+
+下面是人工配置的最小示例；npm 可见性、公开文件边界和远端目标必须显式选择，
+不能依赖工具猜测：
 
 ```yaml
 apiVersion: release-skill/v1
@@ -151,6 +271,7 @@ releaseUnits:
         #   status: READY
     production:
       branchTemplate: release/{tag}
+      branchStrategy: create-release-branch
       releaseTitleTemplate: "{unit} {version}"
       releaseNotes: "人工维护的发布说明"
 ```
@@ -177,6 +298,55 @@ diff unavailable。发生漂移时先停止发布，由人工取得并审阅真
 把 `previousPublicBaseline` 重新绑定到人工接受的不可变 `repo`/`ref`/`commit`，再运行
 新的 `prepare --online --production`、审阅和 approve。
 
+分支策略也必须符合真实仓库语义：
+
+- `create-release-branch`：创建不存在的独立发布分支；同名分支存在即停止。
+- `advance-existing-branch`：在 `previousPublicBaseline` 精确提交上创建单父提交，
+  只允许普通 fast-forward push；远端并发漂移时交由人工。
+- `initialize-default-branch`：受控创建不存在的标准分支；只有显式配置
+  `setAsDefaultBranch` 和 `expectedCurrentDefaultBranch` 时，默认分支切换才成为
+  计划中可批准、可观察、可 reconcile 的独立动作。
+
+三种策略的最小配置如下：
+
+```yaml
+# 新建不可变 release 分支；目标必须不存在。
+previousPublicBaseline: { mode: none } # 仅限真正的首次公开发布
+production:
+  branchTemplate: release/{tag}
+  branchStrategy: create-release-branch
+```
+
+```yaml
+# 推进 main；绑定的 ref 必须与目标分支精确一致。
+previousPublicBaseline:
+  mode: bound
+  repo: owner/my-project
+  ref: refs/heads/main
+  commit: 0123456789abcdef0123456789abcdef01234567
+production:
+  branchTemplate: main
+  branchStrategy: advance-existing-branch
+```
+
+```yaml
+# 一次性创建尚不存在的 main，并显式切换默认分支。
+previousPublicBaseline:
+  mode: bound
+  repo: owner/my-project
+  ref: refs/heads/old-public-branch
+  commit: 0123456789abcdef0123456789abcdef01234567
+production:
+  branchTemplate: main
+  branchStrategy: initialize-default-branch
+  setAsDefaultBranch: true
+  expectedCurrentDefaultBranch: old-public-branch
+```
+
+后两种策略必须运行 `prepare --online --production`。如果观察到的分支、commit、
+目标不存在性或当前默认分支与预期不符，先停止并审阅真实远端状态，再人工更新权威
+源文件/配置；禁止 force push 或弱化基线。
+
 这只是解释机制的本地示例，不是完整的 npm 发布清单。真实发布前必须枚举全部
 公开运行时代码、可执行文件、类型声明、图片和链接文档。monorepo 应把 `source`
 设为 `packages/my-plugin` 之类的子目录；每个 `from` 仍相对工作空间根，例如
@@ -188,47 +358,68 @@ diff unavailable。发生漂移时先停止发布，由人工取得并审阅真
 
 ### 主流程
 
-按以下顺序执行。步骤 1–3 是安全默认（只读或仅本地）；步骤 4–8 是需要显式
+按以下顺序执行。步骤 1–4 是安全默认（只读或仅本地）；步骤 5–9 是需要显式
 人工门禁的生产发布。
 
 ```bash
-# 当前 v0.1.1 发布候选：
-CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
+# npm 安装的 CLI（推荐）：
+CLI=(release-skill)
 PROJECT=/absolute/path/to/my-project
-# npm view 已返回 0.1.1 且安装完成后：
-# CLI=(release-skill)
+ACTOR=your-name
+# 开发回退（源码 checkout）：
+# CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")
 ```
 
-在 npm 生产发布验证完成前，源码 checkout 是候选默认入口；发布验证完成后，
-npm 安装入口才是受支持的用户默认路径。
+v0.1.1 生产发布验证完成后，npm 安装的 CLI 是受支持的用户入口；
+源码 checkout 保留为开发/贡献者路径。
 
 1. **环境检查：**
    ```bash
    "${CLI[@]}" help
    ```
-2. **就绪评估（只读）：**
+2. **首次接入（仅缺少配置时，只读）：**
+   ```bash
+   "${CLI[@]}" setup --root "$PROJECT" --json
+   ```
+   按上文完成 answers 和精确 `setupDigest` 确认；配置已存在时跳过。
+3. **就绪评估（只读）：**
    ```bash
    "${CLI[@]}" assess --root "$PROJECT" --offline --json
    ```
-3. **本地快照与计划冻结：**
+4. **本地快照与计划冻结：**
    ```bash
-   "${CLI[@]}" prepare --root "$PROJECT" --offline --json
+   "${CLI[@]}" prepare --root "$PROJECT" --offline \
+     --acknowledge-hook-side-effects \
+     --acknowledge-gate-side-effects --json
    ```
-4. **人工审阅：** 检查返回的 `planPath`、`externalActions`、
+   只有项目配置没有对应 hook 或 snapshot gate 时，才省略相应授权参数。授权前
+   必须审阅可执行文件、参数、工作目录和副作用，不能把授权参数当固定样板。
+5. **人工审阅：** 检查返回的 `planPath`、`externalActions`、
    `units[].targetVersion` 和 `planDigest`。每个发布单元的快照位于
-   `<evidenceDir>/snapshots/<unit-id>/`。命令只在 `.release-skill/` 下写入本地数据。
-5. **生产计划冻结：**
+   `<evidenceDir>/snapshots/<unit-id>/`。release-skill 自身只把数据写入
+   `.release-skill/`；获得授权的项目 hook/gate 是无沙箱进程，可能写入其他位置或
+   访问网络。
+6. **生产计划冻结：**
    ```bash
-   "${CLI[@]}" prepare --root "$PROJECT" --online --production --json
+   PRODUCTION_JSON=$("${CLI[@]}" prepare --root "$PROJECT" --online --production \
+     --acknowledge-hook-side-effects \
+     --acknowledge-gate-side-effects --json)
+   printf '%s\n' "$PRODUCTION_JSON" | jq .
+   PLAN_PATH=$(printf '%s\n' "$PRODUCTION_JSON" | jq -r '.planPath')
+   PLAN_DIGEST=$(printf '%s\n' "$PRODUCTION_JSON" | jq -r '.planDigest')
    ```
+   同样，只省略配置不需要的授权，并在授权前逐项审阅项目进程。
    审阅新 plan 的 externalActions、npm access/provenance/tag、branch/tag 和冻结摘要。
    `prepare --json` 返回的生产权威 `planPath` 指向
    `<项目>/.release-skill/plans/<planDigest>.json`，后续必须始终沿用这个返回值。
    `.release-skill/release-plan.json` 只是可变便利副本，不得传给生产
    approve/publish/reconcile。
-6. **批准：**
+7. **批准：**
    ```bash
-   "${CLI[@]}" approve --plan <planPath> --digest <planDigest> --actor <name> --json
+   APPROVAL_JSON=$("${CLI[@]}" approve --plan "$PLAN_PATH" \
+     --digest "$PLAN_DIGEST" --actor "$ACTOR" --json)
+   printf '%s\n' "$APPROVAL_JSON" | jq .
+   APPROVAL_PATH=$(printf '%s\n' "$APPROVAL_JSON" | jq -r '.approvalPath')
    ```
    返回的生产权威 `approvalPath` 指向
    `<项目>/.release-skill/approvals/<planDigest>/<approvalDigest>.json`。
@@ -236,22 +427,30 @@ npm 安装入口才是受支持的用户默认路径。
    副本，不得传给生产 publish/reconcile。批准 24 小时失效；PARTIAL 恢复可为同一
    plan 重新批准，同时逐字节保留全部旧批准。后续必须使用返回的 immutable
    `approvalPath` 和 `expiresAt`。
-7. **发布（从此开始写远端）：**
+8. **发布（从此开始写远端）：**
    ```bash
-   "${CLI[@]}" publish --root "$PROJECT" \
-     --plan <planPath> --approval <approvalPath> \
-     --confirm-production <planDigest> --json
+   PUBLISH_JSON=$("${CLI[@]}" publish --root "$PROJECT" \
+     --plan "$PLAN_PATH" --approval "$APPROVAL_PATH" \
+     --confirm-production "$PLAN_DIGEST" --json)
+   printf '%s\n' "$PUBLISH_JSON" | jq .
+   PUBLISH_RUN_PATH=$(printf '%s\n' "$PUBLISH_JSON" | jq -r '.runPath')
    ```
    保存返回的 `runPath`。`PUBLISHED` **不是**终态。
-8. **验证（消费者安装检查）：**
+9. **验证（消费者安装检查）：**
    ```bash
    "${CLI[@]}" verify --root "$PROJECT" \
-     --plan <planPath> --run <publishRunPath> --json
+     --plan "$PLAN_PATH" --run "$PUBLISH_RUN_PATH" \
+     --acknowledge-gate-side-effects --json
    ```
+   只有计划既没有 consumer gate，也没有 npm `smokeBin` 时才省略授权。两者都会
+   执行已安装的项目代码，而且没有操作系统或网络沙箱。
+
+以上返回值交接示例依赖 `jq`。没有 `jq` 时必须从 JSON 原样复制这四个字段；不要把
+文档其他位置的尖括号标签直接当作 shell 语法。
 
 生产 prepare 会把每个公开快照封存为独立 Git commit/tree，并为 npm 单元生成固定
 tarball。`publish` 先对所有动作做只读预检，再按“公开快照 branch → tag → npm →
-GitHub Release → Claude/Codex marketplace 安装”执行并逐项观察。`verify` 在隔离目录
+GitHub Release → Claude/Codex 插件市场（marketplace）安装”执行并逐项观察。`verify` 在隔离目录
 安装每一个精确 npm `package@version`；配置 `smokeBin` 后还会运行 CLI 并校验输出。
 只有全部证据与冻结计划一致才进入 `VERIFIED`。真实发布前运行 `gh auth login`、
 `gh auth setup-git` 和 `npm login`，同时确认 Git HTTPS credential 能访问目标仓库。
@@ -382,17 +581,23 @@ unpublish 已发布的包）。
 使用 `reconcile` 检查实际远端状态，跳过已一致的步骤，安全重试未完成的动作：
 
 ```bash
-"${CLI[@]}" reconcile --root "$PROJECT" \
-  --run <publishRunPath> \
-  --plan <planPath> \
-  --approval <approvalPath> \
-  --confirm-production <planDigest> \
-  --json
+RECONCILE_JSON=$("${CLI[@]}" reconcile --root "$PROJECT" \
+  --run "$PUBLISH_RUN_PATH" \
+  --plan "$PLAN_PATH" \
+  --approval "$APPROVAL_PATH" \
+  --confirm-production "$PLAN_DIGEST" --json)
+printf '%s\n' "$RECONCILE_JSON" | jq .
+RECONCILE_RUN_PATH=$(printf '%s\n' "$RECONCILE_JSON" | jq -r '.runPath')
 # 保存 reconcile 返回的新 runPath，再执行全新的安装验证。
 "${CLI[@]}" verify --root "$PROJECT" \
-  --plan <planPath> --run <reconcileRunPath> --json
+  --plan "$PLAN_PATH" --run "$RECONCILE_RUN_PATH" \
+  --acknowledge-gate-side-effects --json
 ```
 
+只有冻结计划既没有 consumer gate，也没有 npm `smokeBin` 时才省略 verify 授权。
+以上变量沿用主流程从 JSON 提取的精确值；如果恢复期间批准已过期，应为同一个不可变
+计划重新批准，并在 reconcile 前替换 `APPROVAL_PATH`。
+
 `reconcile` 查询实际远端状态（Git refs、npm 版本、GitHub Release、
 marketplace 安装），跳过证据已匹配冻结计划的步骤，只重试安全且未完成的
 步骤。远端冲突（例如意外的 tag 或 npm 版本）需要人工判断，无法自动解决。
@@ -404,6 +609,8 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 - 验证项目配置和发布单元；
 - `assess` 在不修改项目的前提下报告就绪度；
 - 把配置的公开文件复制到隔离快照；
+- 只读发现首次接入候选，经精确 `setupDigest` 确认后仅首次创建配置；
+- 在冻结快照副本和精确消费者安装根运行经人工选择的项目 gate；
 - 检查必需文件、路径安全、精确字节/权限和明显泄漏；
 - 记录 Git/工作区身份，冻结绑定 digest 的发布计划；
 - 用计划摘要、有效期和显式 action allowlist 绑定人工批准；
@@ -412,6 +619,47 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 - 明确区分 `PUBLISHED`（外写完成）与 `VERIFIED`（远端和消费者安装证据完成）；
 - 中途失败停止后续动作，记录独立 run；不修改冻结 plan，不自动撤销已成功动作。
 
+## 个性化验证：hook 与 gate
+
+`hooks.docs/build/test/typecheck/lint` 在冻结前运行，适合确实需要生成源文件或依赖
+父工作区的步骤。它们可能修改项目或访问网络，prepare 必须显式传入
+`--acknowledge-hook-side-effects`。
+
+`verificationGates` 是更适合发布校准的受控扩展点：
+
+```yaml
+verificationGates:
+  - id: package-contract
+    phase: snapshot-verify
+    scope: { unit: my-project }
+    command:
+      - node
+      - -e
+      - "const p=require('./package.json'); if (!p.name) process.exit(1)"
+    cwd: .
+    timeoutMs: 120000
+    envAllowlist: [CI]
+  - id: installed-help
+    phase: consumer-verify
+    scope: { unit: my-project, distribution: npm }
+    command: [node, scripts/check-installed-help.mjs]
+    cwd: .
+    timeoutMs: 30000
+    envAllowlist: []
+    expectedJson: { status: READY }
+```
+
+snapshot 示例刻意设计为自包含，只读取已映射的公开文件。若替换成项目脚本，该脚本
+及其全部依赖必须存在于冻结公开快照；consumer 脚本也必须存在于精确安装的发行物。
+gate 不能借用父工作空间中的测试、开发依赖或 `node_modules`。
+
+`snapshot-verify` 在冻结公开快照的一次性可写副本中执行；`consumer-verify` 在精确
+npm/Claude/Codex 隔离安装根执行。两者都使用命令数组而非 shell 字符串，定义和
+结果会进入摘要证据，并要求 prepare/verify 显式传入
+`--acknowledge-gate-side-effects`。gate 仍是无网络沙箱的项目进程，release-skill
+无法保证它不会写文件或访问网络。push、tag、默认分支切换、GitHub Release 和
+npm publish 不能放进 hook/gate，只能由冻结计划的受控动作执行。
+
 ## 当前不会做什么
 
 <!-- release-skill:capability:unsupported-scope -->
@@ -420,28 +668,38 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 - 不声称已经替项目完成真实生产 canary；
 - `prepare --online` 只观察 bound 前序基线的 ref→commit 映射；目标唯一性由
   publish 全局预检完成；
-- 不 force push，不覆盖已有 branch/tag/Release，不 unpublish npm；
+- 不覆盖已有 branch/tag/Release，不 unpublish npm；新建 ref 仅使用
+  `--force-with-lease=<ref>:` 作为“目标必须不存在”的原子比较并设置断言，推进已有
+  分支使用普通非 force push；
 - 不承诺 Windows 或广泛的跨平台原生写入；
 - 不会隐藏地 commit、push、打 tag、创建 Release 或发布包。
 
 ### 写入安全
 
-`assess` 默认只读，只有显式指定报告输出时才写报告。`prepare` 会在
+`setup` 默认只读，写入只允许精确摘要确认后首次创建配置。`assess` 默认只读，
+只有显式指定报告输出时才写报告。`prepare` 会在
 `.release-skill/` 下写本地文件，但不会写项目源文件或远端服务。如果配置了
 hook，它就是任意本地进程，必须使用 `--acknowledge-hook-side-effects` 明确授权；
-hook 可能自行产生文件系统或网络副作用。`publish` 是唯一生产外写入口，必须同时
+gate 同样是项目进程，必须使用 `--acknowledge-gate-side-effects` 明确授权。它们
+可能自行产生文件系统或网络副作用。`publish` 是唯一生产外写入口，必须同时
 提供 approval 和当前 plan digest。最小安全演练应省略 hook，并在本地沙箱目标运行。
 
 ### 失败时怎么办
 
 | 结果 | 下一步 |
 |---|---|
+| `NEEDS_INPUT` | 补齐 setup 列出的仓库、tag、渠道、基线和 gate 人工决策。 |
+| `LOCAL_ONLY_DETECTED` | 决定建立远端渠道或仅保留本地配置设计；不得冒充生产就绪。 |
+| `SETUP_DIGEST_MISMATCH` | 项目事实或 answers 已变化；重新 dry-run、审阅并确认新摘要。 |
+| `CONFIG_EXISTS` | setup 不覆盖已有配置；运行 assess 后人工增量修改。 |
+| `SAFE_WRITE_UNAVAILABLE` | 当前平台不支持自动 create-once；保留只读报告，由人工首次创建经审阅的配置，且不得覆盖已有文件。 |
 | `CONFIG_INVALID` | 修正 `.release-skill/project.yaml`，重新运行 `assess`。 |
 | `PUBLIC_FILE_MISSING` | 添加或修正配置中的公开文件。 |
 | `FORBIDDEN_CONTENT_DETECTED` | 移除泄漏或私有内容，再次 prepare。 |
 | `SNAPSHOT_FIDELITY_FAILED` | 检查源文件和快照路径，重新运行 `prepare`。 |
 | `BASELINE_CHANGED` | 保留人工修改，重新 prepare、审阅和 approve。 |
-| `GATE_FAILED` | 检查冻结制品、认证、远端唯一性或生产摘要确认。 |
+| `prepare` 阶段 `GATE_FAILED` | 修复 snapshot gate 或冻结公开制品，再生成一份新 plan；失败 plan 不得批准。 |
+| `verify` 阶段 `GATE_FAILED` | 若是消费者环境失败，修复环境后从同一 `PUBLISHED` run 重跑 verify；若是已发布制品缺陷，发布新的补丁版本，不覆盖旧制品。 |
 | `PARTIAL` | 不重跑整套发布、不删除远端；审阅返回的 `runPath` 并运行 `reconcile`（见上文）。 |
 | `PUBLISHED` | 运行 `verify --plan <planPath> --run <publishRunPath>`；此时还不是终态。 |
 | `VERIFIED` | 远端状态、精确 npm 安装和插件消费者安装都与冻结计划一致。 |
@@ -449,14 +707,15 @@ hook 可能自行产生文件系统或网络副作用。`publish` 是唯一生
 ## Skills
 
 - `release-help`：环境检查和下一步引导。
+- `release-setup`：首次接入的只读发现、人工校准和 create-once 配置创建。
 - `release-assess`：只读发布就绪度报告。
 - `release-prepare`：本地快照和可审阅发布计划。
 - `release-publish`：经批准、摘要确认的冻结 GitHub+npm 发布。
 - `release-reconcile`：基于证据恢复 PARTIAL；冲突时人工介入。
 - `release-verify`：发布后验证；只有 `VERIFIED` 才是 happy end。
 
-冲突默认仍由人工介入。v0.1.1 发布前使用上面的源码 CLI；registry 验证通过后，
-受支持的用户入口是 npm 安装的 `release-skill` CLI。
+冲突默认仍由人工介入。v0.1.1 生产发布后，受支持的用户入口是 npm 安装的
+`release-skill` CLI；源码 checkout 保留为开发/贡献者路径。
 
 ## 许可证
 

package/adapters/claude/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.1",
+      "version": "0.1.3",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification"
     }
   ]

package/adapters/claude/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"

package/adapters/claude/skills/release-help/SKILL.md

@@ -12,21 +12,21 @@ 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` 识别项目拓扑
+4. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
 5. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才路由到 `release-publish`
 
 ## 确定性脚本调用
@@ -34,11 +34,13 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ```bash
 # 已确认 registry 存在当前版本后，从 npm 全局安装（推荐）
 release-skill help --json  # PATH 全局安装
+release-skill setup --root <path> --json  # 首次接入，只读发现
 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" setup --root <path> --json
 node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" assess --root <path> --offline --json
 ```
 
@@ -51,7 +53,8 @@ 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` 使用源码路径 |
+| CLI 入口不存在 | 安装 `npm install -g release-skill`；无法使用 npm 时设置 `RELEASE_SKILL_HOME` 使用源码路径 |
+| 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
 | assess 失败 | 运行 `node "$RELEASE_SKILL_HOME/..." assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |