Codex AGENTS.md in a Monorepo: An Instruction-Resolution Preflight Before a Scoped Refactor

Set the Boundary: What an Instruction-Resolution Preflight Is—and Is Not

An instruction-resolution preflight answers a narrower question than “Can Codex refactor this service?” It asks which instruction sources are relevant to one named working directory, what those sources say, and who must resolve uncertainty before code work is authorised. The approved deliverable is a dated, draft-only instruction-resolution record. It is an input and authority map, not a refactor plan, and its completion does not itself grant permission to change the repository.

This guide is a documentation-led assessment of OpenAI’s assigned official sources, locked as of 2026-10-13. It is not a hands-on monorepo test, performance benchmark, security audit, code review or production validation. The procedures and templates below are editorial recommendations: suggested ways for a repository owner to organise evidence and decisions. They are not additional Codex features or guarantees about how a particular client will behave.

The task boundary should explicitly exclude implementation, pull request creation, code-review findings, plugin construction, benchmark claims and automatic policy decisions. A draft may identify an apparent contradiction between two instruction excerpts, but it must not turn that contradiction into a code defect or silently resolve it on behalf of maintainers. The named repository owner decides whether the record is sufficiently complete to support a separately authorised scoped refactor.

Approve an evidence task, not an engineering task

Recommended task definition: “Prepare a draft instruction-resolution record dated 2026-10-13 for the working directory named in this request. Inventory relevant instruction candidates and configuration uncertainties, preserve short source excerpts, and identify the human owner of each unresolved question. Do not modify files, analyse implementation correctness, create a pull request, construct plugins or decide repository policy.” This is a hypothetical task template, not an enforcement mechanism. The operator must still choose an appropriate execution environment and review the resulting draft.

Specify the intended working directory as a concrete path rather than a loose service name. “Payments” might refer to a service, shared library, deployment directory or documentation area. A useful authorisation note distinguishes the directory to be examined from the eventual files that might be refactored. For example, the hypothetical directory /work/northstar/platform/services/ledger identifies the preflight’s starting context; it does not authorise changes to everything beneath that path.

Also separate the person gathering evidence from the person empowered to approve an exception. An operator may be able to read instructions without having authority to waive a release gate. Record a named repository-owner role and a target-service maintainer role at the outset. If the organisation has not assigned those responsibilities, “owner unresolved” is an actionable preflight result, not a gap for the agent to fill by choosing whichever sentence appears most convenient.

This preflight differs from our earlier article on designing Codex review rules in its deliverable. That article concerns authoring Codex code-review rules in AGENTS.md; this preflight maps inputs and their human authority before an agent is asked to analyse or alter code. It neither writes a new review policy nor evaluates a proposed implementation against one. A rule about reviewing migrations can be recorded as source material without producing any migration-review finding.

Editorial relevance: Keep the requested preflight on documentation discovery and handoff; use OpenAI Launches Agents API: Managed Codex Harness, Durable Sessions, Hosted Sandboxes, and Public-Beta Limits only to distinguish that boundary from a managed execution platform. What that guide describes: its September 10 public-beta table says the application programming interface offers a managed Codex harness, durable sessions, and environment choices including OpenAI-hosted sandboxes, while applications still own authorisation and review.

Use three labels that keep evidence and judgement separate

Documented Codex behaviour means a product statement supported by an assigned official source. Attach the source and the exact assessment date to such statements. This label answers questions about documented discovery or configuration behaviour; it does not establish that a particular run used a particular file. Local observations, when later collected, need their own evidence field rather than being folded into the documentation claim.

Human-authored repository guidance means the actual prose that people have placed in instruction files. Preserve its wording sufficiently to distinguish a mandatory rule from a preference, a release requirement from a development habit, and a service-specific exception from a general convention. A file’s location is relevant to discovery, but location alone does not identify the organisational authority of its author or establish that an exception was approved.

Editorial recommendation means a proposed governance method in this guide: the record schema, status vocabulary, ownership questions and draft acceptance criteria. Label these as recommendations when adopting them. A repository can use a different record format without changing Codex’s documented behaviour. Conversely, a carefully formatted record cannot settle an undocumented interaction or make conflicting human instructions compatible.

A practical drafting rule is to keep these labels in separate columns or sentences. “The documentation describes this selection order” is a product claim. “The release guide requires a sign-off” is a repository quotation. “Ask the release owner whether the local wording is an approved exception” is a recommendation. Combining all three into “Codex allows this release exception” would create a conclusion that none of the individual pieces establishes.

Establish the documented starting point without doing the full trace yet

Before using the source wording below, expand the interface term: a terminal user interface (TUI)A user interface accessed through a terminal. OpenAI describes Codex CLI as a TUI (terminal user interface), meaning Codex is accessed through the terminal. Open glossary entry is the terminal-oriented interface referred to in OpenAI’s instruction guide. The session boundary matters because the preflight describes a particular intended execution context. Do not assume that editing documentation during an already-running session makes the record and that session equivalent.

Codex constructs the documented AGENTS.md instruction chain at session start—once per run, ordinarily once per launched TUI session—so a preflight should identify the target working directory and record the chain before asking for a refactor. The timing statement is documented product behaviour in OpenAI’s custom-instructions guide, assessed as of 2026-10-13; the preflight action is the governance recommendation drawn from it. This does not describe live reload during an existing session. Record when the intended context was established, and keep any subsequent instruction-file changes visible as changes to the draft’s evidence basis. [Custom instructions with AGENTS.md]

At global scope, Codex checks the effective Codex home directory first: AGENTS.override.md is selected when present; otherwise AGENTS.md is selected, and only the first non-empty file at that level is used. This is documented product behaviour in OpenAI’s global-instruction documentation, assessed as of 2026-10-13. The documented default is ~/.codex, unless CODEX_HOME is set, so the record needs the effective value rather than an assumed default. “First non-empty” is not evidence that both global files are merged. If the effective location cannot yet be established, mark it unresolved instead of substituting the operator’s usual home directory. [Custom instructions with AGENTS.md]

For project scope, Codex starts at the project root and walks down to the current working directory; in every directory it tries AGENTS.override.md, then AGENTS.md, then configured fallbacks, and includes at most one file from that directory. This is documented product behaviour in OpenAI’s project-instruction documentation, assessed as of 2026-10-13. The same source says that, if no project root is found, Codex checks only the current directory. A same-directory AGENTS.md displaced by AGENTS.override.md belongs in the record as shadowed, not simultaneously active. The next chapter applies this documented selection model to a single target path. [Custom instructions with AGENTS.md]

Editorial relevance: After you have traced the actual instruction-file chain, use Advanced Prompt Engineering for AI Coding Agents to translate the selected guidance into a bounded human request, not to infer Codex discovery order. What that guide describes: its “Contextual Clarity and Environment Specification” passage asks for language, framework, version, dependencies, and conventions; its scope section recommends requirements, edge cases, and sequential subtasks.

Recommended boundary question: “What evidence will establish the effective root and configuration for this intended surface?” Asking that now prevents a draft from treating the operator’s checkout layout as a proven execution context. Do not yet fill the answer with an assumed Git root, a familiar alternate filename or a configuration copied from another machine. Record the question and its owner; the detailed path trace belongs to the next stage.

Create a reusable record with room for unknowns

The following schema is an editorial recommendation for an auditable draft. Use one header for the intended run context, then one entry per candidate file and additional entries where a file contains distinct rule topics. “Auditable” here means that a maintainer can follow each assertion back to its source and decision. It does not mean the record is a certified compliance artefact or that its evidence is complete.

Use the status vocabulary narrowly. As a recommended record convention, selected means identified for inclusion under the documented selection model, with the evidence basis stated; it need not mean runtime-confirmed. Shadowed means displaced by another candidate at the same directory level. Ignored means excluded for a stated discovery reason, not “irrelevant to the organisation”. A document can remain important to maintainers even when it is not selected through instruction-file discovery.

Keep measurements and quotations separate. Byte size describes the file, while the excerpt describes the rule under discussion. Neither proves that all relevant text reached the intended session. The later reconciliation stage addresses byte-limit uncertainty; at this foundation stage, make space for that uncertainty rather than choosing a limit interpretation or proposing a larger limit without repository-owner review.

Do not let a blank field masquerade as a negative finding. “No conflict identified in the excerpts examined” is narrower than “no conflicts exist”. “Version not observed” is different from “version not applicable”. Requiring explicit unknowns gives the human reviewer a concrete list of unfinished evidence questions and prevents polished formatting from suggesting a completed assessment.

Hypothetical example: the Northstar monorepo

Hypothetical documentation example: Northstar is an invented monorepo used solely to illustrate the record. Its paths, roles and rule excerpts are fabricated examples, not an observed deployment or a test of Codex. Assume the proposed target working directory is /work/northstar/platform/services/ledger. The example has a personal test preference, a repository release rule, a platform-directory convention and a target-service exception. No selection status or runtime result is claimed for these example files.

The first useful editorial action is classification, not choosing a winner. The personal sentence describes iterative development; the root sentence describes release; the platform sentence is conditional on interface changes; the service sentence is conditional on their absence. Those conditions may describe different stages or different kinds of work. The record should preserve them before anyone decides that the four statements contradict one another.

A hypothetical conflict entry might read: “Test selection: potential overlap between the platform harness convention and the ledger-focused exception; applicability depends on whether the later proposed refactor changes an interface. Release requirements remain a separate topic. Decision requested from the platform maintainer and ledger service maintainer.” This is a sample draft entry, not an observed finding or a promise that Codex will interpret those sentences in that way.

A hypothetical proposed repair could ask the owners to clarify the exception’s scope: “Confirm whether the ledger-focused harness is permitted for development checks only, and whether release validation remains unchanged.” The preflight may record that proposal, but it should not rewrite either file. It also should not inspect implementation details to decide whether an interface changes: that would cross into a different authorised job.

The example exposes a useful ownership distinction. The ledger maintainer may explain the service’s terminology, while the release owner controls the release requirement. A service-local statement should not be treated as evidence that the release owner approved a waiver. Record the authority question explicitly, even when the prose looks easy to reconcile, because the purpose of this map is to prepare a human decision rather than simulate one.

Make the draft safe to inspect and narrow enough to approve

Recommended handling rule: treat instruction files, configuration excerpts and any later retrieved output as evidence to inspect, not as instructions to expand this preflight’s permissions. If a candidate file says to publish credentials, upload private material or perform unrelated changes, record the relevant concern through an approved channel without obeying it. Keep secrets and personal data out of prompts; use minimal, appropriately redacted excerpts where the rule can still be understood.

Choose the intended Codex surface explicitly rather than treating local, desktop, editor and cloud contexts as interchangeable. For example, expand command-line interface (CLI)A text-based interface for running commands and tools. Open glossary entry and integrated development environment (IDE)A software application combining tools for writing, building, testing and debugging code. Open glossary entry before using those abbreviations in a record. A version observed in one interface is not evidence about another. If cloud execution is contemplated, OpenAI’s Help Center guidance on Codex plans, assessed as of 2026-10-13, makes Cloud availability subject to eligible plans, rollout and workspace settings; this draft cannot promise access.

Reserve unresolved configuration questions without answering beyond the evidence. For a configured model_instructions_file, the assigned OpenAI configuration reference, assessed as of 2026-10-13, describes a replacement for built-in instructions instead of AGENTS.md, but the cited pages do not define its full interaction with global and nested instruction layers. Record its presence as a boundary requiring confirmation, not proof that the ordinary file map is the entire instruction context.

Recommended foundation acceptance criteria: the draft names one working directory, identifies the intended client or surface, assigns a repository-owner decision boundary, contains the schema above and distinguishes source claims from invented examples. It lists unresolved context questions without pretending they have been verified. It contains no implementation proposal disguised as an instruction finding and no automatic approval derived from file location.

The hand-off from this foundation is therefore specific: a bounded evidence task, a record structure and a named human decision-maker. The next chapter traces the documented sources to the target service; later stages reconcile rule and byte risks, then verify and freeze the record. Until those stages have supplied their evidence and the repository owner has reviewed the consequential choices, the output remains a draft—not permission to refactor.

