docs(deployment): rewrite migration prose for goose adoption

Update the deployment book and glossary to reflect the goose-based
schema migration flow shipped in 12b2f9d/0f7450a:

- ch07: clarify startup probe assumes migrations ran out-of-band
- ch08: drop AutoMigrate-with-advisory-lock prose; describe goose Job
- ch12: pod startup checks goose_db_version, no longer runs migrations
- ch14: document the Job→wait→roll deploy gate and how to debug failures
- ch16: add "Migrate Job fails during deploy" + "Schema precondition
  failed" failure modes
- ch17: new runbook entries §26 (run migrations manually), §27 (recover
  from failed/dirty migration), §28 (bootstrap goose on fresh clone)
- ch19: postscript on §13 noting MigrateWithLock approach is superseded
- ch20: mark "Migration Job for schema changes" task done
- glossary: add `goose` and `goose_db_version`; flag AutoMigrate as
  tests-only
- references: add goose links; flag AutoMigrate as tests-only

docs/deployment/08-database.md

@@ -4,8 +4,10 @@
 
 Authoritative user data lives in a Neon-managed Postgres database in AWS
 us-east-1. Connections use TLS (`DB_SSLMODE=require`). Schema is managed
-via GORM AutoMigrate inside the api binary, coordinated across replicas
-by a Postgres advisory lock to prevent concurrent migration attempts.
+via [pressly/goose](https://github.com/pressly/goose) running as a
+one-shot Kubernetes Job before every api/worker rollout. See §Schema
+management below for the full shape; ch19 §13 documents the previous
+in-replica AutoMigrate approach this replaced.
 
 ## Why Neon
 
@@ -78,13 +80,13 @@ Modes PgBouncer supports:
 - **statement** — per-statement (most aggressive; breaks many features)
 
 Neon's pooler runs in **transaction mode**. This is compatible with GORM
-out of the box (we don't use session-level features like LISTEN/NOTIFY
-or session-scope advisory locks). Note: `database.MigrateWithLock()`
-needs the *direct* (non-pooler) endpoint because session-level
-advisory locks don't survive PgBouncer's per-transaction cycling — but
-the migration helper opens its own ad-hoc connection bypassing the
-configured pool, so this happens automatically. See `MigrateWithLock`
-in `internal/database/database.go`.
+runtime queries (we don't use session-level features like LISTEN/NOTIFY
+or session-scope advisory locks in the data path). The one place this
+matters is migrations: goose's session-scoped advisory lock can't
+survive PgBouncer transaction-mode pooling. The migrate Job
+(`deploy-k3s/manifests/migrate/job.yaml`) handles this by stripping
+the `-pooler` segment from `DB_HOST` before invoking goose — runtime
+keeps using the pooler, only migrations bypass it.
 
 ### Connection pool settings
 
@@ -404,11 +406,13 @@ GROUP BY usename, state, application_name;
 - [Neon docs][neon-docs]
 - [Neon pricing][neon-pricing]
 - [Postgres advisory locks][pg-locks]
-- [GORM AutoMigrate][gorm-automigrate]
+- [pressly/goose][goose] — production migration tool
+- [GORM AutoMigrate][gorm-automigrate] (tests only)
 - [honeyDue task architecture][task-arch] (repo-local)
 
 [neon-docs]: https://neon.com/docs/introduction
 [neon-pricing]: https://neon.com/pricing
 [pg-locks]: https://www.postgresql.org/docs/current/explicit-locking.html#ADVISORY-LOCKS
+[goose]: https://github.com/pressly/goose
 [gorm-automigrate]: https://gorm.io/docs/migration.html
 [task-arch]: ../../docs/TASK_LOGIC_ARCHITECTURE.md