Skip to content

S0308-submodule-agent-doc-budgets: relocate the Traps section out of CLAUDE.md - #144

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

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

Conversation

@NSchatz

@NSchatz NSchatz commented Sep 16, 2026

Copy link
Copy Markdown
Contributor

What

CLAUDE.md is loaded whole by every session that works in this checkout, and it stood at 24653 bytes against the 16200-byte ceiling for a submodule agent doc. This moves the ## Traps section, byte for byte and under its existing headings, into documentation/agent-notes/claude-md-relocated-traps.md, and leaves the ## Traps heading in CLAUDE.md above a pointer at the new file at the point the section left.

Markdown only. No parse, mapping, fixture or log line moves.

Why this shape

  • Nothing is deleted and no heading is renamed. All 47 headings the document carried at the base commit are still reachable from it, 38 of them through the new pointer.
  • documentation/agent-notes/<slug>.md is the destination this repo's own standing discipline names for relocated narrative, and the route claude-md-relocated-narrative.md already took. The naming follows it.
  • The five headings the package baseline requires (## Project, ## Status, ## Tech Stack, ## Engineering Guardrails, ## Standing disciplines) stay in CLAUDE.md, well inside the 300-line budget.

Evidence

  • CLAUDE.md: 24653 to 7037 bytes, 289 to 73 lines.
  • Heading reachability against the base commit: prints nothing. Dropping the pointer as a control prints all 38 relocated headings, so the check is not vacuous.
  • Link resolution over CLAUDE.md and the new file: prints nothing. No absolute link, no link leaving the repo, no missing target.
  • pnpm typecheck, pnpm lint, pnpm format:check, pnpm test (112 files, 4361 passed, 5 skipped), pnpm check:no-emdash, pnpm check:no-internal-refs, pnpm phi-scan --staged: all green.
  • drift-check reports the same two dependency findings as the base commit and no agent-doc finding.
  • Nothing in src or test reads either file; the two test references to CLAUDE.md are prose in doc comments. npm pack --dry-run assembles the identical 6-entry file set with the identical shasum before and after, and the docs bundle is built from docs-content/ only.

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

…CLAUDE.md

CLAUDE.md is the file an implementer loads whole inside this checkout, and it
stood at 24653 bytes against the 16200-byte ceiling its readers hold it to. The
`## Traps` section moves byte for byte into
documentation/agent-notes/claude-md-relocated-traps.md, under its existing
headings, with the `## Traps` heading left in CLAUDE.md above a pointer at the
new file at the point the section left.

Nothing is deleted and no heading is renamed: all 47 headings the document
carried are still reachable from it, 38 of them through that one pointer. This
is the route CLAUDE.md's own standing discipline names, narrative to
documentation/agent-notes/<slug>.md with only the imperative coming back, and
the route the relocated narrative already took.

CLAUDE.md: 24653 to 7037 bytes, 289 to 73 lines. The five headings the package
baseline requires stay in it and drift-check reports no new finding. Markdown
only: no parse, mapping, fixture or log line moves, nothing in `src` or `test`
reads either file, and `npm pack --dry-run` assembles the identical file set
with the identical shasum before and after.
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