Principles
- Outcome first. Deliver the smallest complete result that solves the stated problem. Do not expand an exact task into a platform or PR program without explicit approval.
- One coherent PR by default. Split only when every part is independently useful, safe, testable, deployable, and rollbackable. Size alone is not a split criterion.
- Proportional process. A PR contract contains outcome, risk, file scope, acceptance, tests, proof where relevant, and rollback. It is not a separate role or a second implementation project.
- Autonomy inside scope. The owner may edit, test, commit, push, and update the PR. New approval is needed only for material scope, access, spend, external communication, unapproved irreversible production/customer-data work, or bypass.
- Independent exact-head review. A separate read-only identity reviews the complete current diff. Native GitHub rules invalidate stale approvals and gate merge on checks, conversations, latest-push approval, and merge queue.
- Short feedback loops. After two unsuccessful corrections, reassess. A second replan or more implementation PRs requires explicit user approval.
Delivery owner
The delivery owner:- verifies the current goal, repository state, branch, and any existing PR;
- creates a clean task worktree from current
origin/mainfor new work; - writes the proportional PR contract and keeps its file scope current;
- implements the complete acceptance criteria without unrelated cleanup;
- runs targeted tests while iterating and the required broad checks on the stable diff;
- captures actual running proof for frontend changes;
- publishes with the builder identity and responds to objective review findings;
- never self-approves or bypasses protection without an explicit human directive.
Risk tiers
Risk controls review depth; it does not impose line or file caps. Protected paths
listed in
AGENTS.md require critical risk and justification.
Independent review
The reviewer uses.codex/review.md
and blocks only objective failures: incomplete acceptance, scope mismatch, incorrect
behavior, realistic security/privacy/data defects, missing tests or proof, red CI,
unresolved conversations, or stale live state. Style, taste, speculative hardening,
and diff size alone are not blockers.
Any new push or base change requires a fresh review of the new exact snapshot.
Mechanical controls
scripts/check-plan.mjs verifies the PR contract, file allowlist, protected-path risk,
acceptance checklist, domain-test coverage, frontend proof, environment-file ban, and
forbidden executable patterns. CI also runs tests, database sync, a database-free
build, docs checks, secret scanning, and client-data scanning.
Head, PR-body, label, draft-state, and merge-group changes refresh the distinct
trusted metadata policy status only; they do not waste another full build and test
cycle. Invalid metadata removes the PR from the merge queue. The legacy snapshot
gate remains during activation and is removed only after the replacement is required
and proven on both PR and merge-group SHAs.
GitHub must enforce pull requests, one independent approval, stale-review dismissal,
approval of the latest push, conversation resolution, required checks, merge queue,
and blocked direct/force pushes. The live ruleset—not documentation—is authoritative.
Production and rollback
A merge is only code integration. Release proof requires current-main CI, deployment, serving SHA/no drift, a named smoke, appropriate observation, and rollback readiness. If production remains red, use the protected auto-revert path. If production has already recovered on the same SHA, rerun the trusted smoke before deciding to revert. Human controls remain simple:halt-agents stops work, needs-replan records a real
impasse, auto-revert identifies recovery PRs, and force-merge is a rare, explicit,
publicly logged bypass. No label substitutes for correctness, secret hygiene, or the
prisma db push and --no-verify bans.