[tech] Core 兼容范围依赖与架构命名规则

.Knowledge/index.md

@@ -22,6 +22,7 @@
 
 | 主题 | 路径 | 适用场景 | 关联文档（摘要） |
 | --- | --- | --- | --- |
+| architecture-document-naming | `.Knowledge/topics/architecture-document-naming.md` | 架构初稿、终稿固定名称及业务主题无项目名前缀 | stock：[架构文档命名约定](stock-docs/架构文档命名约定_终稿.md) |
 | implement-tech-design | `.Knowledge/topics/f2s-implement-tech-design.md` | 按技术方案实现代码 | req：[技术方案](.Knowledge/req-docs/<技术方案>.md)（必填） |
 | f2s-doc-routing | `.Knowledge/topics/f2s-stock-docs-vs-req-docs.md` | stock-docs / req-docs 目录分工 | stock：[目录边界说明](.Knowledge/stock-docs/<目录边界说明>.md)（可选） |
 | fallback-triage | `.Knowledge/topics/f2s-fallback-triage.md` | 未命中或低置信度：分诊与澄清 | stock：[路由分诊说明](.Knowledge/stock-docs/<分诊说明>.md)（可选） |
@@ -39,7 +40,7 @@
 | flow2spec-init-defaults | `.Knowledge/topics/f2s-init-defaults.md` | `flow2spec init` 字段默认值、四处落点一致性、老项目缺字段补写、init 目标与插件模式（`init plugin`）、`init` 不动 stock/req/topics/matchers、manifest 两个版本字段（`projectRev` / `pkgRev`）对照 | 包源码：`lib/flow2specConfig.js` `DEFAULTS` / `CONFIG_FIELDS`；模板：`templates/{locale}/flow2spec.config.json` |
 | flow2spec-doctor | `.Knowledge/topics/flow2spec-doctor.md` | `flow2spec doctor` 只读检查环境、项目初始化、协作上下文与知识库健康 | stock：[Doctor 诊断命令](stock-docs/Flow2Spec-doctor诊断命令.md)；中英文命令文档：`docs/命令说明.md` / `docs/en/commands-reference.md` |
 | flow2spec-dsh-adapter | `.Knowledge/topics/flow2spec-dsh-adapter.md` | `flow2spec init dsh`、DeepSeek Harness 项目技能发现与 `.dsh/` 目录适配 | 用户文档：`docs/使用说明.md` / `docs/en/usage-guide.md`；实现：`lib/dshAgentsAdapter.js` |
-| flow2spec-core-package | `.Knowledge/topics/flow2spec-core-package.md` | `@double-coding/flow2spec-core` 职责边界：核心实现、发包模板真源、原生插件 API 与 CLI/legacy shim 消费关系 | 开发者文档：`packages/core/README.md`；入口：`packages/core/index.js` |
+| flow2spec-core-package | `.Knowledge/topics/flow2spec-core-package.md` | Core/CLI 所有权、caret 兼容依赖、独立发布与更新 | stock：[兼容依赖与独立更新](stock-docs/Core兼容依赖与独立更新_终稿.md)；开发者文档：`packages/core/README.md` |
 | flow2spec-qoder-plugin | `.Knowledge/topics/flow2spec-qoder-plugin.md` | Qoder 插件构建、`build:qoder-plugin`、zip 打包与插件市场分发 | 构建脚本：`scripts/build-qoder-plugin.js`；内容源：`packages/core/index.js`（resources API） |
 | kb-routing-summary | `.Knowledge/topics/kb-routing-summary.md` | 路由初筛 `taskToTopicRules[].summary` 字段与 matcher 4 字段(`includeAny`/`includeAll`/`excludeAny`/`excludeAll`)语义 | 引擎：`packages/core/lib/knowledgeEngine.js`、`packages/core/lib/routing.js`；创作规范：配置根 `rules/f2s-topic-authoring.*` |
 

.Knowledge/manifest-routing.json

