release-skill 0.6.1 → 0.6.3

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "release-skill",
       "source": "./",
-      "version": "0.6.1",
+      "version": "0.6.3",
       "description": "Safe preparation and frozen GitHub/npm production publishing with full happy end verification",
       "author": {
         "name": "广州市风荷科技有限公司"

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "release-skill",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "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.6.1",
+  "version": "0.6.3",
   "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.6.1",
+  "version": "0.6.3",
   "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.6.1.",
+      "Prepare a release plan for version 0.6.3.",
       "Help me understand the release workflow."
     ]
   }

package/.kimi-plugin/plugin.json

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

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+<!-- release-skill:changelog:start version=0.6.3 locale=en baseline=sha256:a1b8f98d720cae60e0855677b22dd3fd75f6c43eb31123951a5129d149626e70 -->
+## [0.6.3] - 2026-08-20
+
+v0.6.3 adds the postPublish hooks v2 registration mechanism with six built-in presets, checkpoint-level approval records for hooks that write downstream, a postVerify stage that runs hooks only after the main run reaches VERIFIED, an append-only setup proposal flow that drafts postPublish hook declarations for already-configured projects, the O1-O7 release-cycle speed-ups, and release-skill's own dogfood hub-entry proposal declaration — which this release delivers to the public skill-family-hub repository during its postVerify phase under its own checkpoint approval.
+
+### Added
+
+- **postPublish hooks v2 and six presets**: `releaseUnit.postPublish` now accepts a declarative `hooks` array alongside the existing `targets`; each hook is a named preset or a custom command hook following the prepare-hook rules (executable/argument arrays, relative cwd, timeout, environment allowlist — shell strings rejected). Six built-in presets ship with the bundle and are enumerated by `release-skill distribute --list-presets`: `git-mirror` and `marketplace-index-render` (declared in `targets` form), plus `proposal-inbox`, `marketplace-registry-entry`, `docs-refresh`, and `notify-handoff` (declared in `hooks` form); writing presets share `remoteUrl`/`workspace` dual downstream addressing, `proposal-inbox` without a target degrades to `notify-handoff` behavior instead of failing, and `notify-handoff` is the zero-write floor rendering a deterministic manual sync checklist. Every declaration is normalized into the frozen plan, so a hook change changes the plan digest and invalidates existing approvals; existing `targets` configurations stay valid with unchanged execution semantics.
+- **Checkpoint-level hook approval**: a hook with `requiresApproval: true` (the default for public-write presets; projects may tighten, never loosen) parks at `AWAITING_APPROVAL` with zero remote writes until its own checkpoint approval is minted with `release-skill approve --plan <plan> --hook <hookId> --actor <name>` and consumed via `distribute --hook-approval` or `ship --hook-approval`. Approval records follow the new `postpublish-approval-record` schema bound to `(planDigest, hookId)` with the 24-hour expiry; a hook configuration change changes the plan digest and invalidates the approval. The run schema gains the `AWAITING_APPROVAL` checkpoint status, and the approval interface displays the normalized entry summary of each approved hook.
+- **postVerify stage**: hooks declared with `phase: postVerify` run only after the main run reaches VERIFIED; `ship` routes them into an independent postVerify run whose hook context carries the verification evidence (`verifyEvidence`, present in this phase only). A failed postVerify run stays PARTIAL and can be reconciled, but it never rolls the main run back from VERIFIED — the failure is recorded prominently in evidence, never silently.
+- **Setup incremental hook proposal**: for already-configured projects, `setup --discover-downstream` performs read-only discovery of downstream candidates (git remotes, marketplace/docs repository clues, `artifact-graph` configuration, foundation profiles) and `setup --propose-hooks` drafts postPublish hook declarations for human review; after human confirmation of the `setupDigest` the flow appends only the hooks section and never rewrites any other part of the configuration. The create-once boundary is preserved: an existing configuration is never regenerated.
+- **Dogfood hub proposal declaration**: release-skill's own project configuration declares a `proposal-inbox` (git-push) hub-entry proposal toward the public `skill-family-hub` repository, delivered during this release's postVerify phase under its own checkpoint approval; delivery plus the deterministic manual sync prompt in evidence is the closure criterion — hub-side consumption is out of scope for this release.
+
+### Changed
+
+- **Release-cycle speed optimizations (O1-O7)**: `build-adapters --check` and the self-bootstrap fact-pin suite are now fail-closed prepare pre-gates that run before hooks and the full-test gate (a fast pre-gate, not a replacement for full tests); a new one-click derived-artifact sync command validates and rebuilds the version/docs/bundle/adapters/manifest/public-files areas in dependency order and never writes src or test pins; `build-adapters --apply` is the supported rebuild path for existing drifted adapters; the `ship` happy end now orchestrates `prepare --production --online` by default with explicit remediation prompts for non-production and offline plans; online production prepare reports a warning-level observation when the local branch leads origin (non-blocking); `verify --run` accepts a run directory and resolves its `release-run.json` automatically (file form unchanged); and the `generate-platform-manifest --check` baseline drift is fixed.
+
+### Fixed
+
+- **Production CLI distribute adapter registration**: both production CLI adapter registries now register the distribute-git adapter; before this fix the production `distribute`/`ship` auto-distribution path failed with `no distribute adapter registered`. The state-machine reference completes the `DISTRIBUTING`/`DISTRIBUTED` states and their transitions.
+<!-- release-skill:changelog:end version=0.6.3 locale=en -->
+
+
+<!-- release-skill:changelog:start version=0.6.2 locale=en baseline=sha256:103dcbd11e52542a07da9a1220eb246cf812de79ede19ff63a374785393580b7 -->
+## [0.6.2] - 2026-08-19
+
+v0.6.2 promotes the skill resource closure checker to a fail-closed release gate spanning prepare, publish, and verify, closes the five gaps (G1–G5) confirmed by the clause-by-clause gate audit, and fixes lineage commit-identity parsing that corrupted rebuilt commits: missing or drifted skill resources, home-directory search paths, and undeclared host surfaces now block a release before plan freeze, and commit identities are parsed with an anchored regex that fails closed instead of fabricating identity fields.
+
+### Added
+
+- **Skill-resource-closure v2 release gate**: the closure checker is now a fail-closed release gate across all three phases — prepare scans the frozen snapshot and blocks plan freeze on any finding with `GATE_FAILED` (error code 13), publish Gate 2c recomputes closure against the verified frozen snapshots for production plans, and verify validates the real npm install tree and marketplace install directories with per-host receipts. Receipts now carry `unitId`, host/surface detail, digests, `checkerVersion` (`skill-resource-closure-v2`), and counts; the platform registry declares each adapter's host surface as an explicit adapter directory name, and the receipt schema is bound in all six release-plan schema copies. A version mismatch between an old frozen plan and the new checker fails closed.
+- **Closure gate gap closure (G1–G5)**: source-only (`SOURCE_ONLY_NOT_SHIPPED`) exemptions are now listed per reference in the receipt projection and in the prepare evidence — auditable and non-blocking; `~/`, `$HOME/`, and `${HOME}/` search paths inside code spans, fences, and link targets fail closed as `HOME_DIRECTORY_SEARCH`; identical surface-relative resources whose contents diverge across surfaces fail closed as `RESOURCE_DRIFT` with cross-surface reference locations; unreferenced regular files inside adapter skill closure directories fail closed as `STALE_RESOURCE`; every declared plugin distribution must be backed by a receipt host surface with at least one skill (declared-host reconciliation), so a dropped adapter tree can no longer skip the gate silently; and frozen receipts bind a deterministic `preparedAt` freeze timestamp (never a wall-clock sample) plus `exitCode: 0`, so identical sources freeze byte-identical receipts on every re-prepare.
+
+### Fixed
+
+- **Lineage commit-identity parsing (lineage-ident)**: `lineage rebuild` parsed author/committer ident lines with `split(/\s+>/)`, which never matched a legal ident line and corrupted the identities written to rebuilt commits (names containing spaces or `>` were mis-parsed as well). Idents are now parsed with an anchored regex whose greedy name capture lets the last `<email> ts tz` group win; unparseable lines fail closed instead of fabricating identity fields. Commit messages are fed to `commit-tree` via `-F -` stdin from untrimmed `cat-file` output, preserving arbitrary message bytes including trailing whitespace and blank lines.
+- **Assess npm-transport test stability (test-only)**: the assess npm-transport test flaked when the npm lifecycle injected a silent loglevel setting and ambient proxy variables into the child environment — emptying npm stderr and letting a released ephemeral localhost port be hijacked. The test now strips ambient npm-config-namespace environment keys and proxy variables (`isolateNpmTransportEnv`), holds the localhost port for the whole test (`startConnectionResetRegistry`), and asserts `ECONNRESET|ECONNREFUSED` deterministically. No production behavior changed.
+<!-- release-skill:changelog:end version=0.6.2 locale=en -->
+
+
 <!-- release-skill:changelog:start version=0.6.1 locale=en baseline=sha256:dd7c991244d72db1247dda808057fda060b1e7bb03ff866aae691841828e6239 -->
 ## [0.6.1] - 2026-08-18
 

