docs(skills): 明确批处理阈值速记语义

- 更新 gframework-batch-boot skill，明确纯数字速记默认按当前分支相对远程 origin/main 的累计 diff 计算
- 补充文件数与代码行数双阈值的 OR 语义，并将无管道的 75 2000 作为推荐写法
- 同步更新 skills README 与 documentation governance tracking/trace，记录本轮规则收口与恢复点

.agents/skills/README.md

@@ -46,9 +46,23 @@
 /gframework-batch-boot <task-or-stop-condition>
 ```
 
+批处理阈值速记：
+
+```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
+```
+
+- 单个数字默认表示“分支相对基线接近多少个文件变更时停止”
+- 单个数字默认表示“当前分支全部提交相对远程 `origin/main` 接近多少个文件变更时停止”
+- 两个数字默认表示“当前分支全部提交相对远程 `origin/main` 的 `文件数 OR 变更行数`”，顺序固定为 `<files> <lines>`
+- 不推荐写 `/gframework-batch-boot 75 | 2000`，因为 `|` 很像 shell pipe；若用户这样写，也应按 OR 语义理解并在后续说明中归一化成无 `|` 版本
+
 示例：
 
 ```bash
+/gframework-batch-boot 75
+/gframework-batch-boot 75 2000
 /gframework-batch-boot continue analyzer warning reduction until branch diff vs origin/main approaches 75 files
 /gframework-batch-boot keep refactoring repetitive source-generator tests in bounded batches
 ```

.agents/skills/gframework-batch-boot/SKILL.md

@@ -50,6 +50,19 @@ For changed-file limits, measure branch-wide scope against the chosen baseline,
 - use `git diff --name-only <baseline>...HEAD`
 - do not confuse branch diff size with `git status --short`
 
+For changed-line limits, also measure branch-wide scope against the chosen baseline:
+
+- prefer `git diff --numstat <baseline>...HEAD`
+- treat "changed lines" as `added + deleted` summed across the branch diff
+- do not use working-tree-only line counts as a substitute for branch-wide scope
+
+For shorthand numeric thresholds, use a fixed default baseline:
+
+- compare the current branch's cumulative diff against remote `origin/main`
+- include all commits reachable from `HEAD` that are not already in `origin/main`
+- do not reinterpret shorthand thresholds as "this batch only" or "current unstaged changes only"
+- only use another baseline when the user explicitly names it in the prompt
+
 ## Stop Conditions
 
 Choose one primary stop condition before the first batch and restate it to the user.
@@ -63,6 +76,32 @@ Common stop conditions:
 
 If multiple stop conditions exist, rank them and treat one as primary.
 
+## Shorthand Stop-Condition Syntax
+
+`gframework-batch-boot` may be invoked with shorthand numeric thresholds when the user clearly wants a branch-size stop
+condition instead of a long natural-language prompt.
+
+Interpret shorthand as follows:
+
+- `$gframework-batch-boot 75`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files
+- `$gframework-batch-boot 75 2000`
+  - means: stop when the current branch's cumulative diff vs remote `origin/main` approaches `75` changed files OR
+    `2000` changed lines
+  - default positional meaning is `<files> <lines>`
+- `$gframework-batch-boot 75 | 2000`
+  - may be interpreted as the same OR shorthand in plain-language chat
+  - when restating, planning, or documenting the command, normalize it to `$gframework-batch-boot 75 2000`
+  - prefer the no-pipe form because `|` is easy to confuse with a shell pipeline
+
+When shorthand is used:
+
+- report the resolved thresholds explicitly before the first batch
+- report that the baseline is remote `origin/main`, unless the user explicitly overrides it
+- if two numeric thresholds are present, treat file count as the default primary metric for status reporting unless the
+  user says otherwise
+- stop when either threshold is reached or exceeded, even if the other threshold still has headroom
+
 ## Batch Loop
 
 1. Inspect the current state before the first batch:
@@ -134,6 +173,8 @@ When stopping, report:
 
 ## Example Triggers
 
+- `Use $gframework-batch-boot 75 to keep reducing analyzer warnings until the branch diff vs baseline approaches 75 files.`
+- `Use $gframework-batch-boot 75 2000 to keep reducing warnings until the branch diff approaches 75 files or 2000 changed lines.`
 - `Use $gframework-batch-boot and keep reducing analyzer warnings until the branch diff vs origin/main approaches 75 files.`
 - `Use $gframework-batch-boot to continue this repetitive test refactor in bounded batches until the warning count drops below 10.`
 - `Use $gframework-batch-boot and refresh module docs in waves without asking me to trigger every round.`

ai-plan/public/documentation-full-coverage-governance/todos/documentation-full-coverage-governance-tracking.md

@@ -12,9 +12,10 @@
 
 ## 当前恢复点
 
-- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-020`
+- 恢复点编号：`DOCUMENTATION-FULL-COVERAGE-GOV-RP-021`
 - 当前阶段：`Phase 5 - Governance Maintenance`
 - 当前焦点：
