docs: restore docs tree with ADR and design homes - #59
Open
mfw78 wants to merge 2 commits into
Open
Conversation
Recover videre-split-plan.md, issue-milestone-plan.md, and videre-wit-pinned-0.1.0.md from the pre-carve shepherd tree (9e5e36c, fb02235); each port carries a provenance header, carve-era path fixups, and house-lint normalization (ASCII for em-dashes and box-drawing), with the content otherwise unchanged. Add docs/adr/README.md as the ADR home convention so the freeze-gate ADRs (#20) and the freeze runbook (#22) have a landing place. Point the types.wit opaque-status citation at section 4 of the restored pin doc. AI Assistance: Claude Code used for the history recovery, the port, and the gate runs.
Add docs/design/README.md so the design tree states what is authoritative, marks each restored document as historical, and holds the landing place for the #22 wit-deps runbook; drop the duplicate landing sentence from the ADR README. Correct two claims: the pre-carve ADR series lives on the shepherd develop line, not in the shepherd main tree, which carries no docs; and the pinned WIT port applied no path fixup, only the title em-dash. Point the ADR README at AGENTS.md for the documentation style instead of restating it, and list docs/ in both tree indexes. AI Assistance: Claude Code used for the red-team review and these fixes.
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
Restores the
docs/tree that the repo carve dropped: two newdocs/*/README.mdindex files stating each directory's local convention, and three ported design documents (docs/design/videre-split-plan.md,docs/design/videre-wit-pinned-0.1.0.md,docs/design/issue-milestone-plan.md).AGENTS.mdandREADME.mdgain a one-linedocs/entry pointing at the new ADR and design homes, and theintent-statusdoc-comment inwit/videre-types/types.witgains a§4section anchor onto the restored pinned-WIT doc.Why
Closes #46
The three docs were recoverable from the pre-carve monorepo,
nullislabs/shepherd, notnexum-runtime(nexum-runtime history has nodocs/tree at all):videre-split-plan.mdandvidere-wit-pinned-0.1.0.mdcome from shepherd9e5e36c,issue-milestone-plan.mdfromfb02235. Each ported document carries a provenance header naming its source commit and disclaiming bare issue numbers (pre-carve shepherd tracker) and in-tree file paths and line numbers (pre-carve monorepo tree). The carve also left two dangling citations, tovenue-platform-architecture.mdandissue-milestone-plan.json, that pointed at an in-tree path that no longer exists; both now point at the shepherd tree by commit instead. House content-lint forced mechanical normalization beyond the pure port: spaced em-dashes were replaced with ASCII hyphens and box-drawing diagrams were converted to ASCII throughout the ported documents.Testing
Independent CI-parity gate, run on a fresh clone at
7d8b229(detached), baseorigin/qa/hardened-boundaries-sweep=9a579e7(confirmed ancestor). Toolchain: rustc/cargo 1.94.0,wasm32-wasip2installed, cargo-nextest 0.9.127. All cargo invocations underRUSTFLAGS="-D warnings"and--locked.The diff touches no Rust source (
AGENTS.md,README.md, three restoreddocs/design/*.md, two newdocs/*/README.md, and a one-line doc-comment citation inwit/videre-types/types.wit). Because the WIT feedswit-bindgenforvidere-sdk,videre-host,videre-macrosand all five guest modules, the checks were run workspace-wide rather than on a narrower touched-crate set.cargo clippy --workspace --all-targets --all-features --locked -- -D warningspasses clean, zero warnings.RUSTDOCFLAGS='-D warnings' cargo doc --workspace --no-deps --lockedpasses clean.Red-team pass byte-diffed the ports against the original shepherd blobs at
9e5e36candfb02235: apart from the provenance headers only three lines differ, and every remaining line has identical character length, confirming the em-dash and box-drawing substitutions were strictly 1:1 and that the diagrams reproduce the originals' rendering exactly.AI Assistance
Implemented with claude-fable-5, red-teamed with claude-opus-5, PR opened with claude-sonnet-5.