Repository navigation
docs: trim CLAUDE.md, move companion detail to its own file - #694
Merged
Merged
Conversation
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>
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
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.
CLAUDE.mdis 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.mdEleven 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:\codevdirectories and which one is not the wire repo, the nodus-mcp egg-info pitfall, the VS Code PAT organization scope, thenodus-flowrename 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 andpyproject.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 ownversion files agreecheck 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 agreestill covers the real authorities.Also updated
~/.pypirctoken creates a new project on first upload, so a project-scoped token is an alternative rather than a requirement. Established publishingnodus-workflow-ai.Facts re-measured, not carried forward
.venvvssrc/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