release-skill 0.2.1 → 0.2.2

package/.claude-plugin/marketplace.json

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

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/.codebuddy-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"
@@ -19,7 +19,7 @@
     ],
     "defaultPrompt": [
       "Assess this project for release readiness.",
-      "Prepare a release plan for version 0.2.1.",
+      "Prepare a release plan for version 0.2.2.",
       "Help me understand the release workflow."
     ]
   }

package/.kimi-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.2.2 locale=en baseline=sha256:3208d6a99e84307e77201bb42f88030caac232a3bcbf0942e5747e1934c5c658 -->
+## [0.2.2] - 2026-07-26
+
+v0.2.2 closes the CodeBuddy platform distribution loop and adds the external independent marketplace distribution form. CodeBuddy/WorkBuddy joins the publish/reconcile/verify pipeline through a human attestation closed loop isomorphic to kimi: because the codebuddy CLI cannot pin a frozen ref (no ref option; installs track the default branch/latest), the execute phase writes a manual install requirement (never execs the CLI), and observe/verify consume a structured human attestation with read-only install-point validation — missing, expired, mismatched, or path-escaping attestations all fail closed, at the same severity as kimi (post-publish verification cannot be waived). The external marketplace form lets a distribution declare `marketplaceRepo` so prepare freezes the external marketplace HEAD online (codex hard-frozen to a commit sha, claude weak-frozen to its default branch name) with frozen-sha and index-entry integrity checks, and plugin-marketplace gains matching preflight/observe branches under the `external-marketplace-v1` payload contract while the inline/kimi/codebuddy/legacy branches stay byte-for-byte unchanged. Installation docs (en + zh-CN) are unified on the independent marketplace `ifoohoo/artifact-skill-set` primary path. The npm package name (`release-skill`), publishing identity (`publisher: mzdbxqh`), public repository (`ifoohoo/release-skill`), and corporate maintainer remain unchanged.
+
+### Added
+
+- **CodeBuddy platform human attestation closed loop**: CodeBuddy/WorkBuddy joins the release pipeline (`publish`/`reconcile`/`verify`) via a human attestation closed loop isomorphic to kimi. The codebuddy CLI's marketplace add/install cannot pin a frozen ref (no ref option; installs track the default branch/`latest`, measured), so the automated install checkpoint cannot guarantee frozen-artifact identity. Execute writes a manual install requirement and never execs the CLI; observe/verify consume a structured human attestation and read-only-validate the install point. Missing, expired, mismatched, or path-escaping attestations all fail closed, at the same severity as kimi (post-publish verification cannot be waived). Two measured install channels: desktop installs through the WorkBuddy desktop unified marketplace `artifact-skill-set` (`installPath` must contain the `/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/<plugin>` tail segment, segment-checked); cli runs the bundled CLI under an isolated `HOME=<authorityDir>/codebuddy-home` (`installPath` must be contained in that isolated home's marketplace plugin root). Attestations carry `installChannel` + `marketplace` fields and are validated per channel. Pipeline routing: platform id `codebuddy`, distributionType `codebuddy-plugin`, actionType `codebuddy-marketplace-install`, Tier 3 (same tier as kimi); the build adapter keeps its historical directory name `workbuddy` (`adapters/workbuddy/`, `.codebuddy-plugin/plugin.json` manifest, bytes unchanged).
+- **External independent marketplace distribution form**: a distribution declaring `marketplaceRepo` enables the external form. The prepare production loop freezes the external marketplace HEAD online via `git ls-remote --symref` (codex hard-frozen to a commit sha, claude weak-frozen to its default branch name) and validates the external index entry via `gh api` (name match, exactly one entry, `entry.version == target version` for the claude form); declaring the external form while offline fails closed, and the external repository is strictly read-only. Frozen actions carry `repo=marketplaceRepo`, `ref=add-ref`, `marketplaceCommitSha`, `marketplaceLocation=external`, `payloadContract=external-marketplace-v1`; `snapshotPath`/`manifestDigest` still bind this unit's frozen snapshot (payload authority unchanged). Plan integrity gains an external branch (repo match, `marketplaceLocation`, 40-hex `marketplaceCommitSha`, ref structure safety); kimi/codebuddy with `marketplaceRepo` fail closed. `plugin-marketplace` gains external preflight/observe branches: `external-marketplace-v1` uses the same whole-tree containment semantics as `declared-manifest-v1` (authority is `.`, host-added paths recorded as `extraInstalledPaths` rather than failing); preflight skips the in-snapshot marketplace segment and reads the plugin manifest from the snapshot root, validating name/version and the frozen fields; observe reuses the existing strategy for install-side entry comparison (weak-frozen claude version drift fails closed). Inline/kimi/codebuddy/legacy/`declared-manifest-v1` branches are byte-for-byte unchanged.
+
+### Changed
+
+- **Installation docs unified on the marketplace primary path (en + zh-CN)**: README and INSTALL (all four documents) now route plugin installation through the independent marketplace `ifoohoo/artifact-skill-set` as the primary path, and the READMEs add a workflow overview and platform distribution description. Standards and public references (`standards/06-adapter-contract.md`, `references/06-adapter-contract.md`) are synchronized to the codebuddy attestation form and the external marketplace form with its ordering constraints.
+
+### Fixed
+
+- **CodeBuddy plugin manifest `skills` field is now an array**: the `.codebuddy-plugin/plugin.json` manifest's `skills` field is emitted as an array, matching the CodeBuddy host's expected shape.
+- **`verificationGate` scope distribution enum includes `codebuddy-plugin`**: `release-project.schema.json` adds `codebuddy-plugin` to the `verificationGate.scope.distribution` enum (mirroring the existing `kimi-plugin` rule), keeping the schema and the runtime gate whitelist consistent; the embedded schema copies in all four adapters are rebuilt to match.
+<!-- release-skill:changelog:end version=0.2.2 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.2.1 locale=en baseline=sha256:7d616df824b1d28f9939ef181d6a5d5928d3e0f0455974bebb356c742992ac81 -->
 ## [0.2.1] - 2026-07-25
 

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.2.2 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -35,6 +35,80 @@ release-skill help
 
 You should see the version number and the list of available commands.
 
