🚀 feat(cli): 版本联动制——CLI pin Core + update 整体更新与生效验证

.Knowledge/topics/f2s-init-defaults.md

@@ -81,11 +81,11 @@ tags: [policy]
 
 ### 跑 `f2s-kb-upgrade` 时的版本预检
 
-步骤 -1 执行 `flow2spec version` 与 `flow2spec update --check`，分别读取 CLI、Core、Core Range、Template、Protocol 和 npm 最新 Core/Template：
+步骤 -1 执行 `flow2spec version` 与 `flow2spec update --check`，分别读取 CLI、Core、Core Pinned、Template、Protocol 和 npm 最新 Core/Template（CLI 对 Core 为精确 pin，两包联动发布）：
 
-- Core-only 更新：`flow2spec update --core` 后幂等 init 刷新 Hook，不进入完整知识库升级。
-- Template 更新且 Core 兼容：更新 Core 后继续 init 与 `projectRev` / `pkgRev` 分流。
-- 本地版本不可用或 Core 超出范围：显式组合 latest CLI/Core 执行 init，避免 npx 复用旧 Core。
+- CLI/Core 有更新：`flow2spec update --cli`（CLI 与配套 Core 联动更新，自带生效校验）后幂等 init 刷新 Hook。
+- Template 更新：`flow2spec update --cli` 到位后继续 init 与 `projectRev` / `pkgRev` 分流。
+- 本地版本不可用：`npx --yes <cli-package>@latest init`（latest CLI 自带 pin 的配套 Core），避免 npx 复用旧版缓存。
 - `manifest-routing.json.version` 表示 Template Version，不能与 Core Version 混用。
 
 ## init 不动哪些目录

.Knowledge/topics/flow2spec-core-package.md

@@ -34,22 +34,22 @@ Template Version  packages/core/package.json.templateVersion
 Protocol Version  packages/core/capabilities.json.protocolVersion
 ```
 
-- `version:set:cli` 只更新 CLI，可显式提高 `--core-range`。
-- `version:set:core` 只更新 Core，并拒绝落到当前 CLI 范围之外。
+- `version:set:cli` 只更新 CLI，Core pin 自动同步为当前 Core 版本。
+- `version:set:core` 更新 Core 并联动把 CLI 依赖 pin 到同版本（需配套 bump CLI patch 联动发布）。
 - `version:set:template` 更新 Core 元数据及中英文 `manifest-routing.json.version`。
-- `version:check` 校验 semver range、lockfile、双语 Template Version、Protocol Version 与 release tag。
+- `version:check` 强制校验 CLI pin 与 Core 版本精确一致，另校验 lockfile、双语 Template Version、Protocol Version 与 release tag。
 
 ## 发布与更新
 
-- `core-vX.Y.Z` 只发布 Core；`cli-vX.Y.Z` 只发布 CLI。同时发布时先 Core 后 CLI。
-- `flow2spec version` 展示 CLI/Core/Core Range/Template/Protocol。
-- `flow2spec update --check|--cli|--core` 分别检查、更新 CLI、更新兼容 Core。
+- `core-vX.Y.Z` 只发布 Core；`cli-vX.Y.Z` 只发布 CLI。Core/Template 发版必带 CLI patch 联动发布，顺序先 Core 后 CLI。
+- `flow2spec version` 展示 CLI/Core/Core Pinned/Template/Protocol。
+- `flow2spec update --check|--cli|--core` 均以 CLI 为入口整体更新（`--core` 为别名），安装后校验全局生效 Core 版本，失败时提示手动重装命令。
 - Hook 与 `update.check()` 同时返回 Core 与 Template 状态。
-- Core-only 更新：更新 Core 后幂等 init 刷新 Hook，不进入 `f2s-kb-upgrade`。
-- Template 更新：更新 Core、执行 init，再由 `projectRev` / `pkgRev` 决定是否进入完整知识库升级。
+- CLI/Core 更新：`update --cli` 联动到位后幂等 init 刷新 Hook。
+- Template 更新：`update --cli` 后执行 init，再由 `projectRev` / `pkgRev` 决定是否进入完整知识库升级。
 
 ## 边界
 
-- Core 新版必须落在 CLI caret range 内；超出范围先升级 CLI。
+- CLI 对 Core 为精确 pin；用户只需关心 CLI 一个包，`npm i -g <cli>@latest` 即得配套 Core。
 - `.Knowledge/manifest-routing.json.version` 表示 Template Version，不能与 Core Version 混用。
 - 包安装验收使用两包 tarball，并验证 Core templates、类型声明、CLI README 与启动行为。

docs/en/upgrade-guide.md

@@ -1,15 +1,15 @@
-# Flow2Spec Upgrade Guide (CLI 3.6.1 / Core 3.7.1 / Template 3.6.1)
+# Flow2Spec Upgrade Guide (CLI 3.6.2 / Core 3.7.2 / Template 3.6.2)
 
 > Highlight of this release: **routing-summary recall anchors**. Every routing rule in `manifest-routing.json` now carries a `summary` semantic digest (synced automatically from topic frontmatter), which greatly improves knowledge-base hit rates for natural phrasings such as "where are the prototypes" or "which folder holds the flowcharts". `kb check` gains summary quality validation accordingly.
 
 ## Version matrix
 
 | Dimension | Latest | Notes |
 | --- | --- | --- |
-| CLI (`@double-coding/flow2spec`) | 3.6.1 | `kb check` prints warning details |
-| Core (`@double-coding/flow2spec-core`) | 3.7.1 | summary sync engine + quality validation; upgrade-skill project-side alignment check |
-| Template Version | 3.6.1 | templates carry topic-layer changes (projectRev 3) |
-| Qoder plugin | 3.7.1 | self-built (`npm run build:qoder-plugin`), named after the Core version |
+| CLI (`@double-coding/flow2spec`) | 3.6.2 | the only package you need to care about; pins its exact Core, released in lockstep |
+| Core (`@double-coding/flow2spec-core`) | 3.7.2 | installed automatically with the CLI, no separate action needed |
+| Template Version | 3.6.2 | templates carry topic-layer changes (projectRev 3) |
+| Qoder plugin | 3.7.2 | self-built (`npm run build:qoder-plugin`), named after the Core version |
 
 ---
 
@@ -22,7 +22,7 @@ npm install -g @double-coding/flow2spec
 flow2spec init <codex|cursor|claude|dsh>   # multi-select, follow the prompts
 ```
 
