@chengzhao-dev/dsh-cpp-workflow 0.6.13 → 0.6.14

package/README.en.md

@@ -19,13 +19,13 @@ The exception material follows the C++ Core Guidelines' Error handling section a
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.13
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.14
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.13
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.14
 ```
 
 The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.

package/README.md

@@ -19,13 +19,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.13
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.14
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.13
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.14
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.13",
+  "version": "0.6.14",
   "description": "写 C++ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。",
   "type": "module",
   "main": "./lib/index.js",

package/skills/building-cpp/SKILL.md

@@ -21,14 +21,14 @@ metadata:
 
 ## 三种操作
 
+一次只选一种，范围（单点、整段）是任务属性。操作与域的判据、边界和交接见 `../developing-cpp/references/change-model.md`；四类改动是域，不是操作。
+
 | 操作 | 什么时候用 | 从哪步进 |
 | --- | --- | --- |
 | 写作（起稿） | 改环境轴、入口脚本或构建流程 | 第 1 步；新工程走到第 3 步 |
 | 改写 | 环境轴与 target 契约不变，工具配置位置或流程顺序不对 | 从第 2 步重走，可到第 3 步 |
 | 润色 | 只改诊断措辞或失败分流说明 | 第 3 步 |
 
-范围随任务定：单点修正只改一条配置或诊断；整段重构先确认 target 与标准已由 configuring-cmake 写好，再改工具文件，最后跑完整检查。
-
 三种操作共用这些约束：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用单点修正；发现环境轴、编译器、构建目录或 target 契约需要改，退回整段，并转 `configuring-cmake`。
 
 ## 步骤
@@ -41,9 +41,11 @@ metadata:
 
 每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；测试设计、断言与 CTest 注册读 `references/testing.md`；CMake 的 target、标准和函数写法读 `../configuring-cmake/references/`，可复用片段在 `../configuring-cmake/assets/cmake/`。
 
+入口脚本只做配置、构建、CTest 与最小运行；`clang-format` 与 `clang-tidy` 的手动检查留在定工具配置，不塞进入口脚本。`environment.json` 的三个环境轴与 `standard` 是唯一来源，缺项就停。
+
 本轮激活按三条上限走：
 
-- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `developing-cpp` 的交接顺序（源码 → `configuring-cmake` → `building-cpp`）逐段进入，前一段结论落下再开下一段。
+- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `源码 → configuring-cmake → building-cpp` 的顺序逐段进入，前一段结论落下再开下一段。
 - 条文只开该步点名的一份；同号案例留到下一次激活。
 - 标准档只打开项目技能声明的那一档，没有声明时用本技能已有的新工程默认，不把其余标准档读进来。
 
@@ -51,20 +53,20 @@ metadata:
 
 ### 四类改动
 
-四类改动是操作内部的域，不是独立的操作：写作域定环境与流程，布局与排版改配置与形态，润色只改措辞。一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+四类改动是操作内部的域：操作定入口，域定层次。四域的定义、边界与次序见 `../developing-cpp/references/change-model.md`；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」拆开做，前一类落定并经检查再进下一类。
 
-| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
-| --- | --- | --- | --- |
-| 写作 | 改环境轴、入口脚本或构建流程 | 第 1 步 | `steps/01-build.md`、`references/environment.md`、`references/build-script.md` |
-| 布局 | 移动工具配置文件、补 `.vscode/` | 第 2 步 | `steps/02-tooling.md`、`examples/tooling.md` |
-| 排版 | 只改编码、行尾或 clang-format | 第 2 步 | `references/encoding.md`、`steps/02-tooling.md` |
-| 润色 | 只改诊断措辞、失败分流说明 | 第 3 步 | `steps/03-check.md`、`references/build-script.md` |
+| 类型 | 典型请求 | 入口步骤 |
+| --- | --- | --- |
+| 写作 | 改环境轴、入口脚本或构建流程 | `steps/01-build.md` |
+| 布局 | 移动工具配置文件、补 `.vscode/` | `steps/02-tooling.md` |
+| 排版 | 只改编码、行尾或 clang-format | `steps/02-tooling.md` |
+| 润色 | 只改诊断措辞、失败分流说明 | `steps/03-check.md` |
 
 ## 完成判据
 
-- 项目 `environment.json` 的三个环境轴齐全且是合法组合，`standard` 在 `c++11`–`c++23` 内；新工程默认 `c++23`，没有靠猜。
-- 配置命令固定 Ninja 和单一编译器，`build/<compiler>/compile_commands.json` 存在，根 `build/compile_commands.json` 指向当前编译器。
-- target 契约已经成立：程序 `app`、库 target、公共 include、标准与输出目录都已由 `configuring-cmake` 写好；本技能没有偷偷改 CMake 来绕过失败。
-- `clang-format --dry-run --Werror` 与 `clang-tidy` 在项目源码上零告警；只扫描项目源码和项目头。
-- CTest 全绿，程序从该编译器的构建目录启动；有测试时注册用 `gtest_discover_tests` 或项目既有机制，运行带 `--output-on-failure --no-tests=error`，失败时报告的是具体角色和原因。
-- 没有改源码语义，没有覆盖已有工程文件，也没有安装或下载任何工具。
+- [ ] 项目 `environment.json` 的三个环境轴齐全且是合法组合，`standard` 在 `c++11`–`c++23` 内；新工程默认 `c++23`，没有靠猜。
+- [ ] 配置命令固定 Ninja 和单一编译器，`build/<compiler>/compile_commands.json` 存在，根 `build/compile_commands.json` 指向当前编译器。
+- [ ] target 契约已经成立：程序 `app`、库 target、公共 include、标准与输出目录都已由 `configuring-cmake` 写好；本技能没有偷偷改 CMake 来绕过失败。
+- [ ] `clang-format --dry-run --Werror` 与 `clang-tidy` 在项目源码上零告警；只扫描项目源码和项目头。
+- [ ] CTest 全绿，程序从该编译器的构建目录启动；有测试时注册用 `gtest_discover_tests` 或项目既有机制，运行带 `--output-on-failure --no-tests=error`，失败时报告的是具体角色和原因。
+- [ ] 没有改源码语义，没有覆盖已有工程文件，也没有安装或下载任何工具。

package/skills/building-cpp/references/static-analysis.md

@@ -12,7 +12,7 @@ clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
 - 工程必须有根 `.clang-format`；缺失时先复制配置，不要回退到内置风格，回退会掩盖配置缺失。
 - 只扫描项目源码：`src/`、`include/`、`apps/`、`tests/` 等实际存在的目录；不扫描 `build/`、第三方、生成文件。
 - 配置文件在工程根 `.clang-format`；不要依赖用户主目录或编辑器内置配置。
-- `BasedOnStyle: Google`、`Standard: Latest`；clang-format 21/22 不接受 `c++23`，`Latest` 按工具支持的最高标准解析。列宽 80、2 空格、包含顺序都取 Google 预设，不另写 `ColumnLimit` 或 `IncludeCategories`。
+- `BasedOnStyle: Google`、`Standard: Latest`；clang-format 21/22 不接受 `c++23`，`Latest` 按工具支持的最高标准解析。列宽、缩进与包含顺序以工程根 `.clang-format` 为准；工程显式写 `ColumnLimit` 时按工程值执行，模板资产不写 `ColumnLimit`。
 - 格式化失败就是失败，不要用 `// clang-format off` 绕过；确需关闭时只包住无法排版的宏或表格，并写一句理由。
 
 ## clang-tidy

