Luna Flow
简体中文

文档治理

  • 状态：active
  • 读者：贡献者、维护者
  • 权威性：仓库文档策略；从属于 QED 形式规范
  • 范围：文档层级、命名、元数据与交叉引用规则
  • 最近审阅：2026-10-08

本文档定义 QED 仓库的文档治理规则。目标不是增加新的规范层，而是把现有文档按权威性、用途和受众硬性分层，避免同一主题在多个入口里重复叙述并逐渐漂移。

文档层次

QED 当前采用以下文档层级：

  1. 规范层 QED 形式规范 是唯一规范性来源，doc/attachments/qed_formal_spec.typ 是其源文件。
  2. 实现层当前代码与回归测试决定真实 shipped state。
  3. 实现文档层 用户手册、规范符合性、api/、design/ 和 tutorial/ 下的包页面，以及工作区审计（2026-04-18），描述当前实现契约、工程符合性、各包的公开界面和阶段性审计。
  4. 摘要与导航层 README.md、CHANGELOG.md 和手册概览只提供摘要、发布历史和入口导航，不得高于实现层和实现文档层。
  5. 研究层 research/ 只承载未 shipped 的设计研究、promotion gates、go/no-go 结论和原型评估。研究文档不是产品合同。

若代码与文档冲突，先以代码 + 测试核定真实状态，再回写实现文档。若实现与论文规范冲突，论文规范仍为准。

规范入口

每类信息必须有单一主入口：

  • 当前实现合同：用户手册
  • 单个包的公开界面、设计缘由和导览：其在 api/、design/ 和 tutorial/ 下的页面，列于手册概览
  • 当前用户输入语法速查：语法指南
  • 工程符合性与代码/测试映射：规范符合性
  • 阶段性风险与缺口：工作区审计（2026-04-18）
  • 仓库摘要与快速入口：README.md
  • 发布历史：CHANGELOG.md
  • 研究目录入口：research/README.md

其他文档只能补充，不得平行复制“当前状态”。

代码组织与 alias 入口治理由 代码治理 统一定义；它不高于当前代码与实现文档，只负责固定工程边界和维护义务。

元数据契约

除顶层 README.md、CHANGELOG.md、规范正文本身、手册概览以及 api/、design/、tutorial/ 下的包页面（它们遵循 Luna Flow 文档标准）之外，面向维护的文档头部都应包含：

  • Status
  • Audience
  • Authority
  • Scope
  • Last reviewed

状态标签使用以下词汇：

  • active
  • point-in-time audit
  • research-only
  • superseded
  • archival reference

命名规则

  • 实现文档使用职责导向命名，如 manual.md、conformance.md、current_workspace_audit.md。
  • 研究文档使用主题目录 + 阶段文件名，统一采用 lowercase kebab-case。
  • 新研究主题应放在 research/<topic>/ 下，例如 research/rewrite-simplify/。
  • 不再新增 v2、new、tmp、final 这类临时命名；需要替代时直接完成迁移并删除旧入口。

内容规则

  • README.md 只允许写：
    • 项目简介
    • 当前 shipped subset 的高层摘要
    • 构建命令
    • 文档地图
  • README.md 不应承载：
    • 完整支持矩阵
    • 长篇能力列表
    • 审计细节
    • 未来计划细节
  • 用户手册 描述当前实现边界、模块职责、支持矩阵和稳定示例。
  • 每个包页面各自记录一个包：api/<package>.md 列出 pkg.generated.mbti 的每个公开条目，design/<package>.md 解释其背后的决策并以其边界作结，tutorial/<package>.md 通过可针对当前代码编译的示例逐项讲解任务。它们不重复用户手册中的支持矩阵，而是链接到它。
  • 语法指南 只描述当前 shipped theorem-script 输入语法与已知限制，不承担实现合同。
  • 规范符合性 描述规范对齐、代码/测试映射、贡献者检查项和文档示例约束。
  • 工作区审计（2026-04-18） 只记录某一时间点仍然成立的风险、缺口和 follow-up，不长期重复 manual/conformance 的稳定事实。
  • research/ 文档必须显式声明 research-only、not shipped、non-authoritative。

示例与引用规则

  • 公开宣称的 capability 必须能回溯到当前代码和回归测试。
  • public runnable example 必须锚定到现有测试；不得在文档中发明未测试脚本。
  • README.md 只摘要能力，不单独发明示例语义。
  • research 文档可以引用 shipped 状态，但应链接到实现文档，而不是重复写一份长期状态说明。

当前文档地图

  • README.md 仓库摘要与导航入口。
  • CHANGELOG.md 发布历史。
  • 手册概览 包地图与阅读路径。
  • 用户手册 当前实现合同。
  • 包页面（api/、design/、tutorial/） 各包的公开界面、设计缘由和导览。
  • 语法指南 当前 shipped theorem-script 输入语法速查。
  • 规范符合性 代码/测试映射与工程符合性。
  • 代码治理 包分层、alias 入口与代码维护义务。
  • 工作区审计（2026-04-18） 当前工作区阶段性审计。
  • 形式规范变更日志 规范变更记录，属于规范维护辅助材料。
  • research/README.md 研究目录入口与边界声明。

维护规则

当一次改动同时影响实现、公开能力口径和研究判断时，应按下面顺序维护：

  1. 代码与测试
  2. 用户手册
  3. 受影响的包页面（api/、design/、tutorial/）
  4. 规范符合性
  5. README.md 与 CHANGELOG.md
  6. 工作区审计（2026-04-18）
  7. 相关 research/ 文档