@chengzhao-dev/dsh-cpp-workflow 0.3.0 → 0.3.1

package/README.en.md

@@ -8,7 +8,7 @@ Two skills for C++11–C++23 source and build work; new projects default to C++2
 
 | Skill | Covers | Open it when |
 | --- | --- | --- |
-| `developing-cpp` | Behavior, boundaries, declarations, implementation; naming, exceptions, and source comments in `.h` / `.cc` | The user names source code, or the work is a new project or whole-stage refactor |
+| `developing-cpp` | Behavior, boundaries, declarations, implementation; naming, exceptions, and source comments in `.h` / `.cpp` / `.cc` | The user names source code, or the work is a new project or whole-stage refactor |
 | `building-cpp` | Build setup, tool configuration, checks; CMake, Ninja, Clang config, build scripts, and environment combinations | The change touches build files, tool config, or the environment declaration, or the project is first connected to a build |
 
 The exception material follows the C++ Core Guidelines' Error handling section and guides source and examples only during development; the plugin runtime never compiles or executes those rules. Both skills read the project skill `cpp-workflow-project` first. Without it, the workspace gate never exposes these names.
@@ -18,13 +18,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.3.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
 ```
 
 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.
@@ -89,7 +89,9 @@ dsh-cpp-workflow/
 └── icon.svg
 ```
 
-Maintenance notes: flow and gate in [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md), directory and npm whitelist in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md), version rules in [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md).
+The repository also keeps `src/`, `scripts/`, `tests/` and `docs/` for development and review; they are not published. The whitelist lives in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md).
+
+Maintenance notes: flow and gate in [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md), skill layers and data flow in [docs/architecture.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/architecture.md), trigger matrix in [docs/triggering.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/triggering.md), directory and npm whitelist in [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md), version rules in [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md).
 
 ## Local development
 
@@ -97,7 +99,7 @@ Requires Node.js 22 or newer.
 
 ```bash
 npm ci
-npm test              # build, structural check, gate/environment/schema tests
+npm test              # build, structural check, gate/environment/schema/comment tests
 npm run test:matrix   # real build matrix: 4 templates x 5 standards
 npm run pack:check    # inspect the npm package contents
 ```

package/README.md

@@ -8,7 +8,7 @@
 
 | 技能 | 管什么 | 什么时候打开 |
 | --- | --- | --- |
-| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
+| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
 | `building-cpp` | 定构建、定工具配置、通过检查；CMake、Ninja、Clang 配置、构建脚本和环境组合 | 改动落在构建文件、工具配置或环境声明上，或第一次接构建 |
 
 异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。两个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这两个名字。
@@ -18,13 +18,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.1
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.1
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -89,7 +89,9 @@ dsh-cpp-workflow/
 └── icon.svg
 ```
 
-边界与门禁的维护说明在 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md)，目录和进包白名单在 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。
+仓库另有 `src/`、`scripts/`、`tests/` 与 `docs/`，只服务开发与评审，不进包；白名单见 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)。
+
+边界与门禁的维护说明在 [docs/plugin-flow.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-flow.md)，技能的层次与数据流在 [docs/architecture.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/architecture.md)，触发矩阵在 [docs/triggering.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/triggering.md)，目录和进包白名单在 [docs/plugin-layout.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-layout.md)，版本规则在 [docs/versioning.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/versioning.md)。
 
 ## 本地开发
 
@@ -97,7 +99,7 @@ dsh-cpp-workflow/
 
 ```bash
 npm ci
