release-skill 0.5.0 → 0.6.0

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

@@ -613,6 +613,9 @@
           },
           "releaseDocuments": {
             "$ref": "#/definitions/releaseDocuments"
+          },
+          "postPublish": {
+            "$ref": "#/definitions/postPublish"
           }
         },
         "allOf": [
@@ -873,6 +876,294 @@
         }
       }
     },
+    "postPublish": {
+      "type": "object",
+      "description": "发布后分发声明：materialize 钩子从冻结 tag 工作树物化载荷，targets 将载荷镜像或渲染市场索引推送到独立 git 远端。分发在 publish 之后由 distribute 命令执行，时序契约禁止读取工作区状态。",
+      "required": [
+        "materialize",
+        "targets",
+        "commitIdentity"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "materialize": {
+          "$ref": "#/definitions/postPublishMaterialize"
+        },
+        "targets": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/definitions/postPublishTarget"
+          }
+        },
+        "commitIdentity": {
+          "type": "object",
+          "description": "分发仓库提交者身份（bot 身份），通过 git -c user.name/-c user.email 注入，绝不读取或修改全局 git 配置",
+          "required": [
+            "name",
+            "email"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "email": {
+              "type": "string",
+              "minLength": 1
+            }
+          }
+        },
+        "steps": {
+          "type": "array",
+          "description": "物化之后、推送之前按序执行的只读检查步骤；任一步失败即 fail-closed",
+          "items": {
+            "$ref": "#/definitions/postPublishStep"
+          }
+        },
+        "assertMainVersionAhead": {
+          "type": "boolean",
+          "description": "分发前校验主干版本源仍领先于目标版本，防止在已推进的主干上分发旧版本"
+        }
+      }
+    },
+    "postPublishMaterialize": {
+      "type": "object",
+      "description": "载荷物化钩子：executable+参数数组（禁止 shell 字符串），stdout 中 outputMarker 行之后为载荷目录路径；可选 requireReport 对 stdout 首个 JSON 对象做字段断言",
+      "required": [
+        "command",
+        "outputMarker"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true
+        },
+        "outputMarker": {
+          "type": "string",
+          "minLength": 1,
+          "description": "stdout 中标识载荷目录路径的前缀标记（如 \"isolated dir kept: \"）"
+        },
+        "requireReport": {
+          "type": "object",
+          "required": [
+            "parse"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "parse": {
+              "const": "stdout-first-json",
+              "description": "解析 stdout 中第一个完整 JSON 对象作为报告"
+            },
+            "equals": {
+              "type": "object",
+              "description": "报告字段等值断言；任一字段缺失或不等即 fail-closed"
+            }
+          }
+        }
+      }
+    },
+    "postPublishStep": {
+      "type": "object",
+      "description": "物化后按序执行的检查步骤；executable+参数数组（禁止 shell 字符串）",
+      "required": [
+        "name",
+        "command"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "command": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "type": "string"
+          }
+        },
+        "cwd": {
+          "type": "string",
+          "pattern": "^(?:\\.$|(?!\\/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(?:\\/|$))(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/\\/$)(?!.*\\/$).*)$"
+        },
+        "timeoutMs": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 7200000
+        },
+        "envAllowlist": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^(?!.*(?:TOKEN|SECRET|PASSWORD|PASSPHRASE|API_KEY|CREDENTIAL))[A-Z_][A-Z0-9_]*$"
+          },
+          "uniqueItems": true
+        }
+      }
+    },
+    "postPublishTarget": {
+      "type": "object",
+      "description": "分发目标 git 远端：payload-mirror 镜像载荷，marketplace-index 渲染市场索引清单；dependsOn 语义（引用、无环）在运行时 fail-closed 校验",
+      "required": [
+        "id",
+        "kind",
+        "remoteUrl",
+        "visibility",
+        "branch"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$"
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "payload-mirror",
+            "marketplace-index"
+          ]
+        },
+        "remoteUrl": {
+          "type": "string",
+          "pattern": "^(?:https?|file)://.+\\.git$",
+          "description": "仅允许 http(s) 或 file（测试传输）且以 .git 结尾的远端 URL"
+        },
+        "visibility": {
+          "type": "string",
+          "enum": [
+            "internal",
+            "public"
+          ]
+        },
+        "branch": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._/-]*$"
+        },
+        "dependsOn": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9._-]*$",
+          "description": "消费另一目标（须为 payload-mirror）推送后的 commit sha；运行时校验引用存在且无环"
+        },
+        "marketplace": {
+          "type": "object",
+          "description": "marketplace-index 目标必填：渲染 .claude-plugin/marketplace.json 所用的市场元数据",
+          "required": [
+            "form",
+            "name",
+            "owner"
+          ],
+          "additionalProperties": false,
+          "properties": {
+            "form": {
+              "type": "string",
+              "enum": [
+                "github",
+                "url"
+              ]
+            },
+            "name": {
+              "type": "string",
+              "minLength": 1
+            },
+            "owner": {
+              "type": "string",
+              "minLength": 1
+            },
+            "sourceRepo": {
+              "type": "string",
+              "pattern": "^[a-zA-Z0-9._-]+/[a-zA-Z0-9._-]+$",
+              "description": "可选 owner/repo；github form 缺省时以 owner/name 组装"
+            }
+          }
+        },
+        "staticFiles": {
+          "type": "array",
+          "description": "随目标一起写入的静态文件（from 为源仓库相对路径，to 为目标仓库相对路径）",
+          "items": {
+            "type": "object",
+            "required": [
+              "from",
+              "to"
+            ],
+            "additionalProperties": false,
+            "properties": {
+              "from": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+              },
+              "to": {
+                "type": "string",
+                "minLength": 1,
+                "pattern": "^(?!/)(?!\\.\\/)(?!.*\\\\)(?!.*:)(?!\\.\\.(/|$))(?!\\.$)(?!.*\\/\\.\\.\\/)(?!.*\\/\\.\\.$)(?!.*\\/\\.\\/)(?!.*\\/\\/)(?!.*\\0)(?!.*\\/\\.$)(?!.*\\/$).*$"
+              }
+            }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "marketplace-index"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "required": [
+              "marketplace"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "kind": {
+                "const": "payload-mirror"
+              }
+            },
+            "required": [
+              "kind"
+            ]
+          },
+          "then": {
+            "not": {
+              "required": [
+                "marketplace"
+              ]
+            }
+          }
+        }
+      ]
+    },
     "releaseDocuments": {
       "type": "object",
       "description": "Optional configuration-driven multilingual release-document refresh for one release unit. Absence preserves legacy behaviour. Lexical layer only; runtime path, locale-membership and collision checks apply additionally.",

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

@@ -41,7 +41,9 @@
         "PUBLISHED",
         "VERIFIED",
         "PARTIAL",
-        "BLOCKED"
+        "BLOCKED",
+        "DISTRIBUTING",
+        "DISTRIBUTED"
       ],
       "description": "Current status of the run"
     },
