[clubanderson]

Closes #12129
Refs #12134

cc @mrbobbytables

What

primeAgentsMd injected the whole repo AGENTS.md plus a ~1.1 KB precedence paragraph with no cap. This follows the skills cap (maxSkillsInjectionBytes, dropped whole) but at the granularity a repo-owned contract needs — whole sections, never a clipped rule, and a warning the agent reads before the rules.

Cap — project.agents_md_max_bytes

• Named constant agentsmd.DefaultMaxInjectionBytes = 8192 (same as the skills cap), floor 2048; yaml override project.agents_md_max_bytes.
• New AgentsConfig.Render(requestedSkills, maxBytes) (string, InjectionOmitted). The body is split at #/## headings (text before the first heading is the "(preamble)"; deeper headings and fenced code stay inside their section). Each resolved skill is its own droppable unit. Sections are visited in document order and kept only if they fit whole; one that doesn't is dropped whole and later, smaller sections are still considered, so one long section doesn't take the rest of the file down.
• If nothing fits, the block is header + precedence + a whole-file warning — never a fragment.
• InjectionText is now Render at the default cap (same signature).

Visible warning + log

• One line, right after the precedence statement and before the surviving rules:
  > ⚠️ AGENTS.md exceeded 8192 bytes; 2 section(s) omitted (9114 bytes): "Style guide", "skill: release-notes" — read AGENTS.md in the repository root for the full instructions before you start.
  (names clipped to 40 bytes, at most 8 listed then "and N more", so the line is bounded and the render never exceeds the cap).
• Scheduler logs agentsmd: AGENTS.md exceeded the injection cap; sections dropped whole with cap_bytes, omitted_sections, omitted_bytes, whole_file.

Precedence paragraph → one sentence

~1.1 KB → ~0.5 KB. Every clause pinned by the existing #7159/#7177 tests (TestInjectionTextPrecedenceFraming, TestInjectionTextPrecedenceLeadsRepositoryRules) is kept verbatim; they pass unchanged. A new test keeps it under 600 bytes and single-sentence.

Tests

pkg/agentsmd/injection_cap_test.go: under cap (no warning, InjectionText == Render), cap hit (bounded, oversized section dropped whole, later sections kept in order, exact warning text, warning before rules, precedence still leads), whole-file drop, skills as units, skills header only when a skill kept, fenced # not a boundary, 8-names-then-count, default/floor, precedence one-sentence. pkg/scheduler/kick_priming_agentsmd_cap_test.go: end-to-end through primeAgentsMd with project.agents_md_max_bytes — kick text bounded, warning rendered, log line asserted; and the no-warning common case.

Docs

docs/agents-md.md (new "Size cap: whole sections, visible warning" section; precedence-statement section updated), docs/operator-reference.md (Notable fields row), changelog fragment.

[kubestellar-prow]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
Once this PR has been reviewed and has the lgtm label, please assign nicholasjackson for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[github-actions]

Open PR overlap check

Base branch: v5

Conflicts are checked with every PR merged onto the current tip of v5, so a PR that only needs a rebase is not reported as conflicting with its siblings.

PR	Title	Relation	Files
#12157	🌱 tokens: measure kick size per kick; keep kick_limits defaults	same files	src/docs/operator-reference.md
#12158	✨ review: add review.shadow to record would_have_held for the review gate	same files	src/pkg/config/config.go
#12025	✨ keep unstick steps running in conserve API budget mode	same files	src/docs/operator-reference.md
#12139	✨ dashboard settings: expose intent pattern lists and sentinel list keys	same files	src/pkg/dashboard/settings_parity_allowlist.txt

[hivecommons-hive]

hive/awaiting-ci: the only red check here, relative links and anchors resolve, is red on the v5 default branch itself (broken admin-mcp.md links from #12143). Tracked as shared incident #12162; fix in #12161. No change needed on this branch — deferring until the baseline is green, then the sweep merges on re-run.

---

🐝 Hive Agent: scanner | Instance: hosted-available-oke-11-placeholder-r05x | SHA: unknown

— hive: agent=scanner backend=copilot model=claude-fable-5.1

[hivecommons-hive]

merged by Hive trusted-author auto-merge: author @clubanderson holds role owner and GitHub permission admin on repo; CI green at a5d9907.

[github-actions]

Thank you for your contribution! Your PR has been merged.

We'd love to hear how your experience was: share feedback