Forge Covenant

Forge Covenant 是一个面向长期 Agent 工作流的、确定性的项目级意图与执行治理包验证器。当前版本实现了 Phase A：结构与完整性验证边界，所有验证均为只读操作。

它解决什么问题

长期 Agent 任务会跨越多轮对话、多个执行者、不同机器和中断恢复点。仅靠自然语言约定，常见结果是：目标逐渐漂移、同一文件被不同方式解释、审批与产物失去绑定、运行状态无法追溯，以及交接后无法证明“接手的是不是同一份任务”。

完整 Covenant 方案的目标，是把这些隐含约定编译成显式、可审查的 Covenant 文档。当前 Phase A 不负责生成或修订文档，而是接收已经形成的治理包，对其中的文档、引用、依赖关系、事件链、运行时状态和磁盘快照进行确定性验证。它回答的不是“这项工作做得好不好”，而是更基础的问题：

当前看到的意图、证据和运行状态，是否组成同一份结构合法、引用一致、未被无声替换的治理包？

核心竞争力

Forge Covenant 最重要的竞争力不是某一种哈希或某一个 Schema，而是把下面这些能力组合成一条端到端、默认拒绝歧义的验证边界：

1. 同一输入必得同一结论：从严格 JSON、规范化字节、固定校验顺序到不可变报告，结果不依赖解析器宽容度、对象插入顺序或机器上的偶然状态，适合审计、复现和跨 Agent 交接。
2. 同时区分“字节相同”和“语义相同”：精确字节哈希保护原始产物，Schema 约束下的语义哈希识别有效载荷；哈希类型被显式记录，避免把文档、产物、状态或清单的摘要混用。
3. 验证整个治理包，而不只是单个文件：除了字段形状，还检查 ID、引用、授权绑定、依赖图、机械可满足性、事件链、提交前缀以及运行时交叉哈希，能够发现“每个文件单独合法，但组合起来互相矛盾”的问题。
4. Windows 文件系统是一等公民：主动处理大小写碰撞、保留设备名、ADS、重解析点、根目录逃逸和读取期间文件变化等真实风险，而不是把 POSIX 假设直接套到 Windows Agent 环境。
5. PASS 的含义严格封闭：版本目录、文档类型、哈希类型和保证范围都采用显式注册；未知内容不会被猜测为兼容。报告只承诺 Phase A 已验证的结构与完整性，不把记录存在误报成审批真实或生命周期动作已经执行。
6. 只读且零第三方运行时依赖：验证器不修改项目，仅使用 Python 3.12 标准库，部署面、供应链风险和嵌入成本都较低。

普通 JSON Schema 主要验证单文档形状，Git 主要记录字节历史，独立哈希脚本只能证明某段字节没有变化，工作流引擎则侧重执行。Forge Covenant 的差异在于把这些层之间的绑定关系也纳入同一份确定性证据模型。当前 Phase A 因此更像一层“可信地基”，而不是已经完成的全生命周期治理平台。

当前能力

• 在安全整数域内严格解析 UTF-8 JSON；
• 在 Covenant 限定的 JSON 域内执行 RFC 8785 规范化序列化；
• 提供精确字节 SHA-256 与带类型元数据的规范语义 SHA-256；
• 提供封闭的 Covenant 0.1.0 Schema 目录与已注册文档类型；
• 检查规范化清单、哈希、ID、引用、授权绑定、依赖图和机械可满足性；
• 验证 decision、audit、change 链完整性，以及显式提交前缀；
• 检查 state、checkpoint、capability 和 transaction 的结构与交叉哈希；
• 采用 Windows 优先的根目录约束、重解析点拒绝、稳定文件快照和确定性的 ArtifactSelector 展开；
• 生成不可变的规范化验证报告，并提供只读包验证 CLI；
• 仅依赖 Python 3.12 标准库，测试结果可确定复现。

Phase A 的边界

Phase A 的 PASS 仅表示通过 phase_a_structural_and_integrity 范围内的结构与完整性检查。

当前版本不会：

• 验证审批者身份或审批真实性；
• 创建、修改或修订 Covenant 包；
• 判断状态转换是否合法；
• 执行 compare-and-swap 提交；
• 回放账本或恢复事务；
• 应用迁移；
• 开展语义审计；
• 执行交付门禁或渲染交付物。

此外，解析器会在规范化之前拒绝小数和指数形式的数字 token，因此项目不会宣称完整覆盖 RFC 8785 的全部数字测试向量。

仓库结构

forge-covenant/
├── SKILL.md
├── agents/openai.yaml
└── scripts/
    ├── covenant_core/
    ├── tests/
    └── validate_package.py

本地编排记录、模型配置快照和评审笔记不会进入公开仓库。

环境要求

• Python 3.12
• 无第三方运行时依赖

运行测试

在 forge-covenant/scripts 目录中运行：

python -B -m unittest discover -s tests -v
python -B -m unittest tests.test_phase_a_integration -v

使用只读 CLI

验证规范化夹具：

python -B .\validate_package.py --project-root .\tests\fixtures\phase_a\valid_canonical --mode canonical

执行完整 Phase A 验证：

python -B .\validate_package.py --project-root .\tests\fixtures\phase_a\valid_full --mode full

CLI 会向标准输出写入且只写入一份规范化 JSON 报告，并以 LF 结尾。它不提供 fix、apply、migration、recovery 或输出文件选项。

退出码	含义
0	在 Phase A 范围内验证通过
1	内容无效
2	输入或环境条件导致验证被阻断
5	验证器内部缺陷

Python API

公开 Python 包导出以下验证接口：

• validate_document_bytes
• validate_decisions_jsonl_bytes
• extract_semantic_payload
• validate_package_snapshot
• validate_package
• ValidationIssue
• ValidationReport

同时也会导出严格 JSON、哈希、版本和路径相关 API。

安装本地 Skill

将 forge-covenant 目录复制到：

$CODEX_HOME/skills/forge-covenant

如果没有设置 CODEX_HOME，请使用当前用户对应的 Codex Skills 目录。安装或更新后重启 Codex，使新的 Skill 元数据生效。