release-skill 0.6.1 → 0.6.3

package/package.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": "广州市风荷科技有限公司"
@@ -65,6 +65,7 @@
     "sync:public-files:check": "node scripts/sync-public-files.mjs --check",
     "build:adapters": "node scripts/build-adapters.mjs",
     "build:adapters:check": "node scripts/build-adapters.mjs --check",
+    "build:adapters:apply": "node scripts/build-adapters.mjs --apply",
     "build:bundle": "node scripts/build-bundle.mjs",
     "build:bundle:check": "node scripts/build-bundle.mjs --check",
     "native:build": "node-gyp rebuild --directory native/safe-write",

package/platform-manifest.json

@@ -2,11 +2,11 @@
   "schemaVersion": "1.0.0",
   "platformId": "release-skill",
   "platformName": "release-skill Plugin Platform",
-  "version": "0.6.0",
+  "version": "0.6.3",
   "logicalRoot": "skills-src/",
-  "logicalRootDigest": "6d504094e1bf7d38beb6d886ff48ea442e7563b6061a7145a14c2d71a60292f5",
-  "projectionDigest": "2ca5c5d0b71e10622911426d3abf9c0dfae72237ee6001d4eaaada90acb7a0d7",
-  "projectionId": "release-skill:platform:0.6.0",
+  "logicalRootDigest": "3767fc36f42ca561f5e839cea7b7e5bc16d08c47867b5bd6086f25efd0cb0f06",
+  "projectionDigest": "419f7f9601015459956e10aae74f42240ab2ac248238ff7494f3e761643d1749",
+  "projectionId": "release-skill:platform:0.6.3",
   "manifestRequired": true,
   "projectionSources": {
     "skills-src-root": {

package/references/.render-manifest.json

@@ -1,13 +1,13 @@
 {
-  "source": "references",
+  "source": "standards",
   "files": {
     "00-target-state.md": {
       "digest": "d66f8c33b2df2bbcb235ce123f786c18c19b3a797197495793d9af566618099d",
       "bytes": 6335
     },
     "01-state-machine.md": {
-      "digest": "4698e3763f76774798e269ae163fcf87ba8ca358a9638c5bff693f5921455f9f",
-      "bytes": 9114
+      "digest": "711265e093be13f582ac8be89c391eff79ac22f56c25b91d1ccaef31856ef269",
+      "bytes": 12086
     },
     "02-project-config.md": {
       "digest": "f866490d5897c2baf38fd3a6770964c052bea4418f034b75965ecfe49c2f4387",
@@ -22,8 +22,8 @@
       "bytes": 4682
     },
     "05-evidence-and-errors.md": {
-      "digest": "3df7644a6db614ee5f67689834f97227752834cf6c27762dee66650675c34168",
-      "bytes": 11592
+      "digest": "f1352256e3b9e2c96c1aa6689fa921a909ab41f80832c5a3356a10590b640929",
+      "bytes": 12014
     },
     "06-adapter-contract.md": {
       "digest": "4b1ec9ba843345df47c1d133a8bf1aa644bf12a4ecf760cb1d566a43f1e9a9d2",

package/references/01-state-machine.md

@@ -6,7 +6,7 @@
 
 ## 1. 状态定义
 
-发布生命周期包含 7 个主状态和 3 个异常状态，共计 10 个状态。
+发布生命周期包含 9 个主状态和 3 个异常状态，共计 12 个状态。
 
 ### 1.1 主状态
 
@@ -18,6 +18,8 @@
 | **APPROVED** | 人工审阅并批准了冻结的发布计划 | 批准记录绑定到发布计划 hash，且未过期 |
 | **PUBLISHING** | 外部写操作正在按检查点依次执行 | `publish` 命令读取已批准计划并开始执行 |
 | **PUBLISHED** | 所有发布检查点均已成功完成 | 最后一个检查点的 `observe` 验证通过 |
+| **DISTRIBUTING** | 发布后分发正在执行：载荷物化、目标镜像推送与 distribute 阶段 postPublish hooks 按检查点依次进行 | 计划声明 `postPublish`（targets 或 hooks），`ship` 路由到 `distribute` 并通过全部安全门后开始执行 |
+| **DISTRIBUTED** | 分发完成：全部目标与 distribute 阶段 hooks 成功（或远端已一致而幂等跳过） | `distribute` run 无失败且无待批准检查点 |
 | **VERIFIED** | 发布后验证全部通过 | `verify` 命令在全新环境中完成安装、调用、泄漏审计和远端一致性校验 |
 
 ### 1.2 异常状态
@@ -48,7 +50,15 @@
 | PUBLISHING | PUBLISHED | 所有检查点成功 |
 | PUBLISHING | PARTIAL | 至少一个检查点成功但后续失败 |
 | PUBLISHING | BLOCKED | 外部服务阻断且无法继续 |
-| PUBLISHED | VERIFIED | `verify` 的远端、npm、Claude/Codex 等自动化检查全部通过；新计划中的 Kimi/CodeBuddy 人工安装任务不由系统核验且不阻塞该状态 |
+| PUBLISHED | DISTRIBUTING | 计划声明 `postPublish`（targets 或 hooks），`ship` 路由到 `distribute` 开始执行 |
+| PUBLISHED | VERIFIED | 无 `postPublish` 声明时，`verify` 的远端、npm、Claude/Codex 等自动化检查全部通过（Kimi/CodeBuddy 人工安装任务不由系统核验且不阻塞）；声明了 `postPublish` 时必须先经 DISTRIBUTING/DISTRIBUTED 门禁 |
+| DISTRIBUTING | DISTRIBUTED | 全部目标与 distribute 阶段 hooks 成功（或远端已一致幂等跳过），且无待批准检查点 |
+| DISTRIBUTING | PARTIAL | 至少一个外部 checkpoint 已成功后，目标/hooks 失败或存在待批准 checkpoint |
+| DISTRIBUTING | NEEDS_INPUT | `requiresApproval` hook 缺少 checkpoint 级批准，且尚无任何外部副作用 |
+| DISTRIBUTING | BLOCKED | 零外部写入落地且安全门或 hook 失败（失败关闭） |
+| DISTRIBUTED | VERIFIED | `verify` 的 distribute 门禁通过：存在 DISTRIBUTED（或经 `blocksVerified:false` 合法豁免的 PARTIAL）分发 run，且安装/远端校验全部通过 |
+| NEEDS_INPUT | DISTRIBUTING | checkpoint 批准补齐后重跑 `distribute` |
+| PARTIAL | DISTRIBUTING | `distribute` 重跑即 reconcile：跳过已一致目标，仅重跑安全未完成项 |
 | PUBLISHED | POST_PUBLISH_VERIFY_FAILED | 发布后验证失败（保留 PUBLISHED 事实但标记验证失败） |
 | NEEDS_INPUT | DISCOVERED | 用户提供输入后重新开始评估 |
 | NEEDS_INPUT | ASSESSED | 用户提供输入后恢复评估 |
@@ -66,6 +76,14 @@
 - APPROVED -> PREPARED：当 plan digest、目标版本或已批准 action 列表变化时，批准自动失效。planVersion 2 计划的 digest 只绑定信任边界（冻结产物身份、动作列表、目标版本、配置摘要），工作区基线（Git tree hash、workspace digest）是记录层审计数据，不使批准失效；planVersion 1（旧版）计划维持旧规则，Git tree hash 与 workspace digest 变化同样使批准失效。
 - PUBLISHING -> PARTIAL：当任一检查点成功后下一检查点失败时，自动计算 PARTIAL 状态。
 
+### 2.2 分发阶段与 postVerify 阶段（v0.6.3）
+
+postPublish hooks 分两个阶段，各自对应独立的 distribute run：
+
+- **distribute 阶段**（默认 `phase: distribute`）：在 DISTRIBUTING 中执行，载荷只能来自冻结 tagCommit 的 detached worktree（时序契约）。全部目标与 distribute 阶段 hooks 成功后进入 DISTRIBUTED；`verify` 在到达 VERIFIED 前检查 distribute 门禁——存在未 SUCCEEDED 且未经 `blocksVerified: false` 合法豁免的 hook 时不得 VERIFIED。NEEDS_INPUT/BLOCKED 不得静默转 VERIFIED（承袭治理规则）。
+- **postVerify 阶段**（`phase: postVerify`）：主 run VERIFIED 后由 ship/verify 路由触发，产出独立的 distribute run（复用现有 run 记录与 checkpoint 机制）；失败即该 run PARTIAL、reconcile 可续。主 run 的 VERIFIED 不回退，但 postVerify run 的失败必须以证据显著记录，绝不静默。
+- **checkpoint 级批准**：`requiresApproval: true` 的 hook 执行前需要绑定 `(planDigest, hookId)` 的独立批准记录（24h 过期、5 分钟时钟偏移容忍）。批准未获时：尚无外部 checkpoint 成功 → checkpoint 标记 `AWAITING_APPROVAL`、run 进 NEEDS_INPUT；已有外部 checkpoint 成功 → run 保持 PARTIAL。
+
 ---
 
 ## 3. 禁止转换
@@ -84,6 +102,8 @@
 | APPROVED -> VERIFIED | 不能跳过发布直接验证 |
 | APPROVED -> PUBLISHED | 不能跳过发布执行直接到已发布 |
 | PUBLISHING -> VERIFIED | 发布完成后必须先到 PUBLISHED |
+| DISTRIBUTING -> VERIFIED | 分发必须先达 DISTRIBUTED 再经 verify distribute 门禁 |
+| DISTRIBUTING -> APPROVED | 分发进行中不能回退到批准 |
 | PUBLISHING -> APPROVED | 发布进行中不能回退到批准 |
 | PUBLISHING -> PREPARED | 发布进行中不能回退到准备 |
 | PUBLISHED -> PUBLISHING | 已发布的不能重新发布同一计划 |

package/schemas/.render-manifest.json

@@ -21,17 +21,21 @@
       "digest": "b7e14522a5aba818cab191545f23d2323be0e4c80566e9d3e4da576103a00490",
       "bytes": 2390
     },
+    "postpublish-approval-record.schema.json": {
+      "digest": "e365c9e9f5aa189ca6788e68dbedfa718aa120f2c197534417c21e019b9a29a4",
+      "bytes": 1744
+    },
     "release-plan.schema.json": {
-      "digest": "5e988a5301b89b3d3260154ffae12669af0e4d6ec7f9db8c44df21037ea0eaf6",
-      "bytes": 46948
+      "digest": "517ac9b1d92d2bf348497ee0e79c9e474a4c60e6ed8ba77830948716d143dfa2",
+      "bytes": 49369
     },
     "release-project.schema.json": {
-      "digest": "546e05845cd83a3b1db0a54036f9555081420337e9df961d783d2d2630800ef7",
-      "bytes": 41898
+      "digest": "d38649d1dc9b1dbc643f4e2c98fd18d111090e9ce221c9c61fa50245f6c4c232",
+      "bytes": 45715
     },
     "release-run.schema.json": {
-      "digest": "6dd239c59f7045df11d13d6ba2027610d3c55c27a6af5bc87676b0eaad9600fd",
-      "bytes": 17663
+      "digest": "a605db801d6994d657049431ad453233974bd10610b7b447b196136bb0692866",
+      "bytes": 17847
     }
   }
 }

package/schemas/postpublish-approval-record.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://release-skill.dev/schemas/postpublish-approval-record/v1",
+  "title": "PostPublish Hook Approval Record",
+  "description": "Schema for checkpoint-level approval of a requiresApproval postPublish hook (v0.6.3 R1, design §2.7 ruling 2). Binds the approval to (planDigest, hookId); the plan-level approval-record schema is untouched. runId is audit-only and never participates in binding or validation semantics.",
+  "type": "object",
+  "required": [
+    "planDigest",
+    "hookId",
+    "actor",
+    "approvedAt",
+    "expiresAt"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "planDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the frozen release plan whose postPublish hooks block this approval binds to"
+    },
+    "hookId": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "id of the requiresApproval postPublish hook being approved (must be declared in the frozen plan)"
+    },
+    "actor": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Identity of the approver"
+    },
+    "approvedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when approval was granted"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when approval expires (max 24h after approvedAt; 5-minute clock skew tolerated at validation)"
+    },
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Audit-only identifier of the distribute run present when approval was granted; never a binding"
+    }
+  }
+}