package/CONTRIBUTING.md

@@ -29,7 +29,7 @@ on the next regeneration.
 |---|---|---|
 | `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) |
+| `adapters/` | `src/` + `skills-src/` | `npm run build:adapters:apply` (this directory; rebuilds existing targets, `build:adapters` creates fresh ones) |
 | `skills/` | `skills-src/` | `npm run sync:skills` (this directory) |
 
 To update a generated artifact:

package/INSTALL.md

@@ -2,7 +2,7 @@
 
 [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.6.1 -->
+<!-- release-skill:release-version: 0.6.3 -->
 ## Prerequisites
 
 - Node.js 22.0.0 or later
@@ -114,7 +114,7 @@ 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:
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.6.1
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.6.3
    /plugins reload
    ```
 
@@ -317,6 +317,51 @@ native prebuild shipped in v0.1.3. Other platforms fail closed with
 `SAFE_WRITE_UNAVAILABLE`; keep the dry-run report and create the reviewed file
 manually instead of enabling an unsafe pathname fallback.
 
+### Incremental postPublish hook proposals (existing configs)
+
+An already-configured project never reruns create-once setup. Instead, setup
+offers a strictly read-only downstream discovery and an append-only hook
+proposal mode. Discovery reports git remote mirror candidates, marketplace and
+docs clues in the workspace and its immediate neighbors,
+`artifact-graph.config.yaml` presence, and the foundation profile metadata.
+It never writes:
+
+```bash
+PROJECT=/path/to/your/project
+"${CLI[@]}" setup --root "$PROJECT" --discover-downstream --json
+```
+
+The proposal dry-run renders legal postPublish hook declaration drafts plus the
+candidate evidence, and binds the existing configuration bytes, the discovery
+facts, and the selection into a `setupDigest`:
+
+```bash
+PROJECT=/path/to/your/project
+PROPOSAL_REPORT="$(mktemp "${TMPDIR:-/tmp}/release-hooks-proposal.XXXXXX")"
+"${CLI[@]}" setup --root "$PROJECT" --propose-hooks --json > "$PROPOSAL_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.setupDigest){console.error("setupDigest missing");process.exit(2)}process.stdout.write(JSON.stringify({status:r.status,targetUnitId:r.targetUnitId,appendableHookIds:r.appendableHookIds,conflicts:r.conflicts,setupDigest:r.setupDigest},null,2)+"\n")' "$PROPOSAL_REPORT"
+```
+
+`--select-hooks <ids>` narrows the selection to the listed proposal ids;
+`--foundation-profile <path>` adds an explicit foundation profile (proposal
+input only — never auto-applied); `--unit <id>` chooses the release unit when
+several declare the postPublish base. After one human review of the drafts,
+the exact confirmed digest authorizes an append-only write of ONLY
+`releaseUnits[<target>].postPublish.hooks`; the create-once boundary is never
+touched by this mode:
+
+```bash
+"${CLI[@]}" setup --root "$PROJECT" --propose-hooks \
+  --write --confirm-setup <confirmed-setupDigest> --json
+```
+
+The write returns `HOOKS_APPENDED`, or `HOOKS_NO_CHANGE` with zero writes when
+nothing is appendable. A wrong or stale digest fails closed with
+`SETUP_DIGEST_MISMATCH`; rerun the dry-run and review the new digest again.
+The incremental append requires the target release unit to already declare the
+postPublish materialize/commitIdentity distribute base, and it re-validates the
+merged declaration before any write.
+
 After the config exists, check release readiness:
 
 ```bash

package/INSTALL.zh-CN.md

@@ -2,7 +2,7 @@
 
 [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.6.1 -->
+<!-- release-skill:release-version: 0.6.3 -->
 ## 前置条件
 
 - Node.js 22.0.0 或更高版本
@@ -104,7 +104,7 @@ Kimi Code 有交互式插件市场，但**没有可脚本化的非交互安装
 （切勿使用裸仓库地址，它会安装最新 release 或默认分支），确认信任提示后重新加载：
 
    ```
