fix(ENG-RECORD-CONFLICT-SURFACES): retire MAX_README_CHARS, the fourth whole-file budget (#498) - #1245
Merged
Merged
Conversation
…droom, and the cap is the shape AGENTS.md forbids (#498) `MAX_README_CHARS = 30000` is a budget on a whole shared file. Measured on main at 52ce0c8, README.md is 29,993 chars: seven free. The next edit reds CI, and two concurrent edits that each fit alone merge into a file that fails. This is the fourth instance of one shape. Per-class line budgets were retired 2026-08-10, MAX_CHARS and STATUS_RATCHET by 87308de under #364, and PageRules max_chars under #460. 87308de is the governing precedent and kept "every local per-cell and per-paragraph cap" while removing the whole-file budget; this spec mirrors it and records why a per-section cap is rejected rather than adopted. Spec only. No checker semantic and no README content changes in this commit. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: claude:claude-opus-5 [claude-code]
…h whole-file budget (#498) README.md measured 29,993 chars against `MAX_README_CHARS = 30000`: seven free. A budget on a whole shared file makes every addition evict someone else's content, and lets two individually-valid edits merge into a file that fails CI. AGENTS.md Records forbids that shape in its own words, "Limit an entry, not a shared file", and this is the fourth instance to be retired after the per-class line limits, `check-now-current.py`'s MAX_CHARS and STATUS_RATCHET (#364), and PageRules `max_chars` (#460). The obligation relocates rather than disappearing. `MAX_CELL_CHARS = 220` and `MAX_PARAGRAPH_CHARS = 900` are unchanged and are the real entry caps: a paragraph is the largest unit one author writes alone. A per-section cap was rejected in the spec, because a section such as News is written by many pull requests and capping it recreates the same lock at smaller granularity. README.md content is byte-identical at 29,993, so this change cannot be confused with buying headroom. Red-before: `test_oversized_readme_passes_when_every_entry_is_small` and `test_checker_declares_no_whole_file_budget` fail on the unmodified checker for their intended reasons; the suite moves 21 to 23 tests. Green after, and the shipped README still passes. Mutation M1 reintroduces the constant and its branch and turns 2 tests red; M2 raises MAX_PARAGRAPH_CHARS to 10,000,000 and turns the entry-cap tests red, so removing the file budget demonstrably did not disable the entry budgets. Also unblocks half of #1098: its blocker 1 was this cap. Its blocker 2, the doc-checkpoint landing-source rule, is untouched and still owns that issue. Fixes #498. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: claude:claude-opus-5 [claude-code]
localai-bot
pushed a commit
that referenced
this pull request
Aug 18, 2026
…e fourth time `origin/main` advanced twice more (#1245, #1186). Only `.agents/issue-index.md` overlaps, and it overlaps every time because it is the one file in this change that every other branch also appends to. That is why GitHub keeps reporting this pull request CONFLICTING: it does not run the `merge=union` driver `.gitattributes:7` sets, so the conflict is real on the forge and absent locally. Resolved the only way that keeps the file an append-only log: the auto-merge was DISCARDED, main's file taken whole, and only the rows whose KEY main lacks re-appended -- #1074 and #1080. Asserted: main's blob is a strict BYTE prefix of the result (346713 of 349709 bytes), 370 rows, zero duplicate keys. Nothing else overlapped. The delta against `ae581da3e` is the same five files it was against `10fe7f475`. FOLLOWING_AGENTS_PROTOCOL Following-Agents-Protocol: true AI-Assisted: true Assisted-by: AGENT:claude-opus-5 [claude-code]
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
README.mdmeasured 29,993 characters againstMAX_README_CHARS = 30000(
scripts/check-readme-structure.py:47). Seven free. The next README edit redsCI, and two concurrent edits that each fit on their own merge into a file that
fails.
AGENTS.md Records forbids that shape in its own words, "Limit an entry, not a
shared file", and gives the reason: a shared-file budget forces each addition to
remove another entry, and merging two such edits cleanly is worse than
conflicting because it applies both removals.
This is the fourth budget of this shape, not a new argument
MAX_CHARSincheck-now-current.py+STATUS_RATCHETchars87308deaunder #364PageRules.max_charsincheck-public-doc-tables.pyMAX_README_CHARS87308deais the governing precedent and it is explicit about what survives: itkept "every local per-cell and per-paragraph cap" while removing the whole-file
budget. This change mirrors it exactly.
What changed
MAX_README_CHARSand the branch that reads it are removed. The obligationrelocates rather than disappearing:
MAX_CELL_CHARS = 220unchanged, one table cell is one author's entryMAX_PARAGRAPH_CHARS = 900unchanged, one prose paragraph is the largest unitone author writes alone
STATUS_LINKandCONTRIBUTOR_LINKunchanged, because they count defects rather than length and so cannot collide
between concurrent pull requests
README.mdis byte-identical at 29,993 characters. This PR does not add orremove a single character of the landing page, so it cannot be confused with
buying headroom.
Rejected: a per-section budget
Issue #498 offers "a per-section or per-paragraph budget". A per-
##-section capis rejected, and the spec records why: a section such as News is written by many
pull requests, so capping it recreates the same lock at smaller granularity. The
per-paragraph cap is the real entry cap and it already existed.
Evidence
Red-before, on the unmodified checker:
The suite moves 21 to 23 tests, so the new cases demonstrably run. The retired
test_oversized_readme_failsis deleted because it pins the behavior beingremoved; the two new cases plus the entry-cap guard replace its coverage.
Green after:
Ran 23 tests ... OK, andcheck-readme-structure.pystill passeson the shipped, unchanged README.
Mutation, each applied to the committed tree and restored byte-for-byte
(
sha256asserted after every restore):MAX_README_CHARSand its branchMAX_PARAGRAPH_CHARSto 10,000,000MAX_CELL_CHARSto 10,000,000M2 and M3 are the ones that matter for this change: they prove removing the file
budget did not quietly disable the entry budgets, which is the failure mode a
"the tests still pass" report would otherwise hide.
test_checker_declares_no_whole_file_budgetasserts the constant is absent fromthe module rather than checking its value, so the gate fails if it returns under
any threshold.
Full
scripts/agent-preflight.sh: all gates green.Also unblocks half of #1098
#1098 records that
README.mdcannot be corrected, and names two independentblockers. Blocker 1 was this cap: the LTX-2.5 matrix row could only land by
deleting another architecture's row. That blocker is now gone, which also clears
the way for PR #1180's 37-to-40 architecture-count correction.
Blocker 2,
check-doc-checkpoint.pyrefusing any README change that does notalso touch a landing source, is untouched and still owns #1098. No issue-index
row was appended here, because #1098 already has one and AGENTS.md forbids
editing an existing row.
Fixes #498.
FOLLOWING_AGENTS_PROTOCOL
Following-Agents-Protocol: true
AI-Assisted: true
Assisted-by: claude:claude-opus-5 [claude-code]