@@ -35,7 +35,8 @@
     "flow2spec-doctor": ".Knowledge/topics/flow2spec-doctor.md",
     "flow2spec-core-package": ".Knowledge/topics/flow2spec-core-package.md",
     "flow2spec-qoder-plugin": ".Knowledge/topics/flow2spec-qoder-plugin.md",
-    "kb-routing-summary": ".Knowledge/topics/kb-routing-summary.md"
+    "kb-routing-summary": ".Knowledge/topics/kb-routing-summary.md",
+    "architecture-document-naming": ".Knowledge/topics/architecture-document-naming.md"
   },
   "taskToTopicRules": [
     {
@@ -209,6 +210,15 @@
         "kb-routing-summary"
       ],
       "summary": "初筛 summary 与 matcher 分片 4 字段(资格/否决门)语义"
+    },
+    {
+      "task": "architecture-document-naming",
+      "matcherId": "m-architecture-document-naming",
+      "matcherPath": ".Knowledge/matchers/m-architecture-document-naming.json",
+      "topics": [
+        "architecture-document-naming"
+      ],
+      "summary": "架构文档固定命名与业务主题去项目名前缀"
     }
   ],
   "projectRev": 3,
@@ -311,6 +321,10 @@
     "kb-routing-summary": {
       "primary": "feature",
       "confidence": "manual"
+    },
+    "architecture-document-naming": {
+      "primary": "policy",
+      "confidence": "inferred"
     }
   }
 }

.Knowledge/matchers/m-architecture-document-naming.json

@@ -0,0 +1,13 @@
+{
+  "id": "m-architecture-document-naming",
+  "version": "1.0.0",
+  "schema": "flow2spec.matcher.v1",
+  "includeAny": [
+    "项目架构初稿",
+    "项目架构终稿",
+    "架构文档命名",
+    "主题命名前缀",
+    "下游项目名前缀",
+    "project-architecture"
+  ]
+}

.Knowledge/stock-docs/Core兼容依赖与独立更新_终稿.md

@@ -0,0 +1,12 @@
+# Core 兼容依赖与独立更新
+
+CLI 通过 caret 范围消费 Core（当前 `^3.8.2`）。Core 的兼容修复和模板更新可独立发布，CLI 调用新 API 时按需提高范围下限并发版。
+
+## 用户路径
+
+- 保留 CLI：`flow2spec update --core` 刷新兼容 Core，并验证实际加载版本。
+- 更新 CLI：`flow2spec update --cli` 获取 latest CLI 及其兼容 Core。
+- 模板更新后运行 `flow2spec init <agents...>`；按 `projectRev` / `pkgRev` 判断是否需要知识库升级。
+- 已安装包与项目锁文件不会随发版静默变化。旧 CLI 的精确依赖需要一次 CLI 更新才能解除。
+
+实现位于 `scripts/workspace-version.js`、`packages/cli/cli.js`；规则摘要见 [Core 包](../topics/flow2spec-core-package.md)，发布门禁见 [发布与部署](../../docs/发布与部署.md)。

.Knowledge/stock-docs/架构文档命名约定_终稿.md

@@ -0,0 +1,18 @@
+# 架构文档命名约定
+
+## 能力与入口
+
+`f2s-doc-arch` 生成项目架构初稿，交接 `f2s-doc-final` 形成终稿，再由 `f2s-kb-build` 形成可路由主题。文档与主题采用跨项目一致的职责命名，项目身份在正文说明。
+
+## 实现位置
+
+- `packages/core/templates/{zh-CN,en-US}/skills/f2s-doc-arch/SKILL.md`：固定初稿文件名、标题与后续交接。
+- 同目录 `f2s-doc-final/SKILL.md`：整体架构专用命名优先于通用方案命名，覆盖 MD/PDF 输入。
+- 同目录 `f2s-kb-build/SKILL.md`：终稿输入门禁、架构主题命名及旧主题迁移确认。
+- `packages/core/templates/{zh-CN,en-US}/rules/f2s-topic-authoring.md`：主题按职责命名。
+
+## 适用边界
+
+输出目录可指定，架构文件名按语言固定；已有同名文档保留有效内容并增量更新。已有带项目名前缀的主题迁移须确认范围、冲突及引用，不自动删除旧文件。其他能力文档仍按能力命名。
+
+具体命名见 [架构文档命名主题](../topics/architecture-document-naming.md)。变更从 Core 模板分发；当前仓配置根不随模板编辑自动更新。

.Knowledge/topics/architecture-document-naming.md

@@ -0,0 +1,25 @@
+---
+id: architecture-document-naming
+revision: 0
+summary: "架构文档固定命名与业务主题去项目名前缀"
+primary: policy
+confidence: inferred
+sourceDoc: ".Knowledge/stock-docs/架构文档命名约定_终稿.md"
+---
+# 架构文档与主题命名
+
+## 执行约定
+
+- 中文架构初稿：`项目架构初稿.md`，标题 `项目架构初稿`；终稿：`项目架构终稿.md`，标题 `项目架构终稿`。默认位于 `.Knowledge/stock-docs/`。
+- 英文对应 `project-architecture_draft.md` / `project-architecture_final.md`，标题 `Project Architecture Draft` / `Project Architecture Final`。
+- `f2s-doc-arch → f2s-doc-final → f2s-kb-build` 按上述名称交接；建库拒绝含 `初稿` 或 `_draft` 的输入，要求先完成终稿。
+- 架构概览 topic id 为 `project-architecture`，标题 `项目架构`（英文 `Project Architecture`）。业务 topic id、文件名、标题及派生 matcher id 按职责命名，项目名仅用于正文；保留既有 `f2s-*` 技能/规则标识。
+- 指定输出路径时保留目录，归一化架构文件名并告知实际路径；已有同名文档增量更新。带前缀旧主题迁移须确认范围和冲突后同步引用，不自动删除。
+
+## 实现与边界
+
+模板真源为 `packages/core/templates/{zh-CN,en-US}/skills/{f2s-doc-arch,f2s-doc-final,f2s-kb-build}/SKILL.md` 与 `rules/f2s-topic-authoring.md`；普通能力文档沿用通用方案命名。
+
+## 详细资料
+
+[架构文档命名约定](../stock-docs/架构文档命名约定_终稿.md)

.Knowledge/topics/f2s-dev-workflow-constraints.md

@@ -1,6 +1,6 @@
 ---
 id: f2s-dev-workflow-constraints
-revision: 3
+revision: 4
 summary: "Flow2Spec 本仓的模板真源、配置根、版本发布与分发边界"
 primary: policy
 confidence: inferred
@@ -29,9 +29,9 @@ Flow2Spec 本仓开发时判断应改 Core templates、配置根、本仓知识
 
 ## 版本与发布
 
-- CLI、Core、Template、Protocol 独立版本；CLI 用 caret range 约束 Core。
+- CLI、Core、Template、Protocol 独立版本；CLI 用 caret range 约束 Core，版本检查要求当前 Core 在范围内。
 - Core-only 兼容更新不升 Template Version，也不触发知识库升级。
-- `core-vX.Y.Z` 与 `cli-vX.Y.Z` 分别发布对应包。
+- `core-vX.Y.Z` 与 `cli-vX.Y.Z` 分别发布对应包；兼容 Core/Template 变更可独立发布，双包发布先 Core 后 CLI。
 - 发布前执行版本、打包、tarball 安装与 README 门禁。
 
 ## 边界与禁止项

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

@@ -1,6 +1,6 @@
 ---
 id: flow2spec-core-package
-revision: 2
+revision: 3
 summary: "Core/CLI 所有权、公共 API、独立版本、独立发布与更新兼容契约"
 primary: module
 confidence: inferred
@@ -16,7 +16,7 @@ confidence: inferred
 - 根 private workspace 只负责开发编排，不作为 Core 运行时依赖声明位置。
 - `packages/core/lib/` 承载核心实现；`packages/core/templates/{zh-CN,en-US}/` 是受 Git 管理的唯一模板真源并随 Core tarball 发布。
 - 根 `lib/`、根 `templates/` 与 `scripts/sync-core-templates.js` 均不存在。
-- CLI 是薄壳，只通过 `@double-coding/flow2spec-core` 的公共 API 工作；当前运行时范围为 `^3.5.0`。
+- CLI 是薄壳，只通过 `@double-coding/flow2spec-core` 的公共 API 工作；当前运行时范围为 `^3.8.2`。
 
 ## 公共 API
 
@@ -34,22 +34,22 @@ Template Version  packages/core/package.json.templateVersion
 Protocol Version  packages/core/capabilities.json.protocolVersion
 ```
 
-- `version:set:cli` 只更新 CLI，Core pin 自动同步为当前 Core 版本。
-- `version:set:core` 更新 Core 并联动把 CLI 依赖 pin 到同版本（需配套 bump CLI patch 联动发布）。
+- `version:set:cli` 更新 CLI 并保留原 Core 范围；传 `--core-range ^x.y.z` 时显式调整兼容下限。
+- `version:set:core` 只更新 Core 与 lockfile，保留 CLI 版本和范围；不兼容时写盘前报错。
 - `version:set:template` 更新 Core 元数据及中英文 `manifest-routing.json.version`。
-- `version:check` 强制校验 CLI pin 与 Core 版本精确一致，另校验 lockfile、双语 Template Version、Protocol Version 与 release tag。
+- `version:check` 校验当前 Core 满足 CLI caret 范围，另校验 lockfile、双语 Template Version、Protocol Version 与 release tag。
 
 ## 发布与更新
 
-- `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 版本，失败时提示手动重装命令。
+- `core-vX.Y.Z` 只发布 Core；`cli-vX.Y.Z` 只发布 CLI。Core/Template 兼容更新可独立发布；双包更新时先 Core 后 CLI。
+- `flow2spec version` 展示 CLI/Core/Core Range/Template/Protocol。
+- `flow2spec update --check` 展示兼容 Core 目标；`--cli` 更新 latest CLI 及其兼容 Core；`--core` 保留当前 CLI 版本，刷新兼容 Core。更新后校验 CLI 实际解析的 Core，失败返回错误。
 - Hook 与 `update.check()` 同时返回 Core 与 Template 状态。
-- CLI/Core 更新：`update --cli` 联动到位后幂等 init 刷新 Hook。
+- CLI/Core 更新：`update --cli` 到位后幂等 init 刷新 Hook。
 - Template 更新：`update --cli` 后执行 init，再由 `projectRev` / `pkgRev` 决定是否进入完整知识库升级。
 
 ## 边界
 
-- CLI 对 Core 为精确 pin；用户只需关心 CLI 一个包，`npm i -g <cli>@latest` 即得配套 Core。
+- CLI 对 Core 为 caret 兼容范围；已有安装需显式更新，项目锁文件仍固定解析版本。跨兼容范围需先升级支持该 Core 的 CLI。旧精确依赖 CLI 需先升级一次。
 - `.Knowledge/manifest-routing.json.version` 表示 Template Version，不能与 Core Version 混用。
 - 包安装验收使用两包 tarball，并验证 Core templates、类型声明、CLI README 与启动行为。

.claude/rules/repo-dev-workflow-constraints.md

@@ -47,10 +47,10 @@ Template Version  packages/core/package.json.templateVersion
 Protocol Version  packages/core/capabilities.json.protocolVersion
 ```
 
-- CLI 对 Core 使用运行时依赖**精确 pin**（`packages/cli/package.json` 里写死 Core 版本号,不是 caret range）；`scripts/workspace-version.js` 会自动同步。
-- Core 兼容修复/新增 API 也**必须 CLI 锁步 patch bump 并同发**——CLI 精确 pin 决定的:Core 一升,CLI 依赖字段就变,CLI 版本号必须跟着走(`version:set:core` 回执会提示 `remember to bump CLI patch — release in lockstep`)。仅改 CLI 自身代码(不动 Core)时才允许 CLI 单独发。
-- Rule、Skill、Hook、知识模板变化时升 Core,并显式执行 `version:set:template`（同样锁步 CLI patch）。
-- CLI 开始调用新版 Core API 时,升 CLI 并同步 Core 精确 pin。
+- CLI 对 Core 使用运行时 **caret 兼容范围**（如 `^3.8.2`）；已安装依赖通过显式更新刷新，不会静默变化。
+- Core 在 CLI 兼容范围内的更新可独立发布，`version:set:core` 保留 CLI 版本和依赖范围；不兼容时在写盘前报错。
+- Rule、Skill、Hook、知识模板变化时升 Core，并显式执行 `version:set:template`；兼容变更无需为此升 CLI。
+- CLI 开始调用新版 Core API 时，升 CLI 并通过 `version:set:cli --core-range ^x.y.z` 调整兼容下限；不兼容升级须显式评估。
 - Protocol Version 只在公共协议不兼容时调整。
 - 根 private workspace version 不参与 npm 发布匹配。
 
@@ -67,7 +67,7 @@ npm run version:check
 
 - `core-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec-core`。
 - `cli-vX.Y.Z` 只测试、打包并发布 `@double-coding/flow2spec`。
-- 同时发布时先 Core 后 CLI(CLI 精确 pin Core);禁止发布没有版本变化的包。
+- 同时发布时先 Core 后 CLI（先确保其兼容下限可安装）；仅 Core 变化时只创建 Core Release，禁止发布没有版本变化的包。
 - CLI README 与根 README 保持一致;Core README 独立维护。
 - 发布前运行 `npm run version:check`、`npm run pack:check`、`node scripts/test-package-install.js`。
 - `packages/core/templates/` 必须直接进入 Core tarball;不存在模板复制或漂移检查步骤。
@@ -79,16 +79,16 @@ npm run version:check
 标准流程:
 
 1. 在版本 PR(如 `chore/release-core-3.8.0`) merge 到 main 后,本地 `git checkout main && git pull`;
-2. 打两个 tag 并推送:`git tag core-vX.Y.Z && git tag cli-vX.Y.Z && git push --tags`;
-3. **到 GitHub Releases 页面**为每个 tag **创建 Release**(标题 `core-vX.Y.Z` / `cli-vX.Y.Z`);Release published 事件触发 `publish-npm.yml`;
+2. 只为实际升版的包创建并推送对应 tag：`core-vX.Y.Z` 或 `cli-vX.Y.Z`；
+3. 为对应 tag 创建 GitHub Release，触发 `publish-npm.yml`；双包发布时先等 Core 发布成功，再发布 CLI；
 4. workflow 内已包含 `npm run version:check --tag`、`npm test`、`pack:check`、`npm publish --provenance`,失败即中止。
 
 **禁止本地跑 `npm publish`**——即便临时需要 hotfix,也应通过 workflow 走。若确因意外走了本地发布(如本次 3.8.0 / 3.6.3),须在发版 PR / Release notes 中显式记录「本次发布无 provenance」。
 
 ## 更新语义
 
 - `flow2spec version` 展示 CLI、Core、Core Range、Template、Protocol。
-- `flow2spec update --check|--cli|--core` 分别检查、更新 CLI、更新兼容 Core。
+- `flow2spec update --check|--cli|--core` 分别检查、更新 latest CLI 及其兼容 Core、保持当前 CLI 版本只刷新兼容 Core，并验证实际生效版本。
 - Hook 同时比较 Core Version 与 Template Version。
 - Core 变化且 Template 不变：更新 Core 并执行一次幂等 init 刷新 Hook，不进入 `f2s-kb-upgrade`。
 - Template 变化：更新 Core、执行 init，再按 `projectRev` / `pkgRev` 判断是否进入 `f2s-kb-upgrade`。