package/skills/building-cpp/steps/02-tooling.md

@@ -13,7 +13,7 @@
 - `.clangd` 的 `CompilationDatabase` 指向 `build/<compiler>`；切换编译器时同步改，不能留旧目录。**不要写 `-std`**：它会覆盖 `compile_commands.json`，把 C++23 工程降成旧标准；标准只由构建声明和编译数据库决定。
 - `--query-driver` 是 clangd 的命令行参数，写在 `.vscode/settings.json` 的 `clangd.arguments` 里，不是 `.clangd` 的 YAML 键。它告诉 clangd 允许执行哪个编译器驱动来取系统头路径；路径写绝对路径，并与 `environment.json` 的编译器一致。
 - 首次复制时按轴替换三处：`compiler=clang` 用 `CompilationDatabase: build/clang`、`--query-driver=/usr/bin/clang++` 和 `cmake.debugConfig` 的 `MIMode: lldb` / `miDebuggerPath: /usr/bin/lldb`；`compiler=gcc` 用 `build/gcc`、`/usr/bin/g++` 和 `MIMode: gdb` / `/usr/bin/gdb`。只复制模板而不改这三处，GCC 模式会指向错误的数据库、驱动或调试器。原工程已有的 `.clangd` 不覆盖；要改先征得同意。
-- `.clang-format` 保留 `Language: Cpp`、`BasedOnStyle: Google` 和 `Standard`：模板资产写 `Latest`；工程按 `environment.json` 声明 C++11–C++20 时，把 `Standard` 改成 `c++NN`（映射见 `references/standards/README.md`）。clang-format 21/22 的 `Standard` 不接受 `c++23`，所以 C++23 工程仍写 `Latest`。列宽 80、每级 2 空格、不用 tab、包含顺序都取 Google 预设；不要覆盖 `ColumnLimit`、`TabWidth`、`IncludeCategories` 或指针对齐。需要新规则时先改 `references/google-cpp-style.md` 并说明理由。
+- `.clang-format` 保留 `Language: Cpp`、`BasedOnStyle: Google` 和 `Standard`：模板资产写 `Latest`；工程按 `environment.json` 声明 C++11–C++20 时，把 `Standard` 改成 `c++NN`（映射见 `references/standards/README.md`）。clang-format 21/22 的 `Standard` 不接受 `c++23`，所以 C++23 工程仍写 `Latest`。列宽、缩进与包含顺序以工程根 `.clang-format` 为准；工程显式写 `ColumnLimit` 时按工程值执行，模板资产不写 `ColumnLimit`。需要新规则时先改 `references/google-cpp-style.md` 并说明理由。
 - `.clang-tidy` 用 `Checks: '-*, google-*, portability-avoid-pragma-once, readability-identifier-naming'`，保留 `WarningsAsErrors: '*'` 和 `FormatStyle: file`。`google-*` 覆盖 Google 风格能静态检查的部分；`readability-identifier-naming` 只配项目确实统一的命名项：类型/枚举/别名/模板参数 PascalCase，变量/参数/成员 snake_case，类成员尾随 `_`，结构体成员不尾随，常量 `k` + PascalCase。不要设 `FunctionCase`，Google 允许 `count()` / `set_count()` 这类访问器；`portability-avoid-pragma-once` 要打开，因为工程统一用路径式守卫；不要重新打开 `cppcoreguidelines-*` 整包。
 - `.clang-tidy` 关闭项和例外必须写理由；不要借 `-*` 之后再打开 `cppcoreguidelines-*` 这类非 Google 整族检查。
 - `.vscode/extensions.json` 推荐 clangd、CMake Tools 与 C/C++ 扩展；`.vscode/settings.json` 固定 clangd 参数、CMake 构建目录和 `cmake.debugConfig`。配置、构建、运行和调试只从 CMake Tools 进入，不写 `tasks.json` 或 `launch.json`；C/C++ 扩展只作为 CMake 快速调试的后端，IntelliSense 关闭，避免和 clangd 并行。配置注释用 JSONC 的 `//`，贴在被解释的键上方。
@@ -33,7 +33,7 @@
 
 **GCC 模式**：`clangd` 仍可工作，但系统头来自 GCC；`--query-driver` 指向 `g++`。`clang-format` / `clang-tidy` 仍是 Clang 工具，版本要求不因编译器是 GCC 而降低。
 
-**共享库**：静态检查不因链接方式改变；运行时库路径在定构建的 CMake 里设置，不要写进 clang 配置。
+**共享库**：静态检查不因链接方式改变；运行时库路径由 `configuring-cmake` 的 target 设置负责，见其 `references/cmake.md`，不写进 clang 配置。
 
 ## 正反例指针
 

package/skills/building-cpp/steps/03-check.md

@@ -30,11 +30,12 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live   # 活
 | 现象 | 先看 | 回到 |
 | --- | --- | --- |
 | 轴为空、组合非法、版本不匹配 | `environment.json`、`--live` 输出 | 定构建，先修声明 |
-| 找不到头文件、链接失败、target 不存在 | `CMakeLists.txt`、`target_include_directories`、`target_link_libraries` | 定构建 |
-| 没有 `compile_commands.json`、clangd 跳转失败 | 生成器、`CMAKE_EXPORT_COMPILE_COMMANDS`、`.clangd` 路径 | 定构建 / 定工具配置 |
+| 找不到头文件、链接失败、target 不存在 | `CMakeLists.txt`、`target_include_directories`、`target_link_libraries` | `configuring-cmake` 的定 target；修完回定构建 |
+| 没有 `compile_commands.json` | 顶层 `CMAKE_EXPORT_COMPILE_COMMANDS` 是否由 target 图声明 | `configuring-cmake` 的定 target；生成器与目录回定构建 |
+| clangd 跳转失败、数据库指向旧编译器 | `.clangd` 的 `CompilationDatabase`、`build/compile_commands.json` 链接 | 定工具配置 |
 | 编译错误指向函数体 | 实现 | `developing-cpp` 的定实现；先修语义，再重跑 |
 | CTest 失败 | 测试断言、行为句 | `developing-cpp` 的定行为 / 定实现 |
-| `app` 启动失败、找不到共享库 | 输出目录、RPATH / 运行时库路径 | 定构建 |
+| `app` 启动失败、找不到共享库 | 输出目录、RPATH / 运行时库路径 | `configuring-cmake` 的定 target（输出目录与 RPATH） |
 
 分诊只定位，不自动改。一次只改一类问题；改完从失败的那一步重跑，只有行为或边界也变了才回到定行为。
 

package/skills/configuring-cmake/SKILL.md

@@ -13,18 +13,18 @@ metadata:
 
 一次改动同时碰到源码和 CMake 时先开 `developing-cpp` 定行为与边界，再用本技能把源文件、库和程序写进 target，最后到 `building-cpp` 跑检查。只改一个 target 的 include、链接或标准时走单点修正；新工程、新组件、换语言标准或抽公共函数时走整段重构。
 
-存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。`environment.json` 的 `standard` 是 target 标准的唯一来源；缺失、非法或与现有 target 不一致时停在定 target，不猜标准。构建目录、编译器和工具版本由 `building-cpp` 的定构建负责，本技能只写 target 契约。
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。`environment.json` 的 `standard` 是 target 标准的唯一来源；缺失、非法或与现有 target 不一致时停在定 target，不猜标准。构建目录、编译器和工具版本由 `building-cpp` 的定构建负责，本技能只写 target 契约；target 图与 CMake 写法以本技能为权威，`building-cpp` 只读不修改。
 
 ## 三种操作
 
+一次只选一种，范围（单点、整段）是任务属性。操作与域的判据、边界和交接见 `../developing-cpp/references/change-model.md`；四类改动是域，不是操作。
+
 | 操作 | 什么时候用 | 从哪步进 |
 | --- | --- | --- |
 | 写作（起稿） | 新增 target、改公共 include 或链接边界、换语言标准 | 第 1 步；新工程走到第 3 步 |
 | 改写 | target 图与标准不变，模块、函数或目录结构不对 | 从第 2 步重走，可到第 3 步 |
 | 润色 | 只改函数名、注释措辞或错误消息 | 第 2 步 |
 
-范围随任务定：单点修正只改一个 target 的一处；整段重构先定 target 图与标准，再定模块与函数，最后跑完整检查。
-
 三种操作共用这些约束：不发明项目没有声明的 target、标准、编译器或目录；不覆盖已有 `CMakeLists.txt`；不用全局 `include_directories()`、`add_definitions()`、`CMAKE_CXX_FLAGS` 给所有 target 加料；不写 `file(GLOB ...)`；不把 `main()` 编进库；库与程序不下载依赖，只有测试需要时调用 `LinkSettings_FetchGoogleTest`。后一步发现前一步没做完，退回那一步。
 
 ## 步骤
@@ -39,7 +39,7 @@ metadata:
 
 本轮激活按三条上限走：
 
-- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `developing-cpp` 的交接顺序（源码 → `configuring-cmake` → `building-cpp`）逐段进入，前一段结论落下再开下一段。
+- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `源码 → configuring-cmake → building-cpp` 的顺序逐段进入，前一段结论落下再开下一段。
 - 条文只开该步点名的一份；同号案例留到下一次激活。
 - 标准档只打开项目技能声明的那一档，没有声明时用本技能已有的新工程默认，不把其余标准档读进来。
 
@@ -49,20 +49,20 @@ metadata:
 
 ### 四类改动
 
-四类改动是操作内部的域，不是独立的操作：写作域定 target 与边界，布局与排版改模块与形态，润色只改措辞。一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+四类改动是操作内部的域：操作定入口，域定层次。四域的定义、边界与次序见 `../developing-cpp/references/change-model.md`；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」拆开做，前一类落定并经检查再进下一类。
 
-| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
-| --- | --- | --- | --- |
-| 写作 | 新增 target、改公共 include 或链接边界、换语言标准 | 第 1 步 | `steps/01-targets.md`、`references/cxx-standard.md` |
-| 布局 | 抽函数、拆模块、调导入位置 | 第 2 步 | `steps/02-modules.md`、`references/modules.md` |
-| 排版 | 只改 2 空格、行宽或注释形态 | 第 2 步的契约写法 | `steps/02-modules.md`、`references/cmake.md`、`references/modules.md` |
-| 润色 | 只改函数名、注释措辞或错误消息 | 第 2 步 | `steps/02-modules.md`、`references/modules.md` |
+| 类型 | 典型请求 | 入口步骤 |
+| --- | --- | --- |
+| 写作 | 新增 target、改公共 include 或链接边界、换语言标准 | `steps/01-targets.md` |
+| 布局 | 抽函数、拆模块、调导入位置 | `steps/02-modules.md` |
+| 排版 | 只改 2 空格、行宽或注释形态 | `steps/02-modules.md` |
+| 润色 | 只改函数名、注释措辞或错误消息 | `steps/02-modules.md` |
 
 ## 完成判据
 
-- target 图显式：程序 target 叫 `app`，库 target 用组件名，程序链接库，库的公共 include 用 `PUBLIC`；没有全局 include、全局编译选项或 GLOB。
-- 每个 target 的标准来自 `environment.json`；`target_compile_features` 与 `CXX_STANDARD`、`CXX_STANDARD_REQUIRED ON`、`CXX_EXTENSIONS OFF` 同时存在，live 的 `compile_commands.json` 最后一条 `-std=` 与声明一致，不是 `gnu++NN`。
-- 复用的 CMake 函数放在 `cmake/` 模块里，文件名用 UpperCamelCase，函数名用 `<ModuleName>_` 加 PascalCase，有目标与参数校验，根 `CMakeLists.txt` 通过 `CMAKE_MODULE_PATH` 导入；没有重复片段和未使用的旧模块。
-- 公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` / `:keyword` 标参数；不写 `#[[.rst:` 与 `.. command::`，完整写法见 `references/cmake.md`；函数组之间用 `#---`，不画 `#===...===#` 方框。
-- `CMakeLists.txt` 与 `*.cmake` 用 UTF-8 无 BOM、LF、2 空格缩进、不用 tab；行宽按团队约定，默认 80 列。
-- configure 与构建通过，构建产物不落在源码目录；没有改源码语义，也没有覆盖已有工程文件。
+- [ ] target 图显式：程序 target 叫 `app`，库 target 用组件名，程序链接库，库的公共 include 用 `PUBLIC`；没有全局 include、全局编译选项或 GLOB。
+- [ ] 每个 target 的标准来自 `environment.json`；`target_compile_features` 与 `CXX_STANDARD`、`CXX_STANDARD_REQUIRED ON`、`CXX_EXTENSIONS OFF` 同时存在，live 的 `compile_commands.json` 最后一条 `-std=` 与声明一致，不是 `gnu++NN`。
+- [ ] 复用的 CMake 函数放在 `cmake/` 模块里，文件名用 UpperCamelCase，函数名用 `<ModuleName>_` 加 PascalCase，有目标与参数校验，根 `CMakeLists.txt` 通过 `CMAKE_MODULE_PATH` 导入；没有重复片段和未使用的旧模块。
+- [ ] 公开函数上方写中文 `#` 契约：一句功能、空行、边界，再用 `:param` / `:keyword` 标参数；不写 `#[[.rst:` 与 `.. command::`，完整写法见 `references/cmake.md`；函数组之间用 `#---`，不画 `#===...===#` 方框。
+- [ ] `CMakeLists.txt` 与 `*.cmake` 用 UTF-8 无 BOM、LF、2 空格缩进、不用 tab；行宽按团队约定，默认 80 列。
+- [ ] configure 与构建通过，构建产物不落在源码目录；没有改源码语义，也没有覆盖已有工程文件。

package/skills/configuring-cmake/steps/03-check.md