@@ -52,7 +54,8 @@
         "prepare",
         "publish",
         "reconcile",
-        "verify"
+        "verify",
+        "distribute"
       ],
       "description": "The command that initiated this run"
     },
@@ -128,7 +131,9 @@
               "codex-marketplace-install",
               "kimi-marketplace-install",
               "codebuddy-marketplace-install",
-              "set-default-branch"
+              "set-default-branch",
+              "distribute-probe",
+              "distribute-mirror"
             ],
             "description": "Type of external action"
           },
@@ -143,9 +148,10 @@
               "deferred",
               "PASSED_AUTOMATIC",
               "PASSED_MANUAL",
-              "NOT_REQUIRED_UNCHANGED"
+              "NOT_REQUIRED_UNCHANGED",
+              "NO_CHANGE"
             ],
-            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态)"
+            "description": "Result status of this checkpoint (uncertain = started, result unknown; deferred = marketplace action postponed to verify phase; PASSED_AUTOMATIC/PASSED_MANUAL/NOT_REQUIRED_UNCHANGED 为验证阶段专用状态; NO_CHANGE = distribute 目标暂存差异为空，未产生 commit/tag/push)"
           },
           "preObserve": {
             "type": "string",
@@ -206,6 +212,7 @@
                   "GATE_FAILED",
                   "AUTH_MISSING",
                   "REMOTE_CONFLICT",
+                  "REMOTE_UNAVAILABLE",
                   "HOOK_TIMEOUT",
                   "PARTIAL_RELEASE",
                   "POST_PUBLISH_VERIFY_FAILED"
@@ -223,6 +230,51 @@
           "phase": {
             "type": "string",
             "description": "Phase identifier for deferred checkpoints (e.g. post-publish-verification)"
+          },
+          "remoteUrl": {
+            "type": "string",
+            "description": "distribute 目标远端 URL"
+          },
+          "branch": {
+            "type": "string",
+            "description": "distribute 目标分支"
+          },
+          "tag": {
+            "type": "string",
+            "description": "distribute 分发 tag"
+          },
+          "tagCommit": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{40}$",
+            "description": "冻结的 create-tag 预期 commit"
+          },
+          "previousHead": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{40}$",
+            "description": "执行前目标分支 tip"
+          },
+          "pushedCommit": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{40}$",
+            "description": "实际推送的 commit（与 ls-remote 交叉核对）"
+          },
+          "mode": {
+            "type": "string",
+            "enum": [
+              "pushed",
+              "no-change",
+              "dry-run"
+            ],
+            "description": "distribute 执行模式"
+          },
+          "executor": {
+            "type": "string",
+            "description": "执行者标识"
+          },
+          "payloadFileCount": {
+            "type": "integer",
+            "minimum": 0,
+            "description": "写入目标的载荷文件数"
           }
         }
       }
