Skip to content

feat(structure): cap CLAUDE.md line and block length - #331

Merged
possiblyneal merged 4 commits into
mainfrom
possiblyneal/claudemd-length-check-toc
Nov 20, 2026
Merged

possiblyneal merged 4 commits into
mainfrom
possiblyneal/claudemd-length-check-toc

Conversation

@possiblyneal

@possiblyneal possiblyneal commented Nov 20, 2026 •

Copy link
Copy Markdown
Owner

Intent

Requested in session: give every tracked CLAUDE.md a mechanical readability check.

CLAUDE.md files had grown bullets of several hundred characters and paragraphs that span screens. An agent scanning them misses the rule buried inside. scripts/structure now 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's scripts/structure is mirrored. Every existing CLAUDE.md is 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 line
  • docs/adrs/0012-cap-claude-md-line-and-block-length.md: why bytes, why these caps, why no markup quota
  • apps/repo-builder/src/scripts/tests/test_template_contract.py:52: contract_line now rejoins a wrapped bullet
  • Mechanical, safe to skim: the CLAUDE.md reflows (line wrapping only, no wording change) and apps/github-repository-template/src/base-repo/scripts/, which is a byte copy of root scripts/

Decisions

  • Bytes under LC_ALL=C over 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.
  • Exempting fenced code, table rows and single unbreakable tokens, because wrapping them breaks rendering or the literal itself.
  • The 8000-byte section run is advisory rather than a FAIL, because splitting a long section is a judgment about content that no script can settle.
  • No bold or italic quota as a gate (ADR 0012), because a ratio rewards markup added to hit it.

Out of scope

  • The prose guidance on which Markdown features to use. It lives in the operator's user-level documentation.md rule in possiblyneal/devex, not in this repository.

Verified

  • ./scripts/check → exited 0: 0 FAIL, 0 unavailable, 5 not-applicable, 28 pass, including claudemd-lines pass, claudemd-blocks pass (its row now counts the 2 advisory sections) and payload-parity pass; --fast re-run green on the head
  • bash 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 #331 prose line, and the advisory.
  • The awk program run under mawk 1.3.4, gawk and busybox awk on one fixture gives identical findings.
  • uv run pytest. test_root_folders_match_the_audit and the retrofit verify_fixture test failed after the reflow and pass after the contract_line and setup_fixture.py fixes.

Not verified

  • No generated repository has been updated to this payload yet. An existing repository's own CLAUDE.md files may break the caps and fail its gate on the next /repo-builder update until they are reflowed.
  • CI's freshly installed tool versions. This ran only locally.

Merge danger

Door: two-way. A revert restores the audit and the reflowed text.

Blast radius: scripts/structure and its payload copy, so scripts/check and the pre-commit structure hook here and in every repository generated or updated from this payload. Also every CLAUDE.md in this repository, test_template_contract.py, and the retrofit eval fixture.

neal 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
@possiblyneal possiblyneal added the code-reviewed Multi-axis code review passed label Nov 20, 2026
@possiblyneal

Copy link
Copy Markdown
Owner Author

Code review: standard scan, clean.

Axes: Standards+Spec, Correctness/Logic

Reviewed-Head: 4bd8b9a

@possiblyneal
possiblyneal merged commit 26b76d2 into main Nov 20, 2026
7 checks passed
@possiblyneal
possiblyneal deleted the possiblyneal/claudemd-length-check-toc branch November 20, 2026 04:08
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

code-reviewed Multi-axis code review passed

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant