release-skill 0.1.3 → 0.1.4

package/adapters/claude/schemas/release-run.schema.json

@@ -0,0 +1,342 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://release-skill.dev/schemas/release-run/v1",
+  "title": "Release Run",
+  "description": "Schema for a release run record capturing execution checkpoints",
+  "type": "object",
+  "required": [
+    "runId",
+    "command",
+    "planDigest",
+    "planPath",
+    "status",
+    "checkpoints"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "runId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Unique identifier for this run (UUID)"
+    },
+    "runDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "SHA-256 digest of the final run state, excluding this field"
+    },
+    "stateSequence": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Monotonic sequence of an immutable in-flight run state snapshot"
+    },
+    "previousStateDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "Digest of the immediately preceding stateSequence snapshot"
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "PUBLISHING",
+        "PUBLISHED",
+        "VERIFIED",
+        "PARTIAL",
+        "BLOCKED"
+      ],
+      "description": "Current status of the run"
+    },
+    "command": {
+      "type": "string",
+      "enum": [
+        "assess",
+        "prepare",
+        "publish",
+        "reconcile",
+        "verify"
+      ],
+      "description": "The command that initiated this run"
+    },
+    "sourceRunId": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Run ID of the source run (for reconcile runs)"
+    },
+    "sourceRunDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "Digest of the immutable source run consumed by reconcile or verify"
+    },
+    "sourceRunPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path of the immutable source run authority consumed by reconcile or verify"
+    },
+    "planDigest": {
+      "type": "string",
+      "description": "SHA-256 digest of the release plan used"
+    },
+    "planPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Immutable digest-addressed plan authority used by this run"
+    },
+    "approvalDigest": {
+      "type": "string",
+      "pattern": "^[a-f0-9]{64}$",
+      "description": "Digest of the immutable approval authority consumed by publish/reconcile"
+    },
+    "approvalPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Immutable digest-addressed approval authority consumed by publish/reconcile"
+    },
+    "startedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the run started"
+    },
+    "finishedAt": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp when the run finished"
+    },
+    "checkpoints": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "actionId",
+          "actionType",
+          "status"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "actionId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Identifier of the external action"
+          },
+          "actionType": {
+            "type": "string",
+            "enum": [
+              "push-commit",
+              "push-snapshot",
+              "create-tag",
+              "npm-publish",
+              "github-release",
+              "claude-marketplace-install",
+              "codex-marketplace-install",
+              "set-default-branch"
+            ],
+            "description": "Type of external action"
+          },
+          "status": {
+            "type": "string",
+            "enum": [
+              "succeeded",
+              "failed",
+              "skipped",
+              "pending",
+              "uncertain"
+            ],
+            "description": "Result status of this checkpoint (uncertain = started, result unknown)"
+          },
+          "preObserve": {
+            "type": "string",
+            "enum": [
+              "CONSISTENT",
+              "MISSING",
+              "CONFLICTING"
+            ],
+            "description": "Remote state before execution"
+          },
+          "postObserve": {
+            "type": "string",
+            "enum": [
+              "CONSISTENT",
+              "MISSING",
+              "CONFLICTING"
+            ],
+            "description": "Remote state after execution"
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "finishedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "remoteRef": {
+            "type": "object",
+            "description": "Remote resource identifiers (commit, tag, version, URL)",
+            "additionalProperties": false,
+            "properties": {
+              "commit": {
+                "type": "string"
+              },
+              "tag": {
+                "type": "string"
+              },
+              "version": {
+                "type": "string"
+              },
+              "url": {
+                "type": "string"
+              }
+            }
+          },
+          "error": {
+            "type": "object",
+            "description": "Error details when status is failed",
+            "additionalProperties": false,
+            "properties": {
+              "code": {
+                "type": "string",
+                "enum": [
+                  "CONFIG_INVALID",
+                  "BASELINE_CHANGED",
+                  "DIRTY_SCOPE_CONFLICT",
+                  "GATE_FAILED",
+                  "AUTH_MISSING",
+                  "REMOTE_CONFLICT",
+                  "HOOK_TIMEOUT",
+                  "PARTIAL_RELEASE",
+                  "POST_PUBLISH_VERIFY_FAILED"
+                ]
+              },
+              "message": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    },
+    "gateResults": {
+      "type": "array",
+      "description": "Consumer verification gate results bound to this verify run",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "phase",
+          "unitId",
+          "distribution",
+          "gateDigest",
+          "inputDigest",
+          "status",
+          "startedAt",
+          "finishedAt",
+          "exitCode",
+          "stdoutBytes",
+          "stdoutSha256",
+          "stderrBytes",
+          "stderrSha256"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          },
+          "phase": {
+            "const": "consumer-verify"
+          },
+          "unitId": {
+            "type": "string",
+            "minLength": 1
+          },
+          "distribution": {
+            "type": "string",
+            "enum": [
+              "npm",
+              "claude-plugin",
+              "codex-plugin"
+            ]
+          },
+          "gateDigest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "inputDigest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$",
+            "description": "SHA-256 digest of the exact installed consumer tree immediately before gate execution"
+          },
+          "status": {
+            "const": "passed"
+          },
+          "startedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "finishedAt": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "exitCode": {
+            "const": 0
+          },
+          "stdoutBytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "stdoutSha256": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          },
+          "stderrBytes": {
+            "type": "integer",
+            "minimum": 0
+          },
+          "stderrSha256": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "command": {
+            "enum": [
+              "reconcile",
+              "verify"
+            ]
+          }
+        },
+        "required": [
+          "command"
+        ]
+      },
+      "then": {
+        "required": [
+          "sourceRunId",
+          "sourceRunDigest",
+          "sourceRunPath"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "stateSequence": {
+            "minimum": 1
+          }
+        },
+        "required": [
+          "stateSequence"
+        ]
+      },
+      "then": {
+        "required": [
+          "previousStateDigest"
+        ]
+      }
+    }
+  ]
+}