-Installing the CLI automatically brings the latest compatible Core (`^3.6.0` → 3.7.1); no separate install is needed. After init you are on the latest knowledge-base templates with summary-based first-pass recall built in — nothing extra to do.
+Installing the CLI automatically brings its exactly pinned Core (3.7.2); no separate install is needed. After init you are on the latest knowledge-base templates with summary-based first-pass recall built in — nothing extra to do.
 
 ### Option 2: Qoder plugin (self-built install)
 
@@ -33,7 +33,7 @@ The Qoder plugin marketplace hosts official plugins only; build the Flow2Spec pl
    ```bash
    git clone https://github.com/double-coding-lab/Flow2Spec.git
    cd Flow2Spec && npm install && npm run build:qoder-plugin
-   # produces output/flow2spec-3.7.1.zip
+   # produces output/flow2spec-3.7.2.zip
    ```
 
 2. In Qoder's plugin management, choose local install and import the zip;
@@ -47,25 +47,18 @@ Then tell the agent things like "f2s-kb-build / f2s-kb-add" to start building th
 
 Template 3.5.0 → 3.6.x **includes topic-layer changes** (projectRev 2 → 3), so updating the packages alone is not enough — run one knowledge-base upgrade. Three steps:
 
-### Step 1: Update the packages
+### Step 1: Update the package
 
-Check current versions and available updates:
+The CLI and Core release in lockstep (the CLI pins its exact Core), so one command updates everything:
 
 ```bash
-flow2spec version
-flow2spec update --check
+npm install -g @double-coding/flow2spec@latest
+flow2spec version   # confirm CLI 3.6.2 / Core 3.7.2
 ```
 
-Two cases depending on your current CLI:
+Once on 3.6.2 or later, future upgrades can also use `flow2spec update --cli` (it verifies the effective Core version and auto-repairs a broken dependency tree by reinstalling).
 
