Skip to main content
Version: MVP

Governance Model

7 min readFor policy operatorsUpdated 2026-05-19

What you'll learn

  • The runtime contracts that make governance native — not an enterprise add-on.
  • The default security posture and the three named policy profiles.
  • How capability grants, receipts, redaction, immutable paths, memory policy, and contradictions all compose.
  • How Craik degrades transparently when Stigmem isn't available.

Governance-native runtime.

Policy is not an enterprise add-on; it is part of the runtime contract. Every governed action — file write, shell command, GitHub write, memory write, sandbox decision — runs inside a typed envelope and emits a receipt.

Policy envelope​

Every task runs inside a policy envelope. The envelope is a typed runtime record that travels with the task and defines authority.

Field
Type
Purpose
actor
operator_uri
OIDC operator identity driving the task.
task_scope
scope
Which tasks this envelope authorizes.
repository_scope
scope
Which repositories the actions may touch.
memory_scope
scope
Which memory scopes the run can read or propose into.
allowed_capabilities
capability[]
The explicit allowed actions for this envelope.
write_boundaries
paths
Where writes may land — immutable paths excluded.
required_approvals
capability[]
Actions that require explicit approval before execution.
required_verification
command[]
Validation steps that must run before completion.
documentation_obligations
obligation[]
Doc updates the run must produce or propose.
handoff_obligations
obligation[]
Required handoff fields and self-audit items.

Default security posture​

Secure by default. Fail-open by named policy only.

Fail-open behavior is allowed only through named policy profiles. It should never happen as an accidental fallback. Every fail-open decision is visible in the envelope, the case file, the receipts, and the handoff.

Default behavior: task execution starts read-only · file writes require grants · shell commands require grants · GitHub writes require grants · memory writes default to proposals · immutable paths denied by default · runner adapters cannot bypass Craik grants · plugins start probationary · important actions create receipts.

The v0.1 policy profile implementation generates the envelope directly and provides a mandatory fail-open receipt shape for trusted-local opt-ins. Case files and handoffs preserve those fields when assembled and written.

Policy profiles​

Craik ships three conservative named profiles. Switching between them is a policy decision — never an agent decision.

Strict​

The default profile for normal tasks.

strict.yaml
policy:
  mode: strict
  fail_open: false

Expected behavior: read-only by default · explicit grants for all writes · memory writes become proposals unless direct write is granted · shell commands require grant · GitHub writes require grant · immutable path writes denied.

Trusted-local​

Opt-in profile for tightly-scoped local development.

trusted-local.yaml
policy:
  mode: trusted-local
  fail_open: true
  require_receipts: true

Expected behavior: broader local file and shell access may be allowed · receipts remain mandatory · secrets still redacted · immutable path writes still require explicit override · direct memory writes still require a memory.write grant.

Automation​

Profile for CI and unattended workflows.

automation.yaml
policy:
  mode: automation
  fail_open: false

Expected behavior: deterministic grants · no interactive approval requirement · no broad shell access unless granted · no direct memory writes unless granted · failures stop execution instead of widening permissions.

Capability grants​

Agents do not receive ambient authority. A capability grant is a typed, narrow, time-bound permission.

Field
Type
Purpose
capability
capability_name
The specific authority being granted (e.g. repo.write.docs).
target_scope
scope
What this grant applies to — path globs, remote URIs, memory scope.
allowed_operations
operation[]
read · write · execute · propose.
reason
text
Short, human-readable justification.
expiration
timestamp
When the grant stops being valid.
approval_requirement
approver_uri
Who approved the grant.
receipt_requirement
bool
Whether actions under this grant must produce receipts.

Grant examples: read repository files · write docs only · run tests · inspect GitHub PRs · create GitHub comments · write Stigmem facts in a specific scope.

Secret handling and redaction​

Secrets are toxic runtime data.

They are referenced, not copied. The redaction guard runs before every persistence boundary — and redaction failures are treated as security bugs.

Secret storage: local secrets under ~/.craik/secrets/ by default · environment variables for CI and agent-runner workflows · owner-only file permissions where supported · no secrets in project-local state.

