Skip to content

S0308-submodule-agent-doc-budgets: split CLAUDE.md and README.md under their byte budgets - #58

Open
NSchatz wants to merge 1 commit into
mainfrom
sdd/S0308-submodule-agent-doc-budgets-cli
Open

NSchatz wants to merge 1 commit into
mainfrom
sdd/S0308-submodule-agent-doc-budgets-cli

Conversation

@NSchatz

@NSchatz NSchatz commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

Spec: pipeline/active/S0308-submodule-agent-doc-budgets/children/cli.md in the umbrella.

What

CLAUDE.md is always read and measured 23154 bytes against a 16200 byte ceiling. README.md
measured 22693 against 22400. Over budget is a design signal, so the remedy is to split, never to
raise the number and never to delete a line.

Seven whole sections leave CLAUDE.md and two leave README.md, byte for byte, under their existing
headings, into documentation/ (the directory this repo's own agent doc already names for
agent-notes.md and its decision records):

  • documentation/repo-gates.md: the docs sidebar and the IA spine, the pre-commit PHI scanner, the
    em-dash brand gate, branch protection, and the attw gate.
  • documentation/packaging.md: the published package and the FHIR hole, and hard runtime deps.
  • documentation/convert-and-map-codes.md: cosyte convert and cosyte map-codes.

Each reduced document keeps the heading and carries a short pointer at the copy, at the point the
section left. No heading is renamed. Links inside moved text are re-based by exactly one directory,
so every one still resolves and none points outside this repo.

Result

path before after ceiling
CLAUDE.md 23154 11862 16200
README.md 22693 21186 22400

CLAUDE.md is 174 lines and still carries all five headings the estate baseline requires
(## Project, ## Status, ## Tech Stack, ## Engineering Guardrails, ## Standing disciplines).

Evidence

  • Heading reachability, per budgeted path, against the base commit: every heading in the old document
    is still reachable from the document that replaced it. Prints nothing for both paths.
  • Link resolution over both budgeted paths and all three added files: no absolute link, no link
    outside this repo, no missing target. Prints nothing.
  • pnpm test: 777 passed, 41 files. The suite is why redact stayed on the front page:
    test/docs-content.test.ts pins that matrix to README.md, and the first draft that moved it red.
  • pnpm check:agent-notes: OK, 26 qualified pointers from 4 files, all resolving.
  • pnpm check:no-emdash, pnpm check:no-internal-refs, pnpm format:check, pnpm phi-scan: OK.
  • npm pack --dry-run before and after lists the same four entries (CHANGELOG.md, LICENSE,
    README.md, package.json), both with dist/ unbuilt. package.json files is untouched and
    documentation/ is outside it, so the published tarball does not change.

…r their byte budgets

CLAUDE.md is always read and measured 23154 bytes against a 16200 ceiling; README.md
measured 22693 against 22400. Seven whole sections move out of CLAUDE.md and two out of
README.md, byte for byte and under their existing headings, into documentation/:

- documentation/repo-gates.md: the docs sidebar, the pre-commit PHI scanner, the em-dash
  brand gate, branch protection and the attw gate
- documentation/packaging.md: the published package and the FHIR hole, hard runtime deps
- documentation/convert-and-map-codes.md: cosyte convert and cosyte map-codes

No heading is renamed and no line is deleted. Each reduced document keeps its heading and
carries a pointer at the copy, so every heading stays reachable from the document that
replaced it. Links inside moved text are re-based by exactly one directory, so nothing
points outside this repo. package.json files is untouched and npm pack --dry-run lists the
same four entries as before, so the published tarball is unchanged.

CLAUDE.md now measures 11862 bytes over 174 lines and keeps all five required headings;
README.md measures 21186 bytes.
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.

1 participant