docs(style): the test is an interrogative word, not a question mark

Chapter 00's section headings `背景:模块到了,工具链没跟上` and
`谁在为这个落差付账`, and the analogy table's column header
`大致相当于谁的活`, are all colloquial, all violate the register rule, and all
passed check_docs_style.sh. Two independent defects in one check.

THE PREDICATE TESTED A MARKER RATHER THAN THE PROPERTY. It matched `?`, 吗 and
呢 -- the punctuation a question usually carries. The property is the
interrogative word, and neither heading carries the marker.

THE OBJECT SET WAS ENUMERATED SYNTACTICALLY. It read lines beginning with `#`.
The property a heading has -- it names a topic, it is read out of order, it is
what a reader scans -- is held equally by a table's header cells, which were
therefore never examined.

- Chapter 00 rewritten. The scope of a background section is decided by the
  problem, not by the tool: a C++ project needs four things at once and no
  single tool owns all four; CMake is the de facto standard for one of them,
  and a de facto standard is a statement about adoption rather than about the
  experience of use; the environment is the layer that fails most often because
  it is the only one nothing checks. Modules are the fourth constraint on that
  structure rather than the structure.
- 100 headings and 57 column headers become noun phrases, in both languages.
- check_docs_style.sh: the predicate is now the interrogative word set, and a
  fourth rule covers column headers. Chapter 00's title is exempt by name, with
  the reason stated.
- check_docs_structure.sh rule 9 discarded the link fragment, so a link to a
  renamed section resolved to the file and passed. It now computes GitHub's
  slug and verifies the fragment. It immediately reported two anchors in
  chapter 30 that were wrong when they were written.
- The skill records R5 (the scope of a background section), the predicate rule
  and the column-header rule, each with this batch's own sentences as the
  worked example.

Each of the four new checks was falsified before commit: an interrogative
heading with no question mark, a Chinese column header, an English column
header, and an interrogative inside inline code that must not fire.

Author: speak-agent

.agents/skills/mcpp-docs-style/SKILL.md

@@ -95,18 +95,19 @@ docs/specs/    ──▶ docs/              允许
 
 ### 四条产生每个决定的规则
 
-| | 规则 | 它排除了什么 |
+| | 规则 | 排除的形态 |
 |---|---|---|
 | **R1** | **一个主题一个拥有者。** 恰好一章拥有一个主题;其余每一章只写一句话并链接过去 | 同一件事被解释两遍,然后各自过期 |
 | **R2** | **一章为**有任务的读者**而存在,不为**有名字的机制**而存在** | 按机制建目录,于是「测试」「依赖解析」这类**任务**没有家 |
 | **R3** | 每章在**前 15 行**内写明读者、它回答的那一个问题、以及它**排除**什么 | 排除是承重的:它是防止这一章重新吸收 R1 已经分配出去的主题的闸 |
 | **R4** | 一个部分是**某类读者的一段弧**,其内部顺序是那类读者需要它的顺序 | 字母序、按特性发布时间排序 |
+| **R5** | **背景一节的范围由问题决定,不由方案决定。** 先把读者实际面对的那个问题写完整,再写本工具触及其中的哪一部分 | 只写与本工具最近的那一条成因,读者据此以为问题就这么大 |
 
 ### 每章的设计规格
 
 动一章之前,先把这张表填出来。填不出来的那一格,就是还没设计的地方。
 
-| 项 | 要回答什么 |
+| 项 | 填写要求 |
 |---|---|
 | 读者 | 谁在读它。一句话说不出来就是没定位 |
 | 那一个问题 | 它存在的理由,一个问句 |
@@ -159,10 +160,24 @@ docs/specs/    ──▶ docs/              允许
 | What you may rely on, and what changes | Stability guarantees |
 | 0x —— 人人都需要 | 0x —— 基础 |
 | 0x — Everyone | 0x — Fundamentals |
+| 背景:模块到了,工具链没跟上 | 背景:C++ 工程侧的工具现状 |
+| 谁在为这个落差付账 | 这一现状的代价 |
+| 大致相当于谁的活 | 可对照的工具 |
+| 长什么样 | 形式 |
+| 一个 flag 由哪根轴决定 | 决定一个 flag 的轴 |
+| 一条运行时搜索路径可以住在哪里 | 运行时搜索路径的允许位置 |
 
 「…的原因」「…的依据」「…的范围」是把 why 型标题转成名词短语的常用形。
 **保留 why 本身,去掉疑问语气。**
 