package/schemas/release-plan.schema.json

@@ -863,6 +863,13 @@
               "findingCount": {
                 "const": 0
               },
+              "preparedAt": {
+                "type": ["string", "null"],
+                "description": "Deterministic freeze timestamp of the prepare run that produced this receipt (production: the baseline HEAD commit committer date in canonical UTC form; non-production: null). Never a wall-clock sample, so identical sources freeze byte-identical receipts."
+              },
+              "exitCode": {
+                "const": 0
+              },
               "receiptDigest": {
                 "type": "string",
                 "pattern": "^[a-f0-9]{64}$"
@@ -877,6 +884,8 @@
               "referenceCount",
               "sourceOnlyCount",
               "findingCount",
+              "preparedAt",
+              "exitCode",
               "receiptDigest"
             ]
           }
@@ -1298,7 +1307,6 @@
       "description": "冻结的发布后分发块：声明本身 + tag/tagCommit/unitId/payloadSource 绑定。整体参与 plan digest（planVersion 2 记录层剥离不包含该块），任何配置变更都会改变 planDigest。tagCommit 仅在 prepare 能冻结 create-tag 预期 commit 时存在（production 资产）；缺省时 distribute fail-closed。",
       "required": [
         "materialize",
-        "targets",
         "commitIdentity",
         "tag",
         "unitId",
@@ -1316,6 +1324,13 @@
             "$ref": "#/definitions/planPostPublishTarget"
           }
         },
