Skip to main content

Codex Rule Ledger

Evidence-bound audits for Codex runs: support, contradict, or admit the evidence cannot decide.

Open source (MIT) · TypeScript · 77 unit and contract tests plus five Chromium E2E flows, all green · Submitted to OpenAI Build Week 2026 (Developer Tools), judging in progress.

The problem

A diff shows what an agent changed, not whether the captured Codex session actually supports the run’s validation claims. Confusing missing evidence with compliance admits an unverified "done"; confusing it with failure rejects real work that simply was not captured. Teams accept, investigate, or block agent-produced changes with no honest read on what the evidence can and cannot decide.

Rule Ledger reconstructs the global-to-launch-directory instruction chain from a launch capture, then reports each rule as SUPPORTED, CONTRADICTED, NOT_EVIDENCED, or NOT_APPLICABLE, each with exact source links and evidence records. Before asking whether a rule passed, it asks whether the supplied evidence makes any verdict admissible at all. It ends in a deterministic SHA-256 hash-bound JSON export labeled LOCAL_CAPTURE_UNATTESTED. It reports supplied evidence; it does not certify compliance or authenticate a trace.

Quickstart

The audit runs locally and deterministically. Recorded mode is keyless: no API key, no upload, no private repository. Requires Node.js 22.13+ (22.x) or Node.js 24+.

Clone and install:

git clone https://github.com/OrionArchitekton/codex-rule-ledger.git
cd codex-rule-ledger
npm ci

Command surface

  • npm run dev: The keyless recorded-case explorer: switch between two disclosed synthetic cases, read the reconstructed instruction chain, inspect each verdict’s source links and evidence, and export the hash-bound ledger.
  • npm run audit: The v0.2 local CLI over an already-normalized Audit Bundle directory. Recorded mode is the keyless default; explicit --live mode uses one GPT-5.6 request and reads OPENAI_API_KEY only from the environment, never from an argument.
  • npm test: 77 unit and contract tests across the deterministic audit core, the analyzer adapters, and the route contract.
  • npm run test:e2e: Five Chromium E2E flows exercising the case-switch, inspect, and export path at desktop and mobile widths.
  • npm run verify: The full local proof: lint, typecheck, all 77 unit and contract tests, the production build, and the five Chromium E2E flows.

Why it is different

  • Evidence sufficiency comes first: Before asking whether a rule passed, Rule Ledger asks whether the supplied evidence makes any verdict admissible. NOT_EVIDENCED is neither pass nor fail: it means only that the capture lacks sufficient evidence, and it is never treated as proof of non-action.
  • Deterministic TypeScript owns every verdict: GPT-5.6 only proposes semantics, and its output is treated as untrusted data. Deterministic code checks that every exact command, conditional path, polarity, and trigger is entailed by the cited quote. An unknown source anchor, a refusal, malformed semantics, or a timeout fails closed. The model never owns a ledger state, instruction discovery, or a hash.
  • Four honest states, plus a human lane: Results are SUPPORTED, CONTRADICTED, NOT_EVIDENCED, or NOT_APPLICABLE. Subjective, unbounded, or non-observable instructions are declined and routed to human review rather than forced into a mechanical pass or fail.
  • Hash-bound, keyless, recorded-case-only: Every audit ends in a canonical SHA-256-bound JSON export labeled LOCAL_CAPTURE_UNATTESTED. The public demo exposes exactly two disclosed synthetic fixtures with no upload, no key, and no captured-command execution. Hashes bind the supplied bytes; they do not certify compliance or authenticate a trace.

Links