docs(AGENTS.md): make just the only build/test surface for agents - #1115
Merged
Conversation
The platform matrix read as "macOS cannot build or test minimald", which is only true of a *native* build: `just test-cross` cross-compiles the whole workspace (minus minvmd) to musl in Docker and runs its tests, so the daemon and the CLI's test targets are reachable from a Mac. Agents took the old wording as licence to skip that coverage, or to hand-roll cargo invocations around it. - State the native-only limit, then name `just test-cross` as the macOS answer for everything the darwin scope skips, and say plainly that a minimald / CLI-test change is unverified until it has run. - Add the just-only rule: the recipes carry the per-OS scoping, the pinned flags, and the ordering constraints (the macOS codesign, most sharply); a hand-rolled cargo line drops them silently. If a task has no recipe, add one. - Replace the two remaining raw-cargo instructions — the `cargo test -p <crate>` inner loop and the `cargo clippy --allow-dirty --fix` variant — with `just test` and `just fix`, which are those commands, scoped. - Stop quoting runnable cargo lines in the recipe descriptions; they read as commands to copy. Refresh the recipe inventory while here: the count (33) and the list had both fallen nine recipes behind the justfile. Now 42 on Linux / 37 on macOS, with fix, lint-shell, msrv, miri, fuzz, fuzz-check, test-promote-gate, stress, bulk-upload, and kernel-review documented. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
📝 WalkthroughWalkthroughUpdated ChangesWorkflow guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@AGENTS.md`:
- Around line 118-119: Update the recipe-count explanation in the documentation
so it is arithmetically consistent: either change “six” to “five” to describe
the net difference, or explicitly explain that six Linux-only recipes are
replaced by one macOS-only test-cross recipe.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
0chroma
reviewed
Jul 31, 2026
twitchyliquid64
approved these changes
Jul 31, 2026
…ventory Per review: the recipe count and the four enumerated recipe lists were both going to go stale, and the lists gobble context for no gain — `just --list` already prints every recipe available on the host, each with its own description, generated from the justfile. - Drop the "42 on Linux / 37 on macOS" count. It moots the arithmetic CodeRabbit flagged (five vs six) by removing the claim rather than correcting a number that changes every time a recipe lands. - Drop the four enumerated lists (CI-parity gates, e2e & harnesses, stack bring-up, build artifacts): 53 lines that restate `just --list`. - Keep what the generated list cannot carry: the justfile/CI-twin relationship, the `.scratch/` scoping rule, and the `just soak` warning. That last one is kept deliberately. `just --list` renders only the *last* comment line above a recipe, so soak's leading "# Reaps between iterations — this WILL kill this checkout's live dev stack" never reaches the listing; only the trailing description does. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`just --list` renders only the LAST comment line above a recipe, so any
multi-line block loses everything before its final line. Eleven captions
were unusable as a result:
- Mid-sentence fragments: `fix` ("usual case here is running mid-edit
with staged/unstaged work."), `lint-shell`, `test-promote-gate`,
`test-root-integration`.
- CI pointers standing in for a description: `clippy`, `deny`,
`fmt-check`, `miri`, `msrv`, `e2e-native`.
- Dropped warning: `soak` led with "reaps between iterations — this WILL
kill this checkout's live dev stack" and ended on the neutral line, so
the listing showed only the harmless half.
Reorder each block to the convention the rest of the file already uses —
rationale and CI pointers first, a bare `#`, then a one-line summary —
and fold soak's warning into its summary. No recipe body changes.
State the convention in the justfile header so it stops regressing, and
drop the AGENTS.md paragraph that existed only to carry soak's warning
past the listing: the caption carries it now.
Co-Authored-By: Claude Opus 5 (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
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
The Platform matrix said
minimald"does not build" on macOS. Read literally that istrue only of a native build — and agents took it as licence to declare daemon-side work
unverifiable on a Mac, or to hand-roll
cargoinvocations around the scoping.just test-crossalready cross-compiles--workspace --exclude minvmdto musl in Docker andruns its tests, so
minimaldand theminCLI's test targets (whose dev-dependenciespull
minimald) are reachable from macOS.What changed
just test-crossnamedas the macOS answer for everything the darwin scope skips. Pre-PR verification now says
outright that a
minimald/ CLI-test change is unverified until it has run.scoping, the pinned flags, and the ordering constraints (the macOS codesign most
sharply); a hand-rolled
cargoline drops them silently. No recipe for a task → add one.cargo test -p <crate>inner loop andthe
cargo clippy --allow-dirty --fix …variant are nowjust testandjust fix—which are exactly those commands, already scoped for the host.
cargolines; an agent copies what it sees.Inventory refresh (drive-by)
The recipe count and list had both fallen nine behind the justfile. Now 42 on Linux / 37 on
macOS (verified against
just --summaryplus the[linux]/[macos]attributes: sixLinux-only recipes, one macOS-only), with
fix,lint-shell,msrv,miri,fuzz,fuzz-check,test-promote-gate,stress,bulk-upload, andkernel-reviewdocumented.Not touched
CONTRIBUTING.md:63still pairscargo test --workspace --docwithjust doctestin itsCI-mapping table. That is a human-facing cross-reference, not an agent instruction — say
the word if you want it collapsed to the recipe too.
Docs only; no code paths affected.
🤖 Generated with Claude Code
Note
Update AGENTS.md to make
justrecipes the sole build and test surfaceUpdates AGENTS.md to establish
justrecipes as the canonical workflow for building and testing, replacing directcargocommands throughout.just ciand Linux-only crates viajust test-crossfix,test-promote-gate,lint-shell,msrv,miri,fuzz-check,fuzz,stress,bulk-upload, andkernel-reviewminimaldorminCLI tests are unverified on macOS untiljust test-crossrunsChanges since #1115 opened
just --listor barejustfor auto-generated, OS-scoped recipe list [b10f422]just soakreaps between iterations and terminates the checkout's live dev stack, noting this may not surface injust --listoutput [b10f422]justfileto follow the convention thatjust --listdisplays only the last comment line above each recipe as a standalone summary, moving detailed rationale and warnings into preceding comment blocks [f71f5e2]just soakreaps between iterations and terminates the checkout's live dev stack each pass [f71f5e2]Macroscope summarized 0b398f4.
Summary by CodeRabbit