Development Governor

Development Governor is an experimental, deterministic control layer for bounded Codex development work. An LLM can propose and implement a change; the Governor decides whether the project is enrolled, whether a scoped lease is active, which paths may change, which acceptance command is authoritative, and whether the slice can close.

It was built for a practical failure mode: capable coding agents can spend hours in repeated review, test, restart, and documentation loops while producing little new product evidence.

中文摘要：这是一个面向 Codex 开发任务的实验性监督器。它把 Owner 授权、可写 路径、独立验收、尝试/时长/评审预算和多智能体拓扑冻结在模型之外；它不是通过 禁止多智能体来换取安全，也不声称能拦截操作系统中的所有写入。

Try it in two commands

Requires Python 3.9+ and Git.

pipx install git+https://github.com/rossky094-hub/development-governor.git@v0.1.0-beta.5
governor demo

uv tool install works with the same Git URL. A virtual environment also works:

python3 -m venv .venv
.venv/bin/pip install git+https://github.com/rossky094-hub/development-governor.git@v0.1.0-beta.5
.venv/bin/governor demo

The demo invokes no model and does not read or modify your active Governor state. It creates a temporary Git repository and proves one complete transition:

{
  "allowed_mutation": "allowed",
  "blocked_mutation": "denied_outside_scope",
  "closure": "closed",
  "enrollment": "enrolled",
  "lease": "active",
  "model_invocations": 0,
  "status": "demo_passed",
  "verification": "verification_passed"
}

Control flow

Owner policy ──> enroll ──> task capsule ──> execute
                                             │
                   prepare/start ──> supervised Codex exec
                                             │
                   progress ──> frozen verify ──> close
                                             │
                   one external terminal receipt

The canonical project route is:

governor enroll /outside/project-policy.json
governor migrate-policy /outside/replacement-policy.json \
  --expected-policy-hash <current-policy-hash> \
  --owner-authorization-ref <external-owner-reference>
governor execute /outside/task-capsule.json \
  --output-dir /outside/task-run

execute is the normal mutating route. It owns preparation, lease activation, one supervised codex exec process group, hash-backed progress, frozen verification, and closure. Admission failures, execution stops, verification failures, and successful closure each produce one terminal receipt. Separate lifecycle commands remain available for bounded recovery and diagnostics:

governor prepare /outside/task-capsule.json
governor start <task-hash>
governor status --repo /path/to/project
governor wait --repo /path/to/project --reason-ref external:build/42 --until <unix-time>
governor check --repo /path/to/project -- python3 -m unittest -q
governor verify --repo /path/to/project
governor close --repo /path/to/project

Policies and task capsules are stored outside the governed repository. Acceptance commands are argv arrays executed with shell=False in disposable repository snapshots; declared acceptance files and task evidence inputs are content-hash checked. Liveness separates hash-backed product progress, governance activity, in-flight tools, and finite external waits. A time threshold triggers an evidence recovery opportunity; it does not by itself declare a long-running tool or project failed. Explicitly failed tool results clear their in-flight marker without receiving progress credit. The owned execution route continuously reads that same evidence state: it preserves genuine in-flight tools and finite waits, but terminates its own silent process group when the task becomes stalled_no_evidence, at a product-change deadline, or at the total elapsed limit. It does not claim control over unrelated Codex Desktop turns.

See the five-minute quickstart and the annotated policy and task capsule templates.

Project-aware Spec review

The optional review-spec route launches a dedicated reviewer agent; the Governor does not issue the semantic verdict itself. The contract supplies a hash-bound frozen candidate, closed project context, external reviewer Skill, one review-wave lineage, and explicit acceptance target scopes:

governor review-spec /outside/project-review-contract.json \
  --output-dir /outside/project-review-run

For Spec-authoring tasks, prefer the task-bound route. Task capsule v4 freezes post_close_review before writing begins. close hashes the candidate and emits a review obligation. After the exact candidate is committed, one command constructs the serial contract, derives the campaign, selects a fresh output directory, and launches the single authorized wave:

governor review-task <closed-task-hash> \
  --output-root /outside/project-review-runs

If the task declared mode: require_owner, the obligation remains pending until the Owner supplies an exact external reference:

governor authorize-task-review <closed-task-hash> \
  --owner-review-authorization-ref <external-owner-reference>

Use require_owner only outside an enrolled product goal. A goal-bound v4 governance task must use auto_if_authorized and exactly reuse the authority and bounded scopes already frozen in its non_product_exception.

This route does not auto-repair findings or start a second review. It also does not infer Owner authority. See the review-enabled task example.

Derive the required, non-caller-selectable budget lineage before constructing a new contract:

governor review-campaign-id /outside/project-review-contract.json

The ID binds the canonical Git identity, stable review scope, normalized acceptance targets, and exact Owner review authorization reference. Candidate path and content remain batch-bound evidence but do not create a fresh budget when revised or moved. Changing prompts, model settings, context packs, output directories, or a caller-supplied lineage label also cannot reset the campaign.

If an older run wrote a schema-valid final review before terminal-only token usage caused the legacy runner to record interrupted and review: null, recover that existing output without launching another model:

governor recover-review /outside/project-review-contract.json \
  --output-dir /outside/project-review-run

Recovery validates the frozen contract, context, schema, session, raw final agent message, repository nonmutation, token record, and output-last-message. It appends review-recovery-receipt.json; it does not rewrite the original terminal receipt or lineage ledger.

The serial route runs one reviewer against one materialized read-only context. A segmented route requires at least two independent segments plus one cross-scope join. The Governor, rather than a reviewer root, schedules bounded read-only model processes, writes one immutable checkpoint per valid segment, supplies those checkpoint files to the join, and deterministically aggregates the completed receipts. A retry skips valid checkpoints and runs only missing segments and their unresolved dependants. See the project-aware review guide and contract example.

What it controls

• External, append-only project policy and task state.
• A bounded lease before supported Codex mutation paths may write.
• Exact deliverable paths and protected acceptance material.
• Frozen acceptance IDs, commands, file hashes, and content-bound evidence inputs.
• Fail-closed handling for opaque shell commands plus a non-promoting isolated check entry for tests and other commands whose write set cannot be inferred.
• Attempts, elapsed time, review waves, and declared agent limits.
• Serial TDD slices with no extra probe/reviewer lanes.
• Native multi-agent work when two or more lanes have disjoint deliverables and independent acceptance IDs.
• Task capsule v5 research fanout: one root writer may coordinate declared, bounded read-only evidence obligations as a coordinator policy constraint without manufacturing per-worker repository artifacts or acceptance IDs.
• Optional root-process supervision, product-change deadlines, and observed token caps only when usage telemetry is available before terminal completion. Usage first reported by turn.completed is accounting evidence, not a live hard cap.
• One task-capsule execution entry that owns the worker process and closes or terminalizes the Governor task instead of leaving lifecycle cleanup to prose.
• Hash-bound, project-aware Spec review with deterministic campaign identity, one-wave lineage accounting, serial same-session recovery, and checkpointed segmented recovery.

What it does not control

• It is not an OS sandbox or a replacement for Git, CI, containers, or human review.
• The Codex PreToolUse Hook covers supported, recognizable mutation paths; manual edits, other applications, unhooked MCP tools, and future Codex behavior may bypass it.
• A Hook cannot interrupt an unrelated silent Codex Desktop turn. Deterministic product-change and elapsed termination applies to the child process launched by governor execute.
• Snapshot execution protects the governed repository from ordinary relative writes; it does not confine malicious absolute writes to unrelated host paths.
• It cannot guarantee that a specification is correct or that an accepted change is useful.
• It validates reviewer context, topology, budget, nonmutation, and receipt identity; the dedicated reviewer agent, not the Governor, owns the semantic verdict.
• Owner references are preserved and audited but not cryptographically authenticated.
• Token telemetry is optional and may be unavailable or terminal-only. Gross observed throughput includes cached input and is not equivalent to billed/paid tokens. This beta makes no measured cost-saving, quality-improvement, or productivity claim.
• It does not make every task single-agent. Mutating parallelism is admitted by independently verifiable lanes; bounded research fanout is admitted by declared read-only obligations under one root writer.
• The v5 coordinator policy constraint is not machine-enforced per-worker write isolation. The Hook authorizes task-wide paths and cannot authenticate native worker identity.

Read the full control boundary and threat model. The separate Governor / Skill responsibility contract defines why semantic authoring and review Skills never acquire leases or Owner authority.

Optional default Codex entry

After reviewing the managed changes, install the user-level routing rule and Hook:

governor default-enable

This adds a marked block to ~/.codex/AGENTS.md, merges one PreToolUse handler into ~/.codex/hooks.json, and installs a stable local runtime under ~/.codex/development-governor/v0/. It does not launch a model. Disable it with:

If a newer source package is available, default-enable returns upgrade_required instead of silently replacing the active runtime. Upgrade only under an explicit external Owner reference:

governor default-upgrade \
  --owner-authorization-ref <external-owner-reference>

The upgrade verifies the existing managed AGENTS/Hook projections and stable launcher hashes, preserves unrelated configuration, installs a content-addressed runtime, and writes an upgrade receipt. When activation is explicitly bound to a Governor source checkout, the Hook also denies external-project writes if that source has advanced past the active runtime or is unavailable. The Governor repository itself and the explicit upgrade route remain available for recovery. Disable it with:

governor default-disable

Status

v0.1.0-beta.5 is a public experiment. The deterministic kernel and default-entry path have local test coverage; live savings and broad compatibility have not been established. Please report a minimal reproduction through GitHub Issues.

Development

git clone https://github.com/rossky094-hub/development-governor.git
cd development-governor
PYTHONPATH=src python3 -m unittest discover -s tests -v
PYTHONPATH=src python3 -m development_governor demo

See CONTRIBUTING.md, SECURITY.md, and CHANGELOG.md. Licensed under Apache-2.0.