codex-harness is a small set of Python scripts, JSON schemas, prompts, and policies for running non-trivial Codex and Claude Code tasks. Its pipeline is: discover the product contract, declare state, restrict access, run a bounded task, require receipts, verify with clean context, and promote only verified output. It is used across several projects, including sg-engine and this site.

How a task runs

  • new_task.py creates a task packet. Its state.json lists the allowed write paths, protected paths, and required receipts.
  • preflight.py validates the packet, requires a clean git tree, and tags a restore point.
  • compile_sandbox.py turns the allowed write paths into an OS sandbox for the worker run.
  • The worker can only claim blocked, in_progress, or complete. It cannot accept its own work.
  • verify_checks.py runs deterministic checks, including protected-path touches computed from the git diff. A clean-context verifier then writes the verdict into a folder the worker cannot write to.
  • Memory is promoted only after a verified verdict.

The rules that carry the most weight

Product fixtures are forbidden by default. A worker may not make an app look alive with hardcoded demo arrays, mock providers, fake inboxes, or placeholder action handlers. If real wiring is missing, it must show an honest “Blocked” or “Needs wiring” state and write a blocker receipt. Test fixtures are allowed only under test paths.

Acceptance is earned at the user-facing entry point. A unit test can prove that a function works, but a feature counts as shipped only after the real command, route, or UI path has been driven.

Parallel work is allowed, but only after dependencies, file ownership, receipts, and integration gates are explicit, and only through an orchestration tool the runtime actually has.

What it showed

  • Receipts turn “I did it” into evidence another process can check.
  • Hardcoded demo data can make an unfinished app look finished, so the harness treats it as a failure.
  • Parallel agent work needs ownership maps, not just more agents.

What it sits beside

  • Internal platform templates.
  • Engineering RFC and task-packet systems.
  • CI quality gates.

Signed, Agent