+        "hooks": {
+          "type": "array",
+          "description": "冻结的发布后钩子声明（v0.6.3 R1）；随整块参与 plan digest",
+          "items": {
+            "$ref": "#/definitions/planPostPublishHook"
+          }
+        },
         "commitIdentity": {
           "type": "object",
           "required": [
@@ -1364,6 +1379,64 @@
         }
       }
     },
+    "planPostPublishHook": {
+      "type": "object",
+      "description": "冻结的发布后钩子声明项（v0.6.3 R1）：preset 与 command 运行时互斥；phase 缺省 distribute；blocksVerified 缺省 true 且仅 preset 可声明 false",
+      "required": [
+        "id"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "preset": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "distribute",
+            "postVerify"
+          ]
+        },
+        "config": {
+          "type": "object"
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true
+        },
+        "requiresApproval": {
+          "type": "boolean"
+        },
+        "blocksVerified": {
+          "type": "boolean"
+        }
+      }
+    },
     "planPostPublishMaterialize": {
       "type": "object",
       "required": [

package/schemas/release-project.schema.json

@@ -889,7 +889,6 @@
       "description": "发布后分发声明：materialize 钩子从冻结 tag 工作树物化载荷，targets 将载荷镜像或渲染市场索引推送到独立 git 远端。分发在 publish 之后由 distribute 命令执行，时序契约禁止读取工作区状态。",
       "required": [
         "materialize",
-        "targets",
         "commitIdentity"
       ],
       "additionalProperties": false,
@@ -904,6 +903,13 @@
             "$ref": "#/definitions/postPublishTarget"
           }
         },
