Harden repository quality gates

.github/pull_request_template.md

@@ -2,7 +2,7 @@
 
 [简体中文](pull_request_template_ZH.md)
 
-- TODO
+<!-- Describe the intent and user-visible outcome of this change. -->
 
 ## Validation
 
@@ -21,4 +21,4 @@
 
 ## Notes
 
-- TODO
+<!-- Include context that reviewers need, such as migration, compatibility, or follow-up notes. -->

.github/pull_request_template_ZH.md

@@ -2,7 +2,7 @@
 
 [English](pull_request_template.md)
 
-- TODO
+<!-- 说明本次变更的目的以及对用户可见的结果。 -->
 
 ## 验证
 
@@ -18,3 +18,7 @@
 - 受影响的示例路径和框架：
 - 硬件或引脚注意事项：
 - 固件工件影响：
+
+## 备注
+
+<!-- 补充评审所需的背景信息，例如迁移、兼容性或后续工作说明。 -->

.github/workflows/examples.yml

@@ -32,9 +32,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - name: Check repository documentation conventions
+      - name: Check established documentation compatibility rules
         run: python3 scripts/check_docs.py . --config config/markdown-audit.json
-      - name: Run routing, discovery, and documentation checker tests
+      - name: Run routing, discovery, and Markdown audit tests
         run: python3 -m unittest discover -s tests -v
 
   scope:
@@ -47,10 +47,11 @@ jobs:
       arduino_paths: ${{ steps.classify.outputs.arduino_paths }}
       firmware_paths: ${{ steps.classify.outputs.firmware_paths }}
       unknown_paths: ${{ steps.classify.outputs.unknown_paths }}
+      docs_only: ${{ steps.classify.outputs.docs_only }}
     steps:
       - uses: actions/checkout@v4
         with:
-          fetch-depth: 2
+          fetch-depth: 0
       - id: classify
         shell: bash
         run: |
@@ -62,27 +63,47 @@ jobs:
               echo 'arduino_paths=[]'
               echo 'firmware_paths=[]'
               echo 'unknown_paths=[]'
+              echo 'docs_only=false'
             } >> "$GITHUB_OUTPUT"
+            python3 scripts/audit_markdown.py . --all --config config/markdown-audit.json
           else
             if [[ "${{ github.event_name }}" == "pull_request" ]]; then
               base="${{ github.event.pull_request.base.sha }}"
             else
               base="${{ github.event.before }}"
             fi
-            git fetch --no-tags --depth=1 origin "$base"
-            git diff --name-status -z "$base" "${{ github.sha }}" > changed-files.z
-            python3 scripts/ci_scope.py --name-status-file changed-files.z --github-output "$GITHUB_OUTPUT"
+            if [[ -z "$base" || "$base" == "0000000000000000000000000000000000000000" ]]; then
+              echo "A non-empty base SHA is required for changed-scope CI" >&2
+              exit 1
+            fi
+            git fetch --no-tags origin "$base"
+            git cat-file -e "$base^{commit}"
+            git diff --name-status -z --find-renames "$base" "${{ github.sha }}" > changed-files.z
+            git diff --name-status --find-renames "$base" "${{ github.sha }}" > changed-files.txt
+            if [[ ! -s changed-files.z || ! -s changed-files.txt ]]; then
+              echo "Changed-file diff is missing or empty" >&2
+              exit 1
+            fi
+            python3 scripts/ci_scope.py --config config/markdown-audit.json --name-status-file changed-files.z --github-output "$GITHUB_OUTPUT"
+            docs_only="$(grep '^docs_only=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+            audit_args=(. --changed-files-from changed-files.txt --config config/markdown-audit.json)
+            if [[ "$docs_only" == "true" ]]; then
+              audit_args+=(--expect-docs-only)
+            fi
+            python3 scripts/audit_markdown.py "${audit_args[@]}"
           fi
           esp_idf_mode="$(grep '^esp_idf_mode=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
           arduino_mode="$(grep '^arduino_mode=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
           firmware_paths="$(grep '^firmware_paths=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
           unknown_paths="$(grep '^unknown_paths=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
+          docs_only="$(grep '^docs_only=' "$GITHUB_OUTPUT" | tail -n1 | cut -d= -f2-)"
           {
             echo "### CI scope"
             echo "- ESP-IDF mode: $esp_idf_mode"
             echo "- Arduino mode: $arduino_mode"
             echo "- Firmware paths: $firmware_paths"
             echo "- Unknown paths: $unknown_paths"
+            echo "- Documentation-only: $docs_only"
           } >> "$GITHUB_STEP_SUMMARY"
 
   discover-esp-idf:
@@ -95,11 +116,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - id: discover
+        env:
+          SELECTED_PATHS: ${{ needs.scope.outputs.esp_idf_paths }}
         shell: bash
         run: |
           args=()
           if [[ "${{ needs.scope.outputs.esp_idf_mode }}" == "selected" ]]; then
-            args+=(--selected-paths '${{ needs.scope.outputs.esp_idf_paths }}')
+            args+=(--selected-paths "$SELECTED_PATHS")
           fi
           python3 scripts/discover_examples.py --surface esp-idf \
             --selector "${{ github.event.inputs.target || 'all' }}" \
@@ -144,11 +167,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
       - id: discover
+        env:
+          SELECTED_PATHS: ${{ needs.scope.outputs.arduino_paths }}
         shell: bash
         run: |
           args=()
           if [[ "${{ needs.scope.outputs.arduino_mode }}" == "selected" ]]; then
-            args+=(--selected-paths '${{ needs.scope.outputs.arduino_paths }}')
+            args+=(--selected-paths "$SELECTED_PATHS")
           fi
           python3 scripts/discover_examples.py --surface arduino \
             --selector "${{ github.event.inputs.target || 'all' }}" \

docs/ci.md

@@ -31,14 +31,28 @@ Start the workflow manually with `target=all`, an example directory name such as
 
 ## Documentation Checks
 
-The lightweight repository checker runs the focused homepage, bilingual-link,
-and local-link checks configured in `config/markdown-audit.json`:
+The complete self-contained Markdown audit uses `config/markdown-audit.json`
+for ownership, bilingual pairing and reciprocal language links, local and HTML
+links/fragments, homepage structure, and public-text privacy checks. Changed
+PR and push scopes run it with the complete rename-aware input:
+
+```text
+python3 scripts/audit_markdown.py . --changed-files-from changed-files.txt --config config/markdown-audit.json
+```
+
+When the route classifier confirms every old and new affected path is Markdown
+or an exact allowlisted documentation asset file, CI also adds
+`--expect-docs-only`. Missing, empty, malformed, or unavailable changed-file
+data fails the scope job rather than silently passing or selecting all builds.
+
+The legacy checker remains for compatibility with its focused homepage,
+bilingual-link, and local-link conventions:
 
 ```text
 python3 scripts/check_docs.py . --config config/markdown-audit.json
 ```
 
-It is intentionally a limited repository checker, not a complete Markdown audit.
+It is intentionally limited and does not replace the complete audit.
 
 ## Firmware Artifacts
 

docs/ci_ZH.md

@@ -11,13 +11,23 @@
 
 ## 文档检查
 
-轻量级仓库检查器会按 `config/markdown-audit.json` 运行针对主页、双语链接和本地链接的检查：
+完整、自包含的 Markdown 审核使用 `config/markdown-audit.json` 检查所有权、双语配对和互链、
+本地及 HTML 链接/片段、主页结构和公开文本隐私。PR 和 push 的变更范围使用完整的重命名感知输入：
+
+```text
+python3 scripts/audit_markdown.py . --changed-files-from changed-files.txt --config config/markdown-audit.json
+```
+
+当路由分类器确认每个旧路径和新路径均为 Markdown 或精确列入允许列表的文档资源文件时，CI 还会添加
+`--expect-docs-only`。缺失、为空、格式错误或不可用的变更文件数据会使范围作业失败，不会静默通过或选择全部构建。
+
+旧版轻量检查器仍保留，用于兼容其针对主页、双语链接和本地链接的约定：
 
 ```text
 python3 scripts/check_docs.py . --config config/markdown-audit.json
 ```
 
-该检查器有意保持为范围有限的仓库检查器，并非完整的 Markdown 审核。
+该检查器有意保持为范围有限的仓库检查器，不能替代完整审核。
 
 ## Arduino