Bring AGENTS.md under the 32 KiB instruction limit so every agent sees every catalogue rule #626

🤖 Generated by the Agentic Engineer (interactive Claude Code session)

Evidence

• AGENTS.md is 70,748 bytes and 751 lines, measured on main at 945434b on 2026-10-17. Codex reads an instruction file only up to 32 KiB; the monorepo enforces that limit on its own AGENTS.md with .claude/scripts/agent-instructions-layout-contract.test.sh. Here the cut falls at line 403, inside #### Test jobs. A Codex session in this repository therefore never sees the feature-flag-first convention, the authentication patterns, the validation commands, or the whole Maintaining the catalogue section: the blast-radius rule, every tested invariant and the task menu.
• The file has drifted from the repository. The ### Layout block names 8 workflows as belonging to this repository; .github/workflows/ holds 15 of them. The ### Validation Commands heading is followed by paragraphs about to-do forwarding, verified publication and recovery before the commands themselves appear.
• Many paragraphs narrate delivery history: issue numbers, "proven live" dates, superseded behaviour. The portfolio's documentation rule is to describe present behaviour and its rationale, not the journey.
• The root README.md is 103 KB. It is the catalogue's only consumer-facing reference.

Audience and problem

Every agent and contributor who changes the shared catalogue reads this file first. The blast radius is every consumer repository. Rules an agent cannot see, or rules it cannot find among history, are rules it will break. Among those already invisible to Codex: keep the vulnerability-scan allowlist guard, never move a write credential into a fixer lane, and prefer additive, backward-compatible changes.

Hypothesis

A core AGENTS.md under 32 KiB, holding the repository's rules, with each workflow's detailed invariants moved beside the code they govern, lets every agent see every rule. It also makes the next change cheaper to review. Candidate homes for that detail are a per-workflow section in docs/ or the workflow's README section.

Success signal

AGENTS.md is at most 32,768 bytes and a test keeps it there. No rule is lost: each invariant paragraph removed from AGENTS.md exists verbatim or as a stricter statement in the file it moved to, checked by a one-time inventory recorded in the pull request. Measured at merge.

Direction

1. Inventory every rule-bearing paragraph and classify it: a repository rule (stays), a workflow-specific invariant (moves beside its workflow, with a one-line pointer), or history (removed, because the issue or PR is its record).
2. Fix the drift found while classifying: the Layout list and the Validation Commands section.
3. Add a size guard to required CI in the same style as the monorepo's layout contract test.

Acceptance criteria

• AGENTS.md is at most 32 KiB, and required CI fails above that.
• The rule inventory is attached to the pull request and shows each paragraph's new home.
• ### Layout matches the files in .github/workflows/, and ### Validation Commands holds only commands.
• Moved content keeps its tests' references valid; lint-readme-parity and the README parity check stay green.

Priority rationale: every change to the catalogue depends on this file. More than half of its rules are invisible to one of the two engineering lanes today. Effort: medium, mostly careful editing, with very little CI cost. Prerequisites: none.

Rough size: M.