Uh oh!
There was an error while loading. Please reload this page.
docs: correct CLAUDE.md statements the tree contradicts - #301
Merged
Conversation
Two follow-ups on the same file, both instances of the rule the rest of the change set out to apply. The reference-learnings entry hard-coded "seven shipped generators" — a maintained count, sitting one paragraph below the line that had just stopped counting the documents. It now points at that document's own header, which names the generators it surveys, so the fact is re-derivable rather than restated in a second place that can rot. The oracle bullet said the harness CLI "runs them all" two sentences after saying Check stops at the first oracle that fires, which invites reading it as "every oracle runs on every spec". It now says what the CLI actually varies — the input — instead of making a claim about exhaustiveness that the preceding sentence contradicts.
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 freeto 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.
Summary
CLAUDE.mdis binding on every contributor and is read before the code, so a false statement in itis worse than a stale comment: it is followed. Eight of them had accumulated, all in the same shape
— a hand-maintained enumeration or count that the tree moved out from under, which is the failure
mode the file's own "Derive counts; never maintain them" rule exists to prevent.
Where a count could be replaced by the command that derives it, it was. Where a fact had to stay
written down, it now names the site it can be re-derived from.
MarshalJSON/UnmarshalJSONfor special forms (the IR's sum types andBigValdo this)".BigValhas no codec at all — it istype BigVal stringwith one method,String(), and needsnone, because being a string type is what preserves precision. And the sum is asymmetric: all
eleven
TypeDefkinds haveMarshalJSON, none hasUnmarshalJSON; the module's onlyUnmarshalJSONis(*TypeRegistry)'s, which peeks the adjacentkindtag and dispatches.Dropping
BigValalone would have left the second falsehood standing, so the sentence nowdescribes the asymmetry and gives the grep that lists the codecs.
there is no
go:generatedirective anywhere. The kind lists are hand-written, andTestTypeDef_HandWrittenKindListsAreCompleteis what holds them to the kinds theirsourcesdeclare. Calling it generated invites a contributor to look for a generator to re-run instead of
editing the list.
overlay/is the one thecount predates). Deleted rather than corrected: the paragraph below the diagram already says the
diagram deliberately does not name them and gives the command that lists them, so the count was
the one part of that sentence able to rot.
harness.Checkapplies six. Order-invariance wasmissing. That omission was doing active harm two paragraphs later, where the two-order-diff rule
read as though no oracle implemented it — so contributors were being told to hand-roll, per new
construct, a diff that already runs across the corpus under
testdata/. Both are corrected, andthe reworded paragraph says when a targeted case is still worth writing: the oracle proves
order-independence only for constructs its inputs contain.
cmd/morphic/was documented as importingengine;internal/archtest'srulesmap — thestated source of truth — says
{ir, engine}.cmd/morphic-harness/was absent from the layout block entirely, which was the one part ofdocs: CLAUDE.md still describes the pre-implementation repository #63's acceptance ("every package in the tree appears in the documented layout") still unmet.
docs/emitter-design.mdwas missingdespite declaring itself normative for the emitter half, as were
reference-learnings.mdand thetwo
micro-compiler-*.mdrecords. All are now listed, with the two micro-compiler documentsmarked as records of landed work so they are not mistaken for a proposal or a backlog.
rename.
Items 1 and 7 are #277 and the last open bullet of #63. Items 2-6 are not in either issue text;
they surfaced while checking the sections around them and are the same defect, so they are fixed
here rather than left to be re-derived by the next reader.
Deliberately out of scope, so it is not lost:
docs/architecture.md§3 lists the same thirteeninternal packages and also omits
overlay/, and README/architecture carry thecmd/morphicimportrow — those belong to #64 and are being fixed there. Two further sites found while verifying are
filed rather than fixed here: #299 (
docs/micro-compiler-design.mdrepeats the thirteen) and #300(the "a emitter" rename residue, 22 occurrences across five files in
docs/).Test plan
No test guards prose, so every corrected claim was re-derived from the tree by command rather than
by reading, and the whole set was then run against the pre-change file to confirm each correction
was load-bearing — 11 assertions fail against
origin/main'sCLAUDE.md, 0 against this branch.BigValhas no codecgrep -n 'type BigVal|func (v BigVal)' ir/bigval.gotype BigVal string,String()— nothing elsegrep -rnE 'func .*(Unm|M)arshalJSON' ir/MarshalJSON(one pertypeDef()implementer), 1UnmarshalJSON, onTypeRegistrygrep -rn 'go:generate' --include='*.go' .grep -rn 'func TestTypeDef.*Complete' ir/TestTypeDef_KindDispatchIsComplete,TestTypeDef_HandWrittenKindListsAreCompletels -d compilers/openapi/internal/*/ | wc -l14; the same 14 as keys in archtest'srulesinternal/harness/harness.go:50-88orderInvariant→OutcomeOrderDependentcmd/morphicimportsgrep -n '"cmd/morphic"' internal/archtest/arch_test.go{module + "/ir", module + "/engine"}git ls-files '*/*.go' | xargs -n1 dirname | sort -ucompilers/openapi/internal/*as a class by designls docs/*.mdEach command the file now instructs a reader to run was executed as written from the repo root,
including
go run ./cmd/morphic-harness <file>and<dir>— both reportok.Full gate (
gofmt,go vet,golangci-lint,go build,scripts/check-coverage.sh) passes; thechange is documentation only, so no goldens move and coverage is unaffected.
Closes#63
Closes#277
Closes#339