feat: add XP-009 for Codex's cumulative instruction-chain cap (#1289)

.github/tool-release-baselines.json

@@ -204,7 +204,7 @@
       ],
       "github_repo": "cline/cline",
       "release_tag_regex": "^v[0-9]+\\.[0-9]+\\.[0-9]+$",
-      "last_known_version": "v4.0.12",
+      "last_known_version": "v4.1.2",
       "tracked": true,
       "notes": "Tracks only the core Cline vX.Y.Z release train. The repository also publishes desktop-v*, cli-v*, sdk/*, and other interleaved releases that do not correspond to the validator surfaces.",
       "changes_of_interest": {

AGENTS.md

@@ -57,7 +57,7 @@ editors/
 ├── vscode/         # VS Code extension
 ├── jetbrains/      # JetBrains IDE plugin
 └── zed/            # Zed extension
-knowledge-base/     # 442 rules, 75+ sources, rules.json
+knowledge-base/     # 443 rules, 75+ sources, rules.json
 
 tests/fixtures/     # Test cases by category
 ```
@@ -178,7 +178,7 @@ cargo run --bin agnix-mcp   # Run MCP server
 
 ## Rules Reference
 
-442 rules defined in `knowledge-base/rules.json` (source of truth)
+443 rules defined in `knowledge-base/rules.json` (source of truth)
 
 
 Human-readable docs: `knowledge-base/VALIDATION-RULES.md`
@@ -190,7 +190,7 @@ Format: `[CATEGORY]-[NUMBER]` (AS-004, CC-HK-001, etc.)
 ## Current State
 
 - v0.37.3 - Production-ready with full validation pipeline
-- 442 validation rules across 40 validators
+- 443 validation rules across 40 validators
 
 - 4200+ passing tests
 - LSP + MCP servers with VS Code extension

CHANGELOG.md

@@ -18,6 +18,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CC-MEM-014 fired on Cursor `.mdc` files**. `ClaudeMdValidator` is registered for `FileType::CursorRule` for its generic prose checks, so a `.cursor/rules/*.mdc` file was reported as `CLAUDE.md has N non-empty lines, exceeding the recommended 200 line limit` - wrong filename, wrong threshold (Cursor documents 500), wrong tool attribution. Now scoped to Claude memory files.
 - **Stale evidence URLs for 18 rules**. `docs.github.com/en/copilot/customizing-copilot` 301-redirects and `docs.cline.bot/features/cline-rules/overview` 308-redirects; both are updated in `rules.json` and `.github/spec-baselines.json`, so those two sentinel sources can match again.
 
+### Added
+- **XP-009: Codex Instruction Chain Exceeds project_doc_max_bytes**. Codex's 32 KiB `project_doc_max_bytes` cap is cumulative across the instruction chain, not per-file - it "stops adding files once the combined size reaches the limit". XP-007 checks each `AGENTS.md` in isolation, so a project split across several mid-size files was truncated with no diagnostic at all. The new project-level rule builds the chain the way Codex discovers it (root down, at most one file per directory, `AGENTS.override.md` before `AGENTS.md`), sums root-first, and reports on the file where the running total crosses the limit - that file and everything deeper is what Codex drops. Rule count 442 -> 443 (closes #1289).
+
+### Fixed
+- **`AGENTS.override.md` was not recognized as an instruction file**. Codex checks it before `AGENTS.md` in each directory, but `is_instruction_file()` did not list it, so it was invisible to every cross-platform rule. This also made the `AGENTS.override.md` handling added to XP-007 in the previous release unreachable in practice.
+
 ### Added
 - **`args` on command hooks**. The exec-form field - "When present, `command` is resolved as an executable and spawned directly with `args` as the argument vector, with no shell involved" - was absent from the schema, so it was silently ignored and two rules could not tell exec form from shell form.
 

CLAUDE.md

@@ -57,7 +57,7 @@ editors/
 ├── vscode/         # VS Code extension
 ├── jetbrains/      # JetBrains IDE plugin
 └── zed/            # Zed extension
-knowledge-base/     # 442 rules, 75+ sources, rules.json
+knowledge-base/     # 443 rules, 75+ sources, rules.json
 
 tests/fixtures/     # Test cases by category
 ```
@@ -178,7 +178,7 @@ cargo run --bin agnix-mcp   # Run MCP server
 
 ## Rules Reference
 
-442 rules defined in `knowledge-base/rules.json` (source of truth)
+443 rules defined in `knowledge-base/rules.json` (source of truth)
 
 
 Human-readable docs: `knowledge-base/VALIDATION-RULES.md`
@@ -190,7 +190,7 @@ Format: `[CATEGORY]-[NUMBER]` (AS-004, CC-HK-001, etc.)
 ## Current State
 
 - v0.37.3 - Production-ready with full validation pipeline
-- 442 validation rules across 40 validators
+- 443 validation rules across 40 validators
 
 - 4200+ passing tests
 - LSP + MCP servers with VS Code extension

README.md

@@ -12,7 +12,7 @@
   </p>
 </div>
 
-<p align="center">Catch broken agent configs before your AI tools silently ignore them.<br>442 rules across Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and more -<br>validating CLAUDE.md, SKILL.md, hooks, MCP configs, and other agent files.</p>
+<p align="center">Catch broken agent configs before your AI tools silently ignore them.<br>443 rules across Claude Code, Codex CLI, OpenCode, Cursor, Copilot, and more -<br>validating CLAUDE.md, SKILL.md, hooks, MCP configs, and other agent files.</p>
 
 <p align="center"><strong>Auto-fix</strong> | <strong><a href="https://github.com/marketplace/actions/agnix-ci">GitHub Action</a></strong> | <strong><a href="https://marketplace.visualstudio.com/items?itemName=avifenesh.agnix">VS Code</a> + <a href="https://plugins.jetbrains.com/plugin/30087-agnix">JetBrains</a> + <a href="https://github.com/agent-sh/agnix.nvim">Neovim</a> + <a href="https://zed.dev/extensions?query=agnix">Zed</a></strong></p>
 
@@ -37,7 +37,7 @@
 
 **Bad patterns get amplified.** AI assistants don't ignore wrong configs - they [learn from them](https://www.augmentcode.com/guides/enterprise-coding-standards-12-rules-for-ai-ready-teams).
 
-agnix validates all of it - 442 rules sourced from official specs, academic research, and real-world breakage patterns. Auto-fix included.
+agnix validates all of it - 443 rules sourced from official specs, academic research, and real-world breakage patterns. Auto-fix included.
 
 > **Want to try it first?** [Open the playground](https://agent-sh.github.io/agnix/playground) - paste any agent config, see diagnostics instantly. No install, runs in your browser.
 

SPEC.md

@@ -16,7 +16,7 @@
 | Claude Output Styles | .claude/output-styles/*.md | 6 |
 | Claude Settings | .claude/settings.json | 20 |
 | Prompt Engineering | CLAUDE.md, AGENTS.md | 6 |
-| Cross-Platform | AGENTS.md | 9 |
+| Cross-Platform | AGENTS.md | 10 |
 | MCP | tool definitions | 26 |
 | XML | all .md files | 3 |
 | References | @imports | 4 |

crates/agnix-cli/locales/en.yml

@@ -402,6 +402,9 @@ rules:
     message: 'CLAUDE.md contains Claude-specific feature ''%{feature}'' that Cursor cannot interpret: %{description}'
     suggestion: Move Cursor-compatible instructions to .cursor/rules/ or guard Claude-specific content under a '## Claude
       Code' section header
+  xp_009:
+    message: 'Codex instruction chain reaches %{bytes} bytes across %{count} file(s), past the %{limit}-byte project_doc_max_bytes default. Codex stops appending once the combined size hits the limit, so this file and any deeper ones are dropped.'
+    suggestion: Trim the chain, or raise project_doc_max_bytes in the Codex config (e.g. project_doc_max_bytes = 65536)
   cop_001:
     message_empty: Copilot instruction file is empty
     message_no_content: Copilot instruction file has no content after frontmatter

crates/agnix-core/locales/en.yml

@@ -402,6 +402,9 @@ rules:
     message: 'CLAUDE.md contains Claude-specific feature ''%{feature}'' that Cursor cannot interpret: %{description}'
     suggestion: Move Cursor-compatible instructions to .cursor/rules/ or guard Claude-specific content under a '## Claude
       Code' section header
+  xp_009:
+    message: 'Codex instruction chain reaches %{bytes} bytes across %{count} file(s), past the %{limit}-byte project_doc_max_bytes default. Codex stops appending once the combined size hits the limit, so this file and any deeper ones are dropped.'
+    suggestion: Trim the chain, or raise project_doc_max_bytes in the Codex config (e.g. project_doc_max_bytes = 65536)
   cop_001:
     message_empty: Copilot instruction file is empty
     message_no_content: Copilot instruction file has no content after frontmatter

crates/agnix-core/src/rules/project_level.rs

@@ -1,9 +1,11 @@
-//! Project-level cross-file validation rules (AGM-006, XP-004/005/006, VER-001).
+//! Project-level cross-file validation rules (AGM-006, XP-004/005/006, XP-009,
+//! VER-001).
 // All items in this module require the filesystem feature. The file-level inner
 // attribute avoids repeating #[cfg(feature = "filesystem")] on each import and
 // function - unlike pipeline.rs, this file has no non-filesystem items.
 #![cfg(feature = "filesystem")]
 
+use std::collections::BTreeMap;
 use std::path::{Path, PathBuf};
 
 use rust_i18n::t;
@@ -13,6 +15,7 @@ use crate::diagnostics::Diagnostic;
 use crate::file_utils;
 use crate::parsers::frontmatter::normalize_line_endings;
 use crate::schemas;
+use crate::schemas::cross_platform::CODEX_BYTE_LIMIT;
 
 /// Join an iterator of paths into a comma-separated string.
 ///
@@ -148,6 +151,30 @@ pub(crate) fn run_project_level_checks(
             }
         }
 
+        // Drop any `AGENTS.md` shadowed by an `AGENTS.override.md` in the same
+        // directory. Codex "includes at most one file per directory", checking
+        // the override first, so the shadowed file is never loaded - the doc's
+        // own tree labels it "Ignored because an override exists". Comparing the
+        // two as peers reported a conflict between a file and the thing whose
+        // whole purpose is to differ from it.
+        let shadowed: std::collections::BTreeSet<PathBuf> = file_contents
+            .iter()
+            .filter(|(path, _)| {
+                // Case-insensitive, matching `is_instruction_file()`. The three
+                // places that name this file have to agree: that helper collects
+                // it case-insensitively, so an exact-match filter here left a
+                // lowercase `agents.override.md` shadowing nothing while still
+                // being treated as an instruction file.
+                path.file_name()
+                    .and_then(|n| n.to_str())
+                    .is_some_and(|n| n.eq_ignore_ascii_case("AGENTS.override.md"))
+            })
+            .filter_map(|(path, _)| path.parent().map(|dir| dir.join("AGENTS.md")))
+            .collect();
+        if !shadowed.is_empty() {
+            file_contents.retain(|(path, _)| !shadowed.contains(path));
+        }
+
         // XP-004/005/006: each detector runs on a per-rule filtered subset
         // of `file_contents`. A file whose `[[overrides]]` disable the rule
         // is removed from that rule's candidate set up front, so the
@@ -307,9 +334,177 @@ pub(crate) fn run_project_level_checks(
         }
     }
 
+    // XP-009: the Codex instruction chain exceeds `project_doc_max_bytes`.
+    //
+    // XP-007 checks each AGENTS.md against the 32 KiB default in isolation, but
+    // the documented cap is cumulative: Codex "stops adding files once the
+    // combined size reaches the limit defined by `project_doc_max_bytes`". A
+    // project split across several mid-size files is therefore truncated with no
+    // per-file diagnostic - the gap recorded in the XP-007 rule docs.
+    //
+    // Modelled on the documented discovery rules: start at the project root,
+    // walk down, take at most one file per directory in the order
+    // `AGENTS.override.md`, `AGENTS.md`, then any configured
+    // `project_doc_fallback_filenames`. Names outside that set "are ignored for
+    // instruction discovery" and so do not count.
+    if config.is_rule_enabled("XP-009") {
+        // One chain per leaf directory, not one total for the whole tree.
+        //
+        // A Codex chain is a single root-to-cwd path: two sibling packages are
+        // never concatenated. Summing every discovered file into one running
+        // total blamed a sibling for bytes it does not share - and it scaled the
+        // wrong way, since N packages would eventually cross the cap no matter
+        // how small each one is. It also contradicted AGM-006 above, which
+        // recommends splitting across nested directories precisely to stay under
+        // this cap.
+        let chains = codex_instruction_chains(instruction_file_paths, root_dir);
+
+        // Attribute each over-cap chain to the *largest* file in it, not to the
+        // file where the running total happens to cross.
+        //
+        // Those differ, and the difference matters: a 30 KB root with twenty 5 KB
+        // packages crosses inside each package, so blaming the crossing file
+        // produced twenty diagnostics against twenty 5 KB files for a problem
+        // that only trimming the 30 KB root fixes. Trimming any one of them
+        // removes 5 KB from a chain that needs 30 KB removed, and the suggestion
+        // points at the file it names. Attributing to the biggest contributor
+        // names the one edit that resolves every affected chain, and collapses
+        // those twenty reports into one.
+        let mut reported: BTreeMap<PathBuf, (usize, usize)> = BTreeMap::new();
+
+        for chain in &chains {
+            let mut sizes: Vec<(PathBuf, usize)> = Vec::with_capacity(chain.len());
+            let mut total = 0usize;
+            for path in chain {
+                let Ok(content) = config.fs().read_to_string(path) else {
+                    continue;
+                };
+                total += content.len();
+                sizes.push((path.clone(), content.len()));
+            }
+
+            if total <= CODEX_BYTE_LIMIT {
+                continue;
+            }
+
+            // Largest first, then shallowest, so the choice is deterministic when
+            // two files tie.
+            let Some((culprit, _)) = sizes
+                .iter()
+                .max_by_key(|(path, size)| (*size, std::cmp::Reverse(path.components().count())))
+            else {
+                continue;
+            };
+
+            reported
+                .entry(culprit.clone())
+                .and_modify(|entry| {
+                    if total > entry.0 {
+                        *entry = (total, chain.len());
+                    }
+                })
+                .or_insert((total, chain.len()));
+        }
+
+        for (report_path, (running_total, chain_len)) in reported {
+            if config.for_path(&report_path).is_rule_enabled("XP-009") {
+                diagnostics.push(
+                    Diagnostic::warning(
+                        report_path,
+                        1,
+                        1,
+                        "XP-009",
+                        t!(
+                            "rules.xp_009.message",
+                            bytes = running_total,
+                            limit = CODEX_BYTE_LIMIT,
+                            count = chain_len
+                        ),
+                    )
+                    .with_suggestion(t!("rules.xp_009.suggestion")),
+                );
+            }
+        }
+    }
+
     diagnostics
 }
 
+/// Build every Codex instruction chain for XP-009, one per leaf directory.
+///
+/// A chain is a single root-to-directory path: "Starting at the project root
+/// (typically the Git root), Codex walks down to your current working
+/// directory", taking at most one file per directory in the order
+/// `AGENTS.override.md`, then `AGENTS.md`. Sibling subtrees are separate
+/// chains and are never concatenated, so each is summed on its own.
+///
+/// Only files the project walk already collected are considered, so this adds no
+/// filesystem traversal. Each chain is returned root-first, the order Codex
+/// concatenates in.
+fn codex_instruction_chains(
+    instruction_file_paths: &[PathBuf],
+    root_dir: &Path,
+) -> Vec<Vec<PathBuf>> {
+    // `AGENTS.override.md` first, then `AGENTS.md`. Codex also honors any
+    // `project_doc_fallback_filenames`, but those live in the user's Codex
+    // `config.toml` rather than anything agnix reads, so the chain is built from
+    // the two default names. A project relying on fallbacks would have a longer
+    // real chain, which makes this conservative: it can under-report, never
+    // over-report.
+    let precedence: [&str; 2] = ["AGENTS.override.md", "AGENTS.md"];
+
+    // One entry per directory, keeping only the highest-precedence name there.
+    let mut by_dir: BTreeMap<PathBuf, PathBuf> = BTreeMap::new();
+    for path in instruction_file_paths {
+        let Some(name) = path.file_name().and_then(|n| n.to_str()) else {
+            continue;
+        };
+        // Case-insensitive for the same reason as the shadow filter above.
+        let Some(rank) = precedence.iter().position(|p| p.eq_ignore_ascii_case(name)) else {
+            continue;
+        };
+        let Some(dir) = path.parent() else { continue };
+        if !dir.starts_with(root_dir) {
+            continue;
+        }
+        by_dir
+            .entry(dir.to_path_buf())
+            .and_modify(|existing| {
+                let existing_rank = existing
+                    .file_name()
+                    .and_then(|n| n.to_str())
+                    .and_then(|n| precedence.iter().position(|p| p.eq_ignore_ascii_case(n)))
+                    .unwrap_or(usize::MAX);
+                if rank < existing_rank {
+                    *existing = path.clone();
+                }
+            })
+            .or_insert_with(|| path.clone());
+    }
+
+    // A leaf is a directory with no deeper instruction-bearing descendant. Every
+    // leaf yields one chain: itself plus each ancestor that holds a file.
+    let dirs: Vec<&PathBuf> = by_dir.keys().collect();
+    dirs.iter()
+        .filter(|dir| {
+            !dirs
+                .iter()
+                .any(|other| other != *dir && other.starts_with(dir.as_path()))
+        })
+        .map(|leaf| {
+            let mut chain: Vec<PathBuf> = by_dir
+                .iter()
+                .filter(|(dir, _)| leaf.starts_with(dir.as_path()))
+                .map(|(_, file)| file.clone())
+                .collect();
+            // BTreeMap iteration is shallow-to-deep for nested paths, matching
+            // root-down concatenation; sort defensively on depth anyway.
+            chain.sort_by_key(|p| p.components().count());
+            chain
+        })
+        .collect()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

crates/agnix-core/src/schemas/cross_platform.rs

@@ -1005,6 +1005,10 @@ pub fn is_instruction_file(path: &Path) -> bool {
     // Direct filename matches (case-insensitive)
     if file_name.eq_ignore_ascii_case("claude.md")
         || file_name.eq_ignore_ascii_case("agents.md")
+        // Codex checks `AGENTS.override.md` before `AGENTS.md` in each
+        // directory, so it is part of the instruction set and counts toward
+        // `project_doc_max_bytes` (XP-007, XP-009).
+        || file_name.eq_ignore_ascii_case("agents.override.md")
         || file_name.eq_ignore_ascii_case("gemini.md")
         || file_name.eq_ignore_ascii_case("gemini.local.md")
         || file_name.eq_ignore_ascii_case(".clinerules")