Redaction requirements: centralized in craik.runtime.policy.redaction · scrubs known tokens, API keys, bearer headers, auth URLs, and configured patterns · applied before writing logs, receipts, handoffs, case files, memory proposals, errors, and work-graph events · preserves enough shape to debug without exposing raw values · local persistence rejects payloads that still appear to contain unredacted secret material.

Secrets must not be written to Stigmem facts.

Capability-gated actions​

The following actions require explicit grants:

File writes

File deletion

Shell execution

Git branch mutation

Git commit

Git push

GitHub issue / PR / comment

Stigmem direct fact writes

Contradiction resolution that invalidates facts

Plugin execution with side effects

Runner actions that invoke non-read-only tools

Read-only actions may still require grants when they could expose sensitive data.

Immutable path protection​

Project profiles can declare immutable paths — ADR directories, signed release artifacts, generated audit records, historical migration records. Immutable paths are denied by default.

A write to an immutable path requires all of:

  1. Explicit immutable-path override metadata.
  2. User or maintainer approval (recorded in the override).
  3. A capability receipt sealed at the action site.
  4. A handoff note explaining why the override was used.

In v0.1 grant checks, override metadata must include who approved the override and why. The override is still denied unless a matching repo.write.immutable grant is present.

Capability receipts​

Important actions produce receipts. Receipts are not log lines — they're concise accountability records for actions that matter.

Receipt fields: receipt id · actor · task id · capability · target · reason · input summary · result summary · timestamp · policy envelope id · links to artifacts.

Receipts must record when a task runs under a fail-open policy profile or when a capability grant widens access beyond strict defaults.

The v0.1 receipt store persists validated craik.capability_receipt records and exposes local lookup through craik receipts list and craik receipts show. Receipts link directly to tasks and can link to policy envelopes and handoffs through redacted result metadata.

Memory write policy​

Memory writes are classified by source so policy can decide what may act directly versus what must propose.

Class
Source
Typical handling
observed
direct
Seen in repo, tool output, API response, or artifact. May be acted on directly under policy.
reported
testimonial
Stated by a user or agent. Treat as a lead until confirmed.
inferred
derived
Reasoned from evidence. Confirmation required before durable action.
policy
governance
Sourced from ADRs, repo rules, or governance docs. Durable; act on.
external
third-party
Web or package-registry sources. Time-sensitive.
stale-risk
aging
Likely to change. Refresh via freshness probe before use.

Human overrides​

Human overrides create durable records. An override captures what was overridden · who overrode it · why · what evidence or policy applies · what downstream facts or tasks are affected.

Contradictions​

Contradictions are not silently resolved by last-write-wins. Craik surfaces conflicting assertions · source and confidence for each · affected tasks · affected docs · proposed resolution · required reviewer or owner.

Degraded mode​

Craik may run without Stigmem, but governance features should degrade transparently — and the product is explicit about unavailable capabilities.

With Stigmem

  • Durable facts with provenance.
  • Cross-scope contradiction tracking.
  • Federation between Stigmem nodes.
  • Trust tiers enforced.

Without Stigmem

  • Facts are local or ephemeral.
  • Contradiction tracking is local only.
  • Provenance may be limited.
  • Federation is unavailable.
  • Trust tiers may be advisory.

Local state governance​

Craik uses ~/.craik as the default local home, with CRAIK_HOME as the primary override. Local state keeps data classes separated.

config/

User-editable configuration.

secrets/

Local credentials and tokens (owner-only).

state/

SQLite databases and durable runtime state.

cache/

Disposable data.

logs/

Runtime logs.

receipts/

Capability receipts.

handoffs/

Durable handoff artifacts.

case-files/

Assembled task context.

projects/

Project registry metadata.

Security expectations: home and secrets paths should be owner-only where supported · secret values must not appear in receipts, logs, handoffs, or case files · path commands make active local paths inspectable · project-local .craik/ directories are explicit opt-in only.

What's next​

ReadGovernance conceptThe same model from the runtime side — how the pieces fit together.ReferencePolicy profilesThe full ruleset for every profile Craik ships.ReferencePolicy testsThe CI gate that verifies this contract on every PR.