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

package/README.en.md

@@ -2,29 +2,30 @@
 
 [中文](README.md)
 
-Two skills for C++11–C++23 source and build work; new projects default to C++23. The plugin registers a skill provider only; it does not register tools, compile, download a toolchain, or write project files.
+Three skills for C++11–C++23 source, CMake, and build work; new projects default to C++23. The plugin registers a skill provider only; it does not register tools, compile, download a toolchain, or write project files.
 
 ## What it provides
 
 | 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 |
-| `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 |
+| `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 |
+| `configuring-cmake` | Targets, modules, checks; CMakeLists.txt, `cmake/` functions and modules, target properties, C++11–C++23 standards, 2-space layout | The change touches CMake targets, standards, link boundaries, functions, or modules |
+| `building-cpp` | Build setup, tool configuration, checks; Ninja, Clang config, build scripts, environment combinations, formatting, and static analysis | The change touches build commands, 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.
+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. All three skills read the project skill `cpp-workflow-project` first. Without it, the workspace gate never exposes these names.
 
 ## Install
 
 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.5.0
 ```
 
 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.5.0
 ```
 
 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.
@@ -35,7 +36,7 @@ Only one condition must hold before either skill appears: walking up from the cu
 
 The project skill marker is the repository's opt-in declaration. The plugin no longer requires a first-party `CMakeLists.txt` or C++ source file in the same repository: a docs-only repository, a repository that only copied the template, or a repository with no source files yet still matches; with an empty environment axis, the four source steps still work but build setup stops. Without the marker the list is empty, even when the repository contains CMake or `.cpp` files. Scan limits and boundary cases are in [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md).
 
-The packaged skills use rank 550. A project `.agents/skills` skill uses rank 200 and overrides a plugin skill with the same name; do not copy `developing-cpp` or `building-cpp` into a project.
+The packaged skills use rank 550. A project `.agents/skills` skill uses rank 200 and overrides a plugin skill with the same name; do not copy `developing-cpp`, `configuring-cmake`, or `building-cpp` into a project.
 
 ## Project conventions
 
@@ -57,7 +58,7 @@ Keep one `environment.json` per repository. Its first three environment axes are
 | `compiler` | `clang`, `gcc` | One compiler per configuration |
 | `standard` | `c++11`, `c++14`, `c++17`, `c++20`, `c++23` | New projects default to `c++23`; one standard per project |
 
-The standard lives in `environment.json` as `standard` and must match the CMake target and compile database. New projects default to C++23; for C++11–C++20, lower `standard`, `cxx_std_*`, `CXX_STANDARD`, and the `.clang-format` parsing level together, not one at a time. Per-standard facilities, tooling, and downgrade tables are in the [standard directory](skills/building-cpp/references/standards/README.md).
+The standard lives in `environment.json` as `standard` and must match the CMake target and compile database; on the CMake side, prefer `configuring-cmake`'s `CompileSettings_SetCxxStandard` function. New projects default to C++23; for C++11–C++20, lower `standard`, `cxx_std_*`, `CXX_STANDARD`, and the `.clang-format` parsing level together, not one at a time. Per-standard facilities, tooling, and downgrade tables are in the [standard directory](skills/building-cpp/references/standards/README.md); the CMake two-layer declaration is in [cxx-standard.md](skills/configuring-cmake/references/cxx-standard.md).
 
 The generator is always Ninja. Build directories are `build/clang/` and `build/gcc/`; they are never shared. Analysis tools are always `clang-format`, `clang-tidy`, and `clangd`; GCC mode does not switch to another analyzer.
 
@@ -77,7 +78,7 @@ The project root carries only `.vscode/extensions.json` and `settings.json`: cla
 ```text
 dsh-cpp-workflow/
 ├── lib/                 # build output, shipped in the npm package
-├── skills/              # developing-cpp and building-cpp
+├── skills/              # developing-cpp, configuring-cmake, and building-cpp
 ├── templates/           # empty project template to copy
 ├── package.json
 ├── package-lock.json    # repository only, used by npm ci
@@ -89,7 +90,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 +100,7 @@ Requires Node.js 22 or newer.
 
 ```bash
 npm ci
-npm test              # build, structural check, gate/environment/schema tests
+npm test              # build, three-skill 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

@@ -2,29 +2,30 @@
 
 [English](README.en.md)
 
-把 C++11–C++23 的源码工作和构建工作收成两个技能，新工程默认 C++23。插件只注册技能 provider，不注册工具、不编译、不下载工具链、不写项目文件。
+把 C++11–C++23 的源码、CMake 与构建工作收成三个技能，新工程默认 C++23。插件只注册技能 provider，不注册工具、不编译、不下载工具链、不写项目文件。
 
 ## 提供什么
 
 | 技能 | 管什么 | 什么时候打开 |
 | --- | --- | --- |
-| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
-| `building-cpp` | 定构建、定工具配置、通过检查；CMake、Ninja、Clang 配置、构建脚本和环境组合 | 改动落在构建文件、工具配置或环境声明上，或第一次接构建 |
+| `developing-cpp` | 定行为、定边界、定声明、定实现；`.h` / `.cpp` / `.cc` 的命名、异常和源码注释 | 用户点名源码，或需要新建/整段重构源码 |
+| `configuring-cmake` | 定 target、定模块、通过检查；CMakeLists.txt、`cmake/` 函数与模块、target 属性、C++11–C++23 标准、2 空格排版 | 改动落在 CMake target、标准、链接边界、函数或模块上 |
+| `building-cpp` | 定构建、定工具配置、通过检查；Ninja、Clang 配置、构建脚本、环境组合、格式化与静态检查 | 改动落在构建命令、工具配置或环境声明上，或第一次接构建 |
 
-异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。两个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这两个名字。
+异常条文采用 C++ Core Guidelines 的 Error handling，只在开发阶段指导源码和示例；插件运行时不编译、不执行这些规则。三个技能都先读项目技能 `cpp-workflow-project`。没有项目技能时，门禁不会放出这三个名字。
 
 ## 安装
 
 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.5.0
 ```
 
 同版本的 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.5.0
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。
@@ -35,7 +36,7 @@ dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.0
 
 项目技能标记就是仓库选择加入本工作流的声明。插件不再要求同一仓库里已经有第一方 `CMakeLists.txt` 或 C++ 源文件：纯文档仓库、只复制了模板、还没有任何源文件的仓库也会出现；环境轴为空时，源码四步仍能做，但定构建会停。没有标记就返回空列表，即使仓库里有 CMake 或 `.cpp`。扫描上限和边界情形见 [docs/plugin-boundaries.md](https://github.com/chengzhao-dev/dsh-cpp-workflow/blob/main/docs/plugin-boundaries.md)。
 
-插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200，会以同名覆盖插件；不要在项目里复制 `developing-cpp` 或 `building-cpp`。
+插件技能 rank 550。项目自己的 `.agents/skills` 技能 rank 200，会以同名覆盖插件；不要在项目里复制 `developing-cpp`、`configuring-cmake` 或 `building-cpp`。
 
 ## 项目级约定
 
@@ -57,7 +58,7 @@ dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.0
 | `compiler` | `clang`、`gcc` | 一次配置一个编译器 |
 | `standard` | `c++11`、`c++14`、`c++17`、`c++20`、`c++23` | 新工程默认 `c++23`；一个工程一个标准 |
 
-标准写在 `environment.json` 的 `standard`，并同步到 CMake target 和编译数据库。新工程默认 C++23；C++11–C++20 工程把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降级，不要只改一处。每档的设施、工具和降档表见 [标准目录](skills/building-cpp/references/standards/README.md)。
+标准写在 `environment.json` 的 `standard`，并同步到 CMake target 和编译数据库；CMake 侧优先调用 `configuring-cmake` 提供的 `CompileSettings_SetCxxStandard` 函数。新工程默认 C++23；C++11–C++20 工程把 `standard`、`cxx_std_*`、`CXX_STANDARD` 和 `.clang-format` 的解析档位一起降级，不要只改一处。每档的设施、工具和降档表见 [标准目录](skills/building-cpp/references/standards/README.md)，CMake 两层声明见 [cxx-standard.md](skills/configuring-cmake/references/cxx-standard.md)。
 
 生成器固定 Ninja，构建目录是 `build/clang/` 与 `build/gcc/`，不共用 `build/`。诊断工具固定 `clang-format`、`clang-tidy`、`clangd`；GCC 模式也不换成别的分析器。
 
@@ -77,7 +78,7 @@ node "<skill-dir>/scripts/checking-environment.mjs" --project . --live
 ```text
 dsh-cpp-workflow/
 ├── lib/                 # 构建产物，随 npm 包发布
-├── skills/              # developing-cpp 与 building-cpp
+├── skills/              # developing-cpp、configuring-cmake 与 building-cpp
 ├── templates/           # 复制到项目的空模板
 ├── package.json
 ├── package-lock.json    # 只在仓库，供 npm ci
@@ -89,7 +90,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 +100,7 @@ dsh-cpp-workflow/
 
 ```bash
 npm ci
-npm test              # 构建、结构检查、门禁/环境/schema 测试
+npm test              # 构建、三技能结构检查、门禁/环境/schema/注释测试
 npm run test:matrix   # 四套模板 × 五档标准的真实构建矩阵
 npm run pack:check    # 核对 npm 包内容
 ```

package/lib/index.js

@@ -1,6 +1,6 @@
 // dsh-cpp-workflow bundle entry.
 //
-// Registers the two packaged skills as one bundle-scoped skill provider. The
+// Registers the three packaged skills as one bundle-scoped skill provider. The
 // provider is read-only and scans only `skills/<name>/SKILL.md`; each skill
 // directory becomes the resourceBase so relative steps, references, examples
 // and assets resolve from the installed package.
@@ -15,8 +15,8 @@
 //
 // Rank 550 is lower priority than project/user skills (project `.agents/skills`
 // 200, user `.agents/skills` 500) and higher priority than the bundled root
-// (600), so a project can override either skill by name without editing the
-// package. The project skill itself (cpp-workflow-project, rank 200) is a
+// (600), so a project can override any packaged skill by name without editing
+// the package. The project skill itself (cpp-workflow-project, rank 200) is a
 // separate name and does not collide.
 import { readdir, readFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -26,7 +26,7 @@ export const name = 'dsh-cpp-workflow';
 export const inject = ['skills'];
 const PROVIDER = 'dsh-cpp-workflow';
 const RANK = 550;
-const KNOWN_SKILLS = new Set(['building-cpp', 'developing-cpp']);
+const KNOWN_SKILLS = new Set(['building-cpp', 'configuring-cmake', 'developing-cpp']);
 const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 const PACKAGE_ROOT = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
 const SKILLS_ROOT = path.join(PACKAGE_ROOT, 'skills');

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/locale/en.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ Workflow",
-    "description": "Four source steps and three build steps for C++11–C++23 projects (C++23 by default), checked against the environment the project declares."
+    "description": "Four source steps, three CMake steps, and three build steps for C++11–C++23 projects (C++23 by default), checked against the environment the project declares."
   }
 }

package/locale/zh.json

@@ -1,6 +1,6 @@
 {
   "meta": {
     "title": "C++ 工程流程",
-    "description": "用源码四步与构建三步推进 C++11–C++23 工程（默认 C++23），并在项目声明的环境组合里核对构建与 clang 工具链。"
+    "description": "用源码四步、CMake 三步与构建三步推进 C++11–C++23 工程（默认 C++23），并在项目声明的环境组合里核对构建与 clang 工具链。"
   }
 }