package/adapters/claude/skills/release-assess/SKILL.md

@@ -23,16 +23,15 @@ description: Identify project topology and evaluate gaps in public documentation
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组：registry 已有受支持版本且 PATH 可用时为 `CLI=(release-skill)`；否则为 `CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")`
-2. 运行 `"${CLI[@]}" assess --root <path> --offline --json`
-3. 检查 exit code：0 = 成功，非 0 = 根据错误码处理
-4. 读取 JSON 报告中的 `status` 字段（`ASSESSED` / `NEEDS_INPUT` / `BLOCKED`）
-5. 若 `NEEDS_INPUT`，根据报告补充配置后重跑，使用最新输出作为唯一证据
+1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json`
+2. 检查 exit code：0 = 成功，非 0 = 根据错误码处理
+3. 读取 JSON 报告中的 `status` 字段（`ASSESSED` / `NEEDS_INPUT` / `BLOCKED`）
+4. 若 `NEEDS_INPUT`，根据报告补充配置后重跑，使用最新输出作为唯一证据
 
 ## 确定性脚本调用
 
 ```bash
-"${CLI[@]}" assess --root <path> --offline --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
 # 输出到文件: 加 --output <report-path>
 ```
 

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

@@ -23,25 +23,18 @@ description: "Discoverable entry point for release-skill: dependency and environ
 
 ## 正向执行路径
 
-1. 若 `npm view release-skill version` 已返回当前支持版本，探测 PATH 全局安装并运行 `release-skill help --json`
-2. registry 尚未发布当前版本或 PATH 不可用时，回退到源码路径：设置 `RELEASE_SKILL_HOME` 并运行 `node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help --json`
-3. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
-4. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
-5. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才路由到 `release-publish`
+1. 使用插件根相对路径运行 CLI：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json`
+2. 检查 `readiness.localPreparation`；需要生产发布时再检查 `readiness.productionPublish`
+3. 若环境就绪且缺少 `.release-skill/project.yaml`，先路由 `release-setup`；配置已存在才运行 `release-assess`
+4. 默认在审阅本地计划和快照后停止；只有用户明确要求且完成摘要审批时才路由到 `release-publish`
 
 ## 确定性脚本调用
 
 ```bash
-# 已确认 registry 存在当前版本后，从 npm 全局安装（推荐）
-release-skill help --json  # PATH 全局安装
-release-skill setup --root <path> --json  # 首次接入，只读发现
-release-skill assess --root <path> --offline --json  # PATH 全局安装
-
-# 从源码 checkout 运行
-RELEASE_SKILL_HOME=/path/to/release-skill
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" help --json
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" setup --root <path> --json
-node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" assess --root <path> --offline --json
+# 从插件根运行（自包含 bundle，无需 node_modules）
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" help --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" setup --root <path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --root <path> --offline --json
 ```
 
 ## 故障路由
@@ -53,11 +46,11 @@ node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs" assess -
 | pnpm 未安装 | 不影响本地准备；仅出现在 recommendations 中 |
 | npm/gh 未安装 | 本地准备仍可就绪，但 `readiness.productionPublish.status` 为 `NOT_READY` |
 | npm/gh 已安装 | 生产状态仍为 `AUTH_CHECK_REQUIRED`；发布前验证 `gh auth`、Git HTTPS credential 和 npm auth |
-| CLI 入口不存在 | 安装 `npm install -g release-skill`；无法使用 npm 时设置 `RELEASE_SKILL_HOME` 使用源码路径 |
+| CLI 入口不存在 | 确认 `${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs` 存在；不存在时重新安装插件 |
 | 项目配置不存在 | 路由 `release-setup`，默认只读；不得直接生成或覆盖 README/配置 |
