@namewta/speculo 1.0.19 → 1.0.21

package/template/skills/github-npm-ops/references/issue-transport.md

@@ -1,26 +0,0 @@
-# GitHub Issue Transport
-
-本合同提供 GitHub 的读取和受控写入原语，不承担 SpecDev tracker、change、Ticket、Map 或报告所有权。
-
-## 操作
-
-- `issue-read`：读取 title、body、state、URL、author、labels、时间与全部可见评论。
-- `pr-read`：读取 PR 正文、评论、文件列表以及不可变 base/head SHA。
-- `issue-search`：按 query 返回候选，用于去重。
-- `issue-create`：默认 dry-run；调用方确认后使用 `--apply`。
-- `issue-comment-close`：按 marker 幂等评论并关闭；默认 dry-run，只有调用方确认后使用 `--apply`。
-
-脚本：`scripts/issue-transport.mjs`。所有参数通过 argv 传递，不使用 shell 拼接；输出为 JSON，失败退出非零。
-
-## 写入边界
-
-调用方必须在执行前展示 repo、Issue、标题或评论、labels/reason 和准确动作，并取得本次明确授权。脚本的 `--apply` 只表示调用方已经完成该确认，不替代授权本身。
-
-不得把 token、Cookie、认证输出、机器绝对路径或包含秘密的正文写入长期工件。部分失败由调用方保存已完成步骤和恢复条件；不得因远程失败回滚本地事实。
-
-## 完成标准
-
-- 读取结果可以冻结为调用方拥有的工件；
-- dry-run 的外部写入为零；
-- comment-close 的 marker 使重试不会重复评论；
-- 成功结论来自执行后的远程重读。

package/template/skills/github-npm-ops/references/package-json-checklist.md

@@ -1,171 +0,0 @@
-# package.json 发布前字段清单
-
-发布失败的一半原因都是 `package.json` 少字段或字段错位。按这张清单逐项确认。
-
-## 必填字段
-
-### name
-
-- 普通包：全局唯一，小写 + 连字符（如 `my-cli`）
-- Scoped 包：`@scope/name`，必须先在 npm 上拥有 scope
-- **首次发布前用 `npm view <name>` 查询是否被占用**；返回 404 才可用
-
-```bash
-npm view my-cli                 # 404 = 可用；有输出 = 已占用
-npm view @scope/my-cli          # 首次发布会 404，正常
-```
-
-### version
-
-- 遵循 SemVer（MAJOR.MINOR.PATCH）
-- 必须与要发布的 git tag 严格匹配：tag `v0.0.2` ↔ version `0.0.2`
-- npm **不允许重复发布同一个 version**，即使之前 unpublished 也不行（24h 内）
-
-### repository
-
-**npm provenance 强制要求这个字段**，缺失会报 `E422`。
-
-```json
-{
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/owner/my-cli"
-  }
-}
-```
-
-- `url` 必须指向实际托管 workflow 的 GitHub 仓库
-- 注意大小写：GitHub 虽不区分，但 provenance 验证严格匹配
-
-### license
-
-SPDX 标识符（如 `MIT`、`Apache-2.0`、`ISC`）。别写 `LICENSE.md` 或随意字符串。
-
-## CLI 包专用字段
-
-### bin
-
-命令入口。路径必须以 `./` 开头：
-
-```json
-{
-  "bin": {
-    "my-cli": "./dist/cli/index.js"
-  }
-}
-```
-
-入口文件必须：
-
-1. 有可执行权限（`chmod +x`，或通过 `scripts/inject-shebang.mjs` 注入 shebang）
-2. 首行是 `#!/usr/bin/env node`
-3. 是 ESM（`"type": "module"` 时）或 CJS，与 package 一致
-
-### files
-
-显式允许列表，避免把源码、测试、`.env` 发到 npm：
-
-```json
-{
-  "files": [
-    "dist",
-    "templates",
-    "!dist/**/*.test.js",
-    "!dist/**/__tests__",
-    "!dist/**/*.map"
-  ]
-}
-```
-
-- 不写 `files` 时，npm 走 `.gitignore` 加一堆默认规则，通常会漏发或误发
-- 发布前用 `npm pack --dry-run` 看看 tarball 实际内容
-
-## 推荐但可选字段
-
-### description / keywords
-
-影响 npm 搜索结果，写清楚。
-
-### homepage / bugs
-
-```json
-{
-  "homepage": "https://github.com/owner/my-cli#readme",
-  "bugs": {
-    "url": "https://github.com/owner/my-cli/issues"
-  }
-}
-```
-
-显示在 npm 包页面，方便用户找文档和报问题。
-
-### engines
-
-```json
-{
-  "engines": {
-    "node": ">=24.14.1"
-  }
-}
-```
-
-声明最低 Node 版本；npm 会在安装时提示（但不会阻止）。
-
-### type / exports
-
-ESM 包：
-
-```json
-{
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    }
-  }
-}
-```
-
-## scripts
-
-### prepublishOnly
-
-发布前的质量闸门。仅在 `npm publish` 前执行（`npm install` 不触发）：
-
-```json
-{
-  "scripts": {
-    "prepublishOnly": "pnpm check"
-  }
-}
-```
-
-`pnpm check` 通常是 `pnpm lint && pnpm test && pnpm build`。
-
-### 不要用的 scripts
-
-- `prepublish` — 已废弃，会在 `install` 时也触发，容易误伤
-- `prepare` — 在 `install` 时也跑，写构建命令会导致普通安装变慢
-
-## 发布前自检流程
-
-```bash
-# 1. 检查 name 可用（首次发布）
-npm view @scope/my-cli
-
-# 2. 版本一致性
-node -e "console.log(require('./package.json').version)"
-git tag --list 'v*' | sort -V | tail -3
-
-# 3. tarball 内容预览
-npm pack --dry-run
-
-# 4. 运行质量闸门
-pnpm check
-
-# 5. 预演发布（不会真的推送）
-npm publish --dry-run --access public --provenance
-```
-
-如果 5 个命令都正常，再执行真正的 `git tag && git push origin <tag>` 触发 CI 发布。

package/template/skills/github-npm-ops/references/preflight-checklist.md

@@ -1,39 +0,0 @@
-# Phase 0 — 前置检测完整清单
-
-> 本文件是发布编排流程（[release-pipeline.md](release-pipeline.md)）Phase 0 的「展开形态」。编排正文只列出核心前置；这里给出 11 项完整探测、失败信号与建议修复。
-> 全部探测都是**只读**的，不会修改任何文件。任一项不通过 → 命令终止，输出修复建议；不要尝试自动跳过。
-
-## 探测矩阵
-
-| # | 项 | 探测命令 | 通过判定 | 失败建议 |
-|---|----|---------|---------|---------|
-| 1 | 当前分支 | `git rev-parse --abbrev-ref HEAD` | 输出 = 仓库声明的发布分支（默认 `main`） | `git checkout main` 后重新触发；或显式声明本仓库的发布分支 |
-| 2 | 工作区干净 | `git status --porcelain` | 输出为空 | 先 stash / commit；不允许 `git stash` 后立刻发版（stash 内容易丢失） |
-| 3 | 远端可达 | `git ls-remote --exit-code origin` | 退出码 0 | 检查网络 / SSH key / `gh auth status` |
-| 4 | gh 已登录 | `gh auth status` | 含 `Logged in to github.com` | `gh auth login` |
-| 5 | gh 仓库权限 | `gh repo view --json viewerCanAdminister` | `viewerCanAdminister == true` 或至少 push 权限 | 联系仓库管理员；或 fork 后申请 PR 流程 |
-| 6 | Node 版本 | `node --version` | ≥ `package.json#engines.node` | `nvm use` / `fnm use` / 升级本机 Node |
-| 7 | 包管理器 | `pnpm --version` (或 `npm` / `yarn`) | 版本 ≥ 仓库 lockfile 隐含版本 | 安装匹配版本；不要随意切换包管理器 |
-| 8 | release.yml 存在 | `test -f .github/workflows/release.yml` | 文件存在 | 转 `github-npm-ops` skill 的 `references/workflow-yaml-reference.md` 先落该文件 |
-| 9 | release.yml 形态 | 见 [publish-detection.md](publish-detection.md) | 输出 `PUBLISH_TO_NPM=true` 或 `false` | 见 publish-detection 文档的判定矩阵 |
-| 10 | docs-sync state | 对 `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 执行存在性检查与 JSON 解析 | schema v4、scope 已确认，baseline 可解析 | 不存在/未确认 → 走 docs-sync command bootstrap；旧 schema 或损坏 → 停止发布并按 docs-sync state contract 修复，`speculo init` 不解析未登记的 command state |
-| 11 | tag 名称冲突 | `git rev-parse vX.Y.Z 2>/dev/null` | 退出码非 0（tag 不存在） | 同 tag 已存在：先确认是否真的失败需要重发；若是则 `git tag -d` + `git push origin :refs/tags/vX.Y.Z`，否则 bump 到下一版本 |
-
-## 失败处理总策略
-
-- 探测项 1–3、6–7：本机环境问题，提示用户人工修复后重跑命令
-- 探测项 4–5：GitHub 权限问题，给出对应的 `gh` 命令
-- 探测项 8：基础设施缺失，明确转交 `github-npm-ops` skill 而不是在本命令里现写 release.yml
-- 探测项 9：影响 Phase 5 的分支选择，**不阻塞**命令执行（仅决定后续是否做 npm view 校验）
-- 探测项 10：影响 Phase 2 是否进入 docs-sync 主流程
-- 探测项 11：直接关系到能否打 tag，必须在 Phase 0 阶段就排除
-
-## 与后续 Phase 的边界
-
-Phase 0 只做**只读探测**，不执行任何修复 SOP：
-
-- 提交与版本操作在 Phase 1 / Phase 3（见 [version-bump-flow.md](version-bump-flow.md)）
-- 文档同步在 Phase 2 / Phase 6（由调用方执行 `docs-sync` command）
-- 发布监控、验证与恢复在 Phase 4 / 5（见 [release-pipeline.md](release-pipeline.md)、[failure-recovery.md](failure-recovery.md)）
-
-如果 Phase 0 嗅探到的状态需要某个修复 SOP（如 release.yml 缺失），明确转交对应 reference，不要在前置检测阶段现场修复。

package/template/skills/github-npm-ops/references/publish-detection.md

@@ -1,68 +0,0 @@
-# Release.yml 是否含 npm publish 的判定脚本
-
-> 用于决定 Phase 5 是否做 npm 端校验。命令正文只展示了核心 grep；这里给出完整模式集合、第三方 action 清单与误判排除策略。
-
-## 判定输出
-
-```bash
-RELEASE_YML=".github/workflows/release.yml"
-
-if [ ! -f "$RELEASE_YML" ]; then
-  echo "RELEASE_YML_MISSING=true"
-  exit 0
-fi
-
-# 主判定：是否含 npm publish 步骤
-if grep -Eq 'npm[[:space:]]+publish|run:[[:space:]]*pnpm[[:space:]]+publish|run:[[:space:]]*yarn[[:space:]]+publish|JS-DevTools/npm-publish|cycjimmy/semantic-release-action|changesets/action' "$RELEASE_YML"; then
-  echo "PUBLISH_TO_NPM=true"
-else
-  echo "PUBLISH_TO_NPM=false"
-fi
-```
-
-## 模式集合
-
-`PUBLISH_TO_NPM=true` 命中下列任一行时为真：
-
-| 模式 | 形态 | 说明 |
-|------|------|------|
-| `npm publish` | `run: npm publish --provenance --access public` | 官方 npm CLI |
-| `pnpm publish` | `run: pnpm publish --no-git-checks` | pnpm 包管理器 |
-| `yarn publish` | `run: yarn publish --new-version $VERSION` | 旧 yarn / berry |
-| `JS-DevTools/npm-publish@vN` | `uses: JS-DevTools/npm-publish@v3` | 第三方封装 action |
-| `cycjimmy/semantic-release-action@vN` | `uses: cycjimmy/semantic-release-action@v4` | semantic-release 流水线 |
-| `changesets/action@vN` | `uses: changesets/action@v1` 且配置 `publish:` 输入 | Changesets 风格的多包发布 |
-
-## 误判排除
-
-下列形态**不应**触发 `PUBLISH_TO_NPM=true`：
-
-| 形态 | 是否触发 | 原因 |
-|------|---------|------|
-| `# npm publish` 注释行 | ❌ | grep `-E` 默认匹配整行；如需更严格可加 `^[^#]*` 锚定 |
-| `description: 'Run npm publish ...'` | ⚠️ 可能误命中 | 收紧 grep 为 `run:[[:space:]]*npm[[:space:]]+publish` 即可避免 |
-| `npm publish --dry-run` | ✅ 仍命中 | 视作真发布意图；如需排除，可在判定后追加 `--dry-run` 检查并手动降级 |
-| `npm pack` | ❌ | `pack` 不是 `publish` |
-| 仅 `softprops/action-gh-release` | ❌ | 这是 GitHub Release 创建器，不是 npm publish |
-
-## 收紧版（推荐用于精确判定）
-
-```bash
-grep -E '^\s*(run:\s*(npm|pnpm|yarn)\s+publish|uses:\s*(JS-DevTools/npm-publish|cycjimmy/semantic-release-action|changesets/action))\b' "$RELEASE_YML"
-```
-
-> 如果仓库使用了非主流的发布方式（如自写 shell 脚本里调用 `npm publish`），grep 仍可能漏判。
-> 漏判后果：Phase 5 跳过 `npm view` 校验。这是**安全侧**漏判（不会误报"未发布"），但用户应在该仓库的 README 或 SKILL 注释里明确发布方式，避免歧义。
-
-## 多 workflow 文件的处理
-
-若仓库有多个 release 相关 workflow（如 `release.yml` + `publish-canary.yml`），默认只看 `release.yml`。
-如需扩展，在调用方 workflow 或项目上下文中声明 `releaseWorkflowPaths: [...]`，执行时按该列表逐个判定。
-
-## 与 Phase 5 的衔接
-
-| 嗅探结果 | Phase 5 行为 |
-|---------|-------------|
-| `PUBLISH_TO_NPM=true` | 跑 `gh release view` + `gh run` + `npm view` 三端 |
-| `PUBLISH_TO_NPM=false` | 仅跑 `gh release view` + `gh run` 两端，并向用户输出「本仓库 release.yml 不含 npm publish 步骤」提示 |
-| `RELEASE_YML_MISSING=true` | Phase 0 直接终止，不进入后续 phase |

