release-skill 0.1.3 → 0.1.4

package/README.zh-CN.md

@@ -2,6 +2,7 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
+<!-- release-skill:release-version: 0.1.4 -->
 面向 Claude Code 和 Codex 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终
@@ -9,17 +10,20 @@ release-skill 帮助维护者回答三个问题：准备发布什么、还有哪
 最后一步重新生成 README、重新打包活动工作区或覆盖人工内容。
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** 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` 全局预检执行。
+> **当前边界：** 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 安装的 CLI 是受支持的用户入口；
-> 源码 checkout 保留为开发/贡献者路径。
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.1.4 是当前发布版本。**
+> npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
 > - npm 安装：`npm install -g release-skill` → `release-skill help`
@@ -47,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 当前版本条目漂移时，
+  发布前门禁失败关闭。
 
 保护规则只有一句话：**复制当前事实，冻结已审阅事实，不重写人工事实。**
 
@@ -95,24 +104,75 @@ npm exec --yes pnpm@10.17.1 -- install --frozen-lockfile
 !.release-skill/project.yaml
 ```
 
-### 首次接入：先发现，再由人工定稿
+### 首次接入：不加载完整报告的确定性流程
 
-项目尚无配置时，先运行只读 setup。它会扫描包、插件清单、Git remote、旧版
-`public-release.json` 和质量脚本，列出发布单元、tag、分支、前序公开基线及验证
-gate 候选，但不会读取 README 正文作为指令，也不会自动选择或执行脚本：
+setup 默认只读。可能很大的完整报告只写入临时文件；用户和 Agent 只查看确定性的
+`compactSummary`（紧凑摘要）审阅视图。紧凑摘要不能替代授权：`setupDigest` 仍绑定
+完整事实、候选和 answers。
 
 ```bash
-release-skill setup --root /absolute/path/to/my-project --json
+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"
 ```
 
-`NEEDS_INPUT` 和 `LOCAL_ONLY_DETECTED` 会按设计返回退出码 2：它们表示仍需人工决策，
-不是内部崩溃。自动化应读取 JSON 的 `status`，不要把 setup 的所有非零退出码都当作
-工具故障。
+只审阅这份绑定摘要和精确摘要值，并由用户确认一次。确认后使用其字面量首次创建配置：
+
+```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 参考——不是首次接入主路径
 
-审阅候选后，人工创建 answers JSON，其中 `projectConfig` 是完整配置，
-`selectedGateIds` 与其中 `verificationGates[].id` 必须精确一致；不需要个性化 gate
-时显式使用空数组。带 answers 再 dry-run 一次，确认它绑定的新 `setupDigest`，最后
-才允许首次创建配置：
+下面只说明 schema 形状。正常 setup 不应手写，而应按上文机械提取
+`recommendedAnswers`。
 
 ```json
 {
@@ -150,13 +210,11 @@ release-skill setup --root /absolute/path/to/my-project --json
 }
 ```
 
-这是完整的 schema 形状，不是项目事实的权威答案。仓库、渠道、基线与公开文件
-都必须替换为本项目经审阅的事实；只有确认不存在任何历史公开版本时才可使用
-`mode: none`。
+这是 schema 参考，不是接入模板。正常 setup 必须使用机器提案；只有确认不存在任何
+历史公开版本时才可使用 `mode: none`。
 
-如果要选择一个 dry-run 已报告的 gate，保留同一份完整 `projectConfig`，在其中增加
-顶层 `verificationGates`，并让外层 `selectedGateIds` 完全一致。例如 dry-run 已
-报告 `my-project-script-test` 时：
+下面的参考只说明人工审阅过的 gate 与 `selectedGateIds` 的精确对应关系。需要时仅对
+已提取的机器提案做这一处增量编辑：
 
 ```json
 {
@@ -381,7 +439,8 @@ v0.1.1 生产发布验证完成后，npm 安装的 CLI 是受支持的用户入
    ```bash
    "${CLI[@]}" setup --root "$PROJECT" --json
    ```
-   按上文完成 answers 和精确 `setupDigest` 确认；配置已存在时跳过。
+   按上文机械提取 `compactSummary` 与 `recommendedAnswers`，只确认一次绑定后的
+   `setupDigest`；配置已存在时跳过。
 3. **就绪评估（只读）：**
    ```bash
    "${CLI[@]}" assess --root "$PROJECT" --offline --json

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

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.1.3",
+      "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.3",
+  "version": "0.1.4",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "release-skill contributors"