docs(agent-guidance): document fresh-worktree prerequisites for full validation#861
Open
brandonpayton wants to merge 2 commits into
Open
docs(agent-guidance): document fresh-worktree prerequisites for full validation#861brandonpayton wants to merge 2 commits into
brandonpayton wants to merge 2 commits into
Conversation
…validation A new git worktree (and a fresh checkout) does not inherit git submodules, a musl sysroot, node_modules, or fetched test binaries, so Vitest and the conformance/browser suites cannot run until those are built or fetched. Agents were treating this as "cannot validate" rather than a setup step. Document the exact sequence in validation.md and build-docs-and-prs.md: submodule init (with the stray-libc/musl recovery), build-musl.sh (sysroot), build.sh (kernel wasm → local-binaries/kernel.wasm + rootfs), root + host `npm ci` (root provides tsx for the conformance runners), and fetch-binaries.sh. Add the explicit instruction not to report "I can't run Vitest/conformance/browser" because a fresh worktree lacks artifacts — build or fetch them and report the real result, or name the exact step that failed. Verified by running the sequence end-to-end in a fresh worktree: kernel wasm + sysroot + rootfs build, `vitest` (778 pass; the only failures were a missing fetched `programs/wasm64/hello64.wasm`), and Sortix conformance (10/10) all ran. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…uidance Two additions learned from running the full suite in a fresh worktree: - The wasm64 Vitest cases need an LP64 hello64.wasm that fetch-binaries.sh does not carry; build it with build-musl.sh --arch wasm64posix + build-programs.sh. - A few package/demo tests (e.g. the Erlang ring benchmark) can fail for environment/artifact reasons unrelated to a diff. Reproduce on a pristine origin/main kernel-wasm build before attributing the failure to your change. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
Why
A new
git worktree(and a fresh checkout) does not inherit git submodules, a musl sysroot,node_modules, or fetched test binaries — so Vitest and the conformance/browser suites can't run until those are built or fetched. This was being treated as "cannot validate" rather than a one-time setup step.What
Document the exact prerequisite sequence in
docs/agent-guidance/validation.md(new "Preparing a fresh checkout or worktree" section) anddocs/agent-guidance/build-docs-and-prs.md("First build in a fresh checkout or worktree"):git submodule update --init --recursive(musl, libc-test, os-test) — with the stray-libc/muslrecovery (rm -rf libc/musl && git submodule update --init libc/musl).scripts/build-musl.sh— sysroot (~20s).bash build.sh— kernel wasm →local-binaries/kernel.wasm+ host +rootfs.vfs(~1.5min).npm ci(root — providestsxfor the conformance runners) and(cd host && npm ci).scripts/fetch-binaries.sh— prebuilt test binaries the source build doesn't produce (e.g.programs/wasm64/hello64.wasm).Plus an explicit instruction: do not report "I can't run Vitest/conformance/browser" because a fresh worktree lacks artifacts — build/fetch them and report the real result, or name the exact step that failed.
Verified
Ran the sequence end-to-end in a fresh worktree: kernel wasm + sysroot + rootfs built;
vitestran (778 pass — the only failures were a missing fetchedhello64.wasm); Sortix conformance ran 10/10. Each of these previously reported a not-found artifact until the corresponding step above was run.🤖 Generated with Claude Code