-npm test              # 构建、结构检查、门禁/环境/schema 测试
+npm test              # 构建、结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
 ```

package/lib/workspace.js

@@ -6,12 +6,10 @@
 // freshly copied template still sees the workflow. The git root is the
 // repository boundary: marker lookup ignores sibling directories and never
 // searches above the root.
-import { access, readdir } from 'node:fs/promises';
+import { access } from 'node:fs/promises';
 import path from 'node:path';
 export const PROJECT_SKILL = path.join('.agents', 'skills', 'cpp-workflow-project', 'SKILL.md');
 export const MAX_ASCENT = 64;
-export const MAX_SCAN_DEPTH = 12;
-export const MAX_SCAN_ENTRIES = 4000;
 const SKIPPED_DIRS = new Set([
     '.git',
     'node_modules',
@@ -22,16 +20,6 @@ const SKIPPED_DIRS = new Set([
     'temp',
     '.cache',
 ]);
-export const CPP_SOURCE_EXTENSIONS = new Set([
-    '.c',
-    '.cc',
-    '.cpp',
-    '.cxx',
-    '.h',
-    '.hh',
-    '.hpp',
-    '.hxx',
-]);
 export const CPP_BUILD_FILES = new Set(['CMakeLists.txt']);
 async function exists(target) {
     try {
@@ -107,49 +95,6 @@ export async function findProjectSkill(cwd, gitRoot) {
 export async function hasProjectSkill(cwd, gitRoot) {
     return (await findProjectSkill(cwd, gitRoot)) !== undefined;
 }
-/**
- * True when `root` contains at least one first-party `CMakeLists.txt` or C++
- * source/header. Generated, dependency, template and build trees are skipped.
- * The scan is bounded to 12 levels and 4000 directory entries.
- */
-export async function hasCppProject(root) {
-    let seen = 0;
-    const queue = [{ dir: root, depth: 0 }];
-    while (queue.length > 0) {
-        const current = queue.shift();
-        if (!current)
-            break;
-        let entries;
-        try {
-            entries = await readdir(current.dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const entry of entries) {
-            seen += 1;
-            if (seen > MAX_SCAN_ENTRIES)
-                return false;
-            if (entry.isSymbolicLink())
-                continue;
-            if (entry.isDirectory()) {
-                if (current.depth >= MAX_SCAN_DEPTH)
-                    continue;
-                if (SKIPPED_DIRS.has(entry.name))
-                    continue;
-                queue.push({ dir: path.join(current.dir, entry.name), depth: current.depth + 1 });
-                continue;
-            }
-            if (!entry.isFile())
-                continue;
-            if (CPP_BUILD_FILES.has(entry.name))
-                return true;
-            if (CPP_SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase()))
-                return true;
-        }
-    }
-    return false;
-}
 /**
  * Session gate. The project skill must sit between `cwd` and the git root
  * (inclusive). First-party C++ or CMake evidence is deliberately not required:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "C++11–C++23 工程流程技能包：源码四步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",

package/skills/building-cpp/SKILL.md

@@ -32,9 +32,9 @@ metadata:
 | --- | --- | --- | --- |
 | 1 | 定构建 | `steps/01-build.md` | 一次配置一个编译器，Ninja，target-based CMake，编译数据库 |
 | 2 | 定工具配置 | `steps/02-tooling.md` | 格式化、静态检查、clangd 各管一段，互不越界 |
-| 3 | 通过检查 | `steps/03-check.md` | 先跑环境脚本的 `--live`，再跑项目入口，按失败位置分诊 |
+| 3 | 通过检查 | `steps/03-check.md` | 按编码 → 声明校验 → 活动校验 → 项目入口的次序跑，前一步失败就停 |
 
-每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；警告选项、GoogleTest 与 rpath 的 CMake 片段在 `assets/cmake/`，由 `references/cmake.md` 指路。
 
 ## 完成判据
 

package/skills/building-cpp/assets/config/.clang-tidy

@@ -5,6 +5,7 @@ InheritParentConfig: false
 Checks: >
   -*,
   google-*,
+  portability-avoid-pragma-once,
   readability-identifier-naming
 
 WarningsAsErrors: '*'

package/skills/building-cpp/assets/templates/projects/multi/CMakeLists.txt

@@ -7,8 +7,8 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 enable_testing()
 
 add_executable(app
-  src/main.cc
-  src/greeting.cc
+  src/main.cpp
+  src/greeting.cpp
 )
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)

package/skills/building-cpp/assets/templates/projects/shared-library/CMakeLists.txt

@@ -9,7 +9,7 @@ enable_testing()
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES

package/skills/building-cpp/assets/templates/projects/shared-library/greeting/CMakeLists.txt

@@ -1,4 +1,4 @@
-add_library(greeting SHARED src/greeting.cc)
+add_library(greeting SHARED src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES

package/skills/building-cpp/assets/templates/projects/single/CMakeLists.txt

@@ -6,7 +6,7 @@ set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
 enable_testing()
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23

package/skills/building-cpp/assets/templates/projects/static-library/CMakeLists.txt

@@ -9,7 +9,7 @@ enable_testing()
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_include_directories(app PRIVATE ${CMAKE_CURRENT_SOURCE_DIR})
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES

package/skills/building-cpp/assets/templates/projects/static-library/greeting/CMakeLists.txt

@@ -1,4 +1,4 @@
-add_library(greeting STATIC src/greeting.cc)
+add_library(greeting STATIC src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES

package/skills/building-cpp/examples/cmake.md

@@ -10,13 +10,13 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
-add_library(greeting STATIC greeting/src/greeting.cc)
+add_library(greeting STATIC greeting/src/greeting.cpp)
 target_include_directories(greeting PUBLIC greeting/include)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES CXX_EXTENSIONS OFF)
 target_compile_options(greeting PRIVATE -Wall -Wextra -Werror)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES CXX_EXTENSIONS OFF)
 target_link_libraries(app PRIVATE greeting)
@@ -30,7 +30,7 @@ target_link_libraries(app PRIVATE greeting)
 
 ```cmake
 include_directories(include greeting/include)
