Enforcement levels

Oka’s intelligence compounds only when agents consistently emit events and query context. Three enforcement levels offer increasing compliance guarantees.

Level 1: Soft (CLAUDE.md)

Compliance: ~40-60%

Instructions in CLAUDE.md, .cursorrules, or equivalent. The agent follows them most of the time.

## Oka Reason

- Start every task with context() for the relevant area
- Record decisions with decision(), not just observe()
- Call done() when finishing with outcome notes

Pros: Zero setup, no code changes, works with any client.

Cons: Agent may ignore instructions, especially on long sessions or complex tasks. No enforcement mechanism.

Best for: Solo developers, early adoption, low-stakes projects.

Level 2: Medium (hooks + prompts)

Compliance: ~70-85%

Use client hooks to auto-inject Oka calls:

• Session start hook: Automatically calls context for the current project area when an agent session begins
• Post-task prompt: Reminds the agent to record decisions and observations before completing work
• Pre-commit hook: Checks that at least one decision or observe was called before allowing a commit

Example Claude Code hook (.claude/hooks/session-start.sh):

#!/bin/bash
echo "MANDATORY: Call context() for the area you're about to work on before starting."

Pros: Transparent to the agent, higher compliance, still no code changes to @oka-core/reason.

Cons: Hooks are client-specific. Not all MCP clients support hooks. Agents can still skip the prompted actions.

Best for: Teams that want higher compliance without infrastructure changes.

Level 3: Hard (server-side gating)

Compliance: ~95%+

@oka-core/reason tracks whether context() has been called in the current session. If not, write tools (decision, observe, done) return an error prompting the agent to call context() first.

This ensures every agent session both reads from and writes to the intelligence layer. The data flywheel becomes self-sustaining.

Configuration:

Set the OKA_ENFORCEMENT environment variable:

{
  "mcpServers": {
    "oka": {
      "command": "npx",
      "args": ["-y", "@oka-core/reason"],
      "env": {
        "OKA_ENFORCEMENT": "hard"
      }
    }
  }
}

Pros: Near-complete compliance. Every session contributes to and benefits from organizational intelligence.

Cons: Adds friction — agents must call context before they can record anything. May slow down trivial tasks.

Best for: Teams that have validated Oka’s value and want to maximize data capture. Production engineering teams where missing context has caused incidents.

Choosing a level

Scenario	Recommended
Solo developer, exploring Oka	Soft
Small team, early adoption	Soft with hooks
Team that’s validated Oka’s value	Medium
Org-wide rollout, critical codebase	Hard
Onboarding new team members	Hard (they benefit most from context)

Start with Soft. Move to Medium when you see the value. Move to Hard when the team consensus is “we should never skip this.”