release-skill 0.7.5 → 0.7.7

package/package.json

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

package/platform-manifest.json

@@ -2,11 +2,11 @@
   "schemaVersion": "1.0.0",
   "platformId": "release-skill",
   "platformName": "release-skill Plugin Platform",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "logicalRoot": "skills-src/",
-  "logicalRootDigest": "3767fc36f42ca561f5e839cea7b7e5bc16d08c47867b5bd6086f25efd0cb0f06",
-  "projectionDigest": "419f7f9601015459956e10aae74f42240ab2ac248238ff7494f3e761643d1749",
-  "projectionId": "release-skill:platform:0.7.5",
+  "logicalRootDigest": "b261a4cc49e6dc52dabddb083c22e414902fb269d5879ad01ef8146ceffd7bc7",
+  "projectionDigest": "6629de035a25005fd4676b09a0526a46f992a33d974cadd542b0c964d7f906ff",
+  "projectionId": "release-skill:platform:0.7.7",
   "manifestRequired": true,
   "projectionSources": {
     "skills-src-root": {

package/references/.render-manifest.json

@@ -10,8 +10,8 @@
       "bytes": 12086
     },
     "02-project-config.md": {
-      "digest": "f866490d5897c2baf38fd3a6770964c052bea4418f034b75965ecfe49c2f4387",
-      "bytes": 21212
+      "digest": "ce1986761f2aee9aab2646170cbd9ee3d14b7032db3bfb57b17e7369a45197f2",
+      "bytes": 21924
     },
     "03-readme-quality.md": {
       "digest": "d74e41052592443ebbd450d0ace5f9b9b19c7a94db50f952b17c1c5a4c5dc230",
@@ -26,8 +26,8 @@
       "bytes": 12014
     },
     "06-adapter-contract.md": {
-      "digest": "4b1ec9ba843345df47c1d133a8bf1aa644bf12a4ecf760cb1d566a43f1e9a9d2",
-      "bytes": 17282
+      "digest": "e00c175b24764487618dfdf20dc295f12a7e809f7dbfc69f6936a1e97bd02ab8",
+      "bytes": 18517
     }
   }
 }

package/references/02-project-config.md

@@ -27,6 +27,10 @@ project:
   defaultBranch: <string>        # workspace 远端默认分支，必填；不限定为 main
   sourceRepository: <owner/repo> # workspace 源仓库；生产发布必填
 
+publicSourceAuthorityReceipt:    # 可选；把源码坐标与多个 npm tarball 绑定为公开 Release asset
+  coordinatorUnitId: <release-unit-id>
+  subjectUnitIds: [<release-unit-id>]
+
 releaseUnits:               # 发布单元数组，至少 1 个
   - id: <string>            # 唯一标识
     source: <string>        # 源码相对路径（相对项目根目录）
@@ -70,6 +74,20 @@ releaseUnits:               # 发布单元数组，至少 1 个
           versionMarkers:      # 可选；id 唯一
             - id: <string>
               pattern: <string> # 含 {version} 占位符的精确标记模式
+    postPublish:            # 可选；发布单元级的发布后分发配置
+      commitIdentity:
+        name: <string>
+        email: <string>
+      targets:              # 可选；镜像或市场索引目标
+        - id: <string>
+          kind: payload-mirror # 或 marketplace-index
+          remoteUrl: <string>  # file:// 或 https://；禁止 ssh
+          visibility: public   # 或 private / internal
+          branch: <string>
+      hooks:                # 可选；命名 preset 或自定义 command hook
+        - id: <string>
+          command: [<executable>, <arg>]
+          phase: distribute # 或 postVerify
 
 verificationGates:         # 可选；定义会进入冻结计划摘要
   - id: <stable-id>
@@ -83,43 +101,69 @@ verificationGates:         # 可选；定义会进入冻结计划摘要
     envAllowlist: []
 
 hooks:                      # 可选，命令 hooks
+  lint: <hook>
   docs: <hook>
   build: <hook>
   test: <hook>
   typecheck: <hook>
-  lint: <hook>
-
-postPublish:                # 可选；发布后分发配置（W2 closure）
-  distribute:               # 分发行动数组
-    - actionType: <string>      # "distribute-mirror" | "distribute-marketplace-index"
-      adapter: <string>         # "distribute-git" | "distribute-marketplace"
-      kind: <string>            # "payload-mirror" | "marketplace-index-form"
-      targetId: <string>        # 目标标识
-      remoteUrl: <string>       # file:// 或 https://；禁止 ssh
-      branch: <string>          # 分支名，不得以 '-' 开头
-      tag: <string>             # tag 模板，用于版本验证
-      commitIdentity:           # 冻结提交身份
-        name: <string>          # 禁止以 '-' 开头
-        email: <string>         # RFC 5322 valid
-      payloadDir: <string>      # 相对路径
-      dryRun?: boolean          # 可选；只本地执行
-      materialize?: {          # 可选；缺省时载荷由冻结 publicFiles 经 Foundation 托管投影物化
-        command: <string>       # 可执行文件
-        args: [<string>]        # 参数数组，禁止 shell 字符串
-        outputMarker?: <string> # 输出标记，用于验证
-        requireReport: {}       # 前置报告要求
-        urlDependsOn: [<string>]> # 依赖动作完成
-      onConflict?: <string>     # "FAIL" (默认) | "RETRY"
-      retryPolicy?: {          # 可选；重试策略
-        maxAttempts: number
-        backoffMs: number
-      }
 
 policy:                     # 可选，安全策略
   forbiddenPaths: [<string>]
   forbiddenContentPatterns: [<string>]
 ```
 
+`publicSourceAuthorityReceipt` 只适用于 production prepare。`coordinatorUnitId`
+指定承载该文件的 GitHub Release；`subjectUnitIds` 必须引用现有 release unit，且每个
+unit 恰好声明一个 npm distribution。prepare 等所有 subject tarball 冻结后生成
+`source-authority-receipt.json`，其公开结构固定为：
+
+```json
+{"schemaVersion":1,"kind":"skill-family.source-authority-receipt","sourceRepository":"owner/workspace","sourceBaseCommit":"<full-commit>","subjects":[{"packageName":"@scope/package","version":"1.2.3","filename":"scope-package-1.2.3.tgz","sha256":"<sha256>"}]}
+```
+
+该文件使用 canonical JSON，不带自摘要，也不包含 release-skill 的计划、运行或批准字段。
+冻结计划记录文件 SHA-256；publish 将相同字节上传到 coordinator GitHub Release，verify
+重新下载远端字节并核对 SHA-256。离线消费者只需该文件和其中 subjects 对应的精确 tarball，便可
+核对包名、版本、文件名、tarball SHA-256、源码仓库与源码基线提交。
+
+`postPublish` 只能位于某个 `releaseUnits[]` 条目内。下面的完整结构样例会由 schema 契约测试直接读取并校验，避免文档层级再次漂移：
+
+```yaml
+# schema-example: postpublish-release-unit
+apiVersion: release-skill/v1
+kind: ReleaseProject
+project:
+  name: postpublish-example
+  defaultBranch: main
+releaseUnits:
+  - id: postpublish-example
+    source: .
+    publicRepo: example/postpublish-example
+    version:
+      source: package.json
+      tagTemplate: v{version}
+    distributions:
+      - type: npm
+        package: postpublish-example
+        registry: https://registry.npmjs.org
+        publisher: example
+    publicFiles:
+      - from: README.md
+        to: README.md
+        mode: preserve
+    requiredPublicFiles: [README.md]
+    previousPublicBaseline:
+      mode: none
+    postPublish:
+      commitIdentity:
+        name: release-bot
+        email: release-bot@example.com
+      hooks:
+        - id: notify-downstream
+          command: [node, scripts/notify-downstream.mjs]
+          phase: postVerify
+```
+
 ---
 
 ## 3. 公开源码镜像与分发包
@@ -218,7 +262,7 @@ squash、rebase 和默认分支上的无关后续提交可以通过；冲突解
 | `timeoutMs` | 整数 | 否 | 最小 1000，最大 7200000（2 小时） |
 | `envAllowlist` | 字符串数组 | 否 | 每个元素匹配 `^[A-Z_][A-Z0-9_]*$`；无重复元素 |
 
-hook 执行规则：
+hook 执行顺序固定为 `lint → docs → build → test → typecheck`，优先运行成本最低的检查。执行规则如下：
 
 - 使用 `execFile`，不使用 `exec` 或 `{ shell: true }`。
 - 通过 `realpath` 解析 cwd，拒绝逃逸到项目根目录之外。
@@ -254,7 +298,7 @@ hooks:
 
 `snapshot-verify` 获得冻结公开快照的一次性可写副本；副本销毁后重新摘要原快照，失败时还没有远端写入。`consumer-verify` 只在精确 npm 或 Claude/Codex 隔离安装成功后，从安装根执行；结果摘要进入 verify run，失败不得达到 VERIFIED。
 
-gate 与 legacy hook 都是无网络沙箱的本地进程，必须显式确认副作用。release-skill 会限制环境、路径、超时和证据输出，但不能替项目保证其命令不会写文件或访问网络。Git push、tag、默认分支、GitHub Release 和 npm publish 只能是冻结计划里的 adapter action，不能注册为 hook/gate。
+gate 与 legacy hook 都是没有网络沙箱的本地进程。在 `.release-skill/project.yaml` 中配置命令即完成授权，调用对应命令时直接执行，不再增加触发前确认点。旧参数 `--acknowledge-hook-side-effects` 和 `--acknowledge-gate-side-effects` 只作为无效果的兼容输入保留。release-skill 会限制环境、路径、超时和证据输出，但不能替项目保证命令不会写文件或访问网络。恢复触发前强制确认门属于后续设计变更，0.7.6 不提供该确认门。Git push、tag、默认分支、GitHub Release 和 npm publish 只能是冻结计划里的 adapter action，不能注册为 hook/gate。
 
 ### 4.2 首次接入 setup
 

package/schemas/release-plan.schema.json

@@ -53,6 +53,53 @@
         }
       }
     },
+    "publicSourceAuthorityReceipt": {
+      "type": "object",
+      "required": [
+        "coordinatorUnitId",
+        "subjectUnitIds",
+        "asset"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "coordinatorUnitId": {
+          "type": "string",
+          "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "subjectUnitIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$"
+          }
+        },
+        "asset": {
+          "type": "object",
+          "required": [
+            "name",
+            "path",
+            "sha256"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "const": "source-authority-receipt.json"
+            },
+            "path": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\).+$"
+            },
+            "sha256": {
+              "type": "string",
+              "pattern": "^[a-f0-9]{64}$"
+            }
+          }
+        }
+      }
+    },
     "baseline": {
       "type": "object",
       "required": [

package/schemas/release-project.schema.json

@@ -44,6 +44,30 @@
         }
       }
     },
+    "publicSourceAuthorityReceipt": {
+      "type": "object",
+      "description": "Optional public source-authority receipt uploaded to one coordinator GitHub Release after all subject npm tarballs are frozen.",
+      "required": [
+        "coordinatorUnitId",
+        "subjectUnitIds"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "coordinatorUnitId": {
+          "type": "string",
+          "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "subjectUnitIds": {
+          "type": "array",
+          "minItems": 1,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "pattern": "^(?!\\.{1,2}$)[A-Za-z0-9][A-Za-z0-9._-]*$"
+          }
+        }
+      }
+    },
     "releaseUnits": {
       "type": "array",
       "minItems": 1,

package/skills/release-prepare/SKILL.md

@@ -13,7 +13,7 @@ description: Freeze an immutable release plan with local configuration, document
 
 运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
+**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。旧参数 `--acknowledge-hook-side-effects` 和 `--acknowledge-gate-side-effects` 仍可解析，但只作为无效果的兼容输入，不能改变授权或执行语义。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 
@@ -33,6 +33,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+配置声明 `publicSourceAuthorityReceipt` 时，prepare 必须在所有 subject npm tarball
+冻结后生成 `source-authority-receipt.json`，并把该文件的路径与 SHA-256 绑定到
+coordinator unit 的 `github-release` action。该能力不支持非生产 prepare；不得手工
+补写 receipt 或把私有 plan/run 字段复制进公开文件。
 每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
 `bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
 该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做

package/skills-src/release-prepare/SKILL.md

@@ -13,7 +13,7 @@ description: Freeze an immutable release plan with local configuration, document
 
 运行项目构建/测试 hook，生成公开快照并扫描泄漏，冻结不可变发布计划。prepare 自身不调用发布 adapter，但会执行用户配置的 hook。
 
-**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
+**Hook 授权契约（配置时刻即授权，FM-16 处置 A）**: hook 是任意本地进程——在 `.release-skill/project.yaml` 中配置 hook 命令即完成授权，构成「配置时刻即授权」的显式契约。hook 不提供沙箱、无文件系统/网络隔离、触发前无确认点，命令调用本身即授权执行已配置的 hook 和 gate，不再设置额外人工授权环节；hook 可能产生项目目录外的副作用或远端写入，配置者须对其内容负责。旧参数 `--acknowledge-hook-side-effects` 和 `--acknowledge-gate-side-effects` 仍可解析，但只作为无效果的兼容输入，不能改变授权或执行语义。恢复「触发前强制确认门」属于后续加固项（属设计变更，需随新版本引入），当前版本不提供该确认门。
 
 **阶段通过规则**: 本阶段的通过只能由 CLI exit code 0 和结构化状态码 `PREPARED` 确认。Agent 无权自行宣布计划冻结成功。
 
@@ -33,6 +33,10 @@ description: Freeze an immutable release plan with local configuration, document
 
 若用户明确要求 GitHub+npm 生产发布，加入 `--production`。该模式还会封存独立
 Git commit/tree 和 npm tarball，并把路径、SHA/integrity、branch/tag 写入计划。
+配置声明 `publicSourceAuthorityReceipt` 时，prepare 必须在所有 subject npm tarball
+冻结后生成 `source-authority-receipt.json`，并把该文件的路径与 SHA-256 绑定到
+coordinator unit 的 `github-release` action。该能力不支持非生产 prepare；不得手工
+补写 receipt 或把私有 plan/run 字段复制进公开文件。
 每个 npm tarball 在计划落盘前必须静态验证 `package.json` 的具体
 `bin`/`main`/`module`/`types`/`typings`/`exports` 入口均为 tarball 内普通文件；
 该门禁不依赖项目是否配置 `requiredPublicFiles` 或 `smokeBin`。通配符 exports 不做

package/src/adapters/git-github.mjs

@@ -8,8 +8,10 @@ import {
   createResult,
   matchObservation,
 } from './contract.mjs';
-import { resolveFrozenPath, verifyFrozenDirectoryStructure } from '../snapshot/frozen.mjs';
+import { resolveFrozenPath, verifyFrozenDirectoryStructure, verifyFrozenFile } from '../snapshot/frozen.mjs';
 import { githubRepositoryUrl } from './push-snapshot.mjs';
+import { digestReleaseAssetIdentities, normalizeReleaseAssets } from '../core/release-assets.mjs';
+import { sha256Hex } from '../core/digest.mjs';
 
 const execFile = promisify(execFileCb);
 const NAME = 'git-github';
@@ -91,6 +93,82 @@ async function readRemoteBranchCommit(action, exec) {
   return stdout.trim().split(/\s+/)[0] ?? '';
 }
 
+async function validateLocalReleaseAssets(action, context) {
+  const assets = normalizeReleaseAssets(action.releaseAssets);
+  const verified = [];
+  for (const asset of assets) {
+    const file = await verifyFrozenFile({
+      root: context.root,
+      filePath: asset.path,
+      expectedSha256: asset.sha256,
+      label: `frozen GitHub Release asset "${asset.name}"`,
+    });
+    verified.push({ ...asset, physical: file.physical });
+  }
+  return verified;
+}
+
+async function readReleaseWithAssets(action, context, exec) {
+  const environment = { ...process.env, GH_HOST: action.githubHost ?? 'github.com' };
+  const { stdout } = await exec(
+    'gh',
+    ['api', `repos/${action.repo}/releases/tags/${action.tag}`],
+    { cwd: context.root, shell: false, encoding: 'utf8', env: environment },
+  );
+  const release = JSON.parse(stdout);
+  const commitResult = await exec(
+    'gh',
+    ['api', `repos/${action.repo}/git/ref/tags/${action.tag}`, '--jq', '.object.sha'],
+    { cwd: context.root, shell: false, encoding: 'utf8', env: environment },
+  );
+  const plannedAssets = normalizeReleaseAssets(action.releaseAssets);
+  const observedAssets = [];
+  const missingAssets = [];
+  for (const planned of plannedAssets) {
+    const matches = (release.assets ?? []).filter((asset) => asset?.name === planned.name);
+    if (matches.length > 1) throw new Error(`GitHub Release has duplicate asset name "${planned.name}"`);
+    if (matches.length === 0) {
+      missingAssets.push(planned.name);
+      continue;
+    }
+    const remote = matches[0];
+    if (!Number.isInteger(remote.id)) throw new Error(`GitHub Release asset "${planned.name}" has no stable asset id`);
+    const downloaded = await exec(
+      'gh',
+      ['api', `repos/${action.repo}/releases/assets/${remote.id}`, '-H', 'Accept: application/octet-stream'],
+      { cwd: context.root, shell: false, encoding: null, env: environment, maxBuffer: 64 * 1024 * 1024 },
+    );
+    const bytes = Buffer.isBuffer(downloaded.stdout)
+      ? downloaded.stdout
+      : Buffer.from(downloaded.stdout ?? '', 'utf8');
+    observedAssets.push({ ...planned, sha256: sha256Hex(bytes) });
+  }
+  return {
+    observation: {
+      tag: release.tag_name,
+      commit: commitResult.stdout.trim(),
+      releaseUrl: release.html_url,
+      ...(missingAssets.length > 0
+        ? { exists: false, missingReleaseAssets: missingAssets }
+        : { releaseAssetsDigest: digestReleaseAssetIdentities(observedAssets) }),
+    },
+    missingAssets,
+    observedAssets,
+  };
+}
+
+function assertExistingReleaseCompatible(action, state) {
+  if (state.observation.tag !== action.tag || state.observation.commit !== action.commit) {
+    throw new Error('existing GitHub Release tag or commit conflicts with the frozen plan');
+  }
+  const expectedByName = new Map(normalizeReleaseAssets(action.releaseAssets).map((asset) => [asset.name, asset]));
+  for (const observed of state.observedAssets) {
+    if (expectedByName.get(observed.name)?.sha256 !== observed.sha256) {
+      throw new Error(`GitHub Release asset "${observed.name}" bytes conflict with the frozen plan`);
+    }
+  }
+}
+
 export function createGitGithubAdapter(deps = {}) {
   const exec = deps.exec ?? run;
   return Object.freeze({
@@ -110,6 +188,7 @@ export function createGitGithubAdapter(deps = {}) {
         } else if (action.actionType === ActionType.GITHUB_RELEASE) {
           if (!action.repo || !action.tag) throw new Error('github-release requires repo, tag, and commit');
           validateOid(action.commit);
+          const localAssets = await validateLocalReleaseAssets(action, context);
           await exec('gh', ['auth', 'status'], {
             cwd: context.root,
             shell: false,
@@ -123,12 +202,19 @@ export function createGitGithubAdapter(deps = {}) {
             throw new Error(`cannot access GitHub repository ${action.repo}: ${err.message}`);
           });
           try {
-            await exec('gh', ['api', `repos/${action.repo}/releases/tags/${action.tag}`], {
-              cwd: context.root,
-              shell: false,
-              env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
-            });
-            throw new Error(`GitHub Release already exists for ${action.tag}; human intervention required`);
+            if (localAssets.length === 0) {
+              await exec('gh', ['api', `repos/${action.repo}/releases/tags/${action.tag}`], {
+                cwd: context.root,
+                shell: false,
+                env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+              });
+              throw new Error(`GitHub Release already exists for ${action.tag}; human intervention required`);
+            }
+            const state = await readReleaseWithAssets(action, context, exec);
+            assertExistingReleaseCompatible(action, state);
+            if (state.missingAssets.length === 0) {
+              throw new Error(`GitHub Release and assets already exist for ${action.tag}`);
+            }
           } catch (err) {
             if (err.message?.includes('already exists')) throw err;
             if (!isNotFound(err)) throw new Error(`cannot determine GitHub Release uniqueness: ${err.message}`);
@@ -192,13 +278,36 @@ export function createGitGithubAdapter(deps = {}) {
             `refs/tags/${action.tag}`,
           ], { shell: false });
         } else if (action.actionType === ActionType.GITHUB_RELEASE) {
-          await exec('gh', [
-            'release', 'create', action.tag,
-            '--repo', ghRepo(action),
-            '--verify-tag',
-            '--title', action.name ?? `Release ${action.tag}`,
-            '--notes', action.notes ?? `Release ${action.tag}`,
-          ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+          const assets = await validateLocalReleaseAssets(action, context);
+          let existing = null;
+          if (assets.length > 0) {
+            try {
+              existing = await readReleaseWithAssets(action, context, exec);
+            } catch (error) {
+              if (!isNotFound(error)) throw error;
+            }
+          }
+          if (existing) {
+            assertExistingReleaseCompatible(action, existing);
+            const missing = new Set(existing.missingAssets);
+            const uploadPaths = assets.filter((asset) => missing.has(asset.name)).map((asset) => asset.physical);
+            if (uploadPaths.length > 0) {
+              await exec('gh', ['release', 'upload', action.tag, '--repo', ghRepo(action), ...uploadPaths], {
+                cwd: context.root,
+                shell: false,
+                env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' },
+              });
+            }
+          } else {
+            await exec('gh', [
+              'release', 'create', action.tag,
+              '--repo', ghRepo(action),
+              '--verify-tag',
+              '--title', action.name ?? `Release ${action.tag}`,
+              '--notes', action.notes ?? `Release ${action.tag}`,
+              ...assets.map((asset) => asset.physical),
+            ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+          }
         } else if (action.actionType === ActionType.SET_DEFAULT_BRANCH) {
           validateDefaultBranchAction(action);
           const { stdout: current } = await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.default_branch'], {
@@ -242,18 +351,22 @@ export function createGitGithubAdapter(deps = {}) {
           const { remoteUrl } = await validateTagAction(action, context, exec);
           observation = { tag: action.tag, commit: await readRemoteTag(action, remoteUrl, exec) };
         } else if (action.actionType === ActionType.GITHUB_RELEASE) {
-          const { stdout } = await exec('gh', [
-            'release', 'view', action.tag,
-            '--repo', ghRepo(action),
-            '--json', 'tagName,url',
-          ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
-          const release = JSON.parse(stdout);
-          const commitResult = await exec(
-            'gh',
-            ['api', `repos/${action.repo}/git/ref/tags/${action.tag}`, '--jq', '.object.sha'],
-            { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } },
-          );
-          observation = { tag: release.tagName, commit: commitResult.stdout.trim(), releaseUrl: release.url };
+          if (normalizeReleaseAssets(action.releaseAssets).length > 0) {
+            observation = (await readReleaseWithAssets(action, context, exec)).observation;
+          } else {
+            const { stdout } = await exec('gh', [
+              'release', 'view', action.tag,
+              '--repo', ghRepo(action),
+              '--json', 'tagName,url',
+            ], { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } });
+            const release = JSON.parse(stdout);
+            const commitResult = await exec(
+              'gh',
+              ['api', `repos/${action.repo}/git/ref/tags/${action.tag}`, '--jq', '.object.sha'],
+              { cwd: context.root, shell: false, env: { ...process.env, GH_HOST: action.githubHost ?? 'github.com' } },
+            );
+            observation = { tag: release.tagName, commit: commitResult.stdout.trim(), releaseUrl: release.url };
+          }
         } else if (action.actionType === ActionType.SET_DEFAULT_BRANCH) {
           validateDefaultBranchAction(action);
           const { stdout: current } = await exec('gh', ['api', `repos/${action.repo}`, '--jq', '.default_branch'], {