-add_executable(app src/main.cc greeting/src/greeting.cc)
+add_executable(app src/main.cpp greeting/src/greeting.cpp)
 ```
 
 问题：所有 target 共享 include，边界消失；程序直接编译库源码，测试无法只链接库。
@@ -47,7 +47,7 @@ target_link_libraries(app PRIVATE greeting)
 **差**：
 
 ```cmake
-file(GLOB SOURCES "src/*.cc")
+file(GLOB SOURCES "src/*.cpp")
 add_executable(app ${SOURCES})
 ```
 
@@ -57,9 +57,9 @@ add_executable(app ${SOURCES})
 
 ```cmake
 add_executable(app
-  src/main.cc
-  src/task_list.cc
-  src/task_parser.cc
+  src/main.cpp
+  src/task_list.cpp
+  src/task_parser.cpp
 )
 ```
 
@@ -70,15 +70,15 @@ add_executable(app
 **差**：
 
 ```cmake
-add_library(core STATIC src/main.cc src/core.cc)
-add_executable(app src/main.cc)   # 重复定义
+add_library(core STATIC src/main.cpp src/core.cpp)
+add_executable(app src/main.cpp)   # 重复定义
 ```
 
 **好**：
 
 ```cmake
-add_library(core STATIC src/core.cc)
-add_executable(app src/main.cc)
+add_library(core STATIC src/core.cpp)
+add_executable(app src/main.cpp)
 target_link_libraries(app PRIVATE core)
 ```
 
@@ -93,7 +93,7 @@ target_link_libraries(app PRIVATE core)
 ```
 
 ```bash
-clang-tidy src/main.cc   # 没有编译参数，头路径和标准都不对
+clang-tidy src/main.cpp   # 没有编译参数，头路径和标准都不对
 ```
 
 **好**：
@@ -106,7 +106,7 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 cmake -S . -B build/clang -G Ninja -DCMAKE_CXX_COMPILER=clang++
 rm -f build/compile_commands.json
 ln -s clang/compile_commands.json build/compile_commands.json
-clang-tidy -p build/clang src/main.cc
+clang-tidy -p build/clang src/main.cpp
 ```
 
 ## 共享库运行时路径
@@ -120,11 +120,11 @@ LD_LIBRARY_PATH=build/clang/lib ./build/clang/bin/app   # 每次运行都要包
 **好**：
 
 ```cmake
