release-skill 0.8.1 → 0.9.0

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

@@ -17,9 +17,10 @@
       "type": "integer",
       "enum": [
         1,
-        2
+        2,
+        3
       ],
-      "description": "Plan format and digest-scoping version. 1: legacy (every field except the top-level digest binds; commitTimestamp must equal createdAt). 2: T1.2 digest layering (record-layer fields status/createdAt/baseline/per-action status are excluded from the plan digest; commitTimestamp is derived from the HEAD commit committer date)."
+      "description": "Plan format and digest-scoping version. 1: legacy (every field except the top-level digest binds; commitTimestamp must equal createdAt). 2: T1.2 digest layering (record-layer fields status/createdAt/baseline/per-action status are excluded from the plan digest; commitTimestamp is derived from the HEAD commit committer date). 3: multi-release-unit postPublish v3 (postPublish is a declaration ARRAY, one entry per declaring unit in plan.units order, possibly empty; v3 inherits the v2 record-layer semantics and only changes the postPublish shape)."
     },
     "status": {
       "type": "string",
@@ -1121,7 +1122,11 @@
       }
     },
     "postPublish": {
-      "$ref": "#/definitions/planPostPublish"
+      "type": [
+        "object",
+        "array"
+      ],
+      "description": "Frozen post-release distribution block. planVersion 1/2: a single declaration object, or absent (normalized to the empty array view at runtime). planVersion 3: a declaration ARRAY, one entry per declaring unit in plan.units order, possibly empty — never a single object, never absent. The exact allowed shape is enforced conditionally on planVersion (root allOf); readers must never guess the shape from the field value."
     },
     "digest": {
       "type": "string",
@@ -1844,6 +1849,38 @@
     }
   },
   "allOf": [
+    {
+      "if": {
+        "properties": {
+          "planVersion": {
+            "const": 3
+          }
+        },
+        "required": [
+          "planVersion"
+        ]
+      },
+      "then": {
+        "properties": {
+          "postPublish": {
+            "type": "array",
+            "items": {
+              "$ref": "#/definitions/planPostPublish"
+            }
+          }
+        },
+        "required": [
+          "postPublish"
+        ]
+      },
+      "else": {
+        "properties": {
+          "postPublish": {
+            "$ref": "#/definitions/planPostPublish"
+          }
+        }
+      }
+    },
     {
       "if": {
         "properties": {

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

@@ -0,0 +1,65 @@
+---
+name: release-finish
+description: 发布达到 VERIFIED 后处理可选的本地收尾：按发布分支策略决定是否询问合并，并在用户确认后更新本机 Claude、Codex、Kimi、CodeBuddy/WorkBuddy 插件
+---
+
+# release-finish
+
+## 触发
+
+发布刚达到 `VERIFIED`（已完成发布后验证），或用户要求处理发布后的分支合并、本机宿主插件更新。
+
+## 边界
+
+这是发布后的独立收尾，不属于 `prepare → approve → publish → verify` 状态机。它不能把本机更新结果写成新的发布状态，也不能因为本机更新失败而降低 `VERIFIED`。
+
+默认只读取冻结计划和 verify run。没有用户明确同意，不合并分支，不更新插件，不接受 Kimi 的安装信任提示。
+
+## 先生成收尾清单
+
+从插件根执行：
+
+```bash
+node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
+  --plan <plan-path> \
+  --run <verified-run-path> \
+  --json
+```
+
+脚本只接受状态为 `VERIFIED`、且 `planDigest` 与冻结计划一致的 verify run。
+
+## 主动询问
+
+读取返回的 `merge` 和 `localHostUpdate`：
+
+1. `merge.promptRequired=false` 时，发布工作流已经推进或初始化目标分支，不再询问合并。
+2. `merge.promptRequired=true` 时，向用户说明尚未覆盖的发布分支，并询问是否需要合并。用户同意后，先只读核对源分支、目标分支、工作区状态和项目既有合并方式，再用明确的分支名执行；本脚本不猜分支，也不自动推送。
+3. `localHostUpdate.promptRequired=true` 时，列出计划覆盖的宿主，询问是否更新本机插件。两个问题可以一次问完。
+
+## 用户同意更新本机宿主
+
+把用户选择的宿主和清单返回的精确 `planDigest` 传回脚本：
+
+```bash
+node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill-local-finish.mjs" \
+  --plan <plan-path> \
+  --run <verified-run-path> \
+  --update-local-hosts \
+  --hosts claude,codex,kimi,codebuddy,workbuddy \
+  --confirm-plan <planDigest> \
+  --json
+```
+
+只传用户选择且计划声明的宿主。宿主 CLI 不存在时返回 `SKIPPED_NOT_INSTALLED`。各宿主按以下规则处理：
+
+- Claude、Codex 绑定冻结的 Git 引用，并在安装后核对插件、市场、版本和市场检出提交。
+- Kimi 先核对发布标签对应的提交，再通过受控的终端交互界面（TUI）安装，并读取本机安装根的版本、标签与修订号。
+- CodeBuddy/WorkBuddy 的 CLI 不能精确绑定 Git 引用。本机已是目标提交时返回 `ALREADY_CURRENT`，否则返回 `MANUAL_REQUIRED`，不执行“更新到最新”。
+
+任何宿主失败都保留其他宿主的实际结果，不回滚，也不把失败冒充成功。
+
+完成后报告每个宿主的状态，并提醒用户重启已更新的宿主。
+
+## 临时归属
+
+本能力目前只服务发布后的本机收尾，因此保留在 release-skill。第二个技能族需要复用宿主更新或 TUI 驱动，或 Foundation 发布等价公共入口时，再把通用机制上收 Foundation并删除这里的通用部分。release-skill 只保留发布计划到宿主更新输入的领域映射。

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

@@ -42,7 +42,8 @@ verify 只接受 `PUBLISHED` 状态的源 run；`VERIFIED` 是终态，不会再
 1. 确认有 `--run` 路径（必需），且源 run 状态为 PUBLISHED
 2. 使用插件根相对路径运行 CLI；命令调用本身即授权执行已配置的 verification gate 和 smoke process
 3. 检查 exit code 和结构化状态：`VERIFIED`（全部通过）/ 失败（具体错误）
-4. 只有 `VERIFIED` 才是 happy end
+4. 只有 `VERIFIED` 才是发布 happy end
+5. 达到 `VERIFIED` 后立即路由 `release-finish`：先生成只读收尾清单，再按清单主动询问分支合并和本机宿主插件更新；发布策略已包含分支动作时略过合并询问
 
 ## 确定性脚本调用
 
@@ -60,6 +61,10 @@ node "${CODEBUDDY_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --pla
 5. 对 Claude/Codex marketplace distribution 执行全新隔离消费者安装验证；收集 Kimi/CodeBuddy 的非阻塞 `manualFollowUps`
 6. 全部通过 → `VERIFIED`
 
+## 发布后收尾
+
+`VERIFIED` 不代表要自动修改开发分支或本机宿主。进入 `release-finish` 后，只有用户明确同意，才执行对应的本地动作。本机插件更新失败不会改变发布终态。
+
 ## 烟雾测试
 
 - 在 `os.tmpdir()` 创建隔离目录

package/bin/release-skill-cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import { readFile } from 'node:fs/promises';
 import { basename, dirname, join, resolve } from 'node:path';
 import { execFile as execFileCb } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -36,7 +37,7 @@ registerPathRedactor(redactSensitivePaths);
 
 const execFile = promisify(execFileCb);
 
-const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'ship', 'attest', 'hooks', 'artifacts', 'docs', 'distribute', 'route', 'lineage']);
+const COMMANDS = new Set(['help', 'setup', 'assess', 'prepare', 'approve', 'publish', 'reconcile', 'verify', 'ship', 'post-release', 'attest', 'hooks', 'artifacts', 'docs', 'distribute', 'route', 'lineage']);
 
 /**
  * Wait until writes already queued on a process output stream have reached
@@ -308,6 +309,8 @@ Commands:
   verify     Fresh remote and consumer verification; only this reaches VERIFIED
   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
+             only after exact plan confirmation
   attest     Legacy only: record a Kimi/CodeBuddy result for an old frozen plan
   hooks      Run declared development hooks and populate reusable receipts
   artifacts  Artifact status, inspect, update/apply, resolution, and diagnostics
@@ -360,6 +363,9 @@ Options:
   --approve         Approve the ship plan (boolean; plan digest is auto-resolved)
   --hook-approval <path> Checkpoint approval for a requiresApproval postPublish hook (ship/distribute; 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 (default: all declared)
+  --confirm-plan <digest> Confirm the exact VERIFIED plan before local host mutation
   --no-hook-cache  Force every prepare hook to run in full; neither read nor write the hook cache
   --json           Output results as JSON
   --version        Show version and exit
@@ -377,6 +383,7 @@ Safety:
   - To ensure zero remote writes, disable hooks or audit them separately
   - docs refresh --write rewrites only declared README managed regions and the current CHANGELOG entry after exact refreshDigest confirmation; it never commits, pushes, tags, publishes, or installs.
   - publish requires explicit approval; plan digest is auto-read from the plan file
+  - post-release local host updates are optional local mutations and never change VERIFIED
   - publish consumes frozen Git/npm artifacts, never the live workspace
   - existing remote objects and uncertain checks stop for human intervention
   - production-equivalent protocol sandbox is verified; a real remote canary is not
@@ -815,6 +822,19 @@ if (command === 'ship') {
           console.log('then re-run: release-skill ship --root <root> --hook-approval <approval-record>');
         }
       }
+      if (result.status === 'VERIFIED' && result.postRelease) {
+        if (result.postRelease.status === 'UNAVAILABLE') {
+          console.warn(`Post-release checklist unavailable: ${result.postRelease.diagnostic?.message ?? 'unknown error'}`);
+        } else if (result.postRelease.merge.promptRequired) {
+          console.log('Post-release: ask whether to merge the remaining release branch.');
+        } else {
+          console.log('Post-release: branch advancement was already included; skip the merge question.');
+        }
+        if (result.postRelease.localHostUpdate?.promptRequired) {
+          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}`);
+        }
+      }
       for (const followUp of result.manualFollowUps ?? []) {
         console.log(`Manual follow-up [${followUp.platform}] ${followUp.plugin}: not verified by system`);
       }
@@ -1178,6 +1198,91 @@ if (command === 'reconcile') {
   }
 }
 
+// --- Optional local finishing after VERIFIED ---
+if (command === 'post-release') {
+  const value = (flag) => {
+    const idx = args.indexOf(flag);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : undefined;
+  };
+  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>';
+    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');
+    const { validatePlan } = await import('../src/core/plan.mjs');
+    const {
+      loadRun,
+      resolveRunPath,
+      validateRunLineage,
+    } = await import('../src/core/run.mjs');
+    const plan = JSON.parse(await readFile(planPath, 'utf8'));
+    validatePlan(plan);
+    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');
+    const selectedHosts = value('--hosts')
+      ?.split(',')
+      .map((host) => host.trim())
+      .filter(Boolean);
+    const result = updateRequested
+      ? await updateLocalHostPlugins({
+        plan,
+        root: resolve(value('--root') ?? process.cwd()),
+        confirmPlanDigest: value('--confirm-plan'),
+        selectedHosts,
+      })
+      : derivePostReleaseChecklist(plan);
+
+    if (hasJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (!updateRequested) {
+      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) {
+        console.log(`Ask whether to update local host plugins: ${result.localHostUpdate.hosts.join(', ')}`);
+      }
+    } else {
+      console.log(`Local host update: ${result.status}`);
+      for (const entry of result.results) {
+        console.log(`  ${entry.host}/${entry.unitId}: ${entry.status}${entry.version ? ` (${entry.version})` : ''}`);
+      }
+      console.log('The release remains VERIFIED; restart updated hosts before using the new plugin bytes.');
+    }
+    const success = !updateRequested || ['UPDATED', 'ALREADY_CURRENT', 'NO_APPLICABLE_HOSTS'].includes(result.status);
+    await exitAfterFlush(success ? 0 : 1);
+  } catch (err) {
+    if (hasJson) {
+      console.log(JSON.stringify({
+        error: err.code ?? 'POST_RELEASE_FAILED',
+        message: err.message,
+        exitCode: err.exitCode ?? 1,
+      }));
+    } else console.error(`Error: ${err.message}`);
+    await exitAfterFlush(err.exitCode ?? 1);
+  }
+}
+
 // --- Verify command routing ---
 if (command === 'verify') {
 
@@ -1221,6 +1326,18 @@ if (command === 'verify') {
       root,
       verificationGatesAuthorized,
     });
+    if (result.status === 'VERIFIED') {
+      const {
+        derivePostReleaseChecklist,
+        unavailablePostReleaseChecklist,
+      } = await import('../src/commands/post-release-local.mjs');
+      const plan = JSON.parse(await readFile(planPath, 'utf8'));
+      try {
+        result.postRelease = derivePostReleaseChecklist(plan);
+      } catch (error) {
+        result.postRelease = unavailablePostReleaseChecklist(plan, error);
+      }
+    }
 
     if (hasJson) {
       console.log(JSON.stringify(result, null, 2));
@@ -1237,6 +1354,14 @@ if (command === 'verify') {
           console.log(`Baseline advance: ${result.baselineAdvance.committed ? 'advanced and committed' : 'advanced (uncommitted — commit .release-skill/project.yaml manually)'}`);
         }
       }
+      if (result.postRelease?.status === 'UNAVAILABLE') {
+        console.warn(`Post-release checklist unavailable: ${result.postRelease.diagnostic?.message ?? 'unknown error'}`);
+      } else if (result.postRelease?.merge.promptRequired) {
+        console.log('Post-release: ask whether to merge the remaining branch.');
+      }
+      if (result.postRelease?.localHostUpdate.promptRequired) {
+        console.log(`Post-release: ask whether to update local host plugins (${result.postRelease.localHostUpdate.hosts.join(', ')}).`);
+      }
     }
 
     await exitAfterFlush(result.status === 'VERIFIED' ? 0 : 1);

package/bin/release-skill-local-finish.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+if (process.argv[2] !== 'post-release') process.argv.splice(2, 0, 'post-release');
+await import('./release-skill.mjs');