Skip to main content
Version: MVP

Governance

6 min readCore conceptUpdated 2026-05-19

What you'll learn

  • The governance surface Craik enforces — policy profiles, grants, immutable paths, redaction, receipts, memory defaults.
  • What strict, trusted-local, and automation profiles guarantee.
  • How the policy gate verifies all of this in CI.

Governance

The runtime layer that decides, for every task, what an agent may read, what it may change, which actions need approval, and which actions must leave a receipt.

Craik treats governance as a typed runtime object — not advisory configuration. Policy envelopes, capability grants, and immutable paths are first-class records that participate in case files, handoffs, and the work graph.

The v0.1.0 governance surface​

Policy profiles

Named bundles of defaults — strict, trusted-local, automation — that set the posture for a run.

Capability grants

Explicit, time-bound permissions to perform a specific capability against a specific target.

Immutable path protection

ADR directories and other declared evidence paths can be read and cited, never normally edited.

Fail-open visibility

Fail-open paths are profile-gated and always produce receipts. There is no silent fail-open.

Receipt requirements

Provider calls, credential use, memory writes, and policy decisions all produce receipts.

Redaction requirements

Every persisted receipt and handoff passes through the central redaction guard before storage.

Memory proposal defaults

Agent memory updates default to proposals — never direct writes — unless a memory.write grant exists.

Policy regression tests

The policy contract is itself tested every CI run via craik policy test.

The three policy profiles​

Profile
Posture
When to use it
strict
fail-closed
The default. Allows read-oriented context assembly and receipt writing. Denies file writes, shell execution, GitHub writes, and direct memory writes unless a matching grant exists.
trusted-local
fail-open · opt-in
For tightly-scoped local development. Can fail open only when explicitly requested. Even then, redaction, receipts, immutable path protection, and memory-write approvals are still enforced.
automation
fail-closed
For CI and unattended workflows. Stops rather than widens authority. There is no operator at the keyboard to authorize a fail-open path.

Strict by default​

The runtime picks strict whenever a task doesn't ask for something different. This means:

  • Reads are broad. Repository files, public docs, ADRs, configured memory facts, and read-only GitHub state all flow into case files.
  • Writes are denied. File edits, shell execution, GitHub writes, and direct memory writes require explicit grants.
  • Receipts are mandatory. Provider calls and other governed actions produce receipts the operator can audit.

Trusted-local is narrow on purpose​

trusted-local exists to make local development workable without giving up the rest of the governance surface. See Fail-open for the full authorization checklist and the boundaries it never crosses.

Automation is for machines​

Use automation for any run where there isn't an operator standing by: CI, scheduled gateway runs, webhook ingress. When automation can't proceed, it stops — and writes a receipt that says why. Never widens authority.

The release gate​

craik policy test is the regression harness for the entire governance contract. It runs on every PR and verifies:

  1. Immutable path protection. Edits to ADR directories and other declared immutable paths are rejected, regardless of profile.

  2. Proposal-first memory writes. Without a memory.write grant, every agent-initiated memory update becomes a craik.memory_proposal.

  3. Trusted-local fail-open receipts. When trusted-local takes a fail-open path, a receipt with fail_open: true is sealed.

  4. Automation fail-closed behavior. Automation runs stop rather than widen permissions, and the stop is itself receipted.

  5. Runner grant boundary tracking. Capability grants declared in the policy envelope are the only ones runners may exercise.

  6. Redaction for policy-relevant payload shapes. Receipts and handoffs that touch credentials, tokens, or credential-bearing URLs are scrubbed before persistence.

Where governance lives in the run​

project → policy_envelope → case_file → runner → receipt → handoff
                ▲                        │
                └─ grants the actions ───┘

Every governed action references the envelope it ran under. Every receipt names the envelope id. Every handoff references the receipts. The result is one audit trail you can walk forwards or backwards.

What's next​

ReferencePolicy profilesThe full ruleset for every profile Craik ships.DoAdd capability grantsNarrow, time-bound permissions that compose with strict.ReferencePolicy testsHow the policy gate enforces the governance contract.