release-skill 0.9.4 → 0.9.5

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，本机收尾必须等待 `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 无权把本地就绪解释为生产就绪。
 

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

@@ -45,7 +45,7 @@ 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：有未完成 hook 时，先按 approval 合同批准并通过 `ship` 完成 postVerify，再把最终 `DISTRIBUTED` postVerify run 路径交给 `release-finish`；没有 postVerify hook 时，才把当前 verify run 路径交给 `release-finish`。随后按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
@@ -66,6 +66,7 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --pla
 ## 发布后收尾
 
 `VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+核心 prepare、publish、verify 流程跨平台；WorkBuddy 的本机收尾探测和更新仅支持 macOS。
 
 ## 烟雾测试
 

package/bin/release-skill-cli.mjs

@@ -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.
  *
@@ -903,9 +936,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 +1332,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 +1346,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 +1378,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 +1398,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 +1421,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 +1484,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 +1510,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 +1528,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));