release-skill 0.9.4 → 0.9.6

package/adapters/workbuddy/schemas/release-plan.schema.json

@@ -539,6 +539,18 @@
                   ],
                   "description": "市场来源类型：bundled-family（技能族自带市场文件）或 standalone-index（独立市场仓库）；每个平台每次发布只冻结一种来源"
                 },
+                "firstReleaseBootstrap": {
+                  "type": "string",
+                  "enum": [
+                    "manual-index-checkpoint"
+                  ],
+                  "description": "首次 standalone-index 发布的人工索引停点；仅显式 opt-in 时启用"
+                },
+                "marketplaceIndexSha": {
+                  "type": ["string", "null"],
+                  "pattern": "^[0-9a-f]{40}$",
+                  "description": "最终市场索引提交 SHA；首次 bootstrap prepare 阶段必须保持 null，verify 仅记录实际观察值"
+                },
                 "marketplaceCommitSha": {
                   "type": "string",
                   "pattern": "^[0-9a-f]{40}$",
@@ -697,6 +709,30 @@
                     ]
                   }
                 },
+                {
+                  "if": {
+                    "required": [
+                      "firstReleaseBootstrap"
+                    ]
+                  },
+                  "then": {
+                    "required": [
+                      "marketplaceSourceType",
+                      "marketplaceRepo"
+                    ],
+                    "properties": {
+                      "type": {
+                        "enum": [
+                          "claude-plugin",
+                          "codex-plugin"
+                        ]
+                      },
+                      "marketplaceSourceType": {
+                        "const": "standalone-index"
+                      }
+                    }
+                  }
+                },
                 {
                   "if": {
                     "required": [

package/adapters/workbuddy/schemas/release-project.schema.json

@@ -257,6 +257,13 @@
                   ],
                   "description": "市场来源类型：bundled-family（技能族自带市场文件）或 standalone-index（独立市场仓库）；每个平台每次发布只冻结一种来源"
                 },
+                "firstReleaseBootstrap": {
+                  "type": "string",
+                  "enum": [
+                    "manual-index-checkpoint"
+                  ],
+                  "description": "首次 standalone-index 发布的人工索引停点；仅显式 opt-in 时启用"
+                },
                 "marketplaceIndexPath": {
                   "type": "string",
                   "minLength": 1,
@@ -447,6 +454,30 @@
                     ]
                   }
                 },