@@ -568,7 +620,8 @@
           "command": {
             "enum": [
               "reconcile",
-              "verify"
+              "verify",
+              "distribute"
             ]
           }
         },

package/adapters/codex/skills/release-config/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: release-config
+description: "Config-only workflow profile: route confirms config-only diff, assess with schema validation, prepare --workflow config (code-class gates trimmed), workflowDecision records publish path (public bytes unchanged → no publish path; changed → lightchain prepare→approve→publish→verify)"
+---
+
+> **Codex 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md`。
+> 令 `RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。
+> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...`；不得依赖前一次 shell 的变量。
+>
+
+# release-config
+
+## 触发
+
+用户询问或执行纯配置变更的发布流程。包含 `.release-skill/project.yaml`、配置 schema 等配置文件的修改，且无代码、文档或 marketplace 变更。
+
+## 当前状态
+
+`release-config` 是工作流配置文件 (§4) 定义的独立工作流之一，专门处理仅配置变更的场景。它遵循简化生命周期，专注于配置验证和发布路径决策分支。
+
+**机械实现**: `prepare --workflow config` 确定性地裁剪代码类门禁（H5），并比较当前
+per-unit `snapshotDigest` 与最新冻结 plan——公开字节未变 → `publishPath:
+'no-publish-needed'`（externalActions 被移除，无 publish 路径）；字节变化或无对比
+plan → `publishPath: 'publish-needed'`（fail-safe）。决策以 `workflowDecision` 绑定
+进 plan digest，不可篡改。**不存在** `NO_PUBLISH_NEEDED`/`REPORTED` 虚构状态：
+prepare 的真实输出是 plan 内的 `workflowDecision`。
+
+**边界**: 跳过代码类 gates（declared hooks、snapshot-verify gates、source-authority
+closure、skill-resource-closure）。保留 baseline/snapshots/plan freeze/docs
+freshness。consumer-verify 仅在触发生效发布时参与。
+
+## 职责与边界
+
+- **步骤① diff 确认 config-only**: 调用 `release-skill route` command 确认仅有配置变更
+- **步骤② assess with schema validation**: 执行配置结构验证、schema 检查、contract 一致性
+- **步骤③ prepare --workflow config**: 本地 freeze 检查，生成只读计划；输出 `workflowDecision`
+- **步骤④ decision branch**（来自 plan.workflowDecision）:
+  - 场景 A：`publishPath === 'no-publish-needed'`（公开字节未变化）→ 记录决策并结束，
+    无 publish 路径，不运行 approve/publish/verify
+  - 场景 B：`publishPath === 'publish-needed'`（公开 surface 变化或不可判定）→ 运行
+    轻链 (approve→publish→verify)
+
+**授权边界**: 命令调用本身即授权执行配置的 hooks/gates。config-only 工作流的远程写操作受标准 approval 机制约束，不 bypass 安全 gate。
+
+**阶段通过规则**:
+- 场景 A: prepare 输出 `workflowDecision.decision === 'public-bytes-unchanged'`（无 publish 路径）
+- 场景 B: `status === 'VERIFIED'` + CLI exit code 0
+
+## 正向执行路径
+
+1. 运行 `release-skill route --root <path> --json` 获取 diff 分类
+2. 若推荐 `workflowKind === 'config-only'`，则使用本技能
+3. 执行步骤②：运行 `release-skill assess --root <path> --offline --json` 进行 schema validation
+4. 执行步骤③：运行 `release-skill prepare --offline --workflow config --target-version <ver> --json`
+5. 读取输出中的 `workflowDecision`：
+   - **A**: `publishPath === 'no-publish-needed'` → 记录决策（plan 已冻结，无
+     externalActions），结束。无需 approve/publish/verify
+   - **B**: `publishPath === 'publish-needed'` → 继续 approve → publish → verify 链条
+6. (场景 B 续) 执行步骤⑥：运行 `release-skill approve --plan <path> --actor <name>`
+7. (场景 B 续) 执行步骤⑦：运行 `release-skill publish --plan <path> --approval <path>`
+8. (场景 B 续) 执行步骤⑧：运行 `release-skill verify --plan <path> --run <path>`
+
+## 确定性脚本调用
+
+```bash
+# Step 1: Diff classification confirmation (config-only)
+node "$RELEASE_SKILL_ENTRY" route --root <path> --json
+
+# Step 2: Assess with schema validation
+node "$RELEASE_SKILL_ENTRY" assess --root <path> --offline --json
+
+# Step 3: Prepare --workflow config (local freeze + publish-path decision)
+node "$RELEASE_SKILL_ENTRY" prepare --offline \
+  --workflow config --target-version <version> --json
+# Output (JSON): { workflowKind: 'config',
+#   workflowDecision: { decision: 'public-bytes-unchanged'|'public-bytes-changed'|'indeterminable',
+#     publishPath: 'no-publish-needed'|'publish-needed', comparedPlan: '<digest>.json' } }
+
+# Decision Branch A (no-publish-needed): plan frozen with zero externalActions;
+# the decision is bound into the plan digest. No publish commands run.
+
+# Decision Branch B (publish-needed): light chain execution
+node "$RELEASE_SKILL_ENTRY" approve \
+  --plan <path> --actor <person-name>
+node "$RELEASE_SKILL_ENTRY" publish \
+  --plan <path> --approval <path>
+node "$RELEASE_SKILL_ENTRY" verify \
+  --plan <path> --run <path> --json
+```
+
+## 故障路由
+
+| 场景 | 状态 | 处理 |
+|------|------|------|
+| 非纯配置变更（mixed=true） | full-happy-end | 路由到 `release-skill ship` 完整工作流 |
+| schema validation 失败 | CONFIG_SCHEMA_INVALID | 修正 project.yaml 或 schemas 结构错误后重试 step② |
+| contract verification 失败 | CONFIG_CONFLICT | 解决配置冲突后重试 step② |
+| prepare 检测到基线漂移 | BASELINE_DRIFT_DETECTED | 人工审查 drift 后决定是否继续或回滚 |
+| workflowDecision 不可判定（无对比 plan） | indeterminable | fail-safe 到 publish-needed，走场景 B |
+| approval expired | APPROVAL_EXPIRED | 重新执行 approve，digest 必须匹配 |
+| remote conflict at publish | REMOTE_CONFLICT | 人工决策：force override 或 cancel |
+
+## 决策树 (Step 4)
+
+```
+┌─────────────────────────────────────────┐
+│  prepare --workflow config completed    │
+└──────────────────┬──────────────────────┘
+                   │
+        ┌──────────┴──────────┐
+        │                     │
+        ▼                     ▼
+┌───────────────┐   ┌───────────────────┐
+│ public bytes  │   │ public bytes      │
+│ unchanged     │   │ changed /         │
+│ (or no plan   │   │ indeterminable    │
+│  → fail-safe  │   │                   │
+│  → publish    │   │                   │
+│  needed)      │   │                   │
+└───────┬───────┘   └────────┬──────────┘
+        │                    │
+        ▼                    ▼
+┌───────────────┐   ┌───────────────────┐
+│ no-publish    │   │ light chain       │
+│ needed:       │   │ approve→publish   │
+│ decision      │   │ →verify           │
+│ recorded in   │   │                   │
+│ plan digest   │   │                   │
+└───────────────┘   └───────────────────┘
+```
+
+## 与其他工作流的关系
+
+- **docs-only**: 纯文档变更时使用 `release-docs`
+- **marketplace-only**: 仅 marketplace 变更时使用独立工作流
+- **full-happy-end**: 混合变更（code+config+docs）时降级到此完整路径
+
+## 关联技能
+
+- `release-skill route`: 快速入门决策路由（§4.3）
+- `release-assess`: 配置 schema/contract 验证入口
+- `release-prepare`: 离线冻结检查（`--workflow config` 输出 publish-path 决策）
+- `release-approve`: Plan approval（仅场景 B）
+- `release-publish`: 制品发布（仅在 public surface 变化时执行）
+- `release-verify`: 消费者验证（场景 B 的最终验证门）

package/adapters/codex/skills/release-docs/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: release-docs
+description: "Docs-only workflow profile: route confirms docs-only diff, style-guard gates (check-style.mjs file paths), render-public-site --check drift scan, docs refresh rehearsal → binder write, prepare --workflow docs (code-class gates trimmed), approve/publish/verify with consumer-verify preserved"
+---
+
+> **Codex 安装入口解析协议**：在调用 CLI 前，Agent 必须从宿主当前已加载技能的元数据中取得本 `SKILL.md` 的实际绝对路径，并将该字面量记为 `SKILL_FILE`。
+> `SKILL_FILE` 不是环境变量；禁止从工作目录、可执行搜索路径、源码仓库或 shell 调用上下文猜测。若宿主未提供该绝对路径，立即停止并报告安装定位失败。
+> 对 `SKILL_FILE` 执行 `realpath`，取其目录向上两级得到 `PLUGIN_ROOT`；校验真实技能路径匹配 `PLUGIN_ROOT/skills/*/SKILL.md`。
+> 令 `RELEASE_SKILL_ENTRY=PLUGIN_ROOT/bin/release-skill.mjs`，对入口执行 `realpath` containment、`lstat` 非符号链接且为普通文件校验。
+> 每一次 shell 工具调用都必须在同一个调用中用上述已验证绝对值设置 `RELEASE_SKILL_ENTRY`，然后执行 `node "$RELEASE_SKILL_ENTRY" ...`；不得依赖前一次 shell 的变量。
+>
+
+# release-docs
+
+## 触发
+
+用户询问或执行纯文档变更的发布流程。包含 `docs/public/site/`, `README*`, `CHANGELOG`, `release-notes/` 等文件的修改，且无代码、配置或 marketplace 变更。
+
+## 当前状态
+
+`release-docs` 是工作流配置文件 (§4) 定义的独立工作流之一，专门处理仅文档变更的场景。它遵循标准发布生命周期，但跳过代码类检查门（声明式 hooks、snapshot-verify gates、source-authority closure、skill-resource-closure），专注于文档质量 gate。
+
+**机械实现**: `prepare --workflow docs` 在 prepare 内确定性地裁剪代码类门禁（H5），
+plan 记录 `workflowKind: 'docs'` 与 `workflowDecision`（绑定进 plan digest）。
+**边界**: NOT merging repos；不对代码类 gates（如 schema validation、contract verification）负责。
+
+## 职责与边界
+
+- **步骤① diff 分类确认**: 调用 `release-skill route` command 对工作树 diff 分类，确认仅有文档变更
+- **步骤② style-guard 三道门**: 调用 `check-style.mjs`（只接受文件路径参数，exit 0/1/2）执行事实性/可读性/风格检查
+- **步骤③ render-public-site --check**: 调用 `render-public-site.mjs --check [--repo <name>]` 做渲染漂移扫描（内存泄漏扫描 + 树基线对比）
+- **步骤④ docs refresh**: 执行 rehearsal → binder 写入（本地文档更新，不 commit/push）
+- **步骤⑤ prepare --workflow docs**: 轻量 freeze（裁剪代码类 gates，保留 docs freshness/public-surface/baseline/snapshots/plan freeze）
+- **步骤⑥–⑧**: approve → publish → verify（consumer-verify 保留）
+
+**授权边界**: 命令调用本身即授权执行配置的 hooks/gates。本地文档写入授权只覆盖声明的本地文档目标，不是 Git commit/push/publish 或安装的授权。
+
+**阶段通过规则**: `status === 'VERIFIED'` 且 CLI exit code 为 0。`PARTIAL` 状态允许安全重试已完成的 checkpoint。
+
+## 正向执行路径
+
+1. 运行 `release-skill route --root <path> [--target-version <ver>] --json` 获取 diff 分类和工作流推荐
+2. 若推荐 `workflowKind === 'docs-only'`，则使用本技能
+3. 执行步骤②：调用 `check-style.mjs <doc-path>...` 执行事实/可读性/风格检查
+4. 执行步骤③：调用 `render-public-site.mjs --check [--repo <name>]` 验证渲染无漂移
+5. 执行步骤④：运行 `release-skill docs refresh --unit <id> --write --confirm-refresh <digest> --ack-local-document-write`
+6. 执行步骤⑤：运行 `release-skill prepare --offline --workflow docs --target-version <ver>`
+7. 执行步骤⑥：人工审阅后运行 `release-skill approve --plan <path> --actor <name>`
+8. 执行步骤⑦：运行 `release-skill publish --plan <path> --approval <path>`
+9. 执行步骤⑧：运行 `release-skill verify --plan <path> --run <path>`
+
+## 确定性脚本调用
+
+```bash
+# Step 1: Diff classification (from release-skill route)
+node "$RELEASE_SKILL_ENTRY" route --root <path> --json
+
+# Step 2: Style-guard three gates (check-style.mjs takes file paths only)
+node "${WORKBUDDY_ROOT}/adapters/workbuddy/skills/skill-family-docs-style-guard/scripts/check-style.mjs" \
+  <doc-path-1> <doc-path-2>
+
+# Step 3: Render site check (drift + leak scan against committed baseline)
+node "${DOC_RENDER_ROOT}/packages/skill-family-doc-render/scripts/render-public-site.mjs" --check [--repo <repo-name>] # source-only
+
+# Step 4: Docs refresh with rehearsal
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> --json
+# Then confirm and write:
+node "$RELEASE_SKILL_ENTRY" docs refresh --unit <id> \
+  --write --confirm-refresh <refreshDigest> --ack-local-document-write --json
+
+# Step 5: Lightweight prepare --workflow docs
+node "$RELEASE_SKILL_ENTRY" prepare --offline \
+  --workflow docs --target-version <version> --json
+
+# Step 6: Approval
+node "$RELEASE_SKILL_ENTRY" approve \
+  --plan <path> --actor <person-name>
+
+# Step 7: Publish
+node "$RELEASE_SKILL_ENTRY" publish \
+  --plan <path> --approval <path>
+
+# Step 8: Verify (consumer-verify preserved)
+node "$RELEASE_SKILL_ENTRY" verify \
+  --plan <path> --run <path> --json
+```
+
+## 故障路由
+
+| 场景 | 状态 | 处理 |
+|------|------|------|
+| 非纯文档变更（mixed=true） | full-happy-end | 路由到 `release-skill ship` 完整工作流 |
+| style-guard 检查失败 | exit 1（check-style.mjs） | 修正文档问题后重试 step② |
+| check-style.mjs 运行错误 | exit 2 | 检查参数（只接受文件路径）与文件存在性 |
+| render-site 漂移 | RENDER_SITE_DRIFT | 重新渲染并提交基线后重试 step③ |
+| prepare 检测到未刷新文档 | PREPARE_STALE_DOCS | 重新执行 step④ → 提交 → 重新 prepare |
+| 非 VERIFIED 终态 | NEEDS_INPUT / BLOCKED | 根据错误码诊断具体问题 |
+
+## 与其他工作流的关系
+
+- **config-only**: 仅配置变更时使用 `release-config`
+- **marketplace-only**: 仅 marketplace 变更时使用独立工作流
+- **full-happy-end**: 混合变更（code+docs）时降级到此完整路径
+
+## 关联技能
+
+- `release-skill route`: 快速入门决策路由（§4.3）
+- `release-assess`: 项目发布就绪度评估
+- `release-prepare`: 冻结发布计划（`--workflow docs` 裁剪代码类门禁）
+- `release-publish`: 发布 GitHub/npm 制品
+- `release-verify`: 消费者验证和远程状态重检
+- `skill-family-docs-style-guard`（skill-family-docs adapter）: `check-style.mjs` 文档质量三道门
+- `render-public-site`（skill-family-doc-render）: 站点渲染漂移与泄漏扫描