5. CODEX_DEVELOPMENT_CONTRACT.md

5.1 Role

Codex is an implementation capability. It can inspect, design locally, code, test and propose findings. It is not architectural authority and does not receive production authority merely because it can edit source.

5.2 Task Packet schema

Every non-trivial Codex implementation task must resolve to a packet similar to:

task_id: DEV-000123
task_revision: 3
architecture_revision: <git-sha-or-registry-revision>
base_repo_revision: <git-sha>
risk_tier: B
intent: "..."
requirement_ids: [REQ-...]
allowed_change_scope:
  modules: [work]
  paths: [modules/work/**, contracts/work/**]
forbidden_change_scope:
  paths: [architecture/**, security/**, modules/identity/**]
allowed_architecture_delta:
  new_cross_module_dependencies: 0
  new_canonical_owners: 0
  new_privileges: 0
contracts:
  consume: [contracts.identity@v1, contracts.authority@v1]
  may_change: []
semantic_owner: work
assumptions: []
acceptance_scenarios: [SCN-...]
required_tests: [unit, contract, architecture]
terminal_gap_states:
  - BLOCKED_BY_SPEC_GAP
  - BLOCKED_BY_ARCHITECTURE_GAP
  - BLOCKED_BY_MISSING_CAPABILITY

5.3 Risk tiers

Tier A — module-local: no public contract/schema ownership/privilege changes. Fast path.
Tier B — module contract/persistence local: owner-local schema or stable port changes. Migration/contract tests.
Tier C — cross-module: integration contracts/events/topology interactions. Independent architecture review.
Tier D — authority/canonical migration/external side effects: adversarial/property/recovery tests and stricter promotion.
Tier E — Core/guardrails/constitutional: proposal first; changed verifier cannot self-certify.

5.4 Codex preflight for Tier B+

Before write, produce structured implementation plan containing:

modules/files expected to change;
semantic owner(s);
contracts consumed/changed;
canonical state and state-machine transitions affected;
side effects/privileges;
persistence/migrations/events;
failure/retry/restart semantics;
tests to prove invariants.

Plan is machine-checked against Task Packet. Unexpected architecture delta becomes finding/gap.

5.5 Allowed local freedom

Inside an owned module Codex may choose ordinary data structures, algorithms, file decomposition and local refactoring, provided public contracts/invariants/task scope remain intact. Architecture defines constraints, not every function.

5.6 Mandatory Codex completion report

changed files/modules;
contracts/schemas/events/dependencies/privileges touched;
tests actually executed (CI is authoritative evidence);
assumptions made;
known limitations;
unrelated findings not changed;
any specification/architecture gaps.

5.7 Development Commit Gate

Candidate patch → deterministic build/tests → architecture sentinel → DB/migration checks → contract checks → risk-specific review → exact-artifact promotion/merge.

Ordinary Codex tasks never write protected main directly. Promotion moves the evaluated artifact/commit, not a rebuilt unknown variant.

5.8 Architecture Sentinel responsibilities

Deterministically compare declared vs observed architecture:

import/dependency graph;
DB writes/FKs/views/triggers;
event publishers/subscribers;
protected path and diff scope;
third-party dependency diff;
public contract diff;
privileged secret/capability access where enforceable;
guardrail execution health.

AI reviewer handles semantic smells that cannot be mechanically proven: God Ports, ownership leakage, false abstraction, orchestration absorbing domain semantics, hidden co-location assumptions, unsafe retry reasoning.

5.9 Architecture exceptions

No nolint/architecture ignore without registered exception ID containing reason, scope, expiry/removal condition. New debt cannot be introduced silently. Existing baseline debt can be ratcheted down.

5.10 Codex failure is valid

Codex is explicitly allowed to return a typed gap rather than “make it work somehow”. A gap becomes architecture/spec/research task and may revise the original task packet. This is preferred to an unapproved shortcut.

5.11 Cold Agent requirement

At major milestones, a fresh Codex session with no conversational history must be able to explain module ownership/boundaries and implement a bounded task using canonical repo artifacts only. Critical architecture cannot live only in chat history.

4.4 KiB Raw Permalink Blame History