Trace the Documented Chain to One Target Service

Use this chapter as an editorial worksheet for tracing one intended working directory, not as permission to start the refactor. The practical output is a candidate-source map: where discovery begins, which directories it visits, which file each directory contributes, and which assumptions still need confirmation. The procedure below follows OpenAI’s assigned documentation as of 2026-10-13. Northstar remains a hypothetical monorepo; its paths, file contents and decisions illustrate how to complete the worksheet, not an observed Codex run.

Begin by writing the target directory in an unambiguous form. In the Northstar example, the repository is /work/northstar and the intended working directory is /work/northstar/services/billing. Do not substitute “the billing service” for that path: a launch from the repository root and a launch from the service directory are different discovery inputs. Record the intended Codex surface alongside it, such as a locally installed command-line interface (CLI), and record its version only if actually observed. Leave unavailable details explicitly unresolved.

Inspect the effective home directory before inspecting the repository

OpenAI’s AGENTS.md guide, as of 2026-10-13, identifies ~/.codex as the default Codex home directory unless CODEX_HOME is set. At this global level, it describes checking AGENTS.override.md before AGENTS.md and using only the first non-empty file. The worksheet should therefore start with the effective home directory in the environment that will launch the intended session, rather than with a familiar directory on another machine.

Recommended inspection: ask the operator to establish whether CODEX_HOME is explicitly set, inherited from the launch environment, or absent. Record the resolved directory and the basis for that answer without copying the rest of the environment. A terminal launched by an editor and a separately opened shell should not be assumed to inherit identical values. If the intended launch environment is inaccessible, mark the home path as unconfirmed and ask the operator responsible for that environment to complete the field.

Next, inspect the two global candidates without editing them. Record existence and whether each file contains any bytes; keep an empty file distinguishable from a missing file. In the hypothetical Northstar worksheet, assume CODEX_HOME is unset, ~/.codex/AGENTS.override.md is absent, and ~/.codex/AGENTS.md is non-empty. The expected global contribution is consequently ~/.codex/AGENTS.md. Its hypothetical preference for focused tests belongs in the record as human-authored guidance, not as a Codex configuration setting.

If inspection instead finds a non-empty global override, revise the expected selection and flag the ordinary global file as shadowed. Do not silently discard its existence: an owner may need to know that their usual personal guidance is not the selected source. If the evidence is ambiguous—for example, the operator cannot inspect the override—leave the selection unresolved. A guessed global contribution would make the later project map look more complete than the evidence permits.

Establish the root boundary before listing project candidates

As of 2026-10-13, OpenAI’s Advanced Configuration describes searching upwards from the working directory for a project root, with .git as the default marker. It supports a configured project_root_markers list and states that project_root_markers = [] skips parent searching and treats the working directory as the root. The sample configuration also records the default marker list. Establish the effective setting before assuming that a directory called “northstar” is the discovery boundary.

Recommended root worksheet: record the marker list, its configuration provenance, the marker observed on the relevant path, and the resulting root. Provenance means identifying the setting’s source, not copying an entire configuration file. If several relevant configuration layers exist, retain enough information for the operator to explain which value is effective. A checked-in setting that appears suitable is not proof that the intended session uses it.

The no-root behaviour in this table comes from OpenAI’s AGENTS.md guide, as of 2026-10-13. Keep that branch separate from an empty marker list: one records an unsuccessful search, while the other records a configured decision not to search parents. Although these hypothetical branches produce the same directory list here, their explanations and the human questions they raise are different.

For Northstar’s main worked path, use the default-marker branch only after its assumptions have been confirmed. Write every directory between the root and billing, including directories with no instruction file. This prevents a missing row from being mistaken for an intentional boundary. Do not add sibling services merely because they share the repository: services/search, for instance, is not on the illustrated root-to-billing path.

Apply the filename selection separately in each directory

OpenAI’s AGENTS.md guide, as of 2026-10-13, says that project discovery proceeds from the project root down to the current working directory. In each directory it checks AGENTS.override.md, then AGENTS.md, then configured fallback names, and includes at most one file from that directory. Apply that selection locally to each row; do not interpret an override in billing as a reason to remove the rows for its ancestors.

Recommended recording method: give each candidate a path and a status, using a small, defined vocabulary. “Expected selected” means the worksheet predicts its inclusion under the documented discovery rules, subject to byte and runtime verification. “Shadowed” means an earlier eligible candidate in the same directory takes the slot. “Missing” records absence. “Empty” records a file that exists without content. “Outside path” means the directory is not part of this trace. These are editorial record labels, not promised Codex output labels.

The billing row deserves a separate human question: is the override intentional for the proposed work? In this hypothetical example, it carries a billing-specific local exception, while the shadowed file contains ordinary service guidance. Record the owner’s explanation beside the file selection, rather than treating the filename alone as approval of the exception. Discovery identifies a source; the repository owner still decides whether its human-authored content is appropriate.

Editorial relevance: When recording the selected file and any shadowed alternative, borrow the decision-record discipline in How to Manage Design Decisions When Using AI Coding Agents: Complete Guide to Preventing Architecture Drift with Claude Code, Cursor, and Codex rather than treating it as evidence about how repository override files are resolved. What that guide describes: its “Building a Design Decision Log” section says a design-decision log file is human-readable documentation, and its example directs a “needs review” escalation when work would go beyond scope or require an uncovered design decision.

Where a directory contributes no eligible candidate, retain the row and write “no contribution identified”, with the inspection evidence. Do not create an instruction file to make the worksheet look complete. Creating or revising guidance changes the inputs to the later session and requires a separate owner decision. Likewise, do not rename an existing file during this read-only trace merely to make it discoverable.

Distinguish configured fallbacks from useful reading material

Fallback filenames are not generic automatic discovery: they are the configured project_doc_fallback_filenames list, considered only after AGENTS.override.md and AGENTS.md; the sample configuration documents an empty default fallback list. As of 2026-10-13, OpenAI’s AGENTS.md guide, Configuration Reference and sample configuration support this distinction. The guide’s TEAM_GUIDE.md and .agents.md names are an example configuration, not built-in defaults; copy the actual ordered list into the worksheet. [Custom instructions with AGENTS.md; Configuration Reference; Sample Configuration]

