Policy governance#
Governance metadata answers who owns a policy and how it is reviewed. It does not grant permissions, authenticate its author, or prove compliance.
Keep the decision and the review separate#
Use metadata for policy version, owner/author and approver records, lifecycle,
review dates, changelog entries, and control mappings. The field shapes are in
core section 2.5.
Validation rejects malformed dates and control references; advisory checks look
for review and separation-of-duties concerns.
h2h validate --strict policy.yaml
h2h audit policy.yaml
h2h diff previous.yaml policy.yamlThe CLI and Rust SDK expose governance findings. Other SDKs validate the shared metadata shape, but do not claim the same advisory API; see SDK API.
A reviewable policy change#
- Change the canonical policy source and its expected decision tests.
- Resolve inheritance and compare the effective policy, not only the YAML diff.
- Run validation, tests, and advisory audit.
- Have an accountable owner approve the changed permissions.
- Sign or bundle the reviewed policy with an operator-controlled key.
- Deploy through a verified loader and retain the resulting policy identity.
A text approver field is not a cryptographic approval. Bind release approval
to the actual resolved digest and retain the separate organizational record.
Control mappings and reports#
A mapping identifies the controls an author associates with rule paths. It is not evidence that the control was enforced on every runtime effect. Reports aggregate observed receipts; strict evidence profiles add bounded experimental checks. Neither replaces an assurance practitioner's judgment about organizational controls, coverage, or applicable obligations.
Retention and privacy#
Policy metadata and decision targets can reveal internal project names and workflow structure. Minimize those fields, use synthetic examples in CI, and set retention/access rules for logs. Keep private signing keys outside the policy repository and rotate them through an explicit keyring lifecycle.