Operator Control Plane

What Operator Control Plane Is

A local-first control plane for AI coding work. Its center of gravity is a repository-local ledger that records claims, evidence, verification, and the doctor audit trail. It is a trust record for work, not a generic workspace or hosted service.

The roles are distinct:

Quickstart

pip install -r requirements.txt        # runtime: just PyYAML
pip install -r requirements-dev.txt    # tests/lint: pytest, ruff, black, isort
./operator --help

mkdir /tmp/operator-demo && cd /tmp/operator-demo
/path/to/operator init                 # creates .operator/ ledger in current dir
/path/to/operator doctor               # consistency check → "All records consistent."

python3 -m pytest tests/test_operator.py -q   # repo CLI, ledger layout, identity, doctor, usage
python3 -m pytest tests/ -q                     # everything (some suites need Linux)

The ledger (.operator/) is gitignored — it's your work history, not the tool. Its durable local event history is stored in .operator/ledger.sqlite3.

The Trust Model

Operator enforces a strict partition: an agent's claim ("I did X") is only trustworthy if it has evidence attached and is verified by a distinct identity. The system records: task → claim → evidence → verification → session → usage.

The handoff, not the blur

Work is not trusted until it passes from builder output into verifier judgment. Doctor keeps checking the result afterward — it is a continuing audit, not the step that creates trust.

Work → Builder → Draft claim + Evidence → Verifier → Trusted record → Doctor (ongoing)

Draft vs. verified — different thresholds

The same problem (e.g., missing evidence) is warning-level on a draft but a blocking failure on a verified record. A warning on draft material is not proof that the trust boundary has failed.

Core Workflow

The everyday loop is the local path. By default, the product stays local:

1. Task creation — open a task with an objective, optional assignee and reviewer.
2. Claim registration — a builder registers a typed, gate-bound claim (e.g., test_passes, file_exists, numeric_measurement).
3. Evidence attachment — local files are copied into the ledger and fingerprinted with SHA-256, byte size, and modification time.
4. Verification — a different OS UID than the claim author writes status-bearing evidence.
5. Doctor audit — read-only consistency check across the ledger.
6. Session tracking — track coding session and cost, then close out with a handoff brief.

What the daily loop looks like

# Open a task
./operator task-create --objective "Add retry to the uploader" --id up-retry

# Builder registers a claim
./operator claim-add --task up-retry --type test_passes \
    --text "uploader retries 3x on 5xx" --gate tests/test_upload.py

# Evidence + advisory verification
./operator evidence-attach tests/out/upload.log --task up-retry --claim claim-0001 \
    --type test_output --status verified --verified-by reviewer \
    --verify-cmd "pytest -q tests/test_upload.py"

# Doctor reads the record
./operator doctor

# Track session cost, generate handoff
./operator session-start --task up-retry --harness claude
./operator session-end usage-0001 --outcome useful --cost 12.50
./operator handoff-add --task up-retry --changed "uploader.py" --verified "retry test" --open "tune backoff"
./operator export-brief --for codex --task up-retry

A runnable version of this lives at examples/verified-work/run.sh and is executed on every CI run.

Verified facts

• The local claim path writes a draft record with verification still false. Draft output can warn about the same problems that would block a verified record, but only verified records are enforced.
• Evidence attachment copies local files into retained, hashed snapshots — not just a status write.
• Doctor is not a repair tool. It is an audit that returns failure only when issues exist on verified records; warnings on drafts do not make the run fail.
• In enrolled mode, ordinary builder and verifier actions are role-separated, while root-only enrollment and rebind are separate privileged requests.
• A negative verifier write can reopen a task that had been closed.

Ledger Governance

The ledger is the product's memory: it decides what work exists, which evidence supports it, and what can be trusted later.

What is durable, what is not

Store replacement is never silent

When the authority store or projection layer has been replaced, the system does not silently adopt the new incarnation. It requires explicit reset acknowledgment:

1. New store incarnation appears → system detects mismatch
2. System asks for explicit reset acknowledgment
3. After acknowledgment: resets sequence progress, drops prepared work tied to old store
4. Retries prepared broker work idempotently

Recovery is not repair

Doctor reports divergence but does not silently repair either side. A changed verified source or retained snapshot fails closed; an unavailable original source is reported separately when its retained snapshot is still current. Remote evidence without a local snapshot is explicitly uncheckable.

When to Use Enrolled Authority Mode

Enrolled authority is an optional privileged layer above the repo-local ledger. It matters when you need a separate host-managed trust boundary, not just local claim and evidence tracking.

The tradeoff

What enrollment does