-   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.6.1
+   /plugins install https://github.com/ifoohoo/release-skill/releases/tag/release-skill-v0.6.3
    /plugins reload
    ```
 
@@ -272,6 +272,33 @@ node -e 'require("node:fs").rmSync(process.argv[1],{recursive:true,force:false})
 
 自动 create-once 写入使用 v0.1.3 随包提供、带摘要登记的 `darwin-arm64` 原生预构建。其他平台以 `SAFE_WRITE_UNAVAILABLE` 失败关闭；此时保留只读报告，由人工首次创建经审阅的文件，不得启用不安全的路径写入兜底。
 
+### 增量 postPublish hook 提案（已有配置）
+
+已完成配置的项目不会重跑 create-once setup。setup 另外提供严格只读的下游发现与仅追加的 hook 提案模式。发现阶段报告 git 远端镜像候选、工作区及其直接邻居中的 marketplace 与 docs 线索、`artifact-graph.config.yaml` 存在性以及 foundation profile 元信息，全程不写入：
+
+```bash
+PROJECT=/path/to/your/project
+"${CLI[@]}" setup --root "$PROJECT" --discover-downstream --json
+```
+
+提案 dry-run 渲染合法的 postPublish hook 声明草案与候选证据，并把现有配置字节、发现事实与选择集合绑定进 `setupDigest`：
+
+```bash
+PROJECT=/path/to/your/project
+PROPOSAL_REPORT="$(mktemp "${TMPDIR:-/tmp}/release-hooks-proposal.XXXXXX")"
+"${CLI[@]}" setup --root "$PROJECT" --propose-hooks --json > "$PROPOSAL_REPORT"
+node -e 'const fs=require("node:fs");const r=JSON.parse(fs.readFileSync(process.argv[1],"utf8"));if(!r.setupDigest){console.error("setupDigest missing");process.exit(2)}process.stdout.write(JSON.stringify({status:r.status,targetUnitId:r.targetUnitId,appendableHookIds:r.appendableHookIds,conflicts:r.conflicts,setupDigest:r.setupDigest},null,2)+"\n")' "$PROPOSAL_REPORT"
+```
+
+`--select-hooks <ids>` 将选择收窄到列出的提案 id；`--foundation-profile <path>` 追加显式 foundation profile（仅作为提案输入，绝不自动应用）；当多个发布单元声明了 postPublish 基础时，`--unit <id>` 选定目标发布单元。人工审阅草案一次之后，精确确认的摘要授权一次仅追加 `releaseUnits[<target>].postPublish.hooks` 的写入；该模式绝不触碰 create-once 边界：
+
+```bash
+"${CLI[@]}" setup --root "$PROJECT" --propose-hooks \
+  --write --confirm-setup <已确认的 setupDigest> --json
+```
+
+写入返回 `HOOKS_APPENDED`；没有可追加内容时返回 `HOOKS_NO_CHANGE` 且零写入。错误或过期的摘要以 `SETUP_DIGEST_MISMATCH` 失败关闭；重跑 dry-run 并重新审阅新的摘要。增量追加要求目标发布单元已声明 postPublish 的 materialize/commitIdentity 分发基础，且写入前会重新校验合并后的声明。
+
 配置存在后，检查发布就绪度：
 
 ```bash

package/README.md

@@ -2,7 +2,7 @@
 
 [简体中文](README.zh-CN.md) · Installation: [English](INSTALL.md) / [简体中文](INSTALL.zh-CN.md)
 
-<!-- release-skill:release-version: 0.6.1 -->
+<!-- release-skill:release-version: 0.6.3 -->
 Release preparation for Claude Code, CodeBuddy, WorkBuddy, Codex, and Kimi Code, with human-edited files kept intact.
 
 release-skill helps a maintainer answer three questions: what will be released,
@@ -14,20 +14,29 @@ Setup surfaces only the deterministic `compactSummary` review view; the full
 report stays in a temporary session directory.
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.6.1** (2026-08-18)
+**0.6.3** (2026-08-20)
 
-v0.6.1 closes the four root causes of the 0.6.0 self-bootstrap release cycle, in which 22 of 25 runs failed and nearly all wall-clock time was spent in diagnose-repair loops or on external interference: hook failures are no longer silent, stale bundles fail closed at the earliest gate, the freeze path can never skip the full test suite, and a machine-readable frozen marker now tells sibling governance tasks to keep out of a repository mid-release.
+v0.6.3 adds the postPublish hooks v2 registration mechanism with six built-in presets, checkpoint-level approval records for hooks that write downstream, a postVerify stage that runs hooks only after the main run reaches VERIFIED, an append-only setup proposal flow that drafts postPublish hook declarations for already-configured projects, the O1-O7 release-cycle speed-ups, and release-skill's own dogfood hub-entry proposal declaration — which this release delivers to the public skill-family-hub repository during its postVerify phase under its own checkpoint approval.
 
 **Added**
 
