release-skill 0.2.3 → 0.2.4

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.2.3",
+      "version": "0.2.4",
       "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.3",
+  "version": "0.2.4",
   "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.3",
+  "version": "0.2.4",
   "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.3",
+  "version": "0.2.4",
   "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.3.",
+      "Prepare a release plan for version 0.2.4.",
       "Help me understand the release workflow."
     ]
   }

package/.kimi-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.2.4 locale=en baseline=sha256:b0ad6c897df808a11a2630d1565327ff5092e407dd004dc71bc43b954cbf88a6 -->
+## [0.2.4] - 2026-07-28
+
+v0.2.4 is a documentation and marketplace-source remediation release. It corrects the default marketplace source to the bundled-family repository (ifoohoo/release-skill), eliminates stale v0.1.9 residuals, improves README bilingual consistency and navigation, and strengthens anti-regression gates for version drift.
+
+### Changed
+
+- **Default marketplace source corrected**: all installation documentation now uses the bundled-family repository `ifoohoo/release-skill` instead of the external marketplace `ifoohoo/artifact-skill-set`. Claude Code install command is now `/plugin marketplace add ifoohoo/release-skill` with `release-skill@release-skill`.
+- **README restructured for readability**: both EN and ZH READMEs now include a table of contents, Documentation navigation section, and reorganized chapter flow (Quick start moved before preservation contract). Significantly shorter than before.
+- **Positioning sentences completed**: README and root workspace README now list all supported platforms (Claude Code, CodeBuddy, WorkBuddy, Codex, Kimi Code).
+- **Anti-regression gate expanded**: `sync-version.mjs` TEXT_TARGETS now covers the safe-first-command version statement in both EN and ZH READMEs, preventing future v0.1.9-type drift.
+
+### Fixed
+
+- **v0.1.9 residual eliminated**: the safe-first-command block in both READMEs now correctly references the current version (was stuck at v0.1.9).
+- **Stale counting removed**: replaced fragile 'All four plugin hosts' / '四种插件宿主' with 'All supported plugin hosts' / '各插件宿主'.
+- **Root README boundary corrected**: clarified that README/INSTALL/CHANGELOG are human-maintained source files, while references/schemas/adapters/skills are generated artifacts.
+- **CONTRIBUTING updated**: added 'Do not edit generated files' section documenting the authority source and regeneration workflow for references/, schemas/, adapters/, and skills/.
+- **AGENTS.md language rule adjusted**: governance rules file may use English; user-facing documentation remains Chinese.
+<!-- release-skill:changelog:end version=0.2.4 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.2.3 locale=en baseline=sha256:1bc1839f9d2de5481a9edc7748722c02c5c9369d2034f8c6495f6dd00a392339 -->
 ## [0.2.3] - 2026-07-26
 

package/CONTRIBUTING.md

@@ -19,6 +19,33 @@ Thank you for your interest in contributing to release-skill.
 - `references/` - Rendered reference documentation.
 - `test/` - Test suite.
 