package/package.json

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

package/skills/building-cpp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: building-cpp
-description: 用 CMake、Ninja、clang-format、clang-tidy、clangd 配置、构建和检查 C++11–C++23 工程时使用；新工程默认 C++23；按定构建、定工具配置、通过检查三步推进。一次改动同时碰到源码和构建文件时，先打开 developing-cpp。不用于只改源码语义、文档、Python 或与 C++ 无关的文件。
+description: 在已经写好 CMake 的 C++11–C++23 工程上配置、构建和检查时使用：Ninja、compile_commands.json、clang-format、clang-tidy、clangd、environment.json 与 running-build.sh；按定构建、定工具配置、通过检查三步推进。要编写或重构 CMakeLists.txt / cmake 模块时先开 configuring-cmake。一次改动同时碰到源码和构建文件时，先打开 developing-cpp。不用于只改源码语义、文档、Python 或与 C++ 无关的文件。
 metadata:
   short-description: C++11–C++23 构建三步
 ---
@@ -9,38 +9,51 @@ metadata:
 
 ## 适用场景
 
-管 `CMakeLists.txt`、`cmake/`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/` 和 `environment.json`。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。一次改动同时碰到源码和构建文件时，先打开 `developing-cpp`：只改函数体、命名、异常或注释且入口命令可运行时，定实现后直接到本技能的通过检查；新增或移动源文件、改库与程序的边界、补测试 target 时，到本技能先做定构建，把文件写进 CMake，再决定是否定工具配置，最后通过检查。`.qmd`、仓库 README、Python 和非 C++ 文档不打开本技能。
+管 `environment.json`、`running-build.sh`、`.clang-format`、`.clang-tidy`、`.clangd`、`.vscode/`、构建命令、编译数据库、CTest 和运行。`CMakeLists.txt` 与 `cmake/` 下的 target、属性、标准和模块由 `configuring-cmake` 负责；本技能只读它们来配置和检查，不在这一步改 target 图。函数体、类型、命名、异常和源码注释只开 `developing-cpp`。
 
-编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断指向声明或类型，回定声明；诊断是找不到头、链接失败、没有编译数据库或工具不在 PATH，留在本技能的定构建或定工具配置。
+一次改动同时碰到源码和构建文件时，先打开 `developing-cpp` 定行为、边界与实现；需要新增或移动源文件、改库与程序的边界、补测试 target 时，转到 `configuring-cmake` 把文件写进 CMake；最后回到本技能做定工具配置与通过检查。只改函数体、命名、异常或注释且入口命令可运行时，定实现后只开本技能的「通过检查」。
 
-源码和构建文件用 UTF-8 无 BOM、检出 LF；`.bat` / `.cmd` 用 CRLF；`.clang-format` 写 `LineEnding: LF`。MSVC 原生构建优先加 `/utf-8`，不要靠 BOM 过关。完整规则见 `references/encoding.md`，检查脚本是 `scripts/checking-encoding.mjs`，机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准。
+存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。三个环境轴为空、`standard` 非法或组合非法时停在定构建，不猜 WSL、Clang 或构建目录；`windows` + `native` 直接拒绝，提示「本版本不能在 Windows 原生壳里构建」，不要给出补 PowerShell 的路线。
+
+编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断是找不到头、链接失败、target 不存在或标准不对，转 `configuring-cmake` 的对应步骤；诊断是没有编译数据库、format/tidy 不在 PATH 或配置不生效，留在本技能的定工具配置。
 
-存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`、`environment.json` 和 `stages/stage-table.md`。三个环境轴为空、`standard` 非法或组合非法时停在定构建，不猜 WSL、Clang 或构建目录；`windows` + `native` 直接拒绝，提示「本版本不能在 Windows 原生壳里构建」，不要给出补 PowerShell 的路线。环境组合空着时源码四步仍可做，只是不能构建。
+源码和构建文件用 UTF-8 无 BOM、检出 LF；`.bat` / `.cmd` 用 CRLF；`.clang-format` 写 `LineEnding: LF`。MSVC 原生构建优先加 `/utf-8`，不要靠 BOM 过关。完整规则见 `references/encoding.md`，检查脚本是 `scripts/checking-encoding.mjs`，机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准。
 
 ## 两种走法
 
 | 走法 | 什么时候用 | 怎么做 |
 | --- | --- | --- |
