# json-regress 项目协作规则

本文件适用于本项目及子目录。遵循当前用户目标；新指示优先于历史计划。较具体的子目录规则补充本文件。

## 入口与任务范围

先读 [当前状态](docs/codex/CURRENT_STATUS.md)，按任务需要读取 [架构](docs/codex/ARCHITECTURE.md)、[接口](docs/codex/INTERFACES.md) 或 [验证](docs/codex/VALIDATION.md)。以目标代码、调用方和实测结果确认当前行为，计划文档不代表已实现。

实现、评审、集成或验证任务使用 [json-regress-engineering](.agents/skills/json-regress-engineering/SKILL.md)。文档小修可直接处理。对非微小任务，在已有任务文件或工作说明中写清一个问题、基线、输入输出、最小验证及成本边界；不强制先创建远程 Issue。

项目目标：低人工投入完成可用的 MoonBit 回归测试库。用户已选择数值数组适配和一个真实机器学习项目接入，世界模型与强化学习作为展示场景。2026-09-15 用户另确认并已完成文件 CLI、标准报告及检查点/比较重放，详见 [路线图](docs/codex/ROADMAP.md) 和 [文件接口](docs/FILE_COMPARISON.md)。模型训练框架、GPU 后端、完整 RL 算法、新的付费资源和大规模训练不属于当前范围。

## 工程不变量

- 保持 JSON 缺失与 null、对象键无序与数组有序、精确路径和路径转义的已公开语义。
- 当前容差为对称的绝对或相对阈值规则，不等同于 PyTorch `assert_close` 的公式。扩展数值数组时复用明确的规则；改变公式、默认值或错误语义需同步接口、调用方和行为测试，不得偷偷放宽以让样例通过。
- 默认数字采用 Double 语义；不得承诺恢复上游已丢失的精度。当前大幅度数字保护及其在 ML 适配中的限制见接口文档。
- 核心保持纯 MoonBit、使用现有 Json 类型；第三方框架、Python 导出器和文件读写放在集成边界，不让核心测试依赖 GPU、网络或训练。
- 区分已有类型/API 与设计候选；`pkg.generated.mbti` 是实际公开接口，不手工编辑。
- 参考值须独立于被测实现，记录来源、版本和生成方法。只用本库自己的输出作为期望值，不能证明跨实现一致性。
- 世界模型固定输入、状态及随机采样条件；RL 明确轨迹时间对齐和终止语义。单次 loss/return 对比不支持算法性能结论。

## MoonBit 工作约定

每个包有 `moon.pkg`；模块元数据在 `moon.mod`。代码块使用 `///|`，黑盒测试用 `_test.mbt`。稳定行为优先 `assert_eq` 等明确断言；结构调试快照使用 `derive(Debug)`，不要为了调试派生 Show。

新增或改变代码/API 时，运行 `moon info`、`moon fmt`，核对生成接口，按 [验证清单](docs/codex/VALIDATION.md) 运行受影响检查。使用 `bash scripts/moon-local.sh <command>` 复用本机工具链，其他机器可直接运行 `moon`。文档、模板和 skill 修改只做相应结构与引用检查，不为了凑记录重复执行无关模型训练或全量测试。

保留用户已有代码和未提交修改。分支默认 `codex/<topic>`；不编造用户名、远程仓库地址或提交 ID，不用空提交、无意义拆分或回填时间凑参赛次数。

用户明确要求至少 **10 个有实际开发价值的 Git 提交**。2026-09-14 已确认 GitHub 登录账号 willzhang，仅为本仓库配置公开署名及 GitHub noreply 邮箱，并将 10 个实时保存的开发阶段形成正式提交；过程见 docs/DEVELOPMENT_HISTORY.md。后续按已验证的内聚改动及时提交，不回填日期、不改写已有阶段来凑数。发布前执行 `python3 scripts/check-commits.py` 并审阅内容；保护原始开发历史，不通过 squash 丢失满足要求的提交。无需用户发送访问令牌。

## 证据与交接

验证状态分别记录：实现、静态检查、单元测试、固定数据、真实项目集成和远程 CI。定义见 [VALIDATION](docs/codex/VALIDATION.md)。当前全库合计 67 项测试，Native/Wasm 均通过；另有 6 项真实 CPU 集成测试在两个后端通过，以及 19 项 CLI 进程验收、6 个实际输出对照和 7 个注错重放。原始 28 项仅是 JSON 核心基线。编写 CI 文件不等于 CI 通过。

有反复试验时追加 [尝试记录](docs/codex/ATTEMPT_LOG.md)，保留失败原因及恢复方法。改变长期方案时更新 [决策](docs/codex/DECISIONS.md)。仅更新本轮改变的状态和契约，不要求每次重写全部文档。

完成授权的可逆本地工作后报告结果、验证范围和剩余问题。正式发布、报名、对外联系和个人资料处理按用户已有授权执行；2026-09-15 用户已授权公开发布仓库与软件包，可持续修复并推送发布所需变更；正式报名、对外联系及个人资料提交尚未授权。官方申报书的本人撰写要求不妨碍准备有明确 AI 标记的参考稿，不把参考稿伪称为本人独立完成。