release-skill 0.2.0 → 0.2.2

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.2.0 -->
+<!-- release-skill:release-version: 0.2.2 -->
 Release preparation for Claude Code, Codex, and Kimi Code, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -11,25 +11,27 @@ reviewed artifacts first and publishes those same artifacts later; it does not
 regenerate a README or re-pack the live workspace at the last step.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.0** (2026-07-25)
+**0.2.2** (2026-07-26)
 
-v0.2.0 is a hardening release that improves publish reliability, digest reproducibility, version management, and platform registry data-driven architecture. Nine hardening tasks are completed: observe retry backoff, digest decoupling with planVersion 2, declared-manifest payload contract, single-source versioning, real CLI contract tests, incremental hook caching, tiered parallel checkpoint execution, observe-before-execute idempotent skip, and platform registry data-driven architecture. The npm package name (`release-skill`), publishing identity (`publisher: mzdbxqh`), public repository (`ifoohoo/release-skill`), and corporate maintainer remain unchanged.
+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**
 
-- **Observe retry backoff (`observeWithRetry`)**: post-execute observe in publish/reconcile now uses bounded exponential backoff for transient failures. Transient classification is propagating — retries only on transient errors (network timeouts, 5xx); CONFLICTING errors are never retried. Marketplace retry window is clamped to action `timeoutMs`. This resolves intermittent PARTIAL failures caused by transient observe timeouts on real networks.
-- **Digest decoupling with planVersion 2**: plan fields split into binding layer (frozen artifacts, actions, versions, config) vs record layer (baseline, createdAt, status). Frozen commit timestamp derived from `headCommit` for reproducible digests. Approval no longer invalidated by tree/workspace digest drift (v2 plans); baseline check demoted to evidence warning. v1 legacy behavior preserved byte-for-byte (golden-value tested).
-- **Declared-manifest payload contract for marketplace installs**: replace whole-tree byte equality with declared-manifest comparison. Authority entries must exist and match byte-for-byte in the install dir; host-added files are recorded (`extraInstalledPaths`, capped) instead of failing. Legacy plans without `payloadContract` keep exact whole-tree semantics. `consumerTransportExclusions` deprecated (legacy path only).
-- **Single-source versioning with `sync-version` script**: `package.json` version is now the sole handwritten source. New `sync-version.mjs` propagates it to plugin manifests, marketplace.json, README boundary lines, and INSTALL docs (idempotent, `--check` mode, defensive whitelist). `smokeExpectedJson.version` is injected at runtime from `targetVersion`, ending the bump-invalidates-plan loop. docs hook now runs `check-docs-drift.mjs` (render check + sync-version check). Hardcoded version literals in tests replaced with dynamic reads.
-- **Real CLI contract tests for claude/codex/kimi adapters**: isolated-HOME contract tests asserting adapter assumptions against real CLI protocol shapes (`list --json` output forms, subcommand existence), gated by `RELEASE_SKILL_LIVE_CLI=1` with skip-not-fail semantics. Static contract locks in 'kimi has no scriptable install' to prevent fabricated CLI commands from regressing silently.
-- **Incremental hook caching for prepare**: hooks can declare `cacheable`+`cacheInputs`; results cached under `.release-skill/cache/hooks/<name>/<key>.json` keyed by hook config and input content hashes. Failures never cached; hits skip execution but not authorization gates; `--no-hook-cache` escape hatch. Cache dir registered in baseline control-plane exclusions and gitignore. test/typecheck hooks cached in this project: second prepare drops to ~2s with test hook served from cache.
-- **Tiered parallel checkpoint execution for publish**: publish checkpoints grouped into hard-coded `TIER_TABLE` layers. Layers run sequentially, actions within a layer run concurrently with `allSettled` semantics (no fail-fast, successes preserved). State persistence moves to per-layer snapshots keeping the appendRunState hash chain intact; crash recovery verified via SIGKILL-mid-tier integration test. Evidence appends serialized through a mutex chain with sequence starting at 1 and tier info in `details.tier`.
-- **Observe-before-execute idempotent skip**: publish each checkpoint execute now has a single read-only pre-observe. Four-way classification: CONSISTENT→SKIPPED / MISSING→execute / CONFLICTING→FAILED / not observable→execute. Two-layer preflight shares `classifyPreObservation` single source (global Safety Gate 10 arbitration). SKIPPED downstream adaptation: layer folding recognizes success, three `every` checks expanded to SUCCEEDED||SKIPPED, `buildPersistedState` maps skipped, TOCTOU as usual.
-- **Platform registry data-driven architecture**: new `src/platforms/registry.mjs` with `PLATFORMS`/`getPlatform`/`assertRegistry` module self-validation. Three platforms complete description (§3.4 matrix full dimensions) + pure strategy functions. Golden tests 12 cases solidify three platforms execute/observe/list current behavior. `src/producers/build-adapters.mjs` PLATFORMS now derived from registry; `scripts/build-adapters.mjs` duplicate platform table removed for single-source. `build:adapters:check` byte-zero diff (zero behavior change strong evidence).
+- **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:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** v0.2.0 is the current release (v0.1.9 previously held
+> **Current boundary:** v0.2.2 is the current release (v0.1.9 previously held
 > published status before the codex migrated-command-skills fix was added).
 > v0.1.1 completed a real production release to GitHub and npm — the first
 > production-verified milestone — followed by
@@ -63,6 +65,45 @@ v0.2.0 is a hardening release that improves publish reliability, digest reproduc
 > specifically requires `prepare --online --production`. Without digest confirmation,
 > no remote preflight or write starts.
 
+## Release workflow overview
+
+release-skill models the release lifecycle as a strict state machine so that every
+stage has explicit entry and exit conditions and no stage can be skipped. The
+normative definition lives in `references/01-state-machine.md`.
+
+```text
+DISCOVERED -> ASSESSED -> PREPARED -> APPROVED -> PUBLISHING -> PUBLISHED -> VERIFIED
+                                   exception states: NEEDS_INPUT / BLOCKED / PARTIAL
+```
+
+Each CLI command maps to one transition:
+
+- `help` checks the environment; `setup` discovers the project and, after digest
+  confirmation, creates the config once.
+- `assess` performs a read-only readiness evaluation (`DISCOVERED -> ASSESSED`).
+- `prepare` runs the verification gates, freezes an immutable release plan, and
+  copies the configured public files into an isolated snapshot
+  (`ASSESSED -> PREPARED`). It writes only under `.release-skill/` and never
+  touches remote services.
+- `approve` records human approval bound to the plan digest with a 24-hour expiry
+  (`PREPARED -> APPROVED`). A changed plan invalidates the approval automatically.
+- `publish` executes the external write checkpoints in order
+  (`APPROVED -> PUBLISHING -> PUBLISHED`).
+- `reconcile` recovers from `PARTIAL`; `verify` performs a fresh consumer-install
+  check in an isolated environment (`PUBLISHED -> VERIFIED`).
+
+`PUBLISHED` is **not** the terminal state. Only a fresh `verify` run that confirms
+remote state and exact consumer installs match the frozen plan reaches `VERIFIED`.
+
+**Publishing checkpoint order.** `publish` runs a read-only global preflight over
+all actions, then executes and observes in this fixed order: public snapshot
+branch -> signed/tracked tag -> npm publish -> GitHub Release -> configured
+Claude/Codex plugin-marketplace install -> run record. Any failure stops subsequent
+checkpoints and the run lands in `PARTIAL`. The system never auto-deletes remote
+tags, unpublishes packages, or restarts from scratch; `reconcile` queries the actual
+remote state, skips already-consistent steps, and retries only safe, incomplete
+actions, while remote conflicts require a human decision.
+
 ## Why this is safe for a hand-edited README
 
 release-skill does not regenerate or rewrite project source files. `prepare` copies
@@ -121,6 +162,29 @@ npx release-skill help
 release-skill help
 ```
 
+**Install as a plugin (Claude Code / CodeBuddy / WorkBuddy / Codex / Kimi Code):**
+
+All four plugin hosts install from the unified marketplace
+`ifoohoo/artifact-skill-set` — for example, in a Claude Code session:
+
+```
+/plugin marketplace add ifoohoo/artifact-skill-set
+/plugin install release-skill@artifact-skill-set
+```
+
+`ifoohoo/artifact-skill-set` is an **external independent marketplace**: the
+plugin repository carries only the plugin manifest, while the marketplace index
+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. **Release
+ordering:** publish the external marketplace index first — its entry version
+must equal the target release version — before `prepare` can freeze a
+marketplace sha containing that entry. See [INSTALL.md](INSTALL.md) for the
+per-platform commands and `references/06-adapter-contract.md` §2.3/§2.4 for the
+contract and the advanced direct-repository options.
+
 **Development install (contributor fallback, from source checkout):**
 
 Set the checkout location and install dependencies:
@@ -899,6 +963,19 @@ Successful reconcile returns `PUBLISHED`, not `VERIFIED`; only the fresh
   Code (no scriptable install API) it emits a version-pinned manual install
   requirement and proves the entry Skill and payload digest only from a trusted
   attestation bound to the frozen plan digest;
+- supports an external independent marketplace for Claude/Codex distributions
+  (`marketplaceRepo`): `prepare --online --production` freezes the external
+  marketplace HEAD (Codex commit sha / Claude default branch name), validates the
+  marketplace index entry at that sha, and verifies the installed payload against
+  the unit's own frozen snapshot whole-tree (`external-marketplace-v1`), while the
+  install-side CLI list observation fails closed on version drift;
+- ships a generated, self-contained CodeBuddy/WorkBuddy adapter
+  (`adapters/workbuddy/`, manifest `.codebuddy-plugin/plugin.json`, skills
+  rendered with `${CODEBUDDY_PLUGIN_ROOT}`) alongside the Claude/Codex/Kimi
+  adapters; because the codebuddy CLI cannot pin a frozen ref there is no
+  automated marketplace install checkpoint, so it emits a manual install
+  requirement and proves the entry Skill and payload digest only from a trusted
+  attestation bound to the frozen plan digest;
 - distinguishes `PUBLISHED` (writes completed) from `VERIFIED` (remote and
   consumer installation evidence completed);
 - stops subsequent checkpoints on failure and writes a separate run record
@@ -984,6 +1061,9 @@ npm publish may never be hooks/gates; they remain controlled plan actions.
 - no overwrite of branches/tags/releases or npm unpublish; create-only refs use
   `--force-with-lease=<ref>:` solely as an atomic compare-and-set assertion that
   the ref is absent, while existing branches use an ordinary non-force push;
+- no automated CodeBuddy/WorkBuddy marketplace install checkpoint — the
+  codebuddy CLI cannot pin a frozen ref, so installation is a manual step proven
+  by the same attestation closed loop as Kimi Code;
 - no promise of Windows or broad multi-platform native write support;
 - no hidden commit, push, tag, release, or package publication.
 
@@ -1034,6 +1114,29 @@ Conflicts still default to human intervention. The npm-installed `release-skill`
 CLI is the supported user entry after v0.1.1 production publication; source
 checkout remains the development/contributor fallback.
 
+## Platform distribution
+
+One deterministic core engine ships to several targets through build-only adapter
+closures. A release unit declares what reaches users via `distributions`; each
+distribution type maps to a concrete artifact:
+
+| `distributions` type | Physical artifact | Install |
+|---|---|---|
+| `npm` | npm package with CLI entry | `npm install -g release-skill` |
+| `claude-plugin` | self-contained closure under `adapters/claude/` | automated marketplace checkpoint |
+| `codex-plugin` | self-contained closure under `adapters/codex/` | automated marketplace checkpoint |
+| `kimi-plugin` | self-contained closure (no scriptable install API) | manual, attestation-bound |
+| `codebuddy-plugin` | generated `adapters/workbuddy/` with `.codebuddy-plugin/plugin.json` (the codebuddy CLI cannot pin a frozen ref) | manual, attestation-bound |
+
+Each adapter closure bundles its own copy of the CLI bundle, skills, and schemas so
+it runs with no external dependency after installation. The Claude/Codex marketplace
+install checkpoints are automated (preflight, execute, observe, verify); the Kimi
+Code checkpoint fails closed and produces a version-pinned manual install
+requirement; the CodeBuddy/WorkBuddy checkpoint likewise fails closed — because
+the codebuddy CLI cannot pin a frozen ref there is no automated install
+checkpoint — and produces a manual install requirement proven by a trusted
+attestation bound to the frozen plan digest.
+
 ## License
 
 MIT. See [LICENSE](LICENSE).

package/README.zh-CN.md

@@ -2,31 +2,33 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.2.0 -->
+<!-- release-skill:release-version: 0.2.2 -->
 面向 Claude Code、Codex 和 Kimi Code 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终发布的内容是什么。它先冻结并供人工审阅，再从同一份冻结产物发布，不会在最后一步重新生成 README、重新打包当前工作区或覆盖人工内容。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.2.0** (2026-07-25)
+**0.2.2** (2026-07-26)
 
-v0.2.0 是一个硬化发布，提升发布可靠性、摘要可复现性、版本管理和平台注册表数据驱动架构。完成九个硬化任务：暂态重试退避、摘要解耦 planVersion 2、声明式清单载荷契约、版本单源、真实 CLI 契约测试、增量 hooks 缓存、分层并行检查点执行、observe-before-execute 幂等跳过、平台注册表数据化。npm 包名（`release-skill`）、发布身份（`publisher: mzdbxqh`）、公开仓库（`ifoohoo/release-skill`）与公司维护主体保持不变。
+v0.2.2 闭合 CodeBuddy 平台分发链路并新增外部独立市场分发形态。CodeBuddy/WorkBuddy 经与 kimi 同构的人工 attestation 闭环接入 publish/reconcile/verify 流水线：因 codebuddy CLI 无法钉死冻结 ref（无 ref 选项、安装跟踪默认分支/latest），execute 阶段写手动安装 requirement（绝不 exec CLI），observe/verify 消费结构化人工 attestation 并对安装点做只读校验——缺失、过期、不匹配、路径逃逸一律 fail-closed，严重级别与 kimi 一致（发布后验证不可豁免）。外部市场形态允许 distribution 声明 `marketplaceRepo`，prepare 在线冻结外部市场 HEAD（codex 强冻至 commit sha、claude 弱冻至默认分支名）并做冻结 sha 与索引条目完整性校验，plugin-marketplace 在 `external-marketplace-v1` 载荷契约下新增对应 preflight/observe 分支，inline/kimi/codebuddy/legacy 分支一字不变。安装说明（中英四份）统一以独立市场 `ifoohoo/artifact-skill-set` 为主路径。npm 包名（`release-skill`）、发布身份（`publisher: mzdbxqh`）、公开仓库（`ifoohoo/release-skill`）与公司维护主体保持不变。
 
 **新增**
 
-- **暂态重试退避（`observeWithRetry`）**：publish/reconcile 的 execute 后 observe 现在对暂态失败使用有界指数退避。暂态分类具有传播性——仅对暂态错误（网络超时、5xx）重试；CONFLICTING 错误永不重试。市场重试窗口钳制到动作 `timeoutMs`。这解决了真实网络上因暂态 observe 超时导致的间歇性 PARTIAL 失败。
-- **摘要解耦 planVersion 2**：计划字段拆分为绑定层（冻结制品、动作、版本、配置）与记录层（基线、创建时间、状态）。冻结提交时间戳从 `headCommit` 派生，确保摘要可复现。审批不再因树/工作区摘要漂移而失效（v2 计划）；基线检查降级为证据警告。v1 遗留行为逐字节保留（黄金值测试）。
-- **声明式清单载荷契约**：用声明式清单比较替换整树字节相等性。权威条目必须存在且在安装目录中逐字节匹配；主机添加的文件记录（`extraInstalledPaths`，有上限）而非失败。缺少 `payloadContract` 的遗留计划保持精确整树语义。`consumerTransportExclusions` 已弃用（仅遗留路径）。
-- **版本单源 `sync-version` 脚本**：`package.json` 版本现在是唯一手写来源。新的 `sync-version.mjs` 将其传播到插件清单、marketplace.json、README 边界行和 INSTALL 文档（幂等、`--check` 模式、防御性白名单）。`smokeExpectedJson.version` 在运行时从 `targetVersion` 注入，结束 bump-invalidates-plan 循环。docs 钩子现在运行 `check-docs-drift.mjs`（render 检查 + sync-version 检查）。测试中的硬编码版本字面量替换为动态读取。
-- **真实 CLI 契约测试**：隔离 HOME 的契约测试，针对真实 CLI 协议形状（`list --json` 输出形式、子命令存在性）断言适配器假设，由 `RELEASE_SKILL_LIVE_CLI=1` 门控，skip-not-fail 语义。静态契约锁定 'kimi 无脚本化安装'，防止伪造的 CLI 命令静默回归。
-- **增量 hooks 缓存**：hooks 可声明 `cacheable`+`cacheInputs`；结果缓存在 `.release-skill/cache/hooks/<name>/<key>.json`，按 hook 配置和输入内容哈希键控。失败永不缓存；命中跳过执行但不跳过授权门；`--no-hook-cache` 逃生舱。缓存目录注册到基线控制面排除和 gitignore。本项目的 test/typecheck hooks 已缓存：第二次 prepare 降至约 2 秒（test hook 从缓存服务）。
-- **分层并行检查点执行**：publish 检查点分组为硬编码 `TIER_TABLE` 层。层顺序执行，层内动作并发执行，`allSettled` 语义（不快速失败，成功保留）。状态持久化移至每层快照，保持 appendRunState 哈希链完整；通过 SIGKILL-层中集成测试验证崩溃恢复。证据追加通过互斥链序列化，序列从 1 开始，`details.tier` 包含层信息。
-- **observe-before-execute 幂等跳过**：publish 每个检查点 execute 前增加单发只读 pre-observe。四分类：CONSISTENT→SKIPPED / MISSING→execute / CONFLICTING→FAILED / 不可观察→execute。两层 preflight 共用 `classifyPreObservation` 单源（全局 Safety Gate 10 占用仲裁）。SKIPPED 下游适配：层折叠认成功、三处 `every` 扩展为 SUCCEEDED||SKIPPED、`buildPersistedState` 映射 skipped、TOCTOU 照常。
-- **平台注册表数据驱动架构**：新增 `src/platforms/registry.mjs`，包含 `PLATFORMS`/`getPlatform`/`assertRegistry` 模块自校验。三平台完整描述（§3.4 矩阵全维度）+ 纯策略函数。黄金测试 12 用例固化三平台 execute/observe/list 现状行为。`src/producers/build-adapters.mjs` PLATFORMS 改从注册表派生；`scripts/build-adapters.mjs` 重复平台表删除同源导入。`build:adapters:check` 逐字节零 diff（行为零变化强证据）。
+- **CodeBuddy 平台人工 attestation 闭环**：CodeBuddy/WorkBuddy 经与 kimi 同构的人工 attestation 闭环接入发布流水线（`publish`/`reconcile`/`verify`）。因 codebuddy CLI 的 marketplace add/install 均无法钉死冻结 ref（无 ref 选项、安装跟踪默认分支/`latest`，已实测），自动化安装检查点无法保证冻结产物同一性。execute 写手动安装 requirement，绝不 exec CLI；observe/verify 消费结构化人工 attestation 并对安装点做只读校验。缺失、过期、不匹配、路径逃逸的 attestation 一律 fail-closed，严重级别与 kimi 一致（发布后验证不可豁免）。双安装通道（均有实测落盘证据）：desktop 经 WorkBuddy 桌面端统一市场 `artifact-skill-set` 安装（`installPath` 须含 `/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/<plugin>` 尾段，段级检查）；cli 以隔离 `HOME=<authorityDir>/codebuddy-home` 运行捆绑 CLI（`installPath` 须 containment 于该隔离 home 的市场插件根）。attestation 增加 `installChannel` + `marketplace` 字段并按通道校验。管线路由：平台 id `codebuddy`，distributionType `codebuddy-plugin`，actionType `codebuddy-marketplace-install`，列于 Tier 3（与 kimi 同层）；build adapter 保留历史目录名 `workbuddy`（`adapters/workbuddy/`、`.codebuddy-plugin/plugin.json` 清单，字节不变）。
+- **外部独立市场分发形态**：distribution 声明 `marketplaceRepo` 时启用外部形态。prepare 生产循环经 `git ls-remote --symref` 在线冻结外部市场 HEAD（codex 强冻至 commit sha、claude 弱冻至默认分支名），并经 `gh api` 校验外部索引条目（name 匹配、恰一条、claude 形态 `entry.version == 目标版本`）；非在线声明外部形态 fail-closed，外部仓库严格只读。冻结动作携带 `repo=marketplaceRepo`、`ref=add-ref`、`marketplaceCommitSha`、`marketplaceLocation=external`、`payloadContract=external-marketplace-v1`；`snapshotPath`/`manifestDigest` 仍绑本单元冻结快照（载荷权威不变）。plan 完整性校验增加外部分支（repo 匹配、`marketplaceLocation`、40-hex `marketplaceCommitSha`、ref 结构安全）；kimi/codebuddy 携带 `marketplaceRepo` fail-closed。`plugin-marketplace` 新增外部形态 preflight/observe 分支：`external-marketplace-v1` 走与 `declared-manifest-v1` 相同的整树包含语义（权威为 `.`，宿主新增路径记 `extraInstalledPaths` 而非失败）；preflight 跳过快照内市场段，从快照根读 plugin manifest 校验 name/version 与冻结字段；observe 复用既有 strategy 做安装侧条目观察比对（弱冻 claude 版本漂移 fail-closed）。inline/kimi/codebuddy/legacy/`declared-manifest-v1` 分支一字不变。
+
+**变更**
+
+- **安装说明统一市场主路径（中英四份）**：README 与 INSTALL（四份文档）将插件安装统一改为以独立市场 `ifoohoo/artifact-skill-set` 为主路径，README 增补工作流概览与平台分发说明。标准与公开参考（`standards/06-adapter-contract.md`、`references/06-adapter-contract.md`）同步至 codebuddy attestation 形态与外部独立市场形态及其时序约束。
+
+**修复**
+
+- **CodeBuddy 插件 manifest `skills` 字段改为数组**：`.codebuddy-plugin/plugin.json` 清单的 `skills` 字段改为数组输出，与 CodeBuddy 宿主期望的形状一致。
+- **`verificationGate` 作用域 distribution 枚举补 `codebuddy-plugin`**：`release-project.schema.json` 的 `verificationGate.scope.distribution` 枚举补入 `codebuddy-plugin`（镜像既有 `kimi-plugin` 规则），保持 schema 与运行时门白名单一致；四个适配器内嵌的 schema 副本同步重建。
 <!-- release-skill:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.2.0 是当前发布版本（v0.1.9 曾处于已发布、待独立验证状态）。
+> **当前边界：** v0.2.2 是当前发布版本（v0.1.9 曾处于已发布、待独立验证状态）。
 > v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；“当前发布版本”与“首次生产验证里程碑”
@@ -53,6 +55,28 @@ v0.2.0 是一个硬化发布，提升发布可靠性、摘要可复现性、版
 > --confirm-production <planDigest>`；`bound` 前序公开基线必须使用
 > `prepare --online --production`。没有摘要确认就不会预检或写远端。
 
+## 发布工作流概览
+
+release-skill 把发布生命周期建模为一个严格状态机，让每个阶段都有明确的进入和退出条件，且任何阶段都不能跳过。规范定义见 `references/01-state-machine.md`。
+
+```text
+DISCOVERED -> ASSESSED -> PREPARED -> APPROVED -> PUBLISHING -> PUBLISHED -> VERIFIED
+                                   异常态：NEEDS_INPUT / BLOCKED / PARTIAL
+```
+
+每个 CLI 命令对应一次状态转换：
+
+- `help` 检查环境；`setup` 发现项目，并在摘要确认后仅首次创建配置。
+- `assess` 执行只读就绪度评估（`DISCOVERED -> ASSESSED`）。
+- `prepare` 运行验证门、冻结一份不可变发布计划，并把配置的公开文件复制进隔离快照（`ASSESSED -> PREPARED`）。它只写入 `.release-skill/` 目录，从不触碰远端服务。
+- `approve` 记录人工批准，绑定到计划摘要并带 24 小时有效期（`PREPARED -> APPROVED`）。计划一旦变化，批准自动失效。
+- `publish` 按顺序执行外部写操作检查点（`APPROVED -> PUBLISHING -> PUBLISHED`）。
+- `reconcile` 从 `PARTIAL` 恢复；`verify` 在全新隔离环境完成消费者安装验证（`PUBLISHED -> VERIFIED`）。
+
+`PUBLISHED` **不是**终态。只有全新运行的 `verify` 确认远端状态和精确消费者安装都与冻结计划一致时，才会到达 `VERIFIED`。
+
+**发布检查点顺序。** `publish` 先对所有动作做只读全局预检，再按固定顺序执行并观察：公开快照 branch → 签名/可追溯 tag → npm 发布 → GitHub Release → 配置的 Claude/Codex 插件市场安装 → 运行记录。任一步骤失败都会停止后续检查点并使运行进入 `PARTIAL`。系统绝不自动删除远端 tag、不 unpublish 包、不从头重跑；`reconcile` 查询实际远端状态，跳过已一致的步骤，只重试安全且未完成的动作，远端冲突则交由人工决策。
+
 ## 为什么人工修改的 README 不会丢失
 
 release-skill 不重新生成、也不回写项目源文件。`prepare` 从当前工作区把每个公开文件复制到隔离的本地快照，并验证复制前后的字节。README 的 slogan、示例、正文、格式，以及后续任何人工修改都会作为完整文件被保留。
@@ -94,6 +118,25 @@ npx release-skill help
 release-skill help
 ```
 
+**安装为插件（Claude Code / CodeBuddy / WorkBuddy / Codex / Kimi Code）：**
+
+四种插件宿主都从统一市场 `ifoohoo/artifact-skill-set` 安装——以 Claude
+Code 会话为例：
+
+```
+/plugin marketplace add ifoohoo/artifact-skill-set
+/plugin install release-skill@artifact-skill-set
+```
+
+`ifoohoo/artifact-skill-set` 是一个**外部独立市场**：插件仓库只含 plugin
+清单，marketplace 索引集中于外部市场仓库。当发布单元的插件 distribution 声明
+`marketplaceRepo` 时，`prepare --online --production` 会冻结外部市场 HEAD
+（Codex 钉 commit sha——强冻结；Claude 钉默认分支名——弱冻结），并以本单元自身
+冻结快照整树校验安装载荷。**发布时序：** 须先发布外部市场索引——其条目版本须
+等于目标发布版本——之后 `prepare` 才能冻结到含该条目的市场 sha。各平台完整命令
+见 [INSTALL.zh-CN.md](INSTALL.zh-CN.md)，契约与进阶直接仓库安装方式见
+`references/06-adapter-contract.md` §2.3/§2.4。
+
 **开发安装（贡献者回退，从源码 checkout）：**
 
 ```bash
@@ -600,6 +643,8 @@ reconcile 成功只返回 `PUBLISHED`，不会返回 `VERIFIED`；只有全新
 - 用计划摘要、有效期和显式 action allowlist 绑定人工批准；
 - 从冻结 Git object 和 npm tarball 发布，并核对远端 commit/tree/tag/integrity；
 - 从冻结 Git ref 安装配置的 Claude/Codex 插件，证明入口 Skill 和安装载荷摘要；对 Kimi Code（无可脚本化安装接口）产出版本钉死的手动安装要求，仅依据绑定到冻结计划摘要的可信证明来确认入口 Skill 和载荷摘要；
+- 为 Claude/Codex distribution 支持外部独立市场（`marketplaceRepo`）：`prepare --online --production` 冻结外部市场 HEAD（Codex commit sha / Claude 默认分支名），校验该 sha 处的市场索引条目，并以本单元自身冻结快照整树校验安装载荷（`external-marketplace-v1`），安装侧 CLI list 观察在版本漂移时失败关闭；
+- 随 Claude/Codex/Kimi 适配器一并提供生成的自包含 CodeBuddy/WorkBuddy 适配器（`adapters/workbuddy/`，清单 `.codebuddy-plugin/plugin.json`，技能以 `${CODEBUDDY_PLUGIN_ROOT}` 渲染）；因 codebuddy CLI 无法钉死冻结 ref 而无自动化 marketplace 安装检查点，故产出手动安装要求，仅依据绑定到冻结计划摘要的可信证明来确认入口 Skill 和载荷摘要；
 - 明确区分 `PUBLISHED`（外写完成）与 `VERIFIED`（远端和消费者安装证据完成）；
 - 中途失败停止后续动作，记录独立 run；不修改冻结 plan，不自动撤销已成功动作。
 
@@ -651,6 +696,7 @@ push、tag、默认分支修改、GitHub Release 和 npm publish 不能放进 ho
 - 不声称已经替项目完成真实生产 canary；
 - `prepare --online` 只观察 bound 前序基线；目标唯一性由 publish 全局预检完成；
 - 不覆盖已有 branch/tag/Release，不 unpublish npm；
+- 不提供自动化 CodeBuddy/WorkBuddy marketplace 安装检查点——codebuddy CLI 无法钉死冻结 ref，安装为手动步骤，经与 Kimi Code 相同的可信证明闭环确认；
 - 不承诺 Windows 或广泛的跨平台原生写入；
 - 不会隐藏地 commit、push、打 tag、创建 Release 或发布包。
 
@@ -690,6 +736,20 @@ push、tag、默认分支修改、GitHub Release 和 npm publish 不能放进 ho
 - `release-reconcile`：基于证据恢复 PARTIAL；冲突时人工介入。
 - `release-verify`：发布后验证；只有 `VERIFIED` 才是 happy end。
 
+## 平台分发
+
+同一个确定性核心引擎通过 build-only 适配器闭包分发到多个目标。发布单元用 `distributions` 声明要发布给谁；每种分发类型对应一个具体产物：
+
+| `distributions` 类型 | 物理产物 | 安装方式 |
+|---|---|---|
+| `npm` | 带 CLI 入口的 npm 包 | `npm install -g release-skill` |
+| `claude-plugin` | `adapters/claude/` 下的自包含闭包 | 自动化 marketplace 检查点 |
+| `codex-plugin` | `adapters/codex/` 下的自包含闭包 | 自动化 marketplace 检查点 |
+| `kimi-plugin` | 自包含闭包（无可脚本化安装接口） | 手动，需可信证明 |
+| `codebuddy-plugin` | 生成的 `adapters/workbuddy/`，带 `.codebuddy-plugin/plugin.json`（codebuddy CLI 无法钉死冻结 ref） | 手动，需可信证明 |
+
+每个适配器闭包都自带一份 CLI bundle、skills 和 schemas 的副本，安装后无需外部依赖即可运行。Claude/Codex 的 marketplace 安装检查点是自动化的（preflight、execute、observe、verify）；Kimi Code 检查点失败关闭，并产出版本钉死的手动安装要求；CodeBuddy/WorkBuddy 检查点同样失败关闭——因 codebuddy CLI 无法钉死冻结 ref 而无自动化安装检查点——并产出经绑定冻结计划摘要的可信证明确认的手动安装要求。
+
 ## 许可证
 
 MIT，见 [LICENSE](LICENSE)。

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

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.2.0",
+      "version": "0.2.2",
       "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.2.0",
+  "version": "0.2.2",
   "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
   "author": {
     "name": "广州市风荷科技有限公司"