diff --git a/CLAUDE.md b/CLAUDE.md index 75dd498c239..43d3777daa5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,14 +50,14 @@ Rust and QEMU are the development prerequisites. Other host tools must be builda - **Choose the cheapest sufficient test.** First make bugs unrepresentable, then test logic and failure handling on the host, including hardware models. Prefer metal for actual hardware behavior; QEMU is last. Receiving malformed input is a unit or module test, even when the real input arrives from another process. Crossing a component boundary does not itself justify an integration test. - **Keep tests focused.** Userland is tested as units and modules, with at most a cheap smoke test. Avoid scenarios that install software, launch applications and drive unrelated steps. Kernel integration and hardware tests must name the behavior host tests cannot establish. Each test has a clear claim, controlled inputs and a meaningful failure; automated tests do not depend on the public internet. - **Declare where integration tests run.** Record supported metal machines and QEMU configurations with the test registration or harness metadata. Before opening a code PR, run the relevant integration tests on those targets. The broad integration matrix runs nightly, not for every PR or merge-queue entry. Host checks remain routine. Inspect the actual harness and workflows; these instructions do not themselves change their scheduling. -- **AArch64 waits for a metal bench.** Until an AArch64 metal bench exists, there is no AArch64-only work. A PR runs aarch64 guest tests only when it changes AArch64 code or the shared code beneath it, such as memory management, context switch, the loader, and shared atomics or DMA ordering that only aarch64 exposes; nightly covers the rest. An aarch64-only red that the change did not introduce is a sighting unless it shows a defect in shared code. +- **AArch64 waits for a metal bench.** Until an AArch64 metal bench exists, there is no AArch64-only work. A PR runs aarch64 guest tests only when it changes AArch64 code or the shared code beneath it, such as memory management, context switch and the loader; nightly covers the rest. An aarch64-only red that the change did not introduce is a sighting unless it shows a defect in shared code. - **Amortize boots.** Batch compatible metal tests in a shared boot. Separate boots need a reason, such as a boot-only property, destructive test or incompatible image. Plenty of useful metal tests are welcome; unnecessary reboots are not. - **Use real hardware for timing and audio.** QEMU establishes order, completion, contents and counts; its clock is only a hang ceiling. Benchmarks and exploratory comparisons are evidence, not automatically regression tests. A timing test has a justified bound for its declared machine. - **Run what can change.** Use `cargo run -- --ci host` for host checks, `cargo run -- --build-only` for an image, and filtered guest rows for relevant guest behavior. Repeat checks only when a change, failure or unresolved concern could invalidate their result. A new commit, comment deletion or rename alone does not require another integration run; compile where necessary. - **Investigate reds.** Do not rerun a failure merely to get green. Fix a defect introduced by the change. A real unrelated defect may be recorded without blocking the PR once its independence is established. Repair or delete a defective or redundant test according to its value, preserving evidence of any real bug it exposed. A guest red that appears only under host noise is not investigated or fixed; it may be recorded as a sighting. - **Show evidence.** Record commands, exit codes, logs, revisions and machines. Identify earlier evidence reused and why later edits do not invalidate it. Use an independent oracle where available and a negative control where a defect would otherwise land unseen; the whole change reverted onto the measured base is the control for the whole change. Another agent is not an independent oracle. Do not add a test for what a type or straightforward inspection already establishes. -Guest tests run on the guest runner through `guest-rows.yml`'s dispatch (`tests/CLAUDE.md`), and agents may dispatch their own selected rows; aarch64 guests also run on a quiet Mac on demand. Metal runs are coordinated and executed by the orchestrator; implementers prepare them with `--metal-readback`, which touches no machine. +An agent's guest evidence, aarch64 included, comes only from the guest runner through `.github/workflows/guest-rows.yml`'s dispatch (`tests/CLAUDE.md`), and agents may dispatch their own selected rows. aarch64 guests run there emulated and show neither timing nor aarch64's weak ordering, which `kernel/loom/` checks. Metal runs are coordinated and executed by the orchestrator; implementers prepare them with `--metal-readback`, which touches no machine. ## Working safely diff --git a/issues/the-nightly-is-frozen-so-nothing-runs-the-guest-matrix.md b/issues/the-nightly-is-frozen-so-nothing-runs-the-guest-matrix.md index 3ff48f4099d..0cfcb2546b4 100644 --- a/issues/the-nightly-is-frozen-so-nothing-runs-the-guest-matrix.md +++ b/issues/the-nightly-is-frozen-so-nothing-runs-the-guest-matrix.md @@ -20,4 +20,7 @@ QEMU, while `guest.yml`'s container still installs 11.1.1 from its snapshot archive, so its instrument step reds until the container moves to an image carrying 11.1.3. -**Exit**: the nightly resumes, its guest container on 11.1.3. Held by the owner. +**Exit**: the nightly resumes with its guest lanes on the guest runner rather +than GitHub's machines. Only a `workflow_dispatch`-only workflow may name that +runner, so resumption owes a design for a scheduled job under that guard. Held +by the owner.