refactor(docs): consolidate design docs under docs/design - #31
Merged
Conversation
ZK-proving the consensus STF has no leanSpec specification, and leanSpec is Verity's reference implementation. Recording an anticipated migration whose trigger cannot be observed upstream commits the design to a direction the spec does not describe, so the material is removed rather than restated. - delete memo.md: its ethlambda crate comparison predates crates/, and its only live section was the ZK-STF open question - drop the State transition row from the boundary migration table and the paragraph qualifying it; the verification boundary is now documented as moving inward only - drop verifiable-stf as cross-language equivalence evidence and as the second measurement data set; the leanSSZ C ABI PoC remains and still gates Lean adoption on measured seam cost - add frontmatter to design-philosophy.md, which predated the rule
The repository root held eight design documents alongside README, CONTRIBUTING, and CLAUDE, and docs/src/reference/architecture.md was a hand-synced 420-line copy of the root ARCHITECTURE.md. Both problems close together: the published page becomes canonical, and the records that elaborate it move under docs/. - move the six remaining design records to docs/design/, renamed to the lowercase-kebab convention already used throughout docs/ - delete the root ARCHITECTURE.md; docs/src/reference/architecture.md is now canonical rather than a mirror, so the duplicate no longer has to be synced by hand on every edit - add the required frontmatter to each moved document and an index at docs/design/README.md; point README at both surfaces - retarget every path reference: 45 inter-document links, six rustdoc comments, three Cargo.toml comments, CLAUDE.md, and _typos.toml - widen markdownlint and both lychee checks to cover docs/design/, and move the offline link check to quality.yml so it is not gated by the Docs workflow's path filter — which now fires only on the book's own inputs Root markdown is README, CONTRIBUTING, and CLAUDE.
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.
Root markdown is now
README.md,CONTRIBUTING.md, andCLAUDE.md. The eight designdocuments that sat alongside them are gone from the root, and the hand-synced duplicate of
the architecture is gone with them.
Two commits, deliberately split
Reviewing the move and the content removal together would defeat git's rename detection.
The first commit removes content in place; the second moves files whose only remaining
edits are link rewrites and frontmatter, so all six show as renames.
1. Drop ZK-STF and verifiable-stf references
ZK-proving the consensus STF has no leanSpec specification, and leanSpec is Verity's
reference implementation. An anticipated migration whose trigger cannot be observed
upstream commits the design to a direction the spec does not describe.
memo.mddeleted — its ethlambda crate comparison predatescrates/, and its only livesection was the ZK-STF open question
State transitionrow leaves the boundary migration table, along with the paragraphqualifying it; the verification boundary is documented as moving inward only
verifiable-stfdrops out as cross-language equivalence evidence and as the secondmeasurement data set — the leanSSZ C ABI PoC remains and still gates Lean adoption on
measured seam cost
design-philosophy.mdgains the frontmatter it predated2. Consolidate under
docs/design/docs/src/reference/architecture.mdwas a 420-line hand-synced copy of the rootARCHITECTURE.md, declaring the root file canonical. It is now canonical itself, and theroot copy is deleted — nothing leaves the published site, only the duplicate.
docs/design/domain-model·concurrency·sync·storage·key-management·model-check, plus an indexdocs/src/reference/architecture.mdARCHITECTURE.md,memo.mdRenamed to the lowercase-kebab convention already used across
docs/, with the requiredfrontmatter added. Retargeted: 45 inter-document links, 6 rustdoc comments, 3
Cargo.tomlcomments,
CLAUDE.md,_typos.toml.CI
docs/design/— previouslyCONCURRENCY,KEY_MANAGEMENT,SYNC, andMODEL_CHECKwere in none of themquality.yml;docs.ymlis path-filtered to the book'sown inputs, and
docs/design/is outside themdocs.ymlno longer fires on design-document edits, so no site build runs for a pagethe site does not contain
The weekly online check now reaches 6 documents it never covered. Expect it to surface
pre-existing broken external links on its first run.
Verified locally
markdownlint-cli20 errors over 14 files · 0 broken relative links acrossdocs/androot ·
mdbook buildclean with frontmatter stripped from output ·cargo check --workspace --all-targetsclean ·pre-commit run --all-filespassing.