Skip to content

fix(ENG-RECORD-CONFLICT-SURFACES): retire MAX_README_CHARS, the fourth whole-file budget (#498) - #1245

Merged
localai-bot merged 2 commits into
mainfrom
row/ENG-RECORD-CONFLICT-SURFACES-498
Aug 18, 2026
Merged

fix(ENG-RECORD-CONFLICT-SURFACES): retire MAX_README_CHARS, the fourth whole-file budget (#498)#1245
localai-bot merged 2 commits into
mainfrom
row/ENG-RECORD-CONFLICT-SURFACES-498

Conversation

@localai-bot

Copy link
Copy Markdown
Collaborator

README.md measured 29,993 characters against MAX_README_CHARS = 30000
(scripts/check-readme-structure.py:47). Seven free. The next README edit reds
CI, 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

Budget Retired by
per-class line limits 2026-08-10, recorded in AGENTS.md
MAX_CHARS in check-now-current.py + STATUS_RATCHET chars 87308dea under #364
PageRules.max_chars in check-public-doc-tables.py #460 (PR #494)
MAX_README_CHARS this PR, under #498

87308dea is the governing precedent and it is explicit about what survives: it
kept "every local per-cell and per-paragraph cap" while removing the whole-file
budget. This change mirrors it exactly.

What changed

MAX_README_CHARS and the branch that reads it are removed. The obligation
relocates rather than disappearing:

  • MAX_CELL_CHARS = 220 unchanged, one table cell is one author's entry
  • MAX_PARAGRAPH_CHARS = 900 unchanged, one prose paragraph is the largest unit
    one author writes alone
  • required sections, ordering, em-dash, STATUS_LINK and CONTRIBUTOR_LINK
    unchanged, because they count defects rather than length and so cannot collide
    between concurrent pull requests

README.md is byte-identical at 29,993 characters. This PR does not add or
remove 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 cap
is 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:

test_oversized_readme_passes_when_every_entry_is_small
  AssertionError: ['README is 69427 chars, over the 30000-char landing-page budget...'] != []
test_checker_declares_no_whole_file_budget
Ran 23 tests -- FAILED (failures=2)

The suite moves 21 to 23 tests, so the new cases demonstrably run. The retired
test_oversized_readme_fails is deleted because it pins the behavior being
removed; the two new cases plus the entry-cap guard replace its coverage.

Green after: Ran 23 tests ... OK, and check-readme-structure.py still passes
on the shipped, unchanged README.

Mutation, each applied to the committed tree and restored byte-for-byte
(sha256 asserted after every restore):

Mutation Result
M1 reintroduce MAX_README_CHARS and its branch 2 tests RED
M2 MAX_PARAGRAPH_CHARS to 10,000,000 2 tests RED
M3 MAX_CELL_CHARS to 10,000,000 2 tests RED

M2 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_budget asserts the constant is absent from
the 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.md cannot be corrected, and names two independent
blockers. 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.py refusing any README change that does not
also 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]

mudler added 2 commits August 18, 2026 14:46
…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
localai-bot merged commit dabf337 into main Aug 18, 2026
0 of 15 checks passed
@localai-bot
localai-bot deleted the row/ENG-RECORD-CONFLICT-SURFACES-498 branch August 18, 2026 16:15
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]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

README.md has 35 characters of headroom: MAX_README_CHARS is the same whole-file lock retired three times already

2 participants