@@ -34,6 +34,6 @@ GCC 模式把目录和编译器换成 `build/gcc`、`g++`。每次检查都重
 | 函数参数没校验、模块重复导入、旧模块残留 | 第 2 步 |
 | 只是 CTest 或运行失败 | 转 `building-cpp` 的通过检查 |
 
-## 边界
+## 交回构建
 
-本步不替代 `building-cpp`：不安装工具链，不改 `running-build.sh`，不跑 `clang-tidy` 或 CTest。检查通过的判据是 configure 与构建成功、数据库标准正确、结构规则无命中；完整的构建、测试与运行检查仍由 `building-cpp` 的通过检查给出。
+本步的判据是 configure 与构建成功、数据库标准正确、结构规则无命中；工具链、入口脚本、`clang-tidy` 与 CTest 的完整检查见 `building-cpp` 的 `steps/03-check.md`。

package/skills/developing-cpp/SKILL.md

@@ -7,24 +7,24 @@ metadata:
 
 # developing-cpp
 
-## 适用场景
-
 本技能处理换一台机器也不会改的源码内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文取自 C++ Core Guidelines 的 Error handling，只约束开发期的源码，不进入插件运行时。`CMakeLists.txt` 与 `cmake/` 开 `configuring-cmake`；`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 的维护开 `building-cpp`（本技能只读其中的 `standard`）。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `configuring-cmake` 把文件写进 CMake，再开 `building-cpp` 定工具配置并通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
 
-存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。动源码前还要读项目声明的语言标准（`environment.json` 的 `standard`，或项目技能正文写明的档位）；声明 C++20 的工程里不要写 C++23 才有的设施。项目没有声明时才用本技能的新工程默认 C++23。没有项目技能时门禁不会放出本技能，不要猜项目约定。
+## 适用场景
+
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令与语言档位。项目技能没有写档位时，才读 `environment.json` 的 `standard`；两者都没有时才用本技能的新工程默认 C++23。声明 C++20 的工程里不要写 C++23 才有的设施；没有项目技能时门禁不会放出本技能，不要猜项目约定。
 
 源码和构建文件的编码以 `building-cpp` 的 `references/encoding.md` 为准；行尾与 `.clang-format` 的 `LineEnding` 跟仓库根 `.gitattributes` 和 `.editorconfig`。
 
 ## 三种操作
 
+一次只选一种，范围（单点、整段）是任务属性。操作与域的判据、边界和交接见 `references/change-model.md`；四类改动是域，不是操作。
+
 | 操作 | 什么时候用 | 从哪步进 |
 | --- | --- | --- |
 | 写作（起稿） | 新增类型、函数或文件；改可观察行为；改库与程序的边界；补构造后置条件与成员事实 | 第 1 步；新工程走到第 4 步 |
 | 改写 | 行为与契约不变，文件位置、声明顺序或函数体组织不对 | 从被打破的步重走，可到第 4 步 |
 | 润色 | 只改命名或注释措辞 | 第 3 步 |
 
-范围随任务定：单点修正只改判为不合格的一处，其余保持原样；整段重构第 1、2 步先定删留，不动函数体，第 3、4 步才改代码。
-
 三种操作共用这些约束：不发明阶段表和用户请求里没有的行为、类型和命令；选类型与写法时以项目声明的语言标准为上限；只改注释或格式时不改可观察行为；不覆盖已有源码；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。计划、命名方案或注释措辞与条文、项目技能或用户明确要求冲突时，先列冲突位置、原文与出处，由用户选一条；不自行取舍，也不默认采用计划。后一步发现前一步没做完，退回那一步，不在当前步补结构。拿不准先用单点修正；做到一半发现边界被打破，退回整段重构，从被打破的那一步重走。
 
 ## 步骤
@@ -40,7 +40,7 @@ metadata:
 
 本轮激活按三条上限走：
 
-- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `developing-cpp` 的交接顺序（源码 → `configuring-cmake` → `building-cpp`）逐段进入，前一段结论落下再开下一段。
+- 只开当前步对应的一个步骤文件；同一改动域内不同时展开两个技能的步骤。跨域按 `源码 → configuring-cmake → building-cpp` 的顺序逐段进入，前一段结论落下再开下一段。
 - 条文只开该步点名的一份；同号案例留到下一次激活。
 - 标准档只打开项目技能声明的那一档，没有声明时用本技能已有的新工程默认，不把其余标准档读进来。
 
@@ -48,7 +48,7 @@ metadata:
 
 ### 四类改动
 
-四类改动是操作内部的域，不是独立的操作：写作域定行为与边界，布局与排版只改形状，润色只改措辞。一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做，前一类落定并经检查再进下一类。
+四类改动是操作内部的域：操作定入口，域定层次。四域的定义、边界与次序见 `references/change-model.md`；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」拆开做，前一类落定并经检查再进下一类。
 
 | 类型 | 典型请求 | 入口步骤 |
 | --- | --- | --- |
@@ -63,9 +63,9 @@ metadata:
 
 ## 完成判据
 
-- 第 1 步的行为句能被用户或测试验收；有阶段表时只覆盖对应行，没有时只覆盖用户点名的行为。
-- 第 2 步的库 target 不依赖终端、GUI 或脚本；程序 target 只做装配和输入输出；共享抽象有第二个真实使用方。
-- 第 3 步的公共头文件自包含，命名、声明顺序和异常声明符合 `references/` 的条文。
-- 第 4 步的实现只兑现声明；资源由 RAII 管理；失败是正常结果时用返回值，函数无法完成任务时抛异常，不拿异常做正常分支。
-- 源码注释符合 `references/comments.md` 的四节规范，`node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>` 无输出。
-- 没有改 `CMakeLists.txt`、`.clang-*`、构建脚本，也没有把外部资料路径或项目专属类名写进通用条文。
+- [ ] 第 1 步的行为句能被用户或测试验收；有阶段表时只覆盖对应行，没有时只覆盖用户点名的行为。
+- [ ] 第 2 步的库 target 不依赖终端、GUI 或脚本；程序 target 只做装配和输入输出；共享抽象有第二个真实使用方。
+- [ ] 第 3 步的公共头文件自包含，命名、声明顺序和异常声明符合 `references/` 的条文。
+- [ ] 第 4 步的实现只兑现声明；资源由 RAII 管理；失败是正常结果时用返回值，函数无法完成任务时抛异常，不拿异常做正常分支。
+- [ ] 源码注释符合 `references/comments.md` 的四节规范，`node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>` 无输出。
+- [ ] 没有改 `CMakeLists.txt`、`.clang-*`、构建脚本，也没有把外部资料路径或项目专属类名写进通用条文。

package/skills/developing-cpp/examples/comments-declaration.md

@@ -15,9 +15,9 @@
 
 ```cpp
 /// @file cell.h
