项目宪法¶
第一条：规格至上¶
本项目采用 SDD。规格定义产品事实、架构边界、数据语义和验收门。实现必须符合规格，测试必须验证规格，发布必须满足规格。不得用已有代码、时间压力或实现便利作为违反规格的理由。
第二条：真实实现¶
项目不接受 mock 训练、占位成功、伪造设备可用、伪造性能数据或静默 CPU 回退。未完成的能力应不可用并在任务清单中保持未勾选，但正式发布的功能表不得展示其为可用。
第三条：唯一逻辑¶
同一业务语义只能有一个权威实现。公共参数校验、切分增益、叶子权重、模型格式和缓存 key 不得在多个模块复制。CPU 参考和 MPS 后端可以有不同计算实现，但必须共享同一规范、输入结构和结果契约。
第四条：SOLID 与 DRY¶
- Python API 只负责用户契约和输入适配。
- 数据模块只负责验证、量化和数据所有权。
- 训练核心只负责算法状态机和后端编排。
- 后端只负责计算和设备资源，不决定产品参数语义。
- 缓存不参与正确性；删除缓存后结果必须保持等价。
- 模型 I/O 不依赖训练时对象生命周期。
依赖方向固定为：Python API → 应用服务 → 领域核心 ← 后端接口 ← MPS 后端。领域核心不得反向依赖 Python、Objective-C 对象或文件系统。
第五条：正确性优先¶
任何优化前必须有 CPU oracle、边界测试和可复现实验。浮点非确定性必须受容差和稳定 tie-break 约束。检测到错误、溢出、设备失败或损坏缓存时必须明确失败，不能返回部分模型。
第六条：高效是端到端要求¶
性能衡量必须包含输入转换、分箱、设备初始化、kernel、同步和模型组装。优化目标依次为：避免复制、提高有效并行度、减少原子冲突、减少同步、复用内存。单 kernel 快但端到端慢不算成功。
第七条：稳定与易安装¶
正式加速版本必须提供受支持平台的预编译 wheel。普通用户安装不得要求重量级框架、包管理器、构建系统或本地 shader 编译器。设备不可用、资源缺失和 ABI 不匹配必须在训练前明确报错。
第八条：中文可维护性¶
代码文件必须有中文意图说明；公共与复杂函数必须有中文契约注释；并行、内存、缓存和数值关键点必须解释设计原因。注释与代码不一致属于缺陷。
第九条：测试不可操纵¶
禁止删除失败测试、降低断言、扩大无依据容差、用条件跳过真实错误或只测 mock。修复必须针对根因。环境阻塞必须记录为阻塞，不得标记任务完成。
第十条：任务完成真实性¶
tasks.md 的 [x] 是完成声明。只有实现、中文注释、测试、文档和验收全部满足才能打勾。部分完成、只写接口、只通过单元测试或尚未运行验证均保持 [ ]。
第十一条：最小公开承诺¶
对外材料只描述已交付能力。预发布可以用于保留名称，但不得包含假训练接口或让用户误以为功能可用。公开版本不可覆盖，发布物必须可追溯到已验证 commit 和 artifact 哈希。
第十二条：修宪¶
改变宪法必须由用户明确批准，并记录修改原因、受影响模块和迁移方案。任何普通实现任务无权隐式修改宪法。