-add_library(greeting SHARED greeting/src/greeting.cc)
+add_library(greeting SHARED greeting/src/greeting.cpp)
 set_target_properties(greeting PROPERTIES
   LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_link_libraries(app PRIVATE greeting)
 if(APPLE)
   set_target_properties(app PROPERTIES BUILD_RPATH "@loader_path/../lib")

package/skills/building-cpp/examples/tooling.md

@@ -121,7 +121,7 @@ Checks: >
 **差**：
 
 ```bash
-clang-tidy -p build/clang --system-headers src/main.cc
+clang-tidy -p build/clang --system-headers src/main.cpp
 ```
 
 系统头也参与诊断，出现大量第三方告警。
@@ -130,7 +130,7 @@ clang-tidy -p build/clang --system-headers src/main.cc
 
 ```bash
 clang-tidy -p build/clang --header-filter="^$(pwd -P)/(include|src)/" \
-  --warnings-as-errors='*' src/main.cc
+  --warnings-as-errors='*' src/main.cpp
 ```
 
 `--header-filter` 只列项目顶层目录，避免把第三方头纳入；系统头默认排除。工程有别的顶层目录时按实际替换。
@@ -140,7 +140,7 @@ clang-tidy -p build/clang --header-filter="^$(pwd -P)/(include|src)/" \
 **差**：
 
 ```bash
-clang-format -i src/*.cc   # 构建时悄悄改源码
+clang-format -i src/*.cpp   # 构建时悄悄改源码
 ```
 
 **好**：

package/skills/building-cpp/references/cmake.md

@@ -1,6 +1,6 @@
 # CMake
 
-目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`。
+目标：一个编译器、Ninja、target-based 规则、可用的编译数据库。下面是最小形状和常见边界；模板在 `assets/templates/projects/`，可复用的 CMake 片段在 `assets/cmake/`：`applying-warnings.cmake` 管警告选项，`fetching-googletest.cmake` 取测试框架，`setting-rpath.cmake` 设运行时库路径。
 
 ## 排版
 
@@ -19,7 +19,7 @@ project({{PROJECT_NAME}} VERSION 0.1.0 LANGUAGES CXX)
 set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/bin")
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23
@@ -42,7 +42,7 @@ set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/lib")
 
 add_subdirectory(greeting)
 
-add_executable(app src/main.cc)
+add_executable(app src/main.cpp)
 target_compile_features(app PRIVATE cxx_std_23)
 set_target_properties(app PROPERTIES
   CXX_STANDARD 23
@@ -55,7 +55,7 @@ target_compile_options(app PRIVATE -Wall -Wextra -Werror)
 
 ```cmake
 # greeting/CMakeLists.txt
-add_library(greeting STATIC src/greeting.cc)
+add_library(greeting STATIC src/greeting.cpp)
 target_include_directories(greeting PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}/..)
 target_compile_features(greeting PUBLIC cxx_std_23)
 set_target_properties(greeting PROPERTIES
@@ -168,7 +168,7 @@ FetchContent_MakeAvailable(googletest)
 
 | 模板 | 何时用 | 关键文件 |
 | --- | --- | --- |
-| `single` | 一个 `main.cc`，辅助函数很少 | `CMakeLists.txt`, `src/main.cc` |
+| `single` | 一个 `main.cpp`，辅助函数很少 | `CMakeLists.txt`, `src/main.cpp` |
 | `multi` | 多个源文件，一个程序 | `CMakeLists.txt`, `include/`, `src/` |
 | `static-library` | 库需要被测试或第二个程序链接 | 根 + `greeting/` 子目录 |
 | `shared-library` | 需要运行时加载/替换 | 同上，`SHARED` + RPATH |
@@ -178,7 +178,7 @@ FetchContent_MakeAvailable(googletest)
 ## 反模式
 
 - 全局 `include_directories(include)`：所有 target 共享，边界消失。
-- `file(GLOB sources "src/*.cc")`：新增文件不触发重新配置。
+- `file(GLOB sources "src/*.cpp")`：新增文件不触发重新配置。
 - 把库和 `main()` 编进同一个 target：测试无法只链接库。
 - 在源码目录生成 `compile_commands.json` 或可执行文件。
 - 同时设 `CMAKE_CXX_COMPILER` 和 `CXX` 环境变量，互相覆盖。

package/skills/building-cpp/references/linking.md

@@ -15,25 +15,25 @@
 - 链接：把多个目标文件和库合并，解析符号引用。`undefined reference` 在这一步失败。
 - 加载：程序启动时由动态加载器找到共享库；`error while loading shared libraries` 在这一步失败。
 
-`g++ -c file.cc` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
+`g++ -c file.cpp` 只编译不链接；`g++ file.o -o app` 只链接。`-E` 只看预处理，`-S` 只看汇编。
 
 ## 头文件、声明与定义
 
 - `#include` 是文本替换，不是模块导入；头文件只放声明、`inline` 定义、模板和 `constexpr` 定义。
-- 普通函数的定义放 `.cc`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
-- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cc`。
+- 普通函数的定义放 `.cpp`；在头文件里写非 `inline` 函数定义，多个翻译单元包含时会重复定义。
+- 类定义放头文件；成员函数在类外定义时写 `ClassName::`，定义放 `.cpp`。
 - 只用到声明时不要包含完整定义；前置声明可以减少编译依赖，但不能替代需要完整类型的场景（继承、成员对象、按值返回）。
-- 每个头文件自包含：单独编译一个只包含该头文件的 `.cc` 应通过。用路径式 `#define` 守卫防止重复包含，不用 `#pragma once`。
+- 每个头文件自包含：单独编译一个只包含该头文件的 `.cpp` 应通过。用路径式 `#define` 守卫防止重复包含，不用 `#pragma once`。
 
 ## `undefined reference` 分诊
 
 | 现象 | 常见原因 | 修法 |
 | --- | --- | --- |
-| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cc` 没加入 target | 补定义，或把源文件加入 `target_sources` |
+| 链接器说某个成员函数未定义 | 声明了但没写定义，或 `.cpp` 没加入 target | 补定义，或把源文件加入 `target_sources` |
 | 只有某个平台失败 | 条件编译把定义排除了 | 检查宏和平台分支，保证每个平台都有定义 |
 | 第三方库符号缺失 | 没链接库，或库顺序不对 | `target_link_libraries` 加库；CMake 会处理顺序 |
 | C++ 符号被当成 C 符号 | 头文件缺少 `extern \"C\"` | C 接口头加 `extern \"C\"`，C++ 调用方也可见 |
-| 模板成员未定义 | 模板定义在 `.cc`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
+| 模板成员未定义 | 模板定义在 `.cpp`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
 | 静态库中的目标文件没被拉入 | 链接器只取被引用符号所在的目标文件 | 确认符号确实被引用，或改用对象库/共享库 |
 
 先看链接器报的完整符号名和来源文件，不要只看第一行。

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

@@ -5,7 +5,7 @@
 ## clang-format
 
 ```bash
-clang-format --dry-run --Werror src/*.cc include/*.h tests/*.cc
+clang-format --dry-run --Werror src/*.cpp include/*.h tests/*.cpp
 ```
 
 - 检查用 `--dry-run --Werror`；需要自动修复时单独跑 `clang-format -i`，不要在构建脚本里悄悄改源码。
@@ -21,7 +21,7 @@ clang-format --dry-run --Werror src/*.cc include/*.h tests/*.cc
 clang-tidy -p build/clang \
   --header-filter="^$(pwd -P)/(include|src|apps|tests)/" \
   --warnings-as-errors='*' \
-  src/*.cc apps/*.cc tests/*.cc
+  src/*.cpp apps/*.cpp tests/*.cpp
 ```
 
 - `-p` 指向当前编译器的构建目录，读取 `compile_commands.json`。
@@ -30,7 +30,7 @@ clang-tidy -p build/clang \
 - 系统头默认被排除，不要加 `--system-headers`。
 - 只扫描项目源文件；不要把 `build/` 或第三方源码传给 clang-tidy。
 - `--warnings-as-errors='*'` 把警告当失败；修代码，不要新增 `NOLINT`。确需抑制时写 `// NOLINT(检查名): 理由`，理由必须具体。
-- 配置在工程根 `.clang-tidy`；默认集合是 `google-*` 加 `readability-identifier-naming`。关闭某条时逐条写理由，不整族关闭；命名规则只配项目确实统一的项，不设 `FunctionCase`。
+- 配置在工程根 `.clang-tidy`；默认集合是 `google-*`、`portability-avoid-pragma-once` 加 `readability-identifier-naming`（第二条去掉 `#pragma once`，与路径式守卫一致）。关闭某条时逐条写理由，不整族关闭；命名规则只配项目确实统一的项，不设 `FunctionCase`。
 - 没有编译数据库时先回到 `building-cpp` 的定构建生成；不要用 `--` 手工拼编译参数绕过。
 - `clang-tidy` 的诊断可能指向头文件；修头文件里的声明或实现，不要只改调用点。
 

package/skills/building-cpp/steps/01-build.md

@@ -60,7 +60,7 @@ GCC 模式把目录和编译器换成 `build/gcc`、`g++`。工程确有 C 源
 
 ## 情况
 
-**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名，默认标准 C++23；四套模板已按 `__cplusplus` 条件使用 `std::format`，把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降到 C++11–C++20 后仍应能构建，降完跑 `references/standards/README.md` 的五档矩阵。模板源码是 `.cc`，头文件用路径式 `#define` 守卫；新增文件沿用 `.cc` / `.h`，已有工程保持原有扩展名。
+**新工程**：从 `assets/templates/projects/` 选形态：`single` 单文件、`multi` 多文件单程序、`static-library` 静态库 + 程序、`shared-library` 动态库 + 程序。只复制目标工程缺的文件；已有的 `CMakeLists.txt`、`.clang-*`、源码不覆盖。模板里的 `{{PROJECT_NAME}}` 换成真实工程名，默认标准 C++23；四套模板已按 `__cplusplus` 条件使用 `std::format`，把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降到 C++11–C++20 后仍应能构建，降完跑 `references/standards/README.md` 的五档矩阵。模板源码是 `.cpp`，头文件用路径式 `#define` 守卫；新增文件沿用 `.cpp` / `.h`，已有工程保持原有扩展名。
 
 **已有工程**：先读现有 `CMakeLists.txt`，找出全局设置、GLOB、输出目录和 target 命名；只改与当前任务相关的一处。大改前先让通过检查的项目入口跑通，保留可回退点。
 

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

@@ -13,8 +13,8 @@
 - `.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`（clang-format 21/22 不接受 `c++23`）。列宽 80、每级 2 空格、不用 tab、包含顺序都取 Google 预设；不要覆盖 `ColumnLimit`、`TabWidth`、`IncludeCategories` 或指针对齐。需要新规则时先改 `references/google-cpp-style.md` 并说明理由。
-- `.clang-tidy` 用 `Checks: '-*, google-*, readability-identifier-naming'`，保留 `WarningsAsErrors: '*'` 和 `FormatStyle: file`。`google-*` 覆盖 Google 风格能静态检查的部分；`readability-identifier-naming` 只配项目确实统一的命名项：类型/枚举/别名/模板参数 PascalCase，变量/参数/成员 snake_case，类成员尾随 `_`，结构体成员不尾随，常量 `k` + PascalCase。不要设 `FunctionCase`，Google 允许 `count()` / `set_count()` 这类访问器；不要重新打开 `cppcoreguidelines-*` 整包或 `portability-avoid-pragma-once`。
+- `.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-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 的 `//`，贴在被解释的键上方。
 - 配置注释写「为什么这样设」，不写「这一项是什么」；不写策略头、不指向文档路径。

package/skills/developing-cpp/SKILL.md

@@ -9,7 +9,7 @@ metadata:
 
 ## 适用场景
 
-管 `.h` / `.cc` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文采用 C++ Core Guidelines 的 Error handling，作为开发阶段的源码指导；它不进入插件运行时。`CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 只开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `building-cpp` 的定构建，把文件写进 CMake，再决定是否定工具配置，最后通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+管 `.h` / `.hpp` / `.cpp` / `.cc` 里换一台机器也不会改的内容：可观察行为、库与程序的边界、声明、命名、异常和源码注释。文件槽位与守卫以 `references/file-template.md` 为准；排版、命名、头文件与包含顺序以 `references/google-cpp-style.md` 的 Google 基线为准。异常条文采用 C++ Core Guidelines 的 Error handling，作为开发阶段的源码指导；它不进入插件运行时。`CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-*`、`.vscode/` 和 `environment.json` 只开 `building-cpp`。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开 `building-cpp` 的「通过检查」；新增或移动源文件、改库与程序的边界、补测试 target 时，声明和实现可以先写，但完成前必须开 `building-cpp` 的定构建，把文件写进 CMake，再决定是否定工具配置，最后通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
 
 存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。没有项目技能时门禁不会放出本技能，不要猜项目约定。
 
@@ -31,9 +31,22 @@ metadata:
 | 1 | 定行为 | `steps/01-behavior.md` | 把这一处要能观察到的结果写成验收句 |
 | 2 | 定边界 | `steps/02-boundary.md` | 决定哪些放库、哪些放程序，依赖朝哪个方向 |
 | 3 | 定声明 | `steps/03-declaration.md` | 写命名、声明顺序、头文件契约和声明注释 |
-| 4 | 定实现 | `steps/04-implementation.md` | 写 `.cc` 的操作顺序、分组和实现注释 |
+| 4 | 定实现 | `steps/04-implementation.md` | 写 `.cpp` 函数体的操作顺序、分组和实现注释 |
 
-每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。性能问题读 `references/performance.md`，标准库设施选型读 `references/standard-library.md`，链接与产物的细节读 `building-cpp` 的 `references/linking.md`。
+
+### 四类改动
+
+先认这次改的是哪一类，再决定从哪一步进；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做，前一类落定并经检查再进下一类。
+
+| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
+| --- | --- | --- | --- |
+| 写作 | 新增类型、函数或文件；改可观察行为；改库与程序的边界 | 第 1 步 | `steps/01-behavior.md`、`02-boundary.md`、`references/project-design.md` |
+| 布局 | 换文件位置、拆头文件、调声明顺序、补测试 target | 第 3 步 | `references/file-template.md`、`declaration-order.md` |
+| 排版 | 只改缩进、行宽、包含顺序或格式 | 第 3 步的声明写法，或 `building-cpp` 的「定工具配置」 | `references/google-cpp-style.md`、`layout.md` |
+| 润色 | 只改命名、只改注释措辞 | 第 3、4 步 | `references/naming.md`、`comments.md` |
+
+只改格式时不动行为，只改注释时不动签名；类型注释的职责、跨文件边界与线程规则，只按 `references/comments.md` 的条文取内容。
 
 ## 完成判据
 
@@ -41,4 +54,5 @@ metadata:
 - 第 2 步的库 target 不依赖终端、GUI 或脚本；程序 target 只做装配和输入输出；共享抽象有第二个真实使用方。
 - 第 3 步的公共头文件自包含，命名、声明顺序和异常声明符合 `references/` 的条文。
 - 第 4 步的实现只兑现声明；资源由 RAII 管理；失败是正常结果时用返回值，函数无法完成任务时抛异常，不拿异常做正常分支。
+- 源码注释符合 `references/comments.md` 的四层规范，`node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>` 无输出。
 - 没有改 `CMakeLists.txt`、`.clang-*`、构建脚本，也没有把外部资料路径或项目专属类名写进通用条文。