ci: scaffold 自身文档同步检查（防 README 与 template 漂移）

- scripts/check-docs.sh：校验 template/{backend,agent,frontend}/src 各层目录
  及 .vscode/.claude-commands/.copier-answers/pnpm-workspace 都在 README 有记录
- .github/workflows/docs-check.yml：scaffold 仓库根级 CI（区别于 template/.github，
  那是生成项目用的），改 template/ 或 README 时触发
- 仅作用于 scaffold 自身，不进生成项目、不属 skill
- README scripts 树补 check-docs.sh + docs-check.yml

.github/workflows/docs-check.yml

@@ -0,0 +1,28 @@
+name: docs-check
+
+# scaffold 仓库自身的 CI（区别于 template/.github/ 那份——那是生成项目用的）。
+# 防止 README 文档随 template/ 结构改动而漂移。
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "template/**"
+      - "README.md"
+      - "scripts/check-docs.sh"
+  pull_request:
+    paths:
+      - "template/**"
+      - "README.md"
+      - "scripts/check-docs.sh"
+
+jobs:
+  docs-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: 校验 README 与 template 结构同步
+        run: bash scripts/check-docs.sh
+      - name: 脚本语法检查
+        run: |
+          for s in scripts/*.sh; do bash -n "$s"; done

README.md

@@ -141,9 +141,11 @@ scaffold/
 ├── README.md
 ├── .claude/skills/new-project/
 │   └── SKILL.md                         ← skill 元数据 + 生成指令（verify.sh 安装时组装）
+├── .github/workflows/docs-check.yml     ← scaffold 自身 CI：防 README 与 template 漂移
 ├── scripts/
 │   ├── verify.sh                        ← 工具链合规检查（幂等只读，单一源）
 │   ├── install-skill.sh                 ← 把 skill 安装到 ~/.claude/skills/
+│   ├── check-docs.sh                    ← 校验 README 覆盖 template 架构基座目录
 │   └── retrofit.sh                      ← 补装工具链到已有项目
 └── template/
     ├── .copier-answers.yml.jinja        ← 记录模板版本+答案，供 copier update

scripts/check-docs.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# 校验 README.md 是否记录了 template/ 的架构基座目录，防止文档随模板改动漂移。
+# 仅作用于 scaffold 仓库自身（不进生成项目、不属 skill）。
+# 用法：./scripts/check-docs.sh    退出码 0=同步 / 1=有未记录目录
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+README="$ROOT/README.md"
+fail=0
+
+check_service_layers() {
+  local svc="$1" srcdir="$ROOT/template/$svc/src"
+  [ -d "$srcdir" ] || return 0
+  for d in "$srcdir"/*/; do
+    [ -d "$d" ] || continue
+    local name
+    name="$(basename "$d")"
+    if ! grep -q "$name" "$README"; then
+      echo "✗ template/$svc/src/$name/ 未在 README 记录"
+      fail=1
+    fi
+  done
+}
+
+for svc in backend agent frontend; do
+  check_service_layers "$svc"
+done
+
+# 顶层关键产物也应在 README 出现
+for entry in ".vscode" ".claude/commands" ".copier-answers.yml" "pnpm-workspace.yaml"; do
+  if [ -e "$ROOT/template/$entry" ] && ! grep -q "$(basename "$entry")" "$README"; then
+    echo "✗ template/$entry 未在 README 记录"
+    fail=1
+  fi
+done
+
+if [ "$fail" -eq 0 ]; then
+  echo "✓ README 已覆盖 template 的架构基座目录与关键产物"
+else
+  echo ""
+  echo "→ 请更新 README.md 的「架构基座」章节与「脚手架内容」文件树后重试。"
+  exit 1
+fi