跳到主要内容

Document Change Scope Policy

状态：Active / 文档变更范围控制协议 最后更新：2026-05-13 用途：约束团队成员、个人域 Agent 和 Program Controller 在更新治理仓库时只修改本轮授权范围内的文档

1. 目标​

本协议解决的问题是：

团队成员负责不同产品、系统或材料域时，如何允许他们高效更新自己负责的文档，同时避免误改公共入口、其他项目事实源、历史参考材料或发布配置。

本协议不记录固定人员分工。成员、角色和项目 owner 会变化，因此仓库只记录“变更范围”和“授权方式”，不把某个人绑定为长期规则。

2. 基本原则​

  • 默认最小范围：只改本轮任务声明中允许的目录和文件；
  • 项目内事实由项目负责人或对应 Program Controller 提出；
  • 公共入口由 Labs-FinTecAI Controller 或明确授权的公共入口维护者统一更新；
  • 跨项目影响先发 sync 或 escalation，不要直接改其他项目正式文档；
  • 工程细节、接口契约、任务执行过程默认留在工程仓库或协作系统，不提前写入治理仓库；
  • Agent 执行前必须读本协议和本轮变更范围，执行后必须报告实际改动文件。

3. 变更范围类型​

范围允许修改不允许直接修改
finclawprojects/finclaw/、references/finclaw/、evaluation/finclaw/、source/project-prealignment/finclaw/、packets/sync/finclaw-*其他项目目录、公共入口文件，除非另有授权
data-horizonprojects/data-horizon/、references/data-horizon/、packets/sync/data-horizon-*其他项目目录、公共入口文件，除非另有授权
trading-matrixprojects/trading-matrix/、references/trading-matrix/、packets/sync/trading-matrix-*其他项目目录、公共入口文件，除非另有授权
rleprojects/reinforcement-learning-engine/、references/reinforcement-learning-engine/、packets/sync/rle-*、packets/sync/reinforcement-learning-engine-*其他项目目录、公共入口文件，除非另有授权
fefmprojects/financial-expert-foundation-model/、references/financial-expert-foundation-model/、packets/sync/fefm-*、packets/sync/financial-expert-foundation-model-*其他项目目录、公共入口文件，除非另有授权
ecosystembaseline/、contexts/ecosystem/、registry/、governance/、controllers/、README.md、ACCESS_GUIDE.md、CONTEXT-MAP.md项目内容重写，除非对应项目 Controller 已给出明确回写输入
controllerscontrollers/、governance/controller-recovery-protocol.md正式产品事实源、项目定义、参考材料或公共入口文件，除非另有授权
public-entrypointsINDEX.md、CONTEXT-MAP.md、registry/project-registry.md、sidebars.js、docs-manifest.json、llms.txt、ACCESS_GUIDE.md 中与入口相关的段落项目事实内容改写
referencesreferences/、相关 source/ 材料说明将参考项目结论直接改写为正式产品定义
evaluationevaluation/、相关评测报告和 case将评测结论直接提升为 MVP 或产品定义，除非已有吸收决策
portaldocusaurus.config.js、sidebars.js、src/、static/、portal/、package.json、.github/workflows/正式事实源内容改写，除非同步更新已被授权
tooling.github/、scripts/、package.json 中的校验脚本正式事实源内容改写，除非同步更新已被授权

如果一轮变更需要同时覆盖多个范围，应在 PR 或执行指令中显式声明多个范围，例如：

DOC_CHANGE_SCOPE=finclaw,public-entrypoints
DOC_CHANGE_SCOPE=controllers,public-entrypoints

4. 团队成员更新流程​

团队成员或其个人域 Agent 更新本仓库时，应采用以下流程：

  1. 从 ACCESS_GUIDE.md、本协议和本轮对象入口开始；
  2. 声明本轮 DOC_CHANGE_SCOPE；
  3. 只修改 scope 允许的文件；
  4. 如果发现需要改其他范围，先停止并输出 sync / escalation / 公共入口修正请求；
  5. 本地运行 scope 校验、manifest 校验和构建；
  6. 通过 PR 或明确的 publish handoff 进入主线；
  7. Labs-FinTecAI Controller 统一处理公共入口和发布闭环。

5. Agent 执行提示词​