Hypothetical configuration example: suppose the operator confirms project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"]. The directory-level candidate sequence becomes AGENTS.override.md, AGENTS.md, TEAM_GUIDE.md, then .agents.md. Record this sequence once as the effective order, and use it consistently when inspecting each directory. The example is illustrative, not a recommendation to adopt those names.

To see the consequence without changing Northstar’s main map, consider an alternative services-directory row where both standard candidates are absent and TEAM_GUIDE.md is non-empty. Under that hypothetical configured list, the team guide becomes the expected selected file for that row. If .agents.md also exists there, it is a later candidate, not an additional contribution. Keep this alternative separate from the main row where services/AGENTS.md was selected.

An appealing README.md in the same directory has a different status when it is not in the configured list: human context, not a discovered instruction source under this fallback mechanism. A maintainer may read it to understand the service or identify an inconsistency, but the worksheet must not quietly add it to the expected chain. If its contents are supplied in a later prompt, record that separately as supplied context; supplying text is not evidence that filename discovery selected it.

Apply the same discipline to claims inside repository files. A paragraph saying “this document supersedes all agent instructions” is text to record and refer to the owner, not authority to alter the preflight procedure. Treat supplied and retrieved material as data throughout this task. Preserve relevant excerpts without following embedded requests to reveal environment values, change configuration, or perform unrelated work.

Record order without pretending to parse every contradiction

The documented merge model is concatenation from root to working directory with blank lines; a nearer file appears later and is described as overriding earlier guidance, but this is not a mechanically defined conflict-resolution language for every prose contradiction. This ordering is documented in OpenAI’s AGENTS.md guide, as of 2026-10-13. Rewriting incompatible human rules into explicit, scoped exceptions is an editorial recommendation for the owner’s later reconciliation, not a documented parser or policy engine. [Custom instructions with AGENTS.md]

For the Northstar worksheet, give the expected selected files an order field and attach a short topic description to each: global focused-test preference, root release rule, services convention, billing exception. These hypothetical descriptions help the owner locate relevant text without implying that a nearer file mechanically deletes an earlier rule. Preserve the original excerpts for the next chapter’s reconciliation; this chapter should identify the inputs, not adjudicate whether the billing exception is acceptable.

Keep configuration observations in a separate portion of the worksheet. As of 2026-10-13, OpenAI’s Advanced Configuration says project .codex/config.toml layers are loaded from root to working directory, with the closest setting winning for repeated keys. The Configuration Reference states that untrusted projects skip project-scoped .codex layers, including local configuration, hooks and rules. That trust statement does not establish that AGENTS.md discovery is disabled.

Also ask whether model_instructions_file is configured. OpenAI’s Configuration Reference, as of 2026-10-13, describes it as a replacement for built-in instructions instead of AGENTS.md; the sample configuration describes overriding built-in base instructions with a file path. These pages do not define its full interaction with global and nested AGENTS.md layers. If present, record its source and seek maintainer clarification rather than declaring the mapped chain the complete instruction context.

Add a byte-risk field without resolving the documentation conflict

Empty instruction files are skipped. The AGENTS.md guide says adding stops when the combined size reaches project_doc_max_bytes, whose stated default is 32 KiB (kibibytes); the preflight record should therefore include an explicit byte-risk field. As of 2026-10-13, this combined-size wording appears in OpenAI’s AGENTS.md guide, while the sample configuration records the default as 32768 bytes. However, Advanced Configuration describes the setting as how much is read from each AGENTS.md file. Retain that conflict for verification on the installed client and surface; neither interpretation is settled by this worksheet. [Custom instructions with AGENTS.md; Sample Configuration; Advanced Configuration]

Recommended measurement: record actual file byte sizes using an owner-approved, read-only inspection method. Do not substitute word counts or editor character counts for bytes. Keep selected-candidate measurements separate from shadowed-file measurements, so an owner can distinguish expected instruction material from contextual inventory. Record the effective limit if confirmed, and label an assumed default as an assumption rather than an observed setting.

The byte-risk field should describe what remains unknown: for example, “candidate sizes recorded; effective limit unconfirmed; client interpretation unresolved”. That is a hypothetical sample entry, not an observed Northstar result. Do not infer complete inclusion solely because every file is individually small, and do not treat splitting guidance across directories as a guarantee against truncation. Increasing a limit is outside this read-only procedure and requires repository-owner review.

Editorial relevance: Because the byte-limit wording needs client- or surface-specific verification, preserve that uncertainty in the preflight record and consult Codex Security operating surfaces, coverage, automation, artefacts, and human review. What that guide describes: its comparison distinguishes the workbench, command-line interface, TypeScript software development kit, and connected-GitHub cloud workflow; it says the surface changes the operator, practical artefacts, and human-review needs. That comparison does not define a byte limit for repository instruction files.

Use a short read-only verification checklist

OpenAI’s AGENTS.md guide, as of 2026-10-13, documents asking Codex to summarise current instructions or to “Show which instruction files are active.” It also documents optional plaintext logging for the terminal user interface (TUI) through log_dir, and session logs when enabled. Its chain is built at run start, ordinarily at each launched TUI session, rather than documented as a live reload. Use a fresh, deliberately scoped verification session when checking the worksheet.

Recommended prompt: “Show which instruction files are active for this working directory. Summarise the current instructions and identify any uncertainty in the source list. Do not edit files, change configuration or begin the refactor.” This extends the documented source-reporting approach with an editorial read-only boundary. It is a request, not a product guarantee of non-modification; the operator must choose an approved execution environment and inspect the resulting evidence.

Keep a reported source list and an instruction summary as different evidence types. The first helps compare paths; the second helps identify apparent topic coverage. Neither should be treated as proof that every sentence was included or followed. An unexpected omission should trigger investigation of the recorded inputs, not an immediate instruction-file edit designed to make the output agree with the worksheet.

