Skip to content

docs: trim CLAUDE.md, move companion detail to its own file - #694

Merged
Masterplanner25 merged 2 commits into
mainfrom
docs-trim-claude-md
Aug 30, 2026
Merged

Masterplanner25 merged 2 commits into
mainfrom
docs-trim-claude-md

Conversation

@Masterplanner25

Copy link
Copy Markdown
Owner

CLAUDE.md is loaded into context every session, so length there is a running cost. 1,889 → 1,619 lines, with no lesson dropped.

Companion detail → docs/ecosystem/COMPANION_REPOS.md

Eleven per-companion sections sat in three separate regions of the file, interleaved with unrelated material, and the key-file table listed all the same paths a fourth time. They are one document now, reached from a fourteen-row index.

Every gotcha survives — the two C:\codev directories and which one is not the wire repo, the nodus-mcp egg-info pitfall, the VS Code PAT organization scope, the nodus-flow rename rule, and the module-vs-distribution collision that deleted a package's classes with pip reporting success both times.

Two sections were saying the same thing twice

SemVer (146 → 85). It carried a narrative per release duplicating CHANGELOG.md, told 5.7.0's supersession once at the top and again eighty lines down, and printed the "X is current" vs "as of X" paragraph verbatim in two places.

What survives is what the changelog cannot tell you at a glance: the not-additive table — which answers "is this symptom a release, or my change?" — and the rules the release process needs. It now also records that the 5.7.0 rule is about a release a fix will supersede, and does not apply when the Stage 5 defect is pre-existing. That is the distinction 5.8.0 had to make.

Published ecosystem (116 → 94). Per-package detail that now lives in the new file.

Two version claims retired rather than re-registered

They guarded CLAUDE.md quoting version.py's and pyproject.toml's literal contents back at the reader — a third copy of a fact that already has two authorities, kept in step by a claim, while the gate's own version files agree check compares those authorities directly.

The restatement was removed instead of the claim being repointed. A claim is worth having when prose asserts something a reader acts on; it is not worth having to guard a transcription that did not need to exist. 13/13 claims pass, and version files agree still covers the real authorities.

Also updated

Facts re-measured, not carried forward

Claim Was Now
tests collected 2,940 3,132
gate symbols 136 138
runtime blocks 263 268
.venv vs src/ 5.0.0 / 5.7.1 5.0.0 / 5.8.0

Gate

All nine phases pass — static 138/138, runtime 268/268, contracts 6/6, opcodes 28/28, consumers 2/2, shapes 0 new, versions 13/13, invariants 4/4.

🤖 Generated with Claude Code

https://claude.ai/code/session_013uyCMZqPCwvXnjkgc1mSFJ

Masterplanner25 and others added 2 commits August 30, 2026 14:00
CLAUDE.md is loaded into context every session, so length there is a running
cost. 1,889 -> 1,619 lines, with no lesson dropped.

Eleven per-companion sections sat in three separate regions of the file,
interleaved with unrelated material, and the key-file table listed all the same
paths a fourth time. They are one document now -- docs/ecosystem/COMPANION_REPOS.md
-- reached from a fourteen-row index. Every gotcha survives: the two C:\codev
directories and which one is not the wire repo, the nodus-mcp egg-info pitfall,
the VS Code PAT organization scope, the nodus-flow rename rule, the module-vs-
distribution collision that deleted a package's classes with pip reporting
success.

Two sections had been saying the same thing twice. SemVer carried a narrative per
release duplicating CHANGELOG.md, told 5.7.0's supersession once at the top and
again eighty lines down, and printed the "X is current" vs "as of X" paragraph
verbatim in two places -- 146 lines to 85. What survives there is what the
changelog cannot tell you at a glance: the not-additive table, which answers "is
this symptom a release or my change?", and the rules the release process needs.
It also now records that the 5.7.0 rule is about a release a fix will supersede,
and does not apply when the Stage 5 defect is pre-existing -- the distinction
5.8.0 had to make.

Two version claims were retired rather than re-registered. They guarded CLAUDE.md
quoting version.py's and pyproject.toml's literal contents back at the reader: a
third copy of a fact that already has two authorities, kept in step by a claim,
while the gate's own "version files agree" check compares those authorities
directly. The restatement was removed instead of the claim being repointed.

Updated as well: #691 is documented in the language quirks with its repro and its
workaround, and named in the recurring-shape section as an open *candidate* --
deliberately not in that table, whose standard is "confirmed by reading the code"
and which #691 has not met yet. The published-ecosystem section records that
re-deriving the package count only works if the list it derives from is complete,
which at 5.8.0 it was not, and corrects the token note: the account-scoped
~/.pypirc token creates a new project on first upload, so a project-scoped token
is an alternative rather than a requirement.

Facts re-measured, not carried forward: 3,132 tests collected, 138 gate symbols,
268 runtime blocks, .venv still at 5.0.0 against src/ at 5.8.0.

Gate: all nine phases pass.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uyCMZqPCwvXnjkgc1mSFJ
The SemVer rewrite deleted the 'README.md is current' sentence, and an ignore
entry in version_claims.json existed only to suppress the discovery sweep on it.
An entry matching nothing is dead weight, and
test_every_ignore_entry_still_matches_something fails on it -- which is how CI
caught this.

Worth noting which check found it: nodus_gate --versions passed locally, because
the discovery sweep is advisory and the gate does not verify that ignore entries
are still live. Only the test does. Running the gate is not a substitute for
running the tests over the registers the gate reads.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Masterplanner25
Masterplanner25 merged commit 628c32f into main Aug 30, 2026
4 checks passed
@Masterplanner25
Masterplanner25 deleted the docs-trim-claude-md branch August 30, 2026 21:16
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