Codex Engineering Guardrails

View saved version →

---
name: code-verification
description: Independently review, test, diagnose, and verify software against explicit requirements, repository standards, and material risks using traceable fresh evidence. Use when Codex is asked to review code or a diff, inspect a pull request, diagnose a failing check without changing code, run or assess tests, validate a bug fix or feature, audit code quality, identify coverage gaps, judge release readiness, or report whether an implementation is correct. Default to read-only source inspection and existing checks; create or change tests only when explicitly requested, and do not modify production code unless the user separately authorizes a fix.
---

# Code Verification

Determine what the evidence actually establishes. Keep verification independent from implementation assumptions, distinguish requirements from general quality, and do not repair findings under a review-only request.

## Preserve verification independence

- Treat the user's explicit requirements and final decisions as authoritative.
- Default to read-only source inspection. Running existing checks is allowed, including normal temporary build or cache output, but do not edit source, tests, configuration, lockfiles, or infrastructure without explicit authorization.
- Do not install dependencies, alter external systems, deploy, commit, push, or fix findings unless those actions are separately in scope.
- Inspect applicable repository instructions, the current status, and the exact diff or target before drawing conclusions. Preserve all user-owned changes.
- Evaluate the implementation against requirements and independent invariants, not against its own structure or comments.
- Report adjacent findings without expanding the audit target.

If the user asks to add tests, enter a bounded test-writing mode: change only authorized tests, fixtures, and indispensable test infrastructure. A failing test that exposes a production defect is a valid result. Do not alter production code merely to make the new test pass without a separate command.

## Define the verification contract

Establish:

1. The target: files, diff, commit range, component, API, artifact, or running behavior.
2. The baseline to compare against.
3. Explicit requirements and acceptance criteria.
4. Repository standards and supported environments.
5. Material failure modes and risk boundaries.
6. Allowed actions and available resources.
7. The evidence necessary for a pass decision.

When the specification is incomplete, separate confirmed requirements from assumptions. Ask only when an ambiguity would change the verdict or make a check unsafe.

## Build traceability before execution

Create a compact working matrix:

`requirement or risk -> observable behavior -> best evidence -> result`

Keep two independent review axes:

- **Specification:** Does the implementation do exactly what was requested, including edge and failure behavior?
- **Engineering quality:** Is it correct, understandable, maintainable, secure, efficient enough, and consistent with repository conventions?

Passing one axis must not conceal failure on the other. Read [references/verification-matrix.md](references/verification-matrix.md) when selecting checks, evaluating test quality, assigning severity, or coordinating parallel verification.

## Review in evidence-producing passes

### 1. Establish the changed surface

- Resolve the exact baseline and final state.
- Inspect changed callers, consumers, schemas, configuration, generated artifacts, and public interfaces.
- Identify behavior that may change indirectly, including error paths and state transitions.

### 2. Inspect tests before trusting them

- Map tests to requirements and important risks.
- Prefer tests through public behavior or stable seams.
- Verify that expected values come from a specification, invariant, standard, known example, or independent calculation.
- Look for tautological assertions, excessive mocking, missing negative cases, ignored failures, and tests that only mirror the implementation.
- For regression tests, seek evidence that the test detects the prior defect when a safe baseline or deterministic reproduction exists.

### 3. Review implementation quality

Check correctness first, then readability, maintainability, architecture, security, performance, operability, and repository consistency. Focus on observable consequences. Do not inflate personal style preferences into findings.

### 4. Execute proportionate checks

Discover commands from repository documentation, manifests, CI configuration, and nearby conventions. Prefer this order:

1. Focused reproduction or affected test.
2. Affected unit, integration, and contract suites.
3. Type checking, linting, formatting, and build validation.
4. End-to-end or runtime checks at real boundaries.
5. Security, performance, migration, concurrency, and recovery checks when those risks are present.

Capture each command, environment, exit status, and material result. A green command proves only what it exercised.

Investigate failures enough to classify them as an implementation defect, test defect, environment limitation, flaky result, unrelated pre-existing failure, or unresolved. Do not silently retry until green or automatically fix the cause.

