📚 docs(dev-workflow): 修正 CLI-Core 依赖模型与发版流程口径

[Lands-1203]

背景

本次 core-v3.8.0 / cli-v3.6.3 发版由我在本地跑 npm publish 完成,导致 npm 详情页缺 provenance 徽章(参见 https://www.npmjs.com/package/@double-coding/flow2spec 版本历史,3.6.2 有勾、3.6.3 没勾)。

原因追溯:

1. .github/workflows/publish-npm.yml 本来就存在,而且用 GitHub OIDC + trusted publishing + --provenance 写得很完整——触发条件是 release: published 事件(不是 tag push)
2. 我发版时只 git push tags 没到 GitHub 创 Release,workflow 没被触发,才走了本地 npm publish
3. 更深层原因:.claude/rules/repo-dev-workflow-constraints.md 里两段规则已过期:
   • "CLI 对 Core 用 caret range ^3.5.0" —— PR 🚀 feat(cli): 版本联动制——CLI pin Core + update 整体更新与生效验证 #53(2026-08 引入 CLI-pin-Core 联动制)后已是精确 pin,规则文档没同步
   • 「发布门禁」小节只列了 version:check / pack:check 等本地门禁,没写 CI Release 才是正规发布通道

规则不同步导致的结果:发版流程走了错的路径,npm 上 3.6.3 / 3.8.0 的 provenance 已不可补(npm 不允许对已发布版本重新签名)。

改动

版本模型小节

- CLI 对 Core 使用运行时依赖 caret range(当前为 `^3.5.0`);Core 必须落在该范围内。
- Core 兼容修复/新增 API 可只升 Core;Template Version 不变,不触发知识库升级。
+ CLI 对 Core 使用运行时依赖**精确 pin**(`packages/cli/package.json` 里写死 Core 版本号,不是 caret range);`scripts/workspace-version.js` 会自动同步。
+ Core 兼容修复/新增 API 也**必须 CLI 锁步 patch bump 并同发**——CLI 精确 pin 决定的(`version:set:core` 回执会提示 `remember to bump CLI patch — release in lockstep`)。仅改 CLI 自身代码时才允许 CLI 单独发。

新增「发版执行步骤(CI 触发,不本地 npm publish)」小节

写清标准流程:

1. 版本 PR merge → git checkout main && git pull
2. git tag core-vX.Y.Z && git tag cli-vX.Y.Z && git push --tags
3. 到 GitHub Releases 页面创建 Release(标题与 tag 同名)—— 这一步是关键,触发 workflow
4. workflow 内已含 version:check --tag / npm test / pack:check / npm publish --provenance

明确禁止:「本地跑 npm publish」——即便 hotfix 也应通过 workflow;若确因意外本地发布,须在发版 PR / Release notes 显式记录「本次发布无 provenance」。

三端镜像

.claude/rules/*.md + .cursor/rules/*.mdc + .codex/topics/*.md 同步修订(仓库内三端手写镜像)。

门禁

• ✅ flow2spec kb check --strict:knowledge check: ok / topics: 20 / routing drift: no
• 无代码改动、无版本改动、无发布行为——纯规则文档修正

后续动作(不阻塞本 PR)

下次发版(core-v3.8.1 / core-v3.9.0 等)时:

1. 按本 PR 补的新流程,merge 版本 PR 后打 tag 并去 GitHub Releases 创 Release
2. workflow 自动跑,npm publish --provenance 生效,新版本 provenance 勾回归
3. 本次已发出的 3.6.3 / 3.8.0 的 provenance 缺失,下一版本自然覆盖(用户看最新版本时会看到勾)

相关

• PR 🐛 fix(core): matcher includeAll/excludeAny/excludeAll 字段在路由匹配中生效 #55 / 📚 docs(kb): 同步 matcher 4 字段(includeAll/excludeAny/excludeAll)完整语义与填充机制 #57 / 🔖 chore(release): core@3.8.0 + cli@3.6.3 + template@3.7.0 #58(本次发版链路)
• PR 🚀 feat(cli): 版本联动制——CLI pin Core + update 整体更新与生效验证 #53(引入 CLI-pin-Core 联动制,是这次规则修正的直接起因)
• .github/workflows/publish-npm.yml(既有 workflow,本 PR 不动)