package/template/skills/github-npm-ops/references/release-notes-injection.md

@@ -1,238 +0,0 @@
-# CHANGELOG → GitHub Release notes 注入
-
-让每次 `git push origin vX.Y.Z` 触发的 GitHub Release **正文非空**、**与 CHANGELOG 段落严格一致**的标准方案。
-
-## 1. 为什么 GitHub Release 默认是空的
-
-`softprops/action-gh-release@v2` 仅设 `generate_release_notes: true` 时,GitHub 内部调用的是 **REST API `POST /repos/{owner}/{repo}/releases/generate-notes`**,该接口的输入是「上一个 tag → 当前 tag」之间的 **commit + PR + label**,优先取 PR 标题做分类。
-
-两种典型场景下生成器会"贫瘠":
-
-| 场景 | 生成器输出 | 原因 |
-|------|----------|------|
-| 直 push main(无 PR 流程) | 仅 `Full Changelog: vA...vB` 一行 | 生成器没有 PR 可分类,只能给 compare 链接 |
-| 有 PR 但仓库没有 `.github/release.yml` | 全部 PR 都被塞进 "What's Changed" 一节 | 没有 label → 章节映射 |
-
-而仓库通常已经维护了 `CHANGELOG.md`(Keep a Changelog 格式)。**正确做法是把 CHANGELOG 段落作为 Release 正文的事实来源**,自动生成器仅作为补充链接。
-
-## 2. 注入方案
-
-核心思路:在 workflow 里加一步,从 `CHANGELOG.md` 抽取当前 tag 对应的版本段落,写到 `release-notes.md`,再通过 `softprops/action-gh-release` 的 `body_path` 注入。
-
-### 2.1 完整 workflow 步骤
-
-加到 `Verify bin entry` 之后、`Publish to npm` 之前(也可以放 publish 之后,只要在 Create GitHub Release 之前):
-
-```yaml
-- name: Extract release notes from CHANGELOG.md
-  run: |
-    VERSION="${GITHUB_REF_NAME#v}"
-    awk -v v="$VERSION" '
-      $0 ~ "^## \\["v"\\]" { found=1; print; next }
-      found && /^## \[/ { exit }
-      found && /^---[[:space:]]*$/ { next }
-      found { print }
-    ' CHANGELOG.md > release-notes.md
-
-    if [ ! -s release-notes.md ]; then
-      echo "::warning::CHANGELOG.md 中未找到 [$VERSION] 段落,回退到自动生成。"
-      echo "See [CHANGELOG.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOG.md) for details." > release-notes.md
-    fi
-
-    echo "--- Release notes preview ---"
-    cat release-notes.md
-    echo "-----------------------------"
-
-- name: Create GitHub Release
-  uses: softprops/action-gh-release@v2
-  if: success()
-  with:
-    tag_name: ${{ github.ref_name }}
-    name: Release ${{ github.ref_name }}
-    body_path: release-notes.md          # ← 关键
-    generate_release_notes: true         # ← 与 body_path 共存,不冲突
-    draft: false
-    prerelease: false
-  env:
-    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-```
-
-### 2.2 awk 抽取规则解释
-
-```awk
-$0 ~ "^## \\["v"\\]" { found=1; print; next }   # 1. 命中 "## [X.Y.Z]" 起始锚点,开关打开,打印当行
-found && /^## \[/ { exit }                       # 2. 已在段落内,遇到下一个 "## [" 立刻退出
-found && /^---[[:space:]]*$/ { next }            # 3. 跳过 "---" 分隔符(GitHub Release 不需要)
-found { print }                                  # 4. 段落内的其他行原样输出
-```
-
-边界用例:
-
-- **段落是 CHANGELOG 末尾**:没有下一个 `## [`,awk 跑到 EOF 自然结束
-- **存在 `[Unreleased]` 段落**:不会被误抓,因为锚点要求精确匹配 `[X.Y.Z]` 形式
-- **版本号含连字符(rc / beta)**:`0.0.10-rc1` 也能匹配,因为 awk 把 `v` 当字面量
-- **CHANGELOG 缺该段**:`-s` 测试为空 → 写入兜底文案 + 输出 warning
-
-### 2.3 `body_path` + `generate_release_notes` 共存语义
-
-`softprops/action-gh-release@v2` 在两者同时存在时:
-
-- **正文头部**:`body_path` 文件内容(你的 CHANGELOG 段落)
-- **正文尾部**:GitHub 自动生成的 "What's Changed" + "Full Changelog" compare 链接
-
-这是最优组合:**人写的精炼说明 + 机器可追溯的 PR/commit 索引**。
-
-## 3. 事后修复历史 Release(已发布版本正文为空)
-
-GitHub Release 的正文(body)**事后可改**(tag 不可改、npm 包不可改、但 Release body 可改)。两种方式:
-
-### 3.1 命令行(推荐)
-
-`notes_file` 只是一次性传给 `gh --notes-file` 的中间文件；若需要保留回填记录或 release notes，由调用方写入 `<Path>{roots.state}/commands/{command}/{date}-{scope}-{topic}[-NN].md</Path>`。
-
-```bash
-VERSION="0.0.10"
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-awk -v v="$VERSION" '
-  $0 ~ "^## \\["v"\\]" { found=1; print; next }
-  found && /^## \[/ { exit }
-  found && /^---[[:space:]]*$/ { next }
-  found { print }
-' CHANGELOG.md > "$notes_file" && \
-  gh release edit "v$VERSION" --notes-file "$notes_file"
-```
-
-### 3.2 GitHub UI
-
-进入 `https://github.com/<owner>/<repo>/releases/tag/vX.Y.Z`,右上角铅笔图标 → 粘贴 CHANGELOG 段落 → Update release。
-
-### 3.3 批量回填多个历史版本
-
-```bash
-notes_file="$(mktemp -t speculo-release-notes.XXXXXX)"
-trap 'rm -f "$notes_file"' EXIT
-
-for v in 0.0.7 0.0.8 0.0.9; do
-  awk -v ver="$v" '
-    $0 ~ "^## \\["ver"\\]" { found=1; print; next }
-    found && /^## \[/ { exit }
-    found && /^---[[:space:]]*$/ { next }
-    found { print }
-  ' CHANGELOG.md > "$notes_file"
-
-  if [ -s "$notes_file" ]; then
-    gh release edit "v$v" --notes-file "$notes_file"
-    echo "✓ v$v"
-  else
-    echo "✗ v$v: CHANGELOG 中无对应段落,跳过"
-  fi
-done
-```
-
-## 4. 进阶:走 PR 流程的项目
-
-若仓库以 PR 为主、合并产生 commit,推荐 **同时**保留 CHANGELOG 注入 + 配置 `.github/release.yml` 让自动生成器分类更友好。
-
-### 4.1 `.github/release.yml`(GitHub 原生分类配置)
-
-```yaml
-# .github/release.yml
-changelog:
-  exclude:
-    labels:
-      - ignore-for-release
-      - dependencies      # 可选:依赖升级单独成节
-  categories:
-    - title: 🚀 Features
-      labels:
-        - feat
-        - feature
-        - enhancement
-    - title: 🐛 Bug Fixes
-      labels:
-        - fix
-        - bug
-    - title: 📚 Documentation
-      labels:
-        - docs
-        - documentation
-    - title: ♻️ Refactoring
-      labels:
-        - refactor
-    - title: 🧪 Testing
-      labels:
-        - test
-    - title: 🔧 Maintenance
-      labels:
-        - chore
-        - ci
-    - title: Other Changes
-      labels:
-        - "*"
-```
-
-效果:`generate_release_notes` 自动产出的 "What's Changed" 会被分类到上述章节中,与 CHANGELOG 段落叠加在 Release 正文内。
-
-### 4.2 配套的 PR label 自动化
-
-参考仓库已有 `.github/labeler.yml` + `.github/workflows/label-pr.yml`,基于改动路径自动打 label。也可让 PR 模板提示作者按 Conventional Commits 选择类型。
-
-## 5. 多语言 CHANGELOG 处理
-
-如果项目同时维护 `CHANGELOG.md` + `CHANGELOG-ZH.md`,Release 正文应优先取**主语言**(通常英文)。两种策略:
-
-### A. workflow 选择主语言(简单)
-
-```yaml
-- name: Extract release notes
-  run: |
-    # 主语言文件名作为输入
-    awk -v v="${GITHUB_REF_NAME#v}" '...' CHANGELOG.md > release-notes.md
-```
-
-### B. workflow 拼接双语(完整)
-
-```yaml
-- name: Extract release notes (bilingual)
-  run: |
-    VERSION="${GITHUB_REF_NAME#v}"
-    EXTRACT='$0 ~ "^## \\["v"\\]" { found=1; print; next } found && /^## \[/ { exit } found && /^---[[:space:]]*$/ { next } found { print }'
-
-    {
-      awk -v v="$VERSION" "$EXTRACT" CHANGELOG.md
-      echo
-      echo "---"
-      echo
-      echo "### 中文版本说明"
-      echo
-      awk -v v="$VERSION" "$EXTRACT" CHANGELOG-ZH.md
-    } > release-notes.md
-```
-
-## 6. 常见坑位
-
-| 坑 | 现象 | 解法 |
-|---|------|------|
-| `body_path` 文件不存在 | action 失败 `Could not find the body_path` | 加 `if [ ! -s release-notes.md ]` 兜底写入 |
-| awk 没匹配到 | release-notes.md 为空,Release 正文兜底文案 | 检查 CHANGELOG 段落标题与 tag 是否对应(`v0.0.10` ↔ `## [0.0.10]`) |
-| awk 多匹配(同一版本写了两次) | Release 正文重复内容 | CHANGELOG 是 source of truth,先去重 |
-| 全角中括号 `【】` 被当锚点 | 抽取失败 | CHANGELOG 标题统一用半角 `[` |
-| body_path 文件含 BOM | Release 渲染异常 | 用 `sed -i '1s/^\xef\xbb\xbf//' release-notes.md` 去 BOM |
-
-## 7. 验证
-
-每次发布后必查:
-
-```bash
-# Release body 必须非空且包含 CHANGELOG 关键章节
-gh release view "v$VERSION" --json body --jq '.body' | head -20
-
-# 三端齐绿才算发布完成
-npm view @scope/pkg version
-gh release view "v$VERSION" --json isDraft,isPrerelease,publishedAt
-gh run view <run-id> --json conclusion,jobs --jq '{conclusion, steps: [.jobs[].steps[] | select(.name | contains("Extract") or contains("Release")) | {name, conclusion}]}'
-```
-
-`Extract release notes` 步骤未 success → Release 正文将走兜底文案,需排查 awk 是否抽空。