-| 增量修正 | 用户点了一条链接错误、一个工具配置或一条诊断 | 先判断属于定构建还是定工具配置，只改那一处，不动无关 target 和配置 |
-| 整段重构 | 新工程、新阶段、换环境组合，或第一次接构建 | 同样三步；先定 target 和目录，再改工具文件，最后跑完整检查 |
+| 增量修正 | 用户点了一条工具配置、一条诊断或一个入口脚本错误 | 先判断属于定构建还是定工具配置，只改那一处，不动无关 target 和配置 |
+| 整段重构 | 新工程、新阶段、换环境组合，或第一次接构建 | 同样三步；先确认 target 与标准已由 configuring-cmake 写好，再改工具文件，最后跑完整检查 |
 
-共同不变量：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器或构建目录需要改，退回整段，从定构建重走。
+共同不变量：不发明项目没有声明的环境轴、命令和 target；只改格式或配置时不改可观察行为；不覆盖已有源码、`CMakeLists.txt` 和 `.clang-*`；不安装工具链；代理侧不写 `wsl` 或 `bash -lc`。后一步发现前一步没做完，退回那一步。拿不准先用增量修正；发现环境轴、编译器、构建目录或 target 契约需要改，退回整段，并转 `configuring-cmake`。
 
 ## 步骤
 
 | 步 | 名称 | 文件 | 一句话 |
 | --- | --- | --- | --- |
-| 1 | 定构建 | `steps/01-build.md` | 一次配置一个编译器，Ninja，target-based CMake，编译数据库 |
+| 1 | 定构建 | `steps/01-build.md` | 读环境声明，固定 Ninja 与单一编译器，产出编译数据库 |
 | 2 | 定工具配置 | `steps/02-tooling.md` | 格式化、静态检查、clangd 各管一段，互不越界 |
-| 3 | 通过检查 | `steps/03-check.md` | 先跑环境脚本的 `--live`，再跑项目入口，按失败位置分诊 |
+| 3 | 通过检查 | `steps/03-check.md` | 按编码 → 声明校验 → 活动校验 → 项目入口的次序跑，前一步失败就停 |
+
+每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。链接、rpath 与产物布局读 `references/linking.md`；CMake 的 target、标准和函数写法读 `../configuring-cmake/references/`，可复用片段在 `../configuring-cmake/assets/cmake/`。
 