+        "hooks": {
+          "type": "array",
+          "description": "发布后钩子声明（v0.6.3 R1）：每项为命名 preset（+config）或自定义 command 钩子（executable+参数数组，禁止 shell 字符串）。schema 层只校验形状；preset 与 command 互斥、preset 注册表归属等语义在运行时 fail-closed 校验（POSTPUBLISH_HOOK_INVALID）",
+          "items": {
+            "$ref": "#/definitions/postPublishHook"
+          }
+        },
         "commitIdentity": {
           "type": "object",
           "description": "分发仓库提交者身份（bot 身份），通过 git -c user.name/-c user.email 注入，绝不读取或修改全局 git 配置",
@@ -936,6 +942,72 @@
         }
       }
     },
+    "postPublishHook": {
+      "type": "object",
+      "description": "发布后钩子声明项：preset（命名预设 + config）与 command（自定义命令）在运行时互斥校验；phase 缺省为 distribute（VERIFIED 之前执行），postVerify 在 verify 通过后作为独立 run 执行（R3）；blocksVerified 缺省 true，仅 preset 可声明 false",
+      "required": [
+        "id"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "preset": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "description": "预设注册表中的预设名（R2 起）；R1 无注册表，任何 preset 引用在运行时 fail-closed"
+        },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          },
+          "description": "executable+参数数组（禁止 shell 字符串）；在冻结 tag 工作树中执行"
+        },
+        "phase": {
+          "type": "string",
+          "enum": [
+            "distribute",
+            "postVerify"
+          ],
+          "description": "执行阶段；缺省 distribute"
+        },
+        "config": {
+          "type": "object",
+          "description": "preset 钩子的配置对象；语义由预设注册表校验（R2 起）"
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$",
+          "description": "command 钩子执行目录（相对冻结 tag 工作树）；preset 钩子禁止声明（运行时 fail-closed）"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true,
+          "description": "允许透传给钩子进程的环境变量白名单；TOKEN/SECRET 等敏感子串在 schema 层即被拒绝"
+        },
+        "requiresApproval": {
+          "type": "boolean",
+          "description": "执行前需要 checkpoint 级批准（绑定 planDigest + hookId）；public-write preset 缺省 true"
+        },
+        "blocksVerified": {
+          "type": "boolean",
+          "description": "失败时是否阻断 VERIFIED；缺省 true；仅 preset 可声明 false（运行时 fail-closed 校验）"
+        }
+      }
+    },
     "postPublishMaterialize": {
       "type": "object",
       "description": "载荷物化钩子：executable+参数数组（禁止 shell 字符串），stdout 中 outputMarker 行之后为载荷目录路径；可选 requireReport 对 stdout 首个 JSON 对象做字段断言",

package/schemas/release-run.schema.json

@@ -43,7 +43,8 @@
         "PARTIAL",
         "BLOCKED",
         "DISTRIBUTING",
-        "DISTRIBUTED"
+        "DISTRIBUTED",
+        "NEEDS_INPUT"
       ],
       "description": "Current status of the run"
     },
@@ -55,7 +56,8 @@
         "publish",
         "reconcile",
         "verify",
-        "distribute"
+        "distribute",
+        "postverify"
       ],
       "description": "The command that initiated this run"
     },
@@ -133,7 +135,8 @@
               "codebuddy-marketplace-install",
               "set-default-branch",
               "distribute-probe",
-              "distribute-mirror"
+              "distribute-mirror",
+              "postpublish-hook"
             ],
             "description": "Type of external action"
           },
@@ -149,9 +152,10 @@
               "PASSED_AUTOMATIC",
               "PASSED_MANUAL",
               "NOT_REQUIRED_UNCHANGED",
-              "NO_CHANGE"
+              "NO_CHANGE",
+              "AWAITING_APPROVAL"
             ],
-            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push)"
+            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push; AWAITING_APPROVAL = requiresApproval postPublish hook 尚无 checkpoint 批准，v0.6.3 R1)"
           },
           "preObserve": {
             "type": "string",
@@ -621,7 +625,8 @@
             "enum": [
               "reconcile",
               "verify",
-              "distribute"
+              "distribute",
+              "postverify"
             ]
           }
         },

package/src/commands/approve.mjs

@@ -25,7 +25,13 @@ import {
   validatePlanActionCompleteness,
 } from '../core/plan.mjs';
 import { ReleaseError, PLAN_DIGEST_MISMATCH, GATE_FAILED } from '../core/errors.mjs';
