README.md

WaveEngine 文档地图

本目录把“当前事实、长期设计、实施顺序、变更契约和参考输入”分开保存，避免同一结论在多处漂移。

文档职责

文档	唯一职责	不承担
README.md	项目定位、已实现能力、快速开始和当前边界	详细架构与实施方案
AGENTS.md	代理工作规则、验证命令和当前高风险工程契约	产品路线与通用教程
architecture/ai-native-engine.md	全引擎 AI-native 长期不变量和设计取舍	已实现能力声明与具体排期
plans/2026-07-25-game-engine-production-roadmap.md	SampleGame 产品阶段、依赖和完成门禁	接口、格式与实现细节
process/spec-driven-development.md	Spec 生命周期、session 协议和验证留证	具体功能设计
specs/README.md	活跃 Spec 注册表与状态入口	重复保存 Spec 正文
references/	外部或历史设计输入的可追溯快照	WaveEngine 规范与实现真值

具体变更只在一个 Spec 中定义。跨领域不变量只放 Architecture，阶段顺序只放 Roadmap，通用设计资料只放 References。

冲突处理

1. 当前实现事实：以源码、CMakeLists.txt 和本次实际验证为准。
2. 本次可实施范围：以匹配 Spec 的状态和正文为准；Draft 不授权生产实现。
3. 长期设计约束：以 Architecture 为准；具体 Spec 若要偏离，必须先显式更新 Architecture 并说明迁移。
4. 优先级和依赖：以 Roadmap 为准，不用路线提案宣称能力已存在。
5. 参考资料：只解释设计来源，不能覆盖以上任何一层。

发现冲突时先修正文档归属或让 Spec 回到 Draft，不能挑选对当前实现最方便的一份。

新 session 阅读顺序

AGENTS.md
  → Architecture
  → Spec 注册表
  → 匹配 Spec 与直接依赖
  → 相关源码 / CMake / 当前验证

References 只在创建或审查相关 Architecture/Spec 时读取，不要求每次 session 重复加载。

更新规则

• 新的已实现能力或边界变化：更新代码、验证和根 README；若影响代理安全工作，再同步 AGENTS。
• 新的跨领域设计不变量：先更新 Architecture，再更新受影响 Spec、模板或门禁测试。
• 新的阶段或依赖：只更新 Roadmap 和注册表中的链接/状态。
• 新的具体实现：创建或复用一个 Full SDD Spec，不把接口细节复制进 Roadmap。
• 新的外部设计输入：原样放入 References，记录来源快照与校验值；项目化结论写入 Architecture/Spec。