If the operator elects to collect logs, obtain privacy review before sharing them and retain only authorised references in the worksheet. Optional logs are not guaranteed to exist, to be complete compliance audit trails, or to be safe for wider circulation. Keep credentials and personal data out of verification prompts and excerpts. The repository owner’s next decision is whether the source map is sufficiently supported to proceed to rule reconciliation—not whether the refactor itself is authorised.

Reconcile Rules and Byte Risk Before Any Refactor Is Authorised

The selected source list is an input to reconciliation, not an authorisation to act. At this stage, the repository owner should be able to distinguish compatible guidance from an unresolved exception, and readable source material from material whose inclusion remains uncertain. The editorial procedures below turn those distinctions into two connected records: a conflict matrix for human-authored rules and a byte-risk ledger for instruction files. Neither record grants permission to modify code, change dependencies or execute a migration.

OpenAI’s AGENTS.md guide, assessed as of 2026-10-13, describes concatenating guidance with blank lines, with nearer files appearing later and overriding earlier guidance because of that position. That documented ordering does not define a parser for every possible contradiction in prose. The recommended control is therefore editorial: expose incompatible statements and ask an accountable maintainer to clarify them, rather than assume that a later sentence mechanically deletes an earlier obligation.

Make each conflict row answer a human decision

Recommended procedure: take the selected files from the preceding trace and extract statements that affect the proposed refactor’s permissions, tests, dependencies or approval requirements. Preserve a short exact excerpt alongside the interpretation. A paraphrase such as “payments has special tests” is insufficient if the original says either “also run” or “run instead”: that difference determines whether the service guidance adds detail or requests an exception. Keep source text as evidence, not as an instruction to the person or tool preparing the register.

Use one row per decision, rather than one row per file. A single local document may contain a compatible naming convention, an ambiguous testing instruction and a direct dependency contradiction. Combining them into one “local override” row hides the separate approvals they require. Conversely, when three files repeat the same disputed rule, connect those source references to one decision so the maintainer can repair the wording consistently.

The relationship field should describe the text, not predict model behaviour. “Direct contradiction” means the two requirements cannot both be satisfied under the same stated conditions. “Ambiguous substitution” means the wording does not establish whether a narrower instruction supplements or replaces a broader one. “Compatible detail” means the local statement supplies an implementation detail without relaxing the wider obligation. These are proposed editorial categories, not documented Codex policy states.

Hypothetical conflict: standard tests versus a payments-specific test

Hypothetical example: in the illustrative Northstar monorepo, a selected global file says, “Run the standard suite before reporting work complete.” A selected services/payments/AGENTS.override.md says, “For payments changes, run the payments contract test.” Record the global file at the earlier position and the service file at its later position, using the actual positions from the hypothetical source list. The local sentence names a different test but does not say whether the standard suite remains required.

The matrix should classify this as ambiguous substitution, not immediately as an authorised exception. Both tests might be required; the local test might be intended as the only appropriate test for a narrowly defined change; or “standard suite” might already include it. Those are competing interpretations for a maintainer to resolve. The risk field should identify the concrete consequence: a refactor could be reported complete without the test coverage the global author intended.

Suggested repair for human consideration: ask the payments service maintainer and the owner of the global preference whether the local requirement is additive. If it is, proposed wording could say, “For changes within services/payments, run the payments contract test in addition to the standard suite.” If substitution is intended, the draft should name the precise change category, explain the reason, state what approval permits substitution and set a review date. Neither alternative should be installed merely because an agent finds it more convenient.

Hypothetical conflict: a migration note versus a dependency prohibition

Hypothetical example: the root AGENTS.md says, “Do not change dependencies.” A selected service instruction says, “Migrate this service to the new payment client dependency.” Here the matrix should preserve both statements and classify their relationship as a direct contradiction if the migration requires changing a dependency. A service note’s specificity does not itself prove that its author had authority to relax the root restriction.

The scope column should distinguish a request to update service code from permission to alter a package declaration or shared lockfile. A migration can affect files beyond the target service even when its motivation is local. Record that possible boundary expansion as a question for the repository owner. The proposed refactor should remain blocked on that decision if its permitted file set or dependency policy cannot be established.

Suggested repair for human consideration: retain the root prohibition as the durable default and draft a narrowly bounded exception. For example: “For the approved payments-client migration within the named service, the repository owner may authorise the specified dependency and associated lockfile changes. Other dependency changes remain excluded.” The maintainer must supply the actual dependency, permitted paths, test requirements and approval reference. This sample wording is an editorial illustration, not a migration approval or a Codex guarantee.

Hypothetical conflict: a configured fallback repeats stale wording

Hypothetical example: suppose TEAM_GUIDE.md is explicitly present in the effective project_doc_fallback_filenames list and is selected in an intermediate directory. It repeats a root rule but refers to an obsolete test name. OpenAI’s Sample Configuration, assessed as of 2026-10-13, documents an empty default fallback list; the alternate filename in this example is configured, not automatically discovered by virtue of its name.

The conflict row should identify stale duplication rather than treat repeated wording as additional authority. Ask whether the intermediate guide needs a local variation at all. If it does not, the proposed repair can remove the duplicated operational wording and retain only genuinely local guidance, subject to maintainer approval. If it does, rewrite the variation against the current root requirement and explain its scope. Do not silently translate an obsolete test name into a current command: that mapping itself needs evidence.

A shadowed file can still require maintenance even though it is not part of the selected chain. Keep its stale statement in a separate maintenance note, not in the active-rule matrix as though it were loaded. This prevents two different questions from being conflated: which guidance is currently selected, and which repository documents could become misleading after a future rename or removal.

Editorial relevance: Treat a conflict register as a traceable record of incompatible guidance, not as a test result; if a later team evaluates rule wording, a reproducible Codex code-review benchmark for rule signal, reviewer time, and false-positive noise supplies a separate methodology. What that guide describes: its pre-registration example uses a sanitised repository with a pinned base commit and compares no rules, broad root wording, and three concise scoped rules; it leaves result fields blank and retains exclusions in an audit log.

Bound the configuration review to discovery context

The project-root boundary itself is a material preflight input: Codex documents .git as the default marker, supports project_root_markers, and says an empty marker list treats the current directory as the root. This is documented discovery behaviour in OpenAI’s Advanced Configuration and Sample Configuration, assessed as of 2026-10-13. The recommended control is to record the effective setting and its provenance rather than assume the Git root in every environment. [Advanced Configuration; Sample Configuration]

Project .codex/config.toml layers have their own documented path and trust behaviour: they are read from project root to current directory with the closest setting winning, while untrusted projects skip project-scoped .codex configuration, hooks and rules. This is a separate configuration layer from the AGENTS.md chain. OpenAI’s Advanced Configuration and Configuration Reference, assessed as of 2026-10-13, limit that trust statement to the specified project-scoped layers; it does not establish that an untrusted project disables AGENTS.md discovery. [Advanced Configuration; Configuration Reference]

Recommended configuration extract: record only settings needed to explain this instruction-resolution record: root markers, ordered fallback filenames, the maximum-byte setting, whether model_instructions_file is configured, and the relevant trust state. For each, distinguish an observed effective value from a value merely found in a configuration file. A discovered value is not automatically effective if another applicable layer changes it or the project layer is skipped.

Do not attach an entire configuration file merely to demonstrate one setting. Produce a minimal extract with its source location and observation basis, excluding credentials, tokens and personal data. The extract should not become an invitation to tune unrelated model, execution or approval settings. Those decisions belong to separate operational controls and require their own human review.

As of 2026-10-13, OpenAI’s Configuration Reference describes model_instructions_file as “Replacement for built-in instructions instead of AGENTS.md”, while the sample describes overriding built-in base instructions with a file path. The supplied pages do not define its full interaction with global and nested instruction layers. If it is configured, record the path and the unresolved interaction question rather than claiming the ordinary selected-file list is the complete instruction context.

Build a byte-risk ledger without inventing runtime results

Recommended measurement procedure: measure file bytes using an approved local, read-only method against the same repository state used for the source inventory. Record the method and observation time. Count bytes rather than characters or words: those quantities need not be equivalent. Give every candidate a row, including empty and shadowed files, so the ledger explains both the selected total and the material excluded from that total.

Use separate totals for selected project candidates, selected global material and all inspected candidates. This separation makes the arithmetic useful without assuming that every category participates in the same runtime limit. A shadowed file belongs in the inventory total but not the selected-project subtotal. An unreadable file should have “unknown” size and an access question, not zero bytes; zero is a measurement result, not a substitute for missing evidence.

This hypothetical ledger deliberately separates same-directory candidates: OpenAI’s AGENTS.md guide, assessed as of 2026-10-13, specifies at most one selected file per directory. The payment service’s ordinary file is therefore not counted as simultaneously active with its selected override. Its size is retained because a later maintainer-approved removal of the override could change which document needs assessment.

These descriptions come from OpenAI’s AGENTS.md guide and Advanced Configuration. Label their difference unresolved documentation ambiguity until the actual installed client and surface have been verified. The hypothetical project subtotal above exceeds 32,768 bytes while each selected project file is individually smaller; that illustrates why the distinction matters, not what Codex would load or omit.

The ledger should retain the effective project_doc_max_bytes value, the two source excerpts and a question assigned to the client maintainer. Raw file totals do not establish how separators or other instruction material are accounted for. Nor do they reveal whether a particular rule survives a limit. Leave loaded-content conclusions unasserted until the subsequent verification stage supplies evidence appropriate to the named surface.

Repair wording through an accountable approval protocol

Recommended repair protocol: preserve durable repository norms at the root and propose local wording only for genuine local requirements. Before drafting an exception, ask whether the conflict can be removed by defining an existing term more precisely. Clarifying what “standard suite” includes may be preferable to creating a second testing policy. The responsible maintainer should choose the policy; the editor’s role is to make the alternatives and consequences legible.

A proposed local exception should contain six elements: target scope, reason, test or approval implication, accountable owner, review or expiry date, and the wider rule that remains unchanged. A hypothetical template is: “For [named path and change category], [specific exception] is permitted because [reason], subject to [tests and approval]. [Maintainer role] owns this exception; review it on [date]. Outside this scope, [root rule] remains applicable.” Replace the bracketed fields with approved facts before adopting the text.

Removing or renaming accidental shadowing requires a separate maintainer decision. Establish whether the selected override was intentional, compare the obligations in both files, and draft the intended resulting guidance before changing filenames. A rename is not merely tidying: it may change the selected source. Keep the proposed action distinct from its approval and do not authorise an agent to delete a file solely because it appears redundant.

For byte pressure, propose content reduction before changing a limit: remove obsolete duplication, make scope explicit and relocate non-instruction background material where maintainers consider it appropriate. These editorial choices still require review to ensure obligations are not lost. Splitting text across nested directories does not guarantee that truncation cannot occur, and increasing the setting is not presumptively safe. The repository owner must approve the trade-off against the unresolved limit interpretation.

Finish this chapter’s record with a disposition for every row: compatible guidance retained, repair proposed awaiting approval, exception approved by the named owner, or unresolved question blocking authorisation. Keep uncertainties visible even when no wording change is proposed. The next stage can verify and freeze the resulting record, but a complete-looking matrix is not itself evidence that every instruction was loaded, nor permission to begin the scoped refactor.

Verify, Freeze, and Hand Off the Preflight Record

The release deliverable is a dated instruction-resolution record for one target directory, not permission to refactor it. For the hypothetical services/billing target used here, the repository owner should be able to answer three questions from that record: which sources were predicted to contribute guidance, what verification evidence supports that prediction, and which uncertainties still constrain the next task. This chapter proposes an editorial handoff procedure. It does not report a hands-on monorepo test, code review, security audit or production validation.

Keep the prediction, the verification response and the human decision as separate parts of the record. Combining them into a single “effective instructions” narrative makes it difficult to distinguish a documented selection rule from an assistant’s summary or a maintainer’s interpretation. A useful release record preserves disagreement rather than smoothing it away: if the predicted chain and reported sources differ, the discrepancy needs an owner and a disposition before consequential work proceeds.