-- **CLI is already 3.6.x**: run `flow2spec update --core` to get Core 3.7.1 (inside the `^3.6.0` range); if your CLI is below 3.6.1, also run `flow2spec update --cli` (its `kb check` prints warning details, handy for watching step 2 progress).
-- **CLI below 3.6.0**: reinstall the latest:
-
-  ```bash
-  npm install -g @double-coding/flow2spec@latest
-  ```
-
-**Qoder plugin users**: pull the latest code and rebuild the plugin package (`npm run build:qoder-plugin`, producing `output/flow2spec-3.7.1.zip`), then re-import it in Qoder's plugin management; no global npm package needed.
+**Qoder plugin users**: pull the latest code and rebuild the plugin package (`npm run build:qoder-plugin`, producing `output/flow2spec-3.7.2.zip`), then re-import it in Qoder's plugin management; no global npm package needed.
 
 ### Step 2: Knowledge-base upgrade (the key step — let the agent do it)
 
@@ -87,7 +80,7 @@ No manual edits to any `.Knowledge` file are needed.
 ### Step 3: Verify
 
 ```bash
-flow2spec version          # CLI 3.6.1 / Core 3.7.1 / Template 3.6.1
+flow2spec version          # CLI 3.6.2 / Core 3.7.2 / Template 3.6.2
 flow2spec kb check --strict   # expect: knowledge check: ok, no summary warnings
 ```
 
