docs: trim architecture/ to charter — invariants only - #282
Merged
Conversation
Cut pseudocode transcriptions, pasted-code narration, verbatim error-message quotes, and content now fully covered in docs/ or duplicated across the six capability files. Fixed the stale INVALID_SCOPE_DEPENDENCY_ERROR reference in validation.md. KEEP kernels (cycle-guard rationale, effective_scope alias-transitivity, registry sharing, WiringPlan bucket semantics, override-bypasses-scope implications, etc.) preserved with meaning intact. architecture/: 6902 -> 5291 words across the six files; README.md unchanged. No behavior or docs/ changes.
lesnik512
added a commit
that referenced
this pull request
Aug 13, 2026
architecture/ was 11 capability pages, 1,470 lines, restating what modern_di/ already says. It had been cut to invariants twice -- b2404c4 (#282, 433 deletions against 110 insertions across six pages) and 047b6ea (#395, 292 against 147 across four) -- and regrew both times. Promotion discipline was never the failure: 48 of the 67 commits touching modern_di/ also touched it. The PR checklist asked "did you update the page?" and never "should this paragraph exist?", so every PR added a paragraph and none removed one, and the pages ratcheted toward restating code. The invariants turned out to be already executable. 31 tests now carry an INVARIANT: docstring -- the claim on line 1, what breaks it in the second paragraph -- and only four tests are genuinely new (one-graph, compile-resolver-fails-loudly, scope.py import purity, union-member origin degradation). The rest was marking, not writing. tests/test_invariant_census.py guards the scheme: every test name cited in a comment or docstring under modern_di/ and tests/ must resolve to a real test, every INVARIANT: docstring must state what breaks it, and every tests/*.py and planning/*.md path cited from code must exist. Code comments cite tests, not pages. Vocabulary moved to CLAUDE.md, which is auto-loaded where architecture/README.md never was. The free-threaded Beta support level moved to docs/introduction/design-decisions.md at user altitude. planning/decisions/ took nothing. Six records were written during the work and all six were dropped, so the admission check narrowed to three routes: derivable from modern_di/ -> don't write it; enforceable -> a test; a user needs it -> docs/; otherwise it does not get written. Four negative contracts -- transient teardown order, rebinding an in-use provider, override values not being type-checked, and the integration-kit per-adapter boundary -- now live only in the code and its tests. check-links passing after the deletion is the completeness proof: those references resolve while architecture/ exists and only break once it is gone. Co-authored-by: Claude Opus 5 <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
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.
The last item from the 2026-07-06 verbosity benchmark.
architecture/trimmed to its charter — the invariants, edge cases, and rationales a maintainer cannot read off the code. Deleted: a 30-line pseudocode transcription ofContainer.validate(), pasted-code-plus-narration, verbatim error-message quotes (one already stale — it namederrors.INVALID_SCOPE_DEPENDENCY_ERROR, a constant that doesn't exist), and re-explanations of behaviordocs/already owns (now links). Spec:planning/changes/2026-07-07.04-architecture-halving.md.6,902 → 5,320 words (-23%). Short of the spec's ~halving estimate by design: since the docstring cleanup (#280),
architecture/is the sole home of the rationales removed from code, and the trim stopped where cuts risked losing them. An adversarial information-loss review verified all ten protected kernels survive intact (cycle-guard rationale, alias transitivity + edge cases, registry-sharing table,set_contextstaleness, pre-2.16 note, LIFO finalization, WiringPlan buckets, kwargs-bypass-validate, override-bypasses-scope-check, the resolution rule) and checked every deleted passage's survival claim against the named code symbol or docs page.Gates:
just lint-cigreen; stale-constant grep empty; inbound links fromdocs/andCLAUDE.mdverified.