Repository navigation
feat(structure): cap CLAUDE.md line and block length - #331
Merged
Merged
Conversation
added 4 commits
November 19, 2026 22:57
An agent reads a CLAUDE.md by scanning it, and a 600-character bullet or a paragraph of several screens hides the rule it carries. Nothing held the files to a readable shape, so they grew that way. scripts/structure now fails a CLAUDE.md line over 200 bytes or a block over 600 bytes, exempting fenced code, table rows and unbreakable tokens, and reports a section run over 8000 bytes as an advisory that never fails. The caps are bytes under LC_ALL=C so every platform counts the same way. A bold or italic quota was considered and rejected as a gate; ADR 0012 records why. The existing CLAUDE.md files are reflowed to pass. The template contract test now rejoins a wrapped bullet's continuation lines, and the retrofit fixture wraps the Child Index sentence it writes, since the mirrored audit reads both. Generated-By: claude-opus-5-5
Review of #331 found the CLAUDE.md caps misreading Markdown. A `#331` line counted as a heading and skipped the line cap, a `~~~` fence was not recognized, a ``` inside a ~~~ block closed it, and a real heading skipped the line cap. Fences now open on ``` or ~~~ and close only on the same character at the opening length or longer; headings need 1-6 hashes then a space, and are capped like any line. An unbreakable line is exempt from the block cap too, matching the line cap. The 8000-byte section advisory was invisible under scripts/check, which prints only the Result table; the claudemd-blocks row now counts it. The structure doc stated the audit reads one kind of file; it reads two. contract_line() stopped absorbing a nested sub-bullet into its parent. Generated-By: claude-opus-5-5
Regression cases for the previous commit: a ``` inside a ~~~ fence keeps the fence open, a heading over the line cap fails, and a prose line opening with #331 is capped rather than read as a heading. Generated-By: claude-opus-5-5
The fence regex allowed at most three spaces, so a fence inside a nested list item, indented further, was missed and its code lines were capped as prose. Any leading whitespace now opens or closes a fence, keeping the character and length matching. Generated-By: claude-opus-5-5
Owner
Author
|
Code review: standard scan, clean. Axes: Standards+Spec, Correctness/Logic Reviewed-Head: 4bd8b9a |
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.
Intent
Requested in session: give every tracked
CLAUDE.mda mechanical readability check.CLAUDE.mdfiles had grown bullets of several hundred characters and paragraphs that span screens. An agent scanning them misses the rule buried inside.scripts/structurenow fails a physical line over 200 bytes or a block over 600 bytes, and reports a section run over 8000 bytes as an advisory that never fails. The check covers this repository and every generated one, since the payload'sscripts/structureis mirrored. Every existingCLAUDE.mdis reflowed to pass.Read first
scripts/structure:612:claudemd_program, the awk that measures lines, blocks and section runs, and its exemptions. Fences open on ``` or~~~and close only on their own character at the opening length; headings need 1–6 `#` then a space and are capped like any linedocs/adrs/0012-cap-claude-md-line-and-block-length.md: why bytes, why these caps, why no markup quotaapps/repo-builder/src/scripts/tests/test_template_contract.py:52:contract_linenow rejoins a wrapped bulletCLAUDE.mdreflows (line wrapping only, no wording change) andapps/github-repository-template/src/base-repo/scripts/, which is a byte copy of rootscripts/Decisions
LC_ALL=Cover characters, because awk's character counting varies by locale and platform, and a cap that counts differently on two machines passes on one and fails on the other.Out of scope
documentation.mdrule inpossiblyneal/devex, not in this repository.Verified
./scripts/check→exited 0: 0 FAIL, 0 unavailable, 5 not-applicable, 28 pass, includingclaudemd-lines pass,claudemd-blocks pass(its row now counts the 2 advisory sections) andpayload-parity pass;--fastre-run green on the headbash scripts/tests/structure-test→ 92/92. Its new cases cover each cap, each exemption,~~~fences, a fence nested under a list item, a capped heading, a#331prose line, and the advisory.uv run pytest.test_root_folders_match_the_auditand the retrofitverify_fixturetest failed after the reflow and pass after thecontract_lineandsetup_fixture.pyfixes.Not verified
CLAUDE.mdfiles may break the caps and fail its gate on the next/repo-builderupdate until they are reflowed.Merge danger
Door: two-way. A revert restores the audit and the reflowed text.
Blast radius:
scripts/structureand its payload copy, soscripts/checkand the pre-commitstructurehook here and in every repository generated or updated from this payload. Also everyCLAUDE.mdin this repository,test_template_contract.py, and the retrofit eval fixture.