AGENTS.md: two stale file references, two internal restatements, and two doc-vs-enforcement mismatches

Open 💬 1 comment Opened Aug 11, 2026 by StartupBros

What is the type of issue? Documentation is incorrect

What is the issue?

First: AGENTS.md is one of the most accurate agent-context files we've audited — commit citations check out (e.g. the 3c7f013f9735/#16630 RPITIT precedent matches its PR exactly), every justfile recipe and test helper it names exists, and the nested codex-rs/tui/src/bottom_pane/AGENTS.md cleanly complements it. The items below are drift, not quality problems. All verified at 41ece455b7fa (2026-08-11).

  1. Stale path (line 35): codex-rs/codex-mcp/src/mcp_connection_manager.rs no longer exists — renamed to connection_manager.rs in #34522, with the central type renamed McpConnectionManagerMcpConnectionSet in #34708. Both landed after AGENTS.md's most recent edit (f73a072246, 2026-07-08).
  2. Stale reference (lines 264-265): app-server-protocol/src/protocol/v2.rs is listed as a file, but it became a v2/ module directory (~20 submodules) in #21251 (2026-05-05); v1.rs is still flat, so the asymmetry reads as intentional when it isn't.
  3. Restatement: the skip_serializing_if ban at lines 278-280 is repeated near-verbatim at lines 291-292 in the same section.
  4. Restatement + vague qualifier: chatwidget.rs growth discipline is stated at lines 54-57 (high-touch file list) and again at lines 60-61, the second copy hinging on an undefined "unless the change is trivial".
  5. Doc-vs-enforcement mismatch (line 184-187): the file's only bolded "Requirement:" — insta snapshot coverage for UI-affecting changes — has no automated backing: no workflow or script checks snapshot presence (verified with word-boundary greps; naive insta greps false-positive on "install"), and .github/CODEOWNERS has no entry for codex-rs/tui/. Either a check or softer wording would make the doc match reality.
  6. Dual-toolchain expectation gap (lines 64-70): contributors are told to verify with Cargo-native commands (just test → nextest, just fix → cargo clippy), but the sole required status check (CI required via blocking-ci.yml) runs tests and clippy through Bazel (bazel test //..., bazel build --config=clippy); rust-ci.yml contributes only rustfmt, cargo-shear, and a custom lint. Local-green therefore doesn't guarantee CI-green (independent target graphs/pins). One sentence in AGENTS.md setting that expectation would save contributors a surprise.

Where did you find it? AGENTS.md at repo root, cross-checked against the live branch ruleset (gh api repos/openai/codex/rules/branches/main), .github/workflows/{blocking-ci,rust-ci,bazel}.yml, and the commit history of each referenced path. Found during an automated AGENTS.md audit (rent-check); every claim above was independently re-verified before filing.

View original on GitHub ↗

1 Comment

StartupBros · 17 days ago

Since this repo limits PR creation to collaborators, here is the ready-to-apply patch for the two mechanical items (the stale paths — items 1 and 2 above). Cherry-pick from StartupBros/codex@764198a39212434267d5d2d0b9cec0fee665bd11 (branch fix-agents-md-stale-paths), or apply directly:

--- a/AGENTS.md
+++ b/AGENTS.md
@@ line 35
-- When working with MCP tool calls, prefer using `codex-rs/codex-mcp/src/mcp_connection_manager.rs` to handle mutation of tools and tool calls. Aim to minimize the footprint of changes and leverage existing abstractions rather than plumbing code through multiple levels of function calls.
+- When working with MCP tool calls, prefer using `codex-rs/codex-mcp/src/connection_manager.rs` to handle mutation of tools and tool calls. Aim to minimize the footprint of changes and leverage existing abstractions rather than plumbing code through multiple levels of function calls.
@@ line 265
 - `app-server-protocol/src/protocol/common.rs`
-- `app-server-protocol/src/protocol/v2.rs`
+- `app-server-protocol/src/protocol/v2/`
 - `app-server/README.md`
@@ line 276
-- Exception: config RPC payloads are expected to use snake_case to mirror config.toml keys (see the config read/write/list APIs in `app-server-protocol/src/protocol/v2.rs`).
+- Exception: config RPC payloads are expected to use snake_case to mirror config.toml keys (see the config read/write/list APIs in `app-server-protocol/src/protocol/v2/`).

Path-only changes; v1.rs is genuinely still a flat file, so only the v2 references change. Items 3-6 (restatements, the snapshot-Requirement backing, the Cargo/Bazel expectation sentence) are left to maintainer judgment.