-- **Hook failure output passthrough (R1)**: when a prepare hook exits non-zero, the run evidence now carries bounded `stderrTail` / `stdoutTail` projections (last 50 lines, capped at 8 KiB) and the CLI echoes the stderr tail, so failures such as a bare `exit=13` are diagnosable immediately instead of by blind retry. Exit-code semantics are unchanged.
-- **Bundle freshness gate (R2)**: every rebuilt bundle embeds a frozen digest of its source tree, and prepare compares source against bundle right after the config phase; any mismatch fails closed as `BUNDLE_STALE` (error code 54) with the rebuild command in the message, before hooks, snapshots, or network checks run. No workflow path is exempt.
-- **Full-test freeze gate (R3)**: plan digests can no longer be computed unless the full test suite ran in this prepare; the gate sits before `computePlanDigest`, the `testSelection` value is validated against a schema enum in project and plan schemas, and no overlay switch can waive the freeze-path requirement.
-- **Frozen-release marker (R4)**: a successful prepare writes `.release-skill/FROZEN` carrying `planDigest`, `targetVersions` (unit → version), `createdAt`, and `runId`; the marker is removed only when verify reaches `VERIFIED`, giving sibling repositories and governance tasks a machine-readable signal to skip a repository mid-release.
+- **postPublish hooks v2 and six presets**: `releaseUnit.postPublish` now accepts a declarative `hooks` array alongside the existing `targets`; each hook is a named preset or a custom command hook following the prepare-hook rules (executable/argument arrays, relative cwd, timeout, environment allowlist — shell strings rejected). Six built-in presets ship with the bundle and are enumerated by `release-skill distribute --list-presets`: `git-mirror` and `marketplace-index-render` (declared in `targets` form), plus `proposal-inbox`, `marketplace-registry-entry`, `docs-refresh`, and `notify-handoff` (declared in `hooks` form); writing presets share `remoteUrl`/`workspace` dual downstream addressing, `proposal-inbox` without a target degrades to `notify-handoff` behavior instead of failing, and `notify-handoff` is the zero-write floor rendering a deterministic manual sync checklist. Every declaration is normalized into the frozen plan, so a hook change changes the plan digest and invalidates existing approvals; existing `targets` configurations stay valid with unchanged execution semantics.
+- **Checkpoint-level hook approval**: a hook with `requiresApproval: true` (the default for public-write presets; projects may tighten, never loosen) parks at `AWAITING_APPROVAL` with zero remote writes until its own checkpoint approval is minted with `release-skill approve --plan <plan> --hook <hookId> --actor <name>` and consumed via `distribute --hook-approval` or `ship --hook-approval`. Approval records follow the new `postpublish-approval-record` schema bound to `(planDigest, hookId)` with the 24-hour expiry; a hook configuration change changes the plan digest and invalidates the approval. The run schema gains the `AWAITING_APPROVAL` checkpoint status, and the approval interface displays the normalized entry summary of each approved hook.
+- **postVerify stage**: hooks declared with `phase: postVerify` run only after the main run reaches VERIFIED; `ship` routes them into an independent postVerify run whose hook context carries the verification evidence (`verifyEvidence`, present in this phase only). A failed postVerify run stays PARTIAL and can be reconciled, but it never rolls the main run back from VERIFIED — the failure is recorded prominently in evidence, never silently.
+- **Setup incremental hook proposal**: for already-configured projects, `setup --discover-downstream` performs read-only discovery of downstream candidates (git remotes, marketplace/docs repository clues, `artifact-graph` configuration, foundation profiles) and `setup --propose-hooks` drafts postPublish hook declarations for human review; after human confirmation of the `setupDigest` the flow appends only the hooks section and never rewrites any other part of the configuration. The create-once boundary is preserved: an existing configuration is never regenerated.
+- **Dogfood hub proposal declaration**: release-skill's own project configuration declares a `proposal-inbox` (git-push) hub-entry proposal toward the public `skill-family-hub` repository, delivered during this release's postVerify phase under its own checkpoint approval; delivery plus the deterministic manual sync prompt in evidence is the closure criterion — hub-side consumption is out of scope for this release.
+
+**Changed**
+
+- **Release-cycle speed optimizations (O1-O7)**: `build-adapters --check` and the self-bootstrap fact-pin suite are now fail-closed prepare pre-gates that run before hooks and the full-test gate (a fast pre-gate, not a replacement for full tests); a new one-click derived-artifact sync command validates and rebuilds the version/docs/bundle/adapters/manifest/public-files areas in dependency order and never writes src or test pins; `build-adapters --apply` is the supported rebuild path for existing drifted adapters; the `ship` happy end now orchestrates `prepare --production --online` by default with explicit remediation prompts for non-production and offline plans; online production prepare reports a warning-level observation when the local branch leads origin (non-blocking); `verify --run` accepts a run directory and resolves its `release-run.json` automatically (file form unchanged); and the `generate-platform-manifest --check` baseline drift is fixed.
+
+**Fixed**
+
+- **Production CLI distribute adapter registration**: both production CLI adapter registries now register the distribute-git adapter; before this fix the production `distribute`/`ship` auto-distribution path failed with `no distribute adapter registered`. The state-machine reference completes the `DISTRIBUTING`/`DISTRIBUTED` states and their transitions.
 <!-- release-skill:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **Current boundary:** v0.6.1 is the current source candidate; v0.4.1 remains
+> **Current boundary:** v0.6.3 is the current source candidate; v0.4.1 remains
 > the latest published release (v0.2.2 previously held
 > published status before the platform verification convergence fix was added).
 > v0.1.1 completed a real production release to GitHub and npm — the first
@@ -46,7 +55,7 @@ v0.6.1 closes the four root causes of the 0.6.0 self-bootstrap release cycle, in
 > publish global preflight.
 
 <!-- release-skill:capability:safe-first-command -->
-> **Production path verified since the v0.1.1 milestone; v0.6.1 is the current
+> **Production path verified since the v0.1.1 milestone; v0.6.3 is the current
 > source candidate and v0.4.1 is the latest published release.** The npm-installed CLI is the supported user entry. Source checkout
 > is the development/contributor fallback.
 >
