Hot-context managed block uses Claude-only @import in AGENTS.md, dropping hot-tier content for non-Claude tools

[amrmelsayed]

Bug

Since #1119, the generated CODEV HOT CONTEXT block (written by codev init / codev update into both root docs) replaced the inlined contents of arch-critical.md / lessons-critical.md with two Claude Code @import lines:

@codev/resources/arch-critical.md
@codev/resources/lessons-critical.md

renderHotContextBlock() in packages/codev/src/lib/managed-block.ts renders one block and syncHotContextBlock() writes it to both ROOT_DOCS (CLAUDE.md and AGENTS.md, deliberately byte-identical).

For CLAUDE.md this is an improvement: Claude Code expands @import at session launch, the hot files stay the single source of truth, no copy to drift (exactly #1119's rationale).

For AGENTS.md it is a regression for most non-Claude consumers: the agents.md standard defines no import mechanism ("just standard Markdown"; import support is open request agentsmd/agents.md#11), so @-expansion is a per-tool extension. Verified consumer matrix (2026-07-19, methods in the comments below):

Consumer	@import expanded?	Evidence
Claude Code	yes	product feature
Copilot CLI	yes (relative in-repo paths)	GitHub docs
Codex CLI	no	empirical (codex-cli 0.142.5) + official docs (discovery/concat only, no in-file imports)
Antigravity CLI (agy)	no	empirical (inline fact reached context, @import fact did not)
OpenCode	no	open feature request anomalyco/opencode#2225
Cursor (AGENTS.md path)	no documented support	@file refs documented only for .cursor/rules/*.mdc
Copilot coding agent / VS Code	undocumented	no expansion claim in docs

Sharpest consequence: consult's own non-Claude lanes (codex and agy) are empirically confirmed to lose the hot tier. Every CMAP review run in an updated project has its codex and gemini lenses reasoning without the always-on facts and lessons. This is self-inflicted on our consultation stack, not just a third-party-adopter concern. Also observed in an adopting project after its latest codev update: ~65 lines of inlined hot content in AGENTS.md replaced by the two literal import lines.

Porch phase prompts are unaffected (they consume the hot files at runtime via readHotTierFiles()).

Why per-tool native reference mechanisms are NOT a substitute

Several tools do offer their own way to pull extra files into always-on context, so "reference instead of inline" was evaluated per tool:

Tool	Native mechanism	Usable for the hot tier?
OpenCode	opencode.json → instructions array (repo-committed, glob-capable)	yes, cleanly
Cursor	.cursor/rules/*.mdc with alwaysApply: true + @file refs	yes
Copilot CLI	@relative/path in AGENTS.md itself	already works today
Copilot VS Code	.github/copilot-instructions.md / *.instructions.md (docs: file refs NOT expanded in .instructions.md)	only by inlining there too
Codex	effectively none for this case: repo-level .codex/config.toml exists (trusted projects), but project_doc_fallback_filenames is consulted only when AGENTS.md is ABSENT at that directory level — it cannot add files alongside an existing AGENTS.md; and discovery is a root→cwd directory walk, so codev/resources/*.md is never on the path. Content must physically be in AGENTS.md (or AGENTS.override.md)	no
Antigravity (agy)	GEMINI.md override file; no documented import/include mechanism	no

Two conclusions:

1. The per-tool route still doesn't reach codex or agy — the two consult lanes, the empirically confirmed losers. For them the content has to be in AGENTS.md itself, which forces inlining regardless of what else is done.
2. It's an N×format maintenance matrix: each tool has its own config file, syntax, and clobber semantics, and adopters may already own those files (codev would be merging into opencode.json / .cursor/rules/ it didn't create). One regenerated Markdown block has zero per-tool knowledge and covers every present and future consumer.

A later polish issue could add native wiring for OpenCode/Cursor to slim AGENTS.md, but it would be additive, not a substitute.

Suggested fix

Render the block per consumer at generation time:

• CLAUDE.md: keep the @import lines (zero-drift, expanded at launch).
• AGENTS.md: inline the hot-file contents into the generated block, as pre-Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119. Inlined plain Markdown is the only form the standard guarantees every consumer reads, and it degrades nothing for tools that do support imports. The block is regenerated on every codev update, so drift is bounded by update cadence, and Surface codev doctor results (incl. scaffold drift) in the VS Code extension #1207 (doctor drift surfacing) further shrinks that window.

Side effects of inlining on the edit workflow (in scope, not afterthoughts)

Inlining moves a sync burden onto whoever edits the hot files (architects in MAINTAIN cycles, builders routing lessons at review time). Consequences the implementation must address:

1. A regeneration step enters the hot-file edit loop. Only codev init/update calls syncHotContextBlock() today, and there is no lightweight command that refreshes just the block (codev update does far more). Ship a small regeneration affordance (e.g. a codev subcommand that re-syncs the root docs' managed block) and wire it into the places that edit hot files: the update-arch-docs skill, the MAINTAIN protocol, and review-phase prompts.
2. Builder PRs gain a second file to stage. A lesson-routing PR must touch the hot file AND the regenerated AGENTS.md. With explicit staging (no git add -A), forgetting the second file is easy; the symptom is a surprise AGENTS.md working-tree diff at the next codev update (exactly the confusion that produced this report).
3. Duplicated merge-conflict surface. Two concurrent builders adding lessons currently conflict only inside the small hot file. Inlined, they also both rewrite the same generated block, and conflicts in generated content are the worst kind (correct resolution is "regenerate", which git cannot express).
4. Freshness needs enforcement. In this repo: extend governance-sweep.test.ts to assert AGENTS.md's block equals renderHotContextBlock()'s current output, so a PR that edits hot files without regenerating fails CI. In adopter repos: Surface codev doctor results (incl. scaffold drift) in the VS Code extension #1207's doctor drift check (block-vs-hot-files is a local byte-compare, no version info needed).

Unaffected either way: porch phase prompts (runtime injection via readHotTierFiles()), and CLAUDE.md under option 1 (session-launch expansion spares the majority harness all four costs).

Impact on non-Claude users under option 1

Non-Claude consumers become strictly better than today but freshness-second-class unless regeneration is enforced:

• Baseline: post-Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119 they get NO hot tier at all. Bounded staleness is a strict improvement.
• The gap: Claude sessions expand @import at launch (always current); non-Claude sessions read the inlined block (current as of last regeneration). If regeneration lags, agents on the same repo diverge: the Claude lane knows a newly added invariant, the codex/agy lanes don't. In a 3-way CMAP this means reviewers disagreeing because they hold different governance snapshots, not different perspectives; in mixed human teams, a Cursor user's agent can violate an invariant a Claude user's agent already respects — the exact failure class the hot tier exists to prevent.
• With the enforcement above (regeneration wired into the edit loop + CI freshness check), the staleness window collapses from release cadence to the life of the editing PR — effectively zero for everyone consuming main. The workflow burden in the previous section is the price of making non-Claude consumers first-class rather than absent.

Design tension to resolve (the actual decision)

The hot-tier invariant (in arch-critical.md, echoed in managed-block.ts's ROOT_DOCS comment) says CLAUDE.md and AGENTS.md MUST stay byte-identical. Per-consumer rendering breaks byte-identity. Options:

1. Amend the invariant to: identical outside the managed block; the generated hot-context block is rendered per-ecosystem (import for Claude, inline for the standard). Recommended: the invariant's intent is equal capability across tool ecosystems, and the current byte-identity literalism is what produced unequal capability. Per-consumer rendering from a single source still delivers semantically identical content to both files.
2. Inline in both files (full revert of Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119): keeps byte-identity literal and uniform, but reintroduces the drift footgun for CLAUDE.md that Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119 existed to remove — and the drift is not hypothetical: hot files are user-evolved content edited routinely (MAINTAIN cycles, review-time lesson routing), while the inlined block refreshes only at codev update (package-upgrade cadence). Inline-both makes staleness uniform across all consumers instead of keeping the majority harness (Claude Code, which runs porch builders and MAINTAIN itself) always fresh via session-launch expansion.

Whichever lands, the equality test in governance-sweep.test.ts and any byte-compare between the two docs needs updating to compare content outside the managed block (option 1) or is unchanged (option 2).

Affected surfaces

• packages/codev/src/lib/managed-block.ts (render + sync)
• codev init / adopt / update call sites in scaffold.ts and commands
• Byte-identity checks/tests, and the invariant wording in arch-critical.md (both trees: codev/ and codev-skeleton/)

Evidence trail

• Comment 1: spec + Copilot CLI + Cursor documentation check (corrects the original blanket "non-Claude tools render as literal text" claim)
• Comment 2: agy empirical test method + OpenCode documentation check
• Comment 3: codex empirical test + final matrix

Sources: agents.md spec · agentsmd/agents.md#11 · GitHub Copilot CLI custom-instructions docs · learn.chatgpt.com Codex AGENTS.md guide + config reference · opencode.ai/docs/rules · anomalyco/opencode#2225

[amrmelsayed]

Evidence check on the "non-Claude tools render @import as literal text" claim (verified 2026-07-19)

The blanket claim in the report overstates. What the evidence actually shows:

1. The AGENTS.md standard defines no import mechanism (authoritative). agents.md states: "AGENTS.md is just standard Markdown. Use any headings you like; the agent simply parses the text you provide." No import/transclusion syntax exists in the spec. There is an open feature request for exactly this (agentsmd/agents.md#11, citing Claude Code imports, Cursor file references, Zed and Amp includes as prior art), unassigned and unimplemented. So any @-expansion in AGENTS.md is a per-tool extension, not something the standard guarantees.

2. Copilot CLI actually DOES expand @-references in AGENTS.md. GitHub's docs: "In .github/copilot-instructions.md, AGENTS.md, or CLAUDE.md, use @ followed by a relative path to include another file" (with limits: not expanded in GEMINI.md or *.instructions.md; referenced files must stay within the repository). Our generated lines are relative repo paths, so Copilot CLI users are NOT losing the hot tier. The docs cover Copilot CLI specifically; no equivalent documented expansion for the Copilot coding agent or VS Code Copilot custom instructions.

3. Cursor documents @file references only for .cursor/rules/*.mdc rule files, not AGENTS.md. Cursor reads AGENTS.md as instructions; no documented @-expansion inside it.

Net: the regression is real but narrower than reported. Consumers with documented @-expansion in AGENTS.md: Claude Code, Copilot CLI. Consumers without documented expansion (literal text, hot tier lost): Cursor's AGENTS.md path, Copilot coding agent / VS Code (undocumented at minimum), and anything that follows the bare standard. The suggested fix (inline into AGENTS.md's generated block) remains the right direction because inlined plain Markdown is the only form the standard itself guarantees every consumer reads: it degrades nothing for the tools that do support imports.

Sources:

• https://agents.md/ (spec: plain Markdown, no imports)
• Import/reference support agentsmd/agents.md#11 (open import-support request)
• https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions (Copilot CLI @-reference support and limits)
• https://forum.cursor.com/t/support-agents-md/133414 and Cursor rules docs (@file scoped to .mdc rules)

[amrmelsayed]

Addendum: OpenCode + Antigravity CLI checked (empirical where possible, 2026-07-19)

Antigravity CLI (agy) — empirically tested on this machine, does NOT expand @imports in AGENTS.md. Method: scratch git repo whose AGENTS.md contained an inline fact (codeword LION-7) plus the exact import line our generator emits (@codev/resources/arch-critical.md, pointing at a file containing a second codeword ZEBRA-42). agy --new-project -p "list every codeword in your context" answered LION-7 only: AGENTS.md itself is loaded as plain text, the @import line is not expanded, the imported file's content never reached context. Side finding for the consult lane: without --new-project (or a registered project), agy -p from a directory loads no AGENTS.md at all (control with an inline-only fact returned UNKNOWN).

OpenCode — not installed here; documented as NOT expanding @ references in AGENTS.md. There is an open feature request asking for exactly this (anomalyco/opencode#2225, "Automatically load @ referenced files in AGENTS.md into context"). OpenCode's own docs recommend the opencode.json instructions array (glob patterns of extra instruction files) as the mechanism for pulling additional files into context; some community templates work around it by instructing the model to lazily Read @-referenced paths, which is best-effort, not always-on.

Updated consumer matrix for AGENTS.md @-lines:

Consumer	@import expanded?	Evidence
Claude Code	yes	product feature (CLAUDE.md/AGENTS.md imports)
Copilot CLI	yes (relative in-repo paths)	GitHub docs
Antigravity CLI (agy)	no	empirical test, this machine
OpenCode	no	open feature request #2225 + docs steering to opencode.json instructions
Cursor (AGENTS.md path)	no documented support	@file refs documented only for .cursor/rules/*.mdc
Copilot coding agent / VS Code	undocumented	no expansion claim in docs
agents.md standard baseline	no	spec: "just standard Markdown"; import support is open request agentsmd/agents.md#11

This strengthens the case for the per-consumer render fix: our own consult stack's gemini lane (agy) is among the consumers that lose the hot tier under the current @import-only AGENTS.md block.

Sources: https://agents.md/ · agentsmd/agents.md#11 · https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions · https://opencode.ai/docs/rules/ · anomalyco/opencode#2225

[amrmelsayed]

Addendum 2: Codex CLI checked (empirical, 2026-07-19)

Codex CLI (codex-cli 0.142.5) — empirically does NOT expand @-references in AGENTS.md. Same fixture as the agy test (AGENTS.md with inline codeword LION-7 + the generator's exact @codev/resources/arch-critical.md line pointing at a file with codeword ZEBRA-42). codex exec in that repo answered LION-7 only, with zero tool calls in the transcript (read-only sandbox, approval never): AGENTS.md content reaches context via Codex's automatic discovery, the @ line stays literal text.

Consistent with OpenAI's official AGENTS.md guide, which documents only: the discovery precedence chain (global ~/.codex/AGENTS.md, then project files root-down, concatenated), AGENTS.override.md, project_doc_fallback_filenames, and project_doc_max_bytes. No import/include mechanism inside the file is documented.

Final consumer matrix:

Consumer	@import expanded?	Evidence
Claude Code	yes	product feature
Copilot CLI	yes (relative in-repo paths)	GitHub docs
Codex CLI	no	empirical (0.142.5) + official docs
Antigravity CLI (agy)	no	empirical
OpenCode	no	open feature request anomalyco/opencode#2225
Cursor (AGENTS.md path)	no documented support	@file scoped to .cursor/rules/*.mdc
agents.md standard	no	spec + open request agentsmd/agents.md#11

Both of consult's non-Claude lanes (codex, agy) are now empirically confirmed to lose the hot tier under the @import-only AGENTS.md block. That makes this self-inflicted for our own consultation stack, not just a third-party-adopter concern: every consult review run in an updated project reasons without the always-on facts and lessons.

Source: https://learn.chatgpt.com/docs/agent-configuration/agents-md (Codex custom instructions guide)

[amrmelsayed]

@waleedkadous flagging for your review before this spawns, since #1119 (and the Spec 987 managed block before it) is your design. Summary of what's proposed:

• Your Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119 rationale (DRY + the silent-drift footgun with no test/doctor guard) holds, and the zero-drift win is kept for CLAUDE.md: the @import lines stay there.
• What Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119 didn't account for: @import is Claude Code-specific. Verified this week (matrix in the body): codex and agy empirically do NOT expand it in AGENTS.md, OpenCode and Cursor don't either, and the agents.md standard has no import mechanism. Net: every non-Claude consumer of AGENTS.md, including consult's own codex and gemini lanes, currently gets no hot tier at all.
• Proposed: per-consumer render of the managed block — @import in CLAUDE.md, inline in AGENTS.md — plus the guards whose absence Replace hot-context managed block in CLAUDE.md/AGENTS.md with @import lines (single source of truth, kills drift footgun) #1119 called out (regen affordance wired into the hot-file edit loop, governance-sweep freshness check, Surface codev doctor results (incl. scaffold drift) in the VS Code extension #1207 doctor drift check), and amending the byte-identity invariant to identical-outside-the-managed-block.

Full analysis (per-tool native mechanisms, workflow side effects, non-Claude impact) is in the body and comment trail. Anything you'd push back on, especially on the invariant amendment or the regen-command shape?

[waleedkadous]

I was kind of hoping the llms would be smart enough to read the files anyway. Is there a middle path where instead of @import we actually tell it: it is imperative that in addition you read file x. Repetition is a bad smell, that's why I'm trying to avoid static includes. If that doesn't work go ahead with this plan.

…

On Sun, Jul 19, 2026, 7:06 AM Amr Elsayed ***@***.***> wrote: *amrmelsayed* left a comment (cluesmith/codev#1208) <#1208 (comment)> @waleedkadous <https://github.com/waleedkadous> flagging for your review before this spawns, since #1119 <#1119> (and the Spec 987 managed block before it) is your design. Summary of what's proposed: - Your #1119 <#1119> rationale (DRY + the silent-drift footgun with no test/doctor guard) holds, and the zero-drift win is kept for CLAUDE.md: the @import <https://github.com/import> lines stay there. - What #1119 <#1119> didn't account for: @import <https://github.com/import> is Claude Code-specific. Verified this week (matrix in the body): codex and agy empirically do NOT expand it in AGENTS.md, OpenCode and Cursor don't either, and the agents.md standard has no import mechanism. Net: every non-Claude consumer of AGENTS.md, including consult's own codex and gemini lanes, currently gets no hot tier at all. - Proposed: per-consumer render of the managed block — @import <https://github.com/import> in CLAUDE.md, inline in AGENTS.md — plus the guards whose absence #1119 <#1119> called out (regen affordance wired into the hot-file edit loop, governance-sweep freshness check, #1207 <#1207> doctor drift check), and amending the byte-identity invariant to identical-outside-the-managed-block. Full analysis (per-tool native mechanisms, workflow side effects, non-Claude impact) is in the body and comment trail. Anything you'd push back on, especially on the invariant amendment or the regen-command shape? — Reply to this email directly, view it on GitHub <#1208?email_source=notifications&email_token=AAUXGUFHRKHBPMKHXVJLVOD5FRCMRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRGQYTONZYGA2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLDGN5XXIZLSL5RWY2LDNM#issuecomment-5014177804>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAUXGUF4X6P7MBVA6BZ7DK35FRCMRAVCNFSNUABGKJSXA33TNF2G64TZHMYTANRQGI2TAOJRGU5US43TOVSTWNBZGIYTCNBXGIYDNILWAI> . Triage notifications, keep track of coding agent tasks and review pull requests on the go with GitHub Mobile for iOS <https://github.com/notifications/mobile/ios/AAUXGUE7S4WLNBEFPJ32XWD5FRCMRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRGQYTONZYGA2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJKTGN5XXIZLSL5UW64Y> and Android <https://github.com/notifications/mobile/android/AAUXGUEIXZM7EHSDMIGDJAD5FRCMRA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTKMBRGQYTONZYGA2KM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJLTGN5XXIZLSL5QW4ZDSN5UWI>. Download it today! You are receiving this because you were mentioned.Message ID: ***@***.***>