Problem
The repo has unusually strong verification infrastructure that a contributor can't discover:
- The harness is invisible.
cmd/morphic-harness (sweeps specs through no-panic / invariant / round-trip / determinism oracles), internal/harness, and ir/irverify are documented only in their doc.go files. README's Usage/Building/layout sections never mention them; nothing says when to run the harness (e.g. before submitting a compiler change) or what the oracles check.
- The golden/corpus workflow lives in one code comment. The
-update flag works well (verified — regenerates byte-identically, clean tree), but README only says "the corpus test's -update flag" without naming the test or package; the exact command is a comment at compilers/openapi/conformance_test.go:24. The add-a-conformance-case recipe (paired X.yaml/X.golden.json + a table entry in TestConformance — a new .yaml without a table entry is silently un-asserted by that test) and the purpose of testdata/dangling/ are documented nowhere.
- Three fuzz targets, zero mentions.
FuzzCompile, FuzzLowerSchema, FuzzCycleDetector exist and run fine, but "fuzz" appears nowhere in README/CLAUDE.md/docs, so contributors touching the compiler won't know to run them.
Proposed direction
A short "Testing & verification" section in README (or a testdata/README.md): one harness command with a sentence on the oracles, the concrete golden-regen command, the add-a-conformance-case recipe, and an example -fuzz invocation.
Acceptance
- A contributor adding a compiler feature can find, from README alone: how to add a conformance case, regenerate goldens, run the harness, and run the fuzzers.
Problem
The repo has unusually strong verification infrastructure that a contributor can't discover:
cmd/morphic-harness(sweeps specs through no-panic / invariant / round-trip / determinism oracles),internal/harness, andir/irverifyare documented only in theirdoc.gofiles. README's Usage/Building/layout sections never mention them; nothing says when to run the harness (e.g. before submitting a compiler change) or what the oracles check.-updateflag works well (verified — regenerates byte-identically, clean tree), but README only says "the corpus test's-updateflag" without naming the test or package; the exact command is a comment atcompilers/openapi/conformance_test.go:24. The add-a-conformance-case recipe (pairedX.yaml/X.golden.json+ a table entry inTestConformance— a new .yaml without a table entry is silently un-asserted by that test) and the purpose oftestdata/dangling/are documented nowhere.FuzzCompile,FuzzLowerSchema,FuzzCycleDetectorexist and run fine, but "fuzz" appears nowhere in README/CLAUDE.md/docs, so contributors touching the compiler won't know to run them.Proposed direction
A short "Testing & verification" section in README (or a
testdata/README.md): one harness command with a sentence on the oracles, the concrete golden-regen command, the add-a-conformance-case recipe, and an example-fuzzinvocation.Acceptance