跳到主要内容

Checkpoint: scope-guard-required-check

日期：2026-05-14
Controller：Labs-FinTecAI Admin
Lane：knowledge-refactor
状态：Blocked

1. 本批结论​

Batch 7B 尝试把 scope guard 纳入 GitHub required check，但当前 GitHub 仓库权限 / 计划不支持在 private repository 上启用 branch protection 或 rulesets。

本批不修改项目正文、公共入口语义、Controller 产品事实源或门户结构。

2. 当前可用状态​

对象状态
RepositoryCurvature-Lab/Labs-FinTecAI-Gov
VisibilityPRIVATE
Default branchmain
WorkflowChange Scope，路径 .github/workflows/change-scope.yml
Required-check targetjob verify-change-scope in workflow Change Scope
Scope scriptscripts/verify-change-scope.mjs
PR declaration surface.github/PULL_REQUEST_TEMPLATE.md 中的 DOC_CHANGE_SCOPE

3. 阻断证据​

只读检查 GitHub branch protection：

gh api repos/Curvature-Lab/Labs-FinTecAI-Gov/branches/main/protection --include
HTTP/2.0 403 Forbidden
Upgrade to GitHub Pro or make this repository public to enable this feature.

只读检查 GitHub repository rulesets：

gh api repos/Curvature-Lab/Labs-FinTecAI-Gov/rulesets
HTTP 403
Upgrade to GitHub Pro or make this repository public to enable this feature.

由于公开仓库或升级 GitHub plan 都是仓库策略 / 计费层面的外部决策，Admin 不在本批中替用户执行。

4. 解锁后执行目标​

当仓库可使用 branch protection 或 rulesets 后，目标状态为：

  1. main 禁止未检查合并；
  2. Change Scope / verify-change-scope 作为 required status check；
  3. PR body 必须声明 DOC_CHANGE_SCOPE；
  4. scope guard 失败时禁止合并；
  5. 公共入口或跨项目变更仍需 Labs-FinTecAI Admin / 对应 Controller 复核。

建议保留直接 push 管理权限用于 Admin publish closure，但普通成员更新应走 PR。

5. 本地和 PR fallback​

在 required check 解锁前，当前可执行约束是：

  • PR 模板要求声明 DOC_CHANGE_SCOPE；
  • Change Scope workflow 会在 PR 上运行；
  • 本地发布前继续运行：
DOC_CHANGE_SCOPE=<scope> npm run verify:change-scope
node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"
git diff --check
npm run build

该 fallback 是执行纪律，不等同于 GitHub required check。

6. 验证​

  • gh repo view Curvature-Lab/Labs-FinTecAI-Gov --json nameWithOwner,visibility,isPrivate,defaultBranchRef：确认仓库为 PRIVATE，default branch 为 main。
  • gh workflow list --json id,name,path,state：确认 Change Scope 和 Docs workflow 均为 active。
  • gh run list --workflow "Change Scope" --limit 10：当前无历史 PR run。
  • DOC_CHANGE_SCOPE=public-entrypoints,controllers npm run verify:change-scope：通过，4 个变更文件均在声明范围内。
  • node -e "JSON.parse(require('fs').readFileSync('docs-manifest.json','utf8')); console.log('docs-manifest JSON parse OK')"：通过。
  • git diff --check：通过。
  • npm run build：通过，Docusaurus build 成功，Pagefind 索引 141 pages / 6254 words。
  • test -f build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-scope-guard-required-check/index.html：通过，新 checkpoint 页面已进入本地 build。
  • rg -n "scope-guard-required-check|Scope guard required-check" build/docs-manifest.json build/llms.txt build/controllers/labs-fintecai-admin/checkpoints/2026-05-14-scope-guard-required-check/index.html：通过，机器入口和页面产物均包含新 checkpoint。

7. 后续动作​

  1. 若用户升级 GitHub plan 或将仓库公开，重新打开本 checkpoint 并执行 required-check 设置；
  2. 下一批可继续 published-site-verify-script，不依赖 branch protection；
  3. 若后续改为 PR-only 流程，先跑一次测试 PR 来确认 required-check context 名称。