Spec purity: move the VM record into docs/ - #19
Merged
Merged
Conversation
VM.md sections 6 to 8 (the divergence table, the oracle provenance, and the design decision record) were rationale and evidence, not behavior. They move verbatim to docs/vm-record.md with cross references retargeted: record-internal section numbers now point at the record's own sections, and references to evaluator behavior name VM.md explicitly. spec/ now states behavior only. VM.md sections 1 to 5 are unchanged in substance, and its header now names the record as the home of the open Phase 3 questions. COSTS.md and MATCHING.md citations of the decision record follow the move. The divergence labels D1 to D9 are unchanged and remain cited from spec prose, vectors, and the diff harness.
docs/README.md indexes the new VM record. Pointers in opcode-comparison.md and execution-plan.md that named VM.md sections 6 to 8 now name docs/vm-record.md. The root README layout table follows: VM.md is the evaluator alone, and the docs/ row gains the record.
sha256tree.json and secp.json cited VM.md section 6 for their divergence rows (D9 and D2). The table now lives in docs/vm-record.md and the normative operator behavior stays in VM.md section 4, so the citations name section 4 alone with the divergence labels kept. No expectations change: 481 vector cases pass unchanged.
Ground rule 1 now states that spec/ holds behavior only, complete enough on its own to predict every vector's outcome, and that rationale, oracle provenance, and decision records live in docs/. Ground rule 3 and the reference material policy point at docs/vm-record.md instead of spec/VM.md for the divergence table and the oracle provenance.
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.
What changed
spec/VM.md sections 6 to 8 (the divergence table, the oracle provenance, and the design decision record) moved verbatim into a new docs/vm-record.md. The spec now states behavior only. Nothing in the record is needed to predict a vector's outcome, and VM.md sections 1 to 5 are unchanged in substance. Every cross-reference in the repo was retargeted, and the CLAUDE.md ground rules were amended to record the principle and the new locations.
The divergence labels D1 to D9 are unchanged everywhere (spec prose, vectors, harness output), so nothing that cites a label moves.
Authority
The restructure follows the spec-purity decision from our design discussion: spec/ holds normative statements, rationale and evidence live in docs/. This PR also lands the CLAUDE.md ground-rule amendment that records it (rule 1 gains the purity statement, rule 3 and the reference material policy point at docs/vm-record.md).
Read the commits in this order
Verify independently
The grep should return nothing. Ran here: lint clean, 77 unit tests and 481 vector cases pass, sweep empty. The diff harness is untouched by this PR (no behavior change), but a fresh-seed run reproduces Phase 1:
.venv/bin/python tools/diff_clvm.py --count 10000 --seed 20260730.