给个人域 Agent 或团队域 Agent 的最小提示词应包含：

你正在更新 Labs-FinTecAI-Gov。

本轮 DOC_CHANGE_SCOPE：
<finclaw / data-horizon / trading-matrix / rle / fefm / ecosystem / controllers / public-entrypoints / references / evaluation / portal>

允许修改：
<列出目录或文件>

禁止修改：
<列出其他项目、公共入口或工程细节>

如果发现必须越界：
不要直接修改；输出 sync / escalation / 公共入口修正请求。

完成后输出：
- 实际修改文件；
- 是否越界；
- 验证命令和结果；
- 是否需要 Labs-FinTecAI Controller 做公共入口收束或发布闭环。

6. 公共入口越界规则​

项目负责人可以提出公共入口修正建议，但默认不直接修改公共入口文件。

公共入口包括：

  • INDEX.md
  • CONTEXT-MAP.md
  • registry/project-registry.md
  • sidebars.js
  • docs-manifest.json
  • llms.txt
  • ACCESS_GUIDE.md

如果项目文档变化确实需要更新公共入口，应提交短请求：

对象：
需要更新的公共入口：
原因：
新增入口：
移除入口：
语义层：official entry / design support / reference / evaluation / sync / absorbed
验收命令：

Labs-FinTecAI Controller 收到后，按 knowledge-update-closure-protocol.md 分批处理。

7. 技术约束​

本仓库提供脚本 npm run verify:change-scope。

用法示例：

DOC_CHANGE_SCOPE=finclaw npm run verify:change-scope
DOC_CHANGE_SCOPE=data-horizon,public-entrypoints npm run verify:change-scope
DOC_CHANGE_SCOPE=controllers,public-entrypoints npm run verify:change-scope

脚本会检查当前分支相对 origin/main 的变更文件。如果有文件不属于声明范围，校验失败。

该脚本是最低限度的自动约束。真正生效还需要 GitHub 上启用：

  • 禁止直接 push 到 main；
  • 所有更新走 PR；
  • 将 scope guard workflow 设置为 required check；
  • 公共入口或跨项目变更必须由 Labs-FinTecAI Controller 复核；
  • 项目内容变更必须由对应项目负责人或 Program Controller 复核。

8. 与 CODEOWNERS 的关系​

CODEOWNERS 可以用于 GitHub review 自动路由，但不应把成员当前分工写成长期事实。

建议策略：

  • 先用 scope guard 限制文件范围；
  • 再用 GitHub branch protection 强制 review；
  • 当团队 GitHub team 稳定后，再补 CODEOWNERS；
  • CODEOWNERS 只表达 review 路由，不表达产品事实或组织永久分工。

9. 完成定义​

一次成员文档更新完成，应满足：

  • 本轮 scope 声明清晰；
  • 实际改动文件没有越界；
  • 若有越界需求，已转为 sync / escalation / 公共入口修正请求；
  • docs-manifest.json 可解析；
  • git diff --check 通过；
  • 如影响门户，npm run build 通过；
  • PR 或 handoff 清楚说明修改范围、事实依据、验证结果和是否需要发布闭环。

10. Closeout / 内容验收门控（FR-008 / FR-016 纠偏）​

build success、scope guard 通过、docs-manifest.json 可解析、PR 合并、npm run verify:published-site 通过 —— 均为发布闭环证据，不是内容验收证据。

任何写"completed / closed / satisfied / resolved / accepted / 已完成 / 已闭环 / 已收口"的 sync packet、checkpoint 或 state 字段，必须额外满足：

  1. 提供 reader-testing evidence path（按 reader-testing-protocol.md §4 等级表）；
  2. 在 sync 模板 §9 Open Gaps 中显式列出未解决项（不允许写"无"，参见 ../packets/sync/README.md §11.A）；
  3. 区分 doc alignment / project progress / publish evidence 三态，明确本 closeout 属于哪一态。

不满足以上三项的 closeout 视为 incomplete-closeout，scope guard 不阻挡，但 Admin / Controller 应在 PR review 中要求补齐，否则不得进入 final state。

本节是 5/14 batch 8 中识别的 FR-008（"发布闭环被误读为内容重构完成"）和 FR-016（"文档进展替代项目进展"）的工程化纠偏。任何后续重构 / closeout 必须遵循。