+**判据是疑问词,不是问号。**「谁在为这个落差付账」「打什么由谁决定」都不带问号,
+都是疑问句。检查脚本第一版只匹配 `?` / 吗 / 呢,两句全部通过。判据是这一组词:
+谁、哪、什么、多少、为何、如何、怎样、怎么。
+
+**表头单元格与标题同规。** 一个列头按每一条要紧的性质都是标题:它命名一个主题、
+被跳读、并且是读者扫描时看的那一行。`| 部分 | 大致相当于谁的活 |` 通过了当时
+全部的检查,而它是全树最直白的一处违规。
+
 这条同样管**部分名与段位名**,不只管章节标题。「人人都需要」描述的是受众、
 是一个句子片段;「基础」是这一段**是什么**。受众写在每章开头的「读者」那一行,
 不写在目录的骨架上。

.github/tools/check_docs_structure.sh

@@ -144,23 +144,78 @@ for f in .agents/docs/[0-9]*.md; do
     || bad "$f: front matter declares no valid \`status\` (active | landed | superseded | abandoned)"
 done
 
-# ── 9. every relative link in docs/ and examples/ resolves ───────────────
+# ── 9. every relative link in docs/ and examples/ resolves, fragment included ─
 #
 # Rule 3 catches `docs/NN-*.md` named anywhere, including from source comments.
 # This is the other half: a Markdown link in a document that points at a file
 # which is not there. Both halves are needed -- a chapter moved in this batch
 # would satisfy one and break the other.
+#
+# THE FRAGMENT IS PART OF THE LINK. The first version of this rule discarded
+# it (`(?:#[^)]*)?`), so a link to a section that had been renamed resolved to
+# the file and was reported correct. Renaming 100 headings for register in one
+# batch is exactly the change that produces those, and two hand-written anchors
+# in chapter 30 were already wrong before the renames began.
 python3 - <<'PYCHECK' || fail=1
-import re, pathlib, sys
+import re, pathlib, sys, unicodedata
+
+def slug(heading):
+    """GitHub's heading slug: lowercase, drop punctuation and symbols, spaces to hyphens.
+
+    Category P* and S* covers what github-slugger removes -- ASCII punctuation,
+    the em dash, the backticks around inline code, and the full-width comma and
+    colon the Chinese chapters use -- while `-` and `_` are kept because an
+    anchor is allowed to contain them.
+    """
+    t = re.sub(r"^#+\s+", "", heading).strip().lower()
+    keep = []
+    for ch in t:
+        if ch in "-_":
+            keep.append(ch)
+        elif ch.isspace():
+            keep.append(" ")
+        elif unicodedata.category(ch)[0] in "PS":
+            continue
+        else:
+            keep.append(ch)
+    return "".join(keep).replace(" ", "-")
+
+def anchors_of(path):
+    """Every anchor the file defines, with GitHub's -1/-2 suffix for repeats."""
+    seen, out, infence = {}, set(), False
+    for line in path.read_text(errors="ignore").splitlines():
+        if line.startswith("```"):
+            infence = not infence
+            continue
+        if infence or not re.match(r"^#{1,6} ", line):
+            continue
+        s = slug(line)
+        n = seen.get(s, 0)
+        seen[s] = n + 1
+        out.add(s if n == 0 else f"{s}-{n}")
+    return out
+
+files = list(pathlib.Path("docs").rglob("*.md")) + list(pathlib.Path("examples").rglob("*.md"))
+cache = {}
 bad = 0
-for f in list(pathlib.Path("docs").rglob("*.md")) + list(pathlib.Path("examples").rglob("*.md")):
-    for m in re.finditer(r"\]\(([^)#]+?)(?:#[^)]*)?\)", f.read_text(errors="ignore")):
-        t = m.group(1)
+for f in files:
+    for m in re.finditer(r"\]\(([^)\s]*?)(?:#([^)\s]+))?\)", f.read_text(errors="ignore")):
+        t, frag = m.group(1), m.group(2)
         if t.startswith(("http", "mailto:")):
             continue
-        if not (f.parent / t).exists():
+        target = (f.parent / t) if t else f
+        if t and not target.exists():
             print(f"FAIL: {f}: link to `{t}` does not resolve")
             bad += 1
+            continue
+        if not frag or target.suffix != ".md" or not target.is_file():
+            continue
+        key = target.resolve()
+        if key not in cache:
+            cache[key] = anchors_of(target)
+        if frag not in cache[key]:
+            print(f"FAIL: {f}: `#{frag}` is not a heading in {target.as_posix()}")
+            bad += 1
 sys.exit(1 if bad else 0)
 PYCHECK
 

.github/tools/check_docs_style.sh

@@ -8,6 +8,13 @@
 #   2. reference docs do not address the reader in the second person
 #      (tutorials do — they are listed below, not inferred)
 #   3. docs/X.md and docs/zh/X.md have the same heading structure