-/// @brief 定义格子状态与格子。
+/// @brief 格子相关类型定义。
 ///
-/// 包含格子状态 `CellState` 与格子 `Cell`。
+/// 封装了格子的状态枚举 `CellState` 以及格子实体 `Cell`。
 ```
 
 文件头只介绍这个文件里有什么，不写作者和变更史，也不把读者指去另一个文件。
@@ -65,7 +65,7 @@ class Board {
 class Game {
 ```
 
-纯数据结构和枚举只写一句名词短语；类有不变量，且第二段不是重复 `cells_`、`kBoardRows` 这类领域尺寸时，才保留第二段。第二段直接写不变量，不加「限制：」这类标签。函数各自的契约下沉到函数注释，设计理由与分层写进书稿。
+纯数据结构和枚举只写一句名词短语；类有不变量，且第二段不是重复 `cells_`、`kRowCount` 这类领域尺寸时，才保留第二段。第二段直接写不变量，不加「限制：」这类标签。函数各自的契约下沉到函数注释，设计理由与分层写进书稿。
 
 ## 构造函数与析构函数：标签 + 职责
 
@@ -88,7 +88,7 @@ Board() = default;
 virtual ~Ai();
 ```
 
-`= default` 本身不说明成员被初始化成什么；`cells_{}` 把每个 `CellType` 初始化成 `kEmpty`，这条后置条件从签名上看不出来。标签说明这是哪一类特殊成员，冒号后写它建立的状态或承担的职责。
+`= default` 本身不说明成员被初始化成什么；`cells_{}` 把每个 `CellState` 初始化成 `kEmpty`，这条后置条件从签名上看不出来。标签说明这是哪一类特殊成员，冒号后写它建立的状态或承担的职责。
 
 ## 风格理由不进注释
 
@@ -96,31 +96,29 @@ virtual ~Ai();
 
 ```cpp
 /// 检查坐标是否在范围内。函数名用 UpperCamel 而不是 snake_case，与标准库区分。
-[[nodiscard]] static bool IsInRange(CellPosition position) noexcept;
+[[nodiscard]] static bool IsInRange(Position position) noexcept;
 
 /// 检查格子是否为空。函数名用 UpperCamel 而不是 snake_case，与标准库区分。