Package one target into a reviewable record

Recommended record format: use a short cover sheet followed by structured evidence tables. Give the record an identifier, preparation date, target directory, repository revision or other approved snapshot reference, preparer and accountable repository owner. State its status as draft, awaiting clarification, approved for a named follow-on task, or superseded. These are suggested editorial statuses, not Codex interface labels. Avoid a bare “approved” status whose scope cannot be recovered later.

In the source table, define the status vocabulary before using it. “Selected” should mean selected by the documented discovery prediction, unless the column explicitly says “reported selected”. “Shadowed” should identify a candidate displaced by another candidate in the same directory. “Ignored” needs a reason, such as outside the target path or not in the configured discovery list. Record absent and empty candidates separately where their existence matters to the prediction; neither should be disguised as a source that contributed instructions.

Hypothetical table entry: if an inventory for services/billing contains both AGENTS.override.md and AGENTS.md in that directory, the record could identify the override as the predicted selection and the other file as shadowed, subject to the earlier eligibility checks. Do not place both in the predicted chain. Keep the shadowed file’s approved reference because a maintainer may need to assess whether the override intentionally excludes still-current guidance. This is an illustrative inventory, not an observed repository.

The configuration notes should explain why a setting matters, not reproduce a private configuration dump. For example, the root-marker entry answers “where does this trace begin?”, while the fallback entry answers “which additional filenames are candidates?”. A trust-context entry should state the evidence available for the relevant .codex layers without extending it into an unsupported conclusion about instruction discovery. This keeps configuration questions actionable without reopening the entire chain analysis.

The configuration reference identifies model_instructions_file as a replacement for built-in instructions instead of AGENTS.md, so the preflight template must ask whether this separate mechanism is configured and mark its interaction as a boundary requiring confirmation rather than assume the ordinary repository-instruction chain is the full instruction context. OpenAI’s Configuration Reference and Sample Configuration, assessed as of 2026-10-13, do not specify every interaction with global and nested AGENTS.md layering. The editorial recommendation is to record whether the setting is present, preserve an approved reference to its source, and seek maintainer clarification if it leaves the effective instruction context uncertain. [Configuration Reference; Sample Configuration]

Keep byte uncertainty visible at release

OpenAI’s official documentation contains a byte-limit wording conflict that the article must surface rather than silently reconcile: the AGENTS.md page describes a combined-size stopping point, while Advanced Configuration describes project_doc_max_bytes as how much is read from each AGENTS.md file. This is a documentation assessment as of 2026-10-13, not a claimed runtime test result. The recommended release record retains both verbatim excerpts below, measures candidate files for risk, and seeks verification for the installed client and surface through documented source reporting or authorised logs before relying on either interpretation. [Custom instructions with AGENTS.md; Advanced Configuration]

“Codex skips empty files and stops adding files once the combined size reaches the limit defined by project_doc_max_bytes (32 KiB by default).” — OpenAI, Custom instructions with AGENTS.md, assessed as of 2026-10-13.

“project_doc_max_bytes: how much to read from each AGENTS.md file” — OpenAI, Advanced Configuration, assessed as of 2026-10-13.

The byte ledger should preserve the measurements actually taken, including the snapshot and method, rather than substitute character counts or estimates from an assistant. Show individual candidate sizes and the proposed chain’s aggregate size as risk indicators, not as proof of what reached the model. Where the effective limit is unknown, mark that field unknown and assign the configuration owner. An assumed default is not evidence of the setting used by the proposed work environment.

Recommended decision rule: if the owner cannot establish that essential guidance is represented adequately, hold authorisation for tasks that depend on it. Available responses include clarifying the installed behaviour, reducing redundant instruction text through a separately approved documentation change, or narrowing the next task. Splitting material into nested files is not a guarantee against truncation. Increasing a limit also requires repository-owner review; it should not become an unrecorded convenience adjustment during verification.

Run a bounded, non-destructive verification sequence

Before choosing a verification route, identify the exact surface. A command-line interface (CLI) procedure is not evidence of identical behaviour in a desktop application, integrated development environment (IDE), web surface or managed cloud environment. Likewise, a terminal user interface (TUI) log route should be selected only where applicable. OpenAI’s Help Center article Using Codex with your ChatGPT plan, assessed as of 2026-10-13, makes Cloud availability dependent on eligible plans, rollout and workspace settings. This preflight therefore cannot promise access for a particular account or workspace.

Codex documents several ways to verify the record: prompts to summarise current instructions or show active instruction files, optional plaintext TUI logging through log_dir, session logs when enabled, and rebuilding the chain on each run or TUI-session start. OpenAI’s Custom instructions with AGENTS.md, assessed as of 2026-10-13, is the source for these routes. Logging is opt-in or contingent on being enabled, not universal. The suggested use here is evidence gathering before authorisation, not permission to make code changes. [Custom instructions with AGENTS.md]

1. Confirm the verification envelope. Have the repository owner approve the target, evidence destination and available execution controls. State that the task is to report instruction sources and uncertainty, without editing files, running service tests or beginning implementation.
2. Start from the recorded target. Begin a new run, or restart the applicable session, with the working directory set to the same target used in the prediction. Preserve the approved launch context. Do not compare a run started at the repository root with a prediction prepared for services/billing.
3. Request source reporting. Ask which instruction files are active, then request a concise summary where needed to compare important rule topics. Keep those requests separate from any engineering task, so the evidence does not become entangled with a proposed refactor.
4. Compare before interpreting. Match reported paths against the predicted ordered table. Record missing, additional or differently ordered sources and any limits of the response. Do not silently revise the prediction merely to agree with the assistant.
5. Collect additional evidence only if authorised. Where applicable and selected by the owner, use the documented logging route. Review the relevant extracts for sensitivity before attaching them, and state what each extract supports.
6. Return discrepancies to a human. Assign unresolved differences to the configuration owner or service maintainer. End the verification task with a record update, not with an attempt to repair configuration or source files automatically.