-import { computeApprovalDigest, validateApprovalRecordSchema } from '../core/approval.mjs';
+import {
+  computeApprovalDigest,
+  validateApprovalRecordSchema,
+  MAX_APPROVAL_MS,
+} from '../core/approval.mjs';
+import { validatePostPublishApproval } from '../core/postpublish-approval.mjs';
+import { normalizePostPublishHook, effectiveHookRequiresApproval } from '../core/postpublish.mjs';
 import { WORKSPACE_DIGEST_ALGORITHM } from '../core/baseline.mjs';
 
 // ---------------------------------------------------------------------------
@@ -280,3 +286,163 @@ export async function approvePlan(options) {
     latestApprovalPath: writePath,
   });
 }
+
+/**
+ * Approve a requiresApproval postPublish hook (checkpoint-level approval,
+ * v0.6.3 R1, design §2.7 ruling 2).
+ *
+ * The record binds (planDigest, hookId) — the plan-level approval schema is
+ * untouched. Hook config changes change the plan digest, so approvals
+ * invalidate naturally with the plan. The result carries the approved hook's
+ * normalized entry summary (review N-6) so the checkpoint approval interface
+ * can display exactly what was approved.
+ *
+ * @param {Object} options
+ * @param {string} options.planPath - Absolute path to the frozen release plan.
+ * @param {string} options.hookId - id of the declared hook to approve.
+ * @param {string} options.actor - Identity of the approver.
+ * @param {number} [options.expiresInMs] - Validity window in ms (default and max 24h).
+ * @param {() => string} [options.clock] - Clock function returning ISO-8601 strings.
+ * @param {string} [options.runId] - Audit-only distribute run id (never a binding).
+ *
+ * @returns {Promise<object>} { planDigest, hookId, actor, approvedAt,
+ *   expiresAt, approvalDigest, approvalPath, hookSummary }.
+ *
+ * @throws {ReleaseError} GATE_FAILED when the hook is undeclared, does not
+ *   require approval, or the window exceeds 24h.
+ */
+export async function approvePostPublishHook(options) {
+  const {
+    planPath,
+    hookId,
+    actor,
+    expiresInMs = MAX_APPROVAL_MS,
+    clock,
+    runId,
+  } = options ?? {};
+
+  const clockFn = typeof clock === 'function' ? clock : defaultClock;
+
+  if (!planPath || typeof planPath !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'planPath must be a non-empty string');
+  }
+  if (!hookId || typeof hookId !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'hookId must be a non-empty string');
+  }
+  if (!actor || typeof actor !== 'string') {
+    throw new ReleaseError(GATE_FAILED, 'actor must be a non-empty string');
+  }
+  if (typeof expiresInMs !== 'number' || !Number.isFinite(expiresInMs) || expiresInMs <= 0) {
+    throw new ReleaseError(GATE_FAILED, 'expiresInMs must be a positive finite number', { expiresInMs });
+  }
+  if (expiresInMs > MAX_APPROVAL_MS) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `expiresInMs must not exceed 24 hours (${MAX_APPROVAL_MS}ms), got ${expiresInMs}ms`,
+      { expiresInMs },
+    );
+  }
+
+  // --- Load and validate the frozen plan ---
+  let planRaw;
+  try {
+    planRaw = await readFile(planPath, 'utf8');
+  } catch (err) {
+    throw new ReleaseError(GATE_FAILED, `cannot read release plan: ${err.message}`, { planPath, cause: err.code });
+  }
+  let plan;
+  try {
+    plan = JSON.parse(planRaw);
+  } catch (err) {
+    throw new ReleaseError(GATE_FAILED, `release plan is not valid JSON: ${err.message}`, { planPath });
+  }
+  const actualDigest = computePlanDigest(plan);
+  assertImmutablePlanAuthority(planPath, plan);
+  validatePlan(plan);
+
+  // --- Locate the declared hook (fail-closed) ---
+  const hooks = plan.postPublish?.hooks ?? [];
+  const hook = hooks.find((entry) => entry.id === hookId);
+  if (!hook) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `hook "${hookId}" is not declared in the frozen plan's postPublish hooks`,
+      { hookId, declaredHookIds: hooks.map((entry) => entry.id) },
+    );
+  }
+  // Effective requiresApproval (§2.6 grading, R4 review M-1): preset hooks
+  // may inherit the preset-declared default (proposal-inbox git-push,
+  // declared OR inferred from a remoteUrl address -> true) without an
+  // explicit declaration. Grading by the literal value here would refuse to
+  // mint approvals for exactly the hooks the runtime gates — the mint and
+  // validatePostPublishApproval must agree on the effective value.
+  const effectiveRequiresApproval = effectiveHookRequiresApproval(hook);
+  if (effectiveRequiresApproval !== true) {
+    throw new ReleaseError(
+      GATE_FAILED,
+      `hook "${hookId}" does not require approval (effective requiresApproval is not true)`,
+      { hookId, requiresApproval: effectiveRequiresApproval },
+    );
+  }
+
+  // --- Build the checkpoint approval record ---
+  const approvedAt = clockFn();
+  const approvedAtDate = new Date(approvedAt);
+  if (Number.isNaN(approvedAtDate.getTime())) {
+    throw new ReleaseError(GATE_FAILED, `invalid approvedAt timestamp: "${approvedAt}"`, { approvedAt });
+  }
+  const expiresAt = new Date(approvedAtDate.getTime() + expiresInMs).toISOString();
+
+  const approvalRecord = {
+    planDigest: actualDigest,
+    hookId,
+    actor,
+    approvedAt,
+    expiresAt,
+    ...(runId ? { runId } : {}),
+  };
+
+  // Full fail-closed re-validation (schema + bindings + time window).
+  validatePostPublishApproval(plan, approvalRecord, { clock: clockFn });
+
+  // --- Write the digest-addressed authority ---
+  const planDir = dirname(resolve(planPath));
+  const releaseDir = basename(planDir) === 'plans' && basename(planPath) === `${actualDigest}.json`
+    ? dirname(planDir)
+    : planDir;
+  const json = JSON.stringify(approvalRecord, null, 2);
+  const approvalDigest = computeApprovalDigest(json);
+  const immutableApprovalPath = resolve(
+    releaseDir,
+    'approvals',
+    'postpublish',
+    actualDigest,
+    `${approvalDigest}.json`,
+  );
+  await prepareAuthorityDirectory(dirname(immutableApprovalPath));
+  await assertAuthorityFileTarget(immutableApprovalPath);
+  try {
+    await writeFile(immutableApprovalPath, json, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+  } catch (error) {
+    if (error.code !== 'EEXIST') throw error;
+    const existing = await readFile(immutableApprovalPath, 'utf8');
+    if (existing !== json) {
+      throw new ReleaseError(
+        GATE_FAILED,
+        'postpublish approval authority digest collision: existing bytes differ',
+        { planDigest: actualDigest, approvalDigest, immutableApprovalPath },
+      );
+    }
+  }
+
+  // Review N-6: the normalized entry summary is the display surface of the
+  // checkpoint approval interface (defaults applied, digest-bound).
+  const hookSummary = normalizePostPublishHook(hook);
+
+  return Object.freeze({
+    ...approvalRecord,
+    approvalDigest,
+    approvalPath: immutableApprovalPath,
+    hookSummary,
+  });
+}