OCR Runtime
OCR is the execution governor — not optical character recognition. It is a compiled, self-contained Go runtime that loads project truth, classifies tasks, binds skills to bounded workers, verifies output, and controls writeback before anything touches your repo.
Why OCR exists
OCR stops agent drift during real project work. It gives the agent a project constitution and a loop it must obey — authority is enforced at the binary level, not requested in a prompt.
Agents improvise
They skip files, invent completion, ignore prior constraints, and rewrite the mission unless the work is bounded.
Governed loop
Classify intent, bind a skill, execute bounded work, verify against invariants, then control the writeback.
Traceable execution
The result is not just an answer. It is an auditable state transition with proof attached.
What OCR is
OCR is the Go port of the OCR governed runtime — behaviour identical to the Python reference, but distributable and fast. Five properties define it.
Loads project truth
Reads YAML truth packs from .ocr/ — project identity, constraints, decisions, and ontology — plus current project state.
Deterministic pipeline
Task classification, worker selection, skill binding, and verification run as a deterministic governor, not a prompt suggestion.
Bounded authority
Workers execute narrow tasks but can never define or redefine truth. Authority is enforced at the binary level.
No hardcoded provider
Skill execution delegates to an external LLM through a clean executor interface — provider local, api, or mock.
Zero-dependency deploy
One compiled binary; the only external dependency is gopkg.in/yaml.v3. Cross-compiles to linux and darwin (amd64/arm64).
Go 1.22+
Build once, run anywhere. The governor enforces the rules whether the LLM is local, remote, or mocked.
Runtime loop
Every governed task runs the same five-phase pipeline. The governor — not the worker — decides what happens at each gate.
Intent analysis
The governor maps the task description to a worker role and policy path using heuristics and truth rules.
Truth & skill loading
The runtime loads .ocr/ truth and state, then resolves the skills for the selected worker profile.
Bounded workers
Workers perform narrow tasks via the LLM callback. They can propose changes, but they cannot redefine project truth.
State validation
Nine deterministic check handlers test the output — protected assets, truth conflict, escalation, boot status, and more.
Controlled mutation
On a PASS verdict, candidate writes are cleared against protected assets, truth, and path traversal before disk mutation. Failures enter a bounded repair loop.
Engine capabilities
Every capability below is finalized in the Go engine and tested without a running LLM (mockable).
.ocr/ — YAML-driven, matching the Python truth_loader.py..ocr/skills/.Governor.CheckWritebackPaths clears every target against protected assets, truth, runtime/governor, and path traversal before mutation.deny / escalate gate the writeback; invoke / bind emit telemetry.AI_LOG.md writes.local / api / mock; HTTPS required except loopback, API key mandatory for api.How to use it
Build the binary, then point it at a project. --resume is read-only inspection; --task runs the full classify → bind → execute → verify → writeback pipeline.
$ go build ./cmd/ocr-go
# inspect project status (read-only)
$ ./ocr-go --resume --repo-root /path/to/project
# run a governed task without writeback
$ ./ocr-go --task "Refactor error handling" \
--dry-run --repo-root /path/to/project
# run against a remote API LLM
$ ./ocr-go --task "Refactor error handling" \
--llm-provider api \
--llm-base-url https://api.openai.com/v1 \
--llm-api-key $OPENAI_API_KEY \
--llm-model gpt-4 --repo-root /path/to/project
# onboard a new project (interactive)
$ ./ocr-go --onboard --repo-root /path/to/new-project
local or api for --task.local-model / gpt-4)..)..ocr-go.yaml repo config > built-in defaults. Use .ocr-go.yaml for team defaults and flags for per-run overrides; within config, api_key_env is preferred over a literal api_key.Download the engine
Grab the compiled OCR Go engine console package, unzip, and build with go build ./cmd/ocr-go.
The full OCR governed runtime: governor, executor pipeline, LLM client abstraction, YAML truth loader, interactive onboarding skill, and the cmd/ocr-go CLI entrypoint. Single binary, Go 1.22+.
cmd/ocr-go— CLI entrypointpkg/governor— classify, bind, verify, writebackpkg/executor— task pipeline & repair looppkg/llm— local / api / mock clientsruntime/— governor policies
Ecosystem
OCR governs execution. Its sibling, CRP, governs the reasoning that decides what to execute in the first place.