Architecture

Two repositories working as one stack: a governance layer and a guarded execution substrate.

The stack

Layer	Repository	Responsibility
CCI (governance)	`codified-context-infra`	Owns contracts, JSON schemas, Claude Code hooks and contract memory. Decides what a task may touch and whether the work is accepted (`cci-contract`).
CCO (execution)	`codified-orchestrator`	The `cco` command. Launches a third-party agent CLI, then enforces the contract on the result and leaves evidence behind.

The two are coupled only by versioned JSON schemas: contract schema 1.0 and outcome schema 1.0. cco schema --json reports what the installed cco accepts.

The guarded run pipeline

 CCI                                  CCO
 ---                                  ---
 cci-contract start
   contract: task, allowed_files, verify_commands
        |
        +--------------------------> cco run --contract-file ...
                                        |
                                        v
                                 preflight (git work tree, clean tree,
                                            executor present)
                                        |
                                        v
                                 baseline snapshot
                                 (HEAD, branch, ignored set, .git hashes)
                                        |
                                        v
                                 sandboxed executor
                                 (claude | codex | opencode | command)
                                        |
                                        v
                                 scope check vs allowed_files (post hoc)
                                        |
                                        v
                                 verify_commands, run by the runner
                                 (no shell, allowlisted, stop on first fail)
                                        |
                              clean and verified?
                               /               \
                            yes                 no
                             |                   |
                           keep              roll back
                                     (rejected.patch saved first)
                               \               /
                                v             v
                         task_outcome.json + execution_envelope.json
                         + phase_events.jsonl  (<home>/runs/<run_id>/)
        <------------------------------+
        |
        v
 cci-contract close  ->  accept or reject, recorded in contract memory

Acceptance is decided by the scope check and the runner's own verification. The agent's report of success is informational only.

Routing ladder

Routing is configured under runner.routing in the home's config.yaml. It is an ordered list of tiers; a task class maps to the tier a run starts on.

Tier - an executor (claude, codex, opencode or command), an optional model, an optional display name, and executor_cmd (required for command).
Display identity - the name is shown instead of the executor type. A command tier named minimax with model MiniMax-M3 appears as minimax:MiniMax-M3, not command.
Classes - classes maps a class name to a start tier index. Every index must be within the ladder or the config fails validation.
Escalation - after a rolled-back attempt whose diagnostic is verify_failed, unexpected_mutation or executor_failed, the run retries at the next tier, up to max_escalations (default 1). The tree is rolled back before the next tier starts.
Budget - max_budget_usd_per_task caps cumulative reported cost; once reached, no further escalation happens.

Example ladder from the routed-minimax profile: minimax:MiniMax-M3 → claude:sonnet → claude:opus. --executor bypasses routing.

Envelope and outcome records

Each run directory under <home>/runs/<run_id>/ contains:

File	Contents
`execution_envelope.json`	How the run was executed: executor, sandbox, target repository. For routed runs, a `routing` object with `task_class`, `tier_index`, every attempt, `escalations` and `stop_reason`.
`task_outcome.json`	Schema `outcome` 1.0: `state` (`ready`, `degraded`, `blocked`, ...), `diagnostic_code`, `next_command`, `verify_ok`, `mutated_files`, `unexpected_mutations`, `rollback_performed`. This is what `cci-contract close` reads.
`phase_events.jsonl`	Timeline of pipeline phases, used by `cco trace` and the observatory.
`rejected.patch`	Present on rollback: the diff that was rejected.

Observatory

cco observatory is a read-only local dashboard on top of the records above. It reads only files the runner already writes and serves on 127.0.0.1:4173 by default.

Run list with state, diagnostic code, executor and model, cost, duration, task excerpt and target repository
Routing ladder per routed run and a phase timeline
Aggregates: kept rate, rollback rate, escalations, cost per executor:model tier
Aborted and stale run detection; stale runs are excluded from rate calculations
Several homes at once with --homes name=path,...

It has no authentication or TLS, and run artifacts can contain source code and prompts. Use an SSH tunnel rather than a public bind.

Security boundaries

Enforcement is post hoc detection plus reversal inside the repository, not prevention.
Runner git calls disable fsmonitor and hooks; tampering with .git metadata is repaired.
.git/**, .github/workflows/**, AGENTS.md and .context/** are protected unless the contract lists them.
Not covered: writes outside the repo, network exfiltration, detached long-lived processes, and content changes inside pre-existing ignored directories. For untrusted tasks, wrap the executor in a container.

What changed from v1.0

Version 1.0 presented CCO as a multi-agent orchestrator with a built-in memory architecture, retrieval tooling and an MCP server. That architecture was retired. CCO 1.1 is the guarded runner described on this page: it launches a third-party coding agent, enforces a contract on the result, and records what happened.

Governance and durable project knowledge now live in codified-context-infra (contracts, schemas, hooks, contract memory) rather than inside CCO. Some other pages of this guide still describe the v1.0 design and are being updated.