-[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
+[[nodiscard]] bool IsCellEmpty(Position position) const;
 ```
 
 **好**（只写契约）：
 
 ```cpp
 /// 检查坐标是否落在棋盘下标区间内。
-///
-/// 只判断几何边界，不检查格子是否为空、对局是否已经结束。
-[[nodiscard]] static bool IsInRange(CellPosition position) noexcept;
+[[nodiscard]] static bool IsInRange(Position position) noexcept;
 ```
 
 命名与风格约定写进项目文档和读者正文，注释里不解释「为什么用这种命名」。
 
-## 第一句：结果、限制或检查项
+## 第一句：结果、保证或检查项
 
 **差**：
 
 ```cpp
 /// 检查坐标。
 /// 返回格子类型；越界会抛异常。
-CellType GetCellType(CellPosition position) const;
+CellState GetState(Position position) const;
 ```
 
 前两句都没有直接回答“合法时拿到什么、越界时发生什么”，读者要读完三句才拼出合同。
@@ -132,7 +130,7 @@ CellType GetCellType(CellPosition position) const;
 ///
 /// @param position 行列坐标。
 /// @throws std::out_of_range 坐标不在棋盘范围内。
-CellType GetCellType(CellPosition position) const;
+CellState GetState(Position position) const;
 ```
 
 第一句就是结果、失败方式或检查项；后面的标签只补参数与异常细节，不再重复这句话。
@@ -141,14 +139,14 @@ CellType GetCellType(CellPosition position) const;
 
 ```cpp
 /// 比较两个坐标。
-friend bool operator==(const CellPosition&, const CellPosition&) = default;
+friend bool operator==(const Position&, const Position&) = default;
 ```
 
 **好**：
 
 ```cpp
 /// 检查两个坐标的行与列是否都相同。
-friend bool operator==(const CellPosition&, const CellPosition&) = default;
+friend bool operator==(const Position&, const Position&) = default;
 ```
 
 布尔查询和 `operator==` 的第一句都用「检查…是否…」，让读者先看到被检查的条件，而不是一个同义反复的动词。
@@ -161,7 +159,7 @@ friend bool operator==(const CellPosition&, const CellPosition&) = default;
 /// 尝试执行一次落子。
 ///
 /// @param move 落子。
-/// @returns 落子执行成功返回 kPlaced，被拒绝返回 kRejected。
+/// @returns 落子执行成功返回 kPlaced，被拒绝返回 kOccupied。
 [[nodiscard]] PlaceResult TryPlace(const Move& move);
 ```
 
@@ -175,18 +173,18 @@ friend bool operator==(const CellPosition&, const CellPosition&) = default;
 /// 只有本局仍在进行、且落子玩家正是当前玩家时才继续，棋盘、轮次、历史三者一起更新。
 ///
 /// @param move 待执行的落子，玩家必须是当前轮到的玩家。
-/// @return 落子写入棋盘并换手时返回 kPlaced；对局已结束或上述任一条件不满足时返回 kRejected，
+/// @return 落子写入棋盘并换手时返回 kPlaced；对局已结束或上述任一条件不满足时返回 kOccupied，
 ///         棋盘和轮次都不变。
 [[nodiscard]] PlaceResult TryPlace(const Move& move);
 ```
 
-## 布尔查询要写「不检查什么」
+## 布尔查询只写检查什么
 
 **差**：
 
 ```cpp
 /// 检查指定坐标上的棋盘格子是否为空。
-[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
+[[nodiscard]] bool IsCellEmpty(Position position) const;
 ```
 
 **好**：
@@ -194,15 +192,12 @@ friend bool operator==(const CellPosition&, const CellPosition&) = default;
 ```cpp
 /// 检查指定坐标上的棋盘格子是否为空。
 ///
-/// 只回答「这一格能不能落子」，不判断对局是否已经结束：对局结束后格子仍是空的，
-/// 但再落子没有意义。是否需要先看对局状态由调用方决定，棋盘不替它下结论。
-///
 /// @param position 待检查的坐标。
 /// @return 坐标在棋盘内且该格为空时返回 true；越界或该格已有棋子时返回 false。
-[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
+[[nodiscard]] bool IsCellEmpty(Position position) const;
 ```
 
-布尔函数最容易被误用；把「不检查什么」写出来，比多写一个参数说明有用。
+布尔查询的第一句写「检查…是否…」，`@return` 写成立与不成立的条件；能力边界不写成否定清单，调用方要满足的条件用正向限定或 `@pre`。
 
 ## 枚举
 
@@ -235,7 +230,7 @@ enum class GameResult : std::uint8_t {
 
 ```cpp
 Board board_;  // 对局棋盘。
-std::array<std::array<CellType, kBoardCols>, kBoardRows> cells_{};  // 存储棋盘格子。
+std::array<std::array<CellState, kColumnCount>, kRowCount> cells_{};  // 存储棋盘格子。
 ```
 
 前一句把名字翻译了一遍；后一句只复述声明，没有说清两层下标各是什么。
@@ -244,7 +239,7 @@ std::array<std::array<CellType, kBoardCols>, kBoardRows> cells_{};  // 存储棋
 
 ```cpp
 /// 棋盘格子数组：外层下标是行，内层下标是列。
-std::array<std::array<CellType, kBoardCols>, kBoardRows> cells_{};
+std::array<std::array<CellState, kColumnCount>, kRowCount> cells_{};
 /// 当前玩家：开局由 X 先手。
 Player current_player_ = Player::kCross;
 /// 对局结果：落子被拒时保持原值。
@@ -253,7 +248,7 @@ GameResult result_ = GameResult::kInProgress;
 std::vector<Move> history_;
 ```
 
-主注释写在声明上一行，类数据成员（含私有）统一用 `///`；第一句先说是哪个成员，再用全角冒号补名字和类型看不出的范围、初值含义、轴向、哨兵与改写时机。行尾不写补充；`///<` 只给枚举项和 `struct` 短字段。名字已经说明存放对象的 `board_` 不写「对局棋盘」。
+主注释写在声明上一行，类数据成员（含私有）统一用 `///`；第一句先说是哪个成员，再用全角冒号补名字和类型看不出、只属于该成员的范围、轴向、哨兵与所有权。类级初值与状态迁移写在类注释，成员注释不重复。行尾不写补充；`///<` 只给枚举项和 `struct` 短字段。名字已经说明存放对象的 `board_` 不写「对局棋盘」。
 
 ## 完整声明：后置条件与轴向
 
@@ -268,7 +263,7 @@ class Board {
 
  private:
   /// 棋盘格子数组：外层下标是行，内层下标是列。
-  std::array<std::array<CellType, kBoardCols>, kBoardRows> cells_{};
+  std::array<std::array<CellState, kColumnCount>, kRowCount> cells_{};
 };
 ```
 

package/skills/developing-cpp/examples/comments-implementation.md

@@ -10,7 +10,7 @@
 // 遍历所有空格
 for (const auto& position : empty_cells) {
   // 尝试落子
-  const bool wins = game.PreviewWin(position, cell_type) == WinPreviewResult::kWouldWin;
+  const bool wins = game.PreviewWin(position, state) == WinPreviewResult::kWouldWin;
   // 如果能赢
   if (wins) {
     // 返回这一手

package/skills/developing-cpp/examples/exceptions.md

@@ -62,10 +62,10 @@ throw std::out_of_range{row, col};
 
 ```cpp
 // 返回值：失败是可恢复结果，两种模式都返回 false。
-[[nodiscard]] bool TryPlace(CellPosition position, Player player) noexcept;
+[[nodiscard]] bool TryPlace(Position position, Player player) noexcept;
 
 // 越界：两种模式都抛 std::out_of_range；Debug 消息可带 file:line。
-void Place(CellPosition position, Player player);
+void Place(Position position, Player player);
 ```
 
 越界用标准库已有的 `std::out_of_range`，调用方不需要认识项目私有类型；只有调用方必须把它和其它 `out_of_range` 区分开时，才定义派生类并在 `what()` 里补位置信息。

package/skills/developing-cpp/examples/naming.md

@@ -2,14 +2,7 @@
 
 ## 基本规则
 
-| 差 | 好 | 原因 |
-| --- | --- | --- |
-| `class task_list` | `class TaskList` | 类型 PascalCase |
-| `void add_task()` | `void AddTask()` | 函数 PascalCase |
-| `int TaskCount` | `int task_count` | 变量 snake_case |
-| `std::vector<Task> Tasks` | `std::vector<Task> tasks_` | 成员 snake_case + `_` |
-| `constexpr int MAX = 10` | `constexpr int kMaxTasks = 10` | 常量 `k` 前缀 |
-| `enum class Color { Red }` | `enum class Color { kRed }` | 枚举子 `k` 前缀 |
+大小写、前缀与成员尾随 `_` 的规则表见 `references/naming.md`；下面只收需要语境才能判断的例子。
 
 ## 访问器
 

package/skills/developing-cpp/examples/structure.md

@@ -87,8 +87,8 @@ task_list/src/detail.h           // 私有头，只被本组件包含
 
 ```cpp
 // 差：用循环现写八条线，坐标藏在控制流里。
-std::vector<std::vector<CellPosition>> BuildLines() {
-  std::vector<std::vector<CellPosition>> lines;
+std::vector<std::vector<Position>> BuildLines() {
+  std::vector<std::vector<Position>> lines;
   for (int row = 0; row < kRows; ++row) { /* ... */ }
   // 列与两条对角线再各写一段
   return lines;
@@ -99,7 +99,7 @@ std::vector<std::vector<CellPosition>> BuildLines() {
 
 ```cpp
 // board.cpp 的 namespace tictactoe：行、列、对角线三组，坐标固定。
-constexpr std::array<std::array<CellPosition, 3>, 8> kLines = {{
+constexpr std::array<std::array<Position, 3>, 8> kLines = {{
     {{{0, 0}, {0, 1}, {0, 2}}},  // 行 0
     {{{1, 0}, {1, 1}, {1, 2}}},  // 行 1
     {{{2, 0}, {2, 1}, {2, 2}}},  // 行 2
@@ -119,31 +119,31 @@ constexpr std::array<std::array<CellPosition, 3>, 8> kLines = {{
 
 ```cpp
 Board hypothetical = *this;
-const PlaceCellResult placed = hypothetical.PlaceCell(position, cell_type);
-if (placed != PlaceCellResult::kSuccess) {
+const Cell::PlaceResult placed = hypothetical.Place(position, state);
+if (placed != Cell::PlaceResult::kPlaced) {
   return WinPreviewResult::kInvalidPlace;
 }
-return hypothetical.HasLine(cell_type) ? WinPreviewResult::kWouldWin
+return hypothetical.HasLine(state) ? WinPreviewResult::kWouldWin
                                        : WinPreviewResult::kWouldNotWin;
 ```
 
-**好**：判断「这一格换成某种棋子后会不会成线」不需要第二份棋盘。越界、空格、已占用交给 `CheckPlaceable` 统一返回原因；通过之后只在包含该坐标的线上把这一格算作 `cell_type`，其余格子读原棋盘。
+**好**：判断「这一格换成某种棋子后会不会成线」不需要第二份棋盘。越界、空格、已占用交给 `CheckPlaceable` 统一返回原因；通过之后只在包含该坐标的线上把这一格算作 `state`，其余格子读原棋盘。
 
 ```cpp
-WinPreviewResult Board::PreviewWin(CellPosition position, CellType cell_type) const {
-  if (CheckPlaceable(position, cell_type) != PlaceCellResult::kSuccess) {
+WinPreviewResult Board::PreviewWin(Position position, CellState state) const {
+  if (CheckPlaceable(position, state) != Cell::PlaceResult::kPlaced) {
     return WinPreviewResult::kInvalidPlace;
   }
 
-  const auto matches = [&](CellPosition cell) {
+  const auto matches = [&](Position cell) {
     if (cell.row == position.row && cell.col == position.col) {
       return true;
     }
-    return cells_.at(cell.row).at(cell.col) == cell_type;
+    return cells_.at(cell.row).at(cell.col) == state;
   };
 
   const bool completes = std::ranges::any_of(kLines, [&](const auto& line) {
-    const bool contains = std::ranges::find_if(line, [&](CellPosition cell) {
+    const bool contains = std::ranges::find_if(line, [&](Position cell) {
                             return cell.row == position.row && cell.col == position.col;
                           }) != line.end();
     return contains && std::ranges::all_of(line, matches);