Skip to content

S0308-submodule-agent-doc-budgets: split CLAUDE.md into documentation/ - #62

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

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

Conversation

@NSchatz

@NSchatz NSchatz commented Sep 16, 2026 •

Copy link
Copy Markdown
Contributor

What

CLAUDE.md measured 23644 bytes against the 16200-byte ceiling the umbrella budget sets for a
submodule agent doc. Three whole sections move, byte for byte and under their existing headings,
into documentation/ beside agent-notes.md, which this file already names as its long-form
record.

section now lives in
Required checks on main documentation/required-checks-on-main.md
Engineering Guardrails documentation/engineering-guardrails.md
Standing disciplines (every change) documentation/standing-disciplines.md

Each heading STAYS in CLAUDE.md, above a pointer to the file its body moved to. No heading is
renamed, no text is deleted, and the moved bodies are byte for byte what they were: the sha256 of
each new file below its two-line preamble equals the sha256 of the lines it came from at the base
commit, and the retained head of CLAUDE.md hashes the same as lines 1 to 128 of the original.

Why documentation/

This repo's own agent doc names it: the header of CLAUDE.md calls documentation/agent-notes.md
the long-form record, so the split files land beside it rather than in docs-content/, which is
consumer-facing content published to the docs site and gated as a public surface.

Checks

  • Heading reachability (every heading present at the base commit still reachable from CLAUDE.md
    or from a file it links to): prints nothing. 8 headings before, 8 after.
  • Link resolution (no absolute target, no parent-directory target, no missing target) over
    CLAUDE.md and over each of the three added files: prints nothing. The three added files carry
    no markdown links.
  • bash scripts/check-no-emdash.sh: OK, with the three new files tracked.
  • bash scripts/check-no-internal-refs.sh: OK. CLAUDE.md and documentation/ are both outside
    that gate's scan surface, which is README.md, LICENSE, docs-content/ and the npm metadata.
  • CLAUDE.md is now 10364 bytes over 145 lines, and still carries ## Project, ## Status,
    ## Tech Stack, ## Engineering Guardrails and ## Standing disciplines.

Blast radius

Markdown only. No generator, seed, fixture, emitted string or log line is touched. Nothing in the
published file set (dist, README.md, LICENSE, CHANGELOG.md) and nothing in the docs
artifacts (built from docs-content/ and src/) is derived from what moved, so no published byte
changes. The synthetic-safety and PHI discipline section deliberately STAYS in CLAUDE.md: it is
the part every worker must read before touching output, so it keeps its place in the always-read
document rather than buying headroom this file does not need.

No changeset: nothing a consumer installs or reads changes.

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

CLAUDE.md measured 23644 bytes against the 16200-byte ceiling the umbrella
budget sets for a submodule agent doc. Three whole sections move, byte for
byte and under their existing headings, into documentation/ beside
agent-notes.md, which this file already names as its long-form record:

  documentation/required-checks-on-main.md
  documentation/engineering-guardrails.md
  documentation/standing-disciplines.md

Each heading stays in CLAUDE.md above a pointer to the file its body moved
to, so no heading is renamed and no text is deleted. CLAUDE.md is now 10364
bytes over 145 lines, which keeps both the five required headings and the
300-line ceiling the estate's engineering baseline sets for a package repo's
agent doc.

Markdown only: no generator, seed, fixture, emitted string or log line is
touched, and nothing in the published file set is built from what moved.
@NSchatz

NSchatz commented Oct 8, 2026

Copy link
Copy Markdown
Contributor Author

Closing: this pull request came from an internal pipeline that was retired on 2026-10-08, and we are deleting its branch. If the change is still wanted, we will open a fresh pull request for it.

@NSchatz NSchatz closed this Oct 8, 2026
@NSchatz
NSchatz deleted the sdd/S0308-submodule-agent-doc-budgets-synth branch October 8, 2026 18:14
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