跳到主要内容

R4 项目 Controller 文档 IA 重构控制包

1. 触发与背景​

  • 5 个项目 Controller 会话已在各自 workspace 对齐 ready（FinClaw / Data Horizon / AI Trading Matrix / RLE / FEFM）。
  • R1-R3 已完成生态层重构、生态基线 rewrite、FinClaw 首屏 reader-surface 清洗、reader-testing-protocol 建立、engineering seeds 试点。
  • 本轮目标：让各项目 Controller 在治理库中对自己项目的文档目录（IA）与内容做深度整理、清理合并、命名归一、改造优化。
  • 本包是各 Controller 执行文档 IA 重构的唯一权威条款；Controller 不靠记忆做事，靠引用本包。

2. 范围与边界​

Controller-owned（各 Controller 可自主改动）​

范围类型允许改动的路径
项目正文projects/<project>/
项目参考references/<project>/
项目评测evaluation/<project>/
项目来源source/project-prealignment/<project>/
项目同步packets/sync/<project>-*
Controller 状态controllers/<project>/state.md

Admin-owned（Controller 不可自行改动）​

路径说明
README.md / ACCESS_GUIDE.md / INDEX.md / CONTEXT-MAP.md仓库级入口
registry/project-registry.md项目注册表
sidebars.js / docs-manifest.json / llms.txt机器路由与导航
governance/公共治理规则
其他项目目录跨项目隔离

需要联动公共入口时，Controller 提交短请求（格式见 governance/document-change-scope-policy.md §6），Admin 统一合并。

红线​

  • 不允许把工程进展伪装为文档进展（FR-016 / FR-008）。
  • 不允许改其他项目的正式事实。
  • 不允许在 audit 完成前批量 rename 或合并文件。

3. 最小 audit 包格式​

每个 Controller 先产出一份项目文档 IA audit 包，不直接改正文。

路径模板：packets/sync/<project>-doc-ia-audit-2026-05-15.md

必含字段：

#字段内容
1当前目录树项目在 Gov 中的完整目录树（projects/<project>/ + references/<project>/ + evaluation/<project>/ + 相关 packets/sync/）
2文件角色标签每份文件标注：canonical / support / evidence / reference / sync / controller-state / open-gap
3命名问题清单违反 §4 命名规范的具体文件 + 建议新名
4处置建议每份文件标注 keep / rename / merge / move / rewrite / defer，附影响范围（含公共入口链接）
5内容深度问题哪些章节需 rewrite 而非 rename（与 §6 验收挂钩）
6reader-test 计划本批次需 L1 还是 L2，独立读者如何调度
7风险与开放问题open-gap 列表

4. 命名规范（最小集）​

  • 文件名一律 lowercase-kebab-case.md，目录名亦然。
  • 不混用同义后缀：固定为 *-plan.md / *-audit.md / *-task-packet.md / *-reference-analysis.md（desk research）/ *-reference-evaluation.md（复现/体验证据）。
  • 跨目录指向同一对象时，对象名严格一致（含是否带 and、连字符位置）。
  • 版本前缀固定：v1- / v2- 放最前；阶段词（如 readiness-）只用一次。
  • YAML case 文件名应与 case_id 字段对齐；批量改名前先做 id ↔ filename 映射表。
  • 任一 rename 必须列出：旧路径 → 新路径 → 被影响的 Gov 公共入口与外链锚点。
  • 前缀规范（OG-1 裁定）：<project>-* 前缀用于 Controller-owned 的项目 sync packet（如 finclaw-program-controller-handoff-2026-05-09.md）；labs-fintecai-<project>-* 前缀用于 Admin-owned 的跨 Controller 审计/分发包（如 labs-fintecai-finclaw-project-doc-audit-2026-05-14.md）。两种前缀语义不同，不统一 rename。
  • design-output 后缀豁免（OG-9 裁定）：*-design.md、*-prd.md、*-packet.md（含 kickoff）等 design-output 类文件不受上述五类标准后缀强制约束，但需保持项目内一致。

5. 阶段分流​

FinClaw（成熟度最高，本轮试点）​

  • Controller 自审命名问题（Admin 不预播清单）。
  • 先 audit，再做低风险批次（hub 页、命名映射、侧栏一致性）。
  • 不动 canonical 三件套（strategic-whitepaper.md / product-definition.md / mvp-product-definition.md）文件名，除非显式接受改链成本。
  • V1 design 目录、task-packets、reference-experience、evaluation cases 是重点 audit 区域。

Data Horizon（reference-evaluation prealignment）​

  • 保持 reference-evaluation prealignment 定位。
  • 不新建 product-definition.md / mvp-product-definition.md。
  • Audit 重点：角色分层、reference shortlist、输出对象边界、是否需要 references/data-horizon/README.md 作为 desk reference hub。

AI Trading Matrix（reference-evaluation first）​

  • 保持 reference-evaluation-first 定位。
  • 不恢复旧 CONTEXT.md 为入口。
  • Audit 重点：projects/ 与 references/ 的边界、参考评估证据、执行治理（授权/风控/审计/可回滚）语境标注。

RLE / FEFM（readiness-gated）​

  • 保持 readiness-gated 定位。
  • 不套 FinClaw product/MVP 三件套。
  • Audit 重点：readiness checklist、反馈/样本对象最小字段、RLE→FEFM 入模边界（RLE）、能力议程/通用 LLM 关系/样本治理（FEFM）。

6. 验收门控​

  • 每次改动声明 DOC_CHANGE_SCOPE=<project-slug>；涉及公共入口追加 public-entrypoints 并由 Admin 合并。
  • npm run build 必须通过。
  • 项目 canonical / reader-surface 改造完毕：跑 L1，归档到 evidence/reader-tests/<date>-<project>-<topic>-l1/。
  • 公共入口或跨项目导航改动：跑 L2（独立 reader + 工程师双视角）。
  • Closeout 必须显式写：completed / accepted-deferred / blocked / open gaps，禁止只写"全部完成"。
  • Reader-testing evidence path 必须可追溯（参见 governance/reader-testing-protocol.md §4）。

7. Admin 接口​

  • Admin 在每批次提供：合并公共入口、汇总 sidebars / manifest / llms / INDEX / registry、跨项目命名冲突仲裁。
  • Admin 不替项目 Controller 改 projects/<project>/ canonical（FR-010）。
  • Admin 在 FinClaw audit 落盘后回头核对，看是否需要补救或仲裁。

8. 时间盒与节奏​

  • 本包不设硬截止；按 Controller 排期。
  • 单批次（一份 audit + 一组改造 + 一次 reader test）建议 ≤ 1 周。
  • 超时应在 closeout 明示。

9. Open Gaps​

  • 跨项目命名仲裁尚未发生；待第一批 audit 汇齐再定全库 rename 优先级。
  • Sidebar 与 README / manifest 的"双真相"清理范围由 Admin 在第一批后裁定。
  • FinClaw canonical 三件套文件名是否改 rename 为 open decision（当前默认保留）。