• Broker becomes the authority boundary for durable trusted-state changes
• Ordinary commits remain role-gated (builders → claims, verifiers → sign-off)
• Read-only snapshots stay separate from mutating commits
• Reconciliation refuses to silently adopt a replaced store
• Enrollment is pinned to a fixed registry path — a moved or altered repository does not silently inherit authority

What enrollment does not do

Operating Safely and Recovering Cleanly

Recovery follows the boundary that failed. Don't treat every stop the same way.

Recovery principles

• Privilege comes first. The admin surface is root-only and stops until host preflight passes.
• Enrollment lookup is pinned. Fixed registry path + absolute repository/socket paths. Changed identity = error, not silent inheritance.
• Reconciliation is guarded. Explicit acknowledgment → reset progress → drop old work → retry idempotently.
• Checkpointed replay is bounded. Only replays completed phases when the saved plan fingerprint still matches.

What looks solid

• Privileged administration is root-only and host-gated
• Enrollment does not accept a casually moved registry entry
• The broker keeps read-only snapshots separate from mutating commits
• Reconciliation does not silently swallow a replaced store
• Study plans are catalog-validated; mutating phases require approval; quota exhaustion pauses (doesn't skip) the run

Harnesses, Delegation, and Study Work

These are support paths, not a trust model

Harness and study work freeze a concrete execution shape. They make a run more specific by binding it to named harness profiles and explicit phases. But this structure is support infrastructure, not a replacement for the ledger's claim-evidence-verification story.

Three execution surfaces

What is proven, what isn't

Command Reference

The operator CLI exposes ~23 subcommands across the task → claim → evidence → verification → session → usage lifecycle. Run ./operator <command> --help for full flags.

Setup

Tasks

Claims

Claim types: file_exists, test_passes, numeric_measurement, real_data, model_output, firmware_behavior, deployment_state, supervision_credit, paper_or_report_claim

Evidence & Verification

Evidence types: run_log, manifest, database_query, test_output, git_commit, screenshot, transcript, paper_section, external_doc, session_crystal

Sessions

Usage / Quota

Briefs & Handoff

Headless Delegation

./delegate-brief --task ID --brief FILE --harness {claude,codex,grok,gemini-agy,fable,openrouter} [options]
# Preserves brief under --deliver/.brief.md, optional --freeze path hashes, full log + exit code
# --record writes an Operator handoff (dispatch outcome only, not acceptance)

Configuration

Operator is driven by files under .operator/ (created by init):

.operator/identity.yaml — Identity-enforcement policy

mode: enforced          # or: single_user (advisory)
uids:
  1001:
    name: builder
    roles: [builder]
  1002:
    name: reviewer
    roles: [verifier]

In enforced mode, a verification only counts when the verifier's OS UID differs from the claim author's. A different harness name buys nothing. Two agents under one Unix user are one identity.

In single_user mode, status writes remain available and are recorded as advisory, never uid_isolated. A "verified" status is advisory — the builder's own assertion, not an independent check.

.operator/ledger.sqlite3

Append-only, full-snapshot event versions for task, claim, evidence, handoff, and usage/session records. Event versions allocated transactionally, linked by per-record SHA-256 hashes, protected from UPDATE/DELETE through database triggers. Doctor reports divergence but does not silently repair.

Because both SQLite and YAML live on the same writable disk, this improves local durability and auditability — it is not an off-machine backup or an adversarial tamper-proof boundary.

.operator/{tasks,claims,evidence,handoffs,usage}/

Current YAML projections (gitignored). These are compatibility read surfaces, not backup.

Root-managed external policy (P3b)

The operator-admin tool installs the standalone broker under fixed root-controlled paths. It supports strict generation-one install, append-only rotation, terminal revocation, audit, and conservative privilege preflight. This is not repo CLI integration — operator and existing .operator ledgers do not consult the external authority yet.

Open Decisions

1. Stay local, or enroll authority? The local path is the documented default. Enrollment buys a root-managed boundary and costs host prerequisites and operational surface.
2. Who owns reconciliation and store-reset acknowledgment? Should explicit acknowledgment be a first-class documented step rather than an implicit one?
3. Are study plans and phase catalogs owner-facing? They can be presented as supported product workflows or as operator-internal material.
4. Should dogfood stay administrator-only with one acknowledged retry?
5. Is closeout provisional until the transition claim stays verified? (The current design says yes — this is the right answer, but should it be explicit in the owner-facing docs?)
6. Should quota exhaustion pause a study for resumption, or stop the run outright?
7. Should root-only enrollment and rebind be documented as a separate privileged surface rather than as advanced options inside the main flow?
8. Should warning-only doctor output be described as advisory for drafts in owner-facing documentation?

Operating Caveats