package/template/skills/github-npm-ops/references/release-pipeline.md

@@ -1,108 +0,0 @@
-# npm + GitHub Release 编排
-
-把一次 npm 包发布拆成可验证的单向流水线：前置检查 -> 普通改动 commit -> docs-sync -> release commit -> tag -> workflow 监控 -> 三端验证 -> docs-sync 记录 release 节点。
-
-## Iron Law
-
-- 禁止提交破坏构建的代码；release 前必须运行仓库声明的 lint / test / build 或等价质量闸。
-- docs-sync 必须由调用方按 `<Path>{roots.commands}/docs-sync.md</Path>` 执行；输入起点来自最后修改 state 文件的 commit，终点是运行前清洁后的 HEAD，并写入 `last_range`。
-- tag 必须精确指向 release commit，即包含 `package.json` version bump 与 CHANGELOG 迁移的 commit；禁止指向后续 docs / state commit。
-- npm 已成功上传后，同一 version 不可重发；不要通过删 tag 或 unpublish 试图覆盖。
-
-## Phase 0 — 前置检测
-
-读取 `preflight-checklist.md` 和 `publish-detection.md`，固定确认：
-
-- 当前分支是发布分支，默认 `main`
-- 工作区干净，远端可达，`gh auth status` 正常
-- Node 与包管理器满足仓库声明
-- `.github/workflows/release.yml` 存在
-- 已确定 `PUBLISH_TO_NPM=true | false`
-- `<Path>{roots.state}/commands/docs-sync/state.json</Path>` 存在且可解析；不存在时转 docs-sync command 的首次 bootstrap
-- 目标 tag `vX.Y.Z` 不存在，除非正在执行明确的失败恢复
-
-任一项不通过就停止，输出修复建议。
-
-## Phase 1 — 普通改动 commit
-
-- 运行仓库质量闸：优先 `pnpm check`，否则按项目脚本组合 lint / test / build。
-- 审查提交粒度；不把无关修改塞进一个 commit。
-- 暂存显式路径，避免 `git add .` 纳入噪声。
-- 使用 Conventional Commits；body 说明做了什么和为什么。
-
-## Phase 2 — Docs Sync
-
-- 由调用方执行 `<Path>{roots.commands}/docs-sync.md</Path>`。
-- 只修改全局 state 与 workflow sidecar 已确认范围中需要同步的文档或知识资产。
-- CHANGELOG 类文档只写 `[Unreleased]`，保留该段落。
-- 本阶段由 docs-sync 自动提交文档、报告与 state；最终 release commit 仍在 Phase 3 创建，发布后再由 Phase 6 记录为新输入终点。
-
-## Phase 3 — 版本 bump + release commit + tag
-
-读取 `version-bump-flow.md`。
-
-- 将 CHANGELOG 的 `[Unreleased]` 内容迁移到 `## [X.Y.Z] - YYYY-MM-DD` 或项目既有等价格式，并重新保留空 `[Unreleased]`。
-- 将 `package.json#version` 改为 `X.Y.Z`；tag 使用 `vX.Y.Z`。
-- 运行质量闸；除非调用方明确记录外部预演证据，不跳过。
-- release commit 只包含版本 bump 与 CHANGELOG 迁移，提交信息为 `chore(release): vX.Y.Z`。
-- 记录 `RELEASE_COMMIT_SHA`。
-- 先 push 发布分支，再 `git tag vX.Y.Z $RELEASE_COMMIT_SHA`，再 push tag。
-
-## Phase 4 — 监控 release workflow
-
-用 `gh run list` 找到 head SHA 等于 `RELEASE_COMMIT_SHA` 的 release run，再 `gh run watch --exit-status`。
-
-重点检查：
-
-- Verify tag matches package version
-- lint / tests / build / bin entry
-- Extract release notes from CHANGELOG
-- Publish to npm（仅 `PUBLISH_TO_NPM=true`）
-- Create GitHub Release
-
-失败时进入 `failure-recovery.md` 和 `troubleshooting-playbook.md`。
-
-## Phase 5 — 三端验证
-
-始终验证：
-
-```bash
-gh release view "vX.Y.Z" --json name,tagName,isDraft,isPrerelease,body
-gh run list --workflow release.yml --limit 1 --json conclusion,headSha
-```
-
-判定：
-
-- Release 非 draft、非 prerelease
-- Release body 非空，且包含 CHANGELOG 段落；仅 `Full Changelog` 一行视为残缺
-- workflow conclusion 为 success，headSha 等于 `RELEASE_COMMIT_SHA`
-
-仅当 `PUBLISH_TO_NPM=true` 时验证：
-
-```bash
-npm view "<package-name>" version
-npm view "<package-name>" dist-tags
-```
-
-判定 version 与 `dist-tags.latest` 均为 `X.Y.Z`。
-
-## Phase 6 — 记录 release 输入节点
-
-仅当 Phase 1-5 全绿时执行。再次调用 `<Path>{roots.commands}/docs-sync.md</Path>`，并确认运行前 `HEAD` 等于 `RELEASE_COMMIT_SHA`：
-
-- state 的 `last_range.to_sha` 必须等于 `RELEASE_COMMIT_SHA`。
-- `last_range.from_sha` 来自最后修改旧 state 的 commit，或迁移期 explicit baseline。
-- docs-sync 写入 release 后报告/state commit；tag 继续精确指向 release commit，不移动。
-
-本 skill 不直接改 state 或 workflow sidecar；原子写入、范围检查和本地 commit 均由 docs-sync command 负责。
-
-## 完成报告
-
-报告至少包含：
-
-- 版本号、release commit SHA、tag SHA
-- workflow run id 与结论
-- GitHub Release 检查结果
-- npm 检查结果或跳过原因
-- docs-sync `last_range` 与 state-file baseline commit
-- 失败恢复或后续建议