+                {
+                  "if": {
+                    "required": [
+                      "firstReleaseBootstrap"
+                    ]
+                  },
+                  "then": {
+                    "required": [
+                      "marketplaceSourceType",
+                      "marketplaceRepo"
+                    ],
+                    "properties": {
+                      "type": {
+                        "enum": [
+                          "claude-plugin",
+                          "codex-plugin"
+                        ]
+                      },
+                      "marketplaceSourceType": {
+                        "const": "standalone-index"
+                      }
+                    }
+                  }
+                },
                 {
                   "if": {
                     "required": [

package/adapters/workbuddy/skills/release-finish/SKILL.md

@@ -13,7 +13,7 @@ description: 发布达到 VERIFIED 后处理可选的本地收尾：按发布分
 
 这是发布后的独立收尾，不属于 `prepare → approve → publish → verify` 状态机。它不能把本机更新结果写成新的发布状态，也不能因为本机更新失败而降低 `VERIFIED`。
 
-默认只读取冻结计划和 verify run。没有用户明确同意，不合并分支，不更新插件，不接受 Kimi 的安装信任提示。
+默认只读取冻结计划和 verify 或 postVerify run。没有用户明确同意，不合并分支，不更新插件，不接受 Kimi 的安装信任提示。
 
 ## 先生成收尾清单
 
@@ -23,11 +23,11 @@ description: 发布达到 VERIFIED 后处理可选的本地收尾：按发布分
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
-  --run <verified-run-path> \
+  --run <verify-or-postverify-run-path> \
   --json
 ```
 
-脚本只接受状态为 `VERIFIED`、且 `planDigest` 与冻结计划一致的 verify run。
+脚本只接受与冻结计划一致的显式运行证据：计划未声明 `postVerify` hook 时，传入同计划的 `VERIFIED` verify run；计划声明了 `postVerify` hook 时，必须传入同计划、沿同一 `VERIFIED` verify run 继承谱系且所有 hook checkpoint 均为 `succeeded` 或 `NO_CHANGE` 的 `DISTRIBUTED` postVerify run。postVerify 尚未完成时，不能直接运行本机收尾；应先完成所需 checkpoint approval，再通过 `ship` 完成 postVerify，并使用结果中的 postVerify run 路径。
 
 ## 主动询问
 
@@ -45,7 +45,7 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
   --root <project-root> \
   --plan <plan-path> \
-  --run <verified-run-path> \
+  --run <verify-or-postverify-run-path> \
   --update-local-hosts \
   --hosts claude,codex,kimi,codebuddy,workbuddy \
   --confirm-plan <planDigest> \
@@ -56,7 +56,7 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
 
 - Claude 先重新绑定冻结市场，再重新观察安装状态；旧插件若仍存在，才调用正式更新命令。Codex 继续按正式市场协议移除并安装冻结的 Git 引用。两者都在安装后核对插件、市场、版本和市场检出提交。
 - Kimi 的精确当前安装会在返回 `ALREADY_CURRENT` 前核对真实载荷；发生安装或迁移时，只在操作完成后核对结果。包名、版本、发布标签、已安装修订号和受管安装根必须与冻结计划一致；`.git` 只提供附加诊断，不是通过条件。旧的本地路径安装会在同一个受控终端交互界面（TUI）会话中先移除，再按发布标签安装、确认信任并重新加载。
-- CodeBuddy/WorkBuddy 只处理同一 bundled-family 插件和市场。只有冻结标签与计划声明的可变分支都从同一远端解析到冻结提交时，才调用正式市场更新和插件更新命令；完成后重新读取安装列表，并精确核对唯一条目的市场、版本和修订号。目标未安装、来源不符、远端不可访问或身份不一致时返回 `MANUAL_REQUIRED`，不修改宿主。
+- CodeBuddy/WorkBuddy 只处理同一 bundled-family 插件和市场。CodeBuddy 仅探测全局 `codebuddy`/`cbc`，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 固定为有效 `HOME`（环境未提供时取操作系统用户主目录）下名为 `.codebuddy` 的目录；WorkBuddy 仅在 macOS 探测 WorkBuddy 应用内嵌 CLI，由收尾脚本把 `CODEBUDDY_CONFIG_DIR` 与 `WORKBUDDY_CONFIG_DIR` 同时固定为有效 `HOME` 下名为 `.workbuddy` 的目录，绝不把两者互作回退。只有冻结标签与计划声明的可变分支都从同一远端解析到冻结提交时，才调用正式市场更新和插件更新命令；完成后重新读取安装列表，并精确核对唯一条目的市场、版本和修订号。目标未安装、来源不符、远端不可访问或身份不一致时返回 `MANUAL_REQUIRED`，不修改宿主。非 macOS 的 WorkBuddy 返回 `SKIPPED_UNSUPPORTED_PLATFORM`。
 
 任何宿主失败都保留其他宿主的实际结果，不回滚，也不把失败冒充成功。
 

package/adapters/workbuddy/skills/release-help/SKILL.md

@@ -12,12 +12,12 @@ description: "Discoverable entry point for release-skill: dependency and environ
 ## 职责
 
 - 依赖和环境检查：Node.js >= 22、Git 决定本地准备就绪度；npm/gh 另行决定生产依赖就绪度
-- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准
+- 能力说明：缺少配置时走 `help → setup → assess`；已有配置的安全默认路径是 `help → assess → prepare --offline`；日常生产发布优先使用可恢复的 `ship`，兼容的分阶段闭环仍是 `prepare --online --production → approve → publish → verify`。冻结计划批准是正常发布级流程的唯一批准门；声明 `requiresApproval: true` 的 postPublish hook 仍须等待独立 checkpoint 批准。若计划声明 `postVerify` hook，可用 `postverify` 直接执行独立收尾 run，也可由 `ship` 编排该阶段；本机收尾必须等待完成的 postVerify run，不能把仅有 `VERIFIED` 的 verify run 当作本机收尾授权。核心发布流程跨平台，WorkBuddy 本机收尾仅支持 macOS
 - 最小示例：展示从 release-help 到 release-assess 的最短路径
 - 只读诊断：运行 dry-run 检查，不修改任何文件
 - 故障引导：根据错误码指向对应的修复 Skill
 
-## 0.9.4 候选边界
+## 0.9.5 候选边界
 
 当前源码候选允许多发布单元项目在计划冻结前显式选择本轮范围。`prepare` 和新建的 `ship` 状态支持重复传入 `--unit <id>`；未传时继续选择全部配置单元。成功选择会列出选中与延期单元。延期单元不进入本轮计划，也不获得发布状态。
 
@@ -25,7 +25,7 @@ description: "Discoverable entry point for release-skill: dependency and environ
 
 0.9.3 引入的四项工作流保护、Hook cache v2 和稳定隔离安装树记录在 0.9.4 继续保留。0.9.4 精确消费 Foundation 0.16.0 的公开包根 API。Hook cache 只复用绝对路径或经真实 cwd 校验的 cwd-relative executable identity；裸 PATH、PATHEXT、Windows 和观察不可用时，Hook 仍冷执行，缓存复用失败关闭且不写入 v2 cache。缓存没有 TTL。
 
-稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.4 仍是源码候选，不能从本说明推断已批准、发布或验证。
+稳定隔离安装树记录只在宿主命令退出、目录已隔离且扫描期间没有并发写入时执行；宿主附加链接只记录、不跟随，声明载荷中的 symlink 失败关闭，legacy 全树语义保持不变。0.9.5 仍是源码候选，不能从本说明推断已批准、发布或验证。
 
 **阶段通过规则**: `status` 与 `readiness.localPreparation.status` 只判断本地 help/assess/prepare；其充要条件是 `READY` 且 exit code 为 0。`missingRequired` 列出缺失的 Node/Git。生产发布必须另外读取 `readiness.productionPublish`：缺少 npm/gh 时为 `NOT_READY`，依赖存在时仍是 `AUTH_CHECK_REQUIRED`，因为 help 不访问网络、不验证认证。Agent 无权把本地就绪解释为生产就绪。
 
@@ -51,6 +51,10 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> --targe
 # 多发布单元项目显式选择本轮范围；未传 --unit 时仍为全部单元
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" ship --root <path> \
   --target-version <version> --unit <unit-a> --unit <unit-b> --json
+# 对已经 VERIFIED 的计划独立执行 postVerify hook；不读取或写入 ship state
+node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 # 开发阶段执行声明 hooks 并生成 prepare 可复用的内容绑定收据
 # 配置时刻即授权（FM-16 处置 A）：hook 是任意本地进程、无隔离、触发前无确认点，
 # 命令调用本身即授权执行配置中的 hooks

package/adapters/workbuddy/skills/release-verify/SKILL.md

@@ -15,6 +15,11 @@ verify 是发布流程的最终验证阶段，是唯一能将状态提升到 `VE
 它执行远端状态重检、精确 npm 安装烟雾测试和消费者插件安装验证。
 verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再次派生运行。
 
+计划声明 `postVerify` hook 时，`postverify` 命令负责执行独立的收尾阶段。它接收
+`VERIFIED` verify run、同一计划的 approval，以及逐个传入的 checkpoint approval，
+然后原样调用现有 `postVerifyRelease`。该命令产生独立的 `postverify` run，不读取或写入
+ship state；hook approval 缺失、错误或过期时，在 hook 执行前失败关闭。
+
 **注意**: distribute gate (W1) 已经实现并集成在标准 verify 流程中。verify 现在会检查 postPublish 分发状态（git mirror + marketplace index），只有当所有外部动作都完成并通过验证时才达到 VERIFIED。
 
 **工作流兼容性**: 
@@ -45,13 +50,17 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
 4. 只有 `VERIFIED` 才是发布 happy end
-5. 达到 `VERIFIED` 后立即路由 `release-finish`：先生成只读收尾清单，再按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
+5. 达到 `VERIFIED` 后先检查计划是否声明 `postVerify` hook：直接收尾使用独立的 `postverify --plan --approval --run --hook-approval`，由该命令产生 `DISTRIBUTED` postVerify run；若仍由持久化 ship state 承担编排，则使用 `ship --hook-approval` 完成同一阶段，再把最终 run 路径交给 `release-finish`。没有 postVerify hook 时，把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
 ```bash
 # 从插件根运行
 node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <run-path> --json
+# 独立执行已 VERIFIED 计划的 postVerify hook；每个 requiresApproval hook 单独传入批准记录
+node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" postverify --root <path> \
+  --plan <plan-path> --approval <approval-path> --run <verified-run-path> \
+  --hook-approval <immutable-hook-approval-path> --json
 ```
 
 ## 验证步骤
@@ -63,9 +72,13 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --pla
 5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
 6. 全部通过 → `VERIFIED`
 
+`postverify` 不属于上述远端验证步骤。它只处理已经达到 `VERIFIED` 的计划，并把
+`postVerify` 阶段的执行结果写入独立 run。
+
 ## 发布后收尾
 
 `VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+核心 prepare、publish、verify 流程跨平台；WorkBuddy 的本机收尾探测和更新仅支持 macOS。
 
 ## 烟雾测试
 

package/bin/release-skill-cli.mjs

@@ -5,7 +5,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
 import { parseNodeMajor, meetsMinimum, computeReadinessStatus } from '../src/core/node-version.mjs';
-import { registerPathRedactor } from '../src/core/errors.mjs';
+import { EXIT_CODE_MAP, MISSING_PARAMETERS, registerPathRedactor } from '../src/core/errors.mjs';
 import { redactSensitivePaths } from '../src/core/redact.mjs';
 
 // Process output errors can be emitted immediately after a large console
@@ -37,7 +37,7 @@ registerPathRedactor(redactSensitivePaths);
 
 const execFile = promisify(execFileCb);
 
-const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'ship', 'post-release', 'attest', 'hooks', 'artifacts', 'docs', 'distribute', 'route', 'lineage']);
+const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'postverify', 'ship', 'post-release', 'attest', 'hooks', 'artifacts', 'docs', 'distribute', 'route', 'lineage']);
 
 /**
  * Wait until writes already queued on a process output stream have reached
@@ -91,6 +91,39 @@ async function exitAfterFlush(exitCode) {
   process.exit(exitCode);
 }
 
+/**
+ * Keep command-line error JSON useful without exposing internal error objects,
+ * process envelopes, or filesystem details.  Local-finish evidence errors
+ * intentionally expose only their stable cause and executable next steps.
+ *
+ * @param {unknown} error
+ * @returns {Record<string, unknown>}
+ */
+function publicErrorDetails(error) {
+  const details = error?.details;
+  if (!details || typeof details !== 'object' || Array.isArray(details)) return {};
+  const output = {};
+  if (details.cause && typeof details.cause === 'object' && !Array.isArray(details.cause)) {
+    const cause = {};
+    if (typeof details.cause.code === 'string') cause.code = details.cause.code;
+    if (typeof details.cause.message === 'string') cause.message = details.cause.message;
+    if (Object.keys(cause).length > 0) output.cause = cause;
+  }
+  if (Array.isArray(details.nextSteps)) {
+    const nextSteps = details.nextSteps
+      .filter((step) => step && typeof step === 'object' && !Array.isArray(step))
+      .map((step) => ({
+        ...(typeof step.code === 'string' ? { code: step.code } : {}),
+        ...(typeof step.message === 'string' ? { message: step.message } : {}),
+        ...(Array.isArray(step.argv) && step.argv.every((arg) => typeof arg === 'string')
+          ? { argv: [...step.argv] } : {}),
+      }))
+      .filter((step) => Object.keys(step).length > 0);
+    if (nextSteps.length > 0) output.nextSteps = nextSteps;
+  }
+  return output;
+}
+
 /**
  * Check if a command is available and get its version.
  *
@@ -274,6 +307,11 @@ function getCapabilityMaturity() {
       mode: 'fresh consumer verification (protocol-tested; no OS/network sandbox)',
       description: 'Recheck remote state, exact npm installation, CLI help, and automated Claude/Codex installs before VERIFIED; Kimi/CodeBuddy remain unverified manual follow-ups',
     },
+    postverify: {
+      available: true,
+      mode: 'independent postVerify execution',
+      description: 'Run approved postVerify hooks from a VERIFIED run in an independent run; never reads or writes ship state',
+    },
     distribute: {
       available: true,
       mode: 'controlled production (protocol-tested; no OS/network sandbox)',
@@ -307,6 +345,7 @@ Commands:
   publish    Publish frozen GitHub/npm artifacts after approval
   reconcile  Resume PARTIAL state from evidence; conflicts require a human
   verify     Fresh remote and consumer verification; only this reaches VERIFIED
+  postverify Run approved postVerify hooks from a VERIFIED run in an independent run
   ship       Resume one durable prepare -> approve -> publish -> verify flow; completes a parked
              postVerify hook once its checkpoint approval is provided (--hook-approval)
   post-release Inspect optional local finishing work after VERIFIED; update installed host plugins
@@ -321,10 +360,10 @@ Commands:
 
 Options:
   --root <path>    Project root directory (default: cwd)
-  --plan <path>    Path to the release plan file
+  --plan <path>    Path to the release plan file (required for approve/publish/reconcile/verify/postverify)
   --run <path>     Path to the release run file, or a run directory whose release-run.json
-                   is resolved automatically (required for reconcile/verify)
-  --approval <path> Path to the approval record
+                   is resolved automatically (required for reconcile/verify/postverify)
+  --approval <path> Path to the release-level approval record (required for publish/postverify)
   --production     Prepare immutable Git/npm production artifacts
   --output <path>  Override prepare/approve output path (non-production only)
   --run-dir <path> Override prepare run directory; production requires one direct child of .release-skill/runs
@@ -361,7 +400,7 @@ Options:
   --install-path <path> Actual managed plugin path when closure verification requires it
   --install-channel <desktop|cli> CodeBuddy installation channel when required
   --approve         Approve the ship plan (boolean; plan digest is auto-resolved)
-  --hook-approval <path> Checkpoint approval for a requiresApproval postPublish hook (ship/distribute; repeatable)
+  --hook-approval <path> Checkpoint approval for one requiresApproval hook (ship/distribute/postverify; repeatable)
   --state <path>    Override the durable ship state file
   --update-local-hosts Update installed plugins for selected local hosts after VERIFIED
   --hosts <ids>     Comma-separated local hosts for post-release update. No local host is updated unless --hosts contains at least one id
@@ -903,9 +942,15 @@ if (command === 'ship') {
         } else {
           console.log('Post-release: branch advancement was already included; skip the merge question.');
         }
-        if (result.postRelease.localHostUpdate?.promptRequired) {
+        const localHostUpdate = result.postRelease.localHostUpdate;
+        if (localHostUpdate?.available === true && typeof localHostUpdate.runPath === 'string') {
           console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
-          console.log(`Post-release command: release-skill post-release --plan ${result.planPath} --run ${result.verifyRunPath}`);
+          console.log(`Post-release command: release-skill post-release --plan ${result.planPath} --run ${localHostUpdate.runPath}`);
+          console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+        } else {
+          for (const step of localHostUpdate?.nextSteps ?? []) {
+            console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+          }
         }
       }
       for (const followUp of result.manualFollowUps ?? []) {
@@ -1293,14 +1338,13 @@ if (command === 'post-release') {
   const planPath = value('--plan') ? resolve(value('--plan')) : undefined;
   const runPath = value('--run') ? resolve(value('--run')) : undefined;
   if (!planPath || !runPath) {
-    const message = 'post-release requires --plan <path> and --run <verified-run-path>';
+    const message = 'post-release requires --plan <path> and --run <verify-or-postverify-run-path>';
     if (hasJson) console.log(JSON.stringify({ error: 'MISSING_PARAMETERS', message, exitCode: 1 }));
     else console.error(`Error: ${message}`);
     await exitAfterFlush(1);
   }
   try {
     const {
-      assertVerifiedReleaseRun,
       derivePostReleaseChecklist,
       updateLocalHostPlugins,
     } = await import('../src/commands/post-release-local.mjs');
@@ -1308,24 +1352,26 @@ if (command === 'post-release') {
     const {
       loadRun,
       resolveRunPath,
-      validateRunLineage,
     } = await import('../src/core/run.mjs');
     const plan = JSON.parse(await readFile(planPath, 'utf8'));
     validatePlan(plan);
+    const updateRequested = args.includes('--update-local-hosts');
     const resolvedRunPath = await resolveRunPath(runPath);
     const runRecord = await loadRun(resolvedRunPath, {
       requireDigest: true,
       authorityPlanPath: planPath,
     });
-    await validateRunLineage(runRecord, {
-      plan,
-      planPath,
-      runPath: resolvedRunPath,
-      production: Boolean(plan.production),
-    });
-    assertVerifiedReleaseRun(plan, runRecord);
-
-    const updateRequested = args.includes('--update-local-hosts');
+    if (!updateRequested) {
+      const { assertLocalFinishRun } = await import('../src/commands/post-release-local.mjs');
+      await assertLocalFinishRun({
+        plan,
+        planPath,
+        runPath: resolvedRunPath,
+        runRecord,
+        production: Boolean(plan.production),
+        root: resolve(value('--root') ?? process.cwd()),
+      });
+    }
     const hostsIndex = args.indexOf('--hosts');
     const rawHosts = hostsIndex !== -1
       && args[hostsIndex + 1]
@@ -1338,12 +1384,19 @@ if (command === 'post-release') {
       .filter(Boolean);
     const result = updateRequested
       ? await updateLocalHostPlugins({
-        plan,
+        planPath,
+        runPath: resolvedRunPath,
         root: resolve(value('--root') ?? process.cwd()),
         confirmPlanDigest: value('--confirm-plan'),
         selectedHosts,
       })
-      : derivePostReleaseChecklist(plan);
+      : derivePostReleaseChecklist(plan, {
+        runPath: runRecord.command === 'postverify' && runRecord.status === 'DISTRIBUTED'
+          ? resolvedRunPath
+          : runRecord.command === 'verify' ? resolvedRunPath : undefined,
+        root: resolve(value('--root') ?? process.cwd()),
+        postVerifyComplete: runRecord.command === 'postverify' && runRecord.status === 'DISTRIBUTED',
+      });
 
     if (hasJson) {
       console.log(JSON.stringify(result, null, 2));
@@ -1351,8 +1404,14 @@ if (command === 'post-release') {
       console.log(`Post-release status: ${result.status}`);
       if (result.merge.promptRequired) console.log('Ask whether the user wants to merge the remaining branch.');
       else console.log('Branch advancement was already included in the release workflow; skip the merge question.');
-      if (result.localHostUpdate.promptRequired) {
+      if (result.localHostUpdate.available === true && typeof result.localHostUpdate.runPath === 'string') {
         console.log(`Ask whether to update local host plugins: ${result.localHostUpdate.hosts.join(', ')}`);
+        console.log(`Post-release command: release-skill post-release --plan ${planPath} --run ${result.localHostUpdate.runPath}`);
+        console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+      } else {
+        for (const step of result.localHostUpdate.nextSteps ?? []) {
+          console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+        }
       }
     } else {
       console.log(`Local host update: ${result.status}`);
@@ -1368,9 +1427,15 @@ if (command === 'post-release') {
       console.log(JSON.stringify({
         error: err.code ?? 'POST_RELEASE_FAILED',
         message: err.message,
+        details: publicErrorDetails(err),
         exitCode: err.exitCode ?? 1,
       }));
-    } else console.error(`Error: ${err.message}`);
+    } else {
+      console.error(`Error: ${err.message}`);
+      for (const step of err.details?.nextSteps ?? []) {
+        console.error(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+      }
+    }
     await exitAfterFlush(err.exitCode ?? 1);
   }
 }
@@ -1425,7 +1490,7 @@ if (command === 'verify') {
       } = await import('../src/commands/post-release-local.mjs');
       const plan = JSON.parse(await readFile(planPath, 'utf8'));
       try {
-        result.postRelease = derivePostReleaseChecklist(plan);
+        result.postRelease = derivePostReleaseChecklist(plan, { root, runPath: result.runPath });
       } catch (error) {
         result.postRelease = unavailablePostReleaseChecklist(plan, error);
       }
@@ -1451,8 +1516,15 @@ if (command === 'verify') {
       } else if (result.postRelease?.merge.promptRequired) {
         console.log('Post-release: ask whether to merge the remaining branch.');
       }
-      if (result.postRelease?.localHostUpdate.promptRequired) {
+      if (result.postRelease?.localHostUpdate?.available === true
+        && typeof result.postRelease.localHostUpdate.runPath === 'string') {
         console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
+        console.log(`Post-release command: release-skill post-release --plan ${planPath} --run ${result.postRelease.localHostUpdate.runPath}`);
+        console.log('Choose --hosts before adding --update-local-hosts to perform a local update.');
+      } else {
+        for (const step of result.postRelease?.localHostUpdate?.nextSteps ?? []) {
+          console.log(`Next [${step.code}] ${step.message} (${step.argv.join(' ')})`);
+        }
       }
     }
 
@@ -1462,6 +1534,7 @@ if (command === 'verify') {
       const errOutput = {
         error: err.code ?? 'UNKNOWN_ERROR',
         message: err.message,
+        details: err.details ?? {},
         exitCode: err.exitCode ?? 1,
       };
       console.log(JSON.stringify(errOutput));
@@ -1472,6 +1545,124 @@ if (command === 'verify') {
   }
 }
 
+// --- PostVerify command routing ---
+if (command === 'postverify') {
+  if (args.includes('--help') || args.includes('-h')) {
+    const helpText = `release-skill postverify - Run approved postVerify hooks from a VERIFIED run
+
+Usage:
+  release-skill postverify [--root <path>] --plan <path> --approval <path> --run <path> [options]
+
+Required options:
+  --plan <path>             Path to the release plan file
+  --approval <path>         Path to the release-level approval record
+  --run <path>              Path to the VERIFIED verify run file or directory
+
+Optional options:
+  --root <path>             Project root directory (default: cwd)
+  --hook-approval <path>    Checkpoint approval for a requiresApproval postVerify hook (repeatable)
+  --json                    Output results as JSON
+  -h, --help                Show this help message and exit
+
+This command creates an independent postVerify run and never reads or writes ship state.`;
+    if (hasJson) {
+      console.log(JSON.stringify({
+        command: 'postverify',
+        status: 'HELP',
+        usage: 'release-skill postverify [--root <path>] --plan <path> --approval <path> --run <path> [options]',
+        options: {
+          '--root': 'Project root directory (default: cwd)',
+          '--plan': 'Path to the release plan file (required)',
+          '--approval': 'Path to the release-level approval record (required)',
+          '--run': 'Path to the VERIFIED verify run file or directory (required)',
+          '--hook-approval': 'Checkpoint approval for a requiresApproval postVerify hook (repeatable)',
+          '--json': 'Output results as JSON',
+          '-h, --help': 'Show this help message and exit',
+        },
+        message: 'Creates an independent postVerify run and never reads or writes ship state.',
+      }, null, 2));
+    } else {
+      console.log(helpText);
+    }
+    await exitAfterFlush(0);
+  }
+
+  let malformedValuedFlag;
+  const value = (flag) => {
+    let firstValue;
+    for (let i = 0; i < args.length; i += 1) {
+      if (args[i] !== flag) continue;
+      const next = args[i + 1];
+      if (!next || next.startsWith('-')) {
+        malformedValuedFlag ??= flag;
+        continue;
+      }
+      firstValue ??= next;
+    }
+    return firstValue;
+  };
+  const root = resolve(value('--root') ?? process.cwd());
+  const planPath = value('--plan');
+  const approvalPath = value('--approval');
+  const runPath = value('--run');
+  const postpublishApprovalPaths = [];
+  for (let i = 0; i < args.length; i += 1) {
+    if (args[i] === '--hook-approval') {
+      const next = args[i + 1];
+      if (!next || next.startsWith('-')) {
+        malformedValuedFlag ??= '--hook-approval';
+      } else {
+        postpublishApprovalPaths.push(resolve(next));
+      }
+    }
+  }
+
+  if (malformedValuedFlag || !planPath || !approvalPath || !runPath) {
+    const msg = 'postverify requires --plan <path>, --approval <path>, and --run <path>';
+    if (hasJson) {
+      console.log(JSON.stringify({ error: MISSING_PARAMETERS, message: msg, exitCode: EXIT_CODE_MAP[MISSING_PARAMETERS] }));
+    } else {
+      console.error(`Error: ${msg}`);
+    }
+    await exitAfterFlush(EXIT_CODE_MAP[MISSING_PARAMETERS]);
+  }
+
+  try {
+    const { postVerifyRelease } = await import('../src/commands/postverify.mjs');
+    const result = await postVerifyRelease({
+      planPath: resolve(planPath),
+      approvalPath: resolve(approvalPath),
+      sourceRunPath: resolve(runPath),
+      root,
+      ...(postpublishApprovalPaths.length > 0 ? { postpublishApprovalPaths } : {}),
+    });
+
+    if (hasJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`PostVerify status: ${result.status}`);
+      for (const cp of result.checkpoints ?? []) {
+        console.log(`  ${cp.actionId}: ${cp.status}`);
+      }
+      if (result.runPath) console.log(`PostVerify run: ${result.runPath}`);
+    }
+
+    await exitAfterFlush(result.status === 'DISTRIBUTED' ? 0 : 1);
+  } catch (err) {
+    if (hasJson) {
+      console.log(JSON.stringify({
+        error: err.code ?? 'UNKNOWN_ERROR',
+        message: err.message,
+        details: err.details ?? {},
+        exitCode: err.exitCode ?? 1,
+      }));
+    } else {
+      console.error(`Error: ${err.message}`);
+    }
+    await exitAfterFlush(err.exitCode ?? 1);
+  }
+}
+
 // --- Publish command routing ---
 if (command === 'publish') {