-| assess 失败 | 运行 `node "$RELEASE_SKILL_HOME/..." assess --offline --json` 获取详情 |
+| assess 失败 | 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess --offline --json` 获取详情 |
 | 请求生产发布 | 已有公开版本先调用 `release-prepare --online --production` 观察 bound 基线；人工审阅后再路由 `release-publish` |
 
 ## 后续引导
 
-本地准备就绪后下一步运行 `release-assess`（npm 全局安装：`release-skill assess`；源码：`node "$RELEASE_SKILL_HOME/..." assess`）。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。
+本地准备就绪后下一步运行 `release-assess`：`node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" assess`。生产发布还要求 npm、gh 可用，并在发布前另行完成认证检查。

package/adapters/claude/skills/release-prepare/SKILL.md

@@ -25,8 +25,8 @@ description: Freeze an immutable release plan with local configuration, document
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组：registry 已有受支持版本且 PATH 可用时为 `CLI=(release-skill)`；否则为 `CLI=(node "$RELEASE_SKILL_HOME/packages/release-skill/bin/release-skill.mjs")`
-2. 运行 `"${CLI[@]}" prepare --root <path> --offline --json`
+1. 使用插件根相对路径运行 CLI：`CLI="node ${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs"`
+2. 运行 `${CLI} prepare --root <path> --offline --json`
 3. 若遇到 hook/gate 授权门失败，分别展示命令和风险，获取授权后只增加实际需要的 `--acknowledge-hook-side-effects` / `--acknowledge-gate-side-effects`
 4. 检查 exit code 0，读取 JSON 返回的 immutable `planPath=plans/<planDigest>.json`，再从该文件读取 `status`、`units`、`externalActions`
 5. 向用户展示 targetVersion、externalActions、planDigest 和 planPath；后续 approve/publish 只能使用该 immutable planPath，等待确认后再 approve
@@ -48,13 +48,13 @@ prepare 后若人工继续修改 README 或任何源文件，应保留修改并
 ## 确定性脚本调用
 
 ```bash
-"${CLI[@]}" prepare --root <path> --offline --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --json
 # 生产 happy end：bound 基线必须 online；远端目标唯一性仍由 publish 全局预检
-"${CLI[@]}" prepare --root <path> --online --production --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --online --production --json
 # 项目含 hook 时需显式授权:
-"${CLI[@]}" prepare --root <path> --offline --acknowledge-hook-side-effects --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --acknowledge-hook-side-effects --json
 # 项目含 snapshot gate 时另行显式授权:
-"${CLI[@]}" prepare --root <path> --offline --acknowledge-gate-side-effects --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" prepare --root <path> --offline --acknowledge-gate-side-effects --json
 ```
 
 ## 执行顺序

package/adapters/claude/skills/release-publish/SKILL.md

@@ -31,13 +31,10 @@ description: 从已批准且摘要确认的生产计划发布冻结 Git branch/t
 ## 确定性执行
 
 ```bash
-"${CLI[@]}" publish --root <path> --plan <plan-path> \
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" publish --root <path> --plan <plan-path> \
   --approval <approval-path> --confirm-production <planDigest> --json
 ```
 
-`CLI` 必须复用 `release-help` 已解析的入口：registry 已有受支持版本且 PATH 可用时
-为 `CLI=(release-skill)`；否则为源码 checkout 的 node 数组。
-
 执行顺序：全局只读预检 → 配置的公开分支（按三种 `branchStrategy` 执行）→ 必要时
 单独切换默认分支 → tag → npm tarball →
 GitHub Release → Claude/Codex marketplace 隔离安装。每步 execute 后立即 observe；

package/adapters/claude/skills/release-reconcile/SKILL.md

@@ -29,8 +29,8 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ## 正向执行路径
 
-1. 复用 `release-help` 已解析的 CLI 数组，并确认有 `--run` 路径（必需），且源 run 状态为 `PARTIAL`
-2. 运行 `"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --json`
+1. 使用插件根相对路径运行 CLI，确认有 `--run` 路径（必需），且源 run 状态为 `PARTIAL`
+2. 运行 `node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --json`
 3. 检查 exit code 和结构化状态：`PUBLISHED`（恢复完成，待 verify）/ `PARTIAL`（需重试）/ `BLOCKED`（需人工决策）
 4. 若 PARTIAL 且需重试，加 `--approval`；生产计划还必须加 `--confirm-production <planDigest>`
 
@@ -38,11 +38,11 @@ marketplace 隔离消费者 checkpoint，但只恢复到 `PUBLISHED`；最终 np
 
 ```bash
 # reconcile
-"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --json
 # verify
-"${CLI[@]}" verify --root <path> --plan <plan-path> --run <reconcile-run-path> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" verify --root <path> --plan <plan-path> --run <reconcile-run-path> --json
 # 重试（需 --approval）
-"${CLI[@]}" reconcile --root <path> --plan <plan-path> --run <run-path> --approval <approval-path> --confirm-production <planDigest> --json
+node "${CLAUDE_PLUGIN_ROOT}/bin/release-skill.mjs" reconcile --root <path> --plan <plan-path> --run <run-path> --approval <approval-path> --confirm-production <planDigest> --json
 ```
 
 ## 幂等跳过逻辑