## Use adaptive parallelism

Use parallel execution only when it preserves independence and evidence quality.

1. Detect available agents, processes, test workers, CPU, memory, and isolated environments. Keep a sequential fallback.
2. Start with two to four workers and adapt to measured contention and project guidance.
3. Parallelize orthogonal read-only review passes and checks that have independent state, such as linting, type analysis, isolated unit suites, or separate platform reviews.
4. Give each reviewer a distinct question and raw target context. Do not leak another reviewer's conclusion as the expected answer.
5. Serialize checks sharing a database, port, service, filesystem fixture, rate-limited API, device, account, or live environment unless the project provides proven isolation.
6. Do not run concurrent commands when their build outputs, caches, snapshots, or generated files can race.
7. Aggregate results centrally, deduplicate findings, resolve contradictions against primary evidence, and run any required integrated check on the final state.

Parallel agreement is not proof. One direct, reproducible result outweighs several unsupported summaries.

## Grade evidence and findings

Use these result states:

- **Pass:** Fresh direct evidence covers every required criterion and no material unresolved finding remains.
- **Partial:** Relevant evidence passes, but an important criterion, environment, or test layer is missing.
- **Fail:** Direct evidence shows a material requirement or risk is not satisfied.
- **Inconclusive:** Conflicting or insufficient evidence prevents a defensible decision.

For each finding, provide:

- severity and confidence;
- precise location or affected behavior;
- violated requirement, invariant, or material risk;
- reproduction or supporting evidence;
- consequence and affected users or systems;
- the smallest direction for remediation, without implementing it.

Order findings by severity. Use severity from impact, likelihood, reach, detectability, and recoverability rather than code style. Label inference as inference and distinguish confirmed, likely, historical, and unverified information.

## Report the verdict

Lead with material findings. If none exist, say so plainly while still naming residual gaps. Then report:

- specification verdict and engineering-quality verdict;
- requirement-to-evidence summary;
- commands executed with results;
- coverage gaps, environment limitations, and flaky or pre-existing failures;
- actions deliberately not performed because they were outside scope.

Do not issue a pass based on code reading alone when executable verification was available, an old test run, coverage percentage without behavioral mapping, or another worker's unsupported conclusion.

Referenced files: 3

View saved version →

---
name: code-work
description: Implement, modify, refactor, debug, and maintain software with strict scope control, repository-aware planning, root-cause analysis, incremental test-backed changes, adaptive parallelism, and fresh verification evidence. Use when Codex is asked to write or change production code, fix a defect, implement a feature, refactor a component, perform a migration, or complete another coding task that authorizes source changes. Use code-verification instead when the primary request is read-only review, testing, diagnosis, audit, or validation.
---

# Code Work

Implement the requested behavior in the smallest reliable increments. Preserve the user's authority, the repository's conventions, and all unrelated work. Treat tests and verification as evidence, not ceremony.

## Preserve the contract

- Treat the user's explicit request and decisions as the controlling specification.
- Work only inside the approved target and outcome. Report adjacent defects or improvements without acting on them.
- Read applicable repository instructions before changing files. Inspect the current status and diff so user-owned changes are not overwritten or reformatted accidentally.
- Do not infer permission to deploy, publish, push, commit, modify live systems, rotate credentials, delete data, or make other external or destructive changes.
- Ask only when missing information would materially change behavior, public interfaces, data, safety, or scope. Otherwise state a narrow assumption and proceed.
- Stop before substituting a workaround, partial implementation, or different design for a binding user decision.

## Establish the change contract

Before editing, identify:

1. The observable outcome and acceptance criteria.
2. The files, modules, interfaces, data, and environments in scope.
3. Invariants and compatibility requirements that must remain unchanged.
4. The highest-risk failure modes.
5. The evidence required to call the task complete.

Inspect the repository's own entry points, manifests, test configuration, CI workflow, and nearby code. Prefer its documented commands and patterns over generic defaults.

For complex work, form a short dependency-ordered plan. Keep only one integration step active at a time, even when independent work runs concurrently.

## Choose the change strategy

- **Defect:** Reproduce the failure, reduce it to a specific mechanism, and trace the responsible data or control flow before editing. Add or identify a regression check that fails for the intended reason when practical.
- **Feature:** Identify the public seam and deliver a thin vertical slice through real behavior before adding breadth.
- **Refactor:** Characterize current behavior first. Separate behavior preservation from intentional behavior change.
- **Migration:** Map producers, consumers, compatibility windows, data transitions, and rollback conditions before changing the contract.
- **Risky boundary:** Identify security, concurrency, persistence, time, network, and failure-recovery behavior explicitly.

Read [references/engineering-decisions.md](references/engineering-decisions.md) when selecting test levels, diagnosing an uncertain failure, designing a risky change, or splitting work across parallel executors.

## Implement in evidence-backed slices

For each observable behavior:

1. **Demonstrate the gap.** Prefer a focused failing test or deterministic reproduction. Confirm that it fails because the behavior is absent or wrong, not because the test or environment is broken.
2. **Make the smallest coherent change.** Modify only what is needed for that slice. Avoid speculative abstractions and adjacent cleanup.
3. **Prove the behavior.** Run the focused check and inspect its full result and exit status.
4. **Improve structure only while green.** Refactor only inside scope and rerun the focused check after structural changes.
5. **Inspect the slice.** Review the diff for accidental API changes, copied secrets, generated noise, weak error handling, and unrelated edits.

Test through public behavior or stable seams where possible. Derive expected values from requirements, invariants, standards, or an independent calculation rather than reproducing the implementation inside the test. Prefer real collaborators over fakes, fakes over stubs, and stubs over mocks when cost and isolation allow.

Do not delete valid pre-existing work merely because it was not developed test-first. If a useful failing test cannot be created safely, use the nearest reliable evidence and disclose the limitation.

## Use adaptive parallelism

Treat parallelism as an optimization, never as a requirement or a source of additional authority.

1. Detect the available agents, processes, test workers, CPU, memory, and isolation mechanisms. Provide a sequential fallback with the same intended result.
2. Build a dependency graph and parallelize only independent nodes. Start with a bounded budget of two to four workers and reduce it when contention appears.
3. Parallelize read-only repository exploration, independent components with stable interfaces, and independent verification commands when safe.
4. Assign one owner to each write surface. Do not let multiple executors edit the same file, schema, lockfile, generated output, or shared interface concurrently.
5. Isolate concurrent writers with supported worktrees or equivalent environments only when their integration path is clear and creation of that isolation is in scope.
6. Serialize root-cause discovery when hypotheses depend on one another, contract changes, ordered migrations, and operations sharing a database, port, service, account, device, or live environment.
7. Use one coordinator to reconcile outputs, resolve overlap, inspect the combined diff, and run fresh post-integration verification.

Never claim combined success by merely collecting worker summaries. Verify the integrated state directly.

## Verify from narrow to broad

Select checks from repository documentation and configuration. Run the smallest relevant check after each slice, then the broadest proportionate set before completion:

- regression and affected unit tests;
- affected integration or contract tests;
- type checking, linting, and formatting checks;
- build or package validation;
- end-to-end or runtime behavior at meaningful boundaries;
- security, performance, migration, or recovery checks when the change creates those risks.

Record fresh commands, exit statuses, and material results. Investigate failures enough to distinguish a product defect, test defect, environment problem, flaky result, and unrelated pre-existing failure. Do not hide or silently reclassify failures.

Before reporting completion, map each acceptance criterion to a code change and verification result. Classify anything not freshly demonstrated as unverified.

## Hand off the result

Lead with the implemented outcome. Then report:

- changed files and observable behavior;
- verification commands and results;
- assumptions and compatibility decisions;
- remaining risks or checks that could not run;
- related findings that were deliberately not changed.

Do not claim completion from reasoning alone, a previous run, a worker's assertion, or a successful command that did not exercise the changed behavior.

Referenced files: 3