test: add PostgreSQL migration integration coverage

docs/development/repository-workflow.md

@@ -24,6 +24,7 @@ pnpm migrations:plan # read-only comparison with PostgreSQL applied history
 pnpm migrations:apply # locked, transactional application of the pending batch
 pnpm typecheck     # strict TypeScript
 pnpm test          # Vitest
+pnpm test:migrations:integration # production runner against disposable PostgreSQL
 pnpm build         # Turborepo package build graph
 pnpm verify        # every code-only gate; never plan or apply
 ```
@@ -63,13 +64,24 @@ The default command composition supplies no destructive approvals. There is no `
 or source-controlled approval escape hatch; deployments must later compose a trusted external
 provider that supplies an exact module ID, migration identity, and checksum triple.
 
-The migration runner currently has comprehensive unit coverage through its narrow database port.
-Live PostgreSQL tests for real DDL rollback, advisory-lock contention, history-table behavior, and
-driver cleanup are deliberately deferred and are not part of `pnpm verify` or CI yet.
+Migration-runner unit tests cover orchestration through its narrow database port. Run the separate
+live suite when changing migration behavior:
 
-CI runs `pnpm ci:verify`, which adds Compose configuration validation to `pnpm verify`. A separate
-CI job runs the live infrastructure smoke test so code-only local verification does not require
-Docker. The explicit suffix avoids pnpm's built-in `ci` install command.
+```bash
+pnpm test:migrations:integration
+```
+
+It requires Docker with Compose, starts the pinned PostgreSQL image with a generated throwaway
+credential and a Docker-assigned loopback port, creates an isolated database for each scenario,
+and removes its containers, network, databases, and volume afterward. It exercises the production
+adapter and real PostgreSQL transactions, history, advisory locks, approvals, and sanitized errors.
+It remains outside the Docker-free `pnpm verify` command.
+
+CI runs `pnpm ci:verify`, which adds Compose configuration validation to `pnpm verify`. Separate
+`infrastructure-smoke` and `migration-smoke` jobs run the live service and migration suites. The
+exact pull-request context to add to `main` branch protection after merge is
+`CI / migration-smoke (pull_request)`. The explicit `ci:verify` suffix avoids pnpm's built-in `ci`
+install command.
 
 ## Development infrastructure
 

docs/development/testing.md

@@ -0,0 +1,60 @@
+# Testing
+
+Ekklesia separates fast code-level evidence from live infrastructure evidence.
+
+## Unit and repository verification
+
+```bash
+pnpm test
+pnpm verify
+```
+
+These commands exercise package tests, repository boundaries, type checking, offline module and
+migration discovery, formatting, linting, and builds. Migration-runner unit tests use a narrow
+database/session port to prove deterministic planning, approval, transaction orchestration,
+cleanup, and sanitized errors. They do not claim to prove PostgreSQL behavior.
+
+`pnpm verify` is intentionally Docker-free. It never plans or applies migrations against a live
+database.
+
+## Live PostgreSQL migration evidence
+
+Docker and the Docker Compose plugin are required for the live suite:
+
+```bash
+pnpm test:migrations:integration
+```
+
+The command starts the repository's pinned PostgreSQL image in a unique Compose project, waits for
+bounded health readiness, runs the production PostgreSQL adapter and migration services, and then
+removes the container, network, and volume. Each scenario also receives a safely named disposable
+database. Direct host runs use a Docker-assigned random port bound only to `127.0.0.1`; a
+containerized Gitea job joins the isolated Compose network and uses the PostgreSQL service name.
+
+The live suite proves fresh read-only planning, initial and incremental application, genuine
+no-op behavior, exact applied checksums and history, edited or corrupt history rejection,
+whole-batch DDL rollback, Drizzle breakpoint execution, real advisory-lock concurrency and
+timeouts, lock release after failure, exact destructive approvals, and public-error sanitization.
+It does not make migrations automatic during Core startup.
+
+CI runs the same command in the dedicated `migration-smoke` job. After this change is merged, add
+the following pull-request status context to `main` branch protection:
+
+```text
+CI / migration-smoke (pull_request)
+```
+
+## Safe troubleshooting
+
+Confirm the prerequisites without printing configuration:
+
+```bash
+docker info
+docker compose version
+```
+
+Then rerun `pnpm test:migrations:integration`. The harness emits fixed failure messages and does
+not dump PostgreSQL logs, SQL, container inspection output, or the generated database URL. Do not
+enable query logging, print the test environment, run `docker compose config` without redaction,
+or paste Docker inspection output into an issue. If the Docker daemon itself stopped during
+cleanup, restore it before rerunning so the harness can create a fresh uniquely named project.