@@ -59,6 +68,52 @@ v0.6.1 closes the four root causes of the 0.6.0 self-bootstrap release cycle, in
 > **Distribute maturity v1.0 (W2 closure):** postPublish distribution is available as a separate `distribute` command for mirror and marketplace-index actions. After `publish` reaches PUBLISHED status, run `ship distribute` or manually invoke `release-skill distribute --plan <path> --approval <path> --json`. The distribute action implements fail-closed semantics: NO_CHANGE on empty diff (no commit/tag/push), REMOTE_CONFLICT on tag move attempts (never force-push), AUTH_MISSING when external writes are not authorized. Supported modes: `--dry-run` (local commit+tag only), `--json` (structured output), `--help` (command reference). Tag commitment guarantees version consistency — distributed plugin.json.version must match input tag. See [docs/design/2026-08-17-postpublish-distribution.md](../../docs/design/2026-08-17-postpublish-distribution.md) for detailed architecture.
 <!-- release-skill:capability:distribute -->
 
+<!-- release-skill:maturity:postpublish-hooks-v2 -->
+<!-- release-skill:capability:postpublish-hooks -->
+> **postPublish hooks v2:** `releaseUnit.postPublish` accepts a declarative
+> `hooks` array alongside the existing `targets`. Each hook is either a named
+> preset or a custom command hook; custom command hooks follow the same rules
+> as prepare hooks — executable/argument arrays, relative cwd, timeout, and an
+> environment allowlist, with shell strings rejected — and, like all
+> configured hooks and gates, they run as unsandboxed processes. Every
+> declaration is normalized into the frozen plan, so a hook change changes the
+> plan digest and invalidates existing approvals. A hook with
+> `requiresApproval: true` (the default for public-write presets; projects may
+> tighten this, never loosen it) needs its own checkpoint-level approval
+> before execution: mint one with
+> `release-skill approve --plan <plan> --hook <hookId> --actor <name>`, then
+> consume it with `distribute --hook-approval <record>` or
+> `ship --hook-approval <record>` (24-hour expiry, bound to the plan digest
+> and the hook id). Git credentials come only from the host credential
+> helper / OS keychain; release-skill never reads, stores, or prints them.
+<!-- release-skill:capability:postpublish-hooks -->
+
+<!-- release-skill:capability:postpublish-presets -->
+> **postPublish presets:** six built-in presets ship with the bundle and are
+> enumerated by `release-skill distribute --list-presets`: `git-mirror` and
+> `marketplace-index-render` (declared in `targets` form), plus
+> `proposal-inbox`, `marketplace-registry-entry`, `docs-refresh`, and
+> `notify-handoff` (declared in `hooks` form). `proposal-inbox` delivers a
+> machine-readable update proposal through a git-push or local-file transport
+> for autonomous downstream consumption; without a target it degrades to
+> `notify-handoff` behavior instead of failing. `notify-handoff` is the
+> zero-write floor: it only renders a deterministic manual sync checklist.
+> release-skill dogfoods this capability: this repository's own project
+> configuration declares a `proposal-inbox` (git-push) hub-entry proposal
+> toward the public `skill-family-hub` repository, to be delivered during the
+> v0.6.3 release in the postVerify phase under its own checkpoint approval.
+<!-- release-skill:capability:postpublish-presets -->
+
+<!-- release-skill:capability:postverify-stage -->
+> **postVerify stage:** hooks declared with `phase: postVerify` run only after
+> the main run reaches VERIFIED; `ship` routes them into an independent
+> postVerify run whose hook context carries the verification evidence
+> (`verifyEvidence`, present in this phase only). A failed postVerify run
+> stays PARTIAL and can be reconciled, but it never rolls the main run back
+> from VERIFIED — the failure is recorded prominently in evidence, never
+> silently.
+<!-- release-skill:capability:postverify-stage -->
+
 <!-- release-skill:maturity:v0.1-boundary -->
 <!-- release-skill:maturity:boundary -->
 > **Safe defaults:** the recommended path is `help → assess → prepare --offline →
@@ -197,6 +252,17 @@ ACTOR=your-name
    Add a project-specific hook or gate only after human review: edit
    `projectConfig.hooks`, or edit `verificationGates` and add the same id to
    `selectedGateIds`, then rerun the bound dry-run.
+   Downstream postPublish guidance is also read-only until confirmed:
+   `setup --discover-downstream` enumerates downstream candidates (git
+   remotes, neighboring marketplace/docs repositories,
+   `artifact-graph.config.yaml`, and a foundation profile when present), and
+   `setup --propose-hooks` turns those cues into postPublish hook declaration
+   drafts bound by a `setupDigest`. For an already-configured project,
+   `setup --propose-hooks --write --confirm-setup <digest>` appends only the
+   target release unit's `postPublish.hooks` block and never regenerates or
+   rewrites any other part of the configuration (create-once is untouched). A
+   foundation profile is one proposal input among several and never
+   auto-applies.
    See [INSTALL.md](INSTALL.md#first-use-setup) for the full multi-step flow.
 3. **assess** — read-only readiness:
    ```bash
@@ -477,6 +543,60 @@ Hooks run when `prepare` is invoked; the command call itself authorizes
 execution. Gates are the controlled extension point for release calibration
 (see `references/02-project-config.md`).
 
