release-skill 0.1.1 → 0.1.4

package/README.zh-CN.md

@@ -1,7 +1,8 @@
 # release-skill
 
-[English](README.md)
+[English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
+<!-- release-skill:release-version: 0.1.4 -->
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终
@@ -9,23 +10,24 @@ 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.4 是当前发布版本。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 里程碑起已完成真实生产验证；v0.1.4 是当前发布版本。**
+> 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 -->
@@ -49,6 +51,11 @@ release-skill 不重新生成、也不回写项目源文件。`prepare` 从当
 - 远端 branch、tag、Release 或 npm 版本冲突时交给人工；系统不 force、不覆盖。
 - 只有 `publicFiles` 明确列出的文件会被复制；需要发布的翻译 README、图片、
   演示文件和链接文档都要显式加入配置。
+- 发布只冻结当前真相：`prepare` 不会刷新或重写人工文档。维护者必须先更新
+  README、INSTALL 与 CHANGELOG（包括必须与 `package.json` 版本一致的机器可读
+  `release-skill:release-version` 标记，以及当前包版本的正式 CHANGELOG 标题），
+  再 prepare、审阅和批准。任一文档版本标记或 CHANGELOG 当前版本条目漂移时，
+  发布前门禁失败关闭。
 
 保护规则只有一句话：**复制当前事实，冻结已审阅事实，不重写人工事实。**
 
@@ -60,11 +67,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 +85,7 @@ npx release-skill help
 release-skill help
 ```
 
-**开发安装（从源码 checkout）：**
+**开发安装（贡献者回退，从源码 checkout）：**
 
 设置源码路径并安装依赖：
 
@@ -94,8 +97,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 +104,184 @@ npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
 !.release-skill/project.yaml
 ```
 
-然后创建配置；npm 的可见性必须显式选择，不能依赖工具猜测：
+### 首次接入：不加载完整报告的确定性流程
+
+setup 默认只读。可能很大的完整报告只写入临时文件；用户和 Agent 只查看确定性的
+`compactSummary`（紧凑摘要）审阅视图。紧凑摘要不能替代授权：`setupDigest` 仍绑定
+完整事实、候选和 answers。
+
+```bash
+PROJECT=/absolute/path/to/my-project
+SETUP_SESSION="$(mktemp -d "${TMPDIR:-/tmp}/release-setup.XXXXXX")"
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+printf 'SETUP_SESSION=%s\nPROJECT=%s\n' "$SETUP_SESSION" "$PROJECT"
+
+release-skill setup --root "$PROJECT" --json > "$REPORT" || test "$?" -eq 2
+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"
+```
+
+`NEEDS_INPUT` 和 `LOCAL_ONLY_DETECTED` 按设计返回退出码 2。若
+`proposalConflicts` 非空，包括 `PUBLIC_REPO_AUTHORITY_CONFLICT` 或公开文件映射冲突，
+必须停止自动路径，由人工修正冲突的仓库或映射权威事实后重新运行 setup，不得猜测选边。
+
+没有冲突时，只能机械提取机器提案；Agent 不得重写或逐项抄写：
+
+```bash
+SETUP_SESSION='/上一步打印的会话目录绝对路径'
+PROJECT='/上一步打印的项目绝对路径'
+REPORT="$SETUP_SESSION/discovery.json"
+ANSWERS="$SETUP_SESSION/answers.json"
+BOUND_REPORT="$SETUP_SESSION/bound.json"
+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"
+
+release-skill 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"
+```
+
+只审阅这份绑定摘要和精确摘要值，并由用户确认一次。确认后使用其字面量首次创建配置：
+
+```bash
+SETUP_SESSION=<上一步打印的会话目录绝对路径>
+PROJECT=<上一步打印的项目绝对路径>
+ANSWERS="$SETUP_SESSION/answers.json"
+CREATED_REPORT="$SETUP_SESSION/created.json"
+POST_REPORT="$SETUP_SESSION/post-setup.json"
+ASSESS_REPORT="$SETUP_SESSION/assess.json"
+release-skill setup --root "$PROJECT" --answers "$ANSWERS" \
+  --write --confirm-setup <已确认的 setupDigest> --json > "$CREATED_REPORT"
+release-skill setup --root "$PROJECT" --json > "$POST_REPORT"
+set +e
+release-skill 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"||!["ASSESSED","NEEDS_INPUT","BLOCKED"].includes(a.status)){process.exit(2)}process.stdout.write(JSON.stringify({created:c.status,postSetup:p.status,assessment:{status:a.status,summary:a.summary,gapCount:(a.gaps??[]).length,blockingCodes:(a.gaps??[]).filter(g=>g.severity==="error").map(g=>g.code)}},null,2)+"\n")' "$CREATED_REPORT" "$POST_REPORT" "$ASSESS_REPORT"
+node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})' "$SETUP_SESSION"
+```
+
+写入必须返回 `CONFIG_CREATED`，下一次 setup 必须返回 `ALREADY_CONFIGURED`。已有配置
+永不重新生成，后续只做经审阅的增量编辑。解释器/包管理器间接脚本会以
+`SIDE_EFFECTS_UNPROVEN` 排除，不会自动选择；项目特有 hook/gate 只有人工审阅后才
+增量加入：hook 编辑 `projectConfig.hooks`；gate 编辑 `verificationGates` 并将同一 id
+加入 `selectedGateIds`，随后重新运行绑定 dry-run。人工文件保持 `mode: preserve`；只有显式跨单元共享源才使用
+`sourceScope: workspace`。
+
+#### 进阶 schema 参考——不是首次接入主路径
+
+下面只说明 schema 形状。正常 setup 不应手写，而应按上文机械提取
+`recommendedAnswers`。
+
+```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 参考，不是接入模板。正常 setup 必须使用机器提案；只有确认不存在任何
+历史公开版本时才可使用 `mode: none`。
+
+下面的参考只说明人工审阅过的 gate 与 `selectedGateIds` 的精确对应关系。需要时仅对
+已提取的机器提案做这一处增量编辑：
+
+```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 +329,7 @@ releaseUnits:
         #   status: READY
     production:
       branchTemplate: release/{tag}
+      branchStrategy: create-release-branch
       releaseTitleTemplate: "{unit} {version}"
       releaseNotes: "人工维护的发布说明"
 ```
@@ -177,6 +356,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 +416,69 @@ 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
+   ```
+   按上文机械提取 `compactSummary` 与 `recommendedAnswers`，只确认一次绑定后的
+   `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 +486,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 +640,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 +668,8 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 - 验证项目配置和发布单元；
 - `assess` 在不修改项目的前提下报告就绪度；
 - 把配置的公开文件复制到隔离快照；
+- 只读发现首次接入候选，经精确 `setupDigest` 确认后仅首次创建配置；
+- 在冻结快照副本和精确消费者安装根运行经人工选择的项目 gate；
 - 检查必需文件、路径安全、精确字节/权限和明显泄漏；
 - 记录 Git/工作区身份，冻结绑定 digest 的发布计划；
 - 用计划摘要、有效期和显式 action allowlist 绑定人工批准；
@@ -412,6 +678,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 +727,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 +766,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.4",
       "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.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"