+  - 为 `gframework-batch-boot` 明确数字速记阈值语义，避免把“本轮新增文件数”与“整条分支 diff 阈值”混淆
   - 保持 `Core` functional docs surface 的 inline code / 泛型示例在 VitePress 下按真实 C# 语法渲染
   - 保持 `Game` persistence docs surface 与当前 `README`、源码、`PersistenceTests` 使用同一套 owner / adoption path 叙述
   - 保持 `GFramework.Godot.SourceGenerators/README.md` 与 `docs/zh-CN/tutorials/godot-integration.md` 在生命周期接法上的一致性
@@ -42,6 +43,11 @@
   `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处。
 - 上述 8 处 inline code 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 已统一改为真实
   泛型写法，避免在 VitePress 中显示字面量 HTML entity。
+- `2026-04-23` 根据本轮使用反馈，已为 `.agents/skills/gframework-batch-boot/SKILL.md` 与
+  `.agents/skills/README.md` 补充数字速记阈值语义：
+  - `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
+  - `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
+  - `75 | 2000` 仅作为可理解的 OR 写法保留，不再作为推荐写法，以避免与 shell pipe 混淆
 - 当前剩余的托管侧信号是 GitHub `Title check` 对 PR 标题过泛的 inconclusive 提示；这属于 PR 元数据，不是本地
   文件缺陷。
 
@@ -70,14 +76,18 @@
   - 结果：命中 `docs/zh-CN/godot/setting.md:75` 与 `docs/zh-CN/godot/storage.md:102` 两处同类写法，均已修正。
 - `2026-04-23` `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'`
   - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。
+- `2026-04-23` `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md` 与 `sed -n '1,220p' .agents/skills/README.md`
+  - 结果：确认原文仅描述自然语言 stop condition，没有定义数字速记或多阈值 OR 语义；现已补齐。
 - `2026-04-23` `bun run build`（工作目录：`docs/`）
   - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
 
 ## 下一步
 
-1. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内
+1. 若后续继续扩展批处理 skill，可考虑再补充显式单位写法，例如 `75 files 2000 lines`，但当前默认速记已足够覆盖
+   常见分支阈值场景。
+2. 对 `README.md`、`GFramework.*` 与 `docs/zh-CN/**` 继续做下一类低风险 Markdown 渲染巡检，优先排查 code span 内
    的 HTML entity、站点内链接和标题锚点是否仍与当前页面结构一致。
-2. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
+3. 若后续分支继续调整 `Game` persistence runtime、README 或公共 API，优先复核 `docs/zh-CN/game/data.md`、
    `storage.md`、`serialization.md`、`setting.md` 与 landing page 是否仍保持同一套职责边界。
-3. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
+4. 若后续分支继续调整 `Godot` generator 接法，优先复核 `GFramework.Godot.SourceGenerators/README.md`、
    `docs/zh-CN/tutorials/godot-integration.md` 与相关专题页是否仍保持一致。

ai-plan/public/documentation-full-coverage-governance/traces/documentation-full-coverage-governance-trace.md

@@ -2,39 +2,40 @@
 
 ## 2026-04-23
 
-### 当前恢复点：RP-020
+### 当前恢复点：RP-021
 
