# 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:

```yaml
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.