mcpx testing: a contributor test page agents load, kept out of the user-facing AGENTS.md #1976

Relocated from dezren39/darwin-nix#131 on 2026-10-28 (placement audit): mcpx's single source lives in developing-today/code (pkgs/mcpx); re-home tracked at #309. Original body below; issue references inside it are historical (dezren39/nix numbering).

Parent: #99

Summary

Write one contributor page that tells agents working on mcpx the test policy -- what to run (#127), a test per bug (#128), guards per class (#129), flakes (#130) -- and make sure agents editing mcpx code actually load it, without adding it to pkgs/mcpx/AGENTS.md, which is the user-facing guide to using mcpx. (The book itself belongs to the documentation tree; this is only the contributor page.)

Original notes

• testing
  • importantly, as we add more testing agents should not run every single test basically ever. below documents a rough idea of a ci job design/policy, the main priority is being short as possible.
  • agents should make at least 1 simple, new test for every bug observed from any source, when cheap to do so-- aggresively test many permutations.

(The page states the policies decided in the sibling issues; the notes above are quoted there in full with their context.)

Current state

• pkgs/mcpx/AGENTS.md (109 lines) is about using mcpx ("Every MCP server on this machine is reachable from the shell through mcpx" ... "The loop") and says nothing about tests. docs/release-runbook.md:44 treats it as the instruction file "quoted in full" in the published material, so its length is a user-facing cost. There is no repo-root AGENTS.md.
• There is no CONTRIBUTING.md, no docs/testing.md, no PR template. The closest contributor material is scattered in PR bodies ("Verified it fails without the fix", "suite 3x clean", "-race clean").
• How opencode picks up instruction files (source of the version in the nix store, packages/opencode/src/session/instruction.ts):
  • at session start: the first AGENTS.md (else CLAUDE.md) found walking up from the working directory, plus the global file, plus instructions globs from opencode.json (lines 115-150);
  • on every file read: Instruction.resolve (lines 179-221, called from tool/read.ts:300) walks up from the file being read to the project root and attaches each directory's AGENTS.md/CLAUDE.md not already loaded, once per message.
  • Consequence 1: a nested pkgs/mcpx/internal/AGENTS.md reaches exactly the agents that read mcpx source, and nobody else.
  • Consequence 2: an agent reading pkgs/mcpx/internal/... from the repo root already gets pkgs/mcpx/AGENTS.md attached (the walk passes through pkgs/mcpx/). Everything added to that file is paid by contributors as well as users.
• Other harnesses: Claude Code loads nested CLAUDE.md files on demand when it reads files in that subtree; Codex concatenates AGENTS.md from the repo root down to the working directory. So a nested file is the portable mechanism; the exact trigger differs (open question for non-opencode harnesses).
• Not verified: the mechanism by which pkgs/mcpx/AGENTS.md reaches consuming agents outside this repo. Nothing in package.nix installs it and the plugin's instructions option injects a fixed four-sentence string instead (plugin/opencode/mcpx-session.ts:737-746 at 05c78b2, off by default). Either way it is published as the user guide, so the conclusion stands.

Approaches

A -- append a "Developing mcpx" section to pkgs/mcpx/AGENTS.md (least recommended)

One file, zero discovery questions, and opencode's read-time walk already attaches it for contributors. But every consumer of the user guide pays for contributor rules it cannot use (tiers, -count=1, quarantine), the release runbook's "quoted in full" material grows, and the file stops being about one audience. The user asked for this concern to be weighed; it loses.

B -- a contributor file only (pkgs/mcpx/CONTRIBUTING.md or pkgs/mcpx/docs/testing.md)

The conventional home, readable by humans on GitHub, and the book can link it. But no harness loads CONTRIBUTING.md on its own; it reaches an agent only if someone adds it to an instructions list (per-user config, not the repo) or the agent happens to open it. Agents would keep running go test ./... because nothing told them otherwise.

C -- the page in docs/testing.md, plus a short nested pkgs/mcpx/internal/AGENTS.md that points at it (recommended)

• pkgs/mcpx/docs/testing.md: the full policy -- tiers and commands with timings, the per-bug rule and checklist, when to add a guard and how, flake handling, how to reproduce a CI failure. Human-readable; the book (docs tree) links it; CONTRIBUTING.md, if wanted, is a three-line pointer to it.
• pkgs/mcpx/internal/AGENTS.md (~15-25 lines): the rules an agent must not miss -- never go test ./... or unfiltered e2e locally for a routine change (Update Rust crate tracing to v0.1.40 [SECURITY] #127; the reason is time, now that Phase 5: tag event bodies must travel with the event #182 fixed chore(deps): bump build/buck/preludes/buck2-prelude from d956689 to e7457f6 #52's leak), always -count=1 for e2e, the just/script command from Update Rust crate tracing to v0.1.40 [SECURITY] #127, one failing-first test per bug, guards when touching a registry, read CI before merging -- and "details: docs/testing.md". Placed under internal/ so it is attached only when an agent reads Go source there, which is when it is about to change or test something. (cmd/ is one file; a second copy there is unnecessary.)
• A CLAUDE.md symlink beside it is unnecessary for opencode (it prefers AGENTS.md) but cheap for Claude Code users; decide in open questions.
• pkgs/mcpx/AGENTS.md stays untouched.

Recommended because it costs users nothing, reaches contributor agents automatically through the read-time walk, keeps one source of truth (the nested file is a summary with a pointer, not a copy), and survives a harness change since it relies only on the nested-file convention.

A guard (per #129) can keep the summary honest: a unit test that every command quoted in internal/AGENTS.md names a test or recipe that exists.

Tasks

• Write pkgs/mcpx/docs/testing.md once Update Rust crate tracing to v0.1.40 [SECURITY] #127, https://github.com/tobi/omasnap #128, Add omasnap upstream repository to flake inputs #129, Update Rust crate actix-files to v0.6.10 [SECURITY] #130 are decided (can start with Update Rust crate tracing to v0.1.40 [SECURITY] #127 alone; it is the one agents need first).
• Write pkgs/mcpx/internal/AGENTS.md (short), link it from docs/testing.md.
• Hand the book's "Contributing / testing" link to the documentation tree.

Open questions

• docs/testing.md vs CONTRIBUTING.md as the canonical file name (GitHub surfaces CONTRIBUTING.md in the PR UI only at repo root or .github/, and this repo is a whole nix config -- so a package-level CONTRIBUTING.md gets no special treatment).
• Should the nested file sit at pkgs/mcpx/internal/AGENTS.md or at pkgs/mcpx/internal/e2e/AGENTS.md (narrower, only loaded when touching e2e, but then misses unit-only changes)?
• A CLAUDE.md alongside for Claude Code, or rely on its AGENTS.md support?
• Should the repo root get its own short AGENTS.md for the nix repo as a whole? Out of scope here; note for the owner.

Ease · Impact · Related

Ease S · Impact high (it is what makes the other policies reach agents)
Depends on / related: siblings #127, #128, #129, #130; #52 (closed, fixed in #182), #93 (seed/repro wording), #95 (CI facts the page quotes), #97; the documentation tree (#89, the book); #91.

Security/auth deferred; see tracker.

Acceptance criteria

• One contributor test-policy page exists in the documentation tree (not in pkgs/mcpx/AGENTS.md, which stays the user-facing guide to using mcpx), covering: what to run, a test per bug, guards per class, and the flake policy — referencing the sibling policy issues rather than duplicating them.
• A loading mechanism is in place so agents editing mcpx code actually load the page, and the mechanism is named on this issue.
• The work described in the Summary/Scope above is delivered via a branch + PR (no direct push to main); verification runs in GitHub Actions CI, not on the sandbox.
• Evidence (the page path and the loading mechanism) is recorded on this issue before it is closed.