@@ -97,6 +90,12 @@ Then try one natural question (e.g. "where do the prototypes / requirement docs
 
 ## FAQ
 
+**Q: Why does every Core update come with a new CLI version? Which package should I care about?**
+Only the CLI (`@double-coding/flow2spec`). It pins its exact Core version and the two packages release in lockstep: any Core update produces a new CLI version, so `npm install -g @double-coding/flow2spec@latest` always gets you the complete latest pair.
+
+**Q: On an older CLI, `flow2spec update --core` said "updated" but `flow2spec version` did not change?**
+A known defect in CLI ≤ 3.6.1: that command installed Core into an orphaned top-level global location, while the CLI actually loads its own nested copy — which never got updated. Fix: reinstall the CLI once (`npm uninstall -g @double-coding/flow2spec && npm install -g @double-coding/flow2spec@latest`). Since CLI 3.6.2, `update --cli/--core` performs the lockstep update and verifies the effective Core version — no more false success.
+
 **Q: Will the upgrade overwrite the knowledge base I already wrote?**
 No. The init run by `f2s-kb-upgrade` is incremental and only updates template-owned routing structure and rules; your business content in `stock-docs` / `req-docs` / topic bodies is untouched. `--reset-knowledge` is used only when you explicitly ask for an overwrite reset.
 
@@ -114,7 +113,7 @@ f2s-kb-upgrade, force the full flow: run flow2spec init first, then kb build --f
 ```
 
 **Q: After upgrading, git shows lots of changes under `.cursor/` and `.codex/` — is that normal?**
-Yes. Those are real updates to rule and skill bodies in the new templates (including the wholesale removal of `f2s-kb-migrate`), not empty diffs; use `git diff -w` to verify. The upgrade only touches `.Knowledge/`, the agent config roots (`.cursor/` `.codex/` etc.), `AGENTS.md`, and `flow2spec.config.json` — **never your business source code**; commit the upgrade changes separately from business changes. Also, the manifest `version` is the Template Version (3.6.1 after upgrading) and will not equal the Core version — that is expected.
+Yes. Those are real updates to rule and skill bodies in the new templates (including the wholesale removal of `f2s-kb-migrate`), not empty diffs; use `git diff -w` to verify. The upgrade only touches `.Knowledge/`, the agent config roots (`.cursor/` `.codex/` etc.), `AGENTS.md`, and `flow2spec.config.json` — **never your business source code**; commit the upgrade changes separately from business changes. Also, the manifest `version` is the Template Version (3.6.2 after upgrading) and will not equal the Core version — that is expected.
 
 **Q: After upgrading, my commit is blocked by `kb check` reporting routing drift?**
 The manifest and topics are out of sync (usually after hand-editing the manifest). Ask the agent to run `flow2spec kb build` once (idempotent) and it self-heals.

docs/en/usage-guide.md

@@ -135,7 +135,7 @@ Template update: after init, projectRev == pkgRev takes the fast path; a differe
 Legacy layout (V1): built-in migration removed; use a historical package version (@3.4.x or earlier) for a one-time migration, or move into .Knowledge manually
 ```
 
-`flow2spec version` shows CLI, Core, Core Range, Template, and Protocol. `flow2spec update --check|--cli|--core` checks updates, updates CLI, or updates a compatible Core. SessionStart Hooks compare Core and Template independently: Core-only updates do not trigger knowledge upgrade; Template updates use `projectRev` / `pkgRev` after init to decide whether to run `f2s-kb-upgrade`. Failed checks are skipped silently; CLI self-checks do not interrupt `CI` or runs with `FLOW2SPEC_SKIP_UPDATE_CHECK=1`.
+`flow2spec version` shows CLI, Core, Core Pinned, Template, and Protocol. `flow2spec update --check` checks for updates; `flow2spec update --cli` performs the lockstep update (CLI plus its pinned Core arrive together; `--core` is an equivalent alias). SessionStart Hooks compare Core and Template independently: Core-only updates do not trigger knowledge upgrade; Template updates use `projectRev` / `pkgRev` after init to decide whether to run `f2s-kb-upgrade`. Failed checks are skipped silently; CLI self-checks do not interrupt `CI` or runs with `FLOW2SPEC_SKIP_UPDATE_CHECK=1`.
 
 After `flow2spec init codex`, Codex projects include `.codex/hooks.json`, `.codex/hooks/f2s-config-session.js`, and `.codex/hooks/f2s-update-check.js`. On Codex `SessionStart` for `startup|resume`, the first script injects one configuration summary and the second checks the knowledge-base version automatically. When the hook is first generated or changed, trust it through `/hooks` in Codex. Set `updateCheck.enabled=false` in `flow2spec.config.json` to skip only the version check.
 

docs/使用说明.md

@@ -122,7 +122,7 @@ Template 更新：init 后按 projectRev == pkgRev 走快速路径，不等时
 旧版布局（流程 V1）：不再内置迁移；用历史版本包（@3.4.x 及更早）一次性迁移或手动迁入 .Knowledge
 ```
 
-`flow2spec version` 展示 CLI、Core、Core Range、Template、Protocol；`flow2spec update --check|--cli|--core` 分别检查、更新 CLI、更新兼容 Core。SessionStart Hook 同时检查 Core 与 Template：Core-only 更新不触发知识库升级；Template 更新才在 init 后按 `projectRev` / `pkgRev` 决定是否执行 `f2s-kb-upgrade`。更新检查失败会静默跳过，不影响当前命令；`CI` 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时 CLI 自检不打扰当前流程。
+`flow2spec version` 展示 CLI、Core、Core Pinned、Template、Protocol；`flow2spec update --check` 检查更新，`flow2spec update --cli` 整体更新（CLI 与配套 Core 联动发布、一起到位，`--core` 为其等价别名）。SessionStart Hook 同时检查 Core 与 Template：Core-only 更新不触发知识库升级；Template 更新才在 init 后按 `projectRev` / `pkgRev` 决定是否执行 `f2s-kb-upgrade`。更新检查失败会静默跳过，不影响当前命令；`CI` 或设置 `FLOW2SPEC_SKIP_UPDATE_CHECK=1` 时 CLI 自检不打扰当前流程。
 
 Codex 项目执行 `flow2spec init codex` 后会写入 `.codex/hooks.json`、`.codex/hooks/f2s-config-session.js` 与 `.codex/hooks/f2s-update-check.js`：前者在 Codex `SessionStart` 的 `startup|resume` 事件注入一次配置摘要，后者自动检查知识库版本；首次生成或 hook 内容变化后，需要在 Codex 中通过 `/hooks` 信任该项目 hook。`flow2spec.config.json` 中 `updateCheck.enabled=false` 时仅跳过版本检查，不影响配置摘要注入。