This commit is contained in:
@@ -0,0 +1,109 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,17 @@
|
||||
# Development credential policy
|
||||
|
||||
Codex may use credential helpers already configured on the machine, but must not expose or persist their secrets.
|
||||
|
||||
Allowed discovery:
|
||||
- `git credential` / Git Credential Manager as invoked by Git;
|
||||
- Docker credential store as invoked by Docker;
|
||||
- environment variables explicitly supplied to the task/runtime;
|
||||
- sibling project files only to learn endpoint names, secret variable names and deployment conventions.
|
||||
|
||||
Not allowed without a new explicit user instruction:
|
||||
- recursive searching for plaintext passwords/tokens in unrelated repositories;
|
||||
- printing recovered credentials;
|
||||
- copying a literal secret from one project into this repository;
|
||||
- committing `.env.local`, Portainer keys, Gitea tokens or passwords.
|
||||
|
||||
If Git push or Portainer deployment still needs credentials, ask the user for the minimal credential/API key needed.
|
||||
@@ -0,0 +1,7 @@
|
||||
# Development control plane — V1 minimum
|
||||
|
||||
V1 intentionally starts small: Git + task packets + `devctl` + CI + architecture registry. Do not build a separate development platform service yet.
|
||||
|
||||
Development flow:
|
||||
|
||||
`Task Packet -> isolated branch/worktree -> Codex -> tests -> Architecture Sentinel/devctl -> review according to risk -> merge exact evaluated commit`.
|
||||
Reference in New Issue
Block a user