| name | isolated-npm-release-worktree |
| description | 当用户要发布已经提交的 NPM 包，但当前工作区还有未完成、半吊子、staged/unstaged WIP，或用户明确要求“不要把未完成改动发上去”“隔离发布”“全部发布”“发布产物再合回 master”时使用。覆盖 git worktree 隔离发布、NPM stable/beta 全量或窄发布、保护当前 WIP、registry 验证、release commit/tag 回流本地目标分支。 |
Isolated NPM Release Worktree
目标
从已提交代码发布 NPM，同时保护当前工作区的未完成改动。发布完成后，把 release metadata、tags、skill/日志等可回流产物安全合回本地目标分支。
触发条件
- 用户要发布 NPM，但当前工作区不干净。
- 用户说已提交部分可以发，半成品不要发。
- 用户希望在隔离目录发布，发布产物最终回到本地
master / 当前目标分支。
- 用户要求沉淀可复用发布流程。
工作流
-
冻结发布目标：
- 记录当前目标分支、目标提交、dirty/staged/untracked 状态。
- 明确哪些提交允许发布，哪些 WIP 禁止发布。
- 禁止 stash、reset、checkout 用户 WIP，除非用户明确要求。
-
创建隔离 worktree：
git worktree add -b codex/release-<slug> <release-dir> <target-commit>，不要用 detached worktree 直接发布；pnpm publish --publish-branch 会拒绝 detached HEAD。- 后续发布、version、build、pack、publish 都在 release worktree 内执行。
-
决定 release 范围：
- 先用
npm-release-contract-guard 判断 closure。
- 若用户说“全部发布”“别限定”“直接全部”，默认使用 full public workspace batch：
pnpm release:auto:changeset -> pnpm release:version -> pnpm release:publish。
- 不要在用户明确纠偏为全量发布后继续用“最小可生效链路”解释窄发布；全量发布的成功标准是
release:verify:published 确认本批次所有公开包都 published。
- 若 repo changeset flow 会把无关旧债或半成品 package 拉进 batch，允许改用受控窄发布，但必须说明原因。
- 受控窄发布只适用于用户明确接受窄范围，或全量发布存在真实阻塞且用户确认降级。
- 受控窄发布仍必须用
pnpm publish，禁止 raw npm publish。
-
发布前验证：
- 使用与 publish 相同的 npm config 验证 auth，例如
NPM_CONFIG_USERCONFIG=<project>/.npmrc npm whoami。
- 如果主仓库存在私有
.npmrc，隔离 worktree 的所有 npm view、npm install、pnpm publish 和 registry 验证命令都必须带同一个 NPM_CONFIG_USERCONFIG=<project>/.npmrc；不要只在 publish 时带，否则验证和安装烟测可能读到用户级未登录配置并误报 401/404。
- 运行被发布包的
test、tsc、lint、build。
- 用
pnpm pack 检查 tarball manifest，确认 workspace:* 已转成已发布或本批次将发布的精确版本。
- 对依赖闭包关键包做临时安装验证。
-
发布：
- 先发布底层依赖，再发布依赖它的包。
- 全量发布优先用
pnpm release:publish，并在发布前提交 version/changelog commit，保证 npm tags 指向包含 release metadata 的 commit。
- 窄发布在非
master/main 的 release branch 上使用 pnpm publish --publish-branch <branch>。
- 每个包发布后用同一 npm config 执行
npm view <pkg> version dist-tags dependencies --json 验证 registry；首发 scoped package 刚发布后可能短暂 404，先按有限重试处理，不要立刻判定发布失败或重复 publish。
-
回流本地目标分支：
- NPM registry 发布成功后，必须先把 release commit / version / changelog / generated package artifacts / 必要源码修复回流到本地目标分支，再进入最终收尾；不能只停在隔离 worktree。
- 默认在目标工作区执行
git merge --ff-only <release-branch>。如果 release branch 不是目标分支的快进后代，先停下说明差异，不要自动创建 merge commit。
- 若目标工作区有 WIP，只允许在不重叠时 fast-forward；失败就停止，不要 stash、reset 或强行 merge。
- 若因为 WIP 或非快进关系暂时无法回流，最终回复必须明确写“发布已到 registry，但本地目标分支尚未闭合”，并给出阻塞原因。
- 未完成本地目标分支回流时，不得说“全部完成”或“发布闭环完成”。
- 回流后必须在 release worktree 和目标工作区分别运行
git status --short。发布流程自己产生的构建产物、hash 资产或版本文件不能留脏：属于发布记录的就提交，不属于的就恢复/删除；只有发布前已存在且明确属于用户的 WIP 才能保留并在最终回复点名。
-
收尾：
- 创建/更新本次
docs/logs 发布记录。
- 若流程暴露了可复用规则，更新本 skill 或相关 release skill。
- 给出发布包名、版本、dist-tag、验证命令、临时安装结果、release commit、tags。
关键约束
- 已提交代码可以发布；未完成 WIP 不能发布。
- 不要为了发布去整理、修复或提交无关 WIP。
- 不要让 changeset 自动扩大的旧债 batch 偷偷变成本次发布范围。
- 用户已经要求全量发布时，不要再以“避免扩大范围”为理由继续窄发；这时应该解决全量发布的验证问题，或明确报告真实阻塞。
- 若发布了 NPM registry，但 release metadata 尚未回流目标分支，不能说“全部完成”。