+#   4. a table's header cells follow the same register as a heading
+#
+# Rule 4 exists because rule 1 read only lines beginning with `#`, and a column
+# header is a heading by every property that matters: it names a topic, it is
+# read out of order, and it is what a reader scans. `| 部分 | 大致相当于谁的活 |`
+# passed every check in this file while being the plainest register violation
+# in the tree.
 #
 # What it deliberately does NOT check: whether a claim's strength matches its
 # evidence. That is the most important rule in the skill and it needs a reader.
@@ -43,19 +50,69 @@ for f in docs/*.md docs/zh/*.md docs/specs/*.md; do
   base="$(basename "$f")"
 
   # ── 1. heading register ───────────────────────────────────────────────
+  #
+  # An interrogative WORD is the test, not a question mark. `谁在为这个落差付账`
+  # and `打什么由谁决定` carry no `?` and are questions all the same, and the
+  # first version of this rule matched `?`/`吗`/`呢` and passed both.
+  #
+  # THE ONE EXEMPTION IS BY NAME. `# 00 —— mcpp 是什么` mirrors the English
+  # `What mcpp Is`, which is a noun clause rather than a question, and a chapter
+  # title is the chapter's registered name: it appears in three indexes and in
+  # every citation of the chapter. Exempting it here states the decision;
+  # narrowing the rule to `##` and deeper would have hidden it.
   while IFS= read -r h; do
-    case "$h" in
-      *"?"*|*"吗"*|*"呢"*)
+    if [[ "$f" == "docs/zh/00-what-mcpp-is.md" && "$h" == "# 00 —— mcpp 是什么" ]]; then
+      continue
+    fi
+    # Inline code is quoted material: `cxx_stdlib` and `mcpp.why.toolchain`
+    # must not be read for register.
+    bare="$(sed -E 's/`[^`]*`//g' <<< "$h")"
+    case "$bare" in
+      *"?"*|*"？"*|*"吗"*|*"呢"*)
         bad "$f: question heading — use a noun phrase: $h" ;;
+      *"谁"*|*"哪"*|*"如何"*|*"为何"*|*"什么"*|*"多少"*|*"怎样"*|*"怎么"*)
+        bad "$f: interrogative heading — use a noun phrase (…的原因 / …的依据 / …的范围): $h" ;;
     esac
-    case "$h" in
-      *"一段话"*|*"讲完"*|*"姊妹篇"*|*"干活"*|*"怎么"*|*"会怎样"*|*"不许"*)
+    case "$bare" in
+      *"一段话"*|*"讲完"*|*"姊妹篇"*|*"干活"*|*"会怎样"*|*"不许"*|*"跟上"*|*"付账"*|*"长什么样"*)
         bad "$f: conversational heading: $h" ;;
       *"The whole idea"*|*"in one paragraph"*|*"Consuming one"*|*"the thing that"*)
         bad "$f: conversational heading: $h" ;;
     esac
   done < <(headings "$f")
 
+  # ── 4. table header register ──────────────────────────────────────────
+  #
+  # A header row is the row directly above the `|---|---|` separator, so the
+  # separator is what identifies it; matching every `|` line would read data.
+  while IFS= read -r cell; do
+    case "$cell" in
+      *"?"*|*"？"*|*"吗"*|*"呢"*)
+        bad "$f: question in a table header — use a noun phrase: $cell" ;;
+      *"谁"*|*"哪"*|*"如何"*|*"为何"*|*"什么"*|*"多少"*|*"怎样"*|*"怎么"*)
+        bad "$f: interrogative table header — use a noun phrase: $cell" ;;
+    esac
+    shopt -s nocasematch
+    if [[ "$cell" =~ ^(what|which|who|how|why|where|whether)([[:space:]]|$) ]]; then
+      bad "$f: interrogative table header — use a noun phrase: $cell"
+    fi
+    shopt -u nocasematch
+  done < <(awk '
+    /^```/ { infence = !infence; prev = ""; next }
+    infence { next }
+    /^\|[[:space:]:|-]+\|[[:space:]]*$/ && prev ~ /^\|/ {
+      line = prev
+      gsub(/`[^`]*`/, "", line)          # quoted material, as above
+      n = split(line, cells, "|")
+      for (i = 2; i < n; i++) {
+        c = cells[i]
+        gsub(/^[[:space:]]+|[[:space:]]+$/, "", c)
+        if (c != "") print c
+      }
+    }
+    { prev = $0 }
+  ' "$f")
+
   # ── 2. second person in reference docs ────────────────────────────────
   case " $TUTORIALS " in
     *" $base "*) ;;