# utsapoddar/dopa-kernel architecture

> Architecture diagram of the GitHub repository utsapoddar/dopa-kernel, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/utsapoddar/dopa-kernel
- Repository: https://github.com/utsapoddar/dopa-kernel
- Video tour (about a minute): https://gitdiagram.com/utsapoddar/dopa-kernel/video

## Overview

DopaKernel is a semantic controller for AI coding agents: it freezes a goal into verifiable requirements, selects actions from recorded progress, tracks mutation outcomes, and withholds completion until current evidence satisfies the contract. The main route is the `decide.py` CLI; Claude hooks additionally gate tool mutations and turn completion. The README documents the contract and hook behavior, while sampled source supports the state, policy, verification, and gate connections shown. Other unsampled capabilities are represented only where the README establishes them.

Main entry points: [`kernel/decide.py`](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/decide.py) (Controller CLI), [`kernel/model.py`](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/model.py) (Goal State), [`kernel/gate_decide.py`](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_decide.py) (Mutation Gate), [`kernel/gate_tests.py`](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_tests.py) (Completion Gate)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Goal Workflow"]
  node_contract["Goal Contract<br/>[goal-contract.md]"]
  node_cli["Controller CLI<br/>[decide.py]"]
end

subgraph group_kernel["Decision Kernel"]
  node_state[("Goal State<br/>[model.py]")]
  node_policy["Action Policy<br/>[policy.py]"]
  node_evaluator["Evidence Evaluator<br/>[evaluator.py]"]
end

subgraph group_hooks["Claude Hooks"]
  node_pretool["Mutation Gate<br/>[gate_decide.py]"]
  node_stop["Completion Gate<br/>[gate_tests.py]"]
end

subgraph group_guidance["Agent Guidance"]
  node_adapter["Claude Adapter<br/>[SKILL.md]"]
  node_skill["Kernel Guidance<br/>[SKILL.md]"]
end

node_user(("User"))
node_agent(("Coding Agent"))
node_claude["Claude Code"]
node_workspace["Target Workspace"]

node_user -->|"sets objective"| node_agent
node_agent -->|"writes contract"| node_contract
node_agent -->|"runs commands"| node_cli
node_cli -->|"starts or updates"| node_state
node_cli -->|"selects action"| node_policy
node_policy -->|"reads and saves"| node_state
node_cli -->|"verifies or evaluates"| node_evaluator
node_evaluator -->|"runs verifier"| node_workspace
node_evaluator -->|"records evidence"| node_state
node_cli -->|"records outcome"| node_workspace
node_claude -->|"sends tool event"| node_pretool
node_pretool -->|"checks goal state"| node_state
node_pretool -->|"rechecks selection"| node_policy
node_pretool -->|"allows or blocks"| node_claude
node_claude -->|"requests stop"| node_stop
node_stop -->|"evaluates completion"| node_evaluator
node_stop -->|"checks active goal"| node_state
node_stop -->|"allows or blocks"| node_claude
node_agent -.->|"loads guidance"| node_adapter
node_adapter -->|"routes to"| node_skill
node_skill -->|"explains workflow"| node_agent

click node_contract "https://github.com/utsapoddar/dopa-kernel/blob/main/reference/goal-contract.md"
click node_cli "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/decide.py"
click node_state "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/model.py"
click node_policy "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/policy.py"
click node_evaluator "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/evaluator.py"
click node_pretool "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_decide.py"
click node_stop "https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_tests.py"
click node_adapter "https://github.com/utsapoddar/dopa-kernel/blob/main/adapters/claude/SKILL.md"
click node_skill "https://github.com/utsapoddar/dopa-kernel/blob/main/SKILL.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_contract,node_cli,node_user toneBlue
class node_state,node_policy,node_evaluator toneAmber
class node_pretool,node_stop toneMint
class node_adapter,node_skill toneRose
class node_agent,node_claude,node_workspace toneIndigo
```

## Components

### Goal Workflow

- [Goal Contract](https://github.com/utsapoddar/dopa-kernel/blob/main/reference/goal-contract.md): `reference/goal-contract.md`
- [Controller CLI](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/decide.py): `kernel/decide.py`

### Decision Kernel

- [Goal State](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/model.py): `kernel/model.py`
- [Action Policy](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/policy.py): `kernel/policy.py`
- [Evidence Evaluator](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/evaluator.py): `kernel/evaluator.py`

### Claude Hooks

- [Mutation Gate](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_decide.py): `kernel/gate_decide.py`
- [Completion Gate](https://github.com/utsapoddar/dopa-kernel/blob/main/kernel/gate_tests.py): `kernel/gate_tests.py`

### Agent Guidance

- [Claude Adapter](https://github.com/utsapoddar/dopa-kernel/blob/main/adapters/claude/SKILL.md): `adapters/claude/SKILL.md`
- [Kernel Guidance](https://github.com/utsapoddar/dopa-kernel/blob/main/SKILL.md): `SKILL.md`

### Other components

- **User**
- **Coding Agent**
- **Claude Code**
- **Target Workspace**

## Connections

- User → Coding Agent: sets objective
- Coding Agent → Goal Contract: writes contract
- Coding Agent → Controller CLI: runs commands
- Controller CLI → Goal State: starts or updates
- Controller CLI → Action Policy: selects action
- Action Policy → Goal State: reads and saves
- Controller CLI → Evidence Evaluator: verifies or evaluates
- Evidence Evaluator → Target Workspace: runs verifier
- Evidence Evaluator → Goal State: records evidence
- Controller CLI → Target Workspace: records outcome
- Claude Code → Mutation Gate: sends tool event
- Mutation Gate → Goal State: checks goal state
- Mutation Gate → Action Policy: rechecks selection
- Mutation Gate → Claude Code: allows or blocks
- Claude Code → Completion Gate: requests stop
- Completion Gate → Evidence Evaluator: evaluates completion
- Completion Gate → Goal State: checks active goal
- Completion Gate → Claude Code: allows or blocks
- Coding Agent → Claude Adapter: loads guidance
- Claude Adapter → Kernel Guidance: routes to
- Kernel Guidance → Coding Agent: explains workflow