Contract YAML reference

The canonical contract YAML lives in aprender:

Pin format:

[pin]
aprender_commit = "16f25af06"
aprender_pr = 1078
aprender_pr_state = "OPEN"
contract_sha256 = "..."
last_synced = "2026-05-02"

Top-level structure

schema_version: "1.32.0"
name: "claude-code-parity-apr-v1"

gates:
  FALSIFY-CCPA-001:
    name: "trace_schema_roundtrip"
    status: "ACTIVE_RUNTIME"
    description: "..."
    asserted_by:
      - "crates/ccpa-trace/tests/falsify_ccpa_001_roundtrip.rs"

  FALSIFY-CCPA-NNN: { ... }

trace_schema:
  version: 2
  records:
    session_start: { ... }
    # ...

per_tool_equivalence:
  Bash: { ... }
  Read: { ... }
  Write: { ... }
  # ...

sovereignty:
  allowed_network_endpoints:
    - "127.0.0.1:*"
    - "localhost:*"
  forbidden_env_vars:
    - "ANTHROPIC_API_KEY"
    - "OPENAI_API_KEY"
    # ...

Validation — pv validate

pv is the dogfooded contract validator (aprender-contracts-cli). It enforces:

  • Schema correctness (every gate has the required fields)
  • Cross-reference correctness (asserted_by files exist)
  • Pin correctness (contracts/pin.lock's sha256 matches the aprender source at the pinned commit)
pv validate contracts/claude-code-parity-apr-v1.yaml
pv pin-check contracts/pin.lock --aprender-path ../aprender

CI runs both on every PR (FALSIFY-CCPA-012).

Adding a new gate

The M22 5-step ritual:

  1. Propose — add the gate to the canonical aprender YAML at PROPOSED status. Open an aprender PR.
  2. Test — write the falsifier test in the corresponding crate of this repo. PR against this repo.
  3. Mirror — update contracts/pin.lock to the new aprender commit. PR (mechanical).
  4. Verify — CI runs pv validate + pv pin-check + the new falsifier test on every PR. Both must be green.
  5. Promote — once the test passes deterministically, flip status to ACTIVE_ALGORITHM_LEVEL (or ACTIVE_RUNTIME if backed by a measured discharge). PR.

Adding gates without all 5 steps is rejected. The ritual is pv validate-asserted; bypassing it is mechanical impossible.