参与贡献

阅读顺序

AGENTS.md 规定按顺序阅读，每份文档回答一个问题：

#	文档	回答
1	`AGENTS.md`	Entelechy 是什么，规则是什么
2	`README.md`	从外部看它是什么样
3	`ARCHITECTURE-PLAN.md`	工作处于哪个阶段，验收标准是什么
4	`CORE-ARCHITECTURE.md`	边界在哪里
5	`docs/TYPED-FIELD-ARCHITECTURE.md`	为什么只有一种资源
6	`IMPLEMENTATION.md`	代码及其证据在哪里
7	`PROCESS.md`	如何编写、验证、提交和交接
8	`HANDOFF.md`	仓库现状与下一步行动

按问题查：Kernel/场景怎么写 → docs/DOCUMENTS.md；什么命令 → docs/USAGE.md；Agent 发什么 → docs/PROTOCOL.md；骨骼是哪些行 → docs/RIGS.md；Kernel 能调用什么 → entelechy help；为什么这样 → docs/DECISIONS.md。

仓库状态是权威。 不依赖上一次会话的记忆。

代码原则

Host → ABI → IR → Kernel Runtime → Graph Runtime

尊重分层，不为方便而绕过。一个模块一个职责；避免上帝对象、隐藏全局、跨层辅助函数。
每个状态有一个所有者，每条规则也只有一个。发现有两个所有者的规则，收归一个，并由编译器或 crates/interface/entelechy/tests/owners.rs 中的一行保证。
不要静默地从无效运行时状态恢复；返回有意义的错误。热重载失败时保留上一个有效 Kernel。
稳定边界：Capability ABI、Entelechy IR、KernelID、序列化图格式——有意识地修改并测试兼容性。
语言与场景语法只因所有者的决定而增长；写作中的摩擦用函数、包或示例解决。

格式是自动的，架构是有意的。

注释与文档

注释或文档陈述当前事实：它是什么，谁拥有它，保证什么。历史归 git，原因归 docs/DECISIONS.md。不写“曾经”“不再”，不写叙事、比较、含糊或带日期的观察。一个事实一个位置。写入仓库的一切都用英文（对话可以是任何语言）。

Git

main 是主线。在聚焦的 feat/*、fix/*、refactor/*、docs/*、test/*、chore/* 分支上工作，一轮工作一个分支。
一个分支只占 Rust 构建与其上运行之物分界线的一侧：IR/编译器/后端（crates/core、crates/frontend、crates/backends）一个分支；其余 Rust 一个分支；只有 .ent、.esn、回放与文档的改动第三种。
小而有逻辑的英文提交（feat: add kernel registry）。记录实际验证了什么，包括局限。
本地提交的授权不等于推送、合并或发布的授权。 合并回 main 由用户决定，fast-forward。未经要求不得 force-push 或改写历史。

验证：`cargo xtask verify`

cargo xtask verify
tail -f target/verify.log

xtask 按顺序运行（互不依赖的步骤并行）：

fmt，然后 packages（每个包的命名、布局、分层，以及每个 Kernel 都被自己的测试覆盖），然后 clippy（所有目标）、clippy-wasm、clippy-page，警告即错误；
test-build；
tests 与 bridges；
release 构建；
replays、wasi、against_main：
- replays 用 release 构建在每个后端上运行所有示例和包的回放，再以 --small 0、--no-fusion、--round-apart 各跑一遍；
- wasi 构建 WASI 版本并检查 stdin 会话与读写文件的回放；
- against_main 用 main 和分支的构建分别运行每个示例，比较 check、graph（计划）与图片——每个差异都必须是分支有意为之的。

日志以被验证的提交开头，以 passed 结尾。

交接（HANDOFF）

HANDOFF.md 只包含两件事：Context（Agent 行动需要的事实与已验证的面）和 Next（一个可执行的行动及其验收标准）。替换过时内容，不写日记。结束会话前：检查 diff，运行检查，替换 Next。