# CAIN HERMES — Governance Specification

`cain/hermes/spec.py`. Canonical, hashable, versioned organizational intent. Distinct from the contract-authoring
language `cain.gov.source/1`: a GovernanceSpec states what must be true of an autonomous system's behaviour and what
coverage/enforcement is required.

## Objects

- `GovernanceConstraint(dimension, op, value)` — dimensions: budget, time, scope, approval, evidence, consequence,
  environment, delegation, location, jurisdiction.
- `GovernanceRule(rule_id, effect, subject, action, resource, constraints, consequence_ceiling,
  enforcement_targets, evidence_requirements, coverage_requirement, purpose, jurisdiction)`.
  `effect ∈ {PERMIT, DENY, OBLIGE, EXCEPT}`.
- `GovernanceSpec(spec_id, version, tenant, organization, intent, rules, created_at, valid_until, dependencies)`.
- `GovernanceChangeSet` — added/removed/modified rules, broadening/narrowing, `requires_review`.

## Canonicalization and signing

- `semantic_hash()` = SHA-256 over rules normalized and **sorted by rule_id** — independent of declaration order
  and timestamps.
- `digest()` = SHA-256 over the full body; `issue(key)` = domain-separated Ed25519 over `CAIN42/HERMES-GOVERNANCE-SPEC/v1`.
- `verify_spec(rec, pinned_pub=, now=, expected_tenant=)` recomputes digest+signature and rejects duplicate rule ids,
  unknown effects, unknown constraint dimensions, expiry and tenant mismatch.

## Change classification

`diff_specs(old, new)` flags broadening when a consequence ceiling is raised, a constraint is removed, an
enforcement target is removed, or evidence is reduced; adding a rule is broadening. Any broadening requires review.

## Status

IMPLEMENTED, TESTED (`tests/test_hermes.py`).