+## Install as a plugin (unified marketplace — recommended)
+
+All four supported plugin hosts install release-skill from the unified
+marketplace [ifoohoo/artifact-skill-set](https://github.com/ifoohoo/artifact-skill-set),
+which publishes the Claude Code, CodeBuddy/WorkBuddy, Codex, and Kimi Code
+manifests for the same release. Add the marketplace once, then install the
+plugin:
+
+> **External independent marketplace model.** `ifoohoo/artifact-skill-set` is an
+> external independent marketplace: the plugin repository
+> (`ifoohoo/release-skill`) carries only the plugin manifest
+> (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`, …), while the
+> marketplace index (`marketplace.json`) is centralized in the external
+> marketplace repository. When a release unit's plugin distribution declares
+> `marketplaceRepo`, `prepare --online --production` freezes the external
+> marketplace HEAD — Codex pins the commit sha (strong freeze), Claude pins the
+> default branch name (weak freeze) — and verifies the installed payload against
+> the unit's own frozen snapshot whole-tree (contract `external-marketplace-v1`).
+>
+> **Release ordering (marketplace before plugin).** Because the install targets
+> the external marketplace, the marketplace index must be versioned and published
+> **first** — its `release-skill` entry version must equal the target release
+> version (the Claude form verifies this entry) — before
+> `prepare --online --production` can freeze a marketplace sha that contains that
+> entry. See `references/06-adapter-contract.md` §2.3/§2.4.
+
+**Claude Code** (interactive session):
+
+```
+/plugin marketplace add ifoohoo/artifact-skill-set
+/plugin install release-skill@artifact-skill-set
+```
+
+**CodeBuddy / WorkBuddy:**
+
+```bash
+codebuddy plugin marketplace add ifoohoo/artifact-skill-set
+codebuddy plugin install release-skill@artifact-skill-set
+```
+
+WorkBuddy desktop installs only through a registered marketplace: after the
+`marketplace add` above, install `release-skill` from the plugin panel.
+
+**OpenAI Codex:**
+
+```bash
+codex plugin marketplace add ifoohoo/artifact-skill-set
+```
+
+Then install `release-skill` from the interactive `/plugins` browser.
+
+**Kimi Code** (interactive session):
+
+```
+/plugins marketplace https://raw.githubusercontent.com/ifoohoo/artifact-skill-set/main/kimi-marketplace.json
+```
+
+Or point `KIMI_CODE_PLUGIN_MARKETPLACE_URL` at the same URL before launching.
+Then install `release-skill` from the `/plugins` panel.
+
+### Alternative: direct repository install (advanced)
+
+The unified marketplace above is the supported primary path. Direct
+installation from the release repository remains available for advanced
+scenarios:
+
+- Claude Code: `/plugin marketplace add ifoohoo/release-skill`, then
+  `/plugin install release-skill@release-skill`.
+- Kimi Code: the version-pinned `/plugins install <release-tag URL>` documented
+  in the [Kimi Code section](#install-as-a-kimi-code-plugin) below.
+- CodeBuddy: single-session use directly from a source checkout via
+  `--plugin-dir <path>/adapters/workbuddy` (see the
+  [CodeBuddy/WorkBuddy section](#install-as-a-codebuddyworkbuddy-plugin)).
+
 ## Install as a Kimi Code plugin
 
 Kimi Code is a supported plugin host alongside Claude Code and Codex. The
@@ -42,6 +116,11 @@ Kimi Code plugin manifest lives at `.kimi-plugin/plugin.json`, mirroring
 `.claude-plugin/plugin.json` and `.codex-plugin/plugin.json`, and the package
 ships `adapters/kimi/` next to `adapters/claude/` and `adapters/codex/`.
 
+For day-to-day installation, prefer the
+[unified marketplace path](#install-as-a-plugin-unified-marketplace--recommended)
+above. The remainder of this section documents the version-pinned manual
+closed loop that release-skill's own publish/verify pipeline relies on.
+
 Kimi Code has an interactive plugin marketplace but **no scriptable,
 non-interactive install API**. release-skill therefore models Kimi installation
 as a version-pinned **manual** install plus trusted observation/attestation:
@@ -68,7 +147,7 @@ as a version-pinned **manual** install plus trusted observation/attestation:
    default branch), confirm the trust prompt, then reload:
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.1
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.2
    /plugins reload
    ```
 
@@ -83,10 +162,10 @@ as a version-pinned **manual** install plus trusted observation/attestation:
 {
   "consumer": "kimi",
   "plugin": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "entrySkill": "release-help",
   "repo": "ifoohoo/release-skill",
-  "ref": "release-skill-v0.2.1",
+  "ref": "release-skill-v0.2.2",
   "installPath": "<kimiCodeHome>/plugins/managed/release-skill",
   "planDigest": "<64-hex frozen plan digest>",
   "payloadDigest": "<64-hex frozen snapshot payload digest>",
@@ -108,23 +187,106 @@ unit never reaches `VERIFIED`.
 
 ## Install as a CodeBuddy/WorkBuddy plugin
 
-The package also ships a generated, self-contained CodeBuddy/WorkBuddy adapter
-at `adapters/workbuddy/`, next to `adapters/claude/`, `adapters/codex/`, and
-`adapters/kimi/`. Its manifest lives at `.codebuddy-plugin/plugin.json` (the
-components — `skills/`, `bin/`, `schemas/`, `native/` — sit at the plugin
-root, per the CodeBuddy plugin reference), and its skills resolve the CLI
-entry via `${CODEBUDDY_PLUGIN_ROOT}`, which CodeBuddy expands inline like
-Claude Code expands `${CLAUDE_PLUGIN_ROOT}`.
-
-CodeBuddy/WorkBuddy installation is a **manual** step today: the automated
-marketplace install checkpoint (`publish`/`verify`) does not cover CodeBuddy
-yet. To use the adapter, point CodeBuddy at the generated plugin directory —
-for a single session run CodeBuddy with `--plugin-dir <path>/adapters/workbuddy`,
-or add the directory as a marketplace source you control
-(`codebuddy plugin marketplace add <source>`) and install from it
-(`codebuddy plugin install release-skill@<marketplace>`, or the interactive
-`/plugin` manager). The installed copy lands in CodeBuddy's versioned plugin
-cache; the adapter never references files outside its own directory.
+CodeBuddy (desktop product WorkBuddy) is a supported plugin host alongside
+Claude Code, Codex, and Kimi Code. The package ships a generated, self-contained
+CodeBuddy/WorkBuddy adapter at `adapters/workbuddy/`, next to `adapters/claude/`,
+`adapters/codex/`, and `adapters/kimi/`. Its manifest lives at
+`.codebuddy-plugin/plugin.json` (the components — `skills/`, `bin/`, `schemas/`,
+`native/` — sit at the plugin root, per the CodeBuddy plugin reference), and its
+skills resolve the CLI entry via `${CODEBUDDY_PLUGIN_ROOT}`, which CodeBuddy
+expands inline like Claude Code expands `${CLAUDE_PLUGIN_ROOT}`. The build
+adapter directory is named `workbuddy` while the platform / distribution id is
+`codebuddy`; the two names refer to the same target.
+
+For day-to-day installation, prefer the
+[unified marketplace path](#install-as-a-plugin-unified-marketplace--recommended)
+above. The remainder of this section documents the manual attestation closed loop
+that release-skill's own publish/verify pipeline relies on.
+
+The codebuddy CLI can add a marketplace and install a plugin, but **neither
+`plugin marketplace add` nor `plugin install` accepts a ref option** — the install
+tracks the marketplace default branch / latest. An automated install checkpoint
+therefore cannot guarantee the frozen artifact's identity, so release-skill models
+CodeBuddy installation as a **manual** install plus trusted observation/
+attestation (the same capability gap and closed loop as Kimi Code):
+`publish`/`verify` never auto-install CodeBuddy plugins. The closed loop is:
+
+1. `publish` performs the automated writes (Git branch/tag, npm, GitHub
+   Release), then reaches the `codebuddy-marketplace-install` checkpoint. Because
+   the install cannot pin a frozen ref, that checkpoint **fails closed** and the
+   run lands in `PARTIAL` — the successful automated writes are NOT undone. The
+   checkpoint observation (and the requirement file below) names both install
+   channels, the unified marketplace, the isolated CLI home, and the attestation
+   path.
+2. Read the requirement at
+   `<root>/.release-skill/codebuddy-attestations/<planDigest>/<plugin>/release-skill-codebuddy-manual-install.json`.
+3. Install release-skill from the unified marketplace `artifact-skill-set`
+   (https://github.com/ifoohoo/artifact-skill-set) through ONE of two channels:
+
+   **Primary path (WorkBuddy desktop):** install release-skill from the plugin
+   panel, then confirm `~/.workbuddy/settings.json` `enabledPlugins` contains
+   `"release-skill@artifact-skill-set": true`. The plugin lands at
+   `~/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill/`.
+
+   **Alternate path (bundled codebuddy CLI, isolatable):** run the CLI with the
+   **isolated** home from the requirement so the clone lands inside it (do not use
+   your ordinary `~/.codebuddy`):
+
+   ```
+   HOME="<codebuddyHome>" <codebuddy binary> plugin marketplace add https://github.com/ifoohoo/artifact-skill-set
+   HOME="<codebuddyHome>" <codebuddy binary> plugin install release-skill@artifact-skill-set
+   ```
+
+   The CLI ships with WorkBuddy.app (macOS known path
+   `/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`).
+   The plugin lands at
+   `<codebuddyHome>/.codebuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill/`.
+4. **Ref limitation warning:** a codebuddy install tracks the marketplace default
+   branch and CANNOT be pinned to the frozen ref. Before writing the attestation
+   you MUST confirm the installed plugin manifest version equals the frozen
+   version `0.2.1`; otherwise do NOT issue an attestation.
+5. Write the attestation JSON to
+   `<root>/.release-skill/codebuddy-attestations/<planDigest>/<plugin>/release-skill-codebuddy-attestation.json`.
+   `planDigest` MUST be the frozen **plan** digest; `payloadDigest` MUST be the
+   frozen snapshot **payload** digest; `installChannel` MUST be `"desktop"` or
+   `"cli"`; `marketplace` MUST be `artifact-skill-set`; `installPath` MUST be the
+   actual installed plugin directory for the chosen channel; `attestedAt` must not
+   be in the future and `expiresAt` must be within 24 hours of `attestedAt`.
+   Example:
+
+```json
+{
+  "consumer": "codebuddy",
+  "plugin": "release-skill",
+  "version": "0.2.2",
+  "entrySkill": "release-help",
+  "repo": "ifoohoo/release-skill",
+  "ref": "release-skill-v0.2.2",
+  "marketplace": "artifact-skill-set",
+  "installChannel": "desktop",
+  "installPath": "~/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill",
+  "planDigest": "<64-hex frozen plan digest>",
+  "payloadDigest": "<64-hex frozen snapshot payload digest>",
+  "attestedBy": "<person responsible>",
+  "attestedAt": "2026-07-23T00:00:00.000Z",
+  "expiresAt": "2026-07-23T12:00:00.000Z"
+}
+```
+
+6. Run `release-skill reconcile --run <publish-run>` (promotes `PARTIAL` →
+   `PUBLISHED`) and then `release-skill verify --run <reconcile-run>` (→
+   `VERIFIED`). Both read the attestation from the same plan-digest-keyed
+   directory, so their fresh run directories do not lose the proof.
+
+For the cli channel, installing into the ordinary `~/.codebuddy` is **not**
+acceptable proof: the attested `installPath` must resolve inside the requirement's
+isolated `<codebuddyHome>` managed root, otherwise verification fails closed and
+the CodeBuddy unit never reaches `VERIFIED`. (The desktop channel uses the real
+`~/.workbuddy` marketplace layout above, which IS the well-known proof layout.)
+
+For a single session from a source checkout you can also point CodeBuddy at the
+generated plugin directory with `--plugin-dir <path>/adapters/workbuddy`; the
+adapter never references files outside its own directory.
 
 ## Development Install (Local Checkout)
 

package/INSTALL.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.2.1 -->
+<!-- release-skill:release-version: 0.2.2 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本
@@ -32,6 +32,73 @@ release-skill help
 
 输出中应包含版本号和可用命令列表。
 
+## 安装为插件（统一市场——推荐）
+
+四种受支持的插件宿主都从统一市场
+[ifoohoo/artifact-skill-set](https://github.com/ifoohoo/artifact-skill-set)
+安装 release-skill；该市场为同一发布版本提供 Claude Code、
+CodeBuddy/WorkBuddy、Codex 与 Kimi Code 四份清单。先添加一次市场，再安装
+插件：
+
+> **外部独立市场形态。** `ifoohoo/artifact-skill-set` 是一个外部独立市场：
+> 插件仓库（`ifoohoo/release-skill`）只含 plugin 清单
+>（`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 等），marketplace
+> 索引（`marketplace.json`）则集中于外部市场仓库。当发布单元的插件 distribution
+> 声明 `marketplaceRepo` 时，`prepare --online --production` 会冻结外部市场
+> HEAD——Codex 钉 commit sha（强冻结）、Claude 钉默认分支名（弱冻结）——并以
+> 本单元自身冻结快照整树校验安装载荷（契约 `external-marketplace-v1`）。
+>
+> **发布时序（先市场后插件）。** 由于安装目标是外部市场，marketplace 索引必须
+> **先**定版并发布——其 `release-skill` 条目版本须等于目标发布版本（claude 形态
+> 会校验该条目）——之后 `prepare --online --production` 才能冻结到含该条目的市场
+> sha。详见 `references/06-adapter-contract.md` §2.3/§2.4。
+
+**Claude Code**（交互会话中）：
+
+```
+/plugin marketplace add ifoohoo/artifact-skill-set
+/plugin install release-skill@artifact-skill-set
+```
+
+**CodeBuddy / WorkBuddy：**
+
+```bash
+codebuddy plugin marketplace add ifoohoo/artifact-skill-set
+codebuddy plugin install release-skill@artifact-skill-set
+```
+
+WorkBuddy 桌面端只能通过已注册的市场安装：执行上面的 `marketplace add`
+之后，在插件面板中安装 `release-skill`。
+
+**OpenAI Codex：**
+
+```bash
+codex plugin marketplace add ifoohoo/artifact-skill-set
+```
+
+然后在交互式 `/plugins` 浏览器中安装 `release-skill`。
+
+**Kimi Code**（交互会话中）：
+
+```
+/plugins marketplace https://raw.githubusercontent.com/ifoohoo/artifact-skill-set/main/kimi-marketplace.json
+```
+
+或在启动前把 `KIMI_CODE_PLUGIN_MARKETPLACE_URL` 指向同一 URL。然后在
+`/plugins` 面板中安装 `release-skill`。
+
+### 备选：直接从仓库安装（进阶）
+
+上面的统一市场是受支持的主路径。直接从发布仓库安装仍可用于进阶场景：
+
+- Claude Code：`/plugin marketplace add ifoohoo/release-skill`，然后
+  `/plugin install release-skill@release-skill`。
+- Kimi Code：下文 [Kimi Code 小节](#安装为-kimi-code-插件)中版本钉死的
+  `/plugins install <release-tag URL>`。
+- CodeBuddy：源码检出后通过 `--plugin-dir <path>/adapters/workbuddy`
+  单会话使用（见
+  [CodeBuddy/WorkBuddy 小节](#安装为-codebuddyworkbuddy-插件)）。
+
 ## 安装为 Kimi Code 插件
 
 Kimi Code 是与 Claude Code 和 Codex 并列的受支持插件宿主。Kimi Code 插件
@@ -39,6 +106,10 @@ Kimi Code 是与 Claude Code 和 Codex 并列的受支持插件宿主。Kimi Cod
 `.codex-plugin/plugin.json` 对应；包内同时提供 `adapters/kimi/`，与
 `adapters/claude/`、`adapters/codex/` 并列。
 
+日常安装请优先使用上文的
+[统一市场路径](#安装为插件统一市场推荐)。本节其余部分记录的是
+release-skill 自身 publish/verify 流水线所依赖的“版本钉死手动闭环”。
+
 Kimi Code 有交互式插件市场，但**没有可脚本化的非交互安装接口**。因此
 release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观测/人工证明”：
 `publish`/`verify` 从不对 Kimi 执行自动安装。完整闭环如下：
@@ -62,7 +133,7 @@ release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观
    它会安装最新 release 或默认分支），确认信任提示后重新加载：
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.1
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.2
    /plugins reload
    ```
 
@@ -76,10 +147,10 @@ release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观
 {
   "consumer": "kimi",
   "plugin": "release-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "entrySkill": "release-help",
   "repo": "ifoohoo/release-skill",
-  "ref": "release-skill-v0.2.1",
+  "ref": "release-skill-v0.2.2",
   "installPath": "<kimiCodeHome>/plugins/managed/release-skill",
   "planDigest": "<64 位十六进制冻结计划摘要>",
   "payloadDigest": "<64 位十六进制冻结快照载荷摘要>",
@@ -100,21 +171,94 @@ release-skill 把 Kimi 安装建模为“版本钉死的手动安装 + 可信观
 
 ## 安装为 CodeBuddy/WorkBuddy 插件
 
-本包还随 `adapters/claude/`、`adapters/codex/`、`adapters/kimi/` 一并提供生成的
-自包含 CodeBuddy/WorkBuddy 适配器 `adapters/workbuddy/`。其清单位于
+CodeBuddy（桌面端产品 WorkBuddy）是与 Claude Code、Codex、Kimi Code 并列的受支持
+插件宿主。本包随 `adapters/claude/`、`adapters/codex/`、`adapters/kimi/` 一并提供
+生成的自包含 CodeBuddy/WorkBuddy 适配器 `adapters/workbuddy/`。其清单位于
 `.codebuddy-plugin/plugin.json`（组件——`skills/`、`bin/`、`schemas/`、
 `native/`——按 CodeBuddy 插件规范位于插件根目录），技能通过
 `${CODEBUDDY_PLUGIN_ROOT}` 解析 CLI 入口；CodeBuddy 会像 Claude Code 展开
-`${CLAUDE_PLUGIN_ROOT}` 一样内联展开该变量。
-
-CodeBuddy/WorkBuddy 安装目前是**手动**步骤：自动化 marketplace 安装检查点
-（`publish`/`verify`）尚未覆盖 CodeBuddy。使用该适配器时，把 CodeBuddy 指向
-生成的插件目录——单会话可用 `--plugin-dir <path>/adapters/workbuddy` 启动
-CodeBuddy；或把该目录作为你控制的 marketplace 源
-（`codebuddy plugin marketplace add <source>`）再从中安装
-（`codebuddy plugin install release-skill@<marketplace>`，或交互式 `/plugin`
-管理器）。安装后的副本落在 CodeBuddy 的版本化插件缓存中；适配器不引用自身
-目录之外的任何文件。
+`${CLAUDE_PLUGIN_ROOT}` 一样内联展开该变量。build adapter 目录名为 `workbuddy`，
+而平台 / 分发 id 为 `codebuddy`，两个名字指向同一目标。
+
+日常安装请优先使用上文的
+[统一市场路径](#安装为插件统一市场推荐)。本节其余部分记录的是
+release-skill 自身 publish/verify 流水线所依赖的“手动安装 + 可信证明闭环”。
+
+codebuddy CLI 可以添加市场并安装插件，但 **`plugin marketplace add` 与
+`plugin install` 均无 ref 选项**——安装会跟踪市场默认分支 / latest。因此自动化
+安装检查点无法保证冻结产物的同一性，release-skill 把 CodeBuddy 安装建模为
+“**手动**安装 + 可信观测/人工证明”（与 Kimi Code 相同的能力缺口与闭环）：
+`publish`/`verify` 从不对 CodeBuddy 执行自动安装。完整闭环如下：
+
+1. `publish` 先完成自动化写入（Git branch/tag、npm、GitHub Release），随后
+   到达 `codebuddy-marketplace-install` 检查点。由于安装无法钉死冻结 ref，该
+   检查点**失败关闭**，整个 run 落入 `PARTIAL`——已成功的自动化写入**不会**被撤销。
+   检查点输出（以及下面的 requirement 文件）会给出两个安装通道、统一市场、
+   隔离的 CLI home 与证明写入路径。
+2. 读取 requirement：
+   `<root>/.release-skill/codebuddy-attestations/<planDigest>/<plugin>/release-skill-codebuddy-manual-install.json`。
+3. 经**两个通道之一**从统一市场 `artifact-skill-set`
+   （https://github.com/ifoohoo/artifact-skill-set）安装 release-skill：
+
+   **主路径（WorkBuddy 桌面端）：** 从插件面板安装 release-skill，然后确认
+   `~/.workbuddy/settings.json` 的 `enabledPlugins` 含
+   `"release-skill@artifact-skill-set": true`。插件落点为
+   `~/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill/`。
+
+   **备选路径（捆绑的 codebuddy CLI，可隔离）：** 用 requirement 给出的**隔离**
+   home 运行 CLI，使克隆落在其中（不要使用你日常的 `~/.codebuddy`）：
+
+   ```
+   HOME="<codebuddyHome>" <codebuddy 二进制> plugin marketplace add https://github.com/ifoohoo/artifact-skill-set
+   HOME="<codebuddyHome>" <codebuddy 二进制> plugin install release-skill@artifact-skill-set
+   ```
+
+   CLI 随 WorkBuddy.app 捆绑（macOS 已知路径
+   `/Applications/WorkBuddy.app/Contents/Resources/app.asar.unpacked/cli/bin/codebuddy`）。
+   插件落点为
+   `<codebuddyHome>/.codebuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill/`。
+4. **ref 限制警告：** codebuddy 安装跟踪市场默认分支，**无法**钉死到冻结 ref。
+   写出证明之前，必须核实已安装插件清单版本等于冻结版本 `0.2.1`；否则**不得**
+   出具证明。
+5. 把证明 JSON 写入
+   `<root>/.release-skill/codebuddy-attestations/<planDigest>/<plugin>/release-skill-codebuddy-attestation.json`。
+   `planDigest` 必须是冻结**计划**摘要；`payloadDigest` 必须是冻结快照**载荷**
+   摘要；`installChannel` 必须是 `"desktop"` 或 `"cli"`；`marketplace` 必须是
+   `artifact-skill-set`；`installPath` 必须是所选通道的实际安装目录；
+   `attestedAt` 不得为未来时间，`expiresAt` 必须在 `attestedAt` 之后 24 小时内。
+   示例：
+
+```json
+{
+  "consumer": "codebuddy",
+  "plugin": "release-skill",
+  "version": "0.2.2",
+  "entrySkill": "release-help",
+  "repo": "ifoohoo/release-skill",
+  "ref": "release-skill-v0.2.2",
+  "marketplace": "artifact-skill-set",
+  "installChannel": "desktop",
+  "installPath": "~/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill",
+  "planDigest": "<64 位十六进制冻结计划摘要>",
+  "payloadDigest": "<64 位十六进制冻结快照载荷摘要>",
+  "attestedBy": "<责任人>",
+  "attestedAt": "2026-07-23T00:00:00.000Z",
+  "expiresAt": "2026-07-23T12:00:00.000Z"
+}
+```
+
+6. 运行 `release-skill reconcile --run <publish-run>`（把 `PARTIAL` 提升为
+   `PUBLISHED`），再运行 `release-skill verify --run <reconcile-run>`（→
+   `VERIFIED`）。两者都从同一个按计划摘要命名的目录读取证明，因此它们各自的
+   新 run 目录不会丢失该证明。
+
+对 cli 通道而言，把插件安装到日常的 `~/.codebuddy` **不**构成有效证明：证明中的
+`installPath` 必须解析到 requirement 给出的隔离 `<codebuddyHome>` managed 根之内，
+否则验证失败关闭，CodeBuddy 单元绝不进入 `VERIFIED`。（desktop 通道使用上文真实的
+`~/.workbuddy` 市场布局，那本身就是公认的有效证明布局。）
+
+源码检出后也可以用 `--plugin-dir <path>/adapters/workbuddy` 把 CodeBuddy 指向
+生成的插件目录做单会话使用；适配器不引用自身目录之外的任何文件。
 
 ## 开发安装（本地源码）