-- 按 `$gframework-batch-boot` 继续执行 `documentation-full-coverage-governance`。
+- 按当前使用反馈继续执行 `documentation-full-coverage-governance` 下的 skill 文档治理。
-- 将这轮批处理目标定义为“清理 README / `docs/zh-CN` / 模块 README 中仍会在 inline code 里被字面渲染的 HTML 泛型实体”。
+- 本轮目标定义为“为 `$gframework-batch-boot` 补齐数字速记 stop condition 语义，并消除分支 diff 阈值的歧义”。
-- 基线选择为 `origin/main` `aa879d2`（`2026-04-23T17:51:41+08:00`）；当前分支 `docs/sdk-update-documentation`
-  与该基线零差异，适合继续做小批次文档治理。
-- 以 `rg -n '`[^`]*<[^`]*`|`[^`]*>[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'` 扫描后，确认剩余热点只在
-  `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md`，共 8 处。
 - 本轮执行的修复：
-  - 将 `docs/zh-CN/core/functional.md` 中的 `Option<T>`、`Result<T>`、`Nullable<T>` 改为真实泛型写法
+  - 为 `.agents/skills/gframework-batch-boot/SKILL.md` 增加 `Shorthand Stop-Condition Syntax`
-  - 将 `docs/zh-CN/tutorials/functional-programming.md` 中的 `Option<T>`、`Result<T>` 改为真实泛型写法
+  - 明确 `$gframework-batch-boot 75` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个分支 diff 文件时停止”
-  - 同步更新 active tracking / trace，记录 batch objective、基线和新的恢复点
+  - 明确 `$gframework-batch-boot 75 2000` 默认表示“当前分支全部提交相对远程 `origin/main` 接近 75 个文件或 2000 行变更时停止”
+  - 明确 `75 | 2000` 只作为可理解的 OR 输入保留，推荐统一归一化为无 `|` 版本
+  - 为 `.agents/skills/README.md` 同步补充公开入口示例与速记说明
+- 本轮执行的修复：
+  - 同步更新 active tracking / trace，记录该 skill 语义收口和新的恢复点
 
-### 当前决策（RP-020）
+### 当前决策（RP-021）
 
-- 对 Markdown inline code 中的 C# 泛型示例，必须直接写真实的 `<T>` 语法，不能在反引号内部再写
+- 对 `$gframework-batch-boot` 的纯数字速记，默认第一位数字绑定“文件数阈值”，第二位数字绑定“行数阈值”。
-  `&lt;` / `&gt;`，否则 VitePress 会把 entity 当作字面量展示。
+- 对 `$gframework-batch-boot` 的纯数字速记，默认比较口径固定为“当前分支全部提交相对远程 `origin/main` 的累计 diff”。
-- 当一个渲染热点模式可以用本地正则直接衡量时，优先把该模式收敛为一个小批次并一次性清空命中列表，而不是只修单页。
+- 多个数字阈值的默认逻辑为 OR，而不是 AND；否则不符合“任一 reviewability 阈值接近上限就停”的批处理目标。
-- 对文档治理批处理，主 stop condition 采用“热点列表耗尽”，次级 stop condition 采用“相对基线的分支 diff 不接近大批次阈值”。
+- 为避免 shell 语义干扰，文档与后续回复中应优先使用无 `|` 的规范写法，即 `$gframework-batch-boot 75 2000`。
 
-### 当前验证（RP-020）
+### 当前验证（RP-021）
 
-- 同类模式巡检：
+- skill 文档巡检：
-  - `rg -n '`[^`]*&lt;[^`]*`|`[^`]*&gt;[^`]*`' README.md GFramework.* docs/zh-CN -g '*.md'`
+  - `sed -n '1,260p' .agents/skills/gframework-batch-boot/SKILL.md`
-  - 结果：命中 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 共 8 处，已全部修正。
+  - `sed -n '1,220p' .agents/skills/README.md`
+  - 结果：确认原文缺少数字速记与 OR 语义定义，现已补齐。
 - 构建校验：
   - `bun run build`（工作目录：`docs/`）
   - 结果：通过；仅保留既有 VitePress 大 chunk warning，无构建失败。
 
-### 归档摘要（RP-019）
+### 归档摘要（RP-020）
 
-- 使用 `$gframework-pr-review` 重新抓取 PR `#272` 后，定位到 `docs/zh-CN/godot/setting.md` 的 inline code HTML entity 渲染问题。
+- 对 `README.md`、模块 README 与 `docs/zh-CN` 做 HTML entity 泛型热点清理。
-- 顺手扫描当前 PR 已改动的相邻 Godot 文档，又在 `docs/zh-CN/godot/storage.md` 发现同型问题，并已一起修正。
+- 修复 `docs/zh-CN/core/functional.md` 与 `docs/zh-CN/tutorials/functional-programming.md` 中剩余的 8 处写法。
 - `docs/` 站点构建通过。
 
 ### 归档指针