+### postPublish hooks
+
+`postPublish.hooks` declares downstream delivery actions that run after
+`publish`; each entry is a named preset or a custom command hook and follows
+the same command rules as above (executable/argument arrays, not shell
+strings). Presets receive a read-only projection of the frozen plan; custom
+command hooks run in the frozen tag worktree:
+
+```yaml
+postPublish:
+  materialize:
+    command: [node, scripts/materialize-payload.mjs]
+    cwd: .
+    timeoutMs: 600000
+    outputMarker: "payload dir: "
+  commitIdentity:
+    name: release-bot
+    email: mzdbxqh@example.com
+  hooks:
+    - id: mirror-downstream
+      preset: git-mirror
+      config:
+        target:
+          remoteUrl: https://gitlab.example.internal/team/my-project.git
+          branch: main
+    - id: hub-entry-proposal
+      preset: proposal-inbox
+      phase: postVerify
+      requiresApproval: true
+      config:
+        delivery: git-push
+        target:
+          remoteUrl: https://github.com/example/hub.git
+          branch: main
+    - id: custom-notify
+      command: [node, scripts/notify-downstream.mjs]
+      timeoutMs: 300000
+      envAllowlist: [CI]
+```
+
+A hook with `requiresApproval: true` parks at `AWAITING_APPROVAL` until a
+checkpoint approval is minted and consumed. The approval record is bound to
+the plan digest and the hook id, and expires after 24 hours:
+
+```bash
+release-skill approve --plan "$PLAN_PATH" --hook hub-entry-proposal --actor "$ACTOR" --json
+release-skill ship --root "$PROJECT" --hook-approval "$HOOK_APPROVAL_PATH" --json
+```
+
+For an already-configured project, `setup --discover-downstream` and
+`setup --propose-hooks` draft these declarations for human review; the
+append-only incremental flow is described in the setup step above and in
+[INSTALL.md](INSTALL.md#first-use-setup).
+
 ## Skills
 
 - `release-help`: environment check and next-step guidance.

package/README.zh-CN.md

@@ -2,26 +2,35 @@
 
 [English](README.md) · 安装指南：[中文](INSTALL.zh-CN.md) / [English](INSTALL.md)
 
-<!-- release-skill:release-version: 0.6.1 -->
+<!-- release-skill:release-version: 0.6.3 -->
 面向 Claude Code、CodeBuddy、WorkBuddy、Codex 和 Kimi Code 的发布准备工具，完整保留人工维护的文件内容。
 
 release-skill 帮助维护者回答三个问题：准备发布什么、还有哪些检查未通过、最终发布的内容是什么。它不重新生成、也不回写项目源文件。`prepare` 把每个配置的公开文件复制到隔离快照并验证字节——先冻结并供人工审阅，再从同一份冻结产物发布。`setup` 只显示确定性的 `compactSummary` 审阅视图，完整报告保留在临时会话目录中。
 
 <!-- release-skill:managed:start id=latest-release -->
-**0.6.1** (2026-08-18)
+**0.6.3** (2026-08-20)
 
-v0.6.1 收口 0.6.0 自举发布周期暴露的四个根因——该周期 25 次运行中 22 次失败，几乎全部墙钟时间消耗在失败-诊断-修复循环与外部干扰上：hook 失败不再无声、陈旧 bundle 在最早期门禁失败关闭、冻结路径不可能跳过全量测试、机器可读的冻结标记让兄弟仓库的治理任务知道发布期间不要写入本仓库。
+v0.6.3 新增 postPublish hooks v2 注册机制与六个内置预设、面向下游写 hook 的 checkpoint 级批准记录、只在主 run 到达 VERIFIED 后执行 hook 的 postVerify 阶段、为已接入项目起草 postPublish hook 声明的 setup 增量提案、O1–O7 发布周期提速，以及 release-skill 自身的 dogfood hub 提案声明——本次发布即在 postVerify 阶段经自身 checkpoint 批准向公开的 skill-family-hub 仓库投递该提案。
 
 **新增**
 
-- **hook 失败输出透传（R1）**：prepare hook 非零退出时，运行证据携带有界的 `stderrTail` / `stdoutTail` 投影（最后 50 行、上限 8 KiB），CLI 同时回显 stderr 尾部——裸 `exit=13` 这类失败从此可即时诊断，不再需要盲目重试。exit code 语义不变。
-- **bundle 陈旧度门禁（R2）**：每次重建的 bundle 内嵌其源码树冻结摘要，prepare 在 config 阶段之后立即比对源码与 bundle；不一致即以 `BUNDLE_STALE`（错误码 54）失败关闭并在消息中给出重建命令，先于 hooks、快照与网络检查执行。任何工作流路径都不可豁免。
-- **全量测试冻结门禁（R3）**：本次 prepare 未跑全量测试就无法产生计划摘要；门禁位于 `computePlanDigest` 之前，`testSelection` 取值在 project 与 plan schema 中按枚举校验，overlay 无豁免开关。
-- **发布冻结标记（R4）**：prepare 成功后写入 `.release-skill/FROZEN`，内容为 `planDigest`、`targetVersions`（unit → 版本映射）、`createdAt`、`runId`；仅当 verify 到达 `VERIFIED` 时才清除，为兄弟仓库与治理任务提供机器可读的发布期回避信号。
+- **postPublish hooks v2 与六个预设**：`releaseUnit.postPublish` 在既有 `targets` 之外接受声明式 `hooks` 数组；每个 hook 要么是命名预设，要么是遵循 prepare hooks 规则（可执行文件/参数数组、相对 cwd、timeout、环境变量白名单——拒绝 shell 字符串）的自定义 command hook。六个内置预设随 bundle 分发，由 `release-skill distribute --list-presets` 枚举：`git-mirror` 与 `marketplace-index-render`（以 `targets` 形态声明），以及 `proposal-inbox`、`marketplace-registry-entry`、`docs-refresh`、`notify-handoff`（以 `hooks` 形态声明）；写下游预设共用 `remoteUrl`/`workspace` 双寻址，`proposal-inbox` 未声明 target 时退化为 `notify-handoff` 行为而非报错，`notify-handoff` 是零写地板，只渲染确定性的人工同步清单。所有声明归一化进冻结计划，hook 变化即 plan digest 变化，既有批准随之失效；既有 `targets` 配置原样可用，执行语义不变。
+- **checkpoint 级 hook 批准**：`requiresApproval: true` 的 hook（公开写预设缺省为 true；项目可以收紧，不得放松）停留 `AWAITING_APPROVAL`、零远端写，直到用 `release-skill approve --plan <plan> --hook <hookId> --actor <name>` 铸造并经 `distribute --hook-approval` 或 `ship --hook-approval` 消费自己的 checkpoint 批准。批准记录遵循新的 `postpublish-approval-record` schema，绑定 `(planDigest, hookId)`，24 小时有效；hook 配置变化即 plan digest 变化，批准随之失效。run schema 新增 `AWAITING_APPROVAL` checkpoint 状态，批准界面展示被批准 hook 的归一化条目摘要。
+- **postVerify 阶段**：声明 `phase: postVerify` 的 hook 只在主 run 到达 VERIFIED 之后执行；`ship` 把它们路由进一个独立的 postVerify run，其 hook 上下文携带验证证据（`verifyEvidence` 仅该阶段存在）。postVerify run 失败即保持 PARTIAL、可 reconcile，但绝不把主 run 从 VERIFIED 回退——失败在 evidence 中显著记录，绝不静默。
+- **setup 增量 hook 提案**：面向已接入项目，`setup --discover-downstream` 只读发现下游候选（git remote、marketplace/docs 仓线索、`artifact-graph` 配置、foundation profile），`setup --propose-hooks` 起草 postPublish hook 声明供人工审阅；人工确认 `setupDigest` 后只追加 hooks 段，绝不重写既有配置的任何其他部分。create-once 边界保持：既有配置绝不重新生成。
+- **dogfood hub 提案声明**：release-skill 自身的项目配置声明了一个 `proposal-inbox`（git-push）hub 提案，指向公开仓 `skill-family-hub`，在本次发布的 postVerify 阶段经自身 checkpoint 批准投递；投递成功加 evidence 中的确定性人工同步提示即闭环——hub 侧消费不在本期范围。
+
+**变更**
+
+- **发布周期提速（O1–O7）**：`build-adapters --check` 与 self-bootstrap 事实钉套件成为 prepare 快速前置门禁，先于 hooks 与全量测试门禁执行（快速前置，不替代全量测试）；新增派生产物一键同步命令，按依赖顺序校验并按需重建 version/docs/bundle/adapters/manifest/public-files 各区，绝不写 src 与测试钉；`build-adapters --apply` 成为既有漂移 adapter 的受支持重建路径；`ship` happy-end 编排缺省 `prepare --production --online`，非生产与 offline 计划给出明确补救提示；online production prepare 在本地分支领先 origin 时给出 warning 级观测（不阻塞）；`verify --run` 接受 run 目录并自动解析其中的 `release-run.json`（传文件行为不变）；修复 `generate-platform-manifest --check` 的基线漂移。
+
+**修复**
+
+- **生产 CLI distribute adapter 注册**：两处生产 CLI adapter 注册表现在都注册 distribute-git adapter；修复前生产 `distribute`/`ship` 自动分发路径以 `no distribute adapter registered` 失败。状态机参考件补全 `DISTRIBUTING`/`DISTRIBUTED` 状态及其转移。
 <!-- release-skill:managed:end id=latest-release -->
 
 <!-- release-skill:capability:external-write-boundary -->
-> **当前边界：** v0.6.1 是当前源码候选，v0.4.1 仍是最新已发布版本（v0.2.2 曾处于已发布状态，后因平台验证收敛修复而更新）。
+> **当前边界：** v0.6.3 是当前源码候选，v0.4.1 仍是最新已发布版本（v0.2.2 曾处于已发布状态，后因平台验证收敛修复而更新）。
 > v0.1.1 已完成 GitHub 与 npm 的
 > 真实生产发布，是首次生产验证的历史里程碑，并从冻结 Git ref 完成精确 npm
 > 安装及 Claude/Codex 消费者安装验证；"当前发布版本"与"首次生产验证里程碑"
@@ -34,7 +43,7 @@ v0.6.1 收口 0.6.0 自举发布周期暴露的四个根因——该周期 25
 > 远端唯一性检查在 `publish` 全局预检执行。
 
 <!-- release-skill:capability:safe-first-command -->
-> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.6.1 是当前源码候选，v0.4.1 是最新已发布版本。**
+> **生产路径自 v0.1.1 里程碑起已完成真实生产验证；v0.6.3 是当前源码候选，v0.4.1 是最新已发布版本。**
 > npm 安装的 CLI 是受支持的用户入口；源码 checkout 保留为开发/贡献者路径。
 >
 > **第一条命令：**
@@ -46,6 +55,45 @@ v0.6.1 收口 0.6.0 自举发布周期暴露的四个根因——该周期 25
 > **分发能力 v1.0（W2 完成）：** postPublish 分发作为独立的 `distribute` 命令可用，支持镜像和 Marketplace 索引动作。`publish` 达到 PUBLISHED 状态后，可运行 `ship distribute` 或手动调用 `release-skill distribute --plan <path> --approval <path> --json`。分发动作实现 fail-closed 语义：空差异时 NO_CHANGE（不创建 commit/tag/push），tag 移动尝试时 REMOTE_CONFLICT（永不 force-push），外部写未授权时 AUTH_MISSING。支持的模式：`--dry-run`（仅本地提交+tag）、`--json`（结构化输出）、`--help`（命令参考）。标签承诺保证版本一致性——分发的 plugin.json.version 必须与输入 tag 匹配。详见 [docs/design/2026-08-17-postpublish-distribution.md](../../docs/design/2026-08-17-postpublish-distribution.md) 中的架构说明。
 <!-- release-skill:capability:distribute -->
 
+<!-- release-skill:maturity:postpublish-hooks-v2 -->
+<!-- release-skill:capability:postpublish-hooks -->
+> **postPublish hooks v2：** `releaseUnit.postPublish` 在既有 `targets` 之外接受
+> 声明式 `hooks` 数组。每个 hook 要么是命名预设，要么是自定义 command hook；
+> 自定义 command hook 遵循与 prepare hooks 相同的规则——可执行文件/参数数组、
+> 相对 cwd、timeout 与环境变量白名单，拒绝 shell 字符串——并与其他配置的
+> hook 和 gate 一样是无操作系统沙箱的进程。所有声明归一化进冻结计划，因此
+> hook 变化即 plan digest 变化，既有批准随之失效。`requiresApproval: true`
+> 的 hook（公开写预设缺省为 true；项目可以收紧，不得放松）执行前需要自己的
+> checkpoint 级批准：用
+> `release-skill approve --plan <plan> --hook <hookId> --actor <name>`
+> 铸造批准记录，再由 `distribute --hook-approval <record>` 或
+> `ship --hook-approval <record>` 消费（24 小时有效期，绑定 plan digest
+> 与 hook id）。Git 凭证只来自宿主 credential helper / OS keychain；
+> release-skill 绝不读取、存储或打印凭证。
+<!-- release-skill:capability:postpublish-hooks -->
+
+<!-- release-skill:capability:postpublish-presets -->
+> **postPublish 预设：** 六个内置预设随 bundle 分发，由
+> `release-skill distribute --list-presets` 枚举：`git-mirror` 与
+> `marketplace-index-render`（以 `targets` 形态声明），以及
+> `proposal-inbox`、`marketplace-registry-entry`、`docs-refresh`、
+> `notify-handoff`（以 `hooks` 形态声明）。`proposal-inbox` 通过 git-push 或
+> local-file 传输投递机器可读更新提案，供下游自治消费；未声明 target 时
+> 退化为 `notify-handoff` 行为而非报错。`notify-handoff` 是零写地板：
+> 只渲染确定性的人工同步清单。release-skill 自己也在使用该能力：本仓库的
+> 项目配置声明了一个 `proposal-inbox`（git-push）hub 提案，指向公开仓
+> `skill-family-hub`，将在 v0.6.3 发布的 postVerify 阶段经自身的
+> checkpoint 批准投递。
+<!-- release-skill:capability:postpublish-presets -->
+
+<!-- release-skill:capability:postverify-stage -->
+> **postVerify 阶段：** 声明 `phase: postVerify` 的 hook 只在主 run 到达
+> VERIFIED 之后执行；`ship` 把它们路由进一个独立的 postVerify run，其 hook
+> 上下文携带验证证据（`verifyEvidence` 仅该阶段存在）。postVerify run 失败
+> 即保持 PARTIAL、可 reconcile，但绝不把主 run 从 VERIFIED 回退——失败在
+> evidence 中显著记录，绝不静默。
+<!-- release-skill:capability:postverify-stage -->
+
 <!-- release-skill:maturity:v0.1-boundary -->
 <!-- release-skill:maturity:boundary -->
 > **安全默认路径：** 推荐 `help → assess → prepare --offline → 人工审阅`。
@@ -177,6 +225,15 @@ ACTOR=your-name
    `requiredPublicFiles`。只有在人工审阅之后才添加项目专属 hook 或 gate：
    编辑 `projectConfig.hooks`，或编辑 `verificationGates` 并把同一个 id 加入
    `selectedGateIds`，然后重新运行绑定 dry-run。配置已存在时跳过。
+   下游 postPublish 引导在确认前同样只读：`setup --discover-downstream`
+   枚举下游候选（git remote、邻近的 marketplace/docs 仓、
+   `artifact-graph.config.yaml`，以及存在时的 foundation profile）；
+   `setup --propose-hooks` 把这些线索转为由 `setupDigest` 绑定的 postPublish
+   hook 声明草案。对已接入的项目，
+   `setup --propose-hooks --write --confirm-setup <digest>` 只追加目标发布
+   单元的 `postPublish.hooks` 段，绝不重新生成或改写配置的任何其他部分
+   （create-once 边界不受影响）。foundation profile 只是提案输入之一，绝不
+   自动生效。
    完整多步流程见 [INSTALL.zh-CN.md](INSTALL.zh-CN.md#首次接入)。
 3. **assess** — 只读就绪评估：
    ```bash
@@ -431,6 +488,51 @@ hooks:
 
 hook 在 `prepare` 调用时运行，命令调用本身即授权执行。gate 是发布校准的受控扩展点（见 `references/02-project-config.md`）。
 
+### postPublish hook
+
+`postPublish.hooks` 声明 `publish` 之后执行的下游投递动作。每个条目要么是命名预设，要么是自定义 command hook，遵守与上文相同的命令规则（可执行文件/参数数组，不是 shell 字符串）。预设收到冻结计划的只读投影；自定义 command hook 在冻结 tag 工作树中执行：
+
+```yaml
+postPublish:
+  materialize:
+    command: [node, scripts/materialize-payload.mjs]
+    cwd: .
+    timeoutMs: 600000
+    outputMarker: "payload dir: "
+  commitIdentity:
+    name: release-bot
+    email: mzdbxqh@example.com
+  hooks:
+    - id: mirror-downstream
+      preset: git-mirror
+      config:
+        target:
+          remoteUrl: https://gitlab.example.internal/team/my-project.git
+          branch: main
+    - id: hub-entry-proposal
+      preset: proposal-inbox
+      phase: postVerify
+      requiresApproval: true
+      config:
+        delivery: git-push
+        target:
+          remoteUrl: https://github.com/example/hub.git
+          branch: main
+    - id: custom-notify
+      command: [node, scripts/notify-downstream.mjs]
+      timeoutMs: 300000
+      envAllowlist: [CI]
+```
+
+`requiresApproval: true` 的 hook 停留在 `AWAITING_APPROVAL`，直到 checkpoint 批准被铸造并消费。批准记录绑定 plan digest 与 hook id，24 小时后过期：
+
+```bash
+release-skill approve --plan "$PLAN_PATH" --hook hub-entry-proposal --actor "$ACTOR" --json
+release-skill ship --root "$PROJECT" --hook-approval "$HOOK_APPROVAL_PATH" --json
+```
+
+对已接入的项目，`setup --discover-downstream` 与 `setup --propose-hooks` 起草这些声明供人工审阅；仅追加的增量流程见上文 setup 步骤与 [INSTALL.zh-CN.md](INSTALL.zh-CN.md#首次接入)。
+
 ## Skills
 
 - `release-help`：环境检查和下一步引导。