+## Do not edit generated files
+
+The following directories contain **generated artifacts** whose authoritative
+source lives elsewhere. Do not edit them directly; changes will be overwritten
+on the next regeneration.
+
+| Generated directory | Authoritative source | Regeneration command |
+|---|---|---|
+| `references/` | `standards/` (workspace root) | `pnpm public:render` (workspace root) |
+| `schemas/` | `standards/` (workspace root) | `pnpm public:render` (workspace root) |
+| `adapters/` | `src/` + `skills-src/` | `npm run build:adapters` (this directory) |
+| `skills/` | `skills-src/` | `npm run sync:skills` (this directory) |
+
+To update a generated artifact:
+
+1. Edit the authoritative source (e.g., `standards/01-state-machine.md` for
+   `references/01-state-machine.md`, or `skills-src/release-help/SKILL.md` for
+   `skills/release-help/SKILL.md`).
+2. Run the regeneration command.
+3. Verify with `pnpm public:verify` (workspace root) or
+   `npm run build:adapters:check` / `npm run sync:skills:check` (this directory).
+
+**README.md**, **INSTALL.md**, and **CHANGELOG.md** are human-maintained source
+files. Their managed regions are refreshed by the `docs refresh` command using
+structured release-notes YAML; do not hand-edit content between managed-region
+markers.
+
 ## Development Guidelines
 
 - All code uses ESM (`.mjs` extension) on Node.js 22+.

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.2.3 -->
+<!-- release-skill:release-version: 0.2.4 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -35,44 +35,34 @@ 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.
+## Install as a plugin (bundled-family marketplace — recommended)
+
+Claude Code, CodeBuddy, WorkBuddy, and Codex install release-skill from the
+bundled-family marketplace [ifoohoo/release-skill](https://github.com/ifoohoo/release-skill).
+The plugin repository itself carries the marketplace manifest
+(`.claude-plugin/marketplace.json`), so no external marketplace is required.
+Kimi Code has no marketplace install API — see the
+[Kimi Code section](#install-as-a-kimi-code-plugin). Add the marketplace once,
+then install the plugin:
+
+> **Prerequisite: GitHub access.** The `owner/repo` shorthand makes Claude Code
+> clone via `git@github.com:...` (SSH), which requires a GitHub public key
+> configured on this machine. If you do not use SSH, either pass the full HTTPS
+> URL — `/plugin marketplace add https://github.com/ifoohoo/release-skill` — or
+> set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`.
 
 **Claude Code** (interactive session):
 
 ```
-/plugin marketplace add ifoohoo/artifact-skill-set
-/plugin install release-skill@artifact-skill-set
+/plugin marketplace add ifoohoo/release-skill
+/plugin install release-skill@release-skill
 ```
 
 **CodeBuddy / WorkBuddy:**
 
 ```bash
-codebuddy plugin marketplace add ifoohoo/artifact-skill-set
-codebuddy plugin install release-skill@artifact-skill-set
+codebuddy plugin marketplace add ifoohoo/release-skill
+codebuddy plugin install release-skill@release-skill
 ```
 
 WorkBuddy desktop installs only through a registered marketplace: after the
@@ -81,19 +71,16 @@ WorkBuddy desktop installs only through a registered marketplace: after the
 **OpenAI Codex:**
 
 ```bash
-codex plugin marketplace add ifoohoo/artifact-skill-set
+codex plugin marketplace add ifoohoo/release-skill
 ```
 
 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.
+Kimi Code has no marketplace install API. Installation is manual, pinned to a
+specific release tag. See the [Kimi Code section](#install-as-a-kimi-code-plugin)
+for the version-pinned manual install and attestation closed loop.
 
 ### Alternative: direct repository install (advanced)
 
@@ -126,64 +113,51 @@ non-interactive install API**. release-skill therefore models Kimi installation
 as a version-pinned **manual** install plus trusted observation/attestation:
 `publish`/`verify` never auto-install Kimi plugins. The closed loop is:
 
-1. `publish` performs the automated writes (Git branch/tag, npm, GitHub
-   Release), then reaches the `kimi-marketplace-install` checkpoint. Because
-   there is no scriptable install, 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) gives the isolated
-   `KIMI_CODE_HOME`, the pinned install URL, and the attestation path.
+1. `publish` performs the automated remote writes (Git branch/tag, npm, GitHub
+   Release). The `kimi-marketplace-install` action is recorded as `DEFERRED`
+   during publish — the marketplace adapter is not called, and the automated
+   install path fails closed. The run enters `PUBLISHED` after all remote
+   permanent writes are consistent. The run record gives the pinned install URL
+   and the attestation path.
 2. Read the requirement at
    `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-manual-install.json`.
-3. Launch Kimi Code with that **isolated** home so the managed copy lands inside
-   it (do not use your ordinary `~/.kimi-code`):
-
-   ```
-   HOME=<kimiCodeHome> KIMI_CODE_HOME=<kimiCodeHome> kimi
-   ```
-
-   The plugin installs to `<kimiCodeHome>/plugins/managed/<plugin>/`.
-4. In that isolated session, install from the release tag pinned to the exact
+3. Launch Kimi Code and install from the release tag pinned to the exact
    version (never the bare repository URL, which installs the latest release or
-   default branch), confirm the trust prompt, then reload:
+   default branch), confirm the trust prompt, then reload. Before writing the
+   attestation you MUST confirm the installed plugin manifest version equals the
+   frozen version; otherwise do NOT issue an attestation.
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.3
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.2.4
    /plugins reload
    ```
 
-5. Write the attestation JSON to
+4. Write the attestation JSON to
    `<root>/.release-skill/kimi-attestations/<planDigest>/<plugin>/release-skill-kimi-attestation.json`.
-   `planDigest` MUST be the frozen **plan** digest; `payloadDigest` MUST be the
-   frozen snapshot **payload** digest; `installPath` MUST be the isolated
-   managed directory above; `attestedAt` must not be in the future and
-   `expiresAt` must be within 24 hours of `attestedAt`. Example:
+   `planDigest` MUST be the frozen **plan** digest; `result` accepts only
+   `"passed"` or `"failed"`. Example:
 
 ```json
 {
-  "consumer": "kimi",
-  "plugin": "release-skill",
-  "version": "0.2.3",
-  "entrySkill": "release-help",
-  "repo": "ifoohoo/release-skill",
-  "ref": "release-skill-v0.2.3",
-  "installPath": "<kimiCodeHome>/plugins/managed/release-skill",
+  "platform": "kimi",
+  "version": "0.2.4",
   "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"
+  "result": "passed",
+  "actor": "<person who confirmed>",
+  "confirmedAt": "2026-07-23T00:00:00.000Z",
+  "note": "<optional note>"
 }
 ```
 
-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.
+5. Run `release-skill verify --run <publish-run>` (→
+   `VERIFIED`). The verify command reads the attestation from the same
+   plan-digest-keyed directory, so the fresh run directory does not lose the proof.
 
-Installing into the ordinary `~/.kimi-code` is **not** acceptable proof: the
-attested `installPath` must resolve inside the requirement's isolated
-`KIMI_CODE_HOME` managed root, otherwise verification fails closed and the Kimi
-unit never reaches `VERIFIED`.
+When a platform has no reliable automated verification, the bound human
+`passed`/`failed` attestation is authoritative. The `verify` command consumes
+the human result and transitions to `VERIFIED` on success. However, identity,
+version, payload, marketplace source, or installation contract inconsistencies
+MUST NOT be overridden by a human `passed` result.
 
 ## Install as a CodeBuddy/WorkBuddy plugin
 
@@ -211,83 +185,65 @@ 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.
+1. `publish` performs the automated remote writes (Git branch/tag, npm, GitHub
+   Release). The `codebuddy-marketplace-install` action is recorded as `DEFERRED`
+   during publish — the marketplace adapter is not called, and the automated
+   install path fails closed. The run enters `PUBLISHED` after all remote
+   permanent writes are consistent. The run record gives 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.3`; otherwise do NOT issue an attestation.
-5. Write the attestation JSON to
+3. Install release-skill from the bundled-family marketplace `ifoohoo/release-skill`
+   (https://github.com/ifoohoo/release-skill). Before writing the
+   attestation you MUST confirm the installed plugin manifest version equals the
+   frozen version; otherwise do NOT issue an attestation.
+4. 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:
+   `planDigest` MUST be the frozen **plan** digest; `result` accepts only
+   `"passed"` or `"failed"`. Example:
 
 ```json
 {
-  "consumer": "codebuddy",
-  "plugin": "release-skill",
-  "version": "0.2.3",
-  "entrySkill": "release-help",
-  "repo": "ifoohoo/release-skill",
-  "ref": "release-skill-v0.2.3",
-  "marketplace": "artifact-skill-set",
-  "installChannel": "desktop",
-  "installPath": "~/.workbuddy/plugins/marketplaces/artifact-skill-set/plugins/release-skill",
+  "platform": "codebuddy",
+  "version": "0.2.4",
   "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"
+  "result": "passed",
+  "actor": "<person who confirmed>",
+  "confirmedAt": "2026-07-23T00:00:00.000Z",
+  "note": "<optional note>"
 }
 ```
 
-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.
+5. Run `release-skill verify --run <publish-run>` (→
+   `VERIFIED`). The verify command reads the attestation from the same
+   plan-digest-keyed directory, so the fresh run directory does 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.)
+When a platform has no reliable automated verification, the bound human
+`passed`/`failed` attestation is authoritative. The `verify` command consumes
+the human result and transitions to `VERIFIED` on success. However, identity,
+version, payload, marketplace source, or installation contract inconsistencies
+MUST NOT be overridden by a human `passed` result.
 
 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.
 
+## Consumer verification boundaries
+
+**When verification runs.** Consumer-side install verification executes only
+when the installation contract's critical files have changed relative to the
+confirmed public baseline. When critical files are unchanged, the result is
+`NOT_REQUIRED_UNCHANGED`; do not append redundant verification.
+
+**Marketplace source selection.** Each platform, each release, selects exactly
+one marketplace source: `bundled-family` (skill-family ships its own marketplace
+files) or `standalone-index` (independent marketplace index). Never use both.
+
+**Codex automatic verification first.** Codex prefers automated verification.
+Only when the CLI/interface, runtime, or transport is unavailable does the
+system degrade to manual judgment. Identity, version, payload, marketplace
+source, or installation contract inconsistencies are failures and must not be
+human-overridden.
+
 ## Development Install (Local Checkout)
 
 For development or when working from source: