[rigel-mintaka]

This PR is part of a stack containing 3 PRs:

1. main
2. test(e2e): embedded-postgres smoke leg and WithEmbeddedPostgres (RIG-2906) #2211
3. "docs(testing): document the Go testing tiers (RIG-2908)" (this PR)
4. docs(ci): describe CI as the job set behind the rollup check (RIG-5280) #2222

What

T6 of docs/designs/infra/ci/compass-test-harness-tiers/design.md: one contributor page, docs/architecture/testing-tiers.md. The eng-docs site gathers it under Architecture.

The page covers:

• The three tiers: default, pgtest and podman e2e, with their tags, cost and CI job. It gives the rule for picking one: real SQL means pgtest, process or container topology means e2e, anything else uses the default tier.
• pgtest: the RequireDSN DSN order, the per-test schema, COMPASS_REQUIRE_LIVE in CI, and RequirePoolerDSN (which needs both DSNs).
• e2e: sharedFixture(t) versus plain NewFixture, as shipped. There is no WithOwnStack; see the T3 errata.
  • Shared-stack rules: register options from TestMain, route each turn by a marker, await every turn, and no -count above 1, with both causes.
  • Option scope on each path.
  • WithSite and WithEmbeddedPostgres.
  • Why zz_legsix_test.go must run last.
  • The embedded-Postgres smoke leg's role.

Other changes:

• The go/e2e and pgtest package docs link to the page. pgtest.go's build tag moved to line 1, so its doc comment now attaches to the package; before, go list -f '{{.Doc}}' printed nothing.
• TestEmbeddedPostgresSmoke's doc comment no longer says every other leg uses the suite Postgres. Own-stack legs run the stack-owned one too; they just never check its teardown.
• The record ticks T6 and adds an as-shipped errata note: the location, and that the -count note lives in the page, not in fixture.go.

Stacked on #2211 (T4).

The page points to ci.yml for exact commands, not to build-and-ci.md. That page's CI section is stale; it is tracked in RIG-5280.

Verification

• Each claim was checked against the code and ci.yml in two review rounds.
• The -count claim was reproduced: -count=2 on TestCommsTwoAgentConversation fails on the second pass with already_exists.
• rumdl check on both docs: clean. design-ledger-gate: OK. eng-docs gather tests: 141 pass.
• go vet with -tags podman and -tags pgtest: pass. Tagged golangci-lint: 0 issues.
• go list -tags pgtest -f '{{.Doc}}' ./internal/pgtest now prints the package doc.

Spec-impact: none
Ledger-impact: none (ticks T6 with an as-shipped errata; no new decision)

Closes RIG-2908

Refs RIG-2742

Co-authored-by: Matt Wilkinson matt@rigel.build

[linear-code]

RIG-2908

RIG-2742

[rigel-mintaka]

Review at head a52e1789: high 0, medium 0, low 0, nit 0

• Scope: the whole PR, all lenses, 3 rounds. Every claim in the page was checked against the code and ci.yml.
• Round 1 found 4 medium and 6 low: the smoke-leg role, option scope across shared and own stacks, the pgtest surface (RequirePoolerDSN, COMPASS_REQUIRE_LIVE), the second -count cause, the pgtest doc not attaching, CI flags, the podman skip guard, cmd/compass-stack, -shuffle, and a clients.go nit. All folded except the optional clients.go nit.
• Round 2 found 1 medium and 1 low. The link pointed to the stale build-and-ci.md for commands: it now points to ci.yml, and the stale section is filed as RIG-5280. The pooler DSN wording is fixed. Round 3 is clean.
• Checks: -count=2 reproduced already_exists. rumdl is clean, design-ledger-gate is OK, and the eng-docs gather tests pass (141). go vet passes with the podman and pgtest tags. Tagged lint reports 0 issues. go list -f {{.Doc}} now prints the pgtest package doc.

[github-actions]

Compass engineering docs preview: https://compass-comms-rig-2908-testi.compass-eng-docs.pages.dev

Deployed from compass-comms/rig-2908-testing-tiers-doc at a52e178.

Changed pages:

• docs/architecture/testing-tiers.md
• docs/designs/infra/ci/compass-test-harness-tiers/design.md