CLAUDE.md is a router, not a manual: 22.9 KB to 8.3 KB - #725
Merged
Merged
Conversation
lmoresi
force-pushed
the
docs/audit-2026-09
branch
from
September 11, 2026 18:13
fac3b9c to
fb4ccb3
Compare
lmoresi
force-pushed
the
docs/claude-md-trim
branch
from
September 11, 2026 18:13
6db41b3 to
2118b12
Compare
Every session loads this file verbatim before it loads anything else, and it had grown to more than twice the size of the Style Charter it defers to. That is the wrong way round: the file whose job is to point at the governing documents was the bulkiest thing in the context, and the 2026-09 audit found it competing for attention with the rules it exists to route to. Most of the bulk was duplication of documents that already govern their topic. `docs/developer/guides/branching-strategy.md` already carries the branch roles, the API-versus-implementation discipline, the worktree lifecycle, the branch policy and a section addressed to AI assistants; CLAUDE.md restated 4.3 KB of it. The on-demand documentation list restated the authority map in `docs/developer/index.md`. Both are now one pointer each. The build constraints move to `guides/development-setup.md`, which was a stub that still told developers to run `pixi run underworld-build` — a command the tooling replaced with `./uw build`. It now carries the rebuild rule, the editable-install prohibition and its recovery recipe, the PETSc non-relocatability warning, and how worktree environments work. CLAUDE.md keeps the four hard rules as one line each. Nothing normative was dropped. What remains is what a session needs before it knows where to look: the Charter mandate, session bootstrap and the external planning protocol, the hard constraints, where files go, the rulings that are non-obvious and easy to get wrong (rotated free-slip over Nitsche, the data access contract, unwrap-before-atoms, the ambiguous `model`), the test markers, and the pointer to the authority map. Every path this file names was checked to resolve. Underworld development team with AI support from Claude Code
lmoresi
force-pushed
the
docs/claude-md-trim
branch
from
September 11, 2026 21:10
2118b12 to
dd69ed3
Compare
lmoresi
added a commit
that referenced
this pull request
Sep 17, 2026
…doubled band 45 commits of development, three conflicts, all in files the recent audit touched. CLAUDE.md — took development's trimmed version (#725 cut it 22.9 KB -> 8.3 KB by moving detail into docs/ and leaving pointers). This branch still carried the pre-trim file, so taking its side wholesale would have silently reverted that work. The one thing this branch genuinely adds is the adversarial-review ruling, and the guide it points at (docs/developer/guides/adversarial-review.md) is new here and merges cleanly, so the pointer is re-added in the trimmed file's own style rather than the section being restored in full. scripts/test.sh — took development's side. This branch named test_1072_free_surface_spherical.py and test_1074_free_surface_config_drift.py on their own lines, from when test_107* was not batched. It is batched now (test_106*py test_107*py), so the named lines would run those files twice - and they use the old unquoted $PYTEST form, which #731 replaced with a bash array because the string form word-splits `-m "not tier_c"` and silently collects ZERO tests while exiting 0. Keeping them would have reintroduced that. swarm.py — kept BOTH sides. The conflict is two unrelated additions landing at the same point in advection(): this branch's transcript hook (_note_advection, which records the particle count before and after so a run says when a swarm quietly lost particles) and development's population control plus _characteristics_for. Neither supersedes the other; the resolution runs population control, notes the advection, and keeps _characteristics_for as its own method. tests/test_00[0-4]*py 249 passed; tests/test_05*|06*|07*py 714 passed, 6 skipped, 9 xfailed, 1 xpassed. Underworld development team with AI support from Claude Code
lmoresi
added a commit
that referenced
this pull request
Sep 24, 2026
…s, and the expression snapshot 64 commits of development — #697, #716, #753 and #775 among them. Two conflicts, both the same shape as #716's, because this branch forked from the timestepping branch before that merge happened. swarm.py — kept BOTH sides. Two unrelated additions land at the same point: this branch's _adjoint_support (the particle-set rule: an advection is adjointable exactly when the count is unchanged across it) and development's _characteristics_for. Neither supersedes the other. CLAUDE.md — took development's trimmed version. This branch still carried the pre-#725 file, so taking its side wholesale would have reverted a 22.9 KB -> 8.3 KB cut. The one ruling it genuinely adds — the consistent_jacobian tangent policy, and that the rotated constraint is transparent to it — is carried over, rewritten in the trimmed file's voice and attached to the free-slip ruling it belongs with. Also annotated one except-pass the Charter scan flagged in adjoint.py: the _sync_lvec_to_gvec call is an optimisation, not the write. The values are already in out_var.vec; a variable class without that method syncs on demand instead, which is correct and merely later. Caught AttributeError specifically, so a failure inside the sync still propagates. Adjoint suite (test_0018-0026) 38 passed, including the nonlinear-continuation gradient that CI had been failing on. Core band tests/test_00[0-4]*py 292 passed. Deprecated-pattern scan clean. Underworld development team with AI support from Claude Code
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
1 participant
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.
Stacked on #723 — it references
scripts/check_test_coverage.py, which landsthere. Retarget to
developmentonce #723 merges.Why
Every session loads
CLAUDE.mdverbatim before it loads anything else. It hadgrown to 22.9 KB — more than twice the Style Charter it defers to. That is the
wrong way round: the file whose job is to point at the governing documents had
become the bulkiest thing in the context, competing for attention with the rules
it exists to route to.
This came out of the 2026-09 audit, which started from the observation that
adversarial review of the advection/particle PRs was turning up Charter
violations that nobody had been reminded of.
What was actually in there
Mostly duplication of documents that already govern their topic.
guides/branching-strategy.mdalready carries the branch roles, theAPI-versus-implementation discipline, the worktree lifecycle, the branch policy,
and a section addressed to AI assistants. CLAUDE.md restated 4.3 KB of it. The
"On-Demand Documentation References" section restated the authority map in
docs/developer/index.md. Both are now one pointer each.The build constraints move to
guides/development-setup.md— which was a stubthat still told developers to run
pixi run underworld-build, a command thetooling replaced with
./uw build. It now carries the rebuild rule, theeditable-install prohibition with its recovery recipe, the PETSc
non-relocatability warning, and how worktree environments work. CLAUDE.md keeps
those four as one line each, because they are the ones that cost an hour when
broken.
What stayed
What a session needs before it knows where to look: the Charter mandate,
session bootstrap and the external planning protocol, the hard constraints,
where files go, the rulings that are non-obvious and easy to get wrong (rotated
free-slip over Nitsche, the data-access contract, unwrap-before-atoms, the
ambiguous
model), solver-stability, the test markers, and the pointer to theauthority map.
Nothing normative was dropped — checked rule by rule against the previous
version — and every path the file names was verified to resolve.
Underworld development team with AI support from Claude Code