-每步只打开同号的一个步骤文件。判不准才打开 `examples/` 里与该步对应的案例；`references/` 保存完整条文，只在排错、整目录重构，或步骤里明确指向某一条文时按需打开。
+### 四类改动
+
+先认这次改的是哪一类，再决定从哪一步进；一次改动混了两类时，按「写作 → 布局 → 排版 → 润色」的次序拆开做。
+
+| 类型 | 典型请求 | 从哪进 | 先读哪份条文 |
+| --- | --- | --- | --- |
+| 写作 | 改环境轴、入口脚本或构建流程 | 第 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` |
 
 ## 完成判据
 
 - 项目 `environment.json` 的三个环境轴齐全且是合法组合，`standard` 在 `c++11`–`c++23` 内；新工程默认 `c++23`，没有靠猜。
 - 配置命令固定 Ninja 和单一编译器，`build/<compiler>/compile_commands.json` 存在，根 `build/compile_commands.json` 指向当前编译器。
-- 标准写在 target 上（`CXX_STANDARD` + `CXX_STANDARD_REQUIRED ON` + `cxx_std_*`），`CXX_EXTENSIONS OFF`；`compile_commands.json` 的实际 `-std` 与 `environment.json` 一致，没有全局 `include_directories()` 或 GLOB。
+- target 契约已经成立：程序 `app`、库 target、公共 include、标准与输出目录都已由 `configuring-cmake` 写好；本技能没有偷偷改 CMake 来绕过失败。
 - `clang-format --dry-run --Werror` 与 `clang-tidy` 在项目源码上零告警；只扫描项目源码和项目头。
 - CTest 全绿，程序从该编译器的构建目录启动；失败时报告的是具体角色和原因。
 - 没有改源码语义，没有覆盖已有工程文件，也没有安装或下载任何工具。

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/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/build-script.md

@@ -40,6 +40,17 @@
 - 失败时保留原始命令输出；不要在脚本里 `2>/dev/null` 吞掉诊断。
 - 脚本自身用 `bash -n` 检查语法；文件权限保持可执行。
 
+## 构建模式的错误合同
+
+脚本可以为 Debug、Release 各跑一次；模式只改变诊断详略，不改变失败方式：
+
+- 返回值：两种模式的返回值相同，调用方不按 `NDEBUG` 分支。
+- 自定义异常：两种模式都抛；Debug 的 `what()` 可以带 `file:line`，Release 只留值。
+- `Check`：两种模式都在条件不成立时打印诊断并终止。
+- `DebugCheck`：只在 Debug 生效，`NDEBUG` 后展开为空，参数不能带副作用。
+
+不要写成 Debug 抛异常、Release 返回 false 的模式分支；这会把调用方逼成两套逻辑。规则详见 `developing-cpp/references/exceptions.md`。
+
 ## 失败分诊
 
 | 输出 | 先看 | 回到 |

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`，实例化点看不到 | 模板定义移到头文件，或显式实例化 |
 | 静态库中的目标文件没被拉入 | 链接器只取被引用符号所在的目标文件 | 确认符号确实被引用，或改用对象库/共享库 |
 
 先看链接器报的完整符号名和来源文件，不要只看第一行。
@@ -65,7 +65,7 @@ build/<compiler>/
 - 运行时动态加载器默认不搜索可执行文件旁边的 `lib/`；需要 RPATH：
   - Linux：`-Wl,-rpath,'$ORIGIN/../lib'`
   - macOS：`-Wl,-rpath,@loader_path/../lib`
-- CMake 用 `BUILD_RPATH` / `INSTALL_RPATH` 设置，不要手工拼链接命令；见 `assets/cmake/setting-rpath.cmake`。
+- CMake 用 `BUILD_RPATH` / `INSTALL_RPATH` 设置，不要手工拼链接命令；见 [`LinkSettings.cmake`](../../configuring-cmake/assets/cmake/LinkSettings.cmake)。
 - RPATH 里的 `$ORIGIN` 要防止被 shell 展开：CMake 字符串里写 `\$ORIGIN` 或使用 `BUILD_RPATH_USE_ORIGIN`。
 
 ## 验收：`file` 与 `ldd`

package/skills/building-cpp/references/standards/README.md

@@ -160,6 +160,6 @@ target_link_options(app PRIVATE -stdlib=libc++)
 ## 相关文件
 
 - [environment.md](../environment.md)：四轴声明与校验。
-- [cmake.md](../cmake.md)：CMake 形状与排版。
+- [configuring-cmake/references/cxx-standard.md](../../../configuring-cmake/references/cxx-standard.md)：C++11–C++23 在 CMake 里的两层声明与验证。
 - [static-analysis.md](../static-analysis.md)：clang-format / clang-tidy / clangd 分工。
 - [01-build.md](../../steps/01-build.md)：定构建步骤。

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` 的诊断可能指向头文件；修头文件里的声明或实现，不要只改调用点。