110 lines
4.4 KiB
Markdown
110 lines
4.4 KiB
Markdown
# 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.
|