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

package/README.en.md

@@ -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.2.0
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.3.0
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.2.0
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.3.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.

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "C++11–C++23 工程流程技能包：源码四步与构建三步，按项目声明的环境组合校验 · C++11–C++23 workflow skills for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -42,7 +42,8 @@
   "icon": "./icon.svg",
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "npm run build && node scripts/checking-skill-links.mjs && node --test tests/*.test.mjs",
+    "test": "npm run build && node scripts/checking-skill-links.mjs && node skills/building-cpp/scripts/checking-encoding.mjs --quiet && node --test tests/*.test.mjs",
+    "check:encoding": "node skills/building-cpp/scripts/checking-encoding.mjs",
     "test:matrix": "bash scripts/checking-standard-matrix.sh",
     "pack:check": "npm pack --dry-run"
   },

package/skills/building-cpp/SKILL.md

@@ -13,6 +13,8 @@ metadata:
 
 编译失败先分因：诊断指向函数体，回 `developing-cpp` 的定实现；诊断指向声明或类型，回定声明；诊断是找不到头、链接失败、没有编译数据库或工具不在 PATH，留在本技能的定构建或定工具配置。
 
+源码和构建文件用 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 的路线。环境组合空着时源码四步仍可做，只是不能构建。
 
 ## 两种走法

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

@@ -3,3 +3,5 @@
 Language: Cpp
 BasedOnStyle: Google
 Standard: Latest
+# 与根 .gitattributes 和 .editorconfig 同档：格式化不把行尾改回 CRLF。
+LineEnding: LF

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

@@ -0,0 +1,49 @@
+# 编码与行尾
+
+默认组合是 UTF-8 无 BOM、LF。机器规则以仓库根 `.gitattributes` 与 `.editorconfig` 为准，本文件只记决定、MSVC 例外与检查方法。
+
+## 规则
+
+- 文本文件用 UTF-8，不带 BOM。JSON 按 RFC 8259；YAML 按 YAML 1.2.2；不要 GBK、UTF-16 或 Latin-1。
+- 所有文本文件用 LF，包括 `.sh`、Python、C++、Markdown、YAML、CMake 和配置文件。
+- `.sh` 必须 LF：内核会把 shebang 末尾的 CR 当作解释器路径的一部分，导致 `bad interpreter`。
+- `.bat` / `.cmd` 必须 CRLF：`cmd.exe` 对纯 LF 批处理不稳定。
+- 每个文本文件末尾一个换行；文件中间不混用 LF 和 CRLF。
+- 二进制文件（字体、图片）不转码，按 `binary` 处理。
+
+## MSVC 原生
+
+MSVC 默认按 BOM 判断源码编码。源码没有 BOM 时，它按当前用户代码页解释，除非显式传入 `/utf-8` 或 `/source-charset:utf-8`。因此 BOM 不是 MSVC 的硬要求。
+
+- 首选做法是加编译选项：在目标上写 `target_compile_options(<target> PRIVATE $<$<CXX_COMPILER_ID:MSVC>:/utf-8>)`，源码继续 UTF-8 无 BOM、LF。
+- 只有在无法改编译选项时，才把 MSVC 编译的 C/C++ 源文件保存为 UTF-8 BOM。BOM 只允许出现在这类源文件里。
+- `.sh`、`.bat`、`.cmd`、`.json`、`.yml`、`.gitattributes`、`.editorconfig` 和 CMake 文件不要加 BOM。
+- MSVC 接受 LF 源码；CRLF 不是必需项。只有 `.bat` / `.cmd` 固定 CRLF。
+- WSL 与 Linux 构建按默认组合，不要把源码转成 CRLF 来迁就 Windows。
+
+## 工具
+
+- `.gitattributes` 决定 Git 入库和检出；它覆盖贡献者自己的 `core.autocrlf`。
+- `.editorconfig` 决定编辑器保存；`charset` 与 `end_of_line` 必须和 `.gitattributes` 同一档。
+- `.clang-format` 写 `LineEnding: LF`，避免格式化把行尾改回 CRLF。
+
+## 检查
+
+在仓库根运行：
+
+```bash
+node "<skill-dir>/scripts/checking-encoding.mjs" --profile portable
+```
+
+- `portable`（默认）要求所有文本文件 UTF-8 无 BOM、LF、末尾换行。
+- `msvc` 只放宽 MSVC 编译的 C/C++ 源文件：允许 UTF-8 BOM 与 CRLF；Markdown、配置与脚本仍按 `portable` 检查。
+- 退出码：0 无问题，1 有问题，2 参数或 Git 错误。加 `--json` 输出机器可读结果。
+
+再跑 `git diff --check`，确认没有空白错误。不要用 `git add --renormalize` 把行尾改动混进功能改动；确需规范化时单独提交并说明。
+
+## 依据
+
+- MSVC `/utf-8`：<https://learn.microsoft.com/en-us/cpp/build/reference/utf-8-set-source-and-executable-character-sets-to-utf-8?view=msvc-170>
+- MSVC `/source-charset`：<https://learn.microsoft.com/en-us/cpp/build/reference/source-charset-set-source-character-set?view=msvc-170>
+- Unicode UTF-8 BOM FAQ：<https://www.unicode.org/faq/utf_bom.html>
+- Git `.gitattributes`：<https://git-scm.com/docs/gitattributes>

package/skills/building-cpp/references/standards/c++23/README.md

@@ -43,7 +43,7 @@
 
 ## 降档/升级
 
-从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见[标准索引](../README.md#新增标准)。
+从 C++23 降到 C++20 见 [C++20 档案](../c++20/README.md)。升级到 C++26 前先确认 CMake 3.25+、编译器/标准库支持、clang-format 的 `c++26` 枚举；新增目录流程见 [标准索引](../README.md#新增标准)。
 
 ## 验证
 

package/skills/building-cpp/scripts/checking-encoding.mjs

@@ -0,0 +1,241 @@
+#!/usr/bin/env node
+// Read-only encoding audit for a Git work tree.
+//
+// Default profile "portable" is the cross-platform baseline: UTF-8 without BOM,
+// LF line endings, one final newline. Profile "msvc" allows a UTF-8 BOM and CRLF
+// only for MSVC-compiled C/C++ sources; Markdown, CMake, scripts and configs stay
+// portable. It never rewrites files.
+//
+// Usage:
+//   node checking-encoding.mjs [--root DIR] [--profile portable|msvc] [--json] [--quiet]
+//
+// Exit codes: 0 clean, 1 issues found, 2 usage or Git error.
+import { execFileSync } from 'node:child_process'
+import { existsSync, readFileSync, statSync } from 'node:fs'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+export const EXIT = { ok: 0, issues: 1, usage: 2 }
+
+const UTF8_BOM = [0xef, 0xbb, 0xbf]
+const UTF16_LE = [0xff, 0xfe]
+const UTF16_BE = [0xfe, 0xff]
+const UTF32_LE = [0xff, 0xfe, 0x00, 0x00]
+const UTF32_BE = [0x00, 0x00, 0xfe, 0xff]
+
+const CRLF_REQUIRED = new Set(['.bat', '.cmd'])
+const MSVC_SOURCE = new Set([
+  '.c', '.cc', '.cpp', '.cxx', '.h', '.hh', '.hpp', '.hxx', '.inl', '.ixx', '.cppm', '.rc',
+])
+const ALWAYS_LF = new Set([
+  '.md', '.qmd', '.txt', '.rst', '.yml', '.yaml', '.json', '.jsonc', '.json5', '.toml',
+  '.ini', '.cfg', '.conf', '.sh', '.bash', '.zsh', '.fish', '.ps1', '.py', '.mjs', '.cjs',
+  '.js', '.jsx', '.ts', '.tsx', '.css', '.scss', '.sass', '.less', '.html', '.htm', '.xml',
+  '.svg', '.cmake', '.lua', '.sql', '.gitignore', '.gitattributes', '.editorconfig',
+])
+const NO_EXTENSION_LF = new Set(['CMakeLists.txt', 'Makefile', 'Justfile', 'Dockerfile', 'LICENSE'])
+
+function usage(message) {
+  if (message) process.stderr.write(`错误：${message}\n`)
+  process.stderr.write('用法：node checking-encoding.mjs [--root DIR] [--profile portable|msvc] [--json] [--quiet]\n')
+  return EXIT.usage
+}
+
+function parseArgs(argv) {
+  const options = { root: undefined, profile: 'portable', json: false, quiet: false }
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index]
+    if (arg === '--root') {
+      options.root = argv[index + 1]
+      index += 1
+    } else if (arg === '--profile') {
+      options.profile = argv[index + 1]
+      index += 1
+    } else if (arg === '--json') {
+      options.json = true
+    } else if (arg === '--quiet') {
+      options.quiet = true
+    } else if (arg === '--help' || arg === '-h') {
+      options.help = true
+    } else {
+      throw new Error(`未知参数 ${arg}`)
+    }
+  }
+  if (options.profile !== 'portable' && options.profile !== 'msvc') {
+    throw new Error(`--profile 只能是 portable 或 msvc，收到 ${options.profile}`)
+  }
+  return options
+}
+
+function gitRoot(from) {
+  try {
+    return execFileSync('git', ['-C', from, 'rev-parse', '--show-toplevel'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim()
+  } catch {
+    return undefined
+  }
+}
+
+function listFiles(root) {
+  const output = execFileSync('git', ['-C', root, 'ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+    encoding: 'utf8',
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  return output
+    .split('\0')
+    .filter(Boolean)
+    .map((item) => path.join(root, item))
+    .filter((file) => {
+      try {
+        return statSync(file).isFile()
+      } catch {
+        return false
+      }
+    })
+}
+
+function startsWith(buffer, bytes) {
+  return bytes.every((byte, index) => buffer[index] === byte)
+}
+
+function bomOf(buffer) {
+  if (startsWith(buffer, UTF32_LE)) return 'UTF-32 LE'
+  if (startsWith(buffer, UTF32_BE)) return 'UTF-32 BE'
+  if (startsWith(buffer, UTF8_BOM)) return 'UTF-8'
+  if (startsWith(buffer, UTF16_LE)) return 'UTF-16 LE'
+  if (startsWith(buffer, UTF16_BE)) return 'UTF-16 BE'
+  return undefined
+}
+
+function isBinary(buffer) {
+  const limit = Math.min(buffer.length, 8192)
+  for (let index = 0; index < limit; index += 1) {
+    if (buffer[index] === 0) return true
+  }
+  return false
+}
+
+function inspect(file, root, profile) {
+  const rel = path.relative(root, file).split(path.sep).join('/')
+  const extension = path.extname(file).toLowerCase()
+  const source = MSVC_SOURCE.has(extension)
+  const alwaysLf = ALWAYS_LF.has(extension) || NO_EXTENSION_LF.has(path.basename(file))
+  const issues = []
+  const add = (kind, message) => issues.push({ path: rel, kind, message })
+
+  let buffer
+  try {
+    buffer = readFileSync(file)
+  } catch (error) {
+    add('read', `无法读取（${error.message}）`)
+    return { rel, issues }
+  }
+
+  const bom = bomOf(buffer)
+  if (bom === 'UTF-8') {
+    if (profile !== 'msvc' || !source) {
+      add('bom', profile === 'msvc' && !source ? '只有 MSVC 编译的 C/C++ 源码可以带 BOM' : '不应带 BOM')
+    }
+  } else if (bom) {
+    add('bom', `发现 ${bom} BOM；只接受 UTF-8`)
+  }
+
+  if (bom && bom !== 'UTF-8') {
+    return { rel, issues }
+  }
+  if (isBinary(buffer)) {
+    return { rel, issues }
+  }
+
+  let text
+  try {
+    text = new TextDecoder('utf-8', { fatal: true }).decode(buffer)
+  } catch {
+    add('utf8', '不是合法 UTF-8')
+    return { rel, issues }
+  }
+
+  const body = text.startsWith('\uFEFF') ? text.slice(1) : text
+  if (body.includes('\uFEFF')) {
+    add('bom', '文件中间含 U+FEFF')
+  }
+
+  if (buffer.length > 0 && !body.endsWith('\n')) {
+    add('newline', '缺少末尾换行')
+  }
+
+  const crlf = (body.match(/\r\n/g) ?? []).length
+  const lf = (body.match(/(?<!\r)\n/g) ?? []).length
+  const cr = (body.match(/\r(?!\n)/g) ?? []).length
+
+  if (CRLF_REQUIRED.has(extension)) {
+    if (crlf === 0 || lf > 0 || cr > 0) add('eol', '应为 CRLF')
+  } else if (profile === 'msvc' && source && !alwaysLf) {
+    if ((crlf > 0 && lf > 0) || cr > 0) add('eol', '不要混用 CRLF 与 LF')
+  } else if (crlf > 0 || cr > 0) {
+    add('eol', '应为 LF')
+  }
+
+  return { rel, issues }
+}
+
+export function checkEncoding(root, profile = 'portable') {
+  const files = listFiles(root)
+  const results = []
+  for (const file of files) {
+    results.push(inspect(file, root, profile))
+  }
+  const issues = results.flatMap((result) => result.issues)
+  const counts = { files: results.length, issues: issues.length, bom: 0, eol: 0, utf8: 0, newline: 0, read: 0 }
+  for (const issue of issues) counts[issue.kind] = (counts[issue.kind] ?? 0) + 1
+  return { root, profile, files: results.length, issues, counts }
+}
+
+function main() {
+  let options
+  try {
+    options = parseArgs(process.argv.slice(2))
+  } catch (error) {
+    return usage(error.message)
+  }
+  if (options.help) {
+    process.stdout.write('检查 Git 工作树的 UTF-8/BOM、行尾与末尾换行；默认 portable。\n')
+    return EXIT.ok
+  }
+
+  const base = options.root ? path.resolve(options.root) : process.cwd()
+  if (!existsSync(base)) return usage(`根目录不存在：${base}`)
+  const root = gitRoot(base)
+  if (!root) return usage(`不是 Git 工作树：${base}`)
+
+  let report
+  try {
+    report = checkEncoding(root, options.profile)
+  } catch (error) {
+    process.stderr.write(`错误：${error.message}\n`)
+    return EXIT.usage
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`)
+  } else if (!options.quiet || report.issues.length > 0) {
+    if (report.issues.length === 0) {
+      process.stdout.write(`编码检查：${report.files} 个文件，未发现问题（profile ${report.profile}）。\n`)
+    } else {
+      process.stdout.write(`编码检查：${report.files} 个文件，发现 ${report.issues.length} 个问题（profile ${report.profile}）。\n`)
+      for (const issue of report.issues) {
+        process.stdout.write(`  ${issue.path}: [${issue.kind}] ${issue.message}\n`)
+      }
+      process.stdout.write(
+        `汇总：BOM ${report.counts.bom}，行尾 ${report.counts.eol}，UTF-8 ${report.counts.utf8}，末尾换行 ${report.counts.newline}\n`,
+      )
+    }
+  }
+  return report.issues.length === 0 ? EXIT.ok : EXIT.issues
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  process.exitCode = main()
+}

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

@@ -8,15 +8,17 @@
 
 按固定顺序跑，前一步失败就停，不要带着失败继续：
 
-1. **校验环境声明（不带 `--live`）**：读 `environment.json`，检查三个环境轴、`standard` 和组合是否合法。环境轴为空、`standard` 非法或组合非法时，停在这里，不找可执行文件。
-2. **活动校验**：在声明的 build host 上跑 `--live`，核对 PATH 中的角色和版本。`windows` + `native` 在声明校验阶段就返回失败，不会进入这一步。
-3. **跑项目入口命令**：项目技能里写的入口命令（如 `./running-build.sh clang`）。入口命令仍是 `<entry-command>` 或空白时，停在这里，不要猜命令；是真实命令才跑。入口内部依次 configure → build → format → tidy → ctest → run；每一步失败都保留原始输出。
-4. **核对产物**：`build/<compiler>/compile_commands.json` 存在；`build/compile_commands.json` 指向当前编译器；`app` 可执行文件在 `build/<compiler>/bin`。
-5. **记录结果**：通过时记录编译器版本、构建目录、测试数量；失败时记录命令、退出码、第一条根因诊断。
+1. **校验编码与行尾**：在仓库根跑编码检查。默认 UTF-8 无 BOM、LF；MSVC 原生工程加 `--profile msvc`。有问题先按 `references/encoding.md` 修正，不带着 BOM 或混用行尾继续。
+2. **校验环境声明（不带 `--live`）**：读 `environment.json`，检查三个环境轴、`standard` 和组合是否合法。环境轴为空、`standard` 非法或组合非法时，停在这里，不找可执行文件。
+3. **活动校验**：在声明的 build host 上跑 `--live`，核对 PATH 中的角色和版本。`windows` + `native` 在声明校验阶段就返回失败，不会进入这一步。
+4. **跑项目入口命令**：项目技能里写的入口命令（如 `./running-build.sh clang`）。入口命令仍是 `<entry-command>` 或空白时，停在这里，不要猜命令；是真实命令才跑。入口内部依次 configure → build → format → tidy → ctest → run；每一步失败都保留原始输出。
+5. **核对产物**：`build/<compiler>/compile_commands.json` 存在；`build/compile_commands.json` 指向当前编译器；`app` 可执行文件在 `build/<compiler>/bin`。
+6. **记录结果**：通过时记录编译器版本、构建目录、测试数量；失败时记录命令、退出码、第一条根因诊断。
 
-环境校验脚本：
+编码检查与环境校验脚本：
 
 ```bash
+node "<skill-dir>/scripts/checking-encoding.mjs" --profile portable      # UTF-8 无 BOM、LF
 node "<skill-dir>/scripts/checking-environment.mjs" --project .          # 声明校验
 node "<skill-dir>/scripts/checking-environment.mjs" --project . --live   # 活动校验
 ```

package/skills/developing-cpp/SKILL.md

@@ -13,6 +13,8 @@ metadata:
 
 存在项目技能 `cpp-workflow-project` 时先读它的 `SKILL.md`：工程名、库与程序的边界、阶段表、术语增补、入口命令。没有项目技能时门禁不会放出本技能，不要猜项目约定。
 
+源码和构建文件的编码以 `building-cpp` 的 `references/encoding.md` 为准；行尾与 `.clang-format` 的 `LineEnding` 跟仓库根 `.gitattributes` 和 `.editorconfig`。
+
 ## 两种走法
 
 | 走法 | 什么时候用 | 怎么做 |

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

@@ -231,3 +231,32 @@ return true;
 ```
 
 一段连续的实现注释只讲一个判断或一个取舍；不是逐行字幕。
+
+## 成员还是同一命名空间的函数
+
+**差**：
+
+```cpp
+class TaskTable {
+ public:
+  std::size_t CountOverdue() const;
+  bool HasOverdue() const { return CountOverdue() > 0; }
+};
+```
+
+`HasOverdue` 只组合公开查询，不需要直接访问表示，却做成了成员。
+
+**好**：
+
+```cpp
+class TaskTable {
+ public:
+  std::size_t CountOverdue() const;
+};
+
+bool HasOverdue(const TaskTable& table) {
+  return table.CountOverdue() > 0;
+}
+```
+
+函数和类放在同一命名空间；调用方只看到 `HasOverdue(table)`，类不增加只为转发而存在的成员。

package/skills/developing-cpp/references/comments.md

@@ -117,6 +117,24 @@ Standard: Latest
 - 同一个理由只写一次，不逐项复制。
 - 源码注释不写团队政策或流程；那些属于文档，不属于被阅读的代码。
 
+## 润色次序
+
+只改注释时，仍走第 3 步和第 4 步，然后按这个次序回读：
+
+1. 文件头：这个文件负责什么、不负责什么，6 行以内。
+2. 章节横幅：文件超过约 200 行才分组。
+3. 声明契约：`///` 写参数、返回值、失败方式；与 `references/exceptions.md` 一致。
+4. 成员行尾：先写保存的对象，再写约束。
+5. 实现注释：只写为什么和边界，不翻译下一行。
+6. 配置注释：按 `building-cpp` 的定工具写；只写为什么这样设。
+7. 回读：同一概念一种译法；不把读者章节的句子抄进注释。
+
+## 与读者正文的边界
+
+- 中文、术语稳定、不复述下一行；两边各自写自己的文件。
+- 句长、段落、标点、书根 README 不在本插件。
+- `///`、横幅、`@param` 不进入 qmd、YAML、CSS。
+
 ## 禁止
 
 - 注释里写外部资料路径、项目专属类名或跨仓库引用。

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

@@ -44,6 +44,14 @@
 - 修改器用 `Set` + 属性名（`SetCount()` / `set_count()`）或领域动作（`CompleteTask()`）；同一 API 只选一种，不要用 `SetItem` 这类暴露存储细节的名字。
 - `current_` 前缀只在有多个候选、且「当前」可能混淆时使用：`current_order_`。只有一个当前对象时不要加。
 
+## 谓词与查询命名
+
+- 返回 `bool` 的查询用肯定式，读起来像一句断言：`IsEmpty()`、`HasStock()`、`CanReserve()`、`CompletesLine()`。
+- `Get` 只用于取值，`Set` 只用于设值；不要用 `CheckLine()` 当布尔 getter。
+- `Check` / `Validate` 留给会报告错误、产生诊断或可能失败的操作；它们不返回纯 `bool` 查询。
+- 假设性查询在名字里写明条件：`CompletesLine(position, cell)` 读作「这一手会成线吗」；需要更强语气时用 `WouldCompleteLine()`。同一 API 只选一种，改名时同步声明、定义、调用点、测试和注释。
+- 私有谓词同样用肯定式；不要用 `flag`、`status` 或 `check` 这类不说明判据的名字。
+
 ## 类型命名的判断顺序
 
 1. 纯数据、无 invariant、可以直接聚合初始化 → `struct`，名字是名词：`Order`, `TaskRecord`。

package/skills/developing-cpp/references/project-design.md

@@ -44,6 +44,15 @@
 
 依赖方向从外向内；核心不知道适配层存在。
 
+## 谁回答这个问题
+
+判断一个操作该落在哪个类型，先看回答它需要哪些数据：
+
+- 需要的数据在哪个类型里，就由那个类型回答（Information Expert）。
+- 只有直接碰到内部表示的函数才做成成员；只组合公开查询的函数留在同一命名空间（C.4、C.5）。调用方不另写一份。
+- 例外是虚函数、`=`、`()`、`[]`、`->` 这类必须为成员的运算符，以及同一组重载或链式调用里为了接口一致而留下的函数。使用例外时在声明旁写一句原因。
+- 示例不指向任何仓库的类：一次落子仍由对局类型接收，因为它掌握当前参与者、历史和结果；它不重新计算棋盘已经能回答的占格、成线和终局。棋盘类型不包含参与者类型和结果类型。
+
 ## 边界的划分理由
 
 按“变化原因”划分边界，不按文件数量：

package/skills/developing-cpp/steps/02-boundary.md

@@ -21,6 +21,7 @@ app                            只做参数、输入输出和装配
 - 只有一个可执行文件、没有复用需求时，可以不分库；一旦出现第二个调用方或测试需要直接调用，再拆库。
 - 抽共享库前先确认第二个真实使用方和相同语义；只是“看起来会复用”不构成理由。抽象理由写进项目技能或设计注释。
 - 第 2 步不写 `CMakeLists.txt`。只决定边界，构建 target 留给 `building-cpp` 的定构建。
+- 判断一个查询该成为成员还是同一命名空间的函数时，按 `references/project-design.md` 的「谁回答这个问题」：掌握数据的一方回答，只组合公开查询的函数不升级为成员。
 
 ## 情况
 

package/skills/developing-cpp/steps/03-declaration.md

@@ -7,7 +7,7 @@
 ## 通用情况
 
 - 语言标准由项目声明决定，新工程默认 C++23，支持 C++11–C++23；头文件用 `#define` 守卫，名字由源码树全路径生成。
-- 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`、结构体成员不尾随，常量与枚举子 `k` 前缀。
+- 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`、结构体成员不尾随，常量与枚举子 `k` 前缀。布尔查询与 `Check` 的分工见同文件「谓词与查询命名」。
 - 声明顺序按 `references/declaration-order.md`：类型 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
 - 公共头文件自包含：自身需要的头都直接包含，不依赖调用方的包含顺序。
 - 单参数构造函数写 `explicit`；可查询的成员函数加 `[[nodiscard]]`；默认成员初始化写在声明处，不在构造函数里重复。