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

Merged
TH
1d ago
+22-16

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