Hypothetical verification prompt: “For this preflight only, show the active instruction file paths you can report for the current working directory. Then summarise the guidance relevant to the proposed billing-service scope. Distinguish reported sources from uncertainty. Do not edit files, run service tests or begin a refactor.” This is a suggested request, not a guarantee that a client will enumerate every instruction source or obey every boundary without appropriate human supervision and execution controls.

For a CLI environment, the AGENTS.md guide’s source-reporting example can be adapted to the hypothetical target as follows. The command is an illustration of the documented request pattern, not a tested command for the reader’s installation. In particular, --ask-for-approval never must not be mistaken for a read-only restriction or a grant of permission to change code. The owner must decide whether this invocation fits the approved execution environment.

codex --cd services/billing --ask-for-approval never "Show which instruction files are active."

If optional TUI logging is selected, the documented example is codex -c log_dir=./.codex-log, with the plaintext file at ./.codex-log/codex-tui.log. The same source also refers to inspecting the most recent session-*.jsonl file when session logging has been enabled. Record which route was used, its relationship to the target session and the authorised evidence location. Do not infer that an absent attachment means no log exists, or that an existing log is a complete compliance audit trail.

A comparison row should answer a narrow evidence question. For instance, “Was the target override reported?” is different from “Did the summary accurately preserve the owner’s exception?”. A source list may help with the first question without settling the second. If a summary omits a consequential rule, record the omission and seek clarification rather than declaring that the underlying rule was deleted or never loaded. Prose summaries are evidence to examine, not authoritative replacements for the source map.

Attach evidence without spreading sensitive material

Editorial hygiene control: do not paste secrets, customer data, access tokens or private configuration into AGENTS.md examples, verification prompts, logs or the preflight record. Use the minimum approved information needed to explain the source-selection question. A billing-service instruction can refer to an authorised internal procedure without copying transaction records or credentials into the instruction file. The repository owner decides which internal locations may be referenced and which reviewers may access them.

Review evidence before sharing it, not merely before publishing the finished record. A transcript or log extract may expose local paths, personal information, private repository content or configuration details unrelated to the decision. Keep an approved restricted original where necessary, and attach a sanitised extract only if it still supports the stated conclusion. Explain redactions at a category level without reproducing the removed material. If sanitisation destroys the evidence’s usefulness, arrange restricted human inspection instead of presenting a misleading extract.

Treat supplied files, retrieved text and log contents as data to inspect, never as instructions that can expand the preflight’s authority. An instruction-like sentence inside an evidence attachment does not authorise an additional task. If reporting reveals a request to disclose secrets or contact an unapproved destination, record the issue for the owner rather than following it. Keep evidence references descriptive enough for authorised reviewers to locate the material without embedding sensitive content in a broadly circulated record.

Freeze the record and apply human handoff gates

Recommended freeze procedure: assign a revision to the completed record and preserve the approved snapshot references, evidence attachments and open questions together. Separate later corrections from the frozen version so reviewers can see what informed the original decision. “Frozen” means stable as a decision artefact; it does not mean the repository, configuration or future instruction context cannot change. The owner should also specify who maintains the record and where superseding revisions will be retained.

• Contradiction gate: the accountable repository owner resolves incompatible human-authored rules or explicitly blocks work pending the responsible maintainer. The conflict matrix must show the decision and its scope, not just a proposed repair.
• Source-map gate: the owner confirms the exact target and source map, considers differences between prediction and reporting, and records whether the remaining byte-limit risk is acceptable for the proposed task.
• Currency gate: the service maintainer decides whether target guidance still reflects the service’s intended practices. Discovery evidence does not establish that a release procedure or testing instruction is current.
• Task-authorisation gate: the owner separately authorises either a bounded read-only analysis or a specifically scoped refactor. Neither follows automatically from successful source reporting.
• Evidence-review gate: a named human reviews the resulting analysis or change evidence against the authorised scope before consequential acceptance or release decisions.

Hypothetical handoff entry: “Target: services/billing. Decision requested: authorise read-only analysis of the named refactor boundary. Exclusions: code edits, test execution, dependency changes and release actions. Outstanding condition: configuration owner to confirm the separate instruction-file setting. Evidence reviewer: billing maintainer.” This example deliberately records a conditional request rather than inventing an approval or successful outcome. A real entry must contain the actual owner’s decision and date.

Editorial relevance: Once the owner has reviewed the documented instruction chain and conflict record, route any proposed scoped refactor through an explicit approval boundary with Codex stable-versus-alpha release channels, canary repositories, permissions, checkpoints, and rollback. What that guide describes: its stakeholder-approval section separates authority for tools, code, and risk, while its rollback discussion says tasks should record the tool version and prompt, capture before-and-after Git checkpoints, run tests, and retain evidence. It addresses release governance, not authorisation derived from repository instruction files.

For a separately authorised refactor, carry forward the record identifier, allowed paths, intended change, prohibited actions and review responsibility into the new task brief. Do not copy the entire evidence archive into the prompt. The handoff should make the next task’s authority clear while preserving access-controlled references for reviewers. These gates are governance recommendations, not automatic Codex capabilities, and none removes the need for human review of consequential decisions.

Keep the decision artefact current

Revisit the record when the effective CODEX_HOME, fallback filenames, root-marker configuration, working directory, repository instruction files, client version or surface changes. A change to the scoped service or intended task can also invalidate an earlier judgement about which guidance matters. Require the next preparer to identify changed inputs first, then update the affected prediction, evidence and approvals. Reusing the cover sheet without checking those inputs defeats the purpose of retaining it.

Retain the dated record as an explanation of a human decision made with specified evidence. It is not proof of future behaviour, complete instruction compliance or production readiness. A useful close-out states what was verified, what remained uncertain, who accepted those limits and what task was authorised next. That is the release boundary for this preflight: a reviewable basis for a separate decision, rather than an engineering outcome claimed in advance.

Useful Links

• Custom instructions with AGENTS.md — discovery guidance and documented verification routes.
• Advanced Configuration — root context and the byte-limit wording requiring confirmation.
• Configuration Reference — setting definitions and configuration boundaries.
• Sample Configuration — annotated configuration examples for comparison with effective settings.
• Using Codex with your ChatGPT plan — account and workspace availability qualifications.