docs: say where tests and fixtures live and which rules hold it

[thymikee]

Stacked on #3669 (R84) on #3667 (test-kit) on #3659 (R11 devDependencies) on #3645 (R83).

What

Docs for the stack, with no new files:

• AGENTS.md "Module and test topology" states the two colocation conventions (so R84 needs no exemptions): cross-module package tests are index-<aspect>.test.ts beside index.ts, and repo-level guards on Swift sources, manifests, docs or scripts live in test/repo-guards/. It also states R83 in one place: no package exports entry points at test support, a fixture one package uses stays inside it, and helpers shared across packages live only in @agent-device/test-kit, a devDependency that production source never imports and that never depends on platform-*, provider-*, the daemon or root.
• docs/agents/testing.md "Shared test utilities" replaces the stale @agent-device/selectors/snapshot-geometry-fixtures and capture-kit/snapshot-state-fixtures paths with the placement rules: one package's fixture is a *.fixtures.ts beside its module; the packages test-kit builds on cannot declare it (project references are acyclic); never import test-kit inside a vi.mock factory (it loads the module being mocked), spy it in place as pinOwnProcessStartTime does.
• docs/agents/test-audit.md adds "an exports entry only tests import" to the junk patterns.

Budget

docs/agents/ is at 39,999 of its 40,000-byte total (agent-guidance-contract.test.ts), 17 bytes of headroom on main before this PR. I paid for the additions by tightening nearby prose (smoke-test path list, the Gesture Handler canary, the docs-only paragraph) rather than raising the budget or adding a file. Any later docs/agents addition must delete duplication first.

Gates

pnpm check:quick, check:doc-prose, check:doc-links, check:gate-manifest, check:affected --run, repo-wide pnpm format.

🤖 Generated with Claude Code

[cubic-dev-ai]

All reported issues were addressed across 3 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Turn on auto-fix | Re-trigger cubic</sub>

[thymikee]

This PR is ready at eca0098. I found no code problems in the test and fixture placement rules. CI is still pending, with all jobs queued and none failed, and there are no conflicts. I did not check the Ownership and context budgets job against the +7 lines in AGENTS.md, and I did not trace the R11 test-kit factory-import claim or the host-kit/process, command and file module list. I reviewed against base bce7f7d, so I don't know if the stacked base PR merges unchanged. Not blocking, and you can take or leave these: the diff also drops unrelated lines from docs/agents/testing.md (the fuzz worker-process sentence, the "never through a barrel" import rule, and the selectors and capture-kit fixture pointers, including PROPERTY_RUNS and makeSnapshotState), so restoring them or moving the trims to a separate PR would keep those pointers; and the fixture and test-kit rules now appear in both AGENTS.md and testing.md, so one line in AGENTS.md pointing to R83/R84 and testing.md would keep AGENTS.md as a routing file. Before merge, CI needs to go green, in particular the Ownership and context budgets job for the AGENTS.md size.

[thymikee]

Note for review order: this layer carries the docs/agents/testing.md wording for the shared-helper import (test-kit named imports; no barrel claim) that #3667's reviewer asked about.

[thymikee]

The earlier note on eca0098 is now addressed. I reviewed 7000d35 and found no problems with the docs changes in AGENTS.md, docs/agents/testing.md and docs/agents/test-audit.md. The evidence is not complete yet. All 12 remaining checks are still queued and none has failed. The "Ownership and context budgets" job is the one that matters here, because I could not confirm AGENTS.md stays within its size budget until it runs. These docs hunks touch no route the other queued jobs exercise.

Not blocking, and you can take or leave it: testing.md:73 lists six packages that cannot declare test-kit, but R83 in scripts/layering/test-kit-isolation.ts walks the whole dependency closure, so selectors and ad-script (reached through command-registry) are also covered and are missing from the list.

Could testing.md say "any package test-kit reaches through its dependencies (R83, scripts/layering/test-kit-isolation.ts) cannot declare it" instead of keeping a hand-written list that has already drifted? Could the new AGENTS.md bullets also cite R83/R84 without restating the testing.md paragraph? AGENTS.md asks to link to the enforcing rule, not copy it.

Cubic has not reviewed this head. I did not check the 4 resolved threads one by one. My review covered only the three docs files, since the delta stat spans the whole stacked layer. Once the list question is settled and the queued checks pass, especially the